niceeval 0.16.2 → 0.17.0

package/dist/runner/setup-prefix-plan.d.ts

@@ -1,10 +1,8 @@
 import { type SandboxSetupPrefixCacheEligibility, type SandboxSetupPrefixCacheManifest, type SandboxSetupPrefixCacheOperation } from "../sandbox/backend.js";
 import type { ScheduledSandboxBefore } from "../sandbox/link.js";
 import type { LinkedRunPlan } from "../sandbox/plan.js";
-export declare const SETUP_PREFIX_STORAGE_REVISION = "niceeval.setup-prefix-storage/v2";
 export declare const SETUP_PREFIX_INTERPRETER_REVISION = "niceeval.sandbox-step-interpreter/v1";
 export declare const SETUP_PREFIX_QUIESCE_REVISION = "niceeval.setup-prefix-quiesce/v1";
-export declare const SETUP_PREFIX_CAPTURE_REVISION = "niceeval.setup-prefix-capture/v1";
 export interface PlannedSetupPrefixAction {
     readonly entry: Extract<ScheduledSandboxBefore, {
         readonly kind: "action";

package/dist/runner/setup-prefix-plan.js

@@ -1,16 +1,12 @@
 import { createRequire as __niceevalCreateRequire } from "node:module";
 const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
 const __niceevalCanonical = __niceevalRequire("./setup-prefix-plan.cjs");
-const __niceevalExport0 = __niceevalCanonical["SETUP_PREFIX_CAPTURE_REVISION"];
-export { __niceevalExport0 as SETUP_PREFIX_CAPTURE_REVISION };
-const __niceevalExport1 = __niceevalCanonical["SETUP_PREFIX_INTERPRETER_REVISION"];
-export { __niceevalExport1 as SETUP_PREFIX_INTERPRETER_REVISION };
-const __niceevalExport2 = __niceevalCanonical["SETUP_PREFIX_QUIESCE_REVISION"];
-export { __niceevalExport2 as SETUP_PREFIX_QUIESCE_REVISION };
-const __niceevalExport3 = __niceevalCanonical["SETUP_PREFIX_STORAGE_REVISION"];
-export { __niceevalExport3 as SETUP_PREFIX_STORAGE_REVISION };
-const __niceevalExport4 = __niceevalCanonical["plannedSetupPrefixActions"];
-export { __niceevalExport4 as plannedSetupPrefixActions };
-const __niceevalExport5 = __niceevalCanonical["setupPrefixOperation"];
-export { __niceevalExport5 as setupPrefixOperation };
+const __niceevalExport0 = __niceevalCanonical["SETUP_PREFIX_INTERPRETER_REVISION"];
+export { __niceevalExport0 as SETUP_PREFIX_INTERPRETER_REVISION };
+const __niceevalExport1 = __niceevalCanonical["SETUP_PREFIX_QUIESCE_REVISION"];
+export { __niceevalExport1 as SETUP_PREFIX_QUIESCE_REVISION };
+const __niceevalExport2 = __niceevalCanonical["plannedSetupPrefixActions"];
+export { __niceevalExport2 as plannedSetupPrefixActions };
+const __niceevalExport3 = __niceevalCanonical["setupPrefixOperation"];
+export { __niceevalExport3 as setupPrefixOperation };
 //# sourceMappingURL=setup-prefix-plan.js.map

package/dist/sandbox/backend.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxManagedProcessCapabilityError = exports.noSandboxBackendCapabilities = exports.unsupportedBackendCapability = exports.SandboxSetupPrefixCacheCancellationError = exports.SandboxSetupPrefixCacheAmbiguityError = exports.SandboxSetupPrefixCacheCleanupError = exports.SandboxSetupPrefixCacheValidationError = exports.SandboxSetupPrefixCacheRestoreError = exports.SandboxSetupPrefixCacheCaptureError = exports.SandboxSetupPrefixCacheLookupError = exports.SandboxSetupPrefixCacheRegistryError = void 0;
+exports.SandboxManagedProcessCapabilityError = exports.noSandboxBackendCapabilities = exports.unsupportedBackendCapability = exports.SandboxSetupPrefixCacheCancellationError = exports.SandboxSetupPrefixCacheAmbiguityError = exports.SandboxSetupPrefixCacheCleanupError = exports.SandboxSetupPrefixCacheValidationError = exports.SandboxSetupPrefixCacheRestoreError = exports.SandboxSetupPrefixCacheCaptureError = exports.SandboxSetupPrefixCacheLookupError = exports.SandboxSetupPrefixCacheRegistryError = exports.decodeSandboxSetupPrefixCacheKeyScope = void 0;
 exports.unsupportedBackendCapabilityBecause = unsupportedBackendCapabilityBecause;
 exports.supportedBackendCapability = supportedBackendCapability;
 exports.setupPrefixCacheCapability = setupPrefixCacheCapability;
@@ -15,6 +15,15 @@ exports.requireManagedProcessCapability = requireManagedProcessCapability;
 exports.sandboxReuseCapability = sandboxReuseCapability;
 // Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。
 const effect_1 = require("effect");
+const json_value_ts_1 = require("../shared/json-value.cjs");
+const SandboxSetupPrefixCacheKeyScopeSchema = effect_1.Schema.Struct({
+    protocol: effect_1.Schema.String,
+    storageSchemaRevision: effect_1.Schema.String,
+    artifactFormatRevision: effect_1.Schema.String,
+    semanticIdentity: effect_1.Schema.Json.pipe(effect_1.Schema.refine(json_value_ts_1.isJsonValue)),
+});
+/** Provider boundary: a completed cache plan never relies on core defaults. */
+exports.decodeSandboxSetupPrefixCacheKeyScope = effect_1.Schema.decodeUnknownSync(SandboxSetupPrefixCacheKeyScopeSchema, { onExcessProperty: "error" });
 class SandboxSetupPrefixCacheRegistryError extends effect_1.Data.TaggedError("SandboxSetupPrefixCacheRegistryError") {
 }
 exports.SandboxSetupPrefixCacheRegistryError = SandboxSetupPrefixCacheRegistryError;

package/dist/sandbox/backend.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["backend.ts"],"names":[],"mappings":"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","sourcesContent":["// Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。\nimport { Data, Effect } from \"effect\";\nimport type { SandboxActionState } from \"./action.ts\";\nimport type { CommandOptions, CommandResult, CustomProviderSandbox, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations, } from \"./types.ts\";\nexport type SandboxBackendSupport<T> = {\n    readonly _tag: \"Supported\";\n    readonly value: T;\n} | {\n    readonly _tag: \"Unsupported\";\n    readonly reason: string;\n};\nexport type SandboxSetupPrefixCacheUnsupportedCode = \"provider-unsupported\" | \"profile-managed\" | \"compose\" | \"host-socket\" | \"read-only-rootfs\" | \"base-image-unverified\" | \"dynamic-runner-tools\" | \"mounted-state\" | \"sensitive-state\" | \"profile-backed-dind\";\nexport type SandboxSetupPrefixCacheEligibility = {\n    readonly _tag: \"Eligible\";\n    readonly persistence: \"persistent\";\n    readonly dependency: \"parent-backed\";\n    /** Complete action-state surface this provider captures and restores. */\n    readonly coverage: SandboxActionState;\n    /** Exact immutable Base resolved and verified during provider initialization. */\n    readonly baseImageId: string;\n    /** Provider-owned key scope; omission preserves the ordinary Docker rootfs identity exactly. */\n    readonly keyScope?: {\n        readonly protocol: string;\n        readonly storageSchemaRevision: string;\n        readonly artifactFormatRevision: string;\n        readonly semanticIdentity: import(\"../shared/types.ts\").JsonValue;\n    };\n} | {\n    readonly _tag: \"Unsupported\";\n    readonly code: SandboxSetupPrefixCacheUnsupportedCode;\n    readonly reason: string;\n};\nexport interface SandboxSetupPrefixCacheManifest {\n    /** Exact immutable Base identity; floating source references never enter the durable root key alone. */\n    readonly baseImageId: string;\n    /** Content-addressed key planned by the provider-neutral runtime. */\n    readonly setupPrefixKey: string;\n    readonly setupManifestDigest: string;\n    /** Cumulative state required by this exact logical prefix. */\n    readonly requiredState: SandboxActionState;\n    readonly storageSchemaRevision: string;\n    readonly artifactFormatRevision: string;\n    readonly changeFrequency: number;\n    /** Frozen, non-sensitive declaration metadata used for bidirectional registry validation. */\n    readonly declarationMetadata: unknown;\n}\nexport interface SandboxSetupPrefixCacheOperation {\n    readonly operationId: string;\n    readonly manifest: SandboxSetupPrefixCacheManifest;\n    /** Defense-in-depth only; values are checked before an image is published and are never persisted. */\n    readonly knownSensitiveValues?: readonly string[];\n}\ninterface SandboxSetupPrefixCacheErrorFields {\n    readonly operation: string;\n    readonly reason: string;\n    readonly setupPrefixKey?: string;\n    readonly domainId?: string;\n    readonly cause?: unknown;\n}\nexport class SandboxSetupPrefixCacheRegistryError extends Data.TaggedError(\"SandboxSetupPrefixCacheRegistryError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheLookupError extends Data.TaggedError(\"SandboxSetupPrefixCacheLookupError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheCaptureError extends Data.TaggedError(\"SandboxSetupPrefixCacheCaptureError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheRestoreError extends Data.TaggedError(\"SandboxSetupPrefixCacheRestoreError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheValidationError extends Data.TaggedError(\"SandboxSetupPrefixCacheValidationError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheCleanupError extends Data.TaggedError(\"SandboxSetupPrefixCacheCleanupError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheAmbiguityError extends Data.TaggedError(\"SandboxSetupPrefixCacheAmbiguityError\")<SandboxSetupPrefixCacheErrorFields & {\n    readonly operationId: string;\n    readonly terminal: \"unresolved\";\n    readonly diagnosticCommand: string;\n}> {\n}\nexport class SandboxSetupPrefixCacheCancellationError extends Data.TaggedError(\"SandboxSetupPrefixCacheCancellationError\")<SandboxSetupPrefixCacheErrorFields & {\n    readonly operationId: string;\n    readonly terminal: \"cancel-fenced\";\n}> {\n}\nexport type SandboxSetupPrefixCacheError = SandboxSetupPrefixCacheRegistryError | SandboxSetupPrefixCacheLookupError | SandboxSetupPrefixCacheCaptureError | SandboxSetupPrefixCacheRestoreError | SandboxSetupPrefixCacheValidationError | SandboxSetupPrefixCacheCleanupError | SandboxSetupPrefixCacheAmbiguityError | SandboxSetupPrefixCacheCancellationError;\nexport type SandboxSetupPrefixCacheLookupResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"Miss\";\n    readonly setupPrefixKey: string;\n    /** A failed hit was scrubbed in the same private slot before this clean miss receipt. */\n    readonly recovery?: \"restore-failed-replayed\";\n} | {\n    readonly _tag: \"Restored\";\n    readonly setupPrefixKey: string;\n    readonly entryId: string;\n    readonly generation: number;\n    /** Provider-neutral immutable artifact identity. */\n    readonly artifactId: string;\n    /** Present only when the provider artifact is an exact Docker image. */\n    readonly imageId?: string;\n    readonly sandboxId: string;\n};\nexport type SandboxSetupPrefixCacheCaptureResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"Contended\";\n    readonly setupPrefixKey: string;\n    readonly reason: \"active-writer\" | \"indexed-generation\";\n} | {\n    /**\n     * The action already succeeded and the same private sandbox is still a\n     * verified active continuation. The Runner must never clean-base/replay\n     * that action and must disable publication for the remainder of Attempt.\n     */\n    readonly _tag: \"ContinuedUncached\";\n    readonly setupPrefixKey: string;\n    readonly reason: \"capture-failed\" | \"publish-failed\";\n    readonly sandboxId: string;\n} | {\n    readonly _tag: \"Captured\";\n    readonly setupPrefixKey: string;\n    readonly entryId: string;\n    readonly generation: number;\n    /** Provider-neutral immutable artifact identity. */\n    readonly artifactId: string;\n    /** Present only when the provider artifact is an exact Docker image. */\n    readonly imageId?: string;\n    readonly sandboxId: string;\n};\nexport type SandboxSetupPrefixCacheRecoveryResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"RecoveredCleanBase\";\n    readonly baseImageId: string;\n    readonly sandboxId: string;\n};\nexport interface SandboxSetupPrefixCacheCapability {\n    eligibility(): SandboxSetupPrefixCacheEligibility;\n    lookupAndRebase(input: SandboxSetupPrefixCacheOperation): Effect.Effect<SandboxSetupPrefixCacheLookupResult, SandboxSetupPrefixCacheError>;\n    captureAndRebase(input: SandboxSetupPrefixCacheOperation): Effect.Effect<SandboxSetupPrefixCacheCaptureResult, SandboxSetupPrefixCacheError>;\n    /**\n     * One-shot degraded-path seam, only valid before any Action has succeeded in\n     * the current Attempt. The provider DestroyOnly-retires a failed lookup\n     * instance and rebases this stable backend onto the exact Base. Capture\n     * failure paths must return ContinuedUncached or fail; they must never call\n     * this seam and replay an already-successful Action.\n     */\n    recoverCleanBase(): Effect.Effect<SandboxSetupPrefixCacheRecoveryResult, SandboxSetupPrefixCacheError>;\n}\nexport interface SandboxBackendCapabilities {\n    /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */\n    readonly rootCommands: SandboxBackendSupport<true>;\n    readonly appendLog: SandboxBackendSupport<(line: string) => Promise<void>>;\n    readonly suspend: SandboxBackendSupport<() => Promise<void>>;\n    readonly ensureLifetime: SandboxBackendSupport<(minRemainingMs: number) => Promise<{\n        ready: true;\n        expiresAt?: string;\n    } | {\n        ready: false;\n        reason: string;\n    }>>;\n    readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;\n    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;\n    /** Missing providers are normalized to an explicit Unsupported result by setupPrefixCacheCapability(). */\n    readonly setupPrefixCache?: SandboxBackendSupport<SandboxSetupPrefixCacheCapability>;\n}\nexport interface SandboxProviderBackend extends Omit<SandboxTransferOperations, \"upload\"> {\n    readonly workdir: string;\n    readonly sandboxId: string;\n    readonly otlpHost: string | null;\n    readonly capabilities: SandboxBackendCapabilities;\n    runCommand(command: string, args?: readonly string[], options?: CommandOptions): Promise<CommandResult>;\n    runShell(script: string, options?: CommandOptions): Promise<CommandResult>;\n    readText(path: string): Promise<string>;\n    writeText(path: string, content: string): Promise<void>;\n    readBytes(path: string): Promise<Uint8Array>;\n    writeBytes(path: string, content: Uint8Array): Promise<void>;\n    pathExists(path: string): Promise<boolean>;\n    stop(): Promise<void>;\n}\nexport const unsupportedBackendCapability: SandboxBackendSupport<never> = Object.freeze({\n    _tag: \"Unsupported\",\n    reason: \"the provider does not implement this capability\",\n});\nexport function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never> {\n    return Object.freeze({ _tag: \"Unsupported\", reason });\n}\nexport const noSandboxBackendCapabilities: SandboxBackendCapabilities = Object.freeze({\n    rootCommands: unsupportedBackendCapability,\n    appendLog: unsupportedBackendCapability,\n    suspend: unsupportedBackendCapability,\n    ensureLifetime: unsupportedBackendCapability,\n    setCommandDeadline: unsupportedBackendCapability,\n    managedProcess: unsupportedBackendCapability,\n});\nexport function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T> {\n    return Object.freeze({ _tag: \"Supported\", value });\n}\n/** Provider-neutral query seam; absence never masquerades as a cache miss. */\nexport function setupPrefixCacheCapability(capabilities: SandboxBackendCapabilities): SandboxBackendSupport<SandboxSetupPrefixCacheCapability> {\n    return capabilities.setupPrefixCache ?? unsupportedBackendCapabilityBecause(\"the provider does not implement persistent sandbox setup-prefix caching\");\n}\nfunction providerBoundaryError(cause: unknown): Error {\n    return cause instanceof Error ? cause : new Error(String(cause));\n}\n/** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */\nexport function providerBoundaryEffect<T>(operation: (signal: AbortSignal) => Promise<T>): Effect.Effect<T, Error> {\n    return Effect.tryPromise({\n        // 保留 Effect 运行时的取消信号，供真正支持 AbortSignal 的 SDK adapter 接入；不把中断\n        // 编码成 Error，也不在这里启动嵌套 runtime。\n        try: (signal) => operation(signal),\n        catch: providerBoundaryError,\n    });\n}\n/**\n * 公开 Sandbox Promise 接口唯一的兼容入口。\n *\n * 这不是内部 Effect runner：它只把 provider Promise 原样留在公开兼容面，并归一化非 Error\n * rejection。runtime / resource lifecycle 必须改用 providerBoundaryEffect() 组合 Effect。\n */\nexport async function providerCompatibilityPromise<T>(operation: () => Promise<T>): Promise<T> {\n    try {\n        return await operation();\n    }\n    catch (cause) {\n        throw providerBoundaryError(cause);\n    }\n}\n/** defineSandbox() 的公共新接口实现显式降成 provider backend；不探测任何旧方法。 */\nexport function customSandboxBackend(sandbox: CustomProviderSandbox): SandboxProviderBackend {\n    const appendLog = sandbox.appendLog;\n    // Provider facade 产出的 Sandbox 再经 runtime 归一化时必须保留 provider-only capabilities；\n    // 作者直接返回的普通 Sandbox 没有登记项，仍严格退回 Unsupported，不能靠鸭子类型猜能力。\n    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? {\n        ...noSandboxBackendCapabilities,\n        managedProcess: unsupportedBackendCapabilityBecause(\"custom Sandbox facades do not declare the internal managed-process capability\"),\n    };\n    return {\n        get workdir() {\n            return sandbox.workdir;\n        },\n        get sandboxId() {\n            return sandbox.sandboxId;\n        },\n        get otlpHost() {\n            return sandbox.otlpHost;\n        },\n        capabilities: {\n            ...registered,\n            appendLog: appendLog === undefined\n                ? unsupportedBackendCapability\n                : supportedBackendCapability((line) => appendLog.call(sandbox, line)),\n        },\n        runCommand: (command, args, options) => sandbox.runCommand(command, args, options),\n        runShell: (script, options) => sandbox.runShell(script, options),\n        readText: (path) => sandbox.readText(path),\n        writeText: (path, content) => sandbox.writeText(path, content),\n        readBytes: (path) => sandbox.readBytes(path),\n        writeBytes: (path, content) => sandbox.writeBytes(path, content),\n        pathExists: (path) => sandbox.pathExists(path),\n        uploadFile: (source, targetPath) => sandbox.uploadFile(source, targetPath),\n        uploadDirectory: (sourceDir, targetDir, options) => sandbox.uploadDirectory(sourceDir, targetDir, options),\n        downloadFile: (sourcePath, target) => sandbox.downloadFile(sourcePath, target),\n        downloadDirectory: (sourceDir, targetDir, options) => sandbox.downloadDirectory(sourceDir, targetDir, options),\n        stop: () => sandbox.stop(),\n    };\n}\nconst SANDBOX_CAPABILITIES = new WeakMap<CustomProviderSandbox, SandboxBackendCapabilities>();\nexport function registerSandboxCapabilities(sandbox: Sandbox, capabilities: SandboxBackendCapabilities): void {\n    SANDBOX_CAPABILITIES.set(sandbox, capabilities);\n}\n/** 装饰器产生新 Sandbox 对象时显式继承同一份 provider-only 能力，不靠接口外成员探测。 */\nexport function inheritSandboxCapabilities(source: Sandbox, target: Sandbox): void {\n    const capabilities = SANDBOX_CAPABILITIES.get(source);\n    if (capabilities !== undefined)\n        SANDBOX_CAPABILITIES.set(target, capabilities);\n}\nexport function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities {\n    const capabilities = SANDBOX_CAPABILITIES.get(sandbox);\n    if (capabilities === undefined) {\n        throw new Error(`sandbox ${sandbox.sandboxId} was not constructed by the provider facade`);\n    }\n    return capabilities;\n}\n/** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */\nexport function sandboxSupportsRootCommands(sandbox: Sandbox): boolean {\n    return SANDBOX_CAPABILITIES.get(sandbox)?.rootCommands._tag === \"Supported\";\n}\nexport class SandboxManagedProcessCapabilityError extends Error {\n    readonly name = \"SandboxManagedProcessCapabilityError\";\n    constructor(readonly agent: string, readonly sandboxId: string, readonly reason: string) {\n        super(`Agent ${agent} requires the sandbox managed-process capability, but sandbox ${sandboxId} does not support it: ${reason}`);\n    }\n}\nexport function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess> {\n    const capability = sandboxCapabilities(sandbox).managedProcess;\n    if (capability._tag === \"Unsupported\") {\n        throw new SandboxManagedProcessCapabilityError(agent, sandbox.sandboxId, capability.reason);\n    }\n    return capability.value;\n}\n/** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */\nexport function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined {\n    const capability = sandboxCapabilities(sandbox).ensureLifetime;\n    return capability._tag === \"Supported\" ? { ensureLifetime: capability.value } : undefined;\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["backend.ts"],"names":[],"mappings":"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","sourcesContent":["// Provider Promise SDK 与公共 Sandbox facade 之间的唯一边界。\nimport { Data, Effect, Schema } from \"effect\";\nimport { isJsonValue } from \"../shared/json-value.ts\";\nimport type { SandboxActionState } from \"./action.ts\";\nimport type { CommandOptions, CommandResult, CustomProviderSandbox, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations, } from \"./types.ts\";\nexport type SandboxBackendSupport<T> = {\n    readonly _tag: \"Supported\";\n    readonly value: T;\n} | {\n    readonly _tag: \"Unsupported\";\n    readonly reason: string;\n};\nexport type SandboxSetupPrefixCacheUnsupportedCode = \"provider-unsupported\" | \"profile-managed\" | \"compose\" | \"host-socket\" | \"read-only-rootfs\" | \"base-image-unverified\" | \"dynamic-runner-tools\" | \"mounted-state\" | \"sensitive-state\" | \"profile-backed-dind\";\nconst SandboxSetupPrefixCacheKeyScopeSchema = Schema.Struct({\n    protocol: Schema.String,\n    storageSchemaRevision: Schema.String,\n    artifactFormatRevision: Schema.String,\n    semanticIdentity: Schema.Json.pipe(Schema.refine(isJsonValue)),\n});\n/** Provider boundary: a completed cache plan never relies on core defaults. */\nexport const decodeSandboxSetupPrefixCacheKeyScope = Schema.decodeUnknownSync(SandboxSetupPrefixCacheKeyScopeSchema, { onExcessProperty: \"error\" });\nexport type SandboxSetupPrefixCacheEligibility = {\n    readonly _tag: \"Eligible\";\n    readonly persistence: \"persistent\";\n    readonly dependency: \"parent-backed\";\n    /** Complete action-state surface this provider captures and restores. */\n    readonly coverage: SandboxActionState;\n    /** Exact immutable Base resolved and verified during provider initialization. */\n    readonly baseImageId: string;\n    /** Complete provider-owned identity, decoded before entering core planning. */\n    readonly keyScope: Schema.Schema.Type<typeof SandboxSetupPrefixCacheKeyScopeSchema>;\n} | {\n    readonly _tag: \"Unsupported\";\n    readonly code: SandboxSetupPrefixCacheUnsupportedCode;\n    readonly reason: string;\n};\nexport interface SandboxSetupPrefixCacheManifest {\n    /** Exact immutable Base identity; floating source references never enter the durable root key alone. */\n    readonly baseImageId: string;\n    /** Content-addressed key planned by the provider-neutral runtime. */\n    readonly setupPrefixKey: string;\n    readonly setupManifestDigest: string;\n    /** Cumulative state required by this exact logical prefix. */\n    readonly requiredState: SandboxActionState;\n    readonly storageSchemaRevision: string;\n    readonly artifactFormatRevision: string;\n    readonly changeFrequency: number;\n    /** Frozen, non-sensitive declaration metadata used for bidirectional registry validation. */\n    readonly declarationMetadata: unknown;\n}\nexport interface SandboxSetupPrefixCacheOperation {\n    readonly operationId: string;\n    readonly manifest: SandboxSetupPrefixCacheManifest;\n    /** Defense-in-depth only; values are checked before an image is published and are never persisted. */\n    readonly knownSensitiveValues?: readonly string[];\n}\ninterface SandboxSetupPrefixCacheErrorFields {\n    readonly operation: string;\n    readonly reason: string;\n    readonly setupPrefixKey?: string;\n    readonly domainId?: string;\n    readonly cause?: unknown;\n}\nexport class SandboxSetupPrefixCacheRegistryError extends Data.TaggedError(\"SandboxSetupPrefixCacheRegistryError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheLookupError extends Data.TaggedError(\"SandboxSetupPrefixCacheLookupError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheCaptureError extends Data.TaggedError(\"SandboxSetupPrefixCacheCaptureError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheRestoreError extends Data.TaggedError(\"SandboxSetupPrefixCacheRestoreError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheValidationError extends Data.TaggedError(\"SandboxSetupPrefixCacheValidationError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheCleanupError extends Data.TaggedError(\"SandboxSetupPrefixCacheCleanupError\")<SandboxSetupPrefixCacheErrorFields> {\n}\nexport class SandboxSetupPrefixCacheAmbiguityError extends Data.TaggedError(\"SandboxSetupPrefixCacheAmbiguityError\")<SandboxSetupPrefixCacheErrorFields & {\n    readonly operationId: string;\n    readonly terminal: \"unresolved\";\n    readonly diagnosticCommand: string;\n}> {\n}\nexport class SandboxSetupPrefixCacheCancellationError extends Data.TaggedError(\"SandboxSetupPrefixCacheCancellationError\")<SandboxSetupPrefixCacheErrorFields & {\n    readonly operationId: string;\n    readonly terminal: \"cancel-fenced\";\n}> {\n}\nexport type SandboxSetupPrefixCacheError = SandboxSetupPrefixCacheRegistryError | SandboxSetupPrefixCacheLookupError | SandboxSetupPrefixCacheCaptureError | SandboxSetupPrefixCacheRestoreError | SandboxSetupPrefixCacheValidationError | SandboxSetupPrefixCacheCleanupError | SandboxSetupPrefixCacheAmbiguityError | SandboxSetupPrefixCacheCancellationError;\nexport type SandboxSetupPrefixCacheLookupResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"Miss\";\n    readonly setupPrefixKey: string;\n    /** A failed hit was scrubbed in the same private slot before this clean miss receipt. */\n    readonly recovery?: \"restore-failed-replayed\";\n} | {\n    readonly _tag: \"Restored\";\n    readonly setupPrefixKey: string;\n    readonly entryId: string;\n    readonly generation: number;\n    /** Provider-neutral immutable artifact identity. */\n    readonly artifactId: string;\n    /** Present only when the provider artifact is an exact Docker image. */\n    readonly imageId?: string;\n    readonly sandboxId: string;\n};\nexport type SandboxSetupPrefixCacheCaptureResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"Contended\";\n    readonly setupPrefixKey: string;\n    readonly reason: \"active-writer\" | \"indexed-generation\";\n} | {\n    /**\n     * The action already succeeded and the same private sandbox is still a\n     * verified active continuation. The Runner must never clean-base/replay\n     * that action and must disable publication for the remainder of Attempt.\n     */\n    readonly _tag: \"ContinuedUncached\";\n    readonly setupPrefixKey: string;\n    readonly reason: \"capture-failed\" | \"publish-failed\";\n    readonly sandboxId: string;\n} | {\n    readonly _tag: \"Captured\";\n    readonly setupPrefixKey: string;\n    readonly entryId: string;\n    readonly generation: number;\n    /** Provider-neutral immutable artifact identity. */\n    readonly artifactId: string;\n    /** Present only when the provider artifact is an exact Docker image. */\n    readonly imageId?: string;\n    readonly sandboxId: string;\n};\nexport type SandboxSetupPrefixCacheRecoveryResult = Exclude<SandboxSetupPrefixCacheEligibility, {\n    readonly _tag: \"Eligible\";\n}> | {\n    readonly _tag: \"RecoveredCleanBase\";\n    readonly baseImageId: string;\n    readonly sandboxId: string;\n};\nexport interface SandboxSetupPrefixCacheCapability {\n    eligibility(): SandboxSetupPrefixCacheEligibility;\n    lookupAndRebase(input: SandboxSetupPrefixCacheOperation): Effect.Effect<SandboxSetupPrefixCacheLookupResult, SandboxSetupPrefixCacheError>;\n    captureAndRebase(input: SandboxSetupPrefixCacheOperation): Effect.Effect<SandboxSetupPrefixCacheCaptureResult, SandboxSetupPrefixCacheError>;\n    /**\n     * One-shot degraded-path seam, only valid before any Action has succeeded in\n     * the current Attempt. The provider DestroyOnly-retires a failed lookup\n     * instance and rebases this stable backend onto the exact Base. Capture\n     * failure paths must return ContinuedUncached or fail; they must never call\n     * this seam and replay an already-successful Action.\n     */\n    recoverCleanBase(): Effect.Effect<SandboxSetupPrefixCacheRecoveryResult, SandboxSetupPrefixCacheError>;\n}\nexport interface SandboxBackendCapabilities {\n    /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */\n    readonly rootCommands: SandboxBackendSupport<true>;\n    readonly appendLog: SandboxBackendSupport<(line: string) => Promise<void>>;\n    readonly suspend: SandboxBackendSupport<() => Promise<void>>;\n    readonly ensureLifetime: SandboxBackendSupport<(minRemainingMs: number) => Promise<{\n        ready: true;\n        expiresAt?: string;\n    } | {\n        ready: false;\n        reason: string;\n    }>>;\n    readonly setCommandDeadline: SandboxBackendSupport<(deadlineAt?: number) => void>;\n    readonly managedProcess: SandboxBackendSupport<(input: ManagedProcessStart) => Promise<ManagedProcess>>;\n    /** Missing providers are normalized to an explicit Unsupported result by setupPrefixCacheCapability(). */\n    readonly setupPrefixCache?: SandboxBackendSupport<SandboxSetupPrefixCacheCapability>;\n}\nexport interface SandboxProviderBackend extends Omit<SandboxTransferOperations, \"upload\"> {\n    readonly workdir: string;\n    readonly sandboxId: string;\n    readonly otlpHost: string | null;\n    readonly capabilities: SandboxBackendCapabilities;\n    runCommand(command: string, args?: readonly string[], options?: CommandOptions): Promise<CommandResult>;\n    runShell(script: string, options?: CommandOptions): Promise<CommandResult>;\n    readText(path: string): Promise<string>;\n    writeText(path: string, content: string): Promise<void>;\n    readBytes(path: string): Promise<Uint8Array>;\n    writeBytes(path: string, content: Uint8Array): Promise<void>;\n    pathExists(path: string): Promise<boolean>;\n    stop(): Promise<void>;\n}\nexport const unsupportedBackendCapability: SandboxBackendSupport<never> = Object.freeze({\n    _tag: \"Unsupported\",\n    reason: \"the provider does not implement this capability\",\n});\nexport function unsupportedBackendCapabilityBecause(reason: string): SandboxBackendSupport<never> {\n    return Object.freeze({ _tag: \"Unsupported\", reason });\n}\nexport const noSandboxBackendCapabilities: SandboxBackendCapabilities = Object.freeze({\n    rootCommands: unsupportedBackendCapability,\n    appendLog: unsupportedBackendCapability,\n    suspend: unsupportedBackendCapability,\n    ensureLifetime: unsupportedBackendCapability,\n    setCommandDeadline: unsupportedBackendCapability,\n    managedProcess: unsupportedBackendCapability,\n});\nexport function supportedBackendCapability<T>(value: T): SandboxBackendSupport<T> {\n    return Object.freeze({ _tag: \"Supported\", value });\n}\n/** Provider-neutral query seam; absence never masquerades as a cache miss. */\nexport function setupPrefixCacheCapability(capabilities: SandboxBackendCapabilities): SandboxBackendSupport<SandboxSetupPrefixCacheCapability> {\n    return capabilities.setupPrefixCache ?? unsupportedBackendCapabilityBecause(\"the provider does not implement persistent sandbox setup-prefix caching\");\n}\nfunction providerBoundaryError(cause: unknown): Error {\n    return cause instanceof Error ? cause : new Error(String(cause));\n}\n/** Promise provider SDK 在这一处 lift 成 typed-error Effect；Error 实例原样保留给现有归因逻辑。 */\nexport function providerBoundaryEffect<T>(operation: (signal: AbortSignal) => Promise<T>): Effect.Effect<T, Error> {\n    return Effect.tryPromise({\n        // 保留 Effect 运行时的取消信号，供真正支持 AbortSignal 的 SDK adapter 接入；不把中断\n        // 编码成 Error，也不在这里启动嵌套 runtime。\n        try: (signal) => operation(signal),\n        catch: providerBoundaryError,\n    });\n}\n/**\n * 公开 Sandbox Promise 接口唯一的兼容入口。\n *\n * 这不是内部 Effect runner：它只把 provider Promise 原样留在公开兼容面，并归一化非 Error\n * rejection。runtime / resource lifecycle 必须改用 providerBoundaryEffect() 组合 Effect。\n */\nexport async function providerCompatibilityPromise<T>(operation: () => Promise<T>): Promise<T> {\n    try {\n        return await operation();\n    }\n    catch (cause) {\n        throw providerBoundaryError(cause);\n    }\n}\n/** defineSandbox() 的公共新接口实现显式降成 provider backend；不探测任何旧方法。 */\nexport function customSandboxBackend(sandbox: CustomProviderSandbox): SandboxProviderBackend {\n    const appendLog = sandbox.appendLog;\n    // Provider facade 产出的 Sandbox 再经 runtime 归一化时必须保留 provider-only capabilities；\n    // 作者直接返回的普通 Sandbox 没有登记项，仍严格退回 Unsupported，不能靠鸭子类型猜能力。\n    const registered = SANDBOX_CAPABILITIES.get(sandbox) ?? {\n        ...noSandboxBackendCapabilities,\n        managedProcess: unsupportedBackendCapabilityBecause(\"custom Sandbox facades do not declare the internal managed-process capability\"),\n    };\n    return {\n        get workdir() {\n            return sandbox.workdir;\n        },\n        get sandboxId() {\n            return sandbox.sandboxId;\n        },\n        get otlpHost() {\n            return sandbox.otlpHost;\n        },\n        capabilities: {\n            ...registered,\n            appendLog: appendLog === undefined\n                ? unsupportedBackendCapability\n                : supportedBackendCapability((line) => appendLog.call(sandbox, line)),\n        },\n        runCommand: (command, args, options) => sandbox.runCommand(command, args, options),\n        runShell: (script, options) => sandbox.runShell(script, options),\n        readText: (path) => sandbox.readText(path),\n        writeText: (path, content) => sandbox.writeText(path, content),\n        readBytes: (path) => sandbox.readBytes(path),\n        writeBytes: (path, content) => sandbox.writeBytes(path, content),\n        pathExists: (path) => sandbox.pathExists(path),\n        uploadFile: (source, targetPath) => sandbox.uploadFile(source, targetPath),\n        uploadDirectory: (sourceDir, targetDir, options) => sandbox.uploadDirectory(sourceDir, targetDir, options),\n        downloadFile: (sourcePath, target) => sandbox.downloadFile(sourcePath, target),\n        downloadDirectory: (sourceDir, targetDir, options) => sandbox.downloadDirectory(sourceDir, targetDir, options),\n        stop: () => sandbox.stop(),\n    };\n}\nconst SANDBOX_CAPABILITIES = new WeakMap<CustomProviderSandbox, SandboxBackendCapabilities>();\nexport function registerSandboxCapabilities(sandbox: Sandbox, capabilities: SandboxBackendCapabilities): void {\n    SANDBOX_CAPABILITIES.set(sandbox, capabilities);\n}\n/** 装饰器产生新 Sandbox 对象时显式继承同一份 provider-only 能力，不靠接口外成员探测。 */\nexport function inheritSandboxCapabilities(source: Sandbox, target: Sandbox): void {\n    const capabilities = SANDBOX_CAPABILITIES.get(source);\n    if (capabilities !== undefined)\n        SANDBOX_CAPABILITIES.set(target, capabilities);\n}\nexport function sandboxCapabilities(sandbox: Sandbox): SandboxBackendCapabilities {\n    const capabilities = SANDBOX_CAPABILITIES.get(sandbox);\n    if (capabilities === undefined) {\n        throw new Error(`sandbox ${sandbox.sandboxId} was not constructed by the provider facade`);\n    }\n    return capabilities;\n}\n/** 未经 provider facade 登记的普通自定义 Sandbox 保守视为不支持提权，不做鸭子类型猜测。 */\nexport function sandboxSupportsRootCommands(sandbox: Sandbox): boolean {\n    return SANDBOX_CAPABILITIES.get(sandbox)?.rootCommands._tag === \"Supported\";\n}\nexport class SandboxManagedProcessCapabilityError extends Error {\n    readonly name = \"SandboxManagedProcessCapabilityError\";\n    constructor(readonly agent: string, readonly sandboxId: string, readonly reason: string) {\n        super(`Agent ${agent} requires the sandbox managed-process capability, but sandbox ${sandboxId} does not support it: ${reason}`);\n    }\n}\nexport function requireManagedProcessCapability(sandbox: Sandbox, agent: string): (input: ManagedProcessStart) => Promise<ManagedProcess> {\n    const capability = sandboxCapabilities(sandbox).managedProcess;\n    if (capability._tag === \"Unsupported\") {\n        throw new SandboxManagedProcessCapabilityError(agent, sandbox.sandboxId, capability.reason);\n    }\n    return capability.value;\n}\n/** Provider facade 登记的复用寿命能力；不存在时保持显式 Unsupported，不做鸭子类型探测。 */\nexport function sandboxReuseCapability(sandbox: Sandbox): SandboxReuseCapability | undefined {\n    const capability = sandboxCapabilities(sandbox).ensureLifetime;\n    return capability._tag === \"Supported\" ? { ensureLifetime: capability.value } : undefined;\n}\n"]}

package/dist/sandbox/backend.d.cts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import type { SandboxActionState } from "./action.cjs";
 import type { CommandOptions, CommandResult, CustomProviderSandbox, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.cjs";
 export type SandboxBackendSupport<T> = {
@@ -9,6 +9,19 @@ export type SandboxBackendSupport<T> = {
     readonly reason: string;
 };
 export type SandboxSetupPrefixCacheUnsupportedCode = "provider-unsupported" | "profile-managed" | "compose" | "host-socket" | "read-only-rootfs" | "base-image-unverified" | "dynamic-runner-tools" | "mounted-state" | "sensitive-state" | "profile-backed-dind";
+declare const SandboxSetupPrefixCacheKeyScopeSchema: Schema.Struct<{
+    readonly protocol: Schema.String;
+    readonly storageSchemaRevision: Schema.String;
+    readonly artifactFormatRevision: Schema.String;
+    readonly semanticIdentity: Schema.refine<import("./compose.cjs").JsonValue, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Provider boundary: a completed cache plan never relies on core defaults. */
+export declare const decodeSandboxSetupPrefixCacheKeyScope: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly protocol: string;
+    readonly storageSchemaRevision: string;
+    readonly artifactFormatRevision: string;
+    readonly semanticIdentity: import("./compose.cjs").JsonValue;
+};
 export type SandboxSetupPrefixCacheEligibility = {
     readonly _tag: "Eligible";
     readonly persistence: "persistent";
@@ -17,13 +30,8 @@ export type SandboxSetupPrefixCacheEligibility = {
     readonly coverage: SandboxActionState;
     /** Exact immutable Base resolved and verified during provider initialization. */
     readonly baseImageId: string;
-    /** Provider-owned key scope; omission preserves the ordinary Docker rootfs identity exactly. */
-    readonly keyScope?: {
-        readonly protocol: string;
-        readonly storageSchemaRevision: string;
-        readonly artifactFormatRevision: string;
-        readonly semanticIdentity: import("../shared/types.cjs").JsonValue;
-    };
+    /** Complete provider-owned identity, decoded before entering core planning. */
+    readonly keyScope: Schema.Schema.Type<typeof SandboxSetupPrefixCacheKeyScopeSchema>;
 } | {
     readonly _tag: "Unsupported";
     readonly code: SandboxSetupPrefixCacheUnsupportedCode;

package/dist/sandbox/backend.d.mts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import type { SandboxActionState } from "./action.mjs";
 import type { CommandOptions, CommandResult, CustomProviderSandbox, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.mjs";
 export type SandboxBackendSupport<T> = {
@@ -9,6 +9,19 @@ export type SandboxBackendSupport<T> = {
     readonly reason: string;
 };
 export type SandboxSetupPrefixCacheUnsupportedCode = "provider-unsupported" | "profile-managed" | "compose" | "host-socket" | "read-only-rootfs" | "base-image-unverified" | "dynamic-runner-tools" | "mounted-state" | "sensitive-state" | "profile-backed-dind";
+declare const SandboxSetupPrefixCacheKeyScopeSchema: Schema.Struct<{
+    readonly protocol: Schema.String;
+    readonly storageSchemaRevision: Schema.String;
+    readonly artifactFormatRevision: Schema.String;
+    readonly semanticIdentity: Schema.refine<import("./compose.mjs").JsonValue, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Provider boundary: a completed cache plan never relies on core defaults. */
+export declare const decodeSandboxSetupPrefixCacheKeyScope: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly protocol: string;
+    readonly storageSchemaRevision: string;
+    readonly artifactFormatRevision: string;
+    readonly semanticIdentity: import("./compose.mjs").JsonValue;
+};
 export type SandboxSetupPrefixCacheEligibility = {
     readonly _tag: "Eligible";
     readonly persistence: "persistent";
@@ -17,13 +30,8 @@ export type SandboxSetupPrefixCacheEligibility = {
     readonly coverage: SandboxActionState;
     /** Exact immutable Base resolved and verified during provider initialization. */
     readonly baseImageId: string;
-    /** Provider-owned key scope; omission preserves the ordinary Docker rootfs identity exactly. */
-    readonly keyScope?: {
-        readonly protocol: string;
-        readonly storageSchemaRevision: string;
-        readonly artifactFormatRevision: string;
-        readonly semanticIdentity: import("../shared/types.mjs").JsonValue;
-    };
+    /** Complete provider-owned identity, decoded before entering core planning. */
+    readonly keyScope: Schema.Schema.Type<typeof SandboxSetupPrefixCacheKeyScopeSchema>;
 } | {
     readonly _tag: "Unsupported";
     readonly code: SandboxSetupPrefixCacheUnsupportedCode;

package/dist/sandbox/backend.d.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import type { SandboxActionState } from "./action.js";
 import type { CommandOptions, CommandResult, CustomProviderSandbox, Sandbox, ManagedProcess, ManagedProcessStart, SandboxReuseCapability, SandboxTransferOperations } from "./types.js";
 export type SandboxBackendSupport<T> = {
@@ -9,6 +9,19 @@ export type SandboxBackendSupport<T> = {
     readonly reason: string;
 };
 export type SandboxSetupPrefixCacheUnsupportedCode = "provider-unsupported" | "profile-managed" | "compose" | "host-socket" | "read-only-rootfs" | "base-image-unverified" | "dynamic-runner-tools" | "mounted-state" | "sensitive-state" | "profile-backed-dind";
+declare const SandboxSetupPrefixCacheKeyScopeSchema: Schema.Struct<{
+    readonly protocol: Schema.String;
+    readonly storageSchemaRevision: Schema.String;
+    readonly artifactFormatRevision: Schema.String;
+    readonly semanticIdentity: Schema.refine<import("./compose.js").JsonValue, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Provider boundary: a completed cache plan never relies on core defaults. */
+export declare const decodeSandboxSetupPrefixCacheKeyScope: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly protocol: string;
+    readonly storageSchemaRevision: string;
+    readonly artifactFormatRevision: string;
+    readonly semanticIdentity: import("./compose.js").JsonValue;
+};
 export type SandboxSetupPrefixCacheEligibility = {
     readonly _tag: "Eligible";
     readonly persistence: "persistent";
@@ -17,13 +30,8 @@ export type SandboxSetupPrefixCacheEligibility = {
     readonly coverage: SandboxActionState;
     /** Exact immutable Base resolved and verified during provider initialization. */
     readonly baseImageId: string;
-    /** Provider-owned key scope; omission preserves the ordinary Docker rootfs identity exactly. */
-    readonly keyScope?: {
-        readonly protocol: string;
-        readonly storageSchemaRevision: string;
-        readonly artifactFormatRevision: string;
-        readonly semanticIdentity: import("../shared/types.js").JsonValue;
-    };
+    /** Complete provider-owned identity, decoded before entering core planning. */
+    readonly keyScope: Schema.Schema.Type<typeof SandboxSetupPrefixCacheKeyScopeSchema>;
 } | {
     readonly _tag: "Unsupported";
     readonly code: SandboxSetupPrefixCacheUnsupportedCode;

package/dist/sandbox/backend.js

@@ -21,30 +21,32 @@ const __niceevalExport8 = __niceevalCanonical["SandboxSetupPrefixCacheValidation
 export { __niceevalExport8 as SandboxSetupPrefixCacheValidationError };
 const __niceevalExport9 = __niceevalCanonical["customSandboxBackend"];
 export { __niceevalExport9 as customSandboxBackend };
-const __niceevalExport10 = __niceevalCanonical["inheritSandboxCapabilities"];
-export { __niceevalExport10 as inheritSandboxCapabilities };
-const __niceevalExport11 = __niceevalCanonical["noSandboxBackendCapabilities"];
-export { __niceevalExport11 as noSandboxBackendCapabilities };
-const __niceevalExport12 = __niceevalCanonical["providerBoundaryEffect"];
-export { __niceevalExport12 as providerBoundaryEffect };
-const __niceevalExport13 = __niceevalCanonical["providerCompatibilityPromise"];
-export { __niceevalExport13 as providerCompatibilityPromise };
-const __niceevalExport14 = __niceevalCanonical["registerSandboxCapabilities"];
-export { __niceevalExport14 as registerSandboxCapabilities };
-const __niceevalExport15 = __niceevalCanonical["requireManagedProcessCapability"];
-export { __niceevalExport15 as requireManagedProcessCapability };
-const __niceevalExport16 = __niceevalCanonical["sandboxCapabilities"];
-export { __niceevalExport16 as sandboxCapabilities };
-const __niceevalExport17 = __niceevalCanonical["sandboxReuseCapability"];
-export { __niceevalExport17 as sandboxReuseCapability };
-const __niceevalExport18 = __niceevalCanonical["sandboxSupportsRootCommands"];
-export { __niceevalExport18 as sandboxSupportsRootCommands };
-const __niceevalExport19 = __niceevalCanonical["setupPrefixCacheCapability"];
-export { __niceevalExport19 as setupPrefixCacheCapability };
-const __niceevalExport20 = __niceevalCanonical["supportedBackendCapability"];
-export { __niceevalExport20 as supportedBackendCapability };
-const __niceevalExport21 = __niceevalCanonical["unsupportedBackendCapability"];
-export { __niceevalExport21 as unsupportedBackendCapability };
-const __niceevalExport22 = __niceevalCanonical["unsupportedBackendCapabilityBecause"];
-export { __niceevalExport22 as unsupportedBackendCapabilityBecause };
+const __niceevalExport10 = __niceevalCanonical["decodeSandboxSetupPrefixCacheKeyScope"];
+export { __niceevalExport10 as decodeSandboxSetupPrefixCacheKeyScope };
+const __niceevalExport11 = __niceevalCanonical["inheritSandboxCapabilities"];
+export { __niceevalExport11 as inheritSandboxCapabilities };
+const __niceevalExport12 = __niceevalCanonical["noSandboxBackendCapabilities"];
+export { __niceevalExport12 as noSandboxBackendCapabilities };
+const __niceevalExport13 = __niceevalCanonical["providerBoundaryEffect"];
+export { __niceevalExport13 as providerBoundaryEffect };
+const __niceevalExport14 = __niceevalCanonical["providerCompatibilityPromise"];
+export { __niceevalExport14 as providerCompatibilityPromise };
+const __niceevalExport15 = __niceevalCanonical["registerSandboxCapabilities"];
+export { __niceevalExport15 as registerSandboxCapabilities };
+const __niceevalExport16 = __niceevalCanonical["requireManagedProcessCapability"];
+export { __niceevalExport16 as requireManagedProcessCapability };
+const __niceevalExport17 = __niceevalCanonical["sandboxCapabilities"];
+export { __niceevalExport17 as sandboxCapabilities };
+const __niceevalExport18 = __niceevalCanonical["sandboxReuseCapability"];
+export { __niceevalExport18 as sandboxReuseCapability };
+const __niceevalExport19 = __niceevalCanonical["sandboxSupportsRootCommands"];
+export { __niceevalExport19 as sandboxSupportsRootCommands };
+const __niceevalExport20 = __niceevalCanonical["setupPrefixCacheCapability"];
+export { __niceevalExport20 as setupPrefixCacheCapability };
+const __niceevalExport21 = __niceevalCanonical["supportedBackendCapability"];
+export { __niceevalExport21 as supportedBackendCapability };
+const __niceevalExport22 = __niceevalCanonical["unsupportedBackendCapability"];
+export { __niceevalExport22 as unsupportedBackendCapability };
+const __niceevalExport23 = __niceevalCanonical["unsupportedBackendCapabilityBecause"];
+export { __niceevalExport23 as unsupportedBackendCapabilityBecause };
 //# sourceMappingURL=backend.js.map

package/dist/sandbox/docker.cjs

@@ -553,7 +553,7 @@ class DockerSandbox {
                 dependency: "parent-backed",
                 coverage: action_ts_1.sandboxState.dockerData,
                 baseImageId: this.baseImageId,
-                keyScope: Object.freeze({
+                keyScope: (0, backend_ts_1.decodeSandboxSetupPrefixCacheKeyScope)({
                     protocol: capability.protocol,
                     storageSchemaRevision: capability.publicationRevision,
                     artifactFormatRevision: capability.copyRevision,
@@ -652,6 +652,12 @@ class DockerSandbox {
             dependency: "parent-backed",
             coverage: action_ts_1.sandboxState.all,
             baseImageId: this.baseImageId,
+            keyScope: (0, backend_ts_1.decodeSandboxSetupPrefixCacheKeyScope)({
+                protocol: "niceeval-docker-rootfs-setup-prefix/v1",
+                storageSchemaRevision: "niceeval.setup-prefix-storage/v2",
+                artifactFormatRevision: "niceeval.setup-prefix-capture/v1",
+                semanticIdentity: { capture: "outer-writable-rootfs" },
+            }),
         };
     }
     async quiesceProfileSetupPrefix(signal) {