@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.1

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

@@ -18,9 +18,9 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
     {
       "type": "template",
       "subType": "prompt",
-      "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef.",
-      "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code.",
-      "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation.",
+      "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef. A prompt declaring @responseRef also owns the INBOUND half (ADR-0052): the parser-on-receipt, the FR-010 response-format fragment (@promptStyle), and the reply syntax (@responseFormat).",
+      "whenToUse": "You are sending text to an LLM. Declare a prompt template with a typed payload so the prompt is versioned, drift-checked against its fields, and cache-stable — instead of string-building it in code. Add @responseRef when you also want the reply parsed into a typed shape.",
+      "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is the syntax of the rendered PROMPT body, a closed enum keyed by the render engine's escaper; @responseFormat (ADR-0053) is the syntax of the model's REPLY. @responseRef (optional) names the response value-object the prompt expects, drives typed LLM-call trace derivation, and is the sole gate on the inbound codegen tier — which keys on its presence, never on a format value.",
       "children": [
         {
           "type": "attr",
@@ -120,16 +120,43 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
           "name": "responseRef",
           "min": 0,
           "max": 1,
-          "description": "Optional ref to the response value-object this prompt expects (peer of @payloadRef; drives typed LLM-call trace derivation)."
+          "description": "Optional ref to the response value-object this prompt expects (peer of @payloadRef; drives typed LLM-call trace derivation). Its presence is the sole gate on the inbound codegen tier (ADR-0052): parser-on-receipt, tolerant extract, and the FR-010 response-format fragment."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "promptStyle",
+          "min": 0,
+          "max": 1,
+          "default": "guide",
+          "allowedValues": [
+            "guide",
+            "inline",
+            "exampleOnly"
+          ],
+          "description": "FR-010 response-format fragment presentation: 'guide' (prose list + example), 'inline' (inline placeholders / enum choices), or 'exampleOnly' (filled skeleton). Guidance is never emitted as comments."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "responseFormat",
+          "min": 0,
+          "max": 1,
+          "default": "json",
+          "allowedValues": [
+            "json",
+            "xml"
+          ],
+          "description": "ADR-0053: the syntax of the model's REPLY, read by the parser-on-receipt and the FR-010 response-format fragment. Distinct from @format, which is the syntax of the rendered PROMPT body. Two members because two is what every shipping consumer dispatches on; the other @format members are reserved-not-registered."
         }
       ]
     },
     {
       "type": "template",
       "subType": "output",
-      "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs, the FR-010 @promptStyle, and the @kind + email part-refs.",
-      "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time.",
-      "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments.",
+      "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs and the @kind + email part-refs. OUTBOUND ONLY (ADR-0052) — it renders, and generates no parser.",
+      "whenToUse": "You render a document/email/serialized output from typed data. Declare an output template so the {{fields}} are drift-checked against the payload VO at build time. To parse a model's reply instead, declare @responseRef on the template.prompt that elicits it — never a template.output.",
+      "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper. template.output is OUTBOUND ONLY (ADR-0052): it emits a render helper and nothing that reads a model's reply — the parser-on-receipt, the tolerant extract and the FR-010 response-format fragment all belong to template.prompt @responseRef.",
       "children": [
         {
           "type": "attr",
@@ -198,20 +225,6 @@ export const TEMPLATE_DEFINITION: ProviderDefinition = {
           "max": 1,
           "description": "Output tags the rendered text must contain (drives the verify output-tag check)."
         },
-        {
-          "type": "attr",
-          "subType": "string",
-          "name": "promptStyle",
-          "min": 0,
-          "max": 1,
-          "default": "guide",
-          "allowedValues": [
-            "guide",
-            "inline",
-            "exampleOnly"
-          ],
-          "description": "FR-010 output-format prompt presentation: 'guide' (prose list + example), 'inline' (inline placeholders / enum choices), or 'exampleOnly' (filled skeleton). Guidance is never emitted as comments."
-        },
         {
           "type": "attr",
           "subType": "string",

package/src/vocabulary-rewrite.ts

@@ -0,0 +1,350 @@
+// server/typescript/packages/metadata/src/vocabulary-rewrite.ts
+//
+// The raw-document rewriter behind `meta upgrade`.
+//
+// WHY IT CANNOT USE THE LOADER — the constraint that shapes everything here. Once an
+// attribute is deregistered, metadata carrying it FAILS THE LOAD; that is the point of a
+// retirement. So load → transform → canonical-serialize is impossible: the input does not
+// load, and the canonical serializer needs a loaded model. This operates on RAW TEXT.
+//
+// That is also what makes the upgrade path exist at all. An adopter installs the new CLI and
+// runs this against metadata the new CLI REFUSES. A fixer that needed a successful load
+// would be a chicken-and-egg with no exit.
+//
+// SURGICAL, NOT PARSE-AND-REPRINT. Adopters author JSONC with comments and meaningful key
+// order — `meta gen`'s output order, review conventions, "do not reorder" notes. A
+// round-trip through JSON.parse/stringify destroys all of it while reporting success. So
+// every edit here is a span replacement on the original text, and any region we did not
+// deliberately change comes back byte-identical.
+//
+// IT SCOPES EVERY OCCURRENCE, NOT EVERY FILE. Retirements are type-scoped — `@unique` is
+// retired on `identity.secondary` and perfectly live on a field — so the governing type is
+// a property of WHERE the attribute sits, not of the document it sits in. A file-level
+// scope was the original shape and it was wrong in both directions: a caller that ran one
+// pass per type key present in the file let the `identity.secondary` scope reach a
+// `field.string`'s `@unique` (branding live vocabulary retired, and with a `dropAttr` entry
+// DELETING it), and reported every wildcard-scoped refusal once per subtype key in the file.
+// `scopeRanges` below recovers the enclosing `"<type>.<subType>"` for each occurrence, so
+// one pass over the document answers both correctly.
+//
+// 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 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
+// describes are all defensible, and a wrong guess emits metadata that LOADS and means
+// something different — strictly worse than leaving it alone, because the adopter would
+// believe the migration finished.
+
+import {
+  RETIRED_VOCABULARY,
+  note,
+  scopeMatches,
+  type RetiredEntry,
+  type RetirementNote,
+} from "./retired-vocabulary.js";
+
+export interface RewriteChange {
+  /** Attribute name, without the sigil. */
+  readonly attr: string;
+  readonly from: string;
+  readonly to: string;
+  /** 1-indexed line in the ORIGINAL document. */
+  readonly line: number;
+}
+
+export interface RewriteRefusal extends RetirementNote {
+  /** What was refused, ready to print: `@status` for an attribute, `origin.collection` for
+   *  a retired subtype. Carries its own sigil so a caller never has to guess which. */
+  readonly subject: string;
+  readonly value?: string;
+  readonly line: number;
+}
+
+export interface RewriteResult {
+  readonly text: string;
+  readonly changes: readonly RewriteChange[];
+  readonly refusals: readonly RewriteRefusal[];
+}
+
+export interface RewriteOpts {
+  /** Only apply retirements at or before this version. */
+  readonly maxVersion?: string;
+}
+
+/** `0.24.0` → `[0,24,0]`, for an ordered comparison rather than a string one. */
+function parts(v: string): number[] {
+  return v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+}
+
+function atOrBefore(a: string, b: string): boolean {
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] ?? 0) - (y[i] ?? 0);
+    if (d !== 0) return d < 0;
+  }
+  return true;
+}
+
+/** 1-indexed line of `index` in `text`. */
+function lineAt(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === "\n") line++;
+  return line;
+}
+
+/**
+ * Offset just past the bracket closing the one at `open`, or undefined if unbalanced.
+ * String-aware, so a brace inside a JSON string literal cannot unbalance the scan.
+ */
+function closingBracket(text: string, open: number): number | undefined {
+  const close = text[open] === "[" ? "]" : "}";
+  const openCh = text[open];
+  let depth = 0;
+  let inStr = false;
+  for (let j = open; j < text.length; j++) {
+    const c = text[j];
+    if (inStr) {
+      if (c === "\\") j++;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === openCh) depth++;
+    else if (c === close) {
+      depth--;
+      if (depth === 0) return j + 1;
+    }
+  }
+  return undefined;
+}
+
+/** One `{ "<type>.<subType>": { … } }` node body, and where it sits in the text. */
+interface ScopeRange {
+  readonly typeKey: string;
+  /** Offset of the opening quote of the type key — where a reader would point. */
+  readonly keyIndex: number;
+  readonly bodyStart: number;
+  readonly bodyEnd: number;
+}
+
+/**
+ * Every node body in the document, in source order.
+ *
+ * A canonical-JSON node is `{ "<type>.<subType>": { …body… } }`, so an attribute belongs to
+ * the INNERMOST body containing it — which is what makes per-occurrence scoping possible
+ * without a parser we deliberately do not have.
+ */
+function scopeRanges(source: string): ScopeRange[] {
+  const ranges: ScopeRange[] = [];
+  const re = /"([a-z][A-Za-z0-9]*)\.([A-Za-z0-9_*]+)"\s*:\s*\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    const bodyStart = m.index + m[0].length - 1;
+    const bodyEnd = closingBracket(source, bodyStart);
+    if (bodyEnd === undefined) continue;
+    ranges.push({ typeKey: `${m[1]}.${m[2]}`, keyIndex: m.index, bodyStart, bodyEnd });
+  }
+  return ranges;
+}
+
+/** The type key governing `offset` — the innermost body containing it. */
+function scopeAt(ranges: readonly ScopeRange[], offset: number): string | 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;
+}
+
+/**
+ * Matches `"@name"` at a key position, plus the separator that follows, capturing the key
+ * separately so a replacement can keep the original spacing.
+ *
+ * Deliberately NOT a full parser. A parser would have to reproduce the document to emit it,
+ * which is the thing this exists to avoid; matching a key occurrence lets every untouched
+ * byte survive by construction.
+ */
+function keyPattern(attr: string): RegExp {
+  return new RegExp(`("@?${attr}")(\\s*:\\s*)`, "g");
+}
+
+/** The JSON value token starting at `from` — a scalar, or a bracketed array/object. */
+function valueSpan(text: string, from: number): { start: number; end: number; raw: string } | undefined {
+  let i = from;
+  while (i < text.length && /\s/.test(text[i] ?? "")) i++;
+  const open = text[i];
+  if (open === "[" || open === "{") {
+    const end = closingBracket(text, i);
+    return end === undefined ? undefined : { start: i, end, raw: text.slice(i, end) };
+  }
+  // Scalar: to the next comma, closing brace, or newline, whichever comes first.
+  let j = i;
+  let inStr = false;
+  for (; j < text.length; j++) {
+    const c = text[j];
+    if (inStr) {
+      if (c === "\\") j++;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === "," || c === "}" || c === "\n") break;
+  }
+  return { start: i, end: j, raw: text.slice(i, j).trim() };
+}
+
+/** Does the raw token equal this literal? Compares JSON-decoded where possible so
+ *  `"readOnly"` and `readOnly` both match a string literal. */
+function rawEquals(raw: string, want: unknown): boolean {
+  try {
+    return JSON.parse(raw) === want;
+  } catch {
+    return raw === String(want);
+  }
+}
+
+/**
+ * The span to delete so that removing a key leaves loadable JSON.
+ *
+ * The arithmetic is fiddly and every branch is load-bearing, so it lives here with its
+ * steps named rather than inline in the dispatch below.
+ */
+function dropSpan(source: string, keyStart: number, valueEnd: number): { start: number; end: number } {
+  // 1. Absorb the value's trailing spaces, then its trailing comma if it has one.
+  let end = valueEnd;
+  while (end < source.length && /[ \t]/.test(source[end] ?? "")) end++;
+  const hadTrailingComma = source[end] === ",";
+  if (hadTrailingComma) end++;
+
+  // 2. Absorb the key's own indentation, so the removal does not leave a ragged line.
+  let start = keyStart;
+  while (start > 0 && /[ \t]/.test(source[start - 1] ?? "")) start--;
+
+  // 3. THE LAST-KEY CASE, found by dogfooding rather than by a unit test: when the retired
+  //    attr is last in its object there IS no trailing comma — the comma belongs to the
+  //    PRECEDING key. Dropping without taking it leaves `"...",\n}`, which does not parse.
+  //    A tool whose whole job is producing loadable metadata cannot emit invalid JSON.
+  if (!hadTrailingComma) {
+    let back = start;
+    while (back > 0 && /\s/.test(source[back - 1] ?? "")) back--;
+    if (source[back - 1] === ",") start = back - 1;
+  }
+
+  // 4. If the key owned its whole line, take the line terminator too rather than leaving a
+  //    blank line. Otherwise the key shares a line with other content, so undo step 2's
+  //    indentation trim — it would eat the separating space after the preceding key's comma.
+  if (source[start - 1] === "\n" && source[end] === "\n") end++;
+  else if (start > 0 && source[start - 1] !== "\n" && hadTrailingComma) start = keyStart;
+
+  return { start, end };
+}
+
+/**
+ * Rewrite retired vocabulary in one raw canonical-JSON metadata document.
+ *
+ * Pure: no filesystem, no loader, no registry. Returns the new text plus every change and
+ * every refusal, so a caller can print a diff and exit non-zero when work remains.
+ */
+export function rewriteDocument(source: string, opts: RewriteOpts = {}): RewriteResult {
+  const changes: RewriteChange[] = [];
+  const refusals: RewriteRefusal[] = [];
+
+  // Edits are collected as spans against the ORIGINAL text and applied in one pass at the
+  // end, right-to-left. Rewriting incrementally would invalidate every later offset.
+  const edits: { start: number; end: number; text: string }[] = [];
+
+  const inWindow = (e: RetiredEntry): boolean =>
+    opts.maxVersion === undefined || atOrBefore(e.since, opts.maxVersion);
+  const ranges = scopeRanges(source);
+
+  // A retired SUBTYPE has no attribute to rewrite — the node itself has to be re-modelled
+  // (`origin.collection` becomes `origin.aggregate @agg: collect`), which is a judgment the
+  // adopter makes. Reporting it is what keeps `meta upgrade` from exiting 0 on a document
+  // that still will not load; it used to be filtered out entirely and was invisible.
+  for (const r of ranges) {
+    for (const entry of RETIRED_VOCABULARY) {
+      if (entry.isSubTypeRetirement !== true || !inWindow(entry)) continue;
+      if (`${entry.type}.${entry.subType}` !== r.typeKey) continue;
+      refusals.push({ ...note(entry), subject: r.typeKey, line: lineAt(source, r.keyIndex) });
+    }
+  }
+
+  for (const entry of RETIRED_VOCABULARY.filter((e) => e.attr !== undefined && inWindow(e))) {
+    const attr = entry.attr as string;
+    const re = keyPattern(attr);
+    let m: RegExpExecArray | null;
+
+    while ((m = re.exec(source)) !== null) {
+      const keyStart = m.index;
+      const keyEnd = keyStart + (m[1]?.length ?? 0);
+      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 line = lineAt(source, keyStart);
+      const span = valueSpan(source, afterKey);
+
+      // A VALUE-scoped retirement only fires on the retired values. `@dbColumnType: jsonb`
+      // is live vocabulary on the same attribute; touching it would silently change the
+      // column type.
+      if (entry.attrValues !== undefined) {
+        if (!entry.attrValues.some((v) => rawEquals(span?.raw ?? "", v))) continue;
+      }
+
+      const refuse = (): void => {
+        refusals.push({
+          ...note(entry),
+          subject: `@${attr}`,
+          ...(span?.raw !== undefined ? { value: span.raw } : {}),
+          line,
+        });
+      };
+
+      const drop = (): void => {
+        if (span === undefined) return;
+        const { start, end } = dropSpan(source, keyStart, span.end);
+        edits.push({ start, end, text: "" });
+        changes.push({ attr, from: attr, to: "(removed)", line });
+      };
+
+      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 });
+      } else if (rw.kind === "dropAttr") drop();
+      else if (span === undefined) continue;
+      else if (rawEquals(span.raw, rw.fromValue)) {
+        const valText = JSON.stringify(rw.toValue);
+        edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.toAttr}"` });
+        edits.push({ start: span.start, end: span.end, text: valText });
+        changes.push({ attr, from: `${attr}: ${span.raw}`, to: `${rw.toAttr}: ${valText}`, line });
+      }
+      // Every other value of a retired attribute still has to go somewhere — the entry says
+      // which, and the type makes saying it mandatory.
+      else if (rw.otherwise === "drop") drop();
+      else refuse();
+    }
+  }
+
+  edits.sort((a, b) => b.start - a.start);
+  let text = source;
+  for (const e of edits) text = text.slice(0, e.start) + e.text + text.slice(e.end);
+
+  return { text, changes, refusals };
+}

package/dist/core/field/validate-field-readonly.d.ts

@@ -1,9 +0,0 @@
-import type { MetaData } from "../../shared/meta-data.js";
-import { ParseError } from "../../errors.js";
-import type { LoaderWarning } from "../../source.js";
-export interface FieldReadOnlyValidationResult {
-    errors: ParseError[];
-    warnings: LoaderWarning[];
-}
-export declare function validateFieldReadOnly(root: MetaData): FieldReadOnlyValidationResult;
-//# sourceMappingURL=validate-field-readonly.d.ts.map

package/dist/core/field/validate-field-readonly.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"validate-field-readonly.d.ts","sourceRoot":"","sources":["../../../src/core/field/validate-field-readonly.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAerD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,6BAA6B,CAsEnF"}

package/dist/core/field/validate-field-readonly.js

@@ -1,128 +0,0 @@
-// Validation pass: field-level @readOnly cross-attribute rules (FR-013).
-//
-// Codes:
-//   ERR_READONLY_ASSIGNED_PRIMARY — @readOnly: true on a field that is the
-//     target of an identity.primary with @generation: "assigned". The application
-//     has no path to populate the identity value (no setter; not generated; not
-//     defaulted).
-//   ERR_READONLY_DOWNGRADE — a concrete subtype declares @readOnly: false on a
-//     field whose extends-chain parent declares @readOnly: true. Read-only-ness
-//     can only be upgraded, never downgraded.
-//   WARN_READONLY_VALUE_OBJECT — @readOnly: true on a field child of object.value.
-//     The persistence implication does not apply; the attr is retained for
-//     language-specific record/struct treatment.
-import { ParseError } from "../../errors.js";
-import { TYPE_OBJECT, TYPE_FIELD, TYPE_IDENTITY, } from "../../shared/base-types.js";
-import { OBJECT_SUBTYPE_VALUE } 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_READ_ONLY } from "./field-constants.js";
-export function validateFieldReadOnly(root) {
-    const errors = [];
-    const warnings = [];
-    // 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;
-        // 1) WARN_READONLY_VALUE_OBJECT — any @readOnly field child of an object.value.
-        if (isValueObject) {
-            // ADR-0039: own — warns on @readOnly DECLARED on this value's own fields
-            // (readOnlyFlag reads the explicit own flag; the FR-013 read-only checks
-            // are own-vs-super comparisons by design).
-            for (const child of obj.ownChildren()) {
-                if (child.type === TYPE_FIELD && readOnlyFlag(child) === true) {
-                    warnings.push({
-                        code: "WARN_READONLY_VALUE_OBJECT",
-                        message: `field "${child.name}" on object.value "${obj.name}" declares ` +
-                            `@readOnly: true; value-objects have no persistence semantics so ` +
-                            `the read-only contract is advisory (codegen may use it for record/` +
-                            `struct treatment).`,
-                        source: child.source,
-                    });
-                }
-            }
-        }
-        // 2) ERR_READONLY_DOWNGRADE — read-only-ness can only be upgraded across
-        //    extends. Compare own field vs. inherited field's effective @readOnly.
-        // ADR-0039: own — the downgrade check compares this object's OWN explicit
-        // @readOnly:false against the inherited effective value (own-vs-super by design).
-        for (const ownField of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
-            const ownVal = readOnlyFlag(ownField);
-            if (ownVal !== false)
-                continue; // only the explicit downgrade case matters
-            const inherited = inheritedField(obj, ownField.name);
-            if (inherited !== undefined && readOnlyFlag(inherited) === true) {
-                errors.push(new ParseError(`field "${ownField.name}" on "${obj.name}" sets @readOnly: false, but the ` +
-                    `extends-chain parent declares @readOnly: true. Read-only-ness can only be ` +
-                    `upgraded, not downgraded (FR-013).`, { code: "ERR_READONLY_DOWNGRADE", source: ownField.source }));
-            }
-        }
-        // 3) ERR_READONLY_ASSIGNED_PRIMARY — @readOnly: true on a field used in an
-        //    identity.primary whose @generation is "assigned" (effective tree).
-        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 (readOnlyFlag(field) !== true)
-                        continue;
-                    errors.push(new ParseError(`field "${field.name}" on "${obj.name}" is @readOnly: true AND the target ` +
-                        `of identity.primary with @generation: "assigned"; the application has no ` +
-                        `path to populate the identity value (FR-013).`, { code: "ERR_READONLY_ASSIGNED_PRIMARY", source: field.source }));
-                }
-            }
-        }
-    }
-    return { errors, warnings };
-}
-/** Read the explicit @readOnly value from a field's own attrs. Returns
- *  true / false when explicitly set, undefined when absent. */
-function readOnlyFlag(field) {
-    // ADR-0039: own — the FR-013 downgrade rule needs the EXPLICIT own @readOnly on
-    // THIS node (detecting an own :false against an inherited :true); resolving would
-    // mask the downgrade. Deliberate own-vs-super comparison.
-    const v = field.ownAttr(FIELD_ATTR_READ_ONLY);
-    if (typeof v === "boolean")
-        return v;
-    return undefined;
-}
-/** Walk the extends chain looking for a field with the same name; return its
- *  declaring node (own attrs preserved) if found. */
-function inheritedField(obj, name) {
-    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 FR-013 comparison needs the declaring node's own flag).
-        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) {
-    const out = new Set();
-    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;
-}
-//# sourceMappingURL=validate-field-readonly.js.map

package/dist/core/field/validate-field-readonly.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"validate-field-readonly.js","sourceRoot":"","sources":["../../../src/core/field/validate-field-readonly.ts"],"names":[],"mappings":"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"}