Vrida — Cross-Cutting Project Decisions

Cross-system and project-wide decisions. Does not contain per-module lock entries (those live in each module's design doc) or product description (that's docs/WHAT_IS_VRIDA.md).

Migration rules are owned by docs/database/SCHEMA_CONVENTIONS.md → Migrations. The phase/dependency-order table below is cross-cutting build sequencing; the full rule set lives there.

Confirmed (Locked) Decisions

1. Tech Stack

Concern Decision
Mobile Flutter (phone primary, tablet secondary)
Backend NestJS on AWS App Runner
Database PostgreSQL via Supabase
ORM Drizzle (drizzle-orm + drizzle-kit). TypeScript schema via pgSchema/pgTable = single source of truth; native multi-schema; native RLS (pgPolicy); SQL-first migrations. Chosen over Prisma because the schema is RLS-heavy (RLS on nearly every table) — Drizzle manages RLS/policies/SQL constructs natively, whereas Prisma manages only table structure and leaves RLS/triggers/partial-indexes/CHECKs in un-managed raw SQL. Free/OSS; backed by PlanetScale (Mar 2026). Accepted tradeoff: pre-1.0 (v1.0.0-beta), drizzle-kit migration engine maturing, thinner docs than Prisma.
Payments Stripe Connect (platform subscription billing) + Stripe Terminal (in-person)
Hosting AWS App Runner (backend), Supabase (database), Cloudflare (CDN + R2)
AI AWS Bedrock — Claude Haiku 4.5
File storage Cloudflare R2
Real-time Supabase Realtime
Mobile offline cache SQLite via Drift in Flutter
Email Resend
SMS Twilio
Digital signatures HelloSign (Dropbox Sign) for legal-binding documents; in-app canvas for casual signatures

All choices are locked. ORM is Drizzle (the prior Prisma decision was reversed before implementation — see Migrations and the ORM rationale above).

2. Architecture Principles

  • Tenancy: Pattern 2 (shared multi-tenant Postgres + Row-Level Security) as the core model. Pattern 4 (dedicated Supabase project per top Enterprise customer) added as a $500–$2,000/month add-on when a specific customer needs it.
  • Schema-per-module: Each module has its own Postgres schema (inventory, pos, orders, purchasing, crm, reporting, multi_loc, admin, billing, audit, notifications, platform, shared, identity, payments, integrations, ai, files, search, consumer, rewards, offers).
  • Cross-module access via service layer only: modules call other modules' service classes, never their tables.
  • Architecture-first: build schema and infrastructure for all three tiers from the start, even though all tiers do not launch simultaneously; tier differences are enforced via feature flags and usage metering.
  • Soft delete everywhere: deleted_at / status instead of DELETE.
  • Audit log from day one: every consequential change captured for all tenants.

3. Product Direction — Generic Multi-Vertical

This is the standing scoping principle for all module design.

Vrida is a generic retail ERP/POS designed to work for most retail business types. Nursery is the first and reference vertical — it drives concrete requirements and go-to-market — but the platform is built generic-first. Generic-first's real risk is over-abstracting and losing the concrete nursery requirements that make the initial build shippable; "nursery = reference vertical drives requirements and GTM" is the mitigation.

Standing scoping question

"Does this work for any retail business?" — not "Does this work for a nursery?"

Rule Detail
No vertical-specific columns on foundation/shared schemas No nursery, pottery, food/bev, or other business-type columns or assumptions on platform, shared, identity, multi_loc, or cross-cutting modules.
Vertical-specific needs via the locked mechanisms only (1) item_type + JSONB attributes on the item layer. (2) Generic, reusable table design — e.g. pos.guarantee with free-text guarantee_type, not a plant_guarantee table. (3) Clearly-marked vertical add-on modules that sit beside the foundation schemas. Foundation/cross-cutting modules must not depend on add-ons.
NOT a revival of the retired generic-core + vertical-extension model There is no core schema. Masters stay in their owning modules (item → Inventory, customer → CRM, vendor → Purchasing). The mechanism is discriminator + JSONB, not schema multiplication.
Apply forward All future module design starts with generic scope; any vertical assumption is flagged explicitly in the spec and schema at design time.

Reclassifications under this principle

These are notes, not schema rebuilds. They make existing treatment explicit and guide future work.

production module — formally VERTICAL ADD-ON: production/propagation (growing from cuttings, crop schedules, mother plants) is nursery-specific. Not part of the foundation; not a dependency for any generic module. Build only when the nursery vertical is explicitly prioritized. Status: deferred indefinitely.

shared.plant, shared.plant_common_name — known wart: two nursery-specific reference tables ended up in the generic shared schema. Locked and not being rebuilt — accepted as-is. Going forward: vertical reference data must NOT default into shared. When a second vertical is real, consider a per-vertical reference namespace.

shared.usda_hardiness_zone is borderline — climate zone data has broader use than plants (landscaping, agriculture, outdoor retail). Left in shared with no flag.

pos.guarantee — the reference pattern: guarantee_type is free text driven by item_variant.guarantee_terms.type (e.g. 'plant_guarantee'). Any vertical can use it with its own type label. terms_snapshot JSONB is shape-agnostic. This is the canonical example of the right approach — apply when designing any similar feature with a vertical-specific flavor.

4. Multi-Site Architecture + Forward Decisions

Decision: Schema-level multi-site support is built in from the start, even though multi-site UI activates in a later phase.

Why: Retrofitting multi-site into single-site architecture is expensive and risky. The upgrade path should be zero-migration.

Implementation:

  • Every transactional table includes site_id (UUID, NOT NULL).
  • Single-site tenants auto-populate site_id from platform.tenant.primary_site_id.
  • Master data tables (customer, vendor, catalog) are tenant-wide — no site_id.
  • Inter-site operations use multi_loc.transfer.
  • Site-specific permissions, pricing, and policies are configurable.

Status: Locked. All schema work from this point on must include site_id on transactional tables.

Forward decision 1 — site_id requirement rule

site_id is REQUIRED (NOT NULL) on operational tables where activity happens at a physical location: sales, stock movements, orders, purchase receiving, production activity, transfers.

site_id is NOT required on tenant-wide master data: customers, vendors, items, roles, agreements, tenant settings.

Why: this determines which tables carry site_id at all. The schema-design runbook column standard already lists this rule — this decision makes it the official scope-level lock.

Forward decision 2 — site access control rule

Tenant isolation is enforced by RLS via tenant_id. Site-level access is enforced at the application/service layer via identity.user_site_assignment.

Do NOT add site_id as a second RLS isolation dimension.

Why: RLS is a sharp tool — once a policy filters by (tenant_id, site_id), every cross-site query (admin, reporting, transfer, audit) must bypass it via service_role. Site-level filtering is cheaper and clearer at the service layer using user_site_assignment. If site-level data isolation (not just access) becomes necessary in a later phase, it stays app-layer — not a retrofit of RLS.

Forward decision 3 — pricing/tax scope rule

Pricing and tax must be designed so scope can be tenant-level OR site-level. Only tenant-level may be built initially, but schemas MUST NOT assume pricing/tax is permanently tenant-only.

Why: a scope_type column + nullable site_id today is trivial; retrofitting it later is high-cost. Applies when designing pricing and admin/tax setup tables.

5. Database Infrastructure

Connection strategy

  • Direct connection (Supabase port 5432) for all tenant-scoped application queries. SET LOCAL works reliably here with no session leakage risk.
  • Pooled connection (Supabase port 6543 via PgBouncer) for service_role background work only — migrations, reporting MV refresh, provisioning, cross-tenant admin. These bypass RLS intentionally.
  • Connection exhaustion threshold: ~500+ concurrent connections. At that point add Supavisor session-mode pooling or move largest tenants to Pattern 4 dedicated infra.

Drizzle multi-schema setup

  • Drizzle native multi-schema: each schema declared with pgSchema('<name>'); tables hang off the schema object. One TypeScript schema source of truth across all 23 schemas.
  • RLS is managed in Drizzle natively (pgPolicy, .enableRLS() / default-deny when no policy). Policies reference the tenant GUC (e.g. app.current_tenant_id).
  • Tenant context uses Postgres SET LOCAL inside a transaction (a Postgres requirement — set_config/SET LOCAL only persist within a transaction). Handled by the tenant-context wrapper (below).

NestJS tenant-context middleware

  • Global TenantGuard: validates JWT via Supabase Auth, extracts auth.uid, looks up identity.tenant_user → tenant_id, attaches to request context.
  • Global tenant-context wrapper: every request handler runs inside a Drizzle transaction (db.transaction(...)) that issues SET LOCAL app.current_tenant_id = <tenant_id> before any query. All service calls within the request receive the transactional client (tx), never the root db client. (Pattern: a tenantDB(cb) helper resolving tenant from request context, e.g. via AsyncLocalStorage.)
  • @CurrentTenant() decorator: convenience for controllers to access tenant_id from request context.
  • Critical rules: Services NEVER use the root db client for tenant-scoped queries — only the transactional tx with tenant context set. Background jobs (cron, webhooks) must explicitly open a tenant-context transaction before processing. service_role / admin client queries bypass RLS entirely — used only for cross-tenant operations (provisioning, admin, reporting).

Site creation as first provisioning step

Default site is created as provisioning step 2, immediately after the tenant record itself:

  1. tenant_record_created
  2. default_site_created
  3. storage_initialized
  4. identity_initialized
  5. stripe_setup
  6. seed_data_loaded

This guarantees site_id NOT NULL is always satisfiable — no transactional record can be written before the site exists.

Search path policy

  • Default search_path set to public only. No module schemas in search_path.
  • All application code, migrations, functions, triggers, and views MUST use fully schema-qualified table references: inventory.item, platform.tenant, crm.customer — never unqualified.
  • Drizzle handles schema qualification via pgSchema('<name>') in the TypeScript schema — every table is bound to its schema, so generated SQL is fully schema-qualified.
  • Exception: Postgres extensions (uuid-ossp, pgvector, pg_trgm) installed in public, accessible without qualification.

Migration dependency order

Migration rules are owned by docs/database/SCHEMA_CONVENTIONS.md → Migrations. The cross-cutting build sequencing order is:

Phase Modules Why
1 platform Root — tenant table required by everything
2 shared Reference data
3 identity Users / roles
4 multi_loc Sites — needed for site_id
5 payments, integrations, ai Service layers
6 admin Tenant config
7 crm, inventory Master data
8 pos, orders, purchasing, billing Transactional
9 consumer, rewards, offers Consumer layer
10 reporting, audit, notifications Cross-cutting

6. Billing Ownership Split

Two billing concerns, separated by who bills whom:

  • Platform billing (Vrida → tenant, SaaS): lives in the platform schema. Tables: billing_account, subscription, subscription_invoice, payment, tier_definition, tenant_entitlement. Platform scope: SaaS tier plans, signup/trial, recurring subscription charges, prorations, usage metering/tier enforcement, SaaS dunning, plan changes, subscription invoices, MRR/churn analytics, promo codes, Enterprise contracts/quotes. None of this is the billing schema's job.
  • Merchant billing (tenant → its own customers/vendors): lives in the billing schema. Customer A/R (charge accounts, customer account balance, statements, aging) and vendor A/P (payables against purchasing invoices, vendor payments, write-back to purchasing.vendor_invoice). Not GL/accounting — state tracking and payment application only.

Stripe reconciliation: ONE Stripe Customer per tenant = Platform's billing_account (Vrida billing them). N Stripe Connect accounts per site = merchant-side (POS/Billing/Multi-loc — tenant collecting from customers). These are independent Stripe entities.

Payment execution belongs to Payments: Billing records state; it does not call Stripe or ACH directly. PaymentsService is the only module that executes payments.

Deferred by default (unlock on concrete product requirement, not "we should have it"):

  • Formal customer invoice documents
  • AP payment batches / payment runs (one-off vendor payments only initially)
  • Customer credit memos / write-offs / adjustments
  • Dunning / collections for merchant customers
  • Payment plans / installment financing for merchant customers
  • GL / accounting / journal posting / chart of accounts (QuickBooks via Integrations module)
  • Multi-currency settlement

7. AI Onboarding Pipeline Ownership

The zero-mapping import pipeline (import_job / import_file / import_record) lives in the AI module, not Integrations.

Why: the pipeline is one-time onboarding data ingestion driven by AI — not a recurring external-system connector. The zero-mapping magic IS the AI (Claude identifies and maps the data); this pipeline has a hard AI module dependency for its core value. The Integrations connector framework is shaped around external APIs, OAuth, batch sync, and retry — none of which characterize the import pipeline.

The prior assignment of these tables to Integrations is superseded by this decision. Older docs referencing integrations.import_job are historical artifacts; this decision is authoritative.

Flow: tenant uploads files → AIService detects data type and maps fields → records extracted and validated → flagged records shown for tenant review → tenant resolves flags → confirmed records loaded into target module tables (Inventory, CRM, Purchasing) via the owning module's service → platform.tenant_setup_task milestone marked complete. Platform tracks onboarding milestones; AI owns the pipeline; data loads via module service classes.

8. Stripe Architecture

Each tenant has one Stripe Customer for SaaS subscription billing (Platform). Each tenant can have N Stripe Connect accounts, one per site, for in-person payment routing (Payments/POS). These are independent Stripe entities.

9. Consumer-Layer Architecture

Model B — one Vrida consumer account per real-world person

A consumer signs up once on the Vrida platform and sees all Vrida stores they've shopped at. Platform-level identity — not tenant-scoped — lives in its own consumer schema beside platform and shared.

Decision Value
Schema consumer
Tenancy Non-tenant-scoped — no tenant_id on any table except consumer_tenant_link.tenant_id, which is an FK dimension (which nursery), not the RLS scope
RLS pattern WHERE id = current_setting('app.current_consumer_id')::UUID on consumer; WHERE consumer_id = current_setting('app.current_consumer_id')::UUID on related tables. Not tenant-scoped.
Auth pattern ConsumerGuard / ConsumerInterceptor — analogous to TenantGuard / TenantInterceptor. Sets app.current_consumer_id per request context.
Access boundary Tenants NEVER query consumer.* directly — only via ConsumerService (SECURITY DEFINER / service-role boundary). A tenant sees only its own relationship with a consumer. Never sees cross-store activity.

Consumers are a separate user population from tenant staff. Staff auth = Identity module (email/password + 2FA + SSO). Consumer auth = social login (Google / Apple).

crm.customer (tenant-scoped — a business's record of a buyer) links to consumer.consumer (platform-level — the Vrida account) via a nullable consumer_id on crm.customer. The link is optional in both directions: anonymous POS buyers have no consumer_id; app-only signups may have no linked crm.customer yet.

When crm.customer.consumer_id is set, consumer.consumer is the canonical source of truth for name, email, and phone. Read via ConsumerService — never copy fields down to crm.customer.

Consumer creation paths

  1. Self-register via app — consumer signs up with Google/Apple; consumer row created.
  2. Cashier-create at checkout — cashier enters email/phone; unclaimed consumer stub created and linked to new crm.customer. Consumer claims the stub later via the app.
  3. Cashier-link — cashier matches email/phone to existing consumer; links to the existing crm.customer.

Consumer status lifecycle: unclaimed → active.

Cross-store privacy contract

Tenants NEVER read consumer.* directly. ConsumerService is the SECURITY DEFINER boundary. A tenant sees only:

  • Its own crm.customer row (tenant-scoped).
  • Consumer profile fields proxied through ConsumerService (name, email, phone — not cross-store history).

Cross-store visibility belongs to the consumer alone (consumer app only). This is a legal and commercial requirement.

POS seams (when consumer layer is built)

  1. Create / link consumer at checkout — POSService calls ConsumerService.findOrCreate(email|phone) and attaches consumer_id to the sale.
  2. Redeem at checkout — POSService makes two parallel calls: RewardsService.redeem(consumer_id, reward_option_id, amount) (points redemption) and OffersService.redeem(consumer_id, offer_id, sale_id) (coupon/promo redemption). OffersService is NOT a sub-service of RewardsService — they are parallel consumer-layer services.

Sequencing

Built as a dedicated phase after the merchant core (CRM → POS → Orders → Purchasing → Billing), because rewards earn from purchases that happen in POS. Do not build any consumer-layer schema before POS is locked.

Initial consumer scope

View: stores, points balances, offers, AI care chat, purchase history. In-app commerce (buying inside the app) is deferred to a later sub-phase.

10. HR / Workforce — Out of Scope

HR and labor management are permanently out of scope for Vrida. Workforce integrations (Gusto / ADP / Deputy) are not planned — they lose their purpose without an HR module. Flag if a specific customer requires it, but do not plan for it.

11. Data Retention & Tenant Lifecycle

At 90 days post-cancellation, operational data is purged; audit and financial records are retained for 7 years in archived form; consumer-layer data is not deleted on tenant cancellation.

Operational data — purged at 90 days post-cancel:

  • pos.*, orders.*, inventory.*, purchasing.*
  • crm.* (all tenant-scoped customer, contact, consent, note records)
  • multi_loc.*, notifications.*, billing.*

Retained for 7 years (archived/cold form):

  • audit.* — full retention
  • Financial records derivable from audit (sales totals, refunds, tax collected, payments)

Consumer-layer data — NOT deleted on tenant cancellation:

  • consumer.* data (consumer identity, addresses, interests) belongs to the consumer, not the tenant. The tenant's consumer_tenant_link rows are removed on cancellation; the consumer's own records remain intact and continue to be valid at other businesses.
  • This is a legal and commercial requirement, not a policy preference.

90-day reactivation window: within 90 days, a tenant can reactivate and resume with no data loss. After 90 days, operational data is irreversibly purged; archived records remain for compliance and statutory obligations.

12. Identity Expansion — Polymorphic Actor Model and ERP-Grade AuthZ

Decided: 2026-06-28
Detail: docs/modules/module_spec/identity_expansion_intent.md

The pre-expansion identity schema (13 tables, 164 cols) is expanded with a major addition set, INTERLEAVED with finishing identity, not deferred. (Now 14 tables / 170 cols at Batch A Pass 1 LOCKED 2026-06-28; expansion continues through Batches B/C/D.) Two drivers: (1) top-tier competitive ERP goal benchmarked against Salesforce/Workday/SAP/Okta + NIST/SCIM/SOC2 revealed 12 gaps; (2) AI agents operating the ERP is a near-term product requirement, not a future phase.

The central decision is a full polymorphic actor model. A new identity.actor table becomes the default FK target for "who did this" references across identity, platform, and audit. identity_user becomes the human-detail table; service_account and agent_identity are the other detail tables. All actor types share one PK namespace and the same role-assignment mechanism.

identity_user → actor relationship: shared PK / class table inheritance (OQ-1 resolution). identity_user.id IS actor.id — no separate actor_id column on identity_user. The UUID is generated at actor INSERT; identity_user is inserted second with the same UUID as its PK. This overrode the original intent-doc plan of a separate actor_id FK column. Rationale: zero migration data; shared PK is the standard ORM class-table-inheritance pattern; eliminates one column; joins are JOIN identity.actor a ON a.id = u.id with no indirection. Same pattern applies to service_account and agent_identity (not yet built).

REOPENS platform (doc-only until identity-complete): Of the 8 platform deferred FK columns, 4 are retargeted → identity.actor (any actor type may perform these operations) and 4 stay → identity.identity_user (human-semantics records — legal, compliance, CS):

  • → identity.actor: tenant_entitlement.granted_by_user_id, tenant_setup_task.completed_by_user_id, tenant_data_lifecycle.requested_by_user_id, tenant_lifecycle_event.actor_user_id
  • → identity.identity_user: tenant_contact.identity_user_id, agreement_acceptance.accepted_by_user_id, tenant_internal_activity.performed_by_user_id, operator_audit_log.operator_user_id

FK constraints, Drizzle schema, and migration remain deferred to identity-complete (OPEN_ITEMS). audit.audit_log.actor_user_id → identity.actor when Batch A actor table lands (OPEN_ITEMS).

Additional locked decisions in this expansion:

  • Single-parent role inheritance (role.parent_role_id)
  • permission_group (Vrida-defined only) + permission_group_permission
  • role_template (Vrida-defined seeds for custom role creation)
  • role_assignment table (time-bounded, with history — replaces tenant_user.role_id)
  • SoD: detect-and-flag, not block (sod_rule + sod_violation)
  • identity_session (Vrida-side shadow of Supabase sessions; powers "log out all devices")
  • group + group_member (team model + SCIM /Groups anchor)
  • agent_identity, agent_skill, agent_skill_assignment (Vrida-defined skills only)
  • service_account + service_account_credential
  • tenant_security_policy (per-tenant session/MFA/IP overrides)
  • access_request + approval_workflow + approval_step (lightweight SMB governance)
  • consent_record — NOT built in v1 (Batch D investigation complete, 2026-06-28). crm schema owns end-customer/shopper consent; platform.agreement_acceptance covers org-level platform legal consent; US SMB employment basis covers staff data processing — no v1 identity schema gap confirmed. Guard: build consent_record at first EU-based or enterprise customer requiring per-user GDPR Article 7 explicit consent records for staff. See DR-29 in docs/database/schema_docs/identity.md.

Build order: 4 batches (A foundation → B roles/governance → C machine/agent → D security/compliance), each through the full module pipeline before the next begins.

13. Post-Build Schema Reconciliation Direction

Decided: 2026-06-29 (identity module, post-Phase 3 migration + Phase 4 build)

After a module's first migration runs and build begins, a full column-level doc-vs-DB diff must be performed. Two directionality rules apply when drift is found:

DB-authoritative for recovered functional columns — if a column is present in the live DB with clear implementation rationale (it serves a real function, it was written during build, it is used in service code) but was not recorded in the design doc, accept the DB shape as correct and update the doc to match.

Doc-authoritative for design intent not yet materialized — if the design doc specifies a column or constraint that is not yet in the DB (was overlooked at migration time), add it via a follow-up migration.

All resolutions must be additions; no drops or renames without explicit design review. This principle was applied via packages/db/migrations/20260629020000_identity_drift_reconcile.sql (+4 cols, +6 indexes/constraints). Net result: identity realigned at 34 tables / 369 cols.

Forward rule — column-level diff is required after every migration: Count-matching is necessary but not sufficient. A column dropped in one place and re-added in another nets to zero — the count passes but drift exists. After every module migration, run a full column-level diff per table (SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_schema = '<schema>' AND table_name = '<table>' ORDER BY ordinal_position;) and compare against the schema doc. Sign off on column names and types matching — not just count.

14. Tier Display Names — Seed / Grow / Bloom

Decided: 2026-06-30 (admin console build, reconciling the console mockup against the real schema)

Vrida has 3 real subscription tiers, keyed starter / pro / enterprise in platform.tenant.tier and platform.tier_definition.tier_code (CHECK-constrained, unchanged). The admin console mockup introduced a 4-tier consumer-facing marketing ladder — Seed / Grow / Bloom / Crown — as a separate naming scheme.

Resolution: Seed / Grow / Bloom are the tier display names for starter / pro / enterprise respectively — display only, not new keys. There is no 4th tier; Crown is dropped. Any feature previously gated at Crown (e.g. multi-location) now gates at the top real tier (enterprise/Bloom). No migration, no key rename, no seed-data change — tier_definition display-name seeding (still deferred per OPEN_ITEMS, pricing not yet locked) should use these labels when it happens.

Not decided here: the pricing structure (flat-tiered vs. per-location) remains an open strategic question — untouched by this decision.

15. Platform Skeleton Tables — announcement + platform_setting

Decided: 2026-06-30 (admin.vrida.app wrap-up — closing the last 2 🔴 PROPOSED-FEATURE console pages by giving them a real schema)

Two tables added to the locked platform module (21 → 23 tables), through the SCHEMA_DESIGN_RUNBOOK Section 4 audit gate (locked-module touch, not a fresh module lock):

  • announcement — Vrida-authored broadcast messages. Mixed-scope (tenant_id nullable: NULL = all tenants, set = targeted). First platform table to combine a nullable tenant_id with RLS — the policy's NULL branch (tenant_id IS NULL OR tenant_id = current_setting('app.current_tenant_id')::uuid) is load-bearing, mirroring identity.role's DR-3 pattern, to avoid hiding global rows from every tenant (bug class #5).
  • platform_setting — Vrida-wide key-value config. Deliberately not tenant-scoped this pass (scope was explicitly undefined going in — see OPEN_ITEMS' now-closed Settings row) and deliberately has no deleted_at (a bare key-value row has no soft-delete concept; deactivate by overwriting, matching tier_definition/agreement_version's "no delete, deactivate differently" precedent).

Audit findings applied before lock (Section 4, read-only pass first): both tables' proposed columns omitted a convention-required field — announcement was missing deleted_at (tenant-scoped soft-delete default), platform_setting was missing created_at. Both added. platform_setting.value documented as "caller-defined shape, no fixed schema" (Item J) rather than left as bare JSONB. Both identity.actor FKs are live/enforced immediately — no forward-reference deferral needed, since identity is already migrated.

Scope of this pass: both tables are skeletal — schema locked, but no write endpoint. Two read-only service methods exist (PlatformService.listAnnouncements(), getSettings()) behind GET /admin/announcements and GET /admin/settings, closing the two remaining 🔴 PROPOSED FEATURE flags in the admin console (both now render 🟡 sample-flagged real-shaped data instead). Write endpoints, a real Settings scope decision (operator prefs vs. platform-wide config), and a real Announcements authoring flow are still open — tracked in OPEN_ITEMS.

Rejected: giving platform_setting a tenant_id column now to pre-support per-tenant settings. Rejected because the key-uniqueness constraint would need to change to a tenant-aware partial-unique pattern, and no concrete per-tenant setting need exists yet — better decided deliberately later (as a separate tenant_setting table if the need is genuinely per-tenant, not by retrofitting this one).

16. Tenant Admin Console — Mockup-First (tenant.vrida.app)

Decided: 2026-06-30 (commit 16e63ff)

Sequencing choice, mirroring decision #15's pattern for admin.vrida.app: build the tenant.vrida.app UI surface for all 9 identity admin page areas (identity.md §17 — Members, Groups, Roles & Permissions, Service Accounts, AI Agents, Access Requests, Active Sessions, Security Policy, SoD Compliance) as 🟡 sample-data mockups in a new apps/web/tenant Next.js app, before building any HTTP controller for IdentityService's 86 methods. Every page's mock data is typed field-for-field against docs/database/schema_docs/identity.md, so wiring later is a data-source swap rather than a UI rebuild.

Rationale: IdentityService's service layer was already complete and tested (86 methods, 2026-06-29) with zero consumers — building the UI shape first, against the real schema, surfaces UX/scoping questions (which the small-nursery-relevance flag below captures) before committing to specific REST endpoint shapes.

Scope of this pass: UI only — no API endpoints, no auth guard, no tenant-context/RLS wiring. Two new shared UI primitives (DetailCard, TabSwitcher) were extracted for reuse across both apps/web/admin and apps/web/tenant, generalizing a pattern that had been duplicated inline in admin's TenantSkeletonPanels.tsx.

Open scoping question surfaced, not resolved: 5 of the 9 pages (Roles & Permissions, Service Accounts, AI Agents, Access Requests, SoD Compliance) read as enterprise-heavy relative to a single-location nursery's day-to-day needs — tracked as a human product-scoping call in OPEN_ITEMS row 64, not decided here.

17. Shared Module (module #3) — Natural-Key PKs, Plant UUID Exception, Global-From-Day-1, Multi-System Climate

Decided: 2026-07-05 (module #3 build — schema design proposed, reviewed, and locked in the same session)

Ten tables locked in the new shared schema: currency, country, administrative_region, language, locale, unit_of_measure, climate_zone, plant, plant_common_name, plant_climate_zone (101 columns total). Reconciles with and expands the superseded v1 design (docs/old/schema/schema_modules/schema_shared.md, 7 tables) — us_state → administrative_region (ISO 3166-2, global, not US-only) and usda_hardiness_zone → climate_zone (5 systems, not just USDA); language, locale, plant_climate_zone are new.

Decision A — Natural-key PKs, a deliberate deviation from platform/identity's UUID convention: currency, country, language, locale, administrative_region, unit_of_measure, and climate_zone use their ISO/short code as the primary key (e.g. currency.iso_code = 'USD') rather than a UUID. This conflicts with SCHEMA_CONVENTIONS.md §5, which lists only "UUID or smallint" for lookup/reference table PKs — no natural-key text option is documented, and a full precedent survey found zero other tables anywhere in the codebase (v1 or v2, 18 tables checked) using a natural-key PK. This was flagged explicitly during the design-proposal pass, not silently applied — accepted anyway because ISO codes are internationally standardized, effectively permanent identifiers, and FK-readability (country_code = 'US' vs. an opaque UUID) has real value for reference data that every future module will join against. SCHEMA_CONVENTIONS.md §5 should eventually be amended to document this as an authorized third PK option for pure reference-code tables, rather than leaving the deviation implicit.

Decision B — plant is the one exception, using a UUID PK instead: botanical/taxonomic names are not permanently stable — real taxonomic revisions reclassify species over time, unlike ISO codes. A natural-key PK on plant would force every downstream FK (inventory items, plant_common_name, plant_climate_zone, the AI enrichment pipeline, Consumer's interest_ref seam) to cascade on a reclassification. This matches v1's own precedent (schema_shared.md also used a UUID PK for plant, with botanical_name as a separate UNIQUE column).

Decision C — Global from day 1: every table is seeded with real, structural reference data now rather than deferred — see the seed-scope honesty note below for where "global" was deliberately scoped down rather than faked.

Decision D — Multi-system climate zones: climate_zone covers USDA, RHS, AHS Heat, Australian, and EU hardiness/climate systems in one table (composite-string PK, '<system>:<zone_code>'), rather than a single US-only USDA table as in v1. USDA and RHS are high-confidence, well-documented standards; AHS Heat's day-count metric (not a temperature range) required min_temp_c/max_temp_c to be NULL for that system, with the day-count range captured in description instead. Australian and EU zones are seeded as simplified, lower-confidence approximations — there is no single official "EU hardiness zone" standard the way USDA is for the US — and should be reviewed against an authoritative source before being treated as definitive.

Section 4 audit fix applied before lock: administrative_region.region_type's CHECK constraint was originally proposed with 6 values (state/province/prefecture/region/territory/canton) and failed the audit (Item F) — the real diversity of ISO 3166-2 subdivision type labels across countries (department, municipality, district, governorate, oblast, emirate, county, parish, autonomous_republic, city, prefecture, republic, capital_territory, special_administrative_region, administrative_area, and — discovered only during seeding — country, the UK's own top-level ISO 3166-2 type label) required expanding to 21 values before any seed data could be inserted.

Honest seed-scope note — accuracy over volume: two tables were deliberately scaled down from larger originally-discussed targets rather than generating unverifiable volume from memory: administrative_region (186 rows seeded — comprehensive for US/Canada/Mexico/UK/Australia, representative for Germany/France/Italy/Spain/Japan — not the full ~3-4K global ISO 3166-2 set) and plant (114 rows, curated and high-confidence, not "a few hundred" padded with less-certain species). language similarly covers ~94 major languages, not the full ISO 639-1 list of ~184 (some of which are extremely obscure) — and Hawaiian was excluded entirely because it has no ISO 639-1 2-letter code, only the 3-letter iso_639_3='haw', which doesn't fit the char(2) PK (a real, disclosed limitation — see docs/database/schema_docs/shared.md).

Rejected: building country_currency as a join table for countries with multiple simultaneous legal tenders. country.default_currency_code (a single FK) covers the common case; a join table only matters for genuinely dual-currency countries (Panama, Timor-Leste), which is out of scope for a US-market product today. See OPEN_ITEMS for the trigger to revisit.

18. Multi-Location Module (module #4) — Global Address Model, Measurement-System Non-FK, Region↔Country DB Check

Decided: 2026-07-05 (module #4 build — schema design proposed, reviewed, and locked in the same session)

One table locked in the new multi_loc schema: site (29 columns). Tenant-scoped (UUID PK, tenant_id NOT NULL FK → platform.tenant, RLS enabled, soft-delete via deleted_at). Depends on platform and, newly, shared (via 3 FKs). Replaces the superseded v1 design (docs/old/schema/schema_modules/schema_multi_loc.md, 1 table / 21 cols), which used a single address JSONB column ({street, city, state, zip, country}) — a US-shaped model that does not generalize.

Decision A — Global address model, flat columns + natural-key FKs, replacing v1's JSONB: the single address JSONB column is replaced with address_line1, address_line2, address_line3 (flexible, no assumption of a street-number-plus-street-name shape), city, postal_code (free text, not zip-shaped), region_code (FK → shared.administrative_region.iso_3166_2, nullable, ON DELETE SET NULL), and country_code (FK → shared.country.iso_alpha2, nullable, ON DELETE SET NULL). This lets a site work in any country rather than assuming US address structure. Net effect versus v1: −1 JSONB column, +7 replacement address columns, +2 new global-derivation columns (climate_zone_code, measurement_system) = net +8 columns (21 → 29).

Decision B — Currency/locale resolved via join, not stored: site does not carry its own currency or locale columns. Both are resolved at query/service time via country_code joining to shared.country.default_currency_code / shared.country.default_locale_code. This avoids duplicating data that the shared module (module #3) already owns.

Decision C — measurement_system is a plain CHECK column, not an FK: measurement_system (CHECK metric/imperial or NULL) has no FK target because shared.country carries no per-country unit-system lookup to join against. The service layer is responsible for defaulting it from country_code at site-creation time, using an in-code map (e.g. US/LR/MM → imperial, else metric). Rejected alternative: adding a measurement_system column to shared.country itself — rejected because shared is already LOCKED, and reopening a locked module to add one column was judged disproportionate; logged to OPEN_ITEMS as a future option instead.

Decision D — climate_zone_code as a single nullable FK, system-appropriateness left to UI/service layer: climate_zone_code → shared.climate_zone.code is a single FK. Which climate-zone system is appropriate for a given site's country (USDA for the US, RHS for the UK, etc.) is not DB-enforced — there is no country-to-preferred-system mapping in shared for the database to check against. This is the same category of gap as shared.plant_climate_zone.system from module #3's lock (see Decision D under entry #17 above); in both cases the DB stores the value but the application picks the right system based on country_code.

Decision E — New DB-enforceable CHECK, chk_site_region_country_match: (region_code IS NULL OR (country_code IS NOT NULL AND left(region_code,2) = country_code)). Unlike the climate-zone-system gap in Decision D (and its module #3 analog), this check closes cleanly in the database, because administrative_region.iso_3166_2 values always embed their country prefix in the value itself (e.g. 'DE-BW' for Baden-Württemberg, Germany) — so consistency between a site's region and country can be verified with a simple string comparison, with no external system-mapping table required.

Decision F — is_primary, not is_default: the boolean flag marking a tenant's primary site is named is_primary rather than is_default, for naming consistency with the existing identity.user_site_assignment.is_primary_site column.

All 8 named CHECK constraints on site: chk_site_site_type (8 values), chk_site_status (3 values), chk_site_measurement_system, chk_site_is_primary_active (is_primary=false OR status='active'), chk_site_latitude (−90..90), chk_site_longitude (−180..180), chk_site_closed_after_opened (closed_at >= opened_at when both set), chk_site_region_country_match (Decision E, above).

Deferred FKs now unblocked, deliberately not wired this pass: site now exists as a valid FK target, unblocking four FKs that were previously deferred — platform.tenant.primary_site_id → multi_loc.site, identity.tenant_user.default_site_id → multi_loc.site, identity.user_site_assignment.site_id → multi_loc.site, and identity.user_permission_override.scope_id → multi_loc.site (when scope_type='site'). Wiring them requires reopening two already-locked modules (platform and identity), which is a separate, deliberate future pass, not this one. Logged to OPEN_ITEMS.

Deferred to v1.5, unchanged from v1: transfer/transfer_line (cross-site stock movement), site-level pricing/permission overrides, and a PostGIS geo-proximity index on latitude/longitude all remain out of scope for this pass, matching the v1 design's own deferral.

19. Autonomy-First Backfill — Canonical Pattern + Platform/Identity/Shared/Multi-Location Retrofit

Decided: 2026-07-06 (cross-cutting backfill across all 4 locked modules, designed and applied as one coherent proposal — see the retro-audit in OPEN_ITEMS that motivated it, and SCHEMA_DESIGN_RUNBOOK.md §0, the governing rule this backfill brings the 4 foundation modules into compliance with)

This is not a new module lock — it is a retrofit of 4 already-locked modules (platform, identity, shared, multi_loc) against the autonomy-first governing rule, designed once as a single canonical pattern so every future module (starting with the 13 nursery product modules) reuses the same shape rather than reinventing it per module.

The canonical pattern (the reusable standard)

Five pieces, applied selectively per table — not every table needs every piece; Section 0's own rule (a deliberate, recorded exception is valid; silence is not) applies here too.

  1. Agent-as-actor — not a new column, a rule: every action-attribution column resolves to identity.actor (the polymorphic root — actor_type IN ('user','service_account','agent')), never identity.identity_user directly. Naming convention going forward: <verb>_by_actor_id.
  2. Autonomy metadata — automation_source text NOT NULL DEFAULT 'human' CHECK (automation_source IN ('human','agent','system','seed')). No separate created_autonomously boolean — fully derivable from automation_source != 'human', and a second column would just be a second place for it to drift out of sync. is_verified boolean NOT NULL DEFAULT false where trust/accuracy matters (kept as-is — already a good, generic name, established by shared.plant before this pattern existed). confidence_score only where an agent produces a genuinely probabilistic output — not proposed for any of the 4 modules this pass since none had a clear case for it.
  3. Human-in-the-loop seam — review_status text NOT NULL DEFAULT 'not_required' CHECK (review_status IN ('not_required','pending','approved','rejected')) + review_reason text (nullable) + reviewed_by_actor_id uuid REFERENCES identity.actor(id) (nullable) + reviewed_at timestamptz (nullable). Models identity.access_request's existing shape — treated as the reference implementation, not a one-off.
  4. Decision provenance — decision_provenance (or, where the existing precedent already used a different name, e.g. sod_violation.decision_snapshot) jsonb, nullable, documented minimal shape {"rule_fired": string, "inputs": object, "confidence"?: number} (or a table-specific variant, documented inline). Reuse an existing metadata/similar jsonb column instead of adding a new one wherever one already exists (platform.tenant_entitlement.metadata) — document the required shape there rather than duplicating the column.
  5. Agent-safe state machines — not a column, a documentation requirement: any status/lifecycle CHECK's transitions, idempotency, and reversibility (or explicit one-way-door flag) must be recorded in module_spec/<module>.md.

Enforcement of the automation_source != 'human' → decision_provenance populated rule is app-enforced, not a hard DB CHECK (Open Question 1 from the design proposal, resolved): the boundary between "an agent did something deterministic" and "an agent made a judgment call needing provenance" isn't crisp yet with only 4 modules' worth of real cases. Documented as an explicit service-layer invariant, revisit as a hard CHECK once more modules have used the pattern.

Per-module application

platform (+6 cols, 23 tables / 403 cols): operator_audit_log.operator_user_id and tenant_internal_activity.performed_by_user_id retargeted from identity.identity_user to identity.actor — zero-risk, zero-backfill, since identity_user.id is itself a FK to actor.id (shared-PK pattern), so every existing value already satisfied the new target. tenant_entitlement.granted_by_user_id renamed to granted_by_actor_id (Open Question 3, resolved: renamed, not deferred — grep confirmed all references were contained to this repo: 1 Drizzle field, 1 service-layer write, one test file, ~7 doc files, no external consumers) and gained automation_source (its existing metadata jsonb column doubles as the decision-provenance carrier, no new column). promo_code gained automation_source. contract gained the full human-in-the-loop seam (review_status/review_reason/reviewed_by_actor_id/reviewed_at) — high-stakes legal terms, future-proofed for agent-drafted terms needing sign-off, even though every contract today is human-authored.

shared (+7 cols, 10 tables / 108 cols): plant_common_name and plant_climate_zone gained data_source/is_verified matching plant's exact shape — nullable data_source (not NOT NULL DEFAULT), same 3-value CHECK, because module-internal consistency with the already-locked plant sibling outweighs strict adherence to the new canonical automation_source name (that name is the standard for every other module going forward). All 3 plant tables gained nullable created_by_actor_id. Backfill: all 70 existing plant_common_name rows and 68 existing plant_climate_zone rows were explicitly UPDATEd to data_source='seed', is_verified=true in the same migration — the column's own is_verified DEFAULT false is correct for future rows but would have wrongly marked these already-known-good seed rows as unverified.

multi_loc (+8 cols, 1 table / 37 cols): site gained the full canonical set — created_by_actor_id/updated_by_actor_id, automation_source, decision_provenance (field-level, since climate_zone_code and measurement_system can be independently auto-derived from country_code — a single row-level flag can't express mixed provenance within one row), and the full human-in-the-loop seam. The review seam was a deliberate scope addition beyond the literal per-module ask (Open Question 4, resolved: kept — country_code cascades to currency/locale/units/climate and is a deferred FK target for 4 columns in 2 other modules, giving a wrong agent-proposed value outsized downstream reach). Zero backfill risk — no MultiLocService exists yet and the table had 0 rows.

identity (+2 cols, 34 tables / 371 cols): role gained requires_approval_for_agents (boolean, DEFAULT false — zero behavior change for every existing role) — the schema-level piece of an "agent-elevation approval gate." No new column implements the gate itself — identity.access_request already has the exact shape needed; the actual fix is a service-layer rule (assignRole() should require routing through access_request when the assignee is an agent AND the target role has requires_approval_for_agents=true), out of scope for this schema-only pass. sod_violation gained decision_snapshot (jsonb, nullable, Open Question 2 resolved: column shipped now, exact key shape deliberately deferred to whoever next builds SoD detection's next iteration — intent documented as "permission-set/role-combination active at detection time").

Risk-management ordering, not a technical dependency (all 4 modules' additions are independent of each other): platform's FK retargets first (genuinely zero-risk, fixes the most concrete named gap), then shared (best-precedented, simple backfill), then multi_loc (newest, no real data, no service layer), then identity last — not because its 2 additions are riskier, but because it's the authorization backbone, and the pattern deserved validating on 3 lower-stakes modules first.

Verification

Independent Section 4 audit + new tests per module, run by fresh agents with no stake in the build (same adversarial-verification pattern used for the multi_loc module lock). All 4 modules: zero FK/CHECK/nullability drift found. New tests added: platform +10, shared +19, multi_loc +5, identity +4 (33 new, on top of the 159/159 pre-backfill baseline → 192/192 passing, later independently reconfirmed at 197/197 once platform's own earlier H2/I3/D6 rename tests are counted in the baseline — see the module-specific test files for the exact breakdown). One methodological note: concurrent parallel verification agents running jest against the same live shared dev Postgres instance produced transient, non-reproducible failures purely from resource/data contention — resolved by a final, single, sequential full-suite run (197/197, repeated 3× clean) rather than trusting any individual concurrent agent's "it failed" signal.

Retro-audit closure

The 6 OPEN_ITEMS rows logged by the 2026-07-06 autonomy retro-audit (the gap analysis that motivated this backfill) are closed by the additions above — see OPEN_ITEMS.md for the closure notes. Two things the retro-audit flagged are not resolved by this pass, by design: (1) identity.sod_violation.decision_snapshot's exact key shape (deliberately deferred); (2) the actual service-layer enforcement of role.requires_approval_for_agents and of tenant_entitlement/promo_code/contract's new autonomy columns (schema-only pass — no service-layer code was written or changed).

20. Part D Capability-Discovery Walk — Run Against All 4 Locked Modules

Decided: 2026-07-06 (discovery + record only — no schema/module changes; closes the "4 locked modules never run through Part D" gap flagged when Part D was codified into SCHEMA_DESIGN_RUNBOOK.md §2.2.1)

Entry #19 gave platform/identity/shared/multi_loc the schema-translation half of the AI Capability Plane pass. This entry records the other half: each module run through AI_CAPABILITY_PLANE.md Part D's 15-question capability-discovery walk, by fresh agents with no stake in the original build (same adversarial pattern used throughout this pipeline). Full D1–D15 answers, per-action D7 autonomy-boundary tables, and ruled-out capabilities are recorded in each module's own spec, not restated here: module_spec/platform.md §14, module_spec/identity.md §20, module_spec/shared.md §9, module_spec/multi_loc.md §9.

Capabilities that apply, by module (Part B labels; full detail in each module_spec):

  • platform: B1 (narrow — operator forms only), B3, B4, B5, B6, B11, B13; infra A4, A11, A13.
  • identity: B3, B4, B5, B9, B11, B13; infra A4, A5, A11, A12, A13, A14 — the richest of the four, consistent with already having first-class agent-identity tables.
  • shared: B1d, B3, B5, B11, B13; infra A4, A11, A12, A13, C8 — narrow and centered entirely on the already-locked AI→Shared plant-enrichment seam; most tenant-operational Part D questions honestly ruled out (non-tenant-scoped reference data has no capture bar, routing, or offline/channel-sync concern).
  • multi_loc: B3, B5, B13; infra A4, A11, A12, A13 — the fewest hooks of the four, honestly reflecting that no MultiLocService or AI write path exists yet for this table.

Each module also ruled out a substantial list of capabilities with a stated reason (not silently skipped) — see the "Capabilities Recorded" subsection of each module_spec for the full list.

Real gaps found — flagged and logged, none built this pass:

  1. [URGENT] shared — no review/approval seam on AI-write-target plant tables. plant/plant_common_name/plant_climate_zone have is_verified (bare boolean) but no review_status/reviewed_by_actor_id/reviewed_at — unlike the richer seam platform.contract got in entry #19. Higher-stakes here than a tenant-scoped equivalent: shared.plant is read cross-tenant, so an unreviewed bad AI-generated row is visible to every tenant simultaneously. Flagged urgent specifically because a future module's (e.g. crm's) own AI-write seam into shared should have this precedent already established, not invented ad hoc. Not built this pass — logged to OPEN_ITEMS.md.
  2. [URGENT, reconfirms an existing item] identity — role.requires_approval_for_agents (added in entry #19) is still unenforced. assignRole() does not branch on it. This Part D walk found that a large fraction of identity's own D7 "needs-approval" classifications for agent actions depend on this flag actually being checked somewhere — raising the existing OPEN_ITEMS row's practical urgency rather than opening a new one.
  3. [Deferrable] platform — no home (CHECK value or table) for a system/agent-detected finding (anomaly, reconciliation break) distinct from an operator-performed action; tenant_internal_activity/operator_audit_log are both scoped to human/operator actions today.
  4. [Deferrable ×3] identity — role_assignment has no terminal status/sweep when ends_at lapses (unlike invitation/access_request/support_access_grant/api_key, which all do); no rate-limiting/lockout state exists for repeated auth failures (may belong to Supabase Auth, not identity — needs a design decision, not just a column); no decision_snapshot-style structured "before" state for tenant_security_policy changes.
  5. [Deferrable ×2] shared — no scheduled consistency-check job for the two already-known, DB-unenforceable invariants (plant_climate_zone.system-vs-code-prefix; country⇄locale circularity); no defined AI-write rollback-window policy (moot until a real downstream FK consumer like inventory exists).
  6. multi_loc — zero new gaps found. The two limitations this walk surfaced (the unwired primary_site_id FK; no canonical country→climate-zone-system mapping) are both pre-existing, already-tracked OPEN_ITEMS from the module's original lock — not new findings.

All gap details, exact missing fields, and triggers are in OPEN_ITEMS.md, not duplicated here.

Process note: every module's honest "ruled out" answers were recorded, not just what applies — most modules do not trigger anywhere near all 19 Part B capabilities, and forcing a fit would have been worse than an accurate "none." No schema, migration, or service-layer file was touched in this pass; the 6 real gaps above are the concrete, evidence-based bar crm's own Part D walk (and any real-gap findings it produces) will be compared against for consistency.

21. Urgent Part D Findings Closed — Shared Plant Review Seam + Identity Agent-Approval Gate

Decided: 2026-07-06 (both fixes built, tested, and locked — closes the two [URGENT] findings from entry #20)

Entry #20's Part D walk flagged two findings as urgent rather than deferrable, on the reasoning that both were foundational precedents a future product module (crm or otherwise) would look to as the working example for "how does Vrida handle this." Both are now closed.

FIX 1 — shared.plant/plant_common_name/plant_climate_zone review seam (schema). All 3 tables gained review_status (text, CHECK IN not_required/pending/approved/rejected, DEFAULT not_required), review_reason, reviewed_by_actor_id (FK → identity.actor), reviewed_at — the same seam shape platform.contract got in entry #19. A new CHECK per table (is_verified = false OR review_status IN ('not_required','approved')) additionally makes the trust flag and the review workflow mutually consistent at the DB level, which platform.contract's own seam does not yet have — a stronger result than the precedent it followed. A partial index on review_status = 'pending' per table supports the future review queue. Nullable/defaulted: all 252 existing rows (114 plant + 70 plant_common_name + 68 plant_climate_zone, all data_source='seed') satisfy the new CHECK via the not_required default — zero backfill required, verified directly against the live DB. Hand-written migration 20260706040000_shared_plant_review_seam.sql. See schema_docs/shared.md, module_spec/shared.md §9 gap 1 (closed).

FIX 2 — IdentityService.assignRole() agent-approval gate (service). role.requires_approval_for_agents (schema-only since entry #19, DR-30) is now enforced: when the assignee is an agent actor and the target role has requires_approval_for_agents=true, assignRole() routes through the existing submitAccessRequest() on-approval seam (DR-22) instead of assigning directly. The gate is agent-only — human and service_account assignees always assign directly, even to the same role.

  • Loop-prevention discovery: assignRole() has exactly one production caller — approveAccessRequest() itself, which calls it to finalize an approved role request. Without an escape hatch, the new gate would also fire on that call, re-submitting the just-approved request back into access_request and never actually assigning — an infinite loop. Fixed with a skipApprovalGate boolean, set only at that one call site (that call IS the human-reviewed approval the gate exists to enforce).
  • Return type changed: assignRole() now returns {status: 'assigned' | 'pending_approval', id: string} instead of a bare Promise<string>. A string that means "role_assignment.id" in one branch and "access_request.id" in the other is an agent-bug waiting to happen — callers (especially autonomous agent callers) must branch on status to know which table id refers to. The one production caller (approveAccessRequest(), via skipApprovalGate: true) doesn't consume the return value, so this was a non-breaking change in practice; one test (identity-governance.spec.ts, SoD test A5) that captured the return value as a bare string was updated to match.
  • Tests added (identity-governance.spec.ts C6–C8): agent + gated role → {status:'pending_approval'}, no role_assignment row created; agent + ungated role → {status:'assigned'}, direct assignment; human + gated role → {status:'assigned'} (proves the gate is agent-only, not role-only).

See module_spec/identity.md §8 (Agent-elevation approval gate) and §20 (D4/D7/D11, Gap 1 — closed).

Process note: FIX 1 (schema, reopening a locked module) went through propose+STOP before any code was written — same rigor as any locked-module reopen. FIX 2 (service layer, enforcing an already-schema-approved design) went through a lighter "show the logic before finalizing" checkpoint, since the schema decision (requires_approval_for_agents) was already locked in entry #19 — only the enforcement logic and its return-type shape were new judgment calls. This distinction (schema reopen = full propose+STOP; service layer enforcing an already-locked schema = lighter checkpoint) is the reusable pattern for similar situations going forward.

22. Agent-Authority Passport (A5) — identity.agent_duty_grant

Decided: 2026-07-06 (proposed + full runbook build, reopening the locked identity module — the security model crm's and future modules' agents will run within)

AI_CAPABILITY_PLANE.md A5 ("agent identity & permission passport") calls for a per-agent record of which tools/actions it may use, how autonomously (draft-only / needs-approval / may-act-alone), and within what dollar/quantity limits — the mechanism to literally "assign agents their duties." Identity had the pieces A5 assumes (agent identity, skill/permission dual-check, the FIX2 agent-elevation gate) but no schema for per-action authority or limits.

New table: identity.agent_duty_grant (+1 table, +25 cols). Per (agent_identity, permission) authority grant: authority_level (may_act_alone/draft_only/needs_approval; 'never' = no row), spend_limit_cents+spend_limit_currency_code (FK → shared.currency), quantity_limit, scope_type/scope_id(FK → multi_loc.site)/scope_code, status (active/suspended/revoked), grant/revoke actor attribution, automation_source, the standard review seam, decision_provenance jsonb. Additive: identity_access_event.event_type CHECK +3 values (agent_duty_granted/revoked/updated, 39→42). Zero columns touched on any existing table; zero backfill risk (net-new); zero changes to FIX2's assignRole() gate or its tests.

Consolidation pass (reuse-first) — 3 alternatives considered and rejected before proposing a new table:

  • Extend agent_skill_assignment: rejected — skill (competency, DR-25) is deliberately orthogonal to authorization; its 6 categories are too coarse to express "draft POs ≤$2000 but never touch vendor bank data."
  • Attach limits to role_assignment: rejected — a role bundles many permissions (role_permission M:N); a single per-role-assignment limit can't differentiate authority levels across different actions within the same role.
  • Retarget user_permission_override (closest structural precedent — per-actor-per-permission, scoped, with an effect): rejected — its tenant_user_id FK is enforced human-only (DR-26, trg_tenant_user_actor_type_check), so retargeting would be a breaking change to a locked, tested table; and semantically it answers "is X allowed at all" (allow/deny override), a different question from "how autonomously, once already allowed."

One new table is justified by genuine own cardinality (agent × permission, independent of role bundling) and genuine own lifecycle (a duty can be granted/revoked/limit-adjusted independently of the underlying role assignment).

Subsumes, does not conflict with, FIX2 (entry #21): role.requires_approval_for_agents + assignRole()'s gate governs the moment an agent comes to HOLD a role at all (grant-time gate). agent_duty_grant governs, for a permission the agent already holds, how autonomously it may exercise it (execution-time governance record). Sequential, not competing.

DR-31 (unique-index NULL-uniqueness bug, caught by independent adversarial verification before any migration was written): the original proposed unique index included scope_id/scope_code, claiming to mirror user_permission_override_unique. Two independent reviewers (one reproducing it empirically in Postgres) found this false and broken — Postgres treats NULL as distinct in unique indexes, so two scope_type='tenant' grants for the same (agent, permission) would both insert successfully, silently defeating the one-active-grant invariant. The real user_permission_override_unique shape excludes those columns. Fixed to (agent_identity_id, permission_id, scope_type) WHERE status='active' before the migration was written; regression-tested (identity-agent-duty.spec.ts D1 — a second active tenant-scoped grant for the same agent+permission is rejected).

DR-32 (deferred-FK reconsideration, caught by the same verification pass): scope_id's FK to multi_loc.site was originally proposed as deferred, citing user_permission_override.scope_id's precedent — but that precedent's justification (multi_loc not yet locked at the time user_permission_override was designed) no longer applies; multi_loc is locked (module #4). Fixed: scope_id is a real, enforced FK.

Independent verification (two rounds, not self-graded): the proposal itself was reviewed by two independent agents before build (one adversarially re-checking the reuse-first reasoning — caught DR-31; one re-running Section 4 + Part D from scratch — independently caught both DR-31 and DR-32). After build, tests (identity-agent-duty.spec.ts, 10 new tests) and a live-DDL re-audit confirmed both fixes landed correctly (unique index shape, real FK) — full suite 210/210 green across two consecutive runs.

Deferred, logged to OPEN_ITEMS with explicit triggers:

  • grantAgentDuty()/revokeAgentDuty()/checkAgentDutyAuthority() service methods — schema-only this pass.
  • Outbound integration/external-tool scope — no registry exists to FK against.
  • Cumulative/period spend tracking — a real, currently-unmitigated SECURITY LIMITATION: spend_limit_cents is per-action only; it provides no protection against volume-based abuse (many small actions each under the ceiling). Deferred to a future ai-schema usage ledger, not solved by this table.
  • Delegating-human semantics: reuses agent_identity.created_by_actor_id (consistent with DR-24's "organizational not personal ownership" stance) rather than adding a new mutable owner_actor_id — deferred until a real ownership-transfer need is evidenced.

See schema_docs/identity.md (agent_duty_grant section, DR-31/DR-32) and module_spec/identity.md §8 ("Agent-authority passport (A5)").

23. crm Module (First Product Module) — Autonomy-Native, Global-First Design

Decided: 2026-07-06 (full runbook build: Part D walk, autonomy schema-translation, schema design + Section 4 audit, migration applied, docs to follow — the first of the 13 nursery-vertical PRODUCT modules to actually build, following platform/identity/shared/multi_loc, all of which were foundation/service-layer modules)

Scope: 13 tables, 189 columns — customer (32), contact (15), address (15), customer_group (10), customer_note (10), customer_merge (11), customer_merge_candidate (15), customer_consent (12), customer_tax_certificate (19), customer_segment_definition (10), customer_segment_membership (17), customer_tag_assignment (8), customer_task (15). Migration 20260706060000_crm_module.sql, applied live (schema crm verified via information_schema.columns). Drizzle schema at packages/db/src/schema/crm/{_schema,customer,interaction,merge,consent_tax,segment,index}.ts.

v1 reconciliation approach: crm had a full v1 spec/schema to reconcile against, unlike the from-scratch foundation modules. The reconciliation pattern used throughout: keep what v1 got right (single customer table with a customer_type discriminator rather than splitting individual/business; the merge-candidate-then-merge two-table lifecycle), fix what v1 left inconsistent (drop credit_terms/credit_limit_cents, which v1's own docs already assigned to Billing but never actually removed from the customer columns — DR-35), globalize what v1 hard-coded to the US (address and tax-certificate jurisdiction fields — DR-37), and apply the autonomy-first pattern (established in entries #19–#22) fresh to every table rather than retrofitting it later.

Significant, reusable discovery — consumer/rewards/offers/search/files are NOT actually built in v2: docs/modules/MODULE_INDEX.md and CROSS_MODULE_CONTRACTS.md describe consumer, rewards, and offers as "locked" (dated 2026-06-11/12) and list crm.customer.consumer_id → consumer.consumer as an FK marked "READY." Live verification (psql \dn against the local Supabase instance) shows only identity, multi_loc, platform, shared, and now crm exist as schemas — consumer, rewards, offers, search, and files do not exist anywhere in this v2 database, and no corresponding schema_docs/*.md files exist on disk for them either. This confirms those MODULE_INDEX/CROSS_MODULE_CONTRACTS rows are stale v1/pre-pivot documentation, predating the actual v2 rebuild order (platform → identity → shared → multi_loc → crm). Every module going forward should independently verify a claimed dependency actually exists live before wiring an FK to it — a documented "locked" status in these two files is not sufficient evidence on its own until the v2 rebuild catches up. Five forward-refs were deferred as a direct consequence of this finding: customer.consumer_id (plain UUID, no FK), customer.search_vector (generated tsvector column not added at all), customer_tax_certificate.document_ref (no FK), all logged to OPEN_ITEMS.

Design rationale (DR-33 through DR-47):

  • DR-33 — email stays non-unique. Real-world duplicate emails happen legitimately (a walk-in POS customer later creates an online account with the same email); a hard unique constraint would block creation and break offline POS, which cannot check uniqueness against the server. Dedup is handled entirely through the explicit customer_merge_candidate → customer_merge workflow, never a DB constraint.
  • DR-34 — customer.consumer_id is a deferred forward-ref. Plain nullable UUID, no FK — the consumer schema does not exist in v2 (see the discovery above). Same reasoning extends to search_vector (no search schema) and customer_tax_certificate.document_ref (no files schema).
  • DR-35 — credit_terms/credit_limit_cents removed entirely from customer. MODULE_INDEX.md already assigns "customer credit" to the not-yet-built Billing module; v1's schema doc had already split charge_account out to Billing but left these two columns behind as an incomplete migration. Corrected here — Billing's domain, not crm's.
  • DR-36 — customer.is_verified DEFAULTs true, deviating from shared.plant's false default. Staff/POS/import-entered data is presumptively trustworthy; the exception is an AI enrichment agent's own written fields, which should start unverified and be tracked per-field via decision_provenance — the same documented workaround multi_loc.site.decision_provenance already established for climate_zone_code/measurement_system, since a single row-level is_verified can't express mixed per-field trust.
  • DR-37 — Global address/jurisdiction shape. crm.address and customer_tax_certificate's issuing-jurisdiction fields both use flat address lines plus natural-key FKs into shared.country (iso_alpha2, char(2)) and shared.administrative_region (iso_3166_2, text), replacing v1's US-only us_state/country_id shape. Mirrors multi_loc.site's exact precedent, including the region/country consistency CHECK (region_code IS NULL OR (country_code IS NOT NULL AND left(region_code, 2) = country_code)) and its nullability (both nullable, matching site, not v1's NOT NULL country_id).
  • DR-38 — customer_note/customer_task have no review_status. D7 classifies logging an observation or suggesting a follow-up as low-blast-radius, additive actions — a note is append-only, and a task is inert until acted on (dismissing/completing a task IS its review mechanism). A formal review gate would be bureaucratic overhead disproportionate to the risk. Deliberate exception, not an oversight; the task's own open/completed/dismissed state machine substitutes.
  • DR-39 — site_id on customer_note/customer_task. A narrow, deliberate exception to "master data doesn't carry site_id" (SCHEMA_CONVENTIONS.md) — these are event/interaction records, not master data, and multi-site tenants have a real need to know which location an interaction happened at or a task should be handled from.
  • DR-41 — customer_merge_candidate kept separate from customer_merge, not unified with a review_status column bolted onto the append-only audit table. Most candidates are rejected and never become a customer_merge row — genuinely different lifecycle (mutable pending→approved/rejected vs. permanent audit fact) and cardinality (most candidates never produce a merge). customer_merge_candidate.review_status DEFAULTs 'pending' (not 'not_required' like every other table) since every row there exists BECAUSE it needs review; merge execution itself (D7) is always needs-approval, never may-act-alone.
  • DR-42 — customer_consent has no review seam at all. Consent is a captured FACT — the customer's own opt-in/opt-out action — not an inference; there is nothing to review-gate structurally. D7 rule: consent must NEVER be AI-initiated.
  • DR-43 — customer_tax_certificate.status DEFAULTs 'pending_review', changed from v1's 'active' default. An unverified certificate — especially one a future OCR-extraction agent might draft from a photo — must never default to trusted status.
  • DR-44 — customer_tax_certificate reuses its existing status/verified_by_actor_id/verified_at columns as the review seam, rather than adding a parallel review_status/reviewed_by_actor_id/reviewed_at set — v1 already built an equivalent gate; a duplicate would be redundant structure. Also gained two partial unique indexes (customer_tax_certificate_no_region_unique, customer_tax_certificate_with_region_unique), splitting on issuing_region_code IS NULL vs. IS NOT NULL to avoid the NULL-in-multi-column-unique trap — the same bug class DR-31 caught in identity.agent_duty_grant (entry #22).
  • DR-45 — customer_segment_definition mirrors identity.role's mixed-scope pattern exactly. Nullable tenant_id (NULL = Vrida-shipped built-in segment like vip/at_risk/seasonal/wholesale_like; populated = tenant-custom), the same two-partial-unique-index shape ((tenant_id, code) WHERE deleted_at IS NULL and (code) WHERE tenant_id IS NULL AND deleted_at IS NULL), and the same mixed-scope RLS disjunction (tenant_id IS NULL OR tenant_id = current_setting(...)). A proven, already-audited pattern reused, not invented fresh. No autonomy columns — catalog definitions are human/Vrida-curated, never agent-written.
  • DR-46 — Tags and segments kept as two separate tables, per an explicit resolution reconsidering an earlier draft that had proposed unifying them. customer_segment_membership is computed/analytical (agent-assigned, confidence-scored, provenance-tracked, drawn from the customer_segment_definition catalog); customer_tag_assignment is human free-form labeling (no catalog, no confidence, no review, ad-hoc staff-typed text, soft-deleted rather than append-only since removing a tag is a light, reversible action). Different lifecycle, different authority, different provenance.
  • DR-47 — customer_segment_membership uses a stored status column (active/expired), not a partial index predicate on now(). Postgres requires index predicates to be IMMUTABLE; now() is STABLE, and WHERE expires_at > now() was confirmed empirically to fail (ERROR: functions in index predicate must be marked IMMUTABLE) before this migration was written. Fixed to match the existing convention identity.role_assignment.ends_at/identity.agent_duty_grant.ends_at already use: checked on-read or by a service-layer sweep, never computed live inside a partial index.

(DR-40 is folded into DR-38 — a task's own open/completed/dismissed state machine IS its review mechanism; no separate entry.)

Agent-authority mapping (crm → identity.agent_duty_grant): crm introduces no new authority mechanism — it is a pure consumer of the A5 passport (entry #22). Each autonomous crm action maps to an illustrative identity.permission code (module_code crm, confirmed live to need zero identity-module changes since permission.module_code has no CHECK constraint) and an authority_level:

crm action Permission code Authority level Limit dimension
Enrich a customer field crm:customer:enrich draft_only (or may_act_alone above confidence threshold for non-contact fields) quantity_limit; spend_limit_cents typically NULL
Compute a segment membership crm:customer_segment:compute may_act_alone above threshold quantity_limit (batch size)
Propose a merge candidate crm:customer_merge_candidate:propose draft_only quantity_limit
Execute a merge crm:customer_merge:execute needs_approval (always) N/A — gated by authority_level alone
Create a follow-up task crm:customer_task:create draft_only quantity_limit

crm is the first module where agent_duty_grant.spend_limit_cents is essentially always NULL — its autonomous actions are volume-bounded (quantity_limit), not money-bounded — a useful precedent for future non-transactional modules.

Part D summary: applies D1, D3, D4, D5, D6, D7 (the load-bearing question), D8, D9, D11, D14, D15; honestly ruled out D2, D10 (covered by D7/merge-reversal), D12, D13, and the full B2/B7/B8/B9/B12/B14–B20 set (campaigns/loyalty/credit belong to other modules; bulk import is an existing cross-cutting capability crm merely consumes). The D7 autonomy-boundary table — the module's central design artifact — is recorded in full in module_spec/crm.md, not restated here; its conclusions are summarized in the agent-authority mapping and DR entries above (may-act-alone data entry vs. draft-only enrichment vs. always-needs-approval merge execution and tax-certificate verification vs. never-AI-initiated consent).

Deferred, logged to OPEN_ITEMS with explicit triggers (6 rows, all attributed to crm, all citing this entry): the merge-reversal 24-hour window (service-layer, not schema); the customer.consumer_id forward-ref (blocked on the consumer module); customer.search_vector (blocked on the search module); customer_tax_certificate.document_ref (blocked on the files module); the entire CrmService layer (schema-only this pass, same pattern as agent_duty_grant's deferred service methods, entry #22); and the Vrida-default segment catalog (vip/at_risk/seasonal/wholesale_like) not yet seeded.

See schema_docs/crm.md and module_spec/crm.md §D7/§14 (Part D + autonomy detail, once written).

24. inventory Module (Module #12) — First shared.plant Consumer, Biggest Module

Decided: 2026-07-06 (full runbook build: Part D walk, autonomy schema-translation, schema design + Section 4 audit, migration applied, docs to follow — the second of the 13 nursery-vertical PRODUCT modules to actually build, following platform/identity/shared/multi_loc/crm)

Scope: 24 tables, 335 columns — the biggest module built so far. Migration 20260706070000_inventory_module.sql, applied live (schema inventory verified via information_schema.columns: 24 tables, 335 columns, all 24 with RLS enabled). Drizzle schema at packages/db/src/schema/inventory/ (9 files: _schema.ts, catalog.ts, variant_structure.ts, location.ts, stock.ts, count.ts, lot.ts, kit.ts, merge.ts).

Table-by-table breakdown (24 tables, grouped):

  • Catalog (8): item — the core product record, first real FK consumer of shared.plant; item_variant; category; item_category (hard-delete join, no updated_at); tag; item_tag (hard-delete join, no updated_at); barcode; item_image.
  • Variant structure (2): option_type; variant_option.
  • Locations (1): inventory_location.
  • Stock (6): stock; stock_movement (immutable append-only, no updated_at); stock_movement_line (immutable append-only, no updated_at); stock_reservation; stock_adjustment_reason; stock_adjustment_request (NEW this pass).
  • Counts (2): stock_count; stock_count_line.
  • Lots (2): lot; stock_lot.
  • Kits (1): kit_component.
  • Merge (2, NEW this pass, build-now): item_merge_candidate; item_merge (immutable append-only, no updated_at).

Of the 24 tables, 19 carry the set_updated_at trigger; the other 5 correctly do not — stock_movement, stock_movement_line, item_merge (immutable append-only audit facts with no updated_at column at all) plus item_category, item_tag (hard-delete join tables, no updated_at, matching v1's own convention).

v1 reconciliation approach: unlike crm's stale pre-pivot placeholder, v1's locked docs/old/schema/schema_modules/schema_inventory.md (2026-06-09) already specified 21 tables / 238 columns for inventory in the exact same vertical-neutral, post-pivot design — just pre-shared.plant and pre-autonomy. This build's delta: +3 tables (21→24: stock_adjustment_request, item_merge_candidate, item_merge), +97 columns (238→335).

Key design decisions:

  • Decision — item.plant_id is a nullable uuid FK → shared.plant.id (ON DELETE SET NULL), guarded by chk_item_plant_id_item_type: plant_id IS NULL OR item_type = 'plant'. Why: inventory is the first module to actually consume shared.plant as a real FK target rather than a forward-ref placeholder — a hard_good item must never carry a plant reference, but a plant item may legitimately have none (shared.plant's 114-plant seed doesn't cover every real SKU a nursery stocks). Rejected: making plant_id required for item_type='plant' rows — would break on any plant SKU not yet in the seeded taxonomy. Guard: live-tested — inserting a hard_good item with plant_id set is rejected by the CHECK.
  • Decision — UOM columns retyped from v1's assumed uuid to text, FK → shared.unit_of_measure.code. sell_uom_code, stock_uom_code, purchase_uom_code, weight_uom_code (new upgrade from v1's free-text-only weight_uom), and inventory_location.capacity_uom_code are all text FKs against the natural-key code column. Why: shared.unit_of_measure's actual locked PK shape is code (text), not a surrogate uuid — v1 predates shared and guessed wrong. sell_uom_code/stock_uom_code/currency_code are ON DELETE RESTRICT (breaking these mid-flight corrupts pricing/stock math); purchase_uom_code/weight_uom_code/capacity_uom_code are ON DELETE SET NULL (softer, informational). item_variant.currency_code gained a real FK → shared.currency.iso_code (ON DELETE RESTRICT) — v1 left this unenforced.
  • Decision — stock_adjustment_request dedup uses ONE partial unique index, not a two-index split that would let a located and unlocated pending proposal coexist for the same variant: stock_adjustment_request_one_pending_unique UNIQUE btree (tenant_id, site_id, variant_id) WHERE review_status = 'pending'. Why: an earlier draft used two partial indexes (one keyed with inventory_location_id, one without), which would have allowed two simultaneous pending proposals for the same variant at the same site as long as one had a location and the other didn't — a real dedup gap. Guard: live-tested — a second pending proposal for the same (tenant, site, variant), even with a different inventory_location_id (NULL vs. a real location), is rejected with duplicate key value violates unique constraint "stock_adjustment_request_one_pending_unique".
  • Decision — item_merge_candidate/item_merge mirror crm.customer_merge_candidate/customer_merge's propose/execute split, review_status default 'pending', same decision_provenance shape. One deliberate improvement over the crm precedent: crm.customer_merge_candidate shipped with no dedup protection at all — a real gap crm's own post-build Section 4 audit found and logged to OPEN_ITEMS, never fixed there (see docs/database/schema_docs/crm.md's open-items list). item_merge_candidate closes this from day 1 with two guards: chk_item_merge_candidate_pair_order CHECK (item_a_id < item_b_id) enforces canonical pair ordering, then item_merge_candidate_pending_pair_unique UNIQUE (tenant_id, item_a_id, item_b_id) WHERE review_status='pending' prevents duplicate/mirrored simultaneous proposals. Guard: live-tested — inserting the canonical-order pair succeeds; inserting the mirrored (reversed) pair is rejected by the CHECK before it even reaches the uniqueness check, which is correct and sufficient.
  • Decision — item.search_vector/item_variant.search_vector kept as real generated columns, not deferred. Both are GENERATED ALWAYS AS (to_tsvector(...)) STORED with GIN indexes (item_search_vector_idx, item_variant_search_vector_idx), matching v1's spec exactly. Why not deferred like crm's customer.search_vector: a generated tsvector column has zero dependency on a search schema existing — it's self-contained Postgres FTS, not a forward-ref FK. This was already part of the pre-existing 238-column v1 baseline this build's delta is measured against, so keeping it is continuity, not scope creep.
  • Decision — stock_adjustment_request.estimated_impact_cents (bigint, nullable) — enables identity.agent_duty_grant.spend_limit_cents enforcement for stock-adjustment proposals. Why: unlike crm, where spend_limit_cents was "essentially always NULL" (crm's autonomous actions are volume-bounded, not money-bounded — entry #23), a stock adjustment directly changes balance-sheet valuation even with no external payment involved, so inventory is the first module to give this identity column a real, populated meaning.
  • Decision — stock.last_movement_at (timestamptz, nullable) — a maintained cache column giving Pricing/Reporting a cheap dead-stock/aging signal. Why: inventory.stock_changed fires on every movement, not on aging thresholds — nothing else in the schema gave downstream modules a signal for "how long has this sat here."
  • Decision — stock_movement_line.data_source/is_verified use the established vocabulary ('seed','ai_generated','manual'), identical to shared.plant's own CHECK (verified live via pg_constraint to match exactly). Rejected: an earlier draft's invented 'ocr' value — corrected before the migration was written, to keep one shared vocabulary across schemas rather than a module-local dialect.
  • Decision — stock_lot.condition_grade (text, CHECK A/B/C/cull) — closes the pre-pivot v1 feature spec's never-built "Plant condition grading" (module_specs/01_inventory.md Group 15.3).
  • Decision — stock_movement.photo_ref — plain nullable uuid, no FK. Why: genuine deferred forward-ref, same treatment as crm.customer.consumer_id — the files schema does not exist in v2 (verified live via \dn: only identity, multi_loc, platform, shared, crm, inventory exist as of this build, plus system schemas). Logged to OPEN_ITEMS, trigger: "when the files module is built."
  • Decision — all actor columns retargeted to identity.actor, not identity.identity_user: performed_by_actor_id (was performed_by), started_by_actor_id/reconciled_by_actor_id (was started_by/reconciled_by), plus every created_by_actor_id/updated_by_actor_id/reviewed_by_actor_id/proposed_by_actor_id/merged_by_actor_id/counted_by_actor_id introduced fresh this pass. Why: identity becomes a new dependency for inventory — the same canonical actor-attribution pattern crm established first (entry #23), now applied here.
  • Decision — decision_provenance JSONB (on 8 tables — item, item_variant, item_image, stock, stock_adjustment_request, stock_count, item_merge_candidate, item_merge; independent verification caught item_image/item_merge omitted from an earlier 6-table list, corrected here) documents two new keys per the AI_CAPABILITY_GAPS.md gap-rulings below: memory_refs (G5 — agent memory) and delegated_by_actor_id (G3 — multi-agent handoff). No new column or table for either — both are documented JSONB keys only, the same pattern established for prior modules.
  • Decision — item_merge records the merge fact but does not re-point the source item's variant subtree (item_variant, stock, stock_movement_line, lot, barcode, option_type, item_category, item_tag, item_image, kit_component) to the target item. Why: found by independent adversarial verification — a larger-blast-radius analogue of the already-logged crm.customer_merge gap (which doesn't re-point contact/address). Re-pointing an entire variant subtree is service-layer data-migration logic, not something a schema CHECK/trigger should do silently. Guard: logged to OPEN_ITEMS with an explicit trigger — InventoryService.executeMerge() must handle this re-pointing (or document why not) when built.

AI Capability Plane pass — full outcome:

Part D summary: applies D1, D3, D4, D5, D6, D7 (the load-bearing autonomy-boundary question), D8, D9, D11, D14, D15 (capture modality, touching G10). Honestly ruled out D2, D10, D12, D13 as not load-bearing for this module's design.

D7 autonomy-boundary table:

Action Authority
Draft a reorder suggestion draft_only
Propose a stock adjustment draft_only
Execute a stock adjustment needs_approval, always, never may-act-alone
Flag dead/aging stock for markdown draft_only (surfacing only — Pricing owns the write)
Suggest an item/plant taxonomy link draft_only
Record a movement from POS/PO/Orders event may_act_alone, automation_source='system'
Cycle-count reconciliation (review→reconciled) needs_approval, always (app-enforced state machine)
Kit BOM edits never (human-only)
Propose an item merge draft_only
Execute an item merge needs_approval, always, never may-act-alone
OCR-extracted receiving cost draft_only equivalent via is_verified=false

Agent-authority mapping (inventory → identity.agent_duty_grant): pure consumer of the A5 passport, no new mechanism, same as crm.

Inventory action Permission code Authority level Limit dimension
Suggest a reorder inventory:reorder:propose draft_only quantity_limit
Propose a stock adjustment inventory:stock_adjustment:propose draft_only quantity_limit + spend_limit_cents
Execute a stock adjustment inventory:stock_adjustment:execute needs_approval N/A
Propose an item merge inventory:item_merge:propose draft_only quantity_limit
Execute an item merge inventory:item_merge:execute needs_approval N/A

No rows seeded — illustrative mapping only, same as identity's own A5 build (entry #22).

All six schema-translation questions (SCHEMA_DESIGN_RUNBOOK.md §2.2.2), applied per-table across the module: (1) autonomy tier (draft_only / may_act_alone / needs_approval / never) drove the review-gate shape on stock_adjustment_request, item_merge_candidate, stock_count; (2) multi-agent delegation-chain info routed through decision_provenance.delegated_by_actor_id (G3), no new table; (3) confidence/provenance columns (data_source, is_verified, decision_provenance) applied consistently everywhere an agent could plausibly write; (4) reversal window need assessed per table (merge execution reversible via item_merge.metadata snapshot, matching crm's pattern; stock adjustments are not separately reversible beyond a corrective adjustment); (5) spend/quantity limit dimensions identified (estimated_impact_cents for stock adjustments — new this pass, since crm had no comparable money-moving action); (6) agent memory need routed through decision_provenance.memory_refs (G5), no new table; (+1) capture modality (G10/D15) — OCR-extracted receiving cost noted as a draft_only-equivalent pattern via is_verified=false, not a new authority tier.

AI_CAPABILITY_GAPS.md — all 11 gaps, final rulings this pass:

Gap Ruling
G1 (agent-readable catalog flag) Ruled OUT for schema this pass, per the gaps doc's own closing scope note ("agentic commerce (G1)... not the schema-design runbook"). The prior OPEN_ITEMS row (line 104, logged when inventory.item didn't exist yet) is updated, not duplicated, to record this ruling and re-point its trigger to "when the API layer builds agentic-commerce exposure."
G2 (MCP server endpoints) Not a schema concern — API-layer work, unchanged from prior modules.
G3 (multi-agent handoff) Considered, correctly deferred; recorded via decision_provenance.delegated_by_actor_id, no new table.
G4 (governed semantic layer) Cross-cutting, not inventory-specific; out of scope.
G5 (agent memory) Built as documentation only: decision_provenance.memory_refs key, no memory subsystem table.
G6 (simulation/sandbox) Testing/observability-layer work, not schema; out of scope.
G7 (trajectory evals / OTel GenAI conventions) Testing/observability-layer work, not schema; out of scope.
G8 (proactive/scheduled agents) Cross-cutting shared infrastructure, not inventory's to build alone; out of scope.
G9 (agent marketplace) Genuinely none — future-platform concern.
G10 (voice/vision capture) Partially addressed at the design-question level by Part D's D15 (capture modality) — e.g., photographing a packing slip; the actual capture capability remains a capture/API-layer build, not schema.
G11 (standardized agent identity protocols) Genuinely none — future-proofing, no urgency signal.

Seams closed: item.plant_id → shared.plant.id; UOM columns (sell_uom_code/stock_uom_code/purchase_uom_code/weight_uom_code/capacity_uom_code) → shared.unit_of_measure.code; item_variant.currency_code → shared.currency.iso_code; site-scoping columns (inventory_location.site_id, stock.site_id, stock_movement.site_id, stock_reservation.site_id, stock_count.site_id, stock_lot.site_id, stock_adjustment_request.site_id) → multi_loc.site.id; every *_actor_id column → identity.actor.id.

Touches to previously locked modules: identity becomes a new dependency for inventory — every actor-attribution column (performed_by_actor_id, created_by_actor_id, updated_by_actor_id, reviewed_by_actor_id, proposed_by_actor_id, merged_by_actor_id, counted_by_actor_id, started_by_actor_id, reconciled_by_actor_id) FKs to identity.actor.id. No changes required to identity, shared, or multi_loc schemas themselves — inventory consumes all three as a pure downstream module, the same posture crm established (entry #23).

Deferred, logged to OPEN_ITEMS with explicit triggers (6 rows/updates, all attributed to inventory, all citing this entry): stock_movement.photo_ref forward-ref (blocked on the files module); the entire InventoryService layer (schema-only this pass, same pattern as agent_duty_grant's and crm's deferred service layers); pg_trgm fuzzy-search GIN indexes (the pg_trgm extension is not yet enabled in this database, verified live via pg_extension — blocked on enabling it / the Search module building fuzzy search properly); item.attributes/item_variant.attributes JSONB per-item_type example shapes still undocumented (carried forward from v1's own deferred note, narrowed in scope now that shared.plant owns taxonomy/care facts — blocked on InventoryService being built); a cross-reference note on agent_duty_grant.spend_limit_cents's per-action-only security limitation, since inventory is the first module to actually rely on this limit for a real money-moving action; and the update (not duplication) of the existing G1 row (OPEN_ITEMS line 104) recording this pass's ruling.

See schema_docs/inventory.md and module_spec/inventory.md §D7/§14 (Part D + autonomy detail, once written).

25. ai Module (Module #6) — The Agent-Runtime Schema Layer

Decided: 2026-07-06 (full runbook build: Part D walk, autonomy schema-translation, schema design + Section 4 audit, migration applied, docs to follow — the sixth module built in v2, and the first pass to give the agent runtime itself (not just a product domain) real tables)

Scope: 7 tables, 118 columns. Migration packages/db/migrations/20260706080000_ai_module.sql, applied live (schema ai verified via information_schema.columns: 7 tables, 118 columns, all 7 with RLS enabled). Drizzle schema at packages/db/src/schema/ai/ (7 files: _schema.ts, import.ts [3 tables], request.ts, execution.ts, usage.ts, memory.ts, plus index.ts barrel).

Table-by-table breakdown (7 tables):

  • Reconciled from v1 (light retargeting only, 4 tables): import_job, import_file, import_record — the zero-mapping onboarding import pipeline; ai_request — the Bedrock-call log, gaining a nullable agent_identity_id FK this pass (v1 predates agent_identity entirely).
  • New this pass (3 tables): agent_execution — the agent-action ledger (what an agent did, proposed vs. executed, cost/tokens, self-referencing propose/execute linkage); agent_usage_period — the atomic per-period usage/spend meter; agent_memory — the durable agent-memory store (G5).

v1 reconciliation approach: v1's locked docs/old/schema/schema_modules/schema_ai.md (2026-06-11) specified 4 tables / 71 cols for ai — this was NOT stale (confirmed accurate to v1's real design by prior independent verification), just pre-agent-infrastructure (predates identity.agent_identity/agent_duty_grant entirely). This build's delta: +3 tables (4→7), +47 columns (71→118).

Key design decisions:

  • Decision — agent_execution.resolves_execution_id is a nullable self-FK → ai.agent_execution.id, replacing an earlier draft's shared polymorphic target_table/target_row_id key. Why: the earlier draft claimed this polymorphic key "reuses the exact pattern" inventory.stock_adjustment_request/stock_movement and crm.customer_merge_candidate/customer_merge established. Independent verification proved this false — both real precedents use a dedicated FK column (stock_movement.adjustment_request_id, customer_merge.candidate_id), not a shared polymorphic key. Rejected: the polymorphic target_table/target_row_id pair — it has no mechanism at all for linking a "proposed" action (where the target row doesn't exist yet, so target_row_id is NULL) to its later "executed" row. Guard: live-tested the exact failure case the bug was about — a proposed action with target_row_id NULL, later resolved by an executed row that now has a real target_row_id — confirmed the self-FK correctly links the two via a direct JOIN on resolves_execution_id.
  • Decision — agent_execution.idempotency_key + UNIQUE (tenant_id, agent_identity_id, idempotency_key) WHERE idempotency_key IS NOT NULL — dedup protection for retry-prone agent runtimes. Why: matches inventory.stock_movement.idempotency_key's exact precedent — agent runtimes retry on timeout/network failure, and without dedup a retried action could be logged (and potentially re-executed) twice. Guard: live-tested — a duplicate idempotency_key for the same (tenant, agent) is rejected with duplicate key value violates unique constraint "agent_execution_tenant_agent_idempotency_unique".
  • Decision — ai.agent_memory's uniqueness is a partial index: UNIQUE (tenant_id, category, key) WHERE status='active', matching identity.agent_duty_grant's own already-locked precedent exactly (UNIQUE (agent_identity_id, permission_id, scope_type) WHERE status='active'). Rejected: an earlier draft's permanent, non-partial one-row-per-key-ever constraint. Why rejected: independent verification proved it blocks a legitimate case — a memory disabled for cause, later superseded by an unrelated fact under the same key, has nowhere to go once the key is permanently claimed. Guard: live-tested 3 scenarios — (a) two simultaneous active rows for the same key are rejected; (b) disabling the first row, then inserting a fresh active row for the same key, succeeds; (c) after (b), both rows persist (2 total) — the disabled row is preserved as history, not destructively overwritten.
  • Decision — ai_request.agent_identity_id (nullable FK → identity.agent_identity) closes "ai_request has no concept of an agent," since v1 predates agent_identity entirely. Confirmed live: nullable, uuid, FK present.
  • Decision — agent_usage_period's reconciliation formulas are atomic UPSERTs, corrected to sum directly off ai_request.agent_identity_id. total_cost_cents = SUM(agent_execution.cost_millicents)/1000; total_tokens = SUM(ai_request.total_token_count) WHERE ai_request.agent_identity_id = this row's agent AND requested_at falls in [period_start, period_end) — the authoritative attribution path. Rejected: an earlier draft's formula that summed tokens indirectly through agent_execution.ai_request_id. Why rejected: independent verification proved this silently undercounts whenever an LLM call is attributed to an agent but its agent_execution row was never logged (e.g. a read-only query with no proposed/executed action to log). Build requirement (documented as a SQL comment in the migration showing the exact INSERT ... ON CONFLICT ... DO UPDATE SET x = table.x + EXCLUDED.x shape, and to be documented in module_spec/ai.md): every increment to agent_usage_period MUST be a single atomic UPSERT, never an application-level read-then-write. Why: independent verification confirmed two real races an app-level read-modify-write would hit — a lost-update race (concurrent same-period increments) and a duplicate-insert race (concurrent first-actions-of-a-new-period, both racing to INSERT before either commits). The ON CONFLICT clause makes insert-or-increment a single statement Postgres serializes correctly, closing both races.

Post-build independent verification — 3 additional fixes, found against the LIVE built DDL (the Workflow's own Section 4 audit agent and adversarial verification agent, run after the migration was first applied — these only manifest against real constraint behavior, not design prose, which is why the design-phase verification above did not catch them):

  • Fix — ai_request's idempotency uniqueness split into two partial-unique indexes (ai_request_tenant_id_idempotency_key_unique WHERE tenant_id IS NOT NULL, ai_request_null_tenant_idempotency_key_unique WHERE tenant_id IS NULL), replacing a single UNIQUE (tenant_id, idempotency_key) WHERE idempotency_key IS NOT NULL carried forward unmodified from v1. Why: tenant_id is nullable for platform-level calls, and Postgres treats NULL as distinct in unique indexes — two NULL-tenant rows with the same idempotency_key both inserted successfully under the single-unique form (live-reproduced). Same bug class already caught and fixed multiple times this project; missed here because v1's ai_request shape was reconciled without re-auditing it against this exact trap. Guard: live-tested — two NULL-tenant rows sharing an idempotency_key are now rejected.
  • Fix — agent_execution's target CHECK renamed and relaxed from chk_agent_execution_target_all_or_nothing to chk_agent_execution_target_module_table_together. Why: the all-or-nothing form required target_row_id to be set whenever target_module/target_table were set, making it structurally IMPOSSIBLE to tag a 'proposed' create-new-record action with what it's proposing — live-reproduced: inserting (target_module='crm', target_table='customer', target_row_id=NULL, status='proposed') was REJECTED, directly contradicting the documented purpose of resolves_execution_id above. This bug was self-inflicted while fixing that same gap — the all-or-nothing shape was copied from import_record's precedent without checking compatibility with the new propose/execute linkage being added. Fix: relaxed to (all three NULL) OR (target_module IS NOT NULL AND target_table IS NOT NULL). Guard: live-tested — the tagged create-new-record proposal now succeeds, and executing it (setting a real target_row_id + resolves_execution_id) also succeeds.
  • Fix — agent_execution_resolves_execution_id_unique added: UNIQUE (resolves_execution_id) WHERE resolves_execution_id IS NOT NULL. Why: the resolves_execution_id self-FK had no uniqueness guard, so a retried "execute" call (not necessarily reusing the same idempotency_key) could create two rows both resolving the SAME 'proposed' row — live-reproduced as a distinct gap from the idempotency-key fix. Guard: live-tested — a second execution attempting to resolve an already-resolved proposal is rejected, guaranteeing a proposal is resolved at most once.

All 3 fixes were applied to the Drizzle source, the migration file was patched in place (the ai schema had zero real rows — confirmed via a SELECT count(*) sweep — so it was safely dropped and the corrected migration re-applied), and all 3 were re-verified live via direct psql inserts inside rolled-back transactions.

Two additional gaps found by adversarial verification, ruled low-severity and logged to OPEN_ITEMS rather than fixed as schema (see Deferred section below): ai_request.tenant_id/agent_identity_id consistency has no CHECK (no cross-table CHECK possible in Postgres without a trigger; "build thin" argues against a trigger for a not-yet-real caller); decision_provenance.memory_refs has no tenant-consistency enforcement against ai.agent_memory (structurally unfixable — JSONB array elements cannot carry FK constraints in Postgres).

AI Capability Plane pass — full outcome:

Part A schema-vs-runtime classification (of AI_CAPABILITY_PLANE.md's 14 controls, which ones are schema concerns for this module vs. pure runtime/service-layer concerns):

Control Classification
Import/onboarding pipeline (zero-mapping ingestion) Schema — already built in v1 (import_job/import_file/import_record), reconciled this pass
LLM call logging (Bedrock request/response) Schema — ai_request, reconciled + gains agent_identity_id
Agent action ledger (what an agent did, propose/execute) Schema — NEW, agent_execution
Usage/spend metering per agent per period Schema — NEW, agent_usage_period, atomic-upsert requirement
Agent memory (durable facts/preferences) Schema — NEW, agent_memory (closes G5)
Prompt/model orchestration, RAG retrieval Runtime/service-layer — no schema footprint this pass
Agentic checkout/commerce exposure (G1) API-layer — not a schema concern
MCP server endpoints (G2) API-layer — not a schema concern
Multi-agent delegation/handoff (G3) Documented JSONB key only (decision_provenance.delegated_by_actor_id) — no new table, matches crm/inventory's own rulings
Governed semantic layer (G4) Cross-cutting, out of scope for this module
Simulation/sandbox (G6), trajectory evals/OTel (G7) Testing/observability-layer — not schema
Proactive/scheduled agents (G8) Cross-cutting shared infrastructure — not this module's to build alone
Agent marketplace (G9) Future-platform concern — genuinely none needed now
Voice/vision capture (G10) Partially addressed at the design-question level (Part D D15); actual capture capability is a capture/API-layer build

D7 autonomy-boundary table:

Action Authority
Write an agent_execution row (log an action happened) may_act_alone — observational, zero mutation risk
Increment agent_usage_period may_act_alone, automation_source='system' — deterministic bookkeeping
Create an agent_memory row may_act_alone — low-stakes (preferences/patterns, not financial)
Edit/disable a memory entry human-only via owner console (B12: "editable/disableable by owner")
Import-record load decision unchanged from v1 — DB-enforced CHECK gate

The six schema-translation questions (SCHEMA_DESIGN_RUNBOOK.md §2.2.2), applied across the module: (1) autonomy tier (may_act_alone / needs_approval / human-only) drove the review posture on agent_execution writes (observational, low-risk) vs. agent_memory edits (human-only via owner console); (2) multi-agent delegation-chain info routed through decision_provenance.delegated_by_actor_id (G3), no new table — same ruling as crm/inventory; (3) confidence/provenance columns applied to agent_execution (authority_level_applied as a point-in-time snapshot) and agent_memory (data_source, confidence); (4) reversal window need assessed — agent_execution.resolves_execution_id itself IS the reversal/resolution mechanism (propose → execute linkage), no separate reversal table needed; (5) spend/quantity limit dimensions — agent_usage_period is the aggregation target agent_duty_grant.spend_limit_cents/future cumulative ceilings would read from, though the ceiling column itself is deferred (see below); (6) agent memory need (G5) — closed this pass with a real table, ai.agent_memory, not just a documented JSONB key.

AI_CAPABILITY_GAPS.md — all 11 gaps, final rulings this pass:

Gap Ruling
G1 (agentic catalog/checkout) Not a schema concern this pass — API-layer, unchanged ruling from crm/inventory.
G2 (MCP server endpoints) Not a schema concern — API-layer work, unchanged from prior modules.
G3 (multi-agent handoff) Considered, correctly deferred; recorded via decision_provenance.delegated_by_actor_id, no new table — matches crm/inventory's own rulings.
G4 (governed semantic layer) Cross-cutting, not ai-specific; out of scope.
G5 (agent memory) BUILT — ai.agent_memory (schema-locked 2026-07-06), a real target table, not just documentation. Unlike crm/inventory's passes (where memory_refs pointed at nothing), this pass gives memory_refs a real destination: ai.agent_memory.id.
G6 (simulation/sandbox) Testing/observability-layer work, not schema; out of scope.
G7 (trajectory evals / OTel GenAI conventions) Testing/observability-layer work, not schema; out of scope.
G8 (proactive/scheduled agents) Cross-cutting shared infrastructure, not ai's to build alone; out of scope.
G9 (agent marketplace) Genuinely none — future-platform concern.
G10 (voice/vision capture) Partially addressed at the design-question level by Part D's D15 (capture modality); the actual capture capability remains a capture/API-layer build, not schema.
G11 (standardized agent identity protocols) Genuinely none — future-proofing, no urgency signal.

docs/ai/AI_CAPABILITY_GAPS.md's G5 entry and its gap→layer summary table row are updated to reflect schema built (ai.agent_memory, 2026-07-06), not just "Plane coverage: partial" as before. G3 stays correctly deferred (no delegation/handoff table — decision_provenance.delegated_by_actor_id remains a documented JSONB key only, matching crm/inventory's own rulings).

Seams closed: ai_request.agent_identity_id, agent_execution.agent_identity_id, agent_usage_period.agent_identity_id → identity.agent_identity.id (enforced); agent_execution.permission_id → identity.permission.id (enforced); import_job.created_by_actor_id/import_record.reviewed_by_actor_id/agent_memory.created_by_actor_id/updated_by_actor_id → identity.actor.id (enforced); agent_execution.authority_level_applied documented (not FK'd) as a point-in-time snapshot of agent_duty_grant.authority_level at action time; new seam — crm/inventory's decision_provenance.memory_refs (documented on crm.customer/crm.item_merge_candidate-equivalent tables and inventory.item/item_variant/stock/stock_adjustment_request/stock_count/item_merge_candidate/item_merge) now resolves to a real row, ai.agent_memory.id — a plain-UUID reference inside a JSONB array (not an enforced FK, the same "reference inside JSONB, not a column-level FK" pattern decision_provenance already uses everywhere), documented explicitly since it's the first time memory_refs has a real target. import_file.file_id stays a deferred, unenforced forward-ref (plain uuid, no FK) — the files schema is still absent from v2 (verified live).

Touches to previously locked modules: none required to identity, platform, or files(nonexistent) schemas themselves — ai consumes identity.agent_identity/identity.permission/identity.actor as a pure downstream module, the same posture crm and inventory established (entries #23, #24).

Deferred, logged to OPEN_ITEMS with explicit triggers (all attributed to ai, all citing this entry):

  1. Cumulative spend-ceiling column on agent_duty_grant — DEFERRED. Do not reopen identity now. Trigger: "before the first cumulative-spend-limited agent runs — add spend_ceiling_cents + period to agent_duty_grant; agent_usage_period already supplies the data." Rationale: no spending agent exists yet (reorder is quantity-only; money lives in the unbuilt Purchasing module).
  2. Re-logging v1's 4 already-deferred items (archived in docs/old/design_rationale/rationale_ai.md DR6 and schema_ai.md's own "Deferred items" section — surfaced on the live tracking list, restating their original triggers): enrichment_job (batch re-enrichment tracking, DEFERRED v1.5) — trigger: "when scheduled batch re-enrichment (re-verify all unverified plants) becomes a product requirement"; ai_response_cache (popular query result cache, DEFERRED to consumer phase, belongs in the ai schema per v1's own DR6 forward-decision) — trigger: "build at consumer phase"; ai_feedback (thumbs-up/down quality signals, DEFERRED v1.1) — trigger: "when AI feature quality needs structured user-feedback collection"; anomaly_alert (persisted anomaly detection results, DEFERRED v1.1) — trigger: "when anomaly persistence/acknowledgement workflow is a product requirement."
  3. import_file.file_id forward-ref — re-confirmed, not re-derived; the files schema still doesn't exist in v2 (verified live). Trigger: "when the files module is built."
  4. No AIService yet — this build is schema-only (Drizzle + migration + tests against raw SQL, no NestJS service), same pattern as every other module's deferred service layer.
  5. ai_request.tenant_id/agent_identity_id consistency — no CHECK possible without a trigger, low severity. Found by post-build adversarial verification — see the fixes subsection above. Trigger: "when a real platform-level AI call path with agent_identity_id set is built."
  6. decision_provenance.memory_refs cross-tenant reference risk — structurally unfixable at the schema level. JSONB array elements cannot carry FK constraints in Postgres. Found by post-build adversarial verification — see the fixes subsection above. Trigger: "when AIService (or a shared cross-module runtime-logging helper) is built — validate tenant-scoping at the service layer."

Also corrected this pass: a second stale OPEN_ITEMS.md row, distinct from the agent_execution-concept row already closed against this same build (line 50), was found by adversarial verification — the G5 (agent memory) row asserting "no dedicated table exists anywhere (confirmed via grep, 2026-07-06)" is now false, since ai.agent_memory was built this same pass. Closed, citing this entry.

See schema_docs/ai.md and module_spec/ai.md §D7/§14 (Part D + autonomy detail, once written).

26. pricing Module (Module #13) — Outside-Critique-Resolved, Sell-Path-First Design

Decided: 2026-07-06 (full runbook build: outside gap-analysis, schema design + Section 4 audit x2, migration applied, docs to follow — the seventh module built in v2, and the first module of the sell path)

Scope: 4 tables, 75 columns. Migration packages/db/migrations/20260706090000_pricing_module.sql, applied live (schema pricing verified via information_schema.columns: 4 tables, 75 columns, all 4 with RLS enabled — price_level 11 cols, price_rule 33 cols, price_list_assignment 19 cols, price_change_log 12 cols). Drizzle schema at packages/db/src/schema/pricing/ (6 files: _schema.ts, level.ts, rule.ts, assignment.ts, change_log.ts, plus index.ts barrel). This is an incremental delta to pricing's existing MODULE_INDEX.md row, not a new schema addition: v1's own design already specified 4 tables / 56 cols; this build's delta is +0 tables, +19 columns (56→75).

Outside-critique background: before this build, an independent gap analysis compared the original 4-table pricing design against standard commerce/pricing-engine patterns (Odoo, Shopify, Magento, NetSuite, Stripe) — 3 independent cold-read critiques plus this agent's own analysis. It found real gaps: no rounding/tax-inclusive/currency-precision handling; no cost-plus pricing; no promotion-grouping identifier; a mutable price_rule vs. append-only-by-convention price_list_assignment inconsistency (the top finding, cited by all 3 independent critics); and a site-scoping/privacy blast-radius risk for Flutter POS sync of customer-specific rules. The user directed all 6 schema-fixable gaps be RESOLVED in schema (not deferred), plus 3 non-schema gaps recorded as binding Hard Contracts.

The 6 resolved gaps:

  • Decision — supersede-don't-edit price history. price_rule gains superseded_by_id (nullable self-FK → pricing.price_rule.id) plus chk_price_rule_no_self_supersede and chk_price_rule_superseded_by_consistency, and a new trigger, trg_price_rule_validate_supersession, cross-tenant-checks the link at write time. Why: all 3 independent outside critics flagged the same inconsistency — price_list_assignment was already effectively append-only by convention, but price_rule had no equivalent, so a price change destroyed the "what was the price on date X" history a pricing engine needs for margin analysis, disputes, and audit. Rejected: mutating price_rule rows in place (loses history) and a full separate history/versions table (adds a second table for what a self-referencing supersession chain already solves). Guard: live-tested a legitimate same-tenant/variant/scope supersession (succeeds) and a cross-tenant supersession attempt pointing superseded_by_id at a different tenant's row (rejected by the trigger), plus a row attempting to supersede itself (rejected by the CHECK).
  • Decision — explicit site-scoping via applies_all_sites. price_rule gains applies_all_sites boolean alongside the existing site_id, enforced XOR via chk_price_rule_applies_all_sites_xor_site_id, plus chk_price_rule_customer_scope_site_explicit forcing any customer-scoped rule to be explicit about site rather than silently defaulting to all-sites. Why: the outside critique flagged a real privacy/blast-radius risk — a customer-specific discount with an implicit "applies everywhere" default could leak a negotiated price to a Flutter POS terminal at a site the customer never transacts at, with no schema signal that this was intentional. Rejected: leaving site_id nullable-means-all-sites with no explicit flag (the status quo that created the risk) and a separate site-assignment join table (over-built for a boolean scope decision). Guard: live-tested applies_all_sites=true AND site_id both set on a customer-scoped row — rejected by the XOR CHECK.
  • Decision — a project-wide currency-integer convention, with pricing's own documented deviation. chk_price_rule_price_value_integer_for_currency_amounts enforces that fixed_price/fixed_discount-type price_value amounts are whole-number-of-cents-equivalent, while price_value itself stays numeric (not _cents bigint) to accommodate cost_plus_percent's fractional percentages in the same column. Why: the outside critique's currency-precision gap needed closing without breaking the single-column price_value design shared across all price_types. Rejected: splitting price_value into type-specific columns (price_value_cents + price_value_percent), which would have meant every future price_type addition grows the table's column count. Guard: live-tested cost_plus_percent = -50 (a below-cost clearance markdown, valid, succeeds) and cost_plus_percent = 1500 (above the [-100, 1000] ceiling, rejected by chk_price_rule_price_value). This is a deliberate, now-recorded deviation from the project's _cents bigint money convention — mirrors shared's own PK-type deviation (see entry #17 above).
  • Decision — tax_treatment column on price_rule. Gains tax_treatment plus chk_price_rule_tax_treatment. Why: the outside critique noted no pricing table anywhere recorded whether a price was tax-inclusive or tax-exclusive — a POS/checkout-blocking gap once real transactions exist. Rejected: deferring tax handling entirely to a future Tax module (leaves price_rule itself silent on inclusive/exclusive, which every one of the 3 critics called a checkout blocker, not a nice-to-have). Guard: covered by chk_price_rule_tax_treatment's enum enforcement; the residual gap at the bare item_variant.base_price_cents fallback path (no matching price_rule) is logged to OPEN_ITEMS rather than solved here, since that path belongs to inventory, not pricing.
  • Decision — cost_plus_percent as a first-class price_type. price_rule.price_type gains cost_plus_percent alongside fixed_price/fixed_discount, with chk_price_rule_price_type and chk_price_rule_price_value bounding it to [-100, 1000]. Why: cost-plus markup pricing is standard in every commerce platform the outside critique compared against (Odoo, Shopify, Magento, NetSuite) and the original design had no way to express "price = cost + N%" at all. Rejected: modeling markup as a derived/computed value outside the schema (defeats the purpose of a declarative pricing-rule table) or as a separate table per price-type (inconsistent with the existing single-price_rule-table shape). Guard: live-tested the full valid range plus the two rejection boundaries (see regression scenarios 1–2 above).
  • Decision — campaign_label as a lightweight promotion-grouping tag. price_rule gains a plain nullable campaign_label text column (no new table, no coupon/usage-cap machinery). Why: the outside critique flagged that multiple price_rule rows belonging to the same promotional campaign ("Spring Sale 2026") had no way to be grouped or reported on together. Rejected: a full promotion/campaign header object with usage caps, coupon codes, and stacking rules (Odoo/Shopify-style) — ruled out as over-built for this pass; logged to OPEN_ITEMS as a real future gap rather than solved now. Guard: none needed — a plain nullable tag column has no constraint surface to test.

The 3 Hard Contracts (non-schema gaps from the outside critique, resolved as binding commitments rather than vague deferrals — full text in module_spec/pricing.md, not restated here):

  1. pos.sale_line must snapshot the resolved price at sale time — a fully specified column shape (resolved_amount_minor_units, charged_amount_minor_units, currency_code, tax_treatment, resolving_price_rule_id, resolved_quantity), to be recorded in docs/modules/CROSS_MODULE_CONTRACTS.md's existing "Pricing" section and enforced when pos/orders are built.
  2. One versioned resolvePrice() spec with cross-language (Node/Dart) golden test vectors and a named minimum coverage bar, to be recorded in module_spec/pricing.md's Build Requirements section — so the Node PricingService and the Dart offline POS resolver can never silently diverge.
  3. Display rounding (e.g. .99 psychological pricing) is a PricingService concern, never a schema mutation — reconciled with Hard Contract 1's pre/post-rounding amount distinction (resolved_amount_minor_units vs. charged_amount_minor_units).

Verification history: design-phase verification ran TWICE — once on the original 4-table proposal, once again on the round-2 expanded design after the 6 gaps were folded in — each round via an independent 3-agent Workflow (Section 4 audit + adversarial verification + a third specialized check), finding and fixing real bugs both times before this build (full history in module_spec/pricing.md's DR entries). A third, build-phase Section 4 audit ran against the live-applied migration, per this project's standard post-build audit step. 8 live-tested regression scenarios ran inside BEGIN/ROLLBACK transactions (no residual data), covering both boundary rejections and legitimate same-tenant supersession/dedup behavior — see the 22 CHECK constraints and regression scenarios enumerated in the schema docs.

Seams closed: no new cross-module FKs introduced this pass beyond pricing's own internal self-FK (price_rule.superseded_by_id); price_rule/price_list_assignment continue to reference identity.actor, multi_loc.site, and inventory.item_variant per their existing (v1-derived) shape.

Touches to previously locked modules: none required to identity, multi_loc, inventory, or crm schemas themselves — pricing consumes all four as a pure downstream module, the same posture crm, inventory, and ai established (entries #23, #24, #25).

Post-build verification (a third round, against the live-built DDL, after the two design-phase rounds above): an independent Section 4 audit found zero FAILs across all A–P+T items on the live schema. A separate adversarial-verification pass then found one more real bug: the idempotency-key grain's created_by_actor_id is nullable, and the original single-partial-unique let two NULL-actor rows (system/import/unattributed callers) share the same idempotency_key — Postgres NULL≠NULL, live-reproduced — silently defeating idempotency. Fixed with the same two-partial-unique split already established for ai.ai_request's own NULL-tenant fix, applied to both price_rule and price_list_assignment's idempotency indexes; the migration was safely dropped and reapplied (zero real rows existed) and re-verified live. The same pass separately surfaced a systemic, pre-existing, cross-module gap unrelated to this build: the authenticated Postgres role has no schema-level GRANT on pricing, crm, inventory, multi_loc, or shared (only platform has one) — RLS policies are structurally correct but currently unreachable by that role. Not fixed here (out of scope — would require touching 4 other already-locked modules' migrations); logged to OPEN_ITEMS and flagged as a separate follow-up task.

Deferred, logged to OPEN_ITEMS (all attributed to pricing, all citing this entry, unless noted): the agent_duty_grant discount/margin-ceiling gap (spend/quantity limits don't map onto "how much may this agent discount by"); no overlap-prevention EXCLUDE constraint on price_list_assignment for time-windowed customer/group assignments; the full promotion/campaign header object (usage caps, coupon codes, stacking rules) that campaign_label intentionally does not attempt; tax_treatment's residual gap at the bare item_variant.base_price_cents fallback path; all 3 Hard Contracts (not yet satisfied — pos/orders don't exist yet, no shared resolvePrice() spec exists yet, no PricingService display layer exists yet); the absence of a PricingService entirely (schema-only this pass, same pattern as every other module's deferred service layer); and — attributed to (all), not pricing alone — the systemic authenticated-role GRANT gap above.

See schema_docs/pricing.md and module_spec/pricing.md §D7/§14 (Part D + autonomy detail, once written).

27. pos Module (Module #14) — Offline-First, the Sell Path's Transaction Spine

Decided: 2026-07-07 (full runbook build: schema design + Section 4 audit, migration applied, docs to follow — the eighth module built in v2, and the second module of the sell path after pricing)

Scope: 9 tables, 138 columns — down from v1's 19 tables / 280 cols. Migration packages/db/migrations/20260707000000_pos_module.sql, applied live (schema pos verified via information_schema.columns: 9 tables, 138 columns; 6 triggers total — 5x set_updated_at plus 1x custom trg_pos_sale_requires_open_session; 41 CHECK constraints total). Drizzle schema at packages/db/src/schema/pos/ (6 files: _schema.ts, register.ts, sale.ts, payment.ts, sync_conflict.ts, plus index.ts barrel). Test file apps/api/src/pos/__tests__/pos-schema.spec.ts (16 tests, all passing; full apps/api suite 314/314, no regressions).

Framing: pos is the sell path's transaction spine — the point where a resolved price (from pricing), an available unit (from inventory), and a customer (from crm) all converge into an immutable, auditable sale record, in a retail-floor environment where the network cannot be assumed reliable. Its central design problem is not the sale schema itself (a fairly standard header/line/payment/refund shape) but making that shape safe to write from a device that may be offline for hours and reconcile later.

Table-by-table breakdown (9 tables, 138 columns):

  • register (8 cols) — a physical/virtual POS terminal at a site. Site-scoped, minimal: identifies where a sale can originate.
  • register_session (18 cols) — the open/close cash-drawer session that gates all sale activity on a register (opening/closing float, opened/closed timestamps and actors, variance tracking). This is the table trg_pos_sale_requires_open_session reads to enforce its rule.
  • register_cash_entry (9 cols) — paid-in/paid-out cash movements within a session (till adjustments, cash drops), separate from sale_payment because they don't correspond to a sale.
  • sale (24 cols) — the sale header: site/register/session/customer linkage, status (open/completed/voided, deliberately no refunded), total_minor_units (immutable gross), the 5 offline-sync columns (client_uuid, origin, sync_status, idempotency_key, synced_at), currency, actor attribution.
  • sale_line (14 cols) — one line item per sale: item_variant_id, quantity, and the 6 Hard-Contract-1 price-snapshot columns from pricing (below), honored verbatim.
  • sale_payment (26 cols) — one or more tenders against a sale (split-tender support): payment_method, amount, the same 5 offline-sync columns as sale (a payment can itself arrive/replay independently of its parent sale during sync), plus forward-ref columns for Payments (stripe_payment_intent_id, charge_account_ref) and stored-value (gift_card_id, store_credit_id) that stay unenforced until those modules exist.
  • sale_refund (22 cols) — a refund event against a completed sale: refunded_amount_minor_units, reason, restock flag, the same 5 offline-sync columns again (a refund is itself a first-class offline-capable write, not just a mutation of sale).
  • sale_refund_line (7 cols) — which sale_line rows (and what quantity of each) a given sale_refund covers.
  • pos_sync_conflict (10 cols) — the landing table for conflicts detected during offline-sync reconciliation (conflict_type, e.g. stock_oversell), resolution status, and the actor/timestamp of resolution. Schema exists and is tested (test B3); nothing populates it yet since InventoryService doesn't exist.

Key design decisions:

  • Decision — the offline-sync mechanism, and two distinct problems kept separate. Every offline-capable table (sale, sale_payment, sale_refund) carries the same 5-column shape: client_uuid (uuid, NOT NULL, device-generated), origin (online/offline), sync_status (synced/local_only/conflict), idempotency_key (nullable, deterministically derived from client_uuid as a documented build requirement, forwarded unchanged to inventory.stock_movement.idempotency_key on retry), and synced_at. Each table has UNIQUE (tenant_id, client_uuid) WHERE deleted_at IS NULL; the write path is INSERT ... ON CONFLICT (tenant_id, client_uuid) DO NOTHING. Why: a POS terminal on a nursery sales floor can be offline for hours; the sale must be written locally and reconciled later without ever double-charging or double-decrementing stock, and without conflating two genuinely different failure modes that need different fixes. The two problems: (1) duplicate-sale replay — the same logical sale, same client_uuid, arrives twice (retry after a flaky ack) — solved entirely by the client_uuid UNIQUE dedup index; no conflict row is ever created for this case, it's silently absorbed by ON CONFLICT DO NOTHING. (2) genuine two-different-sale oversell — two different offline devices, two different client_uuids, each independently sells the last unit of the same variant — is not caught by #1's dedup at all (different keys, both insert successfully). This requires InventoryService.completeSale() to detect, at sync-processing time, that applying the stock decrement would push inventory.stock.available_qty negative, and instead of allowing negative stock, write a pos.pos_sync_conflict row (conflict_type='stock_oversell'). Rejected: a single generic "conflict" mechanism that tries to handle both cases the same way (conflates a solved problem with an unsolved one, and would falsely flag every ordinary retry as a conflict needing review). Guard: client_uuid dedup is live-tested (duplicate insert with same client_uuid is silently absorbed); the oversell-detection logic itself is a documented, not-yet-built InventoryService requirement — only the schema's ability to represent the resulting conflict row is built and tested (test B3), since InventoryService does not exist yet.
  • Decision — honor pricing's Hard Contract 1 verbatim on sale_line. All 6 required snapshot fields present exactly as specified: resolved_amount_minor_units (bigint), charged_amount_minor_units (bigint), currency_code (char(3)), tax_treatment (text), resolving_price_rule_id (uuid, nullable), resolved_quantity (numeric). Why: entry #26 made this a binding cross-module commitment specifically so pos/orders could never silently diverge from what pricing promised to snapshot — the sale line must be the historical record of what was actually charged, never re-derived from whatever the live price_rule says today. Rejected: re-resolving price from price_rule at read time (defeats the entire purpose of a snapshot — a later price change or supersession would silently rewrite history). Guard: live-tested (test C1) — after the resolving price_rule row is superseded to a new price, sale_line's snapshot amounts remain unchanged.
  • Decision — the immutable-total model; no refunded status on sale. sale.total_minor_units is immutable-gross forever; sale.status CHECK is ('open','completed','voided'), deliberately with no 'refunded' value. Net refunded position is computed at query time as sum(sale_refund.refunded_amount_minor_units) against the sale's refunds, never written back onto sale itself. Why: a sale's original total is an audit-critical historical fact (what was actually transacted) — collapsing "completed" and "partially/fully refunded" into overlapping status values invites exactly the kind of maintained-cache-with-no-reconciliation-formula bug class this project has already logged against other modules (e.g. crm.customer.tax_exempt). Keeping refunds in their own append-only table with the total untouched means there is only one source of truth for "what did this sale total," and refund position is always freshly derived. Rejected: adding a refunded status (ambiguous for partial refunds, and immediately begs a second partially_refunded value) and a maintained refunded_amount_minor_units cache column on sale (reintroduces the reconciliation-formula gap this project has explicitly flagged elsewhere as a bug class to avoid). Guard: live-tested (test D1) — inserting a sale_refund row does not change sale.total_minor_units.
  • Decision — trg_pos_sale_requires_open_session as a trigger, not a CHECK. A BEFORE INSERT trigger (function pos.validate_sale_requires_open_session()) on sale, not a CHECK constraint. Why: the rule — a sale may only be created against a register_session that is currently open — requires reading a different table's current state (register_session.closed_at IS NULL at the moment of insert), which a CHECK constraint cannot express in Postgres (CHECKs are limited to the row's own columns, no cross-table lookups, no subqueries). Rejected: a CHECK constraint (structurally impossible for a cross-table condition) and enforcing the rule only in application code (would leave the DB itself unable to guarantee the invariant against direct writes, migrations, or a future service bug). Guard: live-tested — inserting a sale against a session with closed_at already set is rejected by the trigger; inserting against a genuinely open session succeeds.
  • Decision — the NULL-distinctness class, explicitly checked and found NOT applicable. client_uuid is NOT NULL on all 3 offline-capable tables (sale, sale_payment, sale_refund), so the (tenant_id, client_uuid) unique index needs no COALESCE-based workaround or two-partial-index split — unlike pricing's nullable-actor idempotency-key fix (entry #26) or ai's nullable-tenant fix (entry #25), where a NULL participant in a uniqueness tuple meant Postgres's NULL≠NULL semantics silently defeated the constraint. Why this is called out explicitly: this project's pattern is to check this class of bug on every new uniqueness constraint, not assume it away — this pass is the first time the check was run and the answer came back "not applicable," and that negative result is recorded for the same reason the positive-fix cases were recorded, so a future audit doesn't have to re-derive it. Separately, idempotency_key itself carries no unique constraint within pos — it's a pass-through value forwarded to inventory.stock_movement's own, separately-enforced unique index, a deliberate design, not an oversight. Rejected: N/A — no fix was needed; this decision documents a verification, not a change. Guard: verified live via information_schema.columns that client_uuid is NOT NULL on all 3 tables before concluding no COALESCE/split-index fix was required.
  • Decision — sale.search_vector dropped from the design, not built. An earlier PROPOSE+STOP draft listed a sale.search_vector (generated tsvector, GIN) column, matching the precedent already applied to item/item_variant/customer. Found during build to not actually fit: unlike those 3 tables, sale has no free-text field (name/description/SKU) to feed a full-text index — the only candidate column was status, a 3-value enum, which would produce a near-useless GIN index (near-zero selectivity, high maintenance cost for no real search benefit). Rejected: building it anyway for consistency with the other 3 tables (form over function — a search-vector column with nothing meaningful to search is a maintenance burden, not a feature). Guard: none needed — this is a scope reduction, not a constraint; logged to OPEN_ITEMS as a deferred add-later item (not silently dropped) in case a future free-text field is added to sale (e.g. a cashier note) that would make a search vector worthwhile.

AI Capability Plane pass — full outcome (Section 0/2.2):

Honest finding: pos is overwhelmingly a human-initiated, system-recorded module. A cashier rings up a sale; the register/session state machine and stock/price resolution are deterministic system operations triggered by that human action. There is very little room in the transaction-spine itself for autonomous agent action — the closest thing to an agent-relevant decision point is reviewing a flagged sync anomaly after the fact, not initiating or executing a sale.

D7 autonomy-boundary table:

Action Authority
Ring up / complete a sale human-only (cashier-initiated at the register)
Record a register_session open/close human-only (cashier/manager-initiated)
Record a sale/sale_payment/sale_refund row (system write path once a human/device has acted) may_act_alone, automation_source='system' — deterministic recording of an already-decided human action, zero autonomous judgment involved
Detect and flag a pos_sync_conflict (stock-oversell on sync reconciliation) may_act_alone to flag (observational, system-detected), but review of the flagged anomaly is needs_approval / human-only — resolving which sale "wins" the contested stock is a business judgment call, not a mechanical one
Void a sale human-only (manager-level action in practice, though schema does not itself encode a role gate beyond the state machine)

Agent-authority mapping (pos → identity.agent_duty_grant): pos consumes the existing A5 passport for all agent authority — no new authority mechanism introduced. Given the near-total human/system split above, no illustrative permission-code rows are proposed this pass (unlike crm/inventory, which had genuine draft_only agent actions like reorder-suggestion or merge-proposal); the only plausible future agent surface is the pos_sync_conflict review queue, and that surface doesn't exist as an executable action yet (no InventoryService/POSService review workflow built).

All six schema-translation questions (SCHEMA_DESIGN_RUNBOOK.md §2.2.2), applied across the module: (1) autonomy tier — overwhelmingly human-only/system-recorded, per the D7 table above, with the one narrow exception being system-flagged (not system-resolved) sync conflicts; (2) multi-agent delegation-chain info — not applicable this pass, no agent-initiated action exists in pos to delegate; (3) confidence/provenance columns — actor-attribution columns (*_by_actor_id) present throughout for the human/system actors that do act, but no data_source/is_verified pattern was needed since nothing in this module is agent-drafted content; (4) reversal window — sale_refund itself is the reversal mechanism for a completed sale (no separate reversal table needed, mirroring the pattern already established for ai.agent_execution.resolves_execution_id and crm/inventory merge reversibility); (5) spend/quantity limit dimensions — not applicable, no agent spends money or moves quantity autonomously in this module; (6) agent memory need — not applicable, no agent-facing decision surface exists yet to benefit from ai.agent_memory.

AI_CAPABILITY_GAPS.md — all 11 gaps, final rulings this pass: no gap ruling changes — pos introduces no new schema-fixable resolution to G1–G11 beyond what crm/inventory/ai/pricing already established; the module's overwhelmingly human/system character (above) means most gaps (G1 agentic catalog/checkout, G3 multi-agent handoff, G5 agent memory, G10 capture modality) simply don't have a load-bearing surface in pos the way they did in crm/inventory. Not re-tabulated here since no ruling differs from the prior modules' final positions.

Seams closed — Consumed (pos depends on): multi_loc.site (register.site_id, sale.site_id, both NOT NULL, onDelete restrict); inventory.item_variant (sale_line.item_variant_id, onDelete restrict); inventory.stock.available_qty (read-only netting, no new pos-side reservation table — inventory.stock_reservation.source_type CHECK does not include 'pos', confirmed live; reservations remain Orders' own mechanism; a POS sale calls InventoryService.completeSale() directly); pricing.price_rule (sale_line.resolving_price_rule_id, nullable, onDelete restrict) plus Hard Contract 1 (now honored by pos — marked SATISFIED on pos's side, still pending on Orders' own side); crm.customer (sale.customer_id, nullable, onDelete restrict); shared.currency (sale/sale_line/sale_payment .currency_code → iso_code, onDelete restrict); identity.actor (every *_by_actor_id column across the module). New seam added: orders.order_header.fulfilled_sale_id → pos.sale — the FK lives entirely on Orders' side (not built yet); pos.sale needs no reciprocal column. Direction: Orders → pos, "link-don't-convert; tax finalizes at POS." Payments seam (Payments module not built yet): sale_payment.stripe_payment_intent_id (forward-ref, no FK) and sale_payment.charge_account_ref (forward-ref into a future billing.ar_charge) mirror Billing's own ar_payment/ap_payment precedent. Direction: pos → Payments, forward-ref, deferred FK.

Touches to previously locked modules: none required to multi_loc, inventory, pricing, crm, shared, or identity schemas themselves — pos consumes all six as a pure downstream module, the same posture crm/inventory/ai/pricing established (entries #23–#26).

10 v1 tables deferred this pass, each logged to OPEN_ITEMS with its own concrete trigger: (1) sale_line_tax (full multi-jurisdiction tax breakdown) — trigger: when a real Tax module is built or multi-jurisdiction stacking becomes a real requirement; (2) receipt (delivery tracking) — trigger: when a notifications module is built; (3) gift_card — trigger: when gift_card/store_credit stored-value subsystems are built (tender-tagging preserved via a payment_method enum value + sale_payment.gift_card_id forward-ref column); (4) gift_card_transaction — same trigger as (3); (5) store_credit — same trigger as (3) (sale_payment.store_credit_id forward-ref column); (6) store_credit_transaction — same trigger as (3); (7) layaway_payment — trigger: when installment-payment-plan support is prioritized; (8) sale_template — trigger: when saved-cart/recurring-order UX is prioritized; (9) sale_template_line — same trigger as (8); (10) guarantee — trigger: when guarantee issuance/claim-instance tracking is prioritized, with a caveat carried forward exactly: CROSS_MODULE_CONTRACTS.md's Files section names guarantee.signature_ref -> files.file.id as a live (non-stale) seam that cannot be honored until guarantee itself is built.

4 open questions, all deferred/logged this pass, none resolved: (1) sale_line_tax full multi-jurisdiction breakdown vs. a flat tax_amount_cents/tax_rate on sale_line — deferred alongside the table itself (see deferred-tables item 1); (2) the 10 deferred tables above, each with its own trigger; (3) Rewards/Offers seams (both flagged stale in CROSS_MODULE_CONTRACTS.md, neither module exists in v2) — stay unhonored this pass, logged as an explicit open item rather than silently ignored; (4) sale_payment.status's enum (Stripe-vocabulary-derived) may need revisiting once Payments' actual Terminal integration is built against a real webhook payload — logged with trigger "when Payments' Stripe Terminal integration is built."

Deferred, logged to OPEN_ITEMS (all attributed to pos, all citing this entry, unless noted): the 10 deferred v1 tables and 4 open questions above, each its own row with the trigger stated; the sale.search_vector scope-reduction (deferred add-later item, not silently dropped); the genuine two-different-sale oversell detection logic (a documented InventoryService.completeSale() build requirement — schema-ready via pos_sync_conflict and tested at the schema level only, test B3); Hard Contract 1's Orders-side half (still pending — orders doesn't exist yet); the absence of a POSService/OrdersService entirely (schema-only this pass, same pattern as every other module's deferred service layer).

See schema_docs/pos.md and module_spec/pos.md §D7/§14 (Part D + autonomy detail, once written).

ADDENDUM (2026-07-07) — reopened for one live schema bug found by a 19-to-9 v1-consolidation functionality audit; everything else from that audit is docs/OPEN_ITEMS only.

  • Decision: add chk_sale_payment_no_unvalidated_stored_value_tender (CHECK (payment_method NOT IN ('gift_card','store_credit'))) to sale_payment, migration packages/db/migrations/20260707020000_pos_gift_card_store_credit_gate.sql.
  • Why: chk_sale_payment_payment_method already permitted gift_card/store_credit as tender values, and gift_card_id/store_credit_id are unenforced forward-ref columns with no FK target (both stored-value subsystems deferred, per the 10-tables-deferred list above) — so a tender tagged either was silently accepted with zero balance validation. A cashier could apply $500 of "gift_card" tender against a card with $0 left, expired, or nonexistent, with nothing in the schema signaling a problem — a real, live risk on a cash-handling path, not a hypothetical one.
  • Rejected alternative: requiring gift_card_id/store_credit_id NOT NULL when those methods are used. Rejected because there is still no table to validate the referenced uuid against — this would only force SOME value to be present, not a REAL one, giving a false impression of validation without providing any.
  • Guard: this is a deliberately TEMPORARY, fail-closed restriction, not a permanent design decision — tracked in its own OPEN_ITEMS row, to be dropped or loosened when the gift_card/store_credit stored-value subsystem is built. It coexists with the unchanged base payment_method enum CHECK (both must pass; the enum itself still declares all 7 tender values, preserving the tagging capability).
  • Verification: an initial solo Section 4 re-audit found only this one CHECK addition in scope; confirmed the new CHECK and the base enum CHECK compose correctly (AND semantics, verified live). 3 regression tests (B5a/B5b/B5c) proved unvalidated gift_card/store_credit tenders rejected and every other tender type unaffected. Independent verification (separate agent, not self-graded) then found a real residual gap the solo audit missed: nothing stopped a NON-stored-value tender (cash/card/check/charge_account/reward) from carrying a fabricated or stale gift_card_id/store_credit_id — live-reproduced (payment_method='cash' + a random gift_card_id inserted with zero complaint) — the identical silent-acceptance bug class, just relocated to the two forward-ref columns. Fixed same pass: added a companion chk_sale_payment_stored_value_ref_matches_method (CHECK (payment_method IN ('gift_card','store_credit') OR (gift_card_id IS NULL AND store_credit_id IS NULL))) to the same migration file, applied live, verified the gap is now closed, and added regression test B5d. The independent verifier's second recommendation — that the OPEN_ITEMS trigger explicitly require re-adding real FK validation when the stored-value subsystem ships, not just dropping the CHECKs — was also applied to the OPEN_ITEMS row's trigger text. Full apps/api suite green (per the schema docs) after both fixes.
  • Also this pass (docs/OPEN_ITEMS only, no further schema change, per the task's explicit scope): the same audit found 8 column/enum-level erosions inside otherwise-BUILT tables that were never individually logged — sale (cart hold/resume, B2B fields, loyalty-points snapshot), sale_line (comp/sample/replacement distinction, price-override tracking), register (hardware-pairing config), register_cash_entry (entry_type narrowed 6→3) — each now has its own OPEN_ITEMS row with a concrete trigger; none are rebuilt this pass, restoring any is a future per-feature decision. The existing sale_line_tax row was UPGRADED to state its true severity (an unrecoverable audit-trail loss for stacked-jurisdiction tax, not a simplification) and reframed as a PRE-CUSTOMER decision (must resolve before the first customer transacts in a multi-jurisdiction tax location), not open-ended. See schema_docs/pos.md and module_spec/pos.md DR-G/DR-H for full detail.
  • Process fix: SCHEMA_DESIGN_RUNBOOK.md Section 6 item 12's standing OPEN_ITEMS rule and Section 5's Recurring Bug Class #11 were both extended to explicitly cover column- and enum-level erosions, not just table-level ones — the exact gap this audit found one level below where the 2026-07-06 completeness audit had already checked.

28. crm / inventory / pricing — Retroactive v1→v2 Delta-Accounting Record + Erosion Fixes

Decided: 2026-07-07 (read-only audit 2026-07-07, followed same-day by a full reopen-fix-verify-relock pass on all 3 already-locked modules)

Context — why this entry exists. pos's own 19-to-9 audit (entry #27's addendum) found that table-level BUILT/CONSOLIDATED/DEFERRED tracking can miss real column/enum-level capability loss. The same v1→v2 reconciliation process ran on crm (entry #23), inventory (entry #24), and pricing (entry #26) when they were originally built, but none of them ever got the equivalent column-level accounting pos just received — this entry is that retroactive accounting, run the same way (independent Gather → neutral-facts Classify → adversarial Verify workflow), plus the fixes it justified.

Audit method and headline result (full detail: /Users/cnu/Downloads/crm-inventory-pricing-erosion-audit.md): 15 agents, 183 tool calls, independent classification of every v1 table/column/enum against the live v2 schema and OPEN_ITEMS, then an adversarial pass attacking every CONSOLIDATED claim and hunting for pos-gift-card-style live bugs. crm: 1 live bug (high severity) + 2 real unlogged erosions surfaced by the adversarial pass beyond what the classifier itself flagged. inventory: 0 live bugs, 1 narrow audit-trail gap, 3 pre-existing v1.5 deferrals that had fallen out of active tracking (not new v1→v2 losses). pricing: 0 live bugs, 4 real unlogged capability losses — the sharpest findings of the three modules.

LIVE BUG fixed — crm.customer_tax_certificate (same class as pos's gift-card bug).

  • Decision: add chk_customer_tax_certificate_active_requires_verification (CHECK (status <> 'active' OR (verified_by_actor_id IS NOT NULL AND verified_at IS NOT NULL))) and drop issuing_country_code's DEFAULT 'US'. Migration packages/db/migrations/20260707030000_crm_erosion_fixes.sql.
  • Why: status could be set to 'active' — meaning "this customer is currently tax-exempt" — with verified_by_actor_id/verified_at/document_ref all NULL; the DR-43 pending_review default only suggested the review workflow, nothing enforced it. Separately, issuing_country_code's silent 'US' default meant an omitted country was recorded as domestic rather than surfaced — a real misclassification risk on a compliance-bearing document.
  • Rejected alternative: a NOT-NULL-only requirement on the verifier columns without a CHECK tying them to status — would force presence but not the actual verification-before-trust invariant.
  • Guard: this is a permanent fix, not a temporary gate (unlike pos's stored-value CHECKs) — both verified_by_actor_id/verified_at are real, already-built columns with a real FK target (identity.actor), so there is no future subsystem this needs to be replaced by.
  • Verification: live-reproduced (active+no-verifier rejected; active+both-set succeeds; non-active statuses unaffected) both by my own Section 4 re-audit and by an independent agent that re-derived the same 3 cases from scratch against the live DB, plus confirmed the exact constraint name in the Postgres error and reviewed the 4 new regression tests (crm-schema.spec.ts describe block L) for genuineness (asserts exact code/constraint_name, not generic "any throw" — adversarially confirmed by swapping in a deliberately wrong constraint name and watching the test correctly fail).

Erosion fixed — crm.address.country_code NOT NULL (restores v1's guarantee).

  • Decision: address.country_code is now NOT NULL; its FK's ON DELETE behavior changed from SET NULL to RESTRICT (a NOT NULL column can't silently absorb a deleted-country cascade).
  • Why: v1's country_id was NOT NULL; v2 shipped country_code nullable, and chk_address_region_country_match only fires when region_code IS NOT NULL — so an address with neither set passed trivially, and any downstream tax/shipping logic keyed on country would silently see NULL. Found by the audit's adversarial pass specifically attacking a claim the classifier itself had rated "fully preserved."
  • Guard: 0 existing rows confirmed live before applying (additive/safe); independently re-verified via pg_constraint.confdeltype='r' and a live INSERT reproduction (omitted country rejected, explicit country succeeds).

Erosion fixed — pricing.price_rule.rule_kind + .name restored; price_list_assignment.is_active + uniqueness restored.

  • Decision: price_rule regains rule_kind ('standard'/'sale'/'scheduled', default 'standard') plus price_rule_sale_expiry_idx (partial index on valid_until WHERE rule_kind='sale') and name (nullable text). price_list_assignment regains is_active (default true) plus two partial-unique indexes guaranteeing at most one open-ended (valid_until IS NULL), active, non-deleted assignment per customer_id and per customer_group_id. Migration packages/db/migrations/20260707040000_pricing_erosion_fixes.sql.
  • Why: rule_kind and its supporting expiry-sweep index were dropped entirely with zero OPEN_ITEMS/PROJECT_DECISIONS trace — campaign_label is a free-text promo tag, not a type classification, and cannot back a sale-expiry sweep job. name (the human display label, e.g. "Wholesale tray price") was likewise dropped with no real substitute — campaign_label/reason are semantically different (grouping tag / justification). price_list_assignment.is_active and its uniqueness guarantee were dropped with nothing stopping two conflicting open-ended active assignments for the same customer/group from coexisting — a real correctness risk for wholesale tier assignment. All 3 were confirmed as genuine, previously-unlogged erosions by the audit's adversarial pass (not just the initial classifier).
  • Guard: 0 existing rows in both tables confirmed live before applying. price_list_assignment's uniqueness fix is the most safety-critical of the three restorations — independently break-it-tested: two open-ended active assignments for the same customer (2nd rejected, exact constraint name), same for customer_group, a closed-ended row does NOT conflict, an is_active=false row does NOT conflict, the soft-delete interaction correctly frees the slot without opening a gap, and the pre-existing chk_price_list_assignment_customer_xor_group CHECK still holds against both NULL/NULL and SET/SET edge cases.
  • Not fixed this pass (logged to OPEN_ITEMS instead, v1.1): price_change_log.old_value/new_value (jsonb) cannot reconstruct the actual historical dollar delta for percent_off/amount_off/cost_plus_percent rows the way v1's scalar old_price_cents/new_price_cents could for every rule type — no point-in-time base-price/cost snapshot exists to attach. Reporting-only gap, not a day-one blocker; see OPEN_ITEMS.

Erosion fixed — inventory.stock_reservation.created_by_actor_id (nullable FK → identity.actor).

  • Decision: add created_by_actor_id to stock_reservation. Migration packages/db/migrations/20260707050000_inventory_erosion_fixes.sql.
  • Why: stock_reservation is writable by an autonomous agent (automation_source='agent') but had no actor-attribution column at all — the "no review seam, fully deterministic" framing this table was given at build time doesn't hold for the agent-initiated write path; a misreserved order (wrong variant/quantity/site) would leave no trail of which agent, why, or under what confidence. source_type/source_id remain the primary trace for the deterministic system/POS case; this column adds the missing trail specifically for the agent-initiated case.
  • Guard: nullable, no default — 0 existing rows, zero impact on the deterministic write path. Independently confirmed as a REAL, enforced FK (a random non-existent actor id is rejected with 23503/stock_reservation_created_by_actor_id_fkey), not a silent forward-ref; confirmed the migration is additive-only (+1 column, +1 FK, 0 other changes to the table's 3 CHECKs/4 original FKs/5 indexes).

AMBIGUOUS items resolved (no fix needed): the audit flagged crm.contact.is_primary and crm.address.is_default's partial-unique indexes as unconfirmed from documentation alone. Independently re-verified against the live migration DDL: both contact_customer_id_primary_unique and address_customer_id_address_type_default_unique exist exactly as originally built and actively enforce (live-reproduced: a second is_primary/is_default row for the same customer is rejected by the exact named index). No erosion — the original build got this right; the audit's own ambiguity was a documentation-completeness question, not a real gap.

Re-logged, not new: inventory's 3 pre-existing v1.5 deferrals (stock_movement.movement_type's missing 'produced' value, stock_movement_line.from_site_id/to_site_id, variant_uom_conversion) were already deferred in v1's own design rationale — the audit found they'd simply fallen out of active OPEN_ITEMS tracking when inventory was rebuilt in v2, not that they were newly dropped. Re-logged with concrete triggers. crm.customer.tax_exempt_id's removal was likewise found to be correctly documented already (schema_docs/crm.md DR-35) — just never cross-referenced from OPEN_ITEMS; a process nitpick, not a silent loss, closed by a recorded-not-open OPEN_ITEMS row.

Verification discipline: every fix above was independently re-verified by a separate agent instructed to break it, not read the migration and agree — live INSERT reproductions against the running Postgres DB for every claimed rejection and every claimed success case, pg_constraint/pg_indexes cross-checks against the live DDL (not just the Drizzle source), and a genuineness review of every new regression test (asserts exact Postgres error code + exact constraint/column name via cause.objectContaining, adversarially confirmed non-vacuous). One minor gap the independent pass found — inventory's regression suite covered the valid-actor and nullable-omitted cases but not the FK-rejection case — was fixed in the same pass (test L3 added). Full apps/api suite green (336/336) after all three modules' fixes.

Section 4 re-audits: focused re-audits (matching pos-fix's precedent) confirmed no column drift beyond what's listed above, all new CHECKs/indexes compose correctly with existing constraints, no soft-delete-partial-unique gaps introduced, and every new FK's cross-module name/type target verified against the actual live column. See schema_docs/crm.md, schema_docs/inventory.md, schema_docs/pricing.md for full per-table detail and DR-48/DR-49 (crm), DR-63 (inventory), DR-17/DR-18 (pricing) for the inline rationale.

29. orders — Module #15, the Sell Path's Commercial Layer, First Module Built Under Design-Phase Integrity

Decided: 2026-07-07. Design proposed and adversarially verified, then built, tested, and locked the same day.

Context — why this entry is unusually long. orders is the first module designed AND built under the Design-Phase Integrity rules (SCHEMA_DESIGN_RUNBOOK.md Section 0.5 / 2.3.6), written earlier this same day specifically to prevent silent v1→v2 capability loss (the failure class entries #27's addendum and #28 both found after the fact). Section 0.5/2.3.6 requires the 4 mandatory blocks to be authored BEFORE the table list at design time, and requires the resulting delta-accounting record to be retained here, in PROJECT_DECISIONS.md, at build/lock time — not just delivered in a chat proposal and discarded. This entry is that retained record, verbatim from the approved design, plus the build that followed it. Section 6 item 15's lock-gate grep-verifies this entry exists with real content before orders may lock — this is that gate's first real application, immediately following its own creation.

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS (retained verbatim from the approved design proposal)

BLOCK 1 — v1→v2 Delta Summary. v1: 7 tables / 133 columns → v2 built: 7 tables / 173 columns (172 as proposed + accepted_by_actor_id, added per a resolved decision below).

Table v1 cols v2 built cols Δ
order_header 37 44 +7
order_line 26 38 +12
order_payment 20 27 +7
order_fulfillment 19 26 +7
order_fulfillment_line 13 13 0
order_template 9 16 +7
order_template_line 9 9 0
Total 133 173 +40

Zero table-count change. Every added column is either (a) a binding Hard Contract 1 snapshot field from pricing (PROJECT_DECISIONS #26), (b) the standard autonomy pack (actor attribution / automation_source / review seam / decision_provenance), (c) a new idempotency_key for API-driven dedup, or (d) accepted_by_actor_id (the one column added after the proposal, per a resolved decision below).

BLOCK 2 — Consolidation Justification. None. Every one of v1's 7 tables was preserved 1:1 (all BUILT, zero CONSOLIDATED, zero DROPPED). Each already had its own justified lifecycle/cardinality at v1's own design time (order vs. line vs. payment-installment vs. fulfillment-batch vs. fulfillment-line-split vs. reusable-template vs. template-line), and nothing about the autonomy-first pivot or the pricing/inventory/pos seams changes that reasoning. No merge, no fold-into-JSONB, no table dropped for "fewer tables is cleaner." The only within-table restructuring is order_line's price columns (v1's single unit_price_cents → the 6-field Hard Contract 1 snapshot set) — additive, not a reduction (v2 captures strictly more: currency_code, tax_treatment, resolving_price_rule_id, resolved_quantity, none of which v1 had at all).

BLOCK 3 — Full Table + Column Fate. All 7 v1 tables: BUILT.

v1 table Fate v2 name Column-level notes
order_header BUILT orders.order_header 1 column deferred (search_vector — Search module doesn't exist anywhere in v2); 3 identity-user FKs retargeted to identity.actor (widening); accepted_by preserved verbatim as free text AND joined by a new accepted_by_actor_id (both, not either — resolved decision below); 4 v1 service-enforced-only rules promoted to real CHECKs
order_line BUILT orders.order_line unit_price_cents replaced by the 6-field Hard Contract 1 snapshot (additive); price_override/price_override_reason preserved (a capability pos.sale_line itself dropped — orders restores it); 1 v1 service-only rollup rule promoted to a real CHECK
order_payment BUILT orders.order_payment Fully preserved, incl. v1's own GAP F-1 exclusion of gift_card/store_credit tenders (consistent with pos's independent fail-closed decision on the same tenders)
order_fulfillment BUILT orders.order_fulfillment ship_to_address_id upgraded from a documented-real-in-v1 FK to an actually-real FK now that crm.address is live; tracking_number/carrier remain deferred text (v1's own "Module 14" deferral, unchanged); 1 v1 service-only rule promoted to a real CHECK
order_fulfillment_line BUILT orders.order_fulfillment_line Byte-for-byte unchanged — 13 cols, every CHECK preserved, deliberately zero autonomy columns
order_template BUILT orders.order_template Fully preserved, full autonomy pack added
order_template_line BUILT orders.order_template_line Byte-for-byte unchanged — 9 cols, deliberately zero autonomy columns

Every v1 CHECK constraint, index, and FK target was individually accounted for in the design proposal's Derived Schema section — none silently dropped. Independently adversarially re-verified before the design was ever presented (see "Adversarial Design-Phase Verification" below).

BLOCK 4 — Dependency-Blocked Register.

What's blocked Missing dependency Placeholder Concrete trigger
order_header.draft_po_id (special-order → PO link) Purchasing module (not built) Plain nullable UUID, no FK When Purchasing is designed/built → add real FK
order_payment.stripe_payment_intent_id Payments module (not built) Plain nullable text, no FK When Payments module is built
order_payment.charge_account_ref Billing module (not built) Plain nullable text, no FK When Billing module is built (identical treatment to pos.sale_payment.charge_account_ref)
order_fulfillment.tracking_number / .carrier A Shipping/Fulfillment/Delivery module (not built; MODULE_INDEX already carries a placeholder row for a future delivery module depending on orders+admin) Plain nullable text, no FK/enum (v1's own "Module 14" deferral, unchanged) When the Delivery/Shipping module is designed/built
order_header.search_vector Search module (doesn't exist anywhere in v2 yet) Column doesn't exist at all (matches every other locked module) When Search module is designed/built in v2
order_header.order_number fuzzy/trgm search pg_trgm extension not enabled (already-logged gap, identical to inventory's own deferred trgm indexes) No index built Same trigger as inventory's existing row: when pg_trgm is enabled
Same-module: no OrderService yet This module's own future service layer Schema-only this pass (matches every other module's identical placeholder) When OrderService is built
Same-module: cross-consumer oversell (order + POS both grab the last unit) InventoryService.completeSale()'s stock-oversell detection (not yet built — same gap pos already logged, now shared by a second writer) inventory.pos_sync_conflict's conflict_type enum is generic enough to already cover this; no orders-specific schema gap Same trigger as pos's existing OPEN_ITEMS row: when InventoryService.completeSale()/reserve() implement oversell detection — extend to cover orders as a second writer, don't duplicate the row
Cross-reference, not new: agent discount/margin ceiling on order_line.price_override agent_duty_grant.spend_limit_cents has no cumulative tracking (already logged against identity/pricing/ai) N/A Same trigger as the existing identity/pricing/ai rows — resolve once, not per-module
New this pass: order_header.attributes JSONB per-vertical example shape Real vertical-attribute needs not yet known (resolved decision below — deferred to build, not design) JSONB column exists, DEFAULT '{}', no documented example shape yet When real vertical-attribute needs are known
New this pass: a Files-module seam (signed quote/contract document) Files module (doesn't exist in v2) No column added — v1 never had one either When Files is designed/built AND a signed-document requirement is confirmed for orders specifically

Net capability change vs. v1: none lost, several gained (real CHECKs replacing v1's service-only rules, price_override tracking restored beyond what pos itself kept, real FKs where v1 had to leave things aspirational).

Adversarial Design-Phase Verification (before the proposal was ever presented)

An independent agent adversarially re-derived the v1→v2 column fate from scratch and hunted for anything silently dropped, narrowed, or under-disclosed — the Design-Phase Integrity rules applied to themselves on their first real use. Found and fixed 5 real issues before the proposal was shown for approval:

  1. order_header's cancelled-CHECK silently dropped the actor-attribution requirement. v1 required 3 non-null fields on cancellation (cancelled_at, cancelled_by_user_id, cancellation_reason); the first draft's promoted CHECK only required 2, quietly dropping the actor. Fixed: chk_order_header_cancelled_requires_actor_reason now requires all 3 — confirmed live in the built schema, and regression-tested (block F, tests F1-F4 below).
  2. Every table's index list was entirely unaddressed in the first draft — a real disclosure gap. Most concerning: v1's order_number fuzzy/prefix search index (GIN ... gin_trgm_ops) was never mentioned. Fixed: full index lists included per table in the design; the trgm index correctly classified DEFERRED (same already-logged pg_trgm-not-enabled gap inventory carries), not silently dropped — confirmed absent live at build time (Block 4 above).
  3. order_payment's amount_due_cents/amount_paid_cents non-negativity CHECKs went unmentioned while a sibling CHECK on the same table was carefully disclosed. Fixed: both explicit in the design and built live (chk_order_payment_amount_due_nonneg, chk_order_payment_amount_paid_nonneg).
  4. order_line and order_fulfillment's partial autonomy packs had no stated reasoning. Re-examined against this project's own established tier precedent (full pack = a decision-bearing row with live financial/legal effect, matching price_rule/customer/sale; light/no pack = subordinate/mechanical, matching crm.contact/price_change_log/pos_sync_conflict): both tables actually belong in the full-pack tier. Fixed: both upgraded to the full 7-column pack before the proposal was ever shown — independently reconfirmed correct by the user's own resolved decision (below).
  5. The confirmed_at-required CHECK silently widened beyond v1's literal text (v1 only required it for status='confirmed'; the draft extended it to every later status) — a reasonable call, presented as a mechanical promotion when it was actually new scope. Fixed: disclosed explicitly as a deliberate widening for review, not hidden inside a "same as v1" framing — independently reconfirmed correct by the user's own resolved decision (below).

5 Resolved Decisions (from the design's open questions, applied at build time)

  1. accepted_by — kept the free-text column AND added accepted_by_actor_id (FK → identity.actor, nullable) alongside it. Both, not either. accepted_by keeps v1's free-form acceptance-evidence capacity (a name, an email quote, a verbal-confirmation note); accepted_by_actor_id additionally tracks which staff member (or agent) recorded the acceptance, when applicable. Confirmed live — both columns present on order_header.
  2. confirmed_at CHECK — widened as proposed: required once status reaches 'confirmed' or later (confirmed,fulfilling,partially_fulfilled,fulfilled,closed) — more correct than v1's single-state text, since an order can't logically be "fulfilling" without ever having been confirmed. Confirmed live: chk_order_header_confirmed_requires_timestamp.
  3. order_line + order_fulfillment — full 7-column autonomy pack, per the adversarial re-derivation (finding 4 above); both carry live judgment/anomaly surface matching price_rule/sale's own tier. Confirmed live on both tables.
  4. attributes JSONB shape — deferred to build; documented with an illustrative example in module_spec/orders.md; the GAP is logged to OPEN_ITEMS with trigger "when real vertical-attribute needs are known" (Block 4 above).
  5. Files seam — out of scope (v1 never had one, Files doesn't exist). Registered in Block 4 as a potential future dependency (signed quote/contract doc), no build this pass.

The 3 Named Seams (confirmed live in the built schema)

  1. The reservation seam. order_line.stock_reservation_id → inventory.stock_reservation — a real FK (confirmed live via \d orders.order_line), not deferred. stock_reservation.source_type already anticipated 'order' as a CHECK-enum value before this module existed. Reserve-vs-move is inventory's own unchanged distinction: a reservation only soft-holds (reduces stock.available_qty via reserved_qty), never moves physical stock; fulfillment later writes a real stock_movement row for the actual decrement. Reserve-on-confirm, not on quote (v1's own rule, preserved).
  2. The pos-fulfillment seam. order_header.fulfilled_sale_id → pos.sale (ON DELETE RESTRICT) and order_payment.pos_sale_payment_id → pos.sale_payment — both real FKs, confirmed live. pos.md itself has zero mention of this seam — CROSS_MODULE_CONTRACTS.md is the actual seam catalog and correctly documents it as real-but-not-yet-built until orders existed ("FK lives entirely on Orders' side, pos.sale needs no reciprocal column," "link-don't-convert... tax finalizes at POS"). The seam catalog is the source of truth, not every module's own doc — pos.md's silence was never a gap.
  3. Price-snapshot honoring (Hard Contract 1, PROJECT_DECISIONS #26). order_line carries all 6 required fields verbatim, matching pos.sale_line's own field names/types: resolved_amount_minor_units, charged_amount_minor_units, currency_code, tax_treatment, resolving_price_rule_id, resolved_quantity. Binding, not a design choice — pricing.md names orders as the second required consumer of this exact shape. Confirmed live (all 6 fields present, correct types) and regression-tested (block E below): the snapshot survives the resolving price_rule being superseded to a new price.

Build Verification

7 tables, 173 columns exactly (order_header=44, order_line=38, order_payment=27, order_fulfillment=26, order_fulfillment_line=13, order_template=16, order_template_line=9), verified live via information_schema.columns. 46 CHECK constraints, 43 FK constraints total, verified live via pg_constraint. RLS enabled + a <table>_tenant_isolation policy on all 7 tables (verified live via pg_policy). platform.set_updated_at() (the shared, reused trigger function — no new one-off written) fires on all 7 tables. Idempotency two-partial-unique split confirmed live and NULL-distinctness-checked: order_number is NOT NULL (no trap possible); both idempotency indexes explicitly exclude idempotency_key IS NULL rows (WHERE ... AND idempotency_key IS NOT NULL AND deleted_at IS NULL), so rows with no idempotency key never collide — confirmed via pg_indexes. pg_trgm GIN index on order_number confirmed absent live (correctly deferred, not silently dropped).

41 regression tests, all green (apps/api/src/orders/__tests__/orders-schema.spec.ts): table existence + RLS (7 tables), RLS policy correctness spot-check, the reservation seam, the pos-fulfillment seam (incl. an ON DELETE RESTRICT proof — deleting a referenced pos.sale is rejected with 23503/order_header_fulfilled_sale_id_fkey), the Hard Contract 1 price-snapshot-survives-supersession regression, the cancelled-requires-3-fields regression (all 3 missing-field combinations rejected, all-3-present succeeds), quote-requires-expiry, the line-quantity-rollup CHECK, idempotency dedup (both the actor-scoped and NULL-actor-scoped partial uniques, plus a different-key-succeeds case), FK resolution across all 10 cross-module targets, and full autonomy attribution (automation_source='agent' + decision_provenance JSONB resolving to identity.actor) on all 5 full-pack tables. Full apps/api suite green after (377/377, 21 suites).

Section 4 self-audit (A-P+T+U): zero FAILs. Item J (JSONB shape) closed per resolved decision 4 above (attributes shape documented + OPEN_ITEMS-logged, decision_provenance already covered by the project-wide convention). Item P (module-level rationale) satisfied via this entry plus module_spec/orders.md's DR-N citations. Item U (Design-Phase Integrity blocks present and genuine) — satisfied by this entry itself being the retained record the rule requires.

No OrderService exists yet — schema-only this pass, same pattern as every other module's deferred service layer.

See schema_docs/orders.md and module_spec/orders.md for full per-table/per-DR detail.

30. purchasing — Module #16, the BUY Path, Completing the Supply Loop

Decided: 2026-07-07. Designed, adversarially verified, built, tested, and locked the same day. Second module built under the Design-Phase Integrity rules (after orders).

Context. purchasing is the inbound supply chain — the buy-side counterpart to orders/pos' sell side. It closes the loop: orders/pos sell stock OUT (a stock_movement decrement); purchasing brings stock IN (a stock_movement receipt). This entry is the retained v1→v2 delta-accounting record the Design-Phase Integrity rules require (Section 0.5/2.3.6), grep-verified in-file at lock (Section 6 item 15).

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS (retained from the approved, adversarially-verified proposal)

BLOCK 1 — v1→v2 Delta Summary. v1: 16 tables / 341 columns → v2 built: 16 tables / 398 columns (+57). Zero table-count change.

Table v1 v2 Tier
vendor 31 37 FULL (+linked_customer_id, −search_vector)
vendor_contact 14 16 LIGHT
vendor_address 16 17 LIGHT (global reshape)
vendor_item 22 29 FULL
purchase_order 38 44 FULL
purchase_order_line 24 30 FULL
purchase_order_template 9 15 FULL
purchase_order_template_line 10 10 ZERO
purchase_receipt 23 30 FULL (+idempotency_key)
purchase_receipt_line 25 27 LIGHT
vendor_invoice 33 39 FULL
vendor_invoice_line 18 20 LIGHT
vendor_invoice_match 16 18 LIGHT
vendor_credit 23 24 LIGHT (resolved)
vendor_return 22 23 LIGHT (resolved)
vendor_return_line 17 19 LIGHT
Total 341 398 7 FULL / 8 LIGHT / 1 ZERO

Added columns are (a) autonomy-tier additions, (b) a receiving idempotency_key (v1's rationale intended it, the schema omitted it), and (c) vendor.linked_customer_id. The only removal is vendor.search_vector (Search deferred). Global reshapes + currency-default drops are net-0.

Autonomy tier definitions (a deliberate, disclosed choice): FULL = created_by_actor_id + automation_source + review seam + decision_provenance; LIGHT = created_by_actor_id + automation_source (no review seam, no decision_provenance); ZERO = none. Note: purchasing's LIGHT tier carries automation_source uniformly — a deliberate deviation from crm's lighter created_by-only tier, justified because knowing human/agent/system provenance is useful on every purchasing row given the module's rich agent surface (reorder/OCR/cost-flag). This was the one substantive correction the adversarial pass surfaced (it initially mis-cited crm as the match); it is now disclosed as a deviation, not claimed as a match.

BLOCK 2 — Consolidation Justification. None. All 16 v1 tables preserved 1:1 (zero CONSOLIDATED, zero DROPPED). Four consolidation candidates were actively considered and rejected on load-bearing grounds: contact/address→JSONB (per-row FK + per-type uniqueness + queryability lost), invoice_line→header (line grain is load-bearing for the N:M 3-way match), match→scalar status (genuinely N:M), template pair→PO (independent lifecycle). Vendor-master-stays-in-purchasing-not-crm preserved v1's explicit guard (vendors and customers are fundamentally different relationships). No table dropped for "fewer tables is cleaner."

BLOCK 3 — Full Table + Column Fate. All 16 v1 tables: BUILT. Key column-level fates: vendor.search_vector DROPPED (Search deferred); vendor_address GLOBAL-RESHAPED (us_state_code→region_code/shared.administrative_region, country_code NOT NULL/shared.country, 'US'/'USD' defaults dropped, +region/country CHECK — mirrors crm.address incl. its 2026-07-07 NOT-NULL erosion fix); purchase_receipt +idempotency_key; the 3 v1 DEFERRED forward-ref FKs (purchase_receipt_line.inventory_movement_id, vendor_return_line.inventory_movement_id, purchase_order.source_order_id) become REAL FKs (targets exist live); vendor.linked_customer_id ADDED (nullable, real FK → crm.customer); all *_by_user_id retargeted to identity.actor; all currency_code defaults dropped; the dual-UOM cost snapshot on purchase_order_line preserved verbatim; vendor_invoice.status keeps its no-'paid' invariant (Billing owns payment via write-back columns). v1's own column names inventory_movement_id KEPT on both receipt/return lines (no undisclosed rename — the adversarial pass flagged an earlier draft's rename).

BLOCK 4 — Dependency-Blocked Register. (Each has a real OPEN_ITEMS row with a concrete trigger.)

  • vendor_invoice.billing_ap_ref/.payment_status_ref/.paid_at, purchase_order.amount_paid_cents — Billing not built (write-back placeholders, no FK) → when Billing is built.
  • purchase_receipt.shipment_photo_ref — Files not built (plain text, v1's own forward-ref) → when Files is built.
  • vendor.search_vector + (name gin_trgm_ops) — Search not built / pg_trgm not enabled → when Search is built / pg_trgm enabled.
  • No PurchasingService yet — schema-only this pass → when built.
  • The reorder→PO autonomy loop (agent reads inventory.stock.reorder_point/reorder_qty, drafts a PO) — reorder-detection service not built → when the reorder service is built.
  • AI Invoice OCR draft — no OCR/document-extraction pipeline exists → when built.
  • Cumulative agent spend-ceiling — CROSS-REFERENCE (not a new row) to the existing identity row 114 / ai row 133 / pricing row 142; deferred by decision (see below).
  • Over-receipt / stock-race idempotency — CROSS-REFERENCE to pos/orders' existing InventoryService idempotency rows.

Adversarial Design-Phase Verification (before the proposal was approved)

An independent agent re-derived the v1→v2 fate against the live DB + v1 schema. It verified all 16 FK targets clean, the reorder-signal correction (the signal lives on inventory.stock, NOT stock_adjustment_request), and the spend-ceiling reasoning; and found 3 BLOCKER + 2 disclosure issues, all resolved before build: (1) a vendor off-by-one; (2) three conflicting column totals; (3) the LIGHT-tier mis-citation of crm (now disclosed as a deliberate deviation, see Block 1); (4) purchase_receipt_line's LIGHT tier needed a stated justification vs orders' DR-E (added); (5) the inventory_movement_id→stock_movement_id rename (reverted — v1's name kept).

5 Resolved Decisions

  1. Vendor entity — separate purchasing-owned vendor (NOT a crm variant, per v1's guard) + a new nullable vendor.linked_customer_id → crm.customer (real FK) for the grower-who-also-buys-retail overlap. Both, not either.
  2. Spend-ceiling — DEFER the identity reopen. A reorder agent only DRAFTS a PO; PO-send is needs_approval ALWAYS (the C8 financial-autonomy boundary), so a human is in the loop at every real money commitment. Per-PO agent_duty_grant.spend_limit_cents (bounding the draft) + ai.agent_usage_period (aggregation) suffice for v1. The cumulative ceiling becomes load-bearing only when a may_act_alone PO-send-under-budget is contemplated — cross-referenced to the existing identity/ai/pricing rows, no duplicate row.
  3. vendor_return + vendor_credit — LIGHT (not full). They are human/mechanical AP processes, not agent-proposal surfaces. Confirmed live: no review seam on either.
  4. Scope — all 16 tables built (nothing blocked; deferring the AP tail has no capability justification).
  5. Invoice OCR — schema-ready via vendor_invoice's full pack; the OCR pipeline logged to OPEN_ITEMS.

The Seams (all confirmed live in DDL)

  • The receiving seam (the inbound counterpart to a sale's outbound decrement): purchase_receipt_line.inventory_movement_id → inventory.stock_movement — REAL FK (movement_type='received', source_module='purchasing'). Receiving calls InventoryService.receive(idempotency_key), which writes the movement AND updates item_variant.avg_cost_cents (weighted-average). purchase_receipt.idempotency_key (NEW, NULL-safe unique) dedups a re-run. Purchasing NEVER writes inventory.stock directly (v1 guard). Live-tested: positive JOIN + bogus-FK rejection.
  • The orders seam (both directions): purchase_order.source_order_id → orders.order_header (special order); AND the reciprocal orders.order_header.draft_po_id → purchasing.purchase_order — the forward-ref orders locked with, now CLOSED by an ALTER in purchasing's migration (v1's planned closure; a single FK constraint on an existing column, not an orders reopen). Live-tested both ways + bogus-FK rejection.
  • The return seam: vendor_return_line.inventory_movement_id → inventory.stock_movement (movement_type='returned', outbound to vendor).
  • The vendor↔customer link: vendor.linked_customer_id → crm.customer (nullable). Live-tested.
  • The reorder signal (read-only): a reorder agent reads inventory.stock.reorder_point/reorder_qty/available_qty — a correction to the task's premise (the signal lives on inventory.stock, not stock_adjustment_request, which is the adjustment gate). purchase_order is the buy-side propose/execute counterpart to stock_adjustment_request's pattern, not an FK to it.

Build Verification

16 tables, 398 columns exactly (verified live via information_schema.columns; per-table counts match Block 1). 61 CHECK, 111 FK constraints; RLS + <table>_tenant_isolation on all 16; platform.set_updated_at() (shared, reused) on all 16. Receipt idempotency unique is NULL-safe (WHERE idempotency_key IS NOT NULL AND deleted_at IS NULL); all number/code uniques are WHERE deleted_at IS NULL. vendor_invoice.status CHECK excludes 'paid'. return/credit carry no review seam (LIGHT confirmed live). 6 v1 service-only rules promoted to real CHECKs (PO-approved-requires-actor/at, invoice disputed/void/approved-requires-timestamp, invoice-line item-requires-variant, return rma-required-when-authorized, return authorized-when-not-draft, match resolved-requires-actor/at).

35 regression tests, all green (apps/api/src/purchasing/__tests__/purchasing-schema.spec.ts): 16-table existence + RLS, RLS policy correctness, the receiving seam (positive JOIN + bogus-FK rejection), the orders seam both directions + bogus-FK rejection, linked_customer_id resolution, receipt idempotency dedup + NULL-distinctness, the dual-UOM cost snapshot frozen, agent-drafted PO (automation_source='agent' + review_status='pending' + decision_provenance → actor), return/credit LIGHT (no review column), and CHECK regressions (invoice rejects 'paid', rma-when-authorized, approved-requires-at, item-requires-variant). Full apps/api suite 412/412 green run serially (--runInBand); under default parallel execution 3 identity tests can intermittently fail on a pre-existing shared-DB race on global identity tables (they pass 25/25 in isolation) — unrelated to purchasing's schema.

Section 4 self-audit (A-P+T+U): zero FAILs. Item J (JSONB shapes: vendor.attributes/blackout_config, vendor_item.attributes, purchase_receipt.attributes) logged to OPEN_ITEMS. Item U satisfied by this entry.

No PurchasingService yet — schema-only this pass. See schema_docs/purchasing.md and module_spec/purchasing.md.

31. tax — Module #17, the First Module with Zero v1 Precedent

Decided: 2026-07-07. Designed (jointly with billing, PROJECT_DECISIONS #32), adversarially verified, built, tested, and locked the same day.

Context. tax closes a real, already-logged gap: pos's own 19-to-9 audit found sale_line.tax_amount_cents/tax_rate are a flat aggregate with no per-jurisdiction breakdown — logged as OPEN_ITEMS' PRE-CUSTOMER decision (must resolve before the first customer transacts in a multi-jurisdiction/stacked-tax location, or when a real Tax module is built). This entry is that trigger firing. v1 never had a Tax module at all — v1's architecture assumed tax was 100% outsourced to Stripe Tax (Payments' MODULE_INDEX row: "tax → Stripe Tax"; Admin's: "tax config (Stripe Tax)"), confirmed via find docs/old -iname "*tax*" returning zero results. This is the first module in this build sequence where Design-Phase Integrity's Blocks 1–3 have no v1 to diff against — disclosed honestly below, not fabricated.

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS

BLOCK 1 — v1→v2 Delta Summary. v1: 0 tables / 0 columns (fully outsourced, zero local schema) → v2 built: 2 tables / 37 columns. Not a migration — new schema, required by an already-logged live gap, not invented scope.

Table Cols Tier
tax_calculation 28 FULL
tax_calculation_jurisdiction 9 ZERO (append-only)
Total 37

BLOCK 2 — Consolidation Justification. N/A — no v1 tables exist to consolidate. The 2-table split (header vs. per-jurisdiction breakdown) was itself scrutinized (by the design-phase adversarial pass, PROJECT_DECISIONS proposal discussion) against Section 2.3.3's over-table discipline and found justified: different cardinality (1:N), different mutability (header correctable-via-supersede; jurisdiction rows strictly append-only, no correction mechanism at all), different query shape (jurisdiction-level remittance needs its own indexable rows). A JSONB-consolidation alternative was considered and rejected — a JSONB blob can't carry a FK-enforced append-only guarantee and is one UPDATE away from resurrecting the exact collapsed-tax problem this module exists to fix. No local rate/jurisdiction master tables — deliberately; Stripe Tax owns rate/jurisdiction rules, Admin owns nexus/registration config (v1's own placement, re-confirmed, not duplicated).

BLOCK 3 — Full Table + Column Fate. Both tables: NEW.

  • tax_calculation (28, FULL): header — source (pos/orders/manual, polymorphic source_ref → pos.sale_line/orders.order_line, link-don't-require-reciprocal, no pos/orders reopen), customer, applied exemption certificate, provider (stripe_tax/manual/exempt), totals, is_estimate (orders-time estimate vs. pos-time final — resolved decision 3: kept), supersedes_calculation_id (self-FK, scoped to same-source_ref corrections only — the adversarial-caught fix, see below). Full autonomy pack — the nexus/rate-anomaly-flagging surface, never a rate-computing one.
  • tax_calculation_jurisdiction (9, ZERO, append-only — no updated_at/deleted_at at all, confirmed live): one row per (calculation, jurisdiction) — restores v1's own pre-pivot granularity (state/county/city/district/special) that pos.sale_line's collapse made unrecoverable. Zero autonomy columns — pure decomposition fact, matching every other zero-tier line table's reasoning.

BLOCK 4 — Dependency-Blocked Register.

What's blocked Missing dependency Placeholder Concrete trigger
tax_calculation.provider_ref (Stripe Tax's own calc ID) Payments module (owns all Stripe) not built Plain nullable text, no FK When Payments is built
Actual Stripe Tax API calls TaxService doesn't exist Schema-only this pass When TaxService is built
Nexus/rate-anomaly detection logic No nexus-monitoring service exists (nexus registration itself is Admin's scope, out of this module) Review seam ready; nothing populates it yet When a nexus-monitoring capability is built — cross-reference Admin's "tax config" scope, don't duplicate
billing.ar_charge.tax_calculation_id Billing built same day, second module (#32) Real FK, resolved together Resolved by PROJECT_DECISIONS #32
The orders-estimate → pos-final reconciliation — an adversarial design-phase pass caught that an earlier draft over-claimed this as "a service-layer reconciliation, not a schema gap." It isn't: no line-level link exists anywhere between orders.order_line and pos.sale_line (only the header-level order_header.fulfilled_sale_id does), so supersedes_calculation_id cannot bridge an is_estimate=true row to its later pos-time final. A line-level order_line↔sale_line seam, which doesn't exist anywhere in the codebase today is_estimate exists for labeling only Resolved decision 1, option (b): is_estimate=true (orders) and is_estimate=false (pos) rows deliberately COEXIST as separate, un-superseded records — reconciled only at report time via the existing header-level order_header.fulfilled_sale_id join. No line-level seam is being built; if one becomes a real product requirement, it belongs to a dedicated orders/pos reopen, not a side effect of this module.

Adversarial Design-Phase Verification (before the proposal was approved)

An independent agent re-derived both tax's and billing's design from scratch. Found 2 real blockers, both fixed before build: (1) an over-claimed reconciliation — the orders↔pos "supersession" was asserted as solved when it structurally cannot be (see Block 4 above; resolved via option (b), not a schema fix); (2) billing's Block 4 silently missed a second Purchasing write-back target (purchase_order.amount_paid_cents) — see PROJECT_DECISIONS #32. All other checks passed independently: every live FK target, both modules' full column arithmetic, the "no v1 tax module exists" claim (confirmed via find), the tax-tier autonomy reasoning, and the 2-table split.

Resolved Decisions

  1. Orders↔pos reconciliation = option (b): coexist, reconcile header-level at report time. No auto-supersession across modules; supersedes_calculation_id narrowed to same-source_ref corrections only (the adversarial fix, built as such — confirmed live).
  2. automation_source defaults 'system' — the FIRST justified deviation in the entire codebase from the universal 'human' default (confirmed live: every other automation_source column across every locked module defaults 'human', zero exceptions before this). Deliberate: a tax calculation is a deterministic, externally-computed result (Stripe Tax), never a human action recorded after the fact. This is a precedent other genuinely-deterministic-by-default future tables may cite, not a one-off exception.
  3. is_estimate kept — see resolved decision 1.
  4. tax_calculation_id lives on billing.ar_charge ONLY — statements derive jurisdiction-level tax by joining through ar_charge at report time; no duplication onto ar_payment/ar_statement.

Build Verification

2 tables, 37 columns exactly (tax_calculation=28, tax_calculation_jurisdiction=9), verified live. 14 CHECK, 10 FK constraints. RLS on both tables; 2 triggers, both on tax_calculation only — platform.set_updated_at() and trg_tax_calculation_validate_supersession (added by the addendum below) — the jurisdiction child has no updated_at column at all and no triggers (append-only enforced by the table shape, not asserted in a paragraph, confirmed live). automation_source confirmed live defaulting 'system'.

24 regression tests, all green (apps/api/src/tax/__tests__/tax-schema.spec.ts): table existence + RLS, RLS policy correctness, the source_ref seam (resolves to a real pos.sale_line), the append-only structural guarantee (jurisdiction table has zero updated_at/deleted_at columns; the header correctly does have both), total_tax_amount_cents = SUM(jurisdiction rows) proven against a real 3-jurisdiction stacked-tax fixture (state+county+district), same-source_ref supersession proven, the coexist-don't-bridge behavior for an is_estimate=true row proven, the anomaly-flag review seam (automation_source='agent' override + review_status='pending' + decision_provenance → identity.actor), the exemption seam (resolves to crm.customer_tax_certificate), FK resolution across all targets, and CHECK regressions (invalid source pair, manual-with-source-ref, pos-without-source-ref, invalid provider). Full apps/api suite green after (see PROJECT_DECISIONS #32 for the combined final count, billing built same pass).

Section 4 self-audit (A-P+T+U): zero FAILs at build time. Item U satisfied by this entry disclosing the "no v1 exists" case honestly rather than fabricating a diff, and by the orders↔pos gap being registered in Block 4 rather than silently asserted as solved. Superseded in part by the post-lock independent verification addendum below, which found the same-source_ref scoping (resolved decision 1) was documented but not yet DB-enforced — an Item T (trigger audit) gap, closed same day.

No TaxService yet — schema-only this pass. See schema_docs/tax.md and module_spec/tax.md.

Addendum (2026-07-07, same day) — post-lock independent verification found and closed a real enforcement gap

Two independent, non-self-grading verification agents were run against the built schema (the standing Section 6 lock-gate practice). Both, separately, caught the same real gap: resolved decision 1's "supersedes_calculation_id scoped to same-source_ref corrections only" was, as originally built, a documented convention with no CHECK or trigger enforcing it — a live cross-source_ref supersede attempt (two rows with different source_ref values, one's supersedes_calculation_id set to the other's id) succeeded silently. A plain CHECK cannot express this (it requires comparing against a different row), so it was never expressible as one — it needed a trigger, which the original build omitted.

Fix: trg_tax_calculation_validate_supersession (BEFORE INSERT OR UPDATE OF supersedes_calculation_id), mirroring pricing.trg_price_rule_validate_supersession exactly — rejects any supersedes_calculation_id whose target doesn't share the same tenant_id/source_module/source_type/source_ref. Added to the migration (packages/db/migrations/20260707080000_tax_module.sql, before lock/commit — no separate reopen needed since this was caught pre-commit), applied live, live-reproduced (cross-source_ref rejected; same-source_ref still succeeds), and covered by a new regression test (tax-schema.spec.ts test F3). One of the two verification agents also independently found the new test's first assertion was itself buggy (checked the top-level error message instead of the driver's .cause.message, the same pattern the H-block tests already used correctly) — fixed, re-run, 24/24 green.

This is the same class of catch the adversarial design-phase pass exists for (see above), just running one stage later — against the built schema instead of the proposed one. Consistent with this session's standing practice: independent verification is not a rubber stamp, and a real finding gets fixed same-day, not deferred.

32. billing — Module #18, the SETTLE Half of the Financial Layer

Decided: 2026-07-07. Designed jointly with tax (PROJECT_DECISIONS #31), adversarially verified, built, tested, and locked the same day, immediately after tax.

Context. tax calculates what's owed; billing settles the money. v1 had a real, locked Billing module (docs/old/schema/schema_modules/schema_billing.md, docs/old/design_rationale/rationale_billing.md) — 8 tables / 113 columns, self-verified against the file's own per-table headers. Flags: pre-autonomy (all *_user_id, not identity.actor), pre-tax (no seam to a tax module — didn't exist until #31 built it same day).

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS

BLOCK 1 — v1→v2 Delta Summary. v1: 8 tables / 113 columns → v2 built: 9 tables / 162 columns (+1 table, +49 cols).

Table v1 v2 built Δ Tier
ar_account 12 19 +7 (full pack; v1 had no actor col at all) FULL
ar_charge 19 26 +6 full-pack cols + tax_calculation_id (NEW seam) FULL
ar_payment 17 23 +6 (full pack, actor col retargeted net-0) FULL
ar_payment_application 8 9 +1 (automation_source) LIGHT
ar_statement 19 21 +2 (created_by_actor_id+automation_source) LIGHT
vendor_payable 14 16 +2 (created_by_actor_id+automation_source) LIGHT
ap_payment 16 17 +1 (automation_source) LIGHT
ap_payment_application 8 9 +1 (automation_source) LIGHT
ar_adjustment 0 (NEW) 22 +22 (resolved decision 6 — v1 deferred this table entirely) FULL
Total 113 162 +49 3 FULL(+1 new FULL) / 5 LIGHT

Zero tables consolidated or dropped. Asymmetric autonomy tiering, disclosed deliberately: A/R (ar_account/ar_charge/ar_payment/ar_adjustment) gets FULL — collections/dunning-flag, payment-matching-ambiguity, and write-off/dispute-resolution are real judgment surfaces. A/P (vendor_payable/ap_payment) and both application junction tables stay LIGHT — the real judgment already happened upstream at purchasing.vendor_invoice's own FULL autonomy gate; paying a vendor once approved is procedural, not a fresh decision billing itself makes.

BLOCK 2 — Consolidation Justification. None. All 8 v1 tables preserved 1:1. A unified ledger_entry with a direction flag (replacing A/R and A/P table sets) was considered and rejected, restating v1's own rationale: A/R and A/P "rhyme structurally but wire to completely different sources" (A/R from pos.sale/orders.order_header/crm.customer; A/P from purchasing.vendor_invoice/purchasing.vendor) with different lifecycles and consumer code. No GL/journal invented (v1's own explicit guard, re-confirmed) — billing stays a control layer over receivables/payables, not double-entry bookkeeping. No re-conflation with Platform's SaaS-subscription billing (a different, unrelated "billing," v1's own guard, re-confirmed).

BLOCK 3 — Full Table + Column Fate. All 8 v1 tables: BUILT, zero columns dropped. ar_charge.source_ref/source_payment_ref are polymorphic (→ pos.sale/orders.order_header and pos.sale_payment/orders.order_payment) — plain uuid, no single-table FK (a polymorphic column cannot carry one; the design proposal's "now REAL FKs" language meant the target schemas now exist to validate against, not that a single-column FK is structurally possible across two different tables), validated instead by the source_module/source_type pair CHECK — identical pattern to tax.tax_calculation.source_ref, established the same day. tax_calculation_id (NEW, nullable, real FK → tax.tax_calculation) is the tax seam. ar_adjustment (22 cols, FULL, NEW) is the write-off/dispute-resolution table v1 deferred (a manual ar_charge with source_type='adjustment' covered v1.0) — built now per resolved decision 6, full autonomy pack, draft→posted lifecycle requiring applied_at once posted.

BLOCK 4 — Dependency-Blocked Register.

What's blocked Missing dependency Placeholder Concrete trigger
ar_payment.stripe_payment_intent_id, ap_payment.stripe_payment_intent_id Payments module not built Plain text, no FK (v1's own forward-ref, unchanged) When Payments module is built
No BillingService yet This module's own future service layer Schema-only this pass When BillingService is built
Write-back to purchasing.vendor_invoice (billing_ap_ref/payment_status_ref/paid_at) BillingService doesn't exist to write it Target columns already exist live on purchasing.vendor_invoice (confirmed) When BillingService is built
Write-back to purchasing.purchase_order.amount_paid_cents (adversarial-caught, PROJECT_DECISIONS #31) BillingService doesn't exist; requires summing across potentially multiple vendor_payable rows per PO Target column exists live (confirmed bigint NOT NULL DEFAULT 0), unwritten When BillingService is built — must maintain as SUM(vendor_payable.paid_amount_cents) across every payable tracing to that PO, not a naive 1:1 copy
Write-back into pos.sale_payment.charge_account_ref / orders.order_payment.charge_account_ref BillingService doesn't exist Target columns exist live (text, no FK) When BillingService is built
Formal customer_invoice/credit_memo, AP payment batches, dunning/collections execution, payment plans, GL posting, multi-currency v1's own Billing Module Boundary deferrals Not built When a concrete product requirement names one
Collections/dunning agent DRAFT surface No collections-detection service exists ar_account/ar_charge review seam is ready; nothing populates it yet When a collections-monitoring capability is built

Adversarial Design-Phase Verification

Run jointly with tax's own proposal (see PROJECT_DECISIONS #31) — found 1 real blocker against billing specifically: purchasing.purchase_order.amount_paid_cents was silently missing as a second write-back target (only the vendor_invoice triple was addressed in the first draft). Fixed by documenting the SUM-rollup nuance in Block 4 above.

Resolved Decisions

  1. ar_adjustment BUILT now (not deferred) — full autonomy pack, changes the table count 8→9. An agent-proposed write-off → human-approve is exactly the pattern this codebase already uses everywhere else (purchasing's reorder-draft, inventory's stock-adjustment-request).
  2. A/R FULL / A/P LIGHT asymmetry kept — disclosed, not accidental (see Block 1).
  3. tax_calculation_id lives on ar_charge ONLY — no duplication onto ar_payment/ar_statement.

Build Verification

9 tables, 162 columns exactly, verified live (ar_account=19, ar_charge=26, ar_payment=23, ar_payment_application=9, ar_statement=21, ar_adjustment=22, vendor_payable=16, ap_payment=17, ap_payment_application=9). 47 CHECK, 47 FK constraints, all 47 FKs confirmed resolving to live targets (crm.customer, purchasing.vendor, purchasing.vendor_invoice, tax.tax_calculation, shared.currency, identity.actor, platform.tenant, plus internal billing.* self-references). RLS on all 9 tables. 7 tables carry set_updated_at; the 2 append-only application tables correctly have none (no updated_at column at all — confirmed live, matching tax.tax_calculation_jurisdiction's identical discipline).

A live NULL-distinctness bug found and fixed during build-time testing (not deferred to post-lock): ar_charge's originally-designed single 5-column idempotency index (tenant_id, source_module, source_type, source_ref, source_payment_ref) treats every NULL as distinct — since source_payment_ref is itself nullable (a charge isn't always tied to one specific payment installment), two charges for the SAME source_ref both landing with source_payment_ref IS NULL would NOT collide, silently defeating retry-dedup for the common event-driven-charge-with-no-payment-ref-yet case. Caught by test E1 failing during the build's own test-writing pass (not by post-lock independent verification this time — closed before any lock-gate ran). Fixed via a two-partial-unique split — ar_charge_idempotency_full_unique (both non-null) + ar_charge_idempotency_no_payment_ref_unique (source_ref present, payment_ref null) — mirroring orders.order_header's own idempotency_key precedent exactly. Live-tested both branches (test E1 + E1b) plus the intentional NULL-distinctness carve-out for manual charges (test E2, source_ref IS NULL — excluded from both indexes by design, multiple manual charges must NOT collide).

47 regression tests, all green (apps/api/src/billing/__tests__/billing-schema.spec.ts): table existence + RLS (9 tables), RLS policy correctness, the tax seam (ar_charge.tax_calculation_id resolves to a real tax.tax_calculation), append-only structural guarantee on both application tables, the idempotency dedup fix (both index branches + the manual-charge NULL carve-out), the A/P seam (vendor_payable resolves to purchasing.vendor_invoice, one-per-invoice UNIQUE enforced), ar_adjustment's draft→posted lifecycle (posting without applied_at rejected, with it succeeds, agent-drafted pending review + decision_provenance → identity.actor), CHECK regressions (source pair, applied≤charge, automation_source enum, reviewer-not-creator), FK resolution across all targets, and automation_source confirmed defaulting 'human' on every billing table (unlike tax_calculation's own 'system' default — the asymmetry is deliberate and disclosed, not an inconsistency). Full apps/api suite 483/483 green after (up from 436 pre-billing).

Section 4 self-audit (A-P+T+U): zero FAILs. Item C/D (NULL-distinctness) caught and fixed the idempotency bug above before any lock-gate ran. Item H (cross-module FK correctness) confirmed all 47 FKs live. Item T (trigger audit) confirmed 7-of-9 tables carry set_updated_at, the 2 append-only tables correctly carry none. Item U satisfied — all 4 blocks present, the A/R-vs-A/P tier asymmetry disclosed, the polymorphic-no-FK correction on source_ref/source_payment_ref documented rather than silently built to match imprecise proposal wording.

No BillingService yet — schema-only this pass. See schema_docs/billing.md and module_spec/billing.md.

Confirm: tax + billing locked, the financial layer complete, the tax decomposition gap CLOSED.

33. payments — Module #19, the Money-MOVEMENT Layer (First Module Under the Evidenced Adversarial-Verification Gate)

Decided: 2026-07-07. Designed, adversarially verified (design-phase), built, independently re-audited (post-build, separate agent), and locked the same day, immediately after billing.

Context. billing (#18) records what's owed/settled; payments executes the actual money movement via Stripe Connect. v1 had a real, locked Payments module (docs/old/schema/schema_modules/schema_payments.md, docs/old/design_rationale/rationale_payments.md) — 8 tables / 112 cols, self-verified against the file's own per-table headers, locked 2026-06-10. Confirmed genuine, not stale (unlike the 6 stale-placeholder rows found in an earlier module-inventory audit) — a thorough, internally-consistent v1 design with its own 79-line rationale doc covering idempotency, the offline-charge lifecycle, and the incoming-only scope decision.

This is the first module built under the new hard evidenced-verification gate (SCHEMA_DESIGN_RUNBOOK.md §2.3.7/§2.7/§6 item 1a, added 2026-07-07 — see Bug Class 12, §5 — directly because this module's own design proposal was originally self-graded "Zero FAILs" and found wrong by a later adversarial pass). Both the design-phase and post-build verification passes below are evidenced with pasted, attributed findings, not claimed.

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS

BLOCK 1 — v1→v2 Delta Summary. v1: 8 tables / 112 columns → v2 built: 9 tables / 158 columns (+1 table, +46 cols).

Table v1 v2 built Δ Tier
stripe_connect_account 14 16 +2 (created_by_actor_id+automation_source) LIGHT
payment_intent 25 32 +7 (full pack, fresh) FULL
payment_refund 15 21 +6 (full-pack minus created_by_actor_id, since refunded_by_user_id retargets to refunded_by_actor_id at net 0 and already fills that role) FULL
payout 13 20 +7 (full pack, fresh) FULL
dispute 14 21 +7 (full pack, fresh) FULL
payment_method 13 15 +2 (created_by_actor_id+automation_source) LIGHT
stripe_event_log 8 8 +0 (ZERO tier preserved verbatim) ZERO
stripe_event_dead_letter 10 10 +0 (same) ZERO
terminal_reader 0 (NEW) 15 +15 (closes OPEN_ITEMS row 185) LIGHT
Total 112 158 +46 4 FULL / 3 LIGHT / 2 ZERO

Zero v1 tables consolidated or dropped. chk_payment_intent_source_pair is counted as a constraint addition, not a column addition — it adds no new columns to payment_intent, only a combined-CHECK enforcement over the existing source_module/source_type pair.

BLOCK 2 — Consolidation Justification. None. All 8 v1 tables preserved 1:1; the one candidate NEW table (terminal_reader) is additive, not a consolidation. payment_intent's polymorphic source_ref/source_type design (one table serving 3 source types instead of per-source-type tables) is v1's own already-proven consolidation, re-confirmed rather than re-litigated.

BLOCK 3 — Full Table + Column Fate. All 8 v1 tables: BUILT. payment_intent: BUILT + RESHAPED — source_module CHECK widened ('pos','billing') → ('pos','billing','orders'); source_type CHECK widened ('sale','ar_payment') → ('sale_payment','order_payment','ar_payment') ('sale'→'sale_payment' rename, disclosed); currency_code loses its hardcoded 'USD' default; plus chk_payment_intent_source_pair, a genuine NEW fix (v1 never had this CHECK either — only two separate enum CHECKs, no combined pairing enforcement). payment_refund: BUILT — refunded_by_user_id→refunded_by_actor_id retarget (net 0); currency default removed; +6 new full-pack cols. payout/dispute: BUILT, currency defaults removed, +7 full-pack cols each, fresh. payment_method: BUILT, +2 LIGHT-pack cols, fresh. stripe_event_log/stripe_event_dead_letter: BUILT, unchanged — preserved verbatim, including stripe_event_log's global (non-tenant-scoped) unique on stripe_event_id, the one deliberate deviation from "all uniques are tenant-scoped" (v1's own documented guard, re-confirmed). terminal_reader: NEW — closes OPEN_ITEMS row 185 (pos.register's v1 hardware-pairing config had no v2 equivalent); carries UNIQUE (stripe_reader_id) WHERE deleted_at IS NULL, matching every other Stripe-ID column in this module.

BLOCK 4 — Dependency-Blocked Register.

What's blocked Missing dependency Placeholder Concrete trigger
payment_refund.amount_cents <= remaining cross-row invariant Not DB-enforceable (requires comparing against a derived value) Documented (v1's own honest framing: "Enforced at service layer") When PaymentsService is built
No PaymentsService yet This module's own future service layer Schema-only this pass When PaymentsService is built
The status-writeback to pos.sale_payment.status/orders.order_payment.status/billing.ar_payment.status PaymentsService doesn't exist to write it Service-layer only, not FK-enforced (v1's own design) When PaymentsService is built
billing.ap_payment.stripe_payment_intent_id stays permanently unwired Deliberate v1 scope boundary — Stripe Connect is incoming-only, vendor payments are manual Nullable text column exists, never populated Not a deferral — a confirmed, permanent exclusion; re-open only via a deliberate future scope-expansion decision
Card-expiry alert job/index v1's own deferred item payment_method.exp_month/.exp_year exist, no supporting index When a card-expiry alert job is written
platform.subscription's "PaymentsService" naming ambiguity — reconciled, not new. An earlier design-phase pass on tax+billing (PROJECT_DECISIONS #31/#32) had already logged this exact seam in CROSS_MODULE_CONTRACTS.md ("Platform | payments | Stripe webhook status normalization — open item — at payments module build") and in OPEN_ITEMS.md. This module's own build is that trigger firing. A distinct Vrida-own-billing ingestion service, not yet built platform.subscription.status's column comment corrected at this build to name the distinct service explicitly The normalization SERVICE itself remains unbuilt — see OPEN_ITEMS' reconciled row
Fraud/anomaly, reconciliation-flagging, chargeback-evidence-drafting agent logic No monitoring/detection services exist Review seams ready (review_status/review_reason/reviewed_by_actor_id on all 4 FULL tables); nothing populates them yet When the respective monitoring/detection services are built

Adversarial Design-Phase Verification (before the proposal was approved — 2 independent passes)

Two independent agents re-derived the design from scratch. Pass #1 (a9b8e751ab63f19c5, after an initial stuck non-answer that had to be resumed with a direct instruction): found no FAILs, but caught 1 real gap — CROSS_MODULE_CONTRACTS.md's existing "Payments" section had zero mention of orders.order_payment as a seam. Pass #2 (abc2515d724f7fc37): found 2 real FAILs the original self-graded Section 4 audit had missed — (1) payment_intent was missing the chk_payment_intent_source_pair CHECK its own audit claimed already existed; (2) an arithmetic error in the automation_source='system' table count ("4 more — 5 total" corrected to "3 more — 4 total"). Plus 2 NOTE-level findings, both fixed: (3) terminal_reader.stripe_reader_id missing its expected UNIQUE; (4) Block 4's platform.md finding hadn't been reconciled against the pre-existing CROSS_MODULE_CONTRACTS.md line 445 row. All 5 findings across both passes were fixed in the proposal before build — see /Users/cnu/Downloads/payments-module-design-proposal.md's own §"Propose-Gate Compliance Checklist" for the full pasted verbatim findings from both passes (reproduced there per the new §2.3.8 requirement). This incident is exactly what motivated the new hard gate — see SCHEMA_DESIGN_RUNBOOK.md Bug Class 12.

Resolved Decisions

  1. terminal_reader — BUILD now. Closes OPEN_ITEMS row 185; needed for the Flutter POS Terminal integration; does not touch pos.register's own locked shape. Built WITH the UNIQUE on stripe_reader_id (the adversarial NOTE #9 fix).
  2. platform.md naming clarification — folded in at this build. platform.subscription.status's column comment corrected to distinguish Vrida's own Stripe billing from this module's PaymentsService; the pre-existing CROSS_MODULE_CONTRACTS.md line-445 row and OPEN_ITEMS.md's platform-normalization row both reconciled in the same pass.
  3. automation_source='system' on stripe_connect_account/payout/dispute — approved, the corrected count: extends tax_calculation's precedent to 3 more tables (4 total in the codebase), scoped precisely to "no human decision point in the row's creation."

Build Verification

9 tables, 158 columns exactly, verified live (stripe_connect_account=16, payment_intent=32, payment_refund=21, payout=20, dispute=21, payment_method=15, stripe_event_log=8, stripe_event_dead_letter=10, terminal_reader=15). 35 CHECK, 32 FK constraints, all resolving to live targets (platform.tenant, crm.customer, multi_loc.site, shared.currency, identity.actor, pos.register, payments.payment_intent self-refs). RLS on all 9 tables with real tenant-isolation policies (not RLS-enabled-with-no-policy). 7 tables carry set_updated_at; the 2 ZERO-tier webhook tables correctly have none. chk_payment_intent_source_pair confirmed live and behaviorally correct (rejects pos+ar_payment, accepts all 3 valid pairs). terminal_reader_stripe_reader_id_unique confirmed live, rejects duplicates. The idempotency/double-charge guard live-tested in all 3 directions: duplicate (tenant_id, idempotency_key) rejected; duplicate stripe_payment_intent_id rejected; legitimate multi-tender (same source_ref, NULL idempotency_key) NOT falsely deduped. All 5 hardcoded 'USD' defaults confirmed removed. stripe_event_log's global unique confirmed non-partial, non-tenant-scoped. platform.subscription.status's corrected column comment confirmed live.

46 regression tests, all green (apps/api/src/payments/__tests__/payments-schema.spec.ts): table existence + RLS (9 tables), RLS policy correctness, the source_pair CHECK (invalid pair rejected, all 3 valid pairs succeed), append-only-by-shape on both webhook tables, the idempotency/double-charge guard (all 3 branches), stripe_event_log's global webhook dedup, terminal_reader's UNIQUE, the forward-ref fills (pos.sale_payment.stripe_payment_intent_id populated + payment_intent.source_ref resolves via JOIN), the refund needs-approval/C8 seam (agent-drafted refund records correctly with decision_provenance → identity.actor), automation_source defaults per table ('system' on 3, 'human' on 4), CHECK regressions (total-charged arithmetic, refunded≤total, reviewer-not-creator), and FK resolution across all targets incl. terminal_reader.register_id → pos.register. Full apps/api suite 529/529 green after (up from 483 pre-payments).

Independent Post-Build Re-Audit — SEPARATE agent, findings pasted (SCHEMA_DESIGN_RUNBOOK §2.7/§6 item 1a, first application)

Auditor: a separate agent (a8654ab532aa15f1d) with no prior involvement in this module's build, per the new hard gate. Full findings, pasted verbatim:

Independent Post-Build Re-Audit — payments (module #19)

Item Check Result Evidence
A/1 Table/column counts PASS Live query: 9 tables, 158 cols total; per-table exact match.
B/2 RLS + real tenant_isolation policy on all 9 PASS pg_class.relrowsecurity=t and exactly 1 pg_policy row (*_tenant_isolation) on all 9 tables — no RLS-with-no-policy gap.
3 CHECK + FK constraint counts, FK targets resolve PASS contype='c' → 35; contype='f' → 32. All 32 FKs resolve to real live tables: platform.tenant(9), identity.actor(10), shared.currency(5), crm.customer(2), multi_loc.site(2), pos.register(1), payments.payment_intent self-ref(2). No dangling/unexpected targets.
4 chk_payment_intent_source_pair exists, logic correct, live-tested PASS pg_get_constraintdef exact match to spec. Live: pos+ar_payment → ERROR: violates check constraint. All 3 valid pairs inserted successfully in one rolled-back txn.
5 terminal_reader.stripe_reader_id UNIQUE PASS pg_indexes confirms index with WHERE (deleted_at IS NULL). Live: duplicate → ERROR: duplicate key value violates unique constraint.
6 Idempotency / double-charge guard (a/b/c) PASS (all 3) (a) same tenant_id+idempotency_key → 2nd insert rejected. (b) same source_ref, both idempotency_key NULL → both inserts succeeded, count(*)=2 — correctly NOT deduped. (c) same stripe_payment_intent_id → 2nd insert rejected.
7 stripe_event_log: tenant_id nullable, GLOBAL unique PASS is_nullable='YES'. Index def has no WHERE clause, confirmed global.
8 5 hardcoded 'USD' defaults removed PASS All 5 currency columns show empty column_default.
9 platform.subscription.status comment updated PASS Live col_description explicitly distinguishes the two services, cites PROJECT_DECISIONS #33 and CROSS_MODULE_CONTRACTS.
10 set_updated_at on exactly 7/9 tables PASS Trigger list shows exactly 7 tables (all except the 2 webhook tables), all BEFORE UPDATE.
11 Test suite 46/46, no fixture leakage PASS "Tests: 46 passed, 46 total." Fixture count = 0 after run.
12 Column-level drift vs. proposal PASS payment_intent/terminal_reader live column order/names/types match the proposal's Step 3 spec exactly.
Doc gate OPEN_ITEMS row for the platform-naming item GAP (in-flight, not a schema FAIL) The pre-existing platform-naming OPEN_ITEMS row was still marked open at audit time, needing reconciliation in the same pass as this doc write — now done (see Resolved Decision 2 and OPEN_ITEMS itself).

Verdict: Zero FAILs found on independent re-audit. All 12 requested live-DB/test checks PASS with direct evidence. The build matches the approved proposal's Step 3 specs column-for-column, and both adversarially-found design-phase fixes (chk_payment_intent_source_pair, terminal_reader UNIQUE) are confirmed live and behaviorally correct under test.

Section 4 self-audit (A-P+T+U): the build-time self-audit is explicitly NOT treated as sufficient on its own for this module (see the design-phase incident above) — the independent post-build re-audit above is the operative verdict. Item U satisfied: all 4 blocks present and genuine, the one NEW table justified against an actual logged OPEN_ITEMS trigger, and the dependency-blocked register discloses the reconciled cross-references rather than treating them as new discoveries.

No PaymentsService yet — schema-only this pass. See schema_docs/payments.md and module_spec/payments.md.

Confirm: payments locked — the money-movement layer is live, verified under the new evidenced gate.

34. Admin ↔ Platform Data-Ownership Boundary — Governing Rule (Reverses v1's Admin Module Scope)

Decided: 2026-07-07. Decided in conversation across a multi-step architecture analysis (independent boundary analysis, a full column-level duplication scan, an adversarially-verified resolution proposal, then a formal design-phase pass on both halves) — this entry is the first durable, written record of that decision. Recorded here specifically because two independent adversarial verifiers, run separately against the platform-reopen and Admin-module design proposals, both found the same gap: the rule below was being applied as settled precedent with no corresponding entry anywhere in this file. This entry closes that gap before either build proceeds.

THE RULE:

  • Platform is the single source of truth for tenant IDENTITY + the Vrida relationship: legal name, EIN, business type, addresses, DBAs, NAICS classification, plan/subscription/entitlements. All of it lives on platform.tenant_profile (plus platform.tenant/subscription/tenant_entitlement for the relationship half).
  • Admin is the tenant's own TECHNICAL/OPERATIONAL configuration only: api_key, integration_config (including Stripe/QuickBooks connector keys), webhook_config, hardware_device, tenant_setting, and the tenant-side approval engine (approval_workflow/approval_routing_rule/approval_request) — plus presentational surface: tenant_branding, compliance_document.
  • Admin references platform.tenant for identity — it never duplicates it. Any Admin-side table that needs to know "what plan is this tenant on" or "what's this tenant's legal name" reads it from Platform; it does not carry its own copy.

REVERSAL, stated explicitly. This supersedes v1's own "Admin Module Scope" decision (docs/old/PROJECT_DECISIONS.md, lines ~1129–1171, decided 2026-06-10), which assigned legal name, business type, EIN (encrypted), operating addresses, DBAs, and branding assets to Admin, not Platform — the concrete implementation of that decision was v1's schema_admin.md tenant_business_profile table (17 cols). That table is dropped entirely under this rule; its identity-shaped content moves to platform.tenant_profile.

WHY:

  1. Single source of truth. A full column-level duplication scan (/Users/cnu/Downloads/admin-platform-full-duplication-scan.md) found admin.tenant_business_profile and platform.tenant_profile were two independently-built, partially-overlapping models of the same real-world fact — a tenant's legal identity — with legal_name/business_type/phone duplicated under identical names on both sides, and website/email/display_name duplicated under different names. Left as two tables, "what is this tenant's legal name" has two possible answers with no rule for which wins.
  2. The EIN security conflict. The same scan found the sharpest instance of this: admin.tenant_business_profile.ein_ref stored the tenant's EIN as a vault reference ("encrypted EIN; never stored raw"), while platform.tenant_profile.tax_id stored the identical fact as plain text with no vault indirection at all. Two schemas disagreeing about whether a tenant's federal tax ID is sensitive enough to encrypt is a real security defect, not a stylistic difference. Platform absorbing identity means Platform must also absorb the correct (vault-referenced) security posture for it — see entry #35, Block 3.
  3. The access-control test. Every Admin table is 100% tenant-authored, tenant-RLS, with zero legitimate service_role/cross-tenant read pattern. platform.tenant_profile is already a Vrida-side control-plane record (onboarding funnel, firmographic bands, CS/growth data) that a tenant's own identity naturally sits alongside — not a tenant-operational concern at all. admin-platform-boundary-architecture-analysis.md (full independent 3-lens analysis + adversarial verification) found 10 of Admin's 11 tables have zero platform overlap and unanimously stay in Admin; only tenant_business_profile's identity content crosses the line, for the two reasons above.

SECTION 5 — Approval-engine convergence: DECIDED AS OPTION B. Admin's generic tenant-side approval engine (approval_workflow/approval_routing_rule/approval_request) stays tenant-scoped, tenant-RLS, serving tenant-internal business-process approvals (PO/discount/refund) — designed so purchasing/pricing/payments' own tenant-side approval needs can route through this same engine going forward. platform.contract's own bolted-on review gate (review_status/review_reason/reviewed_by_actor_id/reviewed_at, added 2026-07-06) stays separate and untouched — it is Vrida-operator-reviewed control-plane data, on the opposite side of this same boundary, not a candidate for convergence. Admin's own RLS model assumes the reviewer is the tenant itself, which doesn't fit a Vrida-operator cross-tenant review flow.

BLOCK 3 — full 17-column fate of admin.tenant_business_profile (permanent record, all 17 named, not a hedge):

v1 column Fate
id Dropped with table — row-identity artifact, no independent meaning
tenant_id Dropped with table — platform.tenant_profile already has its own
created_at Dropped with table — platform.tenant_profile already has its own
updated_at Dropped with table — platform.tenant_profile already has its own
deleted_at Dropped with table — platform.tenant_profile is 1:1 with tenant, not independently deletable
legal_name MOVED — exact duplicate of platform's existing legal_name; platform's wins, no new column
business_type MOVED — exact duplicate of platform's existing business_type; platform's wins, no new column
phone MOVED — exact duplicate of platform's existing phone; platform's wins, no new column
website MOVED — renamed onto platform's existing website_url, no new column
email MOVED — becomes platform's NEW business_email (NOT the same fact as support_email)
display_name MOVED — absorbed into platform's EXISTING trading_name slot (retyped, see below)
dbas MOVED — REPLACES platform's trading_name (text → JSONB dbas, retype)
primary_address MOVED — becomes platform's NEW legal_address (platform's own JSONB shape convention, not admin's old shape)
mailing_address MOVED — becomes platform's NEW mailing_address
business_classification MOVED — becomes platform's NEW business_classification_code (NAICS)
ein_ref MOVED — becomes platform's NEW ein_ref (same name/convention adopted)
attributes DROPPED OUTRIGHT — zero known consumers anywhere in the codebase (v1 or v2), no defined shape, zero data-loss risk

16 of 17 columns fully preserved (exact-duplicate elimination, rename, retype, or a genuinely new platform column carrying the same fact); exactly 1 (attributes) is a real, accepted, disclosed capability loss.

Downstream entries: #35 (platform's 4th reopen, executing Platform's side of this rule) and #36 (Admin's first v2 build, executing Admin's side) apply this rule mechanically — neither re-litigates it.

Logged to OPEN_ITEMS (both with concrete triggers, per the standing rule): dbas's exact JSONB element shape (string array vs. object array) must be pinned down before the platform reopen migration is written; mailing_address's "NULL = same as legal_address" convention is documented-not-enforced (no CHECK/trigger), matching the accepted pattern already used for multi_loc.site's climate-zone-system gap (entry #18 Decision D) — logged, not silently assumed.

35. Platform's 4th Reopen — Executing #34's Identity Absorption

Decided: 2026-07-07. Platform's 4th reopen (prior: schema-locked 2026-06-09; reopened 2026-06-30 for announcement/platform_setting, 21→23 tables, entry #15; reopened 2026-07-06 for the autonomy-first backfill, entry #19). This entry executes entry #34's governing rule — Platform absorbing tenant identity from Admin's dropped tenant_business_profile — it does not re-decide or restate that rule, only its build.

Migration: packages/db/migrations/20260707110000_platform_reopen_identity_absorption.sql (hand-written, applied live, verified against information_schema).

What changed — platform.tenant_profile, 34 → 39 cols (+5 new, 1 retyped, 2 deprecated-in-place):

  • 5 new columns, absorbing #34 Block 3's identity content: business_email (from admin's email), legal_address (from admin's primary_address, platform's own JSONB shape convention), mailing_address (new), business_classification_code (NAICS, from admin's business_classification), ein_ref (vault reference, from admin's ein_ref — same name/convention adopted, closing #34's EIN security conflict).
  • 1 retype: trading_name (text) → dbas (jsonb, NOT NULL DEFAULT '[]'). Element shape pinned down per the OPEN_ITEMS trigger from #34: a bare string array, e.g. ["Acme Garden Co","Rose Garden Nursery"] — decided before the migration was written, not left ambiguous.
  • Live safety evidence: a fresh query against platform.tenant_profile, run immediately before writing the migration, confirmed 12 total rows with 0 non-null values on trading_name at retype time — zero data-loss risk on the retype.
  • 2 deprecated in place, no DDL change: tax_id (superseded by ein_ref's vault-reference posture) and logo_url (superseded by admin.tenant_branding.logo_ref, once Admin v2 exists) both got COMMENT ON COLUMN markers only — column comments, not drops. Both remain present, readable, and writable. The same fresh pre-migration query confirmed 0 non-null values on both at comment-time, consistent with the low-risk posture but not the reason for deferring the drop (see OPEN_ITEMS triggers below — the drops are blocked on downstream conditions, not on data presence).

Platform module-wide: 23 tables (unchanged) / 403 → 408 columns. Verified live via information_schema.

Code cutover (all done, verified via typecheck + tests):

  • apps/api/src/platform/platform.service.ts — updateTenantProfile() gained setters for businessEmail/dbas/einRef/legalAddress/mailingAddress/businessClassificationCode; provisionTenant() wraps a single tradingName input into a 1-element dbas array, preserving the existing call shape for callers not yet passing multiple DBAs.
  • apps/api/src/platform/dto/platform.dto.ts — UpdateTenantProfileDto updated to match the new column set.
  • packages/types/index.ts — TenantProfile interface updated; trading_name replaced by dbas: string[].
  • apps/web/admin/app/tenants/[id]/page.tsx — reads p.dbas.join(', ') instead of p.trading_name.

Tests: apps/api/src/platform/__tests__/platform-identity-absorption.spec.ts — 10 new tests (dbas default/wrapping/multi-element-array behavior, all 5 new columns round-trip, deprecated columns still writable and carry DEPRECATED column comments, live column-count sanity checks for both tenant_profile = 39 and platform-wide = 408). Full apps/api suite: 539/539 passing (up from 529 pre-reopen), zero regressions.

OPEN_ITEMS closure and additions:

  • The dbas JSONB-element-shape row from #34 is now RESOLVED — pinned to a bare string array before the migration was written, per above.
  • The mailing_address NULL-fallback row from #34 stays open, unchanged — still documented-not-enforced (no CHECK/trigger), matching the accepted multi_loc.site climate-zone-system precedent (entry #18 Decision D).
  • 3 new rows added this pass, all open:
    1. ein_ref is schema-only until a vault-encryption service exists anywhere in the codebase (confirmed via grep: zero Vault/Encryption service classes in apps/api/src) — trigger: when a vault-encryption service is built.
    2. tax_id's eventual DROP is deferred to a separate, later, explicitly-flagged migration — trigger: both (a) the vault-encryption service existing and (b) the application-code cutover being verified complete (PlatformService/packages/types no longer read/write tax_id).
    3. logo_url's eventual DROP is deferred to a second, later reopen of platform, timed to Admin's actual v2 build — trigger: when Admin v2 is designed/built and admin.tenant_branding.logo_ref is live.

Not touched by this reopen: entry #34 Section 5's approval-engine convergence decision (Option B — tenant-side approvals stay in Admin's engine, platform.contract stays separate) is unaffected; no mention needed here beyond this note of continuity.

Confirm: platform reopened — now the single source of truth for tenant identity.

36. admin — Module #20, First v2 Pass, Executing #34's Admin-Side Consequences

Decided: 2026-07-07. Designed, adversarially verified, built, tested, and locked the same day, immediately after entry #35's platform reopen. This is the first v2 pass of admin — v1 was 11 tables / 145 columns, locked 2026-06-10, never rebuilt for v2 until now. This entry executes entry #34's governing rule (Admin ↔ Platform data-ownership boundary) on Admin's side; it does not re-decide or restate that rule, only its build. Reference #34 for the boundary rule and full 17-column fate mapping of tenant_business_profile, and #35 for platform's corresponding absorption.

THE 4 MANDATORY DESIGN-PHASE INTEGRITY BLOCKS

BLOCK 1 — v1→v2 Delta Summary. v1: 11 tables / 145 columns → v2 built: 10 tables / 128 columns (−1 table, −17 columns). The single table-count change is tenant_business_profile's removal, entirely accounted for by entry #34: 16 of its 17 columns MOVED to platform.tenant_profile (Platform's 4th reopen, entry #35), 1 column (attributes) DROPPED outright with no successor (zero known consumers, no defined shape, zero data-loss risk — see #34 Block 3 for the full 17-column table).

Table v1 cols v2 built cols Δ
tenant_business_profile 17 — (DROPPED, table removed) −17
tenant_branding 12 12 0
compliance_document 14 14 0
tenant_setting 11 11 0
hardware_device 13 13 0
integration_config 13 13 0
webhook_config 12 12 0
api_key 14 14 0
approval_workflow 10 10 0
approval_routing_rule 11 11 0
approval_request 18 18 0
Total 145 128 −17

128 matches 145 minus 17 exactly. Every one of the 10 surviving tables is column-for-column, type-for-type, CHECK-for-CHECK, index-for-index identical to v1 — a faithful port, not a redesign — with exactly one schema-level change across all 10: the module-wide actor-attribution retarget (5 columns, 3 tables — see Block 3).

BLOCK 2 — Consolidation Justification. N/A / MOVED-not-consolidated. tenant_business_profile was not consolidated into another Admin table and not folded into JSONB — its content was relocated across the module boundary entirely, to platform.tenant_profile, per entry #34's governing rule (identity-shaped facts belong to Platform, not Admin). This is a boundary correction, not a schema-consolidation decision internal to Admin. See #34 for the full reasoning (single source of truth, the EIN vault-reference security conflict, the access-control test) — not re-derived here. The other 10 tables show zero consolidation: each already had its own justified, independent lifecycle in v1 (branding vs. compliance docs vs. tenant settings vs. hardware vs. integration config vs. webhook config vs. API keys vs. the 3-table approval-engine chain), and nothing about this pass's boundary correction or actor-retarget changes that reasoning. No table dropped for "fewer tables is cleaner."

BLOCK 3 — Full Table + Column Fate. All 11 v1 tables accounted for.

v1 table Fate v2 name Column-level notes
tenant_business_profile DROPPED (table removed) — 16/17 cols MOVED to platform.tenant_profile (entry #35); attributes DROPPED outright, no successor. Full mapping in #34 Block 3 — not repeated here.
tenant_branding BUILT admin.tenant_branding Byte-for-byte port, 12 cols. Owns the logo (logo_ref, a Files-module forward-ref) — platform.tenant_profile.logo_url deprecated in favor of this (#35). Human-only, zero autonomy columns (branding is a subjective creative/business decision, no legitimate agent-autonomy surface).
compliance_document BUILT admin.compliance_document Byte-for-byte port, 14 cols. document_ref unchanged forward-ref to Files (not yet built).
tenant_setting BUILT admin.tenant_setting Byte-for-byte port, 11 cols, except updated_by_actor_id retargeted identity.identity_user → identity.actor. Config-surface branch 7 (the tenant's own tunable business-process rule, the default/fallback) per #34 Section 6's decision tree.
hardware_device BUILT admin.hardware_device Byte-for-byte port, 13 cols. Config-surface branch 6 (physical device config) per #34 Section 6. LIGHT autonomy: flagging-only (e.g., staleness flagging), never autonomous write access to device config.
integration_config BUILT admin.integration_config Byte-for-byte port, 13 cols. credentials_ref is a vault reference with no vault-encryption service existing yet (same net-new dependency platform.tenant_profile.ein_ref already depends on, not a second one). Config-surface branch 5 (named 3rd-party connector config) per #34 Section 6. LIGHT autonomy: flagging-only (e.g., sync-failure flagging). Real, already-documented FK target for the not-yet-built Integrations module.
webhook_config BUILT admin.webhook_config Byte-for-byte port, 12 cols. secret_ref is the same class of vault reference as integration_config.credentials_ref. LIGHT autonomy: flagging-only. Real, already-documented FK target for the not-yet-built Integrations module.
api_key BUILT admin.api_key Byte-for-byte port, 14 cols, except created_by_actor_id and revoked_by_actor_id retargeted identity.identity_user → identity.actor. Hash-only storage (no raw key at rest), token_hash uniqueness preserved. LIGHT autonomy: flagging-only, never autonomous issuance.
approval_workflow BUILT admin.approval_workflow Byte-for-byte port, 10 cols. Human-only, zero autonomy columns — governance decisions over financial-approval authority itself are not delegable to the system whose actions the workflow exists to check.
approval_routing_rule BUILT admin.approval_routing_rule Byte-for-byte port, 11 cols. Human-only, same reasoning as approval_workflow (a rule DEFINITION, not a routing INSTANCE).
approval_request BUILT admin.approval_request Byte-for-byte port, 18 cols, except requested_by_actor_id and resolved_by_actor_id retargeted identity.identity_user → identity.actor. FULL autonomy: mechanical routing + anomaly/SLA flagging are legitimate agent work; the actual approve/reject decision stays definitionally human.

The 5-column actor-attribution retarget (the module-wide, module-spanning schema-level change — matching every other module built since 2026-06-28): tenant_setting.updated_by_actor_id, api_key.created_by_actor_id, api_key.revoked_by_actor_id, approval_request.requested_by_actor_id, approval_request.resolved_by_actor_id — all 5 changed from identity.identity_user to identity.actor.

BLOCK 4 — Dependency-Blocked Register. Already-established dependency-blocked items (Block 4 status), not new discoveries this pass:

  • tenant_branding.logo_ref and compliance_document.document_ref — unchanged forward-refs to the not-yet-built Files module (files.file.id) — already a documented seam in CROSS_MODULE_CONTRACTS.md.
  • integration_config.credentials_ref and webhook_config.secret_ref — vault references with no vault-encryption service existing anywhere in the codebase yet (confirmed via grep: zero Vault/Encryption service classes in apps/api/src) — the same net-new dependency platform.tenant_profile.ein_ref already depends on (entry #35), not a second one.
  • integration_config and webhook_config are the real, already-documented FK targets for the not-yet-built Integrations module (integrations.connector.integration_config_id → admin.integration_config; integrations.webhook_delivery.webhook_config_id → admin.webhook_config) — Admin's own schema needs no placeholder for these, nothing incomplete on Admin's side.
  • A genuine FUTURE opportunity, not a blocker: if purchasing's own bespoke PO-approval flow (purchase_order.approval_status) is ever migrated to route through Admin's shared approval engine instead, that would be a purchasing reopen, not an Admin concern — approval_request.source_module/.source_type/.source_ref's polymorphic seam already accepts purchasing/purchase_order as a valid source today with zero schema change needed if/when purchasing chooses to adopt it.
  • No AdminService yet — schema-only this pass, same pattern as every other module's deferred service layer.

Part D / Autonomy Summary (established during the design phase, not re-run here)

Part D capability discovery and the autonomy/schema-translation pass ran during design (the adversarially-verified Part B design document). Admin is honestly a LOW-AUTONOMY, mostly-human-configuration module. Only 2 of 10 tables reach a genuine autonomy surface beyond pure human config:

  • approval_request — FULL. Mechanical routing + anomaly/SLA flagging are legitimate agent work; the actual approve/reject decision stays definitionally human.
  • hardware_device / integration_config / webhook_config / api_key — narrow LIGHT, flagging-only surfaces (e.g., sync-failure flagging, staleness flagging) — never autonomous write access to credentials, endpoints, or issuance.

Explicitly ruled out (human-only, matching Section 0's valid "explicitly ruled out" outcome): tenant_branding, approval_workflow, and approval_routing_rule (rule/workflow DEFINITIONS, as distinct from approval_request routing INSTANCES). Branding is a subjective creative/business decision with zero legitimate autonomy surface. Workflow/routing-rule definitions are governance decisions over financial-approval authority itself — not delegable to the same system whose actions the workflow exists to check. No automation_source/review_status/decision_provenance columns were added to any of the 10 tables — a deliberate, disclosed decision: v1 never had these columns, and most of Admin's tables have no legitimate agent-autonomy surface to justify adding them speculatively.

Approval-Engine Convergence — Option B (confirmed, per #34 Section 5)

The tenant-side approval engine (approval_workflow / approval_routing_rule / approval_request) stays Admin-internal, tenant-scoped, tenant-RLS throughout — it does not converge with platform.contract's own separate Vrida-operator review gate (untouched, different plane: Admin's RLS model assumes the reviewer IS the tenant, which does not fit a cross-tenant operator flow). Designed to be the SHARED mechanism any FUTURE tenant-side approval need (purchasing/pricing/payments) can route through. Investigated and confirmed purely forward-compatible, zero changes needed to any already-locked module: purchasing already has its own bespoke, unrelated PO-approval column purchase_order.approval_status; pricing/payments review_status columns are agent-anomaly review gates — a different shape/purpose, not tenant-approval routing. Both coexist with Admin's engine without conflict today.

Build Verification

10 tables, 128 columns exactly, verified live via information_schema. RLS enabled + a <table>_tenant_isolation policy on all 10 tables. All 5 retargeted actor-attribution columns confirmed live resolving to identity.actor (valid accepted, bogus rejected). Zero identity-shaped columns anywhere in the 10 built tables — Admin references platform.tenant for tenant identity throughout, never duplicates it.

Migration: packages/db/migrations/20260707120000_admin_module.sql (hand-written, applied live, verified: 10 tables, 128 cols, RLS enabled + tenant-isolation policy on all 10, all 5 actor FKs confirmed targeting identity.actor).

Drizzle schema: packages/db/src/schema/admin/ — _schema.ts, branding.ts (tenant_branding, compliance_document), config.ts (tenant_setting, hardware_device, integration_config, webhook_config, adminApiKey — exported as adminApiKey to avoid a name collision with identity's own apiKey export; the DB table name is still api_key), approval.ts (approvalWorkflow, approvalRoutingRule, approvalRequest), index.ts barrel. Registered in packages/db/src/schema/index.ts.

Tests: apps/api/src/admin/__tests__/admin-schema.spec.ts — 46 tests, covering: (A) all 10 tables exist with RLS enabled + exact 128-column count; (B) RLS policy correctness; (C) platform.tenant_id FK resolution; (D) the 5 retargeted actor-attribution columns resolve to identity.actor (valid accepted, bogus rejected); (E) the full approval-engine chain (workflow → routing_rule → request, including a non-existent-workflow rejection and the disclosed one-way-transition shape); (F) api_key hash-only storage + token_hash uniqueness; (G) NULL-distinctness on every multi-column unique in the module (9 sub-cases: tenant_branding, tenant_setting's 2-partial pattern including tenant-wide+site-override coexistence, hardware_device, integration_config, approval_workflow's 2 uniques, api_key soft-delete-respecting uniqueness); (H) CHECK constraint spot-checks (5 sub-cases). Full apps/api suite: 585/585 passing (up from 539 pre-Admin-build), zero regressions.

Independent Post-Build Re-Audit (separate agent, findings pasted verbatim per Section 2.3.7/6 item 1a)

Scope: Read-only verification of this entry's claims per SCHEMA_DESIGN_RUNBOOK.md Section 2.3.7/2.7/6 item 1a. This is a separate agent's independent pass, not the builder's self-assessment.

What I independently re-derived and confirmed CORRECT: (1) Live DB shape — exactly 10 tables in admin schema, exactly 128 total columns, every per-table count matches exactly. (2) RLS — all 10 tables have relrowsecurity = t and a real <table>_tenant_isolation policy. (3) Actor-attribution FKs — via pg_constraint, all 5 claimed columns have live FKs targeting identity.actor(id); zero FKs anywhere in admin target identity.identity_user. (4) Zero identity-shaped columns — full 128-column dump confirms no legal_name/business_type/phone/ein/address-type column anywhere. (5) Migration-to-DB drift — cross-checked every index (43 total) and CHECK constraint (13 total) against the live DB, zero drift. (6) approval_request.source_module CHECK confirmed live including 'purchasing' — the forward-compatibility claim is genuine. (7) v1→v2 arithmetic — manually recounted all 11 v1 tables from scratch, got 145 total, 128 for the 10 surviving tables, matching both by subtraction and by direct resum. (8) Tests — ran the suite myself, 46/46 and 585/585, matching claims exactly; spot-read test bodies, genuine assertions against a live DB, not stubs. (9) Doc files exist and are substantive — schema_docs/admin.md (35.5KB) and module_spec/admin.md (19.3KB), not stubs. (10) This entry's 4 Design-Phase Integrity blocks are genuinely present with a real diffed capability-cost accounting.

Confirmed defects — this build is NOT ready to lock (at the time this pass ran): FAIL 1 — no independent verification evidence in this entry (the exact gap this section now closes). FAIL 2 — zero OPEN_ITEMS rows for Admin's own Block 4 items. FAIL 3 — MODULE_INDEX.md still showed the stale v1 row (11/145, no LOCKED marker). FAIL 4 — DOCS_INDEX.md had no Admin lock entry. FAIL 5 — CLAUDE.md's Current-focus line omitted Admin entirely. GAP — MODULE_BUILD_STATUS.md showed as git-staged but appeared to have zero actual diff at inspection time.

Verdict: Not ready to lock. The schema build itself is genuinely excellent — live-verified column-for-column, constraint-for-constraint, zero drift, zero identity leakage, tests are real and fully green, and the v1→v2 arithmetic is exact. But the module failed the audit gate and the doc-completeness gate on 4 of its mandatory items.

Root cause of FAILs 2–5, GAP, disclosed honestly: this workflow ran 9 parallel documentation-writing agents against the same working tree at once. A race between two of those agents — most likely one running a broad git-level operation while a sibling agent's edit to a different file was still uncommitted — silently reverted 4 files' in-progress edits (packages/db/src/schema/index.ts's admin barrel export, MODULE_INDEX.md, DOCS_INDEX.md, CLAUDE.md) back to their last-committed state, even though each agent's own turn had verified its edit landed via git diff at the time. OPEN_ITEMS.md's 5 new Admin rows were lost the same way. This same independent-verification pass caught every one of the losses. All 5 have since been fixed in this same pass: the schema barrel export was restored (confirmed via packages/db rebuild + full test suite re-run, 585/585 green); MODULE_INDEX.md's Admin row now shows 10 | 128 with a SCHEMA LOCKED 2026-07-07 marker; DOCS_INDEX.md's metrics table and narrative now include Admin (15 modules locked, 179 tables); CLAUDE.md's Current-focus paragraph now covers Admin; OPEN_ITEMS.md now carries all 5 Block-4 rows (Files forward-refs, the vault-encryption dependency shared with platform.tenant_profile.ein_ref, the 2 Integrations-module inbound FK targets, no AdminService yet, and the purchasing-approval-engine future-opportunity note). MODULE_BUILD_STATUS.md's footnote ²⁰ was confirmed genuinely present (staged correctly; the verifier's "zero diff" read was a stale git-state snapshot at inspection time, not a real gap). Full apps/api suite re-confirmed green (585/585) after every fix.

Confirm: Admin locked — the first v2 pass of this module, referencing platform for tenant identity throughout, with the independent audit's process-gate findings resolved in-file per the runbook's own gate.

37. Remediation Plan Phase 1 — Enforcement Foundation (2026-07-08)

A senior-architect 8-lens schema review plus a 15-module read-only validation sweep (both 2026-07-08) found several cross-cutting enforcement gaps across the already-locked schema. A 4-phase remediation plan was proposed, adversarially verified, and approved by the user. This entry records Phase 1 — the enforcement foundation (5 approved items), plus 3 additional bugs the phase's own live-reproduction and independent-verification steps found and fixed along the way. Phases 2–4 (non-additive decisions, missing capabilities, futureproofing) are separate, not-yet-started work.

Discipline applied: every enforcement fix was LIVE-REPRODUCED — the bad action that used to succeed was actually attempted against the live DB and shown failing, not just "CHECK added." A separate, adversarial verification pass (3 independent lenses, none self-graded) re-derived every claim from scratch against the live DB before this entry was written.

Item 1 — RLS wiring

Before this phase, tenantDB() had zero real call sites anywhere in the codebase and the app connected to Postgres exclusively as the postgres superuser (bypasses RLS unconditionally). A real, non-superuser authenticated role now exists; GRANT USAGE + blanket table grants were issued to it across all 15 schemas (packages/db/migrations/20260708150000_phase1_rls_wiring.sql). packages/db/src/client.ts was rewritten with an authenticator/authenticated role split (getAdminDb() unchanged, superuser, for admin/background ops; getDb()/tenantDB() now genuinely RLS-bound).

A previously-undiscovered latent bug was found and fixed in the same pass: tenantDB()'s SET LOCAL app.current_tenant_id = $1 is invalid Postgres syntax with a bind parameter (a bare SET statement doesn't accept parameterized values) — it silently raised "syntax error at or near $1" on every call. This was undetected until now purely because the function had never been exercised. Fixed with SELECT set_config('app.current_tenant_id', $1, true) (a normal function call, accepts bind parameters, third arg gives identical SET-LOCAL transaction-scoped-revert semantics).

Scoped deliberately infra-only, per explicit user decision: given neither PlatformService nor IdentityService actually calls tenantDB() today (confirmed 0 real call sites before this phase), migrating either service onto it is separate future work, not folded into this already-large phase — see the updated OPEN_ITEMS row on the tenant-context-interceptor gap.

LIVE-REPRODUCED: apps/api/src/database/__tests__/rls-cross-tenant.spec.ts (new, 5/5 passing) — a cross-tenant write via the authenticated role, which previously had no meaningful restriction path at all, is now genuinely REJECTED (42501).

Two additional RLS coverage gaps found live and fixed in the same pass (found by re-sweeping "does any table have a real tenant_id column but no RLS enabled" across all 15 schemas, after Item 1's own blanket GRANT made the gap newly exploitable):

  • identity.identity_access_event had a real tenant_id (FK'd to platform.tenant) but was originally built with a deliberate "no RLS — access via service_role only" design comment. Item 1's own blanket GRANT to authenticated invalidated that premise — without RLS, any tenant-scoped connection could now read/write every OTHER tenant's login/logout/MFA/support-access history. Fixed by enabling RLS + a tenant_isolation policy identical in shape to every sibling table (packages/db/src/schema/identity/events.ts, migration 20260708170000). Live-reproduced: a tenant-A connection can no longer read tenant B's access events (0 rows visible, confirmed both by the builder and independently by the verification pass).
  • platform.operator_audit_log also had a (nullable) tenant_id, but is genuinely NOT tenant-scoped in usage — a Vrida-operator-only compliance log (original comment: "intentionally non-RLS Vrida-internal"). A tenant-scoped RLS policy would be the wrong fix (operators need cross-tenant visibility). Instead, authenticated's blanket grant was REVOKEd entirely on this one table, restoring the original service_role-only access model. Live-reproduced: authenticated now gets 42501 permission denied on this table.

A full re-sweep after both fixes returned zero remaining "tenant_id present, RLS disabled" tables anywhere in the 15 schemas except operator_audit_log itself (the intentional REVOKE-instead-of-RLS case, by design).

A bonus fix, found live while chasing "full suite green," is only a partial fix (see the Independent Verification section below — the claim of a full fix does NOT hold): PlatformService.listTenants() ordered only by created_at DESC with no tie-breaker, causing non-deterministic pagination when two tenants shared a timestamp. desc(tenant.id) was added as a secondary sort key. This closes the same-timestamp-tie case but was independently found to NOT close a broader, pre-existing cross-file concurrency race (concurrent inserts into platform.tenant from other parallel-running spec files can still shift ranking mid-test) — logged as its own OPEN_ITEMS row rather than overclaimed as fixed here.

Item 2 — C8 financial-autonomy boundary

New CHECK constraints (migration 20260708130000): chk_purchase_order_sent_requires_approval, chk_purchase_order_no_self_approval (purchasing.purchase_order); chk_agent_execution_authority_required_when_executed, chk_agent_execution_needs_approval_requires_resolution (ai.agent_execution).

A real, live bug was found and fixed by this phase's own live-reproduction exercise: the first version of chk_purchase_order_sent_requires_approval read status NOT IN ('sent','partial','received') OR approval_status = 'approved'. In Postgres, an equality comparison against a NULL column evaluates to NULL (not FALSE), and a CHECK constraint only rejects on FALSE — NULL is treated as satisfied. So a PO could reach status='sent' with approval_status left NULL, silently bypassing the exact gate this constraint exists to enforce. LIVE-REPRODUCED both before (bypass succeeded) and after: corrective migration 20260708160000_phase1_fix_po_null_bypass.sql changed the guard to (approval_status IS NOT NULL AND approval_status = 'approved'); the identical bad UPDATE now fails with 23514, and the equivalent valid case (approved, with a distinct approver) succeeds.

The other 3 constraints in this item were live-reproduced directly and reject correctly (23514).

Item 3 — Authority passport self-issue guard

identity.agent_duty_grant gained chk_agent_duty_grant_granted_by_required_and_distinct (granted_by_actor_id IS NOT NULL AND granted_by_actor_id <> agent_identity_id). LIVE-REPRODUCED both sub-cases: a NULL granted_by_actor_id and a true self-issue (granted_by_actor_id = agent_identity_id) are both REJECTED (23514).

Item 4 — Append-only ledgers

New shared trigger function platform.reject_append_only_mutation() (RAISE EXCEPTION using TG_TABLE_SCHEMA/TG_TABLE_NAME/TG_OP, SQLSTATE P0001), applied via REVOKE UPDATE, DELETE FROM authenticated + a BEFORE UPDATE OR DELETE trigger to 9 tables spanning 6 schemas (migration 20260708140000): ai.agent_execution, tax.tax_calculation_jurisdiction, identity.identity_access_event, billing.ar_payment_application, billing.ap_payment_application, inventory.stock_movement, inventory.stock_movement_line, pos.register_cash_entry, pos.sale_line. Belt-and-suspenders design: the REVOKE blocks the app-facing authenticated role at the grant level, the trigger blocks EVERY role including the postgres superuser. LIVE-REPRODUCED: UPDATE and DELETE on these tables are now rejected (P0001), confirmed both by the builder and independently (2 tables, fresh SQL, as the superuser — confirming the trigger, not just the grant, is what's enforcing this).

A real, cascading side effect: once an append-only row references a parent (e.g. identity.actor, pos.sale, multi_loc.site, platform.tenant), that parent becomes transitively un-deletable via FK (no cascade anywhere in this schema). This required updating ~10 existing test-teardown functions across the codebase to tolerate 23503/P0001 rather than fail, and fixing 2 test fixtures that used fixed (non-randomized) names that could collide with an now-permanently-orphaned row from an earlier run.

Item 5 — Fail-open review/trust-flag CHECK sweep

19 new CHECK constraints closing "row marked approved/reconciled/exempt/enabled without recorded evidence" gaps. Pattern A (12 tables, byte-identical shape review_status <> 'approved' OR (reviewed_by_actor_id IS NOT NULL AND reviewed_at IS NOT NULL)): billing.ar_account/ar_adjustment/ar_charge/ar_payment, inventory.item/item_image/item_merge_candidate/item_variant/stock/stock_adjustment_request, pricing.price_list_assignment/price_rule. Pattern B (distinct shapes, all live-reproduced individually): inventory.stock_count (+ new nullable column reconciled_at), payments.dispute, payments.stripe_connect_account, purchasing.vendor_credit (2 CHECKs), tax.tax_calculation, admin.approval_request. All 19/19 LIVE-REPRODUCED — real INSERT/UPDATE attempts in rolled-back transactions, all correctly rejected with 23514; all 12 Pattern-A tables confirmed to share byte-identical constraint text via pg_get_constraintdef.

inventory.stock_count.reconciled_at is the only column-count change in this entire phase — inventory is now 24 tables / 337 columns (was 336). Every other change is CHECK/RLS/GRANT/trigger-only.

Independent Verification (3 separate agents, adversarial, findings pasted per Section 2.3.7/2.7/6 item 1a — no self-grading)

Lens A — CHECK constraint NULL-bypass hunt. Independently re-derived the live definition of every one of the ~24 new constraints via pg_get_constraintdef, checked each nullable-column guard. Verdict: no new bypass found. One constraint (chk_agent_execution_needs_approval_requires_resolution) has the surface shape of the bug class (a bare <> on a nullable column in an OR) but is protected by a genuine sibling CHECK on the same table that forecloses the NULL state whenever status='executed' — live-confirmed safe. Two others (chk_purchase_order_no_self_approval, chk_approval_request_reviewer_not_creator) are deliberately fail-open-on-NULL, matching an established codebase-wide "reviewer ≠ creator" idiom (their job is only to block self-approval, not mandate presence — a separate constraint already handles presence). Independently re-verified the chk_purchase_order_sent_requires_approval fix's live definition and re-attempted the exact bypass: correctly REJECTED (23514); the equivalent valid case correctly succeeded.

Lens B — RLS/GRANT coverage re-sweep. Independently re-ran the "tenant_id present, RLS disabled" sweep across all 15 schemas: exactly one row, platform.operator_audit_log (the intentional REVOKE case) — identity.identity_access_event does not appear. Confirmed via information_schema.role_table_grants and pg_class.relacl that authenticated has zero privileges on operator_audit_log, and live-reproduced the 42501 rejection. Confirmed identity_access_event's new policy is byte-identical in shape to 20 of 22 sibling identity-schema policies, and live-reproduced cross-tenant read isolation (0 rows visible for another tenant's event; 1 row visible for the correct tenant, ruling out "RLS just blocks everything"). Spot-checked GRANT USAGE + a genuine cross-tenant write rejection on 3 schemas the builder didn't design this fix around (crm, orders, shared) — all correct. Grepped for other "service_role only"/"not tenant-scoped" design comments across the whole schema source tree and cross-checked each one's actual grant/RLS state: 8 more tables found, all correctly shaped (global reference tables with no tenant_id at all, or already-correct mixed-scope RLS on identity.role and 2 payments tables). Verdict: all 5 checks pass, no additional undiscovered RLS/GRANT gap.

Lens C — test suite integrity + independent live-reproduction. Independently constructed and ran fresh (not copied) live-reproductions of 4 sampled CHECK constraints across purchasing/billing/payments/identity — all confirmed correct (bad case rejected 23514, valid case succeeds). Confirmed packages/db's compiled dist/ is current, not stale, and that platform.reject_append_only_mutation() is attached via pg_trigger to exactly the 9 claimed tables, no more no less — live-reproduced 4 fresh UPDATE/DELETE rejections as the superuser. Critical finding: "full suite green" as a steady-state claim does NOT hold. Ran the full suite 8 times; found two previously-undocumented, genuinely load/concurrency-driven flakes distinct from the already-logged SoD-detection race — admin-tenants.spec.ts B3 (a cross-file platform.tenant pagination race that the same-day desc(tenant.id) fix does NOT fully close, only the same-timestamp-tie sub-case) and identity-governance.spec.ts D3 (a starts_at/Postgres-now() clock-skew race under heavy parallel load). Neither is a schema/constraint defect — both are pre-existing test-isolation gaps (shared live DB across parallel Jest workers, no per-test transaction rollback in these HTTP-integration-style specs) — logged as 2 new OPEN_ITEMS rows.

Honest "full suite green" framing, given Lens C's finding: every constraint/RLS/trigger this phase built or fixed is independently confirmed correct, live, and stable. The apps/api test suite is green in the large majority of runs (590/590), but roughly half of full-suite runs surface ONE of 3 known, pre-existing, Phase-1-unrelated concurrency flakes (the already-logged SoD-detection race, plus the 2 Lens C found) — none in the functionality this phase built, all logged to OPEN_ITEMS for a future dedicated test-isolation pass, none blocking this phase's own correctness.

Docs

Schema docs (docs/database/schema_docs/) and module specs (docs/modules/module_spec/) updated for all 10 touched modules (admin, ai, billing, identity, inventory, payments, pricing, purchasing, tax, platform) with a dated "Remediation Phase 1" subsection each, referencing this entry. MODULE_INDEX.md's inventory row and header discrepancy-tracking note updated for the 336→337 column delta. OPEN_ITEMS.md updated: closed the pre-existing authenticated-has-no-GRANT row, updated the tenant-context-interceptor row to reflect the now-fixed (but not yet service-consumed) infra, and added 3 new rows (the SoD-detection race, the admin-tenants pagination race, the support-access timing race).

Confirm: Remediation Phase 1 complete — RLS wiring, the C8 financial-autonomy boundary, the authority-passport self-issue guard, append-only ledger enforcement, and the fail-open review-flag sweep are all live, independently verified, and documented. 3 additional real bugs (the PO NULL-bypass, 2 RLS coverage gaps) were found and fixed within the phase itself; 3 pre-existing, unrelated test-concurrency flakes were found and logged (not fixed — out of this phase's scope). Phases 2–4 of the remediation plan are separate future work.

38. Remediation Plan Phase 2 — Non-Additive Decisions (2026-07-08)

Phase 2 of the approved 4-phase remediation plan, covering 2 items: UUIDv7 PK generation on append-only ledgers, and a minimal-now vendor-abstraction anchor on payments.payment_intent.

Pre-build correction applied first: the original plan draft's supporting prose had 3 table-name citation slips (the buildable DDL itself, which only ever touched payments.payment_intent, was unaffected). All 3 corrections were live-verified via information_schema before use: inventory.item_variant.stripe_tax_code → the column is actually on inventory.item; platform.contract.stripe_coupon_id → actually on platform.promo_code; purchasing.vendor_credit_return_line → that table doesn't exist, the real table is purchasing.vendor_return_line (which itself carries no Stripe-related column at all).

Item 6 — UUIDv7 on Append-Only Ledgers

Confirmed live before building anything: this Postgres instance is 17.6 (native uuidv7() ships in PG 18) and has no pg_uuidv7 extension available (SELECT extname FROM pg_extension returns no such row) — the custom PL/pgSQL function was mandatory, not a shortcut.

Created platform.uuid_generate_v7() (packages/db/migrations/20260708180000_phase2_uuidv7_function.sql) — an RFC 9562-conformant UUIDv7 generator: 48-bit unix_ts_ms (from clock_timestamp()) + 4-bit version (0111) + 12-bit rand_a + 2-bit variant (10) + 62-bit rand_b, built from gen_random_bytes(10) (pgcrypto, confirmed available) plus set_byte() bit manipulation. Lives in platform as a shared, cross-cutting utility, matching the precedent of platform.reject_append_only_mutation() from Phase 1.

Scope decision, per the plan's own recommendation: widened beyond the plan's 4 named "hot ledgers" (stock_movement, stock_movement_line, sale_line, agent_execution) to all 25 tables independently confirmed genuinely append-only, at near-zero marginal cost (packages/db/migrations/20260708190000_phase2_uuidv7_widen_defaults.sql). The classification method: query every table across all 15 schemas lacking an updated_at column (30 raw candidates), then read each candidate's own Drizzle schema-source comment to confirm true append-only/immutable semantics — 6 of the 30 were examined and excluded despite lacking updated_at, because each mutates fields in place after insert: crm.customer_tag_assignment (soft-delete via deleted_at), inventory.item_category/item_tag (both explicitly commented "hard-delete" join tables), payments.stripe_event_dead_letter/stripe_event_log (both explicitly commented as mutating retry_count/status/processed_at in place), pos.pos_sync_conflict (an explicit mutable open/resolved/ignored workflow field).

The 25 tables widened: ai.agent_execution, billing.ap_payment_application, billing.ar_payment_application, crm.customer_consent, crm.customer_merge, crm.customer_note, identity.identity_access_event, identity.permission_group_permission, identity.role_permission, identity.role_template_permission_group, identity.sod_rule_permission, inventory.item_merge, inventory.stock_movement, inventory.stock_movement_line, platform.agreement_acceptance, platform.ai_credit_transaction, platform.operator_audit_log, platform.tenant_internal_activity, platform.tenant_lifecycle_event, platform.tenant_usage_summary, pos.register_cash_entry, pos.sale_line, pos.sale_refund_line, pricing.price_change_log, tax.tax_calculation_jurisdiction.

Additive, confirmed three ways: (1) all 25 tables' id column was uuid + gen_random_uuid() default before the change (live-verified); (2) a DEFAULT-only change never touches existing rows; (3) grepped the entire packages/db/src/schema tree and every migration file for any CHECK constraint or index assuming UUIDv4 byte-shape (uuid_generate_v4, version-nibble assertions, byte-pattern checks on any id column) — zero hits.

WHY this is Phase 2 and not Phase 4: UUIDv7 is time-ordered — sorting by the PK also sorts by insert time. An append-only ledger with a UUIDv4 PK can never be converted to time-range partitioning in place once data has landed (the PK carries no time signal to partition on). Doing this now, before any of these 25 tables accumulate production data, keeps that option open for free; doing it later would mean a PK rewrite against live data.

LIVE-REPRODUCED (by the builder): inserted real rows into inventory.stock_movement and ai.agent_execution, confirmed each new id's version nibble is 7; confirmed a stock_movement_line FK reference into the new stock_movement row resolves, and a self-referencing resolves_execution_id FK into the new agent_execution row resolves; inserted 3 rows into platform.tenant_lifecycle_event 2ms apart and confirmed strictly ascending (time-ordered) ids.

Item 7 — Vendor Abstraction (Minimal Now)

payments.payment_intent gained processor (text NOT NULL DEFAULT 'stripe', CHECK (processor IN ('stripe'))) — the minimal-now de-primitivization anchor (packages/db/migrations/20260708200000_phase2_payment_processor_anchor.sql). Additive: payment_intent confirmed 0 rows live before this migration ran. payment_intent.id itself is correctly untouched by Item 6's widening — it's a mutable ledger (status/review_status transition post-insert), not append-only.

LIVE-REPRODUCED: inserted a row omitting processor, confirmed it defaulted to 'stripe'; inserted a row with processor='adyen', confirmed REJECTED (23514, chk_payment_intent_processor).

The full de-primitivization is deliberately deferred, logged to a new OPEN_ITEMS row with a concrete trigger ("before a second payment processor is integrated"): 19 other stripe_* columns across 6 schemas (live-counted, excluding payment_intent's own 2) — billing.ap_payment/ar_payment.stripe_payment_intent_id, inventory.item.stripe_tax_code, orders.order_payment.stripe_payment_intent_id, 9 more columns across payments.dispute/payment_method/payment_refund/payout/stripe_connect_account/stripe_event_dead_letter/stripe_event_log/terminal_reader (×2), platform.billing_account (×2)/promo_code/subscription/subscription_invoice, pos.sale_payment.stripe_payment_intent_id; 2 table renames (candidates TBD at design time, not decided here); 1 NOT NULL relaxation on processor itself; and widening tax.tax_calculation's own chk_tax_calculation_provider CHECK (currently provider IN ('stripe_tax','manual','exempt'), live-verified) if the eventual second processor also supplies its own tax service.

Independent Verification (2 separate agents, adversarial, findings pasted per Section 2.3.7/2.7/6 item 1a — no self-grading)

Lens A — UUIDv4-shape assumption hunt + FK dependent resolution. Independently re-ran the UUIDv4-byte-shape grep across the entire schema tree and every migration file — zero hits outside the two new Phase 2 migrations' own v7-construction logic. Independently re-derived platform.uuid_generate_v7()'s own correctness via pg_get_functiondef; ran it 1000 times, confirmed 0 duplicates, 0 bad version nibbles, 0 bad variant bits, and (after resolving a self-inflicted false alarm about same-millisecond ordering — RFC 9562 guarantees millisecond-granularity ordering, not sub-millisecond monotonicity, which the re-test with per-call jitter confirmed correctly) 0 timestamp-prefix inversions across 1000 distinct millisecond buckets. Independently confirmed all 25 tables' live id default/type via information_schema.columns — zero mismatches. Found and used the one real incoming FK into any of the 21 tables the builder hadn't already tested (pos.sale_refund_line.sale_line_id → pos.sale_line.id, confirmed via a full pg_constraint scan including a check for unvalidated NOT VALID FKs — none exist), plus fresh-row proofs on 4 more tables with no incoming FK at all. Independently re-read all 6 exclusions' own Drizzle source comments and confirmed each is a genuine hard-delete/soft-delete/mutate-in-place table, not append-only. Verdict: 5/5 checks PASS, no BLOCKER.

Lens B — Item 7 correctness + full-suite integrity. Independently re-derived payment_intent.processor's live shape (text, NOT NULL, DEFAULT 'stripe') and chk_payment_intent_processor's live definition; confirmed payment_intent.id is still gen_random_uuid() (correctly excluded from Item 6). Constructed a fresh, self-authored INSERT proving the default applies and a bogus processor value is rejected (23514). Independently re-verified all 3 pre-build citation corrections against live information_schema. Ran the full apps/api suite 3 times — all 3 runs 590/590 clean, the known pre-existing admin-tenants.spec.ts B3 pagination race did not even manifest. Confirmed packages/db's compiled dist/ postdates every touched source file and that the 25-table (not whole-file) scoping of Item 6 survived compilation exactly (spot-checked dist/schema/inventory/stock.ts: only stockMovement/stockMovementLine compile to the new default; the other 4 tables in that file correctly remain gen_random_uuid()). Verdict: 5/5 checks PASS, no new findings.

Docs

Schema docs and module specs updated for all 10 touched modules (ai, billing, crm, identity, inventory, payments, platform, pos, pricing, tax) with a dated "Remediation Phase 2" subsection each, referencing this entry. MODULE_INDEX.md's payments row and header discrepancy-tracking note updated for the 158→159 column delta (the only column-count change this phase — every other module's change is a PK-generation-strategy change only). OPEN_ITEMS.md gained one new row: the deferred full vendor de-primitivization, with the precise 19-column/6-schema list and its trigger.

Confirm: Remediation Phase 2 complete — UUIDv7 is now the PK-generation strategy on all 25 genuinely append-only tables (keeping future time-range partitioning possible before any of them accumulate production data), and the payments.payment_intent.processor anchor column is live, both independently verified with zero BLOCKERs. The full suite is green (3/3 clean runs at final check). Phases 3–4 of the remediation plan are separate future work.

39. Remediation Plan Phase 3 — Missing Capabilities (2026-07-08)

Phase 3 of the approved 4-phase remediation plan, covering 6 items across 6 modules (crm, tax, pos, inventory, identity, admin): a real crm↔billing revenue-blocking orphan, a refund tax-reversal gap, POS receipt numbering + a no-receipt-refund path, a reward-tender fail-closed gate + a nursery-production stock-movement path, an agent kill-switch, and a config-key catalog + a canonical money-unit-suffix convention writeup.

Pre-build corrections applied first: (1) Item 9 was built against tax.tax_calculation's LIVE shape, re-read fresh rather than reused from the original plan draft — the plan predated Phase 1 Item 5c's chk_tax_calculation_exempt_requires_evidence CHECK, and building against a stale snapshot would have silently dropped it. (2) pos.register.label confirmed live NOT NULL + UNIQUE(tenant_id, label) WHERE deleted_at IS NULL before finalizing Item 10's register-session-prefixed sale_number convention. (3) The precedence-list citation for Item 12 was confirmed live as platform.ai_credit_account (not ai.ai_credit_account, which does not exist) before it landed anywhere.

Item 8 — Customer Credit Terms/Limits (the crm↔billing orphan)

crm.customer gained credit_limit_cents (bigint, nullable) and credit_terms (text, nullable, CHECK IN ('due_on_receipt','net_15','net_30','net_45','net_60','net_90')). This fixes a real, live documentation lie, not a schema gap: billing.ar_account's own comment (written at billing's own build, PROJECT_DECISIONS #32) already correctly said "credit limit/terms read from crm.customer, never duplicated" — but crm.customer never actually had those columns; an earlier pass's comment claimed they were "REMOVED and reassigned to billing outright," an incomplete v1→v2 migration that left billing.ar_account expecting a column crm didn't have. Ownership decision: credit-worthiness is a relationship judgment about THIS customer (crm's domain, a is-this-customer-trustworthy question); billing.ar_account owns the running balance and READS the limit, never duplicates it. Additive: crm.customer confirmed 60 live rows; both columns nullable (NULL means no credit extended — fail-closed). Service-layer enforcement (blocking a charge that would exceed the limit) is deferred, logged to OPEN_ITEMS.

LIVE-REPRODUCED: a customer with an explicit (credit_limit_cents, credit_terms) pair inserts cleanly; a negative credit_limit_cents is rejected (chk_customer_credit_limit_nonnegative); an invalid credit_terms value is rejected (chk_customer_credit_terms); omitting both is still accepted with both columns NULL.

Item 9 — Refund Tax Reversal (built against the post-5c shape)

tax.tax_calculation gained calculation_type ('original'/'reversal', default 'original') and reversed_calculation_id (self-FK, declared without inline .references() per the established self-FK Drizzle workaround, actual FK added via a separate ALTER TABLE). chk_tax_calculation_source_type/chk_tax_calculation_source_pair widened to accept (source_module='pos', source_type='sale_refund_line'). The old unconditional-nonneg taxable_amount_cents/total_tax_amount_cents CHECKs were replaced with sign-aware pairs: original calculations stay non-negative (byte-identical old behavior for all 54 pre-existing rows, all calculation_type='original' by DEFAULT); reversal calculations are now REQUIRED non-positive, so SUM(original + reversal) nets to exactly zero for remittance reporting with no per-row branching — this is the entire point of the item, closing the over-reporting-remittance-every-refund gap (today a refund's tax portion is nowhere represented, so a naive remittance report sums every original sale's tax and never nets out refunds). chk_tax_calculation_calculation_type and chk_tax_calculation_reversal_requires_target (1:1 between calculation_type='reversal' and a non-NULL target) round out the CHECK set. trg_tax_calculation_validate_reversal (mirrors the pre-existing trg_tax_calculation_validate_supersession) validates same-tenant-only — deliberately NOT also same-source_module/source_type/source_ref, since a reversal's source_ref (the refund line) is architecturally always different from what it reverses (the original sale line), unlike a same-line supersession correction. pos.sale_refund_line gained tax_amount_cents/tax_rate (mirroring sale_line's own pattern); pos.sale_refund gained tax_refunded_amount_cents — both plain positive POS-layer magnitudes; the sign convention lives only in tax.tax_calculation. Additive: tax.tax_calculation confirmed 54 rows, pos.sale_refund/sale_refund_line confirmed 0 rows each — zero backfill risk anywhere.

Addendum, same day, post-verification: independent adversarial verification (below) flagged that tax_calculation_jurisdiction's own nonneg CHECK was dropped and its sign-consistency-with-parent requirement was disclosed as an unenforced service-layer contract, without noting that this table is INSERT-ONLY (authenticated has no UPDATE/DELETE grant, and trg_tax_calculation_jurisdiction_append_only already rejects both at the trigger level too) — meaning a BEFORE INSERT trigger closes the gap for real with no UPDATE race to worry about, exactly mirroring this same item's own trg_tax_calculation_validate_reversal pattern. Rather than leave it disclosed-but-unenforced, trg_tax_calculation_jurisdiction_validate_sign was added (packages/db/migrations/20260708270000_phase3_item9_addendum_jurisdiction_sign_trigger.sql): looks up the parent tax_calculation.calculation_type and rejects a sign mismatch. This is now DB-enforced, not merely documented.

LIVE-REPRODUCED: a reversal calculation for a refund line inserts with a negative amount (previously not representable at all); SUM(original + reversal) nets to zero; a positive taxable_amount_cents on a reversal row is rejected; calculation_type='reversal' with a NULL target is rejected; a reversed_calculation_id belonging to a different tenant is rejected. Post-addendum: a positive jurisdiction row on an original calc is accepted (unchanged behavior) and a negative one is now rejected (previously silently accepted); a negative jurisdiction row on a reversal calc is accepted and a positive one is now rejected.

Item 10 — POS Receipt/Sale Number + No-Receipt-Refund Path

pos.sale.sale_number (text, NOT NULL) restores an unlogged v1 erosion — v1 had this column (docs/old/schema/schema_modules/schema_pos.md: "Sequential per tenant per site; format configurable"), v2's initial pos build dropped it with no logged reason. Deliberately NOT a global gapless sequence — that would require a live DB round-trip to allocate the next number, defeating pos's own offline-first design — instead register-session-prefixed and client-generated (<register.label>-<session-local-sequence>, e.g. "Register 1-0042"; pos.register.label confirmed live NOT NULL + UNIQUE per tenant, so the prefix is always available and collision-free). DB enforces only UNIQUE(tenant_id, sale_number) WHERE deleted_at IS NULL, mirroring v1's own uniqueness shape exactly. pos.sale confirmed 156 live rows — a 3-step migration (add nullable → backfill 'LEGACY-' || id::text → SET NOT NULL) was required, not a single-step ADD COLUMN ... NOT NULL, which would have failed immediately against the existing rows.

No-receipt-refund: pos.sale_refund_line.sale_line_id relaxed to nullable; a new item_variant_id column (FK → inventory.item_variant, ON DELETE RESTRICT) is the alternative identifier for a refund line with no identifiable historical sale line; chk_sale_refund_line_identification requires at least one of the two. pos.sale_refund_line confirmed 0 live rows — zero backfill risk, pure relax/widen.

Explicitly does NOT enable a fully anonymous walk-in return — pos.sale_refund.sale_id itself is UNCHANGED, still NOT NULL: a real sale/transaction context is still required; only the specific LINE within it can now go unidentified. The anonymous-walk-in-return question (relaxing sale_refund.sale_id too) is a SEPARATE, undecided go/no-go — flagged here for the architect's decision, not decided or bundled into this build, per explicit instruction. Logged to OPEN_ITEMS.

LIVE-REPRODUCED: a fresh sale insert requires sale_number and rejects a NULL value; duplicate (tenant_id, sale_number) is rejected; a no-receipt refund line (sale_line_id NULL, item_variant_id set) is now ACCEPTED — previously impossible; a refund line with NEITHER identifier is rejected; pos.sale_refund.sale_id is confirmed still NOT NULL — the anonymous-return path is confirmed NOT enabled.

Item 11 — Reward Tender Fail-Closed Gate + Produced Stock

Extended the existing fail-closed tender gate to also block 'reward' — same bug class as the 2026-07-07 gift_card/store_credit fix: 'reward' is a valid payment_method ENUM value with NO backing rewards subsystem at all (worse than gift_card/store_credit, which at least carry an unenforced forward-ref column) — was previously silently accepted with zero validation. Renamed chk_sale_payment_no_unvalidated_stored_value_tender → chk_sale_payment_no_unbacked_tender_type (the old name became inaccurate once it also covers a non-stored-value tender type). Confirmed live: 0 rows with payment_method='reward' exist — pure narrowing of an already fail-closed CHECK, no existing row affected.

inventory.stock_movement.movement_type widened to add 'produced' — source_module already permitted 'production' since this table's original build, but no real movement_type existed to pair with it, so a nursery propagating its own stock (cuttings/seed → saleable plant) had no real path. Pure enum-widen, strict superset for every existing row.

LIVE-REPRODUCED: a 'reward' tender is now rejected; 'gift_card' is still rejected (no regression on the prior fix); 'cash' is unaffected; movement_type='produced' with source_module='production' is now ACCEPTED — previously impossible; an unrelated invalid movement_type value is still rejected (the widen didn't loosen the CHECK generally).

Item 12 — Agent Kill-Switch

identity.agent_identity gained status ('active'/'suspended'/'killed', default 'active') + suspended_at/suspended_by_actor_id/suspension_reason. chk_agent_identity_status_suspended_at_consistency requires suspended_at present iff status is not 'active'; suspended_by_actor_id stays independently nullable (a system-initiated suspension, e.g. cascading from a tenant-level or credit-account-level shutoff, may have no specific actor to attribute). 'killed' is meant to be treated as terminal by the service layer — NOT DB-enforced irreversible (no trigger blocks a killed→active transition; that judgment is deliberately left to IdentityService, not baked into schema). Additive: identity.agent_identity confirmed 247 live rows; status DEFAULTs 'active' (identical to today's implicit behavior for every existing row).

The precedence chain (documented, one link added): this column is ONE LINK in a chain of independently-owned half-mechanisms that already existed before it: tenant status (an entire tenant can be off) > platform.ai_credit_account status (a tenant's AI budget can be exhausted/suspended — platform-owned; the pre-build correction confirmed ai.ai_credit_account does NOT exist) > this agent's own status (NEW) > agent_duty_grant (per-permission authority, revocable/expirable) > agent_skill_assignment (what the agent may attempt) > role assignment > feature flags. No single mechanism was authoritative before; this is the missing top-of-agent link, still evaluated in order with the rest — not a replacement for the chain.

LIVE-REPRODUCED: a freshly-provisioned agent defaults to status='active', suspended_at NULL; suspending an agent (status + suspended_at + reason) now works — previously no such flag existed at all; an invalid status value is rejected; status='suspended' with suspended_at NULL is rejected; killing an agent (status='killed') is accepted, distinct from suspended; reactivation (status back to 'active') is accepted (not DB-blocked from killed — deliberate, per the above).

Item 13 — Config Registry + Money-Unit Convention

New table: admin.setting_definition — the config-key catalog covering admin.tenant_setting (a canonical registry of valid (category, key) pairs, declared value_type, default, tenant-editability, site-scopability). Global reference data (no tenant_id, no RLS), mirroring identity.permission/identity.agent_type_catalog's own established catalog-table shape exactly — is_active flag instead of soft-delete, zero autonomy columns (this is Vrida-engineering-maintained metadata, never an agent decision). Covers admin.tenant_setting ONLY — 4 other free-form config surfaces confirmed live (admin.integration_config.settings, admin.hardware_device.config, identity.agent_identity.config, ai module's own config fields) are DELIBERATELY out of scope, logged to OPEN_ITEMS as a deferred decision, not an oversight. NOT enforced against admin.tenant_setting via FK or trigger — disclosed, not silently assumed: a Postgres CHECK cannot reference another table's columns, and retrofitting a validation trigger onto the already-locked tenant_setting table was deliberately deferred rather than bundled into this catalog add. Zero backfill risk — brand-new table, zero rows. Admin: 10 tables/128 cols → 11 tables/140 cols.

Money-unit convention (docs only, zero column change): docs/database/SCHEMA_CONVENTIONS.md §8.1 now documents, in one place for the first time, the three money-unit column suffixes that were previously internally consistent within each module but never written down together: _cents (the default, everywhere except pos), _minor_units (pos module, PLUS orders.order_line's Hard Contract 1 snapshot columns — the one cross-module exception, confirmed live via information_schema and disclosed explicitly, not glossed over), and _millicents (ai module only, sub-cent LLM-call cost precision). All three are semantically bigint; _minor_units is byte-identical to _cents in unit and precision, pure naming-style divergence.

LIVE-REPRODUCED: a valid setting_definition row is accepted; a duplicate (category, key) is rejected; an invalid value_type is rejected; the set_updated_at trigger fires correctly on UPDATE (confirmed via a separate, non-transaction-batched autocommit test — now() is transaction-scoped, so a single BEGIN...ROLLBACK block cannot itself prove trigger-firing timing).

Independent Verification (2 separate agents, adversarial, findings pasted per Section 2.3.7/2.7/6 item 1a — no self-grading)

Lens A — Constraint correctness and migration safety. Independently re-derived every touched CHECK/FK/trigger's live definition via information_schema/pg_get_constraintdef and cross-checked against both the Drizzle source and the applied migrations — no mismatch found. Confirmed every migration's own "additive/safe" claim against live row counts at time of build. Confirmed the self-referencing FK workaround (reversed_calculation_id) is correctly applied, matching supersedes_calculation_id's established precedent. Confirmed packages/db's compiled dist/ and the live DB shape agree for every touched table via direct information_schema.columns queries. Verdict: CLEAN. Two NOTEs, not BLOCKERs: (1) no regression test originally exercised the new 'produced' movement_type value even though the CHECK itself was confirmed correct live — closed same-day by adding inventory-schema.spec.ts section M (M1/M2); (2) admin.setting_definition wasn't yet referenced in schema_docs/admin.md at time of the lens's run — expected, this docs-fan-out pass closes it.

Lens B — Scope discipline and disclosure integrity. Independently confirmed pos.sale_refund.sale_id is UNCHANGED (still NOT NULL) both in Drizzle source and live via \d pos.sale_refund — the anonymous-walk-in-return path was NOT bundled, matching the explicit instruction. Independently confirmed ai.ai_credit_account does NOT exist and platform.ai_credit_account DOES (Item 12's citation correction). Independently confirmed admin.setting_definition has no FK/trigger tying it to admin.tenant_setting — the "disclosed, not enforced" claim is accurate. Independently spot-checked the money-unit convention doc's claims against live schema. Verdict: CLEAN. Three NOTEs, not BLOCKERs, all addressed same-day: (1) the Item 9 migration's own jurisdiction-sign-CHECK-can't-be-DB-enforced claim didn't disclose that a trigger (its own sibling pattern, trg_tax_calculation_validate_reversal, in the SAME migration) could have closed the gap instead — resolved by actually adding trg_tax_calculation_jurisdiction_validate_sign post-verification, upgrading a disclosed gap to a DB-enforced one; (2) the money-unit convention doc's "_minor_units — pos module only" claim was inaccurate — orders.order_line also carries two _minor_units columns (Pricing's Hard Contract 1 seam) — corrected in SCHEMA_CONVENTIONS.md §8.1 to disclose the exception explicitly; (3) migration comments cited "PROJECT_DECISIONS #39"/"OPEN_ITEMS" for the anonymous-return flag and the (now-closed) jurisdiction sign gap before either entry existed — expected sequencing, this docs-fan-out pass adds them.

Docs

Schema docs (docs/database/schema_docs/) and module specs (docs/modules/module_spec/) updated for all 6 touched modules (crm, tax, pos, inventory, identity, admin) with a dated "Remediation Phase 3" subsection each, referencing this entry. CROSS_MODULE_CONTRACTS.md updated: the crm↔billing credit-limit seam (both directions, correcting the stale "credit columns removed, do not re-add" boundary note), the POS→Tax refund-reversal seam, the Identity agent-kill-switch precedence-chain row (with the corrected platform.ai_credit_account citation), and column-count deltas for pos/tax/crm/admin (plus a drive-by fix to inventory's own stale 335→337 count, unrelated to this phase's own inventory change). MODULE_INDEX.md updated: identity 396→400 cols, crm 189→191, tax 37→39, pos 138→143, admin 10→11 tables/128→140 cols; inventory unchanged (CHECK-widen only). OPEN_ITEMS.md gained new rows: the deferred anonymous-walk-in-return decision (flagged for the architect, not decided), the deferred credit-limit service-layer enforcement, the 4 out-of-scope config surfaces for setting_definition, and the closed jurisdiction-sign-trigger gap.

Confirm: Remediation Phase 3 complete — all 6 items live, independently verified with zero BLOCKERs (2/2 lenses CLEAN; every NOTE addressed same-day, not deferred). The anonymous-walk-in-return question is explicitly flagged for the architect's decision, not decided here. The full apps/api suite is green (608–609/609 across 4 runs; the 1 intermittent failure is the already-documented pre-existing admin-tenants.spec.ts B3 pagination race, confirmed unrelated — reproduces in isolation too). Phase 4 (futureproofing) is separate future work.

40. Remediation Plan Phase 4 — Futureproofing (2026-07-08), Final Phase + Closing the Anonymous-Return Decision

Phase 4 of the approved 4-phase remediation plan — the final phase, covering items 14–20 (futureproofing: fiscal periods, legal entity, exchange rates, enum→catalog, GDPR/erasure, custom-field registry, outbox+reconciliation) plus closing the one decision Phase 3 deliberately left open (the anonymous walk-in return). 8 migration files, 11 modules touched (platform, admin, pos, tax, billing, purchasing, orders, crm, ai, inventory, shared), all additive — zero DROP TABLE/DROP COLUMN anywhere in this phase (independently confirmed by adversarial verification below).

Closing the Phase 3 open decision — Anonymous Walk-In Return: DECIDED = ALLOW

pos.sale_refund.sale_id relaxed to nullable; chk_sale_refund_identification CHECK ((sale_id IS NOT NULL) OR (reason IS NOT NULL)) requires a refund to identify itself SOME way — a linked sale, or a documented no-receipt reason — never neither. Confirmed 0 live rows at build time, zero backfill risk. Audit controls a real anonymous-return flow needs (reason required at the UI layer, manager/actor attribution, an approval step for high-value anonymous refunds) are explicitly a SERVICE-LAYER requirement, NOT schema-enforced — logged to OPEN_ITEMS, not built here, per the same schema/service split this codebase has used throughout (e.g. Item 8's credit-limit enforcement, Item 12's agent kill-switch precedence chain).

LIVE-REPRODUCED: a refund with both sale_id and reason NULL is rejected (chk_sale_refund_identification); a refund with sale_id NULL and reason set (e.g. "anonymous walk-in return, no receipt") is now ACCEPTED — previously impossible; a refund with a valid sale_id and NULL reason is unaffected (pre-existing behavior). Independently re-confirmed by both verification lenses below.

Pre-build corrections applied first

  1. Item 14: the shared flag-trigger's OR UPDATE OF business_date clause was dropped specifically for pos.register_cash_entry (kept for sale/sale_refund) — Phase 1's own append-only trigger on register_cash_entry (trg_register_cash_entry_append_only) already rejects every UPDATE unconditionally, so an UPDATE clause on the new trigger would be dead code. Live-confirmed via pg_get_triggerdef: trg_register_cash_entry_flag_closed_period is BEFORE INSERT only, while trg_sale_flag_closed_period/trg_sale_refund_flag_closed_period retain BEFORE INSERT OR UPDATE OF business_date. Independently re-verified by both lenses (Lens A live-tested that an UPDATE attempt on a freshly-inserted register_cash_entry row is rejected outright by the pre-existing trigger, proving the correction was correct, not just stylistic).
  2. Item 15: the plan's draft cited "176 rows, 0 NULLs" for platform.tenant.name — re-verified live and found stale: the real count at build time was 1997 rows, still 0 NULLs. The gap is accumulated test-tenant pollution across this entire remediation effort's own test suites (gov-/rls-test--prefixed slugs, not literal %test% matches for most of them — only a minority match %test% directly). The corrected, live-verified figure is what the migration comment and backfill use, not the stale plan figure. The duplicated row in the originally-referenced "10 tenant-identity-assuming tables" list could not be found or reconciled — no such list existed anywhere in this session's own context (confirmed not present in any doc read this session). Rather than guess at the original list silently, the architect was asked directly and chose to have this list independently derived instead of supplying the original — see the table list under Item 15 below.
  3. Item 20b: the reconciliation view's real join/aggregation logic (sign-aware sums across movement_type) was NOT built this pass — flagged as UNVERIFIED against real transfer data per the explicit pre-build instruction. Only a minimal SHELL view ships now (plain LEFT JOIN, zero aggregation), independently confirmed via pg_get_viewdef by both verification lenses to contain no SUM/GROUP BY/computed drift math whatsoever.

Item 14 — Fiscal Periods

platform.accounting_period (id, tenant_id, period_start, period_end, status, closed_at, closed_by_actor_id) — the first use of Postgres's EXCLUDE USING gist in this codebase (btree_gist extension enabled for it): excl_accounting_period_no_overlap EXCLUDE USING gist (tenant_id WITH =, daterange(period_start, period_end, '[]') WITH &&) prevents two overlapping periods for the SAME tenant while leaving different tenants' identical date ranges unaffected — live-tested by both lenses (same-tenant overlap rejected with an exclusion_violation; same-tenant non-overlap accepted; same date range across two different tenants both accepted). A shared trigger function, platform.flag_closed_period_business_date(), is FLAG-NOT-REJECT by design (sets review_status='pending', never raises) — deliberately non-blocking because offline-sync needs a real June-30 sale to still land in July even if a period closes in between. Consumed by 3 triggers: trg_sale_flag_closed_period/trg_sale_refund_flag_closed_period (BEFORE INSERT OR UPDATE OF business_date) and trg_register_cash_entry_flag_closed_period (BEFORE INSERT only, per the pre-build correction above). pos.register_cash_entry had NO review-seam at all before this item — a genuine, necessary mid-build discovery, not an afterthought: the flag trigger's own review_status='pending' mechanism was literally impossible without first adding the full 5-column seam (review_status/review_reason/reviewed_by_actor_id/reviewed_at/decision_provenance) that every other reviewable table in this codebase already carries. pos.sale gained business_date via a 3-step migration (add nullable → backfill created_at::date for then-189 rows → SET NOT NULL DEFAULT CURRENT_DATE); pos.sale_refund got it directly (0 rows). Zero backfill risk beyond the 189-row sale backfill, itself zero-mismatch (both lenses independently confirmed count(*) FILTER (WHERE business_date IS NULL)=0 and count(*) FILTER (WHERE business_date != created_at::date)=0 against the live, now-grown row count).

LIVE-REPRODUCED (independently re-confirmed by both lenses): an overlapping accounting_period insert for the same tenant is rejected; a non-overlapping one succeeds; the same range for a different tenant succeeds. A pos.sale inserted with business_date inside a closed period is ACCEPTED but flagged review_status='pending'; one outside any closed period is unaffected (review_status='not_required'). Same flag behavior independently confirmed on pos.sale_refund. An UPDATE attempt on a pos.register_cash_entry row is rejected outright by the pre-existing append-only trigger, confirming the pre-build correction was substantively correct, not cosmetic.

Item 15 — Legal Entity

platform.legal_entity (id, tenant_id, name, ein_ref, is_primary, is_active) — 1:N from tenant, so a tenant can incorporate a 2nd LLC without splitting into two tenants. legal_entity_tenant_id_primary_unique (partial unique WHERE is_primary = true) allows exactly one primary entity per tenant while permitting unlimited non-primary ones — live-tested by both lenses (2nd primary rejected; 2nd+3rd non-primary accepted). Backfilled 1 row per existing platform.tenant (1997 rows at build time, corrected per the pre-build note above), name sourced from tenant.name since tenant_profile.legal_name was confirmed 0-for-12 non-null and thus unusable. Nullable entity_id added to 10 tables independently derived (documented with reasoning, since no pre-existing list was found in this session's context — the architect explicitly chose this over supplying the original list): platform.contract, platform.billing_account, admin.compliance_document, tax.tax_calculation, billing.ar_account, billing.vendor_payable, purchasing.vendor_invoice, purchasing.purchase_order, orders.order_header, pos.sale — financial/legal-document-bearing HEADER tables that could plausibly differ per legal entity within one tenant. Disclosed scoping rule, made explicit here per Lens B's finding: entity_id was added ONLY to header tables, never to their line-item children (purchase_order_line, vendor_invoice_line, ar_charge, ar_payment, purchase_receipt) or to purchasing.vendor itself — unlike tenant_id, which this codebase applies uniformly to every table including line items. This is deliberate (a line item's entity is always inherited via its header's FK, never needs its own column), not an oversight, but was not previously stated as an explicit rule anywhere — it is now.

NOTE (found during independent verification, not a defect): the "1 primary legal_entity per tenant" invariant this backfill establishes is a point-in-time guarantee, not an ongoing DB-enforced one. Both lenses independently confirmed that by the time of their own live-testing, platform.tenant had grown past its 1997-row backfill snapshot (to 2127, then further, from this remediation effort's own continued test-suite churn on the shared dev DB) — every tenant created AFTER the backfill ran has zero legal_entity row. This is expected and harmless today (nothing yet reads legal_entity assuming 1:1 coverage, and no service exists to consume it), but no trigger or service-layer hook creates a legal_entity row for new tenants going forward. Logged to OPEN_ITEMS.

LIVE-REPRODUCED: a 2nd is_primary=true row for the same tenant is rejected; 2 additional is_primary=false rows for a tenant with an existing primary are accepted; a blank/whitespace name is rejected (chk_legal_entity_name_not_blank); all 10 entity_id columns confirmed nullable and FK-valid.

Item 16 — Exchange Rates

shared.exchange_rate (id, from_currency_code, to_currency_code, effective_date, rate, source) — a uuid surrogate PK + UNIQUE(from_currency_code, to_currency_code, effective_date), deliberately NOT a natural composite PK despite shared's otherwise natural-key-PK convention: a codebase-wide grep confirmed ZERO composite-PK precedent anywhere in ~180 tables, so this table matches that universal convention over a shared-module-native shape. Pure global reference data (no tenant_id, no RLS) — confirmed live to match every one of shared's other 11 tables with zero exception. billing.validate_ar_payment_application_currency() + trg_ar_payment_application_validate_currency (BEFORE INSERT only, since ar_payment_application is itself append-only) enforces that an ar_payment's currency, its target ar_charge's currency, and (when the same account backs both) the shared ar_account's currency all agree — both branches (payment/charge mismatch, and account-currency drift when payment and charge already agree with each other but not with their shared account) independently live-tested by both lenses with real fixtures and found correctly rejecting/accepting.

LIVE-REPRODUCED: a EUR payment applied to a USD charge is rejected; a matching USD/USD application succeeds; a payment and charge that agree with each other (both USD) but whose shared account carries a different currency (EUR) is ALSO rejected — the account-drift branch, independently exercised by both lenses, not just the simpler payment/charge branch.

Item 17 — Enum→Catalog (Additive Interim Step, a–d)

Each sub-item adds one new catalog table + one new, independently-nullable FK column on each consuming table, while the OLD CHECK-enum column stays completely unchanged. This interim gap (the new FK column is not yet constrained to stay in sync with the legacy CHECK-enum column) is disclosed durably in the Drizzle TypeScript source itself (not just a migration-file SQL comment that could rot if migrations are ever squashed) — independently confirmed present in pos/catalog.ts, shared/payment_terms_catalog.ts, tax/calculation.ts, and admin/config.ts by Lens B.

  • (a) POS tender types: pos.tender_type_catalog (7 seeded rows matching the existing enum, including 'reward') + pos.sale_payment.tender_type_id.
  • (b) Payment terms: shared.payment_terms_catalog (10 seeded rows, including 2_10_net_30 — net_days=30, discount_percent=2.00, discount_days=10 — genuinely representing "2/10 net 30", which a bare CHECK-enum cannot) + payment_terms_id on crm.customer, purchasing.vendor, purchasing.purchase_order. Deliberately simplified to pure global (no tenant_id) during drafting — an earlier draft considered an optional tenant-scoped variant mirroring identity.role's mixed-scope pattern, but this was dropped as unrequested scope creep. NOTE (Lens B): crm.customer.credit_terms's existing CHECK-enum (6 values, from Phase 3) is NOT a clean subset of this catalog's 10 codes — 4 catalog codes (cod, prepaid, net_7, 2_10_net_30) have no credit_terms equivalent at all. The "not yet kept in sync" disclosure is accurate, but whoever executes the eventual cutover must make a real mapping decision for these 4 codes, not assume a trivial 1:1 rename — now stated explicitly here and in OPEN_ITEMS.
  • (c) Tax jurisdiction levels: tax.jurisdiction_level_catalog (6 seeded rows, including country — closing the VAT/GST gap) + tax_calculation_jurisdiction.jurisdiction_level_id, PLUS a REAL widen of chk_tax_calculation_jurisdiction_level to add 'country' to the allowed list — independently confirmed by Lens A to be a genuine widen (the original migration, 20260707080000_tax_module.sql, defined this same-named CHECK without 'country'), not a no-op. NOTE: tax_calculation_jurisdiction is itself append-only (no UPDATE/DELETE grant, plus its own append-only trigger) — meaning the new jurisdiction_level_id column can structurally never be backfilled onto any of the pre-migration rows, only used by future inserts. This is a permanent gap for historical rows, not a temporary sync lag, though the migration's own "zero-risk scaffolding" language already implied this; now stated explicitly.
  • (d) Integration providers: admin.integration_provider_catalog (6 seeded rows) + admin.integration_config.provider_id.

All 4 catalogs independently confirmed to have zero tenant_id and zero RLS (global reference data), matching the established precedent of identity.permission/admin.setting_definition/tax.jurisdiction_level_catalog's sibling design.

NOTE (cross-cutting, pre-existing, NOT introduced by this phase — independently caught by Lens A): all 4 new global catalog tables, along with every pre-existing global-reference table in this codebase (shared.currency, admin.setting_definition, etc.), grant full INSERT/SELECT/UPDATE/DELETE to the authenticated role with no RLS restricting who can mutate them — live-reproduced: a plain tenant-scoped session can DELETE FROM pos.tender_type_catalog WHERE code='cash' and it succeeds. This is a systemic gap in the Postgres role/grant model (no distinct "platform-admin-only, tenant-read-only" role exists yet), not something this phase introduced — Phase 4's 4 new catalogs simply inherited an existing pattern. Logged to OPEN_ITEMS for whoever owns the grant model, not fixed here (out of scope for an additive futureproofing phase).

LIVE-REPRODUCED: all 4 catalogs' seed rows independently confirmed against their documented lists; the widened jurisdiction-level CHECK accepts 'country' and still rejects an unrelated bogus value ('planet'); every new FK column confirmed nullable and independently insertable/omittable.

Item 18 — GDPR/Erasure + Agent Memory

crm.customer.pii_vault_ref (nullable text) mirrors the ein_ref vault precedent, enabling future crypto-shred erasure without duplicating the vault-service dependency already logged in OPEN_ITEMS (row 218) — the new Drizzle comment explicitly says "same disclosed dependency, not a new one," correctly avoiding a redundant OPEN_ITEMS row (independently confirmed by Lens B). ai.agent_memory gains subject_type/subject_ref/expires_at + chk_agent_memory_subject_consistency CHECK ((subject_type IS NULL) = (subject_ref IS NULL)) — a true bidirectional requirement (both null or both set), independently exercised across all 4 combinations by Lens A with zero asymmetry found.

LIVE-REPRODUCED: subject_type set with subject_ref NULL is rejected; the reverse (subject_ref set, subject_type NULL) is also rejected; both NULL is accepted; both set is accepted.

Item 19 — Custom-Field Registry

admin.custom_field_definition (id, tenant_id, entity_type, field_key, display_name, field_type, default_value, is_required, is_active) governs the 7 confirmed ungoverned attributes JSONB columns — independently re-confirmed by Lens B to be exactly 7, no more no fewer: crm.customer, inventory.item, inventory.item_variant, orders.order_header, purchasing.purchase_receipt, purchasing.vendor, purchasing.vendor_item. chk_custom_field_definition_entity_type restricts to exactly these 7; chk_custom_field_definition_field_type restricts to 6 value types (boolean/number/string/json/array/date); custom_field_definition_tenant_entity_key_unique (partial WHERE is_active = true) allows re-registering a retired key. RLS enabled with the standard tenant-isolation policy.

LIVE-REPRODUCED: a valid row inserts cleanly; an entity_type outside the 7 allowed values is rejected; an invalid field_type is rejected; a duplicate active (tenant_id, entity_type, field_key) is rejected while the same key with one row inactive is accepted.

Item 20 — Outbox + Stock Reconciliation (a–c)

(a) platform.outbox — a durable transactional-outbox event table (id, tenant_id, aggregate_type, aggregate_id, event_type, payload, status, attempts, last_attempted_at, delivered_at, error). Deliberately uses gen_random_uuid() for its PK, NOT platform.uuid_generate_v7() — independently confirmed by both lenses to be the correct choice, since this table is genuinely mutable (status/attempts/delivered_at all change after insert, live-tested: an UPDATE to status='delivered' succeeds), unlike this codebase's genuine append-only ledgers which get UUIDv7 per Phase 2's own established rule. chk_outbox_delivered_consistency requires delivered_at set iff status='delivered'.

(b) inventory.stock.last_movement_id (nullable FK → stock_movement) — a reconciliation watermark, 0 rows at build time, zero backfill risk. inventory.stock_reconciliation_shell — the FIRST CREATE VIEW in this entire codebase (independently confirmed by both lenses via grep that no prior CREATE VIEW precedent exists anywhere). Deliberately minimal per the pre-build correction: pg_get_viewdef confirms a plain LEFT JOIN with zero aggregation — the real drift-detection logic (sign-aware sums across movement_type, matching chk_stock_movement_movement_type's own vocabulary) is a named, disclosed follow-up, not silently assumed correct. Fixed a pre-existing test assumption along the way: information_schema.tables includes VIEWs by default, so inventory-schema.spec.ts's hardcoded table-count assertion needed a table_type = 'BASE TABLE' filter to stay correct at 24 (the view doesn't count as a 25th table).

(c) A documented (NOT DB-enforced — no pg_cron in this environment) scheduled-job contract for releasing expired stock reservations: any inventory.stock_reservation row with status='active' and expires_at < now() should be transitioned to status='expired' by a periodic job. No DDL — the schema (status/expires_at) has fully supported this since inventory's original 2026-07-06 build; only the job itself is unbuilt. Logged to OPEN_ITEMS with the exact contract text.

LIVE-REPRODUCED: an outbox row inserts with status defaulting to 'pending'; an invalid status is rejected; a status='delivered' row without delivered_at is rejected, a matched pair is accepted; a subsequent UPDATE to status='delivered' on an existing row succeeds (proving mutability); stock.last_movement_id accepts a valid stock_movement id and is nullable; the reconciliation shell view's definition contains no aggregation math.

Independent Verification (2 separate agents, adversarial, findings pasted per Section 2.3.7/2.7/6 item 1a — no self-grading)

Lens A — Constraint correctness and migration safety. Independently re-derived every touched CHECK/FK/trigger/EXCLUDE/view's live definition via psql/information_schema/pg_get_constraintdef/pg_get_triggerdef/pg_get_viewdef and cross-checked against both the Drizzle source and the applied migrations for all 8 files — no mismatch found. Live-tested (not just statically inspected) every claimed enforcement behavior with real INSERT/UPDATE/ROLLBACK transactions: the accounting_period EXCLUDE constraint (same-tenant overlap rejected, cross-tenant overlap accepted), the register_cash_entry append-only trigger genuinely blocking the UPDATE the pre-build correction anticipated, the flag-not-reject trigger's fail-open behavior on a real pos.sale insert through a live open register session, the legal_entity partial-unique index (both directions), both branches of the ar_payment_application currency trigger, all 4 combinations of the agent_memory subject-consistency CHECK, the custom_field_definition CHECKs and partial-unique, and the outbox mutability claim (contrasted directly against a genuine append-only table's grants). Confirmed packages/db's compiled build is clean and Drizzle source matches live DB column-for-column on 3 sampled tables. Verdict: CLEAN. 2 NOTEs, not BLOCKERs, both folded into this entry above: (1) the legal_entity 1-per-tenant invariant is point-in-time, not an ongoing guarantee — 130 tenants created after the backfill already lack one, purely from this remediation effort's own continued test-suite growth on the shared dev DB; (2) tax_calculation_jurisdiction.jurisdiction_level_id can never be backfilled onto pre-migration rows since the table is append-only — a permanent, not temporary, gap. Plus 1 cross-cutting, pre-existing (not Phase-4-introduced) NOTE: all Vrida-wide catalog tables, old and new, are writable/deletable by any tenant-scoped session — a systemic grant-model gap, logged to OPEN_ITEMS, not fixed here.

Lens B — Scope discipline and disclosure integrity. Independently confirmed every "deliberately deferred"/"disclosed gap"/"additive interim" claim in the migration and Drizzle-source comments is actually true: the anonymous-return CHECK's exact logic matches the specification precisely (not stricter or looser); the Item 14 pre-build correction (dropping the UPDATE clause on register_cash_entry specifically) is genuinely applied and genuinely justified (live-reproduced the append-only trigger's rejection); the Item 17 interim-gap disclosures live durably in Drizzle TypeScript source, not migration-only SQL comments; the Item 20b shell view genuinely contains zero aggregation math; the pii_vault_ref GDPR dependency correctly cross-references the existing ein_ref OPEN_ITEMS row instead of duplicating it; shared.exchange_rate/payment_terms_catalog genuinely match the shared schema's 100%-global convention with zero quiet exception; every new table's RLS/PK-generation posture correctly follows the established tenant-scoped-vs-global and append-only-vs-mutable conventions with no exceptions found; zero destructive DDL (DROP TABLE/DROP COLUMN) anywhere in the phase. Verdict: CLEAN on scope and disclosure integrity — no BLOCKER-level defects in the schema/code itself. The most significant finding, which this entry treats as requiring closure rather than a routine NOTE: zero dedicated regression tests existed for any of Items 14–20 at the time of this lens's run — a real, reproducible deviation from every one of Phases 1–3's own established practice (each of which added dedicated test coverage in the same pass, e.g. Phase 3's own "section M" precedent closing an identical gap same-day). Not evidence of an actual live bug (everything the lens spot-checked live passed), but a genuine process gap. Closed the same day, before this phase was declared complete: dedicated regression tests were added across all 11 touched modules' existing (or, for platform, one new) schema-spec files, covering every constraint/trigger/CHECK/view this lens and Lens A each live-tested by hand — see the Tests subsection below. Two lower-priority NOTEs, folded into the relevant items above: the entity_id "header-only" placement rule was implicit, not stated — now explicit (Item 15); the credit_terms/payment_terms_catalog vocabulary mismatch needed calling out explicitly, not just generically disclosed as "not yet synced" — now explicit (Item 17b).

Tests

Closed same-day, before this phase was declared complete: dedicated regression tests were written and run against the live DB across all 11 touched modules (10 existing schema-spec files extended, 1 new file created for platform, which previously had none), totaling roughly 105 new tests, none of which existed when Lens B's finding was raised:

  • platform-remediation-phase4.spec.ts (NEW file): 16 tests — accounting_period (EXCLUDE overlap same-tenant/cross-tenant, status/date/closed-consistency CHECKs), legal_entity (partial-unique primary, blank-name CHECK), outbox (status/delivered CHECKs, mutability proof via a real UPDATE), contract/billing_account.entity_id spot-checks.
  • pos-schema.spec.ts: +10 tests (sections H–K) — the anonymous-return CHECK (all 3 cases), tender_type_catalog (seed + FK + nullability), the flag-not-reject trigger on sale/sale_refund/register_cash_entry (including the register_cash_entry append-only-blocks-UPDATE proof), sale.entity_id. 34/34 total.
  • tax-schema.spec.ts: +7 tests (section L) — jurisdiction_level_catalog seed, jurisdiction_level_id FK/nullability, the widened CHECK accepting 'country' and still rejecting bogus values, tax_calculation.entity_id. 36/36 total.
  • billing-schema.spec.ts: +5 tests (section K) — both branches of the ar_payment_application currency trigger (payment/charge mismatch, and the distinct account-currency-drift case), ar_account/vendor_payable.entity_id. 52/52 total.
  • purchasing-schema.spec.ts: +10 tests (section K) — vendor/purchase_order.payment_terms_id, purchase_order/vendor_invoice.entity_id, plus bogus-FK-rejection regression checks. 45/45 total.
  • orders-schema.spec.ts: +2 tests (section L) — order_header.entity_id FK resolution + nullability. 43/43 total.
  • crm-schema.spec.ts: +5 tests (section P) — customer.payment_terms_id (FK/nullable/bogus-rejected), customer.pii_vault_ref (accepts text/nullable). 27/27 total.
  • ai-schema.spec.ts: +4 tests (section J) — all 4 combinations of chk_agent_memory_subject_consistency, expires_at nullability. 23/23 total.
  • admin-schema.spec.ts: +28 tests (sections I–K) — custom_field_definition (both CHECKs' full allowed-value coverage, partial-unique reuse-after-deactivation), integration_provider_catalog seed + provider_id FK, compliance_document.entity_id. 74/74 total.
  • shared-schema.spec.ts: +14 tests (sections F–G) — exchange_rate's 3 CHECKs + unique constraint + no-RLS/no-tenant_id confirmation, payment_terms_catalog seed spot-check + no-RLS/no-tenant_id confirmation. 34/34 total.
  • inventory-schema.spec.ts: +4 tests (section N) — stock.last_movement_id FK/nullability, the reconciliation shell view's column shape and LEFT-JOIN behavior (both with and without a last_movement_id). 47/47 total.

A genuine, reusable discovery surfaced independently by 2 of the 11 test-writing passes: this codebase's Postgres driver (postgres.js via Drizzle) does not surface the violated constraint's name in error.message — it lives on error.cause — so .rejects.toThrow(/constraint_name/) (a regex on the top-level message) silently fails against every real constraint violation. The established, correct convention (already used in billing-schema.spec.ts and now confirmed as the sole pattern via a codebase-wide grep for rejects.toThrow(/, zero hits) is bare .rejects.toThrow() or .rejects.toMatchObject({ cause: expect.objectContaining({ code, constraint_name }) }). All new tests conform to this.

Full apps/api suite (post-test-writing, all 11 files together): 707/707 passing across 29 suites, confirmed clean on 2 of 3 consecutive runs; the 1 failure seen was the already-documented, pre-existing admin-tenants.spec.ts B3 pagination flake, reproducing with its exact known signature. packages/db build remains clean.

Docs

Schema docs (docs/database/schema_docs/) and module specs (docs/modules/module_spec/) updated for all 11 touched modules (platform, admin, pos, tax, billing, purchasing, orders, crm, ai, inventory, shared) with a dated "Remediation Phase 4" subsection each, referencing this entry. CROSS_MODULE_CONTRACTS.md updated: the legal_entity FK seam (10 tables), the ar_payment_application currency-agreement trigger, the 4 new catalog tables' consumer seams, the anonymous-return decision closure. MODULE_INDEX.md updated with honest deltas for all 11 touched modules (platform 23→26 tables/408→440 cols, admin 11→13/140→161, pos 9→10/143→160, tax 2→3/39→47, billing 9/162→164, purchasing 16/398→402, orders 7/173→174, crm 13/191→193, ai 7/118→121, inventory 24/337→338 tables unchanged +1 view (not counted as a table)/+1 col, shared 10→12/108→136 — the last of these also corrects a PRE-EXISTING, Phase-4-unrelated 12-column drift: shared's stated baseline of 108 cols never reflected entry #21's own FIX 1 review-seam addition (+4 cols × 3 tables = 12), only the earlier +7 autonomy-backfill; the true pre-Phase-4 baseline was 120, not 108 — corrected here as a disclosed drive-by fix, matching Phase 3's own precedent of fixing an unrelated stale count found in passing). OPEN_ITEMS.md: closed the anonymous-walk-in-return HUMAN DECISION row (resolved = ALLOW, see above); added new rows for the anonymous-return service-layer audit controls (reason/attribution/approval), the Item 17 sync-constraint gap (all 4 sub-items), the Item 20b real join/aggregation logic follow-up, the Item 20c scheduled-job contract text, the legal_entity new-tenant-provisioning gap, the credit_terms/payment_terms_catalog vocabulary-mapping decision, and the cross-cutting catalog-table grant-model gap (all discovered/finalized during this phase's own independent verification, not silently deferred).

Confirm: Remediation Phase 4 complete — the anonymous-return decision built + recorded (ALLOW), all 7 items (14–20) live, independently verified with zero BLOCKERs (2/2 lenses CLEAN on constraint correctness and scope/disclosure integrity; every NOTE addressed same-day — including the missing-regression-tests finding, closed via a full test-writing pass across all 11 touched modules before this phase was declared complete, not deferred). The full apps/api suite is green. This completes the 4-phase remediation plan.

41. Admin Console Wiring — 18 New Read Endpoints, Real-Data Cutover, 2 Live Bugs Found + Fixed

Decided: 2026-07-08. This is application-layer wiring on top of already-locked schemas (platform + identity), not a new module through the design-lock-build pipeline — no new tables or columns were added; every route reads columns that already existed.

Context. The admin console (apps/web/admin) had 3 of 18 page groups on real data (Tenants list/detail-Overview, Announcements, Settings — see entry referenced in MODULE_BUILD_STATUS.md footnote ³) with the rest on mockData.ts. This pass wired the remaining tenant-detail tabs and cross-tenant list pages to real reads, using only existing schema — confirmed against live information_schema queries rather than assumption before writing any query.

Backend — 18 new GET routes, 8 new service methods. PlatformService gained 7 methods (listTenantsByOnboardingStep, listAllSubscriptions, listAllInvoices, listAllPayments, getDunningQueue, getDataLifecycleQueue, listInternalActivityWithNames) plus reused 5 pre-existing methods that had no route yet (getContracts, getAcceptances, listLifecycleEvents, getContacts, getUsage, listDataLifecycleRequests, listPromoCodes, listAgreementVersions). IdentityService gained listSupportAccessGrants(tenantId?) — Identity's first-ever HTTP-reachable route, via a new IdentityController (previously zero controllers existed for this module; see MODULE_BUILD_STATUS.md footnote ⁵, now stale). Routes split across AdminTenantsController (+7 tenant-scoped), 3 new controllers (AdminBillingController, AdminCatalogController, AdminOpsController — cross-tenant, split out because they aren't scoped under a single tenant's :id), and IdentityController (2 routes). Full endpoint table in module_spec/platform.md §7 and module_spec/identity.md §6.

Frontend — all 7 remaining tenant-detail tabs + 8 cross-tenant list pages cut over. TenantSkeletonPanels.tsx (Contracts, Lifecycle, Contacts, Usage, Data & Retention, Internal Notes, Support Access) now takes real data as props instead of importing mockData.ts; Onboarding tab reuses the Overview tab's already-fetched getTenantOnboarding() result (onboarding.tasks) rather than issuing a second fetch. Cross-tenant pages (Onboarding, Subscriptions, Invoices, Payments, Promotions, Agreement Versions, Audit log, Support Access) rewritten against real enums/columns — several diverged from the old mock shapes (e.g. real SubscriptionStatus has 9 values vs. mock's 4; real promo_code.discount_value is percent-or-cents depending on discount_type, documented in schema_docs/platform.md's own money-convention note). Explicitly out of scope, left on mock per an in-session decision: Plans & pricing, Entitlements catalog, Operators (role field — a genuine schema gap, platform-level roles aren't representable today), Reports, and the top-level Usage page's daily-chart/trend-line portions (its per-tenant Usage tab IS real). docs/open-items/OPEN_ITEMS.md row 67 recounts the remaining truly-unwired page total against this list.

Bug 1 — MRR silently string-concatenated instead of summing. listAllSubscriptions()'s computed mrr_cents column (a CASE expression over tier_definition.price_monthly_cents/price_annual_cents, both bigint) was typed sql<number> in Drizzle but the Postgres driver (node-postgres) returns bigint columns as JS strings by default (a precision-loss guard) — the TS type lied about the runtime type. The Dashboard's sum + mrr_cents reduction silently did string concatenation, producing $49,004,900,990,099 instead of the correct $296. Fixed with an explicit ::int cast in the SQL (safe — subscription cents values are well under the ~2.1B int4 ceiling). Caught during the Dashboard's own browser verification, not by any test (none existed for this query).

Bug 2 — DATE-only columns rendering one calendar day early. contract.start_date/end_date, tenant_usage_summary.period_start/period_end, subscription_invoice.due_date, and agreement_version.effective_date are all Postgres date columns (no time-of-day). new Date('2026-06-01') parses as UTC midnight; every existing fmtDate helper across these page components called .toLocaleDateString() with no timeZone option, so it rendered in the browser's local timezone — a day early in any UTC-negative timezone (confirmed: the dev machine is UTC-7, new Date('2026-06-01').toLocaleDateString(...) → "May 31, 2026"). Invisible before this pass because these columns were empty; became visible only once the seed script (below) populated real DATE values. Fixed by adding timeZone: 'UTC' to every DATE-column formatter (a new fmtDateOnly helper in TenantSkeletonPanels.tsx; inline fixes in invoices/page.tsx and agreement-versions/page.tsx) — TIMESTAMP columns (created_at, accepted_at, etc.) were left on local-time formatting, which is correct for those.

Decision — Dashboard aggregates scoped to 5 flagship tenants, not the full platform.tenant table. Discovered mid-build: ~2,283 of ~2,288 platform.tenant rows are schema-test fixtures left over from this codebase's own earlier build/test work (e.g. RLS Test Tenant C (append-only, never cleaned up), Gov Test D3-...), not demo data. A raw COUNT(*)/ORDER BY created_at DESC for "Total customers"/"Recent signups" would have shown ~2,288 and surfaced fixture names directly on the Dashboard. Given the choice between showing the noisy-but-honest raw count, fabricating a filter heuristic, or leaving those specific tiles on mock, the user chose: scope Dashboard aggregates only (FLAGSHIP_TENANT_IDS, a disclosed 5-UUID allowlist now in packages/types/index.ts) to the 5 tenants dev-seed.ts already gives coherent profile+subscription+billing data (Greenleaf Nursery, Blue Bottle Roasters, Harmon Hardware & Supply, Bijou Boutique, Paperback Paradise Books). Every other page (Tenants list, Onboarding pipeline, etc.) still shows the full, real, unscoped table — the fixture noise is visible there, not hidden. platform.subscription/tenant_data_lifecycle turned out to already be naturally scoped to just these 5 tenants (no other tenant ever got a subscription row), so only the tenant-identity and onboarding-pipeline aggregates needed the explicit allowlist. Not resolved by this decision: the ~2,283 fixture rows themselves remain in the DB and still surface on every unscoped page — a cleanup pass would need explicit sign-off (destructive) and is logged to OPEN_ITEMS rather than done here.

Seed data — packages/db/seeds/admin-console-seed.ts, additive-only. 10 of the tables the new routes read from were completely empty (contract, agreement_acceptance, agreement_version, tenant_usage_summary, tenant_data_lifecycle, tenant_internal_activity, subscription_invoice, payment, promo_code, operator_audit_log) — real endpoints, zero rows to show. Unlike dev-seed.ts (which truncates the whole platform schema), this script only INSERTs, scoped to the 5 flagship tenants where tenant-scoped and idempotency-guarded per table (checks for an existing row before inserting, safe to re-run). Also backfills full_name = 'Jordan Ellis' onto the pre-existing, previously-unnamed identity_user row tied to the admin console's own out-of-band JWT-minting fixture, so operator-attributed seed rows (internal notes, audit log) resolve to a real name instead of a truncated UUID.

Testing. All 18 routes smoke-tested against the live local API with a real operator JWT (200s, correct empty-array/empty-object responses on then-still-empty tables). Every wired page walked in the browser post-seed: real data confirmed rendering correctly, zero console errors, zero failed network requests, both bugs above caught and fixed during this pass. npx tsc --noEmit clean on both apps/api and apps/web/admin (3 pre-existing, unrelated inventory/pricing test-file errors excluded). next build (production) clean, all new routes correctly server-rendered on demand. No automated HTTP integration tests existed for any of the 18 routes going into this entry — the established pattern for this (apps/api/src/platform/__tests__/admin-tenants.spec.ts: real supertest + NestJS TestingModule + real local Supabase auth fixtures) was not yet applied here; closed in the same pass as this entry — see the test-file list and pass/fail counts appended below.

Confirm: 18 new endpoints live, real-data cutover complete for every page in scope, 2 real bugs found and fixed during verification (not by pre-existing tests, since none existed), the flagship-tenant-scoping tradeoff made explicitly and disclosed rather than silently hidden.

Testing — closed in the same pass, not deferred. 59 new HTTP integration tests written across 5 files, following the established admin-tenants.spec.ts pattern (real supertest + NestJS TestingModule + real local Supabase auth fixtures): 14 new cases extending admin-tenants.spec.ts (groups I–O, the 7 tenant-scoped routes), admin-billing.spec.ts (new, 13 cases), admin-catalog.spec.ts (new, 10 cases), admin-ops.spec.ts (new, 8 cases), identity/__tests__/identity-controller.spec.ts (new, 14 cases — the first HTTP test file for IdentityController). All 59 green, each file independently re-run for stability, all fixture teardown confirmed leaving zero orphaned rows.

A serious, PRE-EXISTING bug was found while running the full suite — unrelated to this entry's own changes, but too important not to record here. The full-suite run (766 tests, up from 707 — exactly the +59 above) surfaced 15 failures, all inside identity-crud.spec.ts, identity-governance.spec.ts, and identity-machine.spec.ts — none of them files touched by this entry. Root-caused by hand (isolated, minimal reproduction scripts against the live local DB, four rounds of bisection): permission-engine.ts's Step 1/Step 2/Step 4 queries, and platform.service.ts's resolveEntitlements(), all combine a Drizzle-typed bind-parameter condition (eq(...)) with a raw sql fragment containing an unparameterized now() call inside the same and(...) — e.g. and(eq(roleAssignment.actor_id, actorId), sql\${roleAssignment.starts_at} <= now()`)`. Reproduced deterministically: a role assignment written moments earlier via assignRole() (confirmed correct via raw SQL — right actor, right role, status='active', starts_at in the past, ends_at null) is invisible to this exact query shape, while the identical row IS found by (a) the same query with the raw fragment removed, (b) Drizzle's own lte(col, new Date()) in place of the raw fragment, and (c) plain psql. Swapping to lte(col, sql\now()`)— same semantics, no raw-fragment-plus-bind-param combination — also finds the row correctly, isolating the trigger to that specific combination rather than tonow(), the column, or the data itself. Not yet understood: whether this is deterministic on every call or depends on a given connection's prepared-statement cache history (this session's single long-lived local Postgres connection has run thousands of ad hoc queries today) — not chased further, since the reproduction is already solid enough to act on. **Blast radius: 4 call sites, all using the identical pattern** — permission-engine.tslines 124–125 (Step 1, role assignments), 164–165 (Step 2, group role assignments), 277–278 (Step 4, permission overrides), andplatform.service.ts line 447 (resolveEntitlements(), the same query the admin console's own Entitlements tab calls). Fails closed (denies/returns-empty rather than over-granting), so this is a correctness/availability bug, not a privilege-escalation risk — but it means role-based permission checks and entitlement resolution can silently return "no access"/"no entitlements" for actors who should have them, anywhere in the application, not just in these 3 test files. **Not fixed in this entry** — flagged prominently rather than patched blind, since a fix needs to establish *why* the combination breaks (a Drizzle SQL-compiler bug in how it numbers/orders bind params when raw fragments are interleaved, vs. a postgres.jsprepared-statement-cache issue) before deciding whether the right fix is per-call-site (swap tolte()/gte()everywhere, which is proven to work) or a deeper library-level one. Seedocs/open-items/OPEN_ITEMS.md` for the tracked row.

42. Tenant-Isolation Code Review Sweep + Fix Pass — 32 Cross-Tenant Bugs Closed in identity.service.ts/platform.service.ts, 2 New Findings from Adversarial Verification, Corrected Diagnosis of the #41 Drizzle now() Item

Decided: 2026-07-08, same day as entry #41. This is a read-only code review (Part A) immediately followed by a full fix pass (Part B) on PlatformService/IdentityService — no schema change, application-layer only.

Part A — scope confirmation + same-bug-class sweep. Confirmed the prior code-review pass already covered 100% of apps/api's real service-layer code: only platform.service.ts/identity.service.ts (+permission-engine.ts) exist as services; the other 13 module directories are schema-spec-test-only (no .service.ts/.controller.ts anywhere), matching this file's own module-status prose. apps/web/admin/apps/web/tenant frontends confirmed out of scope. A 4-way parallel sweep (re-reading every method in both files against the pattern: bare-ID lookup/mutation with no tenant_id filter, or an authorization gate checking one actor-path but not a sibling) found 20 additional instances beyond the originally-reported set — 18 in identity.service.ts (revokeOverride, updateGroup, deleteGroup, removeGroupMember, listGroupMembers, wireBundleToRole, getServiceAccount, deactivateServiceAccount, revokeApiKey, listApiKeys, getAgent, deactivateAgent, removeSkillFromAgent, listAgentSkillAssignments, acknowledgeSodViolation, waiveSodViolation, resolveSodViolation, revokeSupportAccess) plus 2 new Critical authorization-logic gaps distinct from the tenant-ID pattern: approveAccessRequest/denyAccessRequest never checked that the reviewer was the request's designated approver (or even a member of its tenant), and useSupportAccess never verified the fetched grant's tenant/actor matched what the caller passed in before logging a "used" event — both independently confirmed via direct code read before being counted. 2 more instances found in platform.service.ts (revokeEntitlement, updateTenantContact). The gate/middleware layer (permission-engine.ts, admin-auth.guard.ts, tenant-context.middleware.ts) came back clean.

Part B — fix pass, ~32 methods total (10 originally-named + 20 sweep-found + 2 misc), same shape throughout: add a tenantId parameter, filter every query by it, throw (not silently no-op) on a cross-tenant miss. assignRole additionally now ALWAYS looks up the target role's own tenant_id (previously only looked up conditionally, for the agent-gate check) and rejects tenant_id !== null && tenant_id !== callerTenantId — closing the CRITICAL cross-tenant role-assignment bug where a role from tenant B could be assigned to a tenant-A actor and, since permission-engine.ts never re-checks role.tenant_id on resolution, be silently honored as if it were tenant A's own role. grantOverride gained the equivalent check on tenantUserId. The agent-elevation gate (DR-25) fix: assignRole now blocks (fails closed, requires explicit skipApprovalGate: true) a gated-role assignment via actorGroupId — previously the gate only ever checked opts.actorId, a complete bypass since a role could be wired to a group with zero approval, then any agent added to that group inherited it. addGroupMember closes the other half — it now checks whether the target group already holds an active gated-role assignment before adding an agent actor, same fail-closed/explicit-bypass shape.

Every CRITICAL/HIGH fix was live-reproduced via git stash, not just unit-tested against the fixed code. Isolate the fix under test with git stash push --keep-index -- <file> (reverting ONLY the source file, keeping the new test file), run the new regression test against the pre-fix code (must fail — proves the vulnerability was real), git stash pop (restores the fix), re-run (must pass). Done for all 2 CRITICAL + 4 HIGH explicitly-named items (T1 assignRole, T2 grantOverride, T3 deactivateRole/revokeRole as the representative pair of the 6 role-mutation methods, X5 the actorGroupId/addGroupMember gate bypass) plus all 11 sweep-found identity.service.ts extras and all 6 platform.service.ts extras (28 tests total across 2 new spec files, identity-tenant-isolation.spec.ts/-2.spec.ts) — every one demonstrably succeeded pre-fix and is rejected post-fix. platform.service.ts's stash test needed a standalone script using the OLD (pre-fix) 1-arg call signature directly, since the fix inserted a new leading parameter rather than appending one — running the new test file's 2-arg calls against the reverted 1-arg source would have silently shifted arguments instead of reproducing the real attack; this was caught and corrected rather than reported as a false "fixed" result.

Independent adversarial verification (separate agent) found 2 more genuine gaps, one of which was fixed in this same pass. (1) Self-approval — fixed. submitAccessRequest never validated that a requester couldn't name themselves as approverActorId; combined with the newly-added reviewer-authority check's exact-match branch, a requester could submit-then-immediately-approve their own access request with zero independent review. Closed with a guard in submitAccessRequest itself, live-reproduced the same way as the CRITICAL items above. (2) Agent-elevation gate bypassable via role creation — flagged, not fixed, and correctly scoped as NOT a regression from today's work. createRole/cloneRoleFromTemplate create roles with requires_approval_for_agents=false by default (the schema default) and never set it explicitly; addPermissionToRole/wireBundleToRole never check the flag. A tenant admin who creates a fresh role and wires it the same permissions as an existing gated role, then assigns it directly to an agent, never trips the gate — because that role was never marked as needing it. This is judged to be an inherent property of the flag-based gate design (which predates this pass entirely — requires_approval_for_agents has always been a per-role, admin-set flag, not something derived from the sensitivity of the permissions wired to a role) rather than a bug in the specific assignRole/addGroupMember mechanism this pass was asked to fix. Logged to OPEN_ITEMS as a design question (should permission-sensitivity force gating regardless of a role's own flag?) rather than redesigned inline.

A second, independent investigation corrects the diagnosis of the #41 Drizzle now() item — recommend re-classifying it before further work. Item #6 of this task's own instructions asked to apply the entry-#41 fix pattern to 2 newly-claimed sites, getSubscription/listAnnouncements. Direct inspection first: neither method's raw sql fragment actually contains a now() call (getSubscription's fragment is a literal-value NOT IN (...); listAnnouncements' embeds a bind-worthy ${tenantId} value but no now()), and generating both methods' SQL via .toSQL() showed textually correct, properly-numbered bind parameters in both cases — no fix was applied to either, since there was nothing to fix. Chasing why the original 4-site claim wouldn't reproduce, either: hand-executing the exact flagged code shape from permission-engine.ts (a real INSERT'd role_assignment row, starts_at 60s in the past, ends_at null, then the identical and(eq(...), sql\... <= now()`)query) returned the correct row on the first and second attempt — no failure. Then, in the SAME session, running the fullapps/apitest suite surfaced 21 pre-existing failures (confirmed unrelated to today's diff viagit stash A/B testing) in exactly the methods entry #41 named (resolveEntitlements, plus checkSupportAccessin the same file) — but this time with a decisive new data point:SELECT now()against the local Supabase Postgres container versusDate.now() in the Node test process showed **a consistent, static ~51-second clock skew (Postgres behind Node), re-measured twice a minute apart with no growth** — not the "load-sensitive, ~1-in-8" intermittent race entry #41's own sibling OPEN_ITEMS row (identity-governance.spec.tsD3) had attributed to concurrent-worker scheduling contention. Every one of the 21 failing tests uses aDate.now() ± 1000ms-scale time margin (e.g. startsAt: new Date(Date.now() - 1000)); a 51-second skew comfortably explains all of them without invoking any Drizzle SQL-composition defect, while also explaining why generous-margin reproductions (this entry's assignRole`-based test, and presumably entry #41's own original bisection, which likely also used tight margins) come out clean or wrong depending on margin width, not on the specific bind-param/raw-fragment shape. Not conclusively disproven — a genuine Drizzle bug could still coexist with the clock skew — but the balance of evidence now favors "local dev container clock drift" over "Drizzle SQL-compiler bind-param bug" as the primary cause. Recommend, before any further time is spent on a Drizzle-side fix: sync/restart the local Postgres container's clock and re-run the full suite; if the 21 failures disappear, close entry #41's finding as a misdiagnosed environment artifact rather than a code defect, and separately harden the affected tests' time margins as routine flake-proofing.

Testing. 28 new regression tests across 3 new spec files (identity-tenant-isolation.spec.ts — 6, identity-tenant-isolation-2.spec.ts — 12, platform-tenant-isolation.spec.ts — 6, plus the self-approval addition — 1, for 25 new plus prior existing counts reconciled to 789 total suite tests, up from 766 at entry #41's own close). Full apps/api suite: 769 passed, 21 pre-existing failures (all pre-dating this pass, all attributable to the clock-skew finding above, all confirmed unrelated to today's diff via stash A/B testing), 0 new failures introduced. tsc --noEmit: clean (same 3 pre-existing, unrelated inventory/pricing test-file errors as every prior entry).

Confirm: 32 real cross-tenant/authorization bugs closed across both service files (2 Critical tenant-isolation, 1 additional Critical self-approval, 4 High tenant-isolation named + 24 sweep-found, 1 High agent-elevation-gate bypass, plus 5 Medium/Low misc fixes and 1 genuine orphan removed — see docs/open-items/OPEN_ITEMS.md for the full row-level breakdown), every Critical/High fix independently live-reproduced (not just unit-tested), zero regressions, one adjacent design gap (role-creation-time gate bypass) correctly identified as out-of-scope-for-this-pass rather than silently ignored, and one prior entry's root-cause diagnosis (#41's Drizzle bug) meaningfully corrected with new, stronger evidence rather than blindly propagated.

43. Senior-Review Fix Pass on apps/api — Money Atomicity + Transactions, Structural Tenant-Isolation Sweep (Write Layer), Pagination, SoD Perf, NestJS Standards (2026-07-09)

Decided: 2026-07-09, model claude-fable-5. Application-layer only, no schema change. This is the fix pass for a second senior code review of apps/api (saved at ~/Downloads/apps-api-senior-review-2026-07-08.md), ordered by severity. It is the sequel to entry #42's tenant-isolation sweep — #42 closed the read-layer bare-ID lookups; this closes money atomicity, the WRITE-layer tenant-owned-entity references, and a set of non-security correctness/standards items. Every money and security fix was live-reproduced via git stash A/B (bug/attack succeeds pre-fix, is rejected post-fix), not just unit-tested against the fixed code.

Part 1 — money/state correctness (highest). (1) consumeAiCredit was a read-compute-in-JS-write-absolute sequence — two concurrent consumes both read the same balance and the second's absolute write clobbered the first (lost-update double-spend). Replaced with a single transaction doing an atomic guarded RELATIVE update (balance_cents = balance_cents - :amt with the spend-limit floor enforced inside the same UPDATE's WHERE via RETURNING), deriving balance_after_cents from the actual post-update value, not a stale read. Live-reproduced: old code under 10 concurrent 10¢ consumes on a 1000¢ balance settled at 980¢ (8 debits lost); new code settles at exactly 900¢, ledger has 10 rows. (2) Every multi-write money/state mutation is now wrapped in one Drizzle transaction so a mid-sequence failure leaves NO partial state — consumeAiCredit, grantAiCredit/purchaseAiCredit (atomic upsert + ledger insert), recordPaymentFailure, transitionTenantState (extracted a private _transitionTenantState(exec, …) so sub-steps fold into the caller's tx, with a TOCTOU status-guard), processDunning, recoverDunning, provisionTenant. Live-reproduced: recordPaymentFailure on a suspended tenant (whose suspended→past_due transition is illegal) left subscription.dunning_status='retrying' under the old code; under the new code the illegal transition rolls the whole op back and dunning_status stays NULL. (3) applyPromoCode redemption-cap enforcement moved into an atomic conditional UPDATE (WHERE is_active AND (max_redemptions IS NULL OR redemption_count < max_redemptions) + RETURNING), throwing on zero rows — closing the read-then-increment TOCTOU that let the cap be exceeded under concurrency. 5 regression tests (platform-money-atomicity.spec.ts), all green.

Part 2 — structural WRITE-layer tenant-isolation sweep (not enumeration). Re-swept BOTH services for every method that INSERTs/UPDATEs a row referencing a caller-supplied, tenant-owned entity ID without first verifying that entity's tenant_id matches the caller's. Fixed: (4) assignRole — a group (actorGroupId) from tenant B could receive a tenant-A role assignment; added a group-tenant ownership check. (5) createApiKey — a service account from another tenant could have a live API key (whose verifyApiKey returns THAT row's tenant_id) minted against it; added an SA-tenant check. (6) assignSkillToAgent — a foreign agent could get a skill assignment stamped with the caller's tenant, which (pre the Part 3 fix) the tenant-blind skill check would then honor; added an agent-tenant check. (7) self-approval via the no-designated-approver path — submitAccessRequest allowed naming yourself as approver, or (with the reviewer-authority check added in #42) submitting then self-approving; added a requester≠reviewer guard in assertReviewerAuthorized (now takes requesterActorId) and a self-approver guard in submitAccessRequest. (8) submitAccessRequest foreign requestedRoleId — a request could be created naming another tenant's role; rejected at submit. (9) new sweep-find: assignUserToSite never checked that the target multi_loc.site (or optional siteRoleId) belonged to the user's tenant; added both checks. All 7 fixes live-reproduced via a single A/B pass (identity-tenant-isolation-3.spec.ts, 7 tests): every attack succeeds against the stashed pre-fix code (7 failed) and is rejected post-fix (7 passed). The platform.service.ts insert-by-DTO-tenantId methods (recordInvoice, recordPayment, grantEntitlementOverride, createContract, recordAcceptance, recordUsageSummary, recordOperatorAction, writeInternalActivity) are a DIFFERENT class — they trust a tenantId field IN the DTO rather than cross-checking a referenced entity — and are deliberately deferred to the write-controller wiring (they must derive tenant from the authenticated actor, not the DTO), logged to OPEN_ITEMS with that trigger.

Part 3 — defense-in-depth in the resolution engine. (10) permission-engine.ts Step 2 group-membership resolution now filters both actor_group.tenant_id and actor_group_member.tenant_id by the caller's tenant — so a cross-tenant group grant can't be silently honored even if a row slipped past the write layer. (11) authorizeAgentAction's skill half now filters agent_skill_assignment.tenant_id, matching the (already tenant-scoped) permission half — a skill assignment written under another tenant no longer satisfies the competency gate. (11) is directly covered by isolation-3 test 3.11 (A/B proven).

Part 4 — pagination. Introduced a shared common/pagination.ts (pageLimit/pageOffset, clamped to [1,200] default 50; non-finite/negative inputs degrade to safe defaults, never a 500). Applied offset/limit + a stable secondary sort key (the table PK as tiebreaker, so pagination is deterministic under same-timestamp ties) to every list* method — 22 in PlatformService, 19 in IdentityService. The append-only operator audit log got keyset (cursor) pagination instead — listOperatorAudit(tenantId?, { limit, cursor }) returns { items, nextCursor }, ordering created_at DESC, id DESC (id is a time-ordered uuidv7 → total order, no ties), with the next page fetched via a row-value < comparison on the (created_at, id) tuple; offset pagination degrades on an unbounded ledger (deep offsets scan-and-discard, concurrent inserts shift the window). The admin-ops.controller.ts audit-log route and the apps/web/admin/lib/api.ts client wrapper were updated to the new {items,nextCursor} shape. 3 regression tests (platform-pagination.spec.ts) — offset disjointness + limit-ceiling clamp + a full keyset walk proving every row is seen exactly once, newest-first, terminating on the last partial page — all green.

Part 5 — performance. (13) sweepTenantSod's per-actor detectSodViolations call re-loaded the entire global sod_rule catalog + its sod_rule_permission map from the DB on EVERY actor (an N+1 over the sweep). Extracted a loadActiveSodRuleContext() helper; the sweep now loads that catalog ONCE and threads it into every per-actor call — a per-actor N+1 collapses to 2 fixed queries for the whole sweep. (14) detectSodViolations did two per-matched-rule SELECTs inside its loop (waiver-check + open-violation-check); replaced with ONE batched SELECT loading every open/waived violation for the (tenant, actor) across all matched rules up front, keyed into a map. Behavior is identical (waiver-precedence, at-most-one-open, re-detection last_detected_at refresh all preserved) — verified by the identity-governance.spec.ts SoD tests being unchanged in pass/fail before vs. after the refactor.

Part 6 — NestJS standards. (15) 49 bare throw new Error(...) across both services (1 platform, 48 identity) → semantically-correct NestJS exceptions preserving the exact message (NotFoundException ×28, BadRequestException ×17, ForbiddenException ×6) — so they surface as 404/400/403 instead of an opaque 500. (16) 11 as any casts on insert .values({...}) enum fields → precise column-union / $inferInsert-derived types; 12 accumulator-pattern whole-object as any casts (dynamically-built Record<string,unknown> update objects) deliberately LEFT — converting them requires reshaping the accumulator and is not behavior-neutral, so per the correctness-over-completeness rule they stand (1 inet-column raw-string cast in identity likewise left). (17) main.ts hardening: a global AllExceptionsFilter (unknown errors logged server-side, returned as an opaque 500; HttpExceptions pass through), enableShutdownHooks(), and bootstrap().catch(→ exit 1). CORS + setGlobalPrefix are wired but env-gated OFF (API_CORS_ORIGINS/API_GLOBAL_PREFIX) because the app is currently server-to-server only (the Next.js admin app fetches it from its own server with a bearer token — no browser origin, no /api prefix; enabling the prefix now would break the wired admin pages); helmet is deferred (not installed). Trigger logged to OPEN_ITEMS. (18) cleanup: removed the dead tenantDB import from platform.service.ts, refreshed the stale "will switch to tenantDB when controllers arrive (step 11)" class comment to reflect current reality, and logged the IdentityController empty-@Controller() path-grafting as an OPEN_ITEM.

Verification. All money + security fixes live-reproduced via git stash A/B (Part 1: money atomicity + transactional rollback; Parts 2/3: all 7 tenant-isolation/authz fixes, 7-failed-pre / 7-passed-post in one pass). Concurrency fix (consumeAiCredit) proven under actual Promise.allSettled concurrent execution. An independent adversarial agent re-derived the write-layer tenant-owned-entity sweep from scratch across both services + permission-engine.ts (findings folded in). tsc --noEmit: clean except the same 3 pre-existing, unrelated inventory/pricing test-file errors as every prior entry. Full apps/api suite: 785 passed, 20 failed across 4 suites, 0 regressions — the money/security/pagination specs are all green; the 20 failures are the documented static-~51s-Node↔Postgres-clock-skew flakes (OPEN_ITEMS #252/#41 — resolvePermissions/resolveEntitlements/checkSupportAccess time-window comparisons in identity-crud/identity-machine/identity-governance/platform-billing; confirmed unrelated by reproducing on clean HEAD with both identity files reverted), NOT regressions from this pass. Two admin-ops.spec.ts HTTP tests that asserted the audit-log response was a bare array were updated to the new {items,nextCursor} keyset shape (a real, intended consequence of Part 4, not a flake). The container clock was NOT synced this session, so the clock-skew flakes persist unchanged.

Confirm: money mutations are atomic + transactional (no lost-update double-spend, no partial state on mid-sequence failure); write-layer tenant isolation closed structurally (every caller-supplied tenant-owned entity ID is ownership-checked before a write, or its deferral is logged with a trigger); all list* endpoints paginate (offset+tiebreaker, keyset for the audit ledger); standards clean (typed exceptions, hardened bootstrap, dead code removed).

44. approvals — New Module, Consolidating the Tenant-Side Approval Engine Out of Admin (Reverses #34 Section 5)

Decided: 2026-07-09. Designed (with two independent adversarial verification passes folded into the design document itself before any build started — see below), built, migrated, tested, and self-audited the same day. This is a new module — the first table set in this codebase to move out of an already-locked module into a module that didn't exist yet, rather than into an existing one (every prior move, admin.tenant_business_profile → platform.tenant_profile, entries #34/#35, relocated columns into a destination that already existed). approvals is a central, cross-cutting tenant-side approval-workflow engine: 8 tables, 97 columns, consolidating the 3 tables Admin owned (approval_workflow, approval_routing_rule, approval_request) and generalizing them so any module can route a business-process approval through the same mechanism instead of building its own. Design proposal: ~/Downloads/vrida-approvals-module-design-proposal-2026-07-09.md (summarized throughout this entry, not re-derived).

Schema files: packages/db/src/schema/approvals/{_schema,workflow,request,delivery,index}.ts. Migration: packages/db/migrations/20260709070000_approvals_module.sql (hand-written, applied live). Tests: apps/api/src/approvals/__tests__/approvals-schema.spec.ts — 22 tests, all passing.

What moved, what's net-new — 8 tables / 97 columns

Table Status Cols Notes
approval_workflow MOVED from admin (10→12) 12 +2: step_mode (CHECK sequential/parallel/conditional, default sequential), blocks_agent_approver (boolean NOT NULL DEFAULT false — the C8 boundary anchor, column-write-locked). workflow_type's old CHECK (4 hardcoded business-process names) REMOVED — free text now, since a fixed vocabulary baked domain knowledge into the engine's own schema.
approval_routing_rule MOVED from admin (11→11) 11 Unchanged shape; workflow_type CHECK removed to match approval_workflow.
approval_policy NET-NEW 10 Self-approval & SoD configuration: workflow_type nullable (NULL = tenant-wide default), allow_self_approval (declared intent only, never overrides the hard DB guards), min_distinct_approvers (now DB-enforced, see guards below), require_role_separation (service-layer-only, disclosed as such), escalation_timeout_minutes. 2-partial-unique-index pattern, mirroring admin.tenant_setting's own precedent.
approval_request MOVED from admin + extended (18→20) 20 +2 net, not the +4 a naive "extended" read would suggest: −1 (step_history JSON DROPPED, superseded by the queryable approval_step table) + 3 (initiator_is_agent, escalated_at, expires_at). requested_by_actor_id RENAMED initiator_actor_id and made NOT NULL (was nullable — the root cause of a null-approver bypass, see guards below). source_module CHECK widened 4→8 values. source_type's planned CHECK-enumerated pairing was REMOVED — stays free text (see Boundary-Integrity Scan below). New presence CHECK chk_approval_request_resolved_requires_actor_at.
approval_step NET-NEW 14 Per-request step instance, replacing the dropped step_history JSON with a queryable table. resolution_mode (all_must_approve vs any_one_resolves) distinguishes AND-parallel quorum from OR-fan-out groups sharing a step_index. condition (jsonb) snapshots the workflow's step definition at creation — editing a workflow later must never retroactively change an in-flight approval. 3 triggers (see guards below).
approval_delivery NET-NEW 12 Outbound approver notifications (channel email/in_app/sms, status pending/sent/delivered/opened/failed). Not a duplicate of platform.outbox (different audience — domain-facing state-change events vs. human-facing notifications). Is a disclosed, deliberate, temporary duplication of a slice of the not-yet-built notifications module's own planned scope (docs/modules/MODULE_INDEX.md already lists an 11-table/166-col Notifications module) — logged to OPEN_ITEMS with a reconciliation trigger, not silently carried.
approval_token NET-NEW 10 One-click approve/reject tokens, security-critical. token_hash only (SHA-256 of a ≥256-bit CSPRNG value, mirroring admin.api_key's hash-only convention), expires_at (72hr default), used_at, superseded_at (NEW — closes a sibling-token replay gap). Redemption is one atomic UPDATE ... WHERE used_at IS NULL AND superseded_at IS NULL AND expires_at > now(), folding all three conditions together to close a TOCTOU race a simpler predicate would leave open. Token redemption runs via a service-role connection deriving tenant scope from the matched row — the same RLS-bypass precedent as identity.service_account/api_key's own auth handshake; the identical gap sits unaddressed today in identity.invitation, closed here instead of reproduced.
approval_event NET-NEW 8 Append-only audit log. PK default platform.uuid_generate_v7() (Remediation Phase 2's rule for genuinely append-only tables). Reuses platform.reject_append_only_mutation() (already defined, already consumed by 9 tables/6 schemas) rather than reimplementing it.

Consumer contract, briefly (full shape in the design proposal, not re-derived here): any domain calls requestApproval({ module, type, ref, workflowType, amount?, context, initiatorActorId, initiatorIsAgent }) without the engine ever knowing what a PO, refund, or customer merge is. Resolution is a dual push/pull contract — push via platform.outbox (best-effort; outbox has zero dispatcher anywhere in this codebase today, a pre-existing gap) and pull via a documented read-model query (the load-bearing fallback until a dispatcher exists). Three AI/agent roles are modeled separately: (1) agent-as-requester — wire-capable now; (2) agent-as-approver-assistant (advisory-only, logged as an approval_event, never touches approval_step.decision) — wire-capable now; (3) agent-as-approver (auto-approve) — designed, gated by blocks_agent_approver + a live agent_duty_grant, but NOT wired this pass.

Reversal of #34 Section 5 — Option B

Entry #34 Section 5 decided, as "Option B": "Admin's generic tenant-side approval engine (approval_workflow/approval_routing_rule/approval_request) stays tenant-scoped, tenant-RLS, serving tenant-internal business-process approvals (PO/discount/refund) — designed so purchasing/pricing/payments' own tenant-side approval needs can route through this same engine going forward." That decision is reversed here, explicitly. Recorded honestly, not as "Option B was wrong": it was a reasonable call at the time — the only fork actually evaluated in 2026-07-07 was "does this fit Admin's RLS/reviewer-identity model" (yes), never "does this fit Admin's ownership model" (a cross-cutting engine other modules write into is a different kind of thing than tenant-config Admin owns and no one else touches).

What changed the calculus is new decision-input that didn't exist when #34/#36 were written: a 2026-07-09 codebase-wide 81-mechanism sweep found the engine had zero real consumers as of that reading (admin-schema-spec-test-only), and that purchasing — the one module with a live, analogous need — built its own entirely separate, disconnected mechanism (purchase_order.approval_status) rather than adopt the "shared" one. That's direct evidence the shared-mechanism framing never actually took hold while the engine sat inside Admin. The sweep's own tally was corrected during design verification from an initial 14 down to 13 other business-process-approval candidates across 6 modules (17 nominal "yes" mechanisms found, minus 1 double-count — identity.role.requires_approval_for_agents is the same engine as identity.access_request, not a second mechanism — minus the 3 tables already inside Admin itself). Entry #34's other four sections are untouched: re-read #34 in full during design verification and confirmed the reversal is scoped only to Section 5 — the tenant-identity absorption into platform.tenant_profile, the EIN vault-reference fix, and the 17-column tenant_business_profile fate mapping all stand exactly as recorded. platform.contract's own separate Vrida-operator review gate also stands untouched — a different plane (operator-reviewed control-plane data), never a candidate for this engine, and this design doesn't change that either.

A validating (but not blank-check) precedent, cited honestly. docs/database/schema_docs/identity.md's access_request section (DR-22) already reserves a nullable workflow_id FK to a not-yet-built approval_workflow/approval_step engine — genuine corroboration that the general direction (a dedicated step-tracking table, that exact name) is sound. But DR-22 explicitly rejected building this now for being premature for Vrida's SMB target market, and its own envisioned shape (a direct FK straight onto access_request, tenant_id nullable for Vrida-shipped global templates) is a materially thinner, differently-attached design than the 8-table, always-tenant-scoped engine built here. The 81-mechanism sweep — 17 real mechanisms across 8 modules, not the single-module case DR-22 was evaluating — is the actual justification for building now, not DR-22's own (rejected) conclusion. Two real gaps this creates, both logged to OPEN_ITEMS rather than glossed over: DR-22's direct-FK attachment shape doesn't match this engine's polymorphic source_ref contract (a real re-architecture, not a drop-in, if identity.access_request ever converges); and DR-22's global/mixed-scope template intent (tenant_id nullable) isn't representable under this design's blanket tenant_id NOT NULL rule.

Admin Reopen Delta

Following the same 4-block reopen-delta format entry #36 used for Admin's own last reopen.

Block 1 — Delta Summary. Admin: 13 tables / 161 cols → 10 tables / 122 cols (−3 tables, −39 cols).

Table Before After Δ
approval_workflow 10 — (MOVED to approvals) −10
approval_routing_rule 11 — (MOVED to approvals) −11
approval_request 18 — (MOVED to approvals) −18
tenant_branding, compliance_document, tenant_setting, setting_definition, hardware_device, integration_config, integration_provider_catalog, webhook_config, api_key, custom_field_definition (10 tables) 122 122 0
Total 161 122 −39

122 matches 161 minus 39 exactly. All 3 moved tables land in approvals (see the table above) rather than being dropped or consolidated — this is a boundary correction, not a schema-consolidation decision internal to Admin, the same category distinction entry #36's own Block 2 drew for the tenant_business_profile move. Admin's "Groups:" line drops its "Tenant-Side Approval Engine" concern-group entirely — down to 3 groups: Presentational / Technical-Operational Config / Tenant Extensibility.

Block 2 — Boundary Justification. Admin's own governing character (per #34: "the tenant's own TECHNICAL/OPERATIONAL configuration") never actually described a cross-cutting, multi-consumer workflow engine — see the Reversal section above for the full reasoning (the 81-mechanism sweep, corrected to 13 candidate mechanisms across 6 other modules, is the new fact; zero real consumers of the engine while it sat in Admin is the evidence). A tenant-config module that 6+ other modules must eventually write into is no longer "tenant configuration" in the sense every other Admin table is.

Block 3 — Full Table Fate.

Table Fate Notes
approval_workflow MOVED → approvals.approval_workflow +2 cols (step_mode, blocks_agent_approver); workflow_type CHECK removed
approval_routing_rule MOVED → approvals.approval_routing_rule Unchanged shape
approval_request MOVED → approvals.approval_request 18→20 cols, +2 net; requested_by_actor_id renamed initiator_actor_id (now NOT NULL); source_module CHECK widened; source_type CHECK removed; new presence CHECK
Remaining 10 Admin tables UNCHANGED tenant_branding, compliance_document, tenant_setting, setting_definition, hardware_device, integration_config, integration_provider_catalog, webhook_config, api_key, custom_field_definition

Block 4 — Dependency-Blocked Register. The design's own verification pass found real, substantive stale references that go stale the moment these 3 tables move — an initial claim of "zero cross-references need updating" (citing a non-existent docs/database/CROSS_MODULE_CONTRACTS.md path) was independently found wrong by 3 separate verification lenses during design. The real file is docs/modules/CROSS_MODULE_CONTRACTS.md:

  • ~line 212 — Admin's actor-attribution retarget list, naming approval_request columns (only requested_by_actor_id → initiator_actor_id renames; resolved_by_actor_id is unchanged).
  • ~line 222 — a dedicated contract-table row, Identity → Admin | ... approval_request.requested_by_actor_id/.resolved_by_actor_id → identity.actor.id, stale on both the column name and the owning module.
  • ~line 227 — a dedicated paragraph documenting Option B and stating the engine "stays Admin-internal" — directly contradicted by this move.
  • ~line 479 — Admin's owned-surfaces summary, listing "the tenant-side approval engine" as part of Admin's config.
  • Also docs/database/schema_docs/admin.md ~line 469 makes the identical Admin-internal/Option-B distinction and goes stale the same way.

This entry does not itself edit those two files — that correction is scoped to the same documentation fan-out pass this entry is part of (a parallel doc-writing stream covering CROSS_MODULE_CONTRACTS.md, admin.md, MODULE_INDEX.md, OPEN_ITEMS.md, DOCS_INDEX.md, CLAUDE.md). Recorded here as a Block 4 register item, per entry #36's own precedent, not asserted away.

admin's schema-locked figure after this reopen: 10 tables / 122 cols.

Boundary-Integrity Scan — the domain-knowledge leak, and a second one caught by verification

The engine's job is to know nothing domain-specific. The existing admin.approval_workflow.workflow_type CHECK (po_approval/discount_approval/refund_approval/other) baked 3 business-process names directly into the engine's own schema — resolved by making workflow_type plain text, uniqueness still enforced via the existing partial-unique indexes, just not a fixed vocabulary. A second, initially-unaddressed instance of the identical leak was in the original draft's source_type design (CHECK-enumerated, cross-column-paired with source_module) — independent verification (2 separate lenses, converging) found this was a genuinely NEW coupling, not a preserved one (the live admin.approval_request has zero CHECK on source_type today), and a finer-grained one than source_module would ever be: purchasing alone has 3 separate OPEN_ITEMS convergence candidates that would each need their own pairing-CHECK entry. Fixed the same way as workflow_type: source_type is free text, validated at the service layer, not by a DB CHECK. source_module stays CHECK-enumerated (structural — which of 8 known schemas a UUID points into, a coarse and rarely-widened vocabulary, unlike a record-type string within an already-valid module).

The 6 critical guards — all live-reproduced against the live local Supabase Postgres DB (127.0.0.1:54322)

  1. Approved-by-nobody — chk_approval_request_resolved_requires_actor_at. Live-reproduced: with the constraint and the initiator NOT NULL both temporarily dropped, an INSERT with status='approved', resolver NULL, and zero approval_step rows SUCCEEDED (the bug); restored, the identical attempt now fails at INSERT time (NOT NULL) and via the presence CHECK.
  2. Self-approval, all paths — chk_approval_request_resolver_not_initiator + trg_approval_step_no_self_approval. Live-reproduced 3 sub-cases: header self-approval rejected; self-approval on a non-final step (step 1 of a 2-step chain) rejected; the null-approver path (zero steps ever created, initiator tries to self-resolve the header) rejected.
  3. Parallel-step quorum-spoofing — trg_approval_step_distinct_approvers. Live-reproduced: the same actor deciding 2 sibling parallel steps (same step_index, min_distinct_approvers=2) rejected on the second attempt; a genuinely different actor succeeds.
  4. C8 agent-money-boundary — trg_approval_step_blocks_agent_approver + a column write-lock on blocks_agent_approver. Live-reproduced: an agent-type actor resolving a step on a blocks_agent_approver=true workflow rejected; the same step resolved by a human succeeds. A third bug, found live during THIS build (not by the earlier design-verification agents, which had only asserted the column was "write-protected"): the first-attempt REVOKE UPDATE (blocks_agent_approver) FROM authenticated did not actually restrict anything, because Postgres column-level ACLs are additive against a broader table-level GRANT UPDATE already covering the same privilege — confirmed via information_schema.column_privileges and a live UPDATE that unexpectedly succeeded. Fixed: REVOKE the table-level UPDATE entirely, re-GRANT column-by-column on every column except blocks_agent_approver. Re-tested live: the flip attempt now fails with "permission denied for table approval_workflow"; an ordinary column (description) on the same table remains writable by the same role. This is the same lesson entry #37's own Remediation Phase 1 already had to learn once for a different table — recorded here as its second live occurrence, not a novel discovery.
  5. Token security — hash-only storage, atomic single-use (used_at/superseded_at/expires_at folded into one UPDATE ... WHERE), sibling-supersession triggers. Live-reproduced: first redemption succeeds; replay of the same token rejected (0 rows updated); issuing a 2nd token for the same (step, actor, action) supersedes the older one, which can then no longer be redeemed; an expired token is rejected by the combined atomic predicate.
  6. Append-only audit — approval_event, REVOKE + platform.reject_append_only_mutation() reuse. Live-reproduced: both UPDATE and DELETE against approval_event rejected, even as the postgres superuser — the trigger blocks every role, not just authenticated.

NULL-in-CHECK sweep

All 13 CHECK constraints in the approvals schema were examined for the Postgres FALSE OR NULL = NULL bypass class this codebase has hit before (chk_purchase_order_sent_requires_approval). Every CHECK-guarded enum/threshold column (channel, status, event_type, min_distinct_approvers, source_module, action, resolution_mode, step_mode — 8 columns, confirmed NOT NULL via information_schema) has no NULL-bypass surface at all. The 2 CHECKs on legitimately-nullable columns (chk_approval_request_resolver_not_initiator on resolved_by_actor_id; chk_approval_step_decision on decision) use NULL-safe IS NULL OR ... deliberately, matching intended semantics ("not yet resolved"/"not yet decided" are valid states), not a bypass. The one new presence CHECK (chk_approval_request_resolved_requires_actor_at) uses only NULL-safe predicates — never bare equality against a nullable column — confirmed NULL-safe by construction. Two trigger functions (trg_approval_step_distinct_approvers, trg_approval_step_blocks_agent_approver) rely on FK+NOT-NULL-enforced referential integrity to guarantee certain looked-up values are non-NULL, rather than being self-contained NULL-safe in total isolation — a legitimate design given Postgres's own FK guarantees, disclosed rather than silently assumed.

Section 4 self-audit (builder's own pass — independent re-derivation still pending, see closing note)

Items A–P plus T and U all PASS or N/A, zero FAILs. Three minor GAPs logged, none blocking: (1) approval_step.condition lacks a concrete example JSONB shape in the schema doc — fix opportunistically (e.g. {"amount_cents_gt": 500000}); (2) no index yet on approval_request.expires_at/approval_token.expires_at for a future escalation/expiry-sweep job — deferred, matching this codebase's own "add this index when the alerting query is defined" precedent; (3) no CHECK enforcing step_mode/resolution_mode semantic consistency (resolution_mode is only meaningful when step_mode='parallel') — deferred until real step-creation logic exists and the production shape is known.

Design-Phase Integrity blocks — summary of the design proposal's own record

The design document (cited above) carries all 4 mandatory blocks plus its own evidenced verification appendix, not re-derived here in full:

  • Prior-Decisions Scan — identifies the #34 Section 5 reversal explicitly (quoted above), confirms #34 Sections 1–4 untouched, and cites/critiques the DR-22 precedent honestly (including DR-22's own rejection of building this now, not just its validating half).
  • Reuse-First Scan — 9 existing mechanisms/conventions confirmed reused, never reimplemented: identity.actor (every actor-shaped column), identity.agent_duty_grant (read-only authority-ceiling dependency), platform.outbox (push channel), the tax/billing source_ref polymorphic pattern (partially — see the Boundary-Integrity note above), platform.reject_append_only_mutation(), admin.api_key's hash-only convention, ai.agent_execution's snapshot-not-live-reference convention, Remediation Phase 4's additive-interim enum-widening precedent, and identity.check_tenant_user_actor_type()'s actor-type-aware trigger precedent. The one disclosed, deliberate exception: approval_delivery temporarily duplicates a slice of the not-yet-built notifications module's planned scope.
  • Boundary-Integrity Scan — the workflow_type/source_type domain-knowledge leaks (detailed above), confirmation that no table is domain policy in disguise, and a sharpened test (stated explicitly in the design doc, not merely a column-name heuristic) for telling a genuine business-process approval apart from one of the 41 autonomy review-seam tables: a seam table flags an already-effective write for post-hoc trust; a convergence candidate's row is the pending decision, gating an effect that hasn't happened yet.
  • Adversarial Pre-Mortem — 8 failure modes assessed (god-module creep, polymorphic-integrity loss, agent-moving-money, self-approval/null-approver, token security, circular dependency, outbox degradation, unconsumed-complexity risk), each with a stated mitigation; the design document's own revision note discloses that two independent adversarial re-verification passes (10 separate agents total across a 3-lens then a 7-lens pass) found 2 lens-level FAILs (the null-approver bypass and the unenforced blocks_agent_approver boundary) and 5 CONCERNs before the tables below were corrected in place — a revised proposal, not the original draft, went into this build.

Independent verification — pending, to be appended

This entry, as written, reflects the builder's own design-phase verification (folded into the cited design proposal) and this build's own Section 4 self-audit and live-reproduction evidence — it does not yet include a separate agent's independent post-build re-audit or an evidenced adversarial lock-gate verification. Both run as a later phase of this same workflow (following this codebase's established practice — see entry #36's own "Independent Post-Build Re-Audit" subsection for the precedent of pasting a separate agent's findings verbatim). Per that precedent, this entry will be updated with those findings once that phase completes, rather than the module being declared locked on the strength of this entry alone. docs/open-items/OPEN_ITEMS.md carries the 24 rows this module's design generated (convergence candidates, the notifications-module overlap, the proxy-self-approval residual limitation, the Role-3 enablement precondition, the outbox-dispatcher precondition, and 2 pre-existing gaps in billing/ai surfaced along the way) — logged in the same documentation pass as this entry, not restated here.

Confirm (pending the independent phase above): approvals built — 8 tables/97 cols, 6 critical guards live-reproduced with one new bug (the column-REVOKE/table-GRANT interaction) found and fixed during the build itself; Admin reopened, 13→10 tables/161→122 cols, the 3-table move fully accounted for; #34 Section 5 reversed with an honest account of why, #34 Sections 1–4 confirmed untouched.

45. identity.operator — Isolated Vrida-Operator Identity, Replacing the is_platform_user Overlay

Decided: 2026-07-09. Designed (Option A, 2 tables in identity — a read-only cleanup + design pass with a 5-lens adversarial verification folded in before any build started), then built, migrated, security-live-reproduced, and same-pass code-retargeted the same day. Design doc: ~/Downloads/vrida-operator-schema-design-and-cleanup-2026-07-09.md (the revised, post-verification version — summarized here, not re-derived). Replaces the prior model, where a Vrida operator (cross-tenant SaaS staff with admin-console access) was just an identity_user row with is_platform_user=true — structurally indistinguishable from a tenant employee to anything reading actor_type alone.

Schema file: packages/db/src/schema/identity/operator.ts. Migration: packages/db/migrations/20260709090000_identity_operator.sql (hand-written, applied live). identity is now 37 tables / 422 columns (up from 35/400 after Remediation Phase 3).

Part 1 — Cleanup (executed before design)

A live query found 176 identity_user rows with is_platform_user=true; 174 matched a randomized test-fixture email pattern traced to 7 spec files. The 2 real accounts — operator-3e2cefcb@vrida-test.local (created by admin-console-seed.ts) and admin@vrida.app (created by create-admin-user.ts during E2E login testing) — were both hard-deleted from Supabase Auth and soft-deleted in the DB (identity_user.deleted_at + identity.actor.deleted_at/status='deactivated'), per explicit user confirmation ("Delete both"). Soft-delete (not hard-delete) of the DB rows was a deliberate, disclosed deviation: both actors had dependent identity_session/identity_access_event rows FK'd with plain NO ACTION (no cascade), and this codebase treats that audit history as immutable.

Part 2 — The 2 tables

Table Cols Notes
identity.operator 14 Shared-PK detail table off identity.actor (id = actor.id, actor_type='operator') — mirrors service_account/agent_identity's own class-table-inheritance precedent, the closer, correct fit found by design-phase adversarial verification over inventing a new schema. Own local kill-switch (status/suspended_at/suspended_by_actor_id/suspension_reason, mirroring agent_identity's Remediation Phase 3 precedent) rather than reusing bare actor.status. No MFA/password columns — Supabase Auth owns both.
identity.operator_role_assignment 8 Mirrors identity.role_assignment's revocable-grant shape (status/assigned_at/assigned_by_actor_id/revoked_at/revoked_by_actor_id). role_code CHECK-enumerated (super_admin/admin/support) rather than a catalog table — design-phase adversarial verification cut 3 invented values (billing_ops/sales_ops/read_only); read_only actively collided with a differently-scoped, already-existing tenant-facing role of the same name in identity.role.

actor.actor_type CHECK widened: 'user'/'service_account'/'agent' → adds 'operator'. trg_tenant_user_actor_type_check (the pre-existing Batch C trigger rejecting any tenant_user row whose actor isn't actor_type='user') needed zero modification — 'operator' != 'user' was already rejected by it, live-reproduced rather than assumed.

Part 3 — Security backstop, live-reproduced

Both new tables get an explicit REVOKE SELECT, INSERT, UPDATE, DELETE ON identity.operator, identity.operator_role_assignment FROM authenticated (belt — closing the automatic ALTER DEFAULT PRIVILEGES grant every new table in this schema inherits, per Remediation Phase 1; this is not hypothetical, platform.operator_audit_log needed the identical fix after that same blanket grant, PROJECT_DECISIONS #37) plus ENABLE ROW LEVEL SECURITY with zero policies (suspenders — Postgres denies all rows to any non-superuser/non-owner role when RLS is enabled and no policy applies; no pgPolicy() exists for either table by design, and that absence IS the enforcement mechanism). All reads/writes go through getAdminDb(), never tenantDB()/authenticated.

Live-reproduced against the local Supabase Postgres DB (connected as the real authenticated role, not a simulation): SELECT on identity.operator → permission denied for table operator; INSERT on identity.operator → same; SELECT on identity.operator_role_assignment → permission denied for table operator_role_assignment. All three fail at the REVOKE layer before RLS is even reached, confirming the belt holds; the suspenders layer was independently proven during the design-verification pass (GRANT deliberately restored to simulate the exact failure mode the adversarial review warned about, RLS still blocked all rows).

Self-issue guard, mirroring agent_duty_grant's chk_agent_duty_grant_granted_by_required_and_distinct but NULL-safe (the agent_duty_grant precedent requires assigned_by_actor_id NOT NULL AND != grantee; here it's assigned_by_actor_id IS NULL OR assigned_by_actor_id != operator_id, since the bootstrap super_admin assignment genuinely has no prior assigner). Live-reproduced 3 sub-cases: an operator assigning a role to themselves (assigned_by_actor_id = operator_id) → REJECTED (chk_operator_role_assignment_no_self_issue); a distinct assigner → SUCCEEDS; assigned_by_actor_id = NULL (bootstrap) → SUCCEEDS.

Tenant-contamination guard, live-reproduced directly (not inferred from the trigger's own logic): inserting a tenant_user row whose actor_id points at an actor_type='operator' row → REJECTED by trg_tenant_user_actor_type_check with has actor_type='operator' — only actors with actor_type='user' may be tenant members.

Genuine non-operator login, live-reproduced end-to-end: a real Supabase Auth user + identity_user row (no identity.operator row) signs in, calls POST /admin/auth/login → 401 "No Vrida operator identity found for this auth user". This is a deliberate behavior change from the old model: previously any identity_user row (tenant or operator) would resolve and then fail the is_platform_user check, always yielding 403 for a non-operator; now a genuine non-operator has no operator row to find at all, correctly yielding 401. 403 is reserved for a real operator row whose status != 'active' (suspended/deactivated).

Part 4 — Same-pass code retargets (7 named + 3 found during the build, all landed together)

The 7 explicitly-scoped retargets: AdminAuthGuard.canActivate() → resolveActorFromAuthUser() (now queries identity.operator, returns {actorId, email, fullName, status} — dropped isPlatformUser); recordLogin()'s last_login_at UPDATE target; grantSupportAccess()'s validation (checks operator.status); listSupportAccessGrants()'s join (now identity.operator); getUser()'s return shape (dropped isPlatformUser); create-admin-user.ts's SELECT+INSERT; 7 test spec files' fixtures.

3 more found and fixed during this same build, all the identical bug class (a display-name/creation-path join still assuming operators live in identity_user): (1) platform.service.ts's listInternalActivityWithNames() joined only identityUser.full_name — silently returned null for any operator-performed tenant activity; fixed with a COALESCE across dual leftJoins (identityUser + operator). (2) admin-console-seed.ts's seedOperatorIdentity() still minted its seeded "Jordan Ellis" operator via identity_user/is_platform_user=true/actor_type='user' — invisible to the new AdminAuthGuard; retargeted to identity.operator/actor_type='operator', and its hardcoded Supabase Auth user ID (hard-deleted in Part 1's cleanup) re-minted fresh, set-local-operator-password.ts updated to match. (3) apps/web/admin/app/login/actions.ts's 403-handling copy assumed the old 401/403 semantics (403 = "not an operator") — under the new semantics a genuine non-operator now gets 401, so the specific "does not have Vrida operator access" message was firing for the wrong case (a suspended operator) while genuine non-operators saw a generic, unhelpful message; split into distinct 401/403 copy. Plus 4 stale is_platform_user-referencing code comments corrected (identity.controller.ts, lib/api.ts, operators/page.tsx, mockData.ts) — no behavior change, but left uncorrected they'd describe a security model that no longer exists.

identity_user.is_platform_user is NOT dropped this pass — still readable/writable, no longer read by any auth path — see OPEN_ITEMS for the drop-trigger.

End-to-end login proof

Real Supabase signInWithPassword (admin@vrida.app, recreated via the retargeted create-admin-user.ts after Part 1's cleanup) → POST /admin/auth/login (201, correct actorId resolved, identity_session row created) → GET /admin/support-access (200, real data via the retargeted join) → POST /admin/auth/logout (201, session ended). identity.operator.last_login_at and the session's ended_at both confirmed written in the DB. The "Jordan Ellis" seed operator (admin-console-seed.ts) was similarly recreated with a fresh, valid Supabase Auth ↔ identity.operator pairing.

Section 4 self-audit (builder's own pass — independent re-derivation still pending)

Items A–P, O, T, U all PASS or N/A against the live-built shape (column-for-column exact match against the approved design doc, zero drift on either table). Item T: zero new triggers introduced; the pre-existing trg_tenant_user_actor_type_check needed no modification, confirmed live. Items N/P (cross-reference locked decisions / module-level rationale) are closed by this entry and the accompanying docs fan-out, not a standing gap. One disclosed, intentional deviation from the design doc's own prose: the design doc's REVOKE list read INSERT, UPDATE, DELETE (3 verbs); the built migration REVOKEs SELECT, INSERT, UPDATE, DELETE (4 verbs) — the built artifact is stricter than the design doc's own text, not drift, since omitting SELECT would have left authenticated able to read all operator PII despite being blocked from writing it.

Creation path

create-admin-user.ts (dev/local, retargeted this pass) stays the dev-convenience path. OperatorService.createOperator() is recommended, not built this pass — a real production-safe creation path, gated behind super_admin, callable only via getAdminDb(). No write route/HTTP endpoint built this pass; logged to OPEN_ITEMS.

A note on test-suite clock skew

Live-reproducing the full apps/api suite during this build surfaced that the pre-existing, previously-disclosed clock-skew flake (OPEN_ITEMS rows 234/252 — a static skew between the local Node test process and the Supabase/Postgres dev container, historically ~51 seconds, affecting identity-crud/identity-governance/identity-machine/platform-billing) has grown substantially — a direct DB connection (bypassing all test code) measured roughly 8 hours of skew at the time of this build. This fully explains every one of identity-governance.spec.ts's 11 local failures (all are now()-relative time-window comparisons) and is confirmed environmental, not a regression: the full suite run (793/813 passing) shows exactly the same 4 pre-existing files failing, at the same total count, as the pre-build baseline recorded in this codebase's own history. No fix attempted this pass (an infra-level container-clock resync is outside this build's scope, and docker/colima inspection commands were unavailable in this environment) — logged to OPEN_ITEMS with an updated severity note reflecting the larger magnitude.

Independent verification — separate agent, evidenced (2026-07-09)

A separate agent, with no access to this entry or the builder's own narrative, independently re-derived the schema shape from a live DB connection, live-tested every guard itself (not by reading the builder's claims), swept the whole codebase for leftover is_platform_user auth-path references, and independently re-measured the clock skew rather than accepting the builder's number. Full findings, pasted verbatim:

  1. Schema shape — PASS. Live \d identity.operator (14 cols) / identity.operator_role_assignment (8 cols) match the migration file byte-for-byte — same columns, defaults, CHECKs, indexes. actor_actor_type_check live: CHECK (actor_type = ANY (ARRAY['user','service_account','agent','operator'])). No drift.
  2. Security backstop — PASS. Connected as authenticator → SET LOCAL ROLE authenticated; SELECT and INSERT on both tables → permission denied for table operator/operator_role_assignment (REVOKE fires first). Independently confirmed relrowsecurity=t, pg_policies returns 0 rows, information_schema.role_table_grants returns 0 rows for authenticated on both tables.
  3. Tenant-contamination guard — PASS. Inserting a tenant_user row with an actor_type='operator' actor_id rejected by trg_tenant_user_actor_type_check → identity.check_tenant_user_actor_type(), exact same message this entry already cites.
  4. Self-issue guard — PASS, all 3 sub-cases independently re-run: self-issue rejected (chk_operator_role_assignment_no_self_issue); distinct assigner succeeds; NULL assigner (bootstrap) succeeds. All transactions rolled back, zero residue confirmed.
  5. Code retarget completeness — PASS, one cosmetic nit. Full grep of apps/api/src + packages/db for is_platform_user/isPlatformUser found only: comments, the still-present (deliberately not dropped) identity_user.is_platform_user column, and a test-fixture parameter still named isPlatformUser that — verified by reading the fixture — actually inserts real actor_type='operator' + identity.operator rows, not the old boolean. No production auth path reads/writes the boolean. AdminAuthGuard resolves exclusively via resolveActorFromAuthUser, zero fallback to identity_user.
  6. 401/403 logic — PASS, traced code directly (not comments): resolveActorFromAuthUser returns null if no identity.operator row exists → guard throws 401; a real row with status !== 'active' → guard throws 403.
  7. Admin login — PASS (structural). Server was already live; GET /admin/tenants with no token → 401 (guard actively enforcing). Confirmed a real seeded operator (admin@vrida.app, status='active') exists. Full JWT→guard→controller path traced code-side. login/actions.ts correctly branches 401 vs 403 copy.
  8. Regression check — PASS. tsc --noEmit: exactly the 3 pre-existing, unrelated errors, nothing new. 6 of 7 named test suites pass; identity-governance.spec.ts has exactly 11 failures, all time-window-dependent. Independently re-measured clock skew (not trusting the builder's number): DB now() = 2026-07-09T20:52:03Z vs. Node Date.now() = 2026-07-10T04:49:05Z — ~7h57m, confirming the magnitude claim as real, not hand-waved.
  9. Docs consistency — PASS. Independently queried live DB: information_schema.tables/.columns for schema identity → 37 tables / 422 columns, matching schema_docs/identity.md's stated totals exactly; column counts (14/8) and the actor_type CHECK values also match the doc precisely.

Overall verdict: SAFE TO LOCK. Every claimed guard independently reproduced and holds; the only failing tests are the pre-disclosed, independently-reconfirmed clock-skew failures (isolated to identity-governance.spec.ts), not a regression from this build; zero new typecheck errors; docs match the live DB exactly on every spot-checked number. The one cosmetic nit (a test fixture parameter still named isPlatformUser despite inserting real operator rows) is not functionally significant and does not block the lock gate.

Identity is re-locked on the strength of this independent verification, following this codebase's own established gate (entries #36/#44's precedent).

46. pos Reopen — Header/Line Remediation Fix #8 (sale_refund_line Append-Only Enforcement)

Decided: 2026-07-10. First of 3 reopens (POS → Purchasing → Platform, per the recommended sequence) executing the coordinated, 6-module "Header/Line Remediation" design (~/Downloads/vrida-header-line-remediation-design-2026-07-10.md, itself based on vrida-header-line-pattern-audit-2026-07-10.md) — a systemic sweep for missing header/line reconciliation, unenforced immutability claims, and bare (non-composite) cross-tenant FKs across the codebase, already run through an independent adversarial verification pass (3 separate agents) before any of it was built. This reopen carries only §6b of that design — POS's own fix #8 plus 2 bundled additions. Purchasing and Platform are separate, later reopens under the same effort, not detailed in this entry.

The bug — documented-but-unenforced immutability. pos.sale_refund_line was documented, since its original build (PROJECT_DECISIONS #27), as "write-once, no updated_at, no deleted_at" — but unlike its sibling pos.sale_line, which Remediation Phase 1's cross-schema append-only sweep (20260708140000_phase1_append_only_ledgers.sql) actually covered, sale_refund_line was never included in that migration. Live-reproduced pre-fix: a plain UPDATE and a DELETE against an existing sale_refund_line row both succeeded with zero error — the documented invariant had no DB teeth at all.

The fix. REVOKE UPDATE, DELETE ON pos.sale_refund_line FROM authenticated + a new trigger, trg_sale_refund_line_append_only, reusing platform.reject_append_only_mutation() verbatim — zero new PL/pgSQL, matching sale_line's own Phase 1 precedent exactly (belt-and-suspenders: the REVOKE stops authenticated; the BEFORE trigger stops every role, including a service_role/superuser bypass connection, since a BEFORE trigger fires regardless of who owns the write). Live-reproduced post-fix: the identical UPDATE/DELETE are now rejected with an append-only error.

2 bundled additions, not part of fix #8 itself, taken because POS was already reopened:

  1. Prerequisite for fix #6 (orders.order_line.sale_line_id → pos.sale_line, DEFERRED, not built this pass): pos.sale_line gained UNIQUE (id, tenant_id) (sale_line_id_tenant_id_unique) — confirmed missing by independent verification (design §7 finding V1), not assumed. Free to add (sale_line's PK on id alone already guarantees uniqueness); costs nothing today, and unblocks fix #6 whenever it's picked back up.
  2. Opportunistic fix (design §7 finding V2-1, found during adversarial verification of the design itself, not one of the original 14 fixes): pos.sale_refund_line.sale_line_id was itself a bare, non-composite FK to pos.sale_line — the exact cross-tenant-exposure bug class this whole remediation effort exists to close. Upgraded to composite: FOREIGN KEY (sale_line_id, tenant_id) REFERENCES pos.sale_line (id, tenant_id) (constraint sale_refund_line_sale_line_id_tenant_fkey, replacing the dropped bare sale_refund_line_sale_line_id_fkey). NULL sale_line_id (the no-receipt-refund path, Remediation Phase 3 Item 10) trivially satisfies a composite FK under Postgres's default MATCH SIMPLE — only a set, cross-tenant sale_line_id is rejected.

Direct precedent for bundling a parent UNIQUE(id, tenant_id) addition with a downstream composite-FK rewrite in one migration file: 20260709080000_approvals_fix_cross_tenant_fk.sql.

Migration: packages/db/migrations/20260710000000_headerline_pos_fix8.sql. Schema files: packages/db/src/schema/pos/sale.ts (saleLine gains the unique('sale_line_id_tenant_id_unique').on(t.id, t.tenant_id)), packages/db/src/schema/pos/payment.ts (saleRefundLine's FK converted from a bare .references() to a table-level composite foreignKey({...}), named sale_refund_line_sale_line_id_tenant_fkey).

No table added, no column added or removed — pos stays 10 tables / 160 columns; only constraints and 1 trigger changed.

Verification. Live-reproduced and test-confirmed, full apps/api suite green (816/816). Pre-fix: UPDATE/DELETE against sale_refund_line both succeeded. Post-fix: both rejected with an append-only error; a cross-tenant sale_line_id reference is now rejected by the new composite FK. New test coverage: apps/api/src/pos/__tests__/pos-schema.spec.ts (new sections L/M/N) plus a compatibility fix in apps/api/src/tax/__tests__/tax-schema.spec.ts (its own "K. Refund tax reversal" cleanup now tolerates the append-only rejection instead of assuming an unconditional DELETE would succeed).

Next. Purchasing and Platform reopen next, same effort, per the design doc's §8 recommended sequence — not detailed here; each will get its own PROJECT_DECISIONS entry when it lands.

47. purchasing Reopen — Header/Line Remediation Fixes #10, #12, #4 (Quantity-Rollup CHECK, Line_Number Uniqueness, vendor_credit_line)

Decided: 2026-07-10. Second of 3 reopens (POS → Purchasing → Platform, per the recommended sequence) executing the coordinated, 6-module "Header/Line Remediation" design (~/Downloads/vrida-header-line-remediation-design-2026-07-10.md, §4 — the Purchasing section — itself based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass (3 separate agents) before any of it was built. This reopen bundles 3 fixes into one pass, per the user's own explicit request. POS landed first (fix #8, PROJECT_DECISIONS #46); Platform is a separate, later reopen under the same effort, not detailed in this entry.

Fix #10 (must-fix, financial correctness) — purchase_order_line quantity-rollup CHECK. New: chk_purchase_order_line_quantity_rollup — received_qty + invoiced_qty + cancelled_qty <= ordered_qty. purchase_order_line was the one qty-counter-without-status table in this codebase's own design (Decision B case 4 of the design doc) missing its own rollup CHECK — a real, disclosed gap the design's own audit flagged as more error-prone than an explicit status enum. Mandatory pre-migration audit (SELECT id, ordered_qty, received_qty, invoiced_qty, cancelled_qty FROM purchasing.purchase_order_line WHERE received_qty + invoiced_qty + cancelled_qty > ordered_qty) confirmed zero violating rows live — the table itself had zero rows at the time — so the CHECK was added directly, no NOT VALID fallback needed. Safe by construction, not by NULL-branching: all 4 operands are already NOT NULL.

Fix #12 (guardrail/consistency) — line_number uniqueness on 4 tables. Added as PARTIAL unique indexes (WHERE deleted_at IS NULL), matching purchase_order_line's own pre-existing shape:

  • purchase_receipt_line_receipt_line_number_unique on purchase_receipt_line (purchase_receipt_id, line_number)
  • vendor_invoice_line_invoice_line_number_unique on vendor_invoice_line (vendor_invoice_id, line_number)
  • vendor_return_line_return_line_number_unique on vendor_return_line (vendor_return_id, line_number)
  • purchase_order_template_line_template_line_number_unique on purchase_order_template_line (template_id, line_number)

Mandatory pre-migration dedup audit, once per table, confirmed zero duplicate rows on all 4 (all 4 were zero-row tables at the time) — a plain UNIQUE has no NOT VALID fallback in Postgres (unlike fix #10's CHECK), so this audit was the only safety valve before adding directly.

Fix #4 (structural improvement) — new table purchasing.vendor_credit_line. Per-line decomposition of a vendor_credit's total amount — write-once, no status/updated_at/deleted_at (Decision B case 1, matching tax.tax_calculation_jurisdiction's precedent), fully additive (existing vendor_credit rows simply gain zero lines, no backfill). 8 columns: id (PK, platform.uuid_generate_v7()), tenant_id, vendor_credit_id, vendor_invoice_line_id (nullable), vendor_return_line_id (nullable), amount_cents, description (nullable), created_at.

3 composite-FK prerequisites. vendor_credit_line's 3 FKs — to vendor_credit, vendor_invoice_line, vendor_return_line — all use the composite (col, tenant_id) REFERENCES parent(id, tenant_id) form (the codebase's standing cross-tenant-FK rule). All 3 parent tables were confirmed missing UNIQUE(id, tenant_id) at design time — added first, zero-risk (each table's id is already its sole PK, so the new constraint can never be violated by existing data regardless of row count): vendor_credit_id_tenant_id_unique, vendor_invoice_line_id_tenant_id_unique, vendor_return_line_id_tenant_id_unique.

chk_vendor_credit_line_target requires exactly one of vendor_invoice_line_id/vendor_return_line_id set, or both NULL (the header's own existing 'overpayment'/'other' credit_type case, which has no line to target at all) — never both. NULL-safe, full truth-table walkthrough confirmed during design verification.

Reconciliation trigger — HEADER IS TRUTH. trg_vendor_credit_line_validate_against_credit (function purchasing.validate_vendor_credit_line_against_credit()), BEFORE INSERT OR UPDATE OF amount_cents, vendor_credit_id on vendor_credit_line — rejects any line write that would make SUM(lines.amount_cents) for a given vendor_credit_id exceed that credit's own credit_amount_cents. Lines may legitimately sum to LESS (an undecomposed remainder is fine), never more; vendor_credit.credit_amount_cents itself is never mutated by this trigger. Matches the same header-is-truth pattern this effort's design doc established for Billing's own future ar_charge_line (not built this pass).

Migration: packages/db/migrations/20260710010000_headerline_purchasing_fixes.sql. Schema files: packages/db/src/schema/purchasing/order.ts (purchase_order_line's new CHECK, purchase_order_template_line's new unique index), packages/db/src/schema/purchasing/receipt.ts (purchase_receipt_line's new unique index), packages/db/src/schema/purchasing/invoice.ts (vendor_invoice_line's new unique index + UNIQUE(id, tenant_id)), packages/db/src/schema/purchasing/credit_return.ts (vendor_return_line's new unique index + UNIQUE(id, tenant_id), vendor_credit's new UNIQUE(id, tenant_id), and the brand-new vendor_credit_line table).

+1 table (vendor_credit_line), +8 columns. purchasing is now 17 tables / 410 columns (up from 16/402) — verified live via information_schema.columns/.tables. No table removed, no column added or removed elsewhere; only constraints, 1 new table, and 1 new trigger changed.

Verification. Live-reproduced and test-confirmed: an UPDATE pushing purchase_order_line.received_qty (or received_qty+invoiced_qty combined) over ordered_qty is rejected; an update landing exactly at the limit succeeds (fix #10). A duplicate line_number insert is rejected on vendor_invoice_line and vendor_return_line (both 23505 against the new constraint names), and both purchase_receipt_line/purchase_order_template_line's own indexes confirmed to exist (fix #12). vendor_credit_line: a valid single-target insert succeeds; a second line pushing the running sum over credit_amount_cents is rejected (P0001, "would exceed"); a line landing exactly at the credit total succeeds; a both-targets-set insert is rejected by chk_vendor_credit_line_target (23514); a neither-target (overpayment) insert succeeds; a cross-tenant insert is rejected by the composite FK (23503) (fix #4). New test coverage: apps/api/src/purchasing/__tests__/purchasing-schema.spec.ts, new sections L (3 tests), M (3 tests), N (6 tests) — the module's own schema-spec suite is 58/58 green.

Next. Platform reopens next under the same effort, per the design doc's own recommended sequence — not detailed here; it gets its own PROJECT_DECISIONS entry when it lands.

48. platform Reopen — Header/Line Remediation Fix #1 (subscription_invoice_line, Corrected Migration-Sequencing)

Decided: 2026-07-10. Third and final of 3 reopens (POS → Purchasing → Platform, per the recommended sequence) executing the coordinated, 6-module "Header/Line Remediation" design (~/Downloads/vrida-header-line-remediation-design-2026-07-10.md, §1 — the Platform section — itself based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass (3 separate agents) before any of it was built. POS landed first (fix #8, PROJECT_DECISIONS #46); Purchasing landed second (fixes #10/#12/#4, PROJECT_DECISIONS #47). This reopen closes out the 3 reopens actually carried into implementation this pass — POS, Purchasing, Platform. The design doc's other named fixes (Billing's fix #2, Identity's fix #3, Inventory's #5/#9, Orders/POS's #6/#13) were part of the same 6-module design proposal but were not picked up in this implementation pass; if taken up later they get their own reopen and their own PROJECT_DECISIONS entry, same as these 3.

New table — platform.subscription_invoice_line (10 cols): per-line decomposition of a subscription_invoice's total. id (PK, platform.uuid_generate_v7() default — Decision B case 1, matching tax.tax_calculation_jurisdiction's precedent, not gen_random_uuid()), tenant_id, subscription_invoice_id (composite FK only, no bare FK), line_type (CHECK IN 8 values: base_subscription/ai_credit_overage/additional_seats/additional_sites/proration/one_time_addon/discount/tax), description (NOT NULL), quantity (nullable numeric), unit_amount_cents (nullable bigint), amount_cents (NOT NULL, negative for discount lines), currency_code (FK → shared.currency, default 'USD'), created_at. No updated_at/deleted_at — write-once. RLS enabled (tenant-isolation policy).

Composite FK subscription_invoice_line_invoice_tenant_fkey → subscription_invoice(id, tenant_id) — required a new prerequisite UNIQUE(id, tenant_id) on subscription_invoice itself (subscription_invoice_id_tenant_id_unique), confirmed missing before this migration, not hypothetical (design doc §7 finding V1).

CHECK chk_subscription_invoice_line_amount_matches_qty: both-null-or-both-set-and-consistent (amount_cents = quantity * unit_amount_cents when both are set) — NULL-safe, no bare nullable boolean term.

Reconciliation is LINES-ARE-TRUTH — the opposite pattern from Purchasing's own vendor_credit_line (header-is-truth, PROJECT_DECISIONS #47). Trigger trg_subscription_invoice_line_sync_totals (function platform.sync_subscription_invoice_totals_from_lines()), AFTER INSERT OR UPDATE OR DELETE on the line table, recomputes on the parent: subtotal_cents = SUM(amount_cents) WHERE line_type NOT IN ('tax','discount'), discount_cents = -SUM(amount_cents) WHERE line_type='discount' (stored as a positive magnitude on the header even though the line's own amount_cents is negative), tax_cents = SUM(amount_cents) WHERE line_type='tax', total_cents = subtotal_cents - discount_cents + tax_cents. The header's amount_due_cents/amount_paid_cents payment bookkeeping is untouched.

The single most serious finding of the whole 3-module remediation effort — a genuinely corrected migration-sequencing bug (design doc §7 finding V3-1). The original design draft's order was: create the table + install the sync trigger, then backfill, then "verify SUM(new lines) reconciles against the existing stored subtotal_cents." Since the trigger is AFTER INSERT/UPDATE/DELETE and unconditionally overwrites the header's totals from SUM(lines), it would fire during the backfill itself — meaning by the time the verification step ran, the "existing stored subtotal_cents" it compared against had already been overwritten by the trigger, making the check tautological (it would always "reconcile," even where the original blob genuinely diverged from history). This defeats the explicit stated intent ("log, don't silently fix, any mismatch"). Corrected 8-step order actually used, in the shipped migration (packages/db/migrations/20260710020000_headerline_platform_fix1.sql):

  1. Inspect the real line_items JSONB shape first (mandatory, not optional) — confirmed live that zero code path anywhere in this repo ever populates this column; every one of the 5 pre-existing live rows held only the '[]' default.
  2. Add the prerequisite UNIQUE(id, tenant_id) on subscription_invoice.
  3. Create subscription_invoice_line EMPTY — no sync trigger yet.
  4. Snapshot each invoice's pre-backfill subtotal_cents/discount_cents/tax_cents/total_cents into a temp table, before touching anything else.
  5. Backfill via jsonb_array_elements, guarded by a jsonb_typeof(line_items) = 'array' pre-check first (a stray non-array value throws a hard error on jsonb_array_elements() otherwise — confirmed live during design verification).
  6. Verify the backfill against the snapshot from step 4 (not the live, already-recomputable columns) — log any mismatch via RAISE NOTICE, don't silently fix it.
  7. Only now install the sync trigger (trg_subscription_invoice_line_sync_totals), so it never had the chance to silently overwrite the very data step 6 needed to compare against.
  8. Deprecate line_items in place via COMMENT ON COLUMN (not dropped) — matches this codebase's established convention (tenant_profile.tax_id/.logo_url).

Disclosed pre-existing data-quality finding, not a migration bug. All 5 pre-existing live subscription_invoice rows held line_items = '[]' despite each having a non-zero subtotal_cents (9900/4900/9900/5000/5000) — a genuine, pre-existing gap between the header and a JSONB blob nothing ever actually wrote to. The backfill correctly produced zero new lines for all 5 invoices (there was nothing in the empty array to explode), and the verification step (item 6 above) correctly logged all 5 as reconciliation mismatches via RAISE NOTICE — disclosed, not silently papered over. This is expected and consistent with the pre-migration inspection in step 1, not a defect introduced by this migration.

Migration: packages/db/migrations/20260710020000_headerline_platform_fix1.sql. Schema file: packages/db/src/schema/platform/billing.ts (new subscriptionInvoiceLine export; subscriptionInvoice gains unique('subscription_invoice_id_tenant_id_unique').on(t.id, t.tenant_id); a deprecation comment on subscriptionInvoice.line_items's column definition).

+1 table, +10 columns. platform is now 27 tables / 450 columns (up from 26/440) — verified live via information_schema.columns/.tables. subscription_invoice's own column count is unchanged at 26 (only a constraint + a column comment, no new column).

Verification. Live-reproduced and test-confirmed: an INSERT of a base_subscription line syncs the header's subtotal_cents/total_cents (J1); a tax line + a discount line recompute all four header totals with the discount-as-positive-magnitude sign convention (J2); deleting the tax line re-syncs the header via the trigger's own DELETE path, not just INSERT (J3); chk_subscription_invoice_line_amount_matches_qty rejects a quantity*unit_amount_cents mismatch while accepting both the consistent version and a flat-amount row with neither set (J4); a cross-tenant subscription_invoice_line insert is rejected by the composite FK (J5); an invalid line_type is rejected by its CHECK (J6). New test coverage: apps/api/src/platform/__tests__/platform-billing.spec.ts, new Group J (6 tests, J1–J6). A separate agent's independent verification pass (already run) confirmed all of the above true and live, with one unrelated, already-disclosed concern noted and not re-logged here: platform.payment.invoice_id is a pre-existing bare FK into subscription_invoice, out of this fix's scope and already logged elsewhere in OPEN_ITEMS.

This closes the entire Header/Line Remediation effort's 3 planned reopens (POS, Purchasing, Platform). See PROJECT_DECISIONS #46 (POS) and #47 (Purchasing) for the other two legs.

49. inventory Reopen — Header/Line Remediation Fixes #5, #9 (stock_adjustment_batch, stock_count_line Reconciliation)

Decided: 2026-07-10. First reopen of the second batch of the coordinated, 6-module "Header/Line Remediation" design (vrida-header-line-remediation-design-2026-07-10.md, §5 — the Inventory section — itself based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass (3 separate agents) before any of it was built. The first batch (POS → Purchasing → Platform) closed with fix #1 on Platform (PROJECT_DECISIONS #46/#47/#48); that batch's own closing note explicitly named Inventory's fixes #5/#9 as picked up later, not in that pass — this reopen is that later pass. Per the design doc's own recommended sequence (§8), this reopen was moved ahead of Purchasing's still-deferred fix #7 (movement-line linkage), since fix #7's Purchasing-side composite FK depends on an Inventory-side prerequisite — see the disclosure below.

Fix #5 (structural improvement) — new table inventory.stock_adjustment_batch. A header grouping multiple stock_adjustment_request rows so a full-shelf recount touching many variants can be reviewed and approved/rejected together, rather than only ever one adjustment at a time. 10 columns: id, tenant_id, site_id, batch_reason, status, created_by_actor_id, automation_source, created_at, updated_at, deleted_at. status reuses stock_count's own "status as review seam" convention verbatim (open/reviewing/approved/rejected), plus partially_approved since lines can resolve independently — itself reusing order_header.status's own partially_fulfilled precedent. Carries its own UNIQUE(id, tenant_id) (stock_adjustment_batch_id_tenant_id_unique) from creation — the prerequisite for stock_adjustment_request.batch_id's new composite FK, added on this brand-new table's own DDL from the start rather than as a later correction (this whole remediation effort's own standing rule for every new parent a composite FK will target). stock_adjustment_request gains a new nullable batch_id column with composite FK stock_adjustment_request_batch_tenant_fkey (batch_id, tenant_id) → stock_adjustment_batch(id, tenant_id) — not bare. Fully additive: stock_adjustment_request had 0 live rows at build time, so zero backfill was needed.

Fix #9 (guardrail/consistency) — stock_count_line reconciliation tracking + conditional immutability. Gains reconciled_at (nullable timestamptz) + reconciled_by_actor_id (nullable FK → identity.actor) + a NULL-safe CHECK, chk_stock_count_line_reconciled_requires_counted: reconciled_at IS NULL OR counted_qty IS NOT NULL. Also a bespoke conditional-immutability trigger — deliberately NOT the shared blanket platform.reject_append_only_mutation() used elsewhere in this codebase — because a stock-count line must stay legitimately editable (fill in counted_qty, correct a mis-entry) up until the moment it's reconciled; only after reconciled_at is set does it lock. Trigger function inventory.reject_stock_count_line_mutation_after_reconciled(), fires BEFORE UPDATE OR DELETE, checks OLD.reconciled_at IS NOT NULL and raises 'stock_count_line % is already reconciled and cannot be modified' if so, otherwise RETURN COALESCE(NEW, OLD) — correctly handles both UPDATE (returns NEW, allowing it through) and DELETE (falls through to OLD, avoiding the "BEFORE DELETE returning NULL silently cancels the delete" footgun). Trigger name: trg_stock_count_line_lock_after_reconciled. stock_count_line had 0 live rows at build time — zero backfill needed for the new nullable columns/CHECK.

Migration: packages/db/migrations/20260710030000_headerline_inventory_fixes.sql. Schema files: packages/db/src/schema/inventory/stock.ts (new stockAdjustmentBatch export + stockAdjustmentRequest.batch_id), packages/db/src/schema/inventory/count.ts (stockCountLine's new columns + CHECK).

Table/column count delta, independently recomputed against the live DB (not assumed from any prior narrative): inventory was 24 tables / 338 columns immediately before this reopen (confirmed live via information_schema.tables/.columns with the table_type='BASE TABLE' filter — the module's own established footgun, since a plain information_schema.columns count with no such filter also picks up the stock_reconciliation_shell VIEW's 8 columns, which would otherwise overstate the total by exactly that much). This reopen adds +1 table (stock_adjustment_batch, 10 cols) and +3 columns on existing tables (stock_adjustment_request.batch_id +1, stock_count_line.reconciled_at/.reconciled_by_actor_id +2) — +13 columns total. inventory is now 25 tables / 351 columns (up from 24/338), verified live post-migration: SELECT count(*) FROM information_schema.tables WHERE table_schema='inventory' AND table_type='BASE TABLE' → 25; the equivalent BASE-TABLE-filtered column count → 351, matching the per-table column-count reconciliation sum in docs/database/schema_docs/inventory.md exactly.

Independent verification (separate agent, adversarial, live-DB-checked) — pasted, attributed. Found: PASS on everything — schema shape, composite FK correctness, CHECK formula, trigger behavior (including the NEW/OLD/DELETE edge case), grants unchanged, and 6 live-reproduction scenarios all matched exactly (cross-tenant stock_adjustment_request rejected by the composite FK with the exact expected error; reconciled_at set with counted_qty NULL rejected by the CHECK; pre-reconciliation UPDATE succeeds; post-reconciliation UPDATE and DELETE both rejected with the exact claimed error message). Test suite: 48/48 passed in that pass (a follow-up test-writing pass later extended this further — see below).

One real disclosure gap the verifier flagged (a CONCERN, not a defect in what was built): the design doc (vrida-header-line-remediation-design-2026-07-10.md §5, "Reopen delta, Inventory") names a stock_movement_line UNIQUE(id, tenant_id) addition as belonging to this same Inventory reopen — it is the prerequisite for Purchasing's still-deferred fix #7 (movement-line linkage, intentionally deferred to the upcoming Receiving extraction, out of this task's own scope). That UNIQUE constraint was NOT added in this reopen — confirmed live: stock_movement_line still has only its plain PK, zero unique constraints (SELECT conname FROM pg_constraint WHERE conrelid='inventory.stock_movement_line'::regclass AND contype='u' returns no rows). This mirrors the exact kind of scope-narrowing disclosure already made in PROJECT_DECISIONS #48 for the first batch (Platform reopen disclosed its own fix #7 wasn't picked up there either) — logged to OPEN_ITEMS.md, cross-referenced against the existing Purchasing↔Inventory fix #7 deferred-to-Receiving item so the Inventory-side prerequisite doesn't silently fall out of tracking a second time.

One additional gap found independently while writing this documentation pass, not part of the verifier's own report, disclosed rather than silently fixed: stock_adjustment_batch.updated_at has no maintaining trigger. Confirmed live: SELECT tgname FROM pg_trigger WHERE tgrelid='inventory.stock_adjustment_batch'::regclass AND NOT tgisinternal returns zero rows. Every other soft-delete/mutable table in this module (stock_adjustment_reason, stock_count, stock_reservation, etc.) has a set_updated_at trigger wired via platform.set_updated_at(); this brand-new table's migration never adds one, so updated_at is set once at INSERT and never refreshed on UPDATE. Not a design choice (unlike the 5 legitimately-exempt append-only/hard-delete tables already documented in this module) — a real, disclosed gap. Logged to OPEN_ITEMS.md.

Test-writing (already completed, separately from the design-phase verification above). apps/api/src/inventory/__tests__/inventory-schema.spec.ts extended with 2 new sections: O (fix #5 — 2 tests: a valid same-tenant batch_id reference succeeds; a cross-tenant batch_id reference is REJECTED by the composite FK) and P (fix #9 — 5 tests: reconciled_at set with counted_qty NULL rejected by the CHECK; a pre-reconciliation counted_qty UPDATE succeeds; reconciliation — both fields set — succeeds; a post-reconciliation UPDATE is rejected; a post-reconciliation DELETE is rejected). Independently re-verified against the actual current file (not assumed from the prior paragraph): the file has 30 individually-titled it() blocks plus 1 it.each(ALL_25_TABLES) call generating 25 per-table RLS-existence sub-tests — 55 tests total, up from 47 before this reopen (the it.each array itself grew from ALL_24_TABLES to ALL_25_TABLES when stock_adjustment_batch was added, accounting for the "+8" delta reported for the full apps/api suite being one more than the 7 new named O/P tests alone).

Next. Design doc §5's own disclosure (finding V1-4) means Purchasing's still-deferred fix #7 cannot be picked up until stock_movement_line gets its own UNIQUE(id, tenant_id) — logged as an open item here rather than added speculatively, since it was not part of this reopen's actual scope (fixes #5/#9 only).

50. orders Reopen — Header/Line Remediation Fix #6 (order_line.sale_line_id)

Decided: 2026-07-10. Second reopen of the second batch of the coordinated, 6-module "Header/Line Remediation" design (vrida-header-line-remediation-design-2026-07-10.md, §6a — the Orders section — itself based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass (3 separate agents) before any of it was built. Inventory landed first in this batch (fixes #5/#9, PROJECT_DECISIONS #49); this reopen is the second — sequenced after Inventory and, per the migration's own header comment, "after POS specifically, per the confirmed ripple dependency in vrida-header-line-remediation-design-2026-07-10.md §6a." The prerequisite UNIQUE(id, tenant_id) on pos.sale_line was already laid in the first batch's own POS reopen (fix #8's migration, 20260710000000_headerline_pos_fix8.sql, PROJECT_DECISIONS #46) — confirmed live before writing this migration, not assumed.

Fix #6 — orders.order_line.sale_line_id, line-level fulfillment linkage. New nullable column, composite FK order_line_sale_line_id_tenant_fkey (sale_line_id, tenant_id) → pos.sale_line(id, tenant_id) — not bare. Extends order_header.fulfilled_sale_id's own header-level pos-fulfillment seam down to the line level: which pos.sale_line a given order_line was actually fulfilled by, not just which sale fulfilled the order as a whole. Design rationale: link-don't-convert, matching order_header.fulfilled_sale_id's own established asymmetry — no reciprocal column exists on pos.sale_line's side either, and none is added here (open to reconsideration later if a real "given a sale_line, find its originating order_line" query need emerges). Fully additive: nullable column, zero backfill, no existing order_line data touched (no sale_line_id value can retroactively populate itself).

Migration: packages/db/migrations/20260710040000_headerline_orders_fix6.sql. Schema file: packages/db/src/schema/orders/line.ts (orderLine gains the sale_line_id column plus a table-level composite foreignKey({...}), named order_line_sale_line_id_tenant_fkey — deliberately no .references() on the raw column, since the real constraint is the composite one below it).

Column-count delta, independently recomputed against the live schema (not assumed from any prior narrative). orders was 7 tables / 174 columns immediately before this reopen (post-Remediation-Phase-4, PROJECT_DECISIONS #40 — up from 173 at the original 2026-07-07 lock). Recomputing order_line column-by-column against the actual current packages/db/src/schema/orders/line.ts (not trusting any stated total blindly, per this reopen's own explicit instruction): id, tenant_id, order_id, variant_id, line_type, quantity, reserved_qty, fulfilled_qty, backordered_qty, cancelled_qty, fulfillment_status, stock_reservation_id, sale_line_id (new), resolved_amount_minor_units, charged_amount_minor_units, currency_code, tax_treatment, resolving_price_rule_id, resolved_quantity, price_override, price_override_reason, discount_amount_cents, line_subtotal_cents, line_total_cents, estimated_line_tax_cents, substitution_allowed, substituted_from_variant_id, expected_arrival_at, note, created_by_actor_id, automation_source, review_status, review_reason, reviewed_by_actor_id, reviewed_at, decision_provenance, created_at, updated_at, deleted_at = 39 columns (38 before this fix, matching docs/database/schema_docs/orders.md's own pre-fix stated count exactly). This reopen adds +1 column, 0 new tables — orders is now 7 tables / 175 columns (up from 174), verified against the per-table column-count reconciliation sum in docs/database/schema_docs/orders.md.

Independent verification (separate agent, adversarial, live-DB-checked against a fresh transaction) — pasted, attributed. Found: the core fix #6 deliverable is fully verified and correct — composite FK confirmed genuinely 2-column via pg_constraint, prerequisite UNIQUE(id,tenant_id) on pos.sale_line confirmed present, all 3 live-reproduction scenarios (valid same-tenant reference succeeds, NULL succeeds, cross-tenant reference rejected by order_line_sale_line_id_tenant_fkey) independently reproduced with matching error text, TS source confirmed clean (no dangling imports, no .references() on the raw column), grants unchanged, and the design's stated asymmetry (no reciprocal column on pos.sale_line) confirmed to actually hold.

Two real findings, both disclosed here, neither invalidating fix #6 itself:

  1. A test-suite bug was caught DURING verification (not by the build itself): the test file's afterAll for the new section originally attempted a hard DELETE FROM pos.sale_line, which unconditionally fails because sale_line is append-only-enforced (even for the superuser DB connection, from the prior POS-batch reopen's own trigger) — this would fail CI and leak tenant fixture rows into any environment on every run. This has since been fixed (confirmed live: apps/api/src/orders/__tests__/orders-schema.spec.ts now uses a tryDelete() helper mirroring pos-schema.spec.ts's own established precedent for this exact append-only-table cleanup problem) — independently re-confirmed by re-running the suite this pass: cd apps/api && npx jest src/orders/__tests__/orders-schema.spec.ts --forceExit → 46/46 passing (up from 43/43 before this fix; new section M contributes 3 tests).
  2. A new, previously undisclosed finding (not a defect in fix #6, but flagged explicitly): within orders itself, order_line.order_id, order_payment.order_id, order_fulfillment.order_id, order_fulfillment_line.order_fulfillment_id, and order_template_line.order_template_id are ALL still bare (non-composite) FKs into order_header/order_fulfillment/order_template — none of which currently have UNIQUE(id,tenant_id). This is the identical bug class this whole remediation effort exists to close, sitting inside Orders' own internals, right next to the column this fix just touched — and it isn't named anywhere in the design doc or in any existing PROJECT_DECISIONS entry. Logged as a new OPEN_ITEMS row (a future Orders reopen candidate — NOT fixed in this pass), cross-referenced to this entry (#50).

Verification. Live-reproduced and test-confirmed, full apps/api suite green. Pre-fix: no sale_line_id column existed on order_line. Post-fix: a same-tenant sale_line_id reference resolves via JOIN and succeeds; a NULL sale_line_id (not-yet-fulfilled line) succeeds; a cross-tenant sale_line_id reference is rejected by order_line_sale_line_id_tenant_fkey (23503). New test coverage: apps/api/src/orders/__tests__/orders-schema.spec.ts, new section M (3 tests: M1 valid reference, M2 NULL, M3 cross-tenant rejection).

Next. This closes fix #6 of the second batch. Design doc §5's own disclosure (PROJECT_DECISIONS #49) means Purchasing's still-deferred fix #7 remains blocked on inventory.stock_movement_line gaining its own UNIQUE(id, tenant_id) — unrelated to this entry, tracked separately in OPEN_ITEMS.

51. billing Reopen — Header/Line Remediation Fix #2 (ar_charge_line, Reconstructed Backfill)

Decided: 2026-07-10. Third reopen of the second batch of the coordinated, 6-module "Header/Line Remediation" design (vrida-header-line-remediation-design-2026-07-10.md, §7 — the Billing section — itself based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass (3 separate agents) before any of it was built. Inventory landed first in this batch (fixes #5/#9, PROJECT_DECISIONS #49); Orders landed second (fix #6, PROJECT_DECISIONS #50); billing is third, per the design doc's own recommended dependency order (§8).

Fix #2 — new table billing.ar_charge_line (12 cols). Per-line decomposition of an already-resolved ar_charge.charge_amount_cents — Decision B case 1 (write-once, no status/updated_at/deleted_at), matching tax.tax_calculation_jurisdiction's own precedent exactly. PK platform.uuid_generate_v7() default (not gen_random_uuid() — Remediation Phase 2's append-only-table PK convention). Columns: id, tenant_id, ar_charge_id (composite FK, NOT NULL), source_line_ref/source_line_type (polymorphic, plain uuid, no FK → pos.sale_line.id/orders.order_line.id, NULL-safe both-or-neither CHECK, type constrained to sale_line/order_line), description (NOT NULL), quantity/unit_amount_cents (both nullable, NULL-safe both-or-neither + exact-multiply CHECK when both present), amount_cents (NOT NULL, >= 0), tax_calculation_id (composite FK, nullable — the per-line tax link), tax_amount_cents (NOT NULL DEFAULT 0, >= 0), created_at. Verified live via information_schema.columns: exactly 12 columns (the prompt's own working assumption of 11 was checked against the live schema and found short by one — do not trust it blindly; recomputed from ar.ts/information_schema directly).

Reconciliation is HEADER-IS-TRUTH. Trigger trg_ar_charge_line_validate_against_charge (function billing.validate_ar_charge_line_against_charge(), BEFORE INSERT OR UPDATE OF amount_cents, ar_charge_id) rejects any line write that would push SUM(lines.amount_cents) over the parent ar_charge.charge_amount_cents. Lines may legitimately sum to LESS (an undecomposed remainder is fine), never more; ar_charge.charge_amount_cents itself is never mutated by this trigger. Mirrors purchasing.validate_vendor_credit_line_against_credit() verbatim in shape — the prior batch's own header-is-truth precedent (PROJECT_DECISIONS #47).

2 composite FKs, 2 new prerequisite UNIQUE(id, tenant_id) constraints, both confirmed missing live before this migration. ar_charge_line_charge_tenant_fkey (ar_charge_id, tenant_id) → billing.ar_charge(id, tenant_id) — prerequisite ar_charge_id_tenant_id_unique added to billing.ar_charge by this fix (zero risk: id is already the sole PK, so the constraint can never be violated by existing data regardless of row count — 68 rows at build time). ar_charge_line_tax_calculation_tenant_fkey (tax_calculation_id, tenant_id) → tax.tax_calculation(id, tenant_id) — prerequisite tax_calculation_id_tenant_id_unique added to tax.tax_calculation, a cross-module prerequisite this fix needed and added (218 rows at build time, same zero-risk reasoning — tax's own table/column counts are unaffected, since a UNIQUE constraint adds no column).

Pre-migration dry-run (mandatory, the riskiest part of this whole batch). No JSONB blob existed to convert (unlike Platform's own subscription_invoice_line fix, PROJECT_DECISIONS #48) — ar_charge_line rows had to be RECONSTRUCTED by joining back through source_ref to pos.sale/pos.sale_line. The dry run found zero of the 34 live pos-sourced ar_charge rows (34 distinct tenants) share a tenant with any seeded pos.sale row — these are disconnected seed datasets in this dev environment (confirmed: 34 distinct ar_charge tenants, 0 overlap with pos.sale's own distinct tenant set), not a real reconciliation ambiguity. orders.order_header/order_line are both entirely empty (0 rows), so there is no orders-side data either. The backfill migration query was still written to the FULL reconstructive spec (real per-charge proration logic handling the disclosed sibling-charge-sharing-one-source_ref case — installment/split-billing — per ar_charge's own two-partial-unique-index design) and was actually RUN against live data, producing exactly INSERT 0 0 (confirmed, not assumed) — a real, disclosed historical gap for any pre-existing charges is the honest characterization (this fix's own fallback design: reconcile-or-leave-zero-lines, never force it). Independently re-confirmed live during this docs-writing pass (a second, later query, well after the original build): 47 pos-sourced ar_charge rows / 47 distinct tenants, 0 overlap with pos.sale's 396 distinct tenants, ar_charge_line still at 0 rows, orders.order_header/order_line still both 0 rows — the row/tenant counts have grown further since both the original build (34) and the independent verification pass described below (35), consistent with ongoing, unrelated seed-data growth in a shared dev DB, not a discrepancy; the 0-overlap/0-backfill result itself has held constant across all three checks.

Column-count impact. +1 table, +12 columns, 0 columns changed on any existing table (only the 2 new UNIQUE constraints, which are constraints, not columns) — 164 → 176 columns, 9 → 10 tables. Verified live post-migration: SELECT count(*) FROM information_schema.tables WHERE table_schema='billing' AND table_type='BASE TABLE' → 10; the equivalent BASE-TABLE-filtered column count → 176, matching the per-table column-count reconciliation sum in docs/database/schema_docs/billing.md exactly. Also verified: 58 CHECK constraints, 52 FK constraints, 1 UNIQUE constraint in the billing schema (via pg_constraint), RLS enabled on all 10 tables, set_updated_at firing on 7 tables (unchanged — the 2 append-only application tables plus the new write-once ar_charge_line are the 3 exceptions), 2 triggers total.

Migration: packages/db/migrations/20260710050000_headerline_billing_fix2.sql. Schema files: packages/db/src/schema/billing/ar.ts (new arChargeLine export; arCharge gains unique('ar_charge_id_tenant_id_unique')), packages/db/src/schema/tax/calculation.ts (taxCalculation gains unique('tax_calculation_id_tenant_id_unique')).

Independent verification (separate agent, adversarial, live-DB-checked) — pasted, attributed. Found: schema shape PASS (PK confirmed genuinely uuid_generate_v7()-shaped, not gen_random_uuid()); composite-FK verification PASS (both FKs genuinely 2-column, both prerequisite UNIQUE constraints confirmed); all 13 live-reproduced scenarios PASS (reconciliation trigger under/over/exact-sum, cross-tenant rejection on both FKs, both directions of the NULL-safe source-pair CHECK, invalid source_line_type, amount-matches-qty success/mismatch — all independently re-reproduced in a fresh rolled-back transaction); dry-run/backfill re-derivation PASS (independently reconfirmed 0 overlap, 0 backfill rows — noted the live tenant/row counts had grown slightly since the build, 35 vs 34, expected drift in a shared dev DB, not a discrepancy); NULL-in-CHECK sweep PASS (full truth-table walk on both multi-column CHECKs); grants PASS (full CRUD, no REVOKE — not append-only-enforced, only the trigger constrains the sum invariant).

Two findings, both disclosed here:

  1. CONCERN (real, latent, zero-risk today): billing.ar_charge.tax_calculation_id was ALSO found to be a bare FK by this same verification pass — this is a SEPARATE finding, closed in a LATER migration (packages/db/migrations/20260710070000_headerline_bare_fk_fixes.sql) and its own later docs pass — not credited to this entry. This fix's own migration/schema changes are limited to ar_charge_line's creation and the 2 prerequisite UNIQUE constraints described above.
  2. Minor, latent script fragility (informational only, not a defect): the backfill's dry-run gate computes a single whole-charge rounding while the actual per-line INSERT computes independent per-line rounding — these aren't always arithmetically identical for multi-line sales split across sibling charges (a specific edge case), though unreachable in today's data (every live pos.sale row has exactly 1 line). Worth a one-line disclosure for future reference if this migration pattern is ever reused, not a required fix.

Tests. apps/api/src/billing/__tests__/billing-schema.spec.ts — new section L (1 test: ar_charge_line has 0 pre-existing rows, confirming the backfill matched no live data) and new section M (13 tests: ar_charge_line's reconciliation-trigger under/over/exact-boundary sums, cross-tenant composite-FK rejection on both FKs, the NULL-safe source-pair CHECK in both directions, invalid source_line_type, and amount-matches-qty success/mismatch). Fix #2's own contribution is these 14 named tests, plus a mechanical +1 each in pre-existing sections A2/B when the table-enumeration array widened from ALL_9_TABLES to ALL_10_TABLES to pick up the new table. File total, independently recounted against the actual current file (not assumed): 70 tests — up from 52 immediately before this reopen (baseline confirmed via git show against the last committed version of this file, predating this whole second batch of Header/Line Remediation). The remaining 4-test delta beyond fix #2's own 14 (52 + 2 mechanical + 14 = 68, not 70) is section N (2 tests) — the bare-FK addendum finding above, added by a later pass, not fix #2's own credit.

Next. This is the third reopen of the second batch (Inventory #49 → Orders #50 → Billing #51). The ar_charge.tax_calculation_id bare-FK finding from this fix's own verification pass is picked up by a separate, later "bare-FK fixes" pass (migration 20260710070000_headerline_bare_fk_fixes.sql) with its own PROJECT_DECISIONS entry — not written here, to avoid attributing a different pass's fix to this one.

52. identity Reopen (4th) — Header/Line Remediation Fix #3 (invitation_site_assignment)

Decided: 2026-07-10. Fourth reopen of the second batch of the coordinated, 6-module "Header/Line Remediation" design (vrida-header-line-remediation-design-2026-07-10.md, based on vrida-header-line-pattern-audit-2026-07-10.md), already run through an independent adversarial verification pass before any of it was built. Inventory landed first in this batch (fixes #5/#9, PROJECT_DECISIONS #49); Orders second (fix #6, PROJECT_DECISIONS #50); Billing third (fix #2, PROJECT_DECISIONS #51); identity is fourth — Identity's own 4th reopen overall (after the 2026-06-28 password_policy/scim_config reopen pre-lock, the 2026-07-06 autonomy-first backfill + agent_duty_grant build, and the 2026-07-09 operator-identity build, PROJECT_DECISIONS #45). This is deliberately Identity's weakest-justified reopen in the whole batch — a small, narrowly-scoped fix, not a structural gap — and is documented with unusual care for exactly that reason.

Fix #3 — new table identity.invitation_site_assignment (6 cols). Pre-acceptance staging data mirroring identity.user_site_assignment's own shape almost verbatim — the correctly-modeled POST-acceptance version of this exact concept. Columns: id (PK gen_random_uuid()), tenant_id, invitation_id (composite FK → identity.invitation(id, tenant_id), no bare .references()), site_id (NOT NULL, deliberately NO FK to multi_loc.site — matches user_site_assignment.site_id's own existing, pre-existing, disclosed gap, NOT newly introduced by this fix), site_role_id (nullable FK → identity.role), created_at. Also carries its own UNIQUE(id, tenant_id) — the prerequisite for the reciprocal FK below.

identity.invitation gained UNIQUE(id, tenant_id) (invitation_id_tenant_id_unique, confirmed missing before this build).

identity.user_site_assignment gained a new nullable reciprocal-traceability column, created_from_invitation_site_assignment_id, with a composite FK → identity.invitation_site_assignment(id, tenant_id) (no bare .references() — the design doc's own original draft had this as a bare-FK mistake, caught by independent verification before this build even started, the same bug class independently caught on purchasing.vendor_credit_line/billing.ar_charge_line in the prior batch).

identity.invitation.site_assignments (the old JSONB column) is deprecated in place via a column COMMENT only — still readable/writable, no schema change to the column itself.

Column-count impact. +1 table, +6 cols (the new table) + +1 col (user_site_assignment's new column) — 37 tables / 422 cols → 38 tables / 429 cols.

Pre-migration audits (mandatory, both — documented carefully, this is Identity's lowest-necessity/most-scrutinized reopen in the whole batch):

  1. JSONB inspection: identity.invitation has ZERO rows in this environment — confirmed live before the build. No real site_assignments shape existed to inspect, and there was nothing to backfill (the post-backfill count-reconciliation step this fix's design calls for is trivially 0=0).
  2. Mandatory orphan-check audit — flagged clearly here for a human decision, NOT characterized as resolved. Found exactly ONE live orphaned row in identity.user_site_assignment — a site_id value with no matching row in multi_loc.site (id 4cd177f7-6f3a-42aa-a977-6fe0b34e89e6, site_id 3587ced4-62ba-47a8-b5ba-4cb0ae43ce29). identity.tenant_user.default_site_id has zero non-null rows — zero risk there. Because of this orphan, the OPTIONAL opportunistic bundle the design doc suggested (wiring user_site_assignment.site_id, tenant_user.default_site_id, AND this fix's own new site_id column all to real multi_loc.site FKs, since it would be cheaper than 3 separate future reopens) was deliberately NOT taken in this build — explicitly flagged for a human decision (null out the orphan vs. correct the reference), not unilaterally resolved. See docs/open-items/OPEN_ITEMS.md for the tracked open row.

Independent verification (separate agent, adversarial, live-DB-checked) — pasted, attributed. The verifying agent's own report describes this as "exactly the kind of reopen where scope creep or a rushed shortcut is most likely to slip through unnoticed," given this is Identity's weakest-justified 4th reopen. Findings: PASS on every single check, zero findings of concern. Schema shape confirmed exactly as claimed (including confirming site_id genuinely has no FK at all, not accidentally added and not accidentally missing something else). Both composite FKs confirmed genuinely 2-column. Both pre-migration audits independently re-verified live (the exact same orphan row ID/site_id reconfirmed, the exact zero-count on tenant_user reconfirmed). The "optional bundle was NOT built" claim was independently verified directly (queried all 28 FKs referencing multi_loc.site codebase-wide — none touch any of the 3 columns in question). All 5 live-reproduction scenarios independently reproduced in a fresh two-tenant fixture built entirely from scratch (not reusing any build-time IDs). Grants match the established sibling-table pattern exactly. The deprecation comment was confirmed to have landed on the right column with the column itself otherwise unchanged. A full scope-discipline review of the entire migration file's DDL inventory found zero scope creep — the migration touches exactly what fix #3 claims and nothing more (a real, explicit disciplined-execution finding worth highlighting, not just a formality, given the design doc's own explicit warning about this reopen). The only gap noted: no regression tests existed AT THE TIME of that verification pass (since resolved — see Tests below).

Migration: packages/db/migrations/20260710060000_headerline_identity_fix3.sql. Schema files: packages/db/src/schema/identity/governance.ts (new invitationSiteAssignment export; invitation gains unique('invitation_id_tenant_id_unique')), packages/db/src/schema/identity/assignment.ts (userSiteAssignment gains created_from_invitation_site_assignment_id + its composite FK).

Tests. apps/api/src/identity/__tests__/identity-governance.spec.ts — new Group E (5 tests, E1-E5) covering: valid same-tenant invitation_site_assignment insert; cross-tenant invitation_id rejected; valid same-tenant created_from_invitation_site_assignment_id on user_site_assignment; cross-tenant rejected; NULL succeeds. File went 21→26 tests.

Next. This is the fourth reopen of the second batch (Inventory #49 → Orders #50 → Billing #51 → Identity #52). The optional multi_loc FK-wiring bundle flagged above remains an open, unresolved human decision — logged to OPEN_ITEMS, cross-referenced here, not closed by this entry. A separate, not-yet-docs'd "bare-FK fixes" pass touches other modules under this same effort but is out of scope here.

53. Header/Line Remediation Batch 2 — 3 Bare Cross-Tenant FK Fixes (platform.payment, purchasing.vendor_invoice_match, billing.ar_charge) — Closes the Entire Batch 2 Effort

Decided: 2026-07-10. Fifth and final item of the second batch of the coordinated, 6-module "Header/Line Remediation" design (vrida-header-line-remediation-design-2026-07-10.md, based on vrida-header-line-pattern-audit-2026-07-10.md). Inventory landed first (fixes #5/#9, PROJECT_DECISIONS #49); Orders second (fix #6, PROJECT_DECISIONS #50); Billing third (fix #2, PROJECT_DECISIONS #51); Identity fourth (fix #3, PROJECT_DECISIONS #52). This entry is the fifth and last: 3 standalone bare-cross-tenant-FK fixes, landed in one migration across 3 already-touched modules rather than a fresh reopen of any one of them.

Migration: packages/db/migrations/20260710070000_headerline_bare_fk_fixes.sql (single file, 3 ALTER TABLE pairs — one composite-FK ADD + one bare-FK DROP each).

1. platform.payment.invoice_id (schema: packages/db/src/schema/platform/billing.ts, the payment table) — was bare FOREIGN KEY (invoice_id) REFERENCES platform.subscription_invoice(id), now composite payment_invoice_id_tenant_fkey (invoice_id, tenant_id) → platform.subscription_invoice(id, tenant_id). Prerequisite UNIQUE(id, tenant_id) (subscription_invoice_id_tenant_id_unique) already existed on subscription_invoice — added by the FIRST Header/Line Remediation batch's own Platform reopen (fix #1, PROJECT_DECISIONS #48), not this batch. This gap was disclosed (not fixed) at fix #1's own independent verification pass and tracked in OPEN_ITEMS until now. Pre-migration audit: 3 live rows, 0 cross-tenant mismatches, 0 orphans — safe direct ADD.

2. purchasing.vendor_invoice_match.vendor_invoice_line_id (schema: packages/db/src/schema/purchasing/invoice.ts, the vendorInvoiceMatch table) — was bare, now composite vendor_invoice_match_vendor_invoice_line_id_tenant_fkey (vendor_invoice_line_id, tenant_id) → purchasing.vendor_invoice_line(id, tenant_id). Prerequisite vendor_invoice_line_id_tenant_id_unique already existed — verified its actual origin rather than assumed: it was added in the FIRST Header/Line Remediation batch's own Purchasing reopen (fix #4's vendor_credit_line build, PROJECT_DECISIONS #47, 2026-07-10), predating this second batch entirely, NOT from any of this batch's own Billing/Purchasing work (this batch never reopened Purchasing at all before this entry). Pre-migration audit: 0 live rows in vendor_invoice_match — safe direct ADD. vendor_invoice_match.purchase_receipt_line_id DELIBERATELY remains a bare FK — purchasing.purchase_receipt_line has no UNIQUE(id, tenant_id) today, out of this fix's explicit named scope (only vendor_invoice_line_id was requested) — disclosed via a code comment in invoice.ts, not silently left inconsistent, and logged to OPEN_ITEMS with a concrete future trigger.

3. billing.ar_charge.tax_calculation_id (schema: packages/db/src/schema/billing/ar.ts, the arCharge table) — a 3rd, addendum fix, NOT originally in scope — found bare during independent verification of this same batch's own Billing fix #2 build (already documented in PROJECT_DECISIONS #51), which had already added UNIQUE(id, tenant_id) to both ar_charge and tax_calculation. Folded into THIS migration as a cheap, zero-risk fix rather than a separate reopen. Now composite ar_charge_tax_calculation_tenant_fkey (tax_calculation_id, tenant_id) → tax.tax_calculation(id, tenant_id). Pre-migration audit: 40 rows with populated tax_calculation_id at build time, 0 cross-tenant mismatches — independently re-confirmed live at this docs-writing pass, now 47 rows (this shared dev DB's row counts grow slightly over time), still 0 mismatches.

Independent verification (separate agent, adversarial, live-DB-checked) — pasted, attributed. Composite-FK verification PASS for all 3 (each genuinely 2-column, old bare constraint on each confirmed actually DROPPED — payment_invoice_id_subscription_invoice_id_fk, vendor_invoice_match_vendor_invoice_line_id_fkey, ar_charge_tax_calculation_id_fkey — not left dangling alongside the new one). The purchase_receipt_line_id bare-FK exception confirmed genuine (that table really has no UNIQUE(id, tenant_id), this isn't a fabricated excuse). All 3 pre-migration audits independently re-verified live. Critically: platform.payment and billing.ar_charge cross-tenant rejections were independently reproduced easily (both tables already had live rows to work with), but purchasing.vendor_invoice_match had ZERO live rows in vendor_invoice_line/purchase_receipt_line at build time, so the build itself could NOT reproduce that specific scenario — the independent verifier built a full fixture chain from scratch (vendor → purchase_order → purchase_order_line → purchase_receipt → purchase_receipt_line, plus vendor_invoice → vendor_invoice_line, across 2 tenants) and successfully proved BOTH the same-tenant-succeeds and cross-tenant-rejected cases for real. This was the single most important verification step in this whole fix — the one claim that had NOT been independently proven before that pass, now proven.

One real finding from that pass, since closed. apps/api/src/purchasing/__tests__/purchasing-schema.spec.ts's own header comment claimed a "Section O" test suite for this exact fix that had not actually been written yet at verification time — a test-writing pass immediately closed this gap afterward (Section O, tests O1/O2, using the same from-scratch fixture chain the verifier had just proven necessary). Confirmed landed (verified directly against the current file, not just repeating the claim): purchasing-schema.spec.ts line 829 onward carries a full Section O with a beforeAll building the same vendor→PO→receipt→invoice fixture chain across 2 tenants, and two named tests — (O1) a same-tenant vendor_invoice_line_id reference succeeds and (O2) a cross-tenant vendor_invoice_line_id reference is rejected by vendor_invoice_match_vendor_invoice_line_id_tenant_fkey.

Tests. Three files gained new coverage: apps/api/src/platform/__tests__/platform-billing.spec.ts (Group K, 2 tests — K1 cross-tenant rejection, K2 valid same-tenant success for payment.invoice_id), apps/api/src/billing/__tests__/billing-schema.spec.ts (Group N, 2 tests — N1/N2 for ar_charge.tax_calculation_id), apps/api/src/purchasing/__tests__/purchasing-schema.spec.ts (Group O, 2 tests — O1/O2 for vendor_invoice_match.vendor_invoice_line_id, the full from-scratch fixture chain). Verified current per-file it() counts directly against each file rather than assumed: platform-billing.spec.ts 38 tests total, billing-schema.spec.ts 41 tests total, purchasing-schema.spec.ts 41 tests total — all green.

Column-count impact: none. All 3 fixes are pure constraint-shape changes (bare FK → composite FK) — zero new tables, zero new columns, on any of the 3 modules. platform stays 27 tables / 450 cols, purchasing stays 17 tables / 410 cols, billing stays 10 tables / 176 cols.

This closes out the entire "Header/Line Remediation batch 2" effort. Mirroring how PROJECT_DECISIONS #48 closed the first batch (POS #46 → Purchasing #47 → Platform #48), all 5 items of this second batch are now complete: Inventory (fixes #5/#9, PROJECT_DECISIONS #49), Orders (fix #6, PROJECT_DECISIONS #50), Billing (fix #2, PROJECT_DECISIONS #51), Identity (fix #3, PROJECT_DECISIONS #52), and this entry's 3 bare-cross-tenant-FK fixes (PROJECT_DECISIONS #53). Combined with the first batch, the entire coordinated, 6-module "Header/Line Remediation" effort (vrida-header-line-remediation-design-2026-07-10.md) is now complete across both batches — 8 modules touched in total (pos, purchasing, platform, inventory, orders, billing, identity — platform and purchasing each touched twice, once per batch), zero fixes remain outstanding from either batch's own scoped list. Genuinely deferred, out-of-scope items remain tracked in OPEN_ITEMS (e.g. Purchasing's fix #7/#11 pending the Receiving extraction, the multi_loc site_id FK-wiring bundle pending a human decision, Orders' 5 internal bare FKs, purchase_receipt_line's own missing UNIQUE(id, tenant_id)) — these are follow-on candidates for a FUTURE reopen, not part of either batch's own closed scope.

54. multi_loc Reopen (1st) + identity Reopen (5th) — Orphan Resolution + 3-Column site_id Composite FK Wiring

Decided: 2026-07-10. Direct follow-up to entry #52's own flagged human decision: the orphaned identity.user_site_assignment row that blocked the optional site_id-FK-wiring bundle. This reopens multi_loc for the first time since its 2026-06-29 lock, and identity a fifth time (after the 2026-06-28 pre-lock reopen, the 2026-07-06 autonomy-first backfill + agent_duty_grant build, the 2026-07-09 operator-identity build, and #52's own 4th reopen).

Orphan investigation. Row identity.user_site_assignment id=4cd177f7-6f3a-42aa-a977-6fe0b34e89e6 (site_id=3587ced4-62ba-47a8-b5ba-4cb0ae43ce29) was traced to tenant 5312b5df-c9c3-4099-9733-a93de5fc8517 (auto-generated slug slug-5312b5df). That tenant has exactly 1 tenant_user, this 1 (now-deleted) site assignment, and — confirmed by a DB-wide scan of every table carrying a tenant_id column — only 5 rows total anywhere in the schema for this tenant (2 identity.role, 1 identity.tenant_user, 1 identity.role_assignment, 1 platform.legal_entity; all boilerplate/system rows, zero business data, zero sites/sales/customers/items). The referenced site_id was confirmed to never have existed in multi_loc.site at all, not even soft-deleted. Resolution: the row was DELETED (not nulled — site_id is NOT NULL, so nulling was not an option). All 3 orphan-check/cross-tenant-mismatch audits re-run clean (0 rows) immediately after.

Build — 1 UNIQUE + 3 composite FKs, schema-only, zero new tables/columns.

  • multi_loc.site gained UNIQUE(id, tenant_id) (site_id_tenant_id_unique) — the prerequisite every composite FK below needs. Zero risk on the table's 1252-row-at-build-time (1366 at verification time) live data — id was already the sole PK, so the constraint could never be violated.
  • identity.user_site_assignment.site_id → composite FK user_site_assignment_site_tenant_fkey → multi_loc.site(id, tenant_id).
  • identity.tenant_user.default_site_id → composite FK tenant_user_default_site_tenant_fkey → multi_loc.site(id, tenant_id).
  • identity.invitation_site_assignment.site_id → composite FK invitation_site_assignment_site_tenant_fkey → multi_loc.site(id, tenant_id) — closing the gap #52 itself explicitly left open ("deliberately NO FK ... matches user_site_assignment.site_id's own existing, pre-existing, disclosed gap").

All 3 columns in #52's named bundle are now composite-FK-enforced. Explicitly scoped out of this pass, confirmed still bare by independent verification: platform.tenant.primary_site_id and identity.user_permission_override.scope_id — these were not part of the 3-column bundle #52 flagged and remain open, tracked separately in OPEN_ITEMS. A 4th, previously-untracked bare column surfaced during this entry's own docs pass (not caught by #52's own audit, this build, or the independent verifier — none were asked to look beyond the named 3+2): identity.access_request.requested_scope_id (nullable, no FK, gated by CHECK access_request_scope_check requiring it NOT NULL when requested_scope_type='site') is a 4th site_id-shaped column pointing at the same multi_loc.site target, still bare. It is deliberately not wired in this pass — genuinely out of scope, newly logged rather than silently swept in — see OPEN_ITEMS.

Migration: packages/db/migrations/20260710080000_headerline_multiloc_site_fk_wiring.sql. Schema files: packages/db/src/schema/multi_loc/site.ts (new unique('site_id_tenant_id_unique')), packages/db/src/schema/identity/assignment.ts (userSiteAssignment.site_id retargeted from bare comment to composite FK), packages/db/src/schema/identity/membership.ts (tenantUser.default_site_id likewise), packages/db/src/schema/identity/governance.ts (invitationSiteAssignment.site_id likewise, header comment rewritten to describe the closed gap instead of the open one).

Live-reproduction (9 scenarios, all 3 columns). Same-tenant success, cross-tenant rejection, and orphan-site rejection all verified for each of the 3 columns — including one scenario specifically built to isolate the NEW invitation_site_assignment_site_tenant_fkey from the pre-existing invitation_id FK (a real invitation for tenant B referencing tenant A's site, confirming the new site FK specifically fired, not the older invitation FK).

Tests. apps/api/src/identity/__tests__/permission-engine.spec.ts and identity-governance.spec.ts (Group E, 4 of its 5 tests) both broke against the newly-enforced FKs — both files had used randomUUID() site_id placeholders, legal before this pass since the column was unenforced. Fixed by adding real multi_loc.site row creation via new insertSite() helpers in both files, with cleanup()/teardownE() updated to delete multi_loc.site rows (scoped by tenant) before the shared tenant-delete step. 36/36 in the 2 touched files; full suite 873/873 (confirmed via --runInBand to rule out this codebase's known parallel-worker DB-connection-contention flake, which reproduced once as expected — a different, pre-existing, already-documented admin-tenants.spec.ts pagination race, unrelated to this work).

Independent verification (separate agent, adversarial, live-DB-checked) — pasted, attributed. Overall verdict: CLEAN — zero findings. The agent gave particular scrutiny to the irreversible DELETE (task A), independently re-verifying tenant isolation via its own DB-wide tenant_id scan rather than trusting the claimed counts, and confirmed the delete was justified. All 4 new constraints confirmed correctly composite via pg_constraint, with no leftover bare single-column FK duplicates. Both sibling deferred columns (platform.tenant.primary_site_id, identity.user_permission_override.scope_id) independently confirmed to still carry zero FKs — genuinely untouched. All 9 live-reproduction scenarios independently reconstructed from scratch (fresh two-tenant fixtures, rolled back, no reused IDs) and reproduced exactly as claimed. Full suite run twice: first run 873/873 clean; second run reproduced the known, pre-existing admin-tenants.spec.ts B3 pagination race (documented since 2026-07-08, unrelated to this work) — re-ran in isolation, 32/32 clean, confirming it as the same known flake, not a new regression. Grants on all 4 touched tables confirmed unchanged. One bonus finding beyond the task's explicit ask: docs/modules/CROSS_MODULE_CONTRACTS.md lines 507–508 (not just OPEN_ITEMS.md) also describe these FKs as "deliberately NOT wired" and need the same correction — folded into this entry's own docs pass.

Column-count impact: none. Pure constraint-shape changes (1 UNIQUE + 3 composite FKs replacing 3 bare/absent FKs) — multi_loc stays at its locked table/column count, identity stays 38 tables / 429 cols.

Next. This closes the human decision #52 flagged open. The 2 sibling deferred site_id-shaped columns (platform.tenant.primary_site_id, identity.user_permission_override.scope_id) remain genuinely deferred — not part of this bundle, tracked separately in OPEN_ITEMS, each its own future reopen if ever prioritized.

55. Receiving Module Extraction — New receiving Schema + purchasing/inventory Reopen (Closes Header/Line Remediation Fixes #7/#11)

Decided: 2026-07-10. Direct follow-up to entry #54: with the multi_loc/identity site_id-FK bundle closed, this build executes Part B of the same day's vrida-cc-task-2026-07-10-orphan-fix-and-receiving-design.md — extracting purchasing.purchase_receipt/purchase_receipt_line into a brand-new receiving schema. This is the 2nd instance in this codebase of moving tables out of an already-locked module into a module that didn't exist yet (the 1st was approvals out of admin, entry #44). The design itself was independently, adversarially verified before this build started and found 2 BLOCKERs + 4 real issues in its own first draft, all fixed in the corrected version this build actually followed (the verifier's full, unedited text is preserved in the design doc's own §B.18, per this codebase's standing rule that verification findings are pasted and attributed, never summarized away). This build is a 3-module coordinated reopen: receiving new, purchasing reopened, inventory reopened (its 3rd reopen).

Migration: packages/db/migrations/20260710090000_receiving_extraction.sql, applied live in 13 sequential steps inside one --single-transaction psql invocation.

Build summary.

  • receiving (new, module #22): 2 tables / 62 cols. goods_receipt (33 cols, moved+renamed from purchase_receipt's 30, +3 new: voided_at/voided_by_actor_id/void_reason, closing a real gap where status='void' already existed with zero attribution). goods_receipt_line (29 cols, moved+renamed from purchase_receipt_line's 27, +2 new: stock_movement_line_id [fix #7] and reversal_of_goods_receipt_line_id). All 4 previously-bare FKs on goods_receipt and all 6 on goods_receipt_line upgraded to composite (child_col, tenant_id) → parent(id, tenant_id) — 4 were genuinely cross-module the moment these tables left purchasing; the others were bare and invisible until now. inspection_status CHECK widened +'quarantine'. Schema-bootstrap GRANTs applied (GRANT USAGE + table GRANTs + ALTER DEFAULT PRIVILEGES to authenticated, per Remediation Phase 1's GRANT-closed-by-default rule — the design's own first draft had missed this, caught by its pre-build verification).
  • purchasing (2nd reopen event this same day, 17→15 tables / 410→353 cols): loses the 2 moved tables (−30/−27 cols exactly). Constraint-only additions: vendor/vendor_address/purchase_order/purchase_order_line each gained UNIQUE(id, tenant_id) — the prerequisites receiving's own composite FKs needed. vendor_invoice_match.purchase_receipt_line_id and vendor_return_line.purchase_receipt_line_id both renamed goods_receipt_line_id, upgraded bare → composite → receiving.goods_receipt_line(id, tenant_id) — the 2nd dependency (vendor_return_line's) was missed in the design's own first draft and only caught by its independent verification pass (BLOCKER 2 below).
  • inventory (3rd reopen, unchanged at 25 tables / 351 cols): pure constraint-only — item_variant/lot/stock_movement/stock_movement_line each gained UNIQUE(id, tenant_id), the prerequisites for receiving.goods_receipt_line's own composite FKs into inventory.
  • admin.custom_field_definition: chk_custom_field_definition_entity_type's vocabulary value 'purchasing.purchase_receipt' → 'receiving.goods_receipt'. A pre-migration audit found 11 live rows using the old value (not the zero the design assumed) — investigated and confirmed all 11 are test-fixture debris from repeated admin-schema.spec.ts runs (every one of the 11 tenants is literally named "Admin Test cfd-entity-ok," that test's own fixture literal), backfilled in the same migration rather than left dangling on a retired CHECK value.
  • Entitlement bundling (documented only, nothing to build — no per-module entitlement mechanism exists anywhere in this codebase yet): Receiving is bundled to Purchasing's own toggle, no independent toggle.

BLOCKER 1 — fix #10 × fix #11 interaction (capped write-back), STRENGTHENED a 2nd time post-independent-verification. The design's first draft would have written the raw accepted_qty back onto purchase_order_line.received_qty the instant an over-tolerance receipt occurred — which is fix #11's entire purpose — deterministically violating fix #10's own zero-slack chk_purchase_order_line_quantity_rollup CHECK and rolling back the whole transaction, making the "flag, don't block" path dead code. Fixed at design time: absorbed_qty = LEAST(accepted_qty, ordered_qty − received_qty − invoiced_qty − cancelled_qty) — the PO line's own remaining capacity; only absorbed_qty is ever written back. A second, independent gap surfaced after the first build landed: both the Section-4 re-audit and the adversarial lock-gate verification (2 genuinely separate agents, pasted below) independently converged on the same finding — the first built version left this derivation and the write-back as an external, undocumented-in-DB convention for the not-yet-built ReceivingService to get right on its own. The rollup CHECK protected against silent corruption either way, but neither the formula nor the cap was actually DB-enforced; nothing stopped a future service from writing the raw accepted_qty and simply failing loudly, rather than the cap silently and correctly applying itself. Fixed for real: trg_goods_receipt_line_check_over_receipt_tolerance now derives over_short_qty itself (accepted_qty − absorbed_qty, overriding whatever the caller passed) and performs UPDATE purchase_order_line SET received_qty = received_qty + absorbed_qty atomically, in the same trigger invocation as the goods_receipt_line insert/accepted_qty update — no service, ever, can get this wrong. chk_goods_receipt_line_qty_nonneg was also widened to guard over_short_qty >= 0 (defense-in-depth; the trigger's own arithmetic already guarantees this by construction, given accepted_qty >= 0 and the rollup CHECK's own non-negative-capacity invariant). Live-reproduced (both build passes): an over-tolerance receipt (accepted_qty=120 against ordered_qty=100, zero prior received_qty) self-computes over_short_qty=20 and writes back exactly 100 automatically — no manual UPDATE anywhere in the final test suite; the rollup CHECK holds (100+0+0≤100); the flag path fires (goods_receipt.review_status → 'pending'). Separately proved the cap is load-bearing, not coincidental: a further +20 write-back attempt on top of the already-capped 100 correctly violates the rollup CHECK. Also proved: a blocked/rejected line's write-back correctly does not leak (the whole statement, trigger-side write-back included, aborts).

BLOCKER 2 — the 2nd, initially-missed dependency. The design's first draft named only vendor_invoice_match.purchase_receipt_line_id as blocked on and now closed by this extraction. purchasing.vendor_return_line.purchase_receipt_line_id is a second, live, bare, nullable FK into the exact same table — missed entirely by the first pass, never tracked in any prior OPEN_ITEMS/CROSS_MODULE_CONTRACTS row either. Fixed: both columns renamed goods_receipt_line_id and upgraded to composite in the same migration; both individually live-reproduced for cross-tenant rejection.

Fix #11 (over-receipt tolerance) — full implementation. New trigger trg_goods_receipt_line_check_over_receipt_tolerance / function receiving.check_goods_receipt_line_over_receipt_tolerance(). Reads admin.tenant_setting/admin.setting_definition with precedence site-scoped > tenant-wide > catalog default — 2 new setting_definition rows (receiving/over_receipt_tolerance_percent, number, default 0; receiving/over_receipt_tolerance_action, string, default "flag", CHECK-constrained to flag/block via a new, narrowly-scoped chk_setting_definition_receiving_tolerance_action that correctly ignores every other row in the shared catalog table). action='block' → RAISE EXCEPTION; action='flag' (default) → insert proceeds, reuses the existing FULL-autonomy-pack review seam (review_status/review_reason), zero new columns needed. Live-reproduced all 3 precedence levels, including that a site-scoped 'block' override correctly wins over a tenant-wide 'flag' override for the same tenant.

Disclosed deviation from the design's literal wording (found during THIS build, not the pre-build verification) — itself corrected once, post-independent-verification. The design text says the trigger fires "BEFORE INSERT OR UPDATE," unscoped. The first built version installed BEFORE INSERT OR UPDATE OF over_short_qty — a deliberate narrowing, reasoned through at the time (an unscoped UPDATE trigger would re-run on every unrelated later edit to an already-reviewed line, e.g. fixing a note/defect_code after a human already set goods_receipt.review_status back to 'approved', silently re-flipping review_status to 'pending' even though nothing about the received quantity changed — clobbering a human review decision). Once over_short_qty became a DERIVED value rather than caller-supplied (the BLOCKER 1 strengthening above), that scoping stopped making sense: the column the trigger actually needs to watch is accepted_qty (its real input), not over_short_qty (its output) — an UPDATE OF accepted_qty with over_short_qty left untouched would otherwise silently fail to re-derive. Corrected to BEFORE INSERT OR UPDATE OF accepted_qty. Postgres semantics: UPDATE OF col only restricts the UPDATE arm, never the INSERT arm, so every INSERT still fires unconditionally regardless. Live-reproduced: an UPDATE of note alone does not refire and does not disturb an 'approved' review_status; an UPDATE OF accepted_qty does refire, correctly re-derives over_short_qty against the PO line's current (not stale) remaining capacity, and correctly re-flags if now over-tolerance.

Fix #7 (movement-line linkage): goods_receipt_line.stock_movement_line_id, composite FK → inventory.stock_movement_line(id, tenant_id), superseding the older header-grain stock_movement_id (renamed from inventory_movement_id, kept per this codebase's "deprecate in place, don't drop" convention — its own composite FK also upgraded from bare).

Reversal design — a compensating goods_receipt_line (via reversal_of_goods_receipt_line_id, a self-referencing composite FK) plus a compensating inventory.stock_movement_line carrying a negative quantity_delta (same stock_movement.correlation_id as the original) — the original append-only rows are never edited or deleted. A genuine build-time clarification the design doc did not spell out: the compensating goods_receipt_line's own received_qty/accepted_qty stay positive (a magnitude, e.g. 10, not -10) — chk_goods_receipt_line_qty_nonneg has no reversal carve-out and would reject a negative value there. The reversal's sign lives entirely in the linked stock_movement_line.quantity_delta and in the reversal_of_goods_receipt_line_id link itself; goods_receipt_line's own qty columns record magnitude only, never direction.

3 real bugs found and fixed during this build's own live-reproduction pass (distinct from, and in addition to, the 2 BLOCKERs the design's own pre-build verification already caught):

  1. The migration's first live-apply attempt failed: receiving.goods_receipt was missing its own UNIQUE(id, tenant_id) — needed because goods_receipt_line.goods_receipt_id references its header via composite FK, and Postgres requires the referenced columns to carry a matching unique constraint. This was a real gap in the original design/build (every OTHER parent table in this migration got this prerequisite; the header of the moved pair itself did not), not a mere ordering slip. Fixed in both the migration and the Drizzle source (receiving/receipt.ts) in the same pass.
  2. The admin.custom_field_definition backfill hit a genuine constraint-migration chicken-and-egg case, failing twice before landing on the correct shape: attempt 1 ran the backfill UPDATE before widening the CHECK (failed — the OLD CHECK didn't yet allow the new value); attempt 2 widened the CHECK first, then backfilled (ALSO failed — ADD CONSTRAINT validates every existing row immediately, and the 11 rows still held the OLD value at that exact point, which the NEW CHECK no longer allowed). Fixed by DROPPING the CHECK entirely, running the backfill while unconstrained, then ADDING the final CHECK once every row already conformed.
  3. The tolerance trigger's ::numeric cast on admin.setting_definition/tenant_setting.value had no defensive handling — a corrupted (non-numeric) catalog value would crash the trigger with an unhandled exception (blocking all future over-tolerance receiving for that tenant until manually fixed), instead of failing safe. Found via the verification script's own deliberate test proving the CHECK correctly ignores unrelated setting_definition rows (which legitimately writes an arbitrary non-numeric value into the other catalog row under the same category to prove the point) — this exposed a real crash vector, not a hypothetical one. Fixed live via CREATE OR REPLACE FUNCTION, wrapping the whole 3-level percent-resolution cascade in its own BEGIN/EXCEPTION WHEN invalid_text_representation, falling back to the existing safe COALESCE(...,0) path. Confirmed fixed via a dedicated follow-up test proving the trigger no longer crashes against a corrupted catalog default.

Live-reproduction (32 guard assertions, 6 sections, all PASS), run as a standalone verification script using a full 2-tenant parallel fixture (isolating exactly one mismatched FK column per cross-tenant test, not a representative subset), inside one transaction, ending in ROLLBACK — zero residue, independently confirmed (0 verify-tenant rows remain, the 2 real setting_definition catalog rows are clean): (1) all 13 composite FKs individually cross-tenant-rejected; (2) 8 NULL-in-CHECK sweep tests including the defensive-fix proof; (3) idempotency (duplicate (tenant_id, idempotency_key) still rejected post-move); (4) BLOCKER 1's capped write-back + the tolerance trigger's full precedence chain; (5) 5 reversal assertions; (6) the 3-way match resolving across the new schema boundary.

Section 4 self-audit (builder's own pass). A-P+T+U run against receiving's 2 new tables plus the constraint-only changes on purchasing/inventory. All items PASS except two disclosed GAPs, neither blocking: (L, query-pattern indexes) goods_receipt_line.stock_movement_line_id, .reversal_of_goods_receipt_line_id, and .lot_id have no supporting index — confirmed live via pg_indexes (8 indexes exist on the table, none covering these 3 nullable FK columns). This is consistent with v1's own precedent (the header-grain stock_movement_id/inventory_movement_id was never indexed either), not a new regression, but logged to OPEN_ITEMS rather than left silently inconsistent. (T, trigger audit) the BEFORE INSERT OR UPDATE OF accepted_qty scoping (see above) is a disclosed deviation from the design's literal wording — reasoned through under item T(e)'s own rationale requirement, not silently substituted.

Tests. apps/api/src/receiving/__tests__/receiving-schema.spec.ts — 42/42 passing (40 from the initial pass + 2 added after the trigger strengthening below — I4a/I4b, proving an unrelated column edit doesn't refire the trigger while an accepted_qty edit correctly does), sections A–K covering both tables' existence/RLS/column-counts, all 13 composite FKs individually isolated (same-tenant success + cross-tenant rejection), both new/widened CHECKs, idempotency, the tolerance trigger's full precedence chain (including that an uncapped write-back genuinely violates the rollup CHECK, and that the write-back is now genuinely automatic — no test performs it manually), the reversal design (incl. the positive-magnitude clarification), and the 3-way match. apps/api/src/purchasing/__tests__/purchasing-schema.spec.ts — 60→59 tests (table list corrected 17→15; −2 removed purchase_receipt_line↔stock_movement tests and −2 removed purchase_receipt idempotency tests, both now covered by receiving's own file; +1 new test (O3) isolating vendor_invoice_match.goods_receipt_line_id's own composite FK independently of vendor_invoice_line_id; +4 new tests (Section P) for the 4 new UNIQUE(id,tenant_id) prerequisites), 59/59 passing. apps/api/src/inventory/__tests__/inventory-schema.spec.ts — 55→59 tests (+4 new, Section Q, for the 4 new UNIQUE(id,tenant_id) prerequisites), 59/59 passing, inventory's own table/column counts unchanged. apps/api/src/admin/__tests__/admin-schema.spec.ts — the (I2b) fixture value corrected 'purchasing.purchase_receipt' → 'receiving.goods_receipt' (see below), 60/60 passing.

Docs fan-out (10 files, 2 new + 8 updated): new docs/database/schema_docs/receiving.md (259 lines) and docs/modules/module_spec/receiving.md (153 lines); updated docs/database/schema_docs/purchasing.md, docs/modules/module_spec/purchasing.md, docs/database/schema_docs/inventory.md (also closed a real pre-existing self-contradiction found in passing: OPEN_ITEMS item #12 in that same file claimed stock_movement_line "still lacks UNIQUE(id,tenant_id)," now demonstrably false — closed via the file's own established strikethrough convention), docs/modules/module_spec/inventory.md (new DR-69), docs/modules/MODULE_INDEX.md (25→26 schemas; new Receiving row; Purchasing row corrected 17/410→15/353; running grand total to 241 tables / 3,737 cols), docs/modules/CROSS_MODULE_CONTRACTS.md (new Receiving section, 9 seam rows, including a Receiving → Admin read-only-consumer row for the tolerance-setting reads), docs/open-items/OPEN_ITEMS.md (5 rows closed — fix #7/#11's own deferral, the stock_movement_line UNIQUE gap, vendor_invoice_match's bare FK, 2 stale-reference corrections — + 6 new rows: the named-not-built scale extension points, vendor_return_line.inventory_movement_id's still-deferred other half, the stock_movement.source_module='purchasing' naming asymmetry, the 3-way-match's own untouched tolerance mechanism, the un-indexed FK columns from the Section 4 audit, and — added after the independent verification below — vendor_return_line's 3 OTHER bare FKs into now-uniqued tables), and docs/DOCS_INDEX.md (Modules locked 16→17, Schemas 16→17, Tables 192→193).

Column-count impact: receiving +2 tables / +62 cols (new). purchasing −2 tables / −57 cols (410→353). inventory unchanged (25 tables / 351 cols, constraint-only).

Independent verification — 2 separate agents, adversarial, evidenced, pasted and attributed (mandatory per this design's own history: its first draft had 2 BLOCKERs and a fabricated citation, so a self-graded pass was never going to be accepted at this lock gate). Both agents worked from the raw task and the live DB — neither was handed this entry's own conclusions as ground truth to confirm.

Agent 1 — independent Section-4 re-audit. Verdict: "the database build itself is solid — every column count, every one of the 13 composite FKs, every CHECK, every RLS policy, the trigger's live definition, and the schema-bootstrap GRANTs all independently verified to match what's claimed, down to exact names and targets." It ran receiving-schema.spec.ts (40/40 at the time), purchasing-schema.spec.ts (59/59), inventory-schema.spec.ts (59/59), and the full suite (--runInBand, 915/916 — the one failure being the already-disclosed admin-schema.spec.ts (I2b)), and re-derived every table/column/constraint count directly from information_schema/pg_constraint rather than trusting the claims. It flagged 4 items, all addressed in this pass: (FAIL) (I2b) genuinely still broken — now fixed. (FAIL) the full suite wasn't green as a direct consequence — now 918/918. (FAIL) 3 doc files (schema_docs/receiving.md, MODULE_INDEX.md, DOCS_INDEX.md) already asserted "schema-locked" while this entry's own "Next" section said otherwise — resolved by this entry now actually completing the lock gate those docs assumed. (FAIL) no independent verification had yet been pasted/attributed anywhere in this entry — resolved by this section. It also found (GAP, Item I/M): over_short_qty had "zero DB-level enforcement — no CHECK, no trigger derives or validates it against accepted_qty/the PO line's remaining capacity," recommending the trigger "compute over_short_qty from NEW.accepted_qty and a lookup against purchase_order_line... making the mechanism as structurally unviolable as the write-back cap already is." This is exactly what the BLOCKER 1 strengthening above implements.

Agent 2 — adversarial lock-gate verification. Built its own fresh 2-tenant fixture from scratch (not reusing any existing test's rows or IDs), re-proved every claim independently, and reported: "No BLOCKER-level defect found... composite FKs are real, cross-tenant isolation is real, append-only is real even against superuser, idempotency is real, the 3-way match resolves, and the rename left zero stray references. This is a solid build." On BLOCKER 1 specifically, it independently reproduced the capped write-back but flagged the same gap Agent 1 found from a different angle: "there is no trigger, function, or any DB mechanism anywhere that actually performs this write-back... the capped value is applied via a raw UPDATE written by the test/verifier, not by any enforced application or DB code... Not a data-integrity bug (the CHECK protects regardless) — but a documentation-fidelity gap worth correcting before lock." It also live-verified, as its own from-scratch reproduction (not merely re-stating the claim): the append-only guard on stock_movement_line blocks even a direct UPDATE/DELETE from the DB superuser/table-owner (via trg_stock_movement_line_append_only → platform.reject_append_only_mutation() — "genuine, code-enforced append-only-ness, not a documentation claim"); all 11 distinct parent tables behind the 13 composite FKs carry a real, separate UNIQUE(id,tenant_id) (not just a same-named constraint); the GRANT bootstrap is functionally complete (has_table_privilege() checked, not just information_schema); zero stray FKs anywhere else in the DB still reference the moved tables; and — the one genuinely new finding, not previously disclosed anywhere — purchasing.vendor_return_line still carries 3 bare FKs (item_variant_id, lot_id, purchase_order_line_id) into tables that gained their UNIQUE(id,tenant_id) prerequisite in this very migration, never tracked in any prior OPEN_ITEMS row (only the sibling inventory_movement_id bare FK had one). Now logged to OPEN_ITEMS as its own row, disclosed rather than silently left inconsistent.

Findings resolved in this closing pass: (1) admin-schema.spec.ts (I2b) fixed — full suite now 918/918 passing (confirmed --forceExit --runInBand). (2) BLOCKER 1 strengthened so the write-back and over_short_qty's derivation are genuinely trigger-enforced, not a service-layer convention (see above) — closes both agents' independently-found gap. (3) The trigger's UPDATE scope corrected from OF over_short_qty to OF accepted_qty to match the new derived-column semantics (see above). (4) chk_goods_receipt_line_qty_nonneg widened with over_short_qty >= 0 (defense-in-depth). (5) vendor_return_line's 3 other bare FKs logged to OPEN_ITEMS (genuinely deferred, not fixed in this pass — out of this migration's own named scope, matching the inventory_movement_id sibling's own precedent).

This closes the Receiving module extraction. receiving is now schema-locked (module #22); purchasing and inventory are re-locked.

56. Consumer + Rewards + Offers — the Consumer Layer's Real v2 Build (Model B), Consumer-Boundary Role Mechanism Corrected Mid-Build

Decided: 2026-07-11. Builds the corrected design (~/Downloads/consumer-rewards-offers-design-proposal-2026-07-11.md, post-independent-verification, all 13 design-phase findings fixed) across 3 new schemas — consumer (10 tables, non-tenant-scoped except 2 named exceptions), rewards (6 tables, tenant-scoped), offers (6 tables, tenant-scoped, this build's own AI-authored-offer module). This is the Consumer Layer's first real v2 build — exactly the same shape of event as CRM's own "first actually-built v2 product module" milestone (PROJECT_DECISIONS #23): consumer/rewards/offers were already 3 of MODULE_INDEX's 26 counted schemas, each holding a stale v1-carryover placeholder row (4/47, 6/89, 4/68 — 14 tables/204 cols combined) that was never a real v2 build. This is a delta to those 3 existing rows, not 3 new schemas: 22 tables / 321 cols (consumer 10/104, rewards 6/102, offers 6/115), a +8 tables/+117 cols delta to the running MODULE_INDEX total. Schema-only — no ConsumerService/RewardsService/OffersService yet.

The consumer_authenticated role mechanism — investigated, and corrected mid-build. The design proposal left the consumer-boundary auth mechanism open. This session's own earlier investigation confirmed a Supabase Custom Access Token Auth Hook (PostgREST/GoTrue's automatic JWT-role-claim switching) is structurally viable in this project's Supabase setup in general — but is not the right mechanism for this application, because apps/api (NestJS) never routes through PostgREST's auto-role-switching layer at all. It owns its Postgres connection directly (packages/db/src/client.ts, connected as authenticator) and performs its own explicit SET LOCAL ROLE + set_config() per transaction via tenantDB() — the same pattern every other tenant-scoped request in this codebase already uses. Decided: build a parallel consumerDB() helper applying the identical pattern to a new consumer_authenticated role, not a Custom Access Token Hook. supabase/config.toml is untouched; no hook function was created; no Supabase Auth service restart was needed. consumer_authenticated is NOLOGIN NOINHERIT (deliberate — it must never silently inherit privileges from an unrelated future role grant) and authenticator was made a member of it, mirroring exactly how authenticated itself is wired.

The boundary split. Of consumer's 10 tables, 8 are genuinely consumer-scoped identity tables (consumer, consumer_identifier, consumer_address, consumer_interest, consumer_consent, identity_merge_event, identity_map, consumer_feature) — REVOKEd entirely from the merchant authenticated role, GRANTed to consumer_authenticated only, RLS-scoped to id = current_setting('app.current_consumer_id')::uuid (or the FK-equivalent). The other 2 (consumer_merchant_link, event) are the deliberate exceptions: tenant-scoped, merchant-authenticated-accessible, standard RLS — a merchant legitimately needs "which consumers are linked to my tenant" (POS loyalty lookup) and its own engagement-event stream. rewards.* and offers.* stay wholly tenant-scoped; consumer_authenticated gets zero direct grant on either schema — a consumer's own cross-merchant view (loyalty balances + active offers across every tenant they're linked to) goes exclusively through consumer.get_cross_tenant_activity(p_consumer_id uuid), a narrowly-scoped SECURITY DEFINER function that takes the consumer id as a parameter, never reads an ambient session GUC for its cross-tenant SELECT — closing a leak scenario where an ambiguous "session-variable elevation" implementation could bleed standing RLS access across a whole transaction.

Prerequisite closed, not deferred: pos.sale gained UNIQUE(id, tenant_id) (sale_id_tenant_id_unique) — a mandatory pre-migration audit confirmed 486 live rows, zero risk regardless of row count since id was already the sole PK. This is what makes rewards.loyalty_point_ledger.sale_id and offers.offer_redemption.sale_id real composite FKs rather than forward-refs. approvals.approval_request.source_module's CHECK was also widened to add 'offers' (445 live rows, a CHECK-widen never invalidates existing rows) — the AI-authored-offer review path now routes through the existing engine.

5 critical guards, all live-reproduced.

  1. The concurrency race — naive-vs-fixed A/B, the central finding this build closes. The design proposal's first draft used a two-trigger shape (BEFORE-check / AFTER-sync) for point redemption — independent verification found it exploitable. Live-reproduced both shapes side by side against a 100-point balance: the naive two-trigger shape, under 2 concurrent -80-point redemption transactions, let both pass their own stale-read check and landed the balance at -60 (a real overshoot, both redemptions succeeding when only one should). The fixed shape — a single atomic BEFORE INSERT statement (rewards.sync_loyalty_account_balance()) whose own UPDATE ... RETURNING balance_after_points takes a row lock, serializing concurrent writers — correctly resolved 3-of-5 concurrent -30-point redemption transactions against the same 100-point balance (100 - 3×30 = 10, the other 2 correctly rejected with insufficient points balance), with the final balance_points reconciling exactly to 10. Mirrored in offers.check_and_sync_offer_budget() for the equivalent offer-budget-cap race.
  2. AI margin bypass — zero-cost fail-closed + chk_offer_ai_requires_guardrail. offers.offer.provenance IN ('human_defined','ai_suggested','ai_auto_created'); the CHECK requires any non-human_defined offer to carry max_discount_percent or max_discount_amount_per_order — an AI-authored offer with zero guardrails is structurally impossible to insert. Separately, offers.check_and_sync_offer_budget()'s own margin-floor arithmetic (completing the design proposal's own trigger snippet, which stopped at "margin check proceeds only past this guard" without specifying the comparison) fails CLOSED, not open, against a zero/NULL avg_cost_cents — RAISE EXCEPTION 'cannot verify margin floor against a zero-cost item ... requires human review' rather than silently skipping the check.
  3. Refund clawback. offers.offer_redemption.redemption_type IN ('redeem','reverse'); a 'reverse' row requires a discount_amount_applied_cents < 0 (sign-flipped, chk_offer_redemption_amount_sign), a non-NULL note (chk_offer_redemption_reverse_requires_note), and a reversed_redemption_id pointing at the original (chk_offer_redemption_reverse_requires_original) — live-reproduced reversing a redemption correctly walks budget_used_cents and offer_code.redeemed_count back down through the same atomic trigger, not a separate code path.
  4. Negative-balance CHECK backstop. chk_loyalty_point_ledger_balance_after_points_nonneg on rewards.loyalty_point_ledger.balance_after_points and the trigger's own RAISE EXCEPTION (guard #1 above) are two independent layers — live-reproduced that even a hypothetical direct INSERT bypassing the trigger's own check would still be rejected at the CHECK, not just the trigger.
  5. The consumer_authenticated boundary, proven in both directions at the GRANT level. Live-confirmed via pg_catalog, not just RLS-predicate testing: consumer_authenticated has zero table privilege anywhere in the 17 merchant schemas (explicit REVOKE ALL ON ALL TABLES IN SCHEMA ... across all of them, plus schema-level REVOKE ALL ON SCHEMA ... and ALTER DEFAULT PRIVILEGES closing future tables too) — and, the other direction, authenticated (merchant) has zero table privilege on the 8 consumer-identity tables (explicit REVOKE ALL on each, re-applied after the schema's own blanket GRANT ... ON ALL TABLES — "blanket grant, then narrow the exceptions," the same pattern Remediation Phase 1's RLS wiring established). Neither role's access is RLS-predicate-dependent alone; both are structurally absent at the ACL layer first.

Append-only enforcement on 5 ledger/audit-shaped tables (consumer.event, consumer.identity_merge_event, consumer.consumer_consent, rewards.loyalty_point_ledger, offers.offer_redemption), reusing platform.reject_append_only_mutation() verbatim — matching every other append-only table in this codebase.

2 disclosed Finding-6-class arithmetic corrections found during THIS build (schema drifted from the design doc's own stated column counts, not schema mistakes — the codebase's established practice, per CLAUDE.md's standing rule, of building against the itemized column list and disclosing when a stated total doesn't match it):

  • consumer.consumer_identifier built as 9 cols, not the design doc's stated 10 — its own itemized column list (id, consumer_id, identifier_type, identifier_value, is_primary, is_verified, verified_at, superseded_at, created_at) only ever names 9; the stated "10" total was never reconciled against its own itemization.
  • offers.offer_targeting_rule built as 21 cols, not the design doc's stated 17 — its own itemized list undercounted itself by 4, omitting the standard created_at/updated_at/deleted_at triple plus created_by_actor_id that every other autonomy-pack table in this build carries. Built with the full triple + column, matching every sibling table, not the undercounted total.

Cross-module seams (real, not forward-refs) added this build: rewards.loyalty_point_ledger.sale_id → pos.sale(id, tenant_id) (composite, nullable) and offers.offer_redemption.sale_id → pos.sale(id, tenant_id) (composite, NOT NULL — v1's "THE REDEMPTION SEAM," required on every redemption) / .sale_line_id → pos.sale_line(id, tenant_id) (composite, nullable, the margin-floor verification target) — both riding the new pos.sale UNIQUE(id, tenant_id) prerequisite above. offers.offer_targeting_rule.segment_definition_id → crm.customer_segment_definition.id is a plain FK, not composite — cross-tenant integrity is instead DB-enforced by a dedicated trigger, offers.validate_offer_targeting_rule_segment() (mirrors pricing.trg_price_rule_validate_supersession's own precedent exactly), allowing a NULL-tenant (global/built-in) segment or one belonging to the same tenant, rejecting any other tenant's. consumer.event.site_id → multi_loc.site(id, tenant_id) (composite, nullable). Every *_actor_id column across both new tenant-scoped schemas → identity.actor.id, the standard autonomy-first pattern (PROJECT_DECISIONS #19) — consumer.*'s own 8 consumer-scoped identity tables deliberately carry NO actor attribution (a consumer acts for themselves, not through the tenant-side actor model).

Next. Regression tests (consumer-schema.spec.ts, rewards-schema.spec.ts, offers-schema.spec.ts) and the mandatory evidenced independent lock-gate verification are this same effort's immediate next steps, followed by docs fan-out completion and the formal lock. ConsumerService/RewardsService/OffersService (the HTTP controller layer) remain unbuilt — the next gap once schema locks.

57. Consumer + Rewards + Offers — Lock-Gate Verification Findings, Fixed Same Day, Module Locked

Decided: 2026-07-11, same day, immediately after #56. 73 regression tests written and passing (consumer-schema.spec.ts 27, rewards-schema.spec.ts 19, offers-schema.spec.ts 27), then a separate, independent adversarial agent ran the mandatory lock-gate verification against the live local database — not a rubber stamp: it found 2 real BLOCKERs and 1 real MAJOR, each live-reproduced twice before being reported, plus (via the test-writing pass, as a byproduct) one significant pre-existing, codebase-wide bug unrelated to this build's own new schema. All four are fixed in this entry, in a same-day migration (packages/db/migrations/20260711010000_consumer_rewards_offers_verify_fixes.sql) plus a separate shared-function fix (20260711020000_fix_uuid_generate_v7_search_path.sql).

BLOCKER 1 — the max_discount_percent guardrail silently no-op'd whenever offer.min_purchase_cents was NULL. The original trigger divided discount_amount_applied_cents by NULLIF(min_purchase_cents, 0) — a completely normal, commonly-unset nullable column with no CHECK forcing it. NULLIF(NULL, 0) is NULL, the division is NULL, and IF NULL THEN never fires (Postgres treats a NULL condition as not-true, not as an error) — the guard silently passed. Live-reproduced: an ai_auto_created offer with max_discount_percent=10 and min_purchase_cents left NULL accepted a ~$10,000 discount with zero rejection. The formula itself was also semantically wrong independent of the NULL bug — capping against the offer's own eligibility threshold rather than the actual sale amount being discounted. Fixed: the basis is now the real pos.sale_line.charged_amount_minor_units (or the full pos.sale.total_minor_units for an order-level redemption with no sale_line_id), with an explicit fail-closed rejection when that basis is zero or unresolvable — the same fail-closed philosophy already governing the zero-cost margin guard two lines below it in the same function.

BLOCKER 2 — rewards.loyalty_point_ledger's 'reverse' entries had zero sign or magnitude validation against the row they claim to reverse. Unlike offers.offer_redemption (which at least has chk_offer_redemption_amount_sign forcing reversals negative), nothing on the rewards ledger stopped a wrong-signed reverse. Live-reproduced: an earn of +500 followed by a 'reverse' row also carrying +500 (matching sign, not negated) was accepted, doubling the balance to 1000 instead of clawing it back to 0 — exactly the "does a clawback actually claw back" property this build's own original live-reproduction pass checked only for the correctly-signed case, never adversarially trying the wrong one. Fixed: rewards.sync_loyalty_account_balance() now looks up the reversed_ledger_id row when entry_type='reverse' and requires NEW.amount_points to be the exact negation of that row's amount_points — magnitude-matched, not just sign-checked, strictly stronger than offer_redemption's own precedent.

MAJOR — offer.max_redemptions and offer_code.max_redemptions were declared, clearly-intentioned cap columns that were never read or enforced anywhere. Only budget_cents was checked in the atomic trigger. Live-reproduced twice: a cap of 1 accepted 3 separate redemptions with zero rejection, both with and without a code. Fixed: a new maintained counter, offers.offer.redemption_count (net: redeem +1, reverse −1, same convention as offer_code.redeemed_count), folded into the same atomic-conditional-UPDATE statement already enforcing budget_cents — not a separate, unenforced read, closing the exact same concurrency-race class Finding 3 (#56) closed for the budget path. offer_code.redeemed_count's own existing UPDATE gained an equivalent cap check. offer.max_per_consumer is explicitly NOT fixed in this pass — same class of gap, but requires a new per-(offer, consumer) counter mechanism beyond this fix's own evidenced scope; logged to OPEN_ITEMS, disclosed rather than silently left unstated.

Pre-existing, codebase-wide bug (found as a byproduct, not scoped to this build) — platform.uuid_generate_v7() threw function gen_random_bytes(integer) does not exist under the real application connection. This function is the PK DEFAULT on ~25 append-only tables across the entire codebase (Remediation Phase 2, #38), not just this build's own 3 tables. Root cause, live-confirmed: gen_random_bytes() lives in the extensions schema; the postgres superuser role carries a role-level search_path override including extensions, but authenticator — the actual login role packages/db/src/client.ts's tenantDB()/consumerDB() connect as for every real application query — has no such override, so its session search_path is only "$user", public. The function is SECURITY INVOKER (default), so it ran with the caller's search_path, not a fixed one. This bug was invisible to every prior module's own live-reproduction pass, because none of them had ever exercised a real tenant-role INSERT into a uuid_generate_v7()-keyed table specifically (prior tests either used the admin/superuser bypass connection, or targeted gen_random_uuid()-keyed tables) — first actually exercised here because this build's own regression-test pass performed exactly that. Fixed: extensions.gen_random_bytes() is now explicitly schema-qualified inside the function, plus a defensive SET search_path = pg_catalog, public, extensions on the function itself. Live-reproduced via a real connection as authenticator (not postgres) with search_path matching the exact bug condition — the fix confirmed working for both this build's own tables and (spot-checked) ai.agent_execution, an unrelated pre-existing table sharing the same function.

All 3 fixes re-verified after landing: the exact exploit scenarios the independent verifier used were each re-run and now correctly rejected; the correctly-signed/compliant positive-control cases were also re-run to confirm no regression (a correct reverse still reconciles the balance to exactly its pre-earn value; a compliant discount within the real percent cap still succeeds). 10 new regression tests added across the 3 spec files covering all 3 fixes directly. Full apps/api suite: 1000/1000 passing (up from the 918 pre-build baseline), zero regressions anywhere else in the codebase.

Module locked. consumer/rewards/offers are now locked (2026-07-11) — 22 tables / 321 cols, schema-only (no service layer yet). Commit f1bffa5.

58. Files — Storage Architecture (Hybrid A, locked)

Decided: 2026-07-11. Before building the files module (design proposed and adversarially verified the same day — ~/Downloads/files-module-design-proposal-2026-07-11.md), this entry records the storage-architecture decision the design's storage_provider column had left implicit, so no future contributor has to re-derive it from a bare enum value. Full detail lives in docs/modules/module_spec/files.md §4; this entry is the decision-of-record.

Cloudflare R2 is the SOLE storage of record. Every file files tracks — images and documents alike — lives permanently in R2. Rationale: R2 charges $0 egress at any volume vs. S3's ~$0.09/GB, and Vrida is an image-heavy retail + consumer product (POS catalog photos, tenant-app product images, a consumer-facing image-browsing app) where egress, not storage, dominates cost. At an illustrative 5TB stored / 20TB egress per month: R2 ≈ $75/mo vs. S3 ≈ $1,915/mo — a ~25× difference that only grows with egress volume. R2 is S3-API-compatible, so this is a cost decision, not a rewrite.

AWS S3 is used ONLY as transient staging for AWS Textract's async path. Textract's synchronous API (AnalyzeExpense/DetectDocumentText) accepts raw bytes directly (≤10MB, single page) and needs no S3 at all — this covers the large majority of real invoices/receipts/POs. Only Textract's asynchronous API (StartDocumentAnalysis, required for large/multi-page documents) reads exclusively from S3; for that minority, the pipeline copies the R2 object to a temporary S3 bucket, runs Textract, and deletes the S3 copy — never a second copy of record. S3 is an implementation detail of the extraction service, not a storage tier files itself models — file.storage_provider is always 'r2' in every durable row; 's3' exists as one column of schema headroom for a possible future multi-provider split (e.g. Lambda/S3-Event-Notification integration, Glacier 7-year financial retention), not an active tier today.

Text extraction is tiered for cost, not architected around a single always-on OCR call. Tier 1 (PDF with a real text layer) extracts free, in-process, via PyMuPDF/pdfplumber — covers most vendor-issued digital PDFs. Tier 2 (scan/image, no text layer) routes to AWS Textract — sync API with zero S3 involvement for most documents, async + temporary S3 staging only for large multi-page scans. Tier 3 (structured field extraction — a PDF becoming a real vendor_invoice row with line items) rides Textract AnalyzeExpense and/or a Bedrock LLM call through the ai module's duty-granted, credit-metered agent path, routed through approvals for human confirmation before it becomes a live financial record — explicitly not part of the files module itself, which only owns the source file and the resulting plain text. The extracted text lands in document_chunk.text regardless of which tier produced it, so FTS and future semantic search are agnostic to extraction method. Schema surface: file.extraction_status (pending/extracted/needs_ocr/processing/failed) + file.textract_job_id.

pgvector in Postgres, not an external vector database (Pinecone/Weaviate). Tenant isolation for a multi-tenant RAG system is already solved in this codebase's own Postgres via RLS — moving vectors to an external store would re-solve that same isolation problem in a second system with its own access-control model, which is exactly where cross-tenant RAG leaks happen in practice. Keeping document_chunk.embedding (vector(1024)) inside a normal tenant-scoped, RLS-policed table means a similarity query run through tenantDB() cannot structurally retrieve another tenant's chunks, even if the query itself is written wrong. document_chunk/document_index are built now (the "vector spine," per this session's own prior locked decision) with embedding left NULL until semantic search actually activates — FTS via the generated search_vector column works immediately with zero embeddings populated.

Embedding dimension: vector(1024), Amazon Titan Text Embeddings V2 — Bedrock-native, avoiding a third-party model dependency inside an already-Bedrock-based stack (Cohere Embed v3 noted as a dimension-compatible alternative). A future model change means re-embedding from the already-stored document_chunk.text, never a re-OCR of the source file.

Cost model reference (R2, so the tradeoff stays legible without re-research): $0.015/GB-month storage, $0 egress, $4.50/M Class A ops (writes), $0.36/M Class B ops (reads); free tier covers the first 10GB + 1M writes + 10M reads/month.

See PROJECT_DECISIONS #59 for the module build this decision fed into.

59. Files — Module Build (schema-locked)

Decided: 2026-07-11, same day, immediately after #58. Builds the corrected design (~/Downloads/files-module-design-proposal-2026-07-11.md, post-independent-verification, all findings from that 3-lens design-phase verification fixed before this build started) — 6 tables / 89 cols: file (27), attachment (17, NEW), file_access_grant (16, v1 verbatim), tenant_storage_usage (8, renamed from file_storage_usage), document_index (10, NEW), document_chunk (11, NEW — the "vector spine," built now, populated later). This is the same shape of event as tax/crm/orders/purchasing/Consumer-Layer's own precedents: files was already a stale v1-carryover placeholder row (3 tables/43 cols, locked as a design 2026-06-11, never migrated), so this is a +3 tables/+46 cols delta to that existing row, not a new schema addition to the running MODULE_INDEX total. Migration: packages/db/migrations/20260711030000_files_module.sql.

Every v1 table/column survives — 2 disclosed renames (r2_key/r2_bucket→storage_key/storage_bucket; file_storage_usage→tenant_storage_usage), 1 widened CHECK (file.status +'ready', splitting "R2 confirmed" from "safe to serve"), 1 FK retarget (uploaded_by_user_id→uploaded_by_actor_id onto identity.actor, the standard autonomy-first pattern). Zero tables or columns consolidated or dropped.

files.file carries UNIQUE(id, tenant_id) from this build's own day one — a first for this codebase's history: every prior module needing this composite-FK prerequisite (tax, billing, purchasing, receiving, multi_loc, etc.) added it via a later reopen; here it was designed in from the start, since 8 other modules already hold forward-ref columns (admin.tenant_branding.logo_ref, admin.compliance_document.document_ref, inventory.stock_movement.photo_ref, inventory.item_image.file_id, receiving.goods_receipt.shipment_photo_ref, pos.sale.signature_ref, crm.customer_tax_certificate.document_ref, ai.import_file.file_id) waiting to become real composite FKs. That wiring is a dedicated, deferred follow-up bundle (logged to OPEN_ITEMS), not part of this build — bundling a 6-module coordinated reopen into Files' own first lock would be scope creep, mirroring the "header/line remediation" 2-batch precedent (#46-53) and the multi_loc site_id bundle (#54).

Foundation-layer discipline is the load-bearing design constraint. file.consumer_id and file_access_grant.grantee_customer_id are deliberately LOOSE, unenforced uuid columns (no .references()) — SCHEMA_CONVENTIONS.md §1 forbids a foundation schema FK-ing into the consumer or business layers, and files is foundation-layer. Independently confirmed live via pg_constraint: zero FKs exist from any files.* table into consumer.*.

The dual-principal (merchant/consumer) boundary closes at the GRANT layer, not just RLS. authenticated (merchant) gets the standard blanket GRANT/ALTER DEFAULT PRIVILEGES on the whole files schema. consumer_authenticated gets ZERO grant of any kind on files — by construction, plus an explicit belt-and-suspenders REVOKE (matching the consumer/rewards/offers build's own established defense-in-depth pattern, #56). The sole consumer read path is consumer.get_files_for_consumer(p_consumer_id uuid) — owned by the consumer schema (the permitted calling direction), SECURITY DEFINER, parameter-scoped (never reads an ambient session GUC), mirroring consumer.get_cross_tenant_activity()'s own established shape exactly. This design was corrected during the design-phase's own 3-lens verification (#58's design predecessor) — the pre-verification draft had the FK direction backwards, the function in the wrong schema, and a factually non-executable join; all three were fixed before this build started, not discovered during it.

document_chunk is deliberately NOT append-only — embedding (vector(1024), sized for Amazon Titan Text Embeddings V2) is populated later via a real UPDATE after initial insert. Re-indexing (a new extraction pass superseding a file's prior chunk set) SOFT-deletes the prior generation before inserting the new one — never a hard DELETE (SCHEMA_CONVENTIONS.md §6). search_vector (generated tsvector, GIN-indexed) works immediately with zero embeddings populated.

Live-reproduced guards (11 groups, all pass, run by the build itself and independently re-derived by all 3 verification lenses below): cross-tenant RLS isolation on files.file (42501, plus the DR-3 public-visibility bypass proven both ways); cross-tenant composite-FK rejection on attachment (23503); the entity_type closed-enum CHECK; the reviewer_not_creator CHECK; the file_access_grant grantee-presence CHECK (all 4 branches); tenant_storage_usage's partial-unique-per-tenant; document_index's composite FK + partial-unique; document_chunk's chunk_index nonneg CHECK; the soft-delete re-indexing round-trip (4 physical rows, 2 active, FTS matching only the active generation); the consumer-boundary function's correct scoping in both directions (right consumer → 1 row, wrong consumer → 0 rows); consumer_authenticated's rejection querying files.file directly (42501/insufficient_privilege).

Regression suite: apps/api/src/files/__tests__/files-schema.spec.ts, 40/40 passing, covering all of the above plus the NULL-in-CHECK sweep and a full column-count parity check.

Mandatory evidenced independent lock-gate verification — 3 separate parallel lenses, pasted and attributed, per SCHEMA_DESIGN_RUNBOOK §2.3.7. Each lens independently re-derived every claim against the live database and source (not the build's own report), inside rolled-back transactions, and each ran the actual jest suite themselves rather than trusting a prior pass/fail claim.

Lens A (foundation-layer boundary + dual-principal access model — the highest-stakes lens):

Confirmed zero FK from files.* into consumer schema (pg_constraint, verified twice, independently derived); file.consumer_id/file_access_grant.grantee_customer_id confirmed loose (zero FK constraints reference either); consumer.get_files_for_consumer() confirmed owned by consumer schema, SECURITY DEFINER, parameter-scoped, no current_setting() call anywhere in its body; has_schema_privilege('consumer_authenticated','files','USAGE') = false; zero rows in information_schema.role_table_grants for consumer_authenticated on any files.* table; went further than assigned and checked pg_default_acl/role-membership/rolbypassrls for hidden leaks — none found; live-reproduced SET LOCAL ROLE consumer_authenticated; SELECT id FROM files.file → ERROR: permission denied for schema files (schema-level denial); searched every function's prosrc codebase-wide for any other reference to files.* — get_files_for_consumer is the only one, no backdoor path exists. Cross-tenant composite-FK rejection reproduced directly (23503 on attachment_file_id_tenant_fkey). NULL-in-CHECK sweep of all 19 CHECK constraints found the boundary and enum CHECKs are all gated on NOT NULL columns; the 2 CHECKs touching nullable columns were reasoned through by truth table and confirmed NULL-safe, then live-tested both directions. "FAILS/GAPS/CONCERNS: None found." One neutral observation (not a defect): consumer.get_files_for_consumer() deliberately has no tenant filter, by design, matching get_cross_tenant_activity()'s own established cross-tenant shape.

Lens B (vector-spine mechanics — soft-delete, FTS, composite-FK prerequisite):

Confirmed document_chunk_file_id_chunk_index_unique is genuinely partial (WHERE deleted_at IS NULL); independently reproduced generation-1 insert → soft-delete → generation-2 insert with the same chunk_index, inside their own transaction (not reusing the build's own test) — 2 total rows, 1 active, zero errors; confirmed the only trigger on document_chunk is set_updated_at, nothing forces or blocks a hard DELETE. Confirmed search_vector is attgenerated='s' (a real STORED generated column) independent of embedding; live-inserted a chunk with embedding left NULL and matched it via FTS. Confirmed files.file's UNIQUE(id, tenant_id) and all 4 children's genuinely composite (2-column) FKs via conkey array length. Reproduced the cross-tenant FK rejection independently with a from-scratch 2-tenant fixture. Found 2 real, but purely documentation, gaps: (1) PROJECT_DECISIONS.md entry #59 (this very entry) did not exist at verification time — the migration/module-spec/OPEN_ITEMS all cited it as the build record, but it was never written until after this verification pass, exactly the gap this entry now closes; (2) flagged CLAUDE.md as allegedly missing any Files mention — independently re-checked by the parent session after this report and found NOT reproducible: CLAUDE.md did in fact contain the Files paragraph (confirmed via direct grep -c "module #26" = 1, and the file's own tail content) at the time this lens ran; this appears to be a stale-read artifact in that one lens, not a real gap — logged here for the record rather than silently omitted, since a false negative from a verification pass deserves the same disclosure as a true one.

Lens C (Section 4 audit + test-suite/column parity):

Ran the real jest suite themselves (40/40 passing, not a cached report). Independently dumped every column name/type/nullability/default per table and diffed against both the migration SQL and the Drizzle .ts files — identical, no drift; total 89 cols / 6 tables confirmed live. Confirmed RLS enabled with exactly one PERMISSIVE ALL TO authenticated policy per table, file's policy correctly implementing the DR-3 public-bypass-on-READ exception (no tenant_id IS NULL bypass). Confirmed all 6 tables have a set_updated_at trigger, none missing. Confirmed the migration's DOWN section drops children before the parent, REVOKEs before drops, extension/schema last — no ordering bug. One minor, non-blocking index-coverage note: document_index.file_id is only covered as the second column of a composite index, not a leading column — low severity since every real query path is already tenant-scoped, not a FAIL. Found 1 real, documentation-only gap: module_spec/files.md §10 names as a deferred item that CROSS_MODULE_CONTRACTS.md's Files seam section needs its file_storage_usage references updated to tenant_storage_usage — true, and while the module's own dedicated Files section had been correctly updated, a SEPARATE general "usage-here/limit-in-platform" pattern-summary line elsewhere in the same document (line 77) still said file_storage_usage, and no OPEN_ITEMS row existed for this specific, self-disclosed deferral despite the other 11 files-module deferrals all being correctly logged — "the claimed-but-unlogged deferral" bug class SCHEMA_DESIGN_RUNBOOK.md §5 item 11 names as a recurring failure mode. "No BLOCKER, no MAJOR, no live-data or security defect."

Both real (documentation-only) findings are fixed in this same entry's own pass: CROSS_MODULE_CONTRACTS.md line 77 now says tenant_storage_usage, and this entry (#59) itself closes the missing-build-record gap Lens B found. Zero schema, security, or data-correctness findings survived across all 3 lenses — the foundation-layer boundary and the dual-principal access model (this build's own highest-stakes surface, direct descendants of the very layer-violation the design-phase verification caught and fixed pre-build) were independently confirmed enforced at multiple simultaneous layers (FK absence, RLS, schema-level REVOKE, and function-parameter-scoping), not a single point of failure.

Module locked. files is now locked (2026-07-11) — 6 tables / 89 cols, schema-only (no service layer yet — FilesService is the next gap). See docs/modules/module_spec/files.md and docs/database/schema_docs/files.md for the full spec.

60. rewards + offers Reopen — Proportional (Partial) Reversal, Closing a Real Independent Offers Bug (Pass 1 of a 2-Pass Effort)

Decided: 2026-07-11, same day, as Pass 1 of a two-pass task (Pass 2 builds the returns module against the corrected returns-module-design-proposal-2026-07-11.md, which requires proportional loyalty/offer clawback to actually work). Migration: packages/db/migrations/20260711030000_rewards_offers_proportional_clawback.sql.

The problem, live-reproduced before any fix. rewards.sync_loyalty_account_balance() (built 2026-07-11, PROJECT_DECISIONS #57) hard-enforced exact, full negation only on a reverse entry — reverse ALL of an earn's points or NONE; a genuine partial return (e.g. 2 of 5 units) was rejected outright. Separately, and independent of returns — a real, live bug on its own merits — offers.check_and_sync_offer_budget() had NO magnitude check at all on a reversal, only the pre-existing sign CHECK (chk_offer_redemption_amount_sign). A $10 redemption could be "reversed" by a row claiming a $1,000 discount and the trigger's budget-cap UPDATE would not notice, since it only guards the aggregate budget_used_cents floor (>= 0), never the specific original redemption's own magnitude. Live-reproduced: with the pre-fix function temporarily reinstalled, a $10 (1000-cent) redemption padded by an unrelated legitimate $990 redemption on the same offer, then "reversed" by a fabricated -$1000 (-100000 cents) row — the erroneous reversal succeeded, zeroing budget_used_cents from 100000 to 0 by silently consuming the other, unrelated $990 redemption's legitimate budget rather than being rejected for its own wrong magnitude.

The fix — a cumulative-reversed tracker per original, capped atomically. Two new small, mutable tables — rewards.loyalty_point_ledger_reversal_tracker (7 cols: id, tenant_id, ledger_id, original_amount_points, total_reversed_points, created_at, updated_at) and offers.offer_redemption_reversal_tracker (7 cols, same shape: redemption_id, original_discount_amount_cents, total_reversed_cents) — one lazily-created row per original entry that has ever been touched by a reversal (INSERT ... ON CONFLICT (tenant_id, <fk>) DO NOTHING, snapshotting the original's magnitude on first touch). Why a separate table, not a column on the ledger/redemption row itself: both rewards.loyalty_point_ledger and offers.offer_redemption are append-only via platform.reject_append_only_mutation(), confirmed via pg_get_functiondef to be an unconditional RAISE EXCEPTION with no column-level exception mechanism — a maintained running-total column directly on either table would hit that trigger on the very first UPDATE. This mirrors offers.offer.budget_used_cents/.redemption_count's own precedent (a maintained counter on an otherwise-immutable header), generalized here to a case with no natural existing header to hold it.

The atomic cap — the same proven single-statement shape this codebase already uses (offers.check_and_sync_offer_budget()'s own budget-cap UPDATE, receiving's capped write-back trigger): UPDATE tracker SET total = total + :amount WHERE ... AND total + :amount <= original RETURNING ... — the WHERE clause's own cap check and the increment happen inside one row-locking UPDATE, so a concurrent second reversal blocks on the row lock and re-evaluates against the true post-serialization value. Zero rows returned ⇒ cap exceeded (or wrong sign, or the original wasn't found/isn't reversible) ⇒ RAISE EXCEPTION. The rejected shape — read-then-check-then-write across two separate statements — was deliberately NOT used, since it is the exact race this codebase already found and fixed once before (2 concurrent redemptions jointly overshooting a cap each individually respected, in the original consumer/rewards/offers build).

rewards.sync_loyalty_account_balance(): a reverse entry now lazily creates/updates the tracker row for its reversed_ledger_id, gated by sign(original_amount_points) = -1 * sign(NEW.amount_points) (generalizes correctly across earn(+)/redeem(-)/adjust(±) originals with no per-entry-type special-casing) and the cumulative-cap UPDATE. A new CHECK, chk_loyalty_point_ledger_reverse_nonzero (entry_type != 'reverse' OR amount_points != 0), is a belt-and-suspenders backstop — in practice the BEFORE INSERT trigger's own sign-match logic already rejects a zero-magnitude reversal first (sign(x) = -1*sign(0) = 0 never matches a real original's nonzero sign), so this CHECK is unreachable under normal operation but guards the case the trigger were ever bypassed.

offers.check_and_sync_offer_budget(): same treatment on offer_redemption — a lazily-created tracker row per reversed_redemption_id (the lazy-creation SELECT requires redemption_type = 'redeem' on the source, so attempting to reverse an already-reverse row finds no eligible original, the tracker row is never created, and the capped UPDATE matches zero rows and correctly rejects it). budget_used_cents still adjusts by the exact (possibly partial) amount on every redeem/reverse — real money, always applies in full. redemption_count/offer_code.redeemed_count (integer counts of distinct events, not dollar figures) now only decrement by 1 when a reversal's own cumulative total exactly equals the original discount amount (v_fully_reversed := (v_new_total_reversed = v_original_discount)), preventing a fractional/nonsensical count change on a merely-partial reversal — this is a genuine design refinement beyond what either module previously had, not present in the original 2026-07-11 build.

A correction to the returns design proposal, made explicit per the task's own instruction: returns-module-design-proposal-2026-07-11.md's UNIQUE (reversed_ledger_id) WHERE entry_type='reverse' constraint is now WRONG given this fix — multiple partial reversals against one original row are legal, so a unique constraint on the FK column itself would reject the second legitimate partial reversal outright. It was not added; the tracker's own cumulative CAP is the correct guard, not a uniqueness constraint on the reference.

Live-reproduced (every named guard, both modules):

  • rewards: (a) a PARTIAL reversal (-200 of +500) SUCCEEDS — previously rejected outright; (b) a further reversal that would push the cumulative total over the original (200+400=600>500) is REJECTED; (c) the EXACT remainder (-300, cumulative 500) SUCCEEDS, zeroing the account balance; (d) a further reversal against the now-fully-exhausted original is REJECTED; (e) wrong-sign and reverse-of-reverse are both REJECTED; (f) 3 concurrent -200 reversal attempts against one +500 earn, launched via genuinely simultaneous backgrounded psql processes: exactly 2 succeeded (cumulative 400), 1 was rejected — the tracker's own total_reversed_points confirmed at exactly 400, never 600, and the account balance reconciled correctly throughout (500+500-400=600, lifetime unaffected by reversals). The naive read-then-check-then-write shape was independently demonstrated to actually break under the identical race: a standalone throwaway function replicating that shape, fired with the same 3 concurrent -200 calls against an original cap of 500, let all 3 succeed, ending at total_reversed_points = 600 > 500 — proving the atomic shape isn't a redundant precaution.
  • offers: (a) the exact pre-fix bug scenario ($10 redemption, wrongly reversed by $1000) now REJECTED with the pre-fix success independently reproduced first (see above) by temporarily reinstalling the verbatim pre-fix trigger body, confirming it, then restoring the fixed version before any further tests ran; (b) a partial reversal (-400 of 1000) SUCCEEDS, releases budget_used_cents by the exact partial amount, and does NOT decrement redemption_count; (c) a cumulative-exceeding reversal (400+700=1100>1000) is REJECTED; (d) the exact remainder (-600, cumulative 1000) SUCCEEDS and decrements redemption_count by exactly 1 (fully-reversed); (e) a further reversal against the fully-exhausted original is REJECTED; (f) reverse-of-reverse is REJECTED; (g) 3 concurrent -400 reversals against one 1000-cent redemption: exactly 2 succeeded (cumulative 800), 1 rejected, tracker confirmed at exactly 800.

NULL-in-CHECK sweep: all 3 new/changed CHECK constraints (chk_loyalty_point_ledger_reversal_tracker_total_reversed_bounds, chk_offer_redemption_reversal_tracker_total_reversed_bounds, chk_loyalty_point_ledger_reverse_nonzero) reference only columns confirmed NOT NULL live via information_schema.columns — none is reachable via a NULL-bypass.

Column/table deltas: rewards 6→7 tables, 102→109 cols (+7, exactly loyalty_point_ledger_reversal_tracker). offers 6→7 tables, 115→123 cols (+8: +7 for offer_redemption_reversal_tracker, +1 a pre-existing, this-fix-unrelated drift independently discovered while reconciling counts — offers.offer is live-confirmed at 43 columns, not the 42 the 2026-07-11 build's own MODULE_INDEX entry recorded; the extra column (redemption_count, added same-day by that build's own lock-gate verification fix pass per PROJECT_DECISIONS #57) was never reflected in the MODULE_INDEX row's column count at the time — same class of pre-existing count drift this codebase has disclosed-not-silently-fixed before (e.g. shared's 12-column Phase 4 drift); not touched or caused by this fix).

Regression tests: rewards-schema.spec.ts §H fully rewritten (the old exact-negation-only tests actively asserted behavior this fix deliberately supersedes) — 8 tests including a genuine Promise.allSettled-based 3-way concurrent race against the real DB. offers-schema.spec.ts gained new §K (5 tests). Both files' §A table-count assertions updated 6→7. Full apps/api suite: 1052/1052 passing (up from the 1040 baseline; net +12 across both files).

Pass 1 of 2 — Pass 2 (the returns module build, consuming this new proportional-clawback capability) follows in the same session; see the next PROJECT_DECISIONS entry for its own lock.

61. returns — Customer RMA Module Build (Pass 2 of a 2-Pass Effort), Proportional Clawback Now Working

Decided: 2026-07-11, same day, immediately after Pass 1 (#60). Builds the corrected design (returns-module-design-proposal-2026-07-11.md, post-3-lens-independent-verification) — 9 tables / 152 cols: return_authorization (29), return_authorization_line (28), return_source_line_tracker (10, NEW — closes the design's own Lens A Finding 1), return_resolution (21), return_resolution_line (8, append-only), return_receipt (14), return_receipt_line (16), return_reason (10), warranty (16, revived v1 pos.guarantee). Migration: packages/db/migrations/20260711040000_returns_module.sql. Column counts confirmed identical between the Drizzle schema files, the migration, and the live DB (152 total via information_schema.columns) — zero drift.

Deviation from the design's own Block 4, per this task's explicit Architect Decision 2: the design proposal deferred proportional loyalty/offer clawback as out-of-scope for v1, since rewards/offers' own reversal triggers (at design time) supported only exact-full-negation or unvalidated-magnitude reversal. Pass 1 (#60), run immediately before this build in the same session, closed that exact gap. This build therefore implements proportional clawback as a REAL, WORKING capability from day one — not deferred — by having return_resolution.loyalty_reversal_ledger_id / .offer_reversal_redemption_id link to 'reverse'-typed rows written using rewards/offers' own now-proportional mechanism. returns never re-implements loyalty/offer math, exactly as it never re-implements refund math (pos.sale_refund stays the one source of truth for money) — this is a genuine "returns calls the module that owns it" seam, not a new authority.

5 small companion reopens bundled into this same migration: pos.sale_refund/sale_refund_line and orders.order_header/order_line each gained UNIQUE(id, tenant_id) (all 4 were PK-only before this build); inventory.stock_movement.source_module, approvals.approval_request.source_module, and files.attachment.entity_type CHECKs were each widened to accept a returns-related value ('returns', 'returns', 'return_authorization' respectively). The design's own originally-planned rewards/offers reopens (2 new partial-unique indexes) are obsolete and were NOT applied — Pass 1 already built the correct mechanism, and the design's own proposed UNIQUE (reversed_ledger_id) WHERE entry_type='reverse' would have been actively WRONG given proportional reversal is now legal (multiple partial reversals against one original row).

The 3 new trigger functions, all BEFORE INSERT, all reusing this codebase's own proven atomic patterns:

  • returns.check_and_reserve_source_line() (on return_authorization_line) — the aggregate-cap fix for design Lens A Finding 1: lazily creates a return_source_line_tracker row (INSERT ... ON CONFLICT (tenant_id, sale_line_id) WHERE sale_line_id IS NOT NULL DO NOTHING — a real bug caught and fixed during this build's own live-reproduction: the first draft's ON CONFLICT clause omitted the WHERE predicate needed to match a partial unique index, since — unlike Pass 1's own single-nullable-column trackers — this tracker has two mutually-exclusive nullable alternative columns, sale_line_id/order_line_id), then caps total_authorized_qty/total_eligible_refund_cents atomically via the same UPDATE ... WHERE ... <= ceiling RETURNING shape offers.check_and_sync_offer_budget() already uses.
  • returns.validate_and_apply_resolution_line() (on return_resolution_line) — the corrected cap mechanism for design Lens A Finding 2: sums resolved_amount_cents across every sibling row sharing the same return_authorization_line_id, regardless of which return_resolution header each belongs to, against that line's own eligible_refund_cents ceiling — race-free via an explicit SELECT ... FOR UPDATE row lock on the RA line taken before the SUM (serializing concurrent resolution-line inserts against the same line). Also maintains credited_qty (capped against authorized_qty, the peer counter to received_qty) and reconciles resolved_amount_cents against sale_refund_line.refunded_amount_minor_units when sale_refund_line_id is populated (closes design Lens A Finding 4 — the duplicate-money-fact class).
  • returns.post_and_cap_return_receipt_line() (on return_receipt_line) — derives the absorbable quantity itself via SELECT ... FOR UPDATE on the target RA line, then posts inventory.stock_movement/stock_movement_line atomically in the same invocation using the derived (capped) quantity, never the raw caller-supplied value. Tolerance policy: BLOCK, not flag — a deliberate, disclosed deviation from receiving.goods_receipt_line's own "flag" default, since a customer physically returning goods twice against the same authorization is a materially more dangerous default to leave un-gated pending review. This is the corrected, second-round shape of receiving's own trigger (which needed 2 independent verification passes to get right) — applied here from day one, not repeating receiving's own first, weaker draft.

Live-reproduced (14 sub-guards, sequential, plus a genuine concurrency proof, all against the real local DB):

  • Discount allocation (Architect Decision 1): a $150 basket (2 lines, $100 + $50) with a 20%-off basket-wide offer — returning the $100 line correctly refunds $80, not $100 (allocated_discount_cents = 10000/15000 × 3000 = 2000; effective_unit_price_cents = (10000−2000)/1 = 8000).
  • Aggregate over-return cap: a second, separate RMA against an already-fully-returned line is rejected; a genuine 3-way concurrent race (3 backgrounded psql processes, real simultaneous connections) against a fresh 5-unit line, each requesting qty=2 — exactly 2 of 3 succeeded (cumulative 4, correctly capped under 5), 1 rejected; the tracker's own total_authorized_qty confirmed at exactly 4, never 6.
  • Proportional clawback (Architect Decision 2) — the capability this whole 2-pass effort exists for: buy 5 shrubs with 100 loyalty points earned + a $10 line-scoped offer redeemed → return 2 of 5 → exactly 40 points clawed back (2/5 of 100) and exactly $4.00 of offer budget released (2/5 of $10) via the Pass-1-built proportional mechanism; a second partial return (1 more, cumulative 3/5) correctly clawed back an ADDITIONAL 20 points + $2.00, cumulative 60 points/$6.00 — proving no double-clawback; an over-clawback attempt (70 more, would total 130 > 100) was correctly rejected by Pass 1's own cumulative-cap tracker.
  • Idempotent inventory posting: a return_receipt_line insert posts a real inventory.stock_movement (movement_type='returned', source_module='returns'); a replayed/duplicate receipt attempt against an already-fully-received line is BLOCKED (not flagged), confirmed exactly 1 stock_movement row exists afterward — never double-posted; the reversal_of_return_receipt_line_id self-referencing FK (mirroring goods_receipt_line's own precedent) resolves correctly.
  • Warranty/plant-guarantee no-physical-receipt flow: a return_type='warranty_claim' RA with physical_receipt_required=false gets NO return_receipt at all; resolves directly via resolution_type='replacement'; credited_qty reached authorized_qty (1) while received_qty stayed 0 forever — the independent-peer-counter design (not a chain) working as intended.
  • Restocking fee arithmetic (Architect Decision 3): a $40.00 effective price minus a $5.00 restocking fee correctly yields $35.00 eligible refund (not $40 or $50) — the fee reduces the refund directly and is never separately taxed.
  • Unreferenced/blind return: accepted with NO source_sale_id/source_order_id/customer_id at all, item_variant_id fallback, full risk-tiering (risk_score=75, risk_tier='high') — anonymous walk-in returns are structurally supported, consistent with this codebase's own Phase 4 ALLOW decision (#40).
  • sale_refund stays referenced, not absorbed: every resolution's pos_sale_refund_id points at a genuine pos.sale_refund row created independently by this test narrative — confirmed live.
  • Cross-tenant RLS rejection: a crafted cross-tenant return_authorization insert (claiming a different tenant_id) is rejected with 42501.

NULL-in-CHECK sweep: every new CHECK constraint across all 9 tables references only NOT NULL columns or uses explicit IS NULL/IS NOT NULL-disjunctive forms (e.g. chk_return_authorization_warranty_requires_type: warranty_id IS NULL OR return_type = 'warranty_claim'; chk_return_source_line_tracker_exactly_one_source: (sale_line_id IS NOT NULL) != (order_line_id IS NOT NULL)) — confirmed none is reachable via a NULL-bypass.

Regression tests: apps/api/src/returns/__tests__/returns-schema.spec.ts, new file, 31/31 passing, covering all of the above (table/RLS/column-count existence, discount allocation, sequential + concurrent aggregate cap, proportional clawback + over-clawback rejection, idempotent posting + BLOCK-not-flag over-receipt, warranty no-receipt flow + the conditional-warranty CHECK, restocking fee arithmetic, unreferenced return, cross-tenant RLS, and all 5 companion-reopen constraint/CHECK confirmations). Full apps/api suite: 1083/1083 passing confirmed serially (--runInBand) — one pre-existing, already-disclosed cross-file concurrency flake (admin-tenants.spec.ts, OPEN_ITEMS row on platform.tenant-touching spec parallelism, confirmed unrelated: passes 32/32 in isolation and 1083/1083 serially) intermittently reproduces under parallel Jest workers, not caused by this build.

Section 4 self-audit: Items A (column drift: zero, 152/152 confirmed live), B (RLS: all 9 tables enabled + tenant-isolation policy, cross-tenant rejection live-tested), C (NULL-tenant_id trap: N/A, no nullable tenant_id anywhere in this module), D (soft-delete partial uniques: return_reason/return_authorization/return_receipt all correctly WHERE deleted_at IS NULL-scoped; return_source_line_tracker and return_resolution_line deliberately have no deleted_at at all, mirroring offers.offer_redemption_reversal_tracker's and billing.ar_charge_line's own precedents respectively), E (partial-index enum references: warranty_tenant_id_status_idx ... WHERE status='active' confirmed valid against warranty's own CHECK enum), F (CHECK completeness: every enum used across all 14 live-reproduced sub-guards stayed within its own CHECK, zero violations on legitimate data), G (forward-ref FKs: warranty.signature_ref deferred to the existing Files FK-wiring bundle, disclosed not new), H (cross-module FK names: every composite FK verified against live \d output before writing the schema, zero mismatches), I (money derivation: effective_unit_price_cents/eligible_refund_cents formulas documented inline and in this entry), J (JSONB shapes documented: risk_factors, condition_assessment, terms_snapshot), K (tenant_id index present on all 9 tables), L (query-pattern indexes present: open-RMA sweep, the resolution-cap trigger's own grouping key, active-warranty lookup), M (conditional-column consistency: 3 real CHECKs/triggers, not just documented rules — warranty_id/return_type, resolution_type='refund'/pos_sale_refund_id, sale_refund_line_id reconciliation — all live-tested), N (no conflicts with any other locked module's decisions; this entry itself implements this session's own 4 Architect Decisions), O (N/A, no non-RLS tables), P (module-level rationale recorded in this entry: the tracker-mirroring pattern, the header-is-truth grouping-by-child-FK choice for return_resolution_line's cap mirroring purchasing.vendor_credit_line's own precedent, the BLOCK-not-flag deviation, the independent-peer-counter design for received_qty/credited_qty, and the explicit non-adoption of the design's own now-obsolete rewards/offers reopen plan), T (trigger audit: all 3 new triggers BEFORE INSERT, live-reproduced under both sequential and genuine concurrent load, race-free via row locks or atomic capped UPDATEs, set_updated_at reused verbatim on all 7 mutable tables, append-only reused verbatim on return_resolution_line).

returns is now locked (module #27) — 9 tables / 152 cols, schema-only (no service layer yet — ReturnsService is the next gap, matching every other schema-only module's own established pattern). pos, orders, inventory, approvals, and files are all re-locked (constraint/CHECK-widen only — zero table/column count impact on any of the 5). This closes the entire 2-pass session (Pass 1: rewards/offers proportional-reversal fix, #60; Pass 2: returns module build, this entry) — see the final combined report for both passes.

Addendum — independent lock-gate verification (3 lenses, Workflow, separate agents, run against the live DB after the above was written): found 2 real issues, both fixed before the lock above became final, plus 1 disclosed-not-fixed limitation:

  1. [FIXED, MAJOR] return_authorization.reason_id and return_authorization_line.reason_id were bare (non-composite, non-tenant-scoped) FKs into the tenant-scoped return_reason catalog — inconsistent with this module's own stated composite-FK convention (every other cross-reference in this migration is composite) and with the schema_docs, which had already (over-eagerly) documented them as composite. Live-exploited: as role authenticated scoped to tenant B, a return_authorization row was successfully inserted referencing a return_reason row owned by tenant A — accepted with no rejection (not a SELECT-level RLS leak, since RLS still hides tenant A's row from tenant B's reads, but a genuine referential-integrity gap). Fixed live and in-migration: added return_reason_id_tenant_id_unique UNIQUE(id, tenant_id) as a prerequisite, then retargeted both FKs to real composite (reason_id, tenant_id) REFERENCES returns.return_reason(id, tenant_id). Re-reproduced: the same cross-tenant insert is now rejected (23503); the identical insert without reason_id still succeeds, isolating the fix. Table/column counts unchanged (constraint-shape-only). 2 new regression tests added (returns-schema.spec.ts Section K).
  2. [FIXED, MINOR] returns.validate_and_apply_resolution_line()'s own cap-check logic (IF v_existing_sum + NEW.resolved_amount_cents > v_eligible THEN RAISE, and the analogous qty check) used plain comparisons, which are not NULL-safe — Postgres treats IF <NULL> as false, silently skipping the RAISE. Unlike the sibling check_and_reserve_source_line()'s UPDATE ... WHERE ... RETURNING idiom (NULL-safe by construction: a NULL comparison simply matches zero rows), this trigger's cap was only unreachable in practice because resolved_qty/resolved_amount_cents are themselves column-level NOT NULL — a coincidental backstop, not a designed one. Fixed by adding an explicit IF NEW.resolved_amount_cents IS NULL OR NEW.resolved_qty IS NULL THEN RAISE EXCEPTION ... guard at the top of the function, live-reproduced (a NULL resolved_qty insert is now rejected with the new guard's own message; a valid row still succeeds). 2 new regression tests added (returns-schema.spec.ts Section L).
  3. [DISCLOSED, NOT FIXED] The per-line money-derivation formulas on return_authorization_line (allocated_discount_cents, effective_unit_price_cents, eligible_refund_cents, and the restocking-fee arithmetic) are not themselves DB-enforced — only non-negativity (chk_return_authorization_line_money_nonneg) and the aggregate ceiling against the original source line (return_source_line_tracker) exist as backstops. Live-reproduced: a row with effective_unit_price_cents=1/eligible_refund_cents=14999 (should be ≈3000/6000) was accepted outright, since 14999 stayed under the tracker's own ceiling — a wrong-but-in-bounds combination passes every constraint that exists today. This is judged not a returns-specific regression: the identical class of gap already exists on every other line-level pricing table in this codebase (pos.sale_line, orders.order_line — both non-negativity-only, no derivation CHECK anywhere), so a new, first-of-its-kind formula-verification trigger here would deviate from established convention rather than close a returns-introduced hole. Deliberately not fixed this pass; loudly flagged instead — see OPEN_ITEMS — since ReturnsService (not yet built) is exactly where this arithmetic must be implemented and unit-tested correctly, given the DB will not catch a formula error.

2 minor documentation-only mismatches were also found and corrected in the same pass (no schema/behavior impact): the resolution-line trigger's name in schema_docs/returns.md (trg_return_resolution_line_validate_and_apply → the real trg_return_resolution_line_validate_against_authorization_line), and return_receipt's autonomy-tier label (schema_docs said "no autonomy pack," module_spec correctly said "LIGHT" — both now say LIGHT, matching its real received_by_actor_id/voided_by_actor_id/void_reason attribution columns).

Full apps/api suite re-verified green after all fixes: 1088/1088 (1083 + 5 new regression tests: K1–K3, L1–L2).

62. platform Reopen (6th) — Module Registry + AI Capacity/Regional Policy (agents-v2/v3 Build, Phase 1 of 6)

Decided/built: 2026-07-12. Build authorization for the full agents/semantics/signals build (design of record: vrida-agents-v2-design-amendment-2026-07-11.md as amended by vrida-agents-v3-correction-pass-2026-07-12.md, v3 winning on conflict) is now underway, sequenced in 6 phases per the authorization's own sequencing guard (each phase's independent lock-gate verification must come back clean before the next begins). This entry is Phase 1: platform reopen — 7 new tables, 0 existing tables altered: module_catalog, tier_module_entitlement, tenant_module_activation, module_dependency (A1) + ai_capacity_policy, tenant_ai_capacity_usage, tenant_regional_policy (A8/E4/E7). platform is now 34 tables (up from 27). Migration: packages/db/migrations/20260712000000_platform_module_registry_capacity.sql.

module_catalog replaces the closed CHECK-enum module-tag pattern every polymorphic module column in this codebase has used until now — module_code UNIQUE, layer CHECK IN (foundation/business/consumer), lifecycle_status a SINGLE column (not split lifecycle/implementation, per v3's own A1 decision — this codebase's module pipeline is strictly linear) CHECK IN (planned/designed/in_build/active/deprecated/retired), guarded by a real BEFORE UPDATE OF lifecycle_status trigger enforcing forward-only transitions (or a jump to deprecated/retired from any state). Seeded with all 25 modules — the 22 already-locked modules at lifecycle_status='designed' (platform/identity at in_build, matching their real service-layer status) plus agents/semantics/signals at 'designed' (design is done; each phase's own migration will bump its module to 'in_build' as it lands).

is_toggleable replaced by 3 real tables (tier_module_entitlement, tenant_module_activation, module_dependency), not one — closing a functionally-dead mechanism research found earlier in this same effort (hasEntitlement() had zero callers anywhere in the codebase). module_dependency gets real recursive cycle detection (WITH RECURSIVE reachable AS (...), not just the direct self-reference the CHECK already covers) and a reverse-dependency-on-deactivation guard (I7) — reject, not auto-cascade, deactivating a module for a tenant while another active module for that same tenant still hard-depends on it.

ai_capacity_policy/tenant_ai_capacity_usage implement the A8/E4 6-level precedence chain's atomic enforcement half — a single shared policy-binding table (not 6 separate ones), NULL-means-unbounded per this codebase's own established convention. The atomic spend-increment function (platform.try_increment_ai_capacity_spend) embeds the resolved ceiling as a correlated subquery inside the SAME UPDATE ... WHERE ... RETURNING statement — never a preceding SELECT. tenant_regional_policy (E7) gives each tenant one resolvable regional-placement policy for the later phases' routing/fallback/storage/retrieval/archival decisions to evaluate against.

Live-reproduced (4 guards, all via real concurrent psql sessions where applicable, matching this build authorization's own evidence standard):

  • Lifecycle transition guard: designed → in_build → active (legal, succeeds) then active → designed (illegal backward transition) correctly rejected with illegal lifecycle_status transition active -> designed; deprecated confirmed reachable from any state.
  • Recursive cycle rejection: a 3-hop chain (crm → inventory → pos, all hard) built successfully; the cycle-closing edge (pos → crm) correctly rejected with would create a dependency cycle.
  • Reverse-dependency-on-deactivation: with crm (hard-depends on inventory) and inventory both active for a real tenant, deactivating inventory correctly rejected with an active module still hard-depends on it; deactivating a module with no active dependents succeeds.
  • Atomic capacity race: a platform-wide 1000-cent ceiling, 3 genuinely concurrent 400-cent spend attempts (sum 1200 > ceiling) — exactly 2 of 3 succeeded (running total 800), the 3rd correctly returned NULL (would have exceeded); final current_spend_cents confirmed ≤ 1000, never exceeded. All ad hoc guard-verification test data (dependency edges, activation rows, capacity rows) cleaned up from the shared dev DB after verification, confirmed via a fresh row-count check.

NULL-safety sweep (both variants, per this build authorization's own explicit discipline): every CHECK in this migration references only NOT NULL-backed columns or an explicit IS NULL/IS NOT NULL branch (e.g. chk_ai_capacity_policy_scope_ref_consistency branches on scope_ref IS NULL directly rather than assuming a value) — no FALSE-OR-NULL=NULL bypass possible. Every UNIQUE index's key columns (module_code, (tier_id,module_id), (tenant_id,module_id), (module_id,depends_on_module_id), (tenant_id,period_start), tenant_id) are NOT NULL — no NULL-distinctness bypass possible (the exact class of gap an earlier pass in this same design effort found and fixed on outcome_observation, not repeated here).

Regression tests: apps/api/src/platform/__tests__/platform-module-registry.spec.ts, new file, 16/16 passing — table existence, all 4 live-reproduced guards (as jest assertions against .cause.message/.cause.constraint_name, matching this codebase's own established pattern for asserting on wrapped Postgres trigger/CHECK errors), RLS-enabled confirmation on all 3 tenant-scoped tables, and seed-data confirmation (25 modules, agents/semantics/signals at designed not active).

Composite-FK/partition-key prerequisite check (Phase 0, this build's own pre-flight discipline): none of this phase's 7 tables are composite-FK targets from any other table in the v2/v3 design (module_catalog.id is referenced as a bare FK from later phases, since it is itself a global, non-tenant-scoped catalog — no UNIQUE(id,tenant_id) is needed for a bare-FK target, only the PK, which already exists). No prerequisite gap found or deferred.

Schema-only, as every phase of this build will be until Phase 5 lands the agents module itself — no service-layer changes in this phase.

Addendum — independent lock-gate verification (separate agent, live Postgres + live repo access, run against the completed build above), 4 findings, all fixed before Phase 2 was authorized to proceed, per this build's own sequencing guard:

  1. [FIXED, BLOCKER] module_catalog, tier_module_entitlement, module_dependency, and ai_capacity_policy were, in the live database, freely INSERT/UPDATE/DELETE-able by the ordinary authenticated role — directly contradicting this migration's own written claim ("authenticated gets SELECT only") and defeating this phase's entire stated purpose. Root cause: packages/db/migrations/20260708150000_phase1_rls_wiring.sql's standing ALTER DEFAULT PRIVILEGES IN SCHEMA platform ... GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO authenticated applies automatically to every new table in platform at CREATE TABLE time — before this migration's own narrower GRANT SELECT statements ever ran, and Postgres GRANTs are additive, so the narrower grant never revoked what the default privilege already conferred. Live-exploited (a tenant-scoped authenticated session could delete the platform-wide ai_capacity_policy ceiling outright) and live-reproduced-closed: explicit REVOKE INSERT, UPDATE, DELETE ... FROM authenticated added to the migration for all 4 tables; the identical exploit now correctly fails with 42501. 3 new regression tests added (platform-module-registry.spec.ts Section H).
  2. [FIXED, MAJOR] platform.try_increment_ai_capacity_spend's ceiling check applied unconditionally to EVERY delta, including negative ones (refunds/corrections) — meaning a refund attempted when no ai_capacity_policy row resolved for any scope would silently fail (return NULL) exactly like a real over-budget rejection, with no way to distinguish the two. Live-reproduced (a $5.00 refund against a tenant with 0 resolvable policy rows returned NULL, the counter never decremented) and fixed: p_delta_cents <= 0 now bypasses the ceiling check entirely and always succeeds — a refund can never violate a ceiling by construction. A default interim platform-wide policy (max_cost_cents=100000000, disclosed as a placeholder, not a production-tuned value) was also seeded so positive spends aren't perpetually blocked from day one pending real business limits. 2 new regression tests added (E4, E5).
  3. [FIXED, MAJOR] ai_capacity_policy.priority — documented in the design (A8) as the tie-break mechanism when multiple rows exist for the same scope — was vestigial; the resolver always took MIN(max_cost_cents) across every matching row regardless of priority. Fixed: each scope now resolves via ORDER BY priority DESC, max_cost_cents ASC LIMIT 1 (highest priority wins; ties broken toward the stricter/smaller ceiling), then LEAST() across the 3 resolved scope values as before. 1 new regression test added (E6).
  4. [FIXED, MAJOR] module_catalog's seeded multi_loc row was classified layer='foundation', contradicting docs/database/SCHEMA_CONVENTIONS.md §1's own explicit, pre-existing Business-layer list (multi_loc is named there). Unlike tax/approvals/receiving/returns (genuinely absent from that doc's list, a judgment call), this was a direct, undisclosed contradiction of an existing entry. Fixed: reseeded multi_loc at layer='business'. 1 new regression test added (G2).

All 4 fixes are in the migration file itself (not a separate follow-up file, since the migration had not yet been committed) — packages/db/migrations/20260712000000_platform_module_registry_capacity.sql reflects the corrected, final state. platform-module-registry.spec.ts is now 23/23. Everything the verifier confirmed clean on its first pass (all 4 originally-claimed live-reproduced guards, the full NULL-safety sweep, the atomic-race proofs including a second race shape for brand-new tenant/period rows, barrel exports, typecheck) required no changes.

Addendum 2 — formal Section 4 self-audit (A-P+T+U, read-only pass, run separately from the independent verification above per this build authorization's own explicit "Section 4 audit before each lock" requirement):

Full A-P+T+U findings table run against the built schema (all 7 tables): A column drift PASS (per-table counts 8/7/10/5/10/10/14 = 64, verified live via information_schema.columns, matches Drizzle exactly, matches migration exactly). B RLS per table — PASS for module_catalog/ai_capacity_policy (explicit "No RLS" comment already present) and the 3 tenant-scoped tables (RLS enabled); GAP on tier_module_entitlement/module_dependency (RLS-not-applied status was true but undocumented) — fixed, explicit "No RLS: global reference data" comments added to both. C/D/E N/A (no nullable tenant_id+UNIQUE combination, no soft-delete columns, no partial indexes exist in this table set). F CHECK completeness PASS (all 7 CHECKs cross-checked against their documented state space, no gap found). G/H PASS (no forward-ref FKs; activated_by_actor_id → identity.actor and tier_id → platform.tier_definition both verified against actual locked table names). I N/A (no derived-money columns in this table set). J JSONB shape — GAP on tenant_regional_policy's 7 JSONB columns (no example shape documented, matching a pre-existing gap in the source v2 design doc itself, not introduced here) — fixed, example shapes added as inline comments (region-code arrays for the 4 allowed_*_regions columns; object shapes for provider_restrictions/retention_requirements/classification_restrictions). K PASS (all 3 tenant-scoped tables have tenant_id as leading column of at least one index). L query-pattern indexes — GAP: check_no_active_dependents_before_deactivation's reverse lookup (WHERE depends_on_module_id = ...) had no supporting index (the existing unique index leads with module_id) — fixed, module_dependency_depends_on_module_id_idx added. M PASS (ai_capacity_policy.scope_ref's dependency on scope_type is CHECK-enforced for the NULL/NOT NULL half; the polymorphic-target half is disclosed app-enforced, matching item M's own allowance for when no structural DB check is possible, same shape as billing.ar_charge.source_ref). N PASS (seeded interim capacity ceiling and module lifecycle states cross-checked against no contradicting locked decision). O PASS (non-RLS global tables' access rule — authenticated: SELECT only, writes admin/service_role-only — documented in the migration's own GRANT-section comment, matching this codebase's established tier_definition precedent). P PASS (rationale recorded both inline in the Drizzle files and in this PROJECT_DECISIONS entry). T trigger audit — PASS on firing-events/edge-case/rationale for all 5 triggers; GAP: trg_tenant_module_activation_check_dependents was BEFORE UPDATE (fires on every column update) rather than BEFORE UPDATE OF status like its sibling trg_module_catalog_lifecycle_transition — guard logic was already correct either way (a firing-frequency tightening, not a behavior fix) — fixed for consistency with the established convention. U N/A — this phase adds net-new v2/v3-only tables with no v1 antecedent (a platform reopen, not a new module with v1 precedent to diff against); Design-Phase Integrity's 4-block requirement applies to whole-module builds against a v1 predecessor, not this shape of reopen, consistent with how prior platform reopens (#48, #52, #54) treated item U.

3 GAPs found, all fixed same-pass (2 documentation-only comment additions on tier_module_entitlement/module_dependency/tenant_regional_policy; 1 new supporting index module_dependency_depends_on_module_id_idx; 1 trigger scoped from BEFORE UPDATE to BEFORE UPDATE OF status) — all 4 fixes applied to both the live dev DB and the (still-uncommitted) migration/Drizzle files, so they ship as part of this same Phase 1 commit rather than a follow-up. Full apps/api suite re-confirmed green after all fixes: 1111/1111 (serially; the parallel-worker run surfaces 1 pre-existing, Phase-1-unrelated tenant-list-pagination test-concurrency flake — admin-tenants.spec.ts B3 — already logged among the "3 pre-existing test-concurrency flakes" this codebase's own Remediation Phase 1 entry (#37) first disclosed; confirmed to pass in isolation and under serial full-suite execution).

Phase 1 lock-gate verdict: CLEAN. Phase 2 (ai reopen) is authorized to proceed.

63. ai Reopen (1st) — Registry/Deployment/Prompt/Routing + Partitioned agent_execution/agent_memory + Memory Governance (agents-v2/v3 Build, Phase 2 of 6)

Decided/built: 2026-07-13. Phase 2 of the agents-v2/v3 build authorization. ai.agent_execution and ai.agent_memory — v1 tables, reopened for the first time — are now PARTITIONED BY RANGE(created_at), monthly (E1/BLOCKER 2's composite-identity resolution). 14 new tables (corrected post-independent-verification, was miscounted as 13 in this entry's first draft): C1 registry (provider_registry, model_family, model_version), C1 deployment (model_deployment + _limit/_region/_policy/_override, model_deployment_status_observation), C1 prompts (prompt_definition/_version, prompt_model_compatibility), routing_policy, C4 (agent_memory_source). ai is now 21 logical tables / 227 columns (up from 7/118) — using this codebase's own established logical-table-count convention, matching every other module's own reporting basis. Corrected post-independent-verification (MAJOR, was internally inconsistent in this entry's first draft): the raw, unfiltered information_schema.tables count for the ai schema is 49 — but that figure counts each of agent_execution/agent_memory's 26 partition-child relations (13 monthly + 1 default, ×2) as its own "table," which is not the counting convention this codebase uses anywhere else; 227 columns is the correct companion figure on the SAME (logical, non-partition-inflated) basis. Migration: packages/db/migrations/20260713000000_ai_registry_partition_memory_governance.sql.

Pre-migration audit (mandatory — v1 tables reopened for the first time): ai.agent_execution had 948 live rows, all created_at within a single month (2026-07-08 to 2026-07-12) — 270 with resolves_execution_id set, 135 with idempotency_key set. ai.agent_memory had 0 rows. The audit surfaced a genuine, pre-existing data-integrity violation mid-migration: 1 row (agent_execution.id = 019f4579-..., action_code = 'test.action', tenant 00000000-...-000000000001 — the well-known dev/test boilerplate tenant) had a permission_id referencing a identity.permission row that no longer existed, despite a live, validated FK — confirmed as isolated dev-seed drift (a stale test fixture surviving a identity.permission reseed), not a real business-data problem. Fixed by nulling the orphaned permission_id (the column is nullable; nulling preserves the row rather than destructively deleting it) via a temporary, disclosed ALTER TABLE ... DISABLE/ENABLE TRIGGER bracket around the one UPDATE (the table's own append-only trigger otherwise blocks it) — matching this codebase's own established precedent for this exact class of one-off dev-data correction. Re-verified zero orphans before re-running the migration.

Partitioning mechanics: both tables use a real backfill (not an empty-table swap) — a new _new-suffixed partitioned table, monthly partitions from 2026-06 through 2027-06 plus a DEFAULT catch-all, INSERT ... SELECT from the old table (a self-join resolves resolves_execution_id's new composite shadow column), a row-count + zero-unresolved-shadow verification DO block, then DROP+RENAME. Both gain UNIQUE(id, tenant_id, created_at) — the composite-identity shape ai.agent_memory_source's own composite FK resolves against.

2 genuine gaps neither v2 nor v3 addresses, found during this phase, resolved consistently with BLOCKER 2's own established pattern (a native cross-partition unique index is structurally impossible; a real business invariant must not be silently weakened to per-partition-month scope):

  1. agent_execution.resolves_execution_id's old simple self-FK + partial-unique index (agent_execution_resolves_execution_id_unique) and agent_execution_tenant_agent_idempotency_unique (idempotency dedup) both cannot survive partitioning as native unique indexes. Resolved via composite-identity (a new resolves_execution_created_at shadow column, a real FK) for the existence guarantee, PLUS 2 new BEFORE INSERT triggers (ai.check_agent_execution_single_resolver() row-locks the target row first, matching signals.lock_experiment_causal_basis's own proven shape from the v3 design; ai.check_agent_execution_idempotency() uses pg_advisory_xact_lock, the same class of mechanism BLOCKER 2's own prior-pass fix for outcome_authority used before being superseded by a native upsert there — native isn't possible here, so the advisory-lock pattern is the correct tool) for the at-most-one-resolver / dedup guarantees a cross-partition index cannot express.
  2. agent_memory_tenant_category_key_active_unique (the "at most one active row per (tenant,category,key)" invariant, established at agent_memory's own original build by direct analogy to identity.agent_duty_grant's precedent) has the identical problem. Resolved via ai.check_agent_memory_single_active(), a BEFORE INSERT OR UPDATE OF status trigger using the same advisory-lock pattern; supersession (disable old row, insert fresh active row) re-verified to still work.

C1 registry/deployment/prompt/routing tables built per the v2 design's own C1 spec: 3 genuinely separate state classes (durable config = model_deployment, never overwritten — a traffic-weight change is a new row referencing previous_deployment_id; administrative override = model_deployment_override, a separate small table so an emergency override never touches the durable row; transient runtime observation = model_deployment_status_observation, deliberately mutable/purgeable/NOT partitioned/NOT append-only, implementing Part D's own disclosed fallback "if external observability is never built" — no such infra exists in this codebase yet). model_deployment_override's emergency_traffic_weight is trigger-guarded (ai.check_model_deployment_override_residency()) to only ever RAISE traffic toward a tenant-restricted deployment whose model_deployment_region already satisfies that tenant's platform.tenant_regional_policy-resolved home region — lowering traffic or acting platform-wide bypasses the check entirely, matching C1's own stated rule that an operator can always reduce risk but never use this path to force traffic toward a non-compliant deployment. routing_policy.workload_class_id is a disclosed forward-ref (bare uuid, no FK) to agents.workload_class (Phase 5, not yet built) — logged to OPEN_ITEMS.md.

Live-reproduced (6 guards + the residency guard, all via real psql sessions against the live dev DB, matching this build's own evidence standard):

  • 3 state classes genuinely separate: mutating model_deployment_override left model_deployment.traffic_weight unchanged; model_deployment_status_observation rows are genuinely mutable (a plain UPDATE succeeds, unlike agent_execution's append-only trigger) and purging them leaves both the durable and override rows intact.
  • Composite FK resolves: agent_memory_source with the correct agent_memory_created_at shadow value inserts successfully.
  • Wrong shadow timestamp FK-rejected: the identical insert with a fabricated 2020-01-01 timestamp is rejected by the FK constraint itself (agent_memory_source_agent_memory_id_tenant_created_fkey) — no sync trigger needed or added, matching E1/BLOCKER 2's own "write-once value the FK polices" rule.
  • At-most-one-resolver: a second execution resolving an already-resolved proposal is rejected ("execution ... is already resolved by execution ... at most one resolver is allowed").
  • Idempotency dedup: a second execution with the same (tenant_id, agent_identity_id, idempotency_key) is rejected ("idempotency_key ... already used by execution ...").
  • At-most-one-active memory + supersession: a second active row for the same (tenant,category,key) is rejected ("an active row already exists ..."); disabling the first then inserting a fresh active row still succeeds.
  • Residency guard: raising emergency_traffic_weight toward a tenant whose regional policy doesn't match the deployment's own compatible-region set is rejected ("is not residency-compatible with tenant ...").

A disclosed mistake during this phase's own live-reproduction pass, not hidden: an ad hoc psql cleanup query used an overly broad DELETE ... WHERE action_code LIKE 'test.%' intending to remove only the guard-verification rows this phase itself inserted, but the pattern also matched 270 pre-existing agent_execution rows sharing that same generic prefix (accumulated dev-seed/test debris from earlier sessions, confirmed harmless — all remaining rows are crm.customer.create for one tenant, the substantive 678-row dataset, fully intact and unaffected). ai.agent_execution now holds 678 rows (down from the 948 confirmed by the migration's own backfill), all of them the original, legitimate crm.customer.create simulation data. This does NOT indicate any migration defect — the migration's own row-count-parity DO block verified all 948 rows landed correctly before this unrelated, later cleanup mistake occurred. The regression test suite (ai-registry-partition-memory.spec.ts) was written afterward using an exact, unique TEST_MARKER prefix (zz_test_ai_phase2_) for all cleanup, specifically to not repeat this mistake.

Section 4 self-audit (read-only pass, run separately from the independent verification below): 3 GAPs found, all fixed same-pass — (1) 3 JSONB columns (model_version.capabilities, model_deployment_policy.traffic_policy, routing_policy.criteria) had no documented example shape (item J) — fixed, inline example comments added to all 3; (2) routing_policy's own Drizzle comment falsely claimed a resolution function was "built alongside this table" — no such function exists in this phase (schema-only, matching every other table in this module) — corrected to disclose this accurately; (3) the workload_class_id forward-ref (item G) was documented in the Drizzle comment but not actually logged to OPEN_ITEMS.md as required — fixed, a new row added. All other A-P+T+U items PASS or N/A (no nullable-tenant_id+UNIQUE combinations, no soft-delete columns in this table set, no partial indexes with enum-value WHERE clauses, all CHECKs cross-checked complete, all FK targets verified against actual locked table names, tenant_id present as a leading index column on every tenant-scoped table, all 8 new/modified trigger functions audited for correct firing events and edge-case soundness — including the 2 advisory-lock triggers' NULL-safe short-circuits when the guarded column is NULL). Item U is N/A — this is a ai reopen adding net-new v2/v3-only tables with no v1 antecedent (the C1/C4 tables), not a whole-module build against a v1 predecessor; the partitioning of the 2 genuinely-v1 tables is a schema-shape change, not a v1→v2 capability migration, so the 4-block Design-Phase Integrity requirement doesn't apply the same way (consistent with how Phase 1's own platform reopen treated item U).

Regression tests: apps/api/src/platform/__tests__/ai-registry-partition-memory.spec.ts, new file, 18/18 passing (table existence, all 6+1 live-reproduced guards) — now extended post-independent-verification with a 19th test (H5) proving the BLOCKER fix below, so the exact gap that let the BLOCKER through undetected is closed for good. The pre-existing apps/api/src/ai/__tests__/ai-schema.spec.ts (23 tests, predates this phase) required 5 updates for the new partition-aware shape: table count (corrected below), 2 tests (D1/D3) needed the new resolves_execution_created_at shadow column added to their INSERT statements, and 3 assertions (D3/E1/F1) updated from the old 23505/constraint_name shape to the new trigger message-based shape — all disclosed as expected, correct updates (the same established pattern as every prior module reopen in this codebase's history), not defects.

Addendum — independent lock-gate verification (separate agent, live Postgres + live repo access, run against the completed build above), 1 BLOCKER + 2 MAJOR findings, all fixed before Phase 3 was authorized to proceed, per this build's own sequencing guard:

  1. [FIXED, BLOCKER] Postgres RLS and GRANTs on a partitioned PARENT table do not propagate to its child partitions — each of agent_execution/agent_memory's 14 partitions (13 monthly + 1 default, ×2 tables = 28 relations) is an independently-privileged, independently-RLS'd object. The schema-wide ALTER DEFAULT PRIVILEGES (Phase 1's own already-disclosed culprit) applies to every partition at CREATE TABLE time exactly as it does to any other new table, so all 28 partitions were left with a full INSERT/SELECT/UPDATE/DELETE grant for authenticated and RLS disabled, despite the parent tables' own correct GRANT/RLS setup. Live-exploited and live-reproduced-closed: a tenant-2 session querying ai.agent_execution_2026_07 directly (bypassing the parent) read all of tenant-1's 723 rows, and successfully inserted a forged tenant-1-attributed row the same way — a genuine cross-tenant read leak AND a write-forgery vector, not merely a leak. (The append-only trigger correctly blocked direct UPDATE/DELETE on the partition even before this fix — triggers DO propagate to partitions, unlike GRANT/RLS, which is exactly why this gap was narrower than it could have been.) Fixed: REVOKE ALL ... FROM authenticated applied to all 28 partition relations, forcing every access path through the parent (where GRANT/RLS/append-only all correctly apply) — live-reproduced-closed for both the read leak and the write-forgery vector, with parent-table access confirmed still working correctly (RLS-filtered) throughout. The migration file itself now applies this fix via a DO block iterating pg_inherits immediately after each table's own GRANT section, so a fresh apply gets it right without a follow-up step; a disclosed operational note is included for whoever builds the future partition-maintenance job (E9, deferred infra) — every NEW partition it creates will need the identical REVOKE ALL run immediately after creation, or this exact BLOCKER reopens silently for that one partition. New regression test ai-registry-partition-memory.spec.ts (H5) asserts zero authenticated grants exist on any partition-child relation for either table, directly closing the coverage gap that let this BLOCKER through the original H1 test (which only checked the 2 parent relation names).
  2. [FIXED, MAJOR] This entry's own headline table-count arithmetic was internally inconsistent: "49 tables" (the raw, partition-inflated information_schema.tables count) was stated alongside "227 columns" (computed on the logical, non-partition-inflated basis) as if they were one consistent pair — no other module in this codebase reports counts this way. Fixed: this entry now reports 21 logical tables / 227 columns throughout, matching every other module's own convention; the raw 49-table figure is disclosed once, explicitly labeled as the partition-inflated count, not presented as the headline number.
  3. [FIXED, MAJOR] "13 new tables" was an off-by-one miscount — the actual list (provider_registry, model_family, model_version, model_deployment, _limit, _region, _policy, _override, model_deployment_status_observation, prompt_definition, _version, prompt_model_compatibility, routing_policy, agent_memory_source) is 14 tables. Fixed throughout this entry.

All 6+1 originally-claimed live-reproduced guards were independently re-confirmed correct, including under genuine 3-way concurrent load (not merely sequential) for the 3 advisory-lock/row-lock triggers — the verifier fired 3 simultaneous psql background processes at each of the single-resolver, idempotency-dedup, and memory-single-active guards and confirmed exactly 1 of 3 landed in every case. The composite FK, residency guard (including its boundary case and 2 fail-closed edge cases), backfill data integrity, and the 13 genuinely-new standalone tables' own GRANT/REVOKE correctness (Phase 1's exact mistake was NOT repeated there) were all independently verified clean with no further findings.

Full apps/api suite re-verified green after all fixes: 1129/1129, typecheck clean on packages/db and apps/api.

Phase 2 lock-gate verdict: CLEAN. Phase 3 (semantics, new schema) is authorized to proceed.

Schema-only, as every phase of this build will be until Phase 5 lands the agents module itself — no service-layer changes in this phase.

64. semantics — New Schema, Shared Business Ontology (agents-v2/v3 Build, Phase 3 of 6)

Decided/built: 2026-07-14. Phase 3 of the agents-v2/v3 build authorization. semantics is a brand-new foundation-layer schema, no v1 antecedent (design doc B1, hardened by v3's I2/I3/I4) — the shared business ontology future agents/signals modules read from rather than each inventing their own metric/goal/constraint vocabulary. 14 logical tables / 114 columns: approved_function_registry (I2's supply-chain-hole-closing registry), metric_definition/metric_version/tenant_metric_binding/metric_dependency, entity_definition/entity_alias, dimension_definition, goal_definition/constraint_definition/tenant_goal_binding/tenant_constraint_binding (I3), attribution_model_definition/attribution_model_version (BLOCKER 8/I2). Migration: packages/db/migrations/20260714000000_semantics_new_schema.sql.

No pre-migration audit needed — brand-new schema, zero pre-existing rows anywhere, not a reopen of a v1 table.

I2's approved-function-registry re-verification pattern, the load-bearing mechanism of this phase: semantics.verify_function_still_matches_approval(p_registry_id) re-resolves schema.function(bare_arg_types)::regprocedure fresh from stored TEXT columns on every call (never trusting a cached OID, which is not guaranteed stable across pg_dump/restore or major-version upgrades) and compares md5(pg_get_functiondef(...)) against the stored definition_hash. A new trigger, semantics.validate_metric_binding_function_hash() (BEFORE INSERT OR UPDATE on tenant_metric_binding), calls this on every binding write and rejects if the live function definition no longer matches what was approved — closing the "approve a function, quietly redefine it later, bindings still trust it" supply-chain hole. Implementation detail confirmed critical during the build: argument_signature must store BARE TYPES ONLY ('numeric, numeric'), never parameter-name-included signatures — ::regprocedure throws a hard syntax error on the latter form.

tenant_metric_binding / tenant_goal_binding / tenant_constraint_binding all use EXCLUDE USING gist (reusing platform.accounting_period's own precedent, btree_gist already installed) for overlap prevention on (tenant_id, <definition>_id, tstzrange(effective_from, effective_to)) — HARD-REJECT here, a genuine, disclosed departure from accounting_period's own fuller flag-not-reject pattern: no offline-sync reason exists for a tenant setting an authoritative metric/goal/constraint binding (an online, synchronous admin action), unlike POS's offline-first sale posting.

metric_dependency cycle detection is a real, firing trigger (semantics.check_metric_dependency_no_cycle(), BEFORE INSERT OR UPDATE, a recursive CTE walking the dependency graph) — v3's own disclosed finding was that an earlier draft of this exact logic was written as dead code with no CREATE TRIGGER statement anywhere; this build confirmed the CREATE TRIGGER is genuinely present and live-reproduced it firing (A→B→C→A rejected; a direct self-reference separately rejected by a CHECK, not the trigger).

tenant_goal_binding.module_id/site_id and tenant_constraint_binding.module_id/site_id are deliberately BARE (no FK) — v3's own literal SQL declares them as plain uuid with no REFERENCES clause, and no reconciliation-table row names them as FKs. Disclosed as a genuine judgment call, not a defect: platform.module_catalog now exists (unlike routing_policy.workload_class_id's own Phase-2 forward-ref, where the target genuinely doesn't exist yet) but the design of record does not specify wiring module_id to it — left exactly as specified rather than over-interpreted. Logged to OPEN_ITEMS.md.

Live-reproduced (3 named guards, all via real psql sessions against the live dev DB):

  • EXCLUDE overlap rejection: a first tenant_metric_binding for a (tenant, metric) pair over [2026-01-01, 2026-06-01) succeeds; an overlapping second [2026-03-01, 2026-09-01) is rejected by excl_tenant_metric_binding_no_overlap; a non-overlapping adjacent third [2026-06-01, ∞) succeeds. Same shape independently confirmed for tenant_goal_binding/tenant_constraint_binding.
  • I2 supply-chain-hole guard: registered a real scratch function (SELECT $1 + $2) with its live hash; verify_function_still_matches_approval() returns true; a tenant_metric_binding referencing it via metric_version.resolved_function_reference succeeds; CREATE OR REPLACE FUNCTION redefined it (SELECT $1 * $2); verify_function_still_matches_approval() now returns false; a NEW binding write against the same (now-tampered) metric_version is correctly REJECTED with "references a function whose live definition no longer matches its approved hash".
  • metric_dependency cycle detection: A depends_on B, B depends_on C both succeed; C depends_on A (would close the cycle) is rejected by the trigger, not a CHECK.

Section 4 self-audit (read-only pass, run before independent verification) — 2 real GAPs found, both fixed same-pass before lock:

  1. [FIXED, item F — CHECK completeness] 3 lifecycle_status columns (dimension_definition, goal_definition, attribution_model_definition) carried an enum-like default ('active'/'planned') but had no CHECK constraint at all — the exact "CHECK completeness" trap this runbook's own Section 4 checklist is designed to catch, and a class of bug this build has now hit twice (see metric_definition's own correctly-built CHECK, which was the pattern the 3 gap tables should have matched from the start). Fixed: all 3 now carry chk_<table>_lifecycle_status CHECK (lifecycle_status IN ('planned','designed','in_build','active','deprecated','retired')), matching metric_definition's own vocabulary (the same "definition lifecycle" concept, reused for consistency). Live-reproduced rejecting an invalid value ('bogus') on all 3 tables before lock.
  2. [FIXED, item T — trigger/structural consistency] tenant_metric_binding has created_at/updated_at + a maintaining set_updated_at trigger; the sibling tenant_goal_binding/tenant_constraint_binding (same I3 binding pattern, same mutable approval_status lifecycle) had neither — an asymmetry with no disclosed rationale, found by comparing the 3 binding tables' own shapes against each other rather than against the design doc text alone. Since this is a brand-new schema with zero live rows anywhere (confirmed via SELECT count(*) before the fix), the safer and more disciplined choice was to fix the inconsistency immediately rather than defer it to OPEN_ITEMS.md — both tables now carry created_at/updated_at + the same set_updated_at trigger tenant_metric_binding already had. Column count grew 110 → 114 (+4) as a direct result; the regression test suite's own count assertion was updated to match, with an explanatory comment referencing this exact fix so a future reader isn't confused by the discrepancy from this entry's own earlier interim total.

All other A-P+T+U items PASS or N/A: no nullable-tenant_id+UNIQUE combinations (all 3 tenant-scoped tables have tenant_id NOT NULL); no soft-delete columns anywhere in this table set (no partial-unique traps); no JSONB columns at all (item J N/A); no money-derivation columns (item I N/A — this is a purely definitional/ontology schema, not transactional); tenant_id present as a leading index column on all 3 tenant-scoped tables; the reverse-lookup index on metric_dependency.depends_on_metric_definition_id was added proactively (Phase 1's own lesson about supporting reverse-FK lookups, applied here before an audit had to ask for it); all cross-schema FK targets (platform.tenant, platform.module_catalog, identity.actor) verified against the actual live table names. Non-RLS access control (item O) is documented via migration comments + GRANT SELECT-only to authenticated on all 11 global catalog tables — matching ai's own registry-table precedent from Phase 2. Item U (Design-Phase Integrity 4-block requirement) is N/A — brand-new schema with no v1 predecessor to diff against, consistent with how this build has treated item U for every other genuinely-new (non-reopen) table set.

A schema-usage grant gap found only by the regression test suite, not the read-only Section 4 pass: the migration's original draft never ran GRANT USAGE ON SCHEMA semantics TO authenticated — every prior new-schema migration in this codebase (ai, crm, approvals, returns, files, receiving, consumer/rewards/offers) does this explicitly, and this one silently omitted it. The RLS cross-tenant-isolation test (F1) failed with permission denied for schema semantics — table-level GRANTs are meaningless without schema-level USAGE. Fixed live and in the migration file (GRANT USAGE ON SCHEMA semantics TO authenticated; immediately after CREATE SCHEMA).

Regression tests: apps/api/src/platform/__tests__/semantics-schema.spec.ts, new file, 21/21 passing (table existence + RLS shape, EXCLUDE overlap ×3 tables, I2 supply-chain-hole guard, cycle detection ×2 cases, RLS cross-tenant isolation on all 3 binding tables — extended post-independent-verification, see below — GRANT shape). A companion stale-assertion fix was needed in the pre-existing platform-module-registry.spec.ts (G3): Phase 1 had asserted agents/semantics/signals all stay 'designed' — now that semantics has landed, this migration correctly bumps its module_catalog.lifecycle_status to 'in_build', so G3 was updated to assert agents/signals stay 'designed' while semantics is 'in_build', rather than loosening or deleting the original assertion.

Addendum — independent lock-gate verification (separate agent, live Postgres + live repo access, run against the completed build above), pasted verbatim per this runbook's own Section 6 item 1a requirement. Verdict: 1 MAJOR, 1 MINOR, 2 NOTEs, 1 confirmed test-coverage gap — all fixed before Phase 4 was authorized to proceed. Zero of these were live data leaks or live-exploitable bugs against the current 14 tables.

  1. [FIXED, MAJOR] semantics is the only new-schema migration in this codebase's entire history missing an ALTER DEFAULT PRIVILEGES IN SCHEMA semantics ... GRANT ... TO authenticated statement — the verifier grepped all 6 prior new-schema migrations (approvals, consumer/rewards/offers, returns, receiving, files) and every one establishes this default-ACL immediately after CREATE SCHEMA; this one never did. Confirmed live: pg_default_acl had zero rows scoped to semantics for any role (every one of the other 21 schemas in the live DB has one); the verifier live-reproduced the consequence by creating a scratch table and confirming authenticated got zero grants on it automatically. This is the OPPOSITE failure mode from Phase 2's own partition/default-privilege BLOCKER (which over-granted) — here a future table added to semantics would get NO access at all, silently breaking whatever feature reads it, rather than leaking data. Fixed: ALTER DEFAULT PRIVILEGES IN SCHEMA semantics GRANT SELECT ON TABLES TO authenticated; + the matching consumer_authenticated REVOKE, added immediately after CREATE SCHEMA/GRANT USAGE, both live-applied and added to the migration file. SELECT-only (not full CRUD) was chosen as the default because 11 of this schema's own 14 tables are SELECT-only catalog tables — matching the majority shape, with the 3 mutable binding tables continuing to rely on their own explicit widening GRANT, exactly as they already did before this fix.
  2. [FIXED, MINOR] packages/db/src/schema/semantics/goal.ts declared tenantGoalBinding.approved_by_actor_id and tenantConstraintBinding.approved_by_actor_id as bare uuid('approved_by_actor_id') with no .references() call and no actor import — a genuine drift between the Drizzle schema-of-record and the actually-applied migration SQL / live database, both of which correctly enforce REFERENCES identity.actor(id) on both columns (independently confirmed via pg_constraint). Sibling column tenant_metric_binding.owner_actor_id in metric.ts, same phase, correctly had .references(). Not a live integrity risk (the DB enforces the FK regardless of the TS file), but a real forward risk for Drizzle's relational query builder and any future schema-diff tooling. Fixed: goal.ts now imports actor from ../identity/core.js and both columns carry .references(() => actor.id).
  3. [CONFIRMED, test-coverage gap, FIXED] The regression suite's own §F ("RLS cross-tenant isolation") contained exactly one test (F1), scoped only to tenant_metric_binding — tenant_goal_binding/tenant_constraint_binding were exercised only for EXCLUDE overlap, never for RLS. The verifier independently live-proved the underlying mechanism was NOT broken for either untested table (read isolation confirmed both directions, a forged cross-tenant INSERT correctly rejected with a row-level security error on both), so this was a real coverage gap, not a live vulnerability. Fixed: 2 new tests (F2, F3) added, mirroring F1's shape plus an explicit write-forgery-rejection assertion the verifier's own adversarial pass added but F1 itself didn't have — bringing the suite to 21/21.
  4. [DISCLOSED, NOTE, logged to OPEN_ITEMS, not fixed] dimension_definition and attribution_model_definition both carry a mutable lifecycle_status using the identical vocabulary as metric_definition/goal_definition/constraint_definition, but neither has created_at/updated_at or a maintaining trigger — the same asymmetry class this phase's own Section 4 self-audit (finding 2, above) found and fixed for the 3 binding tables, but not extended to this second, parallel instance. Traced to the design of record itself (v3 §I4's literal SQL for both tables omits these columns) — a design-level gap the build faithfully followed, not a build-introduced defect, so left as-is rather than unilaterally deviating from the design of record a second time in the same phase. Logged to OPEN_ITEMS.md.
  5. [DISCLOSED, NOTE, cosmetic, FIXED] A migration comment read "Grants for the 4 tenant-scoped, RLS-enabled tables" immediately above only 3 GRANT statements — zero functional impact (the actual grant shape was already correct), fixed to say "3".

The verifier also independently re-confirmed, with fresh evidence exceeding the builder's own test coverage: the EXCLUDE constraints correctly reject contained AND open-ended (effective_to IS NULL) overlaps while allowing a different *_definition_id for the same tenant/date-range on all 3 tables; the I2 guard correctly fires on UPDATE (not just INSERT) and correctly short-circuits when resolved_function_reference IS NULL; the cycle-detection trigger correctly rejects 2-node and 4-node cycles while correctly ALLOWING a legitimate diamond-shaped non-cyclic shared-dependency graph (zero false positives); every one of the 18 CHECK constraints was fired with a live invalid insert, not just confirmed to exist; all 20 FKs in the live database resolve to the correct target table/column; and the independently-run table/column counts (14/114) matched exactly. Test suite re-run by the verifier after all adversarial activity: 42/42 (semantics-schema.spec.ts + platform-module-registry.spec.ts combined), confirming the verifier's own cleanup left the database uncorrupted.

Full apps/api suite green after all fixes: 1150/1150, typecheck clean on packages/db and apps/api.

Phase 3 lock-gate verdict: CLEAN. Phase 4 (signals, new schema, HIGHEST RISK) is authorized to proceed.

Schema-only, as every phase of this build will be until Phase 5 lands the agents module itself — no service-layer changes in this phase.

65. signals — New Schema, Feature/Forecast/Outcome Store with Enforced Bitemporal Reads (agents-v2/v3 Build, Phase 4 of 6, HIGHEST RISK)

Decided/built: 2026-07-15. Phase 4 of the agents-v2/v3 build authorization — the highest-risk phase in this build, per the CC task's own explicit designation. signals is a brand-new, no v1 antecedent, observational/high-volume/bitemporal/append-only/partitioned schema — the opposite operational profile from semantics (definitional, low-volume, human-curated). 11 logical tables / 111 columns: feature_definition/feature_version (A2b catalog pattern), feature_value/forecast/anomaly_score (bitemporal, partitioned weekly by recorded_at), outcome_observation (partitioned monthly by created_at) + outcome_authority (the split-authority pattern, unpartitioned), experiment/experiment_version (A2b catalog pattern), experiment_assignment + experiment_exposure_event. Migration: packages/db/migrations/20260715000000_signals_new_schema.sql.

No pre-migration audit needed — brand-new schema, zero pre-existing rows anywhere, not a reopen of a v1 table.

The 4 named critical guards, each corresponding to a v3 BLOCKER, all live-reproduced:

  1. GUARD 1 (BLOCKER 1) — tenant spoof via SECURITY DEFINER as-of functions, fixed by removing the parameter, not validating it. The design's own live-verification (v3 doc) proved that a p_tenant_id uuid parameter on a SECURITY DEFINER function is spoofable by any caller regardless of their real tenant — no version of "check the parameter" closes this, since the parameter itself is attacker-controlled. Fixed: signals.get_feature_as_of()/get_forecast_as_of()/get_anomaly_score_as_of() derive tenant scope from a new helper, platform.current_tenant_id() (SELECT current_setting('app.current_tenant_id', true)::uuid), with no tenant argument in the function signature at all — there is no argument position left to spoof. Each function is owned by a new, minimal role signals_function_owner (NOLOGIN, NOT superuser, NOT the table owner — its own narrow SELECT grant on exactly feature_value/forecast/anomaly_score, nothing else), search_path pinned to 'signals, pg_catalog', REVOKE EXECUTE FROM PUBLIC. Live-reproduced: a session scoped to tenant 1 correctly sees its own row (value=42); the identical call from a session scoped to tenant 2, for the identical entity_ref/feature_version_id, correctly returns nothing — there is no argument to substitute another tenant's ID into.
  2. GUARD 2 (BLOCKER 2) — the partition/authority split for outcome_observation. Live-verified during the design phase (v3 doc) that a native UNIQUE/partial-unique index enforcing "exactly one authoritative observation per scope" cannot survive PARTITION BY RANGE(created_at) — Postgres requires the partition key in every unique constraint, and naively adding it (created_at) silently defeats the guarantee (2 simultaneously-authoritative rows in different months both pass). Resolved via a genuinely separate, unpartitioned table, outcome_authority (PK = (tenant_id, agent_action_id, outcome_type, measurement_window)), maintained by promote_authoritative_observation() — a native INSERT ... ON CONFLICT ... DO UPDATE upsert, Postgres's own race-free primitive, no advisory lock needed. Live-reproduced: an observation in June (partition 1) with is_authoritative=true correctly creates 1 outcome_authority row; a second observation in July (partition 2, same scope tuple) also is_authoritative=true correctly leaves exactly 1 outcome_authority row, now pointing at the July observation — both underlying history rows remain intact in outcome_observation, proving the native upsert works correctly across partitions.
  3. GUARD 3 (BLOCKER 3) — assigned_at forgery and retroactive-exposure contamination. Live-verified during the design phase that DEFAULT now() alone does not stop an explicit backdated INSERT. Fixed: force_assignment_timestamp(), an unconditional BEFORE INSERT trigger, overwrites assigned_at with clock_timestamp() regardless of what the caller supplied. Live-reproduced: an INSERT with an explicit 2020-01-01 assigned_at value is silently overwritten with the real insert time. A second, more subtle race — a genuinely-earlier exposure event arriving AFTER the causal basis is locked — was live-reproduced by the design's own independent review and closed via matching SELECT ... FOR UPDATE row-locks on experiment_assignment in both lock_experiment_causal_basis() (function built this phase; its own CREATE TRIGGER ... ON agents.decision_context_snapshot is deferred to Phase 5, which builds that table — see OPEN_ITEMS) and update_first_eligible_exposure(). Live-reproduced end-to-end: exposure-before-assignment correctly rejected by validate_exposure_after_assignment(); a genuine exposure sets first_eligible_exposure_at; after simulating the causal-basis lock, a genuinely-earlier exposure event (after assigned_at, before the current first_eligible_exposure_at) correctly leaves first_eligible_exposure_at unchanged and flips contamination_status to 'exposure_revised_post_lock' — the causal basis is never silently moved once locked.
  4. GUARD 4 (B3 mandatory test 4a) — enforced bitemporal read. Live-reproduced exactly as the design specifies: a feature_value row with as_of = T-30days (business truth) but recorded_at = T+1day (the ERP learned this fact AFTER a decision made at time T) — calling get_feature_as_of() with p_business_as_of=T, p_knowledge_cutoff=T correctly returns nothing; the identical call with knowledge_cutoff advanced past recorded_at correctly returns the value.

A genuine gap in the design doc's own literal SQL, found and fixed during THIS phase's own migration-apply pass, not by a later audit: the design's own reconciliation appendix specified anomaly_score's uniqueness as (id, tenant_id) and outcome_observation's second unique constraint (uq_outcome_observation_scope_version) without created_at — both fail live against Postgres's own structural requirement that every UNIQUE/PK on a partitioned table include the partition key (the exact error class BLOCKER 2 itself documents for is_authoritative, just not caught by that section's own adversarial pass for these 2 sibling constraints). Fixed: anomaly_score now carries UNIQUE(id, tenant_id, recorded_at), matching feature_value/forecast's own already-correct shape. outcome_observation's scope-version constraint now includes created_at; since this alone would silently weaken the invariant to per-partition-month scope, a genuine cross-partition BEFORE INSERT trigger (check_outcome_observation_no_duplicate_version(), using pg_advisory_xact_lock + a real cross-partition SELECT) was added, matching Phase 2's own established resolution for the identical bug class (ai.agent_execution.idempotency_key). Live-reproduced: an exact duplicate scope-tuple+version landing in a 3rd, different partition (August) is correctly rejected with "already exists".

2 privilege-mechanics gaps found live during the migration-apply pass itself (not the design), both fixed before Phase 4 was considered complete: (1) ALTER FUNCTION ... OWNER TO signals_function_owner requires the migration-running role to be a member of the target role AND for the target role to hold CREATE on the containing schema — live-verified this local Supabase stack's own postgres role is NOT a true superuser (rolsuper = false), so both grants were genuinely required, not optional; CREATE is REVOKEd again immediately after the 3 ownership transfers, since signals_function_owner has no ongoing need to create anything. (2) The SECURITY DEFINER function body calls platform.current_tenant_id() — the executing role (signals_function_owner) needed explicit USAGE on schema platform to even reference it (a genuinely separate requirement from EXECUTE on the function itself, which is PUBLIC-granted by default) — found only when live-reproducing Guard 1 for the first time, not by the read-only Section 4 pass.

Section 4 self-audit (read-only pass) — 1 real GAP found and fixed same-pass: 4 JSONB columns (lineage on feature_value/forecast/anomaly_score, stratification_attributes on experiment_assignment) had no documented example shape (item J) — fixed, inline example comments added to all 4 in the Drizzle schema files. All other A-P+T+U items PASS or N/A: no nullable-tenant_id+UNIQUE combinations (all tenant-scoped tables have tenant_id NOT NULL); no soft-delete columns anywhere in this table set; tenant_id present as a leading index column on every tenant-scoped table; feature_version_id/agent_action_id/experiment_version_id/experiment_assignment_id all have supporting indexes for their own query patterns; all cross-schema FK targets (platform.tenant, semantics.attribution_model_version) verified against actual live table names; non-RLS access control (item O) is documented via migration comments for feature_value/forecast/anomaly_score (REVOKE ALL + function-only access — a deliberate departure from this schema's own otherwise-uniform RLS convention, since the as-of function's own platform.current_tenant_id()-derived WHERE clause is the real tenant boundary, not RLS). Item U (Design-Phase Integrity) is N/A — brand-new schema with no v1 predecessor. Item T (trigger audit): 6 new trigger functions (force_assignment_timestamp, lock_experiment_causal_basis — function only, its own CREATE TRIGGER deferred to Phase 5 — validate_exposure_after_assignment, update_first_eligible_exposure, promote_authoritative_observation, check_outcome_observation_no_duplicate_version), all live-reproduced, correct BEFORE/AFTER placement per the design's own specification.

2 disclosed forward-refs, both logged to OPEN_ITEMS.md: outcome_observation.agent_action_id/outcome_authority.agent_action_id are bare uuid — agents.agent_action doesn't exist until Phase 5 (confirmed live: zero tables in the agents schema as of this phase). The 3 as-of functions have REVOKE EXECUTE FROM PUBLIC but no GRANT EXECUTE to any role — agent_reader doesn't exist until Phase 6 — matching this design's own explicit allowance to "stub the REVOKE ahead of the role's full build." All 4 critical-guard live-reproductions above worked around this by temporarily granting EXECUTE to authenticated and revoking it again afterward, both in the live-reproduction pass and in the regression test suite's own setup/teardown.

Naming resolution, disclosed judgment call: experiment_assignment.subject_type/subject_ref resolve a genuine internal inconsistency in the design doc itself — its own column-list prose named the column assignment_unit, while its own "Uniqueness" line specified subject_type, subject_ref. Treated as the same concept, named per the more specific, typed, structurally-consistent form — matching this codebase's established polymorphic-pointer convention (feature_value.entity_type/entity_ref, ai.agent_execution.target_module/target_row_id).

Regression tests: apps/api/src/platform/__tests__/signals-schema.spec.ts, new file, originally 20/20 passing (table existence + partition shape, partition-level GRANT isolation, all 4 critical guards, RLS cross-tenant isolation, GRANT shape) — extended to 22/22 post-independent-verification, see addendum below. A companion stale-assertion fix was needed in platform-module-registry.spec.ts (G3): signals now correctly bumps to 'in_build' alongside semantics, while agents alone stays 'designed'.

Addendum — independent lock-gate verification (separate agent, live Postgres + live repo access, run against the completed build above), pasted verbatim per this runbook's own Section 6 item 1a requirement. Verdict: 1 BLOCKER + 1 MAJOR, both fixed before Phase 5 was authorized to proceed. The BLOCKER was live-exploitable against the current 11 tables (both a cross-tenant read leak and a cross-tenant write forgery); the MAJOR was a silent-desync risk, not a leak.

  1. [FIXED, BLOCKER] RLS on outcome_observation does not propagate to its 14 monthly partitions — the same structural Postgres behavior Phase 2 found for GRANTs (BLOCKER, entry #63's own addendum), now independently reproduced for RLS specifically, on a table where the danger combination is worse: outcome_observation's partitions ALSO carry real, intentional per-partition SELECT/INSERT/scoped-UPDATE grants to authenticated (needed for the split-authority write path), unlike feature_value/forecast/anomaly_score, whose partitions are safe regardless of RLS gaps because REVOKE ALL already blocks all direct access. The verifier live-exploited this from scratch: a session scoped to tenant 1, querying signals.outcome_observation_2026_07 directly (bypassing the parent, where RLS is correctly configured), read a tenant-2 row in full — a genuine cross-tenant leak — and then successfully inserted a row forging tenant-2's own tenant_id the same way, a write-forgery vector on top of the read leak. Fixed: ENABLE ROW LEVEL SECURITY + the identical tenant_id = current_setting('app.current_tenant_id')::uuid tenant-isolation policy applied to all 14 partitions individually, folded into the same per-partition DO loop that already re-applies GRANTs (migration file, live-applied). Re-verified clean: the identical direct-partition SELECT now correctly returns 0 rows for the tenant-2 row; the identical forged-tenant_id INSERT now correctly fails with "new row violates row-level security policy for table outcome_observation_2026_07". Same disclosed operational note as Phase 2's own precedent: any future partition-maintenance job must apply both GRANT-narrowing and RLS to every new partition it creates, or this exact BLOCKER reopens silently for that one partition.
  2. [FIXED, MAJOR] The original GRANT UPDATE (status, is_authoritative, validated_at) let authenticated flip is_authoritative directly via a plain UPDATE, bypassing trg_outcome_observation_promote entirely — that trigger is AFTER INSERT only, so an in-place UPDATE desyncs the flag from outcome_authority's own PRIMARY KEY (the actual enforcement mechanism) with no error, no trigger fire, and no trace. The verifier live-reproduced the desync: flipping is_authoritative to false on a row already pointed to by outcome_authority succeeded silently, leaving outcome_authority referencing an observation the base table now claims is non-authoritative. Fixed: narrowed to GRANT UPDATE (status, validated_at) on the parent AND all 14 partitions — is_authoritative is no longer directly writable by authenticated at all; every authority change must go through a new INSERT, matching the design's own stated intended workflow ("a later observation is a new row," never an in-place flip) rather than adding new trigger surface. Re-verified clean: a direct UPDATE ... SET is_authoritative = false now correctly fails with "permission denied for table outcome_observation"; a control UPDATE ... SET status = 'superseded' on the same row still succeeds, confirming the narrowed grant did not over-correct.

Both fixes are also now documented in packages/db/src/schema/signals/outcome.ts (header comment + inline column comment) and packages/db/migrations/20260715000000_signals_new_schema.sql (inline rationale at the point of each fix), and 2 new regression tests (E2a, E2b in signals-schema.spec.ts) directly reproduce both — a partition-level cross-tenant SELECT/INSERT test against outcome_observation_2026_07, and an is_authoritative UPDATE-rejection test with a status/validated_at control assertion — bringing the suite to 22/22.

The verifier's remaining checks — all 4 original critical guards, the cross-partition dedup trigger, the bitemporal-read function, the GRANT shape on the 4 global catalog tables and the 3 partitioned-leaf tables — were all independently re-confirmed correct with no further findings.

Full apps/api suite green after all fixes: 1174/1174, typecheck clean on packages/db and apps/api.

Phase 4 lock-gate verdict: CLEAN. Phase 5 (agents, new module #28) is authorized to proceed.

Schema-only, as every phase of this build will be until Phase 5 lands the agents module itself — no service-layer changes in this phase.

66. agents — New Module #28, the Full v1+v2+v3 Merge (agents-v2/v3 Build, Phase 5 of 6)

Decided/built: 2026-07-16. Phase 5 of the agents-v2/v3 build authorization — the module the entire 6-phase build exists to land. agents is a brand-new module, no v1 antecedent as a schema (v1's own 21-table orchestration baseline — agent_task, agent_thread, agent_event_log, agent_schedule, agent_trigger, agent_eval_suite, agent_eval_run, agent_eval_case, agent_performance_profile, agent_shadow_run, agent_shadow_decision, agent_autonomy_profile, agent_action, rollback_recipe, rollback_execution, tool_catalog [superseded], agent_tool_grant, agent_catalog_entry, agent_catalog_entry_required_tool, tenant_agent_deployment, agent_incident — was itself never previously built, confirmed live: zero tables existed anywhere in the agents schema before this migration) merged with v2's amendments (A1–A8) and v3's corrections (BLOCKER 1–8, I1–I8) into one coherent build. 47 logical tables / 475 columns — independently confirmed against the live database on the same non-partition-inflated basis Phase 2 established (entry #63), well above the 30-table figure the design docs' own Appendix-A-scoped delta language could be misread as; the true scope is v1's full 21-table baseline PLUS the v2/v3 net-new tables (tool/skill/marketplace/eval/shadow/certification/decision-context/action/kill-switch/policy families), not a ~30-table delta layered on some smaller baseline. Migration: packages/db/migrations/20260716000000_agents_module_new_schema.sql (1650 lines, 10 sections, including a same-day SECTION 10 appended after the Section 4 self-audit found 2 fixes). Design of record: vrida-agents-module-design-proposal-2026-07-11.md (v1) + vrida-agents-v2-design-amendment-2026-07-11.md (A1–A8) + vrida-agents-v3-correction-pass-2026-07-12.md (BLOCKER 1–8, I1–I8, v3 wins on conflict). I2/I3/I4 (approved-function-registry hardening, tenant goal/constraint bindings, dimension/metric-dependency-cycle trigger) and BLOCKER 1/2/3/8 (signals SECURITY DEFINER fix, partition/authority split, assigned_at forgery, outcome_observation ROI fields) were ALL already built in Phases 3–4 (semantics/signals), confirmed live before writing this migration; I7 (module-dependency cycle + deactivation guard) was already built in Phase 1 (platform reopen). This migration covers exactly the remainder: the agents schema itself, plus the specific cross-schema wiring gaps those earlier phases left as disclosed forward-refs.

No pre-migration audit needed for the agents schema itself — brand-new schema, zero pre-existing rows anywhere, not a reopen of a v1 table (v1's own design was never built). 3 companion prerequisite/cross-schema sections DID touch already-locked modules, each audited: files.document_chunk gained UNIQUE(id, tenant_id) (BLOCKER6's own disclosed prerequisite, confirmed missing — the table previously carried only PRIMARY KEY (id)); approvals.approval_request.chk_approval_request_source_module was widened to add 'agents' (BLOCKER4's saga-exemption seam + A3's autonomy-promotion seam), which also closed a pre-existing, this-fix-unrelated Drizzle-file/live-DB drift found while touching the constraint — 'offers'/'returns' were already live in the CHECK but missing from the Drizzle source file; ai.agent_execution gained 8 new, all-nullable-or-defaulted, purely additive columns (v1 Gap 1's own planned extension, landing now that agents.agent_task exists — agent_task_id, sequence_index, tool_version_id, approval_request_id, retry_count, blocked_by_policy, confidence_threshold, escalation_reason), independently confirmed live. platform also gained 1 new table, polymorphic_target_registry (I6, 4 columns: target_type PK, target_schema, target_table, tenant_column) — the real validator for genuinely-unavoidable polymorphic references (ai.agent_memory_source.source_ref, spanning 4 target tables that cannot be typed as a single FK), seeded with 4 rows. Its own accompanying function, platform.validate_polymorphic_reference(), uses format('... %I.%I ...', v_schema, v_table, ...) on 2 SEPARATE stored columns rather than a single free-text 'schema.table' string — v3's own independent review had found a live SQL-injection vector in the single-string form and separately confirmed a quoted-compound-string %I alternative was ALSO wrong (not a valid two-part identifier), so the 2-column split was applied directly here rather than reproducing the vulnerable draft first.

8 distinct trigger-backed critical guards, all live-reproduced — disclosed honestly as 8, not forced into the "7 named" framing the design docs use, since a genuine 8th (T1, added during this build's own Section 4 audit pass, not originally one of the "7 named" guards) is also proven by a real trigger and real test:

  1. GUARD 1 (BLOCKER 7) — kill-switch history/state split, resume-safe propagation. agents.kill_switch_event (append-only history) resolves into agents.kill_switch_scope_state (current, mutable, native-upsert-maintained) via resolve_kill_switch_state() — a resume directive always resets current_fencing_generation to 0 (never GREATEST'd against the prior kill's generation, which would leak a stale high-water mark forward). propagate_kill_switch_fencing() bumps fencing_token/sets cancellation_requested_at on every in_progress agent_task matched by the kill's scope (global/tenant/agent_identity/skill/tool/model, the last 3 resolved via a join through agent_decision→decision_context_snapshot→ai.agent_execution) — but takes NO action on a resume directive, so resuming never re-bumps fencing or re-cancels anything. agents.is_agent_blocked() is the single shared resolver both the pre-work gate (GUARD 2) and this propagation trigger's own targeting logic read from. Also the guard that absorbed a real Section 4 self-audit RLS fix — see below.
  2. GUARD 2 (A5, corrected per BLOCKER7) — kill-switch check fires on CLAIM, not just creation. check_agent_task_not_blocked() fires BEFORE INSERT OR UPDATE OF status on agent_task (a task claim is an UPDATE, not an INSERT — A5's own original text was insert-time only, corrected by BLOCKER7) and a matching check fires BEFORE INSERT on ai.agent_execution, both calling is_agent_blocked(); also extended (A5's own text) to check agent_duty_grant.status/agent_tool_grant.status for the specific permission/tool referenced on the row. Fail-closed: an agent_identity row not found, or killed/suspended, rejects outright.
  3. GUARD 3 (E3 + v1 Gap 1) — runaway-loop/cost ceiling, BLOCK not flag. enforce_task_runaway_ceiling() atomically caps agent_task.step_count/cost_cents_accrued via a single UPDATE ... WHERE ... AND (max_steps IS NULL OR step_count+1 <= max_steps) AND (...), RAISE EXCEPTION on NOT FOUND (a breach) — v1's own explicit decision that an agent cost/step runaway is a safety property, not a business-judgment tolerance call like receiving's own flag-not-reject over-shipment pattern. A separate trigger DB-enforces E3's idempotency-key requirement (was convention-only in v1) — any is_write=true tool call with a NULL idempotency_key is rejected outright.
  4. GUARD 4 (BLOCKER 4) — the saga gate, enforced against real writes, not a static toolset-shape proxy. enforce_single_module_autonomy() fires on agents.agent_action, atomically claims a task's allowed_mutating_module_id on its first unescorted write (the proven UPDATE ... WHERE ... IS NULL idiom, matching E3's own task-claim and BLOCKER2's own promotion-upsert precedent) and rejects any subsequent write to a DIFFERENT module unless approval_request_id or orchestration_id is set. agent_task_id is derived by joining through agent_execution_id — agent_action has NO direct agent_task_id column, a disclosed, structural fix to a genuine gap in v3's own raw SQL, which referenced NEW.agent_task_id on this trigger without that column ever being declared to exist on agent_action.
  5. GUARD 5 (I1) — agent_action/agent_decision execution-id consistency. validate_action_decision_execution_consistency() rejects any agent_action insert whose own agent_execution_id doesn't match its referenced agent_decision's own agent_execution_id — 2 independently-settable FK columns do not self-reconcile merely by both existing, v3's own independent-review correction.
  6. GUARD 6 (A3 deployment activation + BLOCKER5 duty-check + A8 Rule 4) — skill activation, one function, 3 checks. validate_skill_activation() fires BEFORE INSERT OR UPDATE OF is_enabled on agents.agent_skill_assignment — the disclosed resolution of a real ambiguity: A3's own prose names "a trigger on tenant_agent_deployment, v1's own marketplace table," but that table has no skill_version_id column at all, making the literal trigger structurally impossible; agent_skill_assignment is the schema's own actual "this skill is active for this agent" instantiation point, used here for all 3 checks. Point 1 (A3): a valid, unexpired, unrevoked skill_certification must exist, AND none of the versions it references may itself be retired (an independent-review MAJOR fix — a cert issued against a since-retired version must not remain activatable). Point 2 (BLOCKER5): the agent must hold a sufficient agent_duty_grant for every permission the skill's own skill_version_required_duty names, via an explicit ordinal CASE mapping (may_act_alone=3, needs_approval=2, draft_only=1) — NOT a raw text >= comparison, which would silently invert authority ordering since 'may_act_alone' alphabetically sorts before 'needs_approval'. Point 3 (A8 Rule 4): a skill cannot grant itself more cost ceiling than the LOWEST duty-grant spend_limit_cents reachable for its own required permissions, row-locked FOR UPDATE for the duration of the check — this is where both genuine PL/pgSQL bugs below were found.
  7. GUARD 7 (I6) — the real validator for ai.agent_memory_source.source_ref. Calls platform.validate_polymorphic_reference() (see above), rejecting any insert whose polymorphic target doesn't actually exist for the claimed tenant.
  8. T1 (A2b retirement-version-check, added during the Section 4 audit pass, not one of the original "7 named" guards) — reject_retired_decision_context_versions() rejects any decision_context_snapshot insert referencing a retired model_version/prompt_version/skill_version/toolset_version, checked independently per-table by its own actual column location (A2b's own prose names all 4 generically without pinning which table carries which reference — ai.agent_execution checks only its own tool_version_id via a separate, sibling trigger; agents.decision_context_snapshot checks its own 4 version columns via this one). Tested via a 6th regression-suite guard, distinct from the "7 named" list, proving this is genuinely 8 distinct trigger-backed guards, not 7 — disclosed honestly rather than forced to match the design docs' own count.

2 genuine PL/pgSQL bugs found and fixed during THIS build's own live guard-reproduction pass (not the read-only Section 4 audit), both inside validate_skill_activation() (GUARD 6):

  1. A record-typed PL/pgSQL variable's IS NOT NULL check is UNRELIABLE when used directly as an IF condition. Empirically confirmed via a bare, isolated DO block: a genuinely non-null, fully-populated record still evaluated as if NULL in that specific boolean context (v_policy IS NOT NULL returned false immediately after v_policy IS NULL correctly returned false, even though testing one specific field, v_policy.max_cost_cents IS NOT NULL, worked correctly in isolation). This silently swallowed the entire A8 Rule 4 spend-ceiling check (Point 3 above never fired) until caught by live guard-reproduction, not by the Section 4 read-only pass. Fixed by rewriting the function to declare scalar variables (v_policy_max_cost_cents, v_min_duty_spend_cents) instead of a whole record, and checking each scalar's own NULL-ness directly — the well-established, robust PL/pgSQL pattern, never testing a record variable's own nullity again.
  2. SELECT MIN(...) ... FOR UPDATE is syntactically REJECTED by Postgres ("FOR UPDATE is not allowed with aggregate functions") — a genuine gap found live during this build's own guard reproduction, not caught by the Section 4 read-only audit either. Fixed by splitting into a plain, non-aggregate PERFORM 1 FROM ... FOR UPDATE OF dg (lock the referenced agent_duty_grant rows first) followed by a separate SELECT MIN(dg.spend_limit_cents) INTO ... (aggregate over the now-locked, stable rows in a second query) — the row-locking guarantee is preserved, just split across 2 statements instead of attempted in 1.

1 genuine security gap found and fixed during the SECTION 4 SELF-AUDIT (not live guard testing, a separate, later read-only pass): agents.kill_switch_event had tenant_id + GRANT SELECT, INSERT TO authenticated but ZERO RLS policies — any tenant session could read every other tenant's kill-switch history and forge a kill/suspend/resume event against another tenant's agents (or, though WITH CHECK below correctly blocks this path for ordinary tenant sessions, a platform-wide 'global' kill with tenant_id IS NULL). Fixed with the same established 2-policy mixed-scope RLS pattern already used by agent_eval_suite/rollback_recipe in this same build (a SELECT policy allowing tenant_id = current session's tenant OR tenant_id IS NULL, paired with an ALL policy scoped strictly to the session's own tenant for writes). Live-reproduced: a cross-tenant SELECT returns 0 rows for another tenant's event; a cross-tenant OR global forged INSERT is rejected; a legitimate own-tenant INSERT still succeeds. Regression test I5 (agents-schema.spec.ts) proves all 3 outcomes.

Section 4 self-audit, full A–P+T+U checklist — 2 real GAPs found and disclosed, one FIXED, one logged: Item J (JSONB documentation) — most JSONB columns across this build initially lacked a documented example shape; fixed by adding concise inline shape-example comments to all ~15 logical JSONB columns spanning task.ts, eval.ts, shadow.ts, action.ts, policy.ts, decision_context.ts, skill.ts, tool.ts (confirmed present in the actual source files as of this entry). Item K (tenant_id-leading index coverage) — 12 tenant-scoped tables have no tenant_id-LEADING index: agent_eval_case, agent_event_log, agent_shadow_decision, agent_thread, decision_context_feature/_forecast/_knowledge_source/_metric/_policy, evidence_retention_policy, kill_switch_event, rollback_execution — logged as a GAP to OPEN_ITEMS.md, deliberately NOT fixed this pass: RLS correctness is unaffected (policies work regardless of index presence) and each table's natural query path is via its own FK-indexed parent (snapshot_id, eval_run_id, etc.), not a direct tenant-wide scan. Item T (trigger audit) found and fixed the record-IS NOT NULL PL/pgSQL bug above. All other items (A, C–I except J, L–P) PASS — independently spot-checked for this entry against the actual migration/schema files (JSONB comment presence, the polymorphic_target_registry shape, the per-partition GRANT/RLS re-application DO-block discipline on all 3 newly-partitioned tables, the composite-FK UNIQUE(id, tenant_id, created_at) shapes) with no discrepancy found; item U (Design-Phase Integrity 4-block requirement) is N/A for the agents schema itself — brand-new schema with no v1 predecessor as an actual built table set to diff against, consistent with how this build has treated item U for every other genuinely-new schema (Phases 3–4).

3 pre-existing forward-ref OPEN_ITEMS.md rows CLOSED the same day, because Phase 5 landed their target tables (workload_class, agent_action): ai.routing_policy.workload_class_id → agents.workload_class(id) (plain FK — workload_class is global, no tenant_id); signals.outcome_observation.agent_action_id and signals.outcome_authority.agent_action_id → agents.agent_action(id, tenant_id) (composite FKs). Pre-migration orphan audits found 0 violating rows for all 3 before wiring. Wiring these wasn't just a schema edit: Phase 4's own pre-existing signals-schema.spec.ts had used 5 hardcoded placeholder agent_action_id UUID literals that had to be retrofitted with a real, minimal fixture chain (identity.actor → agent_identity → decision_context_snapshot → ai.agent_execution → agents.agent_decision → agents.agent_action) to keep passing against the now-real FK constraints. A 4th, related forward-ref — the 3 signals as-of functions' REVOKE EXECUTE FROM PUBLIC with no matching GRANT EXECUTE to agent_reader — remains open, since agent_reader is Phase 6's own deliverable, not this phase's; see OPEN_ITEMS.md (row discovered in Phase 4, cross-referenced here since Phase 5 confirmed the role still doesn't exist).

6 disclosed design judgment calls, all recorded as code comments in the Drizzle files at the point of the decision:

  1. tool_catalog (v1) is SUPERSEDED by tool_definition/tool_version (A2b's version-row pattern applied to tools) — v1's tool_catalog already carried exactly the columns A2b requires to be version-pinned (input_schema/is_write/risk_tier) but had no version concept at all; since this whole module is built fresh with zero live rows anywhere, tool_catalog is not built at all — its columns fold directly into tool_definition (identity) + tool_version (the versioned, certifiable payload), mirroring how A2/I5 supersede identity.agent_skill with skill_definition/skill_version. See packages/db/src/schema/agents/tool.ts header.
  2. A1's domain→module_id retype is scoped to EXACTLY 3 columns (agent_task.domain, tool_definition.domain, skill_definition.domain) per A1's own explicit scope-limiting text — deliberately NOT extended to agent_performance_profile.domain/agent_autonomy_profile.domain, which stay free-text. See packages/db/src/schema/agents/task.ts.
  3. agent_eval_run.eval_suite_version_id retargets to agent_eval_suite_version.id (A2b's version-pinning pattern), not the identity row (agent_eval_suite.id). See packages/db/src/schema/agents/eval.ts.
  4. agent_action has NO agent_task_id column — GUARD 4's trigger derives it via a join through agent_execution_id instead, a structural fix (not a patch) to a genuine gap in v3's own literal SQL, which referenced a nonexistent column.
  5. A3's "trigger on tenant_agent_deployment" is resolved instead as a trigger on agents.agent_skill_assignment (the only table with both agent_identity_id + skill_version_id), folding A3's cert-check + BLOCKER5's duty-check + A8 Rule 4's policy-bound check into ONE function, validate_skill_activation() (GUARD 6). See migration SECTION 8.
  6. A2b retirement-rule-1 checks are split by actual column location: ai.agent_execution checks only its own tool_version_id (a separate, sibling trigger, reject_retired_tool_version()); agents.decision_context_snapshot checks its own model_version_id/prompt_version_id/skill_version_id/toolset_version_id (T1, reject_retired_decision_context_versions()) — A2b's own prose names all 4 generically without pinning which table carries which reference, a mapping only settled later by I1/BLOCKER6.

Transitional Drizzle barrel collision, disclosed and resolved via explicit named re-exports, not silently papered over: identity.agent_skill_assignment (v1, still live and actively used by production IdentityService code today) and the new agents.agent_skill_assignment (I5's own destination table, empty, awaiting Phase 6's identity reopen to drop the old one and complete the move) are real tables that coexist simultaneously during this transitional window. packages/db/src/schema/index.ts resolves the plain name agentSkillAssignment to the identity export (load-bearing production code already imports it under that name); the new agents-schema table is available under the alias agentsAgentSkillAssignment until Phase 6 drops the old table and the alias can be retired in favor of the plain name.

Other same-pass amendments, all disclosed above or in their own file headers: packages/db/src/schema/ai/execution.ts (ai.agent_execution +8 columns), packages/db/src/schema/ai/routing.ts (workload_class_id FK wired), packages/db/src/schema/signals/outcome.ts (2 composite FKs wired), packages/db/src/schema/approvals/request.ts (CHECK widened + drift fix), packages/db/src/schema/index.ts (barrel + the agentSkillAssignment naming-collision fix). apps/api/src/platform/__tests__/signals-schema.spec.ts (Phase 4's own file) was retrofitted with the real agent_action fixture chain described above, not just the new agents-schema.spec.ts.

Regression tests: apps/api/src/platform/__tests__/agents-schema.spec.ts, new file, 27/27 passing (24 from the initial build + T2/T3/H2 added post-verification, see addendum below) — table existence (47 tables/475 columns on the logical basis, ai.agent_execution's 8 new columns, polymorphic_target_registry's 4 seeded rows), all 8 trigger-backed guards (kill-switch block/resume, kill-switch mid-flight claim rejection, kill-switch propagation to an in-progress task with correct fencing/cancellation, atomic task claim + fencing with lease-renewal never bumping the token, runaway step/cost ceiling BLOCK behavior, skill activation's 4 sub-cases including the A8 Rule 4 fix, the saga gate + action/decision consistency, the T1 retirement-version-reject guard, manifest self-containment/retention-binding/append-only), and a GRANT-shape sweep (global catalog tables SELECT-only, kill_switch_scope_state zero write grants for authenticated since it's native-upsert-only via a SECURITY DEFINER trigger, append-only tables carry no UPDATE/DELETE grant, RLS cross-tenant isolation on agent_task, and I5 — the kill-switch-event RLS fix's own dedicated regression test).

Full apps/api suite: 1198/1198 green (serially — npx jest --forceExit --runInBand; a known, pre-existing connection-pool-exhaustion flake in database/__tests__/rls-cross-tenant.spec.ts intermittently fails ONLY under parallel workers, unrelated to this build, documented since PROJECT_DECISIONS #37).

2 Postgres partitioning confirmations this phase reused/extended from Phases 2/4, applied to the 3 newly-partitioned tables (decision_context_snapshot, decision_context_manifest, agent_decision, all PARTITION BY RANGE(created_at) monthly, 13 partitions + DEFAULT, matching ai.agent_execution/signals.outcome_observation's own proven shape): GRANT/RLS do NOT propagate to child partitions (a per-partition DO-block loop re-applies both after every CREATE TABLE ... PARTITION OF, matching Phases 2/4's own established discipline); triggers created directly ON a partitioned PARENT table DO automatically clone to every partition (Postgres 11+, confirmed live, no DO-block loop needed for trigger creation — only for GRANT/RLS).

This entry documents the Phase 5 build itself, including its own live guard-reproduction and Section 4 self-audit findings (both already fixed and disclosed above); a separate, evidenced independent lock-gate verification pass — the same standard applied to Phases 1–4 (entries #62–#65) — is expected to follow as its own step before this module is declared formally locked, per this build's own established sequencing discipline. See docs/open-items/OPEN_ITEMS.md (rows dated 2026-07-15, tagged "agents-v2/v3 build Phase 5") for the 3 closed forward-refs, the open agent_reader GRANT EXECUTE item, the Item K tenant_id-index gap, and the record-IS NOT NULL PL/pgSQL pitfall logged as an informational, already-fixed note.

Schema-only — no AgentsService yet. Phase 6 (identity reopen to drop the old agent_skill_assignment, agent_reader role + agentReaderDB() connection helper, an ESLint rule banning adminDb/tenantDB/set_config from agent code paths) is next and closes out the entire 6-phase agents-v2/v3 build.

POST-VERIFICATION ADDENDUM (2026-07-16, same day): the mandatory independent lock-gate verification pass (2 separate agents — a Section 4 re-audit and an adversarial from-scratch guard reproduction, matching entries #62–#65's own established standard) ran against the completed build above and found 2 real FAILs the build's own self-audit missed entirely, both fixed same-day:

  1. FAIL (Item T) — skill/tool/model-scoped kill-switch directives blocked nothing at new-work-creation time. propagate_kill_switch_fencing() correctly fenced an ALREADY-IN-PROGRESS task for these 3 scopes (via its own join through agent_decision→decision_context_snapshot→ai.agent_execution), but both call sites of is_agent_blocked() (check_agent_task_not_blocked() and ai.check_agent_execution_not_blocked()) hardcoded NULL for the skill/toolset/model arguments — a genuine, previously-undisclosed gap in GUARD 1/2's own "single fail-closed resolver" framing above. Root cause: neither agent_task (never carries these refs at all) nor ai.agent_execution (only carries a raw tool_version_id, a shape mismatch with is_agent_blocked()'s own toolset-version-shaped 'tool' scope resolution) has access to all 3 values at its own gate-trigger firing point. Fixed with 2 changes: (a) ai.check_agent_execution_not_blocked() gained a direct 'tool'-scope check resolving NEW.tool_version_id's own tool_definition_id (not routed through is_agent_blocked(), whose shape doesn't fit a raw tool version); (b) agents.reject_retired_decision_context_versions() (T1, GUARD 8) — the actual earliest point in the data model where skill_version_id/toolset_version_id/model_version_id are ALL jointly known, on agents.decision_context_snapshot INSERT — now also calls is_agent_blocked() for those 3 scopes, agent_identity_id intentionally NULL (not yet known at this point; the function simply skips that one scope check on NULL). Both live-reproduced: a killed tool_version correctly rejects a new ai.agent_execution; a killed skill_version correctly rejects a new decision_context_snapshot; both a no-reference control and a non-killed control still succeed. New regression tests T2/T3 (agents-schema.spec.ts).
  2. FAIL (Item H) — agents.agent_eval_case.eval_run_id carried ZERO FK enforcement. Only tenant_id had one; live-reproduced by the verifying agent — a tenant could insert an agent_eval_case row with its own tenant_id but eval_run_id pointing at a REAL agent_eval_run row belonging to a different tenant, with no rejection, despite agent_eval_run already carrying the UNIQUE(id, tenant_id) prerequisite this codebase's own convention uses everywhere else for exactly this shape. Fixed with a standard composite FK, (eval_run_id, tenant_id) → agent_eval_run(id, tenant_id) — pre-migration orphan audit found 0 violating rows. New regression test H2 (agents-schema.spec.ts).

Both fixes applied to the live DB, packages/db/migrations/20260716000000_agents_module_new_schema.sql (new SECTION 11), and the Drizzle source (ai/execution.ts's sibling ai/routing.ts untouched; agents/eval.ts gained the FK; the 2 function bodies live only in the migration, matching this codebase's convention that PL/pgSQL function bodies are not modeled in Drizzle). The verification also disclosed several GAP-severity items, all logged to OPEN_ITEMS.md (2026-07-16 rows) rather than silently accepted: Item M (agent_autonomy_profile.current_mode has no DB-level tie to the real enforcement mechanism, identity.agent_duty_grant.authority_level — advisory-only, can drift); Item P (tool_definition/toolset_definition/skill_definition have updated_at columns but no maintaining trigger, and kill_switch_scope_state.last_event_id is a bare FK); Item B (6 join/global tables in schema_docs/agents.md are missing their explicit "No RLS" annotation line — a documentation-only gap, the live DB config itself is correct). Full apps/api suite re-verified green after both fixes: 1201/1201 (serially; the same pre-existing, build-unrelated connection-pool flake noted above).

This closes the module's own mandatory independent-verification gate. agents (module #28) is now formally schema-locked.

67. Identity Reopen (6th time) + agent_reader Role + ESLint Gate (agents-v2/v3 Build, Phase 6 of 6 — CLOSES THE ENTIRE BUILD)

2026-07-17, same day as entry #66. Phase 6 was not spelled out verbatim as its own section in either design doc (vrida-agents-v2-design-amendment-2026-07-11.md, vrida-agents-v3-correction-pass-2026-07-12.md — both grep-confirmed to contain zero literal "Phase 6" text); its scope is drawn from 2 authoritative sources instead: (a) the comment written during Phase 5's own build on agents.agent_skill_assignment (packages/db/src/schema/agents/skill.ts) explicitly stating "Phase 6's identity reopen drops the old table outright, no backfill needed," and (b) entry #66's own closing line naming the identity reopen + agent_reader role + agentReaderDB() helper + ESLint rule as the phase's contents. A discrepancy in this session's own earlier task-tracker phrasing ("+ files reopen (governance cols)") was investigated and dropped as stale — no such item appears in either authoritative source, and no "governance columns" concept was ever named anywhere in the agents-v2/v3 design corpus.

Part 1 — Identity reopen: drop identity.agent_skill_assignment/agent_skill, cut IdentityService over to agents.skill_definition/skill_version/agent_skill_assignment. Pre-migration audit (live, mandatory per this codebase's own Design-Phase Integrity rules): identity.agent_skill_assignment had 0 live rows; identity.agent_skill had 13 live rows, ALL confirmed test debris (test.skill.%/ti3.skill.% code patterns, matching this codebase's own established TEST_MARKER convention — left behind by test runs across this session that didn't reach their own afterAll cleanup, not real business data; isolated and deleted, matching the same "isolated dev-seed fixture junk" disposition this codebase has reached before, e.g. entry #54's own orphaned-row resolution). Both tables dropped in packages/db/migrations/20260717000000_identity_reopen_drop_legacy_agent_skill.sql. identity is now 36 tables / 410 cols (down from 38/429 — the only column-count change this phase).

IdentityService's 4 skill methods (listSkillCatalog, assignSkillToAgent, removeSkillFromAgent, listAgentSkillAssignments) plus authorizeAgentAction's skill-check half were rewritten to join through agents.skill_version/skill_definition instead of the dropped identity tables — a genuine semantic shift disclosed here rather than smoothed over: assignment is now at skill VERSION granularity, not skill-identity granularity (agents.agent_skill_assignment.skill_version_id, not the old agent_skill_id), matching A2b's own versioned-catalog design. Callers now pass a skillVersionId, and listAgentSkillAssignments's return field was honestly renamed skillVersionId (from skillId) rather than keeping a now-misleading name for convenience. listSkillCatalog's return shape also changed ({id, code, name, lifecycleStatus}, dropping category/moduleCode — no direct equivalent on skill_definition, which is a flatter catalog than the old identity.agent_skill). Blast radius was confirmed contained: zero controllers or DTOs reference any of these 4 methods today (grep-verified), so this is a safe, disclosed API-shape change with no live HTTP consumer.

A real, previously-undocumented guard was discovered live during this cutover's own test-writing pass: agents.validate_skill_activation() (GUARD 6, built in Phase 5) requires a valid, unexpired, unrevoked agents.skill_certification row (plus its own toolset_version) before agent_skill_assignment.is_enabled=true is accepted — test fixtures across identity-machine.spec.ts and identity-tenant-isolation-3.spec.ts needed to construct a full certification chain (skill_definition → skill_version → toolset_definition/toolset_version → skill_certification), not just the skill row itself. This is Phase 5's own guard working exactly as designed, not a new gap — logged here only because it was a genuine surprise this build's own earlier summary of Phase 5 hadn't flagged as a downstream test-writing cost.

Part 2 — agent_reader role + agentReaderDB() connection helper. Per the original agent-orchestration design proposal (vrida-agents-module-design-proposal-2026-07-11.md, Gap 9): a dedicated, SELECT-only, RLS-enforced Postgres role for agent-execution read paths, mirroring consumer_authenticated's own shape exactly (NOLOGIN NOINHERIT, granted to authenticator). Scope is deliberately narrow — the 2 concrete targets the design named, nothing broader invented: files.document_chunk/document_index (SELECT, closing OPEN_ITEMS row 317) and the 3 signals.*_as_of() functions (EXECUTE, closing OPEN_ITEMS row 332, which had its REVOKE stubbed ahead of this role's build back in Phase 4). Migration: packages/db/migrations/20260717000001_agent_reader_role.sql.

A real gap in the original design doc itself was found and fixed during this build, not present in either OPEN_ITEMS row or either design doc: the design's own claim that "RLS policies already on those tables ... apply unchanged — agent_reader inherits the same tenant-isolation enforcement authenticated already has" is FALSE as literally stated. Live-confirmed via pg_policies: document_chunk_tenant_isolation/document_index_tenant_isolation are both roles = {authenticated} — a role-scoped RLS policy in Postgres applies ONLY to sessions running as that exact role (or an INHERIT member of it), and agent_reader is a separate, non-member, NOINHERIT role. GRANT SELECT alone would have left every agent_reader query silently returning zero rows (RLS default-denies when no policy matches the connecting role) — a broken-not-narrower posture, not "the same enforcement." Fixed with 2 NEW, FOR SELECT-only policies scoped TO agent_reader (document_chunk_agent_reader_select/document_index_agent_reader_select), deliberately not by widening the existing FOR ALL/TO authenticated policies (which would also implicitly permit write access at the RLS layer beyond what the GRANT already restricts — doubly-enforced read-only: GRANT SELECT only + RLS SELECT-only policy, matching this codebase's own established belt-and-suspenders posture elsewhere).

agentReaderDB() (packages/db/src/client.ts) mirrors consumerDB() exactly: SET LOCAL ROLE agent_reader + set_config('app.current_tenant_id', ...). All 4 guards live-reproduced via direct psql sessions before being captured as durable regression tests (rls-cross-tenant.spec.ts, 4 new tests): tenant-scoped SELECT returns only the session tenant's own row; a second tenant-scoped session sees only its own (cross-tenant isolation); an INSERT attempt is rejected (42501, GRANT-level — agent_reader has no write grant anywhere); signals.get_feature_as_of() EXECUTE succeeds with no permission error (SECURITY DEFINER, no USAGE ON SCHEMA platform needed by the caller since signals_function_owner already holds it).

Part 3 — ESLint gate. apps/api/eslint.config.mjs gained a scoped override for src/agents/**/*.ts (excluding __tests__, matching every existing *.spec.ts file's own legitimate need for getAdminDb()/tenantDB() fixture setup/teardown): no-restricted-imports bans adminDb/getAdminDb/tenantDB from @vrida/db, and a no-restricted-syntax rule (TemplateElement[value.raw=/set_config/]) bans hand-rolled set_config(...) calls — both closing the OPEN_ITEMS row 318 gap disclosed during the Files module's own design verification ("buildable TODAY, independent of the Files module or the AI runtime"). Verified firing correctly via a temporary probe file under a scratch src/agents/ directory: 4/4 violations caught (3 restricted imports + 1 raw set_config), the equivalent probe under src/agents/__tests__/ passed clean (exemption confirmed), and an unrelated pre-existing file (identity.service.ts, which legitimately imports getAdminDb) was confirmed unaffected by the scoped rule. Probe files removed after verification, no src/agents/ directory exists in the committed tree.

Honest scope disclosure, not a claimed-but-unlogged deferral: no AgentsService or any other agent-execution read path exists in this codebase yet, so agent_reader/agentReaderDB() have zero real call sites today — the same position tenantDB() itself was once in, before Remediation Phase 1 gave it its first real callers. The role's narrower GRANT boundary is provably correct in isolation (all 4 guards pass) but remains structurally inert until real agent-execution code is built and adopts agentReaderDB() instead of tenantDB()/adminDb; the ESLint rule only fires once files actually exist under src/agents/** to lint. Logged as a new, explicit OPEN_ITEMS row (not silently treated as "done") rather than repeating the same "role exists therefore the gap is closed" overclaim the original design proposal's own independent verification (Lens C) had to catch once already.

Full apps/api suite green: 1205/1205 (up from 1201 — 4 new agent_reader regression tests in rls-cross-tenant.spec.ts; one transient re-run needed due to the same pre-existing, build-unrelated Postgres connection-pool flake noted in entries #37/#66, confirmed non-reproducing on retry with connection count well under max_connections).

MANDATORY INDEPENDENT LOCK-GATE VERIFICATION (2026-07-17, same day): 2 separate agents ran a genuinely independent, evidenced verification against the live DB and source (not a self-graded audit), matching the standard this codebase's own SCHEMA_DESIGN_RUNBOOK requires (Bug Class #12). Both re-derived every claim in this entry from scratch — live-reproducing the agent_reader RLS/GRANT guards via their own freshly-built 2-tenant fixtures (created and fully cleaned up), independently testing the ESLint rule via their own throwaway probe files, and independently re-running the full suite. Verdict: CLEAN on Phase 6's own new surface area — zero BLOCKERs, zero MAJORs introduced by this phase. One verifier's connection-pool-flake experience was notably worse than the other's (609 failures on a 2nd consecutive run before a 3rd clean run succeeded), which if anything makes the flake's pre-existing, environment-level nature (not a Phase 6 regression) MORE credible, not less — confirmed via a git stash/re-run isolation test showing the connection-exhaustion pattern persists even with Phase 6's own code entirely reverted against the same already-migrated DB.

One verifier surfaced a real, previously-undisclosed MAJOR finding that is Phase-5-origin, not introduced by Phase 6: agents.agent_skill_assignment.agent_identity_id is a bare (non-composite, non-tenant-scoped) FK into identity.agent_identity(id) — this codebase's own established convention elsewhere is a composite (col, tenant_id) FK for exactly this shape, and the root cause is that identity.agent_identity itself lacks the UNIQUE(id, tenant_id) prerequisite. Live-confirmed not currently exploitable via any live application code path: the sole write path, IdentityService.assignSkillToAgent() (touched by THIS phase's own cutover, but not the site of the bug — the bug is the FK's own shape, unchanged by the cutover), already re-fetches and checks the target agent's own tenant_id at the application layer before insert, correctly rejecting a cross-tenant assignment. Per this codebase's own established practice for this exact bug class (the 2-batch Header/Line Remediation effort, PROJECT_DECISIONS #46-#53, repeatedly deferred out-of-scope bare FKs to their own future reopen rather than scope-creeping an unrelated fix) — logged as a new, open OPEN_ITEMS row (agents schema, FK type), not fixed in this pass, and not blocking this lock.

This closes the entire 6-phase agents-v2/v3 build (Phase 1: platform reopen, #62; Phase 2: ai reopen, #63; Phase 3: semantics, #64; Phase 4: signals, #65; Phase 5: agents module #28, #66; Phase 6: this entry). identity is re-locked at 36 tables / 410 cols; files/signals are unchanged structurally (grant/policy-only additions).

68. Phase 1: Security & Integrity Remediation — Live-DB Structural Sweep Across All 25 Schemas

2026-07-18. A dedicated remediation pass, scoped and authorized separately from the 6-phase agents-v2/v3 build (#62-#67) that had just closed. Governing standard, stated up front and held throughout: for every fix, the test is not "does the correct path work?" but "can a caller with ordinary privileges do the wrong thing anyway?" Every enforcement claim below was live-reproduced via a before/after demonstration (bad action succeeding pre-fix, rejected post-fix) — "constraint added" was never treated as evidence on its own. Explicit scope discipline held throughout: no nursery-vertical extraction, no new business capability, and shared schema's own write-permission lockdown is deliberately deferred to Phase 2's close (see the standing rationale at the end of this entry) — this phase only ever changes who can write to a table and whether its claimed guarantees are real, never what a table means.

Item 1 — platform.polymorphic_target_registry lockdown. Root-caused to a specific, dated migration statement, not treated as an isolated oversight: ALTER DEFAULT PRIVILEGES IN SCHEMA platform GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO authenticated (set 2026-07-08) silently grants broad write access to any table created in platform afterward, regardless of that table's own later, narrower, explicit GRANT. polymorphic_target_registry — a registry table whose whole purpose is validating polymorphic FK targets codebase-wide — had picked up unintended INSERT/UPDATE/DELETE this way. Fixed: REVOKE INSERT, UPDATE, DELETE ON platform.polymorphic_target_registry FROM authenticated (SELECT retained). Migration: 20260718000000_phase1_remediation_item1_polymorphic_registry_lockdown.sql. This root-cause framing directly shaped Item 2's own methodology below — a live-privilege inventory, not migration-file reasoning.

Item 2 — GRANT/REVOKE structural sweep, all 25 business schemas. A live inventory of all 325 authenticated-grantee rows in information_schema.role_table_grants (not a reading of migration files, which cannot show the cumulative, additive result of default-privilege statements layered over time) surfaced 3 distinct issue groups, each closed in one migration (20260718000002_phase1_remediation_item2_grant_revoke_structural_sweep.sql, 14 REVOKE statements):

  • Group 1 — GRANT-additivity on append-only tables (2 tables). Postgres ACLs are additive across granularity: a broad GRANT ... ON ALL TABLES IN SCHEMA issued after a table-specific REVOKE silently re-grants the revoked privilege. Found live on approvals.approval_event and returns.return_resolution_line — both had their own append-only trigger installed correctly at build time, but a later schema-wide GRANT had quietly reopened UPDATE/DELETE anyway. Fixed via a second, later REVOKE.
  • Group 2 — reference/config catalogs (8 tables) narrowed to SELECT-only for authenticated, matching this codebase's own established convention for migration-maintained catalogs (module_catalog, tier_definition, etc.) that were missing the narrowing.
  • Group 3 — cross-tenant-leak surfaces (4 tables) fully REVOKEd from authenticated: identity.actor, identity.identity_user, identity.identity_session, platform.tenant. Confirmed via code grep that IdentityService/PlatformService read these exclusively through getAdminDb() (a superuser connection that bypasses GRANTs/RLS entirely) — so this REVOKE has zero behavioral impact on any real application code path today, but closes the direct-authenticated-connection attack surface these 4 foundational identity tables represented. shared's own 12 tables were deliberately excluded from this sweep — see the deferral note at the end of this entry.

Item 3 — append-only enforcement, 16 tables. A structural sweep (candidates: any table with no updated_at column, on the theory that its absence signals append-only intent) produced 34 candidates; live inspection classified each. "No updated_at" is a naming convention, not enforcement — it found 16 tables that had never received either of the two required layers (REVOKE UPDATE, DELETE FROM authenticated + the shared platform.reject_append_only_mutation() BEFORE UPDATE OR DELETE trigger): platform.agreement_acceptance/ai_credit_transaction/tenant_internal_activity/tenant_lifecycle_event/tenant_usage_summary; crm.customer_note/customer_consent/customer_merge; inventory.item_merge; pricing.price_change_log; agents.decision_context_feature/decision_context_forecast/decision_context_knowledge_source/decision_context_metric/decision_context_policy/agent_shadow_decision. Migration: 20260718000003_phase1_remediation_item3_append_only_enforcement.sql. 3 tables from the same candidate list were deliberately excluded and reclassified "validated-mutable", not append-only, after column-shape inspection found a genuine, already-tested reconciliation trigger validating an UPDATE against a header sum rather than rejecting it outright — billing.ar_charge_line, purchasing.vendor_credit_line, platform.subscription_invoice_line. Installing the blanket append-only trigger on top would have silently made that UPDATE branch dead code — this distinction is now codified as its own case in docs/database/SCHEMA_CONVENTIONS.md §20. A pre-existing doc bug was also caught and fixed in the same pass: agents.rollback_execution was mislabeled "append-only" in both its Drizzle comment and docs/database/schema_docs/agents.md; it is genuinely mutable (a status lifecycle) and was never intended to be append-only — corrected, not enforced.

Item 4 — consumer.event consent enforcement. Read this codebase's own existing documentation first rather than inventing new business capability: a two-level consent model already existed on paper — platform/cross-merchant consent in consumer.consumer_consent (global, no tenant_id), and a separate, deliberately-unlinked merchant-local consent in crm.customer_consent. Neither was the right enforcement surface for consumer.event specifically; the actually-correct existing surface, found by reading further, is consumer.consumer_merchant_link.consumer_opt_in (a per consumer×tenant boolean already modeling exactly "has this consumer opted in to this merchant's tracking"). New function consumer.validate_event_consent() + BEFORE INSERT trigger trg_event_validate_consent: rejects any consumer.event row naming a consumer_id whose merchant link is missing or not opted in; anonymous events (consumer_id IS NULL) bypass the check entirely, unaffected. Migration: 20260718000004_phase1_remediation_item4_consumer_event_consent.sql.

Item 5 — processor vendor lock-in → platform.processor_catalog. payments.payment_intent.processor and tax.tax_calculation.provider were both closed-vocabulary CHECK constraints naming Stripe by string literal — a deferred OPEN_ITEM from the original agents-v2/v3 build's own Phase 1 (PROJECT_DECISIONS #62) flagged this as the "minimal-now" step of a larger vendor de-primitivization, triggered "before a second payment processor is integrated." New table platform.processor_catalog (code PK, kind CHECK'd to payment_processor/tax_provider, display_name, is_active, timestamps + set_updated_at trigger), seeded with 4 rows. Deliberately placed in platform, not reused from admin.integration_provider_catalog (which coincidentally already had a 'stripe' row) — a tenant-configurable integration and a platform-level infrastructure fact are different concepts, and conflating them would have made a future tenant-specific Stripe-alternative integration indistinguishable from the platform's own processor vocabulary. Both payment_intent.processor and tax_calculation.provider were retargeted from CHECK to a real FK against processor_catalog.code. Migration: 20260718000005_phase1_remediation_item5_processor_catalog.sql; platform is now 36 tables / 524 cols (up from 35/518 — the only table/column-count change in this entire remediation phase).

Item 6 — final cross-module FK audit + bare FK fixes. A live sweep of every tenant-scoped FK column found 115 bare (non-composite) FKs across the codebase — deliberately not bulk-fixed: roughly 50 of the 115 fit two apparently-deliberate existing patterns (site_id soft-references, agent_identity_id-shaped bare references) that need individual per-table intent confirmation before a mechanical pass would be safe, not a blind rewrite. 2 fixes judged safe and made now: identity.agent_identity gained the prerequisite UNIQUE(id, tenant_id), closing the exact MAJOR finding PROJECT_DECISIONS #67's own independent verification surfaced and deliberately deferred — agents.agent_skill_assignment.agent_identity_id is now a real composite (agent_identity_id, tenant_id) FK; and 4 bare FK columns on purchasing.vendor_return_line (inventory_movement_id, item_variant_id, purchase_order_line_id, lot_id) were retargeted to their already-UNIQUE(id,tenant_id)-carrying parents. Migration: 20260718000006_phase1_remediation_item6_fk_audit_fixes.sql. One candidate, identity.identity_access_event.session_id, was investigated and explicitly not fixed: 1548 of 1561 live rows (99.2%) are orphaned against identity.identity_session, meaning the composite-FK-safe fix would either reject nearly all live data or require a bulk-null backfill whose correctness this pass could not verify without deeper investigation into why the orphan rate is so high — logged as a disclosed, deferred ruling, not silently skipped. The broader 115-row finding (scratchpad: item6-bare-fks.tsv) is logged to docs/process/OPEN_ITEMS.md as its own row for a future dedicated pass.

Item 7 — drift CI gate. packages/db/scripts/drift-check.ts: a live-DB-vs-Drizzle-vs-docs diff tool, built because every finding in this remediation phase was itself found by comparing the live database against what source/docs claim, not by reading either in isolation. Three checks: (1) every Drizzle-exported table exists live; (2) any live table carrying the platform.reject_append_only_mutation() trigger must not have UPDATE/DELETE granted to authenticated (the exact bug class Items 1-3 found, now a standing invariant); (3) every live hand-written trigger's function name must appear as a literal string in packages/db/src/** or docs/database/schema_docs/** (this codebase's own established, if informal, convention for documenting objects Drizzle cannot model natively) — excluding the 2 shared, generically-documented functions every table reuses verbatim. Built with 3 iterations of live-reproduced false positives fixed in turn (partitioned-parent tables wrongly excluded via relkind; the wrong docs directory searched; 5 Supabase-platform-internal trigger functions wrongly flagged) until it reached a clean PASSED result. Live-reproduced as a real gate, not just "looks right": a real GRANT-additivity bug was deliberately re-introduced on consumer.event (GRANT UPDATE, DELETE ON consumer.event TO authenticated), the script correctly failed naming exactly that finding, then the grant was reverted and the script passed clean again. npm run drift-check added to packages/db/package.json. A GitHub Actions workflow, .github/workflows/db-drift-check.yml (triggered on any PR touching packages/db/migrations/**, packages/db/src/schema/**, packages/db/scripts/drift-check.ts, or docs/database/schema_docs/**; spins up a postgres:17 service, applies every migration in order, runs the gate), was authored to this codebase's own standard convention but is disclosed as unexercised — this environment cannot run GitHub Actions, so only the underlying script's own correctness is live-verified, not the CI wiring around it.

Item 8 — ai barrel export fix + tenant_module_activation RLS Drizzle fix. Completed earlier in this same remediation pass: the ai schema's barrel index.ts was missing 14 of its own table exports (present in the DB and in individual schema files, but never re-exported), which would have made drift-check.ts itself blind to that entire schema had it shipped first — fixed before Item 7 was built, not after. platform.tenant_module_activation's Drizzle definition was also missing its own RLS policy declaration (present live, absent in source — the exact class of drift this whole phase exists to catch).

Item 9 — missing set_updated_at triggers, 4 tables. A structural check (any table with an updated_at column but no maintaining trigger) found 4: admin.integration_provider_catalog, pos.tender_type_catalog, tax.jurisdiction_level_catalog, returns.return_source_line_tracker. Migration: 20260718000001_phase1_remediation_item9_missing_updated_at_triggers.sql. Live-reproduced correctly on all 4 (an UPDATE on a pinned row, selected via ORDER BY id LIMIT 1 \gset to avoid a nondeterministic-row bug caught in an earlier draft of this same check, now correctly advances updated_at).

Item 10 — doc/source drift cleanup. The original sub-item list for this item was lost to an earlier context-compaction event in this same session and was not reconstructed from guesswork. In its place, this entry's own docs fan-out (PROJECT_DECISIONS.md, docs/process/OPEN_ITEMS.md, docs/DOCS_INDEX.md, CLAUDE.md, plus the schema_docs/SCHEMA_CONVENTIONS.md updates folded into Items 1/3/4/5 above) constitutes the closest good-faith substitute available — every doc-drift introduced by Items 1-9's own changes is closed by this same pass. The original, broader-scoped Item 10 is logged to docs/process/OPEN_ITEMS.md as its own explicitly-reopened row, disclosed as not independently executed this pass rather than silently dropped.

Test suite adjustments. Item 3's append-only enforcement cascaded into ~13 test files whose teardown code used hard DELETE against tables that are now genuinely append-only (P0001 rejections), which then cascaded a second layer deeper into 23503 foreign-key violations on parent rows a surviving append-only child still referenced. Fixed systematically with a tryDelete helper (tolerating P0001/23503) reused from this codebase's own pre-established billing-schema.spec.ts/pos-schema.spec.ts precedent, applied across platform-tenant-mgmt.spec.ts, crm-schema.spec.ts, identity-controller.spec.ts, admin-*.spec.ts (4 files), platform-billing.spec.ts, platform-identity-absorption.spec.ts, platform-autonomy-backfill.spec.ts, platform-tenant-isolation.spec.ts, platform-remediation-phase4.spec.ts, platform-money-atomicity.spec.ts, admin-schema.spec.ts, and consumer-schema.spec.ts (Group E's fixture now pre-creates an opted-in consumer_merchant_link row per Item 4). Two schema-wide count assertions (platform-module-registry.spec.ts A1, platform-identity-absorption.spec.ts's column-count test) were updated from 35→36 tables / 518→524 columns to reflect Item 5's real, deliberate processor_catalog addition — not silently patched, both now carry an explanatory comment naming Item 5 as the source of the delta. Full apps/api suite: 1205/1205 (unchanged from the pre-remediation baseline — this phase changed enforcement and added exactly 1 new table, no new test count).

Confirmations on this phase's 8 named target properties:

  1. platform.polymorphic_target_registry is SELECT-only for authenticated and correctly modeled in Drizzle (packages/db/src/schema/platform/module_registry.ts) — CONFIRMED.
  2. Zero GRANT-after-REVOKE instances remain anywhere in the 25-schema live inventory (Item 2's own 3-group sweep, shared excluded per the deferral below) — CONFIRMED for the 21 non-shared schemas swept.
  3. All 16 structurally-enforced append-only tables from Item 3 carry both layers (REVOKE + trigger); all 3 candidate tables correctly reclassified validated-mutable rather than force-enforced — CONFIRMED.
  4. consumer.event rejects an INSERT naming a consumer_id with no opted-in merchant link, and passes anonymous events through unaffected — CONFIRMED, live-reproduced.
  5. processor (payments.payment_intent) and provider (tax.tax_calculation) are both catalog-driven FKs against platform.processor_catalog, no more closed-vocabulary CHECK — CONFIRMED.
  6. Zero unapproved bare tenant-scoped FKs — 2 judged-safe fixes made (Item 6); the broader 115-row finding is disclosed, not silently left unaddressed, and explicitly deferred pending per-table intent confirmation — CONFIRMED as "disclosed, not zero."
  7. The drift CI gate fails on an unmodeled raw-SQL object — CONFIRMED, live-reproduced via deliberate reintroduction of a real bug; the GitHub Actions wiring itself is unexercised (disclosed).
  8. The ai schema barrel exports all of its own tables (14 previously-missing exports restored) — CONFIRMED.

shared schema write-permission lockdown is deliberately deferred to Phase 2's own close, not overlooked. shared holds 12 tables of genuinely global, cross-tenant reference data (units of measure, plant taxonomy, currencies, payment-terms catalogs, etc.) with a fundamentally different access-control shape than every tenant-scoped schema this phase swept — no tenant_id column exists on most of its tables by design, so the same GRANT/REVOKE reasoning this phase applied elsewhere (tenant-leak surfaces, append-only ledgers) does not translate directly; shared's own write model needs its own dedicated design pass (which rows are Vrida-seed-only vs. tenant-extensible, e.g.) rather than a mechanical application of this phase's own patterns. This was the explicit scope boundary given at the start of this phase, held throughout — not a gap discovered after the fact.

MANDATORY EVIDENCED INDEPENDENT LOCK-GATE VERIFICATION (2026-07-18): a separate agent, with no visibility into this build, independently re-derived every claim above against the live DB and source — not a self-graded audit. Items 1-9: all CONFIRMED via live reproduction, not just constraint-existence checks: Item 1's lockdown was proven with a real rejected INSERT; Item 2's 3 groups were proven with a real rejected UPDATE (Group 1), a live grant query (Group 2), and a real rejected SELECT (Group 3), plus a shared.currency sanity check confirming that schema genuinely was untouched; Item 3 was proven by actually firing the append-only trigger on 2 sample tables (rejected) and actually UPDATing one of the 3 "validated-mutable" exclusions (succeeded, confirming the reclassification was correct, not a loophole); Item 4 was proven with a full 4-case fixture (no-link rejected, opted-out rejected, opted-in succeeds, anonymous succeeds); Item 5's FK-not-CHECK shape was confirmed via pg_constraint; Item 6's composite FKs were confirmed via pg_constraint; Item 7's gate was re-proven by the verifier independently re-running the exact same reintroduce-bug-then-revert sequence; Item 8's 21-table barrel completeness was independently recounted file-by-file. A further independent sweep beyond the named tables queried all 137 live tables (including partition children) carrying the append-only trigger and found zero further GRANT-additivity instances — strong positive signal beyond this entry's own named scope.

2 real findings were surfaced and are now fixed as of this same verification pass:

  1. Test-suite regression (real, now fixed). platform-identity-absorption.spec.ts's column-count test had its own descriptive string updated to say "524" but the actual expect(row.n).toBe(518) assertion body was never touched — an editing miss in this same remediation's own test-adjustment step, caught only by the independent verifier actually running the suite rather than trusting the prior "1205/1205 unchanged" claim. Fixed: assertion now reads toBe(524), matching the sibling platform-module-registry.spec.ts table-count test that was correctly updated the first time.
  2. Missing OPEN_ITEMS rows (real, now fixed). This entry's own text (Item 6, Item 10, and the shared deferral note) claims 4 new/updated OPEN_ITEMS.md rows exist; a first edit attempt had drafted them but a follow-up edit meant to add the CLOSED annotation to the pre-existing agent_skill_assignment row accidentally replaced the whole pending change instead of layering on top of it — the 4 new rows were silently never written. Caught only because the verifier grepped the file for 2026-07-18 and found a single hit instead of five. Fixed: all 4 rows now genuinely present in docs/open-items/OPEN_ITEMS.md (the 115-bare-FK finding, the identity_access_event.session_id ruling, the Item 10 disclosure, and the shared Phase 2 deferral note), verified via a direct grep re-check after the fix.

Full apps/api suite re-run after both fixes: 1205/1205, genuinely green this time (confirmed via a second full run, not assumed from the fix alone).

Verdict: this remediation phase is DONE. Items 1-9 are real, live-reproduced security/integrity fixes with zero further instances of the targeted bug class found in an independent broader sweep; both process gaps the independent pass surfaced (a stale test assertion, 4 missing doc rows) were mechanical, non-security-bearing editing misses in this phase's own closing steps, not flaws in the underlying migrations — and both are now closed.

69. Pre-Phase-2 Confirmation — CI Drift-Gate Enforcement, identity_access_event Orphan Root Cause, and 115→230 Bare-FK Triage

2026-07-18, same day, immediately before the nursery-vertical extraction (Phase 2). Two loose ends disclosed at the close of entry #68 needed resolution before that extraction could safely begin, plus the 115-row bare-FK finding needed real triage rather than remaining an OPEN_ITEMS footnote. A dedicated investigation ran across 3 independent fronts (a 6-agent fan-out: 3 investigations + 3 independent spot-checks, each re-deriving the load-bearing claim from scratch against the live DB/source), per the standing instruction to fix only what's trivially fixable and escalate what needs a decision.

Confirmation 1 — the drift CI gate does not actually fire or block, for 3 stacked, independent reasons. .github/workflows/db-drift-check.yml (built in entry #68, disclosed as unexercised) was found, empirically, to have never once been able to catch or block anything in this repo's real workflow:

  1. The trigger never fires. This repo lands 100% of changes via direct commits to main — gh pr list --state all returns zero rows, git log --oneline --merges returns zero merge commits across all 88 commits on main. The workflow's on: pull_request trigger is dead code under this repo's actual practice, independently re-confirmed by a separate verification pass.
  2. main has zero branch protection. gh api repos/.../branches/main confirms "protected": false, required_status_checks.enforcement_level: "off" — even a correctly-firing, correctly-failing gate would block nothing today. (The dedicated branch-protection API 403s on this private repo without a paid-plan upgrade; the plain branch-metadata endpoint confirms the same fact without that gate.)
  3. The CI Postgres service itself cannot run this repo's migrations. A real, unmodified run of all 90 migration files against a vanilla postgres:16/17-family Docker image (no Supabase bootstrap) fails immediately on migration #1 of 90 (CREATE POLICY ... TO "authenticated" → role "authenticated" does not exist) — this repo's schema depends on Supabase-provisioned roles (authenticated, likely consumer_authenticated/agent_reader/authenticator elsewhere) and a pre-installed extensions schema (pgcrypto, pgvector — confirmed missing from vanilla Postgres too via a direct CREATE EXTENSION vector failure). The workflow has zero bootstrap step for any of this.

The underlying detection logic itself remains genuinely sound — this is a CI-wiring gap, not a regression in Item 7's own script. Independently re-proven: drift-check.ts crashes non-zero (process.exit(2), caught by its own .catch()) against an unreachable/bad DATABASE_URL; against a genuinely empty database (zero migrations applied, confirmed via pg_namespace), it reports 333 real failures — every Drizzle-exported table flagged missing — never a false "PASSED". The specific vacuous-pass mechanism the task was scoped to hunt (a silent false-positive PASS against an empty/unmigrated DB) does not exist in this script.

3 decisions are needed from Srini before this gate can protect anything (none silently picked): (a) trigger convention — add push: branches: [main] to match actual practice, or adopt real PRs going forward; (b) CI Postgres image — swap to a Supabase-flavored image, or add an explicit role/extension bootstrap step to the vanilla image; (c) branch protection — requires a GitHub plan/billing decision for this private repo. Logged to docs/open-items/OPEN_ITEMS.md.

Confirmation 2 — the identity_access_event.session_id 99%+ orphan rate is 100% test-fixture debris, root cause fully traced, fixed same-day. A live sweep independently re-confirmed the ratio (1575 of 1588 populated rows, 99.18% orphaned as of this pass — the table has grown continuously since entry #68's 1561-row snapshot) and traced it to a single, exact mechanism: identity-session.spec.ts is the ONLY caller of IdentityService.createSession()/recordLogin()/recordLogout() anywhere in the codebase (grep-confirmed), and its own teardown hard-deleted identity.identity_session rows after every test run — violating that table's own documented design ("no deleted_at — sessions are permanent audit history", docs/database/schema_docs/identity.md, unchanged since original build). Every real production write path is sound: createSession() inserts the session row and immediately logs the login event against the id it just created; zero application code ever deletes a session. Evidence, independently re-sampled and confirmed on a second, disjoint set of 10 orphaned rows: 100% of orphaned rows have tenant_id IS NULL, event_type = 'login' (the exact shape of this one test path); 875 distinct orphaned actor ids, zero of which have any footprint anywhere else in the schema (no tenant_user, role_assignment, crm.customer reference — pure test-fixture actors); day-clustering (07-08 through 07-12) matching repeated dev/CI runs, not a smooth production-accumulation curve. The only 13 non-orphaned session_id rows in the entire table belong to 2 real actors (a genuine tenant_user and a genuine identity.operator) from the actual hand-driven 2026-07-09 admin-login E2E verification this codebase already documents. Fixed: identity-session.spec.ts's teardown no longer hard-deletes identity_session rows (each test already scopes its own assertions to a fresh randomUUID() actor via listActiveSessions(actorId), so leftover rows from other actors are harmless — matching the same append-only-adjacent precedent this file's own teardown already documents for identity_access_event); full 9/9 tests in that file still pass. docs/database/schema_docs/identity.md's DR-21 record and 3 column-doc locations, which have incorrectly claimed session_id was an enforced FK backed by a partial index since the column's original 2026-06-28 build (neither has ever existed in any migration), are corrected to describe the real, unenforced state, with the full root-cause reasoning recorded in DR-21 itself. The FK stays deliberately unenforced going forward — not because deletion is expected (it isn't; the table's own design says sessions are permanent), but because the already-accumulated orphaned rows live permanently inside the hard append-only identity_access_event ledger and cannot be backfilled or cleaned without bypassing that ledger's own reject_append_only_mutation() trigger. Confirmed zero impact on the operator/privileged-access audit trail today (9 of 9 operator-linked rows resolve correctly) — flagged as a latent, not live, exposure: the identical debris pattern would start accumulating the moment an automated operator-auth test suite adopts the same hard-delete-in-teardown shape, worth a note for whoever builds that suite.

The 115-bare-FK finding, triaged — real total is 230, not 115. A live 25-schema sweep (partition-child duplicates excluded, independently re-confirmed by a separate pass at the identical number) found 230 single-column FKs where both child and parent carry tenant_id. Categorized into 5 buckets:

  • 12 — mixed-scope (global-or-tenant) parents. identity.role, ai.ai_request, agents.rollback_recipe, crm.customer_segment_definition all use tenant_id IS NULL as a documented built-in/global-row marker (confirmed in each table's own Drizzle source comments and live-verified against IdentityService's own handling of exactly this pattern). A composite FK here would be a regression, not a fix — it would reject a tenant's legitimate reference to a global row.
  • 13 — agent_identity_id-shaped references into identity.agent_identity, the same shape as the already-fixed agents.agent_skill_assignment case (entry #68, Item 6) — parent already carries the UNIQUE(id,tenant_id) prerequisite. Cheap fix, currently dormant (no service layer yet for agents/ai).
  • 27 — site_id bare FKs into multi_loc.site, distinct from this codebase's own long-disclosed "site_id carries zero FK at all" precedent (platform.tenant.primary_site_id and 3 siblings) — these are real, existing single-column FK constraints, and the parent already carries the prerequisite from the 2026-07-10 site_id FK-wiring reopen. Cheap fix, currently dormant.
  • 61 — genuinely missing composite FKs, parent already has UNIQUE(id,tenant_id). Pure constraint retarget, no schema change to the parent needed. Concentrated in inventory (21), purchasing (14), orders/pos (11). Currently dormant — none of these modules has a service layer yet.
  • 117 — genuinely missing composite FKs, parent LACKS the prerequisite. 39 distinct parent tables need a new UNIQUE(id,tenant_id) added first — the same prerequisite-then-retarget shape the 2-batch Header/Line Remediation effort (entries #46-53) used repeatedly. This tier is comparable in scope to that entire effort.

2 of the 117 are concretely live-code gaps, not dormant schema debt — fixed immediately, not deferred. PlatformService.recordInvoice() inserted a caller-supplied subscription_id with zero tenant check (the method's own comment already said "naive write"); PlatformService.createSubscription() inserted a caller-supplied source_contract_id the same way. Both independently re-confirmed by a separate verification pass reading the actual service code. Neither was live-exploitable (grep confirms zero HTTP controller reaches either method today — only test files call them), but both were real, disclosed-in-code landmines waiting for the first billing controller. Fixed: both methods now verify the referenced row belongs to the caller's tenantId before insert (a tenant-scoped SELECT + NotFoundException, matching the exact 2026-07-08 tenant-ownership-fix idiom already established elsewhere in this same file, e.g. updateContractStatus), with 4 new regression tests (platform-billing.spec.ts, Group L) live-reproducing both the rejection and the legitimate same-tenant case. Full apps/api suite: 1209/1209 (up from 1205 — 4 new tests, zero regressions).

Recommendation: the remaining ~228-row finding needs its own dedicated, multi-batch remediation phase — not folded into Phase 2's nursery-extraction migration. Reasoning: it is a structural retrofit of ~20 already-locked, already-shipped modules, not new nursery-vertical schema — conflating the two would violate this codebase's own one-concern-per-reopen practice; the 39-parent-table UNIQUE(id,tenant_id) prerequisite requirement alone is comparable in scope to the entire 2-batch Header/Line Remediation effort and deserves the same batched-by-schema treatment (suggested grouping: crm+billing+identity; inventory+pos+orders+purchasing; platform+payments+ai+approvals+signals). The 40 cheap, dormant rows (site_id + agent_identity_id) can open that phase's first batch since their prerequisite already exists. Every one of the other ~228 findings sits in a module with zero service layer today, so none has any live write path — this is a pure schema-level, pre-emptive structural-integrity finding, the same category the returns.return_reason bug represented before it was caught at its own lock gate; treated with the same seriousness, not a rubber stamp.

Independent verification of this pass's own findings: a second, disjoint round of 3 agents independently re-derived the single most load-bearing claim in each of the 3 investigations before any of it was written up here. CI gate: independently re-ran the PR/merge-commit check and the branch-protection API call — both claims held exactly. Orphan root cause: independently re-sampled 10 different orphaned rows — every pattern (tenant_id NULL, event_type=login, zero-footprint actors, timestamp clustering) reproduced. FK triage: independently re-ran the sweep query (272 naive vs. 230 after correctly excluding partition-child duplicates — reconciled, not a discrepancy) and independently re-read both flagged Platform methods in source — both confirmed exactly as reported. Nothing in this pass was accepted on a single investigation's own say-so.

Full apps/api suite: 1209/1209. Docs fan-out: docs/open-items/OPEN_ITEMS.md (2 rows reconciled/closed, 1 new row added for the CI gate escalations), docs/database/schema_docs/identity.md (DR-21 + 3 column-doc corrections). shared's own write-permission lockdown (entry #68's own disclosed Phase 2 of this remediation effort) remains untouched by this pass — genuinely separate work, not conflated with the nursery-vertical Phase 2 this confirmation pass is named for.

70. Phase 2 — Nursery Vertical Extraction + shared Lockdown

2026-07-18, same day, immediately after the Pre-Phase-2 Confirmation pass (entry #69). Three independent external design reviews all found the same structural problem: a nursery-specific botanical taxonomy and nursery-flavored discriminator values had entered shared/inventory/multi_loc/consumer/offers — the vertical-neutral core this codebase has otherwise held to strictly across 28 modules. This is a single coordinated, one-migration RELOCATION — zero new business capability, zero grow-cycle/production/propagation capability added (that's Phase 3's own gift-card-adjacent scope, explicitly out of bounds here), and zero data lost.

Governing principle, now codified as SCHEMA_CONVENTIONS.md §21: a generic core table must never gain a vertical-only column or FK when the same relationship can be represented by a tenant-scoped vertical extension table. Vertical data enters only via (a) <vertical>_ref global dictionaries, (b) <vertical>.<entity>_profile tenant extension tables keyed to the core entity, (c) tenant-defined variant options, or (d) generic attribute-typed branches.

Part A — two new schemas. nursery_ref (global, Vrida/AI-curated, non-tenant-scoped, read-only-by-default like shared) and nursery (tenant-scoped extension, standard composite-FK/RLS conventions). FK direction confirmed correct throughout: nursery.item_profile/site_profile point INTO inventory.item/multi_loc.site — the core never points back.

Part B — the extraction, V1 through V6 (V7 below is inspection-only, no schema change):

  • V1: shared.climate_zone, plant, plant_common_name, plant_climate_zone moved to nursery_ref via ALTER TABLE ... SET SCHEMA (data/indexes/constraints/triggers preserved verbatim — the proven mechanic from the approvals-out-of-admin and receiving-out-of-purchasing extractions). Postgres FK constraints track the referenced table by OID, not schema-qualified name, so every FK into these 4 tables kept resolving correctly across the move without any FK-side change needed — independently proven via a from-scratch scratch-schema reproduction (create parent+child in schema A, move parent to schema B, confirm the join and the reject-on-bad-FK both still work with zero FK edits).
  • V2: inventory.item.plant_id replaced by nursery.item_profile (id/tenant_id/item_id composite-FK/plant_id/profile_type/care_attributes JSONB), UNIQUE(tenant_id, item_id) (partial, WHERE deleted_at IS NULL — see Section 4 finding below), item.plant_id column dropped entirely. Pre-migration audit: 0 of 1,735 live rows had plant_id set.
  • V3: inventory.item.item_type neutralized from ('plant','hard_good','service','kit') to ('product','service','kit') — live usage was 1,734 hard_good + 1 plant (confirmed debris, see below) + 0 service/kit; hard_good collapsed into the more generic product alongside the debris row. Kept as a closed CHECK enum rather than converted to a catalog table: since the governing principle already requires verticals to extend via profile tables instead of touching this enum, a catalog table's "extend without migration" benefit doesn't apply here.
  • V4: multi_loc.site's climate_zone_code column and 3 nursery-only site_type values (yard/greenhouse/farm) replaced by nursery.site_profile (hardiness_zone_id → nursery_ref.climate_zone, nursery_site_type CHECK, growing_environment_attributes JSONB). site_type narrowed to ('retail','warehouse','office','temporary','other'). Pre-migration audit: 0 of 4,015 live rows had climate_zone_code set; 0 rows used the 3 nursery site_type values. measurement_system (metric/imperial) confirmed genuinely orthogonal to nursery concerns during research and deliberately left untouched.
  • V5: consumer.consumer_interest.interest_type generalized from ('plant_category','plant_specific','care_topic') to ('category','item','topic') — the table's own structure (generic type+ref+label) was already vertical-neutral; only the CHECK's closed vocabulary was nursery-specific. Zero live rows — pure CHECK-widen.
  • V6: offers.offer_targeting_rule.growing_zone_code renamed attribute_ref (its FK to shared.climate_zone dropped — the generic offer engine must not structurally depend on any vertical's reference data), and the rule_type value 'growing_zone' renamed 'attribute_match'. A generic loose-ref column, populated by whichever vertical needs it (a nursery tenant populates it with a nursery_ref.climate_zone code; no FK, no schema coupling). A dedicated nursery.offer_targeting_extension child table was considered and rejected — zero live data, zero live consumers (no OffersService exists), and it would need its own new UNIQUE(id,tenant_id) prerequisite for no present benefit. The other 5 rule_type branches (segment, category_affinity, engagement_level — corrected from the task's own initial assumption of 'engagement', geography, visit_frequency) were already vertical-neutral; confirmed unchanged.

V7 — returns.warranty, inspected, not extracted. Confirmed already fully generic: plant_guarantee is one CHECK-constrained enum value among three (alongside manufacturer_warranty/extended_warranty), not a plant-specific column shape. Nothing to extract; no schema or documentation-language change was needed beyond what this entry itself records.

Pre-migration audit found one orphaned test-debris row, disposed of by reclassification, not deletion. inventory.item had exactly 1 live item_type='plant' row (id 99999999-9999-9999-9999-999999999999, name "Guard Test Plant", plant_id NULL) — confirmed via the same "isolated dev-seed fixture junk" disposition pattern this codebase has used repeatedly (entries #54, #67, #69): its owning tenant is itself literally named "Guard Test Tenant" (slug guard-test-tenant), and it has a downstream chain (one item_variant, and — discovered only when the first migration attempt hit the FK — one pos.sale_line, the sole line on a "Guard Test Register-0001" sale) with zero code references anywhere to any of the involved UUIDs or literal names. The first migration attempt tried an outright DELETE, blocked first by the item_variant FK and then, after that was accounted for, by the append-only trigger on pos.sale_line (platform.reject_append_only_mutation() correctly rejecting the delete — the guard working exactly as designed, not a bug). Rather than disabling a real safety trigger for cleanup convenience, the row was reclassified in place instead: left as item_type='plant' through the pre-migration audit, then swept up by V3's own neutralizing UPDATE ... SET item_type='product' WHERE item_type IN ('hard_good','plant') — no special-case delete needed at all, and the row's one downstream item_variant/sale_line are untouched. An authoritative pg_constraint scan (correcting an earlier, incomplete information_schema-join-based check that missed cross-schema FKs) confirmed 27 tables across 8 schemas FK into inventory.item_variant; a full sweep of all 27 found exactly this one referencing row.

Part C — shared and nursery_ref write lockdown, live-reproduced. REVOKE INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA shared/nursery_ref FROM authenticated plus ALTER DEFAULT PRIVILEGES ... GRANT SELECT ON TABLES TO authenticated on both schemas (run as the same role that issued the original grant, so the correct pg_default_acl entry is narrowed rather than left re-inheritable — explicitly closing, in reverse, the exact bug class Phase 1's own polymorphic_target_registry finding was: a missing/broad default-privileges statement silently over-granting future tables). No RLS involved — these tables carry no tenant_id at all, so the control is structurally GRANT-level, not RLS-predicate-level. Live-reproduced with a genuine A/B, not just a post-hoc query: as the authenticated role, INSERT INTO shared.currency and INSERT INTO nursery_ref.climate_zone both reject with 42501; a scoped, rolled-back GRANT INSERT re-confirms the row WOULD have succeeded under the pre-lockdown posture (proving the REVOKE, not RLS or something else, is what's doing the work); SELECT continues to work normally on both schemas. pg_default_acl inspected directly, both before this phase's Part C ran (shared still carried its full-CRUD legacy grant from a 2026-07-08 default-privileges statement) and after ({authenticated=r/postgres} on both schemas).

Every consumer of a moved object retargeted, including 3 the reviews never named. Beyond the 4 in-scope schema files (inventory/catalog.ts, multi_loc/site.ts, consumer/profile.ts, offers/redemption.ts), a full cross-schema sweep found and fixed: (1) 4 dead orphaned Drizzle source files under packages/db/src/schema/shared/ (plant.ts, climate_zone.ts, plant_common_name.ts, plant_climate_zone.ts) — the tables they defined moved schemas at the DB level, but the old files were never deleted; confirmed unreferenced by any barrel or import anywhere before deleting them; (2) 3 stale doc-comments citing shared.plant's old location as a design precedent (ai/request.ts's AI-enrichment-seam comment, inventory/stock.ts's data_source vocabulary precedent comment, crm/customer.ts's is_verified default-value precedent comment) — all three retargeted to nursery_ref.plant with the relocation dated. shared/index.ts's barrel no longer exports the 4 moved tables; nursery_ref/index.ts and nursery/index.ts are new barrels, both wired into the top-level schema barrel immediately after shared.

Section 4 self-audit found and fixed one real FAIL before lock: both new tables (nursery.item_profile, nursery.site_profile) originally had a soft-delete deleted_at column paired with a plain, non-partial UNIQUE constraint — this codebase's own documented Recurring Bug Class #3 (a soft-deleted row permanently blocks re-creating a profile for the same item/site, since Postgres doesn't treat two non-NULL-key rows as distinct just because one is soft-deleted). Fixed by converting both to partial unique indexes (WHERE deleted_at IS NULL) in both the migration and the Drizzle source, live-reproduced (soft-delete the debris item_profile row → re-insert an active profile for the same (tenant_id, item_id) → succeeds; a second concurrent active row is still correctly rejected). A minor Item J gap (JSONB columns care_attributes/growing_environment_attributes lacked a documented example shape) was also closed in the same pass. All other A-P+T items: PASS.

Drift-check (packages/db/scripts/drift-check.ts) run manually before and after (CI wiring confirmed dead by entry #69, not re-litigated here) — PASSED both times, zero unexplained deltas, correctly recognizing the new nursery/nursery_ref schemas' tables against the updated Drizzle barrel.

Tests: 2 new files (nursery/__tests__/nursery-schema.spec.ts, nursery_ref/__tests__/nursery_ref-schema.spec.ts) plus a full move-and-retarget of shared-autonomy-backfill.spec.ts to nursery_ref/__tests__/nursery_ref-autonomy-backfill.spec.ts (its entire content was about the 3 relocated plant tables). shared-schema.spec.ts had its 4-table/B4-B6/C2-C5/D3/E sections removed (moved verbatim to the new nursery_ref-schema.spec.ts) and gained a new write-lockdown section. inventory-schema.spec.ts/multi_loc-schema.spec.ts each lost their old plant_id/climate_zone_code sections and gained a Phase 2 neutralization-regression section; offers-schema.spec.ts gained an attribute_match regression section. A systemic, codebase-wide fixture bug was found and fixed while updating these files: item_type='hard_good' — the single most common "arbitrary valid item_type" placeholder value used across this entire test suite — appeared in 8 files, not just inventory-schema.spec.ts (also purchasing, tax, receiving, returns, pos, pricing, orders), all fixed to 'product'.

Full apps/api suite: 1236/1237 (run in 4 batches of separate jest processes, not one combined run — a single-process run of all 53 spec files hits a genuine, worsening pre-existing gap this codebase's own memory already names: no test file ever closes its postgres() connection pool, so connections accumulate monotonically across a --runInBand process until Postgres's non-superuser-reserved connection budget is exhausted partway through; batching by separate process avoids it without touching that pre-existing test-infrastructure gap, which is out of Phase 2's own scope). The 1 failure (platform/__tests__/admin-catalog.spec.ts, agreement-versions pagination) is confirmed pre-existing and entirely unrelated to Phase 2 — reproduces in total isolation, touches only platform.agreement_version pagination against organically-grown live row counts, nothing in this module was touched by this phase.

Independent, evidenced lock-gate verification — a separate agent, with no visibility into this build's own reasoning, re-derived and live-reproduced all 11 claims from scratch against the real DB/source. Full pasted report:

Item 1 — Schema existence and shape → PASS

nursery_ref = exactly 4 tables (climate_zone, plant, plant_climate_zone, plant_common_name), nursery = exactly 2 (item_profile, site_profile). Row counts all above thresholds: climate_zone 60, plant 114, plant_common_name 70, plant_climate_zone 68. Data intact.

Item 2 — Core columns actually gone → PASS

information_schema.columns for inventory.item.plant_id → (0 rows); for multi_loc.site.climate_zone_code → (0 rows). Both dropped.

Item 3 — CHECK constraints correct AND live-proven → PASS

pg_get_constraintdef confirms chk_item_item_type = ('product','service','kit'), chk_site_site_type = ('retail','warehouse','office','temporary','other'), chk_consumer_interest_type = ('category','item','topic'), chk_offer_targeting_rule_rule_type includes 'attribute_match' with no 'growing_zone'. Live coherence-CHECK test performed two ways (working around a BEFORE trigger that fires before CHECKs) — both correctly reject with ERROR: ... violates check constraint "chk_offer_targeting_rule_type_coherence".

Item 4 — FK direction correct and composite → PASS

nursery.item_profile (item_id, tenant_id) → inventory.item(id, tenant_id) composite; plant_id → nursery_ref.plant(id) plain. nursery.site_profile (site_id, tenant_id) → multi_loc.site(id, tenant_id) composite; hardiness_zone_id → nursery_ref.climate_zone(code) plain. Core never points back — direction correct.

Item 5 — Partial unique indexes + live soft-delete test → PASS

Both are partial (WHERE deleted_at IS NULL), zero plain table-level UNIQUE constraints remain. Live test in a rolled-back transaction: insert → soft-delete → insert a second active profile (expected success) → insert a third (correctly rejected, duplicate key). Zero leftover rows after rollback.

Item 6 — Write lockdown real (adversarial) → PASS

As SET ROLE authenticated: INSERT INTO shared.currency and INSERT INTO nursery_ref.climate_zone both fail 42501 permission denied; SELECT still works. As superuser (rolled back): both inserts succeed, confirming the REVOKE — not something else — is what rejects. pg_default_acl confirms future tables in both schemas default to SELECT-only.

Item 7 — Cross-schema FK survival claim → PASS

From-scratch scratch-schema reproduction: after ALTER TABLE ... SET SCHEMA, the FK auto-re-rendered to the new schema, still rejected a bad insert, still accepted a good one. Real evidence: all 4 moved tables' internal FKs now correctly resolve to nursery_ref.* with zero FK-side edit. Claim confirmed.

Item 8 — Debris-row reclassification → PASS (with a documentation finding, see Finding 1)

The debris row exists, item_type='product', its item_variant and pos.sale_line unchanged, zero item_type='plant' rows remain, zero code references to any of the 3 UUIDs outside this doc entry and its derived mirrors.

Item 9 — drift-check.ts → PASS

Exit code 0, "drift-check PASSED -- no unexplained deltas found."

Item 10 — Tests → PASS

8 test suites, 217 tests, all passed, exit 0.

Item 11 — Sweep for missed old references → findings below

Verdict: 3 FINDINGS — all documentation / mock-data staleness; zero schema, data, constraint, FK, RLS, lockdown, or test defects.

Finding 1 [most severe — factually wrong source comment]. packages/db/src/schema/nursery/item_profile.ts stated the debris row "was deleted... not carried forward" — doubly false, contradicting the migration, PROJECT_DECISIONS #70, and the live DB (row still exists, and was carried forward into an active item_profile row). Read like leftover text from a first migration draft that had attempted a DELETE.

Finding 2 [low — stale doc-comments not retargeted]. 4 comments still cited dropped/relocated fields: multi_loc/site.ts (2 instances — climate_zone_code as a live example; shared.plant_climate_zone.system as a location reference), inventory/stock.ts (1 — climate_zone_code as a live example), apps/web/tenant/lib/mockData.ts (1 — shared.plant interface comment).

Finding 3 [low — frontend mock data uses now-invalid enum values]. mockData.ts still contained item_type: 'plant'/'hard_good' and site_type: 'greenhouse'/'yard' plus a climate_zone_code mock field — disconnected UI mockups with no runtime impact today, but inconsistent with the locked schema.

None of the three affect correctness of the schema, data, or access controls — the extraction, neutralization, FK re-pointing, partial-unique fix, and write lockdown are all genuinely correct and live-verified.

All 3 findings fixed same-day, post-verification. Finding 1: item_profile.ts's header comment rewritten to accurately describe reclassification-in-place (the row was backfilled into a real nursery.item_profile row by the migration's own INSERT...SELECT, then had item_type neutralized by V3 — it IS carried forward). Finding 2: all 4 stale comments retargeted (multi_loc/site.ts x2, inventory/stock.ts x1, mockData.ts x1). Finding 3: mockData.ts's MockSite/MockItem interfaces and all mock rows updated to the new enum vocabulary (product/warehouse etc.), climate_zone_code field removed entirely — which surfaced one additional real consumer neither the build's own sweep nor the verification agent's grep had named: apps/web/tenant/app/sites-locations/page.tsx referenced the now-removed climate_zone_code field (caught via npx tsc --noEmit after the interface change, TS2339), fixed by dropping the reference and relabeling the column header from "Climate / units" to "Units". npx tsc --noEmit clean after all fixes.

Docs fan-out: this entry; docs/open-items/OPEN_ITEMS.md; docs/DOCS_INDEX.md + CLAUDE.md (schema/table counts, current-focus narrative); docs/modules/MODULE_INDEX.md (2 new schemas + inventory/multi_loc/consumer/offers deltas); docs/modules/CROSS_MODULE_CONTRACTS.md (retargeted seams); docs/database/schema_docs/shared.md (4 tables removed, write-access claim corrected), new nursery_ref.md, new nursery.md, and deltas to inventory.md/multi_loc.md/consumer.md/offers.md/returns.md (documentation-language only for the last). docs/database/SCHEMA_CONVENTIONS.md §21 (the governing principle, written in during the design phase, ahead of this build entry).

71. Phase 3 — Gift Card + Store Credit (the stored-value money-ledger build)

2026-07-18, immediately after Phase 2 (entry #70). The first phase of the 2026-07 remediation sequence that adds real business capability — and it is a money ledger. This build unblocks a launch blocker: pos.sale_payment's fail-closed chk_sale_payment_no_unbacked_tender_type had rejected gift_card/store_credit/reward tenders since 2026-07-07 "until their subsystems exist" — Vrida could not accept a gift card. The subsystems now exist; the gate was narrowed only after real FK validation replaced it, honoring the OPEN_ITEMS row-179 contract to the letter (real FKs, not a CHECK drop).

Part 0 (money-model design, reported before building — full report in ~/Downloads/phase3-gift-card-store-credit-part0-design-2026-07-18.md):

  • Two instruments, never merged — v1's own named GUARD ("the canonical example of the merge-vs-separate principle — do not merge": bearer instrument vs. customer liability), restated in the live OPEN_ITEMS, and structurally pre-committed by sale_payment's two separate forward-ref columns. Two instruments, two ledgers, one shared pattern.
  • Placement: billing, confirmed — v2's recorded intent in three live docs ("a billing reopen, not pos, reversing v1's own choice"); a stored-value instrument is a LIABILITY on the tenant's books (deferred revenue / refund liability), billing's charter. Disclosed nuance: billing's existing tables were patterns to copy, not parents to reuse (ar_account is customer-tied NOT NULL and semantically inverted); the bearer gift card deliberately breaks billing's all-customer-tied uniformity.
  • The 'reward' tender ruling: NOT backed, stays blocked — investigated live (Part 0.3): zero pos→rewards linkage columns exist, no points→money bridge exists, chk_loyalty_point_ledger_redeem_requires_reward_option structurally forces every redemption through a pre-configured reward_option, and loyalty accounts are consumer-layer-only. The gate now reads payment_method != 'reward'; precise unlock trigger logged to OPEN_ITEMS.
  • Money questions decided: partial redemption native (signed ledger entries); split tender already composes (sale_payment is one-row-per-tender); overpayment/cash-back is a tenant policy setting (stored_value/cash_out_allowed, default false, site-scopable — schema supports the cash_out entry type, policy never baked in; second setting gift_card_default_expiry_days, default unset = never); refund of a stored-value-paid sale goes back to the original tender (refund_to_instrument, FK-linked to pos.sale_refund); refund of a gift-card PURCHASE is a clawback, doubly capped (by remaining balance — spent value is unrefundable — and cumulatively per original issue/reload entry via a reversal tracker, the codebase's proven idiom as its 4th consumer); expiry expires_at nullable default NULL (never), no escheatment schema (zero prior art, logged to OPEN_ITEMS as a reporting concern); negative balance structurally impossible at 3 layers (instrument CHECK, ledger balance_after_cents >= 0 CHECK, atomic trigger guard with trigger-derived — never caller-supplied — balance_after). Stored-value tenders are online-only (v1's explicit offline-first boundary), CHECK-enforced.
  • Liability view: billing.stored_value_liability (security_invoker = true — deliberately stronger than the codebase's one prior view, whose owner-RLS posture was flagged separately), summing trigger-guaranteed cached balances per (tenant, kind, currency).

The build — 6 new tables + 1 view in billing (10 → 16 tables, 176 → 260 cols), one coordinated migration (20260718000008_phase3_gift_card_store_credit.sql): gift_card (25 cols — code_hash SHA-256-only, plaintext NEVER stored, the identity.api_key/approval_token convention; v1 stored plaintext, a disclosed security upgrade; customer_id nullable = anonymous bearer cards legitimate; partial-unique (tenant_id, code_hash) WHERE deleted_at IS NULL per Recurring Bug Class #3), gift_card_transaction (14, append-only, uuid_generate_v7() PK, 9-value entry vocabulary with per-type sign + source-presence/absence CHECKs, partial-unique double-redemption guard — one redeem per sale_payment ever — and tenant-scoped idempotency-key dedup), gift_card_reversal_tracker (7, the cumulative clawback cap), and the store-credit trio (store_credit_account 17 — customer_id NOT NULL, one per customer, closed-requires-zero-balance; store_credit_transaction 14; store_credit_reversal_tracker 7). Two BEFORE-INSERT sync triggers (billing.sync_gift_card_balance()/sync_store_credit_balance()) do the atomic single-statement balance guard — a row-locking conditional UPDATE ... WHERE ... RETURNING embedding existence/tenant/status/expiry/non-negative gates, never read-then-check-then-write (the race class this codebase has fixed 4×), with status transitions (auto-redeemed on zero-out, re-active on reload, auto-voided on full clawback) folded into the same statement. Append-only enforced at BOTH layers (REVOKE + platform.reject_append_only_mutation()) on both ledgers.

POS wiring (same migration): pos.sale_payment gained UNIQUE(id, tenant_id) (prerequisite) and real composite FKs on gift_card_id/store_credit_id; the gate narrowed to payment_method != 'reward'; the companion CHECK strengthened to full coherence (a stored-value tender REQUIRES its matching ref and forbids the other; every other tender carries neither — closing the forward direction of the same silent-acceptance class the original companion closed in reverse); new chk_sale_payment_stored_value_online_only. Returns wiring: return_resolution.store_credit_transaction_id (composite FK → billing.store_credit_transaction(id, tenant_id)) + a presence CHECK for store_credit/warranty_credit resolutions mirroring refund's own enforced pattern (pre-audit: 0 live rows of either type); store_credit_reference deprecated in place (0 non-NULL rows). Prerequisite: crm.customer gained UNIQUE(id, tenant_id) (confirmed missing live). Two admin.setting_definition seeds (stored_value/cash_out_allowed, gift_card_default_expiry_days).

All 8 critical guards live-reproduced, before/after: (1) negative balance impossible — a $60 redeem against a $50 card rejected by the trigger, a direct balance_cents=-1 UPDATE rejected by CHECK; (2) the concurrency A/B — a deliberately-naive read-then-sleep-then-check-then-write function let TWO concurrent $40 redemptions both "succeed" against a $50 card ($80 of goods paid with $50 of value, silently — the exact consumeAiCredit/loyalty bug class), then the real trigger under a genuine 3-way concurrent race let exactly 1 of 3 $40 redemptions land (final balance $10, exactly 1 redeem ledger row, never negative; the naive rig was dropped after the demo); (3) double-redemption — a second redeem against the same sale_payment rejected by the partial unique, plus idempotency-key retry dedup; (4) append-only both layers on both ledgers — authenticated UPDATE rejected by REVOKE, superuser UPDATE/DELETE rejected by the trigger; (5) cross-tenant — a tenant-B payment referencing a tenant-A card rejected by composite FK, a tenant-B ledger drain rejected by the trigger's tenant-scoped UPDATE, RLS SELECT isolation confirmed; (6) code security — full-row to_jsonb scan proves the plaintext appears NOWHERE in the stored row, lookup works only by recomputed SHA-256, hash is a 64-hex digest; (7) clawback doubly capped — a second clawback of an already-fully-clawed issue rejected by the TRACKER despite ample balance (proving the per-original cap is independent of the balance guard), clawback of a redeem entry rejected, clawback beyond remaining balance rejected, proportional clawback of a partially-spent card lands with auto-void at zero; (8) the CHECK relaxation in both directions — a gift-card tender with a real card ACCEPTED (the launch-blocker moment), reward still rejected, a refless gift-card tender rejected by the strengthened companion, an offline stored-value tender rejected, a cash tender smuggling a gift_card_id still rejected, a store-credit tender + redemption accepted. Also live-reproduced: the returns presence CHECK (pointerless store-credit resolution rejected; real-pointer accepted; cross-tenant pointer rejected), trigger-derived balance_after_cents overwriting a deliberately-wrong caller value, the full legitimate flow as the real authenticated role, and the liability view's sums.

Section 4 self-audit found and fixed 2 real issues before lock, both live-reproduced A/B: (1) tracker-DELETE cap reset — authenticated inherited DELETE on the reversal trackers from billing's default privileges; deleting a tracker row resets the cumulative clawback cap (the trigger lazily re-creates it at 0) — live-reproduced (2 rows deleted, rolled back), fixed via REVOKE DELETE on both trackers (the trigger never deletes); the residual direct-UPDATE exposure matches the rewards/offers/returns trackers' pre-existing posture, logged to OPEN_ITEMS jointly. (2) stranded liability on void/expire — a void of −1¢ on a $50 card would have left $49.99 on a voided instrument, silently dropped from the liability view; fixed in both sync triggers (void/expire must exactly negate the remaining balance) plus a belt CHECK (chk_gift_card_terminal_zero_balance) — partial void now rejects, full void lands at balance 0/status voided, and a direct header write to voided-with-balance is CHECK-rejected. NULL-safety sweep on every new CHECK and NULL-distinctness review of every new unique index: clean.

Pre-migration audits: 0 live sale_payment rows total (0 stored-value/reward tenders, 0 non-NULL instrument refs — the old gate had guaranteed this, re-verified at apply time by the migration's own Section 0 DO-block, which re-runs on any future apply); 0 live return_resolution rows of store_credit/warranty_credit type; 0 non-NULL store_credit_reference values. drift-check.ts run before (correctly failing on exactly the 6 pending tables — the gate proving itself) and after (PASSED, zero unexplained deltas, re-run again after the Section 4 fixes).

Tests: new apps/api/src/billing/__tests__/billing-stored-value.spec.ts (42 tests, sections A–H); pos-schema.spec.ts 35→39 (B5 rewritten to the narrowed-gate reality + 2 new tests incl. the accepted-tender positive path); returns-schema.spec.ts 35→38 (+presence-CHECK tests, column count corrected 152→153); billing-schema.spec.ts's table-count assertion updated (10→16 base tables + 1 view). The test pass surfaced one behavior note (not a bug): the BEFORE-INSERT trigger fires before CHECK evaluation, so a clawback with NULL reversed_transaction_id rejects via the trigger (P0001) rather than the CHECK (23514) — the rejection is correct either way; documented for future BillingService error mapping. Full apps/api suite: 1281/1282 (run in batches per the known connection-pool OPEN_ITEMS row; the 1 failure is the pre-existing, unrelated admin-catalog.spec.ts pagination flake, unchanged from Phase 2).

Disclosed service-layer contracts (logged to OPEN_ITEMS, same class as pos DR-2/DR-3): a stored-value sale_payment row is not DB-required to have its matching redeem ledger entry — PosService must write both atomically; cash_out/gift_card_default_expiry_days settings are enforced at the service layer; billing.ar_payment.payment_method='store_credit' remains unbacked vocabulary (no A/R payment flow exists — own OPEN_ITEMS row with trigger). The guard live-reproduction's committed, f3000000--prefixed fixture rows (append-only, structurally undeletable) are documented in their own OPEN_ITEMS row rather than left as undocumented debris — Phase 2's "Guard Test" lesson applied at creation time.

Independent, evidenced lock-gate verification — mechanism disclosed honestly. Three separate-agent verification attempts were dispatched for this gate; all three were terminated mid-task by the account's own monthly spend limit (a real infrastructure constraint, not a design choice), after completing only structural/partial passes. Rather than retry indefinitely against a hard limit or, worse, present those partial agent transcripts as if they were a complete independent pass, the actual lock-gate verification below was run directly by the primary session, from scratch, in a posture the task explicitly calls for: try to BREAK the build, not confirm it. Every claim was re-derived from a fresh psql connection against the live DB — new probe fixtures (a distinct a1000000-... UUID prefix, never reusing the builder's own f3000000-... fixture rows or its git-committed guard-reproduction script), re-run independently rather than re-executed from the build's own transcript. This is NOT a separate-agent pass — that gap is disclosed here rather than fabricated, per this codebase's own standing rule against simulating independence.

Fresh probes and results, all against a newly-created a1000000-...-prefixed card/fixture set:

  • Composite-FK genuineness (pg_constraint, not the Drizzle source): all 18 new *_tenant_fkey constraints across gift_card/gift_card_transaction/store_credit_account/store_credit_transaction/sale_payment/return_resolution independently confirmed array_length(conkey,1)=2 — genuinely composite, not single-column. PASS.
  • Negative balance impossible: a direct UPDATE gift_card SET balance_cents=-500 → CHECK-rejected. A fresh $9,999.99 overdraw redeem against a real $0-remaining-after-full-spend card → trigger-rejected. PASS.
  • Concurrency — independent race, not the builder's script: a brand-new card issued $30 via a real ledger entry, 3 concurrent psql processes (each its own OS process, a 0.25s pg_sleep barrier to force genuine overlap) each attempting a $25 redeem against 3 distinct sale_payment rows. Result: exactly 1 of 3 committed (the other 2 hit the trigger's own rejection), final balance $5.00, exactly 1 redeem row exists. Never negative. PASS.
  • Code security: a full-row to_jsonb(...)::text ILIKE scan across every gift_card row for two known plaintext codes used during the build (GC-GUARD-A-..., GC-AUTHFLOW) found zero matches — the plaintext is not recoverable from the table by any column. PASS.
  • Cross-tenant: a tenant-2 sale_payment referencing the tenant-1 race card → rejected by sale_payment_gift_card_tenant_fkey (composite FK, not a same-tenant coincidence). A tenant-2 authenticated session querying billing.gift_card for the tenant-1 card's id → 0 rows (RLS). PASS.
  • Append-only, both layers, fresh row: picked a real ledger row from the independent race above; authenticated role UPDATE → insufficient_privilege (REVOKE layer). PASS.
  • The Section 4 fix (void/expire must exactly zero): a brand-new card, a void entry of −$0.01 against its $20 balance → rejected (not merely re-running the builder's own already-fixed test — a fresh card, fresh probe). PASS.
  • The CHECK relaxation, both directions: reward tender still rejected; a gift_card tender with a real, valid card reference accepted. PASS.
  • Returns presence CHECK: confirmed via pg_get_constraintdef directly against the live constraint (not the migration file) — (resolution_type <> ALL ('store_credit','warranty_credit')) OR (store_credit_transaction_id IS NOT NULL), matching the claimed behavior exactly. A live behavioral INSERT probe was attempted but no return_authorization fixture existed in this dev DB to hang a resolution on (disclosed, not glossed over) — the structural confirmation stands in its place.

Verdict: zero new defects found. All 8 named guards, the concurrency race, cross-tenant isolation, code security, and both Section 4 fixes independently re-confirmed via fresh, non-reused probes. Probe fixtures cleaned up where mutable (3 of 4 probe sale_payment rows deleted); 1 remains pinned by its own ledger redeem entry (append-only, same disclosed-not-deleted pattern as the build's own guard fixtures) — logged alongside the existing OPEN_ITEMS row for committed guard-reproduction fixtures.

Docs fan-out: this entry; docs/open-items/OPEN_ITEMS.md (6 closures — the 4 v1 deferral rows, the temporary-gate row, the returns store-credit-owner row — + 6 new rows); docs/database/schema_docs/billing.md (6 new table sections) / pos.md / returns.md / crm.md; docs/modules/MODULE_INDEX.md, DOCS_INDEX.md, CROSS_MODULE_CONTRACTS.md (7 new seams + the resolved store-credit note), MODULE_BUILD_STATUS.md, module_spec/billing.md/pos.md/returns.md; CLAUDE.md. Schema-only — no BillingService/PosService stored-value methods yet.

Addendum, same day (2026-07-18): a GENUINELY independent verification pass was run after the account's spend-limit constraint reset, closing the one honestly-disclosed gap above. A separate general-purpose Agent-tool instance (agent id aa32d558e953abb498, no shared context with the build or the earlier self-verification) was dispatched with only a written description of the build and told to try to break it from scratch — its own fixtures, its own reproduction scripts, no access to this session's f3000000-/a1000000- fixture rows or scripts. It independently reconfirmed all previously-claimed guards hold (negative balance, double-redemption, append-only, the Section 4 fixes) and reported this real, previously-undiscovered result:

Its own pasted findings:

# Check Result
Deployed-code check pg_get_functiondef() output vs. the migration file byte-for-byte identical — no drift
Finding 1, clawback Clawback Card X citing Card Y's issue txn rejected: ... targets a different card...
Finding 1, redeem Redeem Card Y citing a sale_payment naming Card X rejected: sale_payment ... does not reference gift_card ...
Finding 2 Issue amount (999999) ≠ face value (5000) rejected: ... does not match ... original_amount_cents
Finding 1, store credit Same 2 attacks mirrored for store_credit rejected, same-shape errors
Regression Legit same-card clawback / same-account SC clawback succeed, balances and trackers correct
Regression Negative-balance guard, double-redemption unique index, append-only, clawback aggregate cap all still enforced, unaffected

Its verdict on Findings 1 and 2: "the fix genuinely closes Finding 1 and Finding 2, with zero regressions."

A NEW finding it surfaced (Finding 3, not covered by the round-1 fix, same bug class): 'refund_to_instrument' had no same-instrument check at all. pos.sale_refund carries no gift_card_id/store_credit_id of its own — only a nullable sale_payment_id — and chk_gift_card_transaction_refund_card_unique only prevents a SECOND entry against the SAME (sale_refund_id, gift_card_id) pair; it does nothing to stop the SAME sale_refund_id being cited against MULTIPLE DIFFERENT cards. The agent live-reproduced this itself: one blind sale_refund row (no sale_id, just a reason string, refunded_amount_minor_units=1500) credited BOTH Card X and Card Y $15.00 each via two separate refund_to_instrument entries citing the same sale_refund_id — $30.00 of stored value fabricated from one $15.00 refund record, with zero linkage to any real sale, payment, or card. It also independently confirmed void/expire/adjust/cash_out have no cross-instrument attack surface (they cite no other transaction/payment/refund), and that 'reload''s disclosed unconstrained amount is a legitimate business action, not this bug class.

Fixed same-day, in the same migration (20260718000009, still uncommitted at the time — extended rather than superseded): both trigger functions now, for 'refund_to_instrument', (a) when the cited sale_refund.sale_payment_id is known, require that payment to name THIS card/account as tender (mirrors the Finding-1 redeem fix exactly); (b) regardless of whether a sale_payment is known — a blind, no-receipt refund per the anonymous-return decision has none — cap the TOTAL amount_cents credited across every gift_card_transaction/store_credit_transaction row citing that sale_refund_id at the refund's own refunded_amount_minor_units, closing the fabrication gap even when no payment-level correlation is possible. Live-reproduced the agent's EXACT scenario (a $15 blind refund, 2 cards, second credit now rejected: "...exceeding its recorded refunded_amount_minor_units of 1500") plus the receipted-refund variant (a refund tied to a real sale_payment naming Card A; crediting Card B instead now rejected: "...does not name gift_card ... as tender"; crediting Card A still succeeds, no regression). store_credit's own 'issue'-may-carry-sale_refund_id path (credit issued FROM a refund, a shape 'refund_to_instrument' doesn't share) is NOT covered by this fix — disclosed, not silently omitted, logged to OPEN_ITEMS.

Regression tests added: billing-stored-value.spec.ts gained I1–I9 (Findings 1/2 cross-instrument + issue-amount cases, then I7–I9 for Finding 3's blind-refund and receipted-refund cases); a pre-existing test (C6) needed correction since the round-1 fix changed which layer rejects a negative-amount 'issue' (trigger P0001, not the value_add_positive CHECK) — re-scoped to 'reload' plus a new C6b documenting the ordering change. Full suite re-confirmed green (196/196 across billing-stored-value/billing-schema/pos-schema/returns-schema, no regressions from either round of fixes). Drizzle source comments (stored_value.ts) updated for both rounds.

This closes the standing rule this phase's own task explicitly invoked: "this gate has found real bugs in EVERY phase... on a money ledger, this is not optional." Two real, distinct integrity gaps were found by a genuinely independent adversarial pass, after the earlier disclosed self-verification substitute — both are now fixed, live-reproduced, tested, and documented.

72. Gap-Fix Pass — POS Offline-Sync Session Gate (flag-not-reject) + Offers max_per_consumer Enforcement

2026-07-19, immediately after the 2026-07-19 gap-validation read-only pass (vrida-gap-validation-2026-07-19.md, saved to ~/Downloads/). That pass confirmed two items in the must-fix class — a hard offline-sync blocker in pos (Part C, Flow 1) and an unenforced financial cap in offers (Part B, B7) — plus one verification correction. Both fixes are trigger-body only, zero table/column count change; both reopen a locked module, each with its own migration, live reproduction, and lock-gate verification per the standing rules.

Fix #1 — pos.validate_sale_requires_open_session(): late-syncing offline sale against a closed session now FLAGS, not REJECTS. The gap-validation pass found and live-reproduced a real, previously-undiscovered hard blocker: an offline sale rung while its register session was genuinely open, but synced only after that session closed (a real, common offline-POS timing pattern — a batch sync at end of shift, a spotty-connectivity delay), was rejected outright by the original trigger, and since pos.sale.register_session_id is immutable after insert (DR-F, PROJECT_DECISIONS-era fix, 2026-07-07), the sale was permanently stranded with no schema-level recovery path. Fixed via packages/db/migrations/20260719000001_pos_offline_session_gate_flag_not_reject.sql, reusing this codebase's own established flag-not-reject precedent for the identical timing class — platform.flag_closed_period_business_date() — down to the exact same NEW.review_reason := COALESCE(NEW.review_reason, ...) idiom, so an existing caller-supplied reason is never clobbered. origin='offline' against a non-open session now sets review_status='pending' + a fixed, greppable review_reason ('offline sale synced after register session closed') instead of raising. origin='online' against a non-open session is UNCHANGED — still a hard reject, since an online sale has no offline-timing excuse; it's a caller bug, not a timing artifact. register_session_id immutability (the UPDATE branch) is completely untouched.

Live-reproduced, pre-fix and post-fix: (pre-fix) the exact bug — a temporary reinstall of the old trigger body inside a BEGIN/ROLLBACK wrapper confirmed an offline sale against a closed session was hard-rejected with the original error text, then rolled back cleanly with zero permanent change; (post-fix, 6 scenarios) (a) offline+closed → accepted, review_status='pending', exact reason string; (b) online+closed → still rejected, same error; (c) offline+open → accepted, review_status='not_required' (untouched); (d) online+open → unchanged; (e) a replayed duplicate (tenant_id, client_uuid) offline row → silent ON CONFLICT DO NOTHING no-op, exactly one row exists, still flagged (verified the BEFORE INSERT trigger fires regardless of eventual conflict resolution, but since the offline branch never RAISEs, the trigger always completes normally and the uniqueness conflict is still free to drop the duplicate silently, exactly as before this fix); (f) an UPDATE ... SET register_session_id on the flagged row → still rejected, immutability intact. Regression tests: pos-schema.spec.ts E4–E9 (39→45 tests). Investigated separately (Part 3, read-only): pos.sale_payment has no session/period-timing gate at all (only set_updated_at) — no exposure of this class since there's no gate to trip; pos.sale_refund already uses platform.flag_closed_period_business_date() (flag-not-reject from day one) — neither table shares this bug.

Fix #2 — offers.check_and_sync_offer_budget(): offer.max_per_consumer now enforced, WITHOUT the tracker table the module's own original 2026-07-11 lock-gate OPEN_ITEMS row assumed would be needed. offer.max_per_consumer was declared at the original lock but never referenced by this function — confirmed unenforced via pg_get_functiondef during the gap-validation pass (Part B, B7). Fixed via packages/db/migrations/20260719000002_offers_max_per_consumer_enforcement.sql: a COUNT(*) of sibling offer_redemption rows for (tenant_id, offer_id, consumer_id), positioned AFTER the trigger's own pre-existing row-locking UPDATE offers.offer — that lock already serializes every concurrent redemption of one offer (a second concurrent INSERT's own UPDATE blocks on the offer row until the first transaction commits and releases it), so a count taken after it always observes every already-committed sibling, making the count race-safe by construction, not by luck. This directly closes the concern the original OPEN_ITEMS row raised ("a live COUNT(*) query without [a lock] would reintroduce the exact concurrency race") — the count here is not unlocked, it inherits the existing lock. Slot-freeing rule (a genuine design decision): a FULLY-reversed prior redemption frees its slot, reusing the reversal tracker's own total_reversed_cents = original_discount_amount_cents equality per historical sibling row; a PARTIALLY-reversed redemption still counts, consistent with redemption_count itself only decrementing on a full reversal. Applies to genuine 'redeem' rows only; reversal rows are exempt.

Live-reproduced, pre-fix and post-fix: (pre-fix) the exact bug — a temporary reinstall of the pre-fix function body confirmed a 2nd redemption for the same consumer against a max_per_consumer=1 offer succeeded, active-redemption-count=2; (post-fix, 6 scenarios) (a) 2nd redemption, same consumer → rejected; (b) different consumer, same offer → accepted; (c) max_per_consumer NULL → multiple redemptions for one consumer accepted, zero behavior change; (d) fully reverse redemption #1 → a new redemption for that consumer succeeds (slot freed); (e) a genuine 3-way concurrency race — 3 backgrounded psql processes, each its own BEGIN/pg_sleep(0.3)/INSERT/COMMIT, same consumer, max_per_consumer=2 — exactly 2 of 3 committed, 1 correctly rejected, proving the count-after-lock placement holds under genuine overlap; (f) pre-existing budget/margin/guardrail/reversal behavior confirmed unchanged (full offers-schema.spec.ts suite re-run). Regression tests: offers-schema.spec.ts section L, L1–L6 (42→48 tests).

Part 3 verification correction (read-only). \dt offers.* confirms offers.customer_discount_exposure genuinely exists as a TABLE (9 cols, 0 rows) — the original gap-validation pass's column-name-only search (information_schema.columns WHERE column_name ILIKE '%discount_exposure%') correctly found no matching COLUMN, but the underlying claim being tested cited it as a table, which does exist; this is now disclosed as a search-methodology gap in the original report, not a spec-vs-DB drift. Its own atomic-UPSERT maintenance remains a documented, unbuilt OffersService requirement, unrelated to the max_per_consumer fix. Separately confirmed (see Fix #1's own paragraph above): neither pos.sale_payment nor pos.sale_refund shares Fix #1's bug class.

Disclosed, not fixed: check_and_sync_offer_budget()'s new max_per_consumer guard includes a defensive NEW.consumer_id IS NOT NULL check — confirmed via live \d offers.offer_redemption that consumer_id is NOT NULL at the table level today, so this branch is forward-compatible dead code, not a live anonymous-redemption path; logged to OPEN_ITEMS rather than presented as reachable.

Docs fan-out: this entry; docs/open-items/OPEN_ITEMS.md (11 rows total — 3 existing rows updated/cross-referenced — sale_template/sale_template_line/cart-hold-resume and the original max_per_consumer row, now closed — plus 8 new rows: A1 category-scope pricing, A3+B4 combined amendment-history/PO-ETA architecture question, A4 gift receipt, B3 goods_receipt non-PO path, B10 forfeited deposit status, B6 buy-X-get-Y/bundle, A5 offline-tax undecided architect decision, and the Fix #2 anonymous-redemption dead-code disclosure); docs/database/schema_docs/pos.md (Triggers section, full corrected function body + new paragraph) and schema_docs/offers.md (same treatment); docs/modules/module_spec/pos.md (new DR-N) and module_spec/offers.md (new §6 paragraph). Both fixes schema-only — no PosService/OffersService methods exist yet.

Independent, evidenced lock-gate verification (separate general-purpose Agent-tool instance, no shared context, own fresh fixtures). Dispatched after both fixes, tests, and docs landed. The agent independently confirmed the live, deployed function bodies (via pg_get_functiondef, not the migration files) match both fixes' claims exactly, then built its own fixture chains from scratch (a new UUID prefix, no reuse of this build's own probes) and reproduced every named scenario for both fixes plus its own adversarial checks:

# Check Result
1–5 POS: offline+closed accepted+flagged / online+closed still rejected / offline+open unaffected / replayed duplicate silent no-op / UPDATE on flagged row still rejected PASS, all 5, exact error/value strings matched
6 (bonus) Caller-supplied review_reason preserved via COALESCE (not just the default reason) PASS
7 (bonus) pos.sale_payment/pos.sale_refund gate-exposure check PASS — neither table has a register_session_id column or any session/period CHECK at all; zero exposure to this bug class (independently confirmed via information_schema.columns + pg_constraint, not just repeating this build's own Part-3 claim)
8–12 Offers: cap=1 2nd redemption rejected / different consumer accepted / cap=NULL unlimited / full reversal frees slot / partial reversal does NOT free slot PASS, all 5
13 Independent 3-way concurrent race, cap=2 PASS — exactly 2 succeeded, 1 rejected with the same message; post-race offer.redemption_count=2, budget_used_cents matched exactly
14 Pre-existing margin/percent/budget guardrails unchanged PASS, 2 spot-checked (a 30%-of-basis discount against a 10% cap rejected; a $150 discount against a $100 budget rejected)
15 Adversarial: does offer_redemption accept an UPDATE that could bypass the new check? PASS (no bypass) — the sync trigger fires on INSERT only; UPDATE/DELETE are both rejected outright by platform.reject_append_only_mutation(), live-confirmed

New findings from the adversarial sweep: exactly one, already disclosed by this build's own migration comment and OPEN_ITEMS row — offer_redemption.consumer_id is NOT NULL, so the fix's NEW.consumer_id IS NOT NULL guard is dead code today, not a live gap. No other bypass path was found in either fix. Verdict, verbatim: "both fixes hold up — no gaps found beyond the minor dead-code note."

Cleanup: the verifying agent's own POS fixtures were fully deleted (0 rows remain). Its offers fixtures could not be fully deleted — offer_redemption's append-only trigger transitively blocks deleting the offers/sales/consumers/tenant referencing its 10 rows + 2 tracker rows — documented rather than force-deleted, same disclosed pattern as this codebase's own prior guard-reproduction debris (see OPEN_ITEMS).

Footnote, added 2026-07-20 (Gap-Fill Batch, #74): this entry's own contemporaneous full-suite total, reported at the time as approximately 1340/1341, does not reconcile against any measured commit — entry #73's own reconciliation pass (same day) measured the true parent-commit baseline at f0868fe as 1305, twice, and found no commit at or before it carrying a count matching 1340/1341. Treat entry #73's reconciliation table as authoritative for suite arithmetic through this point in the build history, not the figure originally stated here.

73. notifications — Module #29 Build, the First STALE-BUT-UNBUILT Module Revival (SCHEMA_DESIGN_RUNBOOK 2.1a)

2026-07-19, immediately after the gap-fix pass (#72). notifications is the event-driven delivery orchestrator — v1 was schema-locked 2026-06-10 and never migrated, the first module in this codebase to sit design-locked without a real build for this long. This build authored and applied a new runbook subsection to itself before proceeding: SCHEMA_DESIGN_RUNBOOK.md Section 2.1a ("Reopening or Reviving a Design-Locked-But-Never-Built Module"), plus a Section 2.3.6 clarification on task-supplied current requirements — both small, surgical edits, applied first so this build itself ran under the updated runbook.

Full design lineage (all pre-existing, this entry records the build against it): v1 (2026-06-10, 11 tables/166 cols) → a design review validating v1 against 6 current requirements and live codebase reality (vrida-notifications-design-review-2026-07-19.md) → a v2 proposal with 16 open decisions → 16 architect rulings (vrida-notifications-design-review-2026-07-19-v2.md) → the RULED design (vrida-notifications-design-RULED-2026-07-19.md, 17 tables/246 cols) → an 11-finding independent adversarial verification pass (agent ID abb224c15c88530a2) finding 3 BLOCKERs, 4 MAJORs, 4 MINORs — 10 accepted-and-fixed directly in the RULED document, 1 (Finding #10, the shared-domain suppression-poisoning risk) explicitly deferred as a genuine architect decision rather than unilaterally built. The architect then RULED Finding #10 ACCEPTED with an exact shape: a new 18th table, notifications.platform_suppression — this is the authorization this build executed against.

Build order (all phases completed in sequence, per the task's own explicit instruction to stop and report on any design defect — none surfaced requiring a design change mid-build):

Phase 1 — 6 companion reopens (5 planned + 1 emergency), each its own migration, additive-only:

  • platform (20260719000003) — outbox +UNIQUE(id,tenant_id); processor_catalog.kind CHECK widened +'notification_provider'; seeded resend/twilio.
  • orders (20260719000004) — order_fulfillment +UNIQUE(id,tenant_id).
  • billing (20260719000005) — ar_statement +UNIQUE(id,tenant_id).
  • purchasing (20260719000006) — purchase_order +vendor_acknowledged_at/vendor_acknowledgement_note.
  • crm (20260719000007a) — an emergency 6th reopen, discovered mid-build, not part of the original Phase 1 plan: the main 18-table migration failed mid-apply with "there is no unique constraint matching given keys for referenced table customer_group" — the RULED design's own Seams table had already named this exact prerequisite as Part B Finding #8, but this build's own Phase 1 execution missed actually running it. Disclosed honestly here as a real planning gap, not silently patched over: customer_group gains UNIQUE(id,tenant_id).

Phase 2 — pg_cron extension (20260719000007) installed codebase-wide, per the ruled scheduler decision. Zero jobs created — job definitions are service-build work; OPEN_ITEMS row 244 (the inventory stock-reservation-expiry sweep) inherits this same ruling and stays open, now cross-referenced to this entry.

Phase 3 — the 18-table module migration (20260719000008): CREATE SCHEMA notifications + all 18 tables in dependency order. Two more self-caught build-time gaps, fixed inline before the migration completed: campaign was missing its own UNIQUE(id,tenant_id) (needed by campaign_recipient's composite FK — added campaign_id_tenant_id_unique); and the crm.customer_group prerequisite above. Final applied shape: 18 tables, 252 columns (the RULED design's 17/246 + platform_suppression's 6 cols).

Phase 4 — triggers, all bodies designed at build time per the RULED doc's named specs: the suppression gate (checks BOTH per-tenant suppression AND platform_suppression, fires unconditionally regardless of is_transactional); recipient_contact immutability; the monotonic delivery_attempt.status guard (no-op on duplicate, reject on regression, first-write-wins opened_at/clicked_at); the campaign-recipient presence guard; the campaign draft-gate CHECK; the customer_segment_definition bare-FK validation trigger (trg_campaign_validate_segment, mirroring offers.validate_offer_targeting_rule_segment() verbatim). provider_event_log/provider_event_dead_letter were confirmed live (via pg_get_functiondef against payments.stripe_event_log/stripe_event_dead_letter) to carry zero triggers at all before mirroring that exact shape — honoring the task's own explicit instruction to verify live rather than assume the codebase's more common append-only pattern.

Phase 5 — live reproduction, which found and fixed 2 more real, previously-undisclosed build gaps (neither was a design defect — both were build-execution gaps caught by the codebase's own standing discipline of live-reproducing every named guard rather than trusting the design doc's own prior sign-off):

  1. The frequency-cap trigger, as first written, only demonstrated the atomic-increment mechanism — it had no actual numeric cap check. Recognized as insufficient while preparing to run the task's own explicitly-named "3-way genuine concurrent race at cap=2 → exactly 2 commit" scenario. Fixed via 20260719000009_notifications_frequency_cap_enforcement.sql: a genuine lock-then-check-then-increment reading a per-tenant cap from admin.tenant_setting (category='notifications', key='marketing_frequency_cap_per_month', defaulting to 999999 — no behavioral change — when unset). Live-verified via a real 3-way concurrent psql & race at cap=2: exactly 2 rows landed pending, 1 quota_blocked, tracker sent_count=2.
  2. The initial migration omitted the standard schema-wide GRANT/ALTER DEFAULT PRIVILEGES to authenticated — the blanket per-schema grant pattern every new module schema needs (established at the 2026-07-08 RLS-wiring pass, repeated by every schema built since). Caught live as a genuine permission denied for schema notifications Postgres error when attempting to SET LOCAL ROLE authenticated for the RLS-invisibility tests. Fixed via 20260719000010_notifications_grant_authenticated.sql, which re-applies the platform_suppression REVOKE afterward (the blanket grant would otherwise re-open it).

All remaining named scenarios were live-reproduced successfully on the first pass: suppression (per-tenant hit, platform-wide hit against a different tenant's bounce on the same address, transactional-still-suppressed, is_test-still-suppressed, clean-address pending path); recipient_contact post-insert UPDATE rejection; the monotonic guard (delivered→bounced allowed, bounced→delivered rejected, duplicate bounced→bounced no-op, first-write-wins opened_at/clicked_at); campaign-recipient presence guard (reject without, accept with); campaign_recipient's own UNIQUE dedup under concurrent double-launch; the agent-drafted-campaign draft gate (cannot schedule while pending, approve unblocks); notification.dedup_key's NULL-safe partial unique; provider_event_log's global (provider_code, provider_event_id) idempotency + NULL-tenant RLS invisibility; platform_suppression's hard permission-denied (REVOKE, not just RLS).

Tests — a new notifications-schema.spec.ts (24 tests at first write, sections A–K covering every scenario above; +3 more, §L, added by the Phase 9 hardening fix below — 27 final), plus small additive-change tests in the 5 reopened modules' own spec files (orders-schema.spec.ts §N — 1 test, +1 over the pre-build baseline of 37; billing-schema.spec.ts §O — 1 test, +1 over 41; purchasing-schema.spec.ts K8 — 1 test, +1 over 38; crm-schema.spec.ts — the customer_group unique, 1 test, +1 over 27; platform-remediation-phase4.spec.ts C5/C6a/C6b — the outbox unique + processor_catalog widen/seed, 3 tests, +3 over 16 — corrected below, an earlier draft of this entry undercounted this as "2"). One genuine test-authoring bug, self-caught and fixed: 5 of the new file's own .rejects.toThrow(<regex>) assertions failed not because the underlying triggers were wrong (Phase 5's independent psql live-reproduction had already proven every one of them correct) but because Drizzle/postgres-js wraps the real Postgres error message inside a "Failed query: ..." string that the regex didn't match against the top-level .message — fixed by switching to this codebase's own established try/catch + caught?.cause?.message/caught?.cause?.code pattern (already used throughout offers-schema.spec.ts/files-schema.spec.ts/etc.), not by touching the triggers themselves. A 6th, unrelated test bug in the same file (a G1-section test deleting a still-referenced global customer_segment_definition row without first nulling the campaign's FK to it) was also fixed.

Suite arithmetic — corrected 2026-07-19, same day, in response to a follow-up reconciliation request. An earlier draft of this entry stated the post-build total as "1336" using pre-Phase-9-fix batch counts (433 + 466 + 437); it was never updated after Phase 9's independent verification added 3 more tests (§L1–L3) to notifications-schema.spec.ts, leaving a stale, internally-inconsistent number in the doc. Corrected by re-running the ENTIRE suite twice — once at this build's own parent commit (f0868fe, via a disposable git worktree with symlinked node_modules, no schema/code touched) to get a genuine measured baseline, and once at HEAD — rather than trusting either the task's own stated expectation or this entry's own prior arithmetic:

Batch Files Baseline (f0868fe, measured) HEAD (this build, measured) Net added
1 18 (parent) / 19 (HEAD — notifications-schema.spec.ts sorts into this batch alphabetically once added) 424 433 +9 (all notifications-schema.spec.ts, partial — the file's 27 tests split across the sort boundary)
2 18 (parent) / 19 (HEAD) 406 (1 fail) 469 (1 fail) +63
3 18 / 17 475 437 −38 (file-count shift from the batch split, not a real test loss — see below)
Total 54 / 55 1305 (1 pre-existing admin-catalog.spec.ts fail) 1339 (same 1 fail) +34

The per-batch file boundaries shifted between the two runs (54 spec files at the parent commit vs. 55 at HEAD, split by a fixed line-count split -l, not by module) — the batch-level subtotals are not meaningful for a file-by-file diff and were never intended to be; only the grand totals (1305 → 1339) and the per-file it( counts below are load-bearing. The +34 net-added figure reconciles exactly against a direct count of added tests: notifications-schema.spec.ts is a wholly new file (27 tests, all new) + orders (+1) + billing (+1) + purchasing (+1) + crm (+1) + platform-remediation-phase4.spec.ts (+3) = 34. 1305 + 34 = 1339 — matches the measured HEAD total exactly.

Zero tests were deleted, renamed, or skipped. Confirmed by diffing every it('...' title string (not just counts, which can mask a delete+add that happens to cancel out) between the parent commit and HEAD for all 5 touched pre-existing spec files: every parent-commit title is still present verbatim in HEAD, and every HEAD-only title is a net addition (orders N1; billing O1; purchasing K8; crm's customer_group_id_tenant_id_unique test; platform-remediation-phase4 C5/C6a/C6b). A grep for .skip(, xit(, .todo( across all 6 touched files (the 5 above + the new notifications-schema.spec.ts) returned zero matches.

The task's own stated expectation of "1341 ± the known flake" does not match either the measured parent-commit baseline (1305) or this build's own prior "1336" claim — neither this build nor any single commit in its history can account for the 36-test gap between 1305 and 1341; it is disclosed here as an unreconciled discrepancy in the task's own stated expectation, not attributed to any specific cause, since no commit at or before f0868fe was found carrying a matching count during this reconciliation pass. The authoritative, twice-measured, arithmetically-reconciled number is 1339 (1305 baseline + 34 net-added), confirmed identical whether computed bottom-up (per-file diff) or top-down (fresh full-suite run at HEAD).

Full apps/api suite confirmed green in 3 batches both before and after the Phase 9 hardening fix (batching required to stay under the local Supabase 100-connection ceiling, a pre-existing test-infrastructure limitation unrelated to this build — each spec file's fresh Jest module registry opens its own postgres.js connection pool that is never explicitly closed, so a single-process full run of all 55 files eventually exhausts connections regardless of --runInBand): final total 1339, 1338 passing, zero NEW failures beyond the 1 pre-existing, disclosed admin-catalog.spec.ts pagination flake (also reproduced, unchanged, at the parent commit — confirming it predates this build).

Docs fan-out (same pass): docs/database/schema_docs/notifications.md (new, full — all 18 tables, the combined insert-guard, design rationale, autonomy mapping); docs/modules/module_spec/notifications.md (new); docs/modules/MODULE_INDEX.md (the stale 11/166 row → 18/252, dependencies corrected to platform/crm/identity/offers/purchasing/orders/billing — integrations/audit dropped as dependency-blocked, neither module exists; the build-order planning list's own notifications line annotated **locked 2026-07-19** matching the precedent already set on the reporting line); docs/modules/CROSS_MODULE_CONTRACTS.md (the Notifications section rewritten with the actual built seams, replacing the pre-build placeholder that assumed an Integrations/Audit module; the Platform/Approvals row's disclosed TEMPORARY duplication marked RECONCILED per Ruling 15); this entry; docs/open-items/OPEN_ITEMS.md (row 163 resolved-with-pointer, row 244 updated to cross-reference this build's own pg_cron installation, row 275 resolved per Ruling 15, plus new rows for the platform-suppression-for-push semantics wrinkle, the D11 manual-poisoning residual risk, and the retention-horizon decision per Ruling 16 — carrying forward the RULED doc's own full Deferred list).

Independent lock-gate verification (separate general-purpose Agent-tool instance, no shared context beyond a fresh task brief, own fixtures — agent ID a9c349b0bb2db4e05). Dispatched adversarially against the LIVE schema with 10 named attack vectors: suppression bypass hunts (case/whitespace/malformed-key), recipient_contact immutability, monotonic-guard bypass hunts, campaign draft-gate + segment-validation cross-tenant hunts, campaign_recipient presence-guard + dedup-under-concurrency, an independent frequency-cap concurrency re-run, cross-tenant RLS reads on provider_event_log, the platform_suppression hard-lockdown check, the source_event_id bare-FK cross-tenant risk, and a full NULL-in-CHECK sweep across all 45 CHECKs in the schema. Full per-item results, pasted verbatim:

# Guard Result
1a Case-mismatch suppression bypass FAIL — mixed-case suppression.address_normalized (e.g. Foo@Bar.com) is never lowercased by the DB, and the guard only lowercases the incoming address, so a stored mixed-case row silently fails to match a correctly-lowercase incoming send.
1a Whitespace suppression bypass FAIL — even against a properly normalized suppression row, a single leading space in recipient_contact->>'email' defeats the match (lower() doesn't trim). This is a bug in the guard itself, not a data-hygiene issue.
1b Malformed/absent recipient_contact key FAIL — {"Email":...} (wrong case), {}, and NULL all silently skip the suppression check entirely (v_address stays NULL, whole block short-circuits) rather than failing closed.
1c is_test=true still suppressed PASS
1d is_transactional=true still suppressed PASS
2 recipient_contact immutability PASS — direct UPDATE and CTE UPDATE both rejected; same-value no-op and semantically-identical-but-differently-whitespaced JSON re-write both correctly allowed via the WHEN (new IS DISTINCT FROM old) clause.
3a Status regression + opened_at in same UPDATE PASS — whole statement atomically rejected, no partial timestamp write survives.
3b First-write-wins on opened_at/clicked_at PASS
3c CHECK rejects invalid status PASS
4a/4b Campaign draft gate, single- and multi-column UPDATE PASS — plain CHECK un-bypassable either way.
4d Cross-tenant segment reference PASS — rejected; global (tenant_id IS NULL) segment correctly accepted.
5a/5b Campaign-recipient presence guard, own-tenant vs cross-tenant PASS
5c campaign_recipient dedup under real concurrency PASS — 5 simultaneous backgrounded inserts, exactly 1 succeeded, 4 hit the UNIQUE violation.
6 Frequency-cap race (cap=2, 5 concurrent inserts) PASS — exactly 2 landed pending, 3 quota_blocked, tracker sent_count=2, no overcounting.
7 provider_event_log NULL-tenant + cross-tenant RLS PASS — as tenant B, both a plain SELECT and one with WHERE tenant_id IS NULL return 0 rows for the NULL-tenant row and tenant A's row.
8 platform_suppression lockdown (SELECT/INSERT/UPDATE/DELETE) PASS on the live table — all 4 rejected with genuine SQLSTATE 42501. Latent-risk gap found separately (below).
9 source_event_id bare-FK cross-tenant reference Disclosed, low severity, confirmed — the bare FK does let tenant A's row point at tenant B's event, but RLS blocks reading the joined content, so no actual leak.
10 NULL-in-CHECK sweep (all 45 CHECKs) PASS — every CHECK referencing an ANY-list enum sits on a NOT NULL column; the one genuinely nullable column used in a CHECK (notification.source_module) is explicitly self-guarded with IS NULL OR .... Zero exploitable NULL-bypasses found.

Verbatim verdict from the report: "1 BLOCKER, 3 MAJOR, 1 MINOR. All 6 named critical guards for campaign gating, delivery-attempt monotonicity, campaign-recipient dedup/presence, frequency-cap concurrency, and cross-tenant RLS on provider_event_log/platform_suppression hold up under adversarial live-reproduction — but the suppression-matching logic in guard_notification_insert() (the single most safety-critical path in this module, governing legal/compliance opt-out enforcement) has a real, trivially-reproducible whitespace-bypass bug plus two related defense-in-depth gaps (case-sensitivity, malformed-key silent skip) that should block lock until fixed, alongside the disclosed-but-unaddressed default-ACL latent risk on platform_suppression."

Disposition — 3 of 4 findings fixed same-day via 20260719000011_notifications_suppression_guard_hardening.sql, 1 disclosed as accepted residual risk:

  • BLOCKER (whitespace bypass) — FIXED. trim() added alongside lower() at the comparison point in guard_notification_insert().
  • MAJOR (case-mismatch on stored side) — FIXED. A new BEFORE INSERT OR UPDATE OF address_normalized normalization trigger (notifications.normalize_suppression_address()) forces NEW.address_normalized := lower(trim(NEW.address_normalized)) on both suppression and platform_suppression — a bad value can no longer be STORED at all, closing the gap at the write path rather than only patching the read path.
  • MAJOR (case-sensitive JSONB key lookup) — FIXED. The guard now falls back to a case-insensitive scan of recipient_contact's own keys via jsonb_each_text() when the exact-case 'email'/'phone' key isn't present, so a caller violating the lowercase-key convention no longer silently bypasses suppression.
  • MAJOR (ALTER DEFAULT PRIVILEGES on the notifications schema still grants authenticated full access to any future table) — DISCLOSED, NOT FIXED. The identical latent-risk class independently found and fixed for platform.polymorphic_target_registry (PROJECT_DECISIONS #68 Item 1). platform_suppression ITSELF is correctly locked down TODAY (0 grants, confirmed live) — the risk only materializes if this specific table is ever dropped and recreated, which default privileges cannot selectively exempt in advance. Fixing it would require revoking the schema-wide default, which would incorrectly block every other table's own future siblings from their legitimate tenant access — logged to OPEN_ITEMS with the concrete mitigation (re-apply the REVOKE in the same migration, if this table is ever recreated), not silently accepted.

All 3 fixes live-reproduced directly (mixed-case+padded email → normalized to foo@bar.com on storage; a leading-space mixed-case incoming send against a normalized suppression entry → correctly suppressed; a wrong-case {"Email":...} key → correctly suppressed) and covered by 3 new regression tests (notifications-schema.spec.ts §L, L1–L3). Full apps/api suite re-confirmed green after the fix (no new failures).

Schema-only — no NotificationsService yet. This closes the entire Notifications build.

What's deferred: classifying each individual feature within each module into a tier bucket (Starter / Pro / Enterprise / All-tiers). Tier decisions must be internally consistent across modules (e.g., "all AI features are Pro+"). Easier to do in a single focused pass than incrementally; does not block module spec progress.

When resolved: per-feature classification will live in each module's feature table (a "Tier" column). High-level tier summaries will live in docs/TIER_FEATURE_MATRIX.md (not yet created).

74. Gap-Fill Batch — A1/A2/A4/B3/B6/B10 (6 Confirmed 2026-07-19 Gaps, 5 Module Reopens)

2026-07-20, architect-authorized fix pass against 6 of the 2026-07-19 gap-validation report's confirmed gaps (vrida-gap-validation-2026-07-19.md) — each with a pre-decided shape, explicitly NOT including A3/B4 (amendment history — dependency-blocked on an undecided audit-trail architecture question, PROJECT_DECISIONS #74's own OPEN_ITEMS row 358), A5 (offline tax — undecided architect decision, row 363), or offer_redemption.consumer_id (ruled an intended boundary, no change). One migration per module reopen, full lock pipeline per runbook.

Collision-detection-before-build discipline (per the task's own explicit instruction): 3 real collisions were found against live schema state and resolved via explicit architect ruling (AskUserQuestion) before any migration was written, rather than silently improvised around:

  1. Pricing's pre-decided column name scope_type collides with an existing column — pricing.price_rule.scope_type already exists, governing the WHO axis (customer/price_level targeting). The new WHAT-axis (category/brand/variant/all) needed its own, distinct name. Ruled: item_scope_type.
  2. No brand catalog table exists anywhere in the codebase — required for A1's brand-scoped rules. Ruled: build a minimal inventory.brand table now (id/tenant_id/name/created_by_actor_id/timestamps only — no slug, description, or hierarchy, since nothing beyond pricing.price_rule.brand_id consumes it yet).
  3. goods_receipt_line.purchase_order_line_id is NOT NULL, which would have made B3's direct-receipt header creatable but line-less (zero lines ever insertable). Ruled: relax it too, beyond the task's own originally-scoped column list.

A 4th, purely mechanical correction (not a design collision): the task's own text said B3 belonged to purchasing — goods_receipt/goods_receipt_line were actually moved to a new receiving schema on 2026-07-10 (PROJECT_DECISIONS #55). The migration correctly targets the current, real location.

The 6 gaps, as built:

  • A1 (pricing) — category/brand-scope price rules. price_rule.item_variant_id relaxed nullable; new item_scope_type (variant/category/brand/all, NOT NULL DEFAULT 'variant') + nullable category_id/brand_id composite FKs (inventory.category/inventory.brand, both requiring a new prerequisite UNIQUE(id,tenant_id) — category's added here, brand's own table built with it from day one). chk_price_rule_item_scope_fk_consistency enforces exactly one target per scope. Resolution precedence (variant > category > brand > all) is documented as a future PricingService rule, not schema-enforced.
  • A2 (pos) — parked carts. New pos.parked_cart/parked_cart_line (register gains a prerequisite UNIQUE(id,tenant_id)). Status parked/resumed/discarded, guarded by trg_parked_cart_guard_status (no-op on a same-value re-write, reject on any transition out of a terminal state — mirroring notifications.delivery_attempt's own monotonic-guard shape, architect-selected since no prior trigger existed on this table to "match precedent" against). Parked carts NEVER reserve stock (a v1 decision, documented in a table comment) — no inventory.stock_reservation interaction exists anywhere in this build.
  • A4 (pos) — gift receipt. sale_line.is_gift boolean NOT NULL DEFAULT false. Line-level, covering mixed baskets. Receipt rendering (hiding price) and the gift-return bearer-credit mechanism remain the receipt-rendering/notifications build's own future work — the flag only persists intent.
  • B3 (receiving) — non-PO ("direct") receiving. goods_receipt.purchase_order_id relaxed nullable + new receipt_source (purchase_order/direct) CHECK-coherent with it; goods_receipt_line.purchase_order_line_id ALSO relaxed nullable (collision #3 above) with a new cross-table trigger (validate_goods_receipt_line_po_reference) enforcing the same source/line-ref coherence down to the line level — a plain CHECK can't reference a parent row, so this is trigger-enforced, mirroring pricing.validate_price_rule_supersession's own established pattern. vendor_id was already NOT NULL, so a direct receipt already carries a real vendor with no new column needed. The pre-existing receiving.check_goods_receipt_line_over_receipt_tolerance() trigger already tolerates a NULL purchase_order_line_id (a defensive guard added 2026-07-10 for an unrelated reason) — confirmed live, no change needed. A full stock-effect walk (a real inventory.stock_movement/stock_movement_line pair, linked back via the line's stock_movement_id/stock_movement_line_id) was live-reproduced end to end for a direct receipt, proving it completes a real inventory effect exactly like a PO-sourced one.
  • B6 (offers) — buy-X-get-Y. New, additive discount_type='buy_x_get_y' (the pre-existing bogo value, tied to a classic 1-for-1 free_item_variant_ref swap, is untouched) with bxgy_qualifying_qty/bxgy_reward_qty/bxgy_reward_variant_id (NULL = same item)/bxgy_reward_discount_pct (100 = free) and a coherence CHECK requiring all three non-NULL for buy_x_get_y, all NULL otherwise. Bundle pricing (arbitrary multi-item combos, "any 3 for $10") stays deferred, per the task's own explicit instruction — its own OPEN_ITEMS row updated, not built. A real bug, found only during this build's own live-reproduction step, not by the original design: the PRE-EXISTING chk_offer_discount_type_coherence CHECK enumerated percent_off/amount_off/free_item+bogo's own required/forbidden columns by name with NO branch at all for the new value — every buy_x_get_y insert would have unconditionally failed this older, unrelated CHECK regardless of the new bxgy_* columns being perfectly correct. Fixed the same day via a follow-up migration (20260720000008) adding the missing branch. This is exactly the class of bug the task's own instruction to "verify existing budget/margin/max_per_consumer triggers unaffected (re-run offers spec sections)" was written to catch.
  • B10 (orders) — forfeited deposits. order_payment.status CHECK widened to add 'forfeited', guarded by a new terminal-state trigger (trg_order_payment_guard_status, same no-op-plus-reject shape as A2's — architect-selected, since neither order_header nor order_payment carried any status-transition trigger beyond set_updated_at to match precedent against). Deliberately NOT a full ordinal ranking across the other 6 non-linear statuses (they branch, they don't chain) — scoped to exactly what B10 asked: forfeited is terminal. The deeper semantic questions this row's own OPEN_ITEMS text raises (does a forfeited deposit still count toward balance_due_cents? does it post anywhere in billing?) are explicitly NOT decided here — that remains OrderService's own future build.

Live reproduction: all 24 named scenarios across the 6 gaps passed on a throwaway gf-tenant-1 fixture (raw psql DO block, fully cleaned up) — every CHECK/trigger's passing case AND each rejecting case, B3's full stock-effect walk, and A2's full park→resume and park→discard walks (including the terminal-state rejections and same-value no-op tolerance). 3 append-only triggers (inventory.stock_movement/stock_movement_line, pos.sale_line) needed a table-owner DISABLE/ENABLE TRIGGER bypass for fixture cleanup only, since the local Supabase postgres role is not a real superuser (session_replication_role is denied) — a test-cleanup mechanic, not a change to the guards themselves, which were already proven live by the passing scenarios above.

Tests: 40 new tests across the 6 touched spec files, each written and run by a separate, parallel agent instance against the live schema (pricing-schema.spec.ts +8, pos-schema.spec.ts +11, offers-schema.spec.ts +5, orders-schema.spec.ts +4, receiving-schema.spec.ts +6, inventory-schema.spec.ts +6 for the new brand table + category's prerequisite unique). 3 pre-existing test assertions were corrected in the same files (not deleted) because the schema changes themselves made their stated counts stale: pos-schema.spec.ts's exhaustive table-count assertion (10→12 tables), receiving-schema.spec.ts's column-count assertion (goods_receipt 33→34 cols), and inventory-schema.spec.ts's table-count assertion (25→26 tables) — each disclosed by its own agent as a required correction, not a stylistic change.

Suite reconciliation: baseline 1339 (per PROJECT_DECISIONS #73's own twice-measured reconciliation) + 40 net-added = 1379, matching the actual measured total exactly. A full-suite run under both default parallel workers and --runInBand intermittently failed 11 suites with PostgresError: remaining connection slots are reserved for roles with the SUPERUSER attribute — a connection-pressure artifact of running all 55 suites back-to-back against the local (non-superuser) postgres role, not a real regression: none of the 6 files this batch touched were ever among the failures, and re-running all 11 failed suites in isolation (small batch, no pressure) reproduced only the ONE already-documented, pre-existing admin-catalog.spec.ts pagination flake (the same flake disclosed repeatedly since PROJECT_DECISIONS #70) — the other 10 passed cleanly. 1378/1379, the 1 failure being the same pre-existing flake as every prior reconciliation in this build history. Zero tests deleted, renamed as removed coverage, or skipped — confirmed via git diff line-count reconciliation (3 "deleted" it( lines are exactly the 3 corrected pre-existing assertions above, each an edit in place, not a removal).

A newly-found, disclosed-not-fixed doc drift (incidental to this batch, found while reconciling MODULE_INDEX.md counts for the inventory reopen): the row's stated column count (358, as of the Phase 2/Nursery-Extraction pass) does not reconcile against a live re-measurement — the true pre-batch live count was 350 cols/25 tables (confirmed by subtracting this batch's own brand table, 7 cols/1 table, from the live post-migration total of 357/26), an 8-column pre-existing drift unrelated to this batch's own work. Logged to OPEN_ITEMS rather than silently corrected without explanation; this entry's own MODULE_INDEX.md update states the corrected true figure (357, not 365) but does not chase the 8-column discrepancy to its root cause.

Table/column deltas this batch, all live-confirmed via information_schema:

Module Before After Δ
pricing 4 tables / 78 cols 4 tables / 81 cols +3 cols (item_scope_type, category_id, brand_id)
inventory 25 tables / 350 cols (true live count — see drift disclosure above) 26 tables / 357 cols +1 table (brand, 7 cols), category +0 cols (constraint-only)
pos 10 tables / 160 cols 12 tables / 183 cols +2 tables (parked_cart 13 cols, parked_cart_line 9 cols) + 1 col (sale_line.is_gift)
receiving 2 tables / 62 cols 2 tables / 63 cols +1 col (receipt_source); goods_receipt_line +0 cols (constraint/trigger-only)
offers 7 tables / 123 cols 7 tables / 127 cols +4 cols (bxgy_qualifying_qty/bxgy_reward_qty/bxgy_reward_variant_id/bxgy_reward_discount_pct)
orders 7 tables / 175 cols 7 tables / 175 cols 0 (CHECK + trigger only)

Independent lock-gate verification (separate agent instance, no shared context, own fresh fixtures): dispatched after all of the above. Independently read all 8 migrations + this entry, built its own throwaway fixtures against the live DB, read every trigger/CHECK's actual deployed definition via pg_get_functiondef/pg_get_constraintdef rather than trusting this entry's claims, and ran 45 adversarial scenarios — including NULL-safety probes on every new/widened CHECK, cross-tenant FK exploit attempts on every new composite FK (category_id/brand_id/bxgy_reward_variant_id), a genuine two-role runtime RLS exploit (SET ROLE authenticated + cross-tenant SELECT/UPDATE attempts) against all 3 new tables, and an independent re-derivation of every claimed table/column count from information_schema. Verdict: all 6 gaps (A1/A2/A4/B3/B6/B10) CONFIRMED WORKING exactly as described above — zero discrepancies found against this entry's own claims, including the table/column delta table immediately above (all 6 rows independently re-derived and matched exactly once the verifier correctly excluded the stock_reconciliation_shell VIEW from inventory's count, matching the convention this entry itself already established). One new, genuinely unrelated finding surfaced: inventory.stock_movement.chk_stock_movement_source_module still lacks a 'receiving' value (a pre-existing drift from the 2026-07-10 receiving schema extraction, PROJECT_DECISIONS #55, not introduced or touched by this batch) — the verifier only discovered it because completing B3's own stock-effect-walk fixture required a real stock_movement insert, and source_module='receiving' was rejected outright, forcing a 'purchasing' workaround. Logged to its own new OPEN_ITEMS row, not fixed in this pass (out of this batch's own named scope).

Schema-only across all 6 touched modules — no service-layer methods exist yet for any of PricingService/POSService/ReceivingService/OffersService/OrderService consuming these new capabilities.

Amendment, 2026-07-20 (Drizzle Sync Follow-Up, same day): the Drizzle↔live-DB drift this entry's own docs pass disclosed (7 touched schema files never updated to mirror the 8 migrations above) is now closed. All 7 files brought into exact parity, proved column-by-column via a getTableConfig()-vs-information_schema diff script (not eyeballed) — the parity script itself caught a genuine miss (pricing/rule.ts had been read but never actually edited) before this amendment was written. A report-only sweep of all 362 Drizzle-exported tables across every schema found zero drift beyond this batch's own. drift-check.ts and the full apps/api suite (1379, zero deltas) both re-confirmed clean. See OPEN_ITEMS' own closure of the corresponding row for full detail.

B. Invitation Expiry Policy

Deferred until: before building the invitation flow (part of the Identity module implementation).

What's deferred: the default validity period for a staff invitation. identity.invitation.expires_at is NOT NULL with no schema-level default — the application must compute and supply it on every insert. A locked policy is needed (e.g., "7 days from issue" or "configurable per tenant within a 1–30 day band").

Why deferred: not a schema gap — expires_at already exists. The policy is an application-level decision (UX + security tradeoff), best made when the invitation UI/flow is designed.

When resolved: record the value here and reference it from the Identity module doc.

C. Customer-App Access Controls

Deferred until: after initial launch and consumer adoption data is available.

What's deferred:

  • Free tier vs paid tier for end consumers (if any)
  • Feature limits for non-connected users (e.g., chat usage caps)
  • Tier benefits for connected consumers (e.g., unlimited chat at premium tier)
  • Subscription model for consumers (if any)
  • Which features require a nursery connection vs which are universal

Initially: all features available to all consumers except white-label theming, which is gated to consumers connected to Enterprise-tier businesses. No other feature gating beyond what is natural (must connect to a business to order from it).

D. Open Consumer-Phase Questions

Record for design time — these are not yet decided:

  • Unclaimed-stub point handling: do unclaimed stubs accumulate points before the consumer claims them? When claimed, are prior points transferred?
  • Reward expiry mechanics: calendar-year reset? rolling window? inactivity-based?
  • Consumer auth provider specifics: which social-login library; Supabase Social Auth vs. custom implementation.

75. Inventory Core Write Protection — Schema-Only Reopen

2026-07-15 task run; governing evidence commit ef767623d8166daeba775d4328a1de896af3a2ed. Inventory was reopened to make the stock/reservation/movement write boundary structural before Transfer is built. This entry records schema enforcement only: no InventoryService, TransferService, API, UI, worker, scheduler, runtime caller, or module wiring was created.

Decision. Ordinary callers may continue editing item_variant catalog fields except avg_cost_cents, and may update only stock.reorder_point, reorder_qty, min_qty, and max_qty. Operational stock, lot, reservation, movement-header, and movement-line writes require narrow NOLOGIN-owned database invariant functions. All protected roles are NOLOGIN/NOINHERIT/non-superuser/non-BYPASSRLS; ordinary/authenticator-reachable roles have no membership. Supabase PostgreSQL 16 retains only the role creator's administrative membership row for postgres, with both inherit_option=false and set_option=false; it cannot inherit or assume the protected roles.

Movement and reservation integrity. Five columns were added: three on stock_movement (posting_integrity, expected_line_count, request_hash) and two on stock_reservation (idempotency_key, request_hash). The locked historical population was exactly 1,892 headers / 1,158 lines: 1,194 zero-line, 468 one-line, and 230 three-line headers. Every historical header remains immutable legacy_unverified; no key, hash, child, provenance, or cost evidence was fabricated. New protected headers are complete, deterministic-key/hash guarded, and commit only with their exact positive deferred child count. Reservation create/retry, oversubscription prevention, standalone non-fulfillment transitions, and combined fulfillment+movement posting are row-lock coupled. Complete reservation-fulfillment movements are additionally source-unique on (tenant_id, reservation source_id): same-key retries must match the stored request hash, and changed-key retries are rejected before any second stock effect.

Returns companion. returns.post_and_cap_return_receipt_line() is now a narrow definer wrapper owned by returns_invariant_owner. It derives facts from locked Returns rows and calls the private Inventory primitive. One receipt line produces one complete header and one line with its stock effect atomically. source_module='returns' remains in live PostgreSQL and Drizzle.

Transfer boundary. No Transfer tables, Transfer wrappers, or Transfer executor grants were built. Transfer enum values remain unreachable. Transfer-specific wrappers are deliberately deferred to the Transfer migration and may exist only after authoritative Transfer rows can be locked to derive authority, tenant, actor, quantity, source identity, time, idempotency, disposition, and cost provenance.

Post-build live shape. 26 base tables / 362 base-table columns / 1 view; 62 CHECKs, 118 FKs, 26 PKs, 13 UNIQUE constraints, 137 indexes, 38 policies, and 31 non-internal triggers. RLS remains enabled on all 26 tables. Numeric, reservation/stock reconciliation, tenant-FK, default-ACL, function owner/search-path, role-closure, movement-cardinality, and Transfer-absence sweeps returned zero violations. The 137th index is the final-verifier-required source-identity unique guard for complete reservation-fulfillment movements.

Migration-state reconciliation. The repository's Drizzle journal contains only its two foundational generated migrations; later hand-written SQL is intentionally executed lexically by the repository drift workflow and is not journaled. The directly applied 20260720000009_inventory_core_write_protection.sql was therefore not represented in drizzle.__drizzle_migrations, and no history row was fabricated. A disposable database proved the Inventory migration sequence after two disclosed upstream/environment prerequisites: the pre-existing Agents migration duplicates kill_switch_event policy creation, and pg_cron is restricted to the configured postgres database. After bypassing only those unrelated blockers, Inventory migrations applied through the repository's lexical path. Schema-only dumps of inventory and returns match the local database after removing function-body comments, proving no untracked target-schema DDL.

Verification status: CLEAN. Builder tests, Drizzle typecheck, API build, targeted drift check, and module regressions are green. Eight focused affected-module suites passed 305 tests; the final core rerun passed 24/24 after the last correction. A 56-suite monolithic API run is not a reliable repository gate because suite-local pools exhaust PostgreSQL's 100-connection ceiling even under --runInBand; every suite reported by that exhaustion passed in its own forced-exit process. The first independent pass's NOT CLEAN report, all dispositions, and the final fresh-context CLEAN report are preserved below. Inventory Core Write Protection is re-locked at the schema boundary.

Section 4 self-audit (post-build). A column drift/counts PASS (26/362, exact +5); B RLS PASS (26/26); C nullable tenant uniqueness PASS (NULLS NOT DISTINCT active-source grain); D soft-delete uniqueness PASS; E partial-index enum predicates PASS; F CHECK completeness PASS (62 live, finite/sign/status relationships exercised); G forward-reference FKs PASS (Transfer remains absent and disclosed); H cross-module consistency PASS (Returns, Orders, POS, Receiving targets verified); I money derivation PASS (no new money column; Returns does not revalue tenant-global average cost); J JSONB shape N/A; K tenant-leading protected indexes PASS; L idempotency/source lookup indexes PASS; M conditional column contracts PASS; N locked decisions PASS; O non-RLS access PASS (all Inventory tables RLS-enabled; narrow roles audited); P rationale PASS (Decision/Why/Rejected/Guard retained here and in module docs); T trigger audit PASS (31 non-internal triggers, deferred-cardinality and write guards live-tested); U four Design-Phase Integrity blocks PASS in the governing RULED design.

Recurring-bug sweeps. Zero non-finite or negative protected numeric rows; zero active reservations without stock; zero stock/reservation aggregate mismatches; zero protected-surface tenant-FK violations; zero Transfer tables/functions; no ordinary protected DML or private primitive EXECUTE; avg_cost_cents remains outside ordinary INSERT/UPDATE grants; future Inventory tables inherit SELECT-only and future postgres-created functions do not inherit PUBLIC EXECUTE. PostgreSQL's function PUBLIC EXECUTE default is global to the creating role, so migration ...00014 correctly uses a global ALTER DEFAULT PRIVILEGES FOR ROLE postgres REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC; the schema-qualified form in the design cannot subtract PostgreSQL's built-in global function default.

Independent post-build verification — verbatim report:

Independent Post-Build Verification — Inventory Core Write Protection

Verifier identity: /root/inventory_core_postbuild_verifier Repository HEAD: ef767623d8166daeba775d4328a1de896af3a2ed Mode: Fresh-context, read-only verification. I made no file changes, database mutations, migrations, or cleanup operations.

Final verdict: NOT CLEAN

The build has one deterministic correctness blocker and multiple material authority, migration-safety, and evidence-integrity defects. It must not be locked or represented as clean in its current form.

Findings

1. BLOCKER — Fulfillment fails when the reservation consumes all or nearly all available stock

Evidence

inventory.fulfill_reservation_and_post_movement_protected() calls the posting primitive before reducing reserved_qty:

  • 20260720000009_inventory_core_write_protection.sql:834-840 posts -v_res.quantity.
  • The primitive immediately reduces stock.on_hand_qty at lines 655-658.
  • Only afterward does fulfillment reduce reserved_qty at lines 842-846.
  • chk_stock_quantity_domain immediately requires reserved_qty <= on_hand_qty.

For stock with on_hand_qty = 5, reserved_qty = 5, and a five-unit fulfillment, the posting statement attempts an intermediate state of on_hand_qty = 0, reserved_qty = 5. PostgreSQL checks the constraint at that statement and rejects the operation before the later reservation decrement.

The test at inventory-core-write-protection.spec.ts:376-414 covers only 20 on hand / 4 reserved, so it misses this boundary.

Required correction

In an additive migration, replace the fulfillment function so an active reservation’s reserved_qty is decremented under the existing stock lock before calling the posting primitive. A later failure will roll back that decrement atomically. Preserve the fulfilled-retry path so it does not decrement twice. Add tests for:

  • Fully reserved stock.
  • Near-fully reserved stock.
  • Failure after the pre-decrement proving complete rollback.
  • Exact retry after successful fulfillment.

2. MAJOR — The Returns definer trigger operates on caller-supplied tenant identity before outer RLS and constraints complete

Evidence

returns.post_and_cap_return_receipt_line() is a SECURITY DEFINER BEFORE INSERT trigger. At lines 888-950 it uses NEW.tenant_id to select and lock the receipt, authorization line, authorization header, source order/POS line, actor records, and to post inventory.

A caller can supply another tenant’s UUID and tenant ID. The eventual outer insert may fail its RLS WITH CHECK, FK, or another constraint and roll the transaction back, but the definer function has already read or locked cross-tenant rows and can expose tenant-dependent errors or timing. The protected owner policies are intentionally unrestricted, so they do not constrain this path.

Required correction

Replace direct ordinary INSERT plus the BEFORE definer trigger with a narrowly granted, source-specific command wrapper, or an equivalent design in which:

  • Tenant identity is derived from a locked authoritative receipt/header.
  • Caller tenant authority is checked before any other tenant-specific lookup.
  • Receipt and authorization facts are derived from locked rows.
  • Direct INSERT cannot invoke privileged posting with spoofed NEW values.
  • Cross-tenant tests assert indistinguishable rejection and no movement, stock, or capacity side effect.

3. MAJOR — Migration preflight is not protected against concurrent stock/reservation changes and omits required source validation

Evidence

The migration locks only:

LOCK TABLE inventory.stock_movement,
           inventory.stock_movement_line
IN ACCESS EXCLUSIVE MODE;

That is line 12 of migration 00009. The reconciliation preflight then reads inventory.stock_reservation and inventory.stock at lines 26-100 without locking those tables. Ordinary write privileges are revoked only later in the migration.

A concurrent valid-numeric stock or reservation write can therefore land after reconciliation but before revocation. Aggregate equality between active reservations and stock.reserved_qty has no final cross-table constraint to catch that race.

The preflight also checks that active reservations have a stock grain, but does not resolve order-sourced reservations against authoritative orders.order_header and orders.order_line tenant/site/variant/source linkage, as required by the ruled design and build task.

Required correction

Add an aborting migration gate that:

  • Acquires sufficient locks on stock_reservation, stock, and the authoritative order source tables before reconciliation.
  • Reruns the full reservation/stock aggregate, duplicate-source, and numeric-domain sweeps.
  • Validates every order reservation’s header, line, tenant, site, variant, source ID, and source-line ID.
  • Fails closed before declaring the protected boundary active.

4. MAJOR — The only executor-granted routine accepts a free reservation UUID with no tenant or source authority check

Evidence

Migration 00009:865 grants inventory_command_executor EXECUTE only on:

inventory.transition_reservation_protected(uuid, text)

The function at lines 767-799 selects a reservation by bare UUID under an invariant-owner definer context. It does not derive the reservation from an authoritative source, validate a tenant/caller relationship, or validate actor authority.

Current role closure prevents an ordinary role from reaching inventory_command_executor, so I found no present authenticated exploit. However, once the executor role is assigned for its intended use, possession of a reservation UUID is sufficient to release, expire, or cancel another tenant’s reservation.

Required correction

The safe immediate correction is to revoke this EXECUTE grant until a source-specific wrapper exists. The durable correction is a command surface that derives and locks the reservation from an authoritative tenant-scoped source and validates executor authority; tenant GUC input alone is not sufficient authority.

5. MAJOR — Test fixtures forge protected “complete” movements without stock effects and pollute the local verification database

This is explicitly test-artifact pollution in the local development/verification database, not an assertion about production data.

Evidence

receiving-schema.spec.ts:879-899 claims a “full stock-effect walk,” but insertProtectedMovementFixture() directly assumes the invariant-owner role and inserts a movement and line. It does not create or update the matching inventory.stock grain through the posting primitive.

A single read-only snapshot of local database postgres returned:

{
  "complete_total": 94,
  "complete_without_matching_stock_grain": 84,
  "returns_complete_without_live_source_line": 10,
  "groups": [
    {
      "source_module": "purchasing",
      "source_type": "<NULL>",
      "n": 44,
      "null_source_id": 44
    },
    {
      "source_module": "purchasing",
      "source_type": "receiving_test_fixture",
      "n": 40,
      "null_source_id": 40
    },
    {
      "source_module": "returns",
      "source_type": "return_receipt_line",
      "n": 10,
      "null_source_id": 0
    }
  ]
}

Their idempotency-key shapes were:

purchasing | <NULL>                 | test:legacy-reconciliation:<uuid> | 44
purchasing | receiving_test_fixture | receiving:test:<uuid>             | 40
returns    | return_receipt_line    | returns:receipt:<uuid>             | 10

All 84 purchasing fixtures lacked a matching stock grain. The ten Returns movements retained their stock effect but their source receipt lines had been deleted by test cleanup.

The historical population remained correctly classified:

complete          | 94   | 94 non-null keys | 94 non-null hashes
legacy_unverified | 1892 | 0 non-null keys  | 0 non-null hashes

Required correction

  • Do not directly manufacture persistent posting_integrity='complete' rows outside the primitive.
  • Use transaction-scoped rollback fixtures or an explicitly authorized cleanup strategy.
  • Rename the Receiving test to an FK/seam test unless a real Receiving posting wrapper is built.
  • Do not claim that it proves a stock effect.
  • Add a post-suite sweep for complete rows lacking supported source identity or matching stock provenance.
  • Treat cleanup of existing append-only test artifacts as a separate architect-authorized operation; do not silently delete them.

6. MAJOR — The new core protection test does not TypeScript-check

Evidence

Command:

npx tsc --noEmit -p apps/api/tsconfig.json --pretty false

The new file produced nine errors:

inventory-core-write-protection.spec.ts(32,3): TS2322
inventory-core-write-protection.spec.ts(354,12): TS18046
inventory-core-write-protection.spec.ts(354,30): TS18046
inventory-core-write-protection.spec.ts(364,59): TS18046
inventory-core-write-protection.spec.ts(368,59): TS18046
inventory-core-write-protection.spec.ts(384,30): TS18046
inventory-core-write-protection.spec.ts(399,27): TS18046
inventory-core-write-protection.spec.ts(400,12): TS18046
inventory-core-write-protection.spec.ts(400,35): TS18046

There were also three existing errors outside the new core test. By contrast:

npx tsc --noEmit -p packages/db/tsconfig.json

passed.

Required correction

Correct the asRole<T> return typing and query result inference, then rerun the API TypeScript check and the protection test suite. A lock-gate test must compile under the repository’s TypeScript configuration.

7. MAJOR — Authoritative module count/status documentation remains stale

Evidence

The live and disposable schemas both contain 26 Inventory tables and 362 columns. The updated Inventory schema documents say 26/362, but docs/modules/MODULE_INDEX.md:37 still declares 26/357 and describes that as the true count.

docs/DOCS_INDEX.md also contains older Inventory and aggregate information, conflicting with the project rule that it is the single source of truth for counts/status.

Required correction

Reconcile the authoritative documentation to the live 26/362 shape, update the reopen/verification status without claiming a clean lock, and rebuild the HTML viewer as required by AGENTS.md.

8. MINOR — One trigger function retains default PUBLIC EXECUTE

Evidence

inventory.guard_item_variant_average_cost() has a null proacl, which means default PUBLIC EXECUTE remains. The other sensitive helper functions were explicitly revoked.

Because it is a non-definer trigger function, it cannot currently be usefully called as an ordinary SQL function, so this is not a demonstrated write bypass.

Required correction

Explicitly REVOKE ALL ... FROM PUBLIC in the next additive migration and include it in the function-ACL regression query.

9. NOTE — The reciprocal-lock test does not exercise production code

Evidence

inventory-core-write-protection.spec.ts:509-524 manually executes an ordered SELECT ... FOR UPDATE twice. It calls no application or protected database routine. No Transfer table or Transfer wrapper exists, which is correct for scope, but the test therefore demonstrates only the test’s own SQL ordering—not production reciprocal multi-grain behavior.

Required correction

Describe this as a canonical ordering pattern test, not runtime Transfer evidence. Add a real reciprocal-concurrency test when a multi-grain wrapper is introduced.

10. NOTE — Migration application identity is not recorded in the database migration journal

The database’s drizzle.__drizzle_migrations and journal contain only the foundational tracked migrations. Migrations 00009–00015 follow the repository’s documented handwritten/untracked convention, so catalog parity demonstrates the resulting shape but the database cannot independently prove which exact file bytes were applied.

Verified file SHA-256 values:

00009  33caded79860ff3b97c3024ba90669eedcb9a5919889684b64d9b0bad2b2f32a
00010  65e3d09b0545bd3d6f3b445d8847fc92cae307ffba6424c98610598cd8d7f8bb
00011  5a8639fc7de259a8e872b17e06598bc0266fbf49ba56fd0cbc7fba1c6c0ee092
00012  f5f1222486add3970e2108ed6deb52790017da067b35e83ef903d7d271e8599d
00013  bffe0ee949d2bfbdc4fa948b1d96cbe461e29717925e4892f798c84c9191f043
00014  b8e90cd292e4147f0aa860fe4e6488e9350b85fee164a3077c262bb98e42c6e6
00015  5c4e636033ef387ed31e4753ec5da22903fa4fde2b26eb9cf97782b83ad492d1

Confirmed implementation properties

The following portions were verified successfully:

  • HEAD exactly matches the requested commit.
  • Local and disposable Inventory schemas both report:
base tables             26
base-table columns      362
CHECK constraints       62
foreign keys            118
primary keys             26
UNIQUE constraints       13
indexes                  136
RLS-enabled tables        26
FORCE RLS tables           0
policies                  38
non-internal triggers     31

The core count query used was:

SELECT
  (SELECT count(*) FROM information_schema.tables
   WHERE table_schema='inventory' AND table_type='BASE TABLE'),
  (SELECT count(*) FROM information_schema.columns
   WHERE table_schema='inventory'
     AND table_name IN (
       SELECT table_name FROM information_schema.tables
       WHERE table_schema='inventory' AND table_type='BASE TABLE'
     )),
  (SELECT count(*) FROM pg_constraint c
   JOIN pg_namespace n ON n.oid=c.connamespace
   WHERE n.nspname='inventory' AND c.contype='c'),
  (SELECT count(*) FROM pg_constraint c
   JOIN pg_namespace n ON n.oid=c.connamespace
   WHERE n.nspname='inventory' AND c.contype='f'),
  (SELECT count(*) FROM pg_policies WHERE schemaname='inventory'),
  (SELECT count(*) FROM pg_trigger t
   JOIN pg_class c ON c.oid=t.tgrelid
   JOIN pg_namespace n ON n.oid=c.relnamespace
   WHERE n.nspname='inventory' AND NOT t.tgisinternal);

Additional confirmed properties:

  • Protected roles are NOLOGIN, NOINHERIT, non-superuser, and non-BYPASSRLS.
  • No ordinary/authenticator-reachable role membership reaches a protected role.
  • Protected definer functions use fixed pg_catalog search paths.
  • The executor has no primitive posting, reserve, or fulfill EXECUTE grant.
  • Ordinary roles cannot directly mutate protected stock quantities, reservations, movements, movement lines, lots, or average cost.
  • Planning-column updates remain separately available and are protected against changing operational stock fields.
  • Default Inventory table privileges grant future authenticated tables SELECT only.
  • Default function privileges were globally closed.
  • Numeric-domain constraints reject NaN, positive infinity, negative infinity, negative quantities, and invalid reserved/on-hand relationships.
  • Complete movement cardinality is enforced by deferred constraint triggers.
  • Legacy rows remain legacy_unverified without fabricated idempotency keys or hashes.
  • No Transfer table, wrapper, executable routine, placeholder row, or live Transfer attribution was introduced.
  • The private posting primitive rejects dormant Transfer attribution.
  • Drizzle preserves the new columns, composite relationships, and Returns source-module representation.
  • The repository drift checker passed.
  • The database-package TypeScript check passed.
  • The disposable database is empty and matches the target local schema shape for the examined objects.

Final verdict: NOT CLEAN

Builder disposition of the first independent report (all 10 findings accepted):

# Severity Disposition Main-body correction and evidence
1 BLOCKER Fixed Additive migration 20260720000016_inventory_core_verifier_corrections.sql changes fulfillment to lock the reservation/stock grain, decrement reserved_qty, mark the reservation fulfilled, and only then post the movement in the same transaction. Any posting failure rolls the pre-decrement and transition back. New tests cover fully reserved stock, nearly fully reserved stock, a deterministic post-decrement collision rollback, and exact retry behavior.
2 MAJOR Fixed Migration ...00016 converts returns.trg_return_receipt_line_post_inventory to AFTER INSERT; the wrapper now derives from the persisted, tenant-validated line and locked parent. Migration ...00018_inventory_core_returns_line_visibility.sql adds the exact owner SELECT policy needed for the post-RLS update. A cross-tenant test proves rejection occurs before any Inventory side effect.
3 MAJOR Fixed Migration ...00016 takes ACCESS EXCLUSIVE locks on inventory.stock_reservation and inventory.stock, compatible SHARE locks on the Orders source tables, and reruns the complete numeric, active-reservation/stock, duplicate-source, and authoritative Orders header/line/tenant/site/variant/linkage sweeps before activating the correction.
4 MAJOR Fixed All executor EXECUTE on the generic UUID-only reservation transition routine is revoked. inventory_command_executor now has zero executable Inventory functions; future authority must be exposed only through source-specific wrappers that derive tenant and source facts from authoritative rows.
5 MAJOR Fixed Inventory, Returns, and Receiving fixtures now post truthful protected movements and clean source rows, movements, stock, and reservations together. The Receiving assertion is explicitly an FK-seam test, not runtime Receiving-posting evidence. A post-suite unsupported-complete-evidence sweep is enforced. After those fixes were proven, exactly 94 identified local test artifacts (44 test:legacy-reconciliation:%, 40 receiving:test:%, 10 orphaned returns:receipt:%) were removed in one deterministic admin-only cleanup; the 1,892 historical legacy_unverified headers were untouched.
6 MAJOR Fixed The new core suite's generic return typing and query-result inference now compile. The API TypeScript check has no Inventory Core errors; its only remaining errors are three pre-existing strictness findings in inventory-schema.spec.ts (stockLotId, siteId) and pricing-schema.spec.ts (ruleId). The database package typecheck and API build pass.
7 MAJOR Fixed MODULE_INDEX, DOCS_INDEX, MODULE_BUILD_STATUS, the Inventory schema document, module specification, catalog, contracts, open items, and this decision record now identify the current 26/362/1 shape and the reopen state. The required HTML viewer is rebuilt after the final Markdown disposition.
8 MINOR Fixed Migration ...00016 explicitly revokes PUBLIC execution of inventory.guard_item_variant_average_cost(). The core suite now asserts the privilege is absent, alongside the avg_cost_cents column-grant checks.
9 NOTE Accepted; scoped evidence corrected The test is named and described only as the canonical ordered-lock pattern. It is not claimed as production Transfer evidence. A real reciprocal multi-grain concurrency test remains mandatory when the Transfer migration introduces a multi-grain wrapper; building that wrapper now would violate the approved scope.
10 NOTE Accepted; reconciled without fabricated history No Drizzle journal row was fabricated. The repository's established post-foundation path is lexical execution of handwritten SQL plus drift/parity verification. A fresh disposable Supabase database applied the Inventory sequence through that path after isolating two unrelated upstream/environment blockers; local and disposable target-schema catalogs match. Migration bytes are pinned by SHA-256 below.

First-report disposition totals: 10 accepted; 8 fixed in this build; 1 corrected as a scoped-evidence claim with the real runtime test deferred to the Transfer build; 1 accepted as migration-history disclosure and reconciled through fresh-database reproduction. Zero findings rejected.

Correction migration SHA-256:

00016  0c48d78b06dde82fda0cf99d306682d35ffdebaf597a677ceb772f04fa7995cf
00017  8a397ff44115394b9311a4464cc91f47a365fe4ff4efde286da7ad8612013152
00018  455b3b9e74d0bdd830a1527af673c24f739c865d371c234a0b49261f33e4ae32
00019  606594ae602b932d91826e3be0a802ec1c02f4e00e28fe013dac94c51e3c9e64
00020  fb2559dde8452845e484b586569742fb3bc8435d86fb07e1f53592d96f5270d4

The first verifier's NOT CLEAN verdict remains historically authoritative for the state it inspected. It is not overwritten by this disposition. A separate fresh-context verifier must judge the corrected design and build before the reopen may be re-locked.

Final independent post-build reverification — verbatim report:

Final Independent Post-Build Verification — Inventory Core Write Protection

Addressed to: /root Verifier identity/session ID: /root/inventory_core_final_reverifier Evidence commit: ef767623d8166daeba775d4328a1de896af3a2ed Mode: Fresh-context independent verification. I edited no files, ran no migrations, and performed no database cleanup. Database behavior probes ran inside explicit rollback transactions; the focused test suite is fixture-self-cleaning. Post-run sweeps confirmed zero verifier artifacts.

Findings and dispositions

BLOCKER — Changed-key fulfillment retry could double-decrement stock — FIXED

I found that the corrected fulfillment routine accepted an already-fulfilled reservation with a different idempotency key. Before correction, a rollback-only reproduction produced:

initial stock:          on_hand=10, reserved=1
fulfillment key 1:      was_retry=false
fulfillment key 2:      was_retry=false, different movement
resulting state:        on_hand=8, reserved=0
fulfillment movements:  2

The existing test covered a changed payload under the same key, but not a changed key.

Migration 20260720000020_inventory_core_fulfillment_source_idempotency.sql fixes this structurally:

  • Adds a locked preflight for existing complete reservation-fulfillment movements.
  • Adds partial unique index stock_movement_reservation_fulfillment_source_unique on (tenant_id, source_id) where the movement is complete and source_type='reservation_fulfillment'.
  • Makes a fulfilled retry resolve and lock the existing source movement.
  • Rejects a different key before posting.
  • Preserves same-key request-hash validation.

Independent rollback-only reverification returned:

changed-key retry:      rejected with idempotency collision
on_hand_qty:            9
reserved_qty:           0
reservation status:     fulfilled
fulfillment movements:  1

A direct attempt to insert a second complete fulfillment header for the same tenant/source failed on the new unique index; the source row count remained one. Both probes rolled back.

MINOR — Executor inherited one PUBLIC trigger-function grant — FIXED

The literal documentation claim that inventory_command_executor had zero executable Inventory functions was initially false because it inherited PUBLIC execution on the pre-existing non-definer trigger function:

inventory.reject_stock_count_line_mutation_after_reconciled()

This was not an exploitable protected-write or UUID-attribution path, but it was an ACL/test-evidence defect.

Migration 20260720000019_inventory_core_trigger_function_acl_closure.sql revokes PUBLIC execution and verifies the entire Inventory function namespace. Local and disposable catalogs now both report:

inventory_command_executor executable Inventory functions: 0
PUBLIC EXECUTE on the trigger function:                      false

No unresolved findings remain.

Verification evidence

Repository and migration chain

  • git rev-parse HEAD matched the requested evidence commit.
  • Migration filenames 20260720000009 through 20260720000020 are lexically ordered and collision-free.
  • Verified SHA-256 values:
00009  33caded79860ff3b97c3024ba90669eedcb9a5919889684b64d9b0bad2b2f32a
00010  65e3d09b0545bd3d6f3b445d8847fc92cae307ffba6424c98610598cd8d7f8bb
00011  5a8639fc7de259a8e872b17e06598bc0266fbf49ba56fd0cbc7fba1c6c0ee092
00012  f5f1222486add3970e2108ed6deb52790017da067b35e83ef903d7d271e8599d
00013  bffe0ee949d2bfbdc4fa948b1d96cbe461e29717925e4892f798c84c9191f043
00014  b8e90cd292e4147f0aa860fe4e6488e9350b85fee164a3077c262bb98e42c6e6
00015  5c4e636033ef387ed31e4753ec5da22903fa4fde2b26eb9cf97782b83ad492d1
00016  0c48d78b06dde82fda0cf99d306682d35ffdebaf597a677ceb772f04fa7995cf
00017  8a397ff44115394b9311a4464cc91f47a365fe4ff4efde286da7ad8612013152
00018  455b3b9e74d0bdd830a1527af673c24f739c865d371c234a0b49261f33e4ae32
00019  606594ae602b932d91826e3be0a802ec1c02f4e00e28fe013dac94c51e3c9e64
00020  fb2559dde8452845e484b586569742fb3bc8435d86fb07e1f53592d96f5270d4

The local Drizzle journal still contains only its two foundational generated migrations. The handwritten chain is not journaled, as disclosed in decision #75. No history row was fabricated. The disposable database is data-empty and its normalized Inventory/Returns schema and ACL dump matches the local database exactly.

Authoritative live shape

Local and disposable catalogs agree on:

Inventory base tables:          26
Base-table columns:             362
Views:                            1
CHECK constraints:              62
Foreign keys:                  118
Primary keys:                   26
UNIQUE constraints:             13
Indexes:                        137
Policies:                        38
Non-internal Inventory triggers: 31
RLS-enabled Inventory tables:    26/26

The 137th index is the new fulfillment source-identity guard.

All ten core ruled triggers are enabled:

  • Operational guards for stock, stock lot, reservation, movement, movement line, and average cost.
  • Append-only triggers on movement header and line.
  • Deferred exact-cardinality triggers on movement header and line.

The complete live trigger inventory contains 31 enabled non-internal Inventory triggers.

Fulfillment, movement, and reservation integrity

Verified:

  • Full and near-full fulfillment no longer violates reserved_qty <= on_hand_qty.
  • Failures after reservation pre-decrement roll back the reservation transition and cached quantity.
  • Same-key fulfillment retry returns the original movement.
  • Changed-key retry is rejected without a second stock effect.
  • Direct duplicate fulfillment source insertion is rejected structurally.
  • Reservation retry is hash-idempotent.
  • Oversubscription is rejected under a stock-row lock.
  • Reservation transitions and cached reserved_qty update atomically.
  • NaN, positive infinity, negative infinity, negative values, zero movement quantities, and invalid reserved/on-hand relationships are rejected.
  • Complete movement headers require their exact positive deferred child count.
  • Zero-line, partial-line, and late-child complete movement artifacts are rejected.
  • Movement headers and lines remain append-only.

The historical population remains intact:

legacy_unverified headers: 1,892
movement lines:            1,158
zero-line headers:         1,194
one-line headers:            468
three-line headers:          230
other cardinalities:           0

No key, hash, child row, or provenance was fabricated for historical headers.

After all focused tests and rollback probes:

complete movement rows:  0
verifier/test artifacts: 0
stock reservations:      0

Returns protection

Catalog and function inspection confirmed:

  • trg_return_receipt_line_post_and_cap is AFTER INSERT.
  • Outer RLS WITH CHECK, row constraints, uniqueness, and immediate composite FKs precede the privileged posting trigger.
  • The persisted receipt is locked first; tenant/site/source facts are derived from locked authoritative parents.
  • Tenant spoofing and invalid parent relationships use generic 42501 command-context errors before inventory effects.
  • Actor attribution is validated against active same-tenant user, agent, or service-account rows.
  • Movement and movement-line links are written back through narrow owner-only columns.
  • Exact owner policies exist for receipt/header/authorization reads and locks plus receipt-line SELECT/UPDATE visibility.
  • Owner table and column grants are limited to the reads, row locks, capacity increment, and derived link writes required by the wrapper.
  • No ordinary role can execute the Returns definer or private Inventory posting primitive.

Authority and ACL closure

All protected roles are:

NOLOGIN
NOINHERIT
NOSUPERUSER
NOCREATEDB
NOCREATEROLE
NOREPLICATION
NOBYPASSRLS

The exact role graph contains three administrative membership rows: postgres, granted by supabase_admin, with admin_option=true, inherit_option=false, and set_option=false. No ordinary or authenticator-reachable role is a member.

Ordinary authenticated privileges are:

inventory.stock:
  SELECT
  UPDATE(reorder_point, reorder_qty, min_qty, max_qty)

inventory.stock_reservation:
  SELECT only

inventory.stock_movement:
  SELECT only

inventory.stock_movement_line:
  SELECT only

Ordinary INSERT/DELETE and operational-column UPDATE privileges are absent. avg_cost_cents remains outside ordinary item-variant INSERT/UPDATE grants.

Default privileges give future postgres-created Inventory tables authenticated SELECT only. Global postgres-created function defaults no longer grant PUBLIC execution. Every Inventory function now yields zero inherited execution to inventory_command_executor.

Migration 00016 preflight and source authority

The correction migration locks Orders source rows before Inventory reservation/stock rows, using:

  • SHARE on orders.order_header and orders.order_line.
  • ACCESS EXCLUSIVE on inventory.stock_reservation and inventory.stock.

Under those locks it reruns:

  • Active-reservation stock-grain existence.
  • Bidirectional reservation aggregate versus cached reserved_qty.
  • Numeric-domain validation.
  • Authoritative active Orders header/line tenant, site, variant, source, reciprocal reservation-link, soft-delete, and source-line validation.

Local and disposable sweeps returned zero failures. The private reserve routine remains ungranted pending a source-specific authoritative wrapper.

Transfer absence and reciprocal-lock claim

Verified zero:

  • Transfer tables.
  • Transfer wrappers or functions.
  • Transfer executor grants.
  • Transfer reservation rows.
  • Transfer movement rows.
  • Placeholder Transfer data.

The private primitive rejects Transfer attribution. The reciprocal-lock test is correctly named and documented only as a canonical ordered-lock pattern; it is not claimed as production Transfer behavior. A real reciprocal multi-grain concurrency test remains correctly deferred until Transfer introduces such a wrapper.

Drizzle, tests, and documentation

Commands run included:

npx tsc --noEmit -p packages/db/tsconfig.json --pretty false
npx tsc --noEmit -p apps/api/tsconfig.json --pretty false
DATABASE_URL=... npm run drift-check --workspace=@vrida/db
npx jest inventory/__tests__/inventory-core-write-protection.spec.ts --runInBand --forceExit

Results:

  • Database package typecheck: PASS.
  • Drift check: PASS.
  • Focused core suite after the final correction: 24/24 PASS.
  • No Inventory Core TypeScript errors.
  • API no-emit check reports only three previously disclosed errors outside the new core suite:
inventory-schema.spec.ts:748   stockLotId used before assignment
inventory-schema.spec.ts:1095  siteId used before assignment
pricing-schema.spec.ts:321     ruleId used before assignment

Affected Drizzle Inventory, Returns, Orders, POS, and Identity definitions match the live columns, composite FKs, indexes, RLS policies, and source-module constraints inspected. Normalized local/disposable inventory and returns dumps are identical.

Authoritative Markdown and generated raw copies match byte-for-byte. Rendered HTML now records migrations 00016–00020, the 26/362/1 shape, and 137 indexes. The required docs viewer rebuild completed successfully after the final correction.

Final verdict: CLEAN

Final-verifier disposition totals: 2 findings accepted and fixed in this build (1 BLOCKER, 1 MINOR); 0 rejected, 0 deferred, 0 unresolved. The final verifier independently reproduced each pre-fix condition in rollback-only transactions, then independently proved each additive correction. Combined with the first report, total verifier dispositions are 12 accepted: 10 from the first pass plus 2 from the final pass.

76. Stock Transfer — Schema-Only Build and Lock

Built 2026-07-16 against governing evidence commit ef767623d8166daeba775d4328a1de896af3a2ed. The approved design of record is /Users/cnu/Downloads/vrida-transfer-design-RULED-FINAL-2026-07-16.md, independently design-verified CLEAN by /root/transfer_final_reverifier. This entry records the schema-only build. No Transfer service, API, UI, worker, scheduler, agent runtime, notification runtime, purchasing workflow, or module-to-module application wiring was created.

Governing runbook and authorization

The current source runbook, docs/database/SCHEMA_DESIGN_RUNBOOK.md, governed this pass:

  • Section 2.6 authorized the column-for-column Drizzle build, hand-written timestamped migrations, local application, and live verification.
  • Section 2.1a supplied the current-repository reconciliation standard for reopening previously locked schema surfaces; Section 4 item G and Section 6 items 8 and 13 require companion and forward-seam touches to be explicit rather than silently bundled.
  • Section 2.7 and Section 6 item 1a require a separate, evidenced post-build verifier whose actual report is retained below.
  • Section 2.8 and Section 6 items 3–14 require the current documentation fan-out and rebuilt/deployed viewer.
  • Section 4 requires the complete A–P+T+U read-only audit over the built result.
  • Section 6 requires zero remaining FAILs, exact documentation/count reconciliation, current OPEN_ITEMS triggers, retained Design-Phase Integrity blocks, and a CLEAN independent verdict before lock.

The approved design supplied the explicit build authorization and exact companion scope. The companion changes are limited to Transfer anti-stranding guards on multi_loc.site, inventory.inventory_location, and inventory.lot, plus already-required composite-parent uniqueness prerequisites. No intercompany, notification, approval, replenishment, or runtime behavior was added.

Final built shape

Table Columns CHECKs FKs Table triggers
inventory.transfer 26 12 9 3
inventory.transfer_line 21 9 8 2
inventory.transfer_reconciliation_event 16 7 3 3
Companion: multi_loc.site — — — 1
Companion: inventory.inventory_location — — — 1
Companion: inventory.lot — — — 1
Transfer total 63 28 20 11

The resulting Inventory catalog is 29 base tables / 425 base-table columns / 1 view / 90 CHECKs / 138 FKs / 29 PKs / 19 UNIQUE constraints / 164 indexes / 46 policies / 41 non-internal triggers, with RLS enabled on all 29 base tables.

Migrations and reproducibility

The build is an additive, collision-free, lexically ordered migration set:

20260720000021_inventory_transfer.sql
20260720000022_inventory_transfer_grouped_lot_guard.sql
20260720000023_inventory_transfer_test_identity_grants.sql
20260720000024_inventory_transfer_lock_and_draft_edit.sql
20260720000025_inventory_transfer_verifier_corrections.sql
20260720000026_inventory_transfer_finalization_retry_fix.sql

Verified SHA-256:

00021  f6a55e8611e16e05f33f6363e0bf8ebb48b48b75d97266c9b235786c2d403eca
00022  5803825dbfb0ad2dcccb13734c9a6501c56cf136c6e3880416803176816c6101
00023  7fcb647221aa52cd96e12e9b7b2e572fb0b494b94495e73ea586660f0bccf006
00024  366ccbcac4cd724141b5204d515c292446bbcfabbc65daabea61ab4c2077aab7
00025  549a3d2052f4a3819699485b4b4cb8c665cd60c2b0f68fc65a231fa09df08618
00026  defb5d50a15a89e7a5a09f13862d2633490184ccb6d206b59f5369b7877ae182

The repository migration directory contains 131 unique SQL basenames; the lexical tail is 00021 through 00026. The local Drizzle journal still contains only the two foundational generated migrations. As with Inventory Core decision #75, the handwritten migration chain is not represented there and no history row was fabricated.

A fresh disposable Supabase PostgreSQL 17.6 database applied all 131 repository migrations through 00026 using the checked-in lexical psql -X -v ON_ERROR_STOP=1 -f runner from .github/workflows/db-drift-check.yml (workflow SHA-256 de5bb9fbfa3631ef529a7cac388d007dc0c34b427f92c82d5212e9284d86e37e). The complete 131-file SHA manifest hash was f6a117d8b4fd71544ead30e67a59c643cbc15df9eff4237adf5858a3486a5a31. A final verifier correctly found that the workflow did not originally encode the already-known historical duplicate-policy handling for 20260716000000_agents_module_new_schema.sql. The workflow now uses the same Supabase PostgreSQL 17.6 image as local verification, preserves that image's required default bootstrap user, pins that historical file's exact source hash, and deterministically omits only its second duplicate policy block while keeping the migration bytes unchanged. Every other migration is executed unchanged. The full checked-in workflow path completed without SQL errors and the fresh database drift check passed. The fresh lexical-runner database correctly had no drizzle.__drizzle_migrations relation; no history was fabricated there or locally.

Normalized local-versus-disposable parity was exact for:

  • Inventory, Multi-Location, Platform, and Identity schema DDL;
  • function bodies and configuration;
  • object, column, routine, and default ACLs;
  • schema/relation/routine ownership;
  • protected and ordinary role attributes and memberships;
  • RLS and table-ACL state.

The normalized four-schema dump was 6,718 lines on both databases with SHA-256 3e24a0c10e6e2e091f55cd19026eac6d306532f38a02642a8ed7aed7f0ed2ea0. Function bodies, ACL/default ACL state, ownership, protected and ordinary role attributes/memberships, RLS, and table ACLs also matched exactly. The disposable container and anonymous volume were destroyed after verification. The current local database has no unexplained schema state relative to the complete migration chain.

Built lifecycle, lot, movement, and cost contract

  • v1 has one atomic shipment per Transfer. Every effective line ships its full approved/reserved quantity. Multiple shipment batches require separate transfers; partial receipts remain supported.
  • transfer_line.lot_id pins zero or one durable inventory.lot. Quantities spanning multiple lots use multiple lines. Duplicate variant/location/lot lines remain valid and are isolated by line UUID and line number.
  • Approval creates exactly one aggregate Inventory reservation per effective line. The lot is a physical allocation identity, not a persistent lot-specific reservation.
  • Shipment locks and validates the deduplicated exact source stock-lot grains, aggregates repeated same-lot demand, fails the whole transaction on shortage, fulfills reservations, decrements source stock and stock-lot, posts one complete outbound movement header with exactly one child per line, and stores that immutable child UUID on the Transfer line.
  • The deterministic outbound key is inventory:transfer:ship:<transfer-line-id>. Built Inventory uniqueness on (tenant_id,idempotency_key) and the Transfer partial source unique on (tenant_id,source_id) for source_type='transfer_line_shipment' make the posting retry-safe and prevent a second complete posting for the same line.
  • A shipment retry locks the exact graph, validates reservation identity/status/key/hash and the complete movement header/child source, site, type, timestamp, actor, variant, locations, lot, quantity, cost fields, request hash, and exact one-child cardinality, then resolves the original IDs. Changed evidence is rejected.
  • A reconciliation event uses caller key uniqueness only to identify the event. The wrapper serializes (tenant,idempotency_key) ownership, rechecks after graph locking, returns the existing event only for the exact same payload, and rejects changed payloads.
  • The inbound key is inventory:transfer:reconcile:<reconciliation-event-id>, with a second Transfer source-identity unique on (tenant_id,source_id) for complete reconciliation movements.
  • Receipt dereferences the immutable outbound movement-line FK and copies its immutable unit_cost_cents; correlation_id is not used as cost authority. Duplicate same-variant lines cannot cross-resolve because each line owns a unique exact outbound child pointer.
  • Clean received quantity and damaged/restock quantity credit destination stock and the exact destination stock-lot grain using the same pinned lot. Missing and damaged/non-restock quantities create no destination stock or stock-lot credit.
  • Integer-cent cost uses cumulative proportional allocation from the immutable outbound line: each event receives the difference between the newly entitled cumulative credited cost and the cost already posted. The final qualifying credit receives the exact residual, so fractional partial receipts reconcile exactly without revaluing from a later average cost.
  • Outbound headers with posting_integrity='legacy_unverified' are rejected as Transfer cost provenance.

Authority, locks, RLS, and grants

Agents may create and edit drafts only. Approval, cancellation, shipment, reconciliation, and finalization are human-only. Every consequential wrapper derives tenant, actor, sites, locations, variant, lot, quantities, timestamps, source identity, keys, disposition, and cost provenance from locked rows. No wrapper accepts tenant, actor, cost, source type, movement key, or provenance as trusted caller facts.

Every protected graph command takes a per-Transfer advisory transaction lock and then uses the canonical PostgreSQL row-lock order:

  1. source and destination sites in canonical UUID order;
  2. source and destination inventory locations in canonical UUID order;
  3. referenced lots in canonical UUID order;
  4. Transfer header;
  5. Transfer lines in canonical UUID order;
  6. reservations in canonical UUID order;
  7. one deduplicated union of affected stock grains;
  8. one deduplicated union of affected stock-lot grains.

The site/location/lot soft-delete guards lock all matching nonterminal Transfer headers/lines in canonical order and do not acquire an earlier lock class after a later class. Destination status may change after shipment, preserving receipt continuity, but soft deletion remains blocked until the Transfer is terminal.

All three Transfer tables are RLS-enabled. authenticated receives tenant-scoped SELECT only; protected operational Inventory and Transfer tables expose no ordinary table-level INSERT/UPDATE/DELETE. Existing stock planning UPDATE remains limited to reorder_point, reorder_qty, min_qty, and max_qty.

The eight outer Transfer wrappers plus lock_transfer_graph_protected and transfer_command_context are owned by inventory_invariant_owner, are SECURITY DEFINER, and have fixed search_path=pg_catalog. authenticated, authenticator, service_role, inventory_command_executor, anon, consumer_authenticated, and agent_reader each have zero executable Transfer functions. The controlled postgres test identity is the only outer-wrapper test path. There is no runtime Transfer credential/session gateway and no runtime EXECUTE grant.

Builder verification

Final builder results:

Transfer focused suite:                    18/18 PASS
Affected Inventory/Orders/Returns/
Receiving/Multi-Location regressions:     245/245 PASS
Complete API suite, file-isolated:      1,426/1,426 PASS (57/57 suites)
packages/db no-emit typecheck:             PASS
API production build:                     PASS
Drizzle/live drift check:                  PASS
git diff --check:                          rerun after final docs generation

A monolithic one-process Jest invocation passed 49 suites and 1,307 tests before suite-local database pools exhausted PostgreSQL's connection limit, causing eight cascading suites to fail with remaining connection slots are reserved. After the finalization-retry correction, every one of the 57 suites passed again in its own forced-exit Jest process, now totaling 1,426 tests, including all eight affected by the earlier connection-slot cascade. API no-emit still reports only the three pre-existing unrelated definite-assignment errors in inventory-schema.spec.ts (two) and pricing-schema.spec.ts (one); the production build is green and there are no Transfer TypeScript errors.

Live post-test sweeps returned zero:

  • Transfer headers, lines, reconciliation events, reservations, and movements;
  • complete movement cardinality mismatches;
  • stock, stock-lot, reservation, or movement-line NaN/infinity values;
  • reservation-cache reconciliation mismatches;
  • ordinary/runtime DML paths on protected Inventory/Transfer tables;
  • ordinary/runtime EXECUTE paths to Transfer wrappers or helpers.

Design-Phase Integrity blocks retained

Block 1 — v1→v2 delta. Phase 1 supplied no usable current Transfer table shape. This build adds exactly transfer 0→26, transfer_line 0→21, and transfer_reconciliation_event 0→16, for +3 tables/+63 columns.

Block 2 — consolidation. Three tables are the minimum durable shape: the header owns lifecycle, the line owns independently reserved/shipped/costed/lot-pinned/reconciled quantities, and the append-only event owns idempotent physical receipt/damage/missing evidence. Events cannot collapse into movements because missing and non-restocked damage intentionally have no movement. Lines cannot be JSONB because their FKs, reservation/outbound pointers, lot identity, and progressive reconciliation are structural.

Block 3 — fate. The three ruled tables are BUILT exactly. Multi-shipment events remain DEFERRED until one business Transfer must ship in multiple physical batches. Split-lot allocation remains DEFERRED until one line must allocate across multiple lots. Both limitations are explicit and do not remove a Phase 1 capability.

Block 4 — dependencies. Inventory Core primitives, roles, completeness, idempotency, source uniques, and lock mechanisms are reused. Required parent uniques and site/location/lot anti-stranding companions are built. The trusted non-spoofable runtime credential/session gateway remains DEPENDENCY-BLOCKED service-phase work; no wrapper EXECUTE may be activated before separate design, verification, and architect authorization.

Section 4 self-audit

Item Result Built evidence
A Column drift/count PASS Exact 26+21+16=63 live and Drizzle
B RLS PASS Three authenticated SELECT + three owner policies; 29/29 Inventory tables RLS-enabled
C NULL tenant uniqueness PASS All Transfer tenant IDs NOT NULL
D Soft-delete uniques PASS Transfer number unique is partial on nondeleted rows
E Partial-index enums PASS Every predicate uses a valid CHECK value
F CHECK completeness PASS Exact 12+9+7=28; lifecycle, finite, rollup, disposition, attribution exercised
G Forward/composite FKs PASS Exact 20; tenant-scoped data parents use composite keys where applicable
H Cross-module consistency PASS Live legal entity, site, location, variant, lot, reservation, movement-line, actor, and tenant targets verified
I Money derivation PASS Immutable outbound child cost plus cumulative proportional integer-cent allocation
J JSONB shape PASS decision_provenance convention retained
K Tenant indexes PASS Tenant-leading indexes on all Transfer tables
L Query indexes PASS Status/site/header/line/lot/idempotency/pointer/source paths present
M Conditional consistency PASS Status evidence, counters, disposition, lot, reservation, and outbound pointers enforced
N Locked decisions PASS One shipment, partial receipts, one lot per line, human consequential authority, asymmetric lifecycle
O Non-RLS access PASS Narrow owner policies/grants; no runtime wrapper execution
P Rationale PASS Non-obvious choices and guards retained in the ruled design and this entry
T Trigger audit PASS All 11 enabled; event timing, append-only, evidence guards, side effects, and reverse-free lifecycle locks exercised
U Integrity blocks PASS Blocks 1–4 retained above and deferrals have concrete triggers

No self-audit FAIL or unresolved schema GAP remains. The only remaining architect/service decision is the concrete non-spoofable credential/session gateway required before any runtime role can execute Transfer commands.

First independent artifact audit — report pasted verbatim

Verifier identity/session ID: /root/transfer_artifact_audit

READ-ONLY AUDIT VERDICT: NOT CLEAN / not lock-ready. Live read-only catalog confirms 3 tables / 63 cols / 28 CHECKs / 20 FKs and runtime roles lack wrapper EXECUTE, but material wrapper/trigger defects remain.

  1. BLOCKER — concurrent same-key reconciliation is not retry-safe and the authored test should deterministically fail/cascade. record_transfer_reconciliation_protected checks the event key only before any serialization (20260720000021...sql:1793-1808), then locks site/location/lot/header/line (1818-1830) and inserts without rechecking (1874-1886). Two callers both see no row; caller 2 waits, then hits tenant/key UNIQUE instead of returning caller 1’s event. Test expects equal IDs at transfer-schema.spec.ts:794-806; failure occurs there and leaves destination site/location inactive, so later tests likely cascade. Must re-read/compare the key under the serialized lock (or otherwise serialize key ownership) before insert.

  2. MAJOR — ruled global lock order is not implemented by all wrappers. Draft-line upsert locks transfer first (...00021.sql:1277-1280) then locations (1284-1286) and lot (1308-1309), inverse of lifecycle→header order; this can deadlock with location/lot soft-delete guards (they hold lifecycle row then seek transfer/line). Approval locks sites/locations/lots/header/lines (1393-1415) but then acquires stock per line (1472-1478) and never FOR UPDATEs source stock_lot; it does not prelock a deduped canonical stock/stock-lot union as RULED §8/§9.1 requires. Cancellation locks header (1522-1525), then lines in line UUID order (1546-1550), while transition_reservation_protected locks each reservation then its stock; it does not lock all reservations in reservation UUID order and all stock grains in canonical union order, so multi-line cancellations can invert with other protected paths. Soft-delete guard uses unordered EXISTS ... FOR UPDATE (1117-1145), not all matching transfers/lines in UUID order; paired with draft-line inverse order this exposes 40P01 risk. Shipment’s patched body in 00024:214-270 follows the class order. Reconciliation follows site→location→lot→header→line→stock→stock_lot for its single line (00021:1818-1830, primitive 809-899). Finalization header→lines (1913-1930) is a valid subset.

  3. MAJOR — trigger guards do not enforce the ruled monotonic/pointer/evidence immutability. guard_transfer_line_write protects only structural fields after draft (993-1041, especially 1019-1031); it allows changing stock_reservation_id, rewriting/clearing outbound_movement_line_id, decreasing/increasing shipped/received/damaged/missing counters subject only to CHECKs, and changing pinned disposition. This contradicts RULED 921-948 (monotonic quantities, immutable reservation/outbound pointer, one shipment, pinned disposition). guard_transfer_write (935-969) protects a small subset and only actor changes for approval/shipment; it does not freeze approved/shipped/terminal timestamps, terminal actor, cancellation evidence, or consequential same-status rewrites. No test attacks invariant-owner pointer/counter/timestamp tampering.

  4. MAJOR — approval and shipment retry validation is weaker than the ruled exact structural retry. Approval retry (1417-1424) checks only that effective lines have a nonnull reservation pointer; it does not validate source type/id/line, quantity, status, deterministic key, or request hash. Shipment retry (00024:272-293) checks source type/id/correlation/key/qty/variant/lot only; it omits movement_type/source_module/site, posting_integrity, expected child count, exact from/to location, unit cost/cost impact, request hash, performed actor/event time, and exactly-one-child validation required by RULED 693-708, 722-748, 797-827. Atomic movement/reservation source-unique indexes exist, but retry evidence is not exact.

  5. MAJOR — Drizzle/live parity is incomplete. SQL adds stock_reservation_transfer_source_line_unique and the two Transfer movement source uniques (00021:306-316; live-confirmed), but packages/db/src/schema/inventory/stock.ts models only reservation idempotency at 638-647 and only reservation-fulfillment movement source uniqueness at 422-434. All 3 new Transfer partial unique indexes are absent. transfer.ts itself models the 63 columns/28 CHECK/20 FK table shape and is exported by inventory/index.ts:10 and root schema barrel.

  6. MAJOR — required test matrix is far from complete (16 tests only; titles at transfer-schema.spec.ts:278,321,354,372,686,777,900,919,960,994,1050,1119,1175,1205,1254,1344). Missing direct tests for exact index inventory; RLS/policy/table ACL/default ACL/role closure; direct DML on all 3 tables/operations; private 19-arg primitive unreachability and non-Transfer wrapper attribution; incomplete/late-child Transfer movements; changed movement key/source unique; ordinary deterministic-key preemption; approval retry exactness; shipment retry cost/hash/location/child exactness; another-tenant and wrong-variant/site/location lots; non-restock damage no-credit; finalize-before-complete; terminal soft-delete allowance; agent denial for ship/reconcile/finalize/cancel; line-site/location/lot immutability after approval; pointer/counter monotonic tamper; lifecycle soft-delete races; reciprocal multi-grain cancellation/draft-edit races; migration-runner/fresh-db/Drizzle drift evidence. Existing same-key race test is defective as finding 1.

  7. MAJOR — preflight in migration is not authorization-complete. 00021:20-61 only checks table absence, role existence, finite stock/lot/reservation and reservation-cache reconciliation. It does not assert the documented Inventory Core function signatures/triggers/policies/ACL/default privileges, ordinary-write denial, Transfer-source unreachability, orphan reservation absence, movement-line non-finite values, or parent-key existence before blindly adding constraints at 64-68.

  8. MODERATE — wrapper queries frequently omit explicit tenant predicates despite RULED 680-689 requiring every definer query to carry them (e.g. draft site lock 1223-1225, line location/lot locks 1284-1286,1309, approval discovery locks 1393-1408, cancellation line scans 1541-1550). UUIDs are globally unique and later validations reduce integrity risk, but this is still a design/DoS-locking discrepancy.

  9. MODERATE — agent draft provenance is misrecorded. Draft context allows any active actor (transfer_command_context(false) at 1206-1222, 1254-1276), but both header and line inserts hardcode automation_source='human' (1243-1249, 1319-1327). RULED allows agent drafts and requires provenance; no test covers agent draft behavior.

  10. MINOR parity/name drift — design names stock_reservation_transfer_line_source_unique with predicate source_line_id IS NOT NULL; migration creates stock_reservation_transfer_source_line_unique and predicates only source_type='transfer' (306-308). Structural uniqueness is effectively similar because NULLs remain distinct and guard requires line ID, but it is not the exact ruled definition.

Positive evidence: packages/db no-emit typecheck PASS. apps/api no-emit has only the 3 known unrelated errors (inventory-schema lines 751/1098, pricing line321), no Transfer TS errors. Live read-only checks: exact table shape present; the 3 source-unique indexes exist; authenticated/authenticator/service_role/inventory_command_executor/anon/consumer_authenticated/agent_reader all have zero EXECUTE on the 8 dormant wrappers; Transfer table grants are authenticated SELECT only and invariant owner narrow write grants. I did not edit files or mutate DB.

First audit dispositions

# Severity Disposition
1 BLOCKER Accepted and fixed. 00025 serializes tenant/key ownership, rechecks after graph locking, compares the exact payload, and the suite now attacks eight simultaneous same-key callers.
2 MAJOR Accepted and fixed. lock_transfer_graph_protected plus all wrappers and lifecycle guards now implement advisory serialization and canonical lifecycle→header→lines→reservations→stock→stock-lot locking.
3 MAJOR Accepted and fixed. Header/line guards now freeze consequential evidence, enforce monotonic counters and immutable reservation/outbound pointers, and are directly attacked through invariant-owner tamper tests.
4 MAJOR Accepted and fixed. Approval and shipment retries now validate exact reservation, key/hash, complete movement header, exact child, actor/time, locations, lot, cost, and source evidence.
5 MAJOR Accepted and fixed. All three Transfer source-identity partial uniques are modeled in stock.ts; typecheck and drift pass.
6 MAJOR Accepted and fixed. The focused suite expanded to 17 high-density tests, including direct catalog/ACL/default-ACL checks, runtime/private path denial, failure injection, exact retry/tamper checks, lifecycle, lot, atomicity, concurrency, cost, and cleanup. The full affected and API regressions are also green.
7 MAJOR Accepted and fixed. 00025 adds a strict closing preflight for Inventory Core signatures, triggers, policies, ACL/default ACL, ordinary-write denial, source isolation, numeric sweeps, reconciliation, parent keys, and index prerequisites. Because 00021–00024 had already been applied, this was additive rather than rewriting applied migration bytes.
8 MODERATE Accepted and fixed. Definer queries now carry explicit tenant predicates derived from the locked graph/context.
9 MODERATE Accepted and fixed. Same-tenant active agents produce automation_source='agent' drafts; all consequential commands reject agents.
10 MINOR Accepted as equivalent live naming/predicate drift; no schema rewrite. The live migration name is authoritative. PostgreSQL unique indexes already treat NULL source-line IDs as distinct, and the protected Transfer reservation guard requires nonnull source_line_id, so the narrower predicate is structurally equivalent for executable Transfer rows. Drizzle now matches the live name and predicate exactly.

Disposition totals: 10 accepted; 9 corrected by additive migration/Drizzle/test changes; 1 accepted as structurally equivalent with the live name retained; 0 rejected; 0 deferred; 0 unresolved.

Final independent post-build verification

The first fresh-context final verifier correctly returned NOT CLEAN. Its report is retained verbatim below, followed by the disposition. Schema lock remains pending until a separate fresh-context re-verification returns CLEAN.

Final Independent Post-Build Verification — Stock Transfer

Verifier identity / canonical task name: /root/transfer_final_build_verifier Session ID: Not exposed by the collaboration runtime Evidence HEAD: ef767623d8166daeba775d4328a1de896af3a2ed Mode: Fresh-context, read-only verification. I edited no files, committed nothing, pushed nothing, and made no persistent database mutation. The behavioral reproduction ran inside a transaction that was rolled back. No disposable database was created.

Final verdict: NOT CLEAN

The corrected build still has one reproducible MAJOR idempotency defect. A legitimate Transfer containing a fully cancelled line can finalize successfully, but the exact same finalization retry fails. Stock Transfer must not be schema-locked until this is corrected and independently reverified.

Evidence basis

  • Repository HEAD exactly matched the requested commit. The Transfer build itself is an uncommitted worktree layered on that HEAD.
  • Read the complete ruled design, current schema runbook, conventions, Decision #76, migrations 20260720000021–00025, Transfer Drizzle definitions, and the 17-test Transfer suite.
  • Verified migration SHA-256 values exactly match Decision #76.
  • Verified 130 unique SQL migration basenames with lexical tail 00021 through 00025.
  • Inspected PostgreSQL 17.6 live catalogs at the supplied local database.
  • Independently confirmed:
    • 3 Transfer tables / 63 columns / 28 CHECKs / 20 FKs / 11 Transfer and companion triggers.
    • Inventory totals of 29 base tables / 425 base-table columns.
    • All three Transfer source partial unique indexes exist, are valid, and match Drizzle.
    • All Transfer triggers are enabled.
    • All three Transfer tables have RLS enabled and authenticated tenant-scoped SELECT policies.
    • authenticated, authenticator, service_role, inventory_command_executor, anon, consumer_authenticated, and agent_reader have zero effective EXECUTE on Transfer wrappers/helpers and the private reservation/posting primitives.
    • Those roles have no direct INSERT/UPDATE/DELETE on Transfer or protected operational Inventory tables.
    • inventory_invariant_owner is NOLOGIN, NOINHERIT, non-superuser, and non-BYPASSRLS.
    • Cross-schema site/location/lot lock permissions and owner RLS policies are present; lifecycle/business columns remain non-updatable.
    • No non-Transfer repository routine was found that can emit Transfer reservation or movement attribution.

Findings

1. MAJOR — Exact finalization retry fails when the Transfer contains a fully cancelled line

The first finalization and its retry apply inconsistent rules.

The initial path in finalize_transfer_receipt_protected() permits a fully cancelled line without reservation or outbound pointers. At 20260720000025_inventory_transfer_verifier_corrections.sql:2663-2682, pointer requirements apply only when:

tl.cancelled_qty < tl.requested_qty

That is correct: a fully cancelled line is intentionally excluded from approval and shipment and therefore legitimately has no reservation or outbound movement.

The already-received retry path at lines 2636-2653 instead unconditionally rejects any line whose reservation or outbound pointer is null:

OR tl.outbound_movement_line_id IS NULL
OR tl.stock_reservation_id IS NULL

It does not exclude fully cancelled lines.

I reproduced this against the corrected live build in a rollback-only transaction:

  1. Created a Transfer with two lines:
    • one effective line;
    • one line with requested_qty=1, cancelled_qty=1.
  2. Approved and shipped the Transfer.
  3. Fully reconciled the effective line.
  4. Finalized successfully; header status became received.
  5. Confirmed the fully cancelled line correctly had null reservation and outbound pointers.
  6. Retried finalization with the same human actor and unchanged evidence.

The exact retry failed with:

changed or incomplete finalization retry evidence

This violates the ruled exact-retry/response-loss contract. The operation has already committed successfully, but a caller retry receives an error instead of the original immutable result.

Required correction: add an additive migration replacing the retry predicate so reservation/outbound-pointer requirements apply only to effective lines, matching the initial finalization predicate. Preserve the existing actor, terminal timestamp, cancellation-evidence, and rollup validations. Add a regression test that finalizes and retries a Transfer containing both an effective line and a fully cancelled line.

The current 17-test suite does not cover this case. Its “exact retry after finalization” test uses a Transfer with no fully cancelled lines.

Section 4 A–P + T + U result

  • PASS: A, B, C, D, E, F, G, H, I, J, K, L, O, P, T, U.
  • FAIL: M and N. The conditional finalization evidence contract and locked exact-retry decision are inconsistent for fully cancelled lines.

Therefore the Section 4 audit is not clean overall.

Confirmed corrected-build properties

Apart from the finding above, the inspected build correctly establishes:

  • exact table, column, CHECK, FK, trigger, index, and RLS shape;
  • migration/Drizzle/live parity for the three Transfer source partial uniques;
  • runtime-dormant wrappers despite spoofable tenant/actor GUCs;
  • human-only consequential commands and agent draft provenance;
  • canonical graph locking in migration 00025;
  • grouped stock and lot demand checks;
  • permanent reservation and movement source identities;
  • exact outbound child pointers and immutable outbound cost authority;
  • clean/restock credit versus missing/non-restock no-credit behavior;
  • cumulative proportional integer-cent allocation;
  • deterministic same-key reconciliation serialization;
  • append-only reconciliation events and movement ledgers.

Residual notes

  • I did not independently rerun the full 130-migration disposable-database runner before the instruction to finalize. No disposable database was created. Static migration ordering, file hashes, local catalog state, and Drizzle/live parity were independently checked.
  • The current git diff --check is not clean because the generated raw Decision viewer copy contains trailing Markdown whitespace. This is not the cause of the schema verdict, but the builder’s “rerun after final docs generation” line is not presently demonstrated.
  • Current Inventory/Transfer count overrides and the expanded column/index/trigger documentation reconcile to 29/425 and 3/63/28/20/11. Historical narratives remain in-file but are explicitly marked superseded.

Final verdict: NOT CLEAN — one reproducible MAJOR finding remains.

First final-verifier disposition

# Severity Disposition
1 MAJOR Accepted and fixed. Additive migration 20260720000026_inventory_transfer_finalization_retry_fix.sql makes the already-received retry predicate identical to the initial finalization predicate: all lines must reconcile to shipped quantity, while reservation/outbound pointers and full-effective-quantity shipment evidence are required only when cancelled_qty < requested_qty. The migration preserves actor, received timestamp, cancellation-evidence, rollup, owner, fixed search path, runtime EXECUTE denial, and migration-test-only execution. The focused suite now has an 18th regression that approves, ships, reconciles, finalizes, and exactly retries a Transfer containing both an effective line and a fully cancelled line; it also proves the cancelled line retains null reservation/outbound pointers and zero shipped quantity.

Disposition totals for this report: 1 accepted and fixed; 0 rejected; 0 deferred; 0 unresolved.

The first final verifier's NOT CLEAN verdict remains authoritative for the state it inspected. A separate fresh-context verifier must judge migration 00026, the 18-test suite, the rebuilt documentation, and the final live/fresh-database evidence before Stock Transfer may be schema-locked.

Second fresh-context final verifier — report pasted verbatim

Final Independent Post-Build Verification — Stock Transfer

Verifier identity / canonical task name: /root/transfer_final_clean_verifier Session ID: 019f6bcd-727b-7481-8397-2aca6336bdd1 Evidence HEAD: ef767623d8166daeba775d4328a1de896af3a2ed Mode: Fresh-context verification using only the ruled-final design, current repository, and local PostgreSQL. No files were edited, no migrations were applied, and all bespoke behavioral probes were rollback-only. The focused test suite cleaned its fixtures.

Final verdict: NOT CLEAN

The corrected live schema and Transfer behavior passed the substantive integrity, authority, lifecycle, concurrency, lot, movement, valuation, reconciliation, and 00026 finalization-retry attacks. However, one MAJOR migration-reproducibility finding and one MINOR current-source inconsistency remain unresolved.

There are zero unresolved schema-behavior BLOCKERs. The verdict is NOT CLEAN because the repository’s documented normal migration runner cannot reproduce the stated 131-file fresh build without an unencoded source-stream workaround.

Findings

1. MAJOR — The documented fresh build is not reproducible by the repository’s normal migration runner unchanged

Decision #76 says all 131 repository migrations were applied using the lexical runner from .github/workflows/db-drift-check.yml, but also states that the second duplicate policy block in 20260716000000_agents_module_new_schema.sql was omitted from the input stream.

The repository workflow itself runs each unchanged file directly:

for f in packages/db/migrations/*.sql; do
  psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f "$f"
done

It contains no logic implementing that omission. Decision #76 also describes this as a psql -X runner, while the checked-in workflow does not pass -X.

Consequently, the documented disposable build demonstrates a controlled manually altered source stream, not an unchanged execution of the normal checked-in runner. A fresh checkout cannot reproduce that evidence through the workflow as written.

This is pre-existing upstream migration debt rather than a defect in migrations 00021–00026, but it directly defeats the requested normal-runner reproducibility gate for locking the complete Transfer migration chain.

Required correction: make the normal runner execute all repository migrations unchanged, preferably by repairing the duplicate policy definitions additively/idempotently through an authorized migration-history correction. Alternatively, encode and document an approved deterministic runner behavior in the checked-in workflow, then reproduce the complete chain through that exact workflow.

2. MINOR — The Transfer Drizzle source comment omits migration 00026

packages/db/src/schema/inventory/transfer.ts currently says:

See migrations 20260720000021_inventory_transfer.sql through
20260720000025_inventory_transfer_verifier_corrections.sql.

The authoritative finalization behavior now depends on:

20260720000026_inventory_transfer_finalization_retry_fix.sql

The Drizzle structures themselves match live PostgreSQL, so this is not a runtime defect. It is a current-source consistency error.

Required correction: update the comment’s migration range through 00026.

Evidence summary

Governing state and migration chain

  • Repository HEAD exactly matched ef767623d8166daeba775d4328a1de896af3a2ed.
  • The complete 1,366-line ruled-final design was read.
  • The repository contains 131 unique SQL basenames, lexically ending with 00021–00026.
  • The complete 131-file manifest hash independently reproduced as:
f6a117d8b4fd71544ead30e67a59c643cbc15df9eff4237adf5858a3486a5a31

Transfer migration SHA-256 values independently matched Decision #76:

00021  f6a55e8611e16e05f33f6363e0bf8ebb48b48b75d97266c9b235786c2d403eca
00022  5803825dbfb0ad2dcccb13734c9a6501c56cf136c6e3880416803176816c6101
00023  7fcb647221aa52cd96e12e9b7b2e572fb0b494b94495e73ea586660f0bccf006
00024  366ccbcac4cd724141b5204d515c292446bbcfabbc65daabea61ab4c2077aab7
00025  549a3d2052f4a3819699485b4b4cb8c665cd60c2b0f68fc65a231fa09df08618
00026  defb5d50a15a89e7a5a09f13862d2633490184ccb6d206b59f5369b7877ae182

Exact catalog shape

Live PostgreSQL 17.6 independently reconciled to:

Transfer tables:       3
Transfer columns:     63
Transfer CHECKs:      28
Transfer FKs:         20
Transfer triggers:    11

Per table:

Table Columns CHECKs FKs Triggers
inventory.transfer 26 12 9 3
inventory.transfer_line 21 9 8 2
inventory.transfer_reconciliation_event 16 7 3 3

Inventory independently reconciled to:

29 base tables
425 base-table columns
1 view
90 CHECKs
138 FKs
29 PKs
19 UNIQUE constraints
164 indexes
46 policies
41 non-internal triggers
29/29 base tables RLS-enabled

All 11 Transfer and companion triggers were enabled.

Drizzle/live and source-identity parity

All three Transfer partial source-identity indexes were live, valid, and modeled in Drizzle:

  • stock_reservation_transfer_source_line_unique
  • stock_movement_transfer_shipment_source_unique
  • stock_movement_transfer_reconciliation_source_unique

The repository drift checker passed:

drift-check PASSED -- no unexplained deltas found.

Both builds passed:

@vrida/db tsc: PASS
apps/api production build: PASS

Authority, RLS, ACL, and ownership

Confirmed live:

  • inventory_invariant_owner and inventory_command_executor are NOLOGIN, NOINHERIT, non-superuser, non-BYPASSRLS.
  • Only disclosed administrative membership rows exist, with inheritance/set disabled.
  • All Transfer wrappers/helpers and both posting-primitive overloads are SECURITY DEFINER, owned by inventory_invariant_owner, with fixed search_path=pg_catalog.
  • authenticated, authenticator, service_role, inventory_command_executor, anon, consumer_authenticated, and agent_reader have zero effective Transfer/private-primitive EXECUTE.
  • Those roles have no operational INSERT/UPDATE/DELETE on Transfer, stock, stock-lot, reservation, movement, or movement-line tables.
  • Transfer tables grant authenticated tenant-scoped SELECT only.
  • Default Inventory table ACL is authenticated SELECT only; no global default function EXECUTE grant exists.
  • The invariant owner can SELECT ... FOR UPDATE site, location, and lot.
  • Its only lifecycle-table UPDATE privilege is updated_at; status, deletion, identity, and business fields remain privilege-denied.

Direct rollback probes performed:

252/252 ordinary/runtime protected DML and EXECUTE attempts denied
3/3 Transfer tables enforced authenticated tenant isolation
site/location/lot FOR UPDATE succeeded for invariant owner
6/6 lifecycle/business-column update attempts denied

Repository search found no non-Transfer production routine able to emit Transfer reservation or movement attribution. The legacy 18-argument movement primitive explicitly rejects Transfer attribution.

Behavioral and concurrency coverage

The focused suite independently passed:

Test Suites: 1 passed
Tests:       18 passed

It exercised:

  • exact schema/catalog and security boundary;
  • human-only consequential authority and agent draft provenance;
  • approval, shipment, and receipt failure-injection atomicity;
  • duplicate same-variant/same-lot lines;
  • different-lot duplicate lines;
  • grouped same-lot demand rejection;
  • concurrent approval oversubscription prevention;
  • one atomic shipment and shipment retry;
  • pinned-lot depletion with complete rollback;
  • destination lifecycle changes after shipment;
  • concurrent destination stock-lot creation;
  • reciprocal A→B/B→A shipment without deadlock;
  • exact reconciliation retries and changed-payload rejection;
  • immutable lifecycle/pointer/counter evidence;
  • draft and approved cancellation;
  • site/location/lot anti-stranding guards.

Static function inspection confirmed:

  • per-Transfer advisory transaction locking;
  • lifecycle → header → lines → reservations → stock → stock-lot row order;
  • canonical stock and stock-lot ordering;
  • ordered soft-delete guard locking;
  • grouped source-stock and lot validation;
  • exact approval and shipment retry evidence;
  • exact outbound child-pointer provenance;
  • immutable outbound unit cost;
  • cumulative proportional integer-cent inbound allocation;
  • clean/restock credit versus missing/non-restock no-credit behavior.

Independent 00026 defect-shape reproduction

A separate rollback-only transaction created:

  • one effective line;
  • one fully cancelled line with requested_qty=1, cancelled_qty=1.

It then approved, shipped, reconciled, finalized, and retried finalization.

Result:

first finalization ID = b058cb57-a557-4754-af66-eb1376f33922
retry ID             = b058cb57-a557-4754-af66-eb1376f33922

The fully cancelled line retained:

stock_reservation_id        = NULL
outbound_movement_line_id   = NULL
shipped_qty                 = 0
cancelled_qty               = 1
requested_qty               = 1

The retry preserved the same terminal actor and non-null receipt timestamp. This independently proves the exact prior defect is corrected and 00026 preserves the remaining finalization evidence checks.

Cleanup and artifact status

After the focused suite and rollback probes, live sweeps returned:

Transfer headers:                       0
Transfer lines:                         0
Transfer reconciliation events:         0
Transfer reservations:                  0
Transfer movements:                     0
Temporary transfer_test_* functions:    0
Temporary transfer-test triggers:       0
Complete-movement cardinality errors:   0
Reservation-cache mismatches:           0

No persistent verifier database rows or functions remain.

Documented regression evidence

  • The checked-in Jest configuration enumerates exactly 57 API suite files.
  • Decision #76 records the final file-isolated result as 57/57 suites and 1,426/1,426 tests.
  • The focused final Transfer suite was independently rerun as 18/18.
  • Database and API production builds were independently rerun successfully.

Section 4 A–P + T + U

Item Result
A Column drift/count PASS
B RLS PASS
C NULL tenant uniqueness PASS
D Soft-delete uniques PASS
E Partial-index enums PASS
F CHECK completeness PASS
G Forward/composite FKs PASS
H Cross-module consistency PASS
I Money derivation PASS
J JSONB shape PASS
K Tenant indexes PASS
L Query indexes PASS
M Conditional consistency PASS
N Locked decisions PASS
O Non-RLS access PASS
P Rationale PASS
T Trigger audit PASS
U Integrity blocks PASS

The schema-level Section 4 audit is clean. The overall build/lock gate is not clean because normal-runner reproducibility and current-source consistency remain unresolved.

Limitations

  • I did not independently rerun the complete 57-suite/1,426-test regression; I verified the documented evidence, enumerated the 57 current suites, reran the focused 18-test Transfer suite, and reran both production builds.
  • I did not create another disposable database or replay all 131 migrations, because the supplied evidence itself discloses that the replay required an unencoded source-stream omission. No disposable database was created.
  • Concurrency behavior beyond the independent rollback probes was exercised by the focused 18-test suite rather than by additional standalone verifier sessions.

Final verdict: NOT CLEAN — one unresolved MAJOR migration-reproducibility finding and one unresolved MINOR current-source consistency finding.

Second final-verifier dispositions

# Severity Disposition
1 MAJOR Accepted and fixed. The existing .github/workflows/db-drift-check.yml now uses the verified Supabase PostgreSQL 17.6 image without overriding its required bootstrap user, passes -X, pins the exact SHA-256 of the already-applied historical Agents migration, and deterministically omits only its duplicate second policy block. The migration file itself remains byte-immutable. A fresh disposable database then ran all 131 migrations and drift through the exact checked-in Bash workflow path with no extra migration logic or source edit; normalized schema, function, ACL/default ACL, ownership, roles/memberships, RLS, and table ACL state matched the main database exactly.
2 MINOR Accepted and fixed. packages/db/src/schema/inventory/transfer.ts now points through 20260720000026_inventory_transfer_finalization_retry_fix.sql; database typecheck and drift remain green.

Disposition totals for this report: 2 accepted and fixed; 0 rejected; 0 deferred; 0 unresolved.

This second verifier's NOT CLEAN verdict remains authoritative for the state it inspected. The exact checked-in workflow replay now succeeds; Stock Transfer remains unlocked until a final fresh-context verifier returns CLEAN against both corrections.

Final fresh-context lock-gate verifier — report pasted verbatim

Final Independent Lock-Gate Verification — Stock Transfer

Verifier identity / canonical task: /root/transfer_lock_gate_verifier Session ID: 019f6bdd-6976-7ea1-9397-fc5997564dd2 Evidence HEAD: ef767623d8166daeba775d4328a1de896af3a2ed Mode: Fresh-context, read-only repository verification. No files edited, migrations applied to main, commits, pushes, or persistent verifier artifacts.

Final verdict: CLEAN

Zero unresolved BLOCKER, MAJOR, MODERATE, or MINOR findings remain.

Findings by severity

  • BLOCKER: None.
  • MAJOR: None.
  • MODERATE: None.
  • MINOR: None.

Both previously accepted corrections are independently verified:

  1. .github/workflows/db-drift-check.yml now provides a reproducible checked-in path.
  2. packages/db/src/schema/inventory/transfer.ts cites migration 20260720000026_inventory_transfer_finalization_retry_fix.sql.

Exact workflow replay

Workflow SHA-256:

de5bb9fbfa3631ef529a7cac388d007dc0c34b427f92c82d5212e9284d86e37e

Verified workflow properties:

  • Image: public.ecr.aws/supabase/postgres:17.6.1.136.
  • Live disposable server: PostgreSQL 17.6.
  • No incompatible POSTGRES_USER override; the image retained its supabase_admin bootstrap default.
  • Every psql invocation passes -X -v ON_ERROR_STOP=1.
  • Historical Agents migration hash is pinned exactly:
746859bfdf67a4253a2de13acacdf1852967d786ba7ab99d84e7b10daf2ca946
  • Only lines 1572–1576 are deterministically omitted with:
sed '1572,1576d'
  • Those lines exactly duplicate the earlier kill_switch_event_select and kill_switch_event_write policies at lines 602–606.
  • All other migrations execute directly and unchanged.

The exact checked-in Bash loop successfully applied all 131 migrations through 00026, followed by:

drift-check PASSED -- no unexplained deltas found.
EXACT_CHECKED_IN_BASH_PATH_PASS

The disposable container had no mounted volume and was destroyed afterward.

Migration inventory:

131 files
131 unique basenames
manifest SHA-256:
f6a117d8b4fd71544ead30e67a59c643cbc15df9eff4237adf5858a3486a5a31

Transfer migration hashes:

00021  f6a55e8611e16e05f33f6363e0bf8ebb48b48b75d97266c9b235786c2d403eca
00022  5803825dbfb0ad2dcccb13734c9a6501c56cf136c6e3880416803176816c6101
00023  7fcb647221aa52cd96e12e9b7b2e572fb0b494b94495e73ea586660f0bccf006
00024  366ccbcac4cd724141b5204d515c292446bbcfabbc65daabea61ab4c2077aab7
00025  549a3d2052f4a3819699485b4b4cb8c665cd60c2b0f68fc65a231fa09df08618
00026  defb5d50a15a89e7a5a09f13862d2633490184ccb6d206b59f5369b7877ae182

Fresh/local parity

Fresh and local four-schema dumps matched exactly after removing nondeterministic restriction markers, blank lines, and comment-only lines:

6,882 lines each
SHA-256:
82786733b52a27c661a2bc859aa05d286f4325ec665fb4ecab7134e0282fd453

A separate normalized security catalog covering relevant roles/memberships, object and column ACLs, default ACLs, owners, routine configuration, RLS, and policies also matched exactly:

316 lines each
SHA-256:
a44b3a192494a7c741346cb8081b66289b0d9b34a390f7539031c5567d230fc3

The fresh database correctly contained no fabricated drizzle.__drizzle_migrations relation.

Exact catalog shape

Transfer tables:       3
Transfer columns:     63
Transfer CHECKs:      28
Transfer FKs:         20
Transfer triggers:    11
Table Columns CHECKs FKs Triggers
inventory.transfer 26 12 9 3
inventory.transfer_line 21 9 8 2
inventory.transfer_reconciliation_event 16 7 3 3

Inventory reconciled identically on fresh and local databases:

29 base tables
425 base-table columns
1 view
90 CHECKs
138 FKs
29 PKs
19 UNIQUE constraints
164 indexes
46 policies
41 non-internal triggers
29/29 tables RLS-enabled

All 11 Transfer and companion triggers are enabled.

Drizzle, uniqueness, and 00026

All three live source-identity partial uniques are valid and modeled in Drizzle:

  • stock_reservation_transfer_source_line_unique
  • stock_movement_transfer_shipment_source_unique
  • stock_movement_transfer_reconciliation_source_unique

The focused suite passed:

Test Suites: 1 passed
Tests:       18 passed

Its eighteenth regression created one effective line and one fully cancelled line, then approved, shipped, reconciled, finalized, and retried finalization. The retry returned the original Transfer ID. The fully cancelled line retained:

stock_reservation_id      = NULL
outbound_movement_line_id = NULL
shipped_qty               = 0

This verifies migration 00026 applies reservation/outbound evidence requirements only to effective lines while preserving exact terminal retry evidence.

Authority and runtime closure

Confirmed:

  • inventory_invariant_owner and inventory_command_executor are NOLOGIN, NOINHERIT, non-superuser, and non-BYPASSRLS.
  • All Transfer tables are RLS-enabled with authenticated tenant-scoped SELECT and owner policies.
  • Inventory’s default table ACL is authenticated SELECT only.
  • Runtime roles have zero effective Transfer/private-primitive EXECUTE paths.
  • Runtime roles have zero protected operational INSERT/UPDATE/DELETE paths.
  • All three source uniques match live SQL and Drizzle.
  • The focused suite exercises owner locking, lifecycle/business-column denial, tenant isolation, human-only consequential authority, canonical locking, exact retries, atomic rollback, lot handling, reconciliation, and anti-stranding guards.

Decision #76 evidence

Decision #76 contains both prior NOT CLEAN reports in the main evidence body:

  • /root/transfer_final_build_verifier
  • /root/transfer_final_clean_verifier

Both reports retain their exact NOT CLEAN verdicts and complete findings. Their dispositions are also present:

First report:  1 accepted/fixed, 0 unresolved
Second report: 2 accepted/fixed, 0 unresolved

Decision #76 also records:

57/57 suites
1,426/1,426 tests
18/18 focused Transfer tests

It contains the exact workflow image, workflow hash, migration manifest hash, historical source pin, deterministic omission description, disposable replay, and normalized-parity evidence. The generated raw documentation viewer copy exactly matches the Markdown source.

Section 4 A–P + T + U

Item Result Evidence
A Column drift/count PASS Exact 26+21+16=63
B RLS PASS Three tenant SELECT and owner policies
C NULL tenant uniqueness PASS All tenant IDs are NOT NULL
D Soft-delete uniques PASS Active transfer number uses a partial unique
E Partial-index enums PASS All predicates use valid constrained values
F CHECK completeness PASS Exact 12+9+7=28
G Forward/composite FKs PASS Exact 20 tenant-safe FKs
H Cross-module consistency PASS Targets/types match live schemas
I Money derivation PASS Immutable outbound cost and cumulative allocation
J JSONB shape PASS Decision-provenance shape documented
K Tenant indexes PASS Tenant-leading indexes on all three tables
L Query indexes PASS Status/site/line/lot/key/pointer paths covered
M Conditional consistency PASS Lifecycle, counters, pointers, disposition and retries enforced
N Locked decisions PASS One shipment, partial receipt, human consequential authority
O Non-RLS access PASS Narrow owner access; runtime wrappers dormant
P Rationale PASS Non-obvious choices and guards retained
T Trigger audit PASS All 11 enabled and exercised
U Integrity blocks PASS All four blocks retained with explicit deferral triggers

Cleanup and artifact status

Post-suite live sweeps:

Transfer headers:                 0
Transfer lines:                   0
Transfer events:                  0
Transfer reservations:            0
Transfer movements:               0
Temporary verifier functions:     0
Temporary verifier triggers:      0
Complete-cardinality errors:      0
Reservation-cache mismatches:     0
Runtime EXECUTE paths:            0
Runtime protected DML paths:      0

The disposable database and container were destroyed, with no named volume. git diff --check passes. The existing uncommitted build remains on the required HEAD; the verifier made no repository edits.

Limitations

  • I did not rerun the entire 57-suite/1,426-test regression. I independently enumerated the current 57 suite files, verified Decision #76’s retained evidence, and reran the required focused 18-test suite.
  • The standalone behavior evidence came from the focused live suite with verified cleanup rather than an additional bespoke transaction.

Final verdict: CLEAN — zero unresolved findings.

Final lock disposition and status

The final lock-gate verifier reported no new findings. Across all Stock Transfer post-build verifier reports, 13 findings were accepted: 1 BLOCKER, 8 MAJOR, 2 MODERATE, and 2 MINOR. Twelve were corrected in the built schema, Drizzle, tests, workflow, or documentation; one MINOR live naming/predicate difference was accepted as structurally equivalent and modeled exactly. 0 findings were rejected, deferred, or left unresolved.

The Stock Transfer schema is LOCKED at the schema boundary on 2026-07-16: 3 tables / 63 columns / 28 CHECKs / 20 FKs / 11 triggers, with Inventory at 29 base tables / 425 base-table columns / 1 view. Transfer services, APIs, UI, workers, module wiring, notification runtime, and runtime wrapper EXECUTE remain unbuilt. The only remaining architect/service decision is the separately designed non-spoofable credential/session gateway required before any runtime role may execute the dormant Transfer commands.

Last modified: Jul 16, 2026, 10:08 AM PT
← Previoustax
On this page
Esc
↑↓ navigate↵ openEsc close