118 lines
6.8 KiB
Markdown
118 lines
6.8 KiB
Markdown
---
|
|
kind: verification
|
|
status: active
|
|
---
|
|
|
|
# P0 Field-Map Currency Verification — 2026-08-29
|
|
|
|
**Purpose:** REQ-MIG-001 (native-kanban-sot.md §5) accepts only when "P0 publishes
|
|
the current `origin/main` field-by-field expand/backfill/compatibility/switch/contract
|
|
map before any schema lane starts." That map exists: [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)
|
|
§5, inspected at `packages/db/src/schema.ts` @ `e72388b2cbfe400842fe940fa6cabf984ed43711`
|
|
(2026-07-13). The M4-3 schema lane (expand migration 0021+) now opens against the
|
|
integration trunk `next`. This document re-verifies the map's currency at the
|
|
lane-opening head and records the measured pre-expand writer inventory. It amends
|
|
nothing normative in SHARED-CONTRACT.md; where the two disagree, SHARED-CONTRACT.md
|
|
wins.
|
|
|
|
## 1. Currency verification (measured)
|
|
|
|
- Map pin: `e72388b2cbfe400842fe940fa6cabf984ed43711` (2026-07-13, `main`).
|
|
- Lane-opening head: `abb0c936011c7f6b8c0bcc90a20a865d5e8a40e9` (`origin/next`,
|
|
2026-08-29).
|
|
- Measurement: `git diff e72388b2 abb0c936 -- packages/db/src/schema.ts` reports
|
|
**300 insertions, 0 deletions** — no existing declaration changed.
|
|
- The additions: the new declarations `logicalAgentConnectorLeases`,
|
|
`connectorLeaseAuditLog`, and the hierarchy layer (`companies`, `estates`,
|
|
`platformProjects`, `workspaces`, `hierarchyGrants`, `hierarchyAuditEvents`,
|
|
`hierarchyOutbox`, plus their enums and constant arrays); a nullable `issuer`
|
|
column on the unmapped BetterAuth `accounts` table (shipped as
|
|
`drizzle/0017_accounts_issuer.sql`); and expanded `drizzle-orm` imports
|
|
(`sql`, `AnyPgColumn`, `unique`, `check`, `bigint`). None touch a mapped
|
|
source.
|
|
- Stronger literal fact: REQ-MIG-001's acceptance names `origin/main`. Measured
|
|
pin → `origin/main` (`7102ccb9`, 2026-08-13): **63 insertions, 0 deletions**
|
|
for `schema.ts`, and `origin/main` is an ancestor of `abb0c936`. The map is
|
|
therefore current at `origin/main` itself, and at the trunk head beyond it.
|
|
|
|
**Consequence:** every source column mapped in SHARED-CONTRACT.md §5.4 —
|
|
`teams`/`team_members`, `projects`, `missions`, `tasks`, `mission_tasks`,
|
|
`agents`, fleet `backlog` — is byte-identical to the declaration the map
|
|
inspected. The field map is current as written. No row changes.
|
|
|
|
## 2. Refinements available since the pin (context, not map changes)
|
|
|
|
1. **The `workspaces` table exists.** The map predates contract 1's hierarchy
|
|
layer; its "bootstrap workspace" backfill step now has a shipped target:
|
|
`workspaces` (uuid PK, chained under platform projects per
|
|
`docs/requirements/hierarchy-schema.md`; hierarchy core in
|
|
`drizzle/0018_clean_cobalt_man.sql`, audit/outbox in
|
|
`0019_volatile_killraven.sql`, visibility in
|
|
`0020_special_betty_brant.sql`). New `workspace_id` columns FK there.
|
|
2. **The audit/outbox envelope pattern is shipped.** `hierarchyAuditEvents` +
|
|
`hierarchyOutbox` implement same-transaction semantic event + outbox. The
|
|
task lane's `task_events`/`task_outbox` mirror the pattern but are
|
|
workspace-scoped with the composite `(workspace_id, id)` key required by
|
|
§5.3 and REQ-SOT-004. The hierarchy tables are a pattern reference, never a
|
|
shared store for task events.
|
|
3. **Trunk designation.** The integration trunk is `next` (`.mosaic/repo.json`).
|
|
§1 measures currency at both the literal `origin/main` REQ-MIG-001 names and
|
|
the trunk head pinned above, so no reinterpretation of the acceptance text
|
|
is needed.
|
|
4. **Migration ownership.** SHARED-CONTRACT.md §6 assigns schema/migration
|
|
ownership to the mission seat `coder2`. Seat identity is operational fleet
|
|
state, not resolvable from this repository, and is outside this document's
|
|
scope. The invariant §6 protects binds regardless of seat and is restated
|
|
here as binding on the M4-3 schema lane: exactly one lane generates
|
|
migrations at a time; expand is additive; no drop/rename/narrow; constraints
|
|
validate before NOT NULL.
|
|
|
|
## 3. Pre-expand writer inventory (measured 2026-08-29 at `abb0c936`)
|
|
|
|
SHARED-CONTRACT.md §5.1 phase 1 requires an N-1 patch that stops
|
|
`mission_tasks.status` as a write source, plus a writer inventory, before any
|
|
expand DDL.
|
|
|
|
- **Sole authoring write path:** `packages/brain/src/mission-tasks.ts`
|
|
`create`/`update` (Drizzle insert/update on `mission_tasks`), invoked by
|
|
`apps/gateway/src/missions/missions.controller.ts`. `update` accepts
|
|
`Partial<NewMissionTask>`, so `status` is writable through both DTOs today.
|
|
The same module also exposes `remove`/`removeByMission` DELETE paths —
|
|
immaterial to `status` writes, listed for inventory completeness.
|
|
- **Storage-layer surfaces that touch the column without authoring it**
|
|
(added 2026-08-29 after independent review of the phase-1 patch):
|
|
`packages/storage/src/migrate-tier.ts` copies whole `mission_tasks` rows
|
|
between storage tiers and must preserve the stored `status` verbatim — row
|
|
transport, exempt from the write prohibition (stripping there would corrupt
|
|
data inside the N-1 window). The generic table-keyed storage adapters
|
|
(`adapters/postgres.ts`, `adapters/pglite.ts`) register `mission_tasks` in
|
|
their table maps but have no caller that targets it: measured at this head,
|
|
every runtime adapter caller passes a fixed collection constant
|
|
(preferences/insights). Neither surface authors a new `status` value.
|
|
- **Read-only consumers of `mission_tasks`:** federation verb services
|
|
(`get-query.service.ts`, `list-query.service.ts`) select only. The MCP
|
|
`brain_*` tools do not touch `mission_tasks` at all; `brain_create_task` /
|
|
`brain_update_task` write the separately mapped `tasks` table, a legitimate
|
|
N-1 writer through the compatibility window.
|
|
- The ratified contract 5 decision
|
|
(`docs/requirements/tool-gateway-mapping.md` §3.2, ruled 2026-08-27) freezes
|
|
the legacy endpoints — including MCP `brain_*` task mutations — for new
|
|
consumers, while existing consumers keep working until each surface's owning
|
|
contract retires it. It does not stop existing writes.
|
|
|
|
**Standing work item:** the phase-1 stop-write patch (reject or ignore `status`
|
|
on `mission_tasks` create/update) MUST land before the expand DDL of migration
|
|
lane M4-3a. It is N-1-safe per the §5.4 row for `mission_tasks.status` (linked
|
|
status is ignored; the column stays declared and readable through the whole
|
|
N-1 window; retirement only after no readers).
|
|
|
|
## 4. Lane opening
|
|
|
|
With this verification merged, REQ-MIG-001's P0-map precondition is satisfied
|
|
for the M4-3 schema lane at pinned head `abb0c936`. The ordered phases (§5.1),
|
|
mission candidate-key DDL order (§5.2), audit/proposal DDL order (§5.3), field
|
|
map (§5.4), and required migration tests (§5.5) bind as written. External
|
|
import machinery (jarvis-brain/Vikunja shadow import, REQ-MIG-001) and client
|
|
cutover (REQ-MIG-002) remain out of scope for M4-3; the legacy surface stays
|
|
frozen for new consumers meanwhile (`tool-gateway-mapping.md` §3.2 decision).
|