@metaobjectsdev/metadata 0.24.0 → 0.24.2

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",

package/src/registry-manifest.ts

@@ -112,7 +112,7 @@ interface ManifestType {
  * 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.10";
+export const METAMODEL_VERSION = "0.13";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {

package/src/retired-vocabulary.ts

@@ -25,6 +25,11 @@
 // 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.
 //
+// ITS SIBLING IS `attr-contradictions.ts` — pairs of LIVE attributes that may not sit on one
+// node. Same two consumers (the loader's diagnostic and the `meta upgrade` rewriter), same
+// reason for existing; kept apart because a retirement matches ONE name while a contradiction
+// matches a PAIR, and merging them would give every entry here fields it can never use.
+//
 // 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
@@ -91,6 +96,7 @@ export interface RetiredEntry extends RetirementNote {
 }
 
 const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
+const RETIRED_STATUS_MIGRATION = "docs/features/migrations/retired-status-restore.md";
 
 export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   // ── 0.24.0: `@violation` is renamed `@counterexample` ──
@@ -124,21 +130,58 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     // behaviour anyone else can observe.
     rewrite: { kind: "dropAttr" },
   },
+  // (@supersededBy is NOT retired vocabulary. 0.24.0 deregistered it; FR-039 registers
+  // it again on `retired` only, and this time it RESOLVES — which is what the
+  // 2026-08-10 ruling asked for at point 4 and never got. An entry here would make
+  // `meta upgrade` delete an attribute the loader now accepts.)
+  // ── FR-039 (0.24.2): `abandoned` / `superseded` become `retired` ──
+  //
+  // These were retired in 0.24.0 on the rule that a requirement never journals what
+  // happened, and `meta upgrade` REFUSED them because what becomes of a retired
+  // capability's record was judgement. FR-039 restores the capability under a name
+  // that states the standing rule rather than the history — `retired` means "this
+  // must not be rebuilt" — so the edit is no longer a judgement call and the tool
+  // can make it.
+  //
+  // TWO entries rather than one value-map, because the rewriter's `renameAttrValue`
+  // carries a single `fromValue` and `attrValues` already scopes each occurrence to
+  // the value it fires on. `otherwise` is therefore unreachable, and is `refuse` so
+  // that a future third member cannot be silently dropped by this entry.
+  //
+  // `@implementedBy` on one of these is handled by ATTR_CONTRADICTIONS, not here —
+  // it is a live attribute made illegal by a sibling's VALUE, which is a different
+  // match shape. Both passes run in one `meta upgrade`, so a legacy entry carrying
+  // both is fully repaired in a single run rather than rewritten into a file that
+  // still will not load.
   {
-    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"],
+    since: "0.24.2",
+    why: "a retired capability is recorded as `retired`, which states the standing rule " +
+         "(do not rebuild this) rather than narrating what happened to it",
+    migration: RETIRED_STATUS_MIGRATION,
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "status",
+      fromValue: "abandoned",
+      toValue: "retired",
+      otherwise: "refuse",
+    },
   },
   {
     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,
+    attrValues: ["superseded"],
+    since: "0.24.2",
+    why: "`superseded` was `retired` plus a pointer, and the pointer is @supersededBy — " +
+         "which is registered again, and now RESOLVES",
+    migration: RETIRED_STATUS_MIGRATION,
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "status",
+      fromValue: "superseded",
+      toValue: "retired",
+      otherwise: "refuse",
+    },
   },
 
   // ── FR-037 R1: @readOnly becomes the @mutability enum (0.24.0) ──

package/src/vocabulary-rewrite.ts

@@ -27,14 +27,24 @@
 // `scopeRanges` below recovers the enclosing `"<type>.<subType>"` for each occurrence, so
 // one pass over the document answers both correctly.
 //
-// CANONICAL JSON ONLY. YAML authoring is real (ADR-0006) but is not rewritable here: a
-// correct YAML editor needs the `yaml` package's CST, and this module is reachable from
-// `src/index.ts`, which the browser-safety test forbids from importing it. A hand-rolled
-// YAML mode was tried and shipped a file-corrupting bug — a multi-item block sequence lost
-// every item but the first, because the value scanner stops at a newline — while the
-// dominant in-repo authoring style (flow mappings, `{ name: x, readOnly: true }`) was not
-// matched at all, so the rename silently did nothing. `meta upgrade` refuses YAML by name
-// instead; a refusal an adopter can act on beats a success they cannot trust.
+// CANONICAL JSON ONLY — YAML lives in `core/vocabulary-rewrite-yaml.ts`, not here. This
+// module is reachable from `src/index.ts`, which may not import the Node-only `yaml`
+// package, so the YAML arm sits behind its own package subpath and `meta upgrade`
+// dynamic-imports it. The split is a bundling constraint, not a difference in contract: both
+// arms return the same result shape, scope every occurrence the same way, and refuse the
+// same retirements.
+//
+// The reason YAML gets a parser and this arm does not: a hand-rolled YAML mode was tried
+// here first and shipped a file-corrupting bug — a multi-item block sequence lost every item
+// but the first, because a scanner stops at a newline — while the dominant authoring style
+// (flow mappings, `{ name: x, readOnly: true }`) was not matched at all. YAML's value extent
+// is not derivable by scanning; JSON's is.
+//
+// IT ALSO RESOLVES ATTRIBUTE CONTRADICTIONS — two LIVE attributes that may not sit on one
+// node (`attr-contradictions.ts`). Same machinery, different match: a retirement finds one
+// key, a contradiction finds a PAIR inside one node body, which is exactly what `scopeRanges`
+// already answers. Doing it by proximity instead ("a `fields` with an `expr` near it") was
+// tried and took a `fields` whose neighbouring `expr` belonged to a SIBLING node.
 //
 // IT REFUSES WHAT IT CANNOT KNOW. A retirement with no `rewrite` (`@status: abandoned`) is
 // reported, never guessed at. Deleting the node, retyping it, and fixing the residue it
@@ -42,6 +52,8 @@
 // something different — strictly worse than leaving it alone, because the adopter would
 // believe the migration finished.
 
+import { ATTR_CONTRADICTIONS, contradictionScopeMatches } from "./attr-contradictions.js";
+import type { AttrContradiction } from "./attr-contradictions.js";
 import {
   RETIRED_VOCABULARY,
   note,
@@ -154,15 +166,71 @@ function scopeRanges(source: string): ScopeRange[] {
   return ranges;
 }
 
-/** The type key governing `offset` — the innermost body containing it. */
-function scopeAt(ranges: readonly ScopeRange[], offset: number): string | undefined {
+/** The innermost node body containing `offset`. */
+function scopeRangeAt(ranges: readonly ScopeRange[], offset: number): ScopeRange | undefined {
   let best: ScopeRange | undefined;
   for (const r of ranges) {
     if (offset <= r.bodyStart || offset >= r.bodyEnd) continue;
     // Properly nested ranges: the innermost containing one starts last.
     if (best === undefined || r.bodyStart > best.bodyStart) best = r;
   }
-  return best?.typeKey;
+  return best;
+}
+
+/** The type key governing `offset`. Derived from the range so the two cannot disagree —
+ *  a retirement asks WHICH type, a contradiction asks WHICH NODE, and answering them from
+ *  two separate walks is how the pair-matching would drift from the scoping. */
+function scopeAt(ranges: readonly ScopeRange[], offset: number): string | undefined {
+  return scopeRangeAt(ranges, offset)?.typeKey;
+}
+
+/** One key occurrence: where the key starts, and where its value begins. */
+interface KeySite {
+  readonly keyStart: number;
+  readonly afterKey: number;
+}
+
+/** Every place `attr` appears as a key inside `range`'s OWN body — a nested node's key of
+ *  the same name belongs to that node, not to this one. Containment alone is not enough:
+ *  a node body contains its children's bodies, so the innermost enclosing range must BE
+ *  this range. That identity test is what proximity matching cannot express. */
+function ownKeys(
+  source: string,
+  ranges: readonly ScopeRange[],
+  range: ScopeRange,
+  attr: string,
+): KeySite[] {
+  const out: KeySite[] = [];
+  const re = keyPattern(attr);
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    if (m.index <= range.bodyStart || m.index >= range.bodyEnd) continue;
+    if (scopeRangeAt(ranges, m.index)?.bodyStart !== range.bodyStart) continue;
+    out.push({ keyStart: m.index, afterKey: m.index + m[0].length });
+  }
+  return out;
+}
+
+
+/** True when `keep` holds one of the entry's `keepValues` (or the entry names none,
+ *  in which case mere presence is the contradiction). */
+function keepValueMatches(source: string, site: KeySite, c: AttrContradiction): boolean {
+  if (c.keepValues === undefined) return true;
+  const raw = valueSpan(source, site.afterKey)?.raw;
+  if (raw === undefined) return false;
+  return c.keepValues.some((v) => rawEquals(raw, v));
+}
+
+/** Does this key carry a string that actually says something? */
+function suppliesText(source: string, site: KeySite): boolean {
+  const raw = valueSpan(source, site.afterKey)?.raw;
+  if (raw === undefined) return false;
+  try {
+    const v: unknown = JSON.parse(raw);
+    return typeof v === "string" && v.trim().length > 0;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -278,6 +346,49 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
     }
   }
 
+  // ── Attribute contradictions: two LIVE attrs that may not sit on one node ──
+  //
+  // Matched per NODE, not per occurrence, because the illegal thing is the pair. `ownKeys`
+  // supplies the node-identity test the proximity approach could not: a `@fields` and an
+  // `@expr` that merely appear near each other may belong to different siblings.
+  //
+  // THE TWO SIDES ARE ASKED DIFFERENT QUESTIONS, mirroring the loader's Rule 1a exactly
+  // (`validation-passes.ts`, `hasFieldsAttr` vs `hasExpr`). The DROP side counts on
+  // PRESENCE — `@fields: []` beside `@expr` is still a declaration of both, and is the case
+  // where the discard is total. The KEEP side counts only when it actually supplies a key,
+  // so `@expr: ""` beside `@fields` is a plain column index the loader accepts and this
+  // must not touch. If those two predicates ever diverge, this deletes an attribute from a
+  // document that was loading.
+  //
+  // IT SEES ONLY THIS NODE'S OWN TEXT. A node declaring `@expr` while INHERITING `@fields`
+  // through `extends` contradicts itself in the loaded model and not on the page, and no
+  // raw-text rewriter can resolve a super-reference. That case stays a refusal from the
+  // loader — correctly, since the fix is on the parent and is the adopter's call.
+  for (const range of ranges) {
+    for (const c of ATTR_CONTRADICTIONS) {
+      if (opts.maxVersion !== undefined && !atOrBefore(c.since, opts.maxVersion)) continue;
+      if (!contradictionScopeMatches(c, range.typeKey)) continue;
+      // `keep` must be present AND, when the entry names values, hold one of them —
+      // otherwise @status and @implementedBy would contradict on every status.
+      if (!ownKeys(source, ranges, range, c.keep).some(
+        (k) => suppliesText(source, k) && keepValueMatches(source, k, c),
+      )) continue;
+
+      for (const site of ownKeys(source, ranges, range, c.drop)) {
+        const span = valueSpan(source, site.afterKey);
+        if (span === undefined) continue;
+        const { start, end } = dropSpan(source, site.keyStart, span.end);
+        edits.push({ start, end, text: "" });
+        changes.push({
+          attr: c.drop,
+          from: c.drop,
+          to: `(removed — @${c.keep} keys this node)`,
+          line: lineAt(source, site.keyStart),
+        });
+      }
+    }
+  }
+
   for (const entry of RETIRED_VOCABULARY.filter((e) => e.attr !== undefined && inWindow(e))) {
     const attr = entry.attr as string;
     const re = keyPattern(attr);
@@ -289,8 +400,9 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
       const afterKey = m.index + m[0].length;
 
       // Scope is decided HERE, per occurrence, from the enclosing node.
-      const scope = scopeAt(ranges, keyStart);
-      if (scope === undefined || !scopeMatches(entry, scope)) continue;
+      const scopeRange = scopeRangeAt(ranges, keyStart);
+      const scope = scopeRange?.typeKey;
+      if (scope === undefined || scopeRange === undefined || !scopeMatches(entry, scope)) continue;
 
       const line = lineAt(source, keyStart);
       const span = valueSpan(source, afterKey);
@@ -321,8 +433,18 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
       const rw = entry.rewrite;
       if (rw === undefined) refuse();
       else if (rw.kind === "renameAttr") {
-        edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.to}"` });
-        changes.push({ attr, from: attr, to: rw.to, line });
+        // A rename onto a key the node ALREADY declares would emit a duplicate — two
+        // `"@counterexample"` members in one object, where JSON parsers silently take
+        // the last and the author's surviving text is the one that loses. Refuse
+        // instead: which of the two sentences is the real one is exactly the judgement
+        // `meta upgrade` does not make.
+        const target = ownKeys(source, ranges, scopeRange, rw.to)
+          .filter((k) => k.keyStart !== keyStart);
+        if (target.length > 0) refuse();
+        else {
+          edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.to}"` });
+          changes.push({ attr, from: attr, to: rw.to, line });
+        }
       } else if (rw.kind === "dropAttr") drop();
       else if (span === undefined) continue;
       else if (rawEquals(span.raw, rw.fromValue)) {