akm-cli 0.9.2-alpha.4 → 0.9.2

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

@@ -4,21 +4,51 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
-import { UsageError } from "../../core/errors.js";
+import { COMPOSITION_INVALID_MULTI_JOB_HINT, UsageError } from "../../core/errors.js";
 import { GuardedExecutionSourceCollector } from "../../execution/guarded-source.js";
 import { defaultMapConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
+import { assertChildOutputReferences } from "../freeze/child-output-references.js";
+import { resolveWorkflowSourceV4 } from "../freeze/source-freeze.js";
 import { compileWorkflowPlan } from "./compile.js";
 import { canonicalJson } from "./plan-hash.js";
-import { decodeWorkflowPlanV4, WORKFLOW_IR_V4_VERSION, } from "./schema-v4.js";
-import { resolveWorkflowSourceV4 } from "./source-freeze-v4.js";
+import { decodeWorkflowPlanV4, WORKFLOW_IR_V5_VERSION, } from "./schema-v4.js";
 /** Compile, resolve, and freeze one executable plan without publishing any state. */
 export async function compileResolveFreezeWorkflowV4(asset, config, options = {}) {
     const sourceCollector = options.sourceCollector ?? new GuardedExecutionSourceCollector();
+    const composition = options.composition ?? {
+        depth: 0,
+        refPath: [asset.ref],
+        budget: { embeddedBytes: 0 },
+    };
+    // Injected rather than imported (A-N7/step-values.ts's `ChildCompositionContext`
+    // doc): `targets/child-workflow.ts` is downstream of this module (via
+    // `resolve-steps.ts` <- `source-freeze.ts`, imported directly above — the
+    // `source-freeze-v4.ts` shim P4 deleted used to sit on this edge), so it
+    // cannot import `compileResolveFreezeWorkflowV4` directly without closing
+    // a static import cycle
+    // (tests/architecture/import-cycle-ratchet.test.ts, shrink-only, empty
+    // baseline). This closure is this function's own recursive call, passed
+    // down as a plain value through `ResolutionContext.freezeChild`.
+    const freezeChild = async (request) => {
+        const child = await compileResolveFreezeWorkflowV4(request.asset, config, {
+            sourceCollector: request.sourceCollector,
+            composition: request.composition,
+        });
+        return { plan: child.plan, sourceCollector: child.sourceCollector };
+    };
     const workflowSource = captureWorkflowSource(asset, sourceCollector);
-    const resolved = await resolveWorkflowSourceV4(asset, workflowSource, config, sourceCollector);
+    const resolved = await resolveWorkflowSourceV4(asset, workflowSource, config, sourceCollector, composition, freezeChild);
     const compiled = compileWorkflowPlan(resolved.sourceIr, asset.title, resolved.units);
     if (!compiled.ok) {
-        throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"), "INVALID_FLAG_VALUE");
+        // P4-N2's mapping (docs/plans/specs/p4-deletions-closeout.md §3.3.4)
+        // applies here too, though `resolved.sourceIr` is already guaranteed
+        // exactly one job by this point (source-freeze.ts's own compile already
+        // succeeded), so this compiler's own errors never carry the
+        // multi-job-unsupported code — the arm always resolves to
+        // WORKFLOW_SOURCE_INVALID.
+        const isMultiJob = compiled.errors.length === 1 && compiled.errors[0]?.code === "multi-job-unsupported";
+        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
+        throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"), code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
     }
     const steps = compiled.plan.steps.map((step) => {
         const frozenJudge = step.gate.criteria.length === 0 ? null : resolved.judges.get(step.stepId);
@@ -42,12 +72,15 @@ export async function compileResolveFreezeWorkflowV4(asset, config, options = {}
             : freezeResolvedUnit(step.root, frozen);
         return Object.freeze({ ...step, root, gate });
     });
+    // P3b, spec §4.4: after every step's target is resolved (so every embedded
+    // child plan is available) and before the plan object is assembled.
+    assertChildOutputReferences(steps);
     const sourceReadSet = sourceCollector
         .snapshot()
         .sources.filter((source) => Boolean(source.identity))
         .map((source) => sourceSnapshot(source));
     const plan = decodeWorkflowPlanV4({
-        irVersion: WORKFLOW_IR_V4_VERSION,
+        irVersion: WORKFLOW_IR_V5_VERSION,
         title: compiled.plan.title,
         ...(compiled.plan.params ? { params: compiled.plan.params } : {}),
         ...(compiled.plan.paramSchemas ? { paramSchemas: compiled.plan.paramSchemas } : {}),
@@ -55,6 +88,7 @@ export async function compileResolveFreezeWorkflowV4(asset, config, options = {}
         execution: { maxConcurrency: workflowMaxConcurrency(config.workflow?.maxConcurrency) },
         sourceReadSet,
         steps,
+        ...(compiled.plan.outputs ? { outputs: compiled.plan.outputs } : {}),
     });
     return Object.freeze({
         plan,
@@ -102,7 +136,7 @@ function captureWorkflowSource(asset, collector) {
     const captured = collector.capture(file, root, { authored: true });
     const parsed = parseBundleRef(asset.ref);
     if (!parsed.bundle || !asset.adapterId) {
-        throw new UsageError(`Workflow ${asset.ref} has no fully-qualified bundle/adapter owner for durable publication.`, "INVALID_FLAG_VALUE");
+        throw new UsageError(`Workflow ${asset.ref} has no fully-qualified bundle/adapter owner for durable publication.`, "WORKFLOW_SOURCE_INVALID");
     }
     return collector.bindIdentity(file, root, {
         ref: asset.ref,

package/dist/workflows/ir/params.js

@@ -8,15 +8,62 @@
  * flowing into a unit prompt. The schemas are frozen into the plan, so
  * validation is a pure function of the frozen plan and supplied params.
  *
- * Uses the same bounded {@link validateJsonSchemaSubset} the engine applies to
- * unit output. Internal callers may validate partial parameter objects; the CLI
- * separately rejects flags that do not exactly name declared parameters.
+ * P2a (docs/plans/specs/p2a-task-source-v4.md §4.3, D3): this module is now a
+ * THIN CONSUMER of the shared input contract, `src/execution/input-contract.ts`
+ * (§4, D3, D3-N1/D3-N2/D3-N3). Every export below keeps its existing name,
+ * signature, message, code, and hint byte-identically —
+ * `tests/workflows/workflow-param-flags.test.ts` and
+ * `tests/integration/workflows/params-validation.test.ts` pin that with zero
+ * diff. `contractFromPlan` adapts a `WorkflowParameterPlan` into an
+ * `InputContract` (every declared param, `required: false` — workflow params
+ * declare nothing required). `WORKFLOW_PARAMETER_DIAGNOSTICS` reproduces
+ * today's five workflow-parameter messages/codes for the shared
+ * `materializeInputFlags` (D3-N3); its `contractViolation` formatter
+ * re-roots each `"$"`-prefixed error from the shared module's internal check
+ * to `"params."`, matching what `validateWorkflowParams` (called directly,
+ * already `"params."`-rooted) has always produced. No coercion or validation
+ * logic lives in this file — it lives once, in the shared module.
  *
  * Pure module: no IO, no engine imports.
  */
 import { UsageError } from "../../core/errors.js";
-import { validateJsonSchemaSubset } from "../../core/json-schema.js";
-import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
+import { materializeInputFlags, validateInputs, } from "../../execution/input-contract.js";
+/** Every declared workflow param as an `InputDeclaration`, `required: false` — workflow params declare nothing required (§4.3). */
+function contractFromPlan(plan) {
+    const names = plan.params ?? Object.keys(plan.paramSchemas ?? {});
+    const contract = {};
+    for (const name of names) {
+        contract[name] = { schema: plan.paramSchemas?.[name] ?? {}, required: false };
+    }
+    return contract;
+}
+/**
+ * `contractFromPlan`, exported under its P3a-facing name (spec
+ * docs/plans/specs/p3a-plan-v5-child-freeze.md A-N8): a child workflow has no
+ * `inputs:` contract of its own (that is task source v4's vocabulary) — it
+ * declares `params:`, and this is the SAME adapter this file already uses
+ * for run-parameter validation, reused so `freezeTaskInputBindings`
+ * (`src/workflows/freeze/task-bindings.ts`, generic over `InputContract`) has
+ * exactly one normalizer for every binding surface. Additive; no behavior
+ * change to this file's own exports.
+ */
+export { contractFromPlan as workflowParamContract };
+function invalidParameter(name, message) {
+    return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
+}
+/** The workflow-parameter message/code vocabulary for `materializeInputFlags` (D3-N3) — today's five strings, unchanged. */
+const WORKFLOW_PARAMETER_DIAGNOSTICS = {
+    unknownFlag: (name, declared) => {
+        const available = declared.map((n) => `--${n}`).join(", ");
+        return new UsageError(`Unknown workflow parameter "--${name}". Parameter flags must exactly match a declared workflow parameter.`, "UNKNOWN_FLAG", available ? `Declared parameters: ${available}.` : "This workflow declares no parameters.");
+    },
+    invalidValue: (name, detail) => invalidParameter(name, detail),
+    contractViolation: (errors) => new UsageError(`Workflow parameter flags do not satisfy the workflow's declared schemas:\n${errors
+        .map((error) => `  - ${error.replace(/^\$/, "params")}`)
+        .join("\n")}`, "INVALID_FLAG_VALUE"),
+    duplicateNonArray: (name) => invalidParameter(name, "was provided more than once but is not declared as an array"),
+    malformedJson: (name) => invalidParameter(name, "must contain valid JSON"),
+};
 /**
  * Materialize exact-name CLI parameter flags against the plan being frozen for
  * the run. The CLI deliberately carries raw values to this boundary so type
@@ -25,123 +72,7 @@ import { PROGRAM_PARAM_NAME_PATTERN } from "../program/schema.js";
 export function materializeWorkflowParameterFlags(plan, flags) {
     if (flags.length === 0)
         return {};
-    const declared = new Set(plan.params ?? Object.keys(plan.paramSchemas ?? {}));
-    const grouped = new Map();
-    for (const flag of flags) {
-        if (!PROGRAM_PARAM_NAME_PATTERN.test(flag.name) || !declared.has(flag.name)) {
-            const available = [...declared]
-                .sort()
-                .map((name) => `--${name}`)
-                .join(", ");
-            throw new UsageError(`Unknown workflow parameter "--${flag.name}". Parameter flags must exactly match a declared workflow parameter.`, "UNKNOWN_FLAG", available ? `Declared parameters: ${available}.` : "This workflow declares no parameters.");
-        }
-        const values = grouped.get(flag.name) ?? [];
-        values.push(flag.value);
-        grouped.set(flag.name, values);
-    }
-    const entries = [];
-    for (const [name, values] of grouped) {
-        const schema = plan.paramSchemas?.[name];
-        entries.push([name, materializeFlagValues(name, values, schema)]);
-    }
-    const params = Object.fromEntries(entries);
-    const errors = validateWorkflowParams(plan, params);
-    if (errors.length > 0) {
-        throw new UsageError(`Workflow parameter flags do not satisfy the workflow's declared schemas:\n${errors.map((error) => `  - ${error}`).join("\n")}`, "INVALID_FLAG_VALUE");
-    }
-    return params;
-}
-function materializeFlagValues(name, values, schema) {
-    const types = schemaTypes(schema);
-    if (types.includes("array")) {
-        if (values.length === 1 && typeof values[0] === "string" && values[0].trim().startsWith("[")) {
-            const parsed = parseJsonFlag(name, values[0]);
-            if (!Array.isArray(parsed))
-                throw invalidParameter(name, "must be a JSON array");
-            return parsed;
-        }
-        const itemSchema = isRecord(schema?.items) ? schema.items : undefined;
-        return values.map((value) => coerceFlagValue(name, value, itemSchema));
-    }
-    if (values.length > 1) {
-        throw invalidParameter(name, "was provided more than once but is not declared as an array");
-    }
-    return coerceFlagValue(name, values[0], schema);
-}
-function coerceFlagValue(name, raw, schema) {
-    const types = schemaTypes(schema);
-    if (types.length === 0)
-        return raw;
-    if (typeof raw === "boolean") {
-        if (types.includes("boolean"))
-            return raw;
-        if (types.includes("string"))
-            return String(raw);
-        throw invalidParameter(name, `requires a value of type ${types.join(" | ")}`);
-    }
-    // A union that permits strings keeps the user's exact text. This prevents a
-    // value such as "001" from being silently converted to a number.
-    if (types.includes("string"))
-        return raw;
-    for (const type of types) {
-        switch (type) {
-            case "boolean":
-                if (raw === "true")
-                    return true;
-                if (raw === "false")
-                    return false;
-                break;
-            case "number": {
-                const value = Number(raw);
-                if (raw.trim() !== "" && Number.isFinite(value))
-                    return value;
-                break;
-            }
-            case "integer": {
-                const value = Number(raw);
-                if (raw.trim() !== "" && Number.isSafeInteger(value))
-                    return value;
-                break;
-            }
-            case "null":
-                if (raw === "null")
-                    return null;
-                break;
-            case "object": {
-                const parsed = parseJsonFlag(name, raw);
-                if (isRecord(parsed))
-                    return parsed;
-                break;
-            }
-            case "array": {
-                const parsed = parseJsonFlag(name, raw);
-                if (Array.isArray(parsed))
-                    return parsed;
-                break;
-            }
-        }
-    }
-    throw invalidParameter(name, `must be ${types.join(" | ")}; received ${JSON.stringify(raw)}`);
-}
-function schemaTypes(schema) {
-    const declared = schema?.type;
-    if (typeof declared === "string")
-        return [declared];
-    return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
-}
-function parseJsonFlag(name, raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        throw invalidParameter(name, "must contain valid JSON");
-    }
-}
-function invalidParameter(name, message) {
-    return new UsageError(`Workflow parameter "--${name}" ${message}.`, "INVALID_FLAG_VALUE");
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return materializeInputFlags(contractFromPlan(plan), flags, WORKFLOW_PARAMETER_DIAGNOSTICS);
 }
 /**
  * Validate a run's supplied params against the plan's frozen param schemas.
@@ -149,16 +80,12 @@ function isRecord(value) {
  * valid). Params the plan does not declare a schema for are not constrained.
  */
 export function validateWorkflowParams(plan, params) {
-    const schemas = plan.paramSchemas;
-    if (!schemas || Object.keys(schemas).length === 0)
+    // A plan with no schemas must not start emitting `properties: {}` noise —
+    // preserved as an explicit early return (§4.3 binding constraint), even
+    // though an empty contract would validate to `[]` regardless.
+    if (!plan.paramSchemas || Object.keys(plan.paramSchemas).length === 0)
         return [];
-    // Validate the params object as a whole against a synthetic object schema
-    // whose `properties` are the declared param schemas. Missing declared params
-    // are NOT required (params may be optional / defaulted downstream); only a
-    // PRESENT param that violates its declared schema is an error.
-    // Re-root the validator's `$` JSON-pointer prefix to `params` for messages
-    // that read naturally in a start/CLI error (e.g. `params.files: expected …`).
-    return validateJsonSchemaSubset(params, { type: "object", properties: schemas }).map((e) => e.replace(/^\$/, "params"));
+    return validateInputs(contractFromPlan(plan), params, { pathRoot: "params" });
 }
 /**
  * Run-integrity assert (reviewer #12): the journaled `params_json`

package/dist/workflows/ir/plan-hash.js

@@ -14,7 +14,7 @@
  */
 import { createHash } from "node:crypto";
 import { utf8Bytes, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_PLAN_BYTES } from "../resource-limits.js";
-import { decodeWorkflowPlanV4, WORKFLOW_IR_V4_VERSION } from "./schema-v4.js";
+import { decodeWorkflowPlanV4, WORKFLOW_IR_V5_VERSION } from "./schema-v4.js";
 /** sha256 hex of the canonical (recursively sorted-keys) JSON of the plan. */
 export function computePlanHash(plan) {
     return createHash("sha256").update(canonicalPlanJson(plan)).digest("hex");
@@ -44,8 +44,8 @@ export function decodeCanonicalPlan(runId, planJson, planHash, expectedVersion)
     const actual = createHash("sha256").update(planJson).digest("hex");
     if (!planHash || !/^[0-9a-f]{64}$/.test(planHash) || actual !== planHash)
         throw new Error(`Workflow run ${runId} frozen plan integrity check failed.`);
-    if (expectedVersion !== undefined && expectedVersion !== null && expectedVersion !== WORKFLOW_IR_V4_VERSION) {
-        throw new Error(`Workflow run ${runId} uses unsupported workflow IR version ${expectedVersion}; this runtime supports only workflow IR version 4.`);
+    if (expectedVersion !== undefined && expectedVersion !== null && expectedVersion !== WORKFLOW_IR_V5_VERSION) {
+        throw new Error(`Workflow run ${runId} uses unsupported workflow IR version ${expectedVersion}; this runtime supports only workflow IR version 5.`);
     }
     const plan = decodeWorkflowPlanV4(parsed);
     const canonical = canonicalPlanJson(plan);