@metaobjectsdev/sdk 0.20.15 → 0.21.0

package/agent-context/skills/metaobjects-audit/SKILL.md

@@ -330,8 +330,12 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
 ## Prompt anti-patterns (hunt per site; classify: fully-modeled / partial / fully-inline)
 
 - Inline prompt strings (triple-quoted / template-literal constants in service code).
-- Untyped payloads (`str.format(**dict)` / f-strings / ad-hoc dicts) — payload should be an
-  `object.value` with `origin.*` (`passthrough` / `aggregate` / `collection`) fields.
+- Untyped payloads (`str.format(**dict)` / f-strings / ad-hoc dicts) — payload should be a declared
+  shape: an `object.value` (caller-supplied fields; `origin.passthrough` only — FR-015 parameter
+  lineage) or, when fields derive by `aggregate` / `collection` / `computed` / `first`, a
+  **sourceless `object.projection`** carrying those origins (#210 — assembly origins on an
+  `object.value` fail load with `ERR_SUBTYPE_RULE_VIOLATION`; `@payloadRef` accepts the sourceless
+  projection).
 - Silent-degradation hack (`try/except KeyError` or `?? ''` around formatting) — flag every instance.
 - Hand-rolled output parsing (regex / XML / ad-hoc JSON) vs declared `template.output` +
   generated `parse*` / `safeParse*` / `extract*` parser — **generated in all five ports**

package/agent-context/skills/metaobjects-prompts/SKILL.md

@@ -28,7 +28,7 @@ Both carry the generic attrs:
 
 | Attr | Required | Purpose |
 |---|---|---|
-| `@payloadRef` | yes | the `object.value` declaring the payload shape |
+| `@payloadRef` | yes | the `object.value` — or sourceless `object.projection` (#210) — declaring the payload shape |
 | `@textRef` | yes for `template.prompt` and a `template.output @kind: document` (the default) — a `template.output @kind: email` carries **no** `@textRef`; it uses `@subjectRef` + `@htmlBodyRef` (+ optional `@textBodyRef`) instead | the 2-layer logical text reference `group/source`, resolved by a provider |
 | `@format` | no | `text` (default) / `html` / `xml` / `csv` / `json` / `markdown` / `spreadsheet` — drives the escaper |
 | `@maxChars` | no | build-time size budget |
@@ -41,7 +41,8 @@ selects how the output-format prompt fragment presents the payload shape to an L
 (see "the output-format prompt fragment" below); `@requiredTags` names output tags
 the rendered text must contain (`verify` checks it) on both subtypes.
 `template.prompt` additionally carries `@responseRef` — naming the response
-value-object the prompt expects, for typed LLM-call trace derivation.
+shape (an `object.value` or sourceless `object.projection`, #210) the prompt
+expects, for typed LLM-call trace derivation.
 
 A third, structurally different subtype is also registered core vocabulary:
 **`template.toolcall`** (`@toolName` + `@payloadRef`, ADR-0011) — a vendor-agnostic
@@ -50,27 +51,27 @@ LLM tool-call envelope with no renderable text body (the body IS the
 `@format` attrs above). The vocabulary exists today; MCP exposure of declared
 prompts/tools is roadmap, not shipped — don't promise it.
 
-## The payload is an `object.value` projection
-
-The payload is **not** an entity — it's an `object.value` whose every field carries
-an `origin.*` child saying where its value comes from. Three origin subtypes:
-
-| Origin | Behavior |
-|---|---|
-| `origin.passthrough @from "Entity.field"` | payload property matches the source field |
-| `origin.aggregate @agg <count\|sum\|avg\|min\|max>` | `count`→long, `avg`→double, others match source |
-| `origin.collection @via "Parent.rel"` | a list of a nested payload, assembled from a relationship |
-
-These are the **payload-assembly** origins — the vocabulary this skill covers.
-**Projection** read models (`object.projection` over an entity) carry a fuller origin
-vocabulary — the `@agg` predicate quantifiers `any`/`all`, the `collect` array rollup,
-plus `origin.computed` (a closed `@expr` grammar) and `origin.first` (an argmax-style
-pick) — those live in the `metaobjects-authoring` skill and
-`docs/features/source-kinds.md`, not here: don't reach for them on a payload VO.
-
-Declaring the payload as a projection is what makes payload bloat visible: adding a
-field to the prompt is a diff on the `object.value`, and a renamed source field
-breaks the build instead of silently degrading the prompt.
+## The payload is a shape you declare — an `object.value`, or a sourceless `object.projection`
+
+The payload is **not** an entity — it's a declared shape whose fields ARE the
+prompt's typed surface: an `object.value` (caller-supplied fields;
+`origin.passthrough` only — FR-015 parameter lineage), or a **sourceless
+`object.projection`** (#210 — no `source.*` child, own or inherited) when fields
+derive by assembly. Every port's payload codegen is
+**declared-type-authoritative (#270)**: a field's generated type comes only from its
+declared `field.<subType>` + `isArray` + `@objectRef`, and a nested payload is a
+declared `field.object @objectRef` to another `object.value` (`isArray: true` for a
+list — nested targets stay value-only, loader-enforced). The caller supplies the
+field values at render time. An `origin.*` child on a payload field is IGNORED for
+typing — and the assembly origins (`aggregate` / `collection` / `computed` /
+`first`) are ILLEGAL on an `object.value` host (`ERR_SUBTYPE_RULE_VIOLATION`, #210):
+an origin-derived payload lives on the sourceless projection, which `@payloadRef`
+accepts. Projections generally are covered by the `metaobjects-authoring` skill and
+`docs/features/source-kinds.md`, not here.
+
+Declaring the payload shape is what makes payload bloat visible: adding a field to
+the prompt is a diff on the declared shape, and `verify` catches template/payload
+drift at build time instead of letting a prompt silently degrade.
 
 ```json
 {
@@ -81,12 +82,10 @@ breaks the build instead of silently degrading the prompt.
         "object.value": {
           "name": "WelcomePayload",
           "children": [
-            { "field.string": { "name": "displayName",
-              "children": [ { "origin.passthrough": { "@from": "Author.name" } } ] } },
-            { "field.long": { "name": "postCount",
-              "children": [ { "origin.aggregate": { "@agg": "count", "@of": "Post.id", "@via": "Author.posts" } } ] } },
+            { "field.string": { "name": "displayName" } },
+            { "field.long": { "name": "postCount" } },
             { "field.object": { "name": "posts", "@objectRef": "PostSummary",
-              "children": [ { "origin.collection": { "@via": "Author.posts" } } ] } }
+              "isArray": true } }
           ]
         }
       },
@@ -94,8 +93,7 @@ breaks the build instead of silently degrading the prompt.
         "object.value": {
           "name": "PostSummary",
           "children": [
-            { "field.string": { "name": "title",
-              "children": [ { "origin.passthrough": { "@from": "Post.title" } } ] } }
+            { "field.string": { "name": "title" } }
           ]
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.20.15",
+  "version": "0.21.0",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.20.15",
+    "@metaobjectsdev/metadata": "0.21.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {