alkstore/docs/architecture/deployment.md

status, last_updated

status	last_updated
draft	2026-10-05

Deployment

What a deployer must know to size, run, and reason about alkstore engines: host semantics, connection budgets, durability knobs, and where engine differences may honestly surface in the contract. The capability-surface decision (how much of this the trait exposes) is OQ-08's; this document holds the facts and the decision's frame.

Host semantics

Engine	Host posture	Notes
SQLite	single-machine, file-backed	NFS two-writers unsupported (honker's honesty posture, inherited, ADR-003). Cross-process on one host is verified POC ground (data_version is cross-process by nature).
Postgres	multi-host native	Nothing assumes a shared host; POC #2 ran all-through-network (docker bridge) with the same properties (ADR-004).

The unified trait must not pretend SQLite is multi-host — but whether that honesty lives as runtime capability flags, compile-time engine knowledge, or a documented matrix only is OQ-08 (ADR-006 note: the trait's shape constrains where capability differences can surface).

Options for OQ-08, with their shape:

1. Compile-time only — a consumer chooses an engine crate at dependency time; the engine's docs carry its deployment facts. Smallest contract; nothing runtime to match on.
2. Store::capabilities() — a runtime description (payload limits, wake cadence knobs, host semantics). Lets a consumer adapt (e.g., chunk large notify payloads) but adds a contract surface all engines must keep honest.
3. Deployment matrix only (this document) — no API surface. The honest-middle choice; matches the ecosystem's doc-first posture but provides no programmatic guard.

Connection budgets

SQLite engine

• Connections are in-process (writer + reader pool + watcher thread owning a connection). No external budget lines; the file lock is the OS-level resource.

Postgres engine

Connection class	Count	Notes
Pool	max_size per process	claims/queries via deadpool
Listener	+1 per LISTEN-ing process	non-pooled, dedicated; pooled connections cannot carry LISTEN (deadpool#360, test-pinned — ADR-004)
—	—	Sizing rule: max_size + 1 per process; verify end-to-end accounting (POC #2's pgdiag-st-4: pool 6 + 1 listener + probe conns = exact server-side count)

Shared-server co-tenancy (the alkblobs ADR-008 precedent — /workspace/@alkdev/alkblobs/docs/architecture/decisions/ — consumer tables co-tenant the pg instance) is supported and expected — the naming / reserved namespace contract protects reserved names; queue/stream/lock tables are schema-named to avoid collisions (layout decision in queues.md, OQ-05's namespace bullet).

Durability knobs

Engine	Knob	Shape
SQLite	synchronous	WAL + NORMAL shipped (ADR-003); FULL is available consumer-side for stricter durability; commit fsyncs land at WAL checkpoints (the ~1000-commit spike cadence, POC #1)
Postgres	synchronous_commit	per-session knob; on is ship config (p50 2.40 ms seam); off trades max-tail (40.9 ms) for slightly better p50 — measured, honest trade (ADR-004); session-level SET mechanics POC-verified

These are engine-configuration concerns, not trait surface. What part of engine config is contract-level shape vs engine-crate docs is decided: constructors and option structs live in the engine crates; the contract is the trait the constructor returns (ADR-008 §6).

Toolchain / platform notes

Note	Engine	Affects
rusqlite 0.40.x needs rustc ≥ 1.99	SQLite	any binary linking alkstore-sqlite (ADR-003)
bundled-sqlite adds a C build (~10 s dev, cacheable)	SQLite	build/CI time
libsqlite3-sys collision with sqlx today	any mixed-driver binary	structurally avoided (ADR-001 single-driver rule)
Listener application_name set for diagnosability (kill-targetable)	Postgres	ops runbooks (ADR-004)

Consumer-facing latency profile (indicative, POC-measured)

From both POCs (single-box, relative shapes are the deliverable — ADR-003 and ADR-004 carry the full tables):

• Tx seam: SQLite ~0.35 ms p50; Postgres ~2.4 ms p50 (ship config).
• Wake: ~1.1–2.2 ms p50 both engines at default cadence.
• Queue claim: LISTEN-driven 3–6 ms p50 (pg); poll-only interval-bound (32–50 ms at a 50 ms poll).
• Absolute numbers will differ per hardware/network; they set expectations of order, not SLAs — contract docs must not bake them in (ADR-007's pg-POC note).

Design Decisions

ADR	Decision	Summary
001	Crate split	single-driver binaries shape the matrix
003	SQLite driver	bundling, toolchain floor
004	Postgres driver	listener budget line, forwarder posture
006	Wake contract	where capability differences may surface
008	Contract v1	constructor/options in engine crates; no capability surface in v1 (OQ-08)

Open Questions

Open questions are tracked in open-questions.md. Key questions affecting this document:

• OQ-08: capability-surface shape — compile-time vs runtime flags vs matrix-only (open)