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

package/dist/workflows/exec/child-workflow.js

@@ -2,71 +2,27 @@
 // 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/.
 /**
- * The child workflow executor (P3b, spec docs/plans/specs/p3b-child-executor.md
- * §3). `driveChildWorkflowUnit` is the ONE place a `child-workflow`-targeted
- * unit is published (idempotently) and driven: no second executor, no second
- * scheduler, no second journal writer. It is reached from the ONE dispatch
- * seam in `native-executor.ts`'s `dispatchJournaledAttempt` (§3.2).
+ * The child workflow executor. `driveChildWorkflowUnit` is the one place a
+ * `child-workflow`-targeted unit is published (idempotently) and driven,
+ * reached from `native-executor.ts`'s dispatch seam: (1) validate the resolved
+ * `with:` bindings against the child's `params:`; (2) derive the deterministic
+ * invocation key; (3) publish the child run idempotently; (4) drive it with
+ * the same engine as a top-level run unless it is already `blocked`/`failed`;
+ * (5) map the child's final status onto this unit's outcome.
  *
- * Ordered algorithm (§3.3): (1) re-verify the embedded child plan's integrity;
- * (2) validate the resolved `with:` bindings against the child's declared
- * `params:`; (3) derive the deterministic invocation key; (4) publish the
- * child run idempotently (`publishChildWorkflowRun`, P3a); (5) read the
- * published row's status; (6) drive it with the SAME engine the top-level path
- * uses (`runWorkflowSteps`) unless it is already terminal-for-this-invocation
- * (`blocked`/`failed`, rows A-22/A-23); (7) map the child's FINAL status
- * through §3.4's table onto this unit's outcome.
- *
- * ## Why `runWorkflowSteps` is reached through a LAZY dynamic import, not a
- * static one (B-N5, and the §7 preservation-gate contingency)
- *
- * `native-executor.ts` must import `driveChildWorkflowUnit` FROM this file
- * (the dispatch seam calls it inline, §3.2) — that edge is fixed. `run-
- * workflow.ts` imports `native-executor.ts` (existing, load-bearing:
- * `executeStepPlan`). If this file ALSO imported `runWorkflowSteps` from
- * `./run-workflow` STATICALLY, the three edges would close a static cycle
- * (native-executor.ts -> child-workflow.ts -> run-workflow.ts ->
- * native-executor.ts), which `tests/architecture/import-cycle-ratchet.test.ts`
- * (shrink-only, EMPTY baseline — an absolute gate) forbids outright; adding an
- * entry to admit it is not an option the ratchet allows. Per this spec's own
- * §7 checklist ("if the ratchet objects, the drive is reached through an
- * injected function value, the pattern `ir/freeze-v4.ts`'s `ChildFreezeFn`
- * already establishes"), the drive is instead reached through
- * {@link driveWithRealEngine}'s `await import("./run-workflow.js")` — a
- * DYNAMIC import, invisible to the static-graph cycle ratchet by design (its
- * own doc: "dynamic `import()` is excluded because it is the repo's
- * sanctioned lazy-loading escape hatch"), registered in
- * `DYNAMIC_IMPORT_BASELINE` (scripts/lint-import-cycles.ts) as a genuine
- * lazy-load: the vast majority of workflow runs compose no child at all, so
- * loading `run-workflow.ts`'s full engine (lease heartbeat, retry loop) is
- * deferred until a `child-workflow` unit is actually dispatched. Bun/Node
- * cache a module on first dynamic import, so this costs nothing on repeat
- * calls, and it resolves the SAME module namespace object a test's
- * `import * as runWorkflowModule from "./run-workflow.js"` holds — a
- * `spyOn(runWorkflowModule, "runWorkflowSteps")` is therefore observed
- * exactly as if this module had imported it statically. Unlike a registered
- * function value (which would depend on `run-workflow.ts` having already
- * been loaded by SOME OTHER file — fragile for a test file exercising this
- * seam in isolation), a dynamic import always resolves correctly regardless
- * of what the rest of the process has loaded. This is the ONLY runtime
- * indirection in the whole drive: no second executor is created, and
- * `driveRun` itself is never exported (B-N5's "no second executor" holds).
+ * `runWorkflowSteps` is reached through a lazy dynamic import: a static one
+ * would close the cycle native-executor -> child-workflow -> run-workflow ->
+ * native-executor, and most runs compose no child at all.
  */
 import { randomUUID } from "node:crypto";
 import { TransientError } from "../../core/errors.js";
 import { withWorkflowRunsRepo } from "../../storage/repositories/workflow-runs-repository.js";
 import { validateWorkflowParams } from "../ir/params.js";
-import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
-import { frozenStepRows } from "../runtime/plan-classifier.js";
+import { canonicalPlanJson } from "../ir/plan-hash.js";
 import { workflowRunExportedResult } from "../runtime/run-outputs.js";
+import { frozenStepRows } from "../runtime/run-plan.js";
 import { computeChildInvocationKey } from "./child-invocation.js";
-/**
- * The real engine's `runWorkflowSteps`, reached ONLY through a dynamic
- * import — see the module doc for why. The return value is deliberately
- * unused by the caller: this module always RE-READS the child run row from
- * the repository afterward (spec step 7) rather than trusting the driver's
- * return value, so no result shape needs to be shared across the seam.
- */
+/** The real engine, via a dynamic import (see the module doc). The caller re-reads the child row afterward. */
 async function driveWithRealEngine(options) {
     const { runWorkflowSteps } = await import("./run-workflow.js");
     await runWorkflowSteps(options);
@@ -74,39 +30,19 @@ async function driveWithRealEngine(options) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
-/** `acquireRunLease`'s exact refusal shape (run-workflow.ts) — matched by text, since this module cannot import that private helper. */
+/** Another live process holds the child run's lock file (run-workflow.ts). */
 function isLeaseBusyError(err) {
-    return err instanceof TransientError && err.message.includes("is already being driven by engine");
+    return err instanceof TransientError && err.code === "RUN_LEASE_HELD";
 }
-/** §3.4's exact `child_workflow_failed` message. */
+/** The `child_workflow_failed` message. */
 function childWorkflowFailedMessage(input) {
     return (`Child workflow run ${input.childRunId} (${input.childRef}) failed at step "${input.childStepId}". ` +
         `Inspect it with \`akm workflow status ${input.childRunId}\`; the parent run's step ` +
         `"${input.parentStepId}" cannot advance until it succeeds.`);
 }
-/**
- * Steps 1-3 (spec §3.3): integrity re-check, param validation, and the
- * deterministic invocation key. Returns either the key or an already-shaped
- * `child_workflow_publish_failed` outcome.
- */
+/** Param validation and the deterministic invocation key, or a `child_workflow_publish_failed` outcome. */
 function precheckAndDeriveInvocationKey(input) {
     const { request, target, ctx, childParams, inputHash } = input;
-    // Step 1 — integrity re-check (row A-10).
-    const recomputedPlanHash = computePlanHash(target.frozenPlan);
-    if (recomputedPlanHash !== target.planHash) {
-        return {
-            ok: false,
-            outcome: {
-                unitId: request.unitId,
-                ok: false,
-                failureReason: "child_workflow_publish_failed",
-                error: `Workflow step "${request.stepId}" composes child workflow ${target.ref}, but its embedded plan's ` +
-                    `recomputed hash (${recomputedPlanHash}) does not match the frozen target's planHash (${target.planHash}). ` +
-                    "The frozen plan has been corrupted or tampered with.",
-            },
-        };
-    }
-    // Step 2 — resolved params against the child's declared param schemas (row A-11).
     const paramErrors = validateWorkflowParams(target.frozenPlan, childParams);
     if (paramErrors.length > 0) {
         return {
@@ -120,7 +56,6 @@ function precheckAndDeriveInvocationKey(input) {
             },
         };
     }
-    // Step 3 — the deterministic invocation key (B-N8: parentUnitId is request.unitId, the parent unit's journalBaseId).
     return {
         ok: true,
         invocationKey: computeChildInvocationKey({
@@ -131,11 +66,8 @@ function precheckAndDeriveInvocationKey(input) {
     };
 }
 /**
- * Step 4/5 (spec §3.3): publish the child run idempotently and return the
- * pre-drive status read (the returned row IS that read). B-N16: no
- * transaction open on this connection — this seam is reached from
- * dispatchJournaledAttempt, outside resumeWorkflowRun's and
- * completeWorkflowStep's own transactions.
+ * Publish the child run idempotently and return the pre-drive row. Runs with
+ * no transaction open on this connection (reached from the dispatch seam).
  */
 async function publishChildRun(input, invocationKey) {
     const { request, target, ctx, childParams } = input;
@@ -162,7 +94,6 @@ async function publishChildRun(input, invocationKey) {
                 updatedAt: now,
                 agentHarness: parentRow.agent_harness,
                 agentSessionId: parentRow.agent_session_id,
-                checkinArmedAt: now,
             },
             steps: frozenStepRows(target.frozenPlan).map((row) => ({ ...row, runId: childRunId })),
             planJson: canonicalPlanJson(target.frozenPlan),
@@ -183,11 +114,9 @@ async function publishChildRun(input, invocationKey) {
     }
 }
 /**
- * Step 6 (spec §3.3): drive the published child run with the real engine,
- * unless it is already terminal-for-this-invocation (`blocked`/`failed`,
- * rows A-22/A-23 — never re-driven, no lease taken). Returns the FINAL row
- * (re-read after the drive) or an already-shaped `child_workflow_busy` /
- * `child_workflow_drive_failed` outcome.
+ * Drive the published child run with the real engine unless it is already
+ * `blocked`/`failed` (never re-driven). Returns the final re-read row, or a
+ * `child_workflow_busy` / `child_workflow_drive_failed` outcome.
  */
 async function driveChildRun(input, childRow) {
     const { request, target, ctx } = input;
@@ -201,27 +130,13 @@ async function driveChildRun(input, childRow) {
         ...(ctx.dispatcher ? { dispatcher: ctx.dispatcher } : {}),
         ...(ctx.maxConcurrency !== undefined ? { maxConcurrency: ctx.maxConcurrency } : {}),
         ...(ctx.eventSource !== undefined ? { eventSource: ctx.eventSource } : {}),
-        // B-N6: a no-op, distinct from the real registry drain — the PARENT's
-        // own `finally` remains the single owner of the process-lifecycle
-        // drain for the whole process (row A-24).
+        // The parent's own `finally` owns the process-lifecycle drain; no maxSteps/maxRetries.
         disposeDispatchResources: () => { },
-        // B-N7: deliberately no maxSteps, no maxRetries (rows A-25, A-26).
     };
     try {
-        // The re-read is INSIDE the same try as the drive (code-review round 4,
-        // finding 1; Review log R1): every throw between here and a mapped
-        // UnitOutcome — the drive itself, OR this immediately-following
-        // getRunById — must be caught. Left to escape, it skips past
-        // dispatchJournaledAttempt's finishJournaledDispatch (no try/catch
-        // wraps this seam there by design), so the parent's reserved attempt
-        // row is never finished; the throw then propagates through runUnit
-        // into concurrentMap's worker (src/core/concurrent.ts), which SWALLOWS
-        // it and leaves the unit's outcome slot `undefined`, which
-        // executeStepPlanInConnection then maps to the false diagnostic
-        // "unit was not dispatched (aborted or scheduler failure)" — losing
-        // the real cause and leaving the composing attempt row stuck
-        // `running` forever (unrecoverable by inspection; a resume + re-drive
-        // reproduces the identical false diagnostic).
+        // The re-read stays inside this try: an escaped throw would skip the
+        // parent attempt's finish and leave its row `running` with a false
+        // "not dispatched" diagnostic.
         await driveWithRealEngine(driveOptions);
         const finalRow = (await withWorkflowRunsRepo((repo) => repo.getRunById(childRow.id))) ?? childRow;
         return { ok: true, finalRow };
@@ -244,22 +159,8 @@ async function driveChildRun(input, childRow) {
                 },
             };
         }
-        // EVERY other throw is mapped here too — never rethrown. §3.5's
-        // original premise ("classified by the existing dispatch_error
-        // handling") was false: no handling exists at this seam
-        // (dispatchJournaledAttempt awaits this call with no try of its own),
-        // so an uncaught throw here escaped all the way into the scheduler and
-        // was silently swallowed (R1, above). Reachable causes include the
-        // child's own LeaseHeartbeat.assertAlive() firing mid-drive,
-        // requireExecutableWorkflowPlan rejecting a
-        // tampered child plan_json, and the child's status changing between
-        // this function's own step 5 read and the drive's internal
-        // getNextWorkflowStep re-read — none of which match
-        // isLeaseBusyError's text. child_workflow_drive_failed is a SIBLING of
-        // child_workflow_publish_failed (row A-10…A-12): same shape, same
-        // errorMessage(err) content, but naming the child run id and ref
-        // (already known at this point, unlike the publish arm above) since
-        // driving — not publishing — is what failed.
+        // Every other throw (a repository error mid-drive, a status race) maps
+        // to child_workflow_drive_failed — never rethrown into the scheduler.
         return {
             ok: false,
             outcome: {
@@ -278,10 +179,7 @@ async function driveChildRun(input, childRow) {
         };
     }
 }
-/**
- * `driveChildWorkflowUnit` — the ONE child drive (spec §3.3). Every failure
- * before step 6 (publication) produces `child_workflow_publish_failed`.
- */
+/** The one child drive. Every failure before the drive produces `child_workflow_publish_failed`. */
 export async function driveChildWorkflowUnit(input) {
     const { request, ctx } = input;
     const precheck = precheckAndDeriveInvocationKey(input);
@@ -304,10 +202,7 @@ export async function driveChildWorkflowUnit(input) {
         status: finalRow.status,
         currentStepId: finalRow.current_step_id,
     };
-    // A-28/A-29: the child did not reach a terminal state, and the parent's
-    // own dispatch signal is what aborted it — checked against the RE-READ
-    // status (not the signal alone) so an already-terminal child is never
-    // misreported as aborted.
+    // Checked against the re-read status, so an already-terminal child is never misreported as aborted.
     if (finalRow.status === "active" && ctx.signal?.aborted) {
         return {
             unitId: request.unitId,
@@ -351,12 +246,8 @@ export async function driveChildWorkflowUnit(input) {
                 childRun: childRunSummary,
             };
         default:
-            // The child's own gate loop exhausted without reaching a terminal
-            // status (a genuine gate rejection on the child's own step, never
-            // reached by this phase's fixtures — B-N7 forwards no maxSteps/
-            // maxRetries, so nothing else can leave a driven child non-terminal
-            // without an abort). Treated conservatively as a failure so the
-            // parent never silently advances on an unresolved child.
+            // A driven child left non-terminal (its own gate loop exhausted) fails
+            // the unit, so the parent never advances on an unresolved child.
             return {
                 unitId: request.unitId,
                 ok: false,

package/dist/workflows/exec/dispatch-redaction.js

@@ -2,37 +2,17 @@
 // 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/.
 /**
- * The ONE redaction contract every frozen-workflow dispatch is held to before
- * anything about its outcome reaches durable state.
- *
- * This is a LEAF module on purpose. Both dispatch paths need it — the unit path
- * (`exec/native-executor.ts`) and the gate-judge path (`exec/frozen-judge.ts`) —
- * and the judge path is reached from `runtime/runs.ts`, which the executor's own
- * dependency chain runs back into. Keeping the helpers here (importing only
- * `core/redaction` plus erased types) means the judge can reuse the exact unit
- * scrub without opening a runtime import cycle.
- *
- * @module workflows/exec/dispatch-redaction
+ * The one redaction contract every frozen-workflow dispatch (unit or gate
+ * judge) is held to before anything about its outcome reaches durable state.
+ * A leaf module, so the judge path reuses it without an import cycle.
  */
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
 import { lookupApiKeyFileValue, lookupApiKeySecretRefValue } from "../../integrations/agent/engine-resolution.js";
 /**
- * Every exact value that must never survive into the journal from ONE frozen
- * dispatch: the resolved `env` bindings injected into the child, the selected
- * engine's (and its SDK fallback's) credential — an env value, a file-backed
- * one (#905), or a secret-store-backed one (#953) — and any `envPassthrough`
- * value the redaction policy does not consider safe to expose.
- *
- * Shared by the unit path and the gate-judge path. There is deliberately ONE
- * collector: a second, parallel implementation is exactly how a dispatch path
- * silently loses the scrub.
- *
- * The credential values are read from `process.env` (or disk / the secret
- * store, for a file- or store-backed one) AT CALL TIME, so a caller must
- * collect no earlier than the dispatch whose outcome it scrubs. A snapshot
- * taken when the dispatch was merely *planned* can predate a credential the
- * dispatch then resolves live, leaving the exact value it must remove out of
- * the set.
+ * Every exact value that must never reach the journal from one dispatch: the
+ * resolved `env` bindings, the engine's (and SDK fallback's) credential from
+ * env, file, or secret store, and unsafe passthrough values. Read at call time,
+ * so collect no earlier than the dispatch being scrubbed.
  */
 export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
     const values = new Set([...Object.values(env ?? {}), ...(dispatch.sensitiveValues ?? [])]);
@@ -87,18 +67,8 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
     return collectSensitiveValues(values);
 }
 /**
- * Scrub a dispatch outcome before ANYTHING about it is journaled.
- *
- * The `failureReason` downgrade is part of the contract: if redaction ALTERED
- * the reason, the reason itself carried a secret, and the persisted failure
- * vocabulary must not become a side channel for it.
- *
- * Structurally typed over `{ failureReason? }` rather than importing
- * `UnitOutcome` from `step-work.ts`: this module must stay a LEAF, and even an
- * erased `import type` edge here would put `frozen-judge → step-work →
- * runtime/runs → frozen-judge` back on the static import graph (the
- * import-cycle ratchet is shrink-only). Callers keep their exact outcome type
- * through the generic.
+ * Scrub a dispatch outcome before anything about it is journaled. A
+ * `failureReason` the scrub altered carried a secret, so it is downgraded.
  */
 export function redactUnitOutcome(outcome, sensitiveValues) {
     const redacted = redactSensitiveValue(outcome, sensitiveValues);
@@ -107,13 +77,7 @@ export function redactUnitOutcome(outcome, sensitiveValues) {
     }
     return redacted;
 }
-/**
- * Scrub a value THROWN out of a dispatch. A rejection is as durable as a
- * resolved failure — the message becomes the blocked step's notes — so it goes
- * through the same value set. Re-wrapped ONLY when redaction actually changed
- * the message, so an untouched throw keeps its original object (and its type,
- * which callers branch on) byte-identical.
- */
+/** Scrub a value thrown out of a dispatch; re-wrapped only when the scrub changed its message. */
 function redactDispatchError(err, sensitiveValues) {
     if (sensitiveValues.length === 0 || !(err instanceof Error))
         return err;
@@ -125,13 +89,9 @@ function redactDispatchError(err, sensitiveValues) {
     return replacement;
 }
 /**
- * Wrap a dispatcher so BOTH its exits are scrubbed with the request's own
- * `sensitiveValues` — the outcome it resolves to and the error it throws — so a
- * caller holding the wrapped dispatcher cannot observe (or journal) either one
- * unredacted. Used at seams whose results head STRAIGHT for durable state (the
- * gate judge, on both its agent and its llm branch); the unit path instead
- * scrubs once at its own journal boundary (`dispatchJournaledAttempt`), AFTER
- * the structured-output parse loop has seen the raw text.
+ * Wrap a dispatcher so both its outcome and its thrown error are scrubbed with
+ * the request's `sensitiveValues` (the gate judge; the unit path scrubs at its
+ * own journal boundary after the structured-output parse).
  */
 export function withDispatchRedaction(inner) {
     return async (request, feedback) => {

package/dist/workflows/exec/environment.js

@@ -0,0 +1,98 @@
+// 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/.
+/**
+ * Materialize a unit's frozen environment at dispatch. Env-file values are the
+ * one deliberately live input to a frozen plan: freeze records each ref's
+ * owner, key set and `${secret:…}` names; the values (and the secrets they
+ * name) are read here, per dispatch, and nothing is returned until every read
+ * has succeeded.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { assetPathForName } from "../../core/asset/asset-placement.js";
+import { compareCodePoints, isWithin } from "../../core/common.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+export const SECRET_TOKEN_RE = /\$\{secret:([A-Za-z0-9_./-]+)\}/g;
+export function materializeFrozenWorkflowEnvironment(descriptors, options = {}) {
+    const values = {};
+    const sensitive = new Set();
+    const audits = [];
+    for (const descriptor of descriptors) {
+        if (descriptor.kind === "literal") {
+            values[descriptor.name] = descriptor.value;
+            if (descriptor.value)
+                sensitive.add(descriptor.value);
+            continue;
+        }
+        if (descriptor.kind === "pass-through") {
+            const value = options.readPassThrough ? options.readPassThrough(descriptor.name) : process.env[descriptor.name];
+            if (value !== undefined) {
+                values[descriptor.name] = value;
+                if (value)
+                    sensitive.add(value);
+            }
+            continue;
+        }
+        const source = options.readEnvFile ? options.readEnvFile(descriptor) : readEnvFile(descriptor.owner);
+        const parsed = dotenv.parse(typeof source === "string" ? source : Buffer.from(source));
+        const keys = Object.keys(parsed).sort(compareCodePoints);
+        if (!sameStrings(keys, descriptor.keys))
+            invalid(`environment ${descriptor.ref} key set changed after it was frozen`);
+        const secretValues = new Map();
+        for (const name of descriptor.secretNames) {
+            const raw = options.readSecret ? options.readSecret({ name, descriptor }) : readSecret(descriptor.owner, name);
+            if (raw === undefined) {
+                throw new NotFoundError(`Environment ${descriptor.ref} references missing secret ${name}; nothing was materialized.`, "FILE_NOT_FOUND");
+            }
+            const value = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+            secretValues.set(name, value);
+            if (value)
+                sensitive.add(value);
+        }
+        for (const [key, rawValue] of Object.entries(parsed)) {
+            const resolved = rawValue.replace(SECRET_TOKEN_RE, (_token, name) => {
+                const secret = secretValues.get(name);
+                if (secret === undefined)
+                    invalid(`environment ${descriptor.ref} secret ${name} was not frozen`);
+                return secret;
+            });
+            values[key] = resolved;
+            if (resolved)
+                sensitive.add(resolved);
+        }
+        audits.push({
+            eventType: "env_access",
+            ref: descriptor.ref,
+            keys: [...descriptor.keys],
+            secretNames: [...descriptor.secretNames],
+        });
+    }
+    return { values, sensitiveValues: [...sensitive], audits };
+}
+function readEnvFile(owner) {
+    if (!isWithin(owner.requestedPath, owner.requestedRoot))
+        invalid(`env file ${owner.relativePath} escapes its bundle`);
+    return fs.readFileSync(owner.requestedPath);
+}
+function readSecret(owner, name) {
+    const secretsRoot = path.join(owner.requestedRoot, "secrets");
+    const secretPath = assetPathForName("secret", secretsRoot, name);
+    if (!isWithin(secretPath, secretsRoot))
+        invalid(`secret name ${name} escapes its bundle`);
+    try {
+        return fs.readFileSync(secretPath);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function invalid(message) {
+    throw new UsageError(`Invalid frozen workflow environment: ${message}.`, "WORKFLOW_SOURCE_INVALID");
+}