@metaobjectsdev/metadata 0.9.0-rc.1 → 0.10.0

package/src/template/prompt-definition.embedded.ts

@@ -0,0 +1,375 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/prompt.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 PROMPT_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-prompt",
+  "extends": [
+    {
+      "type": "field",
+      "subType": "*",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "xmlText",
+          "min": 0,
+          "max": 1,
+          "description": "When true, this field receives its element's XML TEXT CONTENT during tolerant extract (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]) instead of a same-named child. No effect for @format: json."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "example",
+          "min": 0,
+          "max": 1,
+          "description": "FR-010: an example value for this field, shown in the generated output-format prompt fragment."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "instruction",
+          "min": 0,
+          "max": 1,
+          "description": "FR-010: a short instruction for this field, shown in the generated output-format prompt fragment."
+        }
+      ]
+    },
+    {
+      "type": "field",
+      "subType": "enum",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "properties",
+          "name": "enumAlias",
+          "min": 0,
+          "max": 1,
+          "description": "Map of alternate/off-vocabulary tokens to canonical enum members; feeds the FR-010 tolerant extract alias-fold."
+        },
+        {
+          "type": "attr",
+          "subType": "properties",
+          "name": "enumDoc",
+          "min": 0,
+          "max": 1,
+          "description": "Map of enum member to a human-readable description; shown per-member in the FR-010 'guide'-style prompt fragment."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "coerceDefault",
+          "min": 0,
+          "max": 1,
+          "description": "Fallback enum member used by tolerant extract when a present value cannot be coerced; must be one of the field's @values."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "normalize",
+          "min": 0,
+          "max": 1,
+          "default": "strip",
+          "allowedValues": [
+            "none",
+            "collapse",
+            "strip"
+          ],
+          "description": "ASCII normalization mode for tolerant enum extract (none|collapse|strip, default strip). On field.enum it is per-field; on object.value it is the default for the object's enum fields."
+        }
+      ]
+    },
+    {
+      "type": "object",
+      "subType": "value",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "normalize",
+          "min": 0,
+          "max": 1,
+          "default": "strip",
+          "allowedValues": [
+            "none",
+            "collapse",
+            "strip"
+          ],
+          "description": "ASCII normalization mode for tolerant enum extract (none|collapse|strip, default strip). On field.enum it is per-field; on object.value it is the default for the object's enum fields."
+        }
+      ]
+    },
+    {
+      "type": "template",
+      "subType": "prompt",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "payloadRef",
+          "min": 1,
+          "max": 1,
+          "description": "Reference to the payload (a view-object / projection) this template renders against."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "textRef",
+          "min": 0,
+          "max": 1,
+          "description": "2-layer logical reference (group/source) to the body text, resolved by a provider at render time."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "format",
+          "min": 0,
+          "max": 1,
+          "default": "text",
+          "allowedValues": [
+            "text",
+            "html",
+            "xml",
+            "csv",
+            "json",
+            "markdown",
+            "spreadsheet"
+          ],
+          "description": "Output format; drives the render engine's escaping/whitespace behavior."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "maxChars",
+          "min": 0,
+          "max": 1,
+          "description": "Size budget for the rendered output, in characters."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "owner",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the owner of this template."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "since",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the version this template was introduced in."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "requiredTags",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Output tags the rendered text must contain (drives the verify output-tag check)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "maxTokens",
+          "min": 0,
+          "max": 1,
+          "description": "Token budget for the rendered prompt (LLM-specific)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "requiredSlots",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Slots that must resolve at render time (drives the verify check)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "model",
+          "min": 0,
+          "max": 1,
+          "description": "Target model id (LLM-specific)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "responseRef",
+          "min": 0,
+          "max": 1,
+          "description": "Optional ref to the response value-object this prompt expects (peer of @payloadRef; drives typed LLM-call trace derivation)."
+        }
+      ]
+    },
+    {
+      "type": "template",
+      "subType": "output",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "payloadRef",
+          "min": 1,
+          "max": 1,
+          "description": "Reference to the payload (a view-object / projection) this template renders against."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "textRef",
+          "min": 0,
+          "max": 1,
+          "description": "2-layer logical reference (group/source) to the body text, resolved by a provider at render time."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "format",
+          "min": 0,
+          "max": 1,
+          "default": "text",
+          "allowedValues": [
+            "text",
+            "html",
+            "xml",
+            "csv",
+            "json",
+            "markdown",
+            "spreadsheet"
+          ],
+          "description": "Output format; drives the render engine's escaping/whitespace behavior."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "maxChars",
+          "min": 0,
+          "max": 1,
+          "description": "Size budget for the rendered output, in characters."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "owner",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the owner of this template."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "since",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the version this template was introduced in."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "requiredTags",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Output tags the rendered text must contain (drives the verify output-tag check)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "promptStyle",
+          "min": 0,
+          "max": 1,
+          "default": "guide",
+          "allowedValues": [
+            "guide",
+            "inline",
+            "exampleOnly"
+          ],
+          "description": "FR-010 output-format prompt presentation: 'guide' (prose list + example), 'inline' (inline placeholders / enum choices), or 'exampleOnly' (filled skeleton). Guidance is never emitted as comments."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "kind",
+          "min": 0,
+          "max": 1,
+          "default": "document",
+          "allowedValues": [
+            "document",
+            "email"
+          ],
+          "description": "Output shape: 'document' (renders @textRef in @format → one string) or 'email' (renders subject + html + optional text → a structured EmailDocument)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "subjectRef",
+          "min": 0,
+          "max": 1,
+          "description": "Email only: 2-layer logical reference (group/source) to the subject-line text. Required when @kind=\"email\"."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "htmlBodyRef",
+          "min": 0,
+          "max": 1,
+          "description": "Email only: 2-layer logical reference (group/source) to the HTML body text. Required when @kind=\"email\"."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "textBodyRef",
+          "min": 0,
+          "max": 1,
+          "description": "Email only: 2-layer logical reference (group/source) to the optional plain-text alternative body."
+        }
+      ]
+    },
+    {
+      "type": "template",
+      "subType": "toolcall",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "toolName",
+          "min": 1,
+          "max": 1,
+          "description": "Wire tool name surfaced to the LLM (vendor-specific format)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "payloadRef",
+          "min": 1,
+          "max": 1,
+          "description": "Output value-object the tool produces (resolved against the metamodel)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "owner",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the owner of this toolcall."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "since",
+          "min": 0,
+          "max": 1,
+          "description": "Governance: the version this toolcall was introduced in."
+        }
+      ]
+    }
+  ]
+};

package/src/template/prompt-provider.ts

@@ -0,0 +1,29 @@
+// promptProvider — the prompt / AI + serialization MetaDataTypeProvider
+// (FR-004/006/010/011). EXTENDS the core-registered field types with the
+// AI-domain markers that are NOT core field properties:
+//   - every field subtype: @xmlText (XML text-content extract), @example,
+//     @instruction (FR-010 field-teaching prompt fragment);
+//   - field.enum only: @enumAlias / @enumDoc / @coerceDefault / @normalize
+//     (FR-010/FR-011 tolerant-extract overlays);
+//   - object.value only: @normalize (the object-level default normalization mode
+//     for its enum fields' tolerant extract).
+//
+// FR-033 S1.5-B: the attrs + their descriptions are now DATA — read from
+// spec/metamodel/prompt.json (embedded as PROMPT_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 { PROMPT_DEFINITION } from "./prompt-definition.embedded.js";
+
+export const promptProvider: MetaDataTypeProvider = {
+  id: "metaobjects-prompt",
+  dependencies: ["metaobjects-core-types"],
+  description:
+    "Prompt / AI + serialization domain — @xmlText / @example / @instruction field markers on every field subtype, the @enumAlias/@enumDoc/@coerceDefault/@normalize tolerant-extract overlays on field.enum, and the object-level @normalize default on object.value.",
+  registerTypes(registry: TypeRegistry): void {
+    applyProviderDefinition(registry, PROMPT_DEFINITION, {});
+  },
+};

package/src/template/template-constants.ts

@@ -65,6 +65,7 @@ export const TEMPLATE_ATTR_HTML_BODY_REF = "htmlBodyRef";
 export const TEMPLATE_ATTR_TEXT_BODY_REF = "textBodyRef";
 
 // Prompt-overlay attrs (template.prompt only).
+export const TEMPLATE_ATTR_RESPONSE_REF = "responseRef";
 export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
 export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
 export const TEMPLATE_ATTR_MODEL = "model";
@@ -107,3 +108,10 @@ export const PROMPT_STYLES = [
   PROMPT_STYLE_EXAMPLE_ONLY,
 ] as const;
 export type PromptStyle = (typeof PROMPT_STYLES)[number];
+
+// @xmlText — a FIELD-level marker (boolean) for the tolerant extract engine: this field
+// receives its element's TEXT CONTENT when a template.output response is parsed from XML
+// (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]). Registered on field.* by
+// promptProvider (the prompt / AI + serialization domain owns this extract concern — NOT a
+// core field property). No effect for @format: json. Mirrors Java TemplateConstants.ATTR_XML_TEXT.
+export const FIELD_ATTR_XML_TEXT = "xmlText";

package/src/template/template-definition.embedded.ts

@@ -0,0 +1,37 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/template.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 TEMPLATE_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "template",
+      "subType": "base",
+      "description": "Abstract base template — the shared root subtype for the fourth pillar (FR-004, ADR-0011). A template is a typed payload bound to either a rendered text artifact (prompt/output) or a tool-call envelope. The base carries no attrs of its own; concrete subtypes add their reference + governance attrs.",
+      "rules": "A single MetaTemplate node class backs every template subtype (no subType→class dispatch); the subtype selects which reserved-attr set applies. @format (a closed-enum ATTRIBUTE, never a subtype) drives the render engine's escaper/whitespace behavior, so a new format costs one escaper + one enum value rather than a new subtype + cross-language port."
+    },
+    {
+      "type": "template",
+      "subType": "prompt",
+      "description": "An LLM-targeted renderable prompt template (FR-004). Carries the generic reference + governance attrs plus the LLM overlay (@maxTokens / @requiredSlots / @model / @responseRef). Its renderable body is required via @textRef.",
+      "rules": "prompt requires @payloadRef (the typed payload it renders against) AND @textRef (the body text, provider-resolved at render time — enforced in the loader's validateTemplatePayloadRefs pass, not at the attr layer where @textRef is relaxed to optional so template.output email can omit it). @format is a closed enum keyed by the render engine's escaper. @responseRef (optional) names the response value-object the prompt expects and drives typed LLM-call trace derivation."
+    },
+    {
+      "type": "template",
+      "subType": "output",
+      "description": "An output / serialization template (FR-004): every rendered artifact other than an LLM prompt — a document (email, export, docs, config) or an email. Carries the generic reference + governance attrs, the FR-010 @promptStyle, and the @kind + email part-refs.",
+      "rules": "output is either a document (@kind=\"document\" or absent → renders @textRef in @format to one string) or an email (@kind=\"email\" → renders subject + html + optional text to a structured EmailDocument). The cross-field presence rule is enforced in the loader's validateTemplatePayloadRefs pass: document requires @textRef; email requires @subjectRef AND @htmlBodyRef (with @textBodyRef optional) and carries NO @textRef. @format is a closed enum keyed by the render engine's escaper; @promptStyle (FR-010) selects the output-format prompt presentation and is never emitted as comments."
+    },
+    {
+      "type": "template",
+      "subType": "toolcall",
+      "description": "A vendor-agnostic LLM tool-call envelope (ADR-0011). Unlike prompt/output it has NO renderable text body — the body IS the structured output schema resolved via @payloadRef. This is why toolcall is its own subtype rather than template.output + @toolName. Does NOT inherit the generic attrs.",
+      "rules": "toolcall requires @toolName (the wire tool name surfaced to the LLM) AND @payloadRef (the output value-object the tool produces). @textRef is intentionally absent — a tool-call has no renderable text. Core keeps toolcall vendor-agnostic; vendor wire details (retry semantics, fallback shapes, parallel invocation, cache hints) are added by consumer providers via registry.extend(TYPE_TEMPLATE, \"toolcall\", { attributes: [...] }). The LLM-facing tool description reuses the @description documentation common attr (added to every type by docProvider), so it is not redeclared here."
+    }
+  ]
+};

package/src/core/documentation/doc-schema.ts

@@ -1,64 +0,0 @@
-import { type AttrSchema } from "../../registry.js";
-import {
-  ATTR_SUBTYPE_STRING,
-  ATTR_SUBTYPE_STRINGARRAY,
-} from "../attr/attr-constants.js";
-import {
-  DOC_ATTR_ALIASES,
-  DOC_ATTR_DEPRECATED,
-  DOC_ATTR_DESCRIPTION,
-  DOC_ATTR_NOTES,
-  DOC_ATTR_REPLACED_BY,
-  DOC_ATTR_SEE_ALSO,
-  DOC_ATTR_TITLE,
-} from "./doc-constants.js";
-
-/**
- * The 7 universal documentation common attrs. Registered via the
- * registry.registerCommonAttrs() hook by the documentation provider.
- * Per ADR-0006, attr names are bare here; the serializer prefixes with @.
- */
-export const commonDocAttrs: AttrSchema[] = [
-  {
-    name: DOC_ATTR_DESCRIPTION,
-    valueType: ATTR_SUBTYPE_STRING,
-    required: false,
-    description: "Free-form user-facing prose. Markdown allowed, multi-line via YAML '|' block scalar. Flows into doc-gen surfaces (JSDoc / XML-doc / Postgres COMMENT / Mermaid prose).",
-  },
-  {
-    name: DOC_ATTR_TITLE,
-    valueType: ATTR_SUBTYPE_STRING,
-    required: false,
-    description: "Short single-line human label (e.g. 'Email' for a `field.string email`). Optional supplement to description.",
-  },
-  {
-    name: DOC_ATTR_NOTES,
-    valueType: ATTR_SUBTYPE_STRING,
-    required: false,
-    description: "Internal-only rationale. Stays in metadata; never emitted to user-facing docs.",
-  },
-  {
-    name: DOC_ATTR_DEPRECATED,
-    valueType: ATTR_SUBTYPE_STRING,
-    required: false,
-    description: "Text reason for deprecation. Presence ⇒ deprecated. Codegen emits @deprecated / [Obsolete] with this reason.",
-  },
-  {
-    name: DOC_ATTR_REPLACED_BY,
-    valueType: ATTR_SUBTYPE_STRING,
-    required: false,
-    description: "FQN reference to the replacement element. Only meaningful with `deprecated`. Codegen appends 'Replaced by <ref>' to deprecation messages.",
-  },
-  {
-    name: DOC_ATTR_SEE_ALSO,
-    valueType: ATTR_SUBTYPE_STRINGARRAY,
-    required: false,
-    description: "External documentation URLs. Codegen emits @see / <seealso href=...>.",
-  },
-  {
-    name: DOC_ATTR_ALIASES,
-    valueType: ATTR_SUBTYPE_STRINGARRAY,
-    required: false,
-    description: "Alternate names for this element. Aids AI authoring disambiguation, search, migration.",
-  },
-];