Logbook specification

Design

The platform’s one record of state: the working records, the public views of them and the append-only ledger, kept today in a single PostgreSQL 17 database.

J.4.32 min readLast revised November 2026

Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.

Registry entry

Keeps the record of every item, decision and proposal, and the public views of that record.

Formerly: postgres
Namespace: clearedstack
Repository: logbook
Container image: postgres:17-alpine (upstream PostgreSQL; Logbook is the schema and ledger on top)
Depends on: Nothing else in the platform
Depended on by: Conn, Muster
Boundaries: Working records (the core schema): read and written by Muster only
Public views (the pub schema): read-only, for Conn

From the naming registry, which is the one place this component’s name is written down.

On this page

Overview & Role
Runtime & Resource Budget
Interfaces & Data Contracts
Failure Modes & Recovery
Security & Clean-Room Boundaries
Related pages

Logbook is the name for the platform’s record of state, not for the database engine. If PostgreSQL were ever replaced, Logbook would still be Logbook. Today it is a single shared PostgreSQL 17 database (image postgres:17-alpine, with its schema kept in the logbook repository). Running one consolidated database on a Persistent Volume Claim (PVC) eliminates multi-database sync bugs and keeps control-plane memory compact enough for a single 4 GiB k3s node.

Overview & Role#

Logbook is the durable system of record for live operational state, work queues, and sanitized public views:

Single Source of Truth: Stores PA-XXXX item records, evaluation outcomes, decision trails, queue leases, anonymous edit proposals, and an append-only ledger.
Atomic State + Queue Transitions: Because live state and work queues live in the same database, Muster commits an item's state change and its next queue step in a single ACID transaction.
Strict Schema Separation: Splits internal operational data (core.*) from sanitized, public-safe projections (pub.*).

Runtime & Resource Budget#

Attribute	Value
Namespace	`clearedstack` (Control Plane)
Kind	`control-plane`
Version	`17-alpine`
Owning Repo	`logbook`
RAM Request	`256 MiB`
Priority Class	High (Control Plane — protected from eviction)
Storage	Persistent Volume Claim (1 of 3 cluster PVCs)
Network Exposure	Cluster-private (`ClusterIP` only); unreachable from `cs-workers` and public internet

Interfaces & Data Contracts#

Only two services in the entire cluster are permitted to connect to Logbook:

Service	Schema Access	Role / Privileges	Responsibility
Muster	`core.*`	Read / Write	Manages worker queue leases, `needs_subtool` pauses, replay, edit proposals, and append-only ledger entries
Conn	`pub.*`	Read-Only (`pub_ro`)	Reads sanitized public views for the Portal, App Store UI, and monthly restore drill status
`cs-workers` (Trawl through Bellbuoy)	None	Blocked	Zero network access (`NetworkPolicy`) and zero database credentials

Failure Modes & Recovery#

Because Logbook holds one of the cluster's three non-recreatable Persistent Volume Claims, durability and recovery are verified continuously rather than assumed:

Consistent Nightly Backups: A scheduled backup job takes a consistent database dump (never a raw file copy while writes are active), encrypts the dump client-side with age, transfers it to off-node storage, and prunes old snapshots on a fixed retention schedule.
Automated Monthly Restore Drill: Once a month, the cluster provisions an isolated scratch area, downloads the latest age-encrypted backup, decrypts it with the current key, restores Logbook from scratch, and runs deterministic integrity checks on core.* tables and pub.* views before tearing down the scratch environment.
Live Drill Visibility: The timestamp and pass/fail outcome of the four monthly verification checks are published directly to the live Portal so backup drift surfaces immediately.
Pod Restart / Node Reboot: Because data resides on the PVC and Logbook runs under the High Priority Class, k3s reattaches the volume and recovers cleanly via PostgreSQL crash recovery.

Security & Clean-Room Boundaries#

Default-Deny Network Isolation: NetworkPolicy blocks all pods in cs-workers and all external Ingress traffic from reaching Logbook on the network.
Least-Privilege Roles: Conn is restricted to pub_ro on pub.* views, ensuring no public query can ever read core.* tables, internal tokens, or unapproved edit payloads.
Encrypted Off-Node Backups: Backup archives are encrypted with age before leaving the host node, with the decryption key stored separately from the off-node backup target.
Unprivileged Execution: Runs as non-root with dropped capabilities and no privilege escalation.

Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.