Eve library

V9-001 authenticated promotion reads

Evidence

Revision 1

On this page

Date: 2026-07-27

Claim#

The Metis source-promotion ledger is no longer write-verified but read-trusting. Every new promotion carries a domain-separated SHA-256 receipt and HMAC-SHA256 signature over the complete canonical response. Every downstream get_promotion() read authenticates that receipt and revalidates its immutable artifact and verification dependencies before returning it.

This is a repository-owned hardening increment for the authoritative promotion handoff. It does not claim the still-missing production source bundle, live provider evidence, adaptive rendering, final human review, publication signature, or learner delivery required to close the compound V9-001 boxes.

Read-time authority#

A stored promotion is returned only when all of the following remain true:

  • the service has a promotion-verification secret of at least 32 characters;
  • the requested package ID matches the signed response;
  • the domain-separated canonical response digest and its HMAC are valid;
  • the five prerequisite nodes are present exactly once with canonical IDs, stages, storage paths, dependency edges, and no verification-only metadata;
  • the approved manifest, extraction, outline, generation, and evaluation files still exist and retain their promoted SHA-256 digests;
  • the top-level generation and evaluation digests agree with their graph nodes;
  • lesson receipts and TypeScript P0 nodes have unique, exact lesson coverage;
  • every nested TypeScript receipt digest and HMAC remains valid;
  • every TypeScript node retains its canonical stage, content digest, run, storage reference, receipt digest, and generation/evaluation dependencies;
  • the deterministic promotion ID still binds the package version, generation, evaluation, and complete sorted lesson-receipt set.

Older unsigned promotion files fail schema validation instead of being silently trusted. The OpenAPI response and generated TypeScript client now expose the required receipt_sha256 and signature fields.

Adversarial proof#

The direct promotion suite demonstrates that downstream reads reject:

  1. a mutation to signed promotion metadata;
  2. a forged promotion signature;
  3. a changed prerequisite file after promotion; and
  4. a noncanonical dependency graph even when the test re-signs that malformed record with the configured authority secret.

The successful path independently recomputes and asserts both the outer receipt digest and signature, then proves that the authenticated read returns the exact promotion response.

Verification#

Gate Result
Direct promotion service suite 12 passed
Source subsystem plus OpenAPI contract/export pytest 116 passed, 2 expected skips
Python Ruff over changed Python files Passed
Strict MyPy over changed production modules Passed
pnpm metis:contracts:check Passed
Generated Metis OpenAPI TypeScript client freshness Passed

The repository pre-commit affected-typecheck maps the generated shared client to the entire Oshun web application. It remains blocked by three unrelated existing errors in apps/oshun/web/src/components/studio/__tests__/support/study-axe.ts: the current workspace cannot resolve axe-core, which also leaves the violation and node callback parameters implicitly typed as any. This slice does not modify that test or the web application's dependency graph.

Source hashes#

File SHA-256
apps/metis/service/src/metis/schemas/source_promotion.py 90787bafb85d82b9d017eec45421cac6a4996be646c4af9c5db84ce0670af4e0
apps/metis/service/src/metis/services/source_promotion_service.py 1fa68928b10074fcc515e8a38d5defb0ed8bd1cef32e4b750cba2aabd00fe31a
apps/metis/service/tests/test_source_promotion_service.py ccd29576ed4faf4a0581e62ad9658cca37b62a4ea2f569091deee76f434d2bb1
apps/metis/service/openapi/metis.openapi.json 260bcc0f6acd112982ca187eb8e619e94c71d95de239cd05308255443474a1ac
libs/openapi/src/generated/metis.ts cb7270d98631f1088a668ef37b50ae6e9d1fde2333f19eb4c4af3fdf7c06d2bd