@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/src/subtype-rules.ts

@@ -1,17 +1,37 @@
 // Cross-language subtype rules for object subtypes.
 //
-//   - value objects MUST NOT have a primary identity (error)
+//   - value objects MUST NOT have ANY identity (primary, secondary,
+//     reference) — values are pure data shapes (error, FR-024/ADR-0028)
+//   - value objects MUST NOT have a source.* child — values are not
+//     persisted shapes (error, FR-024/ADR-0028)
 //   - entity objects SHOULD have a primary identity, unless @isAbstract (warning)
+//   - projection objects may only extend other projections (error,
+//     FR-024/ADR-0028); identity on a projection is OPTIONAL (no warning)
+//   - projection sources must have a read-only @kind — view,
+//     materializedView, storedProc, tableFunction (ERR_PROJECTION_SOURCE_WRITABLE)
 //   - base objects have no rule (template, may or may not have identity)
+//   - every identity.* node MUST have a name (FR-024 D2: identities are named,
+//     author-chosen, so the dotted by-name extends form can address them)
+//
+// The entity-primary-source-readonly hard cutover (an entity whose PRIMARY
+// source is a read-only kind must become a projection) is deferred to
+// FR-024 Phase E (B4b) — view-primary entities still load today.
 
 import type { MetaData } from "./shared/meta-data.js";
 import { ParseError } from "./errors.js";
-import { TYPE_OBJECT, TYPE_IDENTITY } from "./shared/base-types.js";
+import {
+  TYPE_OBJECT,
+  TYPE_IDENTITY,
+  TYPE_SOURCE,
+} from "./shared/base-types.js";
 import { IDENTITY_SUBTYPE_PRIMARY } from "./core/identity/identity-constants.js";
 import {
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_PROJECTION,
 } from "./core/object/object-constants.js";
+import { MetaSource } from "./persistence/source/meta-source.js";
+import { SOURCE_READ_ONLY_KINDS } from "./persistence/source/source-constants.js";
 
 export interface SubtypeRuleResult {
   errors: ParseError[];
@@ -26,31 +46,128 @@ export function validateSubtypeRules(root: MetaData): SubtypeRuleResult {
 }
 
 function walk(model: MetaData, errors: ParseError[], warnings: string[]): void {
-  if (model.type === TYPE_OBJECT) {
-    const hasPrimary = model.children().some(
-      (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY,
+  // FR-024 D2 — identity nodes require an author-chosen name (any nesting:
+  // object children AND field-nested identities). A nameless node parses
+  // with name === "".
+  if (model.type === TYPE_IDENTITY && model.name === "") {
+    const owner = model.parent?.fqn();
+    errors.push(
+      new ParseError(
+        `identity.${model.subType}${owner !== undefined && owner !== "" ? ` under '${owner}'` : ""} has no name — ` +
+          `identity nodes require an author-chosen name (e.g. "id") so dotted ` +
+          `extends refs can address them (FR-024)`,
+        { code: "ERR_IDENTITY_NAME_REQUIRED", source: model.source },
+      ),
     );
-    if (model.subType === OBJECT_SUBTYPE_VALUE && hasPrimary) {
+  }
+
+  if (model.type === TYPE_OBJECT) {
+    switch (model.subType) {
+      case OBJECT_SUBTYPE_VALUE:
+        validateValuePurity(model, errors);
+        break;
+      case OBJECT_SUBTYPE_ENTITY:
+        validateEntityIdentity(model, warnings);
+        break;
+      case OBJECT_SUBTYPE_PROJECTION:
+        validateProjectionLicensing(model, errors);
+        break;
+      default:
+        // object.base is a template — no rule.
+        break;
+    }
+  }
+
+  for (const child of model.ownChildren()) {
+    walk(child, errors, warnings);
+  }
+}
+
+// FR-024 value purity (ADR-0028): a value object is a pure data shape — it
+// carries NO identity of any subtype and NO source.
+function validateValuePurity(model: MetaData, errors: ParseError[]): void {
+  for (const child of model.children()) {
+    if (child.type === TYPE_IDENTITY) {
       errors.push(
         new ParseError(
-          `value object '${model.fqn()}' must not have a primary identity ` +
-            `(use subType: "entity" for records with identity)`,
-          { code: "ERR_SUBTYPE_RULE_VIOLATION", source: model.source },
+          `value object '${model.fqn()}' must not have an identity ` +
+            `(${TYPE_IDENTITY}.${child.subType} '${child.name}') — value objects are ` +
+            `pure data shapes; use subType: "entity" for records with identity ` +
+            `(FR-024, ADR-0028)`,
+          { code: "ERR_SUBTYPE_RULE_VIOLATION", source: child.source },
         ),
       );
-    } else if (
-      model.subType === OBJECT_SUBTYPE_ENTITY &&
-      !hasPrimary &&
-      !model.isAbstract
-    ) {
-      warnings.push(
-        `entity object '${model.fqn()}' has no primary identity ` +
-          `(add an identity child or mark @isAbstract: true)`,
+    } else if (child.type === TYPE_SOURCE) {
+      errors.push(
+        new ParseError(
+          `value object '${model.fqn()}' must not have a source ` +
+            `(${TYPE_SOURCE}.${child.subType}) — value objects are not persisted ` +
+            `shapes; use subType: "entity" or "projection" for stored objects ` +
+            `(FR-024, ADR-0028)`,
+          { code: "ERR_SUBTYPE_RULE_VIOLATION", source: child.source },
+        ),
       );
     }
   }
+}
 
+// Entities SHOULD have a primary identity unless abstract (warning).
+function validateEntityIdentity(model: MetaData, warnings: string[]): void {
+  const hasPrimary = model
+    .children()
+    .some(
+      (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY,
+    );
+  if (!hasPrimary && !model.isAbstract) {
+    warnings.push(
+      `entity object '${model.fqn()}' has no primary identity ` +
+        `(add an identity child or mark @isAbstract: true)`,
+    );
+  }
+}
+
+// FR-024 projection licensing (ADR-0028):
+//   - a projection's object-level extends may only target another
+//     object.projection (ERR_SUBTYPE_RULE_VIOLATION);
+//   - every source.* on a projection must have a read-only @kind
+//     (ERR_PROJECTION_SOURCE_WRITABLE);
+//   - identity is OPTIONAL on a projection — no warning when absent.
+function validateProjectionLicensing(
+  model: MetaData,
+  errors: ParseError[],
+): void {
+  const sup = model.superResolved;
+  if (
+    sup !== undefined &&
+    (sup.type !== TYPE_OBJECT || sup.subType !== OBJECT_SUBTYPE_PROJECTION)
+  ) {
+    errors.push(
+      new ParseError(
+        `projection '${model.fqn()}' extends '${sup.fqn()}' which is ` +
+          `${sup.type}.${sup.subType} — a projection may only extend another ` +
+          `projection (FR-024, ADR-0028)`,
+        { code: "ERR_SUBTYPE_RULE_VIOLATION", source: model.source },
+      ),
+    );
+  }
+
+  // OWN sources only: an inherited source is validated on the (projection)
+  // object that declares it; an inherited source from a non-projection super
+  // is unreachable without first tripping the extends rule above.
   for (const child of model.ownChildren()) {
-    walk(child, errors, warnings);
+    if (child.type !== TYPE_SOURCE) continue;
+    const kind =
+      child instanceof MetaSource ? child.effectiveKind : child.subType;
+    if (!SOURCE_READ_ONLY_KINDS.has(kind)) {
+      errors.push(
+        new ParseError(
+          `projection '${model.fqn()}' has a writable source (@kind "${kind}") — ` +
+            `a projection is a derived read-only representation; its sources must ` +
+            `be read-only kinds (view, materializedView, storedProc, ` +
+            `tableFunction) (FR-024, ADR-0028)`,
+          { code: "ERR_PROJECTION_SOURCE_WRITABLE", source: child.source },
+        ),
+      );
+    }
   }
 }

package/src/super-resolve.ts

@@ -1,18 +1,26 @@
-// super reference resolution — package navigation helpers
+// super reference resolution — pure FQN match (FR-032 / ADR-0032)
 //
-// Reference syntax (Java metaobjects-core conventions):
-//   Bare name       "Fruit"            → resolve in contextPackage, then root fallback
-//   Absolute        "::fishstore::Fish" → strip leading ::, walk from root
-//   Relative parent "..::common::id"   → up one package level, then resolve "common::id"
-//   Multi-level     "..::..::shared::User" → up two levels, then resolve "shared::User"
-//   Same-package    "common::id"       → try contextPackage prepend first, then root-rooted
+// FR-032 made canonical refs fully-qualified: the YAML desugar expands every
+// authored relative/bare-current ref to its FQN (`expandRef`, naming-refs.ts),
+// and the canonical-JSON guard rejects any surviving `::`/`..::` form. So the
+// refs that reach this resolver are already FQN, and resolution is a pure tree
+// match:
+//   Qualified  "pkg::Name"            → findInTree(fqn)
+//   Bare       "Name" (rare in-tree)  → current package only (`<ctx>::Name`),
+//                                        then literal (root-level). NO root
+//                                        fallback for a packaged bare ref.
+// The old `::`-strip (absolute), `..::`-reduce (relative) and
+// bare-current-then-root-fallback branches were DELETED — that fallback was the
+// silent-shadowing footgun ADR-0032 removes.
 //
-// Super resolution is now IMMEDIATE during parse (Java behavior).
-// This module provides only the lookup helper; the parser calls it inline.
-// The old resolveSupers() multi-pass walker has been deleted.
+// FR-024: a ref whose final `::`-segment is dotted (`pkg::Customer.id`) targets
+// a child nested in the owner object — resolved type-scoped to the referrer.
+//
+// Super resolution is IMMEDIATE during parse (Java behavior). This module
+// provides only the lookup helper; the parser calls it inline.
 
 import type { MetaData } from "./shared/meta-data.js";
-import { PACKAGE_SEPARATOR, PACKAGE_PARENT } from "./shared/structural.js";
+import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "./shared/structural.js";
 
 // ---------------------------------------------------------------------------
 // Tree search helper
@@ -52,6 +60,51 @@ function findInTree(root: MetaData, fqn: string): MetaData | undefined {
 // Reference parsing & resolution
 // ---------------------------------------------------------------------------
 
+/**
+ * FR-024 (ADR-0029): the type-scope of the node whose `extends` is being
+ * resolved. A dotted `Entity.child` ref selects among the owner's children of
+ * the SAME type as the referrer — a field ref resolves fields, an identity
+ * ref resolves identities. Required for the dotted branch; ignored for
+ * dot-free refs (legacy behavior unchanged).
+ */
+export interface ReferrerScope {
+  readonly type: string;
+}
+
+/**
+ * FR-024: true when a ref's final `::`-segment contains a `.` — i.e. the ref
+ * targets a child nested inside an object (`Customer.id`,
+ * `acme::sales::Customer.id`). Names cannot contain `.`, so this is
+ * unambiguous. Call sites use this to apply the dotted-only
+ * type/subtype-mismatch check (ERR_EXTENDS_TARGET_MISMATCH) without altering
+ * shipped top-level extends behavior.
+ */
+export function isChildTargetingRef(ref: string): boolean {
+  const lastSep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  const lastSegment = lastSep === -1 ? ref : ref.slice(lastSep + PACKAGE_SEPARATOR.length);
+  return lastSegment.includes(CHILD_REF_SEPARATOR);
+}
+
+/**
+ * FR-024: split a child-targeting ref into the owner-object ref and the child
+ * traversal path. A multi-dot ref (`X.y.z`) traverses child names to any depth
+ * (object → field → view); returns undefined only for degenerate empty parts
+ * (`.id`, `Customer.`, `Customer..x`).
+ */
+function parseChildTargetingRef(
+  ref: string,
+): { ownerRef: string; path: readonly string[] } | undefined {
+  const lastSep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+  const lastSegment = ref.slice(segStart);
+  const parts = lastSegment.split(CHILD_REF_SEPARATOR);
+  if (parts.length < 2 || parts.some((p) => p === "")) return undefined;
+  return {
+    ownerRef: ref.slice(0, segStart) + parts[0],
+    path: parts.slice(1),
+  };
+}
+
 /**
  * Resolve a single super reference string against a tree.
  *
@@ -59,51 +112,72 @@ function findInTree(root: MetaData, fqn: string): MetaData | undefined {
  * against the loader's accumulating root (intoRoot). Java semantics: if the
  * ref cannot be resolved, the parser throws ParseError.
  *
- * @param ref - The raw super reference (e.g., "Fruit", "::pkg::Name", "..::common::id")
+ * FR-024 (ADR-0029): a ref whose final segment is dotted (`Customer.id`)
+ * targets a child nested inside an object. The owner part resolves with the
+ * existing strategies (absolute / relative / bare / same-package); the child
+ * is then selected among the owner's EFFECTIVE children (so inherited
+ * children resolve) by name AND the referrer's type (type-scoped). A dotted
+ * ref that does not resolve returns undefined WITHOUT falling through to the
+ * bare lookup; a dotted ref with no `referrerScope` is unresolvable.
+ *
+ * @param ref - The raw super reference (e.g., "Fruit", "::pkg::Name", "..::common::id", "Customer.id")
  * @param contextPackage - The package of the model whose super is being resolved
  * @param root - The root MetaData of the accumulating tree to search within
+ * @param referrerScope - FR-024: the extending node's type — required to resolve dotted refs
  * @returns The resolved MetaData, or undefined if the reference cannot be resolved
  */
 export function resolveSuperRef(
   ref: string,
   contextPackage: string,
   root: MetaData,
+  referrerScope?: ReferrerScope,
 ): MetaData | undefined {
   // -------------------------------------------------------------------------
-  // 1. Absolute reference: leading "::"
-  // -------------------------------------------------------------------------
-  if (ref.startsWith(PACKAGE_SEPARATOR)) {
-    const absolutePath = ref.slice(PACKAGE_SEPARATOR.length);
-    return findInTree(root, absolutePath);
-  }
-
-  // -------------------------------------------------------------------------
-  // 2. Relative reference: one or more leading "..::"
+  // 0. FR-024 dotted child-targeting ref: `<rootRef>.<child>...<child>`
+  //
+  // Addressing model (ADR-0029): the package qualifies the ROOT-level node
+  // only; each subsequent segment traverses CHILD NAMES, to any depth
+  // (object → field → view: `Customer.priceCents.display`). INTERMEDIATE
+  // segments select by unique name among the current node's effective
+  // children (a cross-type name collision, e.g. a field AND an identity both
+  // named "id", is ambiguous → unresolved); the FINAL segment is type-scoped
+  // to the referrer (a field ref resolves fields, a view ref views), which is
+  // also what disambiguates the common 2-segment `Customer.id` case.
   // -------------------------------------------------------------------------
-  if (ref.startsWith(PACKAGE_PARENT + PACKAGE_SEPARATOR)) {
-    const parts = ref.split(PACKAGE_SEPARATOR);
-    let levels = 0;
-    while (levels < parts.length && parts[levels] === PACKAGE_PARENT) {
-      levels++;
+  if (isChildTargetingRef(ref)) {
+    if (referrerScope === undefined) return undefined;
+    const parsed = parseChildTargetingRef(ref);
+    if (parsed === undefined) return undefined; // degenerate (empty segment)
+    let current: MetaData | undefined = resolveSuperRef(parsed.ownerRef, contextPackage, root);
+    if (current === undefined) return undefined;
+    for (let i = 0; i < parsed.path.length - 1; i++) {
+      const seg = parsed.path[i]!;
+      const matches: MetaData[] = current.children().filter((c) => c.name === seg);
+      if (matches.length !== 1) return undefined; // missing or ambiguous intermediate
+      current = matches[0]!;
     }
-
-    const pkgParts = contextPackage !== "" ? contextPackage.split(PACKAGE_SEPARATOR) : [];
-    const remainder = parts.slice(levels);
-    if (pkgParts.length < levels || remainder.length === 0) {
-      return undefined;
-    }
-
-    const allParts = [...pkgParts.slice(0, pkgParts.length - levels), ...remainder];
-    return findInTree(root, allParts.join(PACKAGE_SEPARATOR));
+    const last = parsed.path[parsed.path.length - 1]!;
+    return current
+      .children()
+      .find((c) => c.name === last && c.type === referrerScope.type);
   }
-
   // -------------------------------------------------------------------------
-  // 3. Bare name OR same-package shorthand (contains "::" but no leading
-  //    "::" or "..::"): try contextPackage prepend first, then root-rooted.
+  // 1. FR-032 (ADR-0032): refs in the loaded tree are already fully-qualified.
+  //    The YAML desugar expanded every relative/bare-current ref to FQN
+  //    (`expandRef`), and the canonical-JSON guard rejects any surviving
+  //    `::`/`..::` form (ERR_RELATIVE_REF_IN_CANONICAL). So resolution is a
+  //    pure FQN match — the old `::`-strip (absolute), `..::`-reduce (relative)
+  //    and bare-current-then-ROOT-FALLBACK branches are deleted (the footgun).
+  //
+  //    A qualified ref (`pkg::Name`) matches its node directly. A bare ref
+  //    (no `::`) is the rare in-tree case: a root-level/empty-package type, or
+  //    a bare ref constructed during dotted-owner recursion — resolve it in the
+  //    current package ONLY (try `<ctx>::ref`), then bare (root-level) as the
+  //    literal name. NO root fallback for a packaged bare ref.
   // -------------------------------------------------------------------------
-  if (contextPackage !== "") {
-    const found = findInTree(root, `${contextPackage}${PACKAGE_SEPARATOR}${ref}`);
-    if (found !== undefined) return found;
+  if (!ref.includes(PACKAGE_SEPARATOR) && contextPackage !== "") {
+    const inPackage = findInTree(root, `${contextPackage}${PACKAGE_SEPARATOR}${ref}`);
+    if (inPackage !== undefined) return inPackage;
   }
   return findInTree(root, ref);
 }
@@ -119,6 +193,19 @@ export interface DeferredSuperFailure {
   ref: string;
   /** ADR-0009 provenance envelope of the referencing node (FR5a). */
   source: import("./source.js").ErrorSource;
+  /**
+   * FR-024: why resolution failed.
+   * - "unresolved" — no target found (loader emits ERR_UNRESOLVED_SUPER).
+   * - "target-mismatch" — a dotted child-targeting ref resolved, but the
+   *   target's type/subtype differs from the extending node's (loader emits
+   *   ERR_EXTENDS_TARGET_MISMATCH). Applies ONLY to dotted refs — top-level
+   *   extends behavior is unchanged.
+   */
+  kind: "unresolved" | "target-mismatch";
+  /** target-mismatch only: the resolved target's identity, for the message. */
+  target?: { type: string; subType: string };
+  /** target-mismatch only: the extending node's type/subtype, for the message. */
+  referrer?: { type: string; subType: string };
 }
 
 /**
@@ -140,15 +227,38 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
     if (node.superRef === undefined) return;
     if (node.superResolved !== undefined) return;
     const effectivePkg = node.package ?? node.fileDefaultPackage ?? "";
-    const target = resolveSuperRef(node.superRef, effectivePkg, root);
+    // FR-024: thread the referrer's type so dotted `Entity.child` refs resolve
+    // type-scoped (a field ref selects fields; an identity ref identities).
+    const target = resolveSuperRef(node.superRef, effectivePkg, root, { type: node.type });
     if (target !== undefined) {
+      // FR-024: a dotted ref must target a node of the SAME type and subtype
+      // as the extending node. Dotted-only — top-level extends is unchanged.
+      if (
+        isChildTargetingRef(node.superRef) &&
+        (target.type !== node.type || target.subType !== node.subType)
+      ) {
+        failures.push({
+          nodeFqn: node.fqn(),
+          ref: node.superRef,
+          source: node.source,
+          kind: "target-mismatch",
+          target: { type: target.type, subType: target.subType },
+          referrer: { type: node.type, subType: node.subType },
+        });
+        return;
+      }
       try {
         node.setSuperResolved(target);
       } catch {
         // Frozen — ignore; the loader should resolve before freeze.
       }
     } else {
-      failures.push({ nodeFqn: node.fqn(), ref: node.superRef, source: node.source });
+      failures.push({
+        nodeFqn: node.fqn(),
+        ref: node.superRef,
+        source: node.source,
+        kind: "unresolved",
+      });
     }
   });
   return failures;

package/src/template/meta-template.ts

@@ -3,9 +3,10 @@ import { MetaData } from "../shared/meta-data.js";
 /**
  * `template.*` node — the fourth-pillar metatype (FR-004, R1).
  *
- * A single class backs both subtypes (`template.prompt`, `template.output`),
+ * A single class backs every subtype (`template.base/prompt/output/toolcall`),
  * mirroring `MetaSource`: the loader dispatches by subtype and per-subtype
- * attribute schemas (see `template-schema.ts`) drive validation. Typed accessors
+ * attribute schemas (FR-033: externalized to spec/metamodel/template.json,
+ * embedded at build into TEMPLATE_DEFINITION) drive validation. Typed accessors
  * are deferred to the render-engine / verify work — attr values read generically
  * via `ownAttr(...)` until then, so no untested forward-looking surface ships.
  */