@intentius/chant 0.89.0 → 0.91.0

package/src/cli/mcp/workspace-tools.ts

@@ -0,0 +1,449 @@
+/**
+ * #2707 — the workspace tools of `chant serve mcp`: the read contract and the
+ * record writes, for a harness that speaks MCP and has no shell.
+ *
+ * Served when the server starts at or inside a declared workspace. Each tool
+ * is a thin call into the code the CLI runs:
+ *
+ * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
+ *   `workspace-records`, `workspace-points`) run `chant workspace <command>
+ *   ... --json` with the chant this server runs as, in the server's
+ *   directory, and return the
+ *   document it printed, unchanged, with its reason codes (#2536). Running the
+ *   command, rather than calling into it, keeps every rule it has, handing the
+ *   read to the workspace root's pinned chant included (ws-021), and keeps
+ *   anything a command prints away from the protocol on stdout.
+ * - The writes (`records-new`, `records-amend`, `records-review`,
+ *   `records-close`, `points-answer`) call the functions `chant workspace
+ *   records new|amend|review|close` and `points answer` call, and return the
+ *   same JSON result. They keep every rule
+ *   the CLI keeps: the kind's schema, a closed record never changing, an
+ *   approved one changing only as its approval rule allows, a dissent needing
+ *   a note, and `sign` using this host's configured key or refusing with the
+ *   CLI's remedy. Through MCP a new record also opens in the kind's first
+ *   state, `proposed` for a decision, and its stored source block (#2708) says
+ *   it came through MCP: `via: "mcp"` and `client`, the MCP client's
+ *   `clientInfo`. Computed provenance, from git, is unchanged.
+ *
+ * Nothing here listens on a port or authenticates anyone (ws-052): the server
+ * speaks over stdio, and `by` is recorded as given, as `--by` is.
+ */
+
+import { spawn } from "node:child_process";
+import type { ToolContext, ToolDefinition, ToolHandler } from "./types";
+
+/** How the reads run chant: a command and its leading arguments. */
+export type ChantCommand = string[];
+
+/**
+ * The chant this process runs as: node with the same flags (the tsx loader
+ * `bin/chant` registers) and the same entry script.
+ */
+export function ownChantCommand(): ChantCommand {
+  return [process.execPath, ...process.execArgv, process.argv[1]];
+}
+
+export interface WorkspaceToolsOptions {
+  /** Where reads run and writes resolve kinds: the directory the server started in. */
+  cwd: string;
+  /** The chant the reads run. Defaults to {@link ownChantCommand}. */
+  chantCommand?: ChantCommand;
+}
+
+const PROTOCOL =
+  "Records are proposals until they are reviewed: a new record opens proposed, and people decide it through reviews and amendments. " +
+  "by must name the person or agent that actually decided, as it is recorded as given.";
+
+const kindProp = {
+  type: "string",
+  description:
+    "The record kind: a kind file relative to the server's directory, such as decisions/decision.kind.mjs, or a kind the workspace declaration names. Without it, the one kind the declaration names.",
+};
+const atProp = { type: "string", description: "Read at this git revision instead of the working tree (--at)." };
+const dryRunProp = { type: "boolean", description: "Return the result, with the text it would write, and write nothing (--dry-run)." };
+const signProp = {
+  type: "boolean",
+  description:
+    "Seal with this host's configured key, git's user.signingkey with gpg.format ssh, as --sign does. Refused, with the CLI's remedy, when none is set.",
+};
+
+export const workspaceReadTools: ToolDefinition[] = [
+  {
+    name: "workspace-ls",
+    description:
+      "List the workspace's members and groups: chant workspace ls --json. Returns that document unchanged, which follows ls.schema.json of the read contract, reason codes included.",
+    inputSchema: { type: "object", properties: { at: atProp } },
+  },
+  {
+    name: "workspace-status",
+    description:
+      "What each member has released to an environment, its gates, and the steward that runs it with each Op's last run, from the declaration and the lifecycle ledgers: chant workspace status <env> --json. Returns that document unchanged (status.schema.json).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        env: { type: "string", description: "The environment, such as dev." },
+        compareTo: { type: "string", description: "A second environment to compare with (--compare-to)." },
+      },
+      required: ["env"],
+    },
+  },
+  {
+    name: "workspace-graph",
+    description:
+      "The workspace graph: chant workspace graph --json (graph.schema.json); with intent, the intent graph over one region (graph --intent, intent.schema.json); with composites, each composite instance and the components that can deploy it (graph --composites, composites.schema.json). Returns the document unchanged.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "array",
+          items: { type: "string" },
+          description: "Record kind files whose records join the graph (--kind). The plain graph takes one; intent takes several.",
+        },
+        intent: { type: "string", description: "The region for the intent graph: a workspace path, path:line or path:start-end (--intent)." },
+        composites: { type: "boolean", description: "The composites document instead (--composites). Takes no kind or intent." },
+        at: atProp,
+      },
+    },
+  },
+  {
+    name: "workspace-records",
+    description:
+      "The records of a kind, validated, with supersession, provenance, quorum and warnings: chant workspace records --json (records.schema.json). With since, what changed since a revision or a review session (records-since.schema.json). Returns the document unchanged; with id, only that record is kept in records. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: kindProp,
+        current: { type: "boolean", description: "Leave out records a closed record supersedes (--current)." },
+        since: { type: "string", description: "A revision, or a review session id, to compare with (--since)." },
+        id: { type: "string", description: "Keep only the record with this id in the document's records." },
+        at: atProp,
+      },
+    },
+  },
+  {
+    name: "workspace-points",
+    description:
+      "The workspace's decision points and the questions asked of them: chant workspace points --json (points.schema.json, ws-058). A question is open while it is escalated to people, or proposed by a model and not yet confirmed; each lists any model's answer with its confidence and threshold. Returns the document unchanged. chant calls no model to answer this.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        open: { type: "boolean", description: "Only the open questions (--open)." },
+        kind: { type: "string", description: "One answer kind file, in place of the declared ones (--kind)." },
+        at: atProp,
+      },
+    },
+  },
+];
+
+export const workspaceWriteTools: ToolDefinition[] = [
+  {
+    name: "records-new",
+    description:
+      "Propose a new record: chant workspace records new. The record opens in the kind's first state (proposed for a decision); another state is refused. Its source block records that it came through MCP (via mcp, and this client's clientInfo). Validated against the kind's schema; nothing is written on refusal, and nothing is committed. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: kindProp,
+        record: { type: "object", description: "The record's fields, as the kind's schema describes them. The id is allocated when left out." },
+        prefix: { type: "string", description: "The id prefix to allocate under, when the records use several (--prefix)." },
+        by: { type: "string", description: "Who decided: written to the kind's decider field, such as decided_by. Required to sign." },
+        sign: signProp,
+        dryRun: dryRunProp,
+      },
+      required: ["record"],
+    },
+  },
+  {
+    name: "records-amend",
+    description:
+      "Set top-level fields of a record: chant workspace records amend. A closed record never changes, and an approved one changes only in its state, evidence and reviews: anything else, its reasoning included, is a new record that supersedes it. A source block given in the fields records that the change came through MCP. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The record's id." },
+        kind: kindProp,
+        fields: { type: "object", description: "The top-level fields to set; each replaces the whole field." },
+        by: { type: "string", description: "Who decided: written to the kind's decider field." },
+        sign: signProp,
+        dryRun: dryRunProp,
+      },
+      required: ["id", "fields"],
+    },
+  },
+  {
+    name: "records-review",
+    description:
+      "Give a verdict on a record: chant workspace records review. Appends one entry to its reviews with the digest of the text judged, which moves its quorum. A dissent needs a note. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The record's id." },
+        kind: kindProp,
+        verdict: { type: "string", enum: ["agree", "dissent", "abstain"] },
+        by: { type: "string", description: "The reviewer: the person or agent giving the verdict (--by)." },
+        note: { type: "string", description: "Why; required for a dissent (--note)." },
+        session: { type: "string", description: "The open review session the verdict is given in (--session)." },
+        sign: signProp,
+        dryRun: dryRunProp,
+      },
+      required: ["id", "verdict", "by"],
+    },
+  },
+  {
+    name: "records-close",
+    description: "Close an open review session and seal it: chant workspace records close. " + PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The session's id." },
+        kind: { type: "string", description: "The session kind file. Without it, the one session kind the declaration names." },
+        dryRun: dryRunProp,
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "points-answer",
+    description:
+      "Record people's answer to an open decision point question, or confirm a model's proposal: chant workspace points answer. Refused unless the point's quorum is met: distinct people, none holding the agent role, each holding one of the quorum's roles when it names any. An answered question never changes. " +
+      PROTOCOL,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The question's id, as workspace-points lists it." },
+        answer: { type: ["string", "boolean"], description: "One of the question's candidates; for a noul, true or false." },
+        by: { type: "array", items: { type: "string" }, description: "Each person who answered (--by)." },
+        kind: { type: "string", description: "The answer kind file. Without it, the declared answer kinds." },
+        dryRun: dryRunProp,
+      },
+      required: ["id", "answer", "by"],
+    },
+  },
+];
+
+/** A tool call that can't be made as given: the client gets it as an error result, and nothing runs. */
+class ToolInputError extends Error {}
+
+function str(params: Record<string, unknown>, key: string, required = false): string | undefined {
+  const v = params[key];
+  if (v === undefined || v === null) {
+    if (required) throw new ToolInputError(`${key} is required`);
+    return undefined;
+  }
+  if (typeof v !== "string" || v === "") throw new ToolInputError(`${key} must be a non-empty string`);
+  // A value is passed as one argument; one that starts with - would read as a flag.
+  if (v.startsWith("-")) throw new ToolInputError(`${key} may not start with -: ${JSON.stringify(v)}`);
+  return v;
+}
+
+function bool(params: Record<string, unknown>, key: string): boolean {
+  const v = params[key];
+  if (v === undefined || v === null) return false;
+  if (typeof v !== "boolean") throw new ToolInputError(`${key} must be true or false`);
+  return v;
+}
+
+function obj(params: Record<string, unknown>, key: string): Record<string, unknown> {
+  const v = params[key];
+  if (v === null || typeof v !== "object" || Array.isArray(v)) throw new ToolInputError(`${key} must be a JSON object`);
+  return v as Record<string, unknown>;
+}
+
+function kinds(params: Record<string, unknown>): string[] {
+  const v = params.kind;
+  if (v === undefined || v === null) return [];
+  const list = typeof v === "string" ? [v] : v;
+  if (!Array.isArray(list)) throw new ToolInputError("kind must be a kind file, or a list of them");
+  return list.map((k, i) => str({ [`kind[${i}]`]: k }, `kind[${i}]`, true)!);
+}
+
+/** The `chant` arguments each read tool runs, from its input. Exported for the conformance suite's MCP transport. */
+export function readArgv(tool: string, params: Record<string, unknown>): string[] {
+  const at = str(params, "at");
+  const atArgs = at !== undefined ? ["--at", at] : [];
+  switch (tool) {
+    case "workspace-ls":
+      return ["workspace", "ls", ...atArgs, "--json"];
+    case "workspace-status": {
+      const env = str(params, "env", true)!;
+      const compareTo = str(params, "compareTo");
+      return ["workspace", "status", env, ...(compareTo !== undefined ? ["--compare-to", compareTo] : []), "--json"];
+    }
+    case "workspace-graph": {
+      const intent = str(params, "intent");
+      const composites = bool(params, "composites");
+      const kindArgs = kinds(params).flatMap((k) => ["--kind", k]);
+      if (composites) return ["workspace", "graph", "--composites", ...kindArgs, ...(intent !== undefined ? ["--intent", intent] : []), ...atArgs, "--json"];
+      if (intent !== undefined) return ["workspace", "graph", "--intent", intent, ...kindArgs, ...atArgs, "--json"];
+      return ["workspace", "graph", ...kindArgs, ...atArgs, "--json"];
+    }
+    case "workspace-points": {
+      const kind = str(params, "kind");
+      return ["workspace", "points", ...(bool(params, "open") ? ["--open"] : []), ...(kind !== undefined ? ["--kind", kind] : []), ...atArgs, "--json"];
+    }
+    case "workspace-records": {
+      const kind = str(params, "kind");
+      const since = str(params, "since");
+      return [
+        "workspace",
+        "records",
+        ...(kind !== undefined ? ["--kind", kind] : []),
+        ...(bool(params, "current") ? ["--current"] : []),
+        ...(since !== undefined ? ["--since", since] : []),
+        ...atArgs,
+        "--json",
+      ];
+    }
+    default:
+      throw new ToolInputError(`${tool} is not a workspace read tool`);
+  }
+}
+
+/** Run chant and parse the one JSON document it printed. The exit code does not matter: an error document is a document. */
+function runRead(command: ChantCommand, argv: string[], cwd: string): Promise<unknown> {
+  return new Promise((settle, fail) => {
+    const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf-8").on("data", (s: string) => (stdout += s));
+    child.stderr.setEncoding("utf-8").on("data", (s: string) => (stderr += s));
+    child.on("error", (e) => fail(new Error(`could not run chant ${argv.join(" ")}: ${e.message}`)));
+    child.on("close", (status) => {
+      try {
+        settle(JSON.parse(stdout));
+      } catch {
+        const why = stderr.trim() || stdout.trim() || `exit ${status}`;
+        fail(new Error(`chant ${argv.join(" ")} printed no JSON document: ${why}`));
+      }
+    });
+  });
+}
+
+/** Keep only the record with `id` in a records document, or in each kind of a declared set. */
+function onlyRecord(doc: unknown, id: string): unknown {
+  if (doc === null || typeof doc !== "object") return doc;
+  const d = doc as Record<string, unknown>;
+  if (Array.isArray(d.records)) return { ...d, records: (d.records as { id?: unknown }[]).filter((r) => r.id === id) };
+  if (Array.isArray(d.kinds)) return { ...d, kinds: d.kinds.map((k) => onlyRecord(k, id)) };
+  return doc;
+}
+
+/** The source block a write through MCP lays over the record's (#2708). */
+function mcpSource(context: ToolContext | undefined): Record<string, unknown> {
+  const c = context?.clientInfo;
+  const client =
+    c && typeof c.name === "string" && c.name !== ""
+      ? {
+          name: c.name,
+          ...(typeof c.version === "string" && c.version !== "" ? { version: c.version } : {}),
+          ...(typeof c.title === "string" && c.title !== "" ? { title: c.title } : {}),
+        }
+      : undefined;
+  return { via: "mcp", ...(client ? { client } : {}) };
+}
+
+export interface WorkspaceTool {
+  definition: ToolDefinition;
+  handler: ToolHandler;
+}
+
+/** The workspace tools, reads then writes, bound to the server's directory. */
+export function createWorkspaceTools(options: WorkspaceToolsOptions): WorkspaceTool[] {
+  const { cwd } = options;
+  const chant = options.chantCommand ?? ownChantCommand();
+  const reads: WorkspaceTool[] = workspaceReadTools.map((definition) => ({
+    definition,
+    handler: async (params) => {
+      const argv = readArgv(definition.name, params);
+      const id = definition.name === "workspace-records" ? str(params, "id") : undefined;
+      const doc = await runRead(chant, argv, cwd);
+      return id !== undefined ? onlyRecord(doc, id) : doc;
+    },
+  }));
+
+  const write = async () => import("../../workspace/records-write");
+  /** The kind file a write goes through: the one named, or the one the declaration names; else the CLI's usage failure. */
+  const writeKind = async (params: Record<string, unknown>, schema: string, missing: string): Promise<string | object> => {
+    const w = await write();
+    const named = str(params, "kind");
+    return named !== undefined ? w.resolveWriteKind(named, cwd) : w.declaredWriteKind(schema, cwd, missing);
+  };
+  const sign = (params: Record<string, unknown>): true | undefined => (bool(params, "sign") ? true : undefined);
+
+  const handlers: Record<string, ToolHandler> = {
+    "records-new": async (params, context) => {
+      const w = await write();
+      const record = obj(params, "record");
+      const kind = await writeKind(params, w.RECORDS_NEW_SCHEMA_ID, "new needs the kind file");
+      if (typeof kind !== "string") return kind;
+      return w.newRecord({
+        kind,
+        fields: JSON.stringify(record),
+        prefix: str(params, "prefix"),
+        by: str(params, "by"),
+        sign: sign(params),
+        dryRun: bool(params, "dryRun"),
+        cwd,
+        through: { source: mcpSource(context), opensInitial: true },
+      });
+    },
+    "records-amend": async (params, context) => {
+      const w = await write();
+      const id = str(params, "id", true)!;
+      const fields = obj(params, "fields");
+      const kind = await writeKind(params, w.RECORDS_AMEND_SCHEMA_ID, "--kind <kind file> is required");
+      if (typeof kind !== "string") return kind;
+      return w.amendRecord({
+        kind,
+        id,
+        fields: JSON.stringify(fields),
+        by: str(params, "by"),
+        sign: sign(params),
+        dryRun: bool(params, "dryRun"),
+        cwd,
+        through: { source: mcpSource(context) },
+      });
+    },
+    "records-review": async (params) => {
+      const w = await write();
+      const id = str(params, "id", true)!;
+      const kind = await writeKind(params, w.RECORDS_REVIEW_SCHEMA_ID, "--kind <kind file> is required");
+      if (typeof kind !== "string") return kind;
+      return w.reviewRecord({
+        kind,
+        id,
+        verdict: str(params, "verdict", true)!,
+        by: str(params, "by", true)!,
+        note: typeof params.note === "string" ? params.note : undefined,
+        session: str(params, "session"),
+        sign: sign(params),
+        dryRun: bool(params, "dryRun"),
+        cwd,
+      });
+    },
+    "points-answer": async (params) => {
+      const { answerPoint } = await import("../../workspace/decide");
+      const answer = params.answer;
+      if (typeof answer !== "string" && typeof answer !== "boolean") throw new ToolInputError("answer must be a string, or true or false");
+      const by = params.by;
+      if (!Array.isArray(by) || by.length === 0 || !by.every((b) => typeof b === "string" && b.trim() !== "")) throw new ToolInputError("by must list each person who answered");
+      return answerPoint({ cwd, id: str(params, "id", true)!, answer, by: by as string[], kind: str(params, "kind"), dryRun: bool(params, "dryRun") });
+    },
+    "records-close": async (params) => {
+      const w = await write();
+      const { closeRecord, RECORDS_CLOSE_SCHEMA_ID } = await import("../../workspace/records-close");
+      const id = str(params, "id", true)!;
+      const named = str(params, "kind");
+      const kind = named !== undefined ? w.resolveWriteKind(named, cwd) : await w.declaredSessionKind(RECORDS_CLOSE_SCHEMA_ID, cwd);
+      if (typeof kind !== "string") return kind;
+      return closeRecord({ kind, id, dryRun: bool(params, "dryRun"), cwd });
+    },
+  };
+
+  const writes: WorkspaceTool[] = workspaceWriteTools.map((definition) => ({ definition, handler: handlers[definition.name] }));
+  return [...reads, ...writes];
+}

package/src/cli/registry.ts

@@ -287,6 +287,18 @@ export interface ParsedArgs {
   kind?: string;
   /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
   kinds?: string[];
+  /** Every `--by` given, in order: `chant workspace points answer` counts each person toward the quorum (#2739). */
+  bys?: string[];
+  /** `chant workspace points --open` (#2739): only the questions still open. */
+  open?: boolean;
+  /** `chant workspace points ask <point> --inputs <file|->` (#2739): the inputs, as a JSON object. */
+  inputs?: string;
+  /** `chant workspace points ask <point> --response <file>` (#2739): a POST /v1/systemone response the caller got from a backend. */
+  response?: string;
+  /** `chant workspace points ask <point> --subject <id>` (#2739): what the question is about. */
+  subject?: string;
+  /** `chant workspace points answer <id> --answer <value>` (#2739): the people's answer. */
+  answer?: string;
   /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
   composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
@@ -369,6 +381,8 @@ export interface ParsedArgs {
   component?: string;
   /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. Also `chant components export --digest <manifestDigest>` (#929) — a build archive manifest digest to export directly, bypassing env/component resolution. */
   digest?: string;
+  /** `chant components release record --release-plan <file>` (ws-055, #2733) — path to a release plan JSON file, persisted content-addressed to `_plans/<digest>.json` on chant/lifecycle and read back through the read contract (`chant workspace status --json`). The plan's own `digest` field supplies `--digest` when it is omitted, and must match it when both are given. Distinct from `--plan` (#2300, below), the Op gate-approval plan digest. */
+  releasePlanFile?: string;
   /** Every `--digest` value, in order (#2602). `chant components promote --digest <component>=<sha256:...>` is repeatable, one per component; the other commands read the single {@link digest}. */
   digests?: string[];
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
@@ -413,6 +427,23 @@ export interface ParsedArgs {
   interval?: string;
   /** `chant operator --lease-ttl <duration>` (#1485) — how long an acquired lease is valid before it's reclaimable by another operator. Default: 5m. */
   leaseTtl?: string;
+  /**
+   * `chant operator --steward [<name>]` (#2731) — run a declared steward's
+   * local form: its scheduled Ops on their crons, under the steward's own
+   * lease. `""` when the flag is given without a name, which picks the
+   * project's only steward.
+   */
+  steward?: string;
+  /** `chant workspace work claim|renew|release <id> --holder <name>` (#2732): who holds, or releases, the work lease. */
+  holder?: string;
+  /** `chant run <op> --work <id>` (#2748): the work item an Op with a work lease runs under. */
+  work?: string;
+  /** `chant workspace work claim|renew <id> --ttl <seconds|duration>` (#2732): how long the lease lasts unless renewed. */
+  ttl?: string;
+  /** `chant workspace work renew|release <id> --token <token>` (#2732): the fencing token the caller holds. */
+  token?: string;
+  /** `chant workspace work release <id> --outcome <text>` (#2732): how the work ended, such as done or not_done. */
+  outcome?: string;
   /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
   once?: boolean;
   /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */

package/src/components/verbs/vuln-scan.test.ts

@@ -5,7 +5,8 @@
  * `scan-vulnerabilities` capability over an injected scanner.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, test, expect } from "vitest";
 import {
@@ -15,8 +16,13 @@ import {
   createToolVulnScanner,
   createScanVulnerabilitiesCapability,
   autoDetectVulnScanner,
+  sbomPackages,
+  compareVersions,
+  scanWithDatabase,
+  createDatabaseVulnScanner,
   type VulnFinding,
   type VulnScanner,
+  type AdvisoryDatabase,
 } from "./vuln-scan";
 import { ToolNotAvailableError } from "./process-runner";
 import type { SbomDocument } from "./sbom-generator";
@@ -178,6 +184,123 @@ describe("exploitability parsing (#1463)", () => {
   });
 });
 
+// ── offline advisory database (ws-056, INTENTIUS/chant#2735) ─────────────────
+// Ported from chud's supply-chain.mjs tests: an SBOM's purl-derived packages
+// matched against a local, offline advisory database — no scanner binary, no
+// network.
+
+const SPDX_SBOM: SbomDocument = {
+  format: "spdx",
+  mediaType: "application/spdx+json",
+  bytes: JSON.stringify({
+    packages: [
+      { name: "lodash", externalRefs: [{ referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: "pkg:npm/lodash@4.17.20" }] },
+      { name: "left-pad", externalRefs: [{ referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: "pkg:npm/left-pad@1.3.0" }] },
+      { name: "no-purl" },
+    ],
+  }),
+  generator: "lockfile",
+};
+
+const CYCLONEDX_SBOM: SbomDocument = {
+  format: "cyclonedx",
+  mediaType: "application/vnd.cyclonedx+json",
+  bytes: JSON.stringify({
+    components: [{ name: "lodash", purl: "pkg:npm/lodash@4.17.20" }, { name: "left-pad", purl: "pkg:npm/left-pad@1.3.0" }],
+  }),
+  generator: "lockfile",
+};
+
+const DB: AdvisoryDatabase = {
+  advisories: [
+    { id: "CVE-2024-0001", package: "lodash", severity: "critical", introduced: "4.0.0", fixed: "4.17.21" },
+    { id: "CVE-2024-0002", package: "left-pad", severity: "low" },
+    { id: "CVE-2024-0003", package: "lodash", ecosystem: "pypi", severity: "high" },
+  ],
+};
+
+describe("sbomPackages", () => {
+  test("reads purls from an SPDX document's externalRefs, skipping entries with none", () => {
+    const packages = sbomPackages(SPDX_SBOM);
+    expect(packages).toEqual([
+      { ecosystem: "npm", name: "lodash", version: "4.17.20" },
+      { ecosystem: "npm", name: "left-pad", version: "1.3.0" },
+    ]);
+  });
+
+  test("reads purls from a CycloneDX document's components", () => {
+    expect(sbomPackages(CYCLONEDX_SBOM)).toEqual([
+      { ecosystem: "npm", name: "lodash", version: "4.17.20" },
+      { ecosystem: "npm", name: "left-pad", version: "1.3.0" },
+    ]);
+  });
+
+  test("deduplicates identical ecosystem/name/version", () => {
+    const doc = { bytes: JSON.stringify({ components: [{ purl: "pkg:npm/x@1.0.0" }, { purl: "pkg:npm/x@1.0.0" }] }) };
+    expect(sbomPackages(doc)).toHaveLength(1);
+  });
+});
+
+describe("compareVersions", () => {
+  test("compares numerically, not lexically (1.9.0 < 1.10.0)", () => {
+    expect(compareVersions("1.9.0", "1.10.0")).toBe(-1);
+    expect(compareVersions("1.10.0", "1.9.0")).toBe(1);
+    expect(compareVersions("1.2.3", "1.2.3")).toBe(0);
+  });
+
+  test("a pre-release sorts before its release", () => {
+    expect(compareVersions("1.2.0-rc.1", "1.2.0")).toBe(-1);
+    expect(compareVersions("1.2.0", "1.2.0-rc.1")).toBe(1);
+  });
+});
+
+describe("scanWithDatabase", () => {
+  test("matches an SBOM's packages against the database by ecosystem + name, introduced <= version < fixed", () => {
+    const findings = scanWithDatabase(SPDX_SBOM, DB);
+    expect(findings).toHaveLength(2);
+    const lodash = findings.find((f) => f.cveId === "CVE-2024-0001");
+    expect(lodash).toEqual({ cveId: "CVE-2024-0001", severity: "critical", package: "lodash", installedVersion: "4.17.20", fixedVersion: "4.17.21", fixable: true });
+    const leftPad = findings.find((f) => f.cveId === "CVE-2024-0002");
+    expect(leftPad).toMatchObject({ package: "left-pad", fixable: false });
+    expect(leftPad!.fixedVersion).toBeUndefined();
+  });
+
+  test("a version at or after `fixed` is not affected", () => {
+    const doc = { bytes: JSON.stringify({ components: [{ purl: "pkg:npm/lodash@4.17.21" }] }) };
+    expect(scanWithDatabase(doc, DB)).toHaveLength(0);
+  });
+
+  test("an ecosystem mismatch does not match (pypi advisory, npm package)", () => {
+    const findings = scanWithDatabase(SPDX_SBOM, DB);
+    expect(findings.some((f) => f.cveId === "CVE-2024-0003")).toBe(false);
+  });
+
+  test("accepts a bare advisories array as well as { advisories: [...] }", () => {
+    expect(scanWithDatabase(SPDX_SBOM, DB.advisories)).toHaveLength(2);
+  });
+});
+
+describe("createDatabaseVulnScanner", () => {
+  test("scans by reading the database file at scan time", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-vulndb-"));
+    const dbFile = join(dir, "advisories.json");
+    writeFileSync(dbFile, JSON.stringify(DB));
+    const scanner = createDatabaseVulnScanner(dbFile);
+    const findings = await scanner.scan({ sbom: SPDX_SBOM });
+    expect(findings).toHaveLength(2);
+  });
+
+  test("composes with scan-vulnerabilities like any other VulnScanner", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-vulndb-"));
+    const dbFile = join(dir, "advisories.json");
+    writeFileSync(dbFile, JSON.stringify(DB));
+    const cap = createScanVulnerabilitiesCapability(createDatabaseVulnScanner(dbFile));
+    const out = await cap.run(ctx, { sbom: SPDX_SBOM, digest: "sha256:abc" });
+    expect(out.findings).toHaveLength(2);
+    expect(out.digest).toBe("sha256:abc");
+  });
+});
+
 describe("createToolVulnScanner (grype, via MockProcessRunner)", () => {
   test("scans the SBOM with `grype sbom:<file>` and parses the result", async () => {
     const mock = createMockProcessRunner({ tools: { grype: true }, responses: { "grype sbom:": GRYPE_JSON } });