@metaobjectsdev/metadata 0.9.0-rc.1 → 0.10.0

package/src/metamodel-docs/index.ts

@@ -0,0 +1,41 @@
+// FR-033 S3 — metamodel doc-gen public surface.
+//
+// Documents the METAMODEL ITSELF (the type/subtype/attr vocabulary of the strict
+// registry) as tiered, LLM-readable markdown — distinct from `meta docs --model`
+// (which documents a user's entities). The renderer is a pure, deterministic
+// function over the composed registry + a provenance lens; file I/O lives in the
+// CLI.
+
+import type { TypeRegistry } from "../registry.js";
+import { coreProviders } from "../core-types.js";
+import { buildMetamodelProvenance, type MetamodelProvenance } from "./provenance.js";
+import { renderMetamodelDocs } from "./render.js";
+
+export { buildMetamodelProvenance, renderMetamodelDocs };
+export type { MetamodelProvenance } from "./provenance.js";
+
+/**
+ * Build the provider-id → description map from the core provider bundle. The
+ * descriptions live on the provider objects (not the embedded definitions), so
+ * the provenance builder takes them as input; this assembles the default map
+ * for the standard `coreProviders` composition.
+ */
+export function coreProviderDescriptions(): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const p of coreProviders) {
+    if (p.description !== undefined) map.set(p.id, p.description);
+  }
+  return map;
+}
+
+/**
+ * One-shot convenience: build the provenance lens (with the core provider
+ * descriptions) and render the full metamodel doc tree from a composed registry.
+ * The CLI uses this; tests can call the lower-level pieces directly.
+ */
+export function renderCoreMetamodelDocs(registry: TypeRegistry): Map<string, string> {
+  const provenance: MetamodelProvenance = buildMetamodelProvenance(registry, {
+    providerDescriptions: coreProviderDescriptions(),
+  });
+  return renderMetamodelDocs(registry, provenance);
+}

package/src/metamodel-docs/provenance.ts

@@ -0,0 +1,187 @@
+// FR-033 S3 — metamodel provenance: who owns each type and who contributes each attr.
+//
+// The composed registry knows WHAT vocabulary exists but not WHICH of the five
+// concern providers declared each piece — that fact is flattened away at
+// registration. We recover it from the embedded `ProviderDefinition`s:
+//
+//   • a definition's `types[]` (non-universal entries) declare the `type.subType`s
+//     that provider OWNS (registers), plus the attrs that ride INLINE on them;
+//   • a definition's `extends[]` declare attrs a CONCERN provider contributes to a
+//     type another provider owns (subType selector `"*"` / list / single);
+//   • the universal `*.*` entry's attr children are COMMON attrs (documentation).
+//
+// The `"*"` extend selector is resolved against the LIVE registry's registered
+// subtypes, so a concern attr added to "every field" is attributed on every
+// concrete field subtype the doc renderer walks.
+
+import type { TypeRegistry } from "../registry.js";
+import type { ProviderDefinition, TypeDef, ChildDef } from "../provider-data.js";
+import { CHILD_RULE_WILDCARD } from "../shared/structural.js";
+import { isExcludedTypeSubType } from "../registry-manifest-exclusions.js";
+import { ALL_PROVIDER_DEFINITIONS } from "./provider-definitions.js";
+
+const ATTR_CHILD_TYPE = "attr";
+
+/** A `(type, subType)` key, identical to the registry's internal key form. */
+function typeKey(type: string, subType: string): string {
+  return `${type}.${subType}`;
+}
+
+/** A `(type, subType, attrName)` key for the attr-provenance map. */
+function attrKey(type: string, subType: string, attrName: string): string {
+  return `${type}.${subType}.${attrName}`;
+}
+
+function isUniversal(t: TypeDef): boolean {
+  return t.type === CHILD_RULE_WILDCARD && t.subType === CHILD_RULE_WILDCARD;
+}
+
+function isAttrChild(c: ChildDef): boolean {
+  return c.type === ATTR_CHILD_TYPE;
+}
+
+/**
+ * The provenance lens: maps each registered type/attr back to its owning /
+ * contributing provider id, and the inverse (a provider → what it owns +
+ * contributes). Built once from the embedded definitions + the live registry.
+ */
+export interface MetamodelProvenance {
+  /** Provider id that REGISTERS (owns) this `type.subType`, or undefined. */
+  ownerOfType(type: string, subType: string): string | undefined;
+  /** Provider id that declared/contributed this attr on this `type.subType`. */
+  ownerOfAttr(type: string, subType: string, attrName: string): string | undefined;
+  /** Provider id that contributed this common (universal) attr. */
+  ownerOfCommonAttr(attrName: string): string | undefined;
+  /** The provider id → its description (from the embedded definition). */
+  providerDescription(providerId: string): string | undefined;
+  /** All provider ids that declared anything, sorted. */
+  providerIds(): string[];
+  /** The `type.subType`s a provider OWNS (registers), sorted. */
+  typesOwnedBy(providerId: string): string[];
+  /** The `(type.subType → [attrName])` a provider CONTRIBUTES via extends/inline, sorted. */
+  attrsContributedBy(providerId: string): { typeSubType: string; attrs: string[] }[];
+  /** Common attr names a provider contributes (universal), sorted. */
+  commonAttrsBy(providerId: string): string[];
+}
+
+/**
+ * Build the provenance lens from the embedded provider definitions + a composed
+ * registry (the registry resolves `"*"` extend selectors to concrete subtypes).
+ *
+ * The provider descriptions are read from the embedded definitions indirectly:
+ * a `ProviderDefinition` carries only `provider` (the id), so descriptions come
+ * from a small registry-keyed lookup the caller can override; here we accept the
+ * descriptions the provider objects expose by mapping id → the first non-empty
+ * description we can derive. To keep this module pure + dependency-light, the
+ * provider descriptions are supplied via `providerDescriptions`.
+ */
+export function buildMetamodelProvenance(
+  registry: TypeRegistry,
+  opts?: { providerDescriptions?: ReadonlyMap<string, string> },
+): MetamodelProvenance {
+  const ownerType = new Map<string, string>();
+  const ownerAttr = new Map<string, string>();
+  const ownerCommon = new Map<string, string>();
+
+  // Inverse indexes for the provider lens.
+  const ownedByProvider = new Map<string, Set<string>>();
+  const contributedByProvider = new Map<string, Map<string, Set<string>>>();
+  const commonByProvider = new Map<string, Set<string>>();
+  const providerSet = new Set<string>();
+
+  const note = (id: string) => {
+    providerSet.add(id);
+    if (!ownedByProvider.has(id)) ownedByProvider.set(id, new Set());
+    if (!contributedByProvider.has(id)) contributedByProvider.set(id, new Map());
+    if (!commonByProvider.has(id)) commonByProvider.set(id, new Set());
+  };
+
+  const recordContribution = (id: string, type: string, subType: string, attr: string) => {
+    const k = attrKey(type, subType, attr);
+    // First declarer wins (an attr is contributed by exactly one provider).
+    if (!ownerAttr.has(k)) ownerAttr.set(k, id);
+    const byType = contributedByProvider.get(id)!;
+    const tk = typeKey(type, subType);
+    if (!byType.has(tk)) byType.set(tk, new Set());
+    byType.get(tk)!.add(attr);
+  };
+
+  for (const def of ALL_PROVIDER_DEFINITIONS) {
+    const id = def.provider;
+    note(id);
+
+    for (const t of def.types ?? []) {
+      if (isUniversal(t)) {
+        // Universal `*.*` entry → common attrs, owned by this provider.
+        for (const c of t.children ?? []) {
+          if (isAttrChild(c)) {
+            if (!ownerCommon.has(c.name)) ownerCommon.set(c.name, id);
+            commonByProvider.get(id)!.add(c.name);
+          }
+        }
+        continue;
+      }
+      // A real type this provider OWNS (registers).
+      const tk = typeKey(t.type, t.subType);
+      if (!ownerType.has(tk)) ownerType.set(tk, id);
+      // The provider lens ("Owns (registers)" on providers.md) advertises the
+      // SAME agreed vocabulary INDEX/type pages cover — skip the manifest-
+      // excluded rows (the TS-web-presentation `view.*` controls) so all three
+      // doc surfaces share one consistent set. (`ownerType` still records the
+      // raw owner for any internal lookup; only the published list is filtered.)
+      if (!isExcludedTypeSubType(t.type, t.subType)) ownedByProvider.get(id)!.add(tk);
+      // Inline attrs on an owned type are contributed by the same provider.
+      for (const c of t.children ?? []) {
+        if (isAttrChild(c)) recordContribution(id, t.type, t.subType, c.name);
+      }
+    }
+
+    // `extends[]` — a concern provider's attrs added to types another provider owns.
+    for (const ext of def.extends ?? []) {
+      const subTypes = resolveExtendSubTypes(registry, ext.type, ext.subType);
+      for (const subType of subTypes) {
+        for (const c of ext.children) {
+          if (isAttrChild(c)) recordContribution(id, ext.type, subType, c.name);
+        }
+      }
+    }
+  }
+
+  const descriptions = opts?.providerDescriptions ?? new Map<string, string>();
+
+  const sorted = (s: Set<string>): string[] => [...s].sort(compare);
+
+  return {
+    ownerOfType: (type, subType) => ownerType.get(typeKey(type, subType)),
+    ownerOfAttr: (type, subType, attrName) => ownerAttr.get(attrKey(type, subType, attrName)),
+    ownerOfCommonAttr: (attrName) => ownerCommon.get(attrName),
+    providerDescription: (providerId) => descriptions.get(providerId),
+    providerIds: () => [...providerSet].sort(compare),
+    typesOwnedBy: (providerId) => sorted(ownedByProvider.get(providerId) ?? new Set()),
+    attrsContributedBy: (providerId) => {
+      const byType = contributedByProvider.get(providerId) ?? new Map();
+      return [...byType.entries()]
+        .map(([typeSubType, attrs]) => ({
+          typeSubType,
+          attrs: sorted(attrs as Set<string>),
+        }))
+        .sort((a, b) => compare(a.typeSubType, b.typeSubType));
+    },
+    commonAttrsBy: (providerId) => sorted(commonByProvider.get(providerId) ?? new Set()),
+  };
+}
+
+/** Resolve an extend `subType` selector to concrete registered subtypes. */
+function resolveExtendSubTypes(
+  registry: TypeRegistry,
+  type: string,
+  selector: string | readonly string[],
+): readonly string[] {
+  if (selector === CHILD_RULE_WILDCARD) return registry.allSubTypesOf(type);
+  return Array.isArray(selector) ? selector : [selector as string];
+}
+
+/** ASCII codepoint compare — locale-independent, byte-stable. */
+function compare(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/metamodel-docs/provider-definitions.ts

@@ -0,0 +1,50 @@
+// FR-033 S3 — the full set of embedded ProviderDefinitions, in one place.
+//
+// Provenance (which of the concern providers owns/contributes each type/attr)
+// is NOT carried on the composed registry — it is flattened away when providers
+// register. The embedded definition modules ARE the source of that fact: each
+// `ProviderDefinition.provider` says who declared it, its `types[]` say which
+// `type.subType`s it registers (owns), and its `extends[]` say which attrs it
+// contributes to types another provider owns. This module re-exports every
+// embedded definition as one list so the provenance builder can walk them
+// without each consumer re-importing all fifteen.
+
+import type { ProviderDefinition } from "../provider-data.js";
+import { FIELD_DEFINITION } from "../core/field/field-definition.embedded.js";
+import { OBJECT_DEFINITION } from "../core/object/object-definition.embedded.js";
+import { ATTR_DEFINITION } from "../core/attr/attr-definition.embedded.js";
+import { VALIDATOR_DEFINITION } from "../core/validator/validator-definition.embedded.js";
+import { IDENTITY_DEFINITION } from "../core/identity/identity-definition.embedded.js";
+import { RELATIONSHIP_DEFINITION } from "../core/relationship/relationship-definition.embedded.js";
+import { DOCUMENTATION_DEFINITION } from "../core/documentation/documentation-definition.embedded.js";
+import { ORIGIN_DEFINITION } from "../persistence/origin/origin-definition.embedded.js";
+import { SOURCE_DEFINITION } from "../persistence/source/source-definition.embedded.js";
+import { DB_DEFINITION } from "../persistence/db/db-definition.embedded.js";
+import { VIEW_DEFINITION } from "../presentation/view/view-definition.embedded.js";
+import { LAYOUT_DEFINITION } from "../presentation/layout/layout-definition.embedded.js";
+import { UI_DEFINITION } from "../presentation/ui/ui-definition.embedded.js";
+import { TEMPLATE_DEFINITION } from "../template/template-definition.embedded.js";
+import { PROMPT_DEFINITION } from "../template/prompt-definition.embedded.js";
+
+/**
+ * Every embedded provider definition the core metamodel composes from. The
+ * order is irrelevant — the provenance builder keys by `(type.subType, attr)`,
+ * and the registry is the authority on what is actually registered.
+ */
+export const ALL_PROVIDER_DEFINITIONS: readonly ProviderDefinition[] = [
+  FIELD_DEFINITION,
+  OBJECT_DEFINITION,
+  ATTR_DEFINITION,
+  VALIDATOR_DEFINITION,
+  IDENTITY_DEFINITION,
+  RELATIONSHIP_DEFINITION,
+  DOCUMENTATION_DEFINITION,
+  ORIGIN_DEFINITION,
+  SOURCE_DEFINITION,
+  DB_DEFINITION,
+  VIEW_DEFINITION,
+  LAYOUT_DEFINITION,
+  UI_DEFINITION,
+  TEMPLATE_DEFINITION,
+  PROMPT_DEFINITION,
+];

package/src/metamodel-docs/render.ts

@@ -0,0 +1,309 @@
+// FR-033 S3 — the metamodel doc renderer (pure, deterministic, byte-stable).
+//
+// Documents the METAMODEL ITSELF — the type/subtype/attr vocabulary of the
+// strict registry — for an LLM (and humans). This is distinct from `meta docs
+// --model`, which documents a USER's entities. The output is a tiered markdown
+// tree:
+//
+//   INDEX.md          every type.subType + one-liner + link  (always-on map)
+//   types/<type>.md   per family: each subtype's full composed attrs (provider-
+//                     tagged) + allowed children + cardinality + parents
+//   providers.md      the 5-concern ownership index (the provider lens)
+//
+// Rendering is plain deterministic TS string-building: the metadata package
+// owns no codegen-ts / Mustache dependency, and the output is small + fully
+// structural, so a self-contained string builder is simpler and keeps the
+// byte-stability contract trivially auditable. Everything is sorted by ASCII
+// codepoint for cross-run / cross-port determinism.
+
+import type { AttrSchema, ChildRule, TypeDefinition, TypeRegistry } from "../registry.js";
+import type { MetamodelProvenance } from "./provenance.js";
+import { isExcludedTypeSubType } from "../registry-manifest-exclusions.js";
+import { ATTR_SUBTYPE_STRINGARRAY, ATTR_SUBTYPE_STRING } from "../core/attr/attr-constants.js";
+import { CHILD_RULE_WILDCARD } from "../shared/structural.js";
+import { SUBTYPE_BASE } from "../shared/base-types.js";
+
+/** The regeneration command, named in every file's DO-NOT-EDIT header. */
+const REGEN_COMMAND = "meta docs --metamodel";
+
+/** ASCII codepoint compare — locale-independent, byte-stable. */
+function compare(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** The DO-NOT-EDIT header prepended to every emitted file. */
+function header(what: string): string {
+  return (
+    `<!-- @generated — DO NOT EDIT.\n` +
+    `     ${what}\n` +
+    `     Regenerate with: ${REGEN_COMMAND} -->\n`
+  );
+}
+
+/** Escape a markdown table cell: collapse newlines, escape pipes. */
+function cell(s: string): string {
+  return s.replace(/\r?\n/g, " ").replace(/\|/g, "\\|").trim();
+}
+
+/** The anchor GitHub assigns to a `### field.currency` heading: `fieldcurrency`. */
+function anchor(type: string, subType: string): string {
+  return `${type}${subType}`.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/** The scalar value-type + array suffix the docs show for an attr. */
+function attrTypeLabel(attr: AttrSchema): string {
+  const isLegacyStringArray = attr.valueType === ATTR_SUBTYPE_STRINGARRAY;
+  const isArray = attr.isArray === true || isLegacyStringArray;
+  const scalar = isLegacyStringArray
+    ? ATTR_SUBTYPE_STRING
+    : (attr.valueType ?? "any");
+  return isArray ? `${scalar}[]` : scalar;
+}
+
+/** Render one attr value (default / an allowed value) as an inline-code token. */
+function valueToken(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  return `\`${String(v)}\``;
+}
+
+/** The childSubType cell: a single subtype, a `*`, or a comma-joined list. */
+function childSubTypeLabel(childSubType: string | readonly string[]): string {
+  return Array.isArray(childSubType) ? childSubType.join(", ") : (childSubType as string);
+}
+
+/** A cardinality range `min..max` (`*` for unbounded / undefined upper). */
+function cardinality(rule: ChildRule): string {
+  const min = rule.min ?? 0;
+  const max = rule.max === null || rule.max === undefined ? "*" : String(rule.max);
+  return `${min}..${max}`;
+}
+
+/** Whether a child rule is a STRUCTURAL child (not an attr — attrs live in the table). */
+function isStructuralChild(rule: ChildRule): boolean {
+  return rule.childType !== "attr";
+}
+
+/**
+ * Render the per-subtype Attributes table. Columns:
+ *   Attribute | Type | Required | Default | Allowed values | Provider | Description
+ * Sorted by attr name; common (universal documentation) attrs are excluded
+ * (mentioned once on the providers page) to keep per-type pages lean.
+ */
+function attrsTable(
+  def: TypeDefinition,
+  provenance: MetamodelProvenance,
+  commonAttrNames: ReadonlySet<string>,
+): string {
+  const rows = def.attributes
+    .filter((a) => !commonAttrNames.has(a.name))
+    .slice()
+    .sort((a, b) => compare(a.name, b.name));
+  if (rows.length === 0) return "_No subtype-specific attributes._\n";
+
+  const lines: string[] = [
+    "| Attribute | Type | Required | Default | Allowed values | Provider | Description |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
+  ];
+  for (const a of rows) {
+    // Resolve the contributing provider. An attr inherited from `<type>.base`
+    // (FR-033 `extendsBase`) is recorded against the BASE in the embedded data,
+    // not the concrete subtype — so fall back to the base owner when the
+    // subtype-specific lookup misses. (`base` itself has no further fallback.)
+    const provider =
+      provenance.ownerOfAttr(def.typeId.type, def.typeId.subType, a.name) ??
+      provenance.ownerOfAttr(def.typeId.type, SUBTYPE_BASE, a.name) ??
+      "—";
+    const allowed = (a.allowedValues ?? []).map(valueToken).join(", ");
+    lines.push(
+      `| \`@${a.name}\` | ${attrTypeLabel(a)} | ${a.required ? "yes" : "no"} | ` +
+        `${valueToken(a.default)} | ${allowed} | ${provider} | ${cell(a.description)} |`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Render the Allowed children list (structural child rules), sorted. */
+function childrenList(def: TypeDefinition): string {
+  const structural = def.childRules
+    .filter(isStructuralChild)
+    .slice()
+    .sort(
+      (a, b) =>
+        compare(a.childType, b.childType) ||
+        compare(childSubTypeLabel(a.childSubType), childSubTypeLabel(b.childSubType)) ||
+        compare(a.childName, b.childName),
+    );
+  if (structural.length === 0) return "_No structural children._\n";
+  const lines = structural.map((r) => {
+    const nameSuffix =
+      r.childName === CHILD_RULE_WILDCARD ? "" : ` (name \`${r.childName}\`)`;
+    return `- \`${r.childType}.${childSubTypeLabel(r.childSubType)}\`${nameSuffix} — ${cardinality(r)}`;
+  });
+  return `${lines.join("\n")}\n`;
+}
+
+/** Render one subtype section on a type-family page. */
+function subtypeSection(
+  def: TypeDefinition,
+  provenance: MetamodelProvenance,
+  commonAttrNames: ReadonlySet<string>,
+): string {
+  const { type, subType } = def.typeId;
+  const owner = provenance.ownerOfType(type, subType);
+  const parts: string[] = [`### ${type}.${subType}\n`];
+  parts.push(`${def.description}\n`);
+  if (owner !== undefined) parts.push(`**Owning provider:** ${owner}\n`);
+  if (def.rules !== undefined) parts.push(`**Rules:** ${def.rules}\n`);
+  if (def.whenToUse !== undefined) parts.push(`**When to use:** ${def.whenToUse}\n`);
+  if (def.example !== undefined) parts.push(`**Example:**\n\n\`\`\`\n${def.example}\n\`\`\`\n`);
+
+  parts.push(`**Attributes**\n`);
+  parts.push(attrsTable(def, provenance, commonAttrNames));
+
+  parts.push(`**Allowed children**\n`);
+  parts.push(childrenList(def));
+
+  if (def.parents !== undefined && def.parents.length > 0) {
+    const ps = [...def.parents].sort(compare).map((p) => `\`${p}\``).join(", ");
+    parts.push(`**Parents:** ${ps}\n`);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * The registered (type, subType) definitions the metamodel docs cover — every
+ * registered pair EXCEPT the ones the registry-conformance manifest carves out
+ * (TS-web-presentation `view.*` controls + the `metadata.base` inheritance
+ * anchor) so the docs describe exactly the agreed cross-port vocabulary.
+ */
+function coveredDefs(registry: TypeRegistry): TypeDefinition[] {
+  return registry
+    .allTypes()
+    .filter((id) => !isExcludedTypeSubType(id.type, id.subType))
+    .map((id) => registry.find(id.type, id.subType) as TypeDefinition)
+    .sort((a, b) =>
+      compare(
+        `${a.typeId.type}.${a.typeId.subType}`,
+        `${b.typeId.type}.${b.typeId.subType}`,
+      ),
+    );
+}
+
+/** Render INDEX.md — the always-on map: every type.subType + one-liner + link. */
+function renderIndex(defs: readonly TypeDefinition[]): string {
+  const lines: string[] = [
+    header("Metamodel vocabulary index — every type.subType, its one-line description, and a link to its type page."),
+    "# MetaObjects Metamodel — Index\n",
+    "This documents the **metamodel itself** — the type / subtype / attribute",
+    "vocabulary the loader accepts — generated from the strict registry. It is",
+    "NOT documentation of a user's entities (that is `meta docs --model`).\n",
+    "Follow a link into `types/<family>.md` for the full attribute table, allowed",
+    "children, and cardinality of a subtype. Universal documentation attributes",
+    "(`@description`/`@title`/…) apply to every node and are listed once in",
+    "[providers.md](providers.md) under `metaobjects-documentation`.\n",
+    "| Type.subType | Description | Page |",
+    "| --- | --- | --- |",
+  ];
+  for (const def of defs) {
+    const { type, subType } = def.typeId;
+    const link = `[types/${type}.md#${anchor(type, subType)}](types/${type}.md#${anchor(type, subType)})`;
+    lines.push(`| \`${type}.${subType}\` | ${cell(def.description)} | ${link} |`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Render one types/<family>.md page from that family's subtype definitions. */
+function renderTypePage(
+  family: string,
+  defs: readonly TypeDefinition[],
+  provenance: MetamodelProvenance,
+  commonAttrNames: ReadonlySet<string>,
+): string {
+  const parts: string[] = [
+    header(`Metamodel reference for the \`${family}\` type family — each subtype's composed attributes, allowed children, and cardinality.`),
+    `# Metamodel — \`${family}\` types\n`,
+    `Each section below is one \`${family}.<subType>\`. The **Attributes** table lists`,
+    `the subtype's own + concern-contributed attributes (provider-tagged); universal`,
+    `documentation attributes are omitted here (see [providers.md](../providers.md)).`,
+    `**Allowed children** lists the structural child rules with their cardinality`,
+    `(\`min..max\`, \`*\` = unbounded).\n`,
+  ];
+  for (const def of defs) {
+    parts.push(subtypeSection(def, provenance, commonAttrNames));
+  }
+  return `${parts.join("\n")}\n`;
+}
+
+/** Render providers.md — the 5-concern ownership index (the provider lens). */
+function renderProviders(provenance: MetamodelProvenance): string {
+  const parts: string[] = [
+    header("Concern-provider ownership index — which provider owns each type and contributes each attribute."),
+    "# MetaObjects Metamodel — Providers\n",
+    "The metamodel is composed from concern providers. Each **owns** the",
+    "type/subtypes it registers and may **contribute** attributes to types another",
+    "provider owns. This is the ownership lens over the same vocabulary",
+    "[INDEX.md](INDEX.md) lists by type.\n",
+  ];
+  for (const id of provenance.providerIds()) {
+    parts.push(`## ${id}\n`);
+    const desc = provenance.providerDescription(id);
+    if (desc !== undefined) parts.push(`${desc}\n`);
+
+    const owned = provenance.typesOwnedBy(id);
+    if (owned.length > 0) {
+      parts.push(`**Owns (registers):** ${owned.map((t) => `\`${t}\``).join(", ")}\n`);
+    }
+
+    const common = provenance.commonAttrsBy(id);
+    if (common.length > 0) {
+      parts.push(
+        `**Universal attributes (every node):** ${common.map((a) => `\`@${a}\``).join(", ")}\n`,
+      );
+    }
+
+    const contributed = provenance.attrsContributedBy(id);
+    if (contributed.length > 0) {
+      parts.push(`**Contributes attributes:**\n`);
+      const lines = contributed.map(
+        (c) => `- \`${c.typeSubType}\`: ${c.attrs.map((a) => `\`@${a}\``).join(", ")}`,
+      );
+      parts.push(`${lines.join("\n")}\n`);
+    }
+  }
+  return `${parts.join("\n")}\n`;
+}
+
+/**
+ * Render the full metamodel doc tree (pure + deterministic). Returns a
+ * `Map<relativePath, markdown>` keyed by:
+ *   `INDEX.md`, `providers.md`, `types/<family>.md`.
+ *
+ * The registry must already be composed (`composeRegistry(coreProviders)`); the
+ * provenance lens is built once (`buildMetamodelProvenance`) and threaded in.
+ */
+export function renderMetamodelDocs(
+  registry: TypeRegistry,
+  provenance: MetamodelProvenance,
+): Map<string, string> {
+  const defs = coveredDefs(registry);
+  const commonAttrNames = new Set(registry.getCommonAttrs().map((a) => a.name));
+
+  const out = new Map<string, string>();
+  out.set("INDEX.md", renderIndex(defs));
+  out.set("providers.md", renderProviders(provenance));
+
+  // Group by type family, sorted within + across.
+  const byFamily = new Map<string, TypeDefinition[]>();
+  for (const def of defs) {
+    const fam = def.typeId.type;
+    if (!byFamily.has(fam)) byFamily.set(fam, []);
+    byFamily.get(fam)!.push(def);
+  }
+  for (const fam of [...byFamily.keys()].sort(compare)) {
+    out.set(
+      `types/${fam}.md`,
+      renderTypePage(fam, byFamily.get(fam)!, provenance, commonAttrNames),
+    );
+  }
+  return out;
+}