---
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