diff --git a/mod.ts b/mod.ts index b593562..a89669b 100644 --- a/mod.ts +++ b/mod.ts @@ -48,6 +48,7 @@ export { openFileSystem } from "./src/adapter/opfs.ts"; export { FileSystemError, getErrorMessage, getErrorName, toFileSystemError } from "./src/error.ts"; export { getOpfsContext } from "./src/context.ts"; export { probeOpfs } from "./src/probe.ts"; +export { WritableFileStream } from "./src/handle.ts"; export type { CopyOptionsType, DirectoryEntryType, @@ -71,7 +72,10 @@ export type { WalkOptionsType, WriteOptionsType, } from "./src/filesystem.ts"; +export type { AdapterType, FileSystemOptionsType } from "./src/adapter/definition.ts"; +export type { OpenFileSystemOptionsType } from "./src/adapter/opfs.ts"; export type { + CreateWritableOptionsType, DirectoryHandleType, FileHandleType, HandleCreateOptionsType, @@ -84,6 +88,18 @@ export type { export type { SyncFileType } from "./src/sync.ts"; export type { WritableFileType } from "./src/writable.ts"; export type { WriteDataType } from "./src/stream.ts"; +export type { BrowserGlobalType } from "./src/context.ts"; +export type { + FileDriverCopyOptionsType, + FileDriverDirectoryEntryType, + FileDriverMoveOptionsType, + FileDriverReadOptionsType, + FileDriverSignalOptionsType, + FileDriverStatType, + FileDriverSyncFileType, + FileDriverWritableFileType, + FileDriverWriteOptionsType, +} from "./src/driver/file.ts"; export type { AdapterCapabilitiesType, AdapterLimitsType, @@ -101,15 +117,35 @@ export type { MetricsModeType, OpfsContextType, OptimizationType, + PathType, PartitionModeType, RequirementStateType, RequirementType, SupportModeType, WriteModeType, } from "./src/schema.ts"; -export type { FileSystemOptionsType } from "./src/adapter/definition.ts"; -export type { InspectionType, SupportType, WriteSupportType } from "./src/capability.ts"; +export type { + ActionKindType, + ActionType, + DriverPlanInputType, + DriverInspectionType, + DriverOperationType, + DriverPlanType, + DriverType, + ProblemLayerType, + ProblemSeverityType, + ProblemType, +} from "./src/driver/definition.ts"; +export type { AdapterInspectionType, InspectionType, SupportType, WriteSupportType } from "./src/capability.ts"; export type { DriverMetricsType, MetricEntryType, MetricOperationType, MetricsType } from "./src/metrics.ts"; -export { PlanInputSchema, PlanOperationSchema, PlanSchema, WriteSourceSchema } from "./src/plan.ts"; -export type { PlanInputType, PlanOperationType, PlanType, WriteSourceType } from "./src/plan.ts"; +export type { + CopyPlanInputType, + MovePlanInputType, + PlanInputType, + PlanOperationType, + PlanType, + ReadPlanInputType, + WritePlanInputType, + WriteSourceType, +} from "./src/plan.ts"; export type { OpfsCapabilitiesType, OpfsProbeErrorType, OpfsStorageEstimateType } from "./src/probe.ts"; diff --git a/src/context.ts b/src/context.ts index a8daf41..29fa276 100644 --- a/src/context.ts +++ b/src/context.ts @@ -6,7 +6,7 @@ import type { OpfsContextType } from "./schema.ts"; * The library intentionally avoids browser-name checks. Runtime placement is * inferred from the globals that define Window and Worker execution models. */ -interface BrowserGlobalType { +export interface BrowserGlobalType { /** Window document marker. */ readonly document?: object; /** ServiceWorker registration marker. */ diff --git a/src/driver/definition.ts b/src/driver/definition.ts index d6c2305..a27ca0a 100644 --- a/src/driver/definition.ts +++ b/src/driver/definition.ts @@ -27,7 +27,7 @@ import { export const ProblemLayerSchema = z.enum(["client", "driver", "adapter", "filesystem"]); /** A validated storage problem layer. */ -export type ProblemLayerType = z.output; +export type ProblemLayerType = "client" | "driver" | "adapter" | "filesystem"; /** * Severity of one storage planning problem. @@ -38,7 +38,7 @@ export type ProblemLayerType = z.output; export const ProblemSeveritySchema = z.enum(["info", "warning", "error"]); /** A validated storage planning problem severity. */ -export type ProblemSeverityType = z.output; +export type ProblemSeverityType = "info" | "warning" | "error"; /** * Action a caller can take after a storage preflight result. @@ -59,7 +59,15 @@ export const ActionKindSchema = z.enum([ ]); /** A validated storage planning action. */ -export type ActionKindType = z.output; +export type ActionKindType = + | "partition" + | "change-policy" + | "select-driver" + | "reduce-input" + | "enable-optimization" + | "disable-optimization" + | "probe" + | "retry"; /** * One structured problem found while planning a storage operation. @@ -77,7 +85,18 @@ export const ProblemSchema = z.object({ }).strict(); /** A validated storage planning problem. */ -export type ProblemType = z.output; +export interface ProblemType { + /** Stable machine-readable problem code. */ + readonly code: string; + /** Layer that identified the problem. */ + readonly layer: ProblemLayerType; + /** Severity used by diagnostics and policy. */ + readonly severity: ProblemSeverityType; + /** Human-readable summary of the problem. */ + readonly message: string; + /** Related limit when the problem comes from a specific ceiling or budget. */ + readonly limit?: LimitType | undefined; +} /** * One structured action available to the caller after planning. @@ -93,7 +112,14 @@ export const ActionSchema = z.object({ }).strict(); /** A validated storage planning action. */ -export type ActionType = z.output; +export interface ActionType { + /** Coarse-grained next step the caller can take. */ + readonly kind: ActionKindType; + /** Optional machine-readable qualifier for UI or policy routing. */ + readonly code?: string | undefined; + /** Optional human-readable action detail. */ + readonly detail?: string | undefined; +} /** * Operations that a backend driver can preflight without performing I/O. @@ -105,7 +131,7 @@ export type ActionType = z.output; export const DriverOperationSchema = z.enum(["stat", "read", "write", "list", "copy", "move", "remove"]); /** A validated backend driver operation. */ -export type DriverOperationType = z.output; +export type DriverOperationType = "stat" | "read" | "write" | "list" | "copy" | "move" | "remove"; /** * Concrete operation shape presented to a backend driver planner. @@ -125,7 +151,24 @@ export const DriverPlanInputSchema = z.object({ }).strict(); /** A validated backend driver preflight request. */ -export type DriverPlanInputType = z.output; +export interface DriverPlanInputType { + /** Backend-native operation being preflighted. */ + readonly operation: DriverOperationType; + /** Canonical source path when the operation targets one path. */ + readonly path?: string | undefined; + /** Canonical destination path for copy and move operations. */ + readonly destination?: string | undefined; + /** Caller-known logical byte size when available. */ + readonly size?: number | undefined; + /** Caller-known already-buffered byte count for streamed work. */ + readonly inputBytes?: number | undefined; + /** Physical input source form for write operations. */ + readonly source?: "bytes" | "stream" | undefined; + /** Requested write semantics for write operations. */ + readonly mode?: "replace" | "append" | "update" | undefined; + /** Whether a read request targets a byte range instead of the full file. */ + readonly range?: boolean | undefined; +} /** * Serializable result returned by a backend driver planner. @@ -146,7 +189,22 @@ export const DriverPlanSchema = z.object({ }).strict(); /** A validated backend driver preflight result. */ -export type DriverPlanType = z.output; +export interface DriverPlanType { + /** Backend-native operation that was planned. */ + readonly operation: DriverOperationType; + /** Whether the request can proceed under current facts and policy. */ + readonly supported: boolean; + /** Effective support mode for the backend-native route. */ + readonly support: "native" | "emulated" | "partitioned" | "unsupported"; + /** Physical part or block size when partitioning is involved. */ + readonly partBytes?: number | undefined; + /** Physical part or block count when partitioning is involved. */ + readonly parts?: number | undefined; + /** Structured problems reported by driver planning. */ + readonly problems: readonly ProblemType[]; + /** Structured actions the caller can take next. */ + readonly actions: readonly ActionType[]; +} /** * Serializable configured-driver report exposed through filesystem inspection. @@ -165,7 +223,22 @@ export const DriverInspectionSchema = z.object({ }).strict(); /** A validated configured-driver report. */ -export type DriverInspectionType = z.output; +export interface DriverInspectionType { + /** Stable configured driver name. */ + readonly name: string; + /** Backend family implemented by this driver. */ + readonly kind: DriverKindType; + /** Stable backend-native operations and capabilities. */ + readonly provides: readonly string[]; + /** Ownership of any long-lived backend resource. */ + readonly ownership: DriverOwnershipType; + /** Requirements already known for this configured instance. */ + readonly requirements: readonly RequirementType[]; + /** Limits with provider, policy, or probe provenance. */ + readonly limits: readonly LimitType[]; + /** Independently visible driver optimization switches. */ + readonly optimizations: readonly DriverOptimizationType[]; +} /** * Common behavior implemented by every configured storage driver. diff --git a/src/driver/file.ts b/src/driver/file.ts index 46ffcad..7c5cb59 100644 --- a/src/driver/file.ts +++ b/src/driver/file.ts @@ -48,11 +48,13 @@ export interface FileDriverWriteOptionsType extends FileDriverSignalOptionsType /** Options for a file-driver native copy. */ export interface FileDriverCopyOptionsType extends FileDriverSignalOptionsType { + /** Replaces an existing destination when true. */ readonly overwrite: boolean; } /** Options for a file-driver native move. */ export interface FileDriverMoveOptionsType extends FileDriverSignalOptionsType { + /** Replaces an existing destination when true. */ readonly overwrite: boolean; } @@ -65,7 +67,7 @@ export interface FileDriverDirectoryEntryType { } /** Portable file metadata returned by a file driver. */ -export interface FileDriverFileStatType { +interface FileDriverFileStatType { /** Portable discriminator for file metadata. */ readonly kind: "file"; /** File length in bytes. */ @@ -77,15 +79,37 @@ export interface FileDriverFileStatType { } /** Portable directory metadata returned by a file driver. */ -export interface FileDriverDirectoryStatType { +interface FileDriverDirectoryStatType { /** Portable discriminator for directory metadata. */ readonly kind: "directory"; /** Last-modified Unix epoch milliseconds when the backend can observe it. */ readonly lastModified?: number; } -/** Portable file/directory metadata returned by a file driver. */ -export type FileDriverStatType = FileDriverFileStatType | FileDriverDirectoryStatType; +/** + * Portable file or directory metadata returned by a file driver. + * + * The union stays small because callers only need the portable metadata needed + * by adapters and filesystem planning, not every runtime-specific detail from a + * host stat structure. + */ +export type FileDriverStatType = + | { + /** Portable discriminator for file metadata. */ + readonly kind: "file"; + /** File length in bytes. */ + readonly size: number; + /** Last-modified Unix epoch milliseconds. */ + readonly lastModified: number; + /** Media type, or an empty string when the backend does not know one. */ + readonly mediaType: string; + } + | { + /** Portable discriminator for directory metadata. */ + readonly kind: "directory"; + /** Last-modified Unix epoch milliseconds when the backend can observe it. */ + readonly lastModified?: number | undefined; + }; /** * Long-lived asynchronous positional file owned by a file driver. diff --git a/src/plan.ts b/src/plan.ts index b0a5c74..e8462f3 100644 --- a/src/plan.ts +++ b/src/plan.ts @@ -14,6 +14,47 @@ import { normalizePath } from "./path.ts"; import type { OptimizationType, SupportModeType } from "./schema.ts"; import { SupportModeSchema, WriteModeSchema } from "./schema.ts"; +/** Validated read preflight input after defaults are applied. */ +interface ReadPlanInputResolvedType { + readonly operation: "read"; + readonly path?: string | undefined; + readonly size?: number | undefined; + readonly range: boolean; +} + +/** Validated write preflight input after defaults are applied. */ +interface WritePlanInputResolvedType { + readonly operation: "write"; + readonly path?: string | undefined; + readonly size?: number | undefined; + readonly inputBytes?: number | undefined; + readonly source: WriteSourceType; + readonly mode: "replace" | "append" | "update"; +} + +/** Validated copy preflight input. */ +interface CopyPlanInputResolvedType { + readonly operation: "copy"; + readonly path?: string | undefined; + readonly destination?: string | undefined; + readonly size?: number | undefined; +} + +/** Validated move preflight input. */ +interface MovePlanInputResolvedType { + readonly operation: "move"; + readonly path?: string | undefined; + readonly destination?: string | undefined; + readonly size?: number | undefined; +} + +/** Validated preflight input shape after schema defaults are applied. */ +type ResolvedPlanInputType = + | ReadPlanInputResolvedType + | WritePlanInputResolvedType + | CopyPlanInputResolvedType + | MovePlanInputResolvedType; + /** * Physical source form supplied to a planned write. * @@ -22,7 +63,7 @@ import { SupportModeSchema, WriteModeSchema } from "./schema.ts"; */ export const WriteSourceSchema = z.enum(["bytes", "stream"]); /** Validated physical write-source form. */ -export type WriteSourceType = z.output; +export type WriteSourceType = "bytes" | "stream"; /** * Filesystem operations supported by deterministic preflight planning. * @@ -31,7 +72,59 @@ export type WriteSourceType = z.output; */ export const PlanOperationSchema = z.enum(["read", "write", "copy", "move"]); /** Validated preflight operation name. */ -export type PlanOperationType = z.output; +export type PlanOperationType = "read" | "write" | "copy" | "move"; + +/** Preflight input for a read request before schema defaults are applied. */ +export interface ReadPlanInputType { + /** Selects a read preflight request. */ + readonly operation: "read"; + /** Path the caller plans to read. */ + readonly path?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; + /** Whether the read plans a byte range instead of the full file. */ + readonly range?: boolean | undefined; +} + +/** Preflight input for a write request before schema defaults are applied. */ +export interface WritePlanInputType { + /** Selects a write preflight request. */ + readonly operation: "write"; + /** Path the caller plans to write. */ + readonly path?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; + /** Caller-known already-buffered byte count when streaming. */ + readonly inputBytes?: number | undefined; + /** Physical source form for the write request. */ + readonly source: WriteSourceType; + /** Requested write semantics. */ + readonly mode?: "replace" | "append" | "update" | undefined; +} + +/** Preflight input for a copy request. */ +export interface CopyPlanInputType { + /** Selects a copy preflight request. */ + readonly operation: "copy"; + /** Source path the caller plans to copy. */ + readonly path?: string | undefined; + /** Destination path for the copy request. */ + readonly destination?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; +} + +/** Preflight input for a move request. */ +export interface MovePlanInputType { + /** Selects a move preflight request. */ + readonly operation: "move"; + /** Source path the caller plans to move. */ + readonly path?: string | undefined; + /** Destination path for the move request. */ + readonly destination?: string | undefined; + /** Caller-known logical size when available. */ + readonly size?: number | undefined; +} /** * Serializable preflight request for one concrete filesystem operation. @@ -69,7 +162,7 @@ export const PlanInputSchema = z.discriminatedUnion("operation", [ }).strict(), ]); /** Input accepted by filesystem preflight before defaults and path normalization. */ -export type PlanInputType = z.input; +export type PlanInputType = ReadPlanInputType | WritePlanInputType | CopyPlanInputType | MovePlanInputType; /** * Structured preflight result for the complete driver -> adapter -> filesystem stack. @@ -90,7 +183,26 @@ export const PlanSchema = z.object({ actions: z.array(ActionSchema).readonly(), }).strict(); /** Validated complete-stack preflight result. */ -export type PlanType = z.output; +export interface PlanType { + /** Filesystem operation that was planned. */ + readonly operation: PlanOperationType; + /** Whether the complete storage stack can perform the request safely. */ + readonly supported: boolean; + /** Effective support mode after driver, adapter, and facade policy are combined. */ + readonly support: SupportModeType; + /** Backend-native planning result preserved inside the full plan. */ + readonly driver: DriverPlanType; + /** Facade-owned buffering required before the request can proceed. */ + readonly bufferBytes?: number | undefined; + /** Physical part or block size when partitioning is involved. */ + readonly partBytes?: number | undefined; + /** Physical part or block count when partitioning is involved. */ + readonly parts?: number | undefined; + /** Structured problems found across the complete storage stack. */ + readonly problems: readonly ProblemType[]; + /** Structured actions the caller can take next. */ + readonly actions: readonly ActionType[]; +} /** * Internal facade state required to combine adapter and driver preflight. @@ -131,7 +243,7 @@ function action(kind: ActionType["kind"], detail?: string): ActionType { * paths are normalized, defaults are resolved, and only driver-relevant fields * cross the boundary. */ -function getDriverPlan(input: z.output, adapter: AdapterType): DriverPlanType { +function getDriverPlan(input: ResolvedPlanInputType, adapter: AdapterType): DriverPlanType { return adapter.driver.plan({ operation: input.operation, ...(input.path === undefined ? {} : { path: normalizePath(input.path) }), diff --git a/src/schema.ts b/src/schema.ts index d63b7c9..7bf87dc 100644 --- a/src/schema.ts +++ b/src/schema.ts @@ -21,7 +21,7 @@ export const PathSchema = z.string().refine( ); /** A validated canonical virtual filesystem path. */ -export type PathType = z.output; +export type PathType = string; /** Stable non-empty diagnostic name assigned to one adapter implementation. */ export const AdapterNameSchema = z.string().min(1); @@ -38,7 +38,7 @@ export type AdapterNameType = z.output; export const EntryKindSchema = z.enum(["file", "directory"]); /** A validated filesystem entry kind. */ -export type EntryKindType = z.output; +export type EntryKindType = "file" | "directory"; /** * Execution contexts that can host browser storage access. @@ -58,7 +58,13 @@ export const OpfsContextSchema = z.enum([ ]); /** A validated browser execution context classification. */ -export type OpfsContextType = z.output; +export type OpfsContextType = + | "window" + | "dedicated-worker" + | "shared-worker" + | "service-worker" + | "worker" + | "unknown"; /** * Mutation coordination policies supported by {@link createFileSystem}. @@ -70,7 +76,7 @@ export type OpfsContextType = z.output; export const CoordinationModeSchema = z.enum(["auto", "web-locks", "local", "none"]); /** A validated mutation coordination policy. */ -export type CoordinationModeType = z.output; +export type CoordinationModeType = "auto" | "web-locks" | "local" | "none"; /** * Write modes shared by the facade and adapters. @@ -81,7 +87,7 @@ export type CoordinationModeType = z.output; export const WriteModeSchema = z.enum(["replace", "append", "update"]); /** A validated file write mode. */ -export type WriteModeType = z.output; +export type WriteModeType = "replace" | "append" | "update"; /** * How one operation is provided by the selected storage stack. @@ -95,7 +101,7 @@ export type WriteModeType = z.output; export const SupportModeSchema = z.enum(["native", "emulated", "partitioned", "unsupported"]); /** A validated storage support mode. */ -export type SupportModeType = z.output; +export type SupportModeType = "native" | "emulated" | "partitioned" | "unsupported"; /** * Metrics collection cost selected for one filesystem or protocol client. @@ -107,7 +113,7 @@ export type SupportModeType = z.output; export const MetricsModeSchema = z.enum(["none", "basic", "timing"]); /** A validated metrics collection mode. */ -export type MetricsModeType = z.output; +export type MetricsModeType = "none" | "basic" | "timing"; /** * Physical partition policy for backends with a smaller value limit than the @@ -116,7 +122,7 @@ export type MetricsModeType = z.output; export const PartitionModeSchema = z.enum(["never", "auto", "always"]); /** A validated physical partition policy. */ -export type PartitionModeType = z.output; +export type PartitionModeType = "never" | "auto" | "always"; /** * Inspectable physical layout used when one logical file spans provider values. @@ -136,7 +142,20 @@ export const AdapterPartitionSchema = z.object({ }).strict(); /** A validated physical partition layout. */ -export type AdapterPartitionType = z.output; +export interface AdapterPartitionType { + /** Partitioning policy selected for this adapter. */ + readonly mode: PartitionModeType; + /** Physical part or block size used by the layout. */ + readonly partBytes: number; + /** Logical size where `auto` starts partitioning when known. */ + readonly thresholdBytes?: number | undefined; + /** Whether streamed writes already use the partitioned layout. */ + readonly stream?: boolean | undefined; + /** Maximum physical part or block count when known. */ + readonly maxParts?: number | undefined; + /** Stable name of the physical layout strategy. */ + readonly layout: string; +} /** * Optional backend limits that can be inspected before work begins. @@ -165,7 +184,24 @@ export const AdapterLimitsSchema = z.object({ }).strict(); /** Portable hard limits known by one configured adapter. */ -export type AdapterLimitsType = z.output; +export interface AdapterLimitsType { + /** Maximum logical file size accepted by this configured adapter. */ + readonly maxFileBytes?: number | undefined; + /** Maximum materialized backend value size when the backend has one. */ + readonly maxValueBytes?: number | undefined; + /** Maximum serialized key size when the backend has one. */ + readonly maxKeyBytes?: number | undefined; + /** Minimum legal provider part or block size. */ + readonly minPartBytes?: number | undefined; + /** Maximum legal provider part or block size. */ + readonly maxPartBytes?: number | undefined; + /** Maximum provider part or block count for one logical object. */ + readonly maxParts?: number | undefined; + /** Maximum useful concurrency known by this adapter. */ + readonly maxConcurrency?: number | undefined; + /** Maximum bytes allowed in one batched or transactional mutation. */ + readonly maxBatchBytes?: number | undefined; +} /** * Performance routes that the filesystem facade can deliberately bypass. @@ -188,7 +224,18 @@ export const OptimizationSchema = z.object({ }).strict(); /** Resolved performance-route policy for one filesystem facade. */ -export type OptimizationType = z.output; +export interface OptimizationType { + /** Enables adapter-native streaming reads when available. */ + readonly streamRead: boolean; + /** Enables adapter-native streaming writes when available. */ + readonly streamWrite: boolean; + /** Enables native range reads when available. */ + readonly rangeRead: boolean; + /** Enables adapter-native or server-side copy routes when available. */ + readonly nativeCopy: boolean; + /** Enables adapter-native move or rename routes when available. */ + readonly nativeMove: boolean; +} /** * Stable adapter capability description. @@ -222,7 +269,26 @@ export const AdapterCapabilitiesSchema = z.object({ }); /** Native operations implemented by one adapter. */ -export type AdapterCapabilitiesType = z.output; +export interface AdapterCapabilitiesType { + /** Adapter can materialize file bytes through `readFile()`. */ + readonly read: boolean; + /** Adapter can commit materialized file bytes through `writeFile()`. */ + readonly write: boolean; + /** Adapter can open a native read stream. */ + readonly streamRead: boolean; + /** Write modes that `writeStream()` can perform natively. */ + readonly streamWriteModes: readonly WriteModeType[]; + /** Adapter can satisfy byte ranges without whole-file materialization. */ + readonly rangeRead: boolean; + /** Adapter can copy bytes without routing them through the facade. */ + readonly nativeCopy: boolean; + /** Adapter can move or rename through one backend-native route. */ + readonly nativeMove: boolean; + /** Adapter exposes a long-lived asynchronous positional writer. */ + readonly positionalWrite: boolean; + /** Adapter exposes a synchronous random-access file resource. */ + readonly syncAccess: boolean; +} /** * Stable error categories exposed by the package. @@ -248,7 +314,20 @@ export const ErrorCodeSchema = z.enum([ ]); /** A validated package error category. */ -export type ErrorCodeType = z.output; +export type ErrorCodeType = + | "unavailable" + | "not-found" + | "already-exists" + | "type-mismatch" + | "invalid-path" + | "invalid-operation" + | "not-supported" + | "locked" + | "quota-exceeded" + | "permission-denied" + | "aborted" + | "too-large" + | "unknown"; /** Version stored with record-backed filesystem entries. */ export const RecordVersionSchema = z.literal(1); @@ -328,25 +407,25 @@ export type SqlIdentifierType = z.output; export const DriverKindSchema = z.enum(["file", "record", "object"]); /** A validated backend driver family. */ -export type DriverKindType = z.output; +export type DriverKindType = "file" | "record" | "object"; /** Why one driver limit exists. */ export const LimitKindSchema = z.enum(["hard", "policy", "dynamic"]); /** A validated limit kind. */ -export type LimitKindType = z.output; +export type LimitKindType = "hard" | "policy" | "dynamic"; /** Layer that supplied one limit value. */ export const LimitSourceSchema = z.enum(["provider", "implementation", "user", "probe"]); /** A validated limit source. */ -export type LimitSourceType = z.output; +export type LimitSourceType = "provider" | "implementation" | "user" | "probe"; /** Unit used by one numeric limit. */ export const LimitUnitSchema = z.enum(["bytes", "count", "milliseconds", "operations"]); /** A validated limit unit. */ -export type LimitUnitType = z.output; +export type LimitUnitType = "bytes" | "count" | "milliseconds" | "operations"; /** * One inspectable storage limit with explicit provenance. @@ -369,13 +448,26 @@ export const LimitSchema = z.object({ }); /** A validated storage limit. */ -export type LimitType = z.output; +export interface LimitType { + /** Stable machine-readable limit code. */ + readonly code: string; + /** Whether the limit is hard, policy-driven, or dynamic. */ + readonly kind: LimitKindType; + /** Layer that supplied the limit value. */ + readonly source: LimitSourceType; + /** Unit used by the numeric value. */ + readonly unit: LimitUnitType; + /** Current numeric limit when known. */ + readonly value?: number | undefined; + /** Human-readable context for diagnostics. */ + readonly detail?: string | undefined; +} /** Current state of one driver requirement. */ export const RequirementStateSchema = z.enum(["available", "missing", "unknown"]); /** A validated requirement state. */ -export type RequirementStateType = z.output; +export type RequirementStateType = "available" | "missing" | "unknown"; /** * One runtime, provider, permission, or configuration requirement. @@ -394,13 +486,20 @@ export const RequirementSchema = z.object({ }); /** A validated driver requirement. */ -export type RequirementType = z.output; +export interface RequirementType { + /** Stable machine-readable requirement code. */ + readonly code: string; + /** Current known availability state. */ + readonly state: RequirementStateType; + /** Concrete reason when the requirement is missing. */ + readonly reason?: string | undefined; +} /** Ownership state for one configured driver backend resource. */ export const DriverOwnershipSchema = z.enum(["none", "borrowed", "owned"]); /** A validated configured-driver backend ownership state. */ -export type DriverOwnershipType = z.output; +export type DriverOwnershipType = "none" | "borrowed" | "owned"; /** * One independently controllable driver optimization. @@ -422,4 +521,15 @@ export const DriverOptimizationSchema = z.object({ }); /** A validated driver optimization declaration. */ -export type DriverOptimizationType = z.output; +export interface DriverOptimizationType { + /** Stable machine-readable optimization code. */ + readonly code: string; + /** Current enabled state. */ + readonly enabled: boolean; + /** Whether this optimization changes observable behavior. */ + readonly changesBehavior: boolean; + /** Whether callers can turn this optimization off. */ + readonly disableable: boolean; + /** Human-readable detail for diagnostics or documentation. */ + readonly detail?: string | undefined; +}