akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/workflows/runtime/unit-phases.js

@@ -0,0 +1,20 @@
+// 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/.
+/**
+ * Unit-row phase markers — a leaf module (imports nothing) so both the exec
+ * drivers (step-work, brief, run-workflow) and the runtime (unit-checkin) can
+ * key on the phase discriminator without an exec ↔ runtime import cycle.
+ * Extracting {@link GATE_EVALUATION_PHASE} here broke the last workflows-
+ * runtime knot (step-work → runs → unit-checkin → step-work; chunk-8 WI-8.6,
+ * DoD 11).
+ */
+/**
+ * `phase` marker stamped on gate-evaluation unit rows. Step ids cannot contain
+ * dots (`PROGRAM_STEP_ID_PATTERN`), so a step can never be NAMED `x.gate` and
+ * the synthetic `<stepId>.gate` node id is collision-free against user step
+ * ids. The phase column is nonetheless the discriminator we key on — an
+ * explicit marker, not a `node_id` suffix match, so recovery stays robust even
+ * if the id scheme evolves. Dispatch rows always journal `phase: null`.
+ */
+export const GATE_EVALUATION_PHASE = "gate";

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -2,99 +2,242 @@
 // 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/.
 import fs from "node:fs";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { canonicalizeWorkflowName } from "../../core/asset/asset-spec.js";
+import path from "node:path";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { adapterForId } from "../../core/adapter/registry.js";
+import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
+import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
+import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { buildFileContext } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 import { formatWorkflowErrors } from "../authoring/authoring.js";
-import { compileWorkflowPlan, compileWorkflowProgram } from "../ir/compile.js";
 import { parseWorkflow } from "../parser.js";
-import { parseWorkflowProgram } from "../program/parser.js";
-import { isWorkflowProgramPath, projectProgramParameters, projectProgramStepDefinitions } from "../program/project.js";
+import { WORKFLOW_SCHEMA_VERSION } from "../schema.js";
 /**
- * Compile a loaded workflow asset into the plan graph that gets frozen on the
- * run row. YAML programs compile via `compileWorkflowProgram` with full
- * expression validation; markdown documents compile via `compileWorkflowPlan`
- * (linear workflows — the stable contract — produce the same linear plan as
- * today). Exactly one of `program` / `document` is set by this loader.
+ * Build the canonical `workflow_runs.workflow_ref` for an AKM workflow asset.
  */
-export function compileWorkflowAssetPlan(asset) {
-    if (asset.program) {
-        const compiled = compileWorkflowProgram(asset.program);
-        if (!compiled.ok) {
-            throw new UsageError(formatWorkflowErrors(asset.path, compiled.errors));
-        }
-        return compiled.plan;
+export function canonicalWorkflowRunRef(bundle, canonicalName) {
+    return makeBundleRef(bundle, `workflows/${canonicalName}`);
+}
+/** Parse a workflow ref using the canonical `[bundle//]conceptId` grammar. */
+export function parseWorkflowRefInput(ref) {
+    const parsed = parseBundleRef(ref.trim());
+    if (parsed.fragment !== undefined) {
+        throw new UsageError(`Export fragment "#${parsed.fragment}" is not accepted in a workflow ref.`, "INVALID_FLAG_VALUE");
     }
-    if (asset.document) {
-        return compileWorkflowPlan(asset.document);
+    if (parsed.conceptId.startsWith("workflow:")) {
+        throw new UsageError(`Invalid workflow ref "${ref.trim()}". Use [bundle//]conceptId, such as workflows/release.`, "INVALID_FLAG_VALUE");
     }
-    // Unreachable for assets produced by loadWorkflowAsset; guards hand-built ones.
-    throw new UsageError(`Workflow asset ${asset.ref} carries neither a parsed document nor a program to compile.`);
+    return parsed;
+}
+/** Resolve input sugar to the workflow's canonical run identity. */
+export async function canonicalizeWorkflowRefInput(ref) {
+    return (await loadWorkflowAsset(ref)).ref;
 }
 /**
- * Resolve a `workflow:<name>` ref to a fully-projected {@link WorkflowAsset}.
- *
- * Prefers the parsed document cached in `index.db` (fast path) and falls back to
- * reading + parsing the source file from disk. Pure loading/parsing concern —
- * extracted from the run repository so run orchestration no longer owns asset
- * resolution.
+ * Resolve a workflow ref to a fully-projected {@link WorkflowAsset}. Prefers the
+ * parsed document cached in `index.db` (fast path) and falls back to reading +
+ * parsing the source file from disk.
  */
 export async function loadWorkflowAsset(ref) {
-    const parsed = parseAssetRef(ref);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${ref}".`);
-    }
+    const bundleRef = parseWorkflowRefInput(ref);
     const config = loadConfig();
     const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    const installations = deriveInstallations(allSources);
+    const searchSources = allSources.flatMap((source, index) => {
+        const bundleId = installations[index]?.id;
+        if (!bundleId || (bundleRef.bundle !== undefined && bundleRef.bundle !== bundleId))
+            return [];
+        return [{ source, bundleId }];
+    });
+    if (bundleRef.bundle && searchSources.length === 0) {
+        throw new UsageError(`Bundle "${bundleRef.bundle}" was not found among configured sources.`, "INVALID_FLAG_VALUE");
+    }
     let assetPath;
     let sourcePath;
-    for (const source of searchSources) {
+    let sourceBundleId;
+    let workflowName;
+    let workflowAdapterId;
+    let rejectedSource;
+    for (const candidateSource of searchSources) {
+        const { source, bundleId } = candidateSource;
         try {
-            assetPath = await resolveAssetPath(source.path, "workflow", parsed.name);
+            const adapterId = source.adapterId ?? detectAdapterId(source.path);
+            const candidateName = adapterId === "akm-workflow" ? bundleRef.conceptId : workflowNameFromConceptId(bundleRef.conceptId);
+            const ownedSource = source.adapterId ? source : { ...source, adapterId };
+            if (!candidateName) {
+                if (adapterOwnsConcept(source.path, adapterId, bundleRef.conceptId)) {
+                    rejectedSource ??= { source: ownedSource, bundleId };
+                    break;
+                }
+                continue;
+            }
+            const candidate = await resolveNativeWorkflowPath(source.path, adapterId, candidateName);
+            if (!ownsNativeWorkflowRuntime(ownedSource)) {
+                rejectedSource ??= { source: ownedSource, bundleId };
+                break;
+            }
+            assetPath = candidate;
             sourcePath = source.path;
+            sourceBundleId = bundleId;
+            workflowName = candidateName;
+            workflowAdapterId = adapterId;
             break;
         }
-        catch {
-            /* continue */
+        catch (error) {
+            if (error instanceof NotFoundError)
+                continue;
+            throw error;
         }
     }
     if (!assetPath) {
-        throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
-    }
-    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
-    // Canonicalize the stored ref: `workflow:foo.yaml` and `workflow:foo`
-    // resolve to the same file, so they MUST share one run identity. The raw
-    // `parsed.name` (with any extension) is what drives file resolution above;
-    // only the persisted/queried ref is collapsed (matches the index entry key,
-    // which is keyed by the extension-stripped canonical name).
-    const canonicalName = canonicalizeWorkflowName(parsed.name);
-    const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${canonicalName}`;
-    // Format detection by extension: `.yaml`/`.yml` is a YAML workflow program
-    // (redesign addendum, R1); everything else is the markdown document format.
-    if (isWorkflowProgramPath(assetPath)) {
-        const program = loadWorkflowProgramFromDisk(assetPath);
-        return projectProgramAsset(program, fullRef, assetPath, resolvedSourcePath);
-    }
-    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
+        if (rejectedSource) {
+            const sourceName = rejectedSource.bundleId;
+            const adapterId = rejectedSource.source.adapterId ?? "unassigned";
+            throw new UsageError(`Bundle "${sourceName}" uses adapter "${adapterId}", which does not support native workflow execution.`, "INVALID_FLAG_VALUE");
+        }
+        throw new NotFoundError(`Workflow not found for ref: ${ref}`);
+    }
+    const resolvedSourcePath = sourcePath;
+    // Canonicalize the stored ref: `workflows/foo.md` and `workflows/foo` resolve
+    // to the same file, so they MUST share one run identity.
+    const canonicalName = canonicalizeWorkflowName(workflowName);
+    const fullRef = workflowAdapterId === "akm-workflow"
+        ? makeBundleRef(sourceBundleId, canonicalName)
+        : canonicalWorkflowRunRef(sourceBundleId, canonicalName);
+    const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef, workflowAdapterId);
     const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
-    return projectAsset(document, fullRef, assetPath, resolvedSourcePath);
+    return projectAsset(document, fullRef, assetPath, resolvedSourcePath, workflowAdapterId, canonicalName);
+}
+function ownsNativeWorkflowRuntime(source) {
+    return source.adapterId === "akm" || source.adapterId === "akm-workflow";
+}
+function workflowNameFromConceptId(conceptId) {
+    const prefix = "workflows/";
+    return conceptId.startsWith(prefix) && conceptId.length > prefix.length ? conceptId.slice(prefix.length) : undefined;
+}
+function adapterOwnsConcept(sourcePath, adapterId, conceptId) {
+    const adapter = adapterForId(adapterId);
+    if (!adapter)
+        return false;
+    const normalized = conceptId.replaceAll("\\", "/");
+    if (!normalized ||
+        path.posix.isAbsolute(normalized) ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        path.posix.normalize(normalized) !== normalized) {
+        return false;
+    }
+    const extensions = [...adapter.extensions].sort((left, right) => right.length - left.length);
+    const extension = extensions.find((candidate) => normalized.toLowerCase().endsWith(candidate.toLowerCase()));
+    const extensionless = extension ? normalized.slice(0, -extension.length) : normalized;
+    const parent = path.join(sourcePath, path.posix.dirname(extensionless));
+    let realRoot;
+    let realParent;
+    try {
+        realRoot = fs.realpathSync(sourcePath);
+        realParent = fs.realpathSync(parent);
+    }
+    catch {
+        return false;
+    }
+    if (!isWithin(realParent, realRoot))
+        return false;
+    const basename = path.posix.basename(extensionless);
+    let entries;
+    try {
+        entries = fs.readdirSync(realParent, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const recognizedExtension = extensions.find((candidate) => entry.name.toLowerCase().endsWith(candidate.toLowerCase()) &&
+            entry.name.slice(0, -candidate.length) === basename);
+        if (!recognizedExtension)
+            continue;
+        const candidatePath = path.join(realParent, entry.name);
+        try {
+            const document = adapter.recognize({ id: adapterId, adapter: adapterId, root: realRoot, writable: false }, buildFileContext(realRoot, candidatePath));
+            if (document)
+                return true;
+        }
+        catch {
+            // A malformed matching file still belongs to the earlier adapter and cannot be bypassed for execution.
+            return true;
+        }
+    }
+    return false;
+}
+async function resolveNativeWorkflowPath(sourcePath, adapterId, name) {
+    if (adapterId !== "akm-workflow")
+        return resolveAssetPath(sourcePath, "workflow", name);
+    const canonicalName = canonicalizeWorkflowName(name);
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(sourcePath);
+    }
+    catch {
+        throw new NotFoundError(`Workflow bundle root not found: ${sourcePath}`);
+    }
+    const parent = path.join(sourcePath, path.dirname(canonicalName));
+    if (!isWithin(parent, realRoot)) {
+        throw new UsageError("Workflow ref resolves outside the bundle root.", "PATH_ESCAPE_VIOLATION");
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(parent, { withFileTypes: true });
+    }
+    catch {
+        throw new NotFoundError(`Workflow not found: ${name}`);
+    }
+    const basename = path.basename(canonicalName);
+    for (const extension of WORKFLOW_EXTENSIONS) {
+        const matches = entries.filter((entry) => {
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                return false;
+            const entryExtension = path.extname(entry.name);
+            return entryExtension.toLowerCase() === extension && entry.name.slice(0, -entryExtension.length) === basename;
+        });
+        if (matches.length > 1) {
+            throw new UsageError(`Workflow "${canonicalName}" has multiple ${extension} files that differ only by extension case.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        const match = matches[0];
+        if (!match)
+            continue;
+        const candidate = path.join(parent, match.name);
+        let realTarget;
+        try {
+            if (!fs.statSync(candidate).isFile())
+                continue;
+            realTarget = fs.realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (!isWithin(realTarget, realRoot)) {
+            throw new UsageError("Workflow ref resolves outside the bundle root.", "PATH_ESCAPE_VIOLATION");
+        }
+        return realTarget;
+    }
+    throw new NotFoundError(`Workflow not found: ${name}`);
 }
 /**
  * Resolve the `entries.id` for an indexed workflow, or null when the index
  * database does not yet exist or has no matching entry.
  */
-export function resolveWorkflowEntryId(sourcePath, ref) {
+export function resolveWorkflowEntryId(sourcePath, ref, adapterId) {
     if (!fs.existsSync(getDbPath()))
         return null;
-    const parsed = parseAssetRef(ref);
-    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    const entryKey = workflowEntryKey(sourcePath, ref, adapterId);
     return withIndexDb((db) => {
         const row = db
             .prepare(`SELECT id
@@ -106,14 +249,6 @@ export function resolveWorkflowEntryId(sourcePath, ref) {
         return row?.id ?? null;
     });
 }
-function loadWorkflowProgramFromDisk(assetPath) {
-    const content = fs.readFileSync(assetPath, "utf8");
-    const result = parseWorkflowProgram(content, { path: assetPath });
-    if (!result.ok) {
-        throw new UsageError(formatWorkflowErrors(assetPath, result.errors));
-    }
-    return result.program;
-}
 function loadWorkflowDocumentFromDisk(assetPath) {
     const content = fs.readFileSync(assetPath, "utf8");
     const result = parseWorkflow(content, { path: assetPath });
@@ -122,20 +257,19 @@ function loadWorkflowDocumentFromDisk(assetPath) {
     }
     return result.document;
 }
-function readWorkflowDocumentFromIndex(sourcePath, ref) {
+function readWorkflowDocumentFromIndex(sourcePath, ref, adapterId) {
     if (!fs.existsSync(getDbPath()))
         return null;
-    const parsed = parseAssetRef(ref);
-    const entryKey = `${sourcePath}:${parsed.type}:${parsed.name}`;
+    const entryKey = workflowEntryKey(sourcePath, ref, adapterId);
     return withIndexDb((db) => {
         const row = db
-            .prepare(`SELECT wd.document_json AS document_json
+            .prepare(`SELECT wd.document_json AS document_json, wd.schema_version AS schema_version
            FROM workflow_documents wd
            JOIN entries e ON e.id = wd.entry_id
           WHERE e.entry_type = 'workflow' AND e.entry_key = ?
           LIMIT 1`)
             .get(entryKey);
-        if (!row)
+        if (!row || row.schema_version !== WORKFLOW_SCHEMA_VERSION)
             return null;
         try {
             return JSON.parse(row.document_json);
@@ -145,44 +279,48 @@ function readWorkflowDocumentFromIndex(sourcePath, ref) {
         }
     });
 }
-function projectAsset(doc, ref, assetPath, sourcePath) {
+function workflowEntryKey(sourcePath, ref, adapterId) {
+    const bundleRef = parseBundleRef(ref);
+    if ((adapterId ?? detectAdapterId(sourcePath)) === "akm-workflow") {
+        return `${sourcePath}:concept:${bundleRef.conceptId}`;
+    }
+    const name = workflowNameFromConceptId(bundleRef.conceptId);
+    if (!name)
+        throw new UsageError(`Expected a workflow ref, got "${ref}".`);
+    return `${sourcePath}:workflow:${name}`;
+}
+function projectAsset(doc, ref, assetPath, sourcePath, adapterId, canonicalName) {
+    const title = canonicalName.split("/").pop() || canonicalName;
     return {
         ref,
         path: assetPath,
         sourcePath,
-        title: doc.title,
-        ...(doc.parameters
+        adapterId,
+        title,
+        ...(doc.params
             ? {
-                parameters: doc.parameters.map((p) => ({
-                    name: p.name,
-                    ...(p.description ? { description: p.description } : {}),
-                })),
+                parameters: Object.entries(doc.params).map(([name, schema]) => {
+                    const description = schema.description;
+                    return { name, ...(typeof description === "string" && description ? { description } : {}) };
+                }),
             }
             : {}),
         steps: doc.steps.map((s) => ({
             id: s.id,
-            title: s.title,
-            instructions: s.instructions.text,
-            ...(s.completionCriteria ? { completionCriteria: s.completionCriteria.map((c) => c.text) } : {}),
+            title: s.id,
+            instructions: s.instructions?.text ?? stepFallbackInstructions(s),
+            ...(s.gateRubric?.text.trim() ? { completionCriteria: [s.gateRubric.text] } : {}),
             sequenceIndex: s.sequenceIndex,
         })),
         document: doc,
     };
 }
-/**
- * Project a parsed YAML program into the run-repository asset shape. Step
- * instructions carry the RAW `${{ … }}` templates — resolution happens in
- * the engine against the frozen plan, never here.
- */
-function projectProgramAsset(program, ref, assetPath, sourcePath) {
-    const parameters = projectProgramParameters(program);
-    return {
-        ref,
-        path: assetPath,
-        sourcePath,
-        title: program.name,
-        ...(parameters ? { parameters } : {}),
-        steps: projectProgramStepDefinitions(program),
-        program,
-    };
+/** A route-only step with no body section still needs a non-empty spine instructions string. */
+function stepFallbackInstructions(step) {
+    if (!step.route)
+        return "";
+    const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
+    if (step.route.defaultStepId !== undefined)
+        branches.push(`default -> ${step.route.defaultStepId}`);
+    return `Route on ${step.route.input}: ${branches.join(", ")}.`;
 }

package/dist/workflows/schema.js

@@ -1,14 +1,4 @@
 // 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/.
-/**
- * Validated JSON shape for a workflow asset.
- *
- * `parseWorkflow` (parser.ts) converts a workflow markdown file into a
- * `WorkflowDocument` plus a list of `WorkflowError`s. The document is the
- * single source of truth consumed by the renderer, the indexer (cached
- * into `workflow_documents` in `index.db`), and the run engine. Source
- * markdown is referenced by `SourceRef` line spans so editors and agents
- * can rewrite content in place without a full re-parse.
- */
-export const WORKFLOW_SCHEMA_VERSION = 1;
+export const WORKFLOW_SCHEMA_VERSION = 2;

package/dist/workflows/validate-summary.js

@@ -11,16 +11,13 @@
  *
  * The LLM call is injected (`judge`) so the gate is unit-testable without a
  * live endpoint, and the whole gate is fail-open: when no criteria exist or no
- * judge is available the step completes as before. See
- * docs/technical/workflow-agent-checkin-adr.md.
+ * judge is available the step completes as before (per the workflow-agent
+ * check-in ADR).
  *
  * @module workflows/validate-summary
  */
 import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
-/** Feedback surfaced when a REQUIRED gate's judge could not be evaluated. */
-const REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK = "The required completion gate could not be judged — the LLM threw, was unreachable, or returned an " +
-    "unparseable verdict. A required gate must be judged; refusing to pass it. Restore the judge and re-evaluate.";
 const JUDGE_SYSTEM = validateSummaryJudgePrompt;
 function buildUserPrompt(input) {
     const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
@@ -39,22 +36,14 @@ function buildUserPrompt(input) {
 /**
  * Run the summary-validation gate.
  *
- * Fail-open contract (NON-required gates):
+ * Fail-open contract:
  *  - no criteria → `{ complete: true, skipped: true }`
  *  - no judge → `{ complete: true, skipped: true }`
  *  - judge throws / returns unparseable → `{ complete: true, skipped: true }`
  *
- * REQUIRED gates (`opts.required`) do NOT fail open on an un-evaluable judge
- * (Codex round-3 finding A): a judge that throws / is unreachable, or returns an
- * unparseable / malformed verdict, yields `{ complete: false, errored: true }`
- * so the caller BLOCKS the step rather than silently passing an unjudged gate.
- * (A required gate with NO judge at all is blocked upstream in
- * `finalizeExecutedStep` before this gate runs, so that branch stays fail-open.)
- *
  * Only a well-formed `complete: false` verdict blocks completion.
  */
-export async function validateStepSummary(input, judge, opts) {
-    const required = opts?.required === true;
+export async function validateStepSummary(input, judge) {
     const criteria = input.completionCriteria.filter((c) => c.trim().length > 0);
     if (criteria.length === 0) {
         return { complete: true, missing: [], skipped: true };
@@ -67,21 +56,10 @@ export async function validateStepSummary(input, judge, opts) {
         raw = await judge({ system: JUDGE_SYSTEM, user: buildUserPrompt({ ...input, completionCriteria: criteria }) });
     }
     catch {
-        // LLM unreachable / errored. A REQUIRED gate must be judged — block rather
-        // than pass an unjudged gate; a non-required gate fails open so offline use
-        // keeps working.
-        if (required) {
-            return { complete: false, missing: [], errored: true, feedback: REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK };
-        }
         return { complete: true, missing: [], skipped: true };
     }
     const parsed = parseJsonResponse(raw);
     if (!parsed || typeof parsed.complete !== "boolean") {
-        // An unparseable / malformed verdict is a judge that did not actually judge:
-        // a required gate blocks; a non-required gate fails open.
-        if (required) {
-            return { complete: false, missing: [], errored: true, feedback: REQUIRED_GATE_JUDGE_UNAVAILABLE_FEEDBACK };
-        }
         return { complete: true, missing: [], skipped: true };
     }
     if (parsed.complete) {

package/dist/workflows/validator.js

@@ -1,44 +1,66 @@
 // 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/.
-const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use"]);
+/**
+ * Cross-cutting semantic checks over an assembled `WorkflowDocument` draft
+ * that need the whole document (not just one frontmatter key) at once.
+ *
+ * Per-key structural checks (unknown keys, id/param-name patterns, timeout
+ * format, retry taxonomy, route target ordering, duplicate ids, gate/body
+ * binding) all live in `parser.ts`, where line-anchored errors are cheapest to
+ * produce. The workflow-only closed frontmatter allowlist that used to live
+ * here (`ALLOWED_FRONTMATTER_KEYS`/`checkFrontmatterKeys`) is GONE —
+ * `schemas/akm-workflow.json` (`additionalProperties: false` over the shared
+ * asset envelope ∪ the workflow keys) is the closed-key authority now; this
+ * module only runs checks the schema cannot express (canonical xref shape,
+ * resource limits).
+ */
+import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
+import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
-    checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
-    checkStepIdFormat(draft, errors);
-    checkDuplicateStepIds(draft, errors);
+    checkXrefs(frontmatterData.xrefs, frontmatterEndLine, errors);
+    checkResourceLimits(draft, errors);
 }
-function checkFrontmatterKeys(data, fmEndLine, errors) {
-    for (const key of Object.keys(data)) {
-        if (ALLOWED_FRONTMATTER_KEYS.has(key))
-            continue;
-        errors.push({
-            line: fmEndLine,
-            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use.`,
-        });
+function checkXrefs(value, line, errors) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        return; // shape already flagged by parser.ts's checkXrefs
+    for (const ref of value) {
+        try {
+            if (typeof ref !== "string")
+                throw new Error("non-canonical ref");
+            const parsed = parseBundleRef(ref);
+            if (parsed.conceptId.includes(":") || ref !== bundleRefToString(parsed))
+                throw new Error("non-canonical ref");
+        }
+        catch {
+            errors.push({
+                line,
+                message: `Workflow frontmatter "xrefs" contains an invalid or non-canonical ref: ${String(ref)}.`,
+            });
+        }
     }
 }
-function checkStepIdFormat(draft, errors) {
-    for (const step of draft.steps) {
-        if (STEP_ID_REGEX.test(step.id))
-            continue;
-        errors.push({
-            line: step.source.start,
-            message: `Step ID "${step.id}" is invalid. Use letters, numbers, ".", "_" or "-" (e.g. "deploy-job").`,
-        });
+function checkResourceLimits(draft, errors) {
+    if (draft.steps.length > WORKFLOW_MAX_STEPS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
+    }
+    if (Object.keys(draft.params ?? {}).length > WORKFLOW_MAX_PARAMS) {
+        errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_PARAMS} parameters.` });
     }
-}
-function checkDuplicateStepIds(draft, errors) {
-    const firstSeenLine = new Map();
     for (const step of draft.steps) {
-        const previous = firstSeenLine.get(step.id);
-        if (previous !== undefined) {
+        if (step.instructions && utf8Bytes(step.instructions.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+            errors.push({
+                line: step.instructions.source.start,
+                message: `Step "${step.id}" instructions exceed the 256 KiB resource limit.`,
+            });
+        }
+        if (step.gateRubric && utf8Bytes(step.gateRubric.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
             errors.push({
-                line: step.source.start,
-                message: `Step ID "${step.id}" is already used on line ${previous}. Step IDs must be unique within a workflow.`,
+                line: step.gateRubric.source.start,
+                message: `Step "${step.id}" gate rubric exceeds the 256 KiB resource limit.`,
             });
-            continue;
         }
-        firstSeenLine.set(step.id, step.source.start);
     }
 }