book-library.git · PLANS.md

revision fa2c4fa4c44a993c676dbea2861e75c6b8756828 · 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.