alkstore/tasks/pg-engine-schema.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
pg-engine-schema	Postgres engine — schema bootstrap (engine-owned schema, table family)	pending		narrow	low	component	implementation	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