@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.0

package/src/core/field/validate-field-mutability.ts

@@ -0,0 +1,259 @@
+// Validation pass: field-level @mutability cross-attribute rules (FR-037 R1).
+//
+// @mutability is ONE axis — who may write this field, and when — with three
+// mutually exclusive modes, `readWrite` (default) < `writeOnce` < `readOnly`.
+// Modelling it as one enum rather than two booleans is what makes the illegal
+// pair unrepresentable and gives inheritance a total order.
+//
+// Codes:
+//   ERR_MUTABILITY_AUTOSET_CONFLICT — @autoSet on a field whose @mutability is
+//     `writeOnce` or `readOnly`. @autoSet already says the SERVER supplies the
+//     value; that is a different axis from who may write it, and the pair says
+//     two contradictory things about the same column. The boolean era left
+//     readOnly × @autoSet representable but UNVALIDATED — the enum cut closes
+//     both arms with one rule.
+//   ERR_MUTABILITY_DOWNGRADE — a subtype LOOSENS an inherited mode. Replaces
+//     ERR_READONLY_DOWNGRADE: the rule now spans three modes, so a code named
+//     READONLY would misdescribe a `writeOnce` → `readWrite` loosening.
+//   ERR_READONLY_ASSIGNED_PRIMARY — KEEPS ITS NAME: the condition is genuinely
+//     readOnly-specific. Note the asymmetry that justifies the enum — `writeOnce`
+//     on an assigned primary key is LEGAL, and indeed the natural declaration:
+//     the caller supplies the key on create and can never change it after.
+//   WARN_MUTABILITY_VALUE_OBJECT — a non-default @mutability on a field child of
+//     object.value. A value has no persistence semantics, so the contract is
+//     advisory (codegen may still use it for record/struct treatment).
+//   WARN_MUTABILITY_READONLY_HOST — `writeOnce` on a host nothing writes anyway
+//     (a projection, or a read-only source @kind). Benign, not an error: the
+//     declaration is merely inert, and a projection legitimately `extends` an
+//     entity whose field carries it.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import type { LoaderWarning } from "../../source.js";
+import {
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+  TYPE_SOURCE,
+} from "../../shared/base-types.js";
+import { OBJECT_SUBTYPE_VALUE, OBJECT_SUBTYPE_PROJECTION } from "../object/object-constants.js";
+import {
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_ATTR_GENERATION,
+  IDENTITY_ATTR_FIELDS,
+  GENERATION_ASSIGNED,
+} from "../identity/identity-constants.js";
+import {
+  FIELD_ATTR_MUTABILITY,
+  FIELD_ATTR_AUTO_SET,
+  MUTABILITY_READ_WRITE,
+  MUTABILITY_WRITE_ONCE,
+  MUTABILITY_READ_ONLY,
+  MUTABILITY_MODES,
+  type MutabilityMode,
+} from "./field-constants.js";
+import { isReadOnlySource } from "../../shared/node-guards.js";
+
+export interface FieldMutabilityValidationResult {
+  errors: ParseError[];
+  warnings: LoaderWarning[];
+}
+
+/**
+ * A field's EFFECTIVE mutability mode — resolving (ADR-0039), so a concrete
+ * field inheriting from an abstract parent sees the parent's declaration.
+ * Absent ⇒ `readWrite`. THE accessor every consumer should use.
+ */
+export function fieldMutability(field: MetaData): MutabilityMode {
+  const v = field.attr(FIELD_ATTR_MUTABILITY);
+  return isMutabilityMode(v) ? v : MUTABILITY_READ_WRITE;
+}
+
+/** True when nothing may write this field — the `@readOnly: true` of the old
+ *  vocabulary. Does NOT cover derived (origin-bearing) fields; callers that
+ *  need both compose this with `isDerived()`, exactly as before. */
+export function isReadOnlyMutability(field: MetaData): boolean {
+  return fieldMutability(field) === MUTABILITY_READ_ONLY;
+}
+
+/** True when the field is settable on create but excluded from the update shape. */
+export function isWriteOnceMutability(field: MetaData): boolean {
+  return fieldMutability(field) === MUTABILITY_WRITE_ONCE;
+}
+
+function isMutabilityMode(v: unknown): v is MutabilityMode {
+  return typeof v === "string" && (MUTABILITY_MODES as readonly string[]).includes(v);
+}
+
+/** The mode's rank on the tightening order. Declaration order IS the order, so
+ *  "may only tighten" is an index comparison, not a lookup table. */
+function rank(mode: MutabilityMode): number {
+  return (MUTABILITY_MODES as readonly string[]).indexOf(mode);
+}
+
+export function validateFieldMutability(root: MetaData): FieldMutabilityValidationResult {
+  const errors: ParseError[] = [];
+  const warnings: LoaderWarning[] = [];
+
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    const isValueObject = obj.subType === OBJECT_SUBTYPE_VALUE;
+    const hostNeverWritten = isWriteHostReadOnly(obj);
+
+    for (const ownField of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      // ADR-0039: own — these are own-vs-super comparisons by design. `ownMode`
+      // must see what THIS node declared: resolving would mask a downgrade, and
+      // would also warn on a value that merely inherited the mode.
+      const ownDeclared = ownField.ownAttr(FIELD_ATTR_MUTABILITY);
+      const ownMode = isMutabilityMode(ownDeclared) ? ownDeclared : undefined;
+
+      // 1) WARN_MUTABILITY_VALUE_OBJECT — a non-default mode declared on a value's
+      //    own field. Advisory: a value has no persistence semantics.
+      if (isValueObject && ownMode !== undefined && ownMode !== MUTABILITY_READ_WRITE) {
+        warnings.push({
+          code: "WARN_MUTABILITY_VALUE_OBJECT",
+          message:
+            `field "${ownField.name}" on object.value "${obj.name}" declares ` +
+            `@mutability: "${ownMode}"; value objects have no persistence semantics, so the ` +
+            `write contract is advisory (codegen may use it for record/struct treatment).`,
+          source: ownField.source,
+        });
+      }
+
+      // 2) ERR_MUTABILITY_DOWNGRADE — a subtype may TIGHTEN an inherited mode,
+      //    never loosen it. Rank comparison over the declaration order.
+      if (ownMode !== undefined) {
+        const inherited = inheritedField(obj, ownField.name);
+        if (inherited !== undefined) {
+          const inheritedMode = declaredMode(inherited);
+          if (inheritedMode !== undefined && rank(ownMode) < rank(inheritedMode)) {
+            errors.push(
+              new ParseError(
+                `field "${ownField.name}" on "${obj.name}" sets @mutability: "${ownMode}", but ` +
+                  `its extends-chain parent declares "${inheritedMode}". A subtype may only ` +
+                  `TIGHTEN an inherited mode (${MUTABILITY_MODES.join(" < ")}), never loosen it ` +
+                  `(FR-037 R1).`,
+                { code: "ERR_MUTABILITY_DOWNGRADE", source: ownField.source },
+              ),
+            );
+          }
+        }
+      }
+    }
+
+    // The remaining rules read the EFFECTIVE tree — an inherited mode is just as
+    // binding as a declared one for "is this combination coherent?".
+    for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
+      const mode = fieldMutability(field);
+
+      // 3) ERR_MUTABILITY_AUTOSET_CONFLICT — @autoSet with a non-readWrite mode.
+      //    Both arms: readOnly (representable-but-unvalidated in the boolean era)
+      //    and writeOnce (new). @autoSet means the SERVER supplies the value, so
+      //    constraining who ELSE may write it is contradictory, not additive.
+      if (mode !== MUTABILITY_READ_WRITE && field.attr(FIELD_ATTR_AUTO_SET) !== undefined) {
+        errors.push(
+          new ParseError(
+            `field "${field.name}" on "${obj.name}" declares @autoSet together with ` +
+              `@mutability: "${mode}". @autoSet already means the SERVER supplies the value; ` +
+              `@mutability says who may write it. Drop @mutability (an @autoSet field is ` +
+              `already excluded from every input shape) or drop @autoSet (FR-037 R1).`,
+            { code: "ERR_MUTABILITY_AUTOSET_CONFLICT", source: field.source },
+          ),
+        );
+      }
+
+      // 5) WARN_MUTABILITY_READONLY_HOST — writeOnce on a host nothing writes.
+      //    Benign: the declaration is inert, not wrong, and a projection may
+      //    legitimately inherit it from the entity it extends.
+      if (mode === MUTABILITY_WRITE_ONCE && hostNeverWritten) {
+        warnings.push({
+          code: "WARN_MUTABILITY_READONLY_HOST",
+          message:
+            `field "${field.name}" on "${obj.name}" declares @mutability: "writeOnce", but its ` +
+            `host is never written (a projection, or a read-only source @kind). The declaration ` +
+            `is inert — nothing creates a row here for it to be settable on.`,
+          source: field.source,
+        });
+      }
+    }
+
+    // 4) ERR_READONLY_ASSIGNED_PRIMARY — readOnly on an ASSIGNED primary key.
+    //    Note what is NOT here: `writeOnce` on an assigned key is legal, and is
+    //    the natural declaration for one. That asymmetry is why this code keeps
+    //    its readOnly-specific name.
+    if (!isValueObject) {
+      const primaryAssignedFields = primaryAssignedFieldNames(obj);
+      if (primaryAssignedFields.size > 0) {
+        for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
+          if (!primaryAssignedFields.has(field.name)) continue;
+          if (fieldMutability(field) !== MUTABILITY_READ_ONLY) continue;
+          errors.push(
+            new ParseError(
+              `field "${field.name}" on "${obj.name}" is @mutability: "readOnly" AND the target ` +
+                `of identity.primary with @generation: "assigned"; the application has no path ` +
+                `to populate the identity value. Use @mutability: "writeOnce" if the intent is ` +
+                `"set once on create, never changed" (FR-037 R1).`,
+              { code: "ERR_READONLY_ASSIGNED_PRIMARY", source: field.source },
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/** The mode a node DECLARED (own), or undefined when it declared none. */
+function declaredMode(field: MetaData): MutabilityMode | undefined {
+  // ADR-0039: own — the downgrade rule needs the EXPLICIT mode on the DECLARING
+  // node; resolving would report the child's own value back at itself.
+  const v = field.ownAttr(FIELD_ATTR_MUTABILITY);
+  return isMutabilityMode(v) ? v : undefined;
+}
+
+/** True when no write path reaches this object: an object.projection, or an
+ *  object whose every source is a read-only `@kind`. */
+function isWriteHostReadOnly(obj: MetaData): boolean {
+  if (obj.subType === OBJECT_SUBTYPE_PROJECTION) return true;
+  // ADR-0039: resolving — a source may be inherited via extends.
+  const sources = obj.children().filter((c) => c.type === TYPE_SOURCE);
+  if (sources.length === 0) return false;
+  return sources.every((s) => isReadOnlySource(s));
+}
+
+/** Walk the extends chain looking for a field with the same name; return its
+ *  declaring node (own attrs preserved) if found. */
+function inheritedField(obj: MetaData, name: string): MetaData | undefined {
+  let cursor = obj.superResolved;
+  while (cursor !== undefined) {
+    // ADR-0039: own — super-chain walk reading each level's OWN fields to find the
+    // declaring node (the comparison needs the declaring node's own mode).
+    const f = cursor.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === name);
+    if (f !== undefined) return f;
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
+/** Names of fields participating in any identity.primary with @generation:
+ *  "assigned" on `obj` or its extends chain. */
+function primaryAssignedFieldNames(obj: MetaData): Set<string> {
+  const out = new Set<string>();
+  for (const id of obj.children()) {
+    if (id.type !== TYPE_IDENTITY) continue;
+    if (id.subType !== IDENTITY_SUBTYPE_PRIMARY) continue;
+    // ADR-0039: resolving — an identity may inherit @generation / @fields via extends.
+    const gen = id.attr(IDENTITY_ATTR_GENERATION);
+    if (gen !== GENERATION_ASSIGNED) continue;
+    const fields = id.attr(IDENTITY_ATTR_FIELDS);
+    if (Array.isArray(fields)) {
+      for (const fName of fields) {
+        if (typeof fName === "string") out.add(fName);
+      }
+    } else if (typeof fields === "string") {
+      out.add(fields);
+    }
+  }
+  return out;
+}

package/src/core/identity/identity-constants.ts

@@ -15,6 +15,22 @@ export const IDENTITY_SUBTYPES = [
 ] as const;
 export type IdentitySubType = (typeof IDENTITY_SUBTYPES)[number];
 
+/**
+ * The identity subtypes that denote a UNIQUE key.
+ *
+ * ADR-0040 put uniqueness in the TYPE: `identity.primary` and `identity.secondary` are both
+ * unique keys (secondary IS the unique alternate key — `@unique` was removed from it
+ * precisely because the subtype already says so), while `identity.reference` is a foreign
+ * key and carries no uniqueness at all.
+ *
+ * Named here because more than one rule needs "is this a candidate key?" and answering it
+ * by listing subtypes at each site is how the two drift apart.
+ */
+export const IDENTITY_UNIQUE_KEY_SUBTYPES: readonly string[] = [
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+];
+
 // ---------------------------------------------------------------------------
 // Identity attrs
 // ---------------------------------------------------------------------------

package/src/core/object/object-definition.embedded.ts

@@ -104,7 +104,7 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
       "extendsBase": true,
       "description": "A value object — pure shape with NO identity and NO source, ever. Constructed (by caller / embedding), never populated from a store. May `extends` an entity's fields to reuse shape. Equality is by content.",
       "whenToUse": "You need a reusable typed shape with NO identity and NO table — an embedded value, a DTO, a prompt/response payload. Constructed in memory, never persisted on its own.",
-      "rules": "object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller or by embedding — and is never populated from a backing store. A value-hosted field may carry origin.passthrough (FR-015 parameter lineage) but NEVER an assembly origin (origin.aggregate / origin.computed / origin.collection / origin.first) — passthrough on a value is lineage; assembly origins live on object.projection (#210). It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).",
+      "rules": "object.value is pure shape: it NEVER declares an identity and NEVER declares a source, in any role. It is constructed — by a caller or by embedding — and is never populated from a backing store. A value-hosted field may carry origin.passthrough (FR-015 parameter lineage) but NEVER an assembly origin (origin.aggregate / origin.computed / origin.first) — passthrough on a value is lineage; assembly origins live on object.projection (#210). It may `extends` an entity's fields to reuse their shape. @normalize is the object-level default ASCII normalization mode applied to this value's enum fields' tolerant extract (each field may still override per-field). See ADR-0028 (object taxonomy, value purity).",
       "children": [
         {
           "type": "relationship",
@@ -121,7 +121,7 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
       "extendsBase": true,
       "description": "A derived read-only representation of entities. Its fields are extends-bound / origin-derived / self-declared-under-external-assembly, all read-only at the subtype level. Identity is optional and MUST extend an entity identity; sources are restricted to read-only @kinds. The declared field set IS the exposure (inclusive, fail-closed).",
       "whenToUse": "You need a derived, read-only view over entities — a report, summary, or joined/aggregated read model. Declare it (with origin.* children) instead of hand-writing the SELECT/joins; it stays read-only and regenerates.",
-      "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. The assembly origins (origin.aggregate / origin.computed / origin.collection / origin.first) live HERE, not on object.value; a SOURCELESS projection is the legal shape for a wire-assembled read model, and a template-level @payloadRef/@responseRef may target one (#210). See ADR-0028 (object taxonomy, projection).",
+      "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. The assembly origins (origin.aggregate / origin.computed / origin.first) live HERE, not on object.value; a SOURCELESS projection is the legal shape for a wire-assembled read model, and a template-level @payloadRef/@responseRef may target one (#210). See ADR-0028 (object taxonomy, projection).",
       "children": [
         {
           "type": "attr",

package/src/core/requirement/meta-requirement.ts

@@ -13,7 +13,6 @@ import {
   REQUIREMENT_ATTR_DISPOSITION,
   REQUIREMENT_ATTR_TRACKED_BY,
   REQUIREMENT_ATTR_IMPLEMENTED_BY,
-  REQUIREMENT_ATTR_VERIFIED_BY,
   REQUIREMENT_LINK_FLOOR_LEVEL,
   REQUIREMENT_STATUS_PLANNED,
   REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
@@ -78,11 +77,6 @@ export class MetaRequirement extends MetaData {
     return Array.isArray(v) ? (v as string[]) : [];
   }
 
-  verifiedBy(): string[] {
-    const v = this.attr(REQUIREMENT_ATTR_VERIFIED_BY);
-    return Array.isArray(v) ? (v as string[]) : [];
-  }
-
   /** True when this requirement is permitted to reference the model at all.
    *
    *  An UNLEVELLED architectural requirement always may — its claim set is the
@@ -98,7 +92,7 @@ export class MetaRequirement extends MetaData {
   }
 
   /** True when a dangling `@implementedBy` is an ERROR rather than expected.
-   *  An abandoned or superseded requirement's nodes are supposed to be gone. */
+   *  `planned` is the only exemption — there the nodes do not exist YET. */
   requiresLiveNodes(): boolean {
     const s = this.status();
     return s !== undefined && REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES.includes(s);

package/src/core/requirement/requirement-constants.ts

@@ -34,10 +34,8 @@ export const REQUIREMENT_ATTR_STATUS = "status";
 export const REQUIREMENT_ATTR_DISPOSITION = "disposition";
 export const REQUIREMENT_ATTR_TRACKED_BY = "trackedBy";
 export const REQUIREMENT_ATTR_STATEMENT = "statement";
-export const REQUIREMENT_ATTR_VIOLATION = "violation";
+export const REQUIREMENT_ATTR_COUNTEREXAMPLE = "counterexample";
 export const REQUIREMENT_ATTR_IMPLEMENTED_BY = "implementedBy";
-export const REQUIREMENT_ATTR_VERIFIED_BY = "verifiedBy";
-export const REQUIREMENT_ATTR_SUPERSEDED_BY = "supersededBy";
 
 // ---------------------------------------------------------------------------
 // Status — a closed enum, enforced by the registry via `allowedValues`. This is
@@ -49,22 +47,17 @@ export const REQUIREMENT_ATTR_SUPERSEDED_BY = "supersededBy";
 export const REQUIREMENT_STATUS_PLANNED = "planned";
 export const REQUIREMENT_STATUS_LIVE = "live";
 export const REQUIREMENT_STATUS_PARTIAL = "partial";
-export const REQUIREMENT_STATUS_ABANDONED = "abandoned";
-export const REQUIREMENT_STATUS_SUPERSEDED = "superseded";
 
 export const REQUIREMENT_STATUSES = [
   REQUIREMENT_STATUS_PLANNED,
   REQUIREMENT_STATUS_LIVE,
   REQUIREMENT_STATUS_PARTIAL,
-  REQUIREMENT_STATUS_ABANDONED,
-  REQUIREMENT_STATUS_SUPERSEDED,
 ] as const;
 export type RequirementStatus = (typeof REQUIREMENT_STATUSES)[number];
 
 /** Statuses whose implementing nodes are supposed to still exist. A dangling
  *  `@implementedBy` on one of these means the model moved and the requirement is
- *  stale. On `planned` the nodes do not exist YET; on `abandoned`/`superseded`
- *  they are supposed to be GONE — which is the whole point of those entries. */
+ *  stale. `planned` is the only exemption — there the nodes do not exist YET. */
 export const REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES: readonly RequirementStatus[] = [
   REQUIREMENT_STATUS_LIVE,
   REQUIREMENT_STATUS_PARTIAL,

package/src/core/requirement/requirement-definition.embedded.ts

@@ -32,11 +32,9 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
           "allowedValues": [
             "planned",
             "live",
-            "partial",
-            "abandoned",
-            "superseded"
+            "partial"
           ],
-          "description": "planned intended but not built yet; live implemented and in use; partial implemented with known gaps; abandoned built then deliberately retired; superseded replaced by a different mechanism. A dangling @implementedBy is an ERROR on live/partial (the model moved, the requirement is stale) and ALLOWED on planned/abandoned/superseded — on planned the nodes do not exist YET, on the other two they are meant to be gone, and that is the entry doing its job. A planned requirement also never contributes to object coverage: planning a capability must not silence the warning that nothing implements it."
+          "description": "planned intended but not built yet; live implemented and in use; partial implemented with known gaps. A requirement is PRESCRIPTIVE — it states what SHOULD happen and is never a journal of what happened — so a capability that no longer applies is DELETED, not annotated as retired; the record of it having existed belongs to version control and to notes on the entries that survive. A dangling @implementedBy is an ERROR on live/partial (the model moved, the requirement is stale) and ALLOWED on planned, where the nodes do not exist YET. A planned requirement also never contributes to object coverage: planning a capability must not silence the warning that nothing implements it."
         },
         {
           "type": "attr",
@@ -57,7 +55,7 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
           "isArray": true,
           "min": 0,
           "max": 1,
-          "description": "Issue or ticket references for outstanding work — a URL, an owner/repo#123 shorthand, or a tracker key. Free-form and NOT resolved by verify, which does not reach the network; unlike @verifiedBy, nothing here is checked to exist. Its job is to stop a deferred gap becoming invisible, so verify warns when a deferred requirement names no ticket. Also the right place to link the ticket that a planned requirement will be built under."
+          "description": "Issue or ticket references for outstanding work — a URL, an owner/repo#123 shorthand, or a tracker key. Free-form and NOT resolved by verify, which does not reach the network; nothing here is checked to exist. Its job is to stop a deferred gap becoming invisible, so verify warns when a deferred requirement names no ticket. Also the right place to link the ticket that a planned requirement will be built under."
         },
         {
           "type": "attr",
@@ -70,10 +68,10 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
         {
           "type": "attr",
           "subType": "string",
-          "name": "violation",
+          "name": "counterexample",
           "min": 1,
           "max": 1,
-          "description": "What breaking it looks like, in one sentence. A requirement MUST be violable: 'every entity has a uuid primary key' is (point at one with a composite string key); 'things are persisted' is not, and is a description rather than a requirement."
+          "description": "What breaking it looks like, in one sentence — a STATIC falsifiability test, authored once, never a state. A requirement MUST be violable: 'every entity has a uuid primary key' is (point at one with a composite string key); 'things are persisted' is not, and is a description rather than a requirement. Renamed from @violation in 0.24.0, which read as a status."
         },
         {
           "type": "attr",
@@ -84,23 +82,6 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
           "max": 1,
           "description": "FQN references to the model nodes realising this requirement. Legal on level 4 (an object) and level 5 (a field, view or identity) only; an organisational level carrying it is ERR_REQUIREMENT_LINK_ABOVE_FLOOR. Many-to-many by construction — several requirements may name the same node."
         },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "verifiedBy",
-          "isArray": true,
-          "min": 0,
-          "max": 1,
-          "description": "OPTIONAL — omit unless you have opened the test and read what it asserts. Names of tests that assert the behaviour. verify checks each name EXISTS and is not skipped; it never runs them, and it cannot tell whether the named test verifies this requirement — any occurrence in the test corpus satisfies it."
-        },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "supersededBy",
-          "min": 0,
-          "max": 1,
-          "description": "The requirement that replaced this one. Expected on status=superseded."
-        },
         {
           "type": "requirement",
           "subType": "*",
@@ -134,9 +115,7 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
           "allowedValues": [
             "planned",
             "live",
-            "partial",
-            "abandoned",
-            "superseded"
+            "partial"
           ],
           "description": "As on requirement.functional. A live or partial architectural requirement claimed by NOTHING is an error: a policy declared and applied to nothing. A planned one is exempt from that check — it is not applied yet by definition."
         },
@@ -172,10 +151,10 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
         {
           "type": "attr",
           "subType": "string",
-          "name": "violation",
+          "name": "counterexample",
           "min": 1,
           "max": 1,
-          "description": "What breaking it looks like — the node that would contradict it. This is what makes universality checkable."
+          "description": "What breaking it looks like — the node that would contradict it. A STATIC falsifiability test, not a state. This is what makes universality checkable. Renamed from @violation in 0.24.0, which read as a status."
         },
         {
           "type": "attr",
@@ -186,23 +165,6 @@ export const REQUIREMENT_DEFINITION: ProviderDefinition = {
           "max": 1,
           "description": "FQN references to the nodes applying this policy. High fan-out is normal and expected: one uuid-primary-key requirement is claimed by every entity."
         },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "verifiedBy",
-          "isArray": true,
-          "min": 0,
-          "max": 1,
-          "description": "OPTIONAL — omit unless you have opened the test and read what it asserts. Names of tests that assert the policy holds. verify checks each name EXISTS and is not skipped; it never runs them, and it cannot tell whether the named test verifies this requirement — any occurrence in the test corpus satisfies it."
-        },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "supersededBy",
-          "min": 0,
-          "max": 1,
-          "description": "The requirement that replaced this one. Expected on status=superseded."
-        },
         {
           "type": "requirement",
           "subType": "*",

package/src/core/requirement/resolve-claim.ts

@@ -0,0 +1,98 @@
+// resolveClaim — resolve an `@implementedBy` reference to the node it names.
+//
+// Moved here from the CLI's requirement-check so `codegen-ts` can share ONE
+// resolver (FR-038): the requirement-test generator has to know each claimed
+// node's TYPE to fan out per concern, and a second implementation would fork the
+// ADR-0042 package-local binding contract the loader already owns.
+
+import { TYPE_OBJECT, TYPE_REQUIREMENT } from "../../shared/base-types.js";
+import { PACKAGE_SEPARATOR } from "../../shared/structural.js";
+import { resolveObjectRef } from "../../naming-refs.js";
+import type { MetaData } from "../../shared/meta-data.js";
+
+/**
+ * Resolve the owner segment of an `@implementedBy` reference to the node it names.
+ *
+ * OBJECTS FIRST, through the loader's own resolver, so package-local binding stays the
+ * ADR-0042 contract and never a parallel name scan (#228).
+ *
+ * Then ROOT-LEVEL NON-OBJECT nodes — `template.prompt` and its siblings today. The
+ * attribute is documented as naming "the model nodes realising this requirement", and a
+ * declared prompt is one: it is the durable artifact a capability like "the game master
+ * is told what the party can see" actually lives in. Resolving only objects meant the
+ * prompt estate — the thing whose retirement is hardest to see in a model, since a
+ * removed prompt leaves no table behind — was the one part of a model that could not
+ * carry a status. So L4 means "a declared top-level model node", not "an object".
+ *
+ * Requirements themselves are excluded: hierarchy is nesting, and a requirement claiming
+ * a requirement would be a second, contradictory parent mechanism.
+ */
+export function resolveClaimTarget(
+  root: MetaData,
+  owner: string,
+  referrerPkg: string,
+): MetaData | undefined {
+  const { node } = resolveObjectRef(root, owner, referrerPkg);
+  if (node !== undefined) return node;
+
+  const candidates = root
+    .children()
+    .filter((c) => c.type !== TYPE_OBJECT && c.type !== TYPE_REQUIREMENT);
+
+  // A fully-qualified reference binds exactly, like every other FQN in the model.
+  if (owner.includes(PACKAGE_SEPARATOR)) {
+    return candidates.find((c) => c.resolutionKey() === owner);
+  }
+  // A bare reference prefers the referrer's own package, then a root-level node of that
+  // bare name. An ambiguous bare name binds NOTHING — same fail-closed rule objects use,
+  // because silently picking one of two same-named nodes is how a claim ends up pointing
+  // at the wrong thing without anyone noticing.
+  const local =
+    referrerPkg === ""
+      ? []
+      : candidates.filter(
+          (c) => c.resolutionKey() === `${referrerPkg}${PACKAGE_SEPARATOR}${owner}`,
+        );
+  if (local.length === 1) return local[0];
+  // Root-level (unpackaged) only, matching resolveObjectRef's own bare fallback. A bare
+  // ref must not reach into an arbitrary package just because the name is unique there.
+  const bare = candidates.filter(
+    (c) => c.name === owner && c.resolutionKey() === owner,
+  );
+  return bare.length === 1 ? bare[0] : undefined;
+}
+
+/** Walk dotted member segments by CHILD NAME from an object node.
+ *
+ *  Exported alongside `resolveClaimTarget` because the CLI's coverage pass needs the
+ *  OWNER node's `resolutionKey()` while only using member resolution as a yes/no
+ *  validity test. Composing them into `resolveClaim` there would key coverage on the
+ *  member instead of the object — a silent behaviour change. */
+export function resolveMember(obj: MetaData, path: string[]): MetaData | undefined {
+  let cur: MetaData | undefined = obj;
+  for (const seg of path) {
+    if (cur === undefined) return undefined;
+    cur = cur.children().find((c) => c.name === seg);
+  }
+  return cur;
+}
+
+/**
+ * Resolve a full `@implementedBy` reference — owner segment plus any dotted member
+ * segments — to the node it names, or undefined when it does not resolve.
+ *
+ * Resolution walks to the FULL depth of the reference, so `Council.slug.display`
+ * yields the view node rather than stopping at the field. FR-038's fan-out keys on
+ * the resolved node's type, and a resolver that stopped short would silently collapse
+ * two concerns into one.
+ */
+export function resolveClaim(
+  root: MetaData,
+  ref: string,
+  referrerPkg: string,
+): MetaData | undefined {
+  const segs = ref.split(".");
+  const owner = resolveClaimTarget(root, segs[0] ?? "", referrerPkg);
+  if (owner === undefined || segs.length === 1) return owner;
+  return resolveMember(owner, segs.slice(1));
+}

package/src/core-types.ts

@@ -39,7 +39,7 @@ import {
 import { MetaRelationship } from "./core/relationship/meta-relationship.js";
 import { MetaLayout } from "./presentation/layout/meta-layout.js";
 import { MetaSource } from "./persistence/source/meta-source.js";
-import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin, MetaCollectionOrigin, MetaComputedOrigin, MetaFirstOrigin } from "./persistence/origin/meta-origin.js";
+import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin, MetaComputedOrigin, MetaFirstOrigin } from "./persistence/origin/meta-origin.js";
 import { defineProviderFromData, type FactoryMap } from "./provider-data.js";
 import { FIELD_DEFINITION } from "./core/field/field-definition.embedded.js";
 import { OBJECT_DEFINITION } from "./core/object/object-definition.embedded.js";
@@ -104,7 +104,6 @@ import {
   ORIGIN_SUBTYPES,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
-  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_SUBTYPE_COMPUTED,
   ORIGIN_SUBTYPE_FIRST,
 } from "./persistence/origin/origin-constants.js";
@@ -169,7 +168,6 @@ const IDENTITY_CLASS_MAP = new Map<string, NodeConstructor>([
 const ORIGIN_CLASS_MAP = new Map<string, NodeConstructor>([
   [ORIGIN_SUBTYPE_PASSTHROUGH, MetaPassthroughOrigin],
   [ORIGIN_SUBTYPE_AGGREGATE, MetaAggregateOrigin],
-  [ORIGIN_SUBTYPE_COLLECTION, MetaCollectionOrigin],
   [ORIGIN_SUBTYPE_COMPUTED, MetaComputedOrigin],
   [ORIGIN_SUBTYPE_FIRST, MetaFirstOrigin],
 ]);
@@ -377,8 +375,7 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
   // defineProviderFromData lowers it to TypeDefinitions; the factory (behavior)
   // stays code via ORIGIN_FACTORIES, dispatching subType→class:
   //   passthrough → MetaPassthroughOrigin, aggregate → MetaAggregateOrigin,
-  //   collection → MetaCollectionOrigin, base (and any unmapped subtype) →
-  //   MetaOrigin (fallback).
+  //   base (and any unmapped subtype) → MetaOrigin (fallback).
   // FR-033 S1-simple: origin is an ATTR-ONLY type — the "any attr" wildcard child
   // rule is DROPPED (strict/fail-closed) and childRules are left EMPTY; the named
   // attrs still enforce strictly, a misplaced STRUCTURAL child is now
@@ -400,13 +397,15 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
   // (ADR-0011). Four subtypes: base + prompt + output + toolcall; attr-only
   // children. A single MetaTemplate class backs every subtype (mirrors source);
   // per-subtype attr schemas drive validation (prompt + output require
-  // @payloadRef + @textRef + @format closed enum; prompt adds the LLM overlay;
-  // output adds @promptStyle + @kind/email part-refs; toolcall has its own set —
-  // @toolName + @payloadRef, no @textRef requirement since toolcalls have no
+  // @payloadRef + @textRef + @format closed enum; prompt adds the LLM overlay
+  // plus the ADR-0052 inbound half (@responseRef/@promptStyle/@responseFormat);
+  // output adds @kind/email part-refs and is OUTBOUND ONLY; toolcall has its own
+  // set — @toolName + @payloadRef, no @textRef requirement since toolcalls have no
   // renderable body).
   // FR-033: the template provider's declarative definition (the 4-subtype
   // vocabulary + the full per-subtype attr constraints — incl. @format/@promptStyle/
-  // @kind closed-enum allowedValues + defaults + required @payloadRef/@toolName —
+  // @responseFormat/@kind closed-enum allowedValues + defaults + required
+  // @payloadRef/@toolName —
   // + real descriptions + the FR-004/ADR-0011 rules prose) is externalized to
   // spec/metamodel/template.json, embedded at build into TEMPLATE_DEFINITION.
   // defineProviderFromData lowers it to TypeDefinitions; the factory (behavior)
@@ -525,7 +524,7 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
   }
   // NOTE: @implementedBy is deliberately NOT declared as a loader `references`
   // descriptor. That pass always ERRORS on an unresolved target, and a
-  // requirement with status `abandoned`/`superseded` exists precisely to name
+  // requirement with status `planned` names nodes that do not exist YET, so declaring
   // nodes that are GONE — declaring it here would make the entries that carry
   // the mechanism's only controlled evidence fail to load. The loader owns what
   // is unconditional (the status enum, shape, levels); `meta verify` owns the