@metaobjectsdev/codegen-ts 0.24.5 → 1.0.0-rc.1

package/dist/generators/agent-docs-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-docs-file.d.ts","sourceRoot":"","sources":["../../src/generators/agent-docs-file.ts"],"names":[],"mappings":"AA6DA,OAAO,KAAK,EAAE,oBAAoB,EAAyB,MAAM,0BAA0B,CAAC;AAC5F,OAAO,KAAK,EAA0B,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAOhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAuHD,eAAO,MAAM,aAAa,EA0FrB,gBAAgB,CAAC,iBAAiB,CAAC,CAAC"}

package/dist/generators/agent-docs-file.js

@@ -0,0 +1,257 @@
+// agentDocsFile() — the `agent` docs surface.
+//
+// Three pages under `agent/`, each one an agent reads BEFORE touching a tier:
+//
+//   • `agent/schema.md`       — before touching persistence
+//   • `agent/ui.md`           — before touching a form or a grid
+//   • `agent/requirements.md` — before adding a capability
+//
+// (`api/AGENT-API.md`, the fourth file the always-on pointer names, is the api surface's
+// and is emitted by `apiDocsFile()`. It is not duplicated here.)
+//
+// EVERY PAGE IS DERIVED FROM AN EXISTING BUILDER, and that is the design constraint
+// rather than an implementation detail. A documentation surface an agent is told to
+// TRUST has to be true, and the only way to keep three more pages true is to give them
+// no derivation of their own:
+//
+//   schema        ← the expected-schema snapshot `meta migrate` diffs and emits from
+//                   (injected; see agent-schema-input.ts for why codegen-ts refuses to
+//                   compute it) + `resolveObjectNames`, the field→column resolver the
+//                   names artifact and the DDL already share
+//   ui            ← `buildEntityUiDescriptor`, the same derivation emitted as the
+//                   `<Entity>` const that `useEntityForm` reads at runtime
+//   requirements  ← `walkRequirements` + `requirementRows`, the same walk the ledger
+//                   surface and the generated test stubs are built on
+//
+// CONFIG-GATED, like the api surface. Physical names, the dialect and view dispatch all
+// depend on the gen config, so `meta docs` only selects this surface when it has one.
+// The NEUTRAL model surface stays neutral (ADR-0020); this is a different surface with a
+// different contract, not a relaxation of that one.
+//
+// AN EMPTY PAGE IS NO FILE. Each renderer returns "" when its tier has nothing to
+// describe — no physical schema, no UI, no ledger — and an empty render emits nothing.
+// That is what makes the surface safe to leave on: a headless project with no ledger sees
+// no `agent/` directory rather than three pages of headings.
+//
+// These files are READ, never imported. There is no three-way merge and no hand-edit
+// preservation to think about: regenerate and the page is current.
+import { CARDINALITY_MANY, CARDINALITY_ONE, FIELD_SUBTYPE_ENUM, ORIGIN_AGGREGATE_ATTR_AGG, ORIGIN_AGGREGATE_ATTR_OF, ORIGIN_AGGREGATE_ATTR_VIA, ORIGIN_ATTR_ORDER_BY, ORIGIN_PASSTHROUGH_ATTR_FROM, ORIGIN_PASSTHROUGH_ATTR_VIA, ORIGIN_SUBTYPE_AGGREGATE, ORIGIN_SUBTYPE_COMPUTED, ORIGIN_SUBTYPE_FIRST, ORIGIN_SUBTYPE_PASSTHROUGH, RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_ON_DELETE, RELATIONSHIP_ATTR_THROUGH, PHYSICAL_NAME_ATTR_BY_KIND, SOURCE_ROLE_PRIMARY, TYPE_ORIGIN, resolveColumnName, } from "@metaobjectsdev/metadata";
+import { resolveObjectNames } from "../names.js";
+import { isAbstract } from "../instance-artifacts.js";
+import { enumValues, intValueMapOf } from "../enum-meta.js";
+import { renderAgentSchemaPage } from "./agent-schema-page.js";
+import { renderAgentUiPage } from "./agent-ui-page.js";
+import { renderAgentRequirementsPage } from "./agent-requirements-page.js";
+/** All three pages live here, under the docs root. */
+const DEFAULT_AGENT_DIR = "agent";
+/** One `origin.*` child rendered as a lineage phrase. `origin.*` NEVER inherits, so the
+ *  own-accessor read here is the correct one rather than an ADR-0039 slip. */
+function lineageOf(field) {
+    const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
+    if (origin === undefined)
+        return undefined;
+    const str = (name) => {
+        const v = origin.attr(name);
+        return typeof v === "string" && v !== "" ? v : undefined;
+    };
+    switch (origin.subType) {
+        case ORIGIN_SUBTYPE_PASSTHROUGH: {
+            const from = str(ORIGIN_PASSTHROUGH_ATTR_FROM);
+            const via = str(ORIGIN_PASSTHROUGH_ATTR_VIA);
+            return `passthrough from \`${from ?? "?"}\`${via === undefined ? "" : ` via \`${via}\``}`;
+        }
+        case ORIGIN_SUBTYPE_AGGREGATE: {
+            const agg = str(ORIGIN_AGGREGATE_ATTR_AGG) ?? "?";
+            const of = str(ORIGIN_AGGREGATE_ATTR_OF);
+            const via = str(ORIGIN_AGGREGATE_ATTR_VIA);
+            return `\`${agg}\`${of === undefined ? "" : ` of \`${of}\``}${via === undefined ? "" : ` via \`${via}\``}`;
+        }
+        case ORIGIN_SUBTYPE_FIRST: {
+            const of = str(ORIGIN_AGGREGATE_ATTR_OF);
+            const via = str(ORIGIN_AGGREGATE_ATTR_VIA);
+            const order = str(ORIGIN_ATTR_ORDER_BY);
+            return `first${of === undefined ? "" : ` \`${of}\``}${via === undefined ? "" : ` via \`${via}\``}` +
+                `${order === undefined ? "" : ` ordered by \`${order}\``}`;
+        }
+        case ORIGIN_SUBTYPE_COMPUTED:
+            // The @expr tree is structured; naming it is enough to route a reader to the
+            // declaration, and rendering a tree into a cell would be a second SQL lowering.
+            return "computed from a declared `@expr`";
+        default:
+            return `\`origin.${origin.subType}\``;
+    }
+}
+/**
+ * The cardinality phrase, from the DECLARING object's side.
+ *
+ * `@cardinality: one` does NOT mean one-to-one. It means this object holds the foreign
+ * key — many rows of it point at one target row — which is what `relation-resolver.ts`
+ * builds a belongs-to `one()` relation from. Rendering it as "one-to-one" told a reader
+ * the target row is claimed by at most one row here, which is the direction that makes
+ * someone write a lookup expecting a single result.
+ *
+ * `@cardinality` is OPTIONAL vocabulary (min 0), and ABSENT is its own answer: no
+ * navigation is generated at all. Folding that into "one-to-one" invented a shape the
+ * model never declared.
+ */
+function cardinalityPhrase(cardinality, through) {
+    if (cardinality === CARDINALITY_MANY) {
+        return typeof through === "string" && through !== "" ? "many-to-many" : "one-to-many";
+    }
+    if (cardinality === CARDINALITY_ONE)
+        return "many-to-one";
+    return "cardinality not declared";
+}
+/** `- \`Order.lines\` — one-to-many → \`OrderLine\`` */
+function relationshipLines(objects) {
+    const out = [];
+    for (const obj of objects) {
+        for (const rel of obj.relationships()) {
+            const cardinality = rel.attr(RELATIONSHIP_ATTR_CARDINALITY);
+            const target = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
+            const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
+            const onDelete = rel.attr(RELATIONSHIP_ATTR_ON_DELETE);
+            // The FQN, not the short name: this line is an ADDRESS a reader searches for.
+            const parts = [`\`${obj.resolutionKey()}.${rel.name}\``, `\`${rel.subType}\``];
+            parts.push(`${cardinalityPhrase(cardinality, through)} → \`${String(target ?? "?")}\``);
+            if (typeof through === "string" && through !== "")
+                parts.push(`through \`${through}\``);
+            if (typeof onDelete === "string" && onDelete !== "")
+                parts.push(`on delete \`${onDelete}\``);
+            out.push(`- ${parts.join(" · ")}`);
+        }
+    }
+    return out;
+}
+/**
+ * `| \`Order.status\` | OPEN, CLOSED | string-backed |`
+ *
+ * `objects` IS ONLY THE TABLE-BACKED SUBSET OF THE MODEL — the caller scopes it to the
+ * objects the snapshot actually holds as tables. This section sits on the SCHEMA page, so
+ * every row it prints is read as a statement about a column. Walking every loaded object
+ * printed rows for abstract bases, for `object.value`s that have no column anywhere, and
+ * for projections whose "column" is a view expression — three kinds of thing the physical
+ * schema does not contain.
+ *
+ * It also says nothing about a `CHECK`. Whether the database constrains the members is
+ * `table.checks`, which is already on this page from the snapshot, and an `@isArray`
+ * enum deliberately gets none (`migrate-ts` skips it) — so asserting one here was a
+ * SECOND derivation of a fact the page already carries correctly, in the direction that
+ * promises the database will refuse a value it will accept.
+ */
+function enumLines(objects) {
+    const rows = [];
+    for (const obj of objects) {
+        for (const field of obj.fields()) {
+            if (field.subType !== FIELD_SUBTYPE_ENUM)
+                continue;
+            const members = enumValues(field);
+            if (members === undefined || members.length === 0)
+                continue;
+            const intMap = intValueMapOf(field);
+            const backing = intMap === undefined
+                ? "string-backed"
+                : `int-backed (${members.map((m) => `${m}=${intMap[m]}`).join(", ")})`;
+            rows.push(`| \`${obj.resolutionKey()}.${field.name}\` | ${members.map((m) => `\`${m}\``).join(", ")} | ${backing} |`);
+        }
+    }
+    if (rows.length === 0)
+        return [];
+    return ["| Field | Members | Storage |", "|---|---|---|", ...rows];
+}
+export const agentDocsFile = function agentDocsFile(opts) {
+    const dir = (opts?.subDir ?? DEFAULT_AGENT_DIR).replace(/\/$/, "");
+    const generator = {
+        name: "agent-docs",
+        generate(ctx) {
+            const objects = ctx.loadedRoot.objects();
+            const files = [];
+            // ---- schema.md
+            if (opts?.schema !== undefined) {
+                const schema = opts.schema;
+                // The qualified names the snapshot actually holds. An object whose physical name
+                // is not one of these contributes nothing to the physical schema (an abstract
+                // base, a sourceless value, an `@unmanaged` object) and must not appear on a page
+                // describing it — `buildExpectedSchema`'s Pass 1 owns those skip rules and this
+                // reads its answer rather than re-deriving them.
+                const tableNames = new Set(schema.tables.map((t) => schema.qualify(t)));
+                const viewNames = new Set(schema.views.map((v) => schema.qualify(v)));
+                // The objects backed by a TABLE in the snapshot — the enum section's scope, since
+                // a row there is read as a statement about a column.
+                const tableBacked = [];
+                // column → declaring field, per qualified table name. `resolveObjectNames` is the
+                // ONE field→column resolver — the same one the names artifact and the DDL use —
+                // so this mapping cannot disagree with the column it labels.
+                const declaredBy = new Map();
+                const viewLineage = new Map();
+                for (const obj of objects) {
+                    const names = resolveObjectNames(obj, opts.columnNamingStrategy);
+                    // The PRIMARY source's physical name and schema — `names.name` is the object's
+                    // metamodel name since 0.25.0, which would match nothing in the snapshot.
+                    const primary = names?.sources[SOURCE_ROLE_PRIMARY];
+                    const physical = primary === undefined
+                        ? undefined
+                        : primary[(PHYSICAL_NAME_ATTR_BY_KIND.get(primary.kind) ?? "")];
+                    if (typeof physical !== "string")
+                        continue;
+                    const key = schema.qualify({ name: physical, schema: primary?.schema });
+                    const isTable = tableNames.has(key);
+                    if (!isTable && !viewNames.has(key))
+                        continue;
+                    // ABSTRACT BASES ARE EXCLUDED, and being in the snapshot does not exempt them:
+                    // an abstract base that declares the `source.rdb` its concrete child inherits
+                    // resolves to that child's table, so the qualified-name test admits it and the
+                    // page printed the base's enum a second time under a different owner.
+                    // `buildExpectedSchema`'s Pass 1 skips abstracts; this reads the same rule.
+                    if (isTable && !isAbstract(obj))
+                        tableBacked.push(obj);
+                    let map = declaredBy.get(key);
+                    if (map === undefined) {
+                        map = new Map();
+                        declaredBy.set(key, map);
+                    }
+                    const lineage = [];
+                    for (const field of obj.fields()) {
+                        const column = resolveColumnName(field, opts.columnNamingStrategy);
+                        // A TPH base and its subtypes share one table: first writer wins, so the
+                        // base's own column keeps its label rather than being relabelled by whichever
+                        // subtype was walked last.
+                        if (!map.has(column)) {
+                            map.set(column, { field: field.name, type: `${field.type}.${field.subType}` });
+                        }
+                        const line = lineageOf(field);
+                        if (line !== undefined)
+                            lineage.push(`| \`${column}\` | ${line} |`);
+                    }
+                    if (lineage.length > 0)
+                        viewLineage.set(key, lineage);
+                }
+                const content = renderAgentSchemaPage(schema, {
+                    declaredBy,
+                    viewLineage,
+                    relationships: relationshipLines(objects),
+                    enums: enumLines(tableBacked),
+                });
+                if (content !== "")
+                    files.push({ path: `${dir}/schema.md`, content });
+            }
+            // ---- ui.md
+            // The apiPrefix is the project's, from the render context the runner built — the
+            // same value `routes-file.ts` emits as the SERVER mount prefix. Without it the page
+            // names an address nothing serves. (The client descriptor no longer carries it: a
+            // browser's base URL is supplied at runtime by the provider's `baseUrl`.)
+            const ui = renderAgentUiPage(ctx.loadedRoot, ctx.renderContext?.apiPrefix ?? "");
+            if (ui !== "")
+                files.push({ path: `${dir}/ui.md`, content: ui });
+            // ---- requirements.md
+            const requirements = renderAgentRequirementsPage(ctx.loadedRoot);
+            if (requirements !== "")
+                files.push({ path: `${dir}/requirements.md`, content: requirements });
+            return files;
+        },
+    };
+    if (opts?.target)
+        generator.target = opts.target;
+    return generator;
+};
+//# sourceMappingURL=agent-docs-file.js.map

package/dist/generators/agent-docs-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-docs-file.js","sourceRoot":"","sources":["../../src/generators/agent-docs-file.ts"],"names":[],"mappings":"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"}

package/dist/generators/agent-requirements-page.d.ts

@@ -0,0 +1,22 @@
+import type { MetaData } from "@metaobjectsdev/metadata";
+interface NodeIndexEntry {
+    readonly address: string;
+    readonly concern: string;
+    readonly claims: {
+        path: string;
+        subType: string;
+        level: number | undefined;
+        status: string | undefined;
+        statement: string | undefined;
+    }[];
+}
+/** Invert the walk: claimed node → the requirements that claim it. */
+export declare function buildNodeIndex(root: MetaData): NodeIndexEntry[];
+/**
+ * Render the page. Returns "" for a model declaring no requirements — the same contract
+ * `requirementsFile()` keeps, and the only reason a surface that is on by default is a
+ * no-op for a project without a ledger.
+ */
+export declare function renderAgentRequirementsPage(root: MetaData): string;
+export {};
+//# sourceMappingURL=agent-requirements-page.d.ts.map

package/dist/generators/agent-requirements-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-requirements-page.d.ts","sourceRoot":"","sources":["../../src/generators/agent-requirements-page.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAiCzD,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,CAAC;CAC5I;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE,CAqB/D;AAWD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAsFlE"}

package/dist/generators/agent-requirements-page.js

@@ -0,0 +1,175 @@
+// `agent/requirements.md` — the ledger, plus the index that answers the question an agent
+// actually asks.
+//
+// The `requirements` docs surface is REQUIREMENT-KEYED: it lists entries and, under each,
+// what the entry claims. That is the right shape for reading a ledger and the wrong shape
+// for the question that arises while editing code — *"I am about to change this node; does
+// anything claim it?"* Answering that from the requirement-keyed page means reading all of
+// it, which for this repository's own ledger is 175 rows.
+//
+// So this page carries the same index PLUS a NODE index: every claimed node → the
+// requirements claiming it, at every grain. It is an inversion of `walkRequirements`, not
+// a second walk — the same resolution, read the other way, so the two indexes cannot
+// disagree about what resolves.
+//
+// LITERAL FQNs ON EVERY LINE, deliberately and even where it is repetitive. An agent
+// retrieving over a long context finds a node by matching the token it is holding; a row
+// that says "the field above" is unreachable to it. This is also why the node index is
+// FLAT rather than nested under its owning object.
+//
+// A CLAIM THAT DOES NOT RESOLVE IS OMITTED, silently, exactly as `walkRequirements` omits
+// it. Resolution severity depends on `@status` and belongs to `meta verify`; a docs page
+// that rendered a dangling reference as though it pointed somewhere would be asserting
+// the opposite of what the gate says.
+//
+// THE LEDGER IS EMBEDDED BELOW THE INDEX, and that duplication is deliberate rather than
+// an oversight — the same content also lives at `requirements.md` when that surface is on.
+// The node index alone would omit exactly the entries the mechanism is MEASURED on: a
+// `retired` capability may carry no `@implementedBy` at all (FR-039 forbids it), so it
+// resolves to no node and appears in no node index. The one controlled finding behind this
+// whole vocabulary is that a retired capability goes unnoticed without a ledger — 0 of 24
+// against 19 of 40 — and the page an agent is told to read *before adding a capability* is
+// the last place to drop it. The cost is bytes on a large estate; the alternative is a page
+// that silently loses the only part with evidence behind it.
+import { REQUIREMENT_ATTR_STATEMENT } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { concernOf, walkRequirements } from "../requirement-walk.js";
+import { requirementRows } from "./requirements-view.js";
+import { renderRequirementsMarkdown } from "./requirements-markdown.js";
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+/**
+ * The address of any claimed node: the ROOT node's `resolutionKey()` (which carries the
+ * effective package), then the child-name path down to it.
+ *
+ * Built by walking parents rather than read off the node, because only a root-level node
+ * has a resolution key — a claimed FIELD has a bare name, and `Subscriber.status` and
+ * `Order.status` would collide in this index if the owner were dropped.
+ */
+function nodeAddress(node) {
+    const segments = [];
+    let cur = node;
+    while (cur !== undefined) {
+        const parent = cur.parent;
+        // The last node with a parent is the root-level one; the metadata ROOT itself has no
+        // name worth printing, so the walk stops when the next step would leave the model.
+        if (parent === undefined || parent.parent === undefined) {
+            segments.push(cur.resolutionKey());
+            break;
+        }
+        segments.push(cur.name);
+        cur = parent;
+    }
+    return segments.reverse().join(".");
+}
+/** Invert the walk: claimed node → the requirements that claim it. */
+export function buildNodeIndex(root) {
+    const byAddress = new Map();
+    for (const walked of walkRequirements(root)) {
+        const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
+        for (const target of walked.targets) {
+            const address = nodeAddress(target.node);
+            let entry = byAddress.get(address);
+            if (entry === undefined) {
+                entry = { address, concern: concernOf(target.node), claims: [] };
+                byAddress.set(address, entry);
+            }
+            entry.claims.push({
+                path: walked.view.path,
+                subType: walked.view.subType,
+                level: walked.view.level,
+                status: walked.view.status,
+                statement: typeof statement === "string" && statement !== "" ? statement : undefined,
+            });
+        }
+    }
+    return [...byAddress.values()].sort((a, b) => a.address.localeCompare(b.address));
+}
+function mdCell(text) {
+    return text.replace(/\|/g, "\\|");
+}
+/** Collapse to one line — a statement with a newline in it would end the table row. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * Render the page. Returns "" for a model declaring no requirements — the same contract
+ * `requirementsFile()` keeps, and the only reason a surface that is on by default is a
+ * no-op for a project without a ledger.
+ */
+export function renderAgentRequirementsPage(root) {
+    const rows = requirementRows(root);
+    if (rows.length === 0)
+        return "";
+    const index = buildNodeIndex(root);
+    const out = [];
+    out.push(GENERATED_MARKER);
+    out.push("");
+    out.push("# Requirements");
+    out.push("");
+    out.push("Read this before adding a capability, and before extending anything that looks like " +
+        "it already does what you were asked for.");
+    out.push("");
+    out.push("- A requirement is **prescriptive**: it states what should be true, never what " +
+        "happened. `status: retired` means the capability was BUILT and deliberately " +
+        "REMOVED — that entry is a prohibition, not history, and the right response to it " +
+        "is to stop, not to rebuild.");
+    out.push("- The **node index** below answers *\"does anything claim the thing I am about to " +
+        "change?\"*. Match the literal FQN.");
+    out.push("- **The ledger under it is not the same list.** A retired capability carries no " +
+        "`@implementedBy` — there is nothing left to point at — so it appears there and " +
+        "in no index. Read it before you conclude a capability does not exist yet.");
+    out.push("");
+    if (index.length > 0) {
+        out.push("## Node index");
+        out.push("");
+        out.push("| Node | Kind | Claimed by |");
+        out.push("|---|---|---|");
+        for (const entry of index) {
+            const claims = entry.claims
+                .map((c) => {
+                const level = c.level === undefined ? "" : ` L${c.level}`;
+                const status = c.status === undefined ? "" : ` (${c.status})`;
+                return `\`${c.path}\`${level}${status}`;
+            })
+                .join("<br>");
+            out.push(`| \`${entry.address}\` | \`${entry.concern}\` | ${claims} |`);
+        }
+        out.push("");
+        // The statements ride below the table: they are prose, they repeat across nodes a
+        // shared architectural entry claims, and putting one in a cell forces the table wide.
+        const stated = new Map();
+        for (const entry of index) {
+            for (const c of entry.claims) {
+                if (c.statement !== undefined)
+                    stated.set(c.path, { subType: c.subType, statement: c.statement });
+            }
+        }
+        if (stated.size > 0) {
+            out.push("### What those requirements say");
+            out.push("");
+            for (const [path, { subType, statement }] of [...stated.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+                out.push(`- \`${path}\` (\`${subType}\`) — ${mdCell(oneLine(statement))}`);
+            }
+            out.push("");
+        }
+    }
+    else {
+        out.push("## Node index");
+        out.push("");
+        out.push("No requirement resolves to a model node. The common reason is the ordinary one: an " +
+            "entry at L4 or L5 that simply declares no `@implementedBy` yet, which is legal " +
+            "and is what a `planned` entry looks like. The others are an entry sitting ABOVE " +
+            "the L4 link floor (where a claim is not permitted), a `retired` entry (where it " +
+            "is forbidden outright), and a claim that names a node nothing resolves — " +
+            "`meta verify` is what says which.");
+        out.push("");
+    }
+    out.push("## The ledger");
+    out.push("");
+    // The SAME renderer the `requirements` surface uses. A second rendering of the ledger
+    // would be a second thing to keep true. `embedded` drops its own H1 and demotes every
+    // heading one level, so the entries nest under this section instead of escaping it.
+    out.push(renderRequirementsMarkdown(rows, { embedded: true }).replace(/\n+$/, ""));
+    return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}
+//# sourceMappingURL=agent-requirements-page.js.map

package/dist/generators/agent-requirements-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-requirements-page.js","sourceRoot":"","sources":["../../src/generators/agent-requirements-page.ts"],"names":[],"mappings":"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"}

package/dist/generators/agent-schema-input.d.ts

@@ -0,0 +1,69 @@
+/** A canonical SQL type as `migrate-ts` models it. Opaque here — only `columnType` reads it. */
+export interface SchemaColumnLike {
+    readonly name: string;
+    readonly nullable: boolean;
+    readonly default?: {
+        readonly kind: "literal" | "expr";
+        readonly value: string;
+    } | undefined;
+    readonly identity?: "increment" | "uuid" | undefined;
+    /** Threaded from the field's `@description` — the business semantics beside the column. */
+    readonly description?: string | undefined;
+}
+export interface SchemaIndexLike {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    readonly where?: string | undefined;
+    readonly expr?: string | undefined;
+    readonly using?: string | undefined;
+}
+export interface SchemaFkLike {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: string | undefined;
+    readonly onUpdate?: string | undefined;
+}
+export interface SchemaCheckLike {
+    readonly name: string;
+    readonly expression: string;
+}
+export interface SchemaTableLike {
+    readonly name: string;
+    readonly schema?: string | undefined;
+    readonly columns: readonly SchemaColumnLike[];
+    readonly indexes: readonly SchemaIndexLike[];
+    readonly foreignKeys: readonly SchemaFkLike[];
+    readonly checks: readonly SchemaCheckLike[];
+    readonly primaryKey: readonly string[];
+    /** Threaded from the entity's `@description`. */
+    readonly description?: string | undefined;
+}
+export interface SchemaViewLike {
+    readonly name: string;
+    readonly schema?: string | undefined;
+    readonly columns?: readonly {
+        readonly name: string;
+    }[] | undefined;
+}
+/**
+ * Everything `agent/schema.md` renders from, plus the two resolvers it refuses to own.
+ */
+export interface AgentSchemaInput {
+    /** `postgres` | `sqlite` | `d1` — named on the page so a reader knows which SQL they are reading. */
+    readonly dialect: string;
+    readonly tables: readonly SchemaTableLike[];
+    readonly views: readonly SchemaViewLike[];
+    /** Qualified physical name → the declaring object's `resolutionKey()`. */
+    readonly provenance: ReadonlyMap<string, string>;
+    /** `migrate-ts`'s `columnTypeSql`, bound to `dialect`. */
+    readonly columnType: (column: SchemaColumnLike) => string;
+    /** `migrate-ts`'s `qualifiedDbName` — the ONE key the provenance map is built with. */
+    readonly qualify: (obj: {
+        name: string;
+        schema?: string | undefined;
+    }) => string;
+}
+//# sourceMappingURL=agent-schema-input.d.ts.map

package/dist/generators/agent-schema-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-schema-input.d.ts","sourceRoot":"","sources":["../../src/generators/agent-schema-input.ts"],"names":[],"mappings":"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"}

package/dist/generators/agent-schema-input.js

@@ -0,0 +1,23 @@
+// The `agent/schema.md` surface's INPUT contract — the physical schema, supplied by
+// whoever owns it.
+//
+// codegen-ts does not compute any of this and must not. The expected schema, the
+// dialect SQL type of a column, and the qualified name a table is keyed by are all
+// `@metaobjectsdev/migrate-ts`'s answers: it builds the snapshot the diff compares, it
+// renders the DDL, and its `qualifiedDbName` is the one key three separate suppression
+// sets already agree on. Re-deriving any of them here would give an adopter a page
+// describing a schema the tool does not produce — and the disagreement would be
+// invisible, because a documentation page looks authoritative and nothing compares it
+// to the migration.
+//
+// So the surface takes the schema as an ARGUMENT, with the resolvers injected. The
+// types below are structural on purpose: `migrate-ts`'s own `SchemaSnapshot`,
+// `TableDescriptor` and `ColumnDescriptor` satisfy them without codegen-ts taking a
+// dependency on that package (it has none today, and the docs surface is not a reason
+// to add one — `meta docs` in the CLI depends on both and is where they meet).
+//
+// ABSENT INPUT IS A SUPPORTED STATE, not a failure. `meta docs` runs without a gen
+// config, and a project with no dialect has no physical schema to describe; the surface
+// then emits nothing rather than a page full of unknowns.
+export {};
+//# sourceMappingURL=agent-schema-input.js.map

package/dist/generators/agent-schema-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-schema-input.js","sourceRoot":"","sources":["../../src/generators/agent-schema-input.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,mBAAmB;AACnB,EAAE;AACF,iFAAiF;AACjF,mFAAmF;AACnF,uFAAuF;AACvF,uFAAuF;AACvF,mFAAmF;AACnF,gFAAgF;AAChF,sFAAsF;AACtF,oBAAoB;AACpB,EAAE;AACF,mFAAmF;AACnF,8EAA8E;AAC9E,oFAAoF;AACpF,sFAAsF;AACtF,+EAA+E;AAC/E,EAAE;AACF,mFAAmF;AACnF,wFAAwF;AACxF,0DAA0D"}

package/dist/generators/agent-schema-page.d.ts

@@ -0,0 +1,21 @@
+import type { AgentSchemaInput } from "./agent-schema-input.js";
+export interface AgentSchemaPageOptions {
+    /** Column → declaring field, per QUALIFIED table name. Supplied by the generator, which
+     *  holds the loaded model; see `agentDocsFile`. */
+    readonly declaredBy: ReadonlyMap<string, ReadonlyMap<string, {
+        field: string;
+        type: string;
+    }>>;
+    /** Per-projection lineage lines, keyed by QUALIFIED view name. */
+    readonly viewLineage: ReadonlyMap<string, readonly string[]>;
+    /** Relationship lines, already rendered from the model. */
+    readonly relationships: readonly string[];
+    /** Enum lines, already rendered from the model. */
+    readonly enums: readonly string[];
+}
+/**
+ * Render the whole page. Returns "" when there is no physical schema at all, which is
+ * what lets the surface emit no FILE rather than a page describing nothing.
+ */
+export declare function renderAgentSchemaPage(input: AgentSchemaInput, opts: AgentSchemaPageOptions): string;
+//# sourceMappingURL=agent-schema-page.d.ts.map

package/dist/generators/agent-schema-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-schema-page.d.ts","sourceRoot":"","sources":["../../src/generators/agent-schema-page.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,gBAAgB,EAKjB,MAAM,yBAAyB,CAAC;AAsIjC,MAAM,WAAW,sBAAsB;IACrC;uDACmD;IACnD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC/F,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC7D,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,sBAAsB,GAC3B,MAAM,CAiHR"}