@intentius/chant 0.41.20 → 0.44.1

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

@@ -9,10 +9,10 @@
  * digest) over re-scanning the image: deterministic (same SBOM -> same
  * findings), fast, and reuses work already done. Real backends shell out to
  * `grype`/`trivy` through the injectable `ProcessRunner` (./process-runner.ts),
- * exactly like ./tool-sbom-generator.ts's deep-scan backend — tests inject a
- * `MockVulnScanner` (./__tests__/mock-vuln-scanner.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.
+ * exactly like ./tool-sbom-generator.ts's deep-scan backend — tests inject an
+ * 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.
  */
 
 import { writeFileSync } from "node:fs";
@@ -57,6 +57,18 @@ export interface VulnFinding {
   fixedVersion?: string;
   /** True when a fix exists (upgradeable) — the beginner-safe default gate blocks only fixable findings, since an unfixable one can't be actioned by bumping. */
   fixable: boolean;
+  /** EPSS score (0.0–1.0): probability of exploitation in the next 30 days. Absent when the scanner did not report one. */
+  epss?: number;
+  /** EPSS percentile (0.0–1.0) — rank against all scored CVEs. */
+  epssPercentile?: number;
+  /** Present in CISA's Known Exploited Vulnerabilities catalog. `undefined` means the scanner did not report KEV membership at all — NOT the same conclusion as a reported `false`. Never default this. */
+  inKev?: boolean;
+  /** When the CVE entered the KEV catalog (ISO date, as the source reports it). */
+  kevDateAdded?: string;
+  /** KEV remediation due date (ISO date). */
+  kevDueDate?: string;
+  /** Known use in a ransomware campaign, per KEV. */
+  kevRansomware?: boolean;
 }
 
 // ── injectable scanner boundary ──────────────────────────────────────────────
@@ -72,8 +84,8 @@ export interface ScanInput {
  * Injectable vulnerability-scan boundary — the scan-side analogue of
  * `SbomGenerator` (./sbom-generator.ts) and `CloudExecutor`
  * (./cloud-executor.ts). A real implementation shells out to `grype`/`trivy`;
- * tests substitute `MockVulnScanner` (./__tests__/mock-vuln-scanner.ts) and
- * never touch a real tool, network, or vuln DB.
+ * tests substitute an inline fake (an object literal with a canned `scan()`)
+ * and never touch a real tool, network, or vuln DB.
  */
 export interface VulnScanner {
   /** Scan an SBOM, returning every known vulnerability it surfaces. */
@@ -83,15 +95,26 @@ export interface VulnScanner {
 /** Which real CLI scanner a `ProcessRunner`-backed scanner shells out to. */
 export type ScannerTool = "grype" | "trivy";
 
-/** grype `-o json` output shape (the subset we read). */
+/** grype `-o json` output shape (the subset we read). `epss` and `knownExploited` are omitted (not empty) for a vuln grype has no data on, so absence maps to `undefined`, never `false`/`0`. grype's composite `risk` score is deliberately not read — policy gates on the inputs (EPSS, KEV), not one tool's weighting of them. */
 interface GrypeOutput {
   matches?: Array<{
-    vulnerability?: { id?: string; severity?: string; fix?: { versions?: string[]; state?: string } };
+    vulnerability?: {
+      id?: string;
+      severity?: string;
+      fix?: { versions?: string[]; state?: string };
+      epss?: Array<{ cve?: string; epss?: number; percentile?: number; date?: string }>;
+      knownExploited?: Array<{
+        cve?: string;
+        dateAdded?: string;
+        dueDate?: string;
+        knownRansomwareCampaignUse?: string;
+      }>;
+    };
     artifact?: { name?: string; version?: string };
   }>;
 }
 
-/** trivy `--format json` output shape (the subset we read). */
+/** trivy `--format json` output shape (the subset we read). Trivy (v0.73, __fixtures__/trivy-with-kev-epss.json) reports no KEV/EPSS data in its JSON output, so a trivy-backed finding carries every exploitability field as `undefined` — the honest "not reported" state, not `false`. */
 interface TrivyOutput {
   Results?: Array<{
     Vulnerabilities?: Array<{
@@ -109,6 +132,8 @@ export function parseGrypeOutput(stdout: string): VulnFinding[] {
   const doc = JSON.parse(stdout) as GrypeOutput;
   return (doc.matches ?? []).map((m) => {
     const fixVersions = m.vulnerability?.fix?.versions ?? [];
+    const epss = m.vulnerability?.epss?.[0];
+    const kev = m.vulnerability?.knownExploited?.[0];
     return {
       cveId: m.vulnerability?.id ?? "UNKNOWN",
       severity: normalizeSeverity(m.vulnerability?.severity),
@@ -116,6 +141,16 @@ export function parseGrypeOutput(stdout: string): VulnFinding[] {
       installedVersion: m.artifact?.version ?? "",
       fixedVersion: fixVersions[0],
       fixable: m.vulnerability?.fix?.state === "fixed" || fixVersions.length > 0,
+      epss: epss?.epss,
+      epssPercentile: epss?.percentile,
+      // grype omits `knownExploited` for a non-KEV vuln, so `undefined` here
+      // means "no KEV annotation reported" — never coerced to `false`.
+      inKev: kev ? true : undefined,
+      kevDateAdded: kev?.dateAdded,
+      kevDueDate: kev?.dueDate,
+      // KEV's ransomware field is "known"/"unknown" — "unknown" is not "no",
+      // so only an explicit "known" becomes `true`; everything else stays unset.
+      kevRansomware: kev?.knownRansomwareCampaignUse?.toLowerCase() === "known" ? true : undefined,
     } satisfies VulnFinding;
   });
 }

package/src/config.test.ts

@@ -239,6 +239,27 @@ describe("environments (#1166 — string or { name, endpoint })", () => {
   });
 });
 
+describe("vulnPolicy exploitability fields (#1466)", () => {
+  test("loads the exploitability fields, zero thresholds included", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ vulnPolicy: { failOnKev: true, failEpssAtOrAbove: 0, warnEpssAtOrAbove: 0.01, exploitabilityFixableOnly: false } }),
+    );
+
+    const result = await loadChantConfig(TEST_DIR);
+    expect(result.config.vulnPolicy).toEqual({ failOnKev: true, failEpssAtOrAbove: 0, warnEpssAtOrAbove: 0.01, exploitabilityFixableOnly: false });
+  });
+
+  test("rejects an EPSS threshold outside 0.0–1.0", async () => {
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ vulnPolicy: { failEpssAtOrAbove: 1.5 } }),
+    );
+
+    await expect(loadChantConfig(TEST_DIR)).rejects.toThrow(/failEpssAtOrAbove/);
+  });
+});
+
 describe("environmentName / environmentNames / environmentEndpoint (#1166)", () => {
   test("environmentName reduces either form to its name", () => {
     expect(environmentName("prod")).toBe("prod");

package/src/config.ts

@@ -106,6 +106,10 @@ export const ChantConfigSchema = z.object({
     warnSeverity: z.enum(["critical", "high", "medium", "low", "negligible", "unknown"]).optional(),
     failOnLicense: z.boolean().optional(),
     failOnUnknownSeverity: z.boolean().optional(),
+    failOnKev: z.boolean().optional(),
+    failEpssAtOrAbove: z.number().min(0).max(1).optional(),
+    warnEpssAtOrAbove: z.number().min(0).max(1).optional(),
+    exploitabilityFixableOnly: z.boolean().optional(),
     license: z.object({
       allow: z.array(z.string()).optional(),
       deny: z.array(z.string()).optional(),
@@ -308,6 +312,14 @@ export interface ChantConfig {
     failOnLicense?: boolean;
     /** Block on an `unknown`-severity finding (always warned regardless). Default `false`. */
     failOnUnknownSeverity?: boolean;
+    /** Block any finding in the CISA KEV catalog, regardless of severity. Default `false`. */
+    failOnKev?: boolean;
+    /** Block when EPSS is at or above this (0.0–1.0). Omit to ignore EPSS. */
+    failEpssAtOrAbove?: number;
+    /** Warn (not block) at or above this EPSS. Omit to ignore. */
+    warnEpssAtOrAbove?: number;
+    /** Apply `fixableOnly` to exploitability blocks too. Default `true`. */
+    exploitabilityFixableOnly?: boolean;
     /** License allow/deny lists evaluated against the SBOM's declared licenses. */
     license?: { allow?: string[]; deny?: string[] };
     /** Which real scanner a `ProcessRunner`-backed `vuln-gate`/`scan-vulnerabilities` shells out to. Default `"grype"`. Read where the capability/scanner is constructed. */
@@ -560,6 +572,12 @@ export function resolveVulnPolicy(config: ChantConfig): Partial<VulnPolicy> {
   if (v.warnSeverity) out.warnSeverity = v.warnSeverity;
   if (v.failOnLicense !== undefined) out.failOnLicense = v.failOnLicense;
   if (v.failOnUnknownSeverity !== undefined) out.failOnUnknownSeverity = v.failOnUnknownSeverity;
+  // `!== undefined`, never truthiness: `failEpssAtOrAbove: 0` (match any scored
+  // finding) and an explicit `failOnKev: false` override must both survive.
+  if (v.failOnKev !== undefined) out.failOnKev = v.failOnKev;
+  if (v.failEpssAtOrAbove !== undefined) out.failEpssAtOrAbove = v.failEpssAtOrAbove;
+  if (v.warnEpssAtOrAbove !== undefined) out.warnEpssAtOrAbove = v.warnEpssAtOrAbove;
+  if (v.exploitabilityFixableOnly !== undefined) out.exploitabilityFixableOnly = v.exploitabilityFixableOnly;
   if (v.license) out.license = v.license;
   return out;
 }

package/src/deep-observation.test.ts

@@ -75,6 +75,25 @@ describe("normalizeDeepProperties", () => {
     expect(out.List).toEqual(["x", "y"]);
   });
 
+  test("a value the unresolved hook claims collapses to UNRESOLVED, and only that value", () => {
+    const hooks: DeepNormalizationHooks = {
+      unresolved: (n) =>
+        n.side === "declared" && typeof n.value === "string" && n.value.startsWith("[") && n.value.endsWith("]"),
+    };
+    const declared = normalizeDeepProperties(
+      { ref: { id: "[resourceId('T', 'x')]" }, name: "n" },
+      { entityType: "T", side: "declared", hooks },
+    );
+    expect(declared).toEqual({ ref: { id: UNRESOLVED }, name: "n" });
+    // The hook sees the side, so the live tree — where the same shape is an
+    // evaluated value — is untouched.
+    const live = normalizeDeepProperties(
+      { ref: { id: "[literal]" }, name: "n" },
+      { entityType: "T", side: "live", hooks },
+    );
+    expect(live).toEqual({ ref: { id: "[literal]" }, name: "n" });
+  });
+
   test("prunes by hook, and prunes the whole subtree", () => {
     const hooks: DeepNormalizationHooks = { prune: (n) => n.pattern === "Status" };
     const out = normalizeDeepProperties(

package/src/deep-observation.ts

@@ -253,6 +253,19 @@ export interface DeepNormalizationHooks {
    * the order the provider returned it.
    */
   orderKey?(element: DeepArrayElement): string | undefined;
+  /**
+   * Return true when this value cannot be known without deploying — it is
+   * collapsed to {@link UNRESOLVED}, and the diff skips any path whose declared
+   * value is UNRESOLVED, exactly as it already does for a non-JSON intrinsic.
+   *
+   * The pass collapses class-instance intrinsics (`Fn::Sub`, `Ref`) on its own;
+   * this hook exists for the lexicons whose unevaluated references are plain
+   * JSON data the pass cannot recognize — an ARM template's
+   * `"[resourceId(...)]"` expression string is the motivating case (#1213).
+   * Left alone, every such reference diffs against its evaluated live value and
+   * reads as permanent drift.
+   */
+  unresolved?(node: DeepNode): boolean;
 }
 
 /** Everything the pass needs besides the tree itself. */
@@ -371,25 +384,31 @@ export function normalizeDeepProperties(
 ): Record<string, unknown> {
   const { entityType, side, hooks, counterpartPaths } = options;
 
+  const nodeOf = (path: string, pattern: string, key: string, value: unknown): DeepNode => ({
+    entityType,
+    path,
+    pattern,
+    key,
+    value,
+    side,
+    counterpart: !counterpartPaths
+      ? "unknown"
+      : counterpartPaths.has(path) || counterpartPaths.has(pattern)
+        ? "present"
+        : "absent",
+  });
+
   const prune = (path: string, pattern: string, key: string, value: unknown): boolean => {
     if (!hooks?.prune) return false;
-    return hooks.prune({
-      entityType,
-      path,
-      pattern,
-      key,
-      value,
-      side,
-      counterpart: !counterpartPaths
-        ? "unknown"
-        : counterpartPaths.has(path) || counterpartPaths.has(pattern)
-          ? "present"
-          : "absent",
-    });
+    return hooks.prune(nodeOf(path, pattern, key, value));
   };
 
   const normalizeValue = (value: unknown, path: string, pattern: string, key: string): unknown => {
     if (isSensitiveKey(key)) return MASKED;
+    // A value the lexicon says cannot be known without deploying — an
+    // expression-string reference — collapses exactly like a class-instance
+    // intrinsic does below.
+    if (hooks?.unresolved?.(nodeOf(path, pattern, key, value))) return UNRESOLVED;
     if (isJsonPrimitive(value)) return value;
 
     // A PROPERTY-kind Declarable is authored data wearing a class, not an

package/src/lexicon.ts

@@ -1,10 +1,12 @@
 import type { Serializer } from "./serializer";
+import type { Declarable } from "./declarable";
 import type { LintRule } from "./lint/rule";
 import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
 import type { TemplateParser, TemplateIR } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
+import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
@@ -122,6 +124,8 @@ export interface BundleSpec {
   typesDTS: string;
   rules: Map<string, string>;
   skills: Map<string, string>;
+  /** OKF knowledge bundle over the registry and rules (#1060), written to dist/okf/. */
+  okf?: OkfFile[];
   integrity?: ArtifactIntegrity;
   metadata?: PackageMetadata;
 }
@@ -421,6 +425,31 @@ export interface StackStatusObservation {
   healthy?: boolean;
 }
 
+/**
+ * Context for a lexicon's {@link LexiconPlugin.buildRoots} hook (#1548).
+ */
+export interface BuildRootContext {
+  /**
+   * The directory the project configuration was loaded from (where
+   * `chant.config.*` lives) — relative root paths resolve against it, NOT
+   * against `sourceDir`, because a non-chant-source root (a kustomize
+   * overlay tree) usually lives beside the typed source rather than inside
+   * it.
+   */
+  projectRoot: string;
+  /** The resolved project configuration, for the lexicon's own namespace. */
+  config: Record<string, unknown>;
+}
+
+/**
+ * What a build-root render contributes to the build: entities keyed like
+ * discovered ones, plus non-fatal diagnostics.
+ */
+export interface BuildRootContribution {
+  entities: Map<string, Declarable>;
+  warnings?: string[];
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -554,6 +583,27 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): ComponentPipelineResult;
 
+  /**
+   * Render this lexicon's config-declared build roots into entities (#1548
+   * piece 3) — the seam for a build root that is NOT typed chant source. The
+   * k8s lexicon implements it for `k8s.kustomize.roots`: each named
+   * kustomization dir renders (`kustomize build`) at build time and the
+   * documents come back as entities, which the build merges into the
+   * discovered set BEFORE partitioning — so they are serialized by this
+   * lexicon's serializer (ownership stamping included), seen by post-synth
+   * checks, and observed by `describeResources` exactly like discovered
+   * entities.
+   *
+   * Called once per top-level build (never for nested child projects), only
+   * when the CLI wires it up (`collectBuildRootContributors` in
+   * ./cli/plugins.ts → {@link BuildOptions.buildRoots}). A hook that has
+   * nothing configured must return an empty map, not throw; a hook that
+   * cannot render (missing binary, missing dir) should throw with a message
+   * naming the problem — the build reports it as a build error, not a stack
+   * trace. Omit for lexicons with no non-source build-root concept.
+   */
+  buildRoots?(ctx: BuildRootContext): Promise<BuildRootContribution>;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];

package/src/lifecycle/observe.test.ts

@@ -64,6 +64,24 @@ describe("observeResources", () => {
     expect(names).toEqual(["web-vpc"]);
   });
 
+  it("keeps non-resource declarables out of the observation universe", async () => {
+    // Outputs, parameters and serializer directives (gcp's defaultAnnotations)
+    // have no `props` and no live counterpart — a declared name the reader can
+    // never resolve would read as unobserved or missing forever.
+    const buildResult = {
+      outputs: new Map<string, string>([["aws", "{}"]]),
+      entities: new Map<string, unknown>([
+        ["web-vpc", { lexicon: "aws", entityType: "AWS::EC2::VPC", props: {} }],
+        ["annotations", { lexicon: "aws", entityType: "chant:aws:directive" }],
+      ]),
+      errors: [],
+    } as unknown as BuildResult;
+    let names: string[] = [];
+    const plugins = [awsPlugin(({ entityNames }) => { names = entityNames; return {}; })];
+    await observeResources("prod", plugins, buildResult);
+    expect(names).toEqual(["web-vpc"]);
+  });
+
   it("collects a throwing plugin into errors instead of failing the whole graph, and reports its entities unobserved (#1089)", async () => {
     const plugins = [
       awsPlugin(() => { throw new Error("access denied"); }),

package/src/lifecycle/observe.ts

@@ -25,6 +25,7 @@ import {
 } from "../observation";
 import { zeroResourcesWarning } from "../live-endpoint";
 import { unqualifiedKey } from "./identity";
+import { isResourceDeclarable } from "../declarable";
 
 export interface ObserveResult {
   observations: LiveObservation[];
@@ -123,10 +124,16 @@ export async function observeResources(
     const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
     for (const [name, entity] of buildResult.entities) {
       if (entity.lexicon !== plugin.name) continue;
+      // Only resource declarables have a live counterpart to observe. Outputs,
+      // parameters and serializer directives (gcp's `defaultAnnotations`) are
+      // build-time inputs — declared, but with nothing in any cloud to compare
+      // against, so keeping them in the universe makes every diff report a
+      // hole (or worse, a deletion) for a resource that cannot exist.
+      if (!isResourceDeclarable(entity)) continue;
       entityNames.push(name);
       entities.set(name, {
         entityType: entity.entityType,
-        props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+        props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
       });
     }
 
@@ -145,11 +152,11 @@ export async function observeResources(
             stackEntityNames = [];
             stackEntities = new Map();
             for (const [name, entity] of sb.entities) {
-              if (entity.lexicon !== plugin.name) continue;
+              if (entity.lexicon !== plugin.name || !isResourceDeclarable(entity)) continue;
               stackEntityNames.push(name);
               stackEntities.set(name, {
                 entityType: entity.entityType,
-                props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+                props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
               });
             }
             const raw = sb.outputs.get(plugin.name);

package/src/lifecycle/snapshot.ts

@@ -18,6 +18,7 @@ import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedE
 // property tree is ever rendered or committed. Two lists would eventually
 // disagree about what counts as a secret.
 import { isSensitiveKey } from "../deep-observation";
+import { isResourceDeclarable } from "../declarable";
 
 /**
  * Check for potential sensitive data in resource attributes and return warnings.
@@ -125,13 +126,13 @@ export async function takeSnapshot(
     const entityNames: string[] = [];
     const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
     for (const [name, entity] of buildResult.entities) {
-      if (entity.lexicon === plugin.name) {
+      // Resource declarables only — outputs, parameters and serializer
+      // directives have no live counterpart (see lifecycle/observe.ts).
+      if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
         entityNames.push(name);
         entities.set(name, {
           entityType: entity.entityType,
-          props: ("props" in entity && entity.props != null
-            ? entity.props
-            : {}) as Record<string, unknown>,
+          props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
         });
       }
     }

package/src/okf.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildOkfBundle, okfConformanceProblems, splitFrontmatter, OKF_VERSION, type OkfFile } from "./okf";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { setProvenance } from "./provenance";
+import { parseYAML } from "./yaml";
+import { discover } from "./discovery/index";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+function fileMap(bundle: OkfFile[]): Map<string, string> {
+  return new Map(bundle.map((f) => [f.path, f.content]));
+}
+
+/**
+ * Assert the four OKF v0.2 conformance criteria (spec §11) over a bundle via
+ * the shared checker (`okfConformanceProblems`) — the same one the lexicon
+ * bundle tests (#1060) run — plus the version pin our own emitter guarantees.
+ */
+function assertConformant(bundle: OkfFile[]): void {
+  expect(okfConformanceProblems(bundle)).toEqual([]);
+  const index = bundle.find((f) => f.path === "index.md");
+  expect(index).toBeDefined();
+  const split = splitFrontmatter(index!.content);
+  expect(split).toBeDefined();
+  expect(parseYAML(split!.frontmatter)).toEqual({ okf_version: OKF_VERSION });
+}
+
+describe("buildOkfBundle", () => {
+  test("emits one concept per entity with parseable frontmatter and a non-empty type", () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket", kind: "resource" as const });
+    setProvenance(bucket, { sourceFile: "/proj/src/storage.ts" });
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const entities = new Map<string, Declarable>([
+      ["myBucket", bucket],
+      ["vpc", vpc],
+    ]);
+
+    const bundle = buildOkfBundle({ entities, dependencies: new Map() }, "/proj");
+    const files = fileMap(bundle);
+    expect([...files.keys()]).toEqual(["aws/myBucket.md", "gcp/vpc.md", "index.md"]);
+
+    const concept = splitFrontmatter(files.get("aws/myBucket.md")!)!;
+    const front = parseYAML(concept.frontmatter);
+    expect(front.type).toBe("AWS::S3::Bucket");
+    expect(front.title).toBe("myBucket");
+    expect(front.lexicon).toBe("aws");
+    expect(front.kind).toBe("resource");
+    expect(front.source).toBe("src/storage.ts");
+    expect(concept.body).toContain("Declared in `src/storage.ts`.");
+  });
+
+  test("dependency edges become bundle-relative markdown links, both directions", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    const dependencies = new Map([["subnet", new Set(["vpc"])]]);
+
+    const files = fileMap(buildOkfBundle({ entities, dependencies }));
+    expect(files.get("gcp/subnet.md")).toContain("## Depends on");
+    expect(files.get("gcp/subnet.md")).toContain("- [vpc](/gcp/vpc.md)");
+    expect(files.get("gcp/vpc.md")).toContain("## Referenced by");
+    expect(files.get("gcp/vpc.md")).toContain("- [subnet](/gcp/subnet.md)");
+  });
+
+  test("an unresolved dependency emits a link rather than failing — broken links are permitted", () => {
+    const app = decl({ lexicon: "k8s", entityType: "Deployment" });
+    const entities = new Map<string, Declarable>([["app", app]]);
+    const dependencies = new Map([["app", new Set(["ghost"])]]);
+
+    const bundle = buildOkfBundle({ entities, dependencies });
+    expect(fileMap(bundle).get("k8s/app.md")).toContain("- [ghost](/ghost.md)");
+    assertConformant(bundle);
+  });
+
+  test("index.md groups entities into per-lexicon sections with okf_version frontmatter", () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const job = decl({ lexicon: "gitlab", entityType: "GitLab::Job" });
+    const entities = new Map<string, Declarable>([
+      ["assets", bucket],
+      ["buildJob", job],
+    ]);
+
+    const index = fileMap(buildOkfBundle({ entities, dependencies: new Map() })).get("index.md")!;
+    expect(index).toContain(`okf_version: '${OKF_VERSION}'`);
+    expect(index).toContain("# Lexicon: aws");
+    expect(index).toContain("# Lexicon: gitlab");
+    expect(index).toContain("* [assets](/aws/assets.md) - aws resource of type AWS::S3::Bucket");
+    expect(index).toContain("* [buildJob](/gitlab/buildJob.md) - gitlab resource of type GitLab::Job");
+  });
+
+  test("composite provenance rides along as extra frontmatter keys", () => {
+    const dep = decl({ lexicon: "k8s", entityType: "K8s::Apps::Deployment" });
+    setProvenance(dep, { sourceFile: "/proj/src/web.ts", composite: "WebApp", compositeInstance: "prodApp" });
+    const entities = new Map<string, Declarable>([["prodAppDeployment", dep]]);
+
+    const front = parseYAML(
+      splitFrontmatter(fileMap(buildOkfBundle({ entities, dependencies: new Map() }, "/proj")).get("k8s/prodAppDeployment.md")!)!.frontmatter,
+    );
+    expect(front.composite).toBe("WebApp");
+    expect(front.composite_instance).toBe("prodApp");
+  });
+
+  test("entity names that slug to the same path are deduped, never overwritten", () => {
+    const a = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const b = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const entities = new Map<string, Declarable>([
+      ["my/bucket", a],
+      ["my-bucket", b],
+    ]);
+
+    const paths = buildOkfBundle({ entities, dependencies: new Map() }).map((f) => f.path);
+    expect(new Set(paths).size).toBe(paths.length);
+    expect(paths).toContain("aws/my-bucket.md");
+    expect(paths).toContain("aws/my-bucket-2.md");
+  });
+
+  test("an empty project still emits a conformant bundle (just the index)", () => {
+    const bundle = buildOkfBundle({ entities: new Map(), dependencies: new Map() });
+    expect(bundle.map((f) => f.path)).toEqual(["index.md"]);
+    assertConformant(bundle);
+  });
+
+  test("deterministic: the same input yields byte-identical files", () => {
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const subnet = decl({ lexicon: "gcp", entityType: "Subnet" });
+    const entities = new Map<string, Declarable>([
+      ["vpc", vpc],
+      ["subnet", subnet],
+    ]);
+    const dependencies = new Map([["subnet", new Set(["vpc"])]]);
+
+    expect(buildOkfBundle({ entities, dependencies })).toEqual(buildOkfBundle({ entities, dependencies }));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Shipped examples, spanning lexicons (#1058 acceptance): each bundle is
+// asserted conformant against the four v0.2 criteria and snapshot-tested.
+// ---------------------------------------------------------------------------
+
+const repoRoot = resolve(fileURLToPath(import.meta.url), "../../../..");
+
+const exampleCases: Array<[string, string]> = [
+  ["k8s layered-config", "lexicons/k8s/examples/layered-config/src"],
+  ["aws lambda-s3", "lexicons/aws/examples/lambda-s3/src"],
+  ["gitlab node-pipeline", "lexicons/gitlab/examples/node-pipeline/src"],
+];
+
+describe("buildOkfBundle over shipped examples", () => {
+  for (const [name, rel] of exampleCases) {
+    test(`${name} emits a conformant, snapshot-stable bundle`, async () => {
+      const projectPath = resolve(repoRoot, rel);
+      const result = await discover(projectPath);
+      expect(result.errors).toEqual([]);
+      expect(result.entities.size).toBeGreaterThan(0);
+
+      const bundle = buildOkfBundle(result, projectPath);
+      assertConformant(bundle);
+      expect(bundle).toMatchSnapshot();
+    });
+  }
+});