# V9-001 transactional verification-governed promotion

Date: 2026-07-25

Source commit: `5fbf04e9aec333287b642952bfd0fe00f098ddf5`

## Claim

Metis now has a fail-closed, cross-language promotion boundary. The trusted
TypeScript verification runtime can issue a signed `metis-p0-v1` receipt only
for an exact lesson body that received an automatic `pass` from every required
P0 verifier. The Python source forge independently validates that receipt and
uses it as a mandatory admission condition for promotion.

This evidence closes only the V9-001 transactional-evidence and
TypeScript-governs-Python-promotion task. It does not claim a production source
bundle, a live provider run, final publication signing, an adaptive rendered
experience, or learner delivery.

## Authority and fail-closed conditions

The TypeScript receipt builder:

- binds `lessonId`, run, model, exact content SHA-256, gate decision, aggregate
  score, timestamp, and sorted release-relevant verifier results;
- requires `factuality`, `faithfulness`, `citation-sufficiency`,
  `code-correctness`, `process-correctness`, and `pedagogical-quality`;
- rejects a missing, unconfigured, failed, below-threshold, non-pass, or
  content-mismatched result;
- hashes stable cross-language material and signs that digest with HMAC-SHA256;
- refuses signing secrets shorter than 32 characters.

The Python promotion service:

- fails closed when the verification signing secret is unconfigured;
- requires the package version and persisted manifest to remain approved and
  high-stakes allowed;
- requires persisted extraction, outline, generation, and evaluation artifacts;
- admits only a fully `model_generated` build with no template fallback;
- requires a passing evaluation bound to the exact current generation and a
  generation bound to the exact current outline;
- requires one unique signed TypeScript receipt for every generated lesson and
  no extra receipts;
- recomputes content hashes, required P0 results, receipt digests, and HMACs;
- rejects a changed generation digest and rechecks every prerequisite digest
  immediately before persistence.

## Transactional stage/node evidence

One successful promotion atomically records:

1. the approved source-package manifest;
2. normalized source extraction;
3. grounded outline;
4. model-authored generation;
5. grounded evaluation;
6. one TypeScript P0 verification node per lesson.

Each node carries its artifact kind, stage, content SHA-256, storage reference,
and dependency node IDs. Verification nodes additionally carry the TypeScript
run ID and signed receipt digest. The final `promotion.json` is written through
an fsynced temporary file, atomic replace, and directory fsync. A simulated
replace failure proves that neither a partial promotion file nor a temporary
file remains.

## Cross-language proof

Both the TypeScript and Python suites independently derive and assert these
values from the same fixed lesson, P0 results, model, run, timestamp, and test
secret:

| Binding                 | SHA-256 / HMAC-SHA256                                              |
| ----------------------- | ------------------------------------------------------------------ |
| Lesson content          | `b4bb7a521ca9b6fc4a86b6dad4f0db3a6b6467587655b70e37865d0edcfe888d` |
| Stable receipt material | `ca41b5d5bc04a5aacda9fe0959b2a3afa74e841547adeb11a7eb4eac25546773` |
| Receipt signature       | `85bfde83c6c84ef4ddbe784d2723914bbe5068ee9f40e8005fee4fe1ec22c34f` |

The matching constants prove that the producer and consumer agree on the exact
signed bytes, rather than merely implementing similarly named schemas.

## Verification

| Gate                                               | Result                       |
| -------------------------------------------------- | ---------------------------- |
| Full `libs/metis/verification/src` Vitest suite    | 24 files, 176 tests passed   |
| Source subsystem plus OpenAPI contract pytest      | 109 passed, 2 expected skips |
| Direct Python promotion service tests              | 8 passed                     |
| Python Ruff                                        | Passed                       |
| Python strict MyPy over changed production modules | Passed                       |
| Isolated strict TypeScript receipt typecheck       | Passed                       |
| TypeScript ESLint and Prettier                     | Passed                       |
| `pnpm metis:contracts:check`                       | Passed                       |

The package-level TypeScript typecheck remains blocked by an unrelated
pre-existing `libs/shared/tracing/src/genai.ts` union that does not include the
already-published `v7-flagship-revision` source kind. The new receipt module
passes an isolated strict TypeScript check.

## Source hashes

| File                                                                | SHA-256                                                            |
| ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `libs/metis/verification/src/provenance/promotion-receipt.ts`       | `61eeb693fb7bdd4c7dfb33b4002f343bdc7b58b04096dafea80c0d4fb79a025d` |
| `libs/metis/verification/src/provenance/promotion-receipt.spec.ts`  | `cb6ab9ee70039fd901e0b8c0b532780c21fc3bab39143b9de370c71b24172e09` |
| `apps/metis/service/src/metis/schemas/source_promotion.py`          | `5f38e0a1ae5ad8f703f488a97842a0cac2d6b1449846814f5a84d1731fe42e53` |
| `apps/metis/service/src/metis/services/source_promotion_service.py` | `c6a9e9adf0f25dde3adecc6141bb72ca9549b0d5b0d4a4a4a89b7c3e019d549a` |
| `apps/metis/service/tests/test_source_promotion_service.py`         | `f01c84f44e87e0135aebb8b1a7f2d1bb1d27e1df15229d17035f8381d77db62e` |
| `apps/metis/service/src/metis/api/source_ingestion.py`              | `d5865f31c7942d8b3ae64cd5ca014eec8a555a13299d6c2d03d9ed899cfb9e87` |
| `apps/metis/service/openapi/metis.openapi.json`                     | `19c971acaf6d4e7629275920d7ddd2a72430061d3c5b4972428b5f6c2e7632c7` |
| `libs/openapi/src/generated/metis.ts`                               | `d9ae799c99e039e25e465e0f26fab7bc8e30f3eda73a895d64dc21943257eea1` |

## Remaining boundary

No live model execution or real approved production source package was used in
this slice. The separate V9-001 approved-source/entailment box and the full
adaptive-render-review-sign-deliver production-path box therefore remain open.
