@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

package/src/parser-json.ts

@@ -4,8 +4,9 @@
 // the canonical object to the shared buildTree (parser-core.ts).
 
 import { ParseError } from "./errors.js";
-import { buildTree, errOpts } from "./parser-core.js";
+import { buildTree } from "./parser-core.js";
 import type { ParseOptions, ParseResult } from "./parser-core.js";
+import type { ErrorSource } from "./source.js";
 
 export type { ParseOptions, ParseResult } from "./parser-core.js";
 
@@ -18,9 +19,17 @@ export function parseJson(content: string, opts: ParseOptions): ParseResult {
   try {
     parsed = JSON.parse(normalizedContent);
   } catch (err) {
+    // FR5a / ADR-0009 — pre-buildTree errors can't reach the parser's
+    // module-level JsonPathBuilder; build a minimal json-source envelope
+    // rooted at "$" so cross-port callers see a consistent shape.
+    const source: ErrorSource = {
+      format: "json",
+      files: [opts.sourceName ?? "<unknown>"],
+      jsonPath: "$",
+    };
     throw new ParseError(
       `Invalid JSON: ${(err as Error).message}`,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_JSON" },
+      { code: "ERR_MALFORMED_JSON", source },
     );
   }
 

package/src/persistence/source/validate-source-roles.ts

@@ -36,14 +36,14 @@ export function validateSourceRoles(root: MetaData): ParseError[] {
       errors.push(
         new ParseError(
           `object "${obj.name}" declares ${sources.length} source(s) but none has role "${SOURCE_ROLE_PRIMARY}"`,
-          { code: "ERR_SOURCE_NO_PRIMARY" },
+          { code: "ERR_SOURCE_NO_PRIMARY", source: obj.source },
         ),
       );
     } else if (primaryCount > 1) {
       errors.push(
         new ParseError(
           `object "${obj.name}" declares ${primaryCount} sources with role "${SOURCE_ROLE_PRIMARY}"; exactly one is required`,
-          { code: "ERR_SOURCE_MULTIPLE_PRIMARY" },
+          { code: "ERR_SOURCE_MULTIPLE_PRIMARY", source: obj.source },
         ),
       );
     }

package/src/semantic-diff.ts

@@ -0,0 +1,48 @@
+// server/typescript/packages/metadata/src/semantic-diff.ts
+//
+// FR5a / ADR-0009 — Cross-port-aligned semantic-equality compare for metadata
+// trees. Returns `true` if the two inputs differ in any semantically-meaningful
+// way (excluding `source`, which is loader output).
+//
+// Algorithm (ADR-0009 §semantic_diff):
+//   1. Sort attrs lexicographically; compare attr-by-attr; values by canonical
+//      structural equality (key-order independent, whitespace-insensitive).
+//   2. Children are compared as ordered sequences.
+//   3. Reserved structural keys (name, package, extends, abstract, overlay,
+//      isArray, value) participate like attrs.
+//   4. `source` excluded from the diff.
+
+type Tree = Record<string, unknown>;
+
+const EXCLUDED = new Set(["source"]);
+
+function isObject(v: unknown): v is Tree {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function equal(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!equal(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (isObject(a) && isObject(b)) {
+    const aKeys = Object.keys(a).filter((k) => !EXCLUDED.has(k)).sort();
+    const bKeys = Object.keys(b).filter((k) => !EXCLUDED.has(k)).sort();
+    if (aKeys.length !== bKeys.length) return false;
+    for (let i = 0; i < aKeys.length; i++) {
+      if (aKeys[i] !== bKeys[i]) return false;
+      if (!equal(a[aKeys[i]!], b[bKeys[i]!])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Returns `true` if the inputs differ in any semantically-meaningful way. */
+export function semanticDiff(a: Tree, b: Tree): boolean {
+  return !equal(a, b);
+}

package/src/shared/meta-data.ts

@@ -5,6 +5,7 @@ import type { DataType } from "../data-type.js";
 import type { MetaAttr } from "../core/attr/meta-attr.js";
 import { inferAttrSubType } from "../serializer-json.js";
 import { attrClassFor } from "../attr-class-map.js";
+import type { ErrorSource } from "../source.js";
 
 export type AttrValue = string | number | boolean | string[] | AttrObject;
 
@@ -57,6 +58,14 @@ export abstract class MetaData {
   // construction (for field/attr nodes). Read via MetaField/MetaAttr.dataType.
   protected _dataType?: DataType;
 
+  // ADR-0009 provenance. Always populated; defaults to `{ format: "code" }`
+  // for programmatic construction (tests, factories, in-code builders). The
+  // JSON parser overwrites via setSource() during tree walk; future phases
+  // (overlay merge, super resolution) may overwrite with merged/resolved
+  // variants. Excluded from canonical JSON serialization — loader-derived
+  // state, not metadata.
+  private _source: ErrorSource = { format: "code" };
+
   // Per-instance read cache: only populated once the node is frozen.
   private readonly _cache = new Map<string, unknown>();
 
@@ -171,6 +180,25 @@ export abstract class MetaData {
     this._dataType = dt;
   }
 
+  // ---------------------------------------------------------------------------
+  // source (ADR-0009 provenance)
+  // ---------------------------------------------------------------------------
+
+  /** Provenance envelope for this node. Always populated. See ADR-0009. */
+  get source(): ErrorSource {
+    return this._source;
+  }
+
+  /**
+   * Loader-internal: assign provenance. Called by parser and merge phases as
+   * they build the tree. Honors the frozen-guard like other setters.
+   * @internal
+   */
+  setSource(s: ErrorSource): void {
+    this._assertNotFrozen();
+    this._source = s;
+  }
+
   // ---------------------------------------------------------------------------
   // isAbstract
   // ---------------------------------------------------------------------------

package/src/source.ts

@@ -0,0 +1,99 @@
+// server/typescript/packages/metadata/src/source.ts
+//
+// FR5a — Loader error envelope + source-on-node (ADR-0009).
+//
+// Cross-port-aligned types: every metaobjects port emits the same envelope
+// shape so a tool consuming errors from multiple language ports can compare
+// them byte-identically.
+
+/** Discriminated union over the provenance variants a metadata node or error
+ *  can carry. See ADR-0009 §Decision for the canonical shape.
+ *
+ *  FR5b note (finalized 2026-05-27, all four ports): buildTree-emitted errors
+ *  from a YAML input emit `format: "yaml"` and carry the optional
+ *  `yamlPosition` (line/col from the desugar's position map). The
+ *  `yamlPosition` field is also declared optionally on the `format: "json"`
+ *  variant for backward shape-compat with any FR5b-interim envelopes still
+ *  serialized to disk; new YAML errors no longer use that variant. */
+export type ErrorSource =
+  | { format: "json"; files: [string]; jsonPath: string;
+      yamlPosition?: { line: number; col: number } }
+  | { format: "yaml"; files: [string]; jsonPath: string;
+      yamlPosition?: { line: number; col: number } }
+  | { format: "merged"; files: string[]; jsonPath: string;
+      contributors: Contributor[] }
+  | { format: "resolved"; files: string[]; jsonPath?: string;
+      referrer?: string; target?: string }
+  | { format: "database"; dbLocation: { table: string; id: string };
+      jsonPath?: string }
+  | { format: "code"; caller?: string };
+
+export interface Contributor {
+  file: string;
+  role: "overlay-base" | "overlay-extension" | "extends-base" | "extends-extension";
+}
+
+export interface NodeContext {
+  type?: string;
+  subtype?: string;
+  name?: string;
+  fqn?: string;
+}
+
+/** Envelope shape every loader error conforms to. */
+export interface LoaderError {
+  // REQUIRED — conformance-enforced.
+  code: string;
+  message: string;
+  source: ErrorSource;
+  // RECOMMENDED — optional per ADR-0009 §What ports are NOT required to do.
+  suggestions?: string[];
+  fixture?: string;
+  node?: NodeContext;
+}
+
+/** Warning envelope — same shape as LoaderError but a `WARN_*` code. */
+export interface LoaderWarning {
+  code: string;
+  message: string;
+  source: ErrorSource;
+  suggestions?: string[];
+  fixture?: string;
+  node?: NodeContext;
+}
+
+/** Canonical synthetic envelope for programmatic / test-constructed nodes.
+ *  `caller` is an optional human label (e.g. "QueriesTest.makePost"). */
+export function codeSource(caller?: string): ErrorSource {
+  return caller ? { format: "code", caller } : { format: "code" };
+}
+
+/** FR5d — build a `format: "resolved"` envelope from a referrer node's source
+ *  envelope (typically a `format: "json"` or `format: "yaml"` parse-time
+ *  source) plus the referrer FQN and unresolved target string.
+ *
+ *  The resolved envelope carries:
+ *    - `files`: the referrer's source files (so editors can jump to it),
+ *    - `jsonPath`: the referrer's jsonPath when known (the location of the
+ *       broken reference on disk),
+ *    - `referrer`: the FQN of the metadata node that declared the broken
+ *       reference (e.g. "myapp::content::Video"),
+ *    - `target`:  the unresolved reference string itself (e.g. "BaseEntity",
+ *       "Program.weeks.invalid", "DoesNotExist").
+ *
+ *  `referrerSource` may be any FR5a variant — we read its files/jsonPath
+ *  best-effort and fall back to an empty `files: []` when the referrer's
+ *  source is itself a `code`/`database` envelope. */
+export function resolvedSource(
+  referrerSource: ErrorSource,
+  referrer: string,
+  target: string,
+): ErrorSource {
+  const files = "files" in referrerSource ? [...referrerSource.files] : [];
+  const jsonPath = "jsonPath" in referrerSource ? referrerSource.jsonPath : undefined;
+  const out: ErrorSource = { format: "resolved", files, referrer, target };
+  if (jsonPath !== undefined) {
+    (out as { jsonPath?: string }).jsonPath = jsonPath;
+  }
+  return out;
+}

package/src/subtype-rules.ts

@@ -35,7 +35,7 @@ function walk(model: MetaData, errors: ParseError[], warnings: string[]): void {
         new ParseError(
           `value object '${model.fqn()}' must not have a primary identity ` +
             `(use subType: "entity" for records with identity)`,
-          { code: "ERR_SUBTYPE_RULE_VIOLATION" },
+          { code: "ERR_SUBTYPE_RULE_VIOLATION", source: model.source },
         ),
       );
     } else if (

package/src/super-resolve.ts

@@ -100,6 +100,8 @@ export interface DeferredSuperFailure {
   nodeFqn: string;
   /** The raw super ref string that didn't resolve. */
   ref: string;
+  /** ADR-0009 provenance envelope of the referencing node (FR5a). */
+  source: import("./source.js").ErrorSource;
 }
 
 /**
@@ -128,7 +130,7 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
         // Frozen — ignore; the loader should resolve before freeze.
       }
     } else {
-      failures.push({ nodeFqn: node.fqn(), ref: node.superRef });
+      failures.push({ nodeFqn: node.fqn(), ref: node.superRef, source: node.source });
     }
   });
   return failures;

package/src/template/template-constants.ts

@@ -1,10 +1,14 @@
-// template.* subtype vocabulary + reserved attribute names (FR-004, R1).
+// template.* subtype vocabulary + reserved attribute names (FR-004, R1; ADR-0011).
 //
-// `template` is the fourth-pillar base type: a renderable text artifact bound to
-// a typed payload. Two subtypes (by audience/structure, NOT by format):
-//   - prompt: LLM-targeted; carries the prompt-overlay attrs and is the home for
-//     future structured-prompt (role/turn/tool) divergence.
+// `template` is the fourth-pillar base type — a typed payload bound to either
+// a rendered text artifact (prompt/output) or to a tool-call envelope.
+// Three subtypes:
+//   - prompt: LLM-targeted renderable text. Carries the prompt-overlay attrs.
+//             Renderable body required via @textRef.
 //   - output: every other rendered artifact (email, export, docs, config).
+//             Renderable body required via @textRef.
+//   - toolcall: LLM tool-call envelope (no renderable body — the body IS the
+//               structured output schema resolved via @payloadRef). Per ADR-0011.
 //
 // Format is the @format ATTRIBUTE (closed set below), never a subtype — the
 // render engine keys its escaper off @format, so a new format costs one escaper
@@ -14,15 +18,18 @@ import { SUBTYPE_BASE } from "../shared/base-types.js";
 
 export const TEMPLATE_SUBTYPE_PROMPT = "prompt";
 export const TEMPLATE_SUBTYPE_OUTPUT = "output";
+export const TEMPLATE_SUBTYPE_TOOLCALL = "toolcall";
 
 export const TEMPLATE_SUBTYPES = [
   SUBTYPE_BASE,
   TEMPLATE_SUBTYPE_PROMPT,
   TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_TOOLCALL,
 ] as const;
 export type TemplateSubType = (typeof TEMPLATE_SUBTYPES)[number];
 
-// Generic reserved attrs (both subtypes). The "@" is applied at wire time.
+// Generic reserved attrs (prompt + output). The "@" is applied at wire time.
+// NOT inherited by toolcall — toolcall has no renderable body.
 export const TEMPLATE_ATTR_PAYLOAD_REF = "payloadRef";
 export const TEMPLATE_ATTR_TEXT_REF = "textRef";
 export const TEMPLATE_ATTR_FORMAT = "format";
@@ -39,6 +46,16 @@ export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
 export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
 export const TEMPLATE_ATTR_MODEL = "model";
 
+// Toolcall-specific attrs (template.toolcall only). Vendor-agnostic; vendor
+// wire details (retry semantics, fallback shapes, etc.) are added by consumer
+// providers via registry.extend per ADR-0011.
+//
+// @description is intentionally NOT a toolcall-specific constant — every type
+// gets @description via the documentation common-attrs provider. Tool
+// descriptions surfaced to the LLM use the same @description common attr
+// doc-gen uses.
+export const TEMPLATE_ATTR_TOOL_NAME = "toolName";
+
 // Closed format set — escaping/whitespace behavior is keyed off this in the
 // render engine's escaper registry (FR-004 R7).
 export const TEMPLATE_FORMATS = [

package/src/template/template-schema.ts

@@ -16,6 +16,7 @@ import { SUBTYPE_BASE } from "../shared/base-types.js";
 import {
   TEMPLATE_SUBTYPE_PROMPT,
   TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_SUBTYPE_TOOLCALL,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_FORMAT,
@@ -26,6 +27,7 @@ import {
   TEMPLATE_ATTR_MAX_TOKENS,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
   TEMPLATE_ATTR_MODEL,
+  TEMPLATE_ATTR_TOOL_NAME,
   TEMPLATE_FORMATS,
 } from "./template-constants.js";
 
@@ -99,8 +101,49 @@ const promptOverlayAttrs: AttrSchema[] = [
   },
 ];
 
+// Toolcall attrs (template.toolcall only — does NOT inherit genericAttrs).
+// Per ADR-0011: vendor-agnostic in core; vendor wire details (retry semantics,
+// fallback shapes, parallel invocation, cache hints) added by consumer
+// providers via registry.extend(TYPE_TEMPLATE, "toolcall", { attributes: [...] }).
+//
+// Critical: @textRef is intentionally NOT required here. A tool-call has no
+// renderable text body — the body IS the structured output schema resolved
+// via @payloadRef. This is the design rationale for toolcall being its own
+// subtype rather than template.output + @toolName.
+//
+// @description is intentionally NOT declared here — it's already a documentation
+// common attr added to every type by docProvider. Tool descriptions surfaced to
+// the LLM read the same @description common attr that doc-gen uses.
+const toolcallAttrs: AttrSchema[] = [
+  {
+    name: TEMPLATE_ATTR_TOOL_NAME,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "Wire tool name surfaced to the LLM (vendor-specific format).",
+  },
+  {
+    name: TEMPLATE_ATTR_PAYLOAD_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "Output value-object the tool produces (resolved against the metamodel).",
+  },
+  {
+    name: TEMPLATE_ATTR_OWNER,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the owner of this toolcall.",
+  },
+  {
+    name: TEMPLATE_ATTR_SINCE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the version this toolcall was introduced in.",
+  },
+];
+
 export const TEMPLATE_ATTRS_MAP = new Map<string, AttrSchema[]>([
   [SUBTYPE_BASE, []],
   [TEMPLATE_SUBTYPE_PROMPT, [...genericAttrs, ...promptOverlayAttrs]],
   [TEMPLATE_SUBTYPE_OUTPUT, [...genericAttrs]],
+  [TEMPLATE_SUBTYPE_TOOLCALL, [...toolcallAttrs]],
 ]);

package/src/core/file-meta-data-loader.ts

@@ -1,89 +0,0 @@
-// FileMetaDataLoader — discovers file-backed MetaDataSources and runs the
-// MetaDataLoader pipeline over them. A UrlMetaDataLoader will slot in the
-// same way later.
-
-import type { Stats } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
-import { join } from "node:path";
-import { MetaDataLoader, type LoadResult } from "../loader/meta-data-loader.js";
-import { FileSource } from "./file-source.js";
-import { parseYaml } from "./parser-yaml.js";
-import type { ParseOptions, ParseResult } from "../parser-core.js";
-import type { MetaDataSource } from "../loader/meta-data-source.js";
-
-/** Minimal glob matcher supporting `*` (any chars except `/`) and `**` (any chars). */
-function matchSimpleGlob(pattern: string, value: string): boolean {
-  const regexStr = pattern
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replace(/\*\*/g, "::DOUBLESTAR::")
-    .replace(/\*/g, "[^/]*")
-    .replace(/::DOUBLESTAR::/g, ".*");
-  return new RegExp(`^${regexStr}$`).test(value);
-}
-
-export class FileMetaDataLoader extends MetaDataLoader {
-  /** Adds YAML parsing on top of the base loader's JSON-only `parseSource`. */
-  protected override parseSource(
-    content: string,
-    source: MetaDataSource,
-    parseOpts: ParseOptions,
-  ): ParseResult {
-    if (source.format === "yaml") {
-      return parseYaml(content, parseOpts);
-    }
-    return super.parseSource(content, source, parseOpts);
-  }
-
-  /**
-   * Load every `.json` / `.yaml` / `.yml` file in a directory (non-recursive),
-   * in deterministic ordinal filename order.
-   * @param opts.exclude glob patterns (relative to dir) to skip — `*` / `**`.
-   */
-  async loadDirectory(dir: string, opts?: { exclude?: string[] }): Promise<LoadResult> {
-    let entries: string[];
-    try {
-      // Sorted for deterministic multi-file load order: the overlay merge is
-      // order-sensitive (last-writer-wins on attr conflicts), so the scan must
-      // not depend on filesystem readdir order. Ordinal filename sort is
-      // reproducible across the Java/Python/C# ports.
-      entries = (await readdir(dir)).sort();
-    } catch (err) {
-      // Surface the I/O failure as a collected error via the empty-source path.
-      const emptyResult = await this.load([]);
-      return {
-        ...emptyResult,
-        errors: [
-          new Error(`loadDirectory: cannot read ${dir}: ${(err as Error).message}`),
-          ...emptyResult.errors,
-        ],
-      };
-    }
-
-    const excludes = opts?.exclude ?? [];
-    const paths: string[] = [];
-    for (const entry of entries) {
-      const lower = entry.toLowerCase();
-      if (!lower.endsWith(".json") && !lower.endsWith(".yaml") && !lower.endsWith(".yml")) {
-        continue;
-      }
-      const filePath = join(dir, entry);
-      let statResult: Stats;
-      try {
-        statResult = await stat(filePath);
-      } catch {
-        // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
-        // Skip it rather than breaking the no-throw contract of loadDirectory.
-        continue;
-      }
-      if (!statResult.isFile()) continue;
-      if (excludes.some((p) => matchSimpleGlob(p, entry))) continue;
-      paths.push(filePath);
-    }
-    return this.loadFiles(paths);
-  }
-
-  /** Load an explicit list of file paths, in order. */
-  async loadFiles(paths: string[]): Promise<LoadResult> {
-    return this.load(paths.map((p) => new FileSource(p)));
-  }
-}