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:
- a mutation to signed promotion metadata;
- a forged promotion signature;
- a changed prerequisite file after promotion; and
- 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 |