niceeval 0.13.3 → 0.13.4-canary.39

package/dist/sandbox/build-coordinator.cjs

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SANDBOX_BUILD_ACTIVITY = void 0;
+exports.materializationScopeId = materializationScopeId;
+exports.sandboxBuildRef = sandboxBuildRef;
 exports.prepareSandboxBuilds = prepareSandboxBuilds;
 exports.startSandboxBuilds = startSandboxBuilds;
 exports.buildFailureOrigin = buildFailureOrigin;
@@ -11,10 +13,21 @@ exports.buildFailureOrigin = buildFailureOrigin;
 // 落盘形状:docs/feature/record/architecture.md「sandboxBuilds」。
 // 内部是 Effect 协调:逐 key 结算用 Deferred、整批收工用 Fiber 观察、退避用 Clock.sleep、
 // 并发闸用 Semaphore;公开 RunningSandboxBuilds 保持 Promise ABI,只在方法边界 runPromise。
+const node_crypto_1 = require("node:crypto");
 const effect_1 = require("effect");
 const errors_ts_1 = require("./errors.cjs");
 /** Run 级开放 activity key;与 Record 契约同名。 */
 exports.SANDBOX_BUILD_ACTIVITY = "sandbox.build";
+function materializationScopeId(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([
+        input.providerFamily,
+        input.authorityFingerprint,
+        input.materializationProtocolVersion,
+    ])).digest("hex");
+}
+function sandboxBuildRef(scopeId, buildKey) {
+    return (0, node_crypto_1.createHash)("sha256").update(`${scopeId}\0${buildKey}`).digest("hex");
+}
 /**
  * 对仍需 fresh 的 BuildKey 做 Run 级共享准备,等全部 key 结算。
  * 调用方负责先做携带规划、只传入未携带 attempt 引用的 key;本函数不为「查看旧结果」造假 provenance。
@@ -29,16 +42,16 @@ async function prepareSandboxBuilds(works, opts) {
 function startSandboxBuilds(works, opts) {
     const unique = dedupeWorks(works);
     if (unique.length === 0) {
-        const empty = { locators: new Map(), records: [], failures: new Map() };
+        const empty = { sources: new Map(), records: [], failures: new Map() };
         return {
-            locators: empty.locators,
+            sources: empty.sources,
             failures: empty.failures,
             async settled() { },
             done: Promise.resolve(empty),
         };
     }
     const maxConcurrency = Math.max(1, opts.maxConcurrency ?? 2);
-    const locators = new Map();
+    const sources = new Map();
     const records = [];
     const failures = new Map();
     const prepareSignal = combineSignals([
@@ -51,14 +64,14 @@ function startSandboxBuilds(works, opts) {
     // Deferred 结算后状态保持,迟到等待方同样立即放行。
     const perKey = new Map();
     for (const work of unique) {
-        perKey.set(work.buildKey, effect_1.Deferred.unsafeMake(effect_1.FiberId.unsafeMake()));
+        perKey.set(work.ref, effect_1.Deferred.unsafeMake(effect_1.FiberId.unsafeMake()));
     }
     const ctx = {
         timing: opts.timing,
         provider: opts.provider,
         buildTimeoutMs: opts.buildTimeoutMs,
         signal: prepareSignal,
-        locators,
+        sources,
         records,
         failures,
         onActivity: opts.onActivity,
@@ -70,20 +83,20 @@ function startSandboxBuilds(works, opts) {
     // 的失败传播一致,且观察不打断兄弟 fiber,一条出事后其余 key 照常结算。
     const coordination = effect_1.Effect.gen(function* () {
         const gate = yield* effect_1.Effect.makeSemaphore(maxConcurrency);
-        const fibers = yield* effect_1.Effect.forEach(unique, (work) => effect_1.Effect.fork(gate.withPermits(1)(prepareOne(work, ctx)).pipe(effect_1.Effect.ensuring(effect_1.Effect.asVoid(effect_1.Deferred.succeed(perKey.get(work.buildKey), undefined))))));
+        const fibers = yield* effect_1.Effect.forEach(unique, (work) => effect_1.Effect.fork(gate.withPermits(1)(prepareOne(work, ctx)).pipe(effect_1.Effect.ensuring(effect_1.Effect.asVoid(effect_1.Deferred.succeed(perKey.get(work.ref), undefined))))));
         const exits = yield* effect_1.Effect.forEach(fibers, effect_1.Fiber.await, { concurrency: "unbounded" });
         const failed = exits.find(effect_1.Exit.isFailure);
         if (failed !== undefined && effect_1.Exit.isFailure(failed))
             return yield* effect_1.Effect.failCause(failed.cause);
-        return { locators, records, failures };
+        return { sources, records, failures };
     });
     // 边界:唯一一次把 Effect 驱动进公开 Promise ABI。
     const done = effect_1.Effect.runPromise(coordination);
     return {
-        locators,
+        sources,
         failures,
-        async settled(buildKey) {
-            const deferred = perKey.get(buildKey);
+        async settled(ref) {
+            const deferred = perKey.get(ref);
             if (deferred === undefined)
                 return;
             await effect_1.Effect.runPromise(effect_1.Deferred.await(deferred));
@@ -106,8 +119,8 @@ function buildFailureOrigin(failure) {
 function dedupeWorks(works) {
     const seen = new Map();
     for (const work of works) {
-        if (!seen.has(work.buildKey))
-            seen.set(work.buildKey, work);
+        if (!seen.has(work.ref))
+            seen.set(work.ref, work);
     }
     return [...seen.values()];
 }
@@ -123,6 +136,7 @@ function prepareOne(work, ctx) {
         });
         ctx.onActivity?.({
             status: "started",
+            ref: work.ref,
             buildKey: work.buildKey,
             id: parent.id,
             key: exports.SANDBOX_BUILD_ACTIVITY,
@@ -132,7 +146,7 @@ function prepareOne(work, ctx) {
             ctx.signal,
             ctx.buildTimeoutMs !== undefined ? AbortSignal.timeout(ctx.buildTimeoutMs) : undefined,
         ]);
-        const finish = (status, locator, error) => {
+        const finish = (status, source, error) => {
             parent.durationMs = Math.max(0, ctx.timing.offsetNow() - startOffsetMs);
             if (status === "failed" || status === "cancelled")
                 parent.failed = true;
@@ -142,15 +156,16 @@ function prepareOne(work, ctx) {
                 status,
                 timingNodeId: parent.id,
                 inputs: work.inputs,
-                ...(locator !== undefined ? { locator } : {}),
+                ...(source !== undefined ? { locator: source.locator } : {}),
                 ...(error !== undefined ? { error } : {}),
             };
             ctx.records.push(record);
-            if (locator !== undefined && (status === "hit" || status === "built")) {
-                ctx.locators.set(work.buildKey, locator);
+            if (source !== undefined && (status === "hit" || status === "built")) {
+                ctx.sources.set(work.ref, source);
             }
             if (error !== undefined && (status === "failed" || status === "cancelled")) {
-                ctx.failures.set(work.buildKey, {
+                ctx.failures.set(work.ref, {
+                    ref: work.ref,
                     buildKey: work.buildKey,
                     timingNodeId: parent.id,
                     status,
@@ -159,6 +174,8 @@ function prepareOne(work, ctx) {
             }
             ctx.onActivity?.({
                 status: status === "failed" || status === "cancelled" ? "failed" : "done",
+                ref: work.ref,
+                outcome: status,
                 buildKey: work.buildKey,
                 id: parent.id,
                 key: exports.SANDBOX_BUILD_ACTIVITY,
@@ -190,14 +207,16 @@ function prepareOne(work, ctx) {
         }));
         if (lookup._tag === "Left")
             return yield* finishFailure(lookup.left);
-        if (lookup.right !== undefined) {
-            finish("hit", lookup.right);
+        if (lookup.right._tag === "Hit") {
+            finish("hit", lookup.right.source);
             return;
         }
         // 瞬时构建失败(基线镜像拉取限流、传输层中断)退避重试:构建产物是镜像与 template,
         // 没有计费实例的泄漏面,歧义类同样可重试(case.md「Run 级构建协调」第 5 条)。
+        const operationId = (0, node_crypto_1.randomUUID)();
         const build = (attempt) => effect_1.Effect.tryPromise({
             try: () => ctx.provider.build(work, {
+                operationId,
                 signal: keySignal,
                 timing: ctx.timing,
                 parent,

package/dist/sandbox/build-coordinator.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"build-coordinator.js","sourceRoot":"","sources":["build-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["// Run 级构建协调器:携带规划后只为仍需 fresh 的 BuildKey 工作。\n// single-flight、独立并发、逐 key timeout、全局准备上限、abort/cancel;\n// 写 sandbox.build timings 与 sandboxBuilds provenance;失败按依赖集合扇出。\n// 契约单源:docs/feature/sandbox/case.md「Run 级构建协调」;\n// 落盘形状:docs/feature/record/architecture.md「sandboxBuilds」。\n// 内部是 Effect 协调:逐 key 结算用 Deferred、整批收工用 Fiber 观察、退避用 Clock.sleep、\n// 并发闸用 Semaphore;公开 RunningSandboxBuilds 保持 Promise ABI,只在方法边界 runPromise。\nimport { Deferred, Duration, Effect, Exit, Fiber, FiberId, Random } from \"effect\";\nimport type { JsonValue } from \"../shared/types.ts\";\nimport type { RunTimingRecorder } from \"../runner/timing.ts\";\nimport type { SandboxBuildRecord, TimingActivity } from \"../runner/types.ts\";\nimport { classifyProvisionErrorFallback, isRetryableProvisionError } from \"./errors.ts\";\nimport type { BuildKey } from \"./identity.ts\";\n/** Run 级开放 activity key;与 Record 契约同名。 */\nexport const SANDBOX_BUILD_ACTIVITY = \"sandbox.build\" as const;\n/** 一条待协调的构建工作(同 BuildKey 只保留第一次出现的 inputs / provider)。 */\nexport interface SandboxBuildWork {\n    readonly buildKey: BuildKey;\n    readonly provider: string;\n    /** 解析后的构建输入投影;不含凭据值。 */\n    readonly inputs: JsonValue;\n    /** 有界人读标签;省略时用 BuildKey 短前缀。 */\n    readonly label?: string;\n}\n/** provider 侧 cache 查询与真实构建。 */\nexport interface SandboxBuildProvider {\n    /** 查 provider 原生 cache / 本地 build registry;命中返回 locator。 */\n    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<JsonValue | undefined>;\n    /** cache miss 时调用原生构建 API。 */\n    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<JsonValue>;\n    /** 可选:Invocation abort / timeout 时取消远端 build。 */\n    cancel?(work: SandboxBuildWork): Promise<void>;\n}\n/** 构建执行上下文:子 activity 挂在当前 sandbox.build 节点下。 */\nexport interface SandboxBuildExecutionContext {\n    readonly signal: AbortSignal;\n    readonly timing: RunTimingRecorder;\n    readonly parent: TimingActivity;\n}\nexport interface PrepareSandboxBuildsOptions {\n    readonly timing: RunTimingRecorder;\n    readonly provider: SandboxBuildProvider;\n    /** 同时 in-flight 的不同 BuildKey 上限;默认 2。不占 attempt 并发位。 */\n    readonly maxConcurrency?: number;\n    /** 逐 BuildKey 的 timeout(ms);省略 = 无逐 key 上限。 */\n    readonly buildTimeoutMs?: number;\n    /** 整段准备的全局墙钟上限(ms);省略 = 无全局上限。 */\n    readonly prepareBudgetMs?: number;\n    /** Invocation abort(Ctrl+C)。 */\n    readonly signal?: AbortSignal;\n    /**\n     * 每个 BuildKey 真正开始 / 结束时回调一次(有界起止事件)。\n     * 供 live feedback 投影为运行级 active 行 / 非 TTY 永久事件;不改变协调语义。\n     */\n    readonly onActivity?: (event: SandboxBuildActivityEvent) => void;\n    /** 瞬时构建失败的退避重试上限(含首次尝试);默认 3。 */\n    readonly buildAttempts?: number;\n    /** 退避基数(ms),第 n 次重试睡 base × 2^n × 抖动;默认 1000。 */\n    readonly buildRetryBaseMs?: number;\n}\n/** 构建协调器对外的有界 activity 事件(与 Run feedback 的 run-activity 字段对齐)。 */\nexport type SandboxBuildActivityEvent = {\n    status: \"started\";\n    buildKey: BuildKey;\n    id: string;\n    key: typeof SANDBOX_BUILD_ACTIVITY;\n    label: string;\n} | {\n    status: \"done\" | \"failed\";\n    buildKey: BuildKey;\n    id: string;\n    key: typeof SANDBOX_BUILD_ACTIVITY;\n    label: string;\n    durationMs: number;\n};\nexport interface SandboxBuildFailure {\n    readonly buildKey: BuildKey;\n    readonly timingNodeId: string;\n    readonly status: \"failed\" | \"cancelled\";\n    readonly error: NonNullable<SandboxBuildRecord[\"error\"]>;\n}\nexport interface SandboxBuildPreparation {\n    /** 成功(hit / built)的 BuildKey → locator。 */\n    readonly locators: ReadonlyMap<BuildKey, JsonValue>;\n    /** 实际查询或构建过的每条 provenance(不含完全携带、从未过问的 key)。 */\n    readonly records: readonly SandboxBuildRecord[];\n    /** 失败或取消的 BuildKey → 共用同一 Run timing origin 的错误。 */\n    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;\n}\n/** 进行中的 Run 级共享准备:逐 BuildKey 放行,依赖者只等自己引用的那几个 key。 */\nexport interface RunningSandboxBuilds {\n    /** 已结算 key 的实时视图(随构建推进增补,不等整批收工)。 */\n    readonly locators: ReadonlyMap<BuildKey, JsonValue>;\n    /** 已失败 / 已取消 key 的实时视图。 */\n    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;\n    /** 等某个 BuildKey 结算;不在本次协调范围内的 key 立即返回。 */\n    settled(buildKey: BuildKey): Promise<void>;\n    /** 全部 key 结算后的汇总(provenance 在这里齐全)。 */\n    readonly done: Promise<SandboxBuildPreparation>;\n}\n/**\n * 对仍需 fresh 的 BuildKey 做 Run 级共享准备,等全部 key 结算。\n * 调用方负责先做携带规划、只传入未携带 attempt 引用的 key;本函数不为「查看旧结果」造假 provenance。\n */\nexport async function prepareSandboxBuilds(works: readonly SandboxBuildWork[], opts: PrepareSandboxBuildsOptions): Promise<SandboxBuildPreparation> {\n    return startSandboxBuilds(works, opts).done;\n}\n/**\n * 启动 Run 级共享准备并立刻返回句柄:调用方按 BuildKey 逐个等待,\n * 只依赖已就绪 key 的 attempt 不被同批最慢的那个构建挡住(见 case.md「Run 级构建协调」第 4 条)。\n */\nexport function startSandboxBuilds(works: readonly SandboxBuildWork[], opts: PrepareSandboxBuildsOptions): RunningSandboxBuilds {\n    const unique = dedupeWorks(works);\n    if (unique.length === 0) {\n        const empty: SandboxBuildPreparation = { locators: new Map(), records: [], failures: new Map() };\n        return {\n            locators: empty.locators,\n            failures: empty.failures,\n            async settled() { },\n            done: Promise.resolve(empty),\n        };\n    }\n    const maxConcurrency = Math.max(1, opts.maxConcurrency ?? 2);\n    const locators = new Map<BuildKey, JsonValue>();\n    const records: SandboxBuildRecord[] = [];\n    const failures = new Map<BuildKey, SandboxBuildFailure>();\n    const prepareSignal = combineSignals([\n        opts.signal,\n        opts.prepareBudgetMs !== undefined ? AbortSignal.timeout(opts.prepareBudgetMs) : undefined,\n    ]);\n    // 逐 key 的结算 Deferred:key 一结算就 settle,依赖它的 attempt 当场放行,\n    // 不等同批其它 key(single-flight 仍靠这张表,同 key 的第二个 work 复用同一条)。\n    // 在方法边界同步创建,settled() 在任意时刻调用都拿到同一结果;\n    // Deferred 结算后状态保持,迟到等待方同样立即放行。\n    const perKey = new Map<BuildKey, Deferred.Deferred<void, never>>();\n    for (const work of unique) {\n        perKey.set(work.buildKey, Deferred.unsafeMake(FiberId.unsafeMake()));\n    }\n    const ctx = {\n        timing: opts.timing,\n        provider: opts.provider,\n        buildTimeoutMs: opts.buildTimeoutMs,\n        signal: prepareSignal,\n        locators,\n        records,\n        failures,\n        onActivity: opts.onActivity,\n        buildAttempts: Math.max(1, opts.buildAttempts ?? DEFAULT_BUILD_ATTEMPTS),\n        buildRetryBaseMs: Math.max(0, opts.buildRetryBaseMs ?? DEFAULT_BUILD_RETRY_BASE_MS),\n    };\n    // 整段准备是一个 Effect 程序:每 key 一条 gate 保护的 fiber,结算挂在 ensuring 上\n    // (失败/中断同样放行等待方);收尾逐 fiber 观察 exit,先到先报缺陷——与 Promise.all\n    // 的失败传播一致,且观察不打断兄弟 fiber,一条出事后其余 key 照常结算。\n    const coordination = Effect.gen(function* () {\n        const gate = yield* Effect.makeSemaphore(maxConcurrency);\n        const fibers = yield* Effect.forEach(unique, (work) => Effect.fork(gate.withPermits(1)(prepareOne(work, ctx)).pipe(Effect.ensuring(Effect.asVoid(Deferred.succeed(perKey.get(work.buildKey)!, undefined))))));\n        const exits = yield* Effect.forEach(fibers, Fiber.await, { concurrency: \"unbounded\" });\n        const failed = exits.find(Exit.isFailure);\n        if (failed !== undefined && Exit.isFailure(failed))\n            return yield* Effect.failCause(failed.cause);\n        return { locators, records, failures } satisfies SandboxBuildPreparation;\n    });\n    // 边界:唯一一次把 Effect 驱动进公开 Promise ABI。\n    const done = Effect.runPromise(coordination);\n    return {\n        locators,\n        failures,\n        async settled(buildKey) {\n            const deferred = perKey.get(buildKey);\n            if (deferred === undefined)\n                return;\n            await Effect.runPromise(Deferred.await(deferred));\n        },\n        done,\n    };\n}\n/**\n * 从 fresh attempt 依赖表扇出构建失败 → AttemptError 形状所需字段。\n * 同一 BuildKey 的所有依赖者共用同一个 timingNodeId。\n */\nexport function buildFailureOrigin(failure: SandboxBuildFailure): {\n    code: string;\n    message: string;\n    timingNodeId: string;\n    cause?: SandboxBuildFailure[\"error\"][\"cause\"];\n} {\n    return {\n        code: failure.error.code,\n        message: failure.error.message,\n        timingNodeId: failure.timingNodeId,\n        ...(failure.error.cause !== undefined ? { cause: failure.error.cause } : {}),\n    };\n}\nfunction dedupeWorks(works: readonly SandboxBuildWork[]): SandboxBuildWork[] {\n    const seen = new Map<BuildKey, SandboxBuildWork>();\n    for (const work of works) {\n        if (!seen.has(work.buildKey))\n            seen.set(work.buildKey, work);\n    }\n    return [...seen.values()];\n}\nfunction prepareOne(work: SandboxBuildWork, ctx: {\n    timing: RunTimingRecorder;\n    provider: SandboxBuildProvider;\n    buildTimeoutMs: number | undefined;\n    signal: AbortSignal;\n    locators: Map<BuildKey, JsonValue>;\n    records: SandboxBuildRecord[];\n    failures: Map<BuildKey, SandboxBuildFailure>;\n    onActivity?: (event: SandboxBuildActivityEvent) => void;\n    buildAttempts: number;\n    buildRetryBaseMs: number;\n}): Effect.Effect<void> {\n    return Effect.gen(function* () {\n        const label = work.label ?? `build ${work.buildKey.slice(0, 12)}`;\n        const startOffsetMs = ctx.timing.offsetNow();\n        const parent = ctx.timing.child({\n            key: SANDBOX_BUILD_ACTIVITY,\n            label,\n            startOffsetMs,\n            durationMs: 0,\n        });\n        ctx.onActivity?.({\n            status: \"started\",\n            buildKey: work.buildKey,\n            id: parent.id,\n            key: SANDBOX_BUILD_ACTIVITY,\n            label,\n        });\n        const keySignal = combineSignals([\n            ctx.signal,\n            ctx.buildTimeoutMs !== undefined ? AbortSignal.timeout(ctx.buildTimeoutMs) : undefined,\n        ]);\n        const finish = (status: SandboxBuildRecord[\"status\"], locator?: JsonValue, error?: SandboxBuildRecord[\"error\"]) => {\n            parent.durationMs = Math.max(0, ctx.timing.offsetNow() - startOffsetMs);\n            if (status === \"failed\" || status === \"cancelled\")\n                parent.failed = true;\n            const record: SandboxBuildRecord = {\n                buildKey: work.buildKey,\n                provider: work.provider,\n                status,\n                timingNodeId: parent.id,\n                inputs: work.inputs,\n                ...(locator !== undefined ? { locator } : {}),\n                ...(error !== undefined ? { error } : {}),\n            };\n            ctx.records.push(record);\n            if (locator !== undefined && (status === \"hit\" || status === \"built\")) {\n                ctx.locators.set(work.buildKey, locator);\n            }\n            if (error !== undefined && (status === \"failed\" || status === \"cancelled\")) {\n                ctx.failures.set(work.buildKey, {\n                    buildKey: work.buildKey,\n                    timingNodeId: parent.id,\n                    status,\n                    error,\n                });\n            }\n            ctx.onActivity?.({\n                status: status === \"failed\" || status === \"cancelled\" ? \"failed\" : \"done\",\n                buildKey: work.buildKey,\n                id: parent.id,\n                key: SANDBOX_BUILD_ACTIVITY,\n                label,\n                durationMs: parent.durationMs,\n            });\n        };\n        if (keySignal.aborted) {\n            finish(\"cancelled\", undefined, abortError(keySignal, work.buildKey));\n            return;\n        }\n        const finishFailure = (e: unknown): Effect.Effect<void> => Effect.gen(function* () {\n            if (keySignal.aborted || isAbortError(e)) {\n                const cancel = ctx.provider.cancel;\n                if (cancel !== undefined) {\n                    yield* Effect.tryPromise({\n                        try: () => cancel(work),\n                        catch: () => undefined,\n                    }).pipe(Effect.ignore);\n                }\n                finish(\"cancelled\", undefined, abortError(keySignal, work.buildKey, e));\n                return;\n            }\n            finish(\"failed\", undefined, failedError(work.buildKey, e));\n        });\n        const lookup = yield* Effect.either(Effect.tryPromise({\n            try: () => ctx.provider.lookup(work, keySignal),\n            catch: (error) => error,\n        }));\n        if (lookup._tag === \"Left\")\n            return yield* finishFailure(lookup.left);\n        if (lookup.right !== undefined) {\n            finish(\"hit\", lookup.right);\n            return;\n        }\n        // 瞬时构建失败(基线镜像拉取限流、传输层中断)退避重试:构建产物是镜像与 template,\n        // 没有计费实例的泄漏面,歧义类同样可重试(case.md「Run 级构建协调」第 5 条)。\n        const build = (attempt: number): Effect.Effect<JsonValue, unknown> => Effect.tryPromise({\n            try: () => ctx.provider.build(work, {\n                signal: keySignal,\n                timing: ctx.timing,\n                parent,\n            }),\n            catch: (error) => error,\n        }).pipe(Effect.catchAll((error) => {\n            const last = attempt >= ctx.buildAttempts - 1;\n            if (last || keySignal.aborted || isAbortError(error) || !isTransientBuildError(error)) {\n                return Effect.fail(error);\n            }\n            return Random.next.pipe(Effect.map((jitter) => backoffDelay(ctx.buildRetryBaseMs, attempt, jitter)), Effect.flatMap((delayMs) => sleep(delayMs, keySignal)), Effect.flatMap(() => keySignal.aborted ? Effect.fail(error) : build(attempt + 1)));\n        }));\n        const built = yield* Effect.either(build(0));\n        if (built._tag === \"Left\")\n            return yield* finishFailure(built.left);\n        finish(\"built\", built.right);\n    });\n}\n/** 首次尝试 + 2 次重试:与 provisioning 同一种「封顶次数」纪律,构建单次耗时更长所以更浅。 */\nconst DEFAULT_BUILD_ATTEMPTS = 3;\nconst DEFAULT_BUILD_RETRY_BASE_MS = 1000;\n/** 指数退避 + 全抖动(0.5x~1.5x),避免同一批被限流的构建同时醒来再次撞限流。 */\nfunction backoffDelay(baseMs: number, attempt: number, jitter: number): number {\n    return baseMs * 2 ** attempt * (0.5 + jitter);\n}\n/** 退避睡眠:Clock 驱动的 Effect.sleep(TestClock 可验证时序),abort 时提前放行。 */\nfunction sleep(ms: number, signal: AbortSignal): Effect.Effect<void, never> {\n    if (ms <= 0)\n        return Effect.void;\n    const timer = Effect.sleep(Duration.millis(ms));\n    const abort = Effect.async<void>((resume) => {\n        if (signal.aborted) {\n            resume(Effect.void);\n            return;\n        }\n        const onAbort = () => resume(Effect.void);\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n        return Effect.sync(() => signal.removeEventListener(\"abort\", onAbort));\n    });\n    return Effect.raceFirst(timer, abort);\n}\n/**\n * 构建失败的性质分类:瞬时才重试。\n * 先过与 provisioning 共用的保守瞬时分类器,再补 builder CLI 自己的文案形态——\n * registry 限流、拉取中途 EOF、TLS / IO 超时都出现在 `docker compose build` 的 stderr 里,\n * 它们不带 status code,只有文案。\n */\nfunction isTransientBuildError(e: unknown): boolean {\n    if (isRetryableProvisionError(classifyProvisionErrorFallback(e)))\n        return true;\n    const message = e instanceof Error ? e.message : String(e);\n    return /toomanyrequests|unexpected EOF|i\\/o timeout|TLS handshake timeout|failed to do request|connection reset by peer|temporary failure in name resolution|failed to copy: httpReadSeeker|EOF$/im.test(message);\n}\nfunction abortError(signal: AbortSignal, buildKey: BuildKey, cause?: unknown): NonNullable<SandboxBuildRecord[\"error\"]> {\n    const timedOut = isTimeoutReason(signal.reason);\n    const code = timedOut ? \"sandbox-build-timeout\" : \"sandbox-build-cancelled\";\n    const message = timedOut\n        ? `sandbox build timed out for BuildKey ${buildKey.slice(0, 12)}…`\n        : `sandbox build cancelled for BuildKey ${buildKey.slice(0, 12)}…`;\n    return {\n        code,\n        message,\n        ...(cause !== undefined ? { cause: causeSummary(cause) } : {}),\n    };\n}\nfunction isTimeoutReason(reason: unknown): boolean {\n    if (reason === undefined || reason === null)\n        return false;\n    if (typeof DOMException !== \"undefined\" && reason instanceof DOMException && reason.name === \"TimeoutError\") {\n        return true;\n    }\n    return reason instanceof Error && reason.name === \"TimeoutError\";\n}\nfunction failedError(buildKey: BuildKey, e: unknown): NonNullable<SandboxBuildRecord[\"error\"]> {\n    return {\n        code: \"sandbox-build-failed\",\n        message: e instanceof Error ? e.message : `sandbox build failed for BuildKey ${buildKey.slice(0, 12)}…`,\n        cause: causeSummary(e),\n    };\n}\nfunction causeSummary(e: unknown): {\n    name?: string;\n    code?: string;\n    message: string;\n} {\n    if (e instanceof Error) {\n        const withCode = e as Error & {\n            code?: unknown;\n        };\n        const code = typeof withCode.code === \"string\" ? withCode.code : undefined;\n        return {\n            name: e.name,\n            ...(code !== undefined ? { code } : {}),\n            message: e.message,\n        };\n    }\n    return { message: String(e) };\n}\nfunction isAbortError(e: unknown): boolean {\n    if (e instanceof Error && e.name === \"AbortError\")\n        return true;\n    if (typeof DOMException !== \"undefined\" && e instanceof DOMException && e.name === \"AbortError\")\n        return true;\n    return false;\n}\nfunction combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal {\n    const active = signals.filter((s): s is AbortSignal => s !== undefined);\n    if (active.length === 0)\n        return new AbortController().signal;\n    if (active.length === 1)\n        return active[0]!;\n    return AbortSignal.any(active);\n}\n"]}
+{"version":3,"file":"build-coordinator.js","sourceRoot":"","sources":["build-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["// Run 级构建协调器:携带规划后只为仍需 fresh 的 BuildKey 工作。\n// single-flight、独立并发、逐 key timeout、全局准备上限、abort/cancel;\n// 写 sandbox.build timings 与 sandboxBuilds provenance;失败按依赖集合扇出。\n// 契约单源:docs/feature/sandbox/case.md「Run 级构建协调」;\n// 落盘形状:docs/feature/record/architecture.md「sandboxBuilds」。\n// 内部是 Effect 协调:逐 key 结算用 Deferred、整批收工用 Fiber 观察、退避用 Clock.sleep、\n// 并发闸用 Semaphore;公开 RunningSandboxBuilds 保持 Promise ABI,只在方法边界 runPromise。\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { Deferred, Duration, Effect, Exit, Fiber, FiberId, Random } from \"effect\";\nimport type { JsonValue } from \"../shared/types.ts\";\nimport type { RunTimingRecorder } from \"../runner/timing.ts\";\nimport type { SandboxBuildRecord, TimingActivity } from \"../runner/types.ts\";\nimport { classifyProvisionErrorFallback, isRetryableProvisionError } from \"./errors.ts\";\nimport type { BuildKey } from \"./identity.ts\";\n/** Run 级开放 activity key;与 Record 契约同名。 */\nexport const SANDBOX_BUILD_ACTIVITY = \"sandbox.build\" as const;\ndeclare const MaterializationScopeIdBrand: unique symbol;\nexport type MaterializationScopeId = string & {\n    readonly [MaterializationScopeIdBrand]: true;\n};\ndeclare const SandboxBuildRefBrand: unique symbol;\nexport type SandboxBuildRef = string & {\n    readonly [SandboxBuildRefBrand]: true;\n};\nexport function materializationScopeId(input: {\n    readonly providerFamily: string;\n    readonly authorityFingerprint: string;\n    readonly materializationProtocolVersion: number;\n}): MaterializationScopeId {\n    return createHash(\"sha256\").update(JSON.stringify([\n        input.providerFamily,\n        input.authorityFingerprint,\n        input.materializationProtocolVersion,\n    ])).digest(\"hex\") as MaterializationScopeId;\n}\nexport function sandboxBuildRef(scopeId: MaterializationScopeId, buildKey: BuildKey): SandboxBuildRef {\n    return createHash(\"sha256\").update(`${scopeId}\\0${buildKey}`).digest(\"hex\") as SandboxBuildRef;\n}\n/** 一条待协调的构建工作(同 BuildKey 只保留第一次出现的 inputs / provider)。 */\nexport interface SandboxBuildWork {\n    readonly ref: SandboxBuildRef;\n    readonly scopeId: MaterializationScopeId;\n    readonly buildKey: BuildKey;\n    readonly provider: string;\n    /** 解析后的构建输入投影;不含凭据值。 */\n    readonly inputs: JsonValue;\n    /** 有界人读标签;省略时用 BuildKey 短前缀。 */\n    readonly label?: string;\n}\nexport interface SandboxBuildUseHandle {\n    readonly locator: JsonValue;\n    release(): Promise<void> | void;\n}\nexport interface SandboxBuildArtifactSource {\n    readonly locator: JsonValue;\n    readonly source: \"cache\" | \"build\";\n    acquireUse(signal: AbortSignal): Promise<SandboxBuildUseHandle>;\n    release(): Promise<void> | void;\n}\nexport type SandboxBuildLookup = {\n    readonly _tag: \"Hit\";\n    readonly source: SandboxBuildArtifactSource;\n} | {\n    readonly _tag: \"Miss\";\n} | {\n    readonly _tag: \"Unsupported\";\n};\n/** provider 侧 cache 查询与真实构建。 */\nexport interface SandboxBuildProvider {\n    /** 查 provider 原生 cache / 本地 build registry;命中返回 locator。 */\n    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<SandboxBuildLookup>;\n    /** cache miss 时调用原生构建 API。 */\n    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<SandboxBuildArtifactSource>;\n    /** 可选:Invocation abort / timeout 时取消远端 build。 */\n    cancel?(work: SandboxBuildWork): Promise<void>;\n}\n/** 构建执行上下文:子 activity 挂在当前 sandbox.build 节点下。 */\nexport interface SandboxBuildExecutionContext {\n    readonly operationId: string;\n    readonly signal: AbortSignal;\n    readonly timing: RunTimingRecorder;\n    readonly parent: TimingActivity;\n}\nexport interface PrepareSandboxBuildsOptions {\n    readonly timing: RunTimingRecorder;\n    readonly provider: SandboxBuildProvider;\n    /** 同时 in-flight 的不同 BuildKey 上限;默认 2。不占 attempt 并发位。 */\n    readonly maxConcurrency?: number;\n    /** 逐 BuildKey 的 timeout(ms);省略 = 无逐 key 上限。 */\n    readonly buildTimeoutMs?: number;\n    /** 整段准备的全局墙钟上限(ms);省略 = 无全局上限。 */\n    readonly prepareBudgetMs?: number;\n    /** Invocation abort(Ctrl+C)。 */\n    readonly signal?: AbortSignal;\n    /**\n     * 每个 BuildKey 真正开始 / 结束时回调一次(有界起止事件)。\n     * 供 live feedback 投影为运行级 active 行 / 非 TTY 永久事件;不改变协调语义。\n     */\n    readonly onActivity?: (event: SandboxBuildActivityEvent) => void;\n    /** 瞬时构建失败的退避重试上限(含首次尝试);默认 3。 */\n    readonly buildAttempts?: number;\n    /** 退避基数(ms),第 n 次重试睡 base × 2^n × 抖动;默认 1000。 */\n    readonly buildRetryBaseMs?: number;\n}\n/** 构建协调器对外的有界 activity 事件(与 Run feedback 的 run-activity 字段对齐)。 */\nexport type SandboxBuildActivityEvent = {\n    status: \"started\";\n    ref: SandboxBuildRef;\n    buildKey: BuildKey;\n    id: string;\n    key: typeof SANDBOX_BUILD_ACTIVITY;\n    label: string;\n} | {\n    status: \"done\" | \"failed\";\n    outcome: SandboxBuildRecord[\"status\"];\n    ref: SandboxBuildRef;\n    buildKey: BuildKey;\n    id: string;\n    key: typeof SANDBOX_BUILD_ACTIVITY;\n    label: string;\n    durationMs: number;\n};\nexport interface SandboxBuildFailure {\n    readonly ref: SandboxBuildRef;\n    readonly buildKey: BuildKey;\n    readonly timingNodeId: string;\n    readonly status: \"failed\" | \"cancelled\";\n    readonly error: NonNullable<SandboxBuildRecord[\"error\"]>;\n}\nexport interface SandboxBuildPreparation {\n    /** 成功(hit / built)的 BuildKey → locator。 */\n    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;\n    /** 实际查询或构建过的每条 provenance(不含完全携带、从未过问的 key)。 */\n    readonly records: readonly SandboxBuildRecord[];\n    /** 失败或取消的 BuildKey → 共用同一 Run timing origin 的错误。 */\n    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;\n}\n/** 进行中的 Run 级共享准备:逐 BuildKey 放行,依赖者只等自己引用的那几个 key。 */\nexport interface RunningSandboxBuilds {\n    /** 已结算 key 的实时视图(随构建推进增补,不等整批收工)。 */\n    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;\n    /** 已失败 / 已取消 key 的实时视图。 */\n    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;\n    /** 等某个 BuildKey 结算;不在本次协调范围内的 key 立即返回。 */\n    settled(ref: SandboxBuildRef): Promise<void>;\n    /** 全部 key 结算后的汇总(provenance 在这里齐全)。 */\n    readonly done: Promise<SandboxBuildPreparation>;\n}\n/**\n * 对仍需 fresh 的 BuildKey 做 Run 级共享准备,等全部 key 结算。\n * 调用方负责先做携带规划、只传入未携带 attempt 引用的 key;本函数不为「查看旧结果」造假 provenance。\n */\nexport async function prepareSandboxBuilds(works: readonly SandboxBuildWork[], opts: PrepareSandboxBuildsOptions): Promise<SandboxBuildPreparation> {\n    return startSandboxBuilds(works, opts).done;\n}\n/**\n * 启动 Run 级共享准备并立刻返回句柄:调用方按 BuildKey 逐个等待,\n * 只依赖已就绪 key 的 attempt 不被同批最慢的那个构建挡住(见 case.md「Run 级构建协调」第 4 条)。\n */\nexport function startSandboxBuilds(works: readonly SandboxBuildWork[], opts: PrepareSandboxBuildsOptions): RunningSandboxBuilds {\n    const unique = dedupeWorks(works);\n    if (unique.length === 0) {\n        const empty: SandboxBuildPreparation = { sources: new Map(), records: [], failures: new Map() };\n        return {\n            sources: empty.sources,\n            failures: empty.failures,\n            async settled() { },\n            done: Promise.resolve(empty),\n        };\n    }\n    const maxConcurrency = Math.max(1, opts.maxConcurrency ?? 2);\n    const sources = new Map<SandboxBuildRef, SandboxBuildArtifactSource>();\n    const records: SandboxBuildRecord[] = [];\n    const failures = new Map<SandboxBuildRef, SandboxBuildFailure>();\n    const prepareSignal = combineSignals([\n        opts.signal,\n        opts.prepareBudgetMs !== undefined ? AbortSignal.timeout(opts.prepareBudgetMs) : undefined,\n    ]);\n    // 逐 key 的结算 Deferred:key 一结算就 settle,依赖它的 attempt 当场放行,\n    // 不等同批其它 key(single-flight 仍靠这张表,同 key 的第二个 work 复用同一条)。\n    // 在方法边界同步创建,settled() 在任意时刻调用都拿到同一结果;\n    // Deferred 结算后状态保持,迟到等待方同样立即放行。\n    const perKey = new Map<SandboxBuildRef, Deferred.Deferred<void, never>>();\n    for (const work of unique) {\n        perKey.set(work.ref, Deferred.unsafeMake(FiberId.unsafeMake()));\n    }\n    const ctx = {\n        timing: opts.timing,\n        provider: opts.provider,\n        buildTimeoutMs: opts.buildTimeoutMs,\n        signal: prepareSignal,\n        sources,\n        records,\n        failures,\n        onActivity: opts.onActivity,\n        buildAttempts: Math.max(1, opts.buildAttempts ?? DEFAULT_BUILD_ATTEMPTS),\n        buildRetryBaseMs: Math.max(0, opts.buildRetryBaseMs ?? DEFAULT_BUILD_RETRY_BASE_MS),\n    };\n    // 整段准备是一个 Effect 程序:每 key 一条 gate 保护的 fiber,结算挂在 ensuring 上\n    // (失败/中断同样放行等待方);收尾逐 fiber 观察 exit,先到先报缺陷——与 Promise.all\n    // 的失败传播一致,且观察不打断兄弟 fiber,一条出事后其余 key 照常结算。\n    const coordination = Effect.gen(function* () {\n        const gate = yield* Effect.makeSemaphore(maxConcurrency);\n        const fibers = yield* Effect.forEach(unique, (work) => Effect.fork(gate.withPermits(1)(prepareOne(work, ctx)).pipe(Effect.ensuring(Effect.asVoid(Deferred.succeed(perKey.get(work.ref)!, undefined))))));\n        const exits = yield* Effect.forEach(fibers, Fiber.await, { concurrency: \"unbounded\" });\n        const failed = exits.find(Exit.isFailure);\n        if (failed !== undefined && Exit.isFailure(failed))\n            return yield* Effect.failCause(failed.cause);\n        return { sources, records, failures } satisfies SandboxBuildPreparation;\n    });\n    // 边界:唯一一次把 Effect 驱动进公开 Promise ABI。\n    const done = Effect.runPromise(coordination);\n    return {\n        sources,\n        failures,\n        async settled(ref) {\n            const deferred = perKey.get(ref);\n            if (deferred === undefined)\n                return;\n            await Effect.runPromise(Deferred.await(deferred));\n        },\n        done,\n    };\n}\n/**\n * 从 fresh attempt 依赖表扇出构建失败 → AttemptError 形状所需字段。\n * 同一 BuildKey 的所有依赖者共用同一个 timingNodeId。\n */\nexport function buildFailureOrigin(failure: SandboxBuildFailure): {\n    code: string;\n    message: string;\n    timingNodeId: string;\n    cause?: SandboxBuildFailure[\"error\"][\"cause\"];\n} {\n    return {\n        code: failure.error.code,\n        message: failure.error.message,\n        timingNodeId: failure.timingNodeId,\n        ...(failure.error.cause !== undefined ? { cause: failure.error.cause } : {}),\n    };\n}\nfunction dedupeWorks(works: readonly SandboxBuildWork[]): SandboxBuildWork[] {\n    const seen = new Map<SandboxBuildRef, SandboxBuildWork>();\n    for (const work of works) {\n        if (!seen.has(work.ref))\n            seen.set(work.ref, work);\n    }\n    return [...seen.values()];\n}\nfunction prepareOne(work: SandboxBuildWork, ctx: {\n    timing: RunTimingRecorder;\n    provider: SandboxBuildProvider;\n    buildTimeoutMs: number | undefined;\n    signal: AbortSignal;\n    sources: Map<SandboxBuildRef, SandboxBuildArtifactSource>;\n    records: SandboxBuildRecord[];\n    failures: Map<SandboxBuildRef, SandboxBuildFailure>;\n    onActivity?: (event: SandboxBuildActivityEvent) => void;\n    buildAttempts: number;\n    buildRetryBaseMs: number;\n}): Effect.Effect<void> {\n    return Effect.gen(function* () {\n        const label = work.label ?? `build ${work.buildKey.slice(0, 12)}`;\n        const startOffsetMs = ctx.timing.offsetNow();\n        const parent = ctx.timing.child({\n            key: SANDBOX_BUILD_ACTIVITY,\n            label,\n            startOffsetMs,\n            durationMs: 0,\n        });\n        ctx.onActivity?.({\n            status: \"started\",\n            ref: work.ref,\n            buildKey: work.buildKey,\n            id: parent.id,\n            key: SANDBOX_BUILD_ACTIVITY,\n            label,\n        });\n        const keySignal = combineSignals([\n            ctx.signal,\n            ctx.buildTimeoutMs !== undefined ? AbortSignal.timeout(ctx.buildTimeoutMs) : undefined,\n        ]);\n        const finish = (status: SandboxBuildRecord[\"status\"], source?: SandboxBuildArtifactSource, error?: SandboxBuildRecord[\"error\"]) => {\n            parent.durationMs = Math.max(0, ctx.timing.offsetNow() - startOffsetMs);\n            if (status === \"failed\" || status === \"cancelled\")\n                parent.failed = true;\n            const record: SandboxBuildRecord = {\n                buildKey: work.buildKey,\n                provider: work.provider,\n                status,\n                timingNodeId: parent.id,\n                inputs: work.inputs,\n                ...(source !== undefined ? { locator: source.locator } : {}),\n                ...(error !== undefined ? { error } : {}),\n            };\n            ctx.records.push(record);\n            if (source !== undefined && (status === \"hit\" || status === \"built\")) {\n                ctx.sources.set(work.ref, source);\n            }\n            if (error !== undefined && (status === \"failed\" || status === \"cancelled\")) {\n                ctx.failures.set(work.ref, {\n                    ref: work.ref,\n                    buildKey: work.buildKey,\n                    timingNodeId: parent.id,\n                    status,\n                    error,\n                });\n            }\n            ctx.onActivity?.({\n                status: status === \"failed\" || status === \"cancelled\" ? \"failed\" : \"done\",\n                ref: work.ref,\n                outcome: status,\n                buildKey: work.buildKey,\n                id: parent.id,\n                key: SANDBOX_BUILD_ACTIVITY,\n                label,\n                durationMs: parent.durationMs,\n            });\n        };\n        if (keySignal.aborted) {\n            finish(\"cancelled\", undefined, abortError(keySignal, work.buildKey));\n            return;\n        }\n        const finishFailure = (e: unknown): Effect.Effect<void> => Effect.gen(function* () {\n            if (keySignal.aborted || isAbortError(e)) {\n                const cancel = ctx.provider.cancel;\n                if (cancel !== undefined) {\n                    yield* Effect.tryPromise({\n                        try: () => cancel(work),\n                        catch: () => undefined,\n                    }).pipe(Effect.ignore);\n                }\n                finish(\"cancelled\", undefined, abortError(keySignal, work.buildKey, e));\n                return;\n            }\n            finish(\"failed\", undefined, failedError(work.buildKey, e));\n        });\n        const lookup = yield* Effect.either(Effect.tryPromise({\n            try: () => ctx.provider.lookup(work, keySignal),\n            catch: (error) => error,\n        }));\n        if (lookup._tag === \"Left\")\n            return yield* finishFailure(lookup.left);\n        if (lookup.right._tag === \"Hit\") {\n            finish(\"hit\", lookup.right.source);\n            return;\n        }\n        // 瞬时构建失败(基线镜像拉取限流、传输层中断)退避重试:构建产物是镜像与 template,\n        // 没有计费实例的泄漏面,歧义类同样可重试(case.md「Run 级构建协调」第 5 条)。\n        const operationId = randomUUID();\n        const build = (attempt: number): Effect.Effect<SandboxBuildArtifactSource, unknown> => Effect.tryPromise({\n            try: () => ctx.provider.build(work, {\n                operationId,\n                signal: keySignal,\n                timing: ctx.timing,\n                parent,\n            }),\n            catch: (error) => error,\n        }).pipe(Effect.catchAll((error) => {\n            const last = attempt >= ctx.buildAttempts - 1;\n            if (last || keySignal.aborted || isAbortError(error) || !isTransientBuildError(error)) {\n                return Effect.fail(error);\n            }\n            return Random.next.pipe(Effect.map((jitter) => backoffDelay(ctx.buildRetryBaseMs, attempt, jitter)), Effect.flatMap((delayMs) => sleep(delayMs, keySignal)), Effect.flatMap(() => keySignal.aborted ? Effect.fail(error) : build(attempt + 1)));\n        }));\n        const built = yield* Effect.either(build(0));\n        if (built._tag === \"Left\")\n            return yield* finishFailure(built.left);\n        finish(\"built\", built.right);\n    });\n}\n/** 首次尝试 + 2 次重试:与 provisioning 同一种「封顶次数」纪律,构建单次耗时更长所以更浅。 */\nconst DEFAULT_BUILD_ATTEMPTS = 3;\nconst DEFAULT_BUILD_RETRY_BASE_MS = 1000;\n/** 指数退避 + 全抖动(0.5x~1.5x),避免同一批被限流的构建同时醒来再次撞限流。 */\nfunction backoffDelay(baseMs: number, attempt: number, jitter: number): number {\n    return baseMs * 2 ** attempt * (0.5 + jitter);\n}\n/** 退避睡眠:Clock 驱动的 Effect.sleep(TestClock 可验证时序),abort 时提前放行。 */\nfunction sleep(ms: number, signal: AbortSignal): Effect.Effect<void, never> {\n    if (ms <= 0)\n        return Effect.void;\n    const timer = Effect.sleep(Duration.millis(ms));\n    const abort = Effect.async<void>((resume) => {\n        if (signal.aborted) {\n            resume(Effect.void);\n            return;\n        }\n        const onAbort = () => resume(Effect.void);\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n        return Effect.sync(() => signal.removeEventListener(\"abort\", onAbort));\n    });\n    return Effect.raceFirst(timer, abort);\n}\n/**\n * 构建失败的性质分类:瞬时才重试。\n * 先过与 provisioning 共用的保守瞬时分类器,再补 builder CLI 自己的文案形态——\n * registry 限流、拉取中途 EOF、TLS / IO 超时都出现在 `docker compose build` 的 stderr 里,\n * 它们不带 status code,只有文案。\n */\nfunction isTransientBuildError(e: unknown): boolean {\n    if (isRetryableProvisionError(classifyProvisionErrorFallback(e)))\n        return true;\n    const message = e instanceof Error ? e.message : String(e);\n    return /toomanyrequests|unexpected EOF|i\\/o timeout|TLS handshake timeout|failed to do request|connection reset by peer|temporary failure in name resolution|failed to copy: httpReadSeeker|EOF$/im.test(message);\n}\nfunction abortError(signal: AbortSignal, buildKey: BuildKey, cause?: unknown): NonNullable<SandboxBuildRecord[\"error\"]> {\n    const timedOut = isTimeoutReason(signal.reason);\n    const code = timedOut ? \"sandbox-build-timeout\" : \"sandbox-build-cancelled\";\n    const message = timedOut\n        ? `sandbox build timed out for BuildKey ${buildKey.slice(0, 12)}…`\n        : `sandbox build cancelled for BuildKey ${buildKey.slice(0, 12)}…`;\n    return {\n        code,\n        message,\n        ...(cause !== undefined ? { cause: causeSummary(cause) } : {}),\n    };\n}\nfunction isTimeoutReason(reason: unknown): boolean {\n    if (reason === undefined || reason === null)\n        return false;\n    if (typeof DOMException !== \"undefined\" && reason instanceof DOMException && reason.name === \"TimeoutError\") {\n        return true;\n    }\n    return reason instanceof Error && reason.name === \"TimeoutError\";\n}\nfunction failedError(buildKey: BuildKey, e: unknown): NonNullable<SandboxBuildRecord[\"error\"]> {\n    return {\n        code: \"sandbox-build-failed\",\n        message: e instanceof Error ? e.message : `sandbox build failed for BuildKey ${buildKey.slice(0, 12)}…`,\n        cause: causeSummary(e),\n    };\n}\nfunction causeSummary(e: unknown): {\n    name?: string;\n    code?: string;\n    message: string;\n} {\n    if (e instanceof Error) {\n        const withCode = e as Error & {\n            code?: unknown;\n        };\n        const code = typeof withCode.code === \"string\" ? withCode.code : undefined;\n        return {\n            name: e.name,\n            ...(code !== undefined ? { code } : {}),\n            message: e.message,\n        };\n    }\n    return { message: String(e) };\n}\nfunction isAbortError(e: unknown): boolean {\n    if (e instanceof Error && e.name === \"AbortError\")\n        return true;\n    if (typeof DOMException !== \"undefined\" && e instanceof DOMException && e.name === \"AbortError\")\n        return true;\n    return false;\n}\nfunction combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal {\n    const active = signals.filter((s): s is AbortSignal => s !== undefined);\n    if (active.length === 0)\n        return new AbortController().signal;\n    if (active.length === 1)\n        return active[0]!;\n    return AbortSignal.any(active);\n}\n"]}

package/dist/sandbox/build-coordinator.d.cts

@@ -4,8 +4,24 @@ import type { SandboxBuildRecord, TimingActivity } from "../runner/types.cjs";
 import type { BuildKey } from "./identity.cjs";
 /** Run 级开放 activity key;与 Record 契约同名。 */
 export declare const SANDBOX_BUILD_ACTIVITY: "sandbox.build";
+declare const MaterializationScopeIdBrand: unique symbol;
+export type MaterializationScopeId = string & {
+    readonly [MaterializationScopeIdBrand]: true;
+};
+declare const SandboxBuildRefBrand: unique symbol;
+export type SandboxBuildRef = string & {
+    readonly [SandboxBuildRefBrand]: true;
+};
+export declare function materializationScopeId(input: {
+    readonly providerFamily: string;
+    readonly authorityFingerprint: string;
+    readonly materializationProtocolVersion: number;
+}): MaterializationScopeId;
+export declare function sandboxBuildRef(scopeId: MaterializationScopeId, buildKey: BuildKey): SandboxBuildRef;
 /** 一条待协调的构建工作(同 BuildKey 只保留第一次出现的 inputs / provider)。 */
 export interface SandboxBuildWork {
+    readonly ref: SandboxBuildRef;
+    readonly scopeId: MaterializationScopeId;
     readonly buildKey: BuildKey;
     readonly provider: string;
     /** 解析后的构建输入投影;不含凭据值。 */
@@ -13,17 +29,36 @@ export interface SandboxBuildWork {
     /** 有界人读标签;省略时用 BuildKey 短前缀。 */
     readonly label?: string;
 }
+export interface SandboxBuildUseHandle {
+    readonly locator: JsonValue;
+    release(): Promise<void> | void;
+}
+export interface SandboxBuildArtifactSource {
+    readonly locator: JsonValue;
+    readonly source: "cache" | "build";
+    acquireUse(signal: AbortSignal): Promise<SandboxBuildUseHandle>;
+    release(): Promise<void> | void;
+}
+export type SandboxBuildLookup = {
+    readonly _tag: "Hit";
+    readonly source: SandboxBuildArtifactSource;
+} | {
+    readonly _tag: "Miss";
+} | {
+    readonly _tag: "Unsupported";
+};
 /** provider 侧 cache 查询与真实构建。 */
 export interface SandboxBuildProvider {
     /** 查 provider 原生 cache / 本地 build registry;命中返回 locator。 */
-    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<JsonValue | undefined>;
+    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<SandboxBuildLookup>;
     /** cache miss 时调用原生构建 API。 */
-    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<JsonValue>;
+    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<SandboxBuildArtifactSource>;
     /** 可选:Invocation abort / timeout 时取消远端 build。 */
     cancel?(work: SandboxBuildWork): Promise<void>;
 }
 /** 构建执行上下文:子 activity 挂在当前 sandbox.build 节点下。 */
 export interface SandboxBuildExecutionContext {
+    readonly operationId: string;
     readonly signal: AbortSignal;
     readonly timing: RunTimingRecorder;
     readonly parent: TimingActivity;
@@ -52,12 +87,15 @@ export interface PrepareSandboxBuildsOptions {
 /** 构建协调器对外的有界 activity 事件(与 Run feedback 的 run-activity 字段对齐)。 */
 export type SandboxBuildActivityEvent = {
     status: "started";
+    ref: SandboxBuildRef;
     buildKey: BuildKey;
     id: string;
     key: typeof SANDBOX_BUILD_ACTIVITY;
     label: string;
 } | {
     status: "done" | "failed";
+    outcome: SandboxBuildRecord["status"];
+    ref: SandboxBuildRef;
     buildKey: BuildKey;
     id: string;
     key: typeof SANDBOX_BUILD_ACTIVITY;
@@ -65,6 +103,7 @@ export type SandboxBuildActivityEvent = {
     durationMs: number;
 };
 export interface SandboxBuildFailure {
+    readonly ref: SandboxBuildRef;
     readonly buildKey: BuildKey;
     readonly timingNodeId: string;
     readonly status: "failed" | "cancelled";
@@ -72,20 +111,20 @@ export interface SandboxBuildFailure {
 }
 export interface SandboxBuildPreparation {
     /** 成功(hit / built)的 BuildKey → locator。 */
-    readonly locators: ReadonlyMap<BuildKey, JsonValue>;
+    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;
     /** 实际查询或构建过的每条 provenance(不含完全携带、从未过问的 key)。 */
     readonly records: readonly SandboxBuildRecord[];
     /** 失败或取消的 BuildKey → 共用同一 Run timing origin 的错误。 */
-    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;
+    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;
 }
 /** 进行中的 Run 级共享准备:逐 BuildKey 放行,依赖者只等自己引用的那几个 key。 */
 export interface RunningSandboxBuilds {
     /** 已结算 key 的实时视图(随构建推进增补,不等整批收工)。 */
-    readonly locators: ReadonlyMap<BuildKey, JsonValue>;
+    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;
     /** 已失败 / 已取消 key 的实时视图。 */
-    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;
+    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;
     /** 等某个 BuildKey 结算;不在本次协调范围内的 key 立即返回。 */
-    settled(buildKey: BuildKey): Promise<void>;
+    settled(ref: SandboxBuildRef): Promise<void>;
     /** 全部 key 结算后的汇总(provenance 在这里齐全)。 */
     readonly done: Promise<SandboxBuildPreparation>;
 }
@@ -109,3 +148,4 @@ export declare function buildFailureOrigin(failure: SandboxBuildFailure): {
     timingNodeId: string;
     cause?: SandboxBuildFailure["error"]["cause"];
 };
+export {};

package/dist/sandbox/build-coordinator.d.mts

@@ -4,8 +4,24 @@ import type { SandboxBuildRecord, TimingActivity } from "../runner/types.mjs";
 import type { BuildKey } from "./identity.mjs";
 /** Run 级开放 activity key;与 Record 契约同名。 */
 export declare const SANDBOX_BUILD_ACTIVITY: "sandbox.build";
+declare const MaterializationScopeIdBrand: unique symbol;
+export type MaterializationScopeId = string & {
+    readonly [MaterializationScopeIdBrand]: true;
+};
+declare const SandboxBuildRefBrand: unique symbol;
+export type SandboxBuildRef = string & {
+    readonly [SandboxBuildRefBrand]: true;
+};
+export declare function materializationScopeId(input: {
+    readonly providerFamily: string;
+    readonly authorityFingerprint: string;
+    readonly materializationProtocolVersion: number;
+}): MaterializationScopeId;
+export declare function sandboxBuildRef(scopeId: MaterializationScopeId, buildKey: BuildKey): SandboxBuildRef;
 /** 一条待协调的构建工作(同 BuildKey 只保留第一次出现的 inputs / provider)。 */
 export interface SandboxBuildWork {
+    readonly ref: SandboxBuildRef;
+    readonly scopeId: MaterializationScopeId;
     readonly buildKey: BuildKey;
     readonly provider: string;
     /** 解析后的构建输入投影;不含凭据值。 */
@@ -13,17 +29,36 @@ export interface SandboxBuildWork {
     /** 有界人读标签;省略时用 BuildKey 短前缀。 */
     readonly label?: string;
 }
+export interface SandboxBuildUseHandle {
+    readonly locator: JsonValue;
+    release(): Promise<void> | void;
+}
+export interface SandboxBuildArtifactSource {
+    readonly locator: JsonValue;
+    readonly source: "cache" | "build";
+    acquireUse(signal: AbortSignal): Promise<SandboxBuildUseHandle>;
+    release(): Promise<void> | void;
+}
+export type SandboxBuildLookup = {
+    readonly _tag: "Hit";
+    readonly source: SandboxBuildArtifactSource;
+} | {
+    readonly _tag: "Miss";
+} | {
+    readonly _tag: "Unsupported";
+};
 /** provider 侧 cache 查询与真实构建。 */
 export interface SandboxBuildProvider {
     /** 查 provider 原生 cache / 本地 build registry;命中返回 locator。 */
-    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<JsonValue | undefined>;
+    lookup(work: SandboxBuildWork, signal: AbortSignal): Promise<SandboxBuildLookup>;
     /** cache miss 时调用原生构建 API。 */
-    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<JsonValue>;
+    build(work: SandboxBuildWork, ctx: SandboxBuildExecutionContext): Promise<SandboxBuildArtifactSource>;
     /** 可选:Invocation abort / timeout 时取消远端 build。 */
     cancel?(work: SandboxBuildWork): Promise<void>;
 }
 /** 构建执行上下文:子 activity 挂在当前 sandbox.build 节点下。 */
 export interface SandboxBuildExecutionContext {
+    readonly operationId: string;
     readonly signal: AbortSignal;
     readonly timing: RunTimingRecorder;
     readonly parent: TimingActivity;
@@ -52,12 +87,15 @@ export interface PrepareSandboxBuildsOptions {
 /** 构建协调器对外的有界 activity 事件(与 Run feedback 的 run-activity 字段对齐)。 */
 export type SandboxBuildActivityEvent = {
     status: "started";
+    ref: SandboxBuildRef;
     buildKey: BuildKey;
     id: string;
     key: typeof SANDBOX_BUILD_ACTIVITY;
     label: string;
 } | {
     status: "done" | "failed";
+    outcome: SandboxBuildRecord["status"];
+    ref: SandboxBuildRef;
     buildKey: BuildKey;
     id: string;
     key: typeof SANDBOX_BUILD_ACTIVITY;
@@ -65,6 +103,7 @@ export type SandboxBuildActivityEvent = {
     durationMs: number;
 };
 export interface SandboxBuildFailure {
+    readonly ref: SandboxBuildRef;
     readonly buildKey: BuildKey;
     readonly timingNodeId: string;
     readonly status: "failed" | "cancelled";
@@ -72,20 +111,20 @@ export interface SandboxBuildFailure {
 }
 export interface SandboxBuildPreparation {
     /** 成功(hit / built)的 BuildKey → locator。 */
-    readonly locators: ReadonlyMap<BuildKey, JsonValue>;
+    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;
     /** 实际查询或构建过的每条 provenance(不含完全携带、从未过问的 key)。 */
     readonly records: readonly SandboxBuildRecord[];
     /** 失败或取消的 BuildKey → 共用同一 Run timing origin 的错误。 */
-    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;
+    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;
 }
 /** 进行中的 Run 级共享准备:逐 BuildKey 放行,依赖者只等自己引用的那几个 key。 */
 export interface RunningSandboxBuilds {
     /** 已结算 key 的实时视图(随构建推进增补,不等整批收工)。 */
-    readonly locators: ReadonlyMap<BuildKey, JsonValue>;
+    readonly sources: ReadonlyMap<SandboxBuildRef, SandboxBuildArtifactSource>;
     /** 已失败 / 已取消 key 的实时视图。 */
-    readonly failures: ReadonlyMap<BuildKey, SandboxBuildFailure>;
+    readonly failures: ReadonlyMap<SandboxBuildRef, SandboxBuildFailure>;
     /** 等某个 BuildKey 结算;不在本次协调范围内的 key 立即返回。 */
-    settled(buildKey: BuildKey): Promise<void>;
+    settled(ref: SandboxBuildRef): Promise<void>;
     /** 全部 key 结算后的汇总(provenance 在这里齐全)。 */
     readonly done: Promise<SandboxBuildPreparation>;
 }
@@ -109,3 +148,4 @@ export declare function buildFailureOrigin(failure: SandboxBuildFailure): {
     timingNodeId: string;
     cause?: SandboxBuildFailure["error"]["cause"];
 };
+export {};