Plan: Postgres store backend (phase 1)

A Postgres implementation of the handler's DocumentStore interface, config-selected, with the file store staying the default. Branch: feat/postgres-store (stacked on refactor/documentstore-interface).

Parity strategy: store the version-file bytes

The file store's Document.Content is the raw stored bytes including the store frontmatter (version, archived, previous-hash, publisher meta); the handler strips it. The hash chain is computed over those raw bytes. So pgstore stores the byte-identical serialized blob the file store would write, in a stored bytea column. Consequences:

• Get, Versions, VerifyChain, ErrNotModified dedup, and the previous-hash chain carry over exactly.
• File to Postgres migration (either direction) is a blob copy.
• The version-file format becomes shared vocabulary, exported from protocol/store.

Changes to protocol/store (no behavior change)

Export the format helpers so pgstore reuses them instead of duplicating logic (guidelines: don't duplicate):

• SerializeVersion(version, prevRaw []byte, content, meta) refactored out of buildVersionFile (which keeps the file read and delegates).
• ExtractBody, ExtractMetadata, IsArchived, ExtractPreviousHash renamed to exported.
• SetArchived(data, archived) extracted from Archive's in-place frontmatter toggle.
• ValidateMeta, MetaEqual, JoinContent, RetentionValue exported.

File store tests must pass unchanged (behavior-identical refactor).

New package: server/internal/pgstore

pgx driver dependency lives in the server module only; protocol stays dependency-free. Schema applied at startup (CREATE TABLE IF NOT EXISTS):

• documents(path text primary key, current_version int, archived bool)
• versions(path text, version int, stored bytea, body_hash text, modified timestamptz, primary key(path, version))
• index on body_hash (LookupHash queries the DB directly; no in-RAM hash index)

Concurrency: every write transaction row-locks the documents row (SELECT FOR UPDATE, INSERT ON CONFLICT for creation); UNIQUE(path, version) is the backstop CAS. This gives true multi-writer safety; the current-pointer regression race of the file store cannot occur.

Semantics to replicate (from the file-store study)

• WriteVersion expected-version: <0 skip check, 0 create-only, >0 exact; ErrConflict carries Document{Version: current}; post-write conflict check kept.
• ErrNotModified when body and publisher meta equal the tip; allowed at expected or expected+1.
• ErrArchived rejects writes to archived docs.
• Archive toggles the tip's stored frontmatter in place (not a new version) plus the documents.archived column; archived docs drop out of LookupHash.
• Retention: RetentionValue(meta) > 0 prunes versions <= current-keep oldest-first, contiguous, returns PruneResult.
• Append: read base at expectedVersion, JoinContent, delegate to WriteVersion.
• ListDir: distinct next path segments under the prefix; files are docs at exactly prefix/name; a subdirectory lists only if its subtree holds a visible doc; dot-names hidden; archived filtering per flag; sorted; os.ErrNotExist for a prefix with no docs.
• Get: version 0 means current; os.ErrNotExist contract throughout.
• VerifyChain: sha256 of previous stored bytes vs ExtractPreviousHash of current, oldest to newest.
• WalkCurrent equivalent so main.go builds the in-RAM catalog at startup (phase 1 keeps the catalog in RAM; single replica parity).

Testing: conformance suite

server/internal/storetest.RunConformance(t, factory func(t) handler.DocumentStore) exercising the contract above. Run against the file store unconditionally and against pgstore gated on DEMARKUS_TEST_PG_DSN (t.Skip when unset) so CI without Postgres stays green. Behavior divergence between backends is a protocol bug.

Server wiring

Flags -store=file|postgres and -pg-dsn (env DEMARKUS_PG_DSN fallback). Postgres mode skips BuildHashIndex (DB-backed) and builds the catalog from pgstore's WalkCurrent equivalent.

Phase 2 (explicitly out of scope here)

Catalog moves into Postgres (LOOKUP queries the DB) enabling multi-replica world pods; deploy shape changes (Deployment, no PVC). Recorded in ADR 0002 in the deploy project's soul.