book-library.git · PLANS.md

revision 8054cf9f142022c724f94ccf0f5f9a71b7404e0d · complete file

Title: FountainMaintenanceKit server adapter — initial vertical slice

Goal: Consume the published FCIS Kit in the Book Library server and expose a narrow typed maintenance admission/read
surface with server-owned authorization and repeat-safe receipts.

Scope: remote Kit dependency, `MaintenanceAdmission`, health operation, operation receipt lookup, focused tests, and
fixture-server proof.

Non-goals: native Swift Git backend, deployment/promotion executors, real SecretStore provider, TLS termination,
remote production deployment, Reframe UI, or FountainStore integration.

Constraints: no secret values; no guessed SSH or filesystem authority; unsupported operations fail visibly.

Plan:
- Step 1 (status: completed) - Resolve published `FountainMaintenanceKit` and add the server admission adapter.
- Step 2 (status: completed) - Add authorization, idempotency, collision, and receipt tests.
- Step 3 (status: completed) - Run the fixture server and prove health success, retry, denial, receipt retrieval, and
restart persistence.
- Step 4 (status: completed) - Commit and push the Book Library server adapter; record the exact Kit revision.

Validation:
- `swift test`
- fixture server HTTP proof on `/v1/maintenance/operations`
- `git diff --check`

Evidence:
- `FountainMaintenanceKit@0.1.1` revision `3d58c56bf5b685ea8211a0ec503317b1a74552eb`
- `swift test`: 13 tests passed
- Live fixture server: health `200/succeeded`, idempotent retry `200/same receipt`, unauthorized actor `403`, receipt
lookup `200/succeeded`, and after process restart receipt lookup again returned `200/succeeded` with the same
operation timestamp and identity.

## Durable maintenance receipts — Chapter 62/63 follow-on

Goal: make maintenance admission survive service restart without putting secrets or host-bound state into receipts.

Implemented: `MaintenanceAdmission` now writes typed request/receipt entries atomically beneath the explicit
`BOOK_LIBRARY_MAINTENANCE_RECEIPTS_ROOT`; a new process reloads by idempotency key and operation ID. Unsafe keys,
unknown actors, and idempotency collisions fail closed.

Non-goals: deployment executor, native Git, real SecretStore authentication, or remote production rollout.

Validation: 13 Book Library tests plus live stop/restart/receipt lookup proof passed.

## Server-side maintenance authentication — Chapter 63 follow-on

Implemented: `MaintenanceBearerAuthenticator` verifies the SHA-256 digest configured by
`BOOK_LIBRARY_MAINTENANCE_TOKEN_SHA256`. When configured, both maintenance POST and receipt GET routes require an
exact bearer credential; the raw token is never persisted, logged, or placed in a receipt. An absent digest is
explicitly reported as fixture-only mode and is not a production deployment claim.

Validation: 14 Book Library tests passed. Live configured-server proof returned `401` for a wrong bearer, `200` and a
succeeded receipt for the correct bearer, and a receipt lookup containing no token or authorization value.

## Production binding and atomic code rollout — Chapter 63 follow-on

Added reviewed, explicit-apply deployment helpers for the fixed `library.fountain.coach` publication tuple. The
verifier is provisioned separately from the code rollout and accepts only a SHA-256 digest on stdin. The code
deployer requires a clean, exact commit, transfers an archive with a local digest check, builds an immutable release
on the host, switches `current` atomically, verifies health, and restores the prior release on failure. No raw
credential is stored in the repository, archive, service receipt, or command argument.

Acceptance remains open until the current Reframe commit is deployed, the verifier is configured, and an authenticated
`maintenance.health.verify` operation produces a typed receipt through Reframe.