create-mercato-app 0.7.1-develop.7136.1.0f76137a1d → 0.7.1-develop.7148.1.3076e5ccf7

package/agentic/shared/ai/review-checklist.md

@@ -12,6 +12,7 @@ Apply this checklist in addition to the installed `om-code-review` checklist whe
 ## Data, commands, API, and safety
 
 - Editable scoped entities use UUIDs, snake_case storage, tenant/org and standard timestamp/soft-delete columns, plus `updated_at`; migrations and the module snapshot contain only intended changes, and `yarn db:generate` is rerun as a no-op probe without applying migrations.
+- A migration that rewrites stored values (backfill, rename, normalization) on an entity whose CRUD route declares `indexer: { entityType }` exports `queryIndexReindexEntityTypes` via `declareQueryIndexReindex([...])`. Raw SQL bypasses the indexer helpers, so without the declaration `entity_indexes.doc` and its `search_tokens` rows keep the pre-migration value permanently, with no failing job to signal it.
 - Input validators cover every query/body trust boundary. Public request/OpenAPI schemas never accept or require runtime `tenantId`/`organizationId`; handlers derive scope from trusted context and ignore same-named payload fields. Anonymous public business intake uses an explicit trusted tenant+organization binding; missing, partial, or ambiguous binding fails closed, and no path selects or persists the first/oldest active tenant or organization. API routes use per-method auth/feature metadata, `makeCrudRoute`, scoped ORM keys, a separate `openApi` export, stable response keys including `updatedAt`, and `indexer: { entityType }` where searchable.
 - Domain writes go through commands. Each declared create/update/delete/action command independently reaches its required guard, merges the guard result's `modifiedPayload` into the validated input and revalidates it before command dispatch, and reaches its lock/transaction and undo seams; helper vocabulary elsewhere in the module is not evidence for that command. Custom actions prove the complete optimistic-lock path together: the client sends that record's version, the server enforces it, and the client surfaces the 409 conflict with a real retry path. Multi-phase entity/relation/custom-field changes use `withAtomicFlush(..., { transaction: true })` on one EntityManager; command actions keep events, cache invalidation, indexing, queues, and external effects after commit.
 - Availability/uniqueness decisions that race use a database constraint, lock, compare-and-swap, or one atomic claim seam; never a read/check followed by an unguarded create. Idempotency queries and database uniqueness include tenant+organization for scoped records. Concurrent contenders have one deterministic winner and an idempotent retry returns the original outcome.

package/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md

@@ -7,9 +7,37 @@ Load this reference whenever entity metadata changes.
 3. Run `yarn db:generate` as a probe; inspect all SQL and snapshot changes.
 4. Remove unrelated generator churn. If scoped SQL must be written from known metadata, follow the module's existing migration style and update only its snapshot.
 5. Verify forward migration semantics, uniqueness/index names, nullable/default/backfill behavior, and safe rollback/compatibility strategy.
-6. Never modify a shipped migration. Add a new one.
-7. Ask before `yarn db:migrate`, greenfield reset, or changing a database target.
+6. Declare the query-index projections the migration invalidated (see below).
+7. Never modify a shipped migration. Add a new one.
+8. Ask before `yarn db:migrate`, greenfield reset, or changing a database target.
 
 Normal delivery stops after migration file/snapshot/tests; local applied state is not a PR artifact.
 
 Canonical example source — the shape `yarn db:generate` produces and diffs against: [`migrations/Migration20251030150038.ts`](../../../../src/modules/example/migrations/Migration20251030150038.ts), [`migrations/Migration20260226161000_example.ts`](../../../../src/modules/example/migrations/Migration20260226161000_example.ts), and the module-scoped [`migrations/.snapshot-open-mercato.json`](../../../../src/modules/example/migrations/.snapshot-open-mercato.json). Read them for style; never copy a migration into your own module.
+
+## Data migrations MUST declare the projections they invalidate
+
+A migration that rewrites the VALUES of a column in raw SQL — a backfill, a rename, a
+normalization — bypasses every CRUD/indexer helper that would emit `query_index.upsert_one`.
+`entity_indexes.doc`, and every `search_tokens` row derived from it, then keeps the
+pre-migration value permanently, with no failing job and no moved `updated_at` to signal it.
+Global search and any `like`/`ilike` list filter routed through the token index then match the
+record by its OLD text and miss its NEW text.
+
+A migration cannot emit the refresh itself — it holds no DI container, and the projection must
+only be rebuilt once its own transaction has committed. So it **declares**, and
+`mercato db migrate` discharges the obligation after the run:
+
+```ts
+import { declareQueryIndexReindex } from '@open-mercato/shared/lib/query/migration-reindex'
+
+export const queryIndexReindexEntityTypes = declareQueryIndexReindex(['my_module:my_entity'])
+```
+
+- Required whenever the migration changes stored values of a column on an entity whose CRUD route
+  sets `indexer: { entityType }`. Pure `ADD COLUMN`/`CREATE TABLE` DDL with no backfill needs nothing.
+- Identifiers are `module:entity` (snake_case, exactly the `indexer.entityType` value). Use the
+  helper rather than a bare array literal — it throws on a malformed identifier at import time,
+  whereas a hand-written literal is only reported as a warning during `db migrate`.
+- Both originals forward-only? A follow-up migration that carries **only** the declaration and
+  executes no SQL is the repair route for installs that already applied the original.