feat(outbox): govern external delivery receipt evidence

.github/workflows/outbox-delivery-receipt-quality.yml

@@ -0,0 +1,57 @@
+name: Outbox Delivery Receipt Quality
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - "packages/outbox-delivery-receipt/**"
+      - ".github/requirements/foundation-test.txt"
+      - ".github/workflows/outbox-delivery-receipt-quality.yml"
+      - "docs/adr/0151-governed-external-delivery-receipt.md"
+      - "docs/traceability/outbox-delivery-receipt.md"
+      - "docs/doctoring/outbox-delivery-receipt-references.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: outbox-delivery-receipt-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    name: External delivery receipt contract and 100% coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout exact candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Prove exact candidate checkout
+        env:
+          ORGMETRA_EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$ORGMETRA_EXPECTED_HEAD_SHA"
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          check-latest: false
+      - name: Install reviewed test toolchain
+        run: |
+          python -m pip install --require-hashes --no-deps --only-binary=:all: -r .github/requirements/foundation-test.txt
+          python -m pip check
+      - name: Compile delivery receipt package
+        run: python -m compileall -q packages/outbox-delivery-receipt/src packages/outbox-delivery-receipt/tests
+      - name: Test external delivery receipt with exact statement and branch coverage
+        env:
+          PYTHONPATH: packages/outbox-delivery-receipt/src
+          COVERAGE_FILE: /tmp/orgmetra-outbox-delivery-receipt.coverage
+        run: python -m pytest -c packages/outbox-delivery-receipt/pyproject.toml packages/outbox-delivery-receipt/tests
+      - name: Require clean checkout
+        run: |
+          git diff --exit-code
+          test -z "$(git status --porcelain)"

docs/adr/0151-governed-external-delivery-receipt.md

@@ -0,0 +1,77 @@
+# ADR 0151: Govern external transport delivery receipt evidence before outbox completion
+
+- **Status:** Proposed — active PR #151; not protected-main truth
+- **Date:** 2026-08-29
+- **Owners:** Orgmetra integration/audit boundary
+- **Decision scope:** Evidence needed between an external transport response and an
+  authoritative Orgmetra outbox completion transaction
+
+## Context
+
+Protected `develop` already persists immutable audit events and mutable outbox delivery
+state. `complete_outbox_delivery(...)` correctly requires a current tenant-scoped live
+lease, but the protected function does not itself require evidence from the external
+transport that handled the attempt.
+
+ADR 0006 identified external delivery receipts as subsequent work. No open Orgmetra PR was
+found that owned a generic external outbox receipt contract; HR export PR #120 owns a
+different one-time export-egress receipt boundary, and retry-policy PR #82 owns scheduling,
+not transport acknowledgement.
+
+## Decision
+
+Add a standalone package that constructs a value-minimized
+`ExternalDeliveryReceiptEvidence` and verifies exact-attempt correlation.
+
+The evidence binds tenant/outbox/audit/target/attempt, a descriptive transport-provider
+code, a host-normalized opaque receipt reference, SHA-256 of the exact external receipt
+artifact, provider-reported delivery time, host observation time, and evidence version.
+
+External transport evidence remains explicitly untrusted and carries
+`not_authorized_to_mutate_delivery_state`. It excludes raw provider responses and protected
+HR values. Canonical export revalidates every trust-bearing field, including instances
+created through copy or low-level tuple construction, so those construction paths cannot
+bypass fixed safety-state, shape, chronology, or identifier invariants. Separately
+constructed receipts remain untrusted and still require authoritative exact-attempt and
+artifact reconciliation.
+
+Trust-bearing primitive values are accepted only as their exact built-in Python types,
+not caller-defined subclasses whose equality or serialization behavior can be overridden.
+Caller-owned aware datetimes are normalized once during construction into detached,
+built-in UTC `datetime` values before the evidence object retains them. Later changes to a
+caller-owned timezone provider therefore cannot rewrite the canonical JSON or digest.
+Canonical export rejects low-level reconstructed evidence unless both stored timestamps
+are already those frozen built-in UTC values. Exact-attempt verification likewise accepts
+only the exact `ExternalDeliveryReceiptEvidence` type so a subclass cannot override the
+returned digest or other trust behavior.
+
+## Why not modify the outbox migration here
+
+Open Orgmetra stacks already carry many provisional database migrations. Adding another
+durable migration before the evidence contract is reviewed would increase collision and
+restack risk. This slice establishes the package/API evidence boundary first. A subsequent
+authoritative persistence change may bind the canonical receipt digest into outbox
+completion after dependency order permits; it must not backfill or rewrite immutable audit
+history.
+
+## Consequences
+
+- A caller can correlate a normalized external receipt to one exact current outbox attempt
+  before authoritative completion.
+- A receipt cannot by itself authorize `complete_outbox_delivery(...)`.
+- Provider raw payloads, addresses, credentials, HR content, and employment decisions stay
+  out of governance evidence.
+- Receipt replay across retry attempts fails exact-attempt reconciliation.
+- Mutable timezone providers and behavior-overriding primitive subclasses cannot remain
+  embedded in canonical receipt evidence after construction.
+- The contract remains independently extractable as an MSA/API boundary.
+
+## Cryptographic and time references
+
+SHA-256 is used only as deterministic artifact-correlation evidence, not as a signature or
+proof of provider identity. NIST continues to list SHA-2/SHA-256 under FIPS 180-4 while a
+revision of FIPS 180-4 has been announced. UTC `Z` rendering follows the RFC 3339 timestamp
+form with RFC 9557's update to the semantics of `Z`; Orgmetra uses it here simply as a
+canonical zero-offset representation.
+
+See `docs/doctoring/outbox-delivery-receipt-references.md`.

docs/doctoring/outbox-delivery-receipt-references.md

@@ -0,0 +1,25 @@
+# External delivery receipt — primary references
+
+These references support only the narrow cryptographic/time representation decisions in
+PR #151. They do not imply certification, provider authenticity, delivery guarantees, or
+employment-law compliance.
+
+## APA 7 references
+
+National Institute of Standards and Technology. (2015). *Secure Hash Standard (SHS)*
+(FIPS PUB 180-4). U.S. Department of Commerce. https://doi.org/10.6028/NIST.FIPS.180-4
+
+National Institute of Standards and Technology. (2023, March 7). *Decision to revise FIPS
+180-4, Secure Hash Standard (SHS).* https://csrc.nist.gov/News/2023/decision-to-revise-fips-180-4
+
+Sharma, U., & Bormann, C. (2024). *Date and time on the Internet: Timestamps with
+additional information* (RFC 9557). RFC Editor. https://doi.org/10.17487/RFC9557
+
+## Decision notes
+
+- SHA-256 is used for content correlation, not signing. NIST's current CAVP secure-hashing
+  material continues to list SHA-256 in the SHA-2 family under FIPS 180-4; NIST has also
+  announced that FIPS 180-4 will be revised.
+- RFC 9557 updates RFC 3339's interpretation of the `Z` local-offset marker. Orgmetra uses
+  `Z` only to produce one deterministic UTC/zero-offset text representation for evidence
+  hashing; it does not encode a source time zone.

docs/traceability/outbox-delivery-receipt.md

@@ -0,0 +1,34 @@
+# External delivery receipt traceability
+
+**State:** Active PR #151 only. Protected `develop` does not yet expose this package.
+
+| Requirement | Executable evidence | Production boundary |
+| --- | --- | --- |
+| Exact tenant/outbox/audit/target/attempt binding | `test_verifies_only_the_exact_outbox_attempt` | `verify_exact_delivery_attempt` |
+| No HR payload, destination, or credential in the canonical evidence | `test_builds_value_minimized_untrusted_transport_evidence`; fixed-contract parametrization | `ExternalDeliveryReceiptEvidence` fixed safety fields |
+| External receipt remains untrusted and non-authorizing | fixed-contract parametrization; hostile trust-state subclass regression | exact-type fixed-state validation |
+| Opaque normalized receipt identity | receipt-reference parametrization | `_validate_receipt_reference` |
+| Exact provider artifact correlation | digest parametrization | `_validate_digest`, `transport_receipt_digest` |
+| Temporal evidence is detached from caller-owned timezone behavior and canonical UTC; observation cannot predate reported delivery | UTC precision, mutable-timezone, provider-failure, no-offset, and chronology regressions | `_freeze_timestamp`, `_canonical_timestamp`, `_validate_contract` |
+| Trust-bearing text cannot retain behavior-overriding `str` subclasses | exact-attempt equality and fixed trust-state subclass regressions | exact built-in primitive validation |
+| Receipt subclasses cannot override verification/digest behavior | `test_exact_attempt_verification_rejects_receipt_subclasses` | exact-type check in `verify_exact_delivery_attempt` |
+| Retry replay cannot cross attempt boundaries | exact-attempt mismatch regression | `delivery_attempt_count` in reconciliation tuple |
+| Copy/low-level reconstruction cannot bypass fixed safety/trust invariants | `test_copy_bypass_cannot_create_a_second_canonical_truth` | canonical export revalidation |
+| Structural mutation is rejected | `test_evidence_is_structurally_immutable_after_construction` | tuple-backed evidence type |
+| Exact owned statement/branch coverage | hosted `Outbox Delivery Receipt Quality` | pytest-cov gate at 100% |
+
+## Upstream protected-main truth
+
+- `database/migrations/0003_audit_outbox_persistence.sql` owns immutable audit events and
+  durable outbox state.
+- `database/migrations/0005_outbox_delivery_finalization.sql` owns live-lease completion
+  and retry mutation.
+- This PR does not change either migration and does not claim a durable receipt column.
+
+## Downstream acceptance
+
+Before any later durable receipt persistence or `delivered` transition is considered
+commercial truth, the authoritative host must re-resolve the current tenant-scoped leased
+attempt, verify the raw external artifact against the stored digest, preserve immutable
+audit evidence, and pass the then-current exact-head migration/recovery/security/review
+gates.

packages/outbox-delivery-receipt/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## Unreleased
+
+- Define value-minimized external transport delivery receipt evidence.
+- Bind receipts to an exact tenant/outbox/audit/target/attempt coordinate.
+- Keep transport evidence untrusted and explicitly non-authorizing for delivery-state
+  mutation.
+- Require canonical UTC chronology, opaque normalized receipt references, SHA-256 artifact
+  correlation, structural immutability, copy-bypass revalidation, and exact 100% owned
+  statement/branch coverage.
+- Detach caller-owned timezone behavior into built-in UTC timestamps before evidence is
+  retained, reject behavior-overriding trust/identifier string subclasses, and reject
+  receipt subclasses at exact-attempt verification so canonical evidence and returned
+  digests cannot be rewritten through caller-controlled runtime behavior.

packages/outbox-delivery-receipt/README.md

@@ -0,0 +1,50 @@
+# Orgmetra external delivery receipt evidence
+
+This package gives Orgmetra a small, value-minimized evidence object for the moment an
+external transport reports that one outbox attempt was delivered.
+
+It **does not** mark an outbox row delivered. A transport response is untrusted evidence.
+The authoritative Orgmetra host must re-read the live tenant-scoped leased attempt, verify
+the normalized receipt artifact, apply purpose-bound authorization, and persist its own
+immutable audit/outbox evidence in the same governed completion transaction.
+
+## What the evidence binds
+
+`ExternalDeliveryReceiptEvidence` binds one exact:
+
+- tenant, outbox delivery, and audit event;
+- delivery target and attempt number;
+- transport provider code;
+- host-normalized opaque `transport_receipt:<UUIDv4>` reference;
+- SHA-256 digest of the exact external receipt artifact;
+- provider-reported delivery instant and host observation instant; and
+- evidence version.
+
+The canonical packet never carries the HR payload, destination address, credentials,
+compensation, assessment/rating values, free-form model output, or an employment decision.
+
+## Safe next action
+
+Call `verify_exact_delivery_attempt(...)` only after resolving the authoritative current
+outbox attempt. A successful match returns the canonical evidence digest for correlation;
+it is still **not** permission to call `complete_outbox_delivery(...)`. The host must verify
+the external receipt artifact against `transport_receipt_digest` and complete its normal
+lease, authorization, audit, and persistence checks.
+
+## Integrity model
+
+The public evidence type is a tuple-backed immutable value. Ordinary mutation through
+`setattr` or `object.__setattr__` fails. Canonical export also revalidates every
+trust-bearing field, so copy helpers or low-level tuple construction cannot bypass the
+fixed safety-state, shape, chronology, or identifier invariants. A separately constructed
+receipt is still untrusted evidence and must independently match the authoritative exact
+attempt plus the external receipt artifact before any governed completion can occur.
+
+This is an application evidence contract, not a digital-signature scheme. Durable
+cross-process authenticity and retention belong to the authoritative persistence and
+audit/outbox boundary.
+
+## Current integration status
+
+This package is proposed by PR #151. Until that PR integrates into protected `develop`,
+it is active-PR truth, not a commercially available protected-main capability.

packages/outbox-delivery-receipt/SECURITY.md

@@ -0,0 +1,26 @@
+# Security and privacy boundary
+
+External transport receipts are attacker-controlled input until reconciled by Orgmetra.
+
+The contract therefore:
+
+- treats transport evidence as `untrusted_transport_evidence`;
+- binds it to one tenant/outbox/audit/target/attempt coordinate;
+- stores only a host-normalized opaque reference and SHA-256 digest, not raw provider
+  response bodies;
+- excludes HR payloads, destinations, credentials, free-form text, compensation, ratings,
+  assessment outcomes, and model output;
+- rejects noncanonical/sentinel UUID identities, malformed governance codes, non-UUIDv4
+  normalized receipt references, invalid digests, unbounded attempt/version values, and
+  impossible observation chronology;
+- revalidates trust-bearing fields on canonical export to catch copy/bypass-created
+  instances; and
+- never grants authority to mutate `outbox_delivery_record`.
+
+A consumer must not interpret a provider-reported receipt as proof that the intended human
+or system actually consumed the message. It is evidence that the configured transport
+reported delivery for the correlated attempt. Downstream business semantics need their
+own explicit acknowledgement contract.
+
+No secret, provider token, destination address, or raw transport payload belongs in this
+evidence packet or routine logs.

packages/outbox-delivery-receipt/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orgmetra-outbox-delivery-receipt"
+version = "0.1.0"
+description = "PII-minimized external transport delivery receipt evidence for Orgmetra outbox reconciliation."
+requires-python = ">=3.12"
+
+[project.optional-dependencies]
+test = ["pytest>=8.3", "pytest-cov>=5.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--cov=orgmetra_outbox_delivery_receipt",
+  "--cov-branch",
+  "--cov-report=term-missing",
+  "--cov-fail-under=100",
+]

packages/outbox-delivery-receipt/src/orgmetra_outbox_delivery_receipt/__init__.py

@@ -0,0 +1,13 @@
+"""Public contract for Orgmetra external outbox delivery receipt evidence."""
+
+from .receipt import (
+    ExternalDeliveryReceiptEvidence,
+    build_external_delivery_receipt_evidence,
+    verify_exact_delivery_attempt,
+)
+
+__all__ = [
+    "ExternalDeliveryReceiptEvidence",
+    "build_external_delivery_receipt_evidence",
+    "verify_exact_delivery_attempt",
+]