Wave 4 decomposed: Postgres engine — 11 tasks (schema, open/opts, seam, forwarder, mechanisms, scheduler/outbox, integration, review gate); plan synced

tasks/pg-engine-schema.md

@@ -0,0 +1,110 @@
+---
+id: pg-engine-schema
+name: Postgres engine — schema bootstrap (engine-owned schema, table family)
+status: pending
+depends_on: []
+scope: narrow
+risk: low
+impact: component
+level: implementation
+tags: [wave-4, postgres-engine]
+---
+
+## Description
+
+Stand up the pg engine's data model: the engine-owned PostgreSQL schema
+and its table family — the dependency root every later wave-4 task
+rides. Per ADR-010 §8 (one engine-owned schema, default `alkstore`,
+queues as rows — no per-queue tables/schemas) and engine-postgres.md's
+mapping table.
+
+A `schema.rs` module in `alkstore-postgres`:
+
+- **Schema name is engine configuration** (default `alkstore`) — it
+  rides `PgOpts` (the open task wires it; this task's bootstrap takes
+  the schema name as an argument).
+- **Bootstrap is idempotent DDL**, runnable at open on any connection:
+  `CREATE SCHEMA IF NOT EXISTS` + `CREATE TABLE IF NOT EXISTS` +
+  indexes. All engine-owned objects live in the one schema; consumer
+  tables co-tenant the instance untouched (deployment.md's co-tenancy
+  posture).
+- **Table family** (column sets follow the contract's value shapes —
+  the `#[doc(hidden)]` constructors' full field lists in
+  `alkstore/src/{job,stream,schedule}.rs` are the field lists of
+  record; ADR-019 §1/§3, ADR-015 §3, ADR-009 §3, ADR-021 §2):
+  - **job table** (live rows — pending and processing): queue name,
+    payload, enqueue/ready-time resolution columns (`run_at`,
+    `expires_at`), `priority`, the stamped `QueueOpts` columns
+    (`visibility_timeout_s`, `max_attempts`, `backoff_base_s`,
+    `dead_letter_retention_s` — ADR-010 §3a), `attempts`,
+    `worker_id`, `claimed_at`, `claim_expires_at`, `last_error`.
+    Claim-ordering index per ADR-010's ordering row (`priority DESC,
+    run_at ASC, enqueue order`).
+  - **dead table**: the job row's diagnosis fields + `died_at`,
+    `last_error`; retention index for the sweep's retention
+    enforcement.
+  - **stream events table**: `id BIGSERIAL` (the offset — engine-
+    assigned, monotone, immutable, never renumbered), stream name,
+    nullable `key` column (carried metadata, ADR-015 §1), payload,
+    `created_at` (unix-seconds, informational). The `(stream, id)`
+    index serving the `offset ASC` read paths.
+  - **offsets table**: (stream, consumer) → offset, the monotone
+    checkpoint upsert target.
+  - **schedule table** (ADR-009): name (unique), `@every` spec, target
+    queue, payload, the `ScheduleOpts` stamps, and the boundary-state
+    columns the tick math advances (the substrate's
+    `__alkstore_scheduler_tasks` shape is the reference —
+    `reference-honker-machinery.md`).
+  - **locks table**: name (unique), owner, expiry timestamp — the TTL
+    lock machinery's storage (the substrate's lock-table semantics,
+    re-derived; the locks task builds ops on it).
+- **Payload columns store the exact encoded bytes** (`bytea`) — not
+  `JSONB`: JSONB normalization (key reordering, duplicate folding)
+  would break the contract suite's byte-identical-rows row (ADR-020
+  §4). The engine stores exactly what `encode_payload` returned.
+- **No notifications table** — pg notify is native (`pg_notify`); the
+  SQLite notify-table carriage has no pg counterpart. The 8000-byte
+  check is client-side (the seam task), not storage-shaped.
+- **No migration machinery in v1** — tables are created fresh per
+  schema; append-column migrations are the substrate's evolution
+  discipline, not a greenfield v1 need (note the posture in the module
+  docs; wave 6's release pass revisits if the deployment story
+  demands in-place upgrades).
+
+Tests use a raw `tokio_postgres::Connection`/Client against the
+harness server (no engine code yet): bootstrap runs twice cleanly
+(idempotence), every table exists with its pinned columns, the
+bigserial offset behaves (monotone, gap-on-delete), the claim-ordering
+index exists.
+
+## Acceptance Criteria
+
+- [ ] `schema.rs` with an idempotent `bootstrap(conn, schema_name)`
+      creating the full table family + indexes in the one schema
+- [ ] Column sets match the contract's value shapes (the constructors'
+      field lists; stamp columns per ADR-010 §3a; `claimed_at` per
+      ADR-021 §2)
+- [ ] Payload columns are `bytea` (exact-bytes posture, JSONB
+      rejected — documented in the module docs with the reason)
+- [ ] Schema name is a parameter (default `alkstore` decided at the
+      `PgOpts` layer, next task)
+- [ ] Idempotence + table-shape tests green against the harness server
+- [ ] `cargo test -p alkstore-postgres`, clippy `-D warnings`, fmt clean
+
+## References
+
+- docs/architecture/engine-postgres.md (Identity and posture; mapping table)
+- docs/architecture/decisions/010-queue-semantics-depth.md §3a, §8
+- docs/architecture/decisions/015-streams-depth.md §1, §3
+- docs/architecture/decisions/009-scheduler-collapse.md §3
+- docs/architecture/deployment.md (co-tenancy)
+- docs/research/reference-honker-machinery.md (schema reference read)
+- alkstore/src/job.rs, stream.rs, schedule.rs (the field lists of record)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion