@codeworksh/harness 0.0.1-dev.20260825093030 → 0.0.1-dev.20260907170816

package/sandbox-DnL9UPzZ.d.mts

@@ -0,0 +1,668 @@
+import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
+//#region src/sandbox/errors.d.ts
+declare const SandboxNotFoundError_base: Schema.Class<SandboxNotFoundError, Schema.TaggedStruct<"SandboxNotFoundError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Lifecycle errors are confined to the control plane. Once a mount succeeds,
+ * consumers continue to see only FileSystemError and ShellError.
+ */
+declare class SandboxNotFoundError extends SandboxNotFoundError_base {}
+declare const SandboxDriverNotRegisteredError_base: Schema.Class<SandboxDriverNotRegisteredError, Schema.TaggedStruct<"SandboxDriverNotRegisteredError", {
+  readonly driver: Schema.String;
+  readonly registered: Schema.optional<Schema.$Array<Schema.String>>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxDriverNotRegisteredError extends SandboxDriverNotRegisteredError_base {}
+declare const SandboxDriverRegistrationError_base: Schema.Class<SandboxDriverRegistrationError, Schema.TaggedStruct<"SandboxDriverRegistrationError", {
+  readonly driver: Schema.String;
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxDriverRegistrationError extends SandboxDriverRegistrationError_base {}
+declare const SandboxDriverLoadError_base: Schema.Class<SandboxDriverLoadError, Schema.TaggedStruct<"SandboxDriverLoadError", {
+  readonly specifier: Schema.String;
+  readonly phase: Schema.Literals<readonly ["resolve", "import", "module", "api-version", "options", "factory", "registration"]>;
+  readonly driver: Schema.optional<Schema.String>;
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxDriverLoadError extends SandboxDriverLoadError_base {}
+declare const SandboxBusyError_base: Schema.Class<SandboxBusyError, Schema.TaggedStruct<"SandboxBusyError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+  readonly refCount: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxBusyError extends SandboxBusyError_base {}
+declare const SandboxMustBeStoppedError_base: Schema.Class<SandboxMustBeStoppedError, Schema.TaggedStruct<"SandboxMustBeStoppedError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+  readonly status: Schema.Literals<readonly ["provisioning", "online", "offline", "suspending", "removing", "removed", "unavail", "faulted"]>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxMustBeStoppedError extends SandboxMustBeStoppedError_base {}
+declare const SandboxRemovedError_base: Schema.Class<SandboxRemovedError, Schema.TaggedStruct<"SandboxRemovedError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+  readonly removedAt: Schema.optional<Schema.DateTimeUtc>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxRemovedError extends SandboxRemovedError_base {}
+declare const SandboxUnavailError_base: Schema.Class<SandboxUnavailError, Schema.TaggedStruct<"SandboxUnavailError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxUnavailError extends SandboxUnavailError_base {}
+declare const SandboxUnsupportedError_base: Schema.Class<SandboxUnsupportedError, Schema.TaggedStruct<"SandboxUnsupportedError", {
+  readonly id: Schema.optional<Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  }>;
+  readonly driver: Schema.String;
+  readonly operation: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxUnsupportedError extends SandboxUnsupportedError_base {}
+declare const SandboxTransitionConflictError_base: Schema.Class<SandboxTransitionConflictError, Schema.TaggedStruct<"SandboxTransitionConflictError", {
+  readonly id: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+    local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+    create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  };
+  readonly expected: Schema.$Array<Schema.Literals<readonly ["provisioning", "online", "offline", "suspending", "removing", "removed", "unavail", "faulted"]>>;
+  readonly actual: Schema.Literals<readonly ["provisioning", "online", "offline", "suspending", "removing", "removed", "unavail", "faulted"]>;
+}>, import("effect/Cause").YieldableError>;
+declare class SandboxTransitionConflictError extends SandboxTransitionConflictError_base {}
+declare const SandboxProviderError_base: Schema.Class<SandboxProviderError, Schema.TaggedStruct<"SandboxProviderError", {
+  readonly driver: Schema.String;
+  readonly operation: Schema.String;
+  readonly sanitized: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly message: Schema.String;
+    readonly code: Schema.optional<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A lifecycle failure safe to serialize, persist, or log.
+ *
+ * The raw SDK defect is deliberately absent from the schema. It is retained on
+ * a non-enumerable symbol by {@link providerError}, so Effect's default
+ * formatting and JSON serialization cannot expose credentials nested in it.
+ */
+declare class SandboxProviderError extends SandboxProviderError_base {}
+declare const providerErrorCause: (error: SandboxProviderError) => unknown;
+declare const providerErrorIsNotFound: (error: SandboxProviderError) => boolean;
+type Redactor = (value: string) => string;
+/**
+ * Conservative text redaction shared by every driver sanitizer.
+ *
+ * Disclaimer: This can really leak. Its never safe
+ *
+ * Configured secrets are removed exactly. Common authorization/header and URL
+ * query shapes are masked as a second line of defence for values the caller did
+ * not explicitly seed.
+ *
+ * Note: add support for diff regex as needed.
+ */
+declare const makeRedactor: (secrets?: Iterable<string>) => Redactor;
+declare const sanitizeError: (cause: unknown, redact?: Redactor) => PersistedError;
+declare const providerError: (input: {
+  readonly driver: string;
+  readonly operation: string;
+  readonly cause: unknown;
+  readonly redact?: Redactor;
+  readonly sanitize?: (cause: unknown, redact: Redactor) => PersistedError;
+  readonly notFound?: boolean;
+}) => SandboxProviderError;
+type SandboxMountError = SandboxNotFoundError | SandboxDriverNotRegisteredError | SandboxUnavailError | SandboxRemovedError | SandboxProviderError;
+type SandboxCreateError = SandboxDriverNotRegisteredError | SandboxDriverRegistrationError | SandboxProviderError;
+type SandboxRegisterError = SandboxDriverNotRegisteredError | SandboxDriverRegistrationError | SandboxUnsupportedError | SandboxProviderError;
+type SandboxReadError = never;
+type SandboxRefreshError = SandboxNotFoundError | SandboxDriverNotRegisteredError | SandboxUnavailError | SandboxUnsupportedError | SandboxProviderError;
+type SandboxWakeError = SandboxRefreshError | SandboxRemovedError;
+type SandboxStopError = SandboxWakeError | SandboxBusyError | SandboxTransitionConflictError;
+type SandboxDestroyError = SandboxStopError | SandboxMustBeStoppedError;
+declare namespace filesystem_d_exports {
+  export { FileStat, FileSystemError, Interface, OperationUnsupportedError, Provider, RmOptions, filesystem_d_exports as SandboxFileSystem, Service$1 as Service, fromProvider, isNotFoundError, validateRmOptions, withCwd };
+}
+declare const OperationUnsupportedError_base: Schema.Class<OperationUnsupportedError, Schema.TaggedStruct<"OperationUnsupportedError", {
+  readonly operation: Schema.String;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The runtime filesystem contract, independent of any backend.
+ *
+ * Two surfaces, deliberately:
+ * - {@link Provider} is what a backend implements — plain promises that reject,
+ *   matching every SDK we wrap.
+ * - {@link Interface} is what the harness consumes — Effect with a typed error
+ *   channel and tracing spans. {@link fromProvider} bridges the two exactly
+ *   once, so no consumer ever writes `Effect.tryPromise` against a filesystem.
+ *
+ * Implementations:
+ * - Local:
+ * implement it over a VFS (`./local`);
+ * local filesystem use OS primitives; hence have broader filesytem capabilities.
+ *
+ * - Remote:
+ * implement it over a provider (`./remote`).
+ * remote filesytems depends on the interface provided by the remote provider; hence can have limited filesytem capabilities.
+ *
+ * `isFile`/`isDirectory` are required booleans; size, mtime, and isSymbolicLink are omitted when the
+ * backend cannot report them — never fabricated.
+ *
+ * **Paths are POSIX, and the harness is Unix-only (for now!).** Every path uses `/`
+ * separators on both the host and inside a sandbox — Windows is not supported,
+ * so no translation layer exists. Consumers must use the shared Effect POSIX
+ * path implementation, never the platform default, or a host running the harness would
+ * impose its own flavour on a remote sandbox's paths. Relative paths resolve
+ * against the backend's configured `cwd`.
+ */
+declare class OperationUnsupportedError extends OperationUnsupportedError_base {}
+declare const FileSystemError_base: Schema.Class<FileSystemError, Schema.TaggedStruct<"SandboxFileSystemError", {
+  readonly method: Schema.String;
+  readonly path: Schema.String;
+  readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** A backend operation failed. `cause` carries the provider's own rejection. */
+declare class FileSystemError extends FileSystemError_base {}
+interface FileStat {
+  readonly isFile: boolean;
+  readonly isDirectory: boolean;
+  readonly isSymbolicLink?: boolean;
+  readonly size?: number;
+  readonly mtime?: Date;
+}
+interface RmOptions {
+  readonly recursive?: boolean;
+  readonly force?: boolean;
+}
+/** Whether a provider failure means the path itself is definitively absent. */
+declare const isNotFoundError: (cause: unknown) => boolean;
+/**
+ * The backend-facing contract. Backends author plain promises and let them
+ * reject; {@link fromProvider} turns rejections into typed failures.
+ */
+interface Provider {
+  readonly readFile: (path: string) => Promise<string>;
+  readonly readFileBuffer: (path: string) => Promise<Uint8Array>;
+  /**
+   * Write the file. Parents may be missing — do not create them here;
+   * {@link fromProvider} owns that guarantee for every backend.
+   */
+  readonly writeFile: (path: string, content: string | Uint8Array) => Promise<void>;
+  readonly stat: (path: string) => Promise<FileStat>;
+  readonly readdir: (path: string) => Promise<string[]>;
+  readonly exists: (path: string) => Promise<boolean>;
+  readonly mkdir: (path: string, options?: {
+    recursive?: boolean;
+  }) => Promise<void>;
+  readonly rm: (path: string, options?: RmOptions) => Promise<void>;
+  /**
+   * Metadata for the directory entry itself rather than a symlink's target.
+   * Optional: a backend whose `stat` has mixed symlink semantics implements it
+   * so symlink identity is asked for explicitly, never inferred.
+   */
+  readonly lstat?: (path: string) => Promise<FileStat>;
+}
+/**
+ * The consumer-facing contract. `exists` distinguishes "absent" from "could not
+ * tell": a backend failure is a typed failure, not `false`, so a caller acting
+ * on absence never acts on a network blip. Use `SandboxFs.existsOrFalse` where
+ * a best-effort answer really is wanted.
+ */
+interface Interface {
+  readonly readFile: (path: string) => Effect.Effect<string, FileSystemError>;
+  readonly readFileBuffer: (path: string) => Effect.Effect<Uint8Array, FileSystemError>;
+  /** Creates missing parent directories, on every backend. */
+  readonly writeFile: (path: string, content: string | Uint8Array) => Effect.Effect<void, FileSystemError>;
+  readonly stat: (path: string) => Effect.Effect<FileStat, FileSystemError>;
+  readonly readdir: (path: string) => Effect.Effect<string[], FileSystemError>;
+  readonly exists: (path: string) => Effect.Effect<boolean, FileSystemError>;
+  readonly mkdir: (path: string, options?: {
+    recursive?: boolean;
+  }) => Effect.Effect<void, FileSystemError>;
+  readonly rm: (path: string, options?: RmOptions) => Effect.Effect<void, FileSystemError | OperationUnsupportedError>;
+  readonly lstat?: (path: string) => Effect.Effect<FileStat, FileSystemError>;
+}
+declare const Service_base$1: Context.ServiceClass<Service$1, "@codeworksh/harness/sandbox/fs/filesystem/Service", Interface>;
+/** The runtime filesystem service — the live {@link Interface} for the active sandbox. */
+declare class Service$1 extends Service_base$1 {}
+/**
+ * Reject `rm` options a provider does not implement, before any mutation. Only
+ * `recursive` and `force` are part of the contract; anything else is refused
+ * loudly rather than silently ignored.
+ */
+declare const validateRmOptions: (options: RmOptions | undefined, operation?: string) => Effect.Effect<void, OperationUnsupportedError>;
+/**
+ * Lift a {@link Provider} into the runtime {@link Interface}: one place that
+ * converts rejections into {@link FileSystemError}, validates `rm` options,
+ * creates missing parents on write, and names a tracing span per operation.
+ */
+declare const fromProvider: (provider: Provider) => Interface;
+/**
+ * Bind a cwd-neutral filesystem to one mount's working directory.
+ *
+ * The counterpart of `Shell.withCwd`, and the reason relative paths mean the
+ * same thing to both: a shared transport stays rooted at the namespace root, so
+ * resolution happens here, per mount, rather than inside a VFS whose `chdir` is
+ * global state two mounts would fight over.
+ */
+declare const withCwd: (fs: Interface, cwd: string) => Interface;
+//#endregion
+//#region src/sandbox/shell/shell.d.ts
+declare const ShellError_base: Schema.Class<ShellError, Schema.TaggedStruct<"ShellError", {
+  readonly command: Schema.String;
+  readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The pluggable execution contract. Local sandboxes usually get a Shell through
+ * just-bash over the local `Local.Vfs`; remote sandboxes provide their own
+ * native Shell. Either way the rest of the harness depends only on this service
+ * tag.
+ */
+declare class ShellError extends ShellError_base {}
+interface ExecResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+/**
+ * One options shape for every entry point. `cwd` is the operation-level
+ * override: it wins over the mount's working directory, and a relative value
+ * resolves against it. Neither mutates shared state, so concurrent commands in
+ * one mount can run in different directories.
+ */
+interface ShellOptions {
+  readonly env?: Record<string, string>;
+  readonly cwd?: string;
+}
+/**
+ * A streamed chunk of command output, terminated by a single `exit` carrying the
+ * exit code. (A backend-level mirror of the tool layer's event; kept here so
+ * `sandbox/` does not depend on `tools/`.)
+ */
+type ExecChunk = {
+  readonly _tag: "stdout";
+  readonly bytes: Uint8Array;
+} | {
+  readonly _tag: "stderr";
+  readonly bytes: Uint8Array;
+} | {
+  readonly _tag: "exit";
+  readonly exitCode: number;
+};
+/**
+ * The command-execution capability a sandbox exposes. For an in-process
+ * backend this is just-bash; for a remote backend it is the sandbox's own
+ * shell. The {@link Shell} service tag carries this interface.
+ */
+interface ISandboxExe {
+  readonly exec: (command: string, options?: ShellOptions) => Effect.Effect<ExecResult, ShellError>;
+  /**
+   * Run a program with an explicit argument vector, bypassing shell word
+   * splitting. Callers that build commands from untrusted values — branch
+   * names, file paths — must use this instead of interpolating into
+   * {@link exec}, where a space or `$(…)` would change what runs.
+   *
+   * Backends whose transport only accepts a string quote the vector with
+   * {@link quote}; backends that spawn directly pass it through untouched.
+   */
+  readonly execArgv: (argv: ReadonlyArray<string>, options?: ShellOptions) => Effect.Effect<ExecResult, ShellError>;
+  /**
+   * Optional streaming output: stdout/stderr chunks then a terminal `exit`.
+   * Backends that can stream (e.g. Vercel) implement it; `ToolShell.fromSandboxShell`
+   * bridges it to `ToolShell.stream` so the bash tool streams over them too.
+   */
+  readonly stream?: (command: string, options?: ShellOptions) => Stream.Stream<ExecChunk, ShellError>;
+}
+/**
+ * POSIX single-quote escaping: wrap in `'…'` and rewrite each embedded quote as
+ * `'\''`. Everything inside single quotes is literal to the shell, so this is
+ * safe for arbitrary bytes.
+ */
+declare const quote: (value: string) => string;
+/** Render an argument vector as one shell-safe command string. */
+declare const quoteArgv: (argv: ReadonlyArray<string>) => string;
+/**
+ * Complete a string-only backend: `execArgv` quotes the vector and runs it
+ * through `exec`. Backends that spawn a real argument vector (Vercel) implement
+ * `execArgv` themselves instead, so the args never meet a shell parser at all.
+ *
+ * `cwd` rides the options rather than a `cd <dir> && …` prefix. Every backend
+ * we wrap takes a working directory natively, and the prefix form cannot tell a
+ * failed `cd` from a failed command — both arrive as one exit code.
+ */
+declare const fromExec: (backend: Omit<ISandboxExe, "execArgv">) => ISandboxExe;
+declare const Shell_base: Context.ServiceClass<Shell$1, "@codeworksh/harness/sandbox/shell/shell", ISandboxExe>;
+/** Execution service — the live {@link ISandboxExe} for the active sandbox. */
+declare class Shell$1 extends Shell_base {}
+//#endregion
+//#region src/sandbox/io.d.ts
+/**
+ * `SandboxIO` is a **mount**: a filesystem, a shell, and the identity and
+ * working directory they act on.
+ *
+ * It is the whole vocabulary a consumer needs. Project, Git, Copy, Location, and
+ * every tool ask for `SandboxIO.FileSystem`, `SandboxIO.Shell`, and
+ * `SandboxIO.Current` — never for a driver, an address, or a provider SDK — so
+ * a host directory, an in-memory VFS, and a remote microVM are interchangeable
+ * behind one contract.
+ *
+ * The mount neither creates nor destroys infrastructure. `SandboxInstance` is
+ * the durable namespace it acts on — a device, which exists whether or not
+ * anything has it mounted — and `Sandbox.Controller` is the only path that
+ * creates, stops, or destroys one.
+ */
+/**
+ * The filesystem tag. Re-exported here so consumers import one namespace —
+ * Project, Git, Copy, and the runner ask for `SandboxIO.FileSystem`, never for
+ * the module that happens to define it. Code *inside* `sandbox/` keeps importing
+ * the tag directly, since `io.ts` is built on top of it.
+ */
+declare const FileSystem$1: typeof Service$1;
+type FileSystem$1 = Service$1;
+/** The shell tag. Re-exported here so consumers import one namespace. */
+declare const Shell: typeof Shell$1;
+type Shell = Shell$1;
+/**
+ * What a mount sees: immutable identity, plus the working directory resolved for
+ * *this* mount.
+ *
+ * Nothing mutable belongs here. `status`, `usage`, and reference counts all
+ * change while a mount is open, so a mount-time snapshot of them would be wrong
+ * by construction — runtime code that needs live management state asks the
+ * control plane. The driver's own resource locator is likewise absent: consumers
+ * never parse a Vercel name or a Daytona id.
+ */
+interface Identity {
+  readonly id: ID;
+  readonly driver: Name;
+  readonly kind: Kind;
+  /** Absolute, and always a path in *this* namespace. */
+  readonly cwd: string;
+}
+declare const Current_base: Context.ServiceClass<Current, "@codeworksh/harness/sandbox/io/Current", Identity>;
+/** Identity and working directory of the current mount. */
+declare class Current extends Current_base {}
+/** Everything a mount provides. */
+type Provides = Current | Service$1 | Shell$1;
+/** A built mount. */
+type Layer$1<E = never, RIn = never> = Layer.Layer<Provides, E, RIn>;
+//#endregion
+//#region src/sandbox/driver.d.ts
+/** Version of the loadable sandbox-driver module ABI. */
+declare const apiVersion: 1;
+type ApiVersion = typeof apiVersion;
+/** Open driver identity. Adding a driver never extends a union in core. */
+declare const Name: Schema.brand<Schema.String, "SandboxDriver.Name">;
+type Name = typeof Name.Type;
+/** A path whose coordinate system is the mounted namespace. */
+declare const AbsolutePath: Schema.brand<Schema.String, "SandboxDriver.AbsolutePath">;
+type AbsolutePath = typeof AbsolutePath.Type;
+declare const RuntimeConfigBase: Schema.Struct<{
+  readonly defaultCwd: Schema.brand<Schema.String, "SandboxDriver.AbsolutePath">;
+}>;
+interface RuntimeConfigBase extends Schema.Schema.Type<typeof RuntimeConfigBase> {}
+interface Capabilities {
+  readonly inspect: boolean;
+  readonly reattach: boolean;
+  readonly wake: boolean;
+  readonly stop: boolean;
+  readonly destroy: boolean;
+  readonly cancels: boolean;
+}
+interface Observed {
+  readonly status: Status;
+  readonly providerStatus?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+interface Provisioned<RuntimeConfig extends RuntimeConfigBase> {
+  readonly providerResourceId?: string | undefined;
+  readonly providerStatus?: string | undefined;
+  readonly runtimeConfig: RuntimeConfig;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+interface RuntimeInput<RuntimeConfig extends RuntimeConfigBase> {
+  readonly id: ID;
+  readonly providerResourceId: Option.Option<string>;
+  readonly runtimeConfig: RuntimeConfig;
+}
+interface Driver<CreateConfig, RuntimeConfig extends RuntimeConfigBase> {
+  readonly name: Name;
+  readonly kind: Exclude<Kind, "local">;
+  readonly capabilities: Capabilities;
+  readonly createConfigCodec: Schema.Codec<CreateConfig, unknown>;
+  readonly runtimeConfigCodec: Schema.Codec<RuntimeConfig, unknown>;
+  readonly create: (input: {
+    readonly instanceId: ID;
+    readonly config: CreateConfig;
+  }) => Effect.Effect<Provisioned<RuntimeConfig>, SandboxProviderError>;
+  readonly runtimeConfigFor?: ((input: {
+    readonly providerResourceId: string;
+    readonly overrides?: Partial<RuntimeConfig> | undefined;
+  }) => Effect.Effect<RuntimeConfig, SandboxProviderError>) | undefined;
+  readonly attach: (input: RuntimeInput<RuntimeConfig>) => Layer.Layer<FileSystem$1 | Shell, SandboxProviderError>;
+  readonly inspect?: (input: RuntimeInput<RuntimeConfig>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly wake?: (input: RuntimeInput<RuntimeConfig>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly stop?: (input: RuntimeInput<RuntimeConfig>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly destroy?: (input: RuntimeInput<RuntimeConfig>) => Effect.Effect<void, SandboxProviderError>;
+}
+type Definition<CreateConfig, RuntimeConfig extends RuntimeConfigBase> = Pick<Driver<CreateConfig, RuntimeConfig>, "name" | "createConfigCodec" | "runtimeConfigCodec">;
+/** Registry-only erased shape. Driver authors construct it via {@link driver}. */
+interface Registered {
+  readonly name: Name;
+  readonly kind: Exclude<Kind, "local">;
+  readonly capabilities: Capabilities;
+  readonly createConfigCodec: Schema.Codec<unknown, unknown>;
+  readonly runtimeConfigCodec: Schema.Codec<RuntimeConfigBase, unknown>;
+  readonly create: (input: {
+    readonly instanceId: ID;
+    readonly config: unknown;
+  }) => Effect.Effect<Provisioned<RuntimeConfigBase>, SandboxProviderError>;
+  readonly runtimeConfigFor?: ((input: {
+    readonly providerResourceId: string;
+    readonly overrides?: Readonly<Record<string, unknown>> | undefined;
+  }) => Effect.Effect<RuntimeConfigBase, SandboxProviderError>) | undefined;
+  readonly attach: (input: RuntimeInput<RuntimeConfigBase>) => Layer.Layer<FileSystem$1 | Shell, SandboxProviderError>;
+  readonly inspect?: (input: RuntimeInput<RuntimeConfigBase>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly wake?: (input: RuntimeInput<RuntimeConfigBase>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly stop?: (input: RuntimeInput<RuntimeConfigBase>) => Effect.Effect<Observed, SandboxProviderError>;
+  readonly destroy?: (input: RuntimeInput<RuntimeConfigBase>) => Effect.Effect<void, SandboxProviderError>;
+}
+type Source = "core" | "builtin" | "package" | "file";
+interface Registration {
+  readonly registered: Registered;
+  readonly apiVersion: ApiVersion;
+  readonly source: Source;
+}
+interface Module<Options> {
+  readonly apiVersion: ApiVersion;
+  readonly name: Name;
+  readonly options: Schema.Codec<Options, unknown>;
+  readonly make: (options: Options) => Registration;
+}
+interface ModuleDefinition<Options> {
+  readonly apiVersion: ApiVersion;
+  readonly name: string | Name;
+  readonly options: Schema.Codec<Options, unknown>;
+  readonly make: (options: Options) => Registration;
+}
+/** Define the default export of a loadable sandbox package. */
+declare const defineModule: <Options>(value: ModuleDefinition<Options>) => Module<Options>;
+/** Construct a driver and its registry contribution. */
+declare const driver: <CreateConfig, RuntimeConfig extends RuntimeConfigBase>(value: Driver<CreateConfig, RuntimeConfig>) => Driver<CreateConfig, RuntimeConfig> & Registration;
+declare namespace instance_d_exports {
+  export { ID, Info, Kind, Ownership, PersistedError, instance_d_exports as SandboxInstance, Status, Usage, fromColumn, fromField, isMountable, mountable, toColumn, toField };
+}
+/**
+ * A Sandbox instance is a **durable filesystem namespace** plus whatever compute
+ * acts on it — a device in Unix terms, which exists whether or not anything has
+ * it mounted. `Sandbox.Controller` is the only thing that creates,
+ * stops, or destroys one; this module is just its identity and state model.
+ *
+ * The application ID is deliberately separate from the driver's own resource
+ * locator: callers never parse a Vercel name or a Daytona ID, driver formats may
+ * change, and a destroyed resource must stay identifiable in Project/Session
+ * history. A missing resource is never recreated under an existing ID — a new
+ * resource is a new namespace and therefore a new ID.
+ */
+declare const ID: Schema.brand<Schema.String, "SandboxInstance.ID"> & {
+  /**
+   * The host. Reserved, and never written to a column — see {@link toColumn}.
+   * It exists at runtime so nothing has to branch on "is this the host": it is
+   * what identity reads, what logs show, and what the transport cache keys on.
+   */
+  local: string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+  /** A fresh identity for a namespace nothing has named yet. */
+  create: () => string & import("effect/Brand").Brand<"SandboxInstance.ID">;
+};
+type ID = typeof ID.Type;
+/**
+ * The storage boundary for namespace references, in one place.
+ *
+ * The host filesystem exists whether or not a row describes it, so it gets no
+ * row and `NULL` is the only spelling of it — the Unix analogue is exact, since
+ * `/` has no entry in the mount table you consult to find other mounts. That
+ * makes a session or directory writable before any namespace is registered (the
+ * foreign key is skipped on NULL), makes `SET sandbox_instance_id = NULL` a
+ * meaningful "revert to the host", and leaves the host impossible to tombstone,
+ * collect, or destroy, because there is nothing to point at.
+ *
+ * Two SQLite consequences ride on this and break correctness silently if missed:
+ * unique indexes treat NULLs as distinct, so every uniqueness constraint
+ * spanning a namespace column coalesces to `'local'`; and `= NULL` never
+ * matches, so namespace-scoped reads use `IS`.
+ */
+declare const toColumn: (id: ID) => string | null;
+declare const fromColumn: (value: string | null) => ID;
+/**
+ * The same mapping for row models, whose optional columns are `Option` rather
+ * than `null`. Kept beside {@link toColumn} so the boundary stays one place:
+ * `toColumn`/`fromColumn` for SQL parameters, these for `Model.FieldOption`.
+ */
+declare const toField: (id: ID) => Option.Option<ID>;
+declare const fromField: (value: Option.Option<ID>) => ID;
+/**
+ * Filesystem-class taxonomy, mirroring Unix: disk, tmpfs/procfs, NFS/CIFS.
+ * Stored on the row rather than derived from the registered driver, so reading
+ * an instance never depends on the registry — which matters most when a driver
+ * is *not* configured and you need to list or clean up its rows.
+ */
+declare const Kind: Schema.Literals<readonly ["local", "virtual", "remote"]>;
+type Kind = typeof Kind.Type;
+declare const Ownership: Schema.Literals<readonly ["managed", "external"]>;
+type Ownership = typeof Ownership.Type;
+/**
+ * Lifecycle state, in ZFS pool vocabulary. This is the **last observed** value,
+ * not live driver truth: Daytona auto-stops and auto-archives, Vercel sandboxes
+ * expire on their own timeout, so drift is normal. `stateObservedAt` carries the
+ * freshness and `Controller.refresh` updates it without waking anything.
+ *
+ * `removed` and `unavail` are deliberately distinct. `removed` means we deleted
+ * it; `unavail` means the driver claims it is gone. A "not found" is frequently a
+ * misclassification — wrong region, wrong API url, a revoked key answering 404,
+ * eventual consistency right after create — so it must never be recorded as if we
+ * had destroyed the resource ourselves.
+ */
+declare const Status: Schema.Literals<readonly ["provisioning", "online", "offline", "suspending", "removing", "removed", "unavail", "faulted"]>;
+type Status = typeof Status.Type;
+/**
+ * The statuses a `mount` may proceed from. This is the predicate every
+ * conditional write depends on, so it is enumerated once here rather than
+ * restated as prose at each call site.
+ *
+ * `offline` qualifies because mounting wakes.
+ * `faulted` qualifies because a fault is a *usability* condition, not an identity one — see {@link Status}.
+ *
+ * There is no `resuming`: it would exist to be observed by nothing, since
+ * mounting wakes, `offline` is already mountable, and waking is not destructive
+ * so it needs no claim. `suspending` and `removing` stay because they *are*
+ * compare-and-set claims, blocking a concurrent mount mid-destruction.
+ */
+declare const mountable: ReadonlySet<Status>;
+declare const isMountable: (status: Status) => boolean;
+/**
+ * Reference state, derived — never stored. `busy` carries its `umount` meaning:
+ * something holds this and destruction must not proceed unforced.
+ *
+ * `pinned` is the kernel sense of the word: never reclaimable. It short-circuits
+ * counting entirely for instances that cannot be stopped or destroyed (the local
+ * host), which is what keeps them out of any future collector by construction
+ * rather than by an ownership check happening to catch them.
+ */
+declare const Usage: Schema.Literals<readonly ["idle", "busy", "pinned"]>;
+type Usage = typeof Usage.Type;
+/** Sanitized driver failure. The only error shape allowed to be persisted or logged. */
+declare const PersistedError: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly message: Schema.String;
+  readonly code: Schema.optional<Schema.String>;
+}>;
+type PersistedError = typeof PersistedError.Type;
+/** Durable metadata, safe to return and persist. Assembled by the control plane. */
+interface Info {
+  readonly id: ID;
+  readonly driver: Name;
+  readonly kind: Kind;
+  readonly providerResourceId: Option.Option<string>;
+  readonly ownership: Ownership;
+  readonly status: Status;
+  readonly usage: Usage;
+  /** References held by *this* control plane. Process-local; see the transport cache. */
+  readonly refCount: number;
+  readonly providerStatus: Option.Option<string>;
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly lastError: Option.Option<PersistedError>;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+  readonly stateObservedAt: Date;
+  readonly lastMountedAt: Option.Option<Date>;
+  readonly lastUnmountedAt: Option.Option<Date>;
+  readonly lastUsedAt: Option.Option<Date>;
+  readonly removedAt: Option.Option<Date>;
+}
+declare namespace driver_d_exports {
+  export { AbsolutePath, ApiVersion, Capabilities, Definition, Driver, Module, ModuleDefinition, Name, Observed, Provisioned, Registration, RuntimeConfigBase as RuntimeConfig, RuntimeConfigBase, RuntimeInput, driver_d_exports as SandboxDriver, apiVersion, driver, defineModule as module };
+}
+declare namespace io_d_exports {
+  export { Current, FileSystem$1 as FileSystem, Identity, Layer$1 as Layer, Provides, io_d_exports as SandboxIO, Shell };
+}
+declare namespace error_d_exports {
+  export { Redactor, SandboxProviderError, makeRedactor, providerError, providerErrorCause, providerErrorIsNotFound, sanitizeError };
+}
+declare namespace resource_d_exports {
+  export { resource_d_exports as SandboxResource, Service };
+}
+declare const Service_base: Context.ServiceClass<Service, "@codeworksh/harness/sandbox/resource/Service", {
+  readonly providerResourceId: string;
+}>;
+/**
+ * The driver's own locator for the attached resource — a Vercel sandbox name, a
+ * Daytona sandbox id.
+ *
+ * Deliberately *not* on `SandboxIO.Current`: consumers never parse one,
+ * and keeps it separate from the application id precisely so a driver's format can
+ * change without touching identity.
+ *
+ * It exists for the control plane, which records it as `provider_resource_id`,
+ * and for tests that reattach to the same resource.
+ *
+ * One tag for every driver rather than one per driver. A mount has exactly one
+ * driver, so there is nothing to disambiguate, and the control plane has to read
+ * the locator without knowing which driver produced it — keeps the
+ * driver name open, so anything keyed on a closed `"vercel" | "daytona"` set is
+ * a bug waiting for the third driver.
+ */
+declare class Service extends Service_base {}
+declare namespace shell_d_exports {
+  export { ExecChunk, ExecResult, ISandboxExe, Shell$1 as Shell, ShellError, ShellOptions, fromExec, quote, quoteArgv };
+}
+//#endregion
+export { SandboxDriverNotRegisteredError as A, Layer$1 as C, SandboxCreateError as D, filesystem_d_exports as E, SandboxRegisterError as F, SandboxStopError as I, SandboxWakeError as L, SandboxMountError as M, SandboxReadError as N, SandboxDestroyError as O, SandboxRefreshError as P, Identity as S, FileSystemError as T, Name as _, driver_d_exports as a, RuntimeConfigBase as b, Status as c, AbsolutePath as d, ApiVersion as f, Module as g, Driver as h, io_d_exports as i, SandboxDriverRegistrationError as j, SandboxDriverLoadError as k, Usage as l, Definition as m, resource_d_exports as n, ID as o, Capabilities as p, error_d_exports as r, Info as s, shell_d_exports as t, instance_d_exports as u, Registered as v, Provides as w, Source as x, Registration as y };
+//# sourceMappingURL=sandbox-DnL9UPzZ.d.mts.map