@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/src/registry-coverage.ts

@@ -0,0 +1,430 @@
+// SP-G Unit 5 — untested-vocabulary coverage report.
+//
+// Cross-references the REGISTERED metamodel vocabulary (the canonical
+// registry-conformance manifest — "what SHOULD be exercised") against the
+// conformance FIXTURE corpora ("what IS exercised"), and surfaces every
+// registered (type, subType) — and each attr — that NO fixture exercises.
+//
+// This closes the meta-gap that let SP-C's vocabulary drift hide for weeks: a
+// drifted/missing vocabulary member was only caught incidentally, if some
+// fixture happened to use it. Making the *untested* set VISIBLE is the
+// deliverable. The registry-conformance gate (Unit 1) proves the vocabulary is
+// IDENTICAL across ports; this report proves the vocabulary is EXERCISED at all.
+//
+// Pure + testable: takes the parsed manifest + a set of fixture roots, walks the
+// canonical-JSON node graph (nodes keyed `"<type>.<subType>"`, `@attr` inline
+// keys, reserved bare keys, nested `children`), and returns the registered /
+// exercised / untested sets — all deterministic + sorted.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ATTR_PREFIX,
+  RESERVED_KEYS,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "./shared/structural.js";
+
+// ---------------------------------------------------------------------------
+// Manifest shape (a structural subset of fixtures/registry-conformance schema)
+// ---------------------------------------------------------------------------
+
+/** One attr in the registry manifest. */
+export interface ManifestAttr {
+  name: string;
+  valueType: string | null;
+  required: boolean;
+}
+
+/** One registered (type, subType) with its declared attrs. */
+export interface ManifestType {
+  type: string;
+  subType: string;
+  attrs: ManifestAttr[];
+}
+
+/** The canonical registry manifest (expected-registry.json). */
+export interface RegistryManifest {
+  types: ManifestType[];
+  commonAttrs: ManifestAttr[];
+  defaultSubTypes: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Coverage result
+// ---------------------------------------------------------------------------
+
+/** Per-subtype attr coverage: which declared attrs no fixture sets. */
+export interface UntestedAttrs {
+  /** The `"<type>.<subType>"` key. */
+  key: string;
+  /** Sorted attr names declared on this subtype that NO fixture exercises. */
+  untestedAttrs: string[];
+}
+
+/** The full coverage report — all collections sorted for determinism. */
+export interface CoverageReport {
+  /** Total registered `(type, subType)` keys. */
+  registeredSubTypeCount: number;
+  /** Registered keys at least one fixture exercises. */
+  exercisedSubTypeCount: number;
+  /** Sorted registered keys NO fixture exercises (the valuable backlog). */
+  untestedSubTypes: string[];
+  /**
+   * Per EXERCISED subtype, the declared attrs no fixture sets. Only includes
+   * subtypes that ARE exercised (an untested subtype's attrs are all untested
+   * by definition — listing them would be noise). Sorted by key; only entries
+   * with a non-empty `untestedAttrs` list are included.
+   */
+  untestedAttrsByExercisedSubType: UntestedAttrs[];
+}
+
+/** The snapshot written to disk — a stable, diffable subset of the report. */
+export interface CoverageSnapshot {
+  registeredSubTypeCount: number;
+  exercisedSubTypeCount: number;
+  untestedSubTypes: string[];
+  untestedAttrsByExercisedSubType: UntestedAttrs[];
+}
+
+// ---------------------------------------------------------------------------
+// Fixture-corpus scanning
+// ---------------------------------------------------------------------------
+
+/** What a single fixture corpus exercises. */
+interface Usage {
+  /** Set of `"<type>.<subType>"` keys seen in any fixture node. */
+  subTypes: Set<string>;
+  /** key → set of attr names (sans `@` prefix) set on a node of that subtype. */
+  attrsByKey: Map<string, Set<string>>;
+}
+
+function newUsage(): Usage {
+  return { subTypes: new Set<string>(), attrsByKey: new Map<string, Set<string>>() };
+}
+
+/** Recursively collect every *.json file path under a directory root. */
+function collectJsonFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return; // missing/unreadable dir — skip (a corpus root may not exist)
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry);
+      let st: ReturnType<typeof statSync>;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (st.isFile() && entry.endsWith(".json")) {
+        out.push(full);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/** True if a node-body key is a `"<type>.<subType>"` wrapper key. */
+function isTypeSubTypeKey(key: string): boolean {
+  // A wrapper key fuses type + subType with the separator. Reserved structural
+  // keys, `@`-attrs, and the JSON `$schema` key are NOT wrapper keys.
+  if (key.startsWith(ATTR_PREFIX)) return false;
+  if (RESERVED_KEYS.has(key)) return false;
+  if (!key.includes(TYPE_SUBTYPE_SEPARATOR)) return false;
+  if (key.startsWith("$")) return false;
+  // Must be exactly `type.subType` (one separator, two non-empty halves).
+  const idx = key.indexOf(TYPE_SUBTYPE_SEPARATOR);
+  const type = key.slice(0, idx);
+  const subType = key.slice(idx + TYPE_SUBTYPE_SEPARATOR.length);
+  return type.length > 0 && subType.length > 0 && !subType.includes(TYPE_SUBTYPE_SEPARATOR);
+}
+
+/**
+ * Record one node-body: its inline `@attrs` (against the owning wrapper key) and
+ * recurse into its children. `body` is the object under a wrapper key.
+ */
+function visitBody(body: unknown, ownerKey: string, usage: Usage): void {
+  if (body === null || typeof body !== "object" || Array.isArray(body)) return;
+  const obj = body as Record<string, unknown>;
+
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith(ATTR_PREFIX)) {
+      // An inline attr on this node. Strip the prefix → the logical attr name.
+      const attrName = k.slice(ATTR_PREFIX.length);
+      let set = usage.attrsByKey.get(ownerKey);
+      if (!set) {
+        set = new Set<string>();
+        usage.attrsByKey.set(ownerKey, set);
+      }
+      set.add(attrName);
+    } else if (k === "children") {
+      visitNodeList(v, usage);
+    }
+    // Reserved bare keys (name/package/extends/value/...) are not attrs — skip.
+    // (`value` may hold nested arbitrary data, not metamodel nodes — skip it.)
+  }
+}
+
+/** Visit an array of wrapper-keyed nodes (the `children` list, or a root list). */
+function visitNodeList(list: unknown, usage: Usage): void {
+  if (!Array.isArray(list)) return;
+  for (const item of list) {
+    visitNode(item, usage);
+  }
+}
+
+/**
+ * Visit one wrapper-keyed node object: `{ "<type>.<subType>": { ...body } }`.
+ * A single object may carry multiple wrapper keys; handle each.
+ */
+function visitNode(node: unknown, usage: Usage): void {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return;
+  const obj = node as Record<string, unknown>;
+  for (const [key, body] of Object.entries(obj)) {
+    if (isTypeSubTypeKey(key)) {
+      usage.subTypes.add(key);
+      visitBody(body, key, usage);
+    } else if (key === "children") {
+      // Some corpora nest a bare `children` list at a level without a wrapper.
+      visitNodeList(body, usage);
+    }
+  }
+}
+
+/**
+ * Parse one fixture JSON document and fold its vocabulary usage into `usage`.
+ * The document root is the metadata.root wrapper (or, defensively, an array or
+ * a bare node). Robust to non-metadata JSON (e.g. CAPABILITIES.json) — such a
+ * doc simply contributes no wrapper keys.
+ */
+function scanDocument(text: string, usage: Usage): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return; // not JSON / malformed — contributes nothing
+  }
+  if (Array.isArray(parsed)) {
+    visitNodeList(parsed, usage);
+  } else {
+    visitNode(parsed, usage);
+  }
+}
+
+/** Scan a set of corpus roots, unioning vocabulary usage across all of them. */
+export function scanFixtureUsage(roots: readonly string[]): Usage {
+  const usage = newUsage();
+  for (const root of roots) {
+    for (const file of collectJsonFiles(root)) {
+      let text: string;
+      try {
+        text = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      scanDocument(text, usage);
+    }
+  }
+  return usage;
+}
+
+// ---------------------------------------------------------------------------
+// Coverage computation
+// ---------------------------------------------------------------------------
+
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Compute the untested-vocabulary coverage report.
+ *
+ * @param manifest the parsed registry manifest (the registered vocabulary)
+ * @param roots    fixture-corpus directory roots to scan for usage
+ */
+export function computeCoverage(
+  manifest: RegistryManifest,
+  roots: readonly string[],
+): CoverageReport {
+  const usage = scanFixtureUsage(roots);
+
+  const registeredKeys = manifest.types.map(
+    (t) => `${t.type}${TYPE_SUBTYPE_SEPARATOR}${t.subType}`,
+  );
+
+  const untestedSubTypes = registeredKeys
+    .filter((key) => !usage.subTypes.has(key))
+    .sort(compareStrings);
+
+  const exercisedSubTypeCount = registeredKeys.length - untestedSubTypes.length;
+
+  // Per EXERCISED subtype, which declared attrs no fixture sets.
+  const untestedAttrsByExercisedSubType: UntestedAttrs[] = [];
+  for (const t of manifest.types) {
+    const key = `${t.type}${TYPE_SUBTYPE_SEPARATOR}${t.subType}`;
+    if (!usage.subTypes.has(key)) continue; // skip untested subtypes (all-untested by definition)
+    if (t.attrs.length === 0) continue;
+    const seen = usage.attrsByKey.get(key) ?? new Set<string>();
+    const untestedAttrs = t.attrs
+      .map((a) => a.name)
+      .filter((name) => !seen.has(name))
+      .sort(compareStrings);
+    if (untestedAttrs.length > 0) {
+      untestedAttrsByExercisedSubType.push({ key, untestedAttrs });
+    }
+  }
+  untestedAttrsByExercisedSubType.sort((a, b) => compareStrings(a.key, b.key));
+
+  return {
+    registeredSubTypeCount: registeredKeys.length,
+    exercisedSubTypeCount,
+    untestedSubTypes,
+    untestedAttrsByExercisedSubType,
+  };
+}
+
+/** Project a report into the stable, diffable snapshot shape. */
+export function toSnapshot(report: CoverageReport): CoverageSnapshot {
+  return {
+    registeredSubTypeCount: report.registeredSubTypeCount,
+    exercisedSubTypeCount: report.exercisedSubTypeCount,
+    untestedSubTypes: report.untestedSubTypes,
+    untestedAttrsByExercisedSubType: report.untestedAttrsByExercisedSubType,
+  };
+}
+
+/** Serialize a snapshot as byte-stable JSON (2-space indent, trailing newline). */
+export function emitSnapshot(snapshot: CoverageSnapshot): string {
+  return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Monotonic ratchet (Wave 4a)
+// ---------------------------------------------------------------------------
+//
+// The committed snapshot (coverage-report.json) is a BASELINE, not an exact
+// expectation. The ratchet hard-fails only when coverage REGRESSES — never when
+// it improves. Coverage regresses when a registered (type, subType) or an attr
+// on an exercised subtype that the baseline considered EXERCISED becomes
+// UNEXERCISED, i.e. a NEW item appears in an untested set that wasn't there
+// before. Adding an exercising fixture (an item LEAVES an untested set) is an
+// improvement and is always allowed.
+//
+// Comparison granularity is SET-based, not count-based: an integer-only check
+// would let a regression hide behind a simultaneous improvement (untested count
+// stays flat while one item is newly exercised and a different one regresses).
+// We compare the untested SETS directly so each individual regression is named.
+
+/** One named coverage regression — an item that became unexercised. */
+export interface CoverageRegression {
+  /** "subtype" — a registered (type, subType) no longer exercised; or "attr". */
+  kind: "subtype" | "attr";
+  /** The `"<type>.<subType>"` key that regressed. */
+  key: string;
+  /** For an attr regression: the attr name that became untested (else undefined). */
+  attr?: string;
+}
+
+/** The ratchet verdict: ok=true when live coverage is no worse than baseline. */
+export interface RatchetResult {
+  ok: boolean;
+  /** Every named regression (empty when ok). Sorted for determinism. */
+  regressions: CoverageRegression[];
+}
+
+function sortedUnique(items: readonly string[]): string[] {
+  return [...new Set(items)].sort(compareStrings);
+}
+
+/**
+ * Compare a live coverage snapshot against a committed baseline and report any
+ * REGRESSION (an item the baseline had exercised that the live run no longer
+ * exercises). Improvements (items that left an untested set) are NOT regressions.
+ *
+ * - subtype regression: a key in `live.untestedSubTypes` not in baseline's set.
+ * - attr regression: an attr in a live subtype's `untestedAttrs` not in the
+ *   baseline's untested-attrs set for that SAME key. (A subtype that newly became
+ *   untested is reported once as a subtype regression — its attrs are not double-
+ *   reported, since an untested subtype has no per-attr entry by construction.)
+ */
+export function checkRatchet(
+  baseline: CoverageSnapshot,
+  live: CoverageSnapshot,
+): RatchetResult {
+  const baselineUntestedSubTypes = new Set(baseline.untestedSubTypes);
+  const liveUntestedSubTypes = sortedUnique(live.untestedSubTypes);
+
+  const regressions: CoverageRegression[] = [];
+
+  // Subtype regressions: a NEW untested subtype (was exercised in the baseline).
+  for (const key of liveUntestedSubTypes) {
+    if (!baselineUntestedSubTypes.has(key)) {
+      regressions.push({ kind: "subtype", key });
+    }
+  }
+
+  // Attr regressions: for each EXERCISED subtype (it carries a per-attr entry),
+  // any attr now untested that the baseline did not list as untested for that key.
+  const baselineAttrsByKey = new Map<string, Set<string>>();
+  for (const entry of baseline.untestedAttrsByExercisedSubType) {
+    baselineAttrsByKey.set(entry.key, new Set(entry.untestedAttrs));
+  }
+  for (const entry of live.untestedAttrsByExercisedSubType) {
+    // If the whole subtype regressed, it's already reported above — don't also
+    // attribute its attrs (it has no per-attr baseline entry by construction).
+    if (
+      !baselineUntestedSubTypes.has(entry.key) &&
+      liveUntestedSubTypes.includes(entry.key)
+    ) {
+      continue;
+    }
+    const baselineUntested = baselineAttrsByKey.get(entry.key) ?? new Set<string>();
+    for (const attr of sortedUnique(entry.untestedAttrs)) {
+      if (!baselineUntested.has(attr)) {
+        regressions.push({ kind: "attr", key: entry.key, attr });
+      }
+    }
+  }
+
+  regressions.sort((a, b) => {
+    const byKind = compareStrings(a.kind, b.kind);
+    if (byKind !== 0) return byKind;
+    const byKey = compareStrings(a.key, b.key);
+    if (byKey !== 0) return byKey;
+    return compareStrings(a.attr ?? "", b.attr ?? "");
+  });
+
+  return { ok: regressions.length === 0, regressions };
+}
+
+/** Render the regressions into an actionable, human-readable failure message. */
+export function formatRatchetFailure(result: RatchetResult): string {
+  const lines: string[] = [
+    "Registry coverage REGRESSED — a previously-exercised vocabulary member is no",
+    "longer exercised by any conformance fixture (monotonic-ratchet violation):",
+    "",
+  ];
+  for (const r of result.regressions) {
+    if (r.kind === "subtype") {
+      lines.push(`  - subtype  ${r.key}  (no fixture exercises it anymore)`);
+    } else {
+      lines.push(`  - attr     ${r.key} @${r.attr}  (no fixture sets it anymore)`);
+    }
+  }
+  lines.push(
+    "",
+    "Fix: add a conformance fixture that exercises the listed member(s). Only if",
+    "the member was LEGITIMATELY removed from the vocabulary (a justified change)",
+    "should you regenerate the baseline:",
+    "  cd server/typescript",
+    "  MO_UPDATE_COVERAGE_SNAPSHOT=1 bun test packages/metadata/test/registry-coverage.test.ts",
+  );
+  return lines.join("\n");
+}

package/src/registry-manifest-exclusions.ts

@@ -0,0 +1,176 @@
+// SP-G Registry Conformance — manifest emitter CLASSIFICATION (the in/out boundary).
+//
+// WHY THIS FILE IS A CLASSIFICATION, NOT A NAME-MATCH LIST (Wave 3b).
+// ---------------------------------------------------------------------------
+// The manifest's in/out boundary used to be decided by a bare exclusion
+// name-list: an attr was OUT iff its name happened to be hand-added to the set,
+// IN otherwise — a silent default-include. That is a tautology: it cannot tell a
+// genuinely-logical attr from a port-private one; it just records the names
+// someone remembered to list. The next physical/binding attr nobody adds to the
+// list silently enters the cross-port logical contract.
+//
+// The principled axis. Every metamodel facet the emitter encounters is one of:
+//
+//   • LOGICAL  — part of the cross-port vocabulary contract. MUST be identical
+//                in all five ports (this is what the gate measures). INCLUDED.
+//                Note "logical" is NOT "non-physical": the physical-DB attrs
+//                `column`/`dbColumnType`/`db.indexed`/`precision`/`scale`/
+//                `maxLength`/`unique` ARE logical here — they are the agreed
+//                cross-port persistence vocabulary (every port emits the same
+//                DDL contract from them). The axis is cross-port-CONTRACT vs
+//                port-PRIVATE-mechanism, not abstract-vs-physical.
+//
+//   • PORT_PRIVATE — a per-port mechanism, NOT cross-port vocabulary:
+//        - NATIVE_BINDING   factories / native type classes / the ADR-0001
+//                           `object` class-FQN binding + ADR-0005 `objectAdapter`
+//                           value-access seam (OO-port runtime mechanisms).
+//        - STRUCTURAL_KEYWORD bare body keywords (`isArray`/`isAbstract`/
+//                           `extends`/`implements`/`isInterface`) — the
+//                           structural/OO-shape spine, peers of name/children,
+//                           never per-type attributes.
+//        - COMMON_ATTR_DUP  `description` re-registered per-type (it lives in the
+//                           `commonAttrs` block, never as a per-type attr).
+//        - INHERITANCE_ANCHOR the `metadata.base` per-port abstract anchor (the
+//                           deferred `inheritsFrom` facet; other ports register
+//                           only the concrete `metadata.root`).
+//        - PRESENTATION_ONLY the 11 generic `view.*` controls (checkbox/date/…)
+//                           — a TS-web presentation facet (TS web client + TS
+//                           form codegen consume them; zero backend/codegen/
+//                           render consumers in any port), like the TS-only `D1`
+//                           dialect. Stay REGISTERED in TS; deregistered in
+//                           C#/Python; EXCLUDED from the manifest everywhere.
+//
+// The boundary is now an EXPLICIT classification (not a silent default): the
+// port-private set is enumerated WITH a reason category, and a TRIPWIRE
+// (`assertExclusionsAreLive`) asserts every enumerated exclusion is genuinely
+// present in the registry — so a stale/typo'd exclusion (an excluded name no
+// provider registers) fails the emit instead of silently doing nothing.
+//
+// Inclusion-by-default is SOUND here precisely because of ADR-0023: the library
+// seals its composed metamodel registry after the agreed-provider bootstrap, so
+// every registered (type, subType, attr) is, by construction, deliberately-agreed
+// metamodel vocabulary — there is no "accidental" registration to silently let
+// in. The classification's job is therefore to carve the small, declared set of
+// agreed-but-port-private facets OUT of that agreed vocabulary, with a reason and
+// a liveness tripwire. See fixtures/registry-conformance/README.md.
+//
+// FR-033 NOTE — the manifest now emits per-type and per-attr `description`
+// (required, non-empty), optional `rules`/`example`/`whenToUse`, AND the full
+// structural constraint graph (`children` from childRules, with optional
+// cardinality, and optional `parents`) as FIRST-CLASS PROPERTIES of each type/
+// attr entry. The v1 boundary note that listed `childRules` / type-level
+// `description` as EXCLUDED is SUPERSEDED for those facets. This does NOT change
+// the COMMON_ATTR_DUP carve-out below: that entry removes a per-type ATTR whose
+// NAME is "description" (the commonAttr re-registered as a per-type attr) from
+// the `attrs` ARRAY — a different mechanism from the type/attr-level
+// `description` PROPERTY now emitted as a sibling of `attrs`. The carve-out (and
+// the test asserting no `attrs[]` entry is named "description") stays unchanged.
+
+import { RESERVED_KEY_IS_ARRAY, RESERVED_KEY_EXTENDS } from "./shared/structural.js";
+import { DOC_ATTR_DESCRIPTION } from "./core/documentation/doc-constants.js";
+import { SUBTYPE_BASE, TYPE_METADATA, TYPE_VIEW } from "./shared/base-types.js";
+import { VIEW_SUBTYPE_CURRENCY } from "./presentation/view/view-constants.js";
+
+/** The reason an attr/row is classified PORT_PRIVATE (carved out of the agreed vocabulary). */
+export enum ExclusionReason {
+  /** Native type-binding / factory mechanism (incl. ADR-0001 `object`, ADR-0005 `objectAdapter`). */
+  NativeBinding = "native-binding",
+  /** Bare structural / OO-shape keyword (`isArray`/`isAbstract`/`extends`/`implements`/`isInterface`). */
+  StructuralKeyword = "structural-keyword",
+  /** A `commonAttr` (`description`) re-registered per-type — belongs in the commonAttrs block. */
+  CommonAttrDup = "common-attr-dup",
+  /** The `metadata.base` per-port inheritance anchor (deferred `inheritsFrom` facet). */
+  InheritanceAnchor = "inheritance-anchor",
+  /** TS-web-presentation-only facet (the generic `view.*` controls). */
+  PresentationOnly = "presentation-only",
+  /**
+   * FR-024 TS-reference-first rollout (RETIRED at the atomic flip): new
+   * vocabulary genuinely registered (and gated by TS tests) but carved out of
+   * the cross-port manifest until every port registered it; the carve-outs were
+   * then removed and the canonical updated in ONE commit (the same lifecycle
+   * the retired TsPilotVocab carve-outs followed for `@responseRef`/`@provided`).
+   * The `object.projection` row + the `origin.aggregate.via` required-override
+   * flipped when all five ports shipped the FR-024 loader-grammar slice. The
+   * reason is kept as the documented lifecycle slot for the NEXT
+   * reference-first rollout; it currently has no members.
+   */
+  Fr024Pending = "fr024-pending",
+}
+
+/** `isAbstract` as Java's per-type attr name (the contract's bare `abstract` structural keyword). */
+const ATTR_NAME_IS_ABSTRACT = "isAbstract";
+/** Java-OO structural-shape keywords as per-type attr names (the OO modeling spine). */
+const ATTR_NAME_IMPLEMENTS = "implements";
+const ATTR_NAME_IS_INTERFACE = "isInterface";
+/** ADR-0001 class-FQN type binding + ADR-0005 hybrid value-access seam (per-port runtime mechanisms). */
+const ATTR_NAME_OBJECT = "object";
+const ATTR_NAME_OBJECT_ADAPTER = "objectAdapter";
+
+/**
+ * The per-type attr names carved OUT of the agreed vocabulary, each mapped to
+ * its PORT_PRIVATE reason category. This is the classification — an attr name
+ * here is OUT *because of its declared category*, not merely because it is
+ * listed. A per-type attr NOT in this map is LOGICAL (INCLUDED) by the
+ * ADR-0023 sealed-vocabulary contract.
+ */
+export const EXCLUDED_PER_TYPE_ATTRS: ReadonlyMap<string, ExclusionReason> = new Map([
+  [RESERVED_KEY_IS_ARRAY, ExclusionReason.StructuralKeyword],
+  [ATTR_NAME_IS_ABSTRACT, ExclusionReason.StructuralKeyword],
+  [RESERVED_KEY_EXTENDS, ExclusionReason.StructuralKeyword],
+  [ATTR_NAME_IMPLEMENTS, ExclusionReason.StructuralKeyword],
+  [ATTR_NAME_IS_INTERFACE, ExclusionReason.StructuralKeyword],
+  [ATTR_NAME_OBJECT, ExclusionReason.NativeBinding],
+  [ATTR_NAME_OBJECT_ADAPTER, ExclusionReason.NativeBinding],
+  [DOC_ATTR_DESCRIPTION, ExclusionReason.CommonAttrDup],
+]);
+
+/**
+ * `(type, subType)` rows carved OUT of the agreed vocabulary, with reason.
+ * `metadata.base` is the per-port inheritance anchor (INHERITANCE_ANCHOR); the
+ * 11 generic `view.*` controls are TS-web-presentation-only (PRESENTATION_ONLY).
+ * Returns the reason, or `undefined` for an INCLUDED (logical) row.
+ */
+export function classifyTypeSubType(
+  type: string,
+  subType: string,
+): ExclusionReason | undefined {
+  if (type === TYPE_METADATA && subType === SUBTYPE_BASE) {
+    return ExclusionReason.InheritanceAnchor; // C-5 — Java's internal inheritance anchor
+  }
+  if (type === TYPE_VIEW && subType !== SUBTYPE_BASE && subType !== VIEW_SUBTYPE_CURRENCY) {
+    return ExclusionReason.PresentationOnly; // B-2 — TS-web-presentation generic view controls
+  }
+  return undefined;
+}
+
+/** True if a `(type, subType)` row is carved out of the manifest (any reason). */
+export function isExcludedTypeSubType(type: string, subType: string): boolean {
+  return classifyTypeSubType(type, subType) !== undefined;
+}
+
+/**
+ * FR-024-pending manifest REQUIREDNESS overrides (the attr-level analogue of
+ * the `Fr024Pending` row carve-out). Key is `"type.subType.attrName"`; value is
+ * the requiredness the cross-port canonical (`expected-registry.json`) still
+ * records. The TS registry already registers the FR-024 requiredness (and the
+ * TS loader enforces it), but the other four ports have not flipped yet — the
+ * manifest keeps emitting the pre-FR-024 agreed value so the shared canonical
+ * stays byte-identical until the Phase-E atomic all-ports flip, when this map
+ * empties and the canonical is updated in ONE commit.
+ *
+ * Members today: NONE — `origin.aggregate.via` flipped at the FR-024 atomic
+ * all-ports manifest flip (it is OPTIONAL everywhere under ADR-0029 decision 5:
+ * omitted `@via` is inferred when exactly one single-hop relationship leads
+ * from the base entity to the `@of` entity). The mechanism stays for the next
+ * reference-first rollout.
+ */
+export const FR024_PENDING_REQUIRED_OVERRIDES: ReadonlyMap<string, boolean> = new Map([]);
+
+/** Manifest requiredness for an attr — the FR-024-pending override when one exists. */
+export function manifestRequiredOverride(
+  type: string,
+  subType: string,
+  attrName: string,
+): boolean | undefined {
+  return FR024_PENDING_REQUIRED_OVERRIDES.get(`${type}.${subType}.${attrName}`);
+}