metaobjects 0.9.0__py3-none-any.whl

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/references/java.md

@@ -0,0 +1,96 @@
+# Java server runtime
+
+The Java runtime tier is **OMDB** (`metaobjects-omdb`) —
+`com.metaobjects.manager.db.ObjectManagerDB`, a metadata-driven persistence engine
+on modernized JDBC + Spring-tx. It reads the same metadata at runtime and drives
+CRUD with no per-entity ORM boilerplate. OMDB is pure data-access (CRUD / query /
+codec / transactions); schema is owned by the Node `meta` migration tool, not OMDB.
+
+## Construct an `ObjectManagerDB`
+
+`ObjectManagerDB` has a no-arg constructor. Set its `DataSource` (and a
+`DatabaseDriver` for the dialect), then call `init()`:
+
+```java
+import com.metaobjects.manager.db.ObjectManagerDB;
+import com.metaobjects.manager.db.ObjectConnection;
+import com.metaobjects.manager.db.driver.PostgresDriver;
+import com.metaobjects.object.MetaObject;
+import com.metaobjects.object.ValueObject;
+
+import javax.sql.DataSource;
+import java.util.Collection;
+
+ObjectManagerDB om = new ObjectManagerDB();
+om.setDatabaseDriver(new PostgresDriver());
+om.setDataSource(/* javax.sql.DataSource */);
+om.init();
+```
+
+## CRUD + query
+
+Every CRUD/query call takes an `ObjectConnection` obtained from
+`om.getConnection()`; release it with `om.releaseConnection(oc)` when done. Objects
+are `ValueObject` instances created from a `MetaObject` (look the `MetaObject` up by
+its fully-qualified name on the loader's registry).
+
+```java
+ObjectConnection oc = om.getConnection();
+try {
+    MetaObject mo = registry.findMetaObjectByName("acme::blog::Author");
+
+    // Create
+    ValueObject author = (ValueObject) mo.newInstance();
+    author.setString("name", "Ada");
+    om.createObject(oc, author);
+
+    // Load (refresh an object's state by its identity)
+    om.loadObject(oc, author);
+
+    // Update
+    author.setString("name", "Ada Lovelace");
+    om.updateObject(oc, author);
+
+    // Query — all rows of the MetaObject
+    Collection<?> all = om.getObjects(oc, mo);
+
+    // Delete
+    om.deleteObject(oc, author);
+} finally {
+    om.releaseConnection(oc);
+}
+```
+
+`getObjects` also has a filtered overload `om.getObjects(oc, mo, queryOptions)`
+taking a `QueryOptions` (built from an `Expression`). `ValueObject` is the
+map-backed runtime carrier.
+
+## Spring wiring
+
+`metaobjects-core-spring` (or the Spring Boot starter) declares an
+`ObjectManagerDB` bean from the Spring `DataSource` and enrolls it in Spring-managed
+transactions — annotate your service methods `@Transactional` and OMDB participates.
+Inject the bean into your services rather than constructing it by hand.
+
+## Return-type contract
+
+OMDB returns **native in-process Java types**, never wire strings:
+
+- `field.decimal` → `java.math.BigDecimal` — exact, **lossless end-to-end**, no
+  float round-tripping.
+- temporal fields → native date/instant types.
+- `field.object` (jsonb) → a native `Map`.
+
+Wire canonicalization (currency → integer minor units as `Long`, temporals →
+ISO-8601, UUID → canonical hex) happens only when a row leaves over HTTP — at the
+serialization boundary in your Spring controllers — never inside the OMDB query
+path. Compute with `BigDecimal` in-process; let the HTTP layer encode.
+
+## Serving the REST contract
+
+`codegen-spring`'s `SpringControllerGenerator` emits `<Entity>Controller.java` per
+writable entity, on the cross-port REST contract (five CRUD endpoints, `?sort`,
+`?limit`/`?offset`, `?withCount=1` envelope, 404/400 envelopes). The generated
+`<Entity>Repository.java` is a stubbed interface you implement against OMDB (or any
+persistence layer) — wire the controller to call it. The same universal TS/Angular
+web client consumes those controllers unchanged.

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/references/kotlin.md

@@ -0,0 +1,99 @@
+# Kotlin server runtime
+
+The Kotlin port runtime is **generated Exposed `Table` objects plus your own
+JetBrains Exposed transactions** — there is no Kotlin-specific persistence engine.
+`KotlinExposedTableGenerator` emits one `<Entity>Table.kt` per entity with a
+`source.rdb`; you hand-write the (trivial) transaction bodies, since the table
+column definitions and the `@Serializable` entity data class are both generated
+from the same metadata.
+
+(If you want a fully metadata-driven engine instead of hand-written Exposed, the
+Java **OMDB** runtime — `metaobjects-omdb`, `ObjectManagerDB` — is on the JVM and
+callable from Kotlin; see the Java runtime reference. OMDB is pure data-access:
+CRUD / query / codec / transactions. Schema is owned by the Node `meta` migration
+tool, not the runtime.)
+
+## The generated table
+
+For an `Author` entity, `KotlinEntityGenerator` + `KotlinExposedTableGenerator`
+emit a data class and an Exposed `Table`:
+
+```kotlin
+// generated/acme/blog/Author.kt
+@Serializable
+data class Author(
+    val id: Long,
+    val name: String,
+    val bio: String? = null,
+)
+
+// generated/acme/blog/AuthorTable.kt
+object AuthorTable : Table("authors") {
+    val id   = long("id").autoIncrement()
+    val name = varchar("name", 200)
+    val bio  = varchar("bio", 2000).nullable()
+    override val primaryKey = PrimaryKey(id)
+}
+```
+
+## Query + persist with Exposed
+
+Obtain a `Database` (the generated `MetadataExposedConfig` `@Configuration` calls
+`Database.connect(...)` for you, or do it yourself), then wrap reads/writes in
+`transaction(db) { ... }`:
+
+```kotlin
+import org.jetbrains.exposed.sql.Database
+import org.jetbrains.exposed.sql.selectAll
+import org.jetbrains.exposed.sql.insert
+import org.jetbrains.exposed.sql.transactions.transaction
+
+@Service
+class AuthorService(private val db: Database) {
+    fun list(): List<Author> = transaction(db) {
+        AuthorTable.selectAll().map {
+            Author(
+                id   = it[AuthorTable.id],
+                name = it[AuthorTable.name],
+                bio  = it[AuthorTable.bio],
+            )
+        }
+    }
+
+    fun create(name: String, bio: String? = null): Long = transaction(db) {
+        AuthorTable.insert {
+            it[AuthorTable.name] = name
+            it[AuthorTable.bio]  = bio
+        } get AuthorTable.id
+    }
+}
+```
+
+Filtered reads use Exposed's `selectAll()` plus a `where { ... }` op tree (e.g.
+`AuthorTable.selectAll().where { AuthorTable.name eq someName }`), exactly as the
+`integration-tests-kotlin` query-conformance runner does against Testcontainers
+Postgres.
+
+## Return-type contract
+
+An Exposed read yields **native in-process Kotlin/JVM types** at the column, never
+wire strings — this is verified by the port's runtime-return-type test:
+
+- `field.decimal` (NUMERIC) → `java.math.BigDecimal` — exact, lossless, no float
+  round-tripping.
+- `field.long` → `Long`; other scalars to their native Kotlin types.
+- a `timestamp`-with-tz field → `java.time.Instant` (the metaobjects
+  `instantWithTimeZone` `Column<Instant>` path — native temporal, not a String).
+
+Wire canonicalization (currency → integer minor units as `Long`, temporals →
+ISO-8601, UUID → canonical hex) happens only when a row leaves over HTTP — at the
+serialization boundary in your Spring controller — never inside the query path.
+Compute with `BigDecimal`/`Instant` in-process; let the HTTP layer encode.
+
+## Serving the REST contract
+
+`KotlinSpringControllerGenerator` emits `<Entity>Controller.kt` per writable entity
+(`source.rdb` `@kind="table"`) as a Spring `@RestController` on the cross-port REST
+contract (five CRUD endpoints, `?sort`, `?limit`/`?offset`, `?withCount=1`
+envelope). The same universal TS/Angular web client consumes those controllers
+unchanged — the wire format matches the C# and Java backends byte-for-byte.

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/references/react.md

@@ -0,0 +1,86 @@
+# React web client
+
+`@metaobjectsdev/react` is the browser-side React runtime. It is **universal** — it
+consumes any backend (TS / Java / Kotlin / C# / Python) that speaks the cross-port
+REST contract, not just a TS server. It pairs with the `codegen-ts-react`
+`formFile()` generator, which emits `<Entity>.form.tsx` files that import from this
+package.
+
+## Install
+
+```bash
+npm install @metaobjectsdev/react @metaobjectsdev/runtime-web
+npm install --save-dev @metaobjectsdev/codegen-ts-react
+```
+
+`@metaobjectsdev/react` peer-deps on `react`, `react-hook-form`,
+`@hookform/resolvers`, and `zod`.
+
+## Key exports
+
+| Export | Purpose |
+|---|---|
+| `useEntityForm(Entity, InsertSchema)` | React Hook Form bound to a generated Zod insert schema; returns the full `UseFormReturn<T>` plus a `.input.<field>` accessor |
+| `<CurrencyInput>` | controlled bidirectional money input — strips symbol/grouping on focus, re-formats on blur, emits integer minor units (cents) to `onChange` |
+
+## Generated forms (`formFile()`)
+
+Wire `formFile()` in `metaobjects.config.ts` and `meta gen` emits a
+`<Entity>.form.tsx` per entity. The form spreads `.input.<field>` onto each
+control; every metadata-derived attribute (placeholder, type, aria-label, RHF
+validation rule) rides along automatically:
+
+```ts
+// metaobjects.config.ts
+import { defineConfig } from "@metaobjectsdev/cli";
+import { entityFile, queriesFile, barrel } from "@metaobjectsdev/codegen-ts/generators";
+import { formFile } from "@metaobjectsdev/codegen-ts-react";
+
+export default defineConfig({
+  outDir: "src/generated",
+  apiPrefix: "/api",
+  generators: [entityFile(), queriesFile(), barrel(), formFile()],
+});
+```
+
+```tsx
+// generated/Author.form.tsx (consumer's view)
+import { useEntityForm } from "@metaobjectsdev/react";
+import { Author, AuthorInsertSchema } from "./Author";
+
+export function AuthorForm({ onSubmit }: { onSubmit: (v: AuthorInsert) => void }) {
+  const form = useEntityForm(Author, AuthorInsertSchema);
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <input {...form.input.name} />
+      <textarea {...form.input.bio} />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+Validation runs through `zodResolver` against the generated `AuthorInsertSchema`.
+`handleSubmit`, `formState`, `setValue`, etc. are all available since the hook
+returns the full RHF surface.
+
+## Currency input
+
+`field.currency` stores + transmits integer minor units; the browser formats.
+`<CurrencyInput>` keeps editing native (cents in, cents out); `formatCurrency`
+(from `@metaobjectsdev/runtime-web`) is the display side.
+
+```tsx
+import { formatCurrency } from "@metaobjectsdev/runtime-web";
+import { CurrencyInput } from "@metaobjectsdev/react";
+
+formatCurrency(1599, "USD", "en-US");   // "$15.99"
+<CurrencyInput value={1599} onChange={setCents} currency="USD" locale="en-US" />
+```
+
+## Talking to the backend
+
+React forms submit through whatever data layer you wire. For list/query + mutation
+hooks against the REST contract, add the TanStack client
+(`@metaobjectsdev/tanstack` + `codegen-ts-tanstack`) — see `tanstack.md`. Both sit
+on the single `EntityFetcher` seam your app supplies at its root.

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/references/tanstack.md

@@ -0,0 +1,119 @@
+# TanStack web client
+
+`@metaobjectsdev/tanstack` is the browser-side TanStack runtime — TanStack Query
+hooks + a TanStack Table grid component. Like the React client it is **universal**:
+it consumes any backend (TS / Java / Kotlin / C# / Python) that speaks the
+cross-port REST contract. It pairs with `codegen-ts-tanstack`, which emits
+`<Entity>.hooks.ts` and `<Entity>.columns.tsx` that import from this package.
+
+## Contents
+- Install
+- Key exports
+- The `EntityFetcher` contract
+- Generated hooks (`tanstackQuery()`)
+- Generated grid (`tanstackGrid()`)
+- Cell renderer overrides
+
+## Install
+
+```bash
+npm install @metaobjectsdev/tanstack @metaobjectsdev/runtime-web
+npm install --save-dev @metaobjectsdev/codegen-ts-tanstack
+```
+
+Peer-deps: `@tanstack/react-query`, `@tanstack/react-table`.
+
+## Key exports
+
+| Export | Purpose |
+|---|---|
+| `<EntityFetcherProvider value={fetcher}>` | supplies the single `EntityFetcher` every generated hook reads |
+| `useEntityFetcher()` | reads the fetcher from context (generated hooks call this) |
+| `<EntityGrid>` | opinionated TanStack Table component |
+| `<CellRendererProvider>` + `defaultCellRenderers` | renderer overrides keyed by the column's `meta.view` |
+
+## The `EntityFetcher` contract
+
+The client never calls `fetch` directly. Every generated hook delegates to one
+fetcher you supply once at the app root:
+
+```ts
+// from @metaobjectsdev/runtime-web
+export type EntityFetcher = <T>(path: string, init?: RequestInit) => Promise<T>;
+```
+
+```tsx
+import { EntityFetcherProvider } from "@metaobjectsdev/tanstack";
+
+const fetcher = async <T,>(path: string, init?: RequestInit): Promise<T> => {
+  const res = await fetch(path, {
+    ...init,
+    credentials: "include",
+    headers: { "Content-Type": "application/json", ...(init?.headers ?? {}) },
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status} on ${path}`);   // hooks rely on the throw
+  return res.status === 204 ? (undefined as T) : ((await res.json()) as T);
+};
+
+export function App() {
+  return (
+    <EntityFetcherProvider value={fetcher}>
+      <AuthorList />
+    </EntityFetcherProvider>
+  );
+}
+```
+
+The fetcher resolves `path` (always starting with `apiPrefix`) to a full URL,
+attaches auth per your policy, parses JSON, and **throws on non-2xx** — the hooks
+depend on the throw for error state.
+
+## Generated hooks (`tanstackQuery()`)
+
+Emits `<Entity>.hooks.ts` — 5 hooks for a writable entity (2 for read-only
+projections):
+
+| Hook | Verb / Path |
+|---|---|
+| `useAuthor(id)` | `GET /api/author/:id` |
+| `useAuthors(filter?)` | `GET /api/author?filter[..]=..&sort=..&limit=N&offset=N` |
+| `useCreateAuthor()` | `POST /api/author` |
+| `useUpdateAuthor()` | `PATCH /api/author/:id` |
+| `useDeleteAuthor()` | `DELETE /api/author/:id` |
+
+Query hooks return `UseQueryResult`; mutation hooks return `UseMutationResult` and
+invalidate the entity's query keys so lists re-fetch after writes.
+
+## Generated grid (`tanstackGrid()`)
+
+Emits `<Entity>.columns.tsx` from the entity's `layout.dataGrid` child — TanStack
+`ColumnDef<T>[]`, each carrying `meta.view` for the renderer registry. Render with
+`<EntityGrid>`:
+
+```tsx
+import { useAuthors } from "./generated/Author.hooks";
+import { authorColumns } from "./generated/Author.columns";
+import { EntityGrid } from "@metaobjectsdev/tanstack";
+
+const { data } = useAuthors({ sort: "name:asc", limit: 25, offset: 0, withCount: 1 });
+<EntityGrid columns={authorColumns} data={data?.rows ?? []} rowCount={data?.total ?? 0} />
+```
+
+`tanstackGridHook()` (optional) wraps the sorting/pagination/filter state plumbing
+into a `useAuthorGrid()` so the consumer renders `<EntityGrid {...useAuthorGrid()} />`.
+
+## Cell renderer overrides
+
+`<EntityGrid>` routes rendering through `CellRendererProvider`, keyed by `meta.view`
+(`text` / `number` / `date` / `boolean` / `currency` / `dropdown` / …). Override a
+key without touching generated code; per-column `cell` always wins, the provider
+fills in otherwise.
+
+```tsx
+import { CellRendererProvider } from "@metaobjectsdev/tanstack";
+import { formatCurrency } from "@metaobjectsdev/runtime-web";
+
+<CellRendererProvider value={{ currency: (ctx) => formatCurrency(ctx.getValue() as number, "EUR", "fr-FR") }}>
+  <EntityGrid {...gridProps} />
+</CellRendererProvider>
+```

metaobjects/agent_context/_content/skills/metaobjects-runtime-ui/references/typescript.md

@@ -0,0 +1,92 @@
+# TypeScript server runtime
+
+The Node-side runtime tier is `@metaobjectsdev/runtime-ts`. It supplies both the
+helpers the generated routes lean on (`parseFilterParams`) and a metadata-driven
+`ObjectManager` for full-runtime CRUD / validation / relationship traversal.
+
+## Two ways to persist
+
+**1. Generated query helpers (the common path).** `queriesFile()` emits a
+`<Entity>.queries.ts` per entity with typed CRUD. Per ADR-0008 every generated
+helper takes the Drizzle/Kysely `db` as its **first parameter** — no module-level
+`db` singleton:
+
+```ts
+import { findAuthorById, createAuthor, listAuthors } from "./generated/Author.queries";
+
+const author = await findAuthorById(db, 42);            // db passed, not imported
+const created = await createAuthor(db, { name: "Ada" });
+const page = await listAuthors(db, { limit: 25 });
+```
+
+You own the connection lifecycle and thread `db` through every call — that keeps
+the code testable and lets one process talk to multiple databases.
+
+**2. The `ObjectManager` runtime (dynamic CRUD / admin UIs / MCP tools).** Drives
+behavior directly off loaded metadata, no per-entity generated file needed:
+
+```ts
+import { MetaDataLoader } from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { ObjectManager } from "@metaobjectsdev/runtime-ts";
+import { kyselyDriver } from "@metaobjectsdev/runtime-ts/drivers";
+
+const { root } = await new MetaDataLoader().load([
+  new FileSource("metaobjects/meta.blog.json"),
+]);
+
+const om = new ObjectManager({
+  metadata: root,
+  driver: kyselyDriver({ db: kyselyInstance, dialect: "postgres" }),
+});
+
+const post  = await om.create("Post", { title: "Hello", authorId: 1 });
+const found = await om.findById("Post", post.id, { include: ["author"] });
+const list  = await om.findMany("Post", { authorId: 1 }, { limit: 10 });
+await om.update("Post", post.id, { title: "Updated" });
+await om.delete("Post", post.id);
+
+const result = om.validate("Post", { title: "x" });      // pure, no DB hit
+if (!result.ok) console.log(result.errors);
+
+await om.transaction(async (tx) => { /* ... */ });
+```
+
+### Drivers
+
+- `kyselyDriver({ db, dialect })` — real DBs (SQLite/libsql/Turso, Postgres via
+  `pg` / Neon). You provide the Kysely instance.
+- `inMemoryDriver({ seed?, pkFields? })` — Map-backed; unit tests, prototyping, MCP
+  sandboxing.
+
+`findMany` filters take a Mongo-style object: `{ field: value }` (eq),
+`{ field: null }` (IS NULL), `{ field: [a, b] }` (IN), or explicit operators
+`{ field: { $gte, $like, $in, ... } }`.
+
+> Driver note: generated CRUD uses Kysely's `.returning()`. Works on libsql/Turso,
+> `node-postgres`, `@neondatabase/serverless`; NOT on `better-sqlite3` / `bun:sqlite`
+> (no native RETURNING) — use a custom driver or `inMemoryDriver` there.
+
+## Return-type contract
+
+The runtime returns **native in-process types**, never wire strings — temporal
+fields as native dates, jsonb as native objects. The one documented TS outlier:
+`field.decimal` comes back as a **`string`** (JS has no native exact decimal),
+preserving precision. Wire canonicalization (currency → integer minor units,
+temporals → ISO-8601, UUID → canonical hex) is applied only at the HTTP
+serialization boundary, never inside the query path.
+
+## Serving the REST contract
+
+`routesFile()` (Fastify) or `routesFileHono()` (Hono/Workers/edge) emits CRUD
+routes on the cross-port contract. Mount them with the `db` injected:
+
+```ts
+import { registerAuthorRoutes } from "./generated/Author.routes";
+registerAuthorRoutes(app, { db });   // GET/POST/PATCH/PUT/DELETE under apiPrefix
+```
+
+The routes call `parseFilterParams` (from `@metaobjectsdev/runtime-ts/drizzle-fastify`)
+to validate `?filter[..][..]=..&sort=..&limit=&offset=` against the generated
+`<Entity>FilterAllowlist` / `<Entity>SortAllowlist`, returning HTTP 400 on an
+unknown field or disallowed operator.

metaobjects/agent_context/_content/skills/metaobjects-verify/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: metaobjects-verify
+description: Use when verifying MetaObjects: drift checks (verify --db/--codegen/--templates), schema migrations, and interpreting conformance/test failures.
+---
+
+# MetaObjects verify + migrations
+
+The third pillar: **drift detection.** MetaObjects treats metadata as the source of
+truth and generated code + DB schema + prompts as derived. `verify` is the
+cross-cutting discipline that catches divergence; schema migration is the build-time
+pipeline that brings the database into line with metadata. This skill is the
+procedure for running both and reading the failures.
+
+## The drift sources
+
+Drift is any place where a derived artifact has fallen out of sync with the
+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).
+- **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).
+- **Prompt-vs-payload (templates)** — a template references a `{{field}}` that
+  isn't on its `@payloadRef` payload VO (a renamed source field silently degrading
+  a prompt).
+
+Two more are caught structurally rather than by a command: **generated-edited**
+(the `@generated` header + three-way merge surface hand-edits at code review) and
+**migration-vs-metadata** (migrations are emitted *from* metadata diffs, so they
+can't drift by construction).
+
+## 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 catches generated-table drift at app boot as a
+  complementary check, but the authoritative DB-vs-metadata gate is the Node
+  `verify --db`.
+
+- **`--codegen`** — regeneration drift. Re-runs generation and diffs the result
+  against the committed generated files; a non-empty diff means someone edited
+  generated code or skipped a regen. Wire it into CI so a stale `@generated` file
+  fails the build.
+
+- **`--templates`** — prompt/payload drift. For every `template.prompt` /
+  `template.output`, resolves the text, parses each `{{...}}` reference, and fails
+  if any reference isn't on the payload VO. This is the build-time gate for the
+  prompt-construction pillar.
+
+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
+didn't follow.
+
+## Schema migrations are the shared TypeScript engine — for every port
+
+This is the load-bearing architectural fact (ADR-0015): **schema migrations are
+owned by one shared TypeScript engine, regardless of your server language.** The
+Node `meta migrate` and `meta verify --db` are the migration + live-DB-drift
+toolchain for TS, Java, Kotlin, C#, and Python alike.
+
+What this means in practice:
+
+- The Node `meta` CLI emits the migration SQL (diffing metadata → DDL) and applies
+  it. You point it at the same database your server connects to:
+
+  ```
+  meta migrate --db postgresql://... --slug initial   # emit migration SQL
+  meta migrate --db postgresql://... --apply          # apply pending migrations
+  meta migrate --dry-run                              # preview without writing
+  ```
+
+- 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.
+
+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
+the language; only schema crosses to Node.
+
+## Interpreting conformance / test failures
+
+MetaObjects' behavior is pinned by cross-port **conformance corpora** (metamodel,
+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_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.
+- A **persistence / API-contract** failure means a query result row or an HTTP
+  response shape diverged from the cross-port expectation — treat a deviation as a
+  bug in the code under test, not in the corpus.
+
+The corpus is the contract: when output disagrees with a fixture, the output is
+what's wrong.
+
+---
+
+For the migration tooling read `references/migration.md`.

metaobjects/agent_context/_content/skills/metaobjects-verify/references/migration.md

@@ -0,0 +1,72 @@
+# Schema migrations — the shared TypeScript engine (every port)
+
+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.
+
+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
+stays native to the language.
+
+## Install (Node, dev-only)
+
+```bash
+npm install --save-dev @metaobjectsdev/cli @metaobjectsdev/migrate-ts
+```
+
+You point the tool at the **same database your server connects to** — its
+connection is independent of your runtime tier.
+
+## The workflow
+
+1. **Generate a migration** by diffing metadata vs the prior state (the live DB or a
+   committed snapshot). The engine emits paired `up.sql` + `down.sql`:
+
+   ```bash
+   meta migrate --db postgresql://...               # emit up.sql + down.sql
+   meta migrate --db postgresql://... --slug initial # name the migration
+   meta migrate --dry-run                            # preview without writing
+   ```
+
+2. **Review the SQL.** Read the emitted `up.sql` (forward) and `down.sql`
+   (rollback) before applying. Destructive changes (drop column / drop table) are
+   opt-in — the engine blocks them unless explicitly allowed, and routes ambiguous
+   rename-vs-drop+add decisions through a prompt rather than guessing.
+
+3. **Apply** the pending migrations against the DB; migration history is tracked in
+   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
+   ```
+
+## Dialects
+
+- `postgres` (default) — native `ALTER`s.
+- `sqlite` (libsql / Turso) — native `ALTER`s where supported (≥ 3.35), bundling
+  recreate-and-copy per table when a change needs it.
+- `d1` (Cloudflare D1) — **TS-only**; targets D1 via the wrangler CLI, writes
+  Wrangler's native `migrations/<seq>_<slug>.sql` layout. Pass `--dialect d1`.
+
+## Live-DB drift: `meta verify --db`
+
+`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`.
+
+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
+DB didn't follow.
+
+## Not yet shipped
+
+Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+migrations (column-type changes needing data transformation error out with a hint).