@intentius/chant 0.124.12 → 0.124.14

package/dist/observation.js

@@ -0,0 +1,266 @@
+/**
+ * The observation contract (#1089) — what a lexicon's `describeResources()`
+ * is allowed to mean.
+ *
+ * Before this module there were two ways for an observation to return nothing
+ * for a declared entity and no way to tell them apart:
+ *
+ *   1. The provider was asked and said the resource does not exist.
+ *   2. The lexicon never looked — no reader for that kind, the read errored,
+ *      no credentials, no cluster/subscription binding.
+ *
+ * Both arrived at the change set as "absent", and absent + declared classifies
+ * as `create`. So `chant lifecycle plan` proposed creating a Kubernetes CRD
+ * that already existed in the cluster, with nothing in the plan to say the tool
+ * had simply not looked (a warn on stderr is not a signal in a change set).
+ *
+ * The contract is a tri-state, per declared entity:
+ *
+ *   - **OBSERVED-PRESENT** — a key in `resources`. The provider returned it.
+ *   - **OBSERVED-ABSENT** — in neither map. The lexicon looked and the provider
+ *     reported it missing. This is the only shape that may become a `create`.
+ *   - **NOT-OBSERVED** — a key in `unobserved`, carrying a total
+ *     {@link UnobservedReason}. Never a `create`, never a `delete`; consumers
+ *     surface it and stop.
+ *
+ * Compatibility: `describeResources()` may still return the bare
+ * `name → ResourceMetadata` map it always did — that means "everything I was
+ * asked about, I looked at" and normalizes to an empty `unobserved`. Reporting
+ * NOT-OBSERVED requires the explicitly versioned {@link ObservationResult}
+ * envelope, which is discriminated by its literal `observation: "v1"` field (a
+ * bare map's value at any key is a `ResourceMetadata` object, never that
+ * string, so the two shapes can never be confused).
+ */
+/**
+ * Every legal {@link UnobservedReason}, for validation and conformance checks.
+ *
+ * Derived from a witness keyed off the union rather than written out beside it
+ * (chant#2366). A hand-maintained array is only ever checked for holding legal
+ * members, never for holding ALL of them, so a reason added to the type left
+ * the array silently short — `tsc` clean, every observation test green, and a
+ * value the type permits that `observation-conformance.ts` refuses. A lexicon
+ * could construct a value its own suite rejected.
+ *
+ * Keying a `Record` off the union makes the omission a compile error at the
+ * point of the omission. This is the construction #2365 applied to all four
+ * closed sets in `./behaviour.ts`; `BEHAVIOUR_UNPREDICTED_REASONS` derives from
+ * this very type, so that module was already protected against a change here
+ * while this module was not.
+ */
+const UNOBSERVED_REASON_WITNESS = {
+    "read-failed": true,
+    "no-credentials": true,
+    "no-binding": true,
+    "unsupported-kind": true,
+    filtered: true,
+};
+export const UNOBSERVED_REASONS = Object.keys(UNOBSERVED_REASON_WITNESS);
+/** True when `value` is a legal {@link UnobservedReason}. */
+export function isUnobservedReason(value) {
+    return typeof value === "string" && UNOBSERVED_REASONS.includes(value);
+}
+/** True when `value` is the versioned {@link ObservationResult} envelope. */
+export function isObservationResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.observation === "v1");
+}
+/**
+ * Build an {@link ObservationResult}. Lexicons use this rather than writing the
+ * discriminant by hand.
+ */
+export function observation(resources, unobserved, queried, notes, stackExports, sources) {
+    return {
+        observation: "v1",
+        resources,
+        ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+        ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
+        ...(sources && Object.keys(sources).length > 0 ? { sources } : {}),
+        ...(notes && notes.length > 0 ? { notes } : {}),
+        ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+    };
+}
+/**
+ * Normalize either accepted return shape. `undefined` (a lexicon that returned
+ * nothing at all) normalizes to two empty maps — which reads as "everything was
+ * observed absent", so callers that mean "the read failed" must say so with
+ * {@link unobservedAll} rather than returning nothing.
+ */
+export function normalizeObservation(value) {
+    if (!value)
+        return { resources: {}, unobserved: {}, queried: {}, sources: {}, notes: [] };
+    if (isObservationResult(value)) {
+        return {
+            resources: value.resources ?? {},
+            unobserved: value.unobserved ?? {},
+            queried: value.queried ?? {},
+            sources: value.sources ?? {},
+            notes: [...new Set(value.notes ?? [])],
+            ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
+        };
+    }
+    return { resources: value, unobserved: {}, queried: {}, sources: {}, notes: [] };
+}
+/**
+ * Mark every named entity NOT-OBSERVED with one reason — the whole-lexicon
+ * failure case (the provider CLI is missing, the cluster binding refused, the
+ * credentials are gone). Core applies this when `describeResources()` throws,
+ * so a thrown read degrades to an honest "did not look" for each declared
+ * entity instead of an empty map that classifies as N creates.
+ */
+export function unobservedAll(names, reason, detail, types) {
+    const typeOf = (name) => {
+        if (!types)
+            return undefined;
+        if (types instanceof Map)
+            return types.get(name)?.entityType;
+        return types[name];
+    };
+    const out = {};
+    for (const name of names) {
+        const type = typeOf(name);
+        out[name] = { reason, ...(type ? { type } : {}), ...(detail ? { detail } : {}) };
+    }
+    return out;
+}
+/**
+ * Union several observations of the same lexicon (the multi-stack read, where
+ * `describeResources` runs once per stack). Precedence is
+ * present > not-observed > absent: a resource found in any stack is present; an
+ * entity nobody could look at stays not-observed; an entity every reader looked
+ * for and did not find is absent.
+ */
+export function mergeObservations(parts) {
+    const resources = {};
+    const unobserved = {};
+    const queried = {};
+    // Which read answered (#2267) merges the same way `queried` does: it is a
+    // fact about one entity's read, and the parts being merged are reads of
+    // disjoint entity sets (one per stack, or per terraform root).
+    const sources = {};
+    // A note is about the read, not a stack; four stacks saying the same thing
+    // is one note (#1265).
+    const notes = new Set();
+    const stackExports = {};
+    for (const part of parts) {
+        Object.assign(resources, part.resources);
+        Object.assign(unobserved, part.unobserved);
+        Object.assign(queried, part.queried);
+        Object.assign(sources, part.sources);
+        for (const n of part.notes)
+            notes.add(n);
+        Object.assign(stackExports, part.stackExports ?? {});
+    }
+    // Present wins: a stack that could not be read does not un-observe a resource
+    // another stack returned.
+    for (const name of Object.keys(resources))
+        delete unobserved[name];
+    return {
+        resources,
+        unobserved,
+        queried,
+        sources,
+        notes: [...notes],
+        ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+    };
+}
+/** One-line human phrasing of a reason, for CLI output. */
+export function unobservedReasonText(reason) {
+    switch (reason) {
+        case "read-failed":
+            return "read failed";
+        case "no-credentials":
+            return "no credentials";
+        case "no-binding":
+            return "no binding for this environment";
+        case "unsupported-kind":
+            return "no reader for this resource kind";
+        case "filtered":
+            return "withheld by the --owned filter";
+    }
+}
+/** `name — reason (detail) [queried address]`, the shared rendering for CLI and plan output. */
+export function formatUnobserved(name, entry) {
+    const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
+    const detailed = entry.detail ? `${base}: ${entry.detail}` : base;
+    return entry.queried ? `${detailed} [queried ${entry.queried}]` : detailed;
+}
+/** Default concurrency for {@link boundedConcurrently} when a transport ships no pool. */
+export const DEFAULT_OBSERVE_CONCURRENCY = 16;
+/**
+ * Run `fn` over `items` with at most `limit` in flight. A rejected `fn` rejects
+ * the whole run (the harness wraps per-entity reads so this stays for genuinely
+ * unexpected faults).
+ */
+export async function boundedConcurrently(items, fn, limit = DEFAULT_OBSERVE_CONCURRENCY) {
+    const queue = [...items];
+    const size = Math.max(1, Math.min(limit, queue.length || 1));
+    const workers = Array.from({ length: size }, async () => {
+        for (;;) {
+            const next = queue.shift();
+            if (next === undefined)
+                return;
+            await fn(next);
+        }
+    });
+    await Promise.all(workers);
+}
+/**
+ * The shared observer control flow (#1201). Binds via the adapter, reads every
+ * declared entity concurrently, and assembles the tri-state {@link ObservationResult}.
+ *
+ * A `bind()` throw becomes NOT-OBSERVED for every entity (typed by
+ * {@link ObserverAdapter.classifyBindFailure}) unless the adapter asks to
+ * rethrow. A per-entity `read()` throw the adapter did not itself map becomes
+ * `read-failed` for that one entity — never a silent absence, which would
+ * classify as a spurious `create`.
+ */
+export async function observeEntities(declared, adapter) {
+    const typesByName = {};
+    for (const d of declared)
+        typesByName[d.name] = d.type;
+    let client;
+    try {
+        client = await adapter.bind();
+    }
+    catch (err) {
+        const verdict = adapter.classifyBindFailure(err);
+        if (verdict === "rethrow")
+            throw err;
+        return observation({}, unobservedAll(declared.map((d) => d.name), verdict.reason, verdict.detail, typesByName));
+    }
+    const resources = {};
+    const unobserved = {};
+    const queried = {};
+    const run = adapter.concurrently ?? ((items, fn) => boundedConcurrently(items, fn));
+    await run(declared, async (entity) => {
+        let result;
+        try {
+            result = await adapter.read(client, entity);
+        }
+        catch (err) {
+            result = {
+                unobserved: {
+                    reason: "read-failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                },
+            };
+        }
+        if (result.queried)
+            queried[entity.name] = result.queried;
+        if ("present" in result) {
+            resources[entity.name] = result.present;
+        }
+        else if ("unobserved" in result) {
+            unobserved[entity.name] = {
+                type: entity.type,
+                ...result.unobserved,
+                ...(result.queried ? { queried: result.queried } : {}),
+            };
+        }
+        // `absent`: the verdict records nothing — in neither map is how the
+        // contract spells absence — but its address, when the adapter supplied
+        // one, lands in `queried` (#1620) so the absence can explain itself.
+    });
+    return observation(resources, unobserved, queried);
+}

package/dist/okf-read.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { splitFrontmatter } from "./okf.js";
+import { parseYAML } from "./yaml.js";
+/**
+ * OKF bundle reader (#1864, design #1059, epic #1057) — the input half of
+ * `./okf.ts`'s emitter: loads a project-authored knowledge bundle from disk
+ * and binds its concepts to discovered entities.
+ *
+ * Tolerant to the letter of the OKF v0.2 spec (§11), the same posture
+ * `okfConformanceProblems` enforces on the emit side: unknown `type` values
+ * and extra frontmatter keys pass through untouched, a file with unparseable
+ * or missing frontmatter is skipped with a warning, and nothing here ever
+ * rejects the bundle — a missing knowledge directory included.
+ */
+const RESERVED_OKF_FILES = new Set(["index.md", "log.md"]);
+/** `binds` accepts one name or a list (#1059); anything else is treated as "no binding" rather than rejecting the concept. */
+function normalizeBinds(value) {
+    if (typeof value === "string")
+        return value.length > 0 ? [value] : [];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === "string" && v.length > 0);
+    return [];
+}
+/** Recursively collect every `.md` file under `dir`, as bundle-relative (forward-slash) paths paired with their absolute path. */
+async function findMarkdownFiles(dir) {
+    const found = [];
+    async function scan(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: silently skip, same posture as findInfraFiles
+        }
+        for (const entry of entries) {
+            const fullPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await scan(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const relPath = relative(dir, fullPath).split(sep).join("/");
+                found.push({ relPath, fullPath });
+            }
+        }
+    }
+    await scan(dir);
+    return found;
+}
+/**
+ * Load every authored concept from an OKF knowledge bundle directory.
+ * `index.md`/`log.md` are skipped (reserved, by basename, at any depth —
+ * matching `okfConformanceProblems`'s check on the emit side). A directory
+ * that does not exist yields an empty bundle, not an error: the #1059 design
+ * treats a missing `knowledge/` as "this project has none yet," the same
+ * posture as a project with no lexicons configured.
+ *
+ * A file that fails to parse — no frontmatter block, unparseable YAML, or
+ * frontmatter that isn't a mapping — is skipped with a `console.warn` and
+ * does not affect any other file. Nothing here throws.
+ */
+export async function loadOkfBundle(dir) {
+    if (!existsSync(dir))
+        return { concepts: [] };
+    const concepts = [];
+    for (const { relPath, fullPath } of await findMarkdownFiles(dir)) {
+        if (RESERVED_OKF_FILES.has(relPath.split("/").pop()))
+            continue;
+        let content;
+        try {
+            content = await readFile(fullPath, "utf8");
+        }
+        catch {
+            console.warn(`[chant] warning: knowledge bundle concept "${relPath}" could not be read, skipping`);
+            continue;
+        }
+        const split = splitFrontmatter(content);
+        if (!split) {
+            console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has no frontmatter block, skipping`);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseYAML(split.frontmatter);
+        }
+        catch {
+            console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has unparseable frontmatter, skipping`);
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            console.warn(`[chant] warning: knowledge bundle concept "${relPath}" frontmatter is not a mapping, skipping`);
+            continue;
+        }
+        const frontmatter = parsed;
+        concepts.push({
+            path: relPath,
+            type: typeof frontmatter.type === "string" ? frontmatter.type : "",
+            title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+            binds: normalizeBinds(frontmatter.binds),
+            frontmatter,
+            body: split.body,
+        });
+    }
+    concepts.sort((a, b) => a.path.localeCompare(b.path));
+    return { concepts };
+}
+/**
+ * Resolve every concept's `binds` against a project's discovered entities.
+ * `entities` is the same shape `./okf.ts`'s emitter takes, `DiscoveryResult`'s
+ * own `entities` map — a bare logical name is unambiguous within one
+ * discovery pass (#1059's "Rejected options" on binding ambiguity).
+ *
+ * A concept with no `binds` contributes to neither `bound` nor `unresolved`;
+ * an unbound concept is legitimate, not an omission (a runbook, a decision
+ * about the project as a whole).
+ */
+export function bindConcepts(bundle, entities) {
+    const bound = new Map();
+    const unresolved = [];
+    for (const concept of bundle.concepts) {
+        for (const name of concept.binds) {
+            if (entities.has(name)) {
+                if (!bound.has(name))
+                    bound.set(name, []);
+                bound.get(name).push(concept);
+            }
+            else {
+                unresolved.push({ concept, name });
+            }
+        }
+    }
+    return { bound, unresolved };
+}

package/dist/okf.js

@@ -0,0 +1,275 @@
+import { relative, isAbsolute } from "node:path";
+import { buildGraphIr } from "./graph-ir.js";
+import { isLexiconOutput } from "./lexicon-output.js";
+import { getProvenance } from "./provenance.js";
+import { emitYAML, parseYAML } from "./yaml.js";
+/**
+ * OKF bundle emitter (#1058, epic #1057) — projects a discovered entity graph
+ * into an Open Knowledge Format v0.2 bundle: a directory of markdown files
+ * with YAML frontmatter, per the spec at
+ * https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+ *
+ * One concept document per entity, `type` carrying the entity's resource type
+ * string, dependency edges as bundle-relative markdown links (the form the
+ * spec recommends for stability), and a root `index.md` grouping concepts into
+ * per-lexicon sections. Emit-only: OKF as project *input* is #1059.
+ */
+export const OKF_VERSION = "0.2";
+/** Make an entity or lexicon name safe as a single path segment. */
+export function slug(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "");
+    return cleaned === "" ? "unnamed" : cleaned;
+}
+function relFile(file, projectPath) {
+    if (!file)
+        return undefined;
+    if (projectPath && isAbsolute(file)) {
+        const rel = relative(projectPath, file);
+        return rel.startsWith("..") ? file : rel;
+    }
+    return file;
+}
+/**
+ * Render a flat frontmatter mapping as a YAML block. Keys with undefined
+ * values are dropped; scalar quoting is `emitYAML`'s.
+ */
+export function frontmatter(fields) {
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined)
+            continue;
+        lines.push(`${key}: ${emitYAML(value, 0)}`);
+    }
+    lines.push("---");
+    return lines.join("\n");
+}
+/**
+ * Split a concept document into its frontmatter block and body. Returns
+ * undefined when the document does not start with a `---` delimited block.
+ * Exported for the conformance tests (and any future OKF consumer, #1059).
+ */
+export function splitFrontmatter(content) {
+    const lines = content.split("\n");
+    if (lines[0] !== "---")
+        return undefined;
+    const end = lines.indexOf("---", 1);
+    if (end === -1)
+        return undefined;
+    return {
+        frontmatter: lines.slice(1, end).join("\n"),
+        body: lines.slice(end + 1).join("\n"),
+    };
+}
+/**
+ * Check a bundle against the OKF v0.2 conformance criteria (spec §11) and
+ * return every violation found: parseable frontmatter on every non-reserved
+ * `.md`, a non-empty `type` everywhere, a well-formed root `index.md`, and
+ * generated cross-link entries that are bundle-absolute (or external URLs).
+ * Empty result means conformant. Shared by the project-bundle tests (#1058)
+ * and every lexicon's bundle tests (#1060).
+ */
+export function okfConformanceProblems(files) {
+    const problems = [];
+    const reserved = new Set(["index.md", "log.md"]);
+    const linkTarget = /\]\(([^)]+)\)/g;
+    const externalOrAbsolute = (target) => target.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(target);
+    for (const file of files) {
+        if (!file.path.endsWith(".md"))
+            problems.push(`${file.path}: not a markdown file`);
+        if (file.path.startsWith("/") || file.path.includes("..")) {
+            problems.push(`${file.path}: path is not bundle-relative`);
+        }
+        if (reserved.has(file.path.split("/").pop()))
+            continue;
+        const split = splitFrontmatter(file.content);
+        if (!split) {
+            problems.push(`${file.path}: no frontmatter block`);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseYAML(split.frontmatter);
+        }
+        catch {
+            problems.push(`${file.path}: unparseable frontmatter`);
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null) {
+            problems.push(`${file.path}: frontmatter is not a mapping`);
+            continue;
+        }
+        const type = parsed.type;
+        if (typeof type !== "string" || type.length === 0) {
+            problems.push(`${file.path}: frontmatter has no non-empty type`);
+        }
+        // Cross-link entries (the "- [name](target)" lines the emitters generate)
+        // must point inside the bundle or at an external URL. Broken targets are
+        // permitted (not-yet-written knowledge); malformed ones are not. Free-text
+        // knowledge bodies may carry arbitrary links and are not checked.
+        for (const line of split.body.split("\n")) {
+            if (!line.trimStart().startsWith("- ["))
+                continue;
+            for (const match of line.matchAll(linkTarget)) {
+                if (!externalOrAbsolute(match[1])) {
+                    problems.push(`${file.path}: link target "${match[1]}" is neither bundle-absolute nor external`);
+                }
+            }
+        }
+    }
+    const index = files.find((f) => f.path === "index.md");
+    if (!index) {
+        problems.push("bundle has no root index.md");
+        return problems;
+    }
+    const split = splitFrontmatter(index.content);
+    if (!split) {
+        problems.push("index.md: no frontmatter block");
+        return problems;
+    }
+    const parsed = parseYAML(split.frontmatter);
+    for (const key of Object.keys(parsed ?? {})) {
+        if (key !== "okf_version")
+            problems.push(`index.md: frontmatter carries "${key}" — okf_version is the only key an index is allowed`);
+    }
+    for (const line of split.body.split("\n")) {
+        if (line.startsWith("*") && !/^\* \[[^\]]+\]\([^)]+\) - .+$/.test(line)) {
+            problems.push(`index.md: malformed entry line: ${line}`);
+        }
+    }
+    return problems;
+}
+/**
+ * The `type`/`lexicon`/`kind` a concept carries. Most entities state all
+ * three; a `LexiconOutput` (an `output(...)` bridge) carries none of them
+ * directly, so its facts come from its producing side — `type` must be
+ * non-empty for the bundle to conform, never blank.
+ */
+function conceptFacts(entity) {
+    if (isLexiconOutput(entity)) {
+        const out = entity;
+        return { type: "Output", lexicon: out.sourceLexicon || "unknown", kind: "output" };
+    }
+    return {
+        type: entity.entityType || "Entity",
+        lexicon: entity.lexicon || "unknown",
+        kind: entity.kind ?? "resource",
+    };
+}
+/**
+ * Build the OKF bundle for a discovered graph. Pure and deterministic: the
+ * same entities yield byte-identical files, so bundles are diffable and
+ * snapshot-testable. `projectPath` relativizes source-file paths so the
+ * bundle is portable.
+ */
+export function buildOkfBundle(input, projectPath) {
+    // Assign each entity a stable concept path: <lexicon>/<name>.md, deduped
+    // when slugging collides two distinct names.
+    const concepts = new Map();
+    const takenPaths = new Set();
+    const names = [...input.entities.keys()].sort((a, b) => a.localeCompare(b));
+    for (const name of names) {
+        const entity = input.entities.get(name);
+        const facts = conceptFacts(entity);
+        const base = `${slug(facts.lexicon)}/${slug(name)}`;
+        let path = `${base}.md`;
+        for (let n = 2; takenPaths.has(path); n++)
+            path = `${base}-${n}.md`;
+        takenPaths.add(path);
+        concepts.set(name, { name, entity, path, ...facts });
+    }
+    // Dependency edges: the graph IR's AttrRef/Ref-derived edges (the same
+    // derivation `chant graph --format ir` ships) unioned with discovery's
+    // declared dependency map — the map alone misses references that live only
+    // in attribute values.
+    const dependsOn = new Map();
+    const addEdge = (from, to) => {
+        if (!dependsOn.has(from))
+            dependsOn.set(from, new Set());
+        dependsOn.get(from).add(to);
+    };
+    for (const edge of buildGraphIr(input.entities, projectPath).edges)
+        addEdge(edge.from, edge.to);
+    for (const [from, deps] of input.dependencies)
+        for (const to of deps)
+            addEdge(from, to);
+    // Reverse edges: who references each entity.
+    const referencedBy = new Map();
+    for (const [from, deps] of dependsOn) {
+        for (const to of deps) {
+            if (!referencedBy.has(to))
+                referencedBy.set(to, []);
+            referencedBy.get(to).push(from);
+        }
+    }
+    const files = [];
+    for (const name of names) {
+        const concept = concepts.get(name);
+        const { entity } = concept;
+        const prov = getProvenance(entity);
+        const source = relFile(prov?.sourceFile, projectPath);
+        const head = frontmatter({
+            type: concept.type,
+            title: name,
+            description: `${concept.lexicon} ${concept.kind} of type ${concept.type}`,
+            name,
+            lexicon: concept.lexicon,
+            kind: concept.kind,
+            source,
+            composite: prov?.composite,
+            composite_instance: prov?.compositeInstance,
+        });
+        const body = [""];
+        body.push(source ? `Declared in \`${source}\`.` : `Declared by the ${concept.lexicon} lexicon.`);
+        // Cross-resource references become bundle-relative links. A dependency
+        // whose target is not in the bundle still emits a link — the spec permits
+        // broken links (not-yet-written knowledge), so unresolved never fails.
+        const deps = [...(dependsOn.get(name) ?? [])].sort((a, b) => a.localeCompare(b));
+        if (deps.length > 0) {
+            body.push("", "## Depends on", "");
+            for (const dep of deps) {
+                const target = concepts.get(dep)?.path ?? `${slug(dep)}.md`;
+                body.push(`- [${dep}](/${target})`);
+            }
+        }
+        const consumers = (referencedBy.get(name) ?? []).sort((a, b) => a.localeCompare(b));
+        if (consumers.length > 0) {
+            body.push("", "## Referenced by", "");
+            for (const consumer of consumers) {
+                const target = concepts.get(consumer)?.path ?? `${slug(consumer)}.md`;
+                body.push(`- [${consumer}](/${target})`);
+            }
+        }
+        body.push("");
+        files.push({ path: concept.path, content: head + body.join("\n") });
+    }
+    files.push({ path: "index.md", content: buildIndex(concepts, names) });
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return files;
+}
+/**
+ * The bundle-root `index.md` (spec §8): one section per lexicon, each entry a
+ * bundle-relative link plus the concept's description — the spec's
+ * progressive-disclosure mechanism. Root indexes may carry `okf_version`
+ * frontmatter (spec §12), the only frontmatter an index is allowed.
+ */
+function buildIndex(concepts, names) {
+    const byLexicon = new Map();
+    for (const name of names) {
+        const concept = concepts.get(name);
+        if (!byLexicon.has(concept.lexicon))
+            byLexicon.set(concept.lexicon, []);
+        byLexicon.get(concept.lexicon).push(concept);
+    }
+    const lines = ["---", `okf_version: '${OKF_VERSION}'`, "---", ""];
+    const lexicons = [...byLexicon.keys()].sort((a, b) => a.localeCompare(b));
+    for (const lexicon of lexicons) {
+        lines.push(`# Lexicon: ${lexicon}`, "");
+        for (const concept of byLexicon.get(lexicon)) {
+            lines.push(`* [${concept.name}](/${concept.path}) - ${lexicon} ${concept.kind} of type ${concept.type}`);
+        }
+        lines.push("");
+    }
+    if (lexicons.length === 0)
+        lines.push("No entities discovered.", "");
+    return lines.join("\n");
+}