@metaobjectsdev/metadata 0.5.0-rc.3 → 0.6.0-rc.1

package/src/persistence/source/meta-source.ts

@@ -1,38 +1,51 @@
 // MetaSource — concrete node class for type=source nodes.
 // Declares where an object's data lives (Project E).
-// dbTable / dbView source subtypes declare the SQL table or view name.
+// source.rdb uses @table/@kind/@role/@schema; read-only is derived from @kind.
 //
 // Extends MetaData directly: no model wrapper, no metaOf() indirection.
 
 import { MetaData } from "../../shared/meta-data.js";
 import {
-  SOURCE_ATTR_NAME,
-  SOURCE_SUBTYPE_DB_TABLE,
-  SOURCE_SUBTYPE_DB_VIEW,
+  SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_KIND,
+  SOURCE_ATTR_ROLE,
+  SOURCE_READ_ONLY_KINDS,
+  DEFAULT_SOURCE_KIND,
+  DEFAULT_SOURCE_ROLE,
 } from "./source-constants.js";
 
 export class MetaSource extends MetaData {
-  /** The SQL table or view name (value of @name attr on the source child). */
-  get sourceName(): string | undefined {
-    const v = this.ownAttr(SOURCE_ATTR_NAME);
-    return typeof v === "string" ? v : undefined;
+  /** Physical SQL table/view name from @table (source.rdb). */
+  get tableName(): string | undefined {
+    const v = this.ownAttr(SOURCE_ATTR_TABLE);
+    return typeof v === "string" && v !== "" ? v : undefined;
   }
 
   /**
-   * True when this source is a `dbTable` (writable).
-   * Explicitly defined rather than derived from `isReadOnly()` so it remains
-   * correct if a third source subtype is added in the future.
+   * The effective kind for this source: the value of `@kind`, defaulting to
+   * `"table"` when omitted (ADR-0007 Rule 3 — per-paradigm default).
    */
-  isWritable(): boolean {
-    return this.subType === SOURCE_SUBTYPE_DB_TABLE;
+  get effectiveKind(): string {
+    const v = this.ownAttr(SOURCE_ATTR_KIND);
+    return typeof v === "string" && v !== "" ? v : DEFAULT_SOURCE_KIND;
+  }
+
+  /** The multi-source role for this source (defaults to "primary" when omitted). */
+  get role(): string {
+    const v = this.ownAttr(SOURCE_ATTR_ROLE);
+    return typeof v === "string" && v !== "" ? v : DEFAULT_SOURCE_ROLE;
   }
 
   /**
-   * True when this source is a `dbView` (read-only projection).
-   * Explicitly defined rather than derived from `isWritable()` so it remains
-   * correct if a third source subtype is added in the future.
+   * True when this source's effective kind is read-only (view, materializedView,
+   * storedProc, tableFunction). Derived from the @kind attr on source.rdb.
    */
   isReadOnly(): boolean {
-    return this.subType === SOURCE_SUBTYPE_DB_VIEW;
+    return SOURCE_READ_ONLY_KINDS.has(this.effectiveKind);
+  }
+
+  /** True when this source is writable (i.e. not read-only). */
+  isWritable(): boolean {
+    return !this.isReadOnly();
   }
 }

package/src/persistence/source/source-constants.ts

@@ -4,32 +4,81 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 // ---------------------------------------------------------------------------
 // Source type — declares where an object's data lives (Project E).
-// dbTable / dbView ship in v1. Multiple sources per object are allowed
-// and meaningful (write-through CQRS: dbTable for writes + dbView for reads).
+// source.rdb (ADR-0007): paradigm subtype + @table/@kind/@role/@schema attrs.
+// Multiple sources per object are allowed and meaningful (write-through CQRS:
+// writable rdb[table] for writes + read-only rdb[view] for reads).
 // ---------------------------------------------------------------------------
 
-export const SOURCE_SUBTYPE_DB_TABLE = "dbTable";
-export const SOURCE_SUBTYPE_DB_VIEW  = "dbView";
+// --- Source v2 (ADR-0007): paradigm subtype "rdb"; physical name @table; @kind + @role. ---
+export const SOURCE_SUBTYPE_RDB = "rdb";
 
 export const SOURCE_SUBTYPES = [
   SUBTYPE_BASE,
-  SOURCE_SUBTYPE_DB_TABLE,
-  SOURCE_SUBTYPE_DB_VIEW,
+  SOURCE_SUBTYPE_RDB,
 ] as const;
 export type SourceSubType = (typeof SOURCE_SUBTYPES)[number];
 
-// Source attrs — both dbTable and dbView use @name for the SQL identifier
-// (table name and view name respectively). Same key for ergonomic consistency.
-export const SOURCE_DB_TABLE_ATTR_NAME = "name";
-export const SOURCE_DB_VIEW_ATTR_NAME  = "name";
-/** Shared @name attr key for MetaSource (covers both dbTable and dbView). Use this
- *  in generic source accessors instead of the subtype-specific aliases above. */
-export const SOURCE_ATTR_NAME          = "name";
-
-/** Optional DB schema attr on source[dbTable] / source[dbView]. Postgres uses
- *  this to namespace tables/views. SQLite has no schema concept and rejects
- *  any non-default value. Default for Postgres: "public". */
+/** Optional DB schema attr on source.rdb. Postgres uses this to namespace
+ *  tables/views. SQLite has no schema concept and rejects any non-default
+ *  value. Default for Postgres: "public". */
 export const SOURCE_ATTR_SCHEMA = "schema";
 
 /** Default Postgres schema when @schema is omitted from a source. */
 export const DEFAULT_DB_SCHEMA_POSTGRES = "public";
+
+// ---------------------------------------------------------------------------
+// Source v2 (ADR-0007) — rdb paradigm: kind, role, physical table name.
+// ---------------------------------------------------------------------------
+
+/** Physical table/view name on source.rdb. */
+export const SOURCE_ATTR_TABLE = "table";
+/** Object kind within the rdb paradigm; read-only-ness is derived from it. */
+export const SOURCE_ATTR_KIND = "kind";
+/** Multi-source role; exactly one primary per object. */
+export const SOURCE_ATTR_ROLE = "role";
+
+export const SOURCE_KIND_TABLE              = "table";
+export const SOURCE_KIND_VIEW               = "view";
+export const SOURCE_KIND_MATERIALIZED_VIEW  = "materializedView";
+export const SOURCE_KIND_STORED_PROC        = "storedProc";
+export const SOURCE_KIND_TABLE_FUNCTION     = "tableFunction";
+
+export const SOURCE_RDB_KINDS = [
+  SOURCE_KIND_TABLE,
+  SOURCE_KIND_VIEW,
+  SOURCE_KIND_MATERIALIZED_VIEW,
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+] as const;
+export type SourceRdbKind = (typeof SOURCE_RDB_KINDS)[number];
+
+/** rdb @kind default when omitted (writable table). */
+export const DEFAULT_SOURCE_KIND = SOURCE_KIND_TABLE;
+
+/** Kinds whose source is read-only (codegen emits read-only model/queries/routes). */
+export const SOURCE_READ_ONLY_KINDS: ReadonlySet<string> = new Set([
+  SOURCE_KIND_VIEW,
+  SOURCE_KIND_MATERIALIZED_VIEW,
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+]);
+
+export const SOURCE_ROLE_PRIMARY = "primary";
+export const SOURCE_ROLE_REPLICA = "replica";
+export const SOURCE_ROLE_INDEX   = "index";
+export const SOURCE_ROLE_CACHE   = "cache";
+export const SOURCE_ROLE_PUBLISH = "publish";
+export const SOURCE_ROLE_MIRROR  = "mirror";
+
+export const SOURCE_ROLES = [
+  SOURCE_ROLE_PRIMARY,
+  SOURCE_ROLE_REPLICA,
+  SOURCE_ROLE_INDEX,
+  SOURCE_ROLE_CACHE,
+  SOURCE_ROLE_PUBLISH,
+  SOURCE_ROLE_MIRROR,
+] as const;
+export type SourceRole = (typeof SOURCE_ROLES)[number];
+
+/** Role when @role is omitted (system of record). */
+export const DEFAULT_SOURCE_ROLE = SOURCE_ROLE_PRIMARY;

package/src/persistence/source/source-schema.ts

@@ -0,0 +1,54 @@
+// Source v2 attribute schemas — registered by dbProvider for source.rdb.
+// Consumed via sourceRdbAttrs in db-provider.ts.
+
+import type { AttrSchema } from "../../registry.js";
+import { ATTR_SUBTYPE_STRING } from "../../core/attr/attr-constants.js";
+import {
+  SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_KIND,
+  SOURCE_ATTR_ROLE,
+  SOURCE_ATTR_SCHEMA,
+  SOURCE_RDB_KINDS,
+  SOURCE_ROLES,
+} from "./source-constants.js";
+
+/** `@table` — physical SQL table or view name for source.rdb. */
+const tableSchema: AttrSchema = {
+  name: SOURCE_ATTR_TABLE,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Physical SQL table or view name for this rdb source. Defaults to the object name run through the project's columnNamingStrategy when omitted.",
+};
+
+/** `@kind` — object kind within the rdb paradigm; drives read-only derivation. */
+const kindSchema: AttrSchema = {
+  name: SOURCE_ATTR_KIND,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  allowedValues: [...SOURCE_RDB_KINDS],
+  description:
+    "The kind of database object this source represents: table (default, writable), view, materializedView, storedProc, or tableFunction. Non-table kinds are read-only.",
+};
+
+/** `@role` — multi-source role; exactly one primary per object. */
+const roleSchema: AttrSchema = {
+  name: SOURCE_ATTR_ROLE,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  allowedValues: [...SOURCE_ROLES],
+  description:
+    "Role this source plays when an object has multiple sources: primary (default, system of record), replica, index, cache, publish, or mirror.",
+};
+
+/** `@schema` — optional DB schema namespace for this source. */
+const schemaSchema: AttrSchema = {
+  name: SOURCE_ATTR_SCHEMA,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Optional database schema name (e.g. 'catalog', 'public'). Postgres defaults to 'public'; SQLite rejects any non-default value.",
+};
+
+/** All attr schemas for source.rdb, to be registered via registry.extend. */
+export const sourceRdbAttrs: AttrSchema[] = [tableSchema, kindSchema, roleSchema, schemaSchema];

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

@@ -0,0 +1,53 @@
+// Validation pass: one-primary multi-source rule.
+//
+// An object that declares ≥1 source MUST have exactly one with role "primary".
+// Zero sources is allowed (object is not persisted). Violations:
+//   ERR_SOURCE_NO_PRIMARY      — sources present but none is role "primary"
+//   ERR_SOURCE_MULTIPLE_PRIMARY — more than one source has role "primary"
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import { TYPE_OBJECT, TYPE_SOURCE } from "../../shared/base-types.js";
+import { MetaSource } from "./meta-source.js";
+import { SOURCE_ROLE_PRIMARY } from "./source-constants.js";
+
+/**
+ * Walks every object in the root and enforces the one-primary rule for
+ * multi-source objects:
+ *  - 0 sources → no error (object is not backed by any store).
+ *  - 1+ sources, exactly 1 with role "primary" → OK.
+ *  - 1+ sources, 0 with role "primary" → ERR_SOURCE_NO_PRIMARY.
+ *  - 1+ sources, 2+ with role "primary" → ERR_SOURCE_MULTIPLE_PRIMARY.
+ */
+export function validateSourceRoles(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    const sources = obj
+      .ownChildren()
+      .filter((c) => c.type === TYPE_SOURCE)
+      .map((c) => c as MetaSource);
+
+    if (sources.length === 0) continue;
+
+    const primaryCount = sources.filter((s) => s.role === SOURCE_ROLE_PRIMARY).length;
+
+    if (primaryCount === 0) {
+      errors.push(
+        new ParseError(
+          `object "${obj.name}" declares ${sources.length} source(s) but none has role "${SOURCE_ROLE_PRIMARY}"`,
+          { code: "ERR_SOURCE_NO_PRIMARY" },
+        ),
+      );
+    } 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" },
+        ),
+      );
+    }
+  }
+
+  return errors;
+}

package/src/registry.ts

@@ -76,6 +76,9 @@ export class TypeRegistry {
   /** Per-type designated default subType (queried by the YAML desugar). */
   private readonly _defaultSubTypes = new Map<string, string>();
 
+  /** Attrs accepted on every metatype (declared by providers). */
+  private readonly _commonAttrs: AttrSchema[] = [];
+
   register(def: TypeDefinition): void {
     const key = def.typeId.toString();
     if (this._defs.has(key)) {
@@ -140,6 +143,34 @@ export class TypeRegistry {
     return [...(this.find(type, subType)?.attributes ?? [])];
   }
 
+  /**
+   * Register attrs that are accepted on every metatype. Callers (providers) use
+   * this to declare cross-cutting attrs (e.g. doc attrs). Repeated registration
+   * of the same name is silently deduped (first registration wins); conflicts with
+   * per-type attrs are resolved at validation time (Task 1.3).
+   */
+  registerCommonAttrs(attrs: AttrSchema[]): void {
+    for (const attr of attrs) {
+      if (attr.valueType === SUBTYPE_BASE) {
+        throw new Error(
+          `TypeRegistry.registerCommonAttrs: attr "${attr.name}" declares valueType "${SUBTYPE_BASE}", ` +
+          `which is not valid for attrs. Use no valueType (omit the field) for a polymorphic/untyped attr.`,
+        );
+      }
+      if (this._commonAttrs.some((existing) => existing.name === attr.name)) {
+        continue; // dedupe same-name re-registration; conflict-with-per-type-attr is checked at validation time
+      }
+      this._commonAttrs.push(attr);
+    }
+  }
+
+  /** Returns the registered common attrs (attrs accepted on every metatype).
+   *  Returns a defensive copy so callers cannot mutate internal state, matching
+   *  the spread-copy pattern used by `attrsOf` and `allSubTypesOf`. */
+  getCommonAttrs(): readonly AttrSchema[] {
+    return [...this._commonAttrs];
+  }
+
   /**
    * Additively enrich an already-registered (type, subType): append attributes
    * and/or child rules. Does NOT touch factory / typeId / dataType / default

package/src/shared/base-types.ts

@@ -1,7 +1,8 @@
-// Base type vocabulary — the 11 registered base types + universal/metadata subtypes.
+// Base type vocabulary — the 12 registered base types + universal/metadata subtypes.
 
 // ---------------------------------------------------------------------------
-// Base type names (the 11 registered base types — Java metaobjects-core vocabulary)
+// Base type names (the registered base types — Java metaobjects-core vocabulary,
+// plus `template`, the TS-first FR-004 addition for prompt construction)
 // ---------------------------------------------------------------------------
 
 export const TYPE_METADATA = "metadata";
@@ -15,6 +16,7 @@ export const TYPE_RELATIONSHIP = "relationship";
 export const TYPE_LAYOUT = "layout";
 export const TYPE_SOURCE = "source";
 export const TYPE_ORIGIN = "origin";
+export const TYPE_TEMPLATE = "template";
 
 export const BASE_TYPES = [
   TYPE_METADATA,
@@ -28,6 +30,7 @@ export const BASE_TYPES = [
   TYPE_LAYOUT,
   TYPE_SOURCE,
   TYPE_ORIGIN,
+  TYPE_TEMPLATE,
 ] as const;
 export type BaseType = (typeof BASE_TYPES)[number];
 

package/src/template/meta-template.ts

@@ -0,0 +1,12 @@
+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`),
+ * mirroring `MetaSource`: the loader dispatches by subtype and per-subtype
+ * attribute schemas (see `template-schema.ts`) 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.
+ */
+export class MetaTemplate extends MetaData {}

package/src/template/template-constants.ts

@@ -0,0 +1,53 @@
+// template.* subtype vocabulary + reserved attribute names (FR-004, R1).
+//
+// `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.
+//   - output: every other rendered artifact (email, export, docs, config).
+//
+// 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
+// + one enum value, not a new subtype + cross-language port.
+
+import { SUBTYPE_BASE } from "../shared/base-types.js";
+
+export const TEMPLATE_SUBTYPE_PROMPT = "prompt";
+export const TEMPLATE_SUBTYPE_OUTPUT = "output";
+
+export const TEMPLATE_SUBTYPES = [
+  SUBTYPE_BASE,
+  TEMPLATE_SUBTYPE_PROMPT,
+  TEMPLATE_SUBTYPE_OUTPUT,
+] as const;
+export type TemplateSubType = (typeof TEMPLATE_SUBTYPES)[number];
+
+// Generic reserved attrs (both subtypes). The "@" is applied at wire time.
+export const TEMPLATE_ATTR_PAYLOAD_REF = "payloadRef";
+export const TEMPLATE_ATTR_TEXT_REF = "textRef";
+export const TEMPLATE_ATTR_FORMAT = "format";
+export const TEMPLATE_ATTR_MAX_CHARS = "maxChars";
+export const TEMPLATE_ATTR_OWNER = "owner";
+export const TEMPLATE_ATTR_SINCE = "since";
+// Output tags the rendered text must contain (drives the verify output-tag check).
+// Generic — not prompt-only: any rendered artifact (email, export, prompt) can
+// carry a tag contract a downstream parser depends on.
+export const TEMPLATE_ATTR_REQUIRED_TAGS = "requiredTags";
+
+// Prompt-overlay attrs (template.prompt only).
+export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
+export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
+export const TEMPLATE_ATTR_MODEL = "model";
+
+// Closed format set — escaping/whitespace behavior is keyed off this in the
+// render engine's escaper registry (FR-004 R7).
+export const TEMPLATE_FORMATS = [
+  "text",
+  "html",
+  "xml",
+  "csv",
+  "json",
+  "markdown",
+  "spreadsheet",
+] as const;
+export type TemplateFormat = (typeof TEMPLATE_FORMATS)[number];

package/src/template/template-schema.ts

@@ -0,0 +1,106 @@
+// Reserved-attribute schemas per template subtype (FR-004, R1).
+//
+// Both subtypes share the generic attrs; @format is a closed enum (allowedValues)
+// that the render engine keys its escaper off. template.prompt additionally
+// carries the LLM-overlay attrs. References (@payloadRef, @textRef) are plain
+// strings here — resolution against a real payload / text source is render-time
+// `verify` scope (Plan #3), not load-time validation.
+
+import type { AttrSchema } from "../registry.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "../core/attr/attr-constants.js";
+import { SUBTYPE_BASE } from "../shared/base-types.js";
+import {
+  TEMPLATE_SUBTYPE_PROMPT,
+  TEMPLATE_SUBTYPE_OUTPUT,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_TEXT_REF,
+  TEMPLATE_ATTR_FORMAT,
+  TEMPLATE_ATTR_MAX_CHARS,
+  TEMPLATE_ATTR_OWNER,
+  TEMPLATE_ATTR_SINCE,
+  TEMPLATE_ATTR_REQUIRED_TAGS,
+  TEMPLATE_ATTR_MAX_TOKENS,
+  TEMPLATE_ATTR_REQUIRED_SLOTS,
+  TEMPLATE_ATTR_MODEL,
+  TEMPLATE_FORMATS,
+} from "./template-constants.js";
+
+// Generic attrs shared by template.prompt and template.output.
+const genericAttrs: AttrSchema[] = [
+  {
+    name: TEMPLATE_ATTR_PAYLOAD_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "Reference to the payload (a view-object / projection) this template renders against.",
+  },
+  {
+    name: TEMPLATE_ATTR_TEXT_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description: "2-layer logical reference (group/source) to the body text, resolved by a provider at render time.",
+  },
+  {
+    name: TEMPLATE_ATTR_FORMAT,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    default: "text",
+    allowedValues: [...TEMPLATE_FORMATS],
+    description: "Output format; drives the render engine's escaping/whitespace behavior.",
+  },
+  {
+    name: TEMPLATE_ATTR_MAX_CHARS,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Size budget for the rendered output, in characters.",
+  },
+  {
+    name: TEMPLATE_ATTR_OWNER,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the owner of this template.",
+  },
+  {
+    name: TEMPLATE_ATTR_SINCE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Governance: the version this template was introduced in.",
+  },
+  {
+    name: TEMPLATE_ATTR_REQUIRED_TAGS,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: false,
+    description: "Output tags the rendered text must contain (drives the verify output-tag check).",
+  },
+];
+
+// LLM-overlay attrs (template.prompt only).
+const promptOverlayAttrs: AttrSchema[] = [
+  {
+    name: TEMPLATE_ATTR_MAX_TOKENS,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Token budget for the rendered prompt (LLM-specific).",
+  },
+  {
+    name: TEMPLATE_ATTR_REQUIRED_SLOTS,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: false,
+    description: "Slots that must resolve at render time (drives the verify check).",
+  },
+  {
+    name: TEMPLATE_ATTR_MODEL,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Target model id (LLM-specific).",
+  },
+];
+
+export const TEMPLATE_ATTRS_MAP = new Map<string, AttrSchema[]>([
+  [SUBTYPE_BASE, []],
+  [TEMPLATE_SUBTYPE_PROMPT, [...genericAttrs, ...promptOverlayAttrs]],
+  [TEMPLATE_SUBTYPE_OUTPUT, [...genericAttrs]],
+]);