@metaobjectsdev/metadata 1.0.13 → 1.1.1-rc.1

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

@@ -0,0 +1,192 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/reporting.json
+// Regenerate: bun run scripts/generate-embedded-metamodel.ts
+//
+// Embeds the canonical FR-033 ProviderDefinition so the provider can register
+// itself wherever the on-disk spec/ tree is unavailable (bundled builds).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const REPORTING_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "dimension",
+      "subType": "attribute",
+      "description": "A named group-by attribute of the entity that declares it (FR-044). Groups report rows by a column value as-is. @of names Entity.field: the owning entity, or the @via terminal. @via may follow only to-one hops, so grouping by a related row's column can never multiply the measured rows.",
+      "whenToUse": "A column a dashboard groups by: product, status, region. Declare it once on the fact entity and reference it by name from reports.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "of",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted Entity.field reference naming the grouped column (e.g. 'Purchase.programId', or 'Program.title' with @via)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 0,
+          "max": 1,
+          "description": "Optional dotted to-one relationship path from the owning entity to the entity @of names (e.g. 'Purchase.program'). Every hop must be @cardinality: one or an identity.reference."
+        }
+      ]
+    },
+    {
+      "type": "dimension",
+      "subType": "time",
+      "description": "A named time dimension (FR-044): groups report rows by a date or timestamp column truncated to a grain. @of names a field.date or field.timestamp. Weeks start on Monday (ISO-8601) in every lowering. A report names it as 'dimension:grain' and the derived report field is <dimension><Grain> (e.g. purchasedAtDay).",
+      "whenToUse": "Per-day, per-week or per-month series on a dashboard.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "of",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted Entity.field reference naming the date or timestamp column."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 0,
+          "max": 1,
+          "description": "Optional dotted to-one relationship path, as on dimension.attribute."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "grains",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "hour",
+            "day",
+            "week",
+            "month",
+            "quarter",
+            "year"
+          ],
+          "description": "The grains this dimension supports. Weeks start Monday (ISO-8601). 'hour' is refused on a field.date."
+        }
+      ]
+    },
+    {
+      "type": "measure",
+      "subType": "aggregate",
+      "description": "A named aggregate over the declaring entity's own rows (FR-044). @agg count without @distinct counts rows; with @distinct it counts distinct values of @of (a list in @of is a distinct count of the tuple). Unlike origin.aggregate, count is NOT distinct by default: a measure aggregates its own rows and dimensions reach only to-one paths, so no join inflates it.",
+      "whenToUse": "A number a dashboard shows: revenue, purchases, distinct buyers, last activity.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "agg",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "count",
+            "sum",
+            "avg",
+            "min",
+            "max",
+            "any",
+            "all"
+          ],
+          "description": "The aggregate function. sum/avg need a numeric field; min/max refuse boolean, object and map fields; any/all (boolean OR / AND, Postgres bool_or / bool_and) type the measure boolean and take either a field.boolean in @of or no @of, when they ask whether some row (any) or every row (all) passes the measure's @filter / @segment."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "of",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Dotted Entity.field reference(s) on the declaring entity. A bare string is one column; more than one requires @agg: count and @distinct: true. Required for every @agg except any/all, which may omit it to quantify their @filter / @segment over the rows."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "distinct",
+          "min": 0,
+          "max": 1,
+          "description": "Count distinct values. Legal only with @agg: count."
+        },
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 0,
+          "max": 1,
+          "description": "Optional row scope (a portable attr.filter over the declaring entity's fields). May use relative-date values ({ now: \"-P7D\" }). Combines with @segment by AND."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "segment",
+          "min": 0,
+          "max": 1,
+          "description": "Optional name of a segment declared on the same entity. Combines with @filter by AND."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "default",
+          "min": 0,
+          "max": 1,
+          "description": "Optional integer the measure reads when it would otherwise be null: nothing matched, every matched value is null, or (a ratio) the denominator is zero or null. The derived report field is then never null. Refused on @agg: count (a count is never null), on min/max over a field that is not numeric, and on @agg any/all unless it is 0 (false) or 1 (true). A ratio's operand carries its own @default into the ratio."
+        }
+      ]
+    },
+    {
+      "type": "measure",
+      "subType": "ratio",
+      "description": "A named quotient of two numeric measure.aggregate siblings (FR-044), lowered as numerator / NULLIF(denominator, 0) and typed decimal. A zero denominator yields null.",
+      "whenToUse": "Averages per unit that are not a plain avg: average days engaged per starter.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "numerator",
+          "min": 1,
+          "max": 1,
+          "description": "Name of a measure.aggregate on the same entity whose result is numeric: a count, a sum, an avg, or a min or max of a numeric field."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "denominator",
+          "min": 1,
+          "max": 1,
+          "description": "Name of a measure.aggregate on the same entity whose result is numeric: a count, a sum, an avg, or a min or max of a numeric field."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "default",
+          "min": 0,
+          "max": 1,
+          "description": "Optional integer the measure reads when it would otherwise be null: nothing matched, every matched value is null, or (a ratio) the denominator is zero or null. The derived report field is then never null. Refused on @agg: count (a count is never null) and on min/max over a field that is not numeric. A ratio's operand carries its own @default into the ratio."
+        }
+      ]
+    },
+    {
+      "type": "segment",
+      "subType": "filter",
+      "description": "A named, reusable row filter on the declaring entity (FR-044). Measures and reports reference it by name; exporters emit it as a named segment.",
+      "whenToUse": "The same filter (e.g. 'active purchase') would otherwise be repeated in several measures or reports.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 1,
+          "max": 1,
+          "description": "The row scope: a portable attr.filter over the declaring entity's fields. May use relative-date values."
+        }
+      ]
+    }
+  ]
+};

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

@@ -96,3 +96,23 @@ export function resolveClaim(
   if (owner === undefined || segs.length === 1) return owner;
   return resolveMember(owner, segs.slice(1));
 }
+
+/**
+ * The package a requirement node resolves in (ADR-0059 D3/D10): its own declared
+ * `package`, else the nearest enclosing node that declares one, else the file default
+ * package of the top-level node it sits under, else "". One definition for the gate, the summary and
+ * codegen's requirement-test fan-out, so nesting and overlay contribution cannot
+ * make two call sites disagree.
+ */
+export function effectiveRequirementPackage(node: MetaData): string {
+  let cur: MetaData = node;
+  for (;;) {
+    if (cur.package !== undefined && cur.package !== "") return cur.package;
+    const parent: MetaData | undefined = cur.parent;
+    // The tree root is not an "enclosing node": stop at the top-level node, whose file
+    // default package is the answer (a child contributed by another document inherits
+    // the merge target's, matching the overlay-declared package case).
+    if (parent === undefined || parent.parent === undefined) return cur.fileDefaultPackage ?? "";
+    cur = parent;
+  }
+}

package/src/core/yaml-desugar.ts

@@ -35,13 +35,9 @@ import {
   RESERVED_KEYS,
   RESERVED_KEY_CHILDREN,
   RESERVED_KEY_NAME,
-  RESERVED_KEY_PACKAGE,
-  RESERVED_KEY_EXTENDS,
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
-  PACKAGE_SEPARATOR,
 } from "../shared/structural.js";
-import { expandRef, REF_BEARING_ATTR_NAMES } from "../naming-refs.js";
 import {
   getPositionMap,
   setPositionMap,
@@ -76,34 +72,13 @@ export interface DesugarResult {
 /** Desugar a parsed-YAML authoring document into a canonical-shaped object. */
 export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
   const errors: CollectedError[] = [];
-  // FR-032 (ADR-0032): the desugar threads the effective package context down
-  // the tree so every ref-bearing attr (extends + @objectRef/@references/@from/
-  // @of/@via/@parameterRef/@payloadRef/@responseRef) is expanded to its FQN via
-  // expandRef. The root context is empty (the metadata.root's own `package`
-  // body key seeds the first real context inside desugarNode).
-  const node = desugarNode(input, registry, errors, "<root>", "");
+  // ADR-0059 R1: the desugar is syntax only. Reference VALUES (extends, @objectRef,
+  // @of, ...) pass through exactly as written; the loader's one resolver gives every
+  // form its meaning once the whole tree exists.
+  const node = desugarNode(input, registry, errors, "<root>");
   return { canonical: node ?? {}, errors };
 }
 
-// FR-032: compute a node's effective package from its raw `package` body key
-// (inheriting the parent context when absent). Mirrors parser-core's
-// expandPackageForPath so the desugar's ref-expansion context matches the JSON
-// loader's package resolution. The `package` attr itself is NEVER ref-expanded
-// (ADR-0032 §2.1 — it is the node's identity, taken literally/absolute).
-function effectivePackageFor(rawBody: unknown, parentPkg: string): string {
-  if (typeof rawBody !== "object" || rawBody === null || Array.isArray(rawBody)) {
-    return parentPkg;
-  }
-  const rawPkg = (rawBody as Record<string, unknown>)[RESERVED_KEY_PACKAGE];
-  if (typeof rawPkg !== "string") return parentPkg;
-  // Legacy expandPackageForPath: a leading "::" on a child package prepends the
-  // parent; otherwise it is used as-is.
-  if (parentPkg !== "" && rawPkg.startsWith(PACKAGE_SEPARATOR)) {
-    return parentPkg + rawPkg;
-  }
-  return rawPkg;
-}
-
 // Desugar one node — a single-key mapping { "type.subType": body }.
 // Returns the canonical node object, or undefined if `input` is not a usable
 // node (the caller substitutes a placeholder).
@@ -112,7 +87,6 @@ function desugarNode(
   registry: TypeRegistry,
   errors: CollectedError[],
   path: string,
-  parentPkg: string,
 ): Record<string, unknown> | undefined {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
     errors.push({ message: `Node at ${path} must be a mapping with one type key` });
@@ -149,16 +123,11 @@ function desugarNode(
   // Rule 1: a bare `type` key → the type's registry default subType.
   const canonicalKey = resolveKey(key, registry, errors, path);
 
-  // FR-032: this node's effective package context (its own `package` body key,
-  // else inherited). Used to expand its ref-bearing attrs AND threaded to its
-  // children so their bare/relative refs resolve against the right package.
-  const nodePkg = effectivePackageFor(rawBody, parentPkg);
-
   // Rule 2: a scalar body → { name: <scalar> }.
   // FR5b — propagate the wrapper-key's position into the synthesized body
   // when the input body was a scalar (no body-side positions to inherit).
   const wrapperKeyPos = wrapperPositions?.[rawKey];
-  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos, nodePkg);
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -169,7 +138,7 @@ function desugarNode(
     const children: unknown[] = [];
     for (let i = 0; i < rawChildren.length; i++) {
       const childPath = `${path}.${RESERVED_KEY_CHILDREN}[${i}]`;
-      const child = desugarNode(rawChildren[i], registry, errors, childPath, nodePkg);
+      const child = desugarNode(rawChildren[i], registry, errors, childPath);
       // On a bad child keep an empty-object placeholder so sibling indices
       // stay stable; the error is already collected.
       children.push(child ?? {});
@@ -230,10 +199,6 @@ function desugarBody(
    *  empty bodies; for mapping bodies we use the body's own position-by-key
    *  map. */
   wrapperKeyPos: { line: number; col: number } | undefined,
-  /** FR-032: this node's effective package context, used to expand its
-   *  ref-bearing attrs (extends + @objectRef/@references/@from/@of/@via/
-   *  @parameterRef/@payloadRef/@responseRef) to FQN via expandRef. */
-  nodePkg: string,
 ): Record<string, unknown> {
   if (
     typeof rawBody === "string" ||
@@ -280,26 +245,16 @@ function desugarBody(
     let outKey: string;
     if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
       outKey = key;
-      // FR-032: expand a ref-bearing value to FQN. `extends` (reserved) and the
-      // @-prefixed ref attrs are expanded; everything else is copied verbatim.
+      // ADR-0059 R1: every value, references included, is copied as written.
       const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
-      if (key === RESERVED_KEY_EXTENDS || (attrName !== "" && REF_BEARING_ATTR_NAMES.has(attrName))) {
-        out[key] = expandRefValue(src[key], nodePkg, errors, path, key);
-      } else {
-        out[key] = src[key];
-      }
+      out[key] = src[key];
       // D2 also applies to author-written @-keys (the awkward form).
       if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
         checkCoercion(attrName, src[key], schemaIndex, errors, path);
       }
     } else {
       outKey = `${ATTR_PREFIX}${key}`;
-      // FR-032: a bare (sigil-free) ref-bearing attr is expanded to FQN too.
-      if (REF_BEARING_ATTR_NAMES.has(key)) {
-        out[outKey] = expandRefValue(src[key], nodePkg, errors, path, outKey);
-      } else {
-        out[outKey] = src[key];
-      }
+      out[outKey] = src[key];
       checkCoercion(key, src[key], schemaIndex, errors, path);
     }
     const pos = srcPositions?.[key];
@@ -312,41 +267,6 @@ function desugarBody(
   return out;
 }
 
-// ---------------------------------------------------------------------------
-// FR-032 (ADR-0032) — expand a ref-bearing value to FQN.
-//
-// A ref value is a single string (most refs) or a string-array (@references can
-// carry multiple). expandRef preserves any FR-024 dotted child suffix and the
-// `package` attr is never touched here (it is not a ref). A parent-relative
-// over-drop (more `..::` than the package has segments) throws inside expandRef;
-// we collect it as ERR_BAD_ATTR_VALUE and pass the raw value through so the rest
-// of the desugar/load proceeds and surfaces a single actionable error.
-// ---------------------------------------------------------------------------
-
-function expandRefValue(
-  raw: unknown,
-  nodePkg: string,
-  errors: CollectedError[],
-  path: string,
-  refLabel: string,
-): unknown {
-  if (typeof raw === "string") {
-    try {
-      return expandRef(raw, nodePkg);
-    } catch (err) {
-      errors.push({
-        message: `Cannot expand reference '${refLabel}' at ${path}: ${(err as Error).message}`,
-        code: "ERR_BAD_ATTR_VALUE",
-      });
-      return raw;
-    }
-  }
-  if (Array.isArray(raw)) {
-    return raw.map((el) => (typeof el === "string" ? expandRefValue(el, nodePkg, errors, path, refLabel) : el));
-  }
-  return raw;
-}
-
 // ---------------------------------------------------------------------------
 // D2 — YAML type-coercion guard
 // ---------------------------------------------------------------------------

package/src/core-types.ts

@@ -60,6 +60,15 @@ import { INDEX_SUBTYPES } from "./core/index/index-constants.js";
 import { MetaRequirement } from "./core/requirement/meta-requirement.js";
 import { REQUIREMENT_DEFINITION } from "./core/requirement/requirement-definition.embedded.js";
 import { REQUIREMENT_SUBTYPES } from "./core/requirement/requirement-constants.js";
+import { MetaDimension } from "./core/reporting/meta-dimension.js";
+import { MetaMeasure } from "./core/reporting/meta-measure.js";
+import { MetaSegment } from "./core/reporting/meta-segment.js";
+import { REPORTING_DEFINITION } from "./core/reporting/reporting-definition.embedded.js";
+import {
+  DIMENSION_SUBTYPES,
+  MEASURE_SUBTYPES,
+  SEGMENT_SUBTYPES,
+} from "./core/reporting/reporting-constants.js";
 import {
   TYPE_METADATA,
   TYPE_OBJECT,
@@ -75,6 +84,9 @@ import {
   TYPE_TEMPLATE,
   TYPE_INDEX,
   TYPE_REQUIREMENT,
+  TYPE_DIMENSION,
+  TYPE_MEASURE,
+  TYPE_SEGMENT,
   SUBTYPE_ROOT,
 } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
@@ -510,6 +522,35 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     registry.register(reqDef);
   }
 
+  // FR-044 reporting vocabulary — dimension / measure / segment. Declared as
+  // children of `object.entity` (spec/metamodel/object.json), never root-level, so
+  // no root wildcard is added above. Three types in one provider file because they
+  // are one vocabulary: a report names dimensions and measures, and both may
+  // reference a segment. `measure.derived` is NOT registered (waits for FR-037 R5).
+  const REPORTING_FACTORIES: FactoryMap = {
+    ...Object.fromEntries(
+      DIMENSION_SUBTYPES.map((subType) => [
+        `${TYPE_DIMENSION}.${subType}`,
+        (typeId: TypeId, name: string) => new MetaDimension(typeId, name),
+      ]),
+    ),
+    ...Object.fromEntries(
+      MEASURE_SUBTYPES.map((subType) => [
+        `${TYPE_MEASURE}.${subType}`,
+        (typeId: TypeId, name: string) => new MetaMeasure(typeId, name),
+      ]),
+    ),
+    ...Object.fromEntries(
+      SEGMENT_SUBTYPES.map((subType) => [
+        `${TYPE_SEGMENT}.${subType}`,
+        (typeId: TypeId, name: string) => new MetaSegment(typeId, name),
+      ]),
+    ),
+  };
+  for (const reportingDef of defineProviderFromData(REPORTING_DEFINITION, REPORTING_FACTORIES)) {
+    registry.register(reportingDef);
+  }
+
   // Declare the core cross-references ON their TypeDefinitions, so the loader's
   // registry-derived validation resolves them generically (a dangling target fails the
   // load). Set on the concrete subtypes the parser produces. (Production moves these into

package/src/docs-ref.ts

@@ -0,0 +1,41 @@
+// docs-ref.ts — where a guide URL points, derived from the running version.
+//
+// A guide URL that says `blob/main` moves after the release is cut, and no installed
+// package ships the guides, so the CLI and the agent context name the TAG of the release
+// they belong to: `blob/v1.1.0/...`. A prerelease version has no tag, so it keeps `main`.
+// The repository URL and the rule live here once; nothing else spells either. This file is
+// pure (browser-safe, reachable from the root entry); reading the running version is the
+// Node-side `release-docs.ts`.
+
+/** The public repository the guides live in. */
+export const DOCS_REPO_URL = "https://github.com/metaobjectsdev/metaobjects";
+
+/** The branch a prerelease or an unresolvable version links to. */
+export const DOCS_DEFAULT_REF = "main";
+
+const RELEASE_VERSION = /^\d+\.\d+\.\d+$/;
+
+/**
+ * The git ref a guide URL pins to: `v<version>` for a release (`1.1.0` → `v1.1.0`),
+ * `main` for anything with no tag — a prerelease (`1.1.0-rc.7`), the `0.0.0` sentinel a
+ * port stamps when it cannot resolve its own version, or text that is not a version.
+ */
+export function docsRefForVersion(version: string): string {
+  const v = version.trim();
+  return RELEASE_VERSION.test(v) && v !== "0.0.0" ? `v${v}` : DOCS_DEFAULT_REF;
+}
+
+/** `https://github.com/<repo>/blob/<ref>/<repoRelativePath>`. */
+export function docsBlobUrl(repoRelativePath: string, ref: string = DOCS_DEFAULT_REF): string {
+  return `${DOCS_REPO_URL}/blob/${ref}/${repoRelativePath.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Rewrite every `…/blob/main/` link into this repository, inside `text`, to `ref`.
+ * Authors of shipped prose write `main` as the placeholder; the pin is applied once, at
+ * render time, so no template carries a version.
+ */
+export function pinDocsRefs(text: string, ref: string): string {
+  if (ref === DOCS_DEFAULT_REF) return text;
+  return text.split(`${DOCS_REPO_URL}/blob/${DOCS_DEFAULT_REF}/`).join(`${DOCS_REPO_URL}/blob/${ref}/`);
+}

package/src/errors.ts

@@ -201,12 +201,6 @@ export const ERROR_CODES = [
   // ADR-0023 — a registration was attempted against a registry sealed after its
   // agreed metamodel-provider bootstrap. Codegen cannot invent metamodel attrs.
   "ERR_REGISTRY_SEALED",
-  // FR-032 (ADR-0032) — a ref-bearing attr (extends/@objectRef/@references/
-  // origin @from/@of/@via/@parameterRef/@payloadRef/@responseRef) in CANONICAL
-  // JSON used a relative authoring form (leading `::` or `..::`). Canonical JSON
-  // is the self-contained interchange form: every ref MUST be fully-qualified.
-  // Relative navigation is YAML-only (the desugar expands it via expandRef).
-  "ERR_RELATIVE_REF_IN_CANONICAL",
   // FR-033 — a provider set's merged metamodel constraint graph is contradictory.
   // Surfaced by validateConstraints (constraint-validate.ts) at registry compose:
   // dangling ref / unsatisfiable required child / bad cardinality / closed-set
@@ -218,6 +212,23 @@ export const ERROR_CODES = [
   // @fields), whichever is declared supplies no key, or a named field does not exist
   // on the owning entity's effective (resolved via extends) field set.
   "ERR_INVALID_INDEX",
+  // FR-044 — reporting vocabulary (validateReporting, loader/reporting-validation.ts).
+  // Rule ids D1-D4 / M1-M6 / R1-R7 are the cross-port rule table; S1/F1/F2 reuse
+  // ERR_BAD_ATTR_FILTER.
+  // A dimension's @of/@via does not resolve, @via crosses a to-many hop, or a
+  // time dimension's column or grains do not fit its type (D1-D4).
+  "ERR_INVALID_DIMENSION",
+  // A measure's @of is not a field of its own entity, a tuple/@distinct/@agg
+  // combination is illegal, @segment does not resolve, or a ratio operand is not a
+  // measure.aggregate of the same entity (M1-M6).
+  "ERR_INVALID_MEASURE",
+  // An object.report's @from is not an entity, a @dimensions/@measures/@segment
+  // item does not resolve, it declares a field/identity or a writable source, or
+  // two items derive the same report field name (R1-R7).
+  "ERR_INVALID_REPORT",
+  // An object.report lists a measure that belongs to an entity other than @from;
+  // v1 refuses multi-fact reports (R3).
+  "ERR_REPORT_FOREIGN_MEASURE",
   // FR-039 — a requirement.* with @status: retired declares @implementedBy. Refused
   // rather than exempted: a retired capability has no implementation BY DEFINITION,
   // so forbidding the attribute makes the dangling-reference class unreachable

package/src/fmt.ts

@@ -149,7 +149,9 @@ export function formatMetadataFile(content: string, opts: FormatFileOptions): Fo
       };
     }
 
-    return { ok: true, text: canonicalSerialize(result.root) };
+    // ADR-0059 (C2): formatting never rewrites a reference — refs and packages are
+    // written as authored; only layout, key order and sugar are normalized.
+    return { ok: true, text: canonicalSerialize(result.root, { refs: "authored" }) };
   } catch (err) {
     return {
       ok: false,

package/src/index.ts

@@ -42,9 +42,52 @@ export * from "./core/identity/identity-constants.js";
 export * from "./core/index/index-constants.js";
 export * from "./core/requirement/requirement-constants.js";
 export { MetaRequirement } from "./core/requirement/meta-requirement.js";
+export * from "./core/reporting/reporting-constants.js";
+export { MetaDimension } from "./core/reporting/meta-dimension.js";
+export { MetaMeasure } from "./core/reporting/meta-measure.js";
+export { MetaSegment } from "./core/reporting/meta-segment.js";
+export {
+  reportFrom,
+  reportSpine,
+  reportDimensionItems,
+  reportMeasureNames,
+  reportMeasureItemName,
+  reportMeasureItemOwner,
+  reportDerivedFieldName,
+  type ReportDimensionItem,
+} from "./core/reporting/report-accessors.js";
+export {
+  measureDerivedSubType,
+  reportShape,
+  reportSpineEntity,
+  reportSpineHops,
+  reportingMemberOwner,
+  reportingViaHops,
+  resolveReportingFieldRef,
+  resolveDimensionOf,
+  type ReportField,
+  type ReportFieldRole,
+  type ReportShape,
+} from "./core/reporting/report-shape.js";
+export { reportReadModel, reportReadSource } from "./core/reporting/report-read-model.js";
+export {
+  describeDimension,
+  describeDimensionColumn,
+  describeFilter,
+  describeMeasure,
+  describeReportField,
+  describeReportRowScope,
+  describeReportRows,
+  describeRowScope,
+  describeSegment,
+  reportFieldTypeName,
+  reportNotServedReason,
+  reportingDescribedAttrs,
+} from "./core/reporting/report-describe.js";
 // Shared `@implementedBy` resolution — one resolver for the CLI's requirement
 // checks and codegen's requirement-test fan-out (FR-038).
 export {
+  effectiveRequirementPackage,
   resolveClaim,
   resolveClaimTarget,
   resolveMember,
@@ -81,6 +124,9 @@ export {
 // Core node classes
 export { MetaObject } from "./core/object/meta-object.js";
 export { MetaField } from "./core/field/meta-field.js";
+// The one authority for "which type does this enum field have" — the loader's #246
+// check and every codegen site share it (ADR-0026 Amendment 1).
+export { isSharedEnumDeclaration, resolveSharedEnumDeclaration } from "./core/field/shared-enum.js";
 export { MetaAttr } from "./core/attr/meta-attr.js";
 
 // Runtime object model — backing objects + FQN→factory binding (Phase A).
@@ -193,7 +239,7 @@ export { ExclusionReason } from "./registry-manifest-exclusions.js";
 
 // FR-033 S3 — metamodel doc-gen: tiered, LLM-readable docs FOR THE METAMODEL
 // (the type/subtype/attr vocabulary), generated from the strict registry.
-// Distinct from `meta docs --model` (which documents a user's entities).
+// Distinct from the `docs` generator (which documents a user's entities).
 export {
   renderMetamodelDocs,
   buildMetamodelProvenance,
@@ -251,7 +297,22 @@ export type { FormatFileOptions, FormatFileResult } from "./fmt.js";
 export { resolveSuperRef } from "./super-resolve.js";
 
 // FR-032 (ADR-0032) — canonical reference expansion + FQN object matching.
-export { expandRef, isRelativeRef, refMatchesObject, resolveObjectRef, didYouMeanHint, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
+export {
+  expandRef,
+  isRelativeRef,
+  refMatchesObject,
+  resolveObjectRef,
+  resolveRef,
+  lookupCanonical,
+  refTarget,
+  spellRef,
+  splitChildTail,
+  RefOverDropError,
+  didYouMeanHint,
+  didYouMeanSuperHint,
+  REF_BEARING_ATTR_NAMES,
+} from "./naming-refs.js";
+export { resolveReferences } from "./loader/resolve-references.js";
 
 // Loader hierarchy
 export { MetaDataLoader, declaredTopLevelKeys } from "./loader/meta-data-loader.js";
@@ -299,17 +360,24 @@ export type { Scope, CompiledScope } from "./scope.js";
 export { validateAttrSchema } from "./attr-schema-validate.js";
 export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
 
+// Guide URLs pinned to the running release's tag (prerelease → main).
+export {
+  DOCS_REPO_URL, DOCS_DEFAULT_REF, docsRefForVersion, docsBlobUrl, pinDocsRefs,
+} from "./docs-ref.js";
+
 // Naming — hoisted from runtime-ts in v0.2.3 so multiple consumers (runtime-ts, migrate-ts, codegen-ts)
 // share identical name resolution. See spec §4.1.
 export {
   toSnakeCase, toKebabCase, pluralize, pluralizeTableNameLegacy,
-  applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY,
+  applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, COLUMN_NAMING_STRATEGIES,
+  TABLE_NAMING_RULES, DEFAULT_PHYSICAL_NAMING, physicalNamingOf, applyTableNamingRule,
+  PHYSICAL_NAMING_MIGRATION_GUIDE, PHYSICAL_NAMING_MIGRATION_GUIDE_PATH, physicalNamingRemovedMessage,
   resolveTableName, resolveColumnName, resolveTableSchema, resolveIndexName,
   primaryRdbSource, sourceAddressKey,
   buildNameMap,
   stripPackage, packageOfResolutionKey,
 } from "./naming.js";
-export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
+export type { EntityNameMap, ColumnNamingStrategy, PhysicalNaming, TableNamingRule } from "./naming.js";
 
 // Retired vocabulary: the map the loader reads to explain a retirement, and the raw-document
 // rewriter `meta upgrade` drives from the SAME entries — so the error message and the fix