akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/workflows/ir/schema-v4.js

@@ -1,745 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Additive durable workflow plan v4.
- *
- * This is the sole executable workflow plan. Older stored plans are rejected
- * at the run-storage boundary instead of being replayed through a second
- * runtime architecture.
- */
-import { createHash } from "node:crypto";
-import path from "node:path";
-import { compareCodePoints } from "../../core/common.js";
-import { UsageError } from "../../core/errors.js";
-import { decodeFrozenExecutableIdentity } from "../../execution/executable-identity.js";
-import { INPUT_NAME_PATTERN } from "../../execution/input-contract.js";
-import { canonicalResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
-import { decodeExecutionSourceIdentity } from "../../execution/source.js";
-import { decodeFrozenRunnerSpec } from "../../integrations/agent/execution-lowering.js";
-import { parseReference } from "../program/expressions.js";
-import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
-import { utf8Bytes } from "../resource-limits.js";
-import { decodeWorkflowExecSpec, validateWorkflowPlanStructure, } from "./schema.js";
-export const WORKFLOW_IR_V5_VERSION = 5;
-/**
- * Strict v4 corruption gate. No authored source or config is consulted here.
- *
- * `depth` is the composition-depth recursion counter (0 at the root
- * workflow plan; +1 for every embedded child-workflow plan), and `budget` is
- * a MUTABLE, tree-wide running total of embedded child-plan bytes charged so
- * far. Both are internal to the recursive child-workflow decode path below
- * (`decodeChildWorkflowTarget` calls this function again on an embedded
- * `frozenPlan`, sharing the SAME `budget` object across the whole recursion —
- * mirroring `ChildCompositionContext.budget` on the freeze side) — every
- * external caller decodes a plan at the top level and relies on the
- * defaults. Re-enforces the composition depth bound AND the aggregate
- * embedded-bytes bound at decode as corruption gates (spec docs/plans/specs/
- * p3a-plan-v5-child-freeze.md §3.6 step 6, rows A-23, A-N6); the actionable
- * freeze-time `COMPOSITION_INVALID` gates live in
- * `src/workflows/freeze/targets/child-workflow.ts` (Lane B).
- */
-export function decodeWorkflowPlanV4(input, depth = 0, budget = { embeddedBytes: 0 }) {
-    const raw = record(input, "plan");
-    if (raw.irVersion !== WORKFLOW_IR_V5_VERSION)
-        fail("irVersion must be 5");
-    assertKeys(raw, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps", "sourceReadSet", "outputs"], "plan");
-    if (!Object.hasOwn(raw, "sourceReadSet"))
-        fail("sourceReadSet is required");
-    const sourceReadSet = decodeSourceReadSet(raw.sourceReadSet);
-    validateWorkflowPlanStructure(raw, {
-        expectedVersion: WORKFLOW_IR_V5_VERSION,
-        planExtraKeys: ["sourceReadSet", "outputs"],
-        unitExtraKeys: ["frozenTarget", "environment"],
-        gateExtraKeys: ["frozenJudge"],
-    });
-    const rawSteps = raw.steps;
-    const stepIds = new Set(rawSteps.map((rawStep) => rawStep.stepId));
-    const requiredSources = [];
-    const steps = rawSteps.map((rawStep, index) => {
-        const step = rawStep;
-        const sourceStep = record(rawSteps[index], `step ${step.stepId}`);
-        const gate = decodeGateV4(sourceStep.gate, step.stepId, requiredSources);
-        if (!step.root)
-            return Object.freeze({ ...step, gate });
-        const rawRoot = record(sourceStep.root, `step ${step.stepId} root`);
-        const root = rawRoot.kind === "map"
-            ? (() => {
-                const { template: _template, ...map } = rawRoot;
-                return {
-                    ...map,
-                    template: decodeUnitV4(record(rawRoot.template, `map ${String(rawRoot.id)} template`), requiredSources, depth, budget),
-                };
-            })()
-            : decodeUnitV4(rawRoot, requiredSources, depth, budget);
-        return Object.freeze({ ...step, root, gate });
-    });
-    assertRequiredSources(sourceReadSet, requiredSources);
-    const outputs = Object.hasOwn(raw, "outputs") ? decodeWorkflowOutputs(raw.outputs, stepIds) : undefined;
-    const { outputs: _rawOutputs, ...restRaw } = raw;
-    return Object.freeze({
-        ...restRaw,
-        irVersion: WORKFLOW_IR_V5_VERSION,
-        sourceReadSet,
-        steps,
-        ...(outputs ? { outputs } : {}),
-    });
-}
-/**
- * Decode a plan's `outputs` (P3b, spec §4.2): a corruption gate mirroring
- * {@link decodeInputBindings} — non-empty, sorted-unique keys (canonical wire
- * order, same rule `inputBindings` enforces), each name matching the
- * `params:` name pattern, each entry's closed key set, `from` re-parsing as a
- * `stepOutput` reference whose step id is declared in `plan.steps`.
- */
-function decodeWorkflowOutputs(value, stepIds) {
-    const raw = record(value, "plan outputs");
-    const names = Object.keys(raw);
-    if (names.length === 0)
-        fail("plan outputs must be a non-empty object");
-    let prior;
-    const outputs = {};
-    for (const name of names) {
-        if (!PROGRAM_PARAM_NAME_PATTERN.test(name))
-            fail(`plan outputs has invalid name ${name}`);
-        if (prior !== undefined && compareCodePoints(prior, name) >= 0) {
-            fail("plan outputs must be sorted by unique name");
-        }
-        prior = name;
-        const entry = record(raw[name], `plan outputs.${name}`);
-        assertKeys(entry, ["from", "schema"], `plan outputs.${name}`);
-        if (typeof entry.from !== "string" || !entry.from)
-            fail(`plan outputs.${name} from is invalid`);
-        const parsed = parseReference(entry.from);
-        if (!parsed.ok || parsed.expr.kind !== "stepOutput") {
-            fail(`plan outputs.${name} from must be a steps.<id>.output reference`);
-        }
-        if (!stepIds.has(parsed.expr.stepId)) {
-            fail(`plan outputs.${name} from names step ${parsed.expr.stepId}, which is not in plan.steps`);
-        }
-        const schema = Object.hasOwn(entry, "schema") ? record(entry.schema, `plan outputs.${name} schema`) : undefined;
-        outputs[name] = Object.freeze({ from: entry.from, ...(schema ? { schema: Object.freeze(schema) } : {}) });
-    }
-    return Object.freeze(outputs);
-}
-function decodeUnitV4(raw, requiredSources, depth, budget) {
-    const id = raw.id;
-    if (!Object.hasOwn(raw, "frozenTarget"))
-        fail(`unit ${id} frozenTarget is required`);
-    if (!Object.hasOwn(raw, "environment"))
-        fail(`unit ${id} environment is required`);
-    const environment = decodeEnvironment(raw.environment, id);
-    const frozenTarget = decodeFrozenTarget(raw.frozenTarget, raw, environment, requiredSources, depth, budget);
-    const { frozenTarget: _target, environment: _environment, ...core } = raw;
-    return Object.freeze({
-        ...core,
-        frozenTarget,
-        environment: Object.freeze(environment),
-    });
-}
-function decodeGateV4(value, stepId, requiredSources) {
-    const gate = record(value, `gate ${stepId}`);
-    const criteria = gate.criteria;
-    if (criteria.length === 0) {
-        if (gate.frozenJudge !== null)
-            fail(`gate ${stepId} without criteria cannot have a frozen judge target`);
-        return Object.freeze({
-            kind: "gate",
-            id: gate.id,
-            stepId,
-            criteria,
-            maxLoops: gate.maxLoops,
-            frozenJudge: null,
-        });
-    }
-    if (!Object.hasOwn(gate, "frozenJudge")) {
-        fail(`gate ${stepId} with criteria is missing its frozenJudge field`);
-    }
-    if (gate.frozenJudge === null) {
-        return Object.freeze({
-            kind: "gate",
-            id: gate.id,
-            stepId,
-            criteria,
-            maxLoops: gate.maxLoops,
-            frozenJudge: null,
-        });
-    }
-    const identity = {
-        kind: "unit",
-        id: gate.id,
-        instructions: criteria.join("\n"),
-        onError: "fail",
-        isolation: "none",
-    };
-    return Object.freeze({
-        kind: "gate",
-        id: gate.id,
-        stepId,
-        criteria,
-        maxLoops: gate.maxLoops,
-        frozenJudge: decodeCommandTarget(record(gate.frozenJudge, `gate ${stepId} frozenJudge`), identity, requiredSources),
-    });
-}
-function decodeFrozenTarget(value, unit, environment, requiredSources, depth, budget) {
-    const target = record(value, `unit ${unit.id} frozenTarget`);
-    if (target.kind === "command")
-        return decodeCommandTarget(target, unit, requiredSources);
-    if (target.kind === "shell")
-        return decodeShellTarget(target, unit, environment);
-    if (target.kind === "script")
-        return decodeScriptTarget(target, unit, requiredSources);
-    if (target.kind === "child-workflow")
-        return decodeChildWorkflowTarget(target, unit, depth, budget);
-    fail(`unit ${unit.id} frozenTarget has unsupported kind ${String(target.kind)}`);
-}
-/**
- * Decode a `kind: "child-workflow"` frozen target (§3.5): the embedded
- * COMPLETE child plan, re-verified against its own `planHash` and this
- * target's own `contentHash` on every decode (rows A-20, A-21), recursively
- * enforcing `irVersion` 5 (row A-22, via the recursive
- * {@link decodeWorkflowPlanV4} call), the composition depth bound (row A-23),
- * and the AGGREGATE embedded-plan-bytes bound (§3.6 step 6, A-N6) as the
- * decoder recurses. `WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES` — unlike the
- * depth bound above — is imported directly from
- * `src/workflows/resource-limits.ts` rather than reproduced: that constant
- * was already Lane B's when this decode-time re-enforcement was added (no
- * lane-ordering constraint left to honor), and re-deriving a byte cap by
- * hand invites drift a depth integer does not. `budget` is charged with
- * THIS child's own full canonical byte length AFTER it decodes (so any
- * further-nested grandchildren it embeds have already charged themselves,
- * mirroring the freeze-side `chargeEmbeddedBudget`'s post-recursion charge
- * order in `src/workflows/freeze/targets/child-workflow.ts`) — a rejected
- * plan therefore never partially charges the budget. `frozenPlan` is
- * covered wholesale through `planHash`, so it is deliberately NOT
- * re-serialized into `contentHash` (§3.5). No `requiredSources`
- * contribution: unlike a command/script target's own referenced source, the
- * child's transitive sources live in the child's OWN `sourceReadSet`,
- * verified by the recursive decode call itself; the PARENT's
- * `sourceReadSet` absorbing the child's files (row B-05) is a freeze-time
- * concern (Lane B), not a decode-time structural one.
- */
-function decodeChildWorkflowTarget(target, unit, depth, budget) {
-    assertKeys(target, ["kind", "ref", "planHash", "frozenPlan", "contentHash", "via", "taskRef", "inputBindings"], `unit ${unit.id} child workflow target`);
-    if (typeof target.ref !== "string" || !target.ref)
-        fail(`unit ${unit.id} child workflow ref is invalid`);
-    const planHash = digest(target.planHash, `unit ${unit.id} child workflow planHash`);
-    if (target.via !== "direct" && target.via !== "task")
-        fail(`unit ${unit.id} child workflow via is invalid`);
-    const via = target.via;
-    if (via === "task") {
-        if (typeof target.taskRef !== "string" || !target.taskRef) {
-            fail(`unit ${unit.id} child workflow via "task" requires a taskRef`);
-        }
-    }
-    else if (target.taskRef !== undefined) {
-        fail(`unit ${unit.id} child workflow via "direct" cannot carry a taskRef`);
-    }
-    const taskRef = target.taskRef;
-    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} child workflow target`);
-    const contentHash = digest(target.contentHash, `unit ${unit.id} child workflow contentHash`);
-    const expectedContentHash = childWorkflowContentHash({ ref: target.ref, planHash, via, taskRef, inputBindings });
-    if (contentHash !== expectedContentHash) {
-        fail(`unit ${unit.id} child workflow contentHash does not match its frozen dispatch`);
-    }
-    const childDepth = depth + 1;
-    const frozenPlan = decodeWorkflowPlanV4(target.frozenPlan, childDepth, budget);
-    const embeddedPlanJson = canonicalJsonLocal(frozenPlan);
-    const actualPlanHash = sha256(embeddedPlanJson);
-    if (actualPlanHash !== planHash) {
-        fail(`unit ${unit.id} child workflow embedded plan does not match its frozen planHash`);
-    }
-    budget.embeddedBytes += utf8Bytes(embeddedPlanJson);
-    return Object.freeze({
-        kind: "child-workflow",
-        ref: target.ref,
-        planHash,
-        frozenPlan,
-        contentHash,
-        via,
-        ...(taskRef !== undefined ? { taskRef } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    });
-}
-/** §3.5's exact `contentHash` formula. */
-function childWorkflowContentHash(fields) {
-    return createHash("sha256")
-        .update("akm.workflow.child-workflow\0v1\0")
-        .update(canonicalJsonLocal({
-        ref: fields.ref,
-        planHash: fields.planHash,
-        via: fields.via,
-        taskRef: fields.taskRef ?? null,
-        inputBindings: fields.inputBindings ?? null,
-    }))
-        .digest("hex");
-}
-function decodeCommandTarget(target, unit, requiredSources) {
-    assertKeys(target, [
-        "kind",
-        "ref",
-        "contentHash",
-        "request",
-        "runner",
-        "concurrency",
-        "cwdIdentity",
-        "executable",
-        "gitCommitOid",
-        "inputBindings",
-    ], `unit ${unit.id} command target`);
-    if (target.ref !== null && typeof target.ref !== "string")
-        fail(`unit ${unit.id} command target ref is invalid`);
-    const request = decodeResolvedExecutionRequest(target.request);
-    if (request.authorization.status === "denied")
-        fail(`unit ${unit.id} command authorization is denied by policy`);
-    if (Object.hasOwn(request.runtime, "environment")) {
-        fail(`unit ${unit.id} resolved request runtime.environment is live and cannot be persisted`);
-    }
-    const contentHash = digest(target.contentHash, `unit ${unit.id} command contentHash`);
-    const actualContentHash = sha256(request.command.content);
-    if (contentHash !== actualContentHash)
-        fail(`unit ${unit.id} command contentHash does not match request content`);
-    const runner = decodeFrozenRunnerSpec(target.runner);
-    if (target.concurrency !== undefined &&
-        (!Number.isSafeInteger(target.concurrency) ||
-            target.concurrency < 1 ||
-            target.concurrency > 64)) {
-        fail(`unit ${unit.id} frozen target concurrency is invalid`);
-    }
-    if (runner.engine !== request.engine.name || runner.kind !== request.engine.kind) {
-        fail(`unit ${unit.id} frozen runner must match the resolved request engine`);
-    }
-    const source = request.command.source;
-    if (source) {
-        requiredSources.push(source);
-        if (target.ref !== source.ref)
-            fail(`unit ${unit.id} command target ref must match request source`);
-    }
-    else if (target.ref !== null) {
-        fail(`unit ${unit.id} inline command target ref must be null`);
-    }
-    if (request.persona)
-        requiredSources.push(request.persona.source);
-    const cwdIdentity = Object.hasOwn(target, "cwdIdentity")
-        ? decodeDirectoryIdentity(target.cwdIdentity, unit.id)
-        : undefined;
-    const executable = Object.hasOwn(target, "executable")
-        ? decodeFrozenExecutableIdentity(target.executable, `unit ${unit.id} executable`)
-        : undefined;
-    if (runner.kind === "agent" && (cwdIdentity !== undefined || executable !== undefined)) {
-        if (!cwdIdentity || !executable)
-            fail(`unit ${unit.id} CLI command target requires cwdIdentity and executable`);
-        if (runner.profile.bin !== executable.requested && runner.profile.bin !== executable.absolutePath) {
-            fail(`unit ${unit.id} executable does not match the frozen runner bin`);
-        }
-    }
-    else if (runner.kind !== "agent" && executable !== undefined) {
-        fail(`unit ${unit.id} non-CLI target cannot carry a host executable`);
-    }
-    const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
-    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} command target`);
-    // Force the shared request canonicalizer across every accepted wire request.
-    canonicalResolvedExecutionRequest(request);
-    return Object.freeze({
-        kind: "command",
-        ref: target.ref,
-        contentHash,
-        request,
-        runner,
-        ...(target.concurrency !== undefined ? { concurrency: target.concurrency } : {}),
-        ...(cwdIdentity ? { cwdIdentity } : {}),
-        ...(executable ? { executable } : {}),
-        ...(gitCommitOid ? { gitCommitOid } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    });
-}
-function decodeShellTarget(target, unit, environment) {
-    assertKeys(target, ["kind", "contentHash", "exec", "cwdIdentity", "executable", "gitCommitOid", "inputBindings"], `unit ${unit.id} shell target`);
-    const exec = decodeWorkflowExecSpec(target.exec, `unit ${unit.id} shell target exec`);
-    const cwdIdentity = decodeDirectoryIdentity(target.cwdIdentity, unit.id);
-    const executable = Object.hasOwn(target, "executable")
-        ? decodeFrozenExecutableIdentity(target.executable, `unit ${unit.id} executable`)
-        : undefined;
-    if (executable && exec.command[0] !== executable.requested && exec.command[0] !== executable.absolutePath) {
-        fail(`unit ${unit.id} shell executable does not match the frozen command`);
-    }
-    const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
-    const contentHash = digest(target.contentHash, `unit ${unit.id} shell contentHash`);
-    // inputBindings deliberately sits OUTSIDE this preimage (P2b A-N7): identity
-    // coverage for a task-composed unit comes from computeUnitInputHash's own
-    // frozenTarget field (step-work.ts), which hashes this whole target anyway.
-    const expected = createHash("sha256")
-        .update("akm.workflow.shell.v1\0")
-        .update(canonicalJsonLocal({ exec, environment, cwdIdentity }))
-        .digest("hex");
-    if (contentHash !== expected)
-        fail(`unit ${unit.id} shell contentHash does not match its frozen dispatch`);
-    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} shell target`);
-    return Object.freeze({
-        kind: "shell",
-        contentHash,
-        exec,
-        cwdIdentity,
-        ...(executable ? { executable } : {}),
-        ...(gitCommitOid ? { gitCommitOid } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    });
-}
-function decodeScriptTarget(target, unit, requiredSources) {
-    assertKeys(target, [
-        "kind",
-        "ref",
-        "contentHash",
-        "exec",
-        "interpreter",
-        "extension",
-        "bytesBase64",
-        "byteLength",
-        "cwdIdentity",
-        "materialization",
-        "executable",
-        "gitCommitOid",
-        "inputBindings",
-    ], `unit ${unit.id} script target`);
-    const exec = decodeWorkflowExecSpec(target.exec, `unit ${unit.id} script target exec`);
-    if (typeof target.ref !== "string" || !target.ref.includes("//"))
-        fail(`unit ${unit.id} script ref is invalid`);
-    if (typeof target.interpreter !== "string" || !target.interpreter)
-        fail(`unit ${unit.id} script interpreter is invalid`);
-    if (typeof target.extension !== "string" || !/^\.[A-Za-z0-9]+$/.test(target.extension)) {
-        fail(`unit ${unit.id} script extension is invalid`);
-    }
-    if (typeof target.bytesBase64 !== "string")
-        fail(`unit ${unit.id} script bytesBase64 is invalid`);
-    const bytes = Buffer.from(target.bytesBase64, "base64");
-    if (bytes.toString("base64") !== target.bytesBase64)
-        fail(`unit ${unit.id} script bytesBase64 is noncanonical`);
-    if (!Number.isSafeInteger(target.byteLength) || target.byteLength !== bytes.byteLength) {
-        fail(`unit ${unit.id} script byteLength does not match frozen bytes`);
-    }
-    const contentHash = digest(target.contentHash, `unit ${unit.id} script contentHash`);
-    if (contentHash !== sha256(bytes))
-        fail(`unit ${unit.id} script contentHash does not match frozen bytes`);
-    if (target.materialization !== "ephemeral-0700-delete")
-        fail(`unit ${unit.id} script materialization is invalid`);
-    const cwdIdentity = decodeDirectoryIdentity(target.cwdIdentity, unit.id);
-    const executable = Object.hasOwn(target, "executable")
-        ? decodeFrozenExecutableIdentity(target.executable, `unit ${unit.id} executable`)
-        : undefined;
-    const gitCommitOid = decodeGitCommitOid(target.gitCommitOid, unit);
-    const inputBindings = decodeInputBindings(target.inputBindings, `unit ${unit.id} script target`);
-    requiredSources.push({ ref: target.ref, bundle: "", adapter: "", file: "", hash: contentHash });
-    return Object.freeze({
-        kind: "script",
-        ref: target.ref,
-        contentHash,
-        exec,
-        interpreter: target.interpreter,
-        extension: target.extension,
-        bytesBase64: target.bytesBase64,
-        byteLength: target.byteLength,
-        cwdIdentity,
-        materialization: "ephemeral-0700-delete",
-        ...(executable ? { executable } : {}),
-        ...(gitCommitOid ? { gitCommitOid } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    });
-}
-/**
- * Decode a frozen target's `inputBindings` (P2b §3.2 A-N7): a composing
- * step's `with:` normalized against the composed task's declared inputs.
- * Closed `kind`, `INPUT_NAME_PATTERN` name, unique and sorted by name (never
- * `[]` — absence is the identity-preserving default). A `literal` entry
- * requires `value`; a `reference` entry requires a `parseReference`-valid
- * `from` plus the declaration's bounded `schema` (§3.6's widened reference
- * arm, `src/execution/input-contract.ts`).
- */
-function decodeInputBindings(value, label) {
-    if (value === undefined)
-        return undefined;
-    if (!Array.isArray(value) || value.length === 0)
-        fail(`${label} inputBindings must be a non-empty array`);
-    let prior;
-    const bindings = value.map((raw, index) => {
-        const binding = record(raw, `${label} inputBindings[${index}]`);
-        if (typeof binding.name !== "string" || !INPUT_NAME_PATTERN.test(binding.name)) {
-            fail(`${label} inputBindings[${index}] name is invalid`);
-        }
-        if (prior !== undefined && compareCodePoints(prior, binding.name) >= 0) {
-            fail(`${label} inputBindings must be sorted by unique name`);
-        }
-        prior = binding.name;
-        if (binding.kind === "literal") {
-            assertKeys(binding, ["kind", "name", "value"], `${label} inputBindings[${index}]`);
-            if (!Object.hasOwn(binding, "value"))
-                fail(`${label} inputBindings[${index}] literal binding requires value`);
-            return Object.freeze({ kind: "literal", name: binding.name, value: binding.value });
-        }
-        if (binding.kind === "reference") {
-            assertKeys(binding, ["kind", "name", "from", "schema"], `${label} inputBindings[${index}]`);
-            if (typeof binding.from !== "string" || !parseReference(binding.from).ok) {
-                fail(`${label} inputBindings[${index}] from is not a valid reference`);
-            }
-            const schema = record(binding.schema, `${label} inputBindings[${index}] schema`);
-            return Object.freeze({
-                kind: "reference",
-                name: binding.name,
-                from: binding.from,
-                schema: Object.freeze(schema),
-            });
-        }
-        return fail(`${label} inputBindings[${index}] has unsupported kind ${String(binding.kind)}`);
-    });
-    return Object.freeze(bindings);
-}
-function decodeGitCommitOid(value, unit) {
-    if (unit.isolation === "worktree") {
-        if (typeof value !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value)) {
-            fail(`unit ${unit.id} worktree target requires a canonical gitCommitOid`);
-        }
-        return value;
-    }
-    if (value !== undefined)
-        fail(`unit ${unit.id} gitCommitOid is only valid for worktree isolation`);
-    return undefined;
-}
-function decodeDirectoryIdentity(value, unitId) {
-    const identity = record(value, `unit ${unitId} cwdIdentity`);
-    const fields = [
-        "requestedRoot",
-        "realRoot",
-        "rootDevice",
-        "rootInode",
-        "requestedCwd",
-        "realCwd",
-        "cwdDevice",
-        "cwdInode",
-    ];
-    assertKeys(identity, fields, `unit ${unitId} cwdIdentity`);
-    for (const field of fields) {
-        if (typeof identity[field] !== "string" || !identity[field])
-            fail(`unit ${unitId} cwdIdentity.${field} is invalid`);
-    }
-    for (const field of ["requestedRoot", "realRoot", "requestedCwd", "realCwd"]) {
-        if (!path.isAbsolute(identity[field]))
-            fail(`unit ${unitId} cwdIdentity.${field} must be absolute`);
-    }
-    return Object.freeze(identity);
-}
-function decodeEnvironment(value, unitId) {
-    if (!Array.isArray(value))
-        fail(`unit ${unitId} environment must be an array`);
-    const out = [];
-    const names = new Set();
-    for (const [index, raw] of value.entries()) {
-        const binding = record(raw, `unit ${unitId} environment[${index}]`);
-        if (binding.kind === "literal") {
-            assertKeys(binding, ["kind", "name", "value"], `unit ${unitId} environment[${index}]`);
-            environmentName(binding.name, unitId, index);
-            if (typeof binding.value !== "string")
-                fail(`unit ${unitId} literal environment value must be a string`);
-            if (literalLooksSecret(binding.name, binding.value)) {
-                fail(`unit ${unitId} literal environment value is secret-shaped`);
-            }
-            out.push(Object.freeze({ kind: "literal", name: binding.name, value: binding.value }));
-        }
-        else if (binding.kind === "pass-through") {
-            assertKeys(binding, ["kind", "name"], `unit ${unitId} environment[${index}]`);
-            environmentName(binding.name, unitId, index);
-            out.push(Object.freeze({ kind: "pass-through", name: binding.name }));
-        }
-        else if (binding.kind === "env-ref") {
-            assertKeys(binding, ["kind", "ref", "owner", "keys", "secretNames", "precedence"], `unit ${unitId} environment[${index}]`);
-            if (typeof binding.ref !== "string" || !binding.ref.includes("//")) {
-                fail(`unit ${unitId} environment[${index}] env-ref must be fully qualified`);
-            }
-            const owner = decodeEnvironmentOwner(binding.owner, binding.ref, unitId, index);
-            const keys = sortedUniqueStrings(binding.keys, `unit ${unitId} environment[${index}] keys`, (value) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(value));
-            const secretNames = sortedUniqueStrings(binding.secretNames, `unit ${unitId} environment[${index}] secretNames`, (value) => /^[A-Za-z0-9_./-]+$/.test(value) && !value.includes(".."));
-            if (!Number.isSafeInteger(binding.precedence) || binding.precedence < 0) {
-                fail(`unit ${unitId} environment[${index}] precedence is invalid`);
-            }
-            out.push(Object.freeze({
-                kind: "env-ref",
-                ref: binding.ref,
-                owner,
-                keys: Object.freeze(keys),
-                secretNames: Object.freeze(secretNames),
-                precedence: binding.precedence,
-            }));
-        }
-        else {
-            fail(`unit ${unitId} environment[${index}] has unsupported kind`);
-        }
-        if (binding.kind !== "env-ref") {
-            const name = binding.name;
-            if (names.has(name))
-                fail(`unit ${unitId} environment contains duplicate name ${name}`);
-            names.add(name);
-        }
-    }
-    return out;
-}
-function decodeEnvironmentOwner(value, ref, unitId, index) {
-    const label = `unit ${unitId} environment[${index}] owner`;
-    const owner = record(value, label);
-    const fields = [
-        "bundle",
-        "adapter",
-        "requestedRoot",
-        "realRoot",
-        "rootPhysicalIdentity",
-        "requestedPath",
-        "realPath",
-        "relativePath",
-    ];
-    assertKeys(owner, fields, label);
-    for (const field of fields) {
-        if (typeof owner[field] !== "string" || !owner[field])
-            fail(`${label}.${field} is invalid`);
-    }
-    if (!ref.startsWith(`${owner.bundle}//`))
-        fail(`${label}.bundle does not own env-ref ${ref}`);
-    for (const field of ["requestedRoot", "realRoot", "requestedPath", "realPath"]) {
-        if (!path.isAbsolute(owner[field]))
-            fail(`${label}.${field} must be absolute`);
-    }
-    const relativePath = owner.relativePath;
-    if (relativePath.includes("\\") ||
-        relativePath === "." ||
-        relativePath.startsWith("../") ||
-        path.isAbsolute(relativePath)) {
-        fail(`${label}.relativePath is not canonical`);
-    }
-    if (path.resolve(owner.requestedRoot, relativePath) !== path.resolve(owner.requestedPath)) {
-        fail(`${label}.requestedPath does not match relativePath`);
-    }
-    if (path.resolve(owner.realRoot, relativePath) !== path.resolve(owner.realPath)) {
-        fail(`${label}.realPath does not match relativePath`);
-    }
-    return Object.freeze(owner);
-}
-function sortedUniqueStrings(value, label, accepts) {
-    if (!Array.isArray(value))
-        fail(`${label} must be an array`);
-    const out = [];
-    let prior;
-    for (const item of value) {
-        if (typeof item !== "string" || !accepts(item))
-            fail(`${label} contains an invalid value`);
-        if (prior !== undefined && compareCodePoints(prior, item) >= 0)
-            fail(`${label} must be sorted and unique`);
-        prior = item;
-        out.push(item);
-    }
-    return out;
-}
-function decodeSourceReadSet(value) {
-    if (!Array.isArray(value) || value.length === 0)
-        fail("sourceReadSet must contain at least one source identity");
-    const out = [];
-    const logical = new Set();
-    const physical = new Map();
-    let priorKey;
-    for (const [index, raw] of value.entries()) {
-        const snapshot = record(raw, `sourceReadSet[${index}]`);
-        assertKeys(snapshot, ["identity", "containmentPhysicalIdentity", "physicalIdentity", "size"], `sourceReadSet[${index}]`);
-        const identity = decodeExecutionSourceIdentity(snapshot.identity, `sourceReadSet[${index}].identity`);
-        const key = sourceKey(identity);
-        if (logical.has(key))
-            fail(`sourceReadSet contains duplicate identity key ${key}`);
-        if (typeof snapshot.containmentPhysicalIdentity !== "string" || !snapshot.containmentPhysicalIdentity) {
-            fail(`sourceReadSet[${index}] containment physical identity is invalid`);
-        }
-        if (typeof snapshot.physicalIdentity !== "string" || !snapshot.physicalIdentity) {
-            fail(`sourceReadSet[${index}] physical identity is invalid`);
-        }
-        if (!Number.isSafeInteger(snapshot.size) || snapshot.size < 0)
-            fail(`sourceReadSet[${index}] size is invalid`);
-        const physicalKey = `${snapshot.containmentPhysicalIdentity}\0${snapshot.physicalIdentity}`;
-        const alias = physical.get(physicalKey);
-        if (alias !== undefined && alias !== key)
-            fail(`sourceReadSet logical refs alias the same physical file identity`);
-        physical.set(physicalKey, key);
-        if (priorKey !== undefined && compareCodePoints(priorKey, key) >= 0) {
-            fail("sourceReadSet is not in canonical ref, adapter, file sort order");
-        }
-        logical.add(key);
-        priorKey = key;
-        out.push(Object.freeze({
-            identity,
-            containmentPhysicalIdentity: snapshot.containmentPhysicalIdentity,
-            physicalIdentity: snapshot.physicalIdentity,
-            size: snapshot.size,
-        }));
-    }
-    return out;
-}
-function assertRequiredSources(readSet, required) {
-    for (const identity of required) {
-        const found = readSet.find((snapshot) => snapshot.identity.ref === identity.ref);
-        if (!found)
-            fail(`source read-set is missing required command/persona/script source ${identity.ref}`);
-        if (identity.bundle && sourceKey(found.identity) !== sourceKey(identity)) {
-            fail(`source read-set identity mismatch for ${identity.ref}`);
-        }
-        if (found.identity.hash !== identity.hash)
-            fail(`source read-set hash mismatch for ${identity.ref}`);
-    }
-}
-function sourceKey(identity) {
-    return `${identity.ref}\0${identity.adapter}\0${identity.file}`;
-}
-function environmentName(value, unitId, index) {
-    if (typeof value !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
-        fail(`unit ${unitId} environment[${index}] has an invalid name`);
-    }
-}
-function literalLooksSecret(name, value) {
-    const key = name.toLowerCase();
-    if (/(?:secret|token|password|passwd|api[_-]?key|access[_-]?key|private[_-]?key|credential|bearer|client_secret)/.test(key)) {
-        return true;
-    }
-    const candidate = value.trim();
-    if (candidate.length < 20 || /\s/.test(candidate))
-        return false;
-    if (/^(?:sk-|rk-|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|xox[baprs]-|AKIA|ASIA|AIza|ya29\.|-----BEGIN)/.test(candidate)) {
-        return true;
-    }
-    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^A-Za-z0-9]/].filter((pattern) => pattern.test(candidate)).length;
-    return (candidate.length >= 24 && classes >= 3) || (candidate.length >= 32 && /^[A-Za-z0-9+/=_-]+$/.test(candidate));
-}
-function digest(value, label) {
-    if (typeof value !== "string" || !/^[0-9a-f]{64}$/.test(value))
-        fail(`${label} must be a SHA-256 digest`);
-    return value;
-}
-function sha256(value) {
-    return createHash("sha256").update(value).digest("hex");
-}
-function canonicalJsonLocal(value) {
-    const sort = (entry) => {
-        if (Array.isArray(entry))
-            return entry.map(sort);
-        if (entry && typeof entry === "object") {
-            return Object.fromEntries(Object.entries(entry)
-                .sort(([left], [right]) => compareCodePoints(left, right))
-                .map(([key, nested]) => [key, sort(nested)]));
-        }
-        return entry;
-    };
-    return JSON.stringify(sort(value));
-}
-function record(value, label) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        fail(`${label} must be an object`);
-    return value;
-}
-function assertKeys(value, allowed, label) {
-    for (const key of Object.keys(value))
-        if (!allowed.includes(key))
-            fail(`${label} contains unknown key ${key}`);
-}
-function fail(message) {
-    throw new UsageError(`Invalid frozen workflow plan v4: ${message}.`, "INVALID_JSON_ARGUMENT");
-}