@metaobjectsdev/sdk 0.20.16 → 0.21.1

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-codegen/references/java.md

@@ -89,9 +89,10 @@ concrete imports and signatures so you don't have to guess them.
 
 ## `codegen-spring` generators
 
-All live in `metaobjects-codegen-spring` under
+Most live in `metaobjects-codegen-spring` under
 `com.metaobjects.generator.spring.*`; wire any subset, typically all three of the
-first group together:
+first group together. (`JavaObjectCodeGenerator`, last row below, lives in the
+separate `metaobjects-codegen-base` module instead.)
 
 | Generator | Output |
 |---|---|
@@ -105,6 +106,7 @@ first group together:
 | `SpringRenderHelperGenerator` | the typed render helper for a `template.prompt` payload |
 | `LlmTraceHelperGenerator` | `<Entity>TraceHelper.java` per concrete entity — the LLM-trace helper |
 | `SpringFilterAllowlistGenerator` | per-entity filter allowlist |
+| `JavaObjectCodeGenerator` | module `metaobjects-codegen-base` (`com.metaobjects.generator.direct.object.javacode`), a separate module from the Spring generators above. Flavor-selected via the `flavor` generator arg. `flavor=pojoAware` → `class <Name> extends PojoObject` (a concrete `MetaObjectAware` class with a `(MetaObject)` constructor) — its inherited `getMetaData()` back-reference is what breaks a default Jackson/Gson mapper, see "Serializing generated objects" below. `flavor=valueObject` → `class <Name> extends ValueObject` (map-backed; less hostile to a default mapper, but still not the sanctioned serialization path). Either concrete flavor also emits a `<Name>Extractor` plus a self-registering `ObjectClassBindingProvider`. For a plain default-Jackson-friendly type, use the `codegen-spring` record surface instead — never `pojoAware`. |
 
 **Projections (read-only views).** An `object.projection` (read-only `source.rdb`
 `@kind: view` child) is served read-only through OMDB at the ObjectManager layer
@@ -153,3 +155,69 @@ polymorphic + per-subtype-scoped repository seam the consumer implements against
 Spring Data JPA / JDBC. Conformance-gated by `fixtures/api-contract-conformance/tph`
 (HTTP wire shape) and `fixtures/persistence-conformance/tph-*` (single-table
 runtime semantics).
+
+## Serializing generated objects
+
+Two paths hand you a `MetaObjectAware` instance: (a) `JavaObjectCodeGenerator`'s
+flavored codegen above (a `pojoAware` or `valueObject` class), and (b) the om/omdb
+runtime (`ObjectManager.getObjects(...)` / `MetaObject.newInstance()` — see the
+runtime-ui reference). **A default Jackson/Gson mapper over a `PojoObject` subtype
+fails on the `MetaObject` back-reference** — the inherited `getMetaData()` getter
+leads a bean-style mapper into the metadata graph, and on a modular JVM into
+`InaccessibleObjectException`. This is expected, not a bug to work around. If you
+want a type that serializes cleanly with a bare default mapper, use the
+`codegen-spring` record surface (`SpringDtoGenerator` / `SpringPayloadGenerator` /
+`SpringValueObjectGenerator`) instead — never `pojoAware`.
+
+Serialize any `MetaObjectAware` instance through the MetaObjects JSON layer's
+`JsonObjectWriter`/`JsonObjectReader`, not a bare mapper — it applies the temporal
+wire form below, and read/write round-trip through the same pair of calls:
+
+```java
+import com.metaobjects.io.object.json.JsonObjectWriter;
+import com.metaobjects.io.object.json.JsonObjectReader;
+import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.object.MetaObject;
+
+import java.io.StringReader;
+import java.io.StringWriter;
+import java.nio.file.Path;
+
+MetaDataLoader loader = MetaDataLoader.fromDirectory("app", Path.of("src/main/metaobjects"));
+MetaObject mo = loader.getMetaObjectByName("acme::blog::Author");
+
+// pojoAware-flavor generated class: public Author(MetaObject mo) { super(mo); }
+Author author = new Author(mo);
+author.setName("Ada");
+author.setBirthDate(new java.util.Date());     // field.date
+
+// Write
+StringWriter out = new StringWriter();
+JsonObjectWriter.writeObject(author, out);
+String json = out.toString();
+// {"@type":"acme::blog::Author","name":"Ada","birthDate":"2026-06-03"}
+
+// Read
+Author roundTripped = JsonObjectReader.readObject(Author.class, mo, new StringReader(json));
+```
+
+**Wire form** (`field.date` / `field.timestamp`):
+
+| Field | Wire form | Example |
+|---|---|---|
+| `field.date` | calendar date of the instant at UTC — `YYYY-MM-DD` | `"2026-06-03"` |
+| `field.timestamp` + `@localTime: true` | wall clock of the instant at UTC, no `Z` | `"2026-06-03T14:30:00.123"` |
+| `field.timestamp` (default, tz-aware) | UTC instant, with `Z` | `"2026-06-03T14:30:00.123Z"` |
+
+Fraction is millisecond resolution, trailing zeros stripped, and the `.` plus
+fraction omitted entirely when zero (`.123`→`.123`, `.120`→`.12`, `.100`→`.1`,
+`.000`→omitted). A `null` value writes JSON `null`. Readers are tolerant and
+backward-compatible: a JSON **number** is still read as **legacy epoch
+milliseconds**; a JSON **string** is tried in order as an ISO instant (the `Z`
+form) → a local date-time (no `Z`) → a date-only form, failing with a message
+naming all three accepted forms.
+
+**Known bounded caveat:** a hand-constructed `field.date` value carrying a
+sub-day time component writes as the calendar date only (truncated on first
+write, stable thereafter) — this matches the shipped OMDB DATE codec, which
+anchors DATE columns at midnight UTC.

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,21 +51,26 @@ 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` you declare
+## The payload is a shape you declare — an `object.value`, or a sourceless `object.projection`
 
-The payload is **not** an entity — it's an `object.value` whose DECLARED fields ARE
-the prompt's typed shape. Every port's payload codegen is
+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). The caller supplies the field values at render time. An `origin.*` child on a
-payload field is IGNORED for typing — never author assembly origins (`aggregate` /
-`collection` / `computed` / `first`) on a payload VO. Derivation belongs to
-**projection** read models (`object.projection` over an entity), covered by the
-`metaobjects-authoring` skill and `docs/features/source-kinds.md`, not here.
+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 `object.value`, and `verify` catches template/payload
+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

package/agent-context/skills/metaobjects-prompts/references/java.md

@@ -53,6 +53,14 @@ rather than a throw. The payload record itself comes from `SpringPayloadGenerato
 — the parser is a companion to it, so the parser and payload VO can't silently
 drift.
 
+Both `parse()` and `extractLenient(...)` here return **plain Java 21 records** —
+safe with any mapper, nothing special needed. That's specific to this
+`codegen-spring` extract tier: the codegen-base flavored `<Name>Extractor` and the
+raw `MetaObjectExtractor` (the alternative extraction path, see the codegen
+reference) return `MetaObjectAware` instances instead, and those need
+`JsonObjectWriter`/`MetaObjectSerializer` — not a bare mapper — to serialize
+correctly (see the codegen reference's "Serializing generated objects" section).
+
 ## The output-format prompt fragment (FR-010)
 
 For every json/xml-format `template.output`, `codegen-spring`'s

package/agent-context/skills/metaobjects-runtime-ui/references/java.md

@@ -65,6 +65,22 @@ try {
 taking a `QueryOptions` (built from an `Expression`). `ValueObject` is the
 map-backed runtime carrier.
 
+## Serializing a row
+
+A `ValueObject` **is** a `Map<String, Object>`, so a default Jackson
+`ObjectMapper` map-serializes it without special configuration — you may not
+hit a hard failure at all. The hard failure other shapes hit is the
+**`pojoAware`** codegen flavor's bean shape (a public `getMetaData()`
+back-reference a bean-style mapper walks into) and any direct Gson field walk
+over a `MetaObjectAware` instance — an OMDB `ValueObject` row sidesteps both.
+
+Even so, the MetaObjects JSON layer (`JsonObjectWriter`/`JsonObjectReader`,
+`com.metaobjects.io.object.json`) is the sanctioned path for an OMDB row
+regardless of mapper friendliness — it's what applies the temporal wire form
+(`field.date`/`field.timestamp` render per the cross-port contract; a default
+mapper has no idea what shape those should take). See the codegen reference's
+"Serializing generated objects" section for the write+read snippet.
+
 ## Spring wiring
 
 `metaobjects-core-spring` (or the Spring Boot starter) declares an

package/agent-context/templates/always-on.md.mustache

@@ -15,6 +15,7 @@ spine; generated code is the disposable artifact. Regenerate with `{{codegenComm
 - Never hand-edit generated files — change the metadata and regenerate (three-way merge preserves hand-written regions).
 - Use the generated constants for any string that names metadata.
 - The loaded metadata model is READ-ONLY — never inject nodes or mutate the tree at load time (no "enrich the model on load" hooks). Need an extra field/column? Author it in the metadata, or derive it during codegen (read the metadata, emit output). Mutating the loaded model makes it diverge from what's declared — a bad practice reserved for very rare cases.
+- **JVM:** serialize a MetaObject-backed instance (a `pojoAware`-flavor generated class, a runtime `ValueObject`, or any `MetaObjectAware` type) through the MetaObjects JSON layer — never hand-configure a Jackson/Gson mapper around the framework fields to make a default mapper cope.
 
 ## Authoring rules you must not violate
 - Nodes are fused-key maps: `{"<type>.<subType>": { ... }}` (e.g. `{"field.string": {"name": "email"}}`) — never split the type and subtype into separate keys.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.20.16",
+  "version": "0.21.1",
   "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.16",
+    "@metaobjectsdev/metadata": "0.21.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {