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

package/dist/commands/workflow-cli.js

@@ -12,6 +12,7 @@
  * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
  */
 import { defineCommand } from "citty";
+import { getStringArg } from "../cli/parse-args.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { parseAssetRef } from "../core/asset/asset-ref.js";
@@ -22,8 +23,9 @@ import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { hasBooleanFlag } from "../output/context.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
+import { createWorkflowAsset, formatWorkflowErrors, getWorkflowProgramTemplate, getWorkflowTemplate, validateWorkflowProgramSource, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
 import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
+import { isWorkflowProgramPath } from "../workflows/program/project.js";
 import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStartCommand = defineJsonCommand({
     meta: {
@@ -140,9 +142,16 @@ const workflowStatusCommand = defineJsonCommand({
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+        units: {
+            type: "boolean",
+            description: "Also list per-unit rows from the run journal (unit id, status, failure_reason, and any result/error " +
+                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected (#22).",
+            default: false,
+        },
     },
     async run({ args }) {
         const target = args.target;
+        const includeUnits = args.units === true;
         // Check if target looks like a workflow ref
         const parsed = (() => {
             try {
@@ -161,11 +170,11 @@ const workflowStatusCommand = defineJsonCommand({
             const mostRecent = runs[0];
             if (!mostRecent)
                 throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id);
+            const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
             output("workflow-status", result);
         }
         else {
-            const result = await getWorkflowStatus(target);
+            const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
         }
     },
@@ -187,19 +196,22 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow markdown document in the working stash",
+        description: "Create a workflow in the working stash (markdown document by default; a .yaml/.yml name writes a YAML program)",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory)",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory). A .yaml/.yml suffix creates a YAML program.",
             required: true,
         },
         path: {
             type: "string",
             description: "Relative subdirectory under workflows/ to place the workflow in (e.g. 'release'). The filename comes from the name.",
         },
-        from: { type: "string", description: "Import and validate markdown from an existing file" },
+        from: {
+            type: "string",
+            description: "Import and validate content from an existing file (parsed per the destination extension)",
+        },
         force: {
             type: "boolean",
             description: "Overwrite an existing workflow (requires --from or --reset)",
@@ -237,26 +249,54 @@ const workflowCreateCommand = defineJsonCommand({
 const workflowTemplateCommand = defineCommand({
     meta: {
         name: "template",
-        description: "Print a valid workflow markdown template",
+        description: "Print a valid workflow template (markdown by default, --yaml for a YAML program)",
+    },
+    args: {
+        yaml: {
+            type: "boolean",
+            description: "Print a minimal valid YAML workflow program instead of the markdown template",
+            default: false,
+        },
     },
-    run() {
-        process.stdout.write(getWorkflowTemplate());
+    run({ args }) {
+        process.stdout.write(args.yaml ? getWorkflowProgramTemplate() : getWorkflowTemplate());
     },
 });
 const workflowValidateCommand = defineJsonCommand({
     meta: {
         name: "validate",
-        description: "Validate a workflow markdown file or ref and print any errors",
+        description: "Validate a workflow file or ref (markdown document or YAML program) and print any errors",
     },
     args: {
         target: {
             type: "positional",
-            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md",
+            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md/.yaml",
             required: true,
         },
     },
     async run({ args }) {
         const filePath = await resolveWorkflowFilePath(args.target);
+        // YAML programs (redesign addendum, R1) validate through the program
+        // parser AND compiler so expression/reference errors surface at lint
+        // time; both error lists carry line numbers. Markdown is unchanged.
+        if (isWorkflowProgramPath(filePath)) {
+            const { result } = validateWorkflowProgramSource(filePath);
+            if (!result.ok) {
+                throw new UsageError(formatWorkflowErrors(filePath, result.errors));
+            }
+            // Non-fatal WARNINGS ride the envelope additively — `ok` stays true. The
+            // text formatter renders them clearly marked for humans; the JSON key is
+            // the machine channel. Empty array when the program is fully typed/declared.
+            output("workflow-validate", {
+                ok: true,
+                path: filePath,
+                format: "program",
+                title: result.program.name,
+                stepCount: result.program.steps.length,
+                warnings: result.warnings.map((w) => ({ line: w.line, message: w.message })),
+            });
+            return;
+        }
         const { parse } = validateWorkflowSource(filePath);
         if (parse.ok) {
             output("workflow-validate", {
@@ -271,7 +311,15 @@ const workflowValidateCommand = defineJsonCommand({
     },
 });
 async function resolveWorkflowFilePath(target) {
-    if (!target.startsWith("workflow:"))
+    // A bare (`workflow:<name>`) OR origin-qualified (`<origin>//workflow:<name>`)
+    // ref resolves through the source search, exactly like `workflow start` /
+    // `status` / `next`. Anything else is treated as a filesystem path. Detecting
+    // the origin-qualified form here (not just the bare prefix) keeps `validate`'s
+    // ref contract in lockstep with the rest of the workflow command family — an
+    // `extra//workflow:foo` ref validates the file that `extra//workflow:foo`
+    // starts, rather than being mistaken for a relative path that does not exist.
+    const looksLikeWorkflowRef = target.startsWith("workflow:") || target.includes("//workflow:");
+    if (!looksLikeWorkflowRef)
         return target;
     const parsed = parseAssetRef(target);
     if (parsed.type !== "workflow") {
@@ -290,6 +338,218 @@ async function resolveWorkflowFilePath(target) {
     }
     throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
 }
+const workflowRunCommand = defineJsonCommand({
+    meta: {
+        name: "run",
+        description: "EXPERIMENTAL: execute a workflow's steps with the native engine — akm dispatches each step's units " +
+            "(fan-out, schema output) to the configured runner and advances the run through the normal completion gates",
+    },
+    args: {
+        target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
+        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+        "max-steps": { type: "string", description: "Stop after executing this many steps" },
+        "require-gates": {
+            type: "boolean",
+            description: "Treat every criteria-bearing completion gate as required: if no LLM judge is available, BLOCK the step " +
+                "(for a human to resolve via `akm workflow resume`) instead of failing open. A per-step `gate.required: true` " +
+                "in the workflow does the same on every surface; this is the run-wide override (#18).",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
+        const rawMaxSteps = getStringArg(args, "max-steps");
+        let maxSteps;
+        if (rawMaxSteps !== undefined) {
+            maxSteps = Number.parseInt(rawMaxSteps, 10);
+            if (!/^\d+$/.test(rawMaxSteps) || maxSteps <= 0) {
+                throw new UsageError(`--max-steps must be a positive integer, got "${rawMaxSteps}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        const result = await runWorkflowSteps({
+            target: args.target,
+            ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
+            ...(maxSteps !== undefined ? { maxSteps } : {}),
+            ...(args["require-gates"] === true ? { requireGates: true } : {}),
+        });
+        output("workflow-run", result);
+    },
+});
+const workflowBriefCommand = defineJsonCommand({
+    meta: {
+        name: "brief",
+        description: "EXPERIMENTAL: describe a run's active step as an executable work-list for ANY agent session (the " +
+            "harness-neutral driver protocol) — read-only, takes no engine lease, mutates nothing; prints per-unit " +
+            "instructions, output schema, env binding names, and the exact `akm workflow report` command lines",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow run id (or a workflow ref with an active run)",
+            required: true,
+        },
+    },
+    async run({ args }) {
+        const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
+        const result = await buildWorkflowBrief(args.target);
+        output("workflow-brief", result);
+    },
+});
+const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
+const workflowReportCommand = defineJsonCommand({
+    meta: {
+        name: "report",
+        description: "EXPERIMENTAL: report a unit's result back into a run (the mutating half of the harness-neutral driver " +
+            "protocol) — ingested through the SAME shared step semantics the engine uses. --status running claims/" +
+            "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
+            "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
+            "parked on a route-only/empty step. Refused while a live engine lease exists",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow run id (or a workflow ref with an active run)",
+            required: true,
+        },
+        unit: {
+            type: "string",
+            description: "Content-derived unit id from `akm workflow brief` (copy it verbatim). Omit with --settle.",
+        },
+        settle: {
+            type: "boolean",
+            description: "Advance/finalize a run whose active step has NO unit left to report: a non-dispatching step (params-based route, empty fan-out, all-unresolvable) OR a fully-terminal step still needing finalization (every unit ran but the gate never judged — e.g. after resuming a required-gate block). Runs the deterministic completion path. Mutually exclusive with --unit; refused when the step still has genuinely pending units",
+            default: false,
+        },
+        "expect-step": {
+            type: "string",
+            description: "Guard: the step id you briefed against. Refuses the report if the run's active step has since moved (from the `brief` report/settle command line)",
+        },
+        status: { type: "string", description: `Unit status: ${WORKFLOW_REPORT_STATES.join(", ")}` },
+        result: { type: "string", description: "Result payload (JSON for a schema unit, else text). completed only." },
+        "result-file": { type: "string", description: "Read the result payload from this file instead of --result/stdin" },
+        tokens: { type: "string", description: "Tokens spent on this unit (counts against a declared budget)" },
+        "session-id": { type: "string", description: "Harness-native session id revealed while executing the unit" },
+        "failure-reason": { type: "string", description: "Structured failure vocabulary for a --status failed report" },
+        note: { type: "string", description: "Short progress note for a --status running heartbeat (not persisted)" },
+        rerun: {
+            type: "boolean",
+            description: "Re-run an already-FAILED unit: record a NEW attempt (re-applies budget) instead of refusing a differing re-report",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        // --settle: the unit-less verb that advances a run parked on a
+        // non-dispatching step. Mutually exclusive with the per-unit report flags.
+        if (args.settle === true) {
+            if (getStringArg(args, "unit") !== undefined || getStringArg(args, "status") !== undefined) {
+                throw new UsageError("--settle advances a route-only/empty step and takes no --unit or --status. Drop them, or report a " +
+                    "specific unit with `--unit <id> --status <state>` instead.", "INVALID_FLAG_VALUE");
+            }
+            const { settleWorkflowSpine } = await import("../workflows/exec/report.js");
+            const result = await settleWorkflowSpine({
+                target: args.target,
+                ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
+            });
+            output("workflow-report", result);
+            return;
+        }
+        const status = args.status;
+        if (!status) {
+            throw new UsageError("--status is required (completed | failed | running), or pass --settle to advance a non-dispatching step.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        if (!WORKFLOW_REPORT_STATES.includes(status)) {
+            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
+        }
+        const unitId = getStringArg(args, "unit");
+        if (!unitId) {
+            throw new UsageError("--unit is required (the content-derived unit id from `akm workflow brief`), or pass --settle for a route-only/empty step.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        let tokens;
+        const rawTokens = getStringArg(args, "tokens");
+        if (rawTokens !== undefined) {
+            tokens = Number.parseInt(rawTokens, 10);
+            if (!/^\d+$/.test(rawTokens)) {
+                throw new UsageError(`--tokens must be a non-negative integer, got "${rawTokens}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        // Result payload precedence: --result, then --result-file, then stdin
+        // (completed/failed only; a running heartbeat carries no result).
+        let resultRaw;
+        if (status !== "running") {
+            const resultFile = getStringArg(args, "result-file");
+            if (args.result !== undefined && resultFile !== undefined) {
+                throw new UsageError("Pass at most one of --result or --result-file.", "INVALID_FLAG_VALUE");
+            }
+            if (args.result !== undefined) {
+                resultRaw = String(args.result);
+            }
+            else if (resultFile !== undefined) {
+                const fs = await import("node:fs");
+                resultRaw = fs.readFileSync(resultFile, "utf8");
+            }
+            else if (!process.stdin.isTTY) {
+                resultRaw = await readStdin();
+            }
+        }
+        const { reportWorkflowUnit } = await import("../workflows/exec/report.js");
+        const result = await reportWorkflowUnit({
+            target: args.target,
+            unitId,
+            status: status,
+            ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
+            ...(resultRaw !== undefined ? { resultRaw } : {}),
+            ...(tokens !== undefined ? { tokens } : {}),
+            ...(args.rerun === true ? { rerun: true } : {}),
+            ...(getStringArg(args, "session-id") !== undefined ? { sessionId: getStringArg(args, "session-id") } : {}),
+            ...(getStringArg(args, "failure-reason") !== undefined
+                ? { failureReason: getStringArg(args, "failure-reason") }
+                : {}),
+            ...(getStringArg(args, "note") !== undefined ? { note: getStringArg(args, "note") } : {}),
+        });
+        output("workflow-report", result);
+    },
+});
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const workflowWatchCommand = defineJsonCommand({
+    meta: {
+        name: "watch",
+        description: "Print a run's workflow_* events (state.db events table) as NDJSON and exit; --stream polls in the " +
+            "foreground until the run reaches a terminal status (no daemon)",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+        stream: {
+            type: "boolean",
+            description: "Keep polling for new events until the run leaves 'active' (completed/failed/blocked)",
+            default: false,
+        },
+        "interval-ms": { type: "string", description: "Poll interval in milliseconds for --stream (default: 1000)" },
+    },
+    async run({ args }) {
+        const rawInterval = getStringArg(args, "interval-ms");
+        let intervalMs;
+        if (rawInterval !== undefined) {
+            intervalMs = Number.parseInt(rawInterval, 10);
+            if (!/^\d+$/.test(rawInterval) || intervalMs <= 0) {
+                throw new UsageError(`--interval-ms must be a positive integer, got "${rawInterval}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        const { watchWorkflowRun } = await import("../workflows/exec/watch.js");
+        const result = await watchWorkflowRun({
+            runId: args.runId,
+            stream: args.stream === true,
+            ...(intervalMs !== undefined ? { intervalMs } : {}),
+        });
+        // The event lines above are raw NDJSON on stdout; this trailing envelope
+        // is the machine-readable command result (counts + terminal status).
+        output("workflow-watch", { ok: true, ...result });
+    },
+});
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -332,6 +592,10 @@ export const workflowCommand = defineCommand({
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
         validate: workflowValidateCommand,
+        run: workflowRunCommand,
+        brief: workflowBriefCommand,
+        report: workflowReportCommand,
+        watch: workflowWatchCommand,
     },
     run({ args }) {
         return runWithJsonErrors(async () => {

package/dist/core/asset/asset-spec.js

@@ -1,6 +1,7 @@
 // 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/.
+import fs from "node:fs";
 import path from "node:path";
 import { buildWorkflowAction } from "../../output/renderers.js";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry.js";
@@ -8,6 +9,59 @@ function toPosix(input) {
     return input.replace(/\\/g, "/");
 }
 const buildTaskAction = (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`;
+/**
+ * Recognized workflow asset extensions, in resolution-priority order.
+ * `.md` (classic linear markdown workflows — the stable contract) stays
+ * FIRST for back-compat; `.yaml`/`.yml` hold YAML workflow *programs*
+ * (redesign addendum, R1). `workflow:<name>` refs resolve against this list.
+ */
+export const WORKFLOW_EXTENSIONS = [".md", ".yaml", ".yml"];
+/**
+ * Strip a recognized workflow extension (`.md`/`.yaml`/`.yml`) from a workflow
+ * asset *name* so `foo`, `foo.yaml`, `foo.yml`, and `foo.md` collapse to one
+ * canonical identity — the same collapse `workflowSpec.toCanonicalName`
+ * performs on a resolved file path. Callers that turn a `workflow:<name>` ref
+ * into run identity (the active-run guard, list/status filters) MUST route the
+ * name through this so an aliased spelling (`workflow:foo.yaml`) and the
+ * canonical `workflow:foo` cannot start or hide parallel runs of the same
+ * workflow. Names without a recognized workflow extension pass through
+ * unchanged.
+ */
+export function canonicalizeWorkflowName(name) {
+    const lower = name.toLowerCase();
+    for (const ext of WORKFLOW_EXTENSIONS) {
+        if (lower.endsWith(ext))
+            return name.slice(0, -ext.length);
+    }
+    return name;
+}
+const workflowSpec = {
+    isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (rel.toLowerCase().endsWith(ext))
+                return rel.slice(0, -ext.length);
+        }
+        return rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Explicit extension wins (accepts refs like "release/ship.yaml").
+        const lower = name.toLowerCase();
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (lower.endsWith(ext))
+                return path.join(typeRoot, name);
+        }
+        // Probe in priority order — `.md` first for back-compat — and fall back
+        // to the markdown path so error messages keep naming the canonical file.
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            const candidate = path.join(typeRoot, `${name}${ext}`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(typeRoot, `${name}.md`);
+    },
+};
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -62,7 +116,10 @@ const ASSET_SPECS_INTERNAL = {
     knowledge: { stashDir: "knowledge", ...markdownSpec },
     workflow: {
         stashDir: "workflows",
-        ...markdownSpec,
+        ...workflowSpec,
+        // Type-level renderer for markdown workflows; YAML programs are claimed by
+        // the dedicated `workflowProgramMatcher`, which names the
+        // "workflow-program-yaml" renderer directly on its MatchResult.
         rendererName: "workflow-md",
         actionBuilder: (ref) => buildWorkflowAction(ref),
     },

package/dist/core/config/config-schema.js

@@ -832,6 +832,26 @@ export const IndexConfigSchema = z.preprocess((raw, ctx) => {
     stalenessDetection: StalenessDetectionSchema.optional(),
 })
     .catchall(IndexPassConfigSchema));
+// ── Workflow engine ─────────────────────────────────────────────────────────
+/**
+ * Workflow-engine settings (`workflow`).
+ *
+ * `maxConcurrency` is the engine-wide ceiling on concurrent units for native
+ * fan-out (`akm workflow run`). It replaces the hard-coded `min(16, cores−2)`
+ * cap (which matched Claude Code) with a user knob:
+ *   - UNSET  → the CPU-derived default `min(16, max(1, cores−2))`.
+ *   - SET    → the explicit positive integer, CLAMPED at read time to
+ *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]` (64). Values above the ceiling
+ *     are clamped, not rejected, so a config shared across machines with wildly
+ *     different core counts never hard-fails validation.
+ * The R3 brief/report driver surface does NOT consult this — drivers own their
+ * own parallelism (the engine only caps native dispatch).
+ */
+export const WorkflowConfigSchema = z
+    .object({
+    maxConcurrency: positiveInt.optional(),
+})
+    .passthrough();
 // ── Setup-derived recommendations ──────────────────────────────────────────
 /**
  * Cron-style schedule hints derived by `akm setup --reset-recommended`.
@@ -895,6 +915,7 @@ export const AkmConfigShape = {
     feedback: FeedbackConfigSchema.optional(),
     archiveRetentionDays: nonNegativeNumber.optional(),
     improve: ImproveConfigSchema.optional(),
+    workflow: WorkflowConfigSchema.optional(),
     setup: SetupConfigSchema.optional(),
 };
 export const AkmConfigBaseSchema = z.object(AkmConfigShape).passthrough();

package/dist/core/json-schema.js

@@ -0,0 +1,142 @@
+// 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/.
+/**
+ * Structural JSON-Schema-subset validator (orchestration plan P1).
+ *
+ * The workflow engine's structured-output normalization needs to validate
+ * unit results against the author-declared unit `output` schema on any harness —
+ * including ones with no native schema support. Pulling in a full
+ * draft-2020-12 validator is deliberately avoided (dependency surface); this
+ * module implements the bounded subset that covers the schemas workflow
+ * authors actually write:
+ *
+ *   Supported: `type` (string | string[] — string, number, integer, boolean,
+ *   object, array, null), `properties`, `required`, `items`,
+ *   `additionalProperties: false`, `enum` (primitives), `minItems`,
+ *   `maxItems`, `minLength`, `maxLength`, `minimum`, `maximum`.
+ *
+ *   Ignored (permissive): `$ref`, `allOf`/`anyOf`/`oneOf`/`not`, `pattern`,
+ *   `format`, and every other keyword. Unknown keywords never throw — a
+ *   schema using them simply constrains less. Callers needing full JSON
+ *   Schema semantics should validate downstream.
+ *
+ * Returns a flat list of human-readable error strings (empty = valid), each
+ * prefixed with a JSON-pointer-ish path — the shape `runStructured`'s
+ * corrective-feedback builder wants.
+ */
+export function validateJsonSchemaSubset(value, schema) {
+    const errors = [];
+    validateNode(value, schema, "$", errors);
+    return errors;
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "boolean":
+            return "boolean";
+        case "number":
+            return Number.isInteger(value) ? "integer" : "number";
+        default:
+            return "object";
+    }
+}
+function matchesType(actual, expected) {
+    if (expected === actual)
+        return true;
+    // JSON Schema: every integer is also a number.
+    return expected === "number" && actual === "integer";
+}
+function validateNode(value, schema, path, errors) {
+    const actual = typeOf(value);
+    const declared = schema.type;
+    if (typeof declared === "string" || Array.isArray(declared)) {
+        const expected = (Array.isArray(declared) ? declared : [declared]).filter((t) => typeof t === "string");
+        if (expected.length > 0 && !expected.some((t) => matchesType(actual, t))) {
+            errors.push(`${path}: expected type ${expected.join(" | ")}, got ${actual}`);
+            return; // type mismatch makes the remaining constraints meaningless
+        }
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        const allowed = schema.enum;
+        if (!allowed.some((candidate) => candidate === value)) {
+            errors.push(`${path}: value ${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`);
+            return;
+        }
+    }
+    if (actual === "string" && typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+        }
+        if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+            errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+        }
+        return;
+    }
+    if ((actual === "number" || actual === "integer") && typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            errors.push(`${path}: ${value} is above maximum ${schema.maximum}`);
+        }
+        return;
+    }
+    if (actual === "array" && Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            errors.push(`${path}: array has fewer than minItems ${schema.minItems}`);
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            errors.push(`${path}: array has more than maxItems ${schema.maxItems}`);
+        }
+        const items = schema.items;
+        if (items && typeof items === "object" && !Array.isArray(items)) {
+            value.forEach((element, index) => {
+                validateNode(element, items, `${path}[${index}]`, errors);
+            });
+        }
+        return;
+    }
+    if (actual === "object" && typeof value === "object" && value !== null) {
+        const record = value;
+        const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)
+            ? schema.properties
+            : undefined;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                // `Object.hasOwn`, not `key in record`: a required key satisfied only by
+                // an inherited prototype member (e.g. "toString", "constructor") is NOT
+                // present on the value itself, so `{}` must fail `required: ["toString"]`.
+                if (typeof key === "string" && !Object.hasOwn(record, key)) {
+                    errors.push(`${path}: missing required property "${key}"`);
+                }
+            }
+        }
+        if (properties) {
+            for (const [key, propSchema] of Object.entries(properties)) {
+                if (!Object.hasOwn(record, key))
+                    continue;
+                if (propSchema && typeof propSchema === "object" && !Array.isArray(propSchema)) {
+                    validateNode(record[key], propSchema, `${path}.${key}`, errors);
+                }
+            }
+        }
+        // `additionalProperties: false` closes the object to exactly its declared
+        // `properties`. This MUST run even when no `properties` object is present:
+        // `{ type: "object", additionalProperties: false }` admits only `{}`. Use
+        // `Object.hasOwn` so an inherited key name (e.g. "toString") on the empty
+        // property set is not mistaken for a declared property.
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(record)) {
+                if (!properties || !Object.hasOwn(properties, key)) {
+                    errors.push(`${path}: unexpected property "${key}" (additionalProperties: false)`);
+                }
+            }
+        }
+    }
+}

package/dist/indexer/db/db.js

@@ -46,7 +46,8 @@ export function openIndexDatabase(dbPath, options) {
  */
 function resolveConfiguredEmbeddingDim() {
     try {
-        const { loadConfig } = require("../../core/config/config");
+        const esmRequire = createRequire(import.meta.url);
+        const { loadConfig } = esmRequire("../../core/config/config");
         const dim = loadConfig().embedding?.dimension;
         if (typeof dim === "number" && Number.isInteger(dim) && dim > 0 && dim <= 4096) {
             return dim;