# V9-001 signed publication and learner delivery

Date: 2026-07-27

## Claim

Metis now has a repository-owned, fail-closed path from an authenticated source
promotion through deterministic adaptive packaging, safe experience rendering,
administrator inspection and review, canonical continuous-recertification
admission, signed atomic release, audience-gated learner delivery, and a signed
immutable delivery receipt.

This closes the previously missing software integration after the source
promotion ledger. It does **not** close the compound V9-001 production-path
checkbox. The repository still lacks an authorized production source run, live
provider output, a real administrator's review, a real learner delivery, and
production operational evidence for this exact end-to-end path.

## Authoritative chain

The publication service accepts only the exact generation referenced by
`SourcePromotionService.get_promotion()`. That read reauthenticates the outer
promotion, every prerequisite artifact, and every nested TypeScript P0 receipt.
Publication then enforces the following boundaries:

1. An instructor who owns the promoted course/workspace/notebook scope, or an
   administrator, creates a content-addressed candidate for an explicit,
   duplicate-free learner audience.
2. The candidate rebuilds and binds the canonical promoted content. It includes
   the complete assessment questions, plain-text study artifacts, escaped static
   lesson HTML, per-lesson content/rendering hashes, and the exact P0
   verification receipt for every lesson.
3. The adaptive plan binds deterministic prerequisites, assessment routing,
   remediation, and the requested mastery threshold. Cold-start profiles use
   `awaiting_first_graded_evidence`; missing evidence always produces
   `preserve_and_abstain`, never invented mastery.
4. Only an administrator can inspect the exact candidate and record a review.
   The decision is bound to the candidate digest, reviewer identity, comment,
   and idempotency key, then protected by a domain-separated SHA-256 receipt and
   HMAC-SHA256 signature.
5. Only an exact signed `approve` review plus a current authenticated REL-003
   admission can create a release. The admission can only be issued after the
   canonical graph/backlog/evidence/exercise evaluator allows release and binds
   its decision, policy, graph revision, current input fingerprint, affected
   slots, exact candidate digest, and expiry.
6. The immutable release archive binds the source promotion, candidate, review,
   recertification admission, audience, publisher, and learner endpoint. A
   mutable live pointer is replaced only after the immutable archive is durable.
7. Every learner read revalidates the complete promotion-to-release chain,
   compares the live record to its immutable archive, reauthenticates the
   admission and refuses it after expiry, and checks exact audience membership
   before returning any content.
8. Each successful learner response is itself content-addressed, signed, and
   durably created under the publication delivery archive before it is returned.

The publication signing, TypeScript P0/promotion verification, and
recertification admission secrets are three separate trust boundaries and each
must contain at least 32 characters. Candidate, review, release, and delivery
identifiers are validated before being used in storage paths. Immutable writes
use an fsynced temporary file plus a no-replace hard link so concurrent writers
cannot silently overwrite an audit record.

## Adversarial and API proof

The focused suite proves:

- source-scope ownership and signing configuration fail closed;
- an instructor cannot inspect the administrator review payload or self-review;
- an administrator can inspect only an exact, reverified candidate;
- non-approval cannot publish and a learner outside the signed audience cannot
  receive content;
- unsafe source markup is escaped and assessment/study content survives the
  rendering boundary without answer-key leakage or executable HTML;
- candidate, review, live release, and promoted-generation mutation are rejected
  on delivery;
- recomputing a candidate hash over noncanonical rendered content does not make
  it reviewable;
- a review idempotency key cannot authorize different input;
- blocked lifecycle state cannot issue an admission, and forged, wrong-artifact,
  future, expired, or unconfigured admissions cannot publish;
- a restarted service rechecks persisted admission freshness and stops delivery
  after expiry;
- a simulated failure while replacing the live pointer leaves one immutable
  release, no partial live publication, and no temporary residue; a retry
  recovers;
- the returned learner delivery receipt and HMAC independently recompute and the
  exact response is present in the immutable delivery archive.

## Verification

| Gate                                                         | Result                                                                  |
| ------------------------------------------------------------ | ----------------------------------------------------------------------- |
| Focused publication service and API suite                    | 18 passed                                                               |
| Complete source subsystem suite                              | 114 passed, 2 expected skips                                            |
| Publication/promotion/OpenAPI/export integration suite       | 50 passed                                                               |
| Canonical REL-003 issuer and graph suite                     | 88 passed                                                               |
| Extraction skip audit                                        | Pillow and python-docx unavailable; 5 remaining extraction tests passed |
| Python Ruff over changed production/tests                    | Passed                                                                  |
| Strict MyPy over changed production modules                  | Passed                                                                  |
| `pnpm metis:contracts:check`                                 | Passed                                                                  |
| Checked-in OpenAPI and generated TypeScript client freshness | Passed                                                                  |
| `git diff --check`                                           | Passed                                                                  |

No browser or mobile UI changed in this increment, so Playwright/mobile UI
coverage is not applicable. The API authority path is exercised through
FastAPI's `TestClient`.

## Source hashes

| File                                                                     | SHA-256                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `.env.example`                                                           | `54097d7a5a064c2a2880420292871893770728cc51662572f3fef78b6d2f1ab1` |
| `apps/metis/service/src/metis/config.py`                                 | `42d6f2c385db74d25749e7778b007cb270190f7e0552679b8b089c59088ff6c4` |
| `apps/metis/service/src/metis/schemas/source_publication.py`             | `9ef1d83c3871696ff9459b2131f55a73fbbff4f8b415543d904f0444659ac27c` |
| `apps/metis/service/src/metis/services/source_publication_service.py`    | `ddbccb617f8a426a4bf82e480922c44047ef470929da1917ea8b2ab7a50876e9` |
| `apps/metis/service/src/metis/api/source_ingestion.py`                   | `6f994c52fed033561cff8453a14141ef455b50e07490e9bf4bd76abfa13f16c8` |
| `apps/metis/service/tests/test_source_publication_service.py`            | `8cbd6b3df1bcfe2c47e2133c5608827618af292bed1ece6493e962579f9c23ca` |
| `apps/metis/service/openapi/metis.openapi.json`                          | `971047214cd2724a035fc8aeb16ddbbd716572e5b1472ba34c1d8c2398788ee1` |
| `libs/openapi/src/generated/metis.ts`                                    | `31a27bf6ad2eb89c2e17be604484a0c4b25bcd0b78745aeedd88a39235a9bc86` |
| `libs/contracts/src/content-coverage/continuous-recertification.ts`      | `61c035343c10daddd07cba0bbe59216fe8624493a395c2e2d13bf141fc2e7296` |
| `libs/contracts/src/content-coverage/continuous-recertification.spec.ts` | `0c6a0cc392830d2e83773b91fd4b88369f8de73b3067cbab3691de9a5815d008` |
