@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/src/persistence/origin/origin-definition.embedded.ts

@@ -0,0 +1,95 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/origin.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 ORIGIN_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "origin",
+      "subType": "base",
+      "description": "Abstract base origin — the shared root subtype for field-level provenance. A field carrying any origin.* is derived ⇒ read-only wherever it lives. The base carries no attrs of its own; concrete subtypes add their provenance attrs."
+    },
+    {
+      "type": "origin",
+      "subType": "passthrough",
+      "description": "A cross-entity field reference: this projection field passes a source entity's value straight through (@from), optionally reached via a relationship path (@via).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "from",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted Entity.field reference identifying the source value this projection field passes through (e.g. 'Program.title')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 0,
+          "max": 1,
+          "description": "Optional dotted relationship path used to reach the source entity (e.g. 'Program.weeks')."
+        }
+      ]
+    },
+    {
+      "type": "origin",
+      "subType": "aggregate",
+      "description": "A count/sum/avg/min/max (@agg) computed over a column (@of) reached along a relationship path (@via) from the base entity.",
+      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "agg",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "count",
+            "sum",
+            "avg",
+            "min",
+            "max"
+          ],
+          "description": "Aggregate function applied over the relationship path: count, sum, avg, min, or max."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "of",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 0,
+          "max": 1,
+          "description": "Dotted relationship path from the base entity to the aggregated rows (e.g. 'Program.weeks' or 'Program.weeks.workouts'). May be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (FR-024, ADR-0029)."
+        }
+      ]
+    },
+    {
+      "type": "origin",
+      "subType": "collection",
+      "description": "A relationship-derived array of nested view-objects: walks @via to produce the collection (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted relationship path the collection walks to produce an array of nested view-objects (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection (e.g. '*.User')."
+        }
+      ]
+    }
+  ]
+};

package/src/persistence/source/source-definition.embedded.ts

@@ -0,0 +1,24 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/source.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 SOURCE_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "source",
+      "subType": "base",
+      "description": "Abstract base source — the shared root subtype for declaring where an object's data lives (Project E). The base carries no attrs of its own; the concrete paradigm subtype (rdb) carries the physical-storage attrs, which are contributed by the db domain provider."
+    },
+    {
+      "type": "source",
+      "subType": "rdb",
+      "description": "The relational-database paradigm source (ADR-0007): binds an object to a physical relational object. Its physical name is the @table attr (not the structural `name`), and read-only-ness is DERIVED from @kind — table is writable; view, materializedView, storedProc, and tableFunction are read-only. The @table/@kind/@role/@schema/@parameterRef attrs are contributed by the db domain provider, not by core-types.",
+      "rules": "ADR-0007: source declares where an object's data lives; rdb is the relational paradigm subtype. An object may declare multiple sources, distinguished by @role, with exactly ONE @role: \"primary\" per object (write-through CQRS: a writable table for writes plus a read-only view for reads). The physical name is the @table attr (or the @kind-matching alias), never the structural `name`. Read-only-ness is derived from @kind (table → writable; view / materializedView / storedProc / tableFunction → read-only). The pre-v2 dbTable / dbView subtypes are retired."
+    }
+  ]
+};

package/src/persistence/source/validate-source-parameter-ref.ts

@@ -48,7 +48,12 @@ const CALLABLE_KINDS = new Set<string>([
 export function validateSourceParameterRef(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
 
-  // Pre-index every object by name AND fqn so resolution costs O(1) per source.
+  // Pre-index every object by name, fqn AND effective FQN resolution key so
+  // resolution costs O(1) per source. FR-032 — @parameterRef is FQN-qualified
+  // after the desugar/sweep, but objects keep a BARE fqn() per the FR5d
+  // contract, so the FQN form `<package | fileDefaultPackage>::<name>` only
+  // matches via resolutionKey() (these fixtures declare package at metadata.root
+  // only, so obj.package is undefined and the file-default must be folded in).
   const objectIndex = new Map<string, MetaData>();
   for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
     objectIndex.set(obj.name, obj);
@@ -56,6 +61,7 @@ export function validateSourceParameterRef(root: MetaData): ParseError[] {
       ? `${obj.package}${PACKAGE_SEPARATOR}${obj.name}`
       : obj.name;
     objectIndex.set(fqn, obj);
+    objectIndex.set(obj.resolutionKey(), obj);
   }
 
   for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {

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

@@ -9,7 +9,8 @@ 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";
+import { SOURCE_ROLE_PRIMARY, SOURCE_READ_ONLY_KINDS } from "./source-constants.js";
+import { OBJECT_SUBTYPE_ENTITY } from "../../core/object/object-constants.js";
 
 /**
  * Walks every object in the root and enforces the one-primary rule for
@@ -47,6 +48,26 @@ export function validateSourceRoles(root: MetaData): ParseError[] {
         ),
       );
     }
+
+    // FR-024 (ADR-0028) — THE HARD CUTOVER: an entity's PRIMARY source must be
+    // writable; read-only kinds (view/materializedView/storedProc/tableFunction)
+    // are legal only in non-primary (read) roles. The pre-FR-024 spellings
+    // (view-primary "projection" entities, proc-result-as-entity) are removed
+    // outright — a derived read model is an `object.projection`.
+    if (obj.subType === OBJECT_SUBTYPE_ENTITY) {
+      for (const s of sources) {
+        if (s.role === SOURCE_ROLE_PRIMARY && SOURCE_READ_ONLY_KINDS.has(s.effectiveKind)) {
+          errors.push(
+            new ParseError(
+              `entity "${obj.name}" has a primary source of read-only kind "${s.effectiveKind}" — ` +
+                `read-only kinds are legal only in non-primary roles; a derived read model ` +
+                `is an object.projection (FR-024, ADR-0028)`,
+              { code: "ERR_ENTITY_PRIMARY_SOURCE_READONLY", source: s.source },
+            ),
+          );
+        }
+      }
+    }
   }
 
   return errors;

package/src/presentation/layout/layout-definition.embedded.ts

@@ -0,0 +1,23 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/layout.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 LAYOUT_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "layout",
+      "subType": "base",
+      "description": "Abstract base layout — the shared root subtype for object-level UI surfaces. A layout attaches a presentation concern (grids, forms, tabs, cards) to an object. The base carries no attrs of its own; concrete subtypes add their presentation attrs."
+    },
+    {
+      "type": "layout",
+      "subType": "dataGrid",
+      "description": "A metadata-driven data grid attached to an object: declares the displayed columns, page size, default sort, and an optional preset filter the generated grid renders."
+    }
+  ]
+};

package/src/presentation/ui/ui-definition.embedded.ts

@@ -0,0 +1,121 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/ui.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 UI_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-ui",
+  "extends": [
+    {
+      "type": "field",
+      "subType": "*",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "filterable",
+          "min": 0,
+          "max": 1,
+          "description": "When true, the field is exposed in generated CRUD filter allowlists (Project D filter layer)."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "sortable",
+          "min": 0,
+          "max": 1,
+          "description": "When true, the field is exposed in generated CRUD sort allowlists. Inherits from @filterable by default; set false to opt out."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sortableDefaultOrder",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "asc",
+            "desc"
+          ],
+          "description": "Default sort direction applied when this field is the default sort field."
+        }
+      ]
+    },
+    {
+      "type": "view",
+      "subType": "currency",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "locale",
+          "min": 0,
+          "max": 1,
+          "default": "en-US",
+          "description": "BCP 47 locale code controlling currency display formatting. Defaults to 'en-US' when omitted."
+        }
+      ]
+    },
+    {
+      "type": "layout",
+      "subType": "dataGrid",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "pageSize",
+          "min": 0,
+          "max": 1,
+          "description": "Number of rows per page in the generated data grid."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "defaultSortField",
+          "min": 0,
+          "max": 1,
+          "description": "Field name the grid is sorted by on initial render. Must reference an actual field on the entity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "defaultSortOrder",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "asc",
+            "desc"
+          ],
+          "description": "Initial sort direction for the default sort field: 'asc' or 'desc'."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "filterable",
+          "min": 0,
+          "max": 1,
+          "description": "When true, the generated grid exposes column filtering UI."
+        },
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 0,
+          "max": 1,
+          "description": "Structured preset filter object applied to the grid at the metadata level. Desugared to canonical { field: { op: value } } form at parse time."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "columns",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Flat ordered list of field names to display as grid columns."
+        }
+      ]
+    }
+  ]
+};

package/src/presentation/ui/ui-provider.ts

@@ -0,0 +1,25 @@
+// uiProvider — the presentation + query-surface MetaDataTypeProvider. Extends
+// every field subtype with the UI/query-surface markers @filterable / @sortable /
+// @sortableDefaultOrder by extending the core-registered field types. These are
+// presentation/query concerns, NOT core field properties, so they live here —
+// mirroring the dbProvider (db-provider.ts) and promptProvider patterns.
+//
+// FR-033 S1.5-B: the attrs + their descriptions are now DATA — read from
+// spec/metamodel/ui.json (embedded as UI_DEFINITION) via the unified
+// applyProviderDefinition apply path's `extends` handling. The provider declares
+// no new types, so the factory map is empty.
+
+import type { MetaDataTypeProvider } from "../../provider.js";
+import type { TypeRegistry } from "../../registry.js";
+import { applyProviderDefinition } from "../../provider-data.js";
+import { UI_DEFINITION } from "./ui-definition.embedded.js";
+
+export const uiProvider: MetaDataTypeProvider = {
+  id: "metaobjects-ui",
+  dependencies: ["metaobjects-core-types"],
+  description:
+    "UI/query-surface domain — @filterable / @sortable / @sortableDefaultOrder field markers driving generated CRUD filter + sort allowlists (Project D).",
+  registerTypes(registry: TypeRegistry): void {
+    applyProviderDefinition(registry, UI_DEFINITION, {});
+  },
+};

package/src/presentation/view/view-definition.embedded.ts

@@ -0,0 +1,83 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/view.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 VIEW_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "view",
+      "subType": "base",
+      "description": "Abstract view base — the shared root subtype for field-level UI/render hints. A view declares how a field's value is rendered or edited; the base carries no attrs of its own."
+    },
+    {
+      "type": "view",
+      "subType": "text",
+      "description": "Single-line text input/display."
+    },
+    {
+      "type": "view",
+      "subType": "textarea",
+      "description": "Multi-line text area."
+    },
+    {
+      "type": "view",
+      "subType": "date",
+      "description": "Date picker / date display."
+    },
+    {
+      "type": "view",
+      "subType": "month",
+      "description": "Month picker / month display."
+    },
+    {
+      "type": "view",
+      "subType": "hotlink",
+      "description": "Renders the value as a clickable link."
+    },
+    {
+      "type": "view",
+      "subType": "dropdown",
+      "description": "Single-select dropdown control."
+    },
+    {
+      "type": "view",
+      "subType": "radio",
+      "description": "Radio-button selection control."
+    },
+    {
+      "type": "view",
+      "subType": "checkbox",
+      "description": "Checkbox selection control."
+    },
+    {
+      "type": "view",
+      "subType": "number",
+      "description": "Numeric input control."
+    },
+    {
+      "type": "view",
+      "subType": "password",
+      "description": "Masked input for sensitive values."
+    },
+    {
+      "type": "view",
+      "subType": "hidden",
+      "description": "Not rendered; carried but not shown."
+    },
+    {
+      "type": "view",
+      "subType": "web",
+      "description": "Abstract base for web-rendered views."
+    },
+    {
+      "type": "view",
+      "subType": "currency",
+      "description": "Currency display formatting (locale-aware via @locale)."
+    }
+  ]
+};