@metaobjectsdev/sdk 0.16.0 → 0.17.0-rc.1

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

@@ -8,6 +8,7 @@ provider/LLM-call layer; you compose the call yourself.
 ## Contents
 - Wire the generator
 - What it emits
+- The output-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Drift gate
@@ -52,6 +53,28 @@ 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.
 
+## The output-format prompt fragment (FR-010)
+
+For every json/xml-format `template.output`, `codegen-spring`'s
+`SpringOutputPromptGenerator` emits a `<TemplateShortName>OutputPrompt` class with a
+static `renderFormat()` / `renderFormat(PromptOverrides)` pair, backed by
+`OutputFormatRenderer` from the `metaobjects-render` module — the "produce your
+answer like this" fragment for the model. Wire it alongside
+`SpringOutputParserGenerator` in the Maven plugin's `<generators>` list:
+
+```xml
+<generator>
+  <classname>com.metaobjects.generator.spring.SpringOutputPromptGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/java</outputDir></args>
+</generator>
+```
+
+`@promptStyle` on the `template.output` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped
+for `template.prompt` nodes, non-json/xml `@format`, and unresolved `@payloadRef` —
+the same skip contract as the parser generator. The `SPEC`'s root name is the
+capitalized payload class name, agreeing with the parser's extract-codegen root.
+
 ## The three-step consumer pattern
 
 Render the prompt → call your LLM client (provider-agnostic; nothing is generated
@@ -87,9 +110,15 @@ NpcResponsePayload npc = NpcResponseParser.parse(response);   // the generated p
 Non-Spring JVM apps: **LangChain4j** (`ChatLanguageModel.generate(prompt)`) is the
 equivalent one-call seam.
 
-> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
-> today; the JVM port is planned (ADR-0024). Until then the call is your code and the
-> generated parser is the typed receive side.
+> The typed-trace **recorder** has shipped on this port too — `LlmTraceHelperGenerator`
+> emits a `record<Entity>(...)` helper (per concrete entity extending `LlmCallBase`
+> with a `@responseRef`-carrying `template.prompt`) that extracts the typed response,
+> builds the base trace row, and persists it via the OMDB `LlmCallRecorder` seam. What's
+> still TS-only is the **`call<Entity>` render→call→record convenience loop** — Java
+> intentionally does not emit it, because the `LlmClient` seam it wraps is BYO /
+> vendor-neutral here (ADR-0024). So you compose render → your LLM call → the
+> generated `record<Entity>(...)` yourself; the parser above is the standalone
+> receive side if you don't even want the recorder.
 
 ## Drift gate
 

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

@@ -10,6 +10,7 @@ the parser and the payload VO can't silently drift.
 ## Contents
 - Wire the generators
 - What it emits
+- The output-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Consumer dependency
 - Recommended LLM caller (bring-your-own)
@@ -62,6 +63,28 @@ null) and a `extractLenient(loader, text)` overload that delegates to the runtim
 components. The lenient mirror type (`<Name>Extracted`) uses nullable fields per
 the Kotlin null-safety port — a missing/malformed component is `null`, not a throw.
 
+## The output-format prompt fragment (FR-010)
+
+For every json/xml-format `template.output`, `codegen-kotlin`'s
+`KotlinOutputPromptGenerator` emits a `<TemplateShortName>OutputPrompt.kt` `object`
+with `renderFormat()` / `renderFormat(overrides: PromptOverrides)`, backed by
+`OutputFormatRenderer` from the `metaobjects-render` module — the "produce your
+answer like this" fragment for the model. Wire it alongside
+`KotlinOutputParserGenerator` in the Maven plugin's `<generators>` list:
+
+```xml
+<generator>
+  <classname>com.metaobjects.generator.kotlin.KotlinOutputPromptGenerator</classname>
+  <args><outputDir>${project.build.directory}/generated-sources/kotlin</outputDir></args>
+</generator>
+```
+
+`@promptStyle` on the `template.output` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped
+for `template.prompt` nodes, non-json/xml `@format`, and unresolved `@payloadRef` —
+the same skip contract as the parser generator. The `SPEC`'s root name is the
+capitalized payload class name, agreeing with the parser's extract-codegen root.
+
 ## The three-step consumer pattern
 
 Render the prompt → call your LLM client (provider-agnostic; nothing is generated
@@ -115,9 +138,16 @@ val npc = NpcResponseParser.parseNpcResponse(response)   // the generated parser
 (`ChatLanguageModel.generate(prompt)`) for non-Spring JVM — both provider-agnostic,
 both a one-call seam Kotlin uses idiomatically.
 
-> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
-> today; the JVM port is planned (ADR-0024). Until then the call is your code and the
-> generated parser is the typed receive side.
+> The typed-trace **recorder** has shipped on the JVM — `codegen-spring`'s
+> `LlmTraceHelperGenerator` emits a Java `record<Entity>(...)` helper (per concrete
+> entity extending `LlmCallBase` with a `@responseRef`-carrying `template.prompt`);
+> Kotlin code calls it directly (same JVM, same classpath) — there is no separate
+> Kotlin-native (`codegen-kotlin`/KotlinPoet) trace-helper emitter yet. What's TS-only
+> is the **`call<Entity>` render→call→record convenience loop** — neither JVM
+> generator emits it, because the `LlmClient` seam it wraps is BYO / vendor-neutral on
+> the JVM (ADR-0024). So you compose render → your LLM call → the generated Java
+> `record<Entity>(...)` yourself; the parser above is the standalone receive side if
+> you don't even want the recorder.
 
 ## Drift gate
 

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

@@ -10,6 +10,7 @@ drift.
 ## Contents
 - Wire the generators
 - What it emits
+- The output-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Consumer dependency
@@ -54,6 +55,24 @@ best-effort variant — `extract_lenient_<name>(text) -> ExtractionResult[<Name>
 per-field report rather than a raise. The lenient mirror (`<Name>PayloadExtracted`)
 uses `Optional[...]` fields — a missing/malformed component is `None`, not a raise.
 
+## The output-format prompt fragment (FR-010)
+
+For every json/xml-format `template.output`, the `output-prompt` generator (run via
+`metaobjects gen`) emits one `<template_name>_output_prompt.py` module exposing
+`render_<name>_format(overrides=None) -> str`, backed by the render engine's
+`render_output_format()` — the "produce your answer like this" fragment for the
+model:
+
+```bash
+metaobjects gen ./metadata --out ./generated --generators payload,output-prompt
+```
+
+`@promptStyle` on the `template.output` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation; guidance is never emitted as comments. Skipped
+for `template.prompt` nodes, non-json/xml `@format`, and unresolved `@payloadRef` —
+the same skip contract as the `output-parser` generator. The baked spec's root name
+is the payload class name, agreeing with the parser's `extract_<name>()` root.
+
 ## The three-step consumer pattern
 
 Render the prompt → call your LLM client (provider-agnostic; nothing is generated
@@ -96,9 +115,16 @@ to enforce the typed shape instead, **Instructor** or **Pydantic-AI** return a
 validated Pydantic model — but that overlaps MetaObjects' own typed `extract`, so pick
 one boundary, not both.
 
-> The typed-trace recorder + render→call→record convenience loop ship in TypeScript
-> today; the Python port is planned (ADR-0024). Until then the call is your code and
-> the generated parser is the typed receive side.
+> The typed-trace **recorder** has shipped on this port too — the `trace-helper`
+> generator emits a `record_<entity>(recorder, input, redact=None)` helper (per
+> concrete entity extending `LlmCallBase` with a `@responseRef`/`@payloadRef`-carrying
+> `template.prompt`) that tolerantly extracts the typed response, builds the base
+> trace row, and persists it once. What's still TS-only is the **`call<Entity>`
+> render→call→record convenience loop** — Python intentionally does not emit it,
+> because the `LlmClient` seam it wraps is BYO / vendor-neutral here (ADR-0024). So
+> you compose render → your LLM call → the generated `record_<entity>(...)` yourself;
+> the parser above is the standalone receive side if you don't even want the
+> recorder.
 
 ## Consumer dependency
 

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

@@ -9,6 +9,7 @@ call yourself.
 ## Contents
 - Wire the generator
 - What it emits
+- The output-format prompt fragment (FR-010)
 - The three-step consumer pattern
 - Recommended LLM caller (bring-your-own)
 - Drift gate
@@ -66,7 +67,7 @@ The dual API mirrors Zod's idiomatic shape: `parse*` throws a `ZodError`,
 structurally identical to the `promptRender()` payload VO, so you can pass values
 between the render and parse sides interchangeably.
 
-Field-type → Zod mapping: `field.string` → `z.string()`; `field.int`/`long`/`short`/`byte`
+Field-type → Zod mapping: `field.string` → `z.string()`; `field.int`/`long`
 → `z.number().int()`; `field.double`/`float` → `z.number()`; `field.boolean` →
 `z.boolean()`; `field.object` (with `@objectRef`) → a nested `z.object({...})`;
 `isArray: true` → wrapped in `z.array(...)`. Any subtype outside this scalar set —
@@ -75,6 +76,38 @@ including `field.enum` — falls through to `z.unknown()` in the strict
 in the entity insert/update schemas, not in this output parser; the lenient extract
 path carries the enum-as-string handling).
 
+## The output-format prompt fragment (FR-010)
+
+For every json/xml-format `template.output`, the `outputPrompt()` generator (same
+import path, `@metaobjectsdev/codegen-ts/generators`) emits a
+`<TemplateName>.prompt.ts` exporting `render<TemplateName>Format(overrides?)` —
+backed by the render engine's `renderOutputFormat()`. This is the "produce your
+answer like this" fragment you splice into the prompt text so the model returns the
+shape the parser above expects:
+
+```ts
+// metaobjects.config.ts
+import { entityFile, queriesFile, barrel, promptRender, outputParser, outputPrompt }
+  from "@metaobjectsdev/codegen-ts/generators";
+
+export default defineConfig({
+  outDir: "src/generated",
+  generators: [
+    entityFile(), queriesFile(), barrel(),
+    promptRender(), outputParser(), outputPrompt(),
+  ],
+});
+```
+
+`@promptStyle` on the `template.output` (`guide` default / `inline` / `exampleOnly`)
+controls the fragment's presentation: `guide` is a prose field list + example
+skeleton, `inline` is one skeleton with inline placeholders/enum choices,
+`exampleOnly` is just the filled skeleton. Guidance is never emitted as comments —
+models ignore them. Skipped for non-json/xml `@format` outputs and for any output
+whose `@payloadRef` doesn't resolve to a value-object — the same skip contract as
+`outputParser()`. The baked spec's root name matches the payload class name, so the
+fragment and the parser's `extract()` agree on the same root.
+
 ## The three-step consumer pattern
 
 Render the prompt → call your LLM client (provider-agnostic; nothing is generated

package/agent-context/skills/metaobjects-runtime-ui/SKILL.md

@@ -76,7 +76,7 @@ a field → HTTP 400.
 | `in`, `like` | yes | `in` only | – |
 | `gt`, `gte`, `lt`, `lte` | – | yes | – |
 
-These eight (`eq` `ne` `gt` `gte` `lt` `lte` `in` `like` `isNull`) are the whole
+These nine (`eq` `ne` `gt` `gte` `lt` `lte` `in` `like` `isNull`) are the whole
 closed set — every port implements these and only these.
 
 ### Sort + pagination

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

@@ -0,0 +1,90 @@
+# C# server runtime
+
+The C# runtime tier **is the generated EF Core stack itself** — there is no separate
+`ObjectManager` engine to wire. `EntityGenerator` + `DbContextGenerator` emit
+`<Entity>.g.cs` classes plus one `AppDbContext.g.cs` that ARE the persistence layer (EF
+Core), and `RoutesGenerator` emits ASP.NET minimal-API routes that mount on your
+`WebApplication`. Unlike the other ports, C# leaves **no repository seam** — the generated
+code is what runs. Schema is TS-owned (ADR-0015); EF Core is pure data-access at runtime.
+
+## The generated persistence layer
+
+`dotnet meta gen` emits an entity POCO per `object.entity` / projection and a single
+`AppDbContext` with a `DbSet<T>` per entity (naively pluralized) plus an `OnModelCreating`
+that carries the mapping:
+
+```csharp
+// generated AppDbContext.g.cs
+public class AppDbContext : DbContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
+
+    public DbSet<Author> Authors { get; set; } = default!;
+
+    protected override void OnModelCreating(ModelBuilder b)
+    {
+        // .HasConversion<string>() (enums), .OwnsOne(...).ToJson(...) / .OwnsMany(...).ToJson(...)
+        // (jsonb object fields), .HasPrecision(p,s) (decimals), .ToView("v_...") (projections),
+        // .HasDiscriminator(...).HasValue<Sub>(...) (TPH single-table).
+    }
+}
+```
+
+## Query + persist with EF Core
+
+Register the generated context against your provider, then query/write with plain LINQ +
+`SaveChangesAsync` — the generated entities and `AppDbContext` are ordinary EF Core:
+
+```csharp
+builder.Services.AddDbContext<AppDbContext>(o => o.UseNpgsql(connString));
+// ...
+var authors = await db.Authors.AsNoTracking()
+    .Where(a => a.Name == "Ada").ToListAsync();
+
+db.Authors.Add(new Author { Name = "Ada" });
+await db.SaveChangesAsync();   // server-generated PK round-trips back onto the entity
+```
+
+## Return-type contract
+
+The EF Core query path materializes **native in-process CLR types**, never wire strings
+(ADR-0019), verified by the port's runtime-return-type test:
+
+- `field.decimal` → `decimal` — exact, **lossless end-to-end**, no float round-tripping.
+- `field.long` → `long`; other scalars to their native CLR types.
+- a default `field.timestamp` (instant) → `DateTimeOffset` over a `timestamptz` column; a
+  naive `@localTime:true` timestamp → `DateTime` — native temporals, not strings.
+- an untyped `@dbColumnType:jsonb` open-JSON column → a `System.Text.Json.JsonDocument` (the
+  parsed value, not raw text); a **typed** `field.object @storage:jsonb` (with `@objectRef`)
+  materializes the generated value-object class via `OwnsOne`/`OwnsMany(...).ToJson(...)`.
+
+Wire canonicalization (currency → integer minor units, temporals → ISO-8601, UUID →
+canonical hex) happens only when a row leaves over HTTP — at the serialization boundary in
+the generated routes — never inside the EF Core query path. Currency is integer minor units
+on the wire and in storage (a native `long` in-process); the server never formats —
+formatting is client-side in the universal (TS/Angular) web client.
+
+## Serving the REST contract
+
+`RoutesGenerator` emits `<Entity>Routes.g.cs` — full CRUD per writable entity
+(`source.rdb @kind="table"`), read-only list/get for a projection/view, and a collection-GET
+for a composite-/no-PK entity — with a `Map<Entity>Routes(this IEndpointRouteBuilder,
+string prefix = "/api")` extension, on the
+cross-port REST contract (five CRUD endpoints, `?filter[field][op]=`, `?sort=field:asc`,
+`?limit`/`?offset`, `?withCount=1` envelope, 400/404 envelopes). A TPH `@discriminator`
+base emits polymorphic `GET /<base>(+/{id})` plus a per-subtype CRUD set at
+`/<base>/<discriminatorValue lowercased>` (create injects the discriminator, cross-subtype
+get/update/delete → 404). Wire it after registering the context:
+
+```csharp
+var app = builder.Build();
+app.MapAuthorRoutes("/api");   // the generated extension; you pass the prefix at mount time (default "/api")
+app.Run();
+```
+
+Filter operators (`eq` `ne` `gt` `gte` `lt` `lte` `in` `like` `isNull`) ship via the
+per-entity `<Entity>FilterAllowlist` (from `FilterAllowlistGenerator`); the generated list
+handler calls the `FilterParser` / `EfCoreFilterDispatch` runtime helpers in
+`MetaObjects.Codegen`, so your ASP.NET host references that assembly at runtime. The same
+universal TS/Angular web client consumes those routes unchanged — the wire format matches
+the Java, Kotlin, and Python backends byte-for-byte.

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

@@ -0,0 +1,94 @@
+# Python server runtime
+
+The Python runtime tier is the **`metaobjects.runtime.ObjectManager`** — a
+metadata-driven query/CRUD engine that reads the same metadata at runtime and drives
+persistence with no per-entity ORM boilerplate. It is the cross-port analog of Java's
+OMDB: a method-based API (`find_by_id` / `find_many` / `count` / `create` / `update` /
+`delete` / `relate`) that compiles a Filter dict to parameterized SQL and runs it via a
+pluggable driver. It is **pure data-access** (CRUD / query / codec); schema is owned by
+the Node `meta` migration tool, not the runtime.
+
+## Construct an `ObjectManager`
+
+`ObjectManager(root, driver)` takes a loaded metadata `root` plus a `PostgresDriver`
+wrapping any DB-API 2 connection (pg8000 / psycopg):
+
+```python
+import pg8000
+from metaobjects import load_directory
+from metaobjects.runtime import ObjectManager, PostgresDriver
+
+result = load_directory("metaobjects")     # same canonical JSON every port reads
+conn = pg8000.connect(...)                 # any DB-API 2 connection
+om = ObjectManager(result.root, PostgresDriver(conn))
+```
+
+## CRUD + query
+
+Rows come back as **plain dicts keyed by metadata field name**, values native (see
+below). Write calls take a field-keyed dict of values in their native authoring forms;
+the write codec coerces each to the native Python type the driver binds:
+
+```python
+# Create — returns the inserted row (incl. any server-generated PK) via RETURNING
+author = om.create("Author", {"name": "Ada"})
+
+# Read
+one  = om.find_by_id("Author", author["id"])
+rows = om.find_many("Author", {"name": {"like": "Ada%"}},
+                    sort=[("createdAt", "desc")], limit=25, offset=0)
+n    = om.count("Author", {"name": {"eq": "Ada"}})
+
+# Update (partial, by PK) / Delete
+om.update("Author", author["id"], {"name": "Ada Lovelace"})   # None if no row matched
+om.delete("Author", author["id"])                             # bool
+```
+
+`create()` stamps `@autoSet` timestamps (`createdAt` / `updatedAt`) with a shared `now()`,
+**overriding** any caller-supplied value, and `update()` strips `onCreate`-only columns. For
+a data import/restore that must preserve original timestamps, use `insert_preserving()` (#203).
+
+The Filter dict is `{field: value}` (equality shortcut), `{field: {op: value}}` (typed
+ops), or `{"and": [filter, ...]}` (combinator). The operator set is the closed cross-port
+nine — `eq` `ne` `gt` `gte` `lt` `lte` `in` `like` `isNull`. `relate()` traverses an M:N
+relationship from a source record to its related rows (hetero / directed / symmetric
+self-joins), resolved generically from the junction's `identity.reference` children.
+
+## Return-type contract
+
+`ObjectManager` returns **native in-process Python types**, never wire strings (ADR-0019),
+verified by the port's runtime-return-type test:
+
+- `field.decimal` → `decimal.Decimal` — exact, **lossless end-to-end**, never via float.
+- temporal fields → native `datetime` / `date` / `time`.
+- `field.object` / jsonb → a native `dict` (pg8000 decodes jsonb).
+- `field.uuid` → `uuid.UUID`; `field.currency` → a native `int` (integer minor units).
+
+Wire canonicalization (currency → integer minor units, temporals → ISO-8601, UUID →
+canonical hex) happens only at the serialization boundary, never inside the query path.
+Compute with `Decimal` in-process; let the encoding layer emit the wire form. Currency is
+integer minor units on the wire; the runtime never formats — formatting is client-side in
+the universal (TS/Angular) web client. (Port-specific note: because pg8000 returns a plain
+`int` for both INTEGER and BIGINT, `ObjectManager` exposes each query's per-column Postgres
+OIDs via `last_column_oids` so the **canonical serializer** — the persistence-conformance
+boundary — can apply the cross-port BIGINT→string rule. The generated FastAPI router serves
+`field.long` as a JSON number, and the row *values* always stay native.)
+
+## Serving the REST contract
+
+The `routes` generator (run via `metaobjects gen`) emits a **FastAPI `APIRouter`** per
+writable entity (`source.rdb @kind="table"`) on the cross-port REST contract (five CRUD
+endpoints, `?filter[field][op]=`, `?sort=field:asc`, `?limit`/`?offset`, `?withCount=1`
+envelope, 400/404 envelopes). Each router declares a repository **`Protocol`** you
+implement and inject via FastAPI's `app.dependency_overrides` — back it with
+`ObjectManager`, or your own SQLAlchemy Core / asyncpg code. There is **no** generated
+`main.py`; create one and mount the routers (`app.include_router(...)`). The same
+universal TS/Angular web client consumes those routes unchanged.
+
+Two shape notes (do **not** hand-edit generated files around them): the generated router
+assumes a **single-field** PK (a composite PK takes `@fields[0]`), and the PK's type is
+**derived from its field subtype** — a `field.uuid` PK binds `uuid.UUID` on the route and
+Protocol, not `int`. The PATCH body is typed `dict[str, Any]` **deliberately**: the generated
+`<Entity>Create` / `<Entity>Patch` Pydantic models already validate constraints over HTTP
+(FR-036), and the `dict` seam preserves the FR-035 present-key PATCH tristate (absent ≠
+explicit-null) — retyping the PATCH parameter to the model would collapse that tristate.

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

@@ -19,10 +19,21 @@ metadata that should define it. The ones a developer must actively guard:
 - **DB-vs-metadata** — the live database schema has diverged from the metadata
   (a column the metadata no longer declares, a missing index, a type mismatch). A
   **modeled projection's** view body is compared too — a changed `CREATE VIEW` emits
-  a `replace-view`. But a **hand-authored, unmodeled view is *unmanaged*** (reported
-  as informational, never failed, never dropped), so a hand-written view standing in
-  for an expressible `object.projection` is the one drift class `verify --db` can't
-  catch — the `metaobjects-audit` skill is the only gate that sees it.
+  a `replace-view`. For a genuinely irreducible view body (recursive CTE, window
+  function, set operation) that `origin.*` can't express, use the `source.rdb`
+  `@sql` escape: a hand-written body the tool still registers, fingerprints, and
+  drift-checks — emitted verbatim instead of synthesized (adopt a pre-existing
+  hand-written view once with `meta migrate --allow adopt-view`). For a DB object
+  — view **or table** — owned entirely elsewhere (Flyway, a hand-migration,
+  another app's schema), mark it `@unmanaged: true`; `meta migrate` never
+  touches it and `verify --db` reports it as *external (declared)* rather than
+  silently. `@sql` and `@unmanaged` are mutually exclusive on one source. But a
+  hand-authored view carrying **neither** marker is *unmanaged by omission*
+  (reported as informational, never failed, never dropped) — so an **undeclared**
+  hand-written view standing in for an expressible `object.projection` is the one
+  drift class `verify --db` can't catch; the `metaobjects-audit` skill is the only
+  gate that sees it. See `references/migration.md` → "DDL-ownership escape
+  valves (`@sql` / `@unmanaged`) — #208" for the full contract.
 - **Generated-vs-metadata (codegen)** — committed generated code no longer matches
   what the current metadata would emit (someone edited a `@generated` file, or
   forgot to regenerate after changing metadata).
@@ -49,16 +60,24 @@ it and call the generated query/field instead of keeping the hand-rolled version
 This is the most common way a build ends up *declaring* a projection yet still
 hand-aggregating in a route — verify catches exactly that.
 
+**A bare `verify` is a partial check, not the full gate.** The Node/C# default runs
+only `--templates`; Java/Python's bare default runs only `--codegen` — either way,
+paired with the advisory anti-pattern pass above, never all three subverbs. Treat a
+bare run as a smoke test: the real done-check is running the subverbs your project
+uses explicitly — `verify --codegen`, and, where a DB exists, `verify --db <url>`.
+
 ## The `verify` subverbs
 
 `verify` has three drift checks. Run them in CI.
 
 - **`--db`** — schema drift. Introspects the live database and fails if it has
   diverged from metadata. This is a **schema concern, so it is the Node toolchain's
-  job regardless of your server language** (see migrations below). On the JVM ports
-  a runtime startup validator *can* catch generated-table drift at app boot as an
-  optional complementary check (if your project wires one), but the authoritative
-  DB-vs-metadata gate is the Node `verify --db`.
+  job regardless of your server language** (see migrations below). The JVM ports
+  have no schema surface of their own — ADR-0015 Decision 2 removed the old
+  dev/test auto-create validator (OMDB is pure data-access) — so a JVM, Python, or
+  C# project's dev/test databases are provisioned the same way production is: by
+  applying the Node-emitted SQL. The Node `verify --db` is the only DB-vs-metadata
+  gate, for every port.
 
 - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result
   against the committed generated files; a non-empty diff means someone edited
@@ -70,6 +89,20 @@ hand-aggregating in a route — verify catches exactly that.
   if any reference isn't on the payload VO. This is the build-time gate for the
   prompt-construction pillar.
 
+**Only `--db` is Node-universal.** `--codegen` / `--templates` run through each
+port's own build tool, not the Node `meta`:
+
+| Port | Codegen drift | Template drift | Schema drift |
+|---|---|---|---|
+| TS | `meta verify --codegen` | `meta verify --templates` | `meta verify --db <url>` |
+| Java / Kotlin | `mvn metaobjects:verify -Dmeta.verify.mode=codegen` | `mvn metaobjects:verify -Dmeta.verify.mode=templates` | Node `meta verify --db` only |
+| C# | `dotnet meta verify --codegen` | `dotnet meta verify --templates` | Node `meta verify --db` only |
+| Python | `metaobjects verify --codegen` | `metaobjects verify --templates` | Node `meta verify --db` only |
+
+Every non-TS port's `verify` rejects `--db` outright (exit 2, "schema verify is the
+migrate engine") — schema drift always runs through the Node `meta verify --db`,
+per the shared-migration-engine doctrine below.
+
 A clean run is silent; a failure names the entity/template, the drifted artifact,
 and (for templates) the missing reference. **Bias toward trusting the tool** — a
 verify failure almost always means the metadata changed and a derived artifact
@@ -121,9 +154,11 @@ What this means in practice:
 
 - Dialects: `postgres` (default), `sqlite`, and `d1` (Cloudflare D1, TS-only).
 - The JVM and Python ports have **no** migration command of their own — their
-  former migrate goals/modules were removed. A JVM service may auto-create
-  dev/test tables at startup for convenience, but production schema is always the
-  Node migrate engine's output.
+  former migrate goals/modules were removed, and (ADR-0015 Decision 2) the JVM
+  runtime's own dev/test schema auto-create path
+  (`MetaClassDBValidatorService` + the drivers' DDL) was removed too: OMDB is
+  pure data-access. Every port's schema — dev, test, and production alike — is
+  always the Node migrate engine's output.
 
 So even in a Java or Python or C# project, schema migration and `verify --db` run
 through the Node `meta` tool. The per-port `gen`/codegen tooling stays native to
@@ -136,9 +171,9 @@ database by hand** — no `psql`/console `ALTER TABLE` / `CREATE` / `DROP`, not
 to patch a mismatch, not to "just unblock" a boot. It is the single most common way a database ends up
 in a state no migration can reproduce:
 
-- The column now exists but no migration recorded it, so the next `meta migrate` (or a JVM app's
-  boot-time migrator) tries to add it again and dies on `column ... already exists` — or worse,
-  silently diverges and the drift only surfaces days later.
+- The column now exists but no migration recorded it, so the next `meta migrate` tries to add it
+  again and dies on `column ... already exists` — or worse, silently diverges and the drift only
+  surfaces days later.
 - "I'll just add it real quick so I can see it in the tool" is the exact rationalization to catch. It
   doesn't *feel* like a schema change, so it skips the metadata-first check — but it is one.
 
@@ -159,7 +194,7 @@ render, persistence, API-contract, verify). When a test or conformance fixture
 fails:
 
 - A **loader** failure cites an `ERR_*` code (e.g. `ERR_RESERVED_ATTR`,
-  `ERR_UNKNOWN_EXTENDS`, `ERR_MISSING_REQUIRED_ATTR`, `ERR_BAD_ATTR_VALUE`,
+  `ERR_UNRESOLVED_SUPER`, `ERR_MISSING_REQUIRED_ATTR`, `ERR_BAD_ATTR_VALUE`,
   `ERR_YAML_COERCION`) — fix the metadata, not the loader.
 - A **render/verify** failure means the rendered bytes or the template-drift
   result diverged from the pinned expectation — usually a payload/text mismatch.

package/agent-context/skills/metaobjects-verify/references/migration.md

@@ -4,9 +4,11 @@ Schema migration is owned by **one shared TypeScript engine** regardless of your
 server language (ADR-0015). The Node `meta` CLI (`@metaobjectsdev/cli`, on top of
 `@metaobjectsdev/migrate-ts`) is the migration + live-DB-drift toolchain for **TS,
 Java, Kotlin, C#, and Python alike**. The non-TS ports have **no** migration command
-of their own — their former migrate goals/modules were removed. A JVM service may
-auto-create dev/test tables at startup for convenience, but production schema is
-always the Node migrate engine's output.
+of their own — their former migrate goals/modules were removed, and (ADR-0015
+Decision 2) the JVM runtime's own dev/test schema auto-create path
+(`MetaClassDBValidatorService` + the drivers' DDL) was removed too: OMDB is pure
+data-access. Every port's schema — dev, test, and production alike — is always the
+Node migrate engine's output.
 
 So even in a Java / Python / C# / Kotlin project you run `meta migrate` and
 `meta verify --db` through Node. Only schema crosses to Node; per-port `gen`/codegen
@@ -78,8 +80,9 @@ next-step hint pointing to the exact `baseline` command.
    a ledger table:
 
    ```bash
-   meta migrate --db postgresql://... --apply       # run pending up.sql
-   meta migrate --db postgresql://... --rollback     # run down.sql for the last migration
+   meta migrate --db postgresql://... --apply                # run pending up.sql
+   meta migrate --db postgresql://... --rollback <target>     # run down.sql for migrations newer than <target>
+   meta migrate --db postgresql://... --rollback ""           # roll back everything (empty target)
    ```
 
 ## Dialects
@@ -95,9 +98,9 @@ next-step hint pointing to the exact `baseline` command.
 `meta verify --db` introspects the live database and fails if its schema has
 diverged from the metadata (a column the metadata no longer declares, a missing
 index, a type mismatch). This is the **authoritative** DB-vs-metadata gate for every
-port — wire it into CI. On the JVM ports a runtime startup validator can catch
-generated-table drift at app boot as a complementary check, but the gate that owns
-DB drift is the Node `meta verify --db`.
+port — wire it into CI. The JVM ports have no runtime schema-validation surface of
+their own (ADR-0015 Decision 2 removed it); the Node `meta verify --db` is the only
+gate that owns DB drift, for every port.
 
 A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
@@ -129,8 +132,10 @@ A non-unique recency index is `index.lookup`:
 
 The `@where` / `@using` / `@expr` / `@orders` attributes are **index** physical
 escapes on `identity.secondary` / `index.lookup` — they are NOT a raw-SQL escape
-hatch for views. There is no attribute that injects hand-written SQL into a
-projection view body (by design — see below).
+hatch for views. For a genuinely-irreducible view body, use the `source.rdb`
+**`@sql`** escape (a tool-managed, opaque hand-written body — see the
+"DDL-ownership escape valves" section below); for a DB object owned entirely by
+Flyway / a hand-migration, use **`@unmanaged`**.
 
 ## Projection views (generated view DDL)
 
@@ -151,10 +156,58 @@ canonical view-SQL emitter shared with drift detection.
   `metaobjects-audit` skill, not here.
 
 **Do not hand-author view SQL for a shape origins can express** — model it as a
-projection so the view DDL is generated and drift-checked. The only case for
-hand-written view DDL is a genuinely irreducible view (recursive CTE, window
-function, set operation) that origins can't express; carry that in a hand-edited
-migration file.
+projection so the view DDL is generated and drift-checked. For a genuinely
+irreducible view (recursive CTE, window function, set operation) that origins
+can't express, use the `@sql` escape below rather than a hand-edited migration
+file — that keeps the view tool-managed (emitted, fingerprinted, drift-checked)
+instead of accidentally unmanaged.
+
+## DDL-ownership escape valves (`@sql` / `@unmanaged`) — #208
+
+Two mutually-exclusive `source.rdb` attributes express *who owns a DB object's
+DDL* (ADR-0043). They are the escape from "a projection's view is always
+synthesized from its `origin.*` children."
+
+**`@sql`** — a hand-written view body the tool **registers, fingerprints, and
+drift-checks but never authors or parses**. The value is the body *inside*
+`CREATE VIEW <name> AS …` (not the `CREATE` wrapper, not the name). Legal only on
+a read-only kind; v1 migrate lowers it on `@kind: view` only (matview/proc → a
+hard error, deferred). Authored sigil-free in YAML as a block scalar:
+
+```yaml
+object.projection:
+  name: OrgTree
+  children:
+    - source.rdb:
+        kind: view
+        view: v_org_tree
+        sql: |
+          WITH RECURSIVE t AS (
+            SELECT id, parent_id FROM org WHERE parent_id IS NULL
+            UNION ALL SELECT o.id, o.parent_id FROM org o JOIN t ON o.parent_id = t.id)
+          SELECT * FROM t
+    - field.long: { name: id, extends: Org.id }
+    - identity.primary: { extends: Org.pk }
+```
+
+The `extends`-bound identity/fields declare the read model's shape and row
+identity *without* triggering wrong synthesis (the suppression rule). The view is
+emitted verbatim with a fingerprint COMMENT stamp; a second `meta migrate` is a
+no-op. **Adopting a pre-existing hand-written view** at that name: the first diff
+reports `replace-view` **blocked** (an unstamped view is indistinguishable from
+someone else's SQL) — run **`meta migrate --allow adopt-view`** once to stamp it,
+then it converges. `@sql` **forbids** `origin.*` children and a `@filter` on the
+same host (two sources of truth → load error).
+
+**`@unmanaged: true`** — this DB object (a view **or a table**) is managed
+elsewhere (Flyway / a hand-migration owns its DDL). `meta migrate` never creates,
+drops, or drift-checks it; `meta verify --db` reports it as *external (declared)*.
+Legal on any `@kind`, including `table` (the Flyway-owned-entity case). An FK from
+a managed table into an `@unmanaged` table resolves its physical name, but the
+external object must exist before that FK is applied (a documented ordering caveat,
+not enforced).
+
+`@sql` and `@unmanaged` are **mutually exclusive** on one source.
 
 ## Adopting an existing database (non-destructive)