@metaobjectsdev/sdk 0.16.0 → 0.17.0

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

@@ -291,9 +291,10 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
 5. **Runtime schema patching** (`ALTER TABLE … ADD COLUMN IF NOT EXISTS`, `_ensure_schema()`) — N schema owners.
 6. **N declarations of one shape** — same entity as Drizzle table + Zod schema + Pydantic model + hand dataclass; target is 1 + N generated.
 7. **`own*()` accessor read of an effective property** (ADR-0039) — `ownAttr` / `ownFields` / `own_children` / bare Python `attr(` / `getMetaAttr(name, false)` / native `IsArray` used to read a value or iterate members outside the sanctioned subclass-emit / own-serializer / `@dbColumnType` cases → silently drops `extends`-inherited values. A **correctness defect** (axis G2), not advisory.
-8. **Hand-written `CREATE VIEW` / read-only SQL standing in for a projection (view-necessity test).** Grep migrations, checked-in `.sql`, and repository/query code for `CREATE [OR REPLACE] [MATERIALIZED] VIEW`, and for hand-rolled read-only queries that mirror a read model — a pure-`SELECT` repository/service method with joins or `GROUP BY` feeding a DTO, or a raw-SQL escape (`db.execute(sql…)`, `FromSqlRaw`, a JPA @Query with hand-written SQL). For each, run the **necessity test** — can `object.projection` + origins express this shape? It can when every output column is (a) a base-entity or relationship-joined column → `origin.passthrough` (`@from` / `@via`), (b) a count/sum/avg/min/max over related rows → `origin.aggregate` (`@agg` / `@of` / `@via`, optionally row-scoped with `@filter`), (c) a child collection → `origin.collection` (`@via`), or (d) a column borrowed via `extends` — and the joins follow declared relationships / `identity.reference` FKs.
-   - **Expressible → CODEGEN CANDIDATE (high):** convert to an `object.projection` with a read-only `source.rdb` `@kind: view` child, let `meta migrate` emit the `CREATE VIEW`, and consume the generated read-only query — the hand-written view is a second source of truth for a derivable shape. Flag in the finding that **`meta verify --db` cannot catch this**: an unmodeled DB view is *unmanaged*, so this audit is the only gate that sees it. Parity-gate: the generated view returns row-identical results before the hand-written SQL is deleted.
-   - **Not expressible → BESPOKE (keep), with a NAMED justification:** record the construct that makes it irreducible (recursive CTE, window function / `OVER`, `UNION` / `INTERSECT` / `EXCEPT`, `DISTINCT ON`, lateral join, non-aggregate expression column). "It's an aggregation" is NOT a justification — plain count/sum/avg/min/max rollups are `origin.aggregate`.
+8. **Hand-written `CREATE VIEW` / read-only SQL standing in for a projection or entity read-view (view-necessity test).** Grep migrations, checked-in `.sql`, and repository/query code for `CREATE [OR REPLACE] [MATERIALIZED] VIEW`, and for hand-rolled read-only queries that mirror a read model — a pure-`SELECT` repository/service method with joins or `GROUP BY` feeding a DTO, or a raw-SQL escape (`db.execute(sql…)`, `FromSqlRaw`, a JPA @Query with hand-written SQL). For each, run the **necessity test** — can origins express this shape? A column is derivable when it is (a) a base-entity or relationship-joined column → `origin.passthrough` (`@from` / `@via`), (b) a count/sum/avg/min/max over related rows → `origin.aggregate` (`@agg` / `@of` / `@via`), or an `EXISTS` / `array_agg` → `origin.aggregate` `any` / `all` / `collect` — any of them optionally row-scoped with `@filter`, (c) a child collection → `origin.collection` (`@via`), (d) a computed scalar / **non-aggregate expression column** → `origin.computed` (`@expr`, #195), (e) one related row's column picked by an ordering — an **argmax / `DISTINCT ON … ORDER BY` / correlated `ORDER BY … LIMIT 1`** → `origin.first` (`@of` / `@via` / `@orderBy`, #195), or (f) a column borrowed via `extends` — and the joins follow declared relationships / `identity.reference` FKs.
+   - **Entity-shaped (`SELECT own.* + derived`) → an entity read-view, NOT a projection (#214).** The single most common legacy view is an entity's OWN columns plus a joined/derived extra (`SELECT o.*, c.name AS customer_name`). This is the `Order` **entity with a read route**, not an exposure contract — route it to an **entity read-view**: keep the writable `@role: primary` `@kind: table` source and add a **non-primary `@role: replica` `@kind: view`** source, declaring only the *extra* as a derived `origin.*` field on the entity (the own field set already covers `o.*`). Reads route to the replica view, writes to the table. Reach for a **projection** instead only when the view renames base columns or **row-filters** (`WHERE status='active'`, soft-delete) — the latter is a projection with an object-level `@filter` (#207) that lowers to the outer `WHERE`.
+   - **Exposure contract, expressible → CODEGEN CANDIDATE (high):** a subset / renamed / versioned / multi-base read model → convert to an `object.projection` with a read-only `source.rdb` `@kind: view` child, let `meta migrate` emit the `CREATE VIEW`, and consume the generated read-only query — the hand-written view is a second source of truth for a derivable shape. Parity-gate: the generated view returns row-identical results before the hand-written SQL is deleted.
+   - **Not expressible → carry it in `@sql` or `@unmanaged`, never a hand-edited migration (#208, ADR-0043).** When a NAMED irreducible construct blocks origin authoring — recursive CTE, window function / `OVER`, `UNION` / `INTERSECT` / `EXCEPT`, lateral join — the body still belongs in the metadata: carry the hand-written SQL in the `source.rdb` **`@sql`** escape — a read-only-`@kind` body the tool REGISTERS, fingerprints, and drift-checks (adopt a pre-existing view with `meta migrate --allow adopt-view`); `@sql` forbids `origin.*` children (two sources of truth). A DB object whose DDL is owned **entirely elsewhere** (Flyway / a hand-migration) → mark its source **`@unmanaged: true`** (legal on any `@kind` incl. `table`); `meta migrate` never creates/drops/drift-checks it and `verify --db` reports it as external. `@sql` and `@unmanaged` are mutually exclusive. **Only a view left *undeclared*** — neither modeled, nor `@sql`, nor `@unmanaged` — is truly *unmanaged*, invisible to `meta verify --db`, so this audit is the only gate that sees it. "It's an aggregation" is NOT an irreducibility justification (plain count/sum/avg/min/max rollups are `origin.aggregate`); nor is a `DISTINCT ON` pick-one-row (`origin.first`) or a non-aggregate expression column (`origin.computed`).
 9. **A closed variant-set hand-modeled per instance** — N sibling modules / classes / config blocks, one per channel / provider / target, sharing a payload + config shape and diverging only by transport. Grep for sibling-file families and switch-on-a-string dispatch; verify the set is closed and recurring (never a one-off). → axis I "New-vocabulary OPPORTUNITY" (VOCAB CANDIDATE, advisory).
 
 ---
@@ -313,10 +314,12 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
   own + customize / author a template-spec / fix upstream / stopgap.
 - **Verify the DB artifact, not just the types** — computed view columns may appear in the
   contract but be dropped from the view DDL; the contract may lie.
-- **A hand-authored DB view is invisible to `meta verify --db`.** An unmodeled view is
-  *unmanaged* (informational only — never actionable drift, never auto-dropped), so a
-  hand-written view standing in for an expressible `object.projection` can never be
-  outsourced to the drift gate; hunt it here (drift signature 8, below).
+- **An *undeclared* hand-authored DB view is invisible to `meta verify --db`.** A view that is
+  neither modeled nor carried in the `source.rdb` `@sql` / `@unmanaged` escapes is *unmanaged*
+  (informational only — never actionable drift, never auto-dropped), so a hand-written view
+  standing in for an expressible `object.projection` / entity read-view can never be outsourced
+  to the drift gate; hunt it here (drift signature 8, below). Once carried in `@sql` (#208) it IS
+  registered, fingerprinted, and drift-checked — no longer audit-only.
 - **Version skew:** check *actually-resolved* package versions, not declared; consuming a fix
   requires a coordinated lockstep bump, not a source-file copy.
 
@@ -329,8 +332,9 @@ Per finding: `file:line` → what → generated-equivalent exists? → recommend
   `object.value` with `origin.*` (`passthrough` / `aggregate` / `collection`) fields.
 - 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. **Java hand-writes the Jackson
-  one-liner — do NOT flag it** (§ Calibration).
+  generated `parse*` / `safeParse*` / `extract*` parser — **generated in all five ports**
+  (Java's generated `<Name>Parser` owns the Jackson `readValue`); flag a hand-rolled parser
+  in a **non-generated** file where a `template.output` node exists.
 - Engine-side formatting breaking byte-identical render (prompt-cache exact-prefix hits
   depend on byte-stability).
 - `template.toolcall` candidates: LLM tool schemas hand-defined per call vs modeled
@@ -445,9 +449,18 @@ The audit never edits code. Pattern: **dry-run → review the diff → apply**.
 
 ## Calibration — port gaps & non-defects (do NOT flag these as adopter fault)
 
-- **Filter-operator route codegen** is full only in **TS**; Java/Kotlin/C#/Python generate
-  pagination/sort/`withCount` but defer filter ops — do not flag hand-added filter handling.
-- **Output-parser codegen** ships TS/C#/Python/Kotlin; **Java hand-writes the Jackson parse** — not a defect.
+- **Filter-operator route codegen — the CORE grammar ships in all five ports.** The
+  `?filter[field][op]=value` grammar (all 9 operators `eq/ne/gt/gte/lt/lte/in/like/isNull`,
+  implicit-AND across params, the generated `<Entity>FilterAllowlist` + `invalid-field` /
+  `invalid-op` / `in`-over-cap 400s) is **generated in every port** (Java `SpringControllerGenerator`,
+  C# `RoutesGenerator`, Python `router_generator`, Kotlin `KotlinSpringControllerGenerator`, TS) —
+  gated by the api-contract corpus in BOTH lanes. **Flag hand-rolled filter parsing anywhere.**
+  Only the *richer* surface is genuinely **TS-only**: free-text `?search=`, the explicit
+  `filter[or][N]` / `filter[and][N]` nested boolean combinators (+ their nesting-depth cap), and
+  leading-wildcard gating — do NOT flag the absence of those in a non-TS port.
+- **Output-parser codegen** ships in **all five ports** — Java's `SpringOutputParserGenerator`
+  *generates* the `<Name>Parser` (the Jackson `readValue` lives inside that generated file). A
+  hand-rolled parser in a **non-generated** file where a `template.output` node exists IS a finding.
 - **Python** still hand-wires the FastAPI router + repository impl around a generated
   `APIRouter`; relationship / non-`table` source-kind / `field.object flattened` codegen is partial.
 - **C#** has no ObjectManager runtime tier (EF Core is the runtime) — hand services over the generated `DbContext` are expected.

package/agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -53,8 +53,10 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
   assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
   (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
-  hints), `@xmlText` (hand XML-text mapping). Indexed-without-filter suppression is the
-  `db.indexed` attr (cite without the `@` sigil — it is a dotted attr name).
+  hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
+  *`@filterable`-without-index* Loader warning (you assert the column is indexed by other
+  means); it is a dotted attr name but canonical JSON still authors it WITH the sigil:
+  `"@db.indexed": true`.
 - **CALIBRATION — cut subtypes:** `field.byte`, `field.short`, `field.class` are
   non-functional removed stubs. **Do NOT audit for them and never recommend them.**
 
@@ -63,15 +65,29 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`source.rdb`** (`@table`, `@schema`) — hunt hard-coded physical table/schema names that
   diverge from the default naming the source models.
 - **`@kind` = `view` / `materializedView`** — hunt hand-written SQL views where an authored
-  projection source (read-only `@kind`) belongs. Apply the **view-necessity test** (SKILL.md,
-  drift signature 8): a hand-written `CREATE VIEW` (or read-only SQL mirroring a read model) is a
-  CODEGEN CANDIDATE when its shape is expressible via `origin.passthrough` / `origin.aggregate` /
-  `origin.collection` + `extends` — convert it to an `object.projection` so `meta migrate` emits
-  the view DDL. It is BESPOKE-keep only when a NAMED irreducible construct (recursive CTE, window
-  function, set op) blocks projection authoring. `meta verify --db` can't see an unmodeled view,
+  read-only source belongs. Apply the **view-necessity test** (SKILL.md, drift signature 8): a
+  hand-written `CREATE VIEW` (or read-only SQL mirroring a read model) is a CODEGEN CANDIDATE when
+  its shape is expressible via `origin.passthrough` / `origin.aggregate` / `origin.collection` /
+  `origin.computed` / `origin.first` + `extends`. Route by shape: an entity's OWN columns plus an
+  extra (`SELECT o.*, …`) → an **entity read-view** (#214: a `@role: replica` view beside the
+  writable `table`); a subset / renamed / row-filtered exposure → an `object.projection` (row-scope
+  with an object-level `@filter`, #207) — so `meta migrate` emits the view DDL. A genuinely
+  irreducible body (recursive CTE, window function, set op) belongs in the `source.rdb` `@sql`
+  escape (#208), not a hand migration. Only an *undeclared* view is invisible to `meta verify --db`,
   so this is audit-only.
 - **`@kind` = `storedProc` / `tableFunction`** (`@parameterRef`) — hunt hand-called procs /
   table functions that a modeled callable source with `@parameterRef` already describes.
+- **`@sql`** (read-only `@kind` only; mutually exclusive with `@unmanaged`) — a hand-written SQL
+  body the tool REGISTERS, fingerprints, and drift-checks but never authors or parses (#208,
+  ADR-0043). The **escape valve for a genuinely irreducible view** origins can't express (recursive
+  CTE, window function, set op): carry the body here rather than in a hand-edited migration where it
+  goes accidentally unmanaged. Forbids `origin.*` children (two sources of truth); adopt a
+  pre-existing view with `meta migrate --allow adopt-view`. Hunt a hand-written irreducible
+  `CREATE VIEW` in a migration / `.sql` that should be carried in `@sql`.
+- **`@unmanaged`** (any `@kind` incl. `table`; mutually exclusive with `@sql`) — marks a DB object
+  whose DDL is owned entirely elsewhere (Flyway / a hand-migration). `meta migrate` never creates,
+  drops, or drift-checks it; `verify --db` reports it as external (declared). Hunt an
+  externally-owned table/view the metadata silently omits instead of declaring `@unmanaged: true`.
 - **`@role` = `primary`** (multi-source write-through) — hunt manual CQRS / write-through
   wiring; exactly one `primary` source per object models it.
 - **`source.base`** — abstract source base (no audit target of its own).
@@ -107,16 +123,28 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
   a NON-unique retrieval index (uniqueness is what distinguishes it from `identity.secondary`);
   hunt hand-created lookup / recency indexes (`CREATE INDEX …`) it models.
 
-## Origin — `origin.*` (projection-field derivation)
+## Origin — `origin.*` (derived fields — on projections AND entity read-views)
 
-- **`origin.aggregate`** (`@agg`, `@of`, `@via`) — hunt hand `COUNT` / `SUM` / `AVG`
+- **`origin.aggregate`** (`@agg`, `@of`, `@via`, `@filter`) — `@agg`: `count`/`sum`/`avg`/`min`/`max`
+  (numeric reduces over `@of`), `any`/`all` (predicate quantifiers over `@filter`; `@of` forbidden),
+  `collect` (array rollup of `@of` into an `isArray` field; `@distinct`/`@orderBy` collect-only).
+  Any aggregate may be row-scoped with `@filter`. Hunt hand `COUNT`/`SUM`/`AVG`/`EXISTS`/`array_agg`
   subqueries or in-app rollups a derived aggregate field models.
-- **`origin.passthrough`** (`@from`, `@via`) — hunt denormalized-by-hand copied fields that a
-  passthrough origin pulls across a relationship.
+- **`origin.passthrough`** (`@from`, `@via`, `@convert`) — hunt denormalized-by-hand copied fields
+  that a passthrough origin pulls across a relationship.
 - **`origin.collection`** (`@via`) — hunt hand-assembled child-collection loading a collection
   origin derives.
+- **`origin.computed`** (`@expr` — a closed `attr.expression` grammar) — hunt a hand-computed derived
+  scalar (a formula over other fields) a computed origin models.
+- **`origin.first`** (`@of`, `@via`, `@orderBy`, `@filter`; `@orderBy` REQUIRED) — hunt a hand
+  argmax-style "one related row's column" projection — a `DISTINCT ON … ORDER BY` or correlated
+  `ORDER BY … LIMIT 1` — a first origin models (nullable).
 - **`origin.base`** — abstract base.
 
+Distinct from the per-aggregate `@filter` above, an **object-level `@filter` on
+`object.projection`** (#207) row-scopes the WHOLE view (outer `WHERE`) — hunt a hand-written
+soft-delete / status / type view it models.
+
 ## Validator — `validator.*`
 
 - **`validator.required` / `validator.length` / `validator.numeric` / `validator.array` /
@@ -144,12 +172,14 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 ## Template — `template.*` (prompt pillar)
 
 - **`template.prompt`** (`@payloadRef`, `@textRef`, `@responseRef`, `@requiredSlots`,
-  `@maxTokens`, `@maxChars`, `@format`, `@model`, `@promptStyle`) — hunt prompt strings
+  `@requiredTags`, `@maxTokens`, `@maxChars`, `@format`, `@model`) — hunt prompt strings
   assembled inline in services, payloads built ad-hoc, output parsing without a typed
   `@responseRef`, or token/char budgets enforced by hand.
 - **`template.output`** (`@kind` = `document` | `email`; `@subjectRef`, `@htmlBodyRef`,
-  `@textBodyRef`) — hunt hand-built document/email rendering + hand-written
-  parse-on-receipt the output template + generated render helper/parser cover.
+  `@textBodyRef`, `@promptStyle`, `@requiredTags`) — hunt hand-built document/email rendering +
+  hand-written parse-on-receipt the output template + generated render helper/parser cover.
+  (`@promptStyle` — the FR-010 output-format presentation — is on `template.output` ONLY;
+  authoring it on `template.prompt` fails load with `ERR_UNKNOWN_ATTR`.)
 - **`template.toolcall`** (`@toolName`, `@payloadRef`) — hunt hand-declared LLM tool schemas
   a modeled tool call describes.
 - **`template.base`** — abstract base.
@@ -185,11 +215,15 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
   `origin.*` never inherits).
 - **Filter + sort + pagination REST layer** — hunt hand-written query parsing, `LIMIT`/
   `OFFSET` pagination, total-count queries, and filter/sort handling the generated CRUD layer
-  (8 filter operators + sort + `?limit=N&offset=N` + count) already provides.
-  - **CALIBRATION — per-port codegen gaps:** filter-operator route codegen is full only in
-    **TS**; Java / Kotlin / C# / Python generate pagination/sort/count but **defer filter
-    ops** — do NOT flag hand-added filter handling there. Output-parser codegen ships
-    TS/C#/Python/Kotlin; **Java hand-writes** the Jackson parse (acceptable). **Python**
+  (9 filter operators `eq/ne/gt/gte/lt/lte/in/like/isNull` + sort + `?limit=N&offset=N` + count)
+  already provides.
+  - **CALIBRATION — per-port codegen gaps:** the core `?filter[field][op]` filter grammar (all
+    9 operators + the generated allowlist + `invalid-field` / `invalid-op` / `in`-over-cap 400s)
+    is **generated in all five ports** (api-contract corpus, both lanes) — **flag hand-rolled
+    filter parsing anywhere.** Only the richer surface (`?search=`, explicit
+    `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating) is TS-only.
+    Output-parser codegen also ships in **all five ports** — Java's `SpringOutputParserGenerator`
+    *generates* the parser (the Jackson `readValue` lives inside that generated file). **Python**
     still hand-wires the FastAPI router around a generated `APIRouter` (relationship /
     non-`table` source-kind / flattened-object codegen is partial). **C#** has no
     ObjectManager runtime tier (EF Core *is* the runtime) — hand services over the generated

package/agent-context/skills/metaobjects-audit/references/csharp.md

@@ -95,10 +95,13 @@ version across these packages is an intra-port skew finding.
   pattern, not a defect.
 - **No C# migrate command.** Schema migration is Node-`meta`-owned for every port
   (ADR-0015). `dotnet meta` has no migrate subcommand; `meta migrate` is correct.
-- **Filter-operator route codegen deferred.** The generated `<Entity>Routes.cs` (Minimal
-  API) supports `?sort`, `?limit`/`?offset`, and `?withCount=1` envelope, but filter
-  operators (`?filter[field][op]=value`) are not yet generated. Do NOT flag hand-added
-  C# filter handling as an adopter defect.
+- **Core filter-operator codegen ships in C# — do NOT treat it as deferred.** The `routes`
+  generator (`<Entity>Routes.cs`, Minimal API) generates the `?filter[field][op]=value` grammar
+  (all 9 operators `eq/ne/gt/gte/lt/lte/in/like/isNull`) via the runtime `FilterParser` +
+  `EfCoreFilterDispatch`, validated against the generated filter allowlist (api-contract corpus,
+  both lanes). **Flag a hand-rolled filter parser as a finding.** Only the richer surface
+  (`?search=`, `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating) is
+  TS-only — do NOT flag its absence in C#.
 - **Output-parser codegen ships in C#.** `output-parser` / `extractor` / `render-helper`
   generators are available (`dotnet meta gen --generators output-parser`). Absence of
   wired output parsers where `template.output` nodes exist IS a finding.

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

@@ -88,16 +88,18 @@ versioning — **do not flag it** (only intra-port skew matters).
 
 ## Calibration gaps (do NOT flag these)
 
-- **Hand-written output parser is expected.** The `SpringOutputParserGenerator` emits
-  a typed `<Name>Parser` class, but the Jackson `readValue` one-liner inside it is
-  hand-written by the generator — it is NOT a defect to see Jackson deserialization in
-  generated `*Parser.java` files. **Do not flag Jackson `readValue` calls in
-  `*Parser.java` files.** Only flag hand-rolled parsers in *non*-generated files where
-  a `template.output` node exists.
-- **Filter-operator route codegen deferred.** The generated `<Entity>Controller.java`
-  supports `?sort`, `?limit`/`?offset`, and `?withCount=1` envelope but defers
-  filter-operator validation (`?filter[field][op]=value`). Do NOT flag hand-added
-  Java filter handling as an adopter defect.
+- **Jackson `readValue` inside a generated parser is expected.** `SpringOutputParserGenerator`
+  *generates* the typed `<Name>Parser` class; the Jackson `readValue` call lives inside that
+  generated file. It is NOT a defect to see Jackson deserialization in a generated `*Parser.java`
+  file. **Do not flag Jackson `readValue` calls in generated `*Parser.java` files.** DO flag a
+  hand-rolled parser in a *non*-generated file where a `template.output` node exists.
+- **Core filter-operator codegen ships in Java — do NOT treat it as deferred.**
+  `SpringControllerGenerator` generates the `?filter[field][op]=value` grammar (all 9 operators
+  `eq/ne/gt/gte/lt/lte/in/like/isNull`): it parses via the runtime `FilterParser`, validates
+  against the generated `<Entity>FilterAllowlist`, and 400s on unknown field / disallowed op /
+  over-cap `in`-list (api-contract corpus, both lanes). **Flag a hand-rolled filter parser as a
+  finding.** Only the *richer* surface is TS-only — `?search=`, `filter[or][N]` / `filter[and][N]`
+  combinators, leading-wildcard gating — do NOT flag the absence of those in Java.
 - **Repository interface is a hand-implemented stub.** `SpringRepositoryGenerator`
   emits `<Entity>Repository.java` as a stub `interface`; the consumer hand-writes the
   implementation against OMDB (or any persistence layer). Hand-written repository

package/agent-context/skills/metaobjects-audit/references/kotlin.md

@@ -97,12 +97,16 @@ cross-port versioning — **do not flag it** (only intra-port skew matters).
   emits the `Table` column definitions; the consumer hand-writes the (typically trivial)
   `transaction(db) { ... }` bodies that query and mutate those tables. This is the expected
   Kotlin runtime pattern — do NOT flag hand-written Exposed transactions as a defect.
-- **Hand-written output parser is expected.** `KotlinOutputParserGenerator` emits a typed
-  parser class, but the deserialization body inside it uses a hand-written kotlinx.serialization
-  call — do NOT flag this. Only flag hand-rolled parsers in non-generated files where a
-  `template.output` node exists.
-- **Filter-operator route codegen deferred.** The generated `<Entity>Controller.kt` supports
-  `?sort`, `?limit`/`?offset`, and `?withCount=1` envelope but defers filter-operator
-  validation. Do NOT flag hand-added Kotlin filter handling as an adopter defect.
+- **Output-parser codegen ships in Kotlin — do NOT treat it as deferred.**
+  `KotlinOutputParserGenerator` generates the typed parser class AND its deserialization body
+  (a kotlinx `Json.decodeFromString` call inside the generated file — kotlinx, not Jackson: the
+  #187 Jackson move was jsonb-codec-only, prompt payloads/parsers stay on kotlinx). Only flag
+  a hand-rolled parser in a NON-generated file where a `template.output` node exists.
+- **Core filter-operator codegen ships in Kotlin — do NOT treat it as deferred.**
+  `KotlinSpringControllerGenerator` generates the `?filter[field][op]=value` grammar (all 9
+  operators `eq/ne/gt/gte/lt/lte/in/like/isNull`) validated against the generated filter allowlist
+  (api-contract corpus, both lanes). **Flag a hand-rolled filter parser as a finding.** Only the
+  richer surface (`?search=`, `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard
+  gating) is TS-only — do NOT flag its absence in Kotlin.
 - **No JVM migrate goal.** Schema migration is Node-`meta`-owned for every port
   (ADR-0015). The Maven plugin has no migrate goal; `meta migrate` is correct.

package/agent-context/skills/metaobjects-audit/references/python.md

@@ -98,10 +98,13 @@ another) matters.
   generated router are typed `dict[str, Any]` and responses return `Any`. Tightening
   to the typed Pydantic model is a hand-edit the adopter may choose — do NOT flag
   the `Any` as an adopter fault.
-- **Filter-operator route codegen deferred.** The generated `APIRouter` supports
-  `?sort`, `?limit`/`?offset`, and `?withCount=1` envelope but defers filter-operator
-  validation (`?filter[field][op]=value`). Do NOT flag hand-added Python filter
-  handling as an adopter defect.
+- **Core filter-operator codegen ships in Python — do NOT treat it as deferred.** The `routes`
+  generator emits an `APIRouter` whose list route parses the `?filter[field][op]=value` grammar
+  (all 9 operators `eq/ne/gt/gte/lt/lte/in/like/isNull`) via the generated `filter_parser` module,
+  validated against the generated filter allowlist (api-contract corpus, both lanes). **Flag a
+  hand-rolled filter parser as a finding.** Only the richer surface (`?search=`,
+  `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating) is TS-only — do NOT
+  flag its absence in Python.
 - **Partial relationship + flattened-object codegen.** Relationship navigation,
   non-`table` source kinds, and `field.object @storage: flattened` codegen are
   partially implemented in the Python port. Do NOT flag these gaps as adopter defects.

package/agent-context/skills/metaobjects-audit/references/typescript.md

@@ -106,7 +106,7 @@ via `metamodelVersion` (see the Phase 0 cross-language consistency item).
 
 TypeScript is the reference implementation — it ships the full feature set:
 
-- Filter-operator codegen: **complete** (`<Entity>FilterAllowlist`, 8 operators, all four CRUD routes validate against it).
+- Filter-operator codegen: **complete** — the core `?filter[field][op]` grammar (all 9 operators `eq/ne/gt/gte/lt/lte/in/like/isNull`, `<Entity>FilterAllowlist`) generates in every port; TS additionally ships the richer surface (`?search=`, `filter[or][N]` / `filter[and][N]` combinators, leading-wildcard gating).
 - Output-parser codegen: **complete** (`outputParser()` generator; `parse*`/`safeParse*`/`extract*` per `template.output`).
 - ObjectManager: **complete** (`@metaobjectsdev/runtime-ts`; `kyselyDriver` / `inMemoryDriver`).
 - Schema migrate / `meta verify --db`: **complete** (TS owns the shared migrate engine — ADR-0015).

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

@@ -198,18 +198,23 @@ name   package   extends   abstract   overlay   isArray   children   value
 | `field.string` | text | `@maxLength` drives `varchar(N)` |
 | `field.int` | 32-bit integer | |
 | `field.long` | 64-bit integer | |
-| `field.double` | float | |
+| `field.double` | double float | approximate; not for money |
+| `field.float` | single-precision float | native double/number (TS has no distinct float); DB `REAL`; not for money |
 | `field.boolean` | true/false | |
 | `field.date` | calendar date | ISO 8601 `YYYY-MM-DD` on the wire |
+| `field.time` | time-of-day | no calendar date; DB `TIME` |
 | `field.timestamp` | instant (tz-aware) | ISO 8601 with timezone on the wire; `@localTime: true` for a naive wall-clock value |
 | `field.decimal` | exact decimal | `@precision` / `@scale`; lossless money/quantity |
 | `field.currency` | integer minor units | see Currency below |
 | `field.enum` | string member | `@values` required; see Enum below |
 | `field.uuid` | UUID | canonical lowercase hex on the wire |
 | `field.object` | embedded value object | `@objectRef` + `@storage`; see below |
+| `field.map` | open-keyed map | one jsonb column; string keys; `@valueType` (scalar subtype) XOR `@objectRef` (value object); `isArray` does not apply |
 
 Common field attributes: `@required`, `@maxLength`, `@column` (physical column
-name), `@default`, `@filterable`, `@sortable`.
+name), `@default`, `@filterable`, `@sortable`. On temporal fields
+(`field.date`/`field.time`/`field.timestamp`) `@autoSet` stamps the value
+automatically — see the `@autoSet` callout under Timestamps below.
 
 ### Choosing the right shape — the general decision procedure (ADR-0037)
 
@@ -277,7 +282,7 @@ Canonical form for common field needs — reach for these before inventing anyth
 | IDs / unique keys / **any UUID column** | `field.uuid` | native UUID type. **NEVER `field.string` + `@dbColumnType: uuid`** — see the smell callout below |
 | Money | `field.currency` | integer minor units; never a float |
 | Closed set of symbols | `field.enum` | `@values` required |
-| Instant / event time (created/updated) | `field.timestamp` | instant / tz-aware by default (Postgres `timestamptz`; native `Instant`/`DateTimeOffset`/aware `datetime`) |
+| Instant / event time (created/updated) | `field.timestamp` + `@autoSet` | instant / tz-aware by default (Postgres `timestamptz`; native `Instant`/`DateTimeOffset`/aware `datetime`); `@autoSet: onCreate` for `createdAt`, `@autoSet: onUpdate` for `updatedAt` — never hand-stamp |
 | Naive wall-clock value (store-open time, birthday-with-time) | `field.timestamp` + `@localTime: true` | `timestamp without time zone` — opt out of zone-awareness only for a genuine wall-clock value |
 | A list of anything | `isArray: true` | on the base subtype (e.g. `field.string` + `isArray`) — there is **no** array `@dbColumnType` (retired) |
 | Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
@@ -322,6 +327,20 @@ lives in `field.timestamp` (instant by default) + the `@localTime` naive opt-out
 { "field.timestamp": { "name": "opensAt", "@localTime": true } }
 ```
 
+**`@autoSet` — let the runtime stamp created/updated times; never hand-set them.**
+`@autoSet` is registered on the temporal subtypes (`field.date` / `field.time` /
+`field.timestamp`) and takes **`onCreate`** (stamp on insert) or **`onUpdate`**
+(stamp on every write). This is the model-first way to express audit timestamps —
+declare it and the generated write path stamps the column, so you never hand-write
+`createdAt = now()` in application code (the exact hand-stamping anti-pattern). A
+`@required` field carrying `@autoSet: onCreate` is correctly *optional* on POST (the
+server supplies it).
+
+```json
+{ "field.timestamp": { "name": "createdAt", "@autoSet": "onCreate", "@required": true } }
+{ "field.timestamp": { "name": "updatedAt", "@autoSet": "onUpdate" } }
+```
+
 **String-shaped natives & validated strings (ADR-0036 Wave 3).** A URL/URI is its own
 native type with URL behavior → **`field.uri`** (subtype, step 2a), not a validated
 string. An IP address likewise → **`field.inet`**. An email or hostname is a *plain
@@ -539,30 +558,72 @@ at the same level as fields and identities.
 
 ## Relationships
 
-`relationship.composition` is the "this entity owns / aggregates instances of
-that entity" side; `identity.reference` (above) is the FK-column side. They are
-the two halves of one FK.
+A `relationship.*` child is the navigation / ownership side of a link to another
+entity; `identity.reference` (above) is the FK-column side. They are the two halves
+of one FK. **Choose the subtype by ownership semantics — it decides the default
+referential action**, so modeling every FK as `composition` silently arms unintended
+`CASCADE` deletes:
 
-| Attr | On | Values |
-|---|---|---|
-| `@objectRef` | composition | target entity name |
-| `@cardinality` | composition | `one` / `many` |
-| `@onDelete` / `@onUpdate` | `relationship.*` only | `cascade` / `set-null` / `restrict` / `no-action` |
+| Subtype | Ownership | Default `@onDelete` | Use when |
+|---|---|---|---|
+| `relationship.composition` | owns the target's lifecycle | `cascade` | children are owned and deleted with the parent |
+| `relationship.aggregation` | groups, does NOT own | `set-null` | children outlive the parent; delete nulls the FK |
+| `relationship.association` | plain reference, no ownership | `restrict` | you just point at an independent entity |
+
+Common attrs (on any subtype): `@objectRef` (target entity name / FQN),
+`@cardinality` (`one` / `many`), and `@onDelete` / `@onUpdate`
+(`cascade` / `set-null` / `restrict` / `no-action`). `@onDelete` defaults **per
+subtype** as in the table; `@onUpdate` defaults to `cascade` on every subtype.
 
 ```json
-{ "relationship.composition": {
-    "name": "posts", "@objectRef": "Post",
-    "@cardinality": "many", "@onDelete": "cascade" } }
+{ "relationship.composition": { "name": "posts",   "@objectRef": "Post", "@cardinality": "many" } }
+{ "relationship.aggregation": { "name": "members", "@objectRef": "User", "@cardinality": "many" } }
+{ "relationship.association": { "name": "author",  "@objectRef": "User", "@cardinality": "one" } }
 ```
 
-**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
-`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
-adopting an existing database (matching metadata to a live schema), omitting these
-makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
-`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+**Many-to-many (FR-018) — `@through` a junction entity.** Model an M:N link with
+`@cardinality: "many"` + `@objectRef` (the target) + **`@through`** (the junction
+entity). The junction MUST declare **two `identity.reference` children**, one per FK
+side; the relationship's FK fields are **derived** from those references — never
+restated. Two optional attrs handle self-joins:
+
+- `@sourceRefField` — names the source-side FK field on the junction, disambiguating a
+  **directed** self-join (e.g. `follows`, where both references point at `User`).
+- `@symmetric: true` — marks an **undirected** self-join (union-on-read). Valid only
+  when `@objectRef` is the declaring entity itself, and **mutually exclusive** with
+  `@sourceRefField`.
+
+(Any relationship subtype carries the M:N attrs; the conformance fixtures author them
+on `relationship.association`.)
 
 ```json
-{ "relationship.composition": { "name": "author", "@objectRef": "User",
+{ "relationship.association": {
+    "name": "tags", "@cardinality": "many",
+    "@objectRef": "Tag", "@through": "PostTag" } }
+```
+
+The `PostTag` junction supplies the FK direction via its two references:
+
+```json
+{ "object.entity": { "name": "PostTag", "children": [
+    { "field.long": { "name": "id" } },
+    { "field.long": { "name": "postId" } },
+    { "field.long": { "name": "tagId" } },
+    { "identity.primary":   { "name": "id", "@fields": "id" } },
+    { "identity.reference": { "name": "postRef", "@fields": "postId", "@references": "Post" } },
+    { "identity.reference": { "name": "tagRef",  "@fields": "tagId",  "@references": "Tag" } }
+] } }
+```
+
+**Adoption footgun — pin BOTH actions.** `@onDelete` defaults *per subtype* (above)
+and `@onUpdate` defaults to `cascade` — but a plain SQL foreign key is `NO ACTION` on
+both. If you're adopting an existing database (matching metadata to a live schema),
+leaving these implicit makes the metadata declare a referential action the DB doesn't
+have — a perpetual `verify --db` drift. Pin **both** explicitly to the DB's real
+behavior:
+
+```json
+{ "relationship.association": { "name": "author", "@objectRef": "User",
     "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
 ```
 
@@ -601,13 +662,17 @@ These are children of `object.entity`, alongside its fields and identities.
 | `storedProc` | yes | – |
 | `tableFunction` | yes | – |
 
-The physical name is `@table` (NOT `@name`). The physical column name on a field
-is `@column`. `@schema` namespaces the DB schema (Postgres default `public`;
-SQLite rejects non-default values). Multi-source: multiple `source.rdb` children,
-each with a `@role`, exactly one `primary`.
+The physical name attr is **kind-matched** — never `@name`: `@table` for a table,
+`@view` for a view, `@materializedView`, `@proc` (storedProc), `@function`
+(tableFunction). (`@table` on a non-table kind is a pre-1.0 legacy spelling the
+canonical serializer rewrites to the kind's alias; author the kind-matched attr
+directly.) The physical column name on a field is `@column`. `@schema` namespaces
+the DB schema (Postgres default `public`; SQLite rejects non-default values).
+Multi-source: multiple `source.rdb` children, each with a `@role`, exactly one
+`primary`.
 
 ```json
-{ "source.rdb": { "@kind": "view", "@table": "v_author", "@schema": "blog" } }
+{ "source.rdb": { "@kind": "view", "@view": "v_author", "@schema": "blog" } }
 ```
 
 **An entity's PRIMARY source must be writable** (`table`) — read-only kinds are
@@ -615,18 +680,83 @@ legal only in non-primary roles (e.g. table `primary` + view `replica` for
 read-through). A derived read model over a view/proc is an **`object.projection`**
 (FR-024): its fields `extends` entity fields (`extends: "Author.id"` — dotted
 child traversal, package only on the root segment) and/or carry `origin.*`
-children (`passthrough` / `aggregate` / `collection`) declaring assembly; its
-identity passes through via `extends` (`identity.primary: { name: id, extends:
-"Author.id" }`); it is read-only by construction and the declared field set IS
-the exposure (fail-closed). Give it a read-only `source.rdb` `@kind: view`
-child (`source.rdb: { kind: view, table: v_author }`) — codegen keys projection
-detection + view DDL off that read-only source, so without it `meta gen` emits
-nothing for the projection. **The `CREATE VIEW` body is generated from those
-`origin.*` children by the Node `meta migrate` — never hand-author view SQL for a
-shape origins can express** (an unmodeled view is *unmanaged*, so `meta verify --db`
-can't even catch the drift). Hand-write a view only when a construct origins can't
-express (recursive CTE, window function, set operation) blocks projection authoring,
-and keep that DDL in a hand-edited migration file.
+children (`passthrough` / `aggregate` / `collection` / `computed` / `first`)
+declaring assembly; its identity passes through via `extends` (`identity.primary:
+{ name: id, extends: "Author.id" }`); it is read-only by construction and the
+declared field set IS the exposure (fail-closed). Give it a read-only `source.rdb`
+`@kind: view` child (`source.rdb: { kind: view, view: v_author }`) — codegen keys
+projection detection + view DDL off that read-only source, so without it `meta gen`
+emits nothing for the projection.
+
+**Origin vocabulary (#195).** `origin.aggregate @agg` takes `count`/`sum`/`avg`/`min`/`max`
+(numeric reduces over `@of`), `any`/`all` (predicate quantifiers over a `@filter`; `@of`
+forbidden; empty set → `any=false`, `all=true`), and `collect` (an array rollup of `@of`
+into an `isArray` field, with optional `@distinct` / `@orderBy`). Any aggregate may be
+row-scoped with `@filter`. `origin.computed` carries a closed structured `@expr` tree (a
+derived scalar). `origin.first` picks one related row's column (`@of`) along `@via`,
+ordered by a **required `@orderBy`** (`["field:asc|desc", …]`, with the PK as tie-break) —
+the ordering is what makes `origin.first` express "latest / earliest X"; it may be
+row-scoped with `@filter` and is nullable. A field carrying any `origin.*` is derived ⇒
+read-only.
+
+`@expr` and `@filter` are **structured objects, not SQL strings** — guessing a string
+body fails the load:
+
+- **`@expr`** (on `origin.computed`) is a closed operation tree; a string body is a load
+  error (`ERR_BAD_ATTR_VALUE`):
+  ```json
+  { "origin.computed": { "@expr": { "op": "isNotNull", "arg": { "field": "payloadJson" } } } }
+  ```
+- **`@filter`** (on `origin.aggregate` / `origin.first`, and object-level on a projection)
+  is an `attr.filter` object — a field→predicate map. A bare value is `eq` shorthand; an
+  operator map spells the op:
+  ```json
+  { "origin.aggregate": { "@agg": "any", "@via": "Session.turns", "@filter": { "success": false } } }
+  { "@filter": { "status": { "ne": "archived" } } }
+  ```
+
+**Projection row-scope `@filter` (#207).** An object-level `@filter` on `object.projection`
+(the same `attr.filter` object shown above) scopes the WHOLE view's rows — it lowers to
+the view's outer `WHERE`. This is the metadata-managed way to author a soft-delete /
+status / type view without hand-writing SQL. It may reference **only declared,
+non-aggregate-derived** projection fields: naming an undeclared field fails the load
+(`ERR_BAD_ATTR_FILTER`), and so does naming a field whose value comes from an
+`origin.aggregate`.
+
+```json
+{ "object.projection": { "name": "ActiveOrders",
+    "@filter": { "status": { "ne": "archived" } }, "children": [ … ] } }
+```
+
+**The `CREATE VIEW` body is generated from those `origin.*` children by the Node
+`meta migrate` — never hand-author view SQL for a shape origins can express** (an unmodeled
+view is *unmanaged*, so `meta verify --db` can't even catch the drift). For a genuinely
+irreducible body (recursive CTE, window function, set operation) that origins can't express,
+carry it in the `source.rdb` **`@sql`** escape (#208, ADR-0043) — a hand-written body the
+tool registers, fingerprints, and drift-checks (adopt a pre-existing view with
+`meta migrate --allow adopt-view`) — rather than a hand-edited migration file where it goes
+accidentally unmanaged. For a DB object owned entirely elsewhere (Flyway), mark its source
+**`@unmanaged: true`** (view or table); migrate/verify then never touch it.
+
+**`@sql` fail-closed rules — an `@sql` body is a *second* source of truth, so the loader
+walls it off (#208).** Author an `@sql` source under these constraints or the load fails:
+
+- `@sql` is legal **only on a read-only `@kind`** (view / materializedView / storedProc /
+  tableFunction) — never on a writable `@kind: table` (`ERR_SQL_BODY_ON_WRITABLE_KIND`).
+- **No `origin.*`-bearing field may live under an `@sql` host** — the body already *is*
+  the derivation, so an origin alongside it is a double-declaration
+  (`ERR_ORIGIN_UNDER_SQL_BODY`). If you add an `@sql` body to a projection, **move its
+  derived fields out** (into plain declared fields the body computes) rather than keeping
+  their `origin.*` children.
+- The object-level `@filter` (#207) is **mutually exclusive with `@sql`** (same error) —
+  fold the predicate into the `@sql` body's own `WHERE`.
+- `@sql` and `@unmanaged` are **mutually exclusive** (`ERR_SQL_BODY_WITH_UNMANAGED`); an
+  empty/whitespace `@sql` is rejected (`ERR_BAD_ATTR_VALUE`).
+- Under **`@unmanaged`**, an `origin.*`-bearing field only **warns** (the marker acts on
+  nothing, so a documented-but-unacted-on lineage is benign) — the asymmetry with `@sql`
+  is deliberate.
+- Today `meta migrate` **lowers `@sql` only on `@kind: view`**; on matview / storedProc /
+  tableFunction it is registered but not yet migrate-managed (mark those `@unmanaged`).
 
 **A `passthrough` field must match its `@from` source's type.** A passthrough
 forwards the source value unchanged, so the projection field's `field.<subType>`
@@ -668,10 +798,12 @@ Resolution facts:
 
 - **Deferred.** `extends:` resolves *after all files load* — abstracts can live in
   any file, forward references are fine.
-- **Multi-level chains flatten** (`Author extends BaseEntity extends Auditable`).
+- **Multi-level chains resolve through the whole chain** (`Author extends BaseEntity
+  extends Auditable`) — each `extends` is a super-*reference*, so resolution walks the
+  full chain (it does not flatten inherited members onto the child; see ADR-0039 below).
 - **Cross-package** refs use the fully-qualified name (`extends: "shared::auditable"`);
   same-package refs use the bare name.
-- An unresolved reference fails with `ERR_UNKNOWN_EXTENDS`.
+- An unresolved reference fails with `ERR_UNRESOLVED_SUPER`.
 
 `abstract` and `extends` are **structural keys** (bare, no `@`).