From fb7c1df32e95383ae05b277cf120f83686d43ec1 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Wed, 24 Jun 2026 20:31:38 -0400 Subject: [PATCH 1/2] fix(agent-context): hedge the JVM startup-validator claim in verify skill (invariant vs binding) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Audit of the agent-context corpus (5 skill bodies + 16 reference fragments + README) for the issue #1 defect class — conflating a generic invariant with a project-specific binding, or guessing a binding — found it broadly clean: per-stack reference fragments correctly carry their own stack's binding without guessing a second one, LLM callers are explicitly bring-your-own, and the "schema/migrations are metadata-derived" framing is intact across all ports. One consistency fix: verify/SKILL.md asserted that on the JVM ports "a runtime startup validator catches generated-table drift at app boot" as a flat fact — but whether an adopter wires that validator is an opt-in project binding. migration.md already hedges the same capability ("can catch"); this aligns verify/SKILL.md to it: "can catch ... an optional complementary check (if your project wires one)". Regenerated the 4 cross-stack conformance fixtures (the skill body is installed for every stack). Conformance + byte-identity gates green. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky --- agent-context/skills/metaobjects-verify/SKILL.md | 6 +++--- .../expected/.claude/skills/metaobjects-verify/SKILL.md | 6 +++--- .../expected/.claude/skills/metaobjects-verify/SKILL.md | 6 +++--- .../expected/.claude/skills/metaobjects-verify/SKILL.md | 6 +++--- .../expected/.claude/skills/metaobjects-verify/SKILL.md | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/agent-context/skills/metaobjects-verify/SKILL.md b/agent-context/skills/metaobjects-verify/SKILL.md index 121d5e87d..05db139a7 100644 --- a/agent-context/skills/metaobjects-verify/SKILL.md +++ b/agent-context/skills/metaobjects-verify/SKILL.md @@ -37,9 +37,9 @@ can't drift by construction). - **`--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`. + 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`. - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result against the committed generated files; a non-empty diff means someone edited diff --git a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md index 121d5e87d..05db139a7 100644 --- a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md +++ b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md @@ -37,9 +37,9 @@ can't drift by construction). - **`--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`. + 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`. - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result against the committed generated files; a non-empty diff means someone edited diff --git a/fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/SKILL.md b/fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/SKILL.md index 121d5e87d..05db139a7 100644 --- a/fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/SKILL.md +++ b/fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-verify/SKILL.md @@ -37,9 +37,9 @@ can't drift by construction). - **`--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`. + 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`. - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result against the committed generated files; a non-empty diff means someone edited diff --git a/fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-verify/SKILL.md b/fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-verify/SKILL.md index 121d5e87d..05db139a7 100644 --- a/fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-verify/SKILL.md +++ b/fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-verify/SKILL.md @@ -37,9 +37,9 @@ can't drift by construction). - **`--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`. + 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`. - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result against the committed generated files; a non-empty diff means someone edited diff --git a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md index 121d5e87d..05db139a7 100644 --- a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md +++ b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-verify/SKILL.md @@ -37,9 +37,9 @@ can't drift by construction). - **`--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`. + 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`. - **`--codegen`** — regeneration drift. Re-runs generation and diffs the result against the committed generated files; a non-empty diff means someone edited From 5bd86d8bc4244fcd014d3b8e04ac686ec383cfa9 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Wed, 24 Jun 2026 20:41:09 -0400 Subject: [PATCH 2/2] no-mistakes(document): sync Java migration/drift docs to ADR-0015 validator removal --- README.md | 2 +- docs/features/migrations-and-drift.md | 10 +++++----- docs/ports/java.md | 14 +++++++------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 008d0ea9c..011897d3a 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ working code. | Templates + render (FR-004) | Yes | Yes | Yes (wraps Java) | Yes | Yes | | Payload-VO codegen | Yes (via projection) | – (consumers use `Map`) | Yes (`@Serializable`) | Yes | – (consumers use `dict`) | | Migration emission | `meta migrate` (Postgres / SQLite / D1) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | Via TS toolchain (`@metaobjectsdev/cli migrate`) | Via TS toolchain (ADR-0015) | Via TS toolchain (ADR-0015) | -| DB-drift verify | `meta verify --db` | Template-drift: `Renderer.verify`; startup: `MetaClassDBValidatorService` | Template-drift: `Renderer.verify`; startup: `MetadataStartupValidator` | `dotnet meta verify` (codegen-drift) | Schema-drift is TS-owned (ADR-0015) | +| DB-drift verify | `meta verify --db` | Template-drift: `Renderer.verify`; schema-drift is TS-owned (ADR-0015) | Template-drift: `Renderer.verify`; startup: `MetadataStartupValidator` | `dotnet meta verify` (codegen-drift) | Schema-drift is TS-owned (ADR-0015) | | Template-drift verify | Yes | Yes (`Renderer.verify`) | Yes (via Java) | Yes (`meta verify`) | Yes (`metaobjects.render.verify`) | | YAML authoring (sigil-free → JSON) | Yes | Yes | Yes (via Java) | Yes | Yes | | Runtime metadata (ObjectManager-style) | Yes (`runtime-ts`) | Yes (OMDB) | Yes (via Java OMDB + Exposed) | Roadmap | Yes (ObjectManager) | diff --git a/docs/features/migrations-and-drift.md b/docs/features/migrations-and-drift.md index ab014afe7..4b7e1b863 100644 --- a/docs/features/migrations-and-drift.md +++ b/docs/features/migrations-and-drift.md @@ -13,7 +13,7 @@ There are **7 drift sources**, and the toolchain has a guard for each. |---|---|---| | **Code-vs-DB** | Codegen — the generated SQL DDL is emitted from the same metadata as the entity / table code. | Build time | | **Code-vs-API-doc** | Cross-port codegen from the same metadata. | Build time | -| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. Java/Kotlin: runtime startup validator (`MetaClassDBValidatorService`) catches generated-table drift at app startup; the removed `meta:verify` Maven goal is not available. | CI on every PR (TS); app startup (Java/Kotlin) | +| **DB-vs-metadata** | `meta verify --db` (TS CLI) — introspects the live DB and fails if it has drifted from metadata. This is a schema concern owned by the Node toolchain regardless of server language; on the JVM ports the runtime auto-create/validator path was removed (ADR-0015) and the `meta:verify` Maven goal is not available. | CI on every PR | | **Migration-vs-metadata** | `meta migrate` (TS / C# / Python) emits migrations FROM metadata diffs — they cannot drift from metadata by construction. Java/Kotlin schema migrations are also owned by the TS toolchain (`@metaobjectsdev/cli migrate`). | Build time | | **Generated-edited** | `@generated` headers in emitted code + three-way merge that preserves hand-edits inside non-generated regions. | Code review | | **Prompt-vs-payload** | FR-004 `Renderer.verify` parses `{{...}}` references in templates and checks each one exists on the payload VO. | Build time + runtime | @@ -59,9 +59,9 @@ configured in `metaobjects.config.ts` (typically `./migrations/__