akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -0,0 +1,525 @@
+// 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 { UsageError } from "../../core/errors.js";
+import { decodeFrozenExecutableIdentity } from "../../execution/executable-identity.js";
+import { canonicalResolvedExecutionRequest, decodeResolvedExecutionRequest, } from "../../execution/resolved-request.js";
+import { decodeExecutionSourceIdentity } from "../../execution/source.js";
+import { decodeFrozenRunnerSpec } from "../../integrations/agent/execution-lowering.js";
+import { decodeWorkflowExecSpec, validateWorkflowPlanStructure, } from "./schema.js";
+export const WORKFLOW_IR_V4_VERSION = 4;
+/** Strict v4 corruption gate. No authored source or config is consulted here. */
+export function decodeWorkflowPlanV4(input, hooks = {}) {
+    const raw = record(input, "plan");
+    if (raw.irVersion !== WORKFLOW_IR_V4_VERSION)
+        fail("irVersion must be 4");
+    assertKeys(raw, ["irVersion", "title", "params", "paramSchemas", "budget", "execution", "steps", "sourceReadSet"], "plan");
+    if (!Object.hasOwn(raw, "sourceReadSet"))
+        fail("sourceReadSet is required");
+    const sourceReadSet = decodeSourceReadSet(raw.sourceReadSet);
+    validateWorkflowPlanStructure(raw, {
+        expectedVersion: WORKFLOW_IR_V4_VERSION,
+        planExtraKeys: ["sourceReadSet"],
+        unitExtraKeys: ["frozenTarget", "environment"],
+        gateExtraKeys: ["frozenJudge"],
+    }, hooks);
+    const rawSteps = raw.steps;
+    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),
+                };
+            })()
+            : decodeUnitV4(rawRoot, requiredSources);
+        return Object.freeze({ ...step, root, gate });
+    });
+    assertRequiredSources(sourceReadSet, requiredSources);
+    return Object.freeze({
+        ...raw,
+        irVersion: WORKFLOW_IR_V4_VERSION,
+        sourceReadSet,
+        steps,
+    });
+}
+function decodeUnitV4(raw, requiredSources) {
+    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);
+    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") || gate.frozenJudge === null) {
+        fail(`gate ${stepId} with criteria requires a frozen judge target`);
+    }
+    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) {
+    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);
+    fail(`unit ${unit.id} frozenTarget has unsupported kind ${String(target.kind)}`);
+}
+function decodeCommandTarget(target, unit, requiredSources) {
+    assertKeys(target, ["kind", "ref", "contentHash", "request", "runner", "concurrency", "cwdIdentity", "executable", "gitCommitOid"], `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);
+    // 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 } : {}),
+    });
+}
+function decodeShellTarget(target, unit, environment) {
+    assertKeys(target, ["kind", "contentHash", "exec", "cwdIdentity", "executable", "gitCommitOid"], `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`);
+    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`);
+    return Object.freeze({
+        kind: "shell",
+        contentHash,
+        exec,
+        cwdIdentity,
+        ...(executable ? { executable } : {}),
+        ...(gitCommitOid ? { gitCommitOid } : {}),
+    });
+}
+function decodeScriptTarget(target, unit, requiredSources) {
+    assertKeys(target, [
+        "kind",
+        "ref",
+        "contentHash",
+        "exec",
+        "interpreter",
+        "extension",
+        "bytesBase64",
+        "byteLength",
+        "cwdIdentity",
+        "materialization",
+        "executable",
+        "gitCommitOid",
+    ], `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);
+    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 } : {}),
+    });
+}
+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 compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+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");
+}