@intentius/chant 0.90.0 → 0.93.0

package/src/codegen/release-wiring.test.ts

@@ -171,7 +171,54 @@ describe("release wiring: preflight gates both recipes (#1255)", () => {
     }
   });
 
-  it("the whole-repo release requires main, since it pushes main", () => {
-    expect(recipeBody("release")).toMatch(/release-preflight\.sh main/);
+});
+
+/**
+ * #2816 — main's HEAD is rarely green, so a release tags the newest green
+ * commit on main (or the one named) and merges the bump back into main.
+ * scripts/release-preflight.test.ts runs the mechanics; this pins the wiring.
+ */
+describe("release wiring: release the newest green commit (#2816)", () => {
+  it("both recipes tag the commit the preflight chose, not HEAD", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      const body = recipeBody(recipe);
+      expect(body).toMatch(/sha=\$\(bash scripts\/release-preflight\.sh/);
+      expect(body).toMatch(/release_open "\$sha"/);
+    }
+  });
+
+  it("both recipes merge the tag back into main instead of pushing HEAD", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      const body = recipeBody(recipe);
+      expect(body).toMatch(/release_ship "\$tag"/);
+      expect(body).not.toMatch(/git push/);
+      expect(body.indexOf("git tag")).toBeLessThan(body.indexOf("release_ship"));
+    }
+    const lib = readFileSync(join(repoRoot, "scripts", "release-lib.sh"), "utf-8");
+    // main and the tag land together or not at all, and nothing is forced.
+    expect(lib).toMatch(/git push --quiet --atomic origin "HEAD:refs\/heads\/main" "refs\/tags\/\$tag"/);
+    expect(lib).not.toMatch(/git push[^\n]*(--force|\s-f\b)/);
+  });
+
+  it("both recipes offer a dry run that stops before committing", () => {
+    for (const recipe of ["release", "release-lexicon"]) {
+      const body = recipeBody(recipe);
+      expect(body.indexOf("RELEASE_DRY_RUN")).toBeGreaterThan(-1);
+      expect(body.indexOf("RELEASE_DRY_RUN")).toBeLessThan(body.indexOf("git commit"));
+    }
+  });
+
+  it("the whole-repo floor reads main as well as the green commit", () => {
+    expect(recipeBody("release")).toMatch(/release_version_at "\$RELEASE_MAIN"/);
+    expect(recipeBody("release-lexicon")).toMatch(/release_version_at "\$RELEASE_MAIN"/);
+  });
+
+  it("a push to main does not cancel main's chant run; PR runs still cancel", () => {
+    const workflow = readFileSync(join(repoRoot, ".github", "workflows", "chant.yml"), "utf-8");
+    const block = workflow.match(/^concurrency:\n((?:[ ]+.*\n)+)/m)?.[1] ?? "";
+    // One group per commit on main, so a later push neither cancels a running
+    // run nor replaces a queued one.
+    expect(block).toMatch(/group:.*github\.ref == 'refs\/heads\/main' && github\.sha \|\| github\.ref/);
+    expect(block).toMatch(/cancel-in-progress: \$\{\{ github\.ref != 'refs\/heads\/main' \}\}/);
   });
 });

package/src/components/capability-plugin-loader.ts

@@ -22,7 +22,7 @@
  */
 
 import { CapabilityRegistry } from "./capability";
-import { lexiconModulePath } from "../lexicon-module";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import type { CapabilityPlugin } from "./capability-plugin";
 import { isCapabilityPlugin } from "./capability-plugin";
 import { starterCapabilityPlugin } from "./starter-plugin";
@@ -62,7 +62,7 @@ export async function loadCapabilityPlugin(name: string): Promise<CapabilityPlug
   const packageName = `@intentius/chant-capability-${name}`;
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(packageName)) as Record<string, unknown>;
+    mod = (await importLexiconPackage(packageName)) as Record<string, unknown>;
   } catch (err) {
     throw new Error(
       `capability plugin package "${packageName}" could not be loaded: ${err instanceof Error ? err.message : String(err)}`,
@@ -118,7 +118,7 @@ export async function loadCapabilityPluginFromLexicon(name: string): Promise<Cap
   const packageName = lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`;
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(packageName)) as Record<string, unknown>;
+    mod = (await importLexiconPackage(packageName)) as Record<string, unknown>;
   } catch {
     return null; // lexicon not installed / not resolvable here — nothing to contribute.
   }

package/src/components/cli-support.ts

@@ -22,7 +22,7 @@
  *    executor, the CLI entrypoint the driver (#556) never had.
  */
 
-import { lexiconModulePath, lexiconNames } from "../lexicon-module";
+import { lexiconModulePath, lexiconNames, importLexiconPackage } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
 import { inferArchetype, projectToJson, type Archetype } from "./component";
@@ -244,7 +244,7 @@ export interface GenerateComponentsResult {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await importLexiconPackage(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

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 } });

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

@@ -13,9 +13,17 @@
  * inline fake `VulnScanner` (an object literal with a canned `scan()`, see
  * ./vuln-gate.test.ts) and never invoke a real scanner, network, or vuln DB.
  * The scanner's vuln DB currency is the tool's job, not chant's.
+ *
+ * `createDatabaseVulnScanner` (ws-056, INTENTIUS/chant#2735) is the one
+ * hermetic exception: a `VulnScanner` matched against a local, offline
+ * advisory-database file instead of a real scanner binary — no `grype`/
+ * `trivy` required, deterministic, at the cost of covering only the
+ * advisories the database names. Ported from chud's `supply-chain.mjs`
+ * (`scanWithDatabase`/`sbomPackages`/`compareVersions`), which built its own
+ * copy of this because `scan-vulnerabilities` had no offline backend.
  */
 
-import { writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
@@ -174,6 +182,139 @@ export function parseTrivyOutput(stdout: string): VulnFinding[] {
   return out;
 }
 
+// ── offline advisory database ────────────────────────────────────────────────
+
+/** One package an SBOM names, by purl: the ecosystem, its name and its installed version. */
+export interface SbomPackage {
+  ecosystem: string;
+  name: string;
+  version: string;
+}
+
+/**
+ * The packages an SPDX or CycloneDX document lists, by purl (SPDX's
+ * `externalRefs` with `referenceType: "purl"`, CycloneDX's `components[].purl`),
+ * deduplicated by ecosystem/name/version. Parses `doc.bytes` (a string, as
+ * every `SbomDocument` carries it) rather than requiring a pre-parsed object,
+ * so a caller can pass a `scan-vulnerabilities` input's `sbom` straight
+ * through.
+ */
+export function sbomPackages(doc: Pick<SbomDocument, "bytes">): SbomPackage[] {
+  const parsed = JSON.parse(doc.bytes) as {
+    packages?: Array<{ externalRefs?: Array<{ referenceType?: string; referenceLocator?: string }> }>;
+    components?: Array<{ purl?: string }>;
+  };
+  const purls = [
+    ...(parsed.packages ?? []).flatMap((p) =>
+      (p.externalRefs ?? []).filter((r) => r.referenceType === "purl").map((r) => r.referenceLocator ?? ""),
+    ),
+    ...(parsed.components ?? []).map((c) => c.purl).filter((p): p is string => Boolean(p)),
+  ];
+  const seen = new Map<string, SbomPackage>();
+  for (const purl of purls) {
+    const m = /^pkg:([^/]+)\/(.+)@([^?#]+)/.exec(purl);
+    if (!m) continue;
+    const pkg: SbomPackage = { ecosystem: m[1], name: decodeURIComponent(m[2]), version: decodeURIComponent(m[3]) };
+    seen.set(`${pkg.ecosystem}:${pkg.name}@${pkg.version}`, pkg);
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Compare two dotted version strings numerically, a pre-release sorting
+ * before its release (`1.2.0-rc.1` < `1.2.0`). Not full semver (no build
+ * metadata, no ordering between differing pre-release labels beyond "a
+ * pre-release exists") — just enough to place an installed version between
+ * an advisory's `introduced` and `fixed`.
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const parse = (v: string) => {
+    const [core, pre] = String(v).replace(/^v/, "").split("-", 2);
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) {
+    const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+    if (d) return Math.sign(d) as -1 | 1;
+  }
+  if (x.pre && !y.pre) return -1;
+  if (!x.pre && y.pre) return 1;
+  if (x.pre === y.pre) return 0;
+  return x.pre! < y.pre! ? -1 : 1;
+}
+
+/** One advisory in a local, offline advisory database (`AdvisoryDatabase.advisories`). */
+export interface Advisory {
+  /** Advisory id, e.g. `"CVE-2024-12345"` or `"GHSA-…"`. */
+  id: string;
+  /** Ecosystem the advisory applies to (npm, pypi, …). Default: `"npm"`. */
+  ecosystem?: string;
+  /** Affected package name, matched against the SBOM's purl-derived package name. */
+  package: string;
+  severity?: string;
+  /** First affected version. Default: `"0"` (affects every version up to `fixed`). */
+  introduced?: string;
+  /** First version that fixes it. Omitted for a vulnerability with no fix yet. */
+  fixed?: string;
+  summary?: string;
+}
+
+/** A local, offline advisory database: `{ "advisories": [...] }` (or a bare array, for convenience). */
+export interface AdvisoryDatabase {
+  advisories: Advisory[];
+}
+
+/**
+ * Match an SBOM's packages against a local, offline advisory database —
+ * no scanner binary, no network, deterministic. A package is affected when
+ * `introduced <= installedVersion < fixed` (or unconditionally affected when
+ * the advisory names no `fixed`). Findings are `VulnFinding`-shaped, so they
+ * feed `vuln-gate` exactly like `grype`/`trivy` output does; every
+ * exploitability field (`epss`, `inKev`, …) an offline database can't supply
+ * is left `undefined`, never defaulted to a false negative.
+ */
+export function scanWithDatabase(doc: Pick<SbomDocument, "bytes">, db: AdvisoryDatabase | Advisory[]): VulnFinding[] {
+  const advisories = Array.isArray(db) ? db : (db.advisories ?? []);
+  const findings: VulnFinding[] = [];
+  for (const pkg of sbomPackages(doc)) {
+    for (const a of advisories) {
+      if ((a.ecosystem ?? "npm") !== pkg.ecosystem || a.package !== pkg.name) continue;
+      if (compareVersions(pkg.version, a.introduced ?? "0") < 0) continue;
+      if (a.fixed && compareVersions(pkg.version, a.fixed) >= 0) continue;
+      findings.push({
+        cveId: a.id,
+        severity: normalizeSeverity(a.severity),
+        package: pkg.name,
+        installedVersion: pkg.version,
+        ...(a.fixed ? { fixedVersion: a.fixed } : {}),
+        fixable: Boolean(a.fixed),
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * A `VulnScanner` backed by a local, offline advisory database file (JSON:
+ * `{ "advisories": [...] }`, see `AdvisoryDatabase`) instead of a real
+ * scanner binary — the hermetic fallback `autoDetectVulnScanner`'s doc
+ * comment says a scan doesn't have ("there is no hermetic fallback, a scan
+ * needs a real vuln DB"): deterministic, offline, no `grype`/`trivy`
+ * install required, at the cost of covering only the advisories the
+ * database names. Reads the file once per call (a database pinned in the
+ * repo changes rarely; callers that scan repeatedly should cache the parsed
+ * `AdvisoryDatabase` and call `scanWithDatabase` directly instead).
+ */
+export function createDatabaseVulnScanner(dbFile: string): VulnScanner {
+  return {
+    async scan(input) {
+      const db = JSON.parse(readFileSync(dbFile, "utf8")) as AdvisoryDatabase | Advisory[];
+      return scanWithDatabase(input.sbom, db);
+    },
+  };
+}
+
 /**
  * A real `VulnScanner` that writes the SBOM to a temp file and scans it with
  * `grype` (default) or `trivy`, through the injectable `ProcessRunner`.

package/src/config.ts

@@ -11,6 +11,7 @@ import type { BuildParamProvenance } from "./provenance";
 import { findProjectConfig } from "./project-root";
 import { evaluateProjectConfig } from "./config-sandbox";
 import { lexiconNames, pathLexiconRoot, registerLexiconDeclarations, type LexiconDeclaration } from "./lexicon-module";
+import { decideConfigSchema, type DecideConfig } from "./op/decide-config";
 
 /**
  * One project-declared environment (chant #1166). Historically always a bare
@@ -194,6 +195,7 @@ export const ChantConfigSchema = z.object({
   knowledge: z.object({
     dir: z.string().min(1).optional(),
   }).optional(),
+  decide: decideConfigSchema.optional(),
   exclude: z.array(z.string().min(1)).optional(),
   include: z.array(z.string().min(1)).optional(),
   rootOnly: z.boolean().optional(),
@@ -449,6 +451,15 @@ export interface ChantConfig {
     dir?: string;
   };
 
+  /**
+   * The backends the `decide` Op activity calls (#2828): backend name, as a
+   * decision point's model decider names it, to `{ url, key?, timeoutMs? }`.
+   * A key is `{ env }` or a brokered capability, never a literal (SYS001). A
+   * `decide` step's own `backends` take the place of these. See
+   * `./op/decide-config.ts`.
+   */
+  decide?: DecideConfig;
+
   /**
    * Globs, relative to the directory holding this config, naming files that
    * source discovery must skip (#2519): `build`, `lint`, `list`, `explain`

package/src/lexicon-module.ts

@@ -24,7 +24,9 @@
  * a project that names lexicons by package takes exactly the path it always did.
  */
 
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
 
 /**
  * One `lexicons` entry: a package-backed name, or a name plus the module that
@@ -213,3 +215,56 @@ export function lexiconPackagesToInstall(
 ): string[] {
   return names.filter((name) => !paths.has(name)).map((name) => `@intentius/chant-lexicon-${name}`);
 }
+
+/**
+ * chant#2845 — the npm package a bare specifier names: `@scope/name` for a
+ * scoped one, else its first segment. `undefined` for a relative or absolute
+ * path, which is not a package.
+ */
+export function packageNameOf(spec: string): string | undefined {
+  if (spec.startsWith(".") || isAbsolute(spec) || spec.startsWith("file:")) return undefined;
+  const parts = spec.split("/");
+  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+/** True when `err` says the package `pkg` itself could not be found, not something it imports. */
+function isPackageNotFound(err: unknown, pkg: string): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") return false;
+  const message = err instanceof Error ? err.message : String(err);
+  return message.includes(`'${pkg}'`) || message.includes(`"${pkg}"`) || message.includes(`${pkg}/`);
+}
+
+/**
+ * chant#2845 — resolve `spec` (a lexicon package or one of its subpaths) from
+ * `fromDir` instead of from chant's own install, or `undefined` when the
+ * project doesn't have it either.
+ */
+export function resolveFromProject(spec: string, fromDir: string = process.cwd()): string | undefined {
+  try {
+    return createRequire(join(fromDir, "package.json")).resolve(spec);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * chant#2845 — import a lexicon package, or one of its subpaths, by its bare
+ * specifier. chant's own install is tried first, as a bare `import()` always
+ * did, so a lexicon chant can reach loads exactly as before. When the package
+ * isn't there, which is the case for a chant installed globally and a project
+ * that installs its lexicons in its own node_modules, it is resolved from
+ * `fromDir` (the project) and imported from there. Any other failure, and a
+ * package the project doesn't have either, rethrows the first error.
+ */
+export async function importLexiconPackage(spec: string, fromDir: string = process.cwd()): Promise<Record<string, unknown>> {
+  try {
+    return (await import(spec)) as Record<string, unknown>;
+  } catch (err) {
+    const pkg = packageNameOf(spec);
+    if (pkg === undefined || !isPackageNotFound(err, pkg)) throw err;
+    const resolved = resolveFromProject(spec, fromDir);
+    if (resolved === undefined) throw err;
+    return (await import(pathToFileURL(resolved).href)) as Record<string, unknown>;
+  }
+}

package/src/lexicon-package.test.ts

@@ -0,0 +1,96 @@
+/**
+ * chant#2845 — a lexicon the project installs in its own node_modules loads
+ * when chant's own install can't reach it (a global chant): the plugin, its
+ * op activities and its activity contracts, resolved from the working
+ * directory after the bare import from chant's location fails.
+ */
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { importLexiconPackage, packageNameOf, resolveFromProject } from "./lexicon-module";
+import { loadActivities } from "./op/activity-registry";
+import { loadActivityContracts } from "./op/activity-contract-registry";
+import { resolveLexiconVersions } from "./cli/plugins";
+
+const NAME = "zz2845";
+const PKG = `@intentius/chant-lexicon-${NAME}`;
+let project: string;
+
+beforeAll(async () => {
+  project = await mkdtemp(join(tmpdir(), "chant-2845-"));
+  const dir = join(project, "node_modules", "@intentius", `chant-lexicon-${NAME}`);
+  await mkdir(join(dir, "op"), { recursive: true });
+  await writeFile(
+    join(dir, "package.json"),
+    JSON.stringify({
+      name: PKG,
+      version: "9.9.9",
+      type: "module",
+      exports: { ".": { default: "./index.js" }, "./op/activities": { default: "./op/activities.js" }, "./op/activity-contracts": { default: "./op/contracts.js" } },
+    }),
+  );
+  await writeFile(join(dir, "index.js"), "export const marker = 'plugin';\n");
+  await writeFile(join(dir, "op", "activities.js"), "export async function zz2845Probe() { return { ok: true }; }\n");
+  // A contract is branded with a global symbol, so a plain object built here is one.
+  await writeFile(
+    join(dir, "op", "contracts.js"),
+    "export const zz2845ProbeContract = { [Symbol.for('chant.op.activityContract')]: true, name: 'zz2845Probe', args: {}, returns: {} };\n",
+  );
+});
+
+afterAll(async () => {
+  await rm(project, { recursive: true, force: true });
+});
+
+describe("importLexiconPackage (#2845)", () => {
+  test("a package chant can't reach is imported from the project", async () => {
+    await expect(import(PKG)).rejects.toThrow();
+    const mod = await importLexiconPackage(PKG, project);
+    expect(mod.marker).toBe("plugin");
+    const op = await importLexiconPackage(`${PKG}/op/activities`, project);
+    expect(typeof op.zz2845Probe).toBe("function");
+  });
+
+  test("a package chant reaches loads from chant's install, whatever the directory", async () => {
+    const mod = await importLexiconPackage("zod", project);
+    expect(typeof mod.z).toBe("object");
+  });
+
+  test("a package neither has fails with the bare import's own error", async () => {
+    await expect(importLexiconPackage("@intentius/chant-lexicon-nope-2845", project)).rejects.toThrow(/chant-lexicon-nope-2845/);
+  });
+
+  test("a path is not looked up in the project", () => {
+    expect(packageNameOf("/abs/lexicon.ts")).toBeUndefined();
+    expect(packageNameOf("./lexicon.ts")).toBeUndefined();
+    expect(packageNameOf(`${PKG}/op/activities`)).toBe(PKG);
+    expect(resolveFromProject(PKG, project)).toMatch(/index\.js$/);
+  });
+});
+
+describe("the loaders take the project's lexicon (#2845)", () => {
+  const inProject = async <T>(fn: () => Promise<T> | T): Promise<T> => {
+    const cwd = process.cwd();
+    process.chdir(project);
+    try {
+      return await fn();
+    } finally {
+      process.chdir(cwd);
+    }
+  };
+
+  test("loadActivities finds its op activities", async () => {
+    const activities = await inProject(() => loadActivities([NAME]));
+    expect(activities.has("zz2845Probe")).toBe(true);
+  });
+
+  test("loadActivityContracts finds its contracts", async () => {
+    const contracts = await inProject(() => loadActivityContracts([NAME]));
+    expect(contracts.has("zz2845Probe")).toBe(true);
+  });
+
+  test("resolveLexiconVersions reads its version", async () => {
+    expect(await inProject(() => resolveLexiconVersions([NAME]))).toEqual({ [NAME]: "9.9.9" });
+  });
+});

package/src/lifecycle/converge-ledger.ts

@@ -66,6 +66,12 @@ export interface ConvergeRuleOutcome {
   action: "ran" | "reported" | "skipped-budget" | "skipped-flap" | "gated";
   /** The dispatched Op name, for `action: "ran"` or `"gated"`. */
   op?: string;
+  /**
+   * The resource the rule fired for, on a tick of a ConvergeOp with an
+   * observer step (#2778), which evaluates its rules once per resource. The
+   * dispatched Op reads it from `CHANT_CONVERGE_RESOURCE`.
+   */
+  resource?: string;
   /** The gate's signal name, for `action: "gated"`. */
   gateName?: string;
   /**
@@ -131,6 +137,14 @@ export function componentVerdicts(rows: readonly ComponentStatusRow[]): Converge
   }));
 }
 
+/** One resource an observer step reported on a tick (#2778). */
+export interface ConvergeResourceVerdict {
+  name: string;
+  status: "in-sync" | "drifted" | "unknown";
+  /** The observer's reason, capped to one line. */
+  detail?: string;
+}
+
 /** One immutable converge-tick record. */
 export interface ConvergeTickRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
@@ -168,6 +182,12 @@ export interface ConvergeTickRecord {
    * records written before #2027 have none; absent is not "no components".
    */
   components?: ConvergeComponentVerdict[];
+  /**
+   * What a ConvergeOp's observer step reported this tick (#2778), one entry
+   * per resource: in its place of `components` for resources no lexicon
+   * observes. Absent on a tick observed through a lexicon environment.
+   */
+  resources?: ConvergeResourceVerdict[];
   /** Aggregate counts backing the tick's one log line. */
   summary: {
     drifted: number;