fix(verify,codegen): gate the schema snapshot (#292), agree on CHECK names (#293)

#292 -- THE SNAPSHOT WAS THE ONE FILE NOTHING CHECKED

  `meta migrate` diffs metadata against .metaobjects/migrations/.schema.<dialect>.json
  by default, so that file decides what DDL the next migration contains. `verify --db`
  compared the live database against the METADATA and never against it. A snapshot gone
  stale -- an interrupted migrate, a rollback, a bad merge -- passed clean, and the next
  `migrate --slug` emitted DDL that failed at apply.

  Reproduced end to end on a real Postgres before and after: drop a column from the
  snapshot, verify says `schema in sync`, migrate emits ADD COLUMN, apply gives
  `column "notes" of relation "contact" already exists`. An adopter had already been
  bitten and carried a manual workaround in its traps list.

  THE CHECK IS CONDITIONED ON metadata==DB, and that is the whole design. The snapshot
  advances at GENERATION time, so between `migrate --slug` and applying it the snapshot
  legitimately leads the database; there the metadata drift is non-empty and this stays
  silent. When metadata and the DB agree, nothing pending explains a difference.

  The first design keyed on the migration LEDGER instead, and the integration harness
  killed it: that harness applies its SQL directly, so there are no ledger rows, so every
  migration reads as pending and the gate would have silently never fired. Real projects
  apply out of band too (psql, a CI step). A gate that cannot fire is the defect being
  fixed, wearing a different hat.

#293 -- TWO EMITTERS, TWO CONVENTIONS, NOTHING COMPARING THEM

  `check("chk_order_items_status")` in the generated table versus
  `ADD CONSTRAINT "order_items_status_chk"` in the migration. The name in the source
  never matched the name in the database.

  CODEGEN CHANGED, NOT MIGRATE. Migrate's suffix form is systematic across five
  constraint kinds and those names are already in live databases -- flipping migrate
  would emit DROP/ADD CONSTRAINT churn against production for a cosmetic fix. Codegen's
  prefix was two lines landing in regenerated source.

  Gated by a test that renders BOTH emitters from one model and asserts they agree,
  reading codegen's side off disk so it pins what an adopter receives. Each side was
  internally consistent and separately tested, which is how the split survived.

@Verifiedby -- A NAME IN A COMMENT NO LONGER COUNTS AS EVIDENCE

  Auditing a real 19-name ledger found four claims that did not verify what they were
  attached to; one matched a `// via mountCrudRoutes(...)` note that was its only
  occurrence anywhere. Comment-only matches now emit WARN_REQUIREMENT_TEST_COMMENT_ONLY.

  WHOLE-LINE, not strip-to-EOL: a test titled with a URL contains `//`, and truncating
  there would turn a real match into a confident false error -- the failure this scan
  exists to avoid. Pinned by a test. `#` counts only in Python, where it is a comment.

  The docs now say plainly that @Verifiedby is existence evidence, not proof. The other
  three audited failures are semantic and no lexical rule reaches them, which is what
  FR-038 addresses: generate the test FROM the requirement so there is no name for an
  author to pick. Roadmap gains rows for FR-038 and FR-037 (whose row was missing).

Full local CI green (18/18) after regenerating the advanced-modeling example, whose
committed output pins a check name -- the golden lives outside the package suite.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,79 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — `verify` gates the committed schema snapshot, which nothing checked (npm) — [#292](https://github.com/metaobjectsdev/metaobjects/issues/292)
+
+`meta migrate` diffs metadata against `.metaobjects/migrations/.schema.<dialect>.json` by default
+(`--from-db` is the documented opt-out), so **that file decides what DDL the next migration
+contains** — and nothing in the toolchain verified it. `meta verify --db` compares the live database
+against the *metadata* and never against the snapshot.
+
+A snapshot gone stale — an interrupted migrate, a rollback, a bad merge resolution — passed `verify`
+clean, and the next `migrate --slug` then emitted DDL that failed at apply. Reproduced end to end on
+a real Postgres: drop a column from the snapshot, `verify --db` still reports `schema in sync`,
+`migrate` emits `ALTER TABLE "contact" ADD COLUMN "notes" TEXT`, and applying it gives
+`column "notes" of relation "contact" already exists`. **The toolchain had everything it needed to
+know the snapshot was wrong and reported healthy.** An adopter had already been bitten and carried a
+manual "diff the snapshot after any migration-adjacent rollback" note in its traps list.
+
+`verify --db` now compares the committed snapshot against the live database and fails when they
+disagree, naming the differences and how to re-derive it.
+
+**The check is conditioned on metadata==DB, and that is what makes it false-positive-free.** The
+snapshot advances at migration-GENERATION time, so between `migrate --slug` and applying that
+migration it legitimately leads the database; in exactly that window the metadata↔DB drift is
+non-empty and this check stays silent. When metadata and the database agree there is no pending work
+left to explain a difference, so a snapshot that disagrees is stale.
+
+Keying on the drift result rather than on the migration **ledger** is deliberate. A ledger-based
+"are there unapplied migrations?" test looks equivalent and is not: a project that applies its
+migrations out of band — `psql`, a CI step, another tool — has no ledger rows at all, so every
+migration reads as pending and the gate would silently never fire. That is the same class of defect
+as the one being fixed, and the integration harness (which applies its SQL directly) surfaced it
+before the design shipped. Fails open when no snapshot exists or it cannot be parsed; d1 is
+unaffected (its migrations stay Wrangler-native).
+
+### Fixed — codegen and migrate named the same CHECK constraint two different ways (npm) — [#293](https://github.com/metaobjectsdev/metaobjects/issues/293)
+
+For one `field.enum`, the generated Drizzle table emitted `check("chk_order_items_status", …)` while
+the migration emitted `ADD CONSTRAINT "order_items_status_chk"` — prefix versus suffix, same
+metadata, same version, same dialect. So the constraint name in the generated source never matched
+the one in the database: a `DROP CONSTRAINT` written from the generated name fails, a Postgres error
+quotes a name that appears nowhere in the source anyone would grep, and any reconciliation between
+the two (drizzle-kit introspect/push, a schema diff run as a sanity check) reports a difference that
+is not real.
+
+**Codegen changed, not migrate**, and the direction is not arbitrary: migrate's suffix form is
+systematic across five constraint kinds (`_numeric_chk`, `_length_chk`, `_regex_chk`, `_cmp_chk`,
+`_chk`) and **those names are already in live databases**, so flipping migrate would emit DROP/ADD
+CONSTRAINT churn against production for a cosmetic fix. Codegen's prefix was two lines of one file,
+landing in regenerated source where changing it costs nothing.
+
+Gated by a new test that renders both emitters from the same metadata and asserts the names match —
+reading codegen's side off disk rather than from an internal, so it asserts the text an adopter
+receives. Nothing compared the two before; each was internally consistent and separately tested,
+which is exactly how the divergence survived.
+
+### Fixed — a `@verifiedBy` name found only in a comment now warns instead of passing (npm)
+
+`checkVerifiedBy` matches a name anywhere in the test corpus as a whole word, so **a name occurring
+only inside a comment satisfied it.** Auditing a real 19-name ledger found four claims that did not
+verify what they were attached to, one of them matching a `// via mountCrudRoutes(...)` note that was
+its single occurrence in the entire corpus. A comment-only match now emits
+`WARN_REQUIREMENT_TEST_COMMENT_ONLY`, naming the file and line.
+
+A **whole-line** comment test, deliberately, rather than stripping to end-of-line: a test titled with
+a URL contains `//`, and truncating there would turn a real match into a confident false error — the
+failure this scan exists to avoid. A trailing comment after code therefore still counts as code,
+which under-flags, matching the repo's standing bias for drift checks. `#` is treated as a comment
+only in Python files, where it is one.
+
+`docs/features/requirements.md` now states the boundary plainly: **`@verifiedBy` is existence
+evidence, not proof.** The other three audited failures — a dependency-injection key, a real test of
+a different claim, and a test of the entry's output where the claim was about its source text — are
+semantic, and no lexical rule reaches them. Inverting the relationship so the test is *generated
+from* the requirement is specified as **FR-038**.
+
 ## [0.23.0] — npm `0.23.0` · PyPI `0.23.0` · NuGet `0.23.0` · Maven `7.23.0`
 
 A coordinated **MINOR** across all four registries, cut as MINOR because it adds registered

docs/features/requirements.md

@@ -149,6 +149,19 @@ entry.
 `@verifiedBy` names tests: `verify` checks each exists and is not skipped. It never runs
 them. `@trackedBy` names issues or tickets and is **not** resolved — `verify` has no network.
 
+> **`@verifiedBy` is existence evidence, not proof — and the difference matters most to whoever
+> authored it.** The scan matches a name anywhere in the test corpus, as a whole word, in any
+> language; that generosity is deliberate (a "missing" verdict then means the name appears in no
+> test file at all, which is broken in any ecosystem) but it means the check **cannot tell whether
+> the named test verifies the claim.** Auditing a real 19-name ledger found four that did not: one
+> matched a **comment**, one a **dependency-injection key** in test setup, one a **real test of a
+> different claim**, and one a test of the entry's *output* where the claim was about its *source
+> text*. `verify` reported clean throughout. A comment-only match now warns
+> (`WARN_REQUIREMENT_TEST_COMMENT_ONLY`); the other three are semantic and no scan will ever reach
+> them. **After authoring `@verifiedBy`, open each named test and read what it asserts.** If the
+> claim has no test, write one rather than pointing at a name that happens to exist — a property
+> about source text (no forbidden identifier, no unbounded call) is testable by reading the file.
+
 **Every run prints a summary**, clean or not:
 
 ```

docs/superpowers/specs/2026-08-15-fr-038-requirement-derived-test-stubs-design.md

@@ -0,0 +1,145 @@
+# FR-038 — Requirement-derived test stubs: invert `@verifiedBy` so the link cannot be faked
+
+**Status:** proposed · **Date:** 2026-08-15 · **Depends on:** the `requirement.*` family (0.22.0,
+0.23.0) · **Supersedes nothing** — `@verifiedBy` stays, with a narrowed role (§7).
+
+## 1. The problem, measured
+
+`@verifiedBy` asks the author to name a test that proves a requirement. `meta verify` then checks
+the name appears somewhere in the test corpus. **The author chooses the string, so the cheapest way
+to satisfy the check is to find any name that already exists** — and an agent optimising against a
+gate will take the cheapest satisfying move every time.
+
+Auditing one real adopter ledger (55 entries, 9 carrying `@verifiedBy`, **19 names**) by opening
+each named test and reading its assertions found **4 of 19 did not verify the claim**:
+
+| what the name matched | |
+|---|---|
+| a **comment** — its only occurrence in the entire corpus | `mountCrudRoutes` |
+| a **dependency-injection key** in test setup | `upsertLead: contactDeps.upsertLead,` |
+| a **real test of a different claim** | a test that the audit row survives a persistence *failure* |
+| a real test of the entry's **output**, where the claim was about its **source text** | `deriveContacts` on "the funnel names no source" |
+
+`meta verify` reported **0 errors** throughout. The same agent authored the requirement statements
+and the evidence pointers, and nothing independent existed to disagree.
+
+The scan is not defective — it is precision-over-recall on purpose, so a "missing" verdict means
+the name appears in **no** test file at all, which is broken in any ecosystem. It simply cannot
+distinguish verification from coincidence. Comment-only matches now warn
+(`WARN_REQUIREMENT_TEST_COMMENT_ONLY`), which reaches one of the four. **The other three are
+semantic and no lexical rule will ever reach them.**
+
+## 2. The inversion
+
+Stop asking the author to name a test. **Generate the test from the requirement.**
+
+```
+requirement.functional  leadRecord  (L4, live)
+        │  @statement / @violation
+        ▼
+  meta gen  ──►  tests/requirements/leadRecord.test.ts   ← generated identity, hand-written body
+        │
+        ▼
+  meta verify --codegen  ──►  the stub exists, is current, and matches the ledger
+```
+
+The requirement's dotted path determines the test's file and name. **There is no string for the
+author to choose, so there is nothing to fake.** The claim and the test are the same object viewed
+from two sides.
+
+## 3. Why this is the right shape
+
+**It reuses the strongest gate instead of inventing a weak one.** A generated stub is an ordinary
+generated artifact, so `verify --codegen` already covers "the stub exists and is current" — the
+same drift gate that caught an adopter's two-release-old regen in the field. No new scan, no new
+diagnostic family, no new fail-open rules to reason about.
+
+**It inverts the authoring gradient.** Today the cheapest satisfying move is "find a name that
+exists." With stubs the cheapest move is "fill in the red test already in front of you." The gate
+stops rewarding the shortcut.
+
+**It matches this repo's own doctrine.** *Pattern-derivable from metadata = codegen, never
+hand-code.* A test's **identity and location** are derivable from a requirement; its **assertions**
+are not. That is exactly the generated-file-with-preserved-hand-edits split ADR-0034
+(scaffold-and-own) and the three-way merge already exist for: the stub is generated, the body is
+hand-written inside it and survives regeneration.
+
+**It puts the claim where the work happens.** `@statement` and `@violation` are emitted as the
+file's doc comment, so whoever writes the assertion has the claim and its failure mode in front of
+them. That is better prompting than a ledger in another file, and it turns the audit from a search
+into a diff.
+
+## 4. `@status` is already the emission switch
+
+The vocabulary shipped in 0.23.0 turns out to encode exactly what each entry should emit:
+
+| `@status` | emits | why |
+|---|---|---|
+| `planned` | a **skipped/todo** stub | intended, not built — a red build for something deliberately unbuilt is noise, and the existing scan already warns on skipped |
+| `live` | a stub that **fails until filled** | the claim says this works; an empty green test would assert the opposite |
+| `partial` | a stub that fails until filled, doc-commented with the `@disposition` and `@trackedBy` | a known gap still deserves the part that does work to be pinned |
+| `abandoned` / `superseded` | **nothing**, and an existing stub is removed | the entry's job is to record that this is gone |
+
+An empty generated stub must **not** pass. A `live` stub therefore emits a failing assertion
+carrying the statement, not an empty body — otherwise the inversion recreates the original defect
+in a new place.
+
+## 5. Scope
+
+1. A `requirementTests()` generator in `codegen-ts`, emitting one file per `requirement.*` node at
+   or below the link floor (L4/L5 — organisational tiers implement nothing and get no stub).
+2. Deterministic naming from the requirement's dotted path, and a collision rule (ADR-0044's
+   payload-naming precedent applies: FQN-keyed with collision-scoped naming, never bare-name).
+3. Emission-by-status per §4, including **removal** on `abandoned`/`superseded`.
+4. `@statement` / `@violation` / `@implementedBy` rendered as the doc comment.
+5. Opt-in (§6), then the four non-TS ports, each through its own codegen (the pattern exists in all
+   five).
+
+## 6. The hazard, and the opt-in it forces
+
+**An adopter with an existing ledger would get one new red test per requirement** — 245 of them on
+the poker estate, 55 on the other. That is hostile, and it would get the generator switched off
+permanently on first contact, which is the outcome to avoid above all others.
+
+So: **opt-in, per generator and per entry.** A project adds `requirementTests()` deliberately; an
+entry can decline a stub. New requirements authored after adoption are the natural first users.
+`@verifiedBy` remains for the case stubs cannot serve — a suite that already exists, written before
+the requirement was, which is most of what an adopter has on day one.
+
+## 7. What happens to `@verifiedBy`
+
+It survives, narrowed and honestly documented:
+
+- **Adoption path** — point at tests that already exist. Existence evidence, never proof, with the
+  audit obligation stated in the docs (already done).
+- **Greenfield path** — the generated stub, where the link is structural.
+
+An entry with a generated stub needs no `@verifiedBy`; the two are alternatives, not layers.
+
+## 8. What this still does not solve
+
+**A filled-in stub can assert something irrelevant.** The inversion removes the fakeable *name*,
+not the possibility of a weak assertion. What it buys is that the claim and the assertion are
+co-located and diffable, and that the gradient no longer rewards the shortcut.
+
+The unfakeable formulation remains **`@violation`-driven mutation** — "the named test goes RED when
+the violation is real" — which the vocabulary already carries both halves of. It is deliberately
+out of scope here: `verify` is contractually forbidden from running tests (*"it never runs them"*
+is byte-gated in `expected-registry.json` across all five ports and restated in
+`spec/capability-ledger.md`), so proving belongs in a separate opt-in command or an adopter-CI
+recipe, specified separately. Generated stubs are the natural place for it to land later, since a
+stub can carry its mutation target as structured metadata rather than the hand-written
+`// MUTATION TARGET n:` comments adopters write today.
+
+## 9. Open questions
+
+- **Where do stubs live?** A dedicated `tests/requirements/` tree is greppable and easy to exclude
+  from coverage; co-locating beside the implementation's tests is more idiomatic per ecosystem.
+- **Does a stub reference `@implementedBy`?** Importing the named entity would make the stub fail
+  to compile when the model moves — a stronger link than a doc comment, but it couples the test to
+  generated code the requirement may not otherwise touch.
+- **Renames.** A requirement renamed at L4 changes its stub's identity; the three-way merge cannot
+  follow that, so the hand-written body would be orphaned. Needs a rename story before this is
+  usable on a ledger that churns.
+- **Does the failing-stub default break `meta init`'s first run?** A scaffold that ships red is a
+  bad first impression; likely the scaffolded ledger starts with `planned` entries only.

examples/advanced-modeling/src/generated/Program.ts

@@ -42,7 +42,7 @@ export const programs = pgTable(
   },
   (table) => [
     check(
-      "chk_programs_status",
+      "programs_status_chk",
       sql`status IN ('draft', 'published', 'archived')`,
     ),
   ],

examples/advanced-modeling/src/generated/Purchase.ts

@@ -32,7 +32,7 @@ export const purchases = pgTable(
   },
   (table) => [
     check(
-      "chk_purchases_status",
+      "purchases_status_chk",
       sql`status IN ('pending', 'completed', 'refunded')`,
     ),
   ],