@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.1

package/src/persistence/origin/meta-origin.ts

@@ -14,7 +14,6 @@ import {
   ORIGIN_AGGREGATE_ATTR_AGG,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
   ORIGIN_COMPUTED_ATTR_EXPR,
   ORIGIN_FIRST_ATTR_OF,
   ORIGIN_FIRST_ATTR_VIA,
@@ -77,21 +76,6 @@ export class MetaAggregateOrigin extends MetaOrigin {
   }
 }
 
-/**
- * Collection origin — the (array) field's value is a relationship-derived
- * array of nested view-objects (FR-004 R4). Carries `@via` (required): the
- * dotted relationship path the collection walks (e.g. "Author.posts"), or a
- * wildcard-prefixed selector for a package-spanning collection (e.g. "*.User").
- */
-export class MetaCollectionOrigin extends MetaOrigin {
-  /** The dotted relationship path (or wildcard selector) this collection is sourced from. */
-  get via(): string | undefined {
-    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
-    const v = this.ownAttr(ORIGIN_COLLECTION_ATTR_VIA);
-    return typeof v === "string" ? v : undefined;
-  }
-}
-
 /**
  * Computed origin (#195) — a row-level value computed from the base entity's own
  * fields via a structured expression tree (`@expr`). No related rows, no `@via`.

package/src/persistence/origin/origin-constants.ts

@@ -13,7 +13,15 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 export const ORIGIN_SUBTYPE_PASSTHROUGH = "passthrough";
 export const ORIGIN_SUBTYPE_AGGREGATE   = "aggregate";
-export const ORIGIN_SUBTYPE_COLLECTION  = "collection";
+// FR-037 R2 — `collection` is RESERVED, NOT REGISTERED. It duplicated
+// `origin.aggregate @agg: collect` on a strictly smaller attr set (@via only —
+// no @filter, no @orderBy, no @distinct), and nothing dispatched on it: its last
+// real consumer, the payload-VO typing edge, was deleted in 0.20.16 (#270) for
+// being actively wrong. Re-entry bar (ADR-0007 Amendment 2): a member enters the
+// registry only when a shipping consumer dispatches on it. The designated
+// re-entry shape is `@agg: collect` with `@of` made OPTIONAL (absent = whole-
+// object rollup, typed by the field's declared @objectRef + isArray), NOT a
+// restored subtype.
 // #195 — computed: a row-level value from the base entity's own fields via a
 // structured @expr tree (no related rows). first: the single related row picked
 // by @orderBy along @via, projecting @of (argmax-then-project).
@@ -24,7 +32,6 @@ export const ORIGIN_SUBTYPES = [
   SUBTYPE_BASE,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
-  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_SUBTYPE_COMPUTED,
   ORIGIN_SUBTYPE_FIRST,
 ] as const;
@@ -38,7 +45,6 @@ export type OriginSubType = (typeof ORIGIN_SUBTYPES)[number];
 export const ASSEMBLY_ORIGIN_SUBTYPES = [
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COMPUTED,
-  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_SUBTYPE_FIRST,
 ] as const;
 
@@ -50,11 +56,6 @@ export const ORIGIN_PASSTHROUGH_ATTR_VIA  = "via";
 // does NOT generate a cast; real type-converting projections are origin.computed (#195/#159).
 export const ORIGIN_PASSTHROUGH_ATTR_CONVERT = "convert";
 
-// collection attrs — a relationship-derived array of nested view-objects
-// (FR-004 R4). @via is the dotted relationship path (optionally wildcard-
-// prefixed, e.g. "*.User", for a package-spanning collection).
-export const ORIGIN_COLLECTION_ATTR_VIA = "via";
-
 // aggregate attrs
 export const ORIGIN_AGGREGATE_ATTR_AGG = "agg";
 export const ORIGIN_AGGREGATE_ATTR_OF  = "of";

package/src/persistence/origin/origin-definition.embedded.ts

@@ -49,9 +49,9 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
     {
       "type": "origin",
       "subType": "aggregate",
-      "description": "A value reduced from the related row-set reached along a relationship path (@via) from the base entity: count/sum/avg/min/max over a column (@of); any/all predicate quantifiers over a @filter; or collect (an array rollup of @of).",
+      "description": "A value reduced from the related row-set reached along a relationship path (@via) from the base entity: count/sum/avg/min/max over a column (@of); any/all predicate quantifiers over a @filter; or collect (an array rollup — of the @of column, or of the carrying field.object's declared @objectRef value object when @of is omitted).",
       "whenToUse": "A projection needs a value derived by reducing related rows — a count/sum/avg/min/max, a 'did any/every related row match' flag, or an array of collected values. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
-      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly. @of is required for count/sum/avg/min/max/collect and forbidden for any/all (which quantify over rows via @filter, not a column). @filter is required for any/all. The field must be isArray:true for collect and isArray:false for every other @agg. @distinct and @orderBy are collect-only.",
+      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly. @of is required for count/sum/avg/min/max and forbidden for any/all (which quantify over rows via @filter, not a column). @filter is required for any/all. The field must be isArray:true for collect and isArray:false for every other @agg. @distinct and @orderBy are collect-only. On @agg:collect @of is OPTIONAL: omitting it declares a WHOLE-OBJECT rollup, which collects each related row as the carrying field's declared @objectRef value object instead of one scalar column. A whole-object rollup requires a field.object carrying @objectRef, requires that @objectRef to name an object.value, requires an explicit @via (there is no @of entity to infer the path from), and refuses @distinct. Its @orderBy keys resolve against the @via TERMINAL entity, not the head or a middle hop. Its value-object members bind to the terminal entity's fields BY NAME — member name == terminal field name, deliberately NOT extends, so one value object stays collectable from two different entities — and every member must match a terminal field agreeing on BOTH field.<subType> and array-ness.",
       "children": [
         {
           "type": "attr",
@@ -69,7 +69,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
             "all",
             "collect"
           ],
-          "description": "The reducing function applied over the related row-set: count/sum/avg/min/max (numeric/ordinal reduces over @of); any/all (predicate quantifiers over @filter — @of forbidden; empty set → any=false, all=true); collect (array rollup of @of — the field must be isArray)."
+          "description": "The reducing function applied over the related row-set: count/sum/avg/min/max (numeric/ordinal reduces over @of); any/all (predicate quantifiers over @filter — @of forbidden; empty set → any=false, all=true); collect (array rollup — of the @of column, or of the carrying field.object's declared @objectRef value object when @of is omitted; the field must be isArray)."
         },
         {
           "type": "attr",
@@ -77,7 +77,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
           "name": "of",
           "min": 0,
           "max": 1,
-          "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes'). Required for count/sum/avg/min/max/collect; forbidden for any/all (which quantify over rows via @filter, not a column)."
+          "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes'). Required for count/sum/avg/min/max; OPTIONAL for collect, where absent means a whole-object rollup of the field's declared @objectRef value object; forbidden for any/all (which quantify over rows via @filter, not a column)."
         },
         {
           "type": "attr",
@@ -101,7 +101,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
           "name": "distinct",
           "min": 0,
           "max": 1,
-          "description": "Set (collect-only) to dedupe collected values (set semantics)."
+          "description": "Set (collect-only) to dedupe collected values (set semantics). Not supported on a whole-object collect (@of omitted): it is a guaranteed no-op whenever the value object carries the primary key, and a silent no-op is worse than a refusal."
         },
         {
           "type": "attr",
@@ -114,22 +114,6 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
         }
       ]
     },
-    {
-      "type": "origin",
-      "subType": "collection",
-      "description": "A relationship-derived array of nested view-objects: walks @via to produce the collection (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection.",
-      "whenToUse": "A projection needs an array of nested child view-objects (a parent with its children inline). Declare it instead of hand-assembling the nested query + mapping.",
-      "children": [
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "via",
-          "min": 1,
-          "max": 1,
-          "description": "Dotted relationship path the collection walks to produce an array of nested view-objects (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection (e.g. '*.User')."
-        }
-      ]
-    },
     {
       "type": "origin",
       "subType": "computed",

package/src/registry-manifest.ts

@@ -103,11 +103,16 @@ interface ManifestType {
  * manifest (the byte-exact bill of materials), NOT a per-provider or per-file marker:
  * every port emits the same string, asserted by registry-conformance. Pre-1.0 the
  * vocabulary is still `0.x` (semver = unstable, may change) but largely settled going
- * into the quiet period, so this is `"0.9"` (near-final); the 1.0 cut (readiness G1)
- * freezes it to `"1.0"`. Decoupled from every package line — it is the spec version,
- * not a package version.
+ * into the quiet period; the 1.0 cut (readiness G1) freezes it to `"1.0"`. Decoupled
+ * from every package line — it is the spec version, not a package version.
+ *
+ * The current value is the declaration below and nothing else. Do not restate it in
+ * prose: `scripts/check-metamodel-version.mjs --set` rewrites the declaration, so any
+ * copy in a comment goes stale on the very next bump (it said `"0.9"` here while the
+ * constant read `"0.10"`). Bump with that script — never by hand — so the manifest and
+ * all four port constants move together.
  */
-export const METAMODEL_VERSION = "0.9";
+export const METAMODEL_VERSION = "0.12";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {

package/src/retired-vocabulary.ts

@@ -0,0 +1,280 @@
+// server/typescript/packages/metadata/src/retired-vocabulary.ts
+//
+// Vocabulary this project USED to register, and what to do instead.
+//
+// WHY THIS EXISTS (#337). Under ADR-0023 the registry is strict and sealed, so retired
+// vocabulary fails the load — correctly. But the message it failed with said the attribute
+// was "not declared by any registered provider", which tells an author their metadata is
+// malformed when the truth is that the vocabulary was retired ON PURPOSE, in a named
+// release, with a written migration. An adopter read that error, concluded the tool had a
+// registration bug, filed it as one, and argued against a decision whose reasoning they had
+// never seen — because nothing in the error pointed at it. The migration guide answered
+// their objection precisely. They never found it.
+//
+// THIS CHANGES NO LOAD OUTCOME. Retired vocabulary still fails, with the same error code,
+// at the same site. Only the message gains a sentence. That is deliberate: making any of
+// these load again would undo an adjudicated breaking change, and a "helpful" shim is how a
+// retirement quietly stops being one.
+//
+// SCOPE IS BY TYPE, NEVER BY BARE NAME. `@unique` is retired on `identity.secondary` and
+// perfectly live on a field; a name-only match would brand a valid declaration as retired,
+// which is worse than the generic message it replaces. Every entry names the type it
+// applies to, and `*` means "every subtype of this type" — never "every type".
+//
+// A GENUINE TYPO MUST STAY GENERIC. This map is consulted only after the normal check has
+// already decided to fail, and it returns undefined for anything it does not recognise, so
+// `@maxLenght` still reports as an unknown attribute. The map speaks only where it KNOWS.
+//
+// CROSS-PORT: this is a DIAGNOSTIC, not registered vocabulary — it affects no registry
+// manifest and no load outcome, so it carries no registry-conformance obligation. The other
+// four ports fail identically today, just with the generic message; mirroring this map is a
+// per-port ergonomics follow-up, not a conformance gap.
+
+/** What a reader needs at the moment their load fails. */
+export interface RetirementNote {
+  /** The release that retired it. */
+  readonly since: string;
+  /** One line: what it was, and why it went. */
+  readonly why: string;
+  /** The vocabulary that replaced it, when something did. */
+  readonly replacedBy?: string;
+  /** Repo-relative migration guide. */
+  readonly migration?: string;
+}
+
+/**
+ * The mechanical fix, when one exists.
+ *
+ * ABSENT MEANS JUDGMENT — `@status: abandoned` can be resolved by deleting the node, by
+ * retyping it, or by fixing the residue it describes, and only a human knows which. A tool
+ * that guessed would emit metadata that LOADS and means something different, which is worse
+ * than refusing: the adopter would believe the migration finished.
+ */
+export type VocabularyRewrite =
+  /** The attribute name changed; the value is untouched. */
+  | { readonly kind: "renameAttr"; readonly to: string }
+  /** The attribute went away with no replacement — drop it. */
+  | { readonly kind: "dropAttr" }
+  /**
+   * Both the name and the value changed (`@readOnly: true` → `@mutability: "readOnly"`).
+   *
+   * `otherwise` is REQUIRED, and that is the point. The attribute is retired for EVERY
+   * value it could hold, so an entry that names only the value it can rewrite has said
+   * nothing about the rest — and the rewriter's only honest options are to drop them or to
+   * refuse them. Leaving it implicit is how `@readOnly: false` came to be silently skipped:
+   * the entry's prose said "treated as a drop", the code fell through to `continue`, and
+   * `meta upgrade` exited 0 on a file that still would not load.
+   */
+  | {
+      readonly kind: "renameAttrValue";
+      readonly toAttr: string;
+      readonly fromValue: unknown;
+      readonly toValue: unknown;
+      /** What happens to every value other than `fromValue`. */
+      readonly otherwise: "drop" | "refuse";
+    };
+
+/** One retirement. `subType: "*"` means every subtype of `type`. */
+export interface RetiredEntry extends RetirementNote {
+  readonly type: string;
+  /** `*` for every subtype of `type`, else the exact subtype. */
+  readonly subType: string;
+  /** Retired ATTRIBUTE name (no `@`), when the attribute itself went. */
+  readonly attr?: string;
+  /** Retired VALUES of a surviving attribute, when only some members went. */
+  readonly attrValues?: readonly string[];
+  /** Set when the SUBTYPE itself was retired (`attr`/`attrValues` absent). */
+  readonly isSubTypeRetirement?: boolean;
+  /** How `meta upgrade` fixes it. Absent ⇒ the human decides; the tool refuses and
+   *  prints `migration`. */
+  readonly rewrite?: VocabularyRewrite;
+}
+
+const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
+
+export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
+  // ── 0.24.0: `@violation` is renamed `@counterexample` ──
+  //
+  // Pure rename — no semantics change. The field always held a static falsifiability test
+  // ("what would contradict this"), authored once, never a state. `@violation` READ as a
+  // status, and did so to the person who approved the vocabulary, who asked whether it
+  // meant "we know this requirement is currently violated". A name that misleads its own
+  // owner has earned replacing.
+  //
+  // Fully mechanical, which is the point: adopters migrate with `meta upgrade --apply`
+  // rather than a hand sweep. This entry is the first real user of that tool.
+  {
+    type: "requirement", subType: "*", attr: "violation",
+    since: "0.24.0",
+    why: "it named a static falsifiability test but read as a status — 'this requirement " +
+         "is in violation' — which is not what the field has ever held",
+    replacedBy: "@counterexample",
+    migration: "docs/features/migrations/violation-to-counterexample.md",
+    rewrite: { kind: "renameAttr", to: "counterexample" },
+  },
+
+  // ── FR-038: the requirement vocabulary becomes prescriptive-only (0.24.0) ──
+  {
+    type: "requirement", subType: "*", attr: "verifiedBy",
+    since: "0.24.0",
+    why: "it asked you to name a test, and verify could only check that the NAME occurred " +
+         "somewhere in your test sources — never that the named test verified the claim",
+    migration: REQUIREMENT_MIGRATION,
+    // Nothing replaced it, so the fix is removal. Safe to automate: the attribute drove no
+    // behaviour anyone else can observe.
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "requirement", subType: "*", attr: "supersededBy",
+    since: "0.24.0",
+    why: "a requirement is prescriptive — it states what should be true and is never a " +
+         "journal of what happened",
+    migration: REQUIREMENT_MIGRATION,
+    rewrite: { kind: "dropAttr" },
+  },
+  {
+    type: "requirement", subType: "*", attr: "status",
+    attrValues: ["abandoned", "superseded"],
+    since: "0.24.0",
+    why: "retiring a capability is DELETING its requirement; version control holds that it " +
+         "existed, and `notes` on a surviving entry holds what a reader still needs",
+    migration: REQUIREMENT_MIGRATION,
+  },
+
+  // ── FR-037 R1: @readOnly becomes the @mutability enum (0.24.0) ──
+  {
+    type: "field", subType: "*", attr: "readOnly",
+    since: "0.24.0",
+    why: "a boolean could not express write-once, so the axis became an enum",
+    replacedBy: "@mutability",
+    migration: "docs/features/migrations/readonly-to-mutability.md",
+    // Key AND value: `@readOnly: true` becomes `@mutability: "readOnly"`. `@readOnly: false`
+    // was the default and simply goes away — hence `otherwise: "drop"` rather than inventing
+    // a mutability the author never stated. Both arms must be stated: the attribute is
+    // deregistered for every value, so an unhandled arm is a file that still fails to load
+    // after a run that reported success.
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "mutability",
+      fromValue: true,
+      toValue: "readOnly",
+      otherwise: "drop",
+    },
+  },
+
+  // ── FR-037 R2: origin.collection retires to reserved-not-registered (0.24.0) ──
+  {
+    type: "origin", subType: "collection", isSubTypeRetirement: true,
+    since: "0.24.0",
+    why: "it duplicated `origin.aggregate @agg: collect` on a strictly smaller attribute " +
+         "set, and nothing dispatched on it",
+    replacedBy: "origin.aggregate @agg: collect",
+    migration: "docs/features/migrations/origin-collection-retirement.md",
+  },
+
+  // ── ADR-0040: uniqueness lives in the TYPE, not an attribute (0.15.1) ──
+  {
+    type: "identity", subType: "secondary", attr: "unique",
+    since: "0.15.1",
+    why: "`identity.secondary` is now always a unique alternate key — uniqueness is encoded " +
+         "in the type, so the attribute had nothing left to say",
+    replacedBy: "index.lookup (for a NON-unique retrieval index)",
+    migration: "docs/features/migrations/identity-secondary-to-index-lookup.md",
+  },
+
+  // ── Metamodel 1.0: @dbColumnType slim-and-derive (0.15.0) ──
+  {
+    type: "field", subType: "*", attr: "dbColumnType",
+    attrValues: ["uuid_array", "text_array"],
+    since: "0.15.0",
+    why: "array-ness is DERIVED from `isArray`, so an array-flavoured physical type restated " +
+         "something the model already knew",
+    replacedBy: "isArray: true on the field",
+    // On a VALUE-scoped entry, `dropAttr` means "drop it when the value is one of the
+    // retired ones" — never unconditionally. `@dbColumnType: jsonb` is live vocabulary on
+    // the same attribute, and removing it would silently change the column type.
+    //
+    // Safe because the attribute said nothing the model did not already know: the field
+    // carrying `uuid_array` necessarily has `isArray: true`, which is where array-ness now
+    // comes from. There is no guide for this one, so without the rewrite an adopter would
+    // be told it is retired and given nowhere to go — which is what the dead-end test that
+    // caught this exists to prevent.
+    rewrite: { kind: "dropAttr" },
+  },
+];
+
+/**
+ * True when `entry` governs `typeKey` (`"<type>.<subType>"`).
+ *
+ * Exported because the rewriter scopes every occurrence with the SAME rule. It used to
+ * carry its own copy, and a scoping rule that lives in two files is one that will be fixed
+ * in one of them.
+ */
+export function scopeMatches(entry: RetiredEntry, typeKey: string): boolean {
+  const dot = typeKey.indexOf(".");
+  if (dot < 0) return false;
+  if (entry.type !== typeKey.slice(0, dot)) return false;
+  return entry.subType === "*" || entry.subType === typeKey.slice(dot + 1);
+}
+
+/** The reader-facing half of an entry, without the matching machinery. */
+export function note(entry: RetiredEntry): RetirementNote {
+  return {
+    since: entry.since,
+    why: entry.why,
+    ...(entry.replacedBy !== undefined ? { replacedBy: entry.replacedBy } : {}),
+    ...(entry.migration !== undefined ? { migration: entry.migration } : {}),
+  };
+}
+
+/** First entry satisfying `match`, as a note. The three lookups below differ only in it. */
+function noted(match: (e: RetiredEntry) => boolean): RetirementNote | undefined {
+  const hit = RETIRED_VOCABULARY.find(match);
+  return hit === undefined ? undefined : note(hit);
+}
+
+/**
+ * The attribute NAME itself was retired for this type. Returns undefined for an attr whose
+ * name is unknown here — a typo must keep reporting as a typo.
+ *
+ * An entry carrying `attrValues` is a VALUE retirement on a surviving attribute, so it is
+ * deliberately not matched here: `@status` is still perfectly good vocabulary.
+ */
+export function retiredAttr(typeKey: string, attrName: string): RetirementNote | undefined {
+  return noted(
+    (e) => e.attr === attrName && e.attrValues === undefined && scopeMatches(e, typeKey),
+  );
+}
+
+/** A specific VALUE of a surviving attribute was retired. */
+export function retiredAttrValue(
+  typeKey: string,
+  attrName: string,
+  value: unknown,
+): RetirementNote | undefined {
+  if (typeof value !== "string") return undefined;
+  return noted(
+    (e) => e.attr === attrName && e.attrValues?.includes(value) === true && scopeMatches(e, typeKey),
+  );
+}
+
+/** The SUBTYPE itself was retired (`origin.collection`). */
+export function retiredSubType(type: string, subType: string): RetirementNote | undefined {
+  return noted((e) => e.isSubTypeRetirement === true && e.type === type && e.subType === subType);
+}
+
+/**
+ * The sentence appended to a failing diagnostic. Kept here rather than at each call site so
+ * all three failure sites word a retirement identically — an adopter who has seen one
+ * recognises the next.
+ */
+export function retirementHint(n: RetirementNote): string {
+  // Sentences are built WITHOUT their terminator and punctuated once at the end. The
+  // previous form appended a period to each fragment and then repaired the doubling with a
+  // global `".." → "."` — which would silently rewrite an ellipsis, or a `../` in a
+  // migration path, inside the user-facing load error.
+  const parts = [`retired in ${n.since} — ${n.why}`];
+  if (n.replacedBy !== undefined) parts.push(`Use ${n.replacedBy} instead`);
+  if (n.migration !== undefined) parts.push(`Migration: ${n.migration}`);
+  return `${parts.join(". ")}.`;
+}

package/src/super-resolve.ts

@@ -21,6 +21,8 @@
 
 import type { MetaData } from "./shared/meta-data.js";
 import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "./shared/structural.js";
+import { TYPE_IDENTITY } from "./shared/base-types.js";
+import { IDENTITY_UNIQUE_KEY_SUBTYPES } from "./core/identity/identity-constants.js";
 
 // ---------------------------------------------------------------------------
 // Tree search helper
@@ -87,6 +89,51 @@ export function isChildTargetingRef(ref: string): boolean {
   return lastSegment.includes(CHILD_REF_SEPARATOR);
 }
 
+/**
+ * Whether a dotted `extends` target is acceptable for the extending node.
+ *
+ * Type must match exactly. Subtype must match too — with ONE exception, on identities
+ * (#310). For an identity, subtype equality was answering the wrong question: it read as
+ * "the same kind of thing", but ADR-0040 encodes uniqueness in the TYPE, so `primary` and
+ * `secondary` are both UNIQUE KEYS and differ only in which one the entity nominated as
+ * its main handle. Borrowing a key borrows uniqueness, not that nomination — so a read
+ * model may key off a business key the entity models as `identity.secondary` while never
+ * surfacing its surrogate `identity.primary` at all.
+ *
+ * The gate was never written for identities in the first place: its only conformance
+ * fixture is `error-extends-entity-field-type-mismatch`, a `field.uuid` extending a
+ * `field.string`. For a FIELD, subtype IS the datatype and inheriting across it is
+ * incoherent; for an identity, subtype is a ROLE. A field-shape rule was generalized onto
+ * a role axis without a fixture ever exercising it.
+ *
+ * `identity.reference` is excluded on both sides: a foreign key is not unique, so it can
+ * never back a borrowed key — and a set-membership test says that once, rather than
+ * enumerating the legal pairs.
+ *
+ * EXPORTED because there are two doors: this module's deferred resolution and
+ * `parser-core`'s eager check. They had independent copies of the boolean, so a change to
+ * one silently left the other enforcing the old rule on whichever path a given loader
+ * configuration takes.
+ */
+export function extendsTargetCompatible(node: MetaData, target: MetaData): boolean {
+  if (target.type !== node.type) return false;
+  if (target.subType === node.subType) return true;
+  return (
+    node.type === TYPE_IDENTITY &&
+    IDENTITY_UNIQUE_KEY_SUBTYPES.includes(node.subType) &&
+    IDENTITY_UNIQUE_KEY_SUBTYPES.includes(target.subType)
+  );
+}
+
+/**
+ * The one wording for `ERR_EXTENDS_TARGET_MISMATCH`, shared by both doors and mirrored in
+ * the other three ports. States the exception, so an author who hits it on a `field` is
+ * not left wondering why their identity case was allowed.
+ */
+export const EXTENDS_TARGET_MISMATCH_RULE =
+  "a dotted extends must target a node of the same type and subtype — the one exception " +
+  "is an identity, which may extend any UNIQUE key (identity.primary or identity.secondary)";
+
 /**
  * FR-024: split a child-targeting ref into the owner-object ref and the child
  * traversal path. A multi-dot ref (`X.y.z`) traverses child names to any depth
@@ -276,9 +323,20 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
     if (target !== undefined) {
       // FR-024: a dotted ref must target a node of the SAME type and subtype
       // as the extending node. Dotted-only — top-level extends is unchanged.
+      //
+      // #310 — with ONE exception, on identities. Subtype equality here was standing in
+      // for "the target is the same kind of thing", and for identities that is the wrong
+      // question: ADR-0040 put uniqueness in the TYPE, so `identity.primary` and
+      // `identity.secondary` are both UNIQUE KEYS and differ only in which one the entity
+      // nominated as its main handle. A projection borrowing a key is borrowing
+      // uniqueness, not that nomination — so a read model may key off a business key the
+      // entity models as `identity.secondary` while never surfacing its surrogate
+      // `identity.primary` at all, which is the shape that was foreclosed.
+      //
+      // `identity.reference` stays out: an FK is not unique, so it can never back a key.
       if (
         isChildTargetingRef(node.superRef) &&
-        (target.type !== node.type || target.subType !== node.subType)
+        !extendsTargetCompatible(node, target)
       ) {
         failures.push({
           nodeFqn: node.fqn(),

package/src/template/prompt-definition.embedded.ts

@@ -19,7 +19,7 @@ export const PROMPT_DEFINITION: ProviderDefinition = {
           "name": "xmlText",
           "min": 0,
           "max": 1,
-          "description": "When true, this field receives its element's XML TEXT CONTENT during tolerant extract (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]) instead of a same-named child. No effect for @format: json."
+          "description": "When true, this field receives its element's XML TEXT CONTENT during tolerant extract (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]) instead of a same-named child. No effect when the eliciting prompt's @responseFormat is json."
         },
         {
           "type": "attr",

package/src/template/template-constants.ts

@@ -66,6 +66,10 @@ export const TEMPLATE_ATTR_HTML_BODY_REF = "htmlBodyRef";
 export const TEMPLATE_ATTR_TEXT_BODY_REF = "textBodyRef";
 
 // Prompt-overlay attrs (template.prompt only).
+//
+// ADR-0052: @responseRef is also the INBOUND gate. Its presence — never a format
+// value — is what makes a prompt emit a parser-on-receipt, a tolerant extract, and
+// the FR-010 response-format fragment. A template.output emits none of those.
 export const TEMPLATE_ATTR_RESPONSE_REF = "responseRef";
 export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
 export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
@@ -94,7 +98,8 @@ export const TEMPLATE_FORMATS = [
 ] as const;
 export type TemplateFormat = (typeof TEMPLATE_FORMATS)[number];
 
-// FR-010 artifact-1 prompt presentation style (template.output only). Closed enum;
+// FR-010 response-format fragment presentation (template.prompt only — ADR-0052 moved
+// it off template.output, where its own name contradicted the subtype). Closed enum;
 // guidance is NEVER carried in comments. Default "guide". Set project-wide via an
 // abstract template base + extends, with a render-time override on top.
 export const TEMPLATE_ATTR_PROMPT_STYLE = "promptStyle";
@@ -110,6 +115,27 @@ export const PROMPT_STYLES = [
 ] as const;
 export type PromptStyle = (typeof PROMPT_STYLES)[number];
 
+// ADR-0053 — the syntax of the model's REPLY (template.prompt only). Distinct from
+// @format, which is the syntax of the rendered PROMPT body: the two genuinely differ
+// (a plain-text prompt may elicit an XML reply), which is why one attribute cannot
+// serve both directions.
+//
+// Two members, not TEMPLATE_FORMATS' seven, because two is what every shipping
+// consumer dispatches on (Format.JSON / Format.XML) in all five ports. The rest are
+// reserved-not-registered under ADR-0007 Amendment 2's re-entry bar: a member enters
+// the registry only when a shipping consumer dispatches on it.
+//
+// Default "json" reproduces the trace helper's pre-ADR-0053 fallback exactly (anything
+// not "xml" was treated as JSON), so the default is behaviour-preserving rather than a
+// new policy.
+export const TEMPLATE_ATTR_RESPONSE_FORMAT = "responseFormat";
+export const RESPONSE_FORMAT_JSON = "json";
+export const RESPONSE_FORMAT_XML = "xml";
+
+export const TEMPLATE_RESPONSE_FORMATS = [RESPONSE_FORMAT_JSON, RESPONSE_FORMAT_XML] as const;
+export type ResponseFormat = (typeof TEMPLATE_RESPONSE_FORMATS)[number];
+export const RESPONSE_FORMAT_DEFAULT: ResponseFormat = RESPONSE_FORMAT_JSON;
+
 // @xmlText — a FIELD-level marker (boolean) for the tolerant extract engine: this field
 // receives its element's TEXT CONTENT when a template.output response is parsed from XML
 // (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]). Registered on field.* by