book-library.git · README.md

revision b74ab7882c763c01c2c66e5245c3979a47c88a49 · complete file

# Book of Reframe Source Library

Standalone Swift source provider for the curated Book of Reframe library.

This repository is outside Fountain-Store. It owns source provenance, curated publication manifests, normalized
fixtures, withdrawal state, and the HTTP/OpenAPI projection. Reframe consumes it as a source provider beside DraCor
and local-file input; FountainStore remains the persistence authority after import.

## Local fixture server

```sh
swift test
swift run book-library-server Fixtures/library
curl http://127.0.0.1:8787/v1/catalog
```

The fixture is intentionally owned test content. It is not a claim about the legal status of any external work.
Production entries require item-level provenance, rights, jurisdiction, attribution, and transformation review.

## Acquisition and promotion

The `book-library-importer` executable is a remote staging tool. It accepts one explicit HTTPS source edition and
writes an isolated `review-required` candidate; it never changes the published `current` release. After approval,
`Deploy/promote-candidate.sh` copies the candidate to a new immutable release, switches `current` atomically, and
verifies the service. Reframe is read-only with respect to this service.

Example candidate acquisition (metadata is part of the review record):

```sh
swift run book-library-importer \
--source-url https://www.gutenberg.org/cache/epub/1342/pg1342.txt \
--work-id gutenberg-pride-and-prejudice-1342 \
--title "Pride and Prejudice" --author "Jane Austen" \
--edition "Project Gutenberg eBook 1342, plain text edition" \
--rights "item notice reviewed" \
--jurisdiction "US reviewed; other jurisdictions separately reviewed" \
--attribution "Project Gutenberg eBook 1342: https://www.gutenberg.org/ebooks/1342" \
--candidate-root /var/lib/book-library/candidates/gutenberg-pride-and-prejudice-1342 \
--provider-release candidate-YYYYMMDD
```

This creates a candidate only. A human must inspect the manifest and explicitly promote it with the deployment skill.

The managed server also exposes the governed promotion boundary for an already staged candidate. It requires an
idempotency key and an explicit approver, returns a pollable `libraryPromotion` receipt, creates a new immutable
release, records the previous release as rollback evidence, and atomically switches `current`. Promotion never
re-imports the release into Reframe:

The server authorization boundary is configured with `BOOK_LIBRARY_APPROVERS`, a comma-separated allowlist of approved
reviewer identities. An arbitrary `approvedBy` value is rejected; no Reframe client can grant itself publication
authority.

```sh
curl -X POST https://library.fountain.coach/v1/library/candidates/<candidate-operation-id>/promote \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: promote-<candidate-operation-id>-<release-id>' \
-d '{"candidateID":"<candidate-operation-id>","releaseID":"<release-id>","approvedBy":"<approver>"}'
```

## Curated classical candidates

The reproducible classical build uses Gutenberg plain-text sources and explicit navigation metadata:

```sh
python3 Scripts/build-classical-candidates.py --output /tmp/classical-candidates
```

It produces Ulysses eBook 4300 with the 18 Gilbert-named episodes, and the Riley Metamorphoses eBooks 21765 and
26073 with Book-grouped FABLE units. Both remain `review-required` until an approver promotes them. Promotion writes
the release ID into the provider and work manifests, records an approval receipt, and makes the chapter/Myth metadata
available through `/v1/works/{work}/chapters`.

## Portability

The service is configured by DNS at deployment time. The migration package consists of the provider release manifest,
work manifests, source content, hashes, deployment configuration, Git project bundles, refs, and restore verification.
No Reframe client may hardcode a server IP.

Managed Git projects can be moved without changing their project IDs or revision IDs:

```sh
Deploy/export-git-state.sh /srv/fountain-git/my-project /srv/migration
Deploy/import-git-state.sh /srv/migration/my-project.bundle /srv/fountain-git-restored my-project
Deploy/verify-git-migration.sh /srv/fountain-git/my-project /srv/fountain-git-restored/my-project
```

Bundles contain Git objects and refs only. SecretStore credentials, ACL secrets, endpoint configuration, and TLS keys
are re-established on the destination and are never exported. DNS/HTTPS cutover and rollback remain deployment
operations, followed by the provider health/catalog and Reframe handoff checks.