WS-XINT-003-02D: publish REV authorization integration contracts

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/ACTION_CUSTODY.md

@@ -32,7 +32,7 @@ This table is the planning source of truth for the v0.1 review and human-revisio
 | `review.artifact_reference.reconcile` | `operations.reconcile.run` | fixed artifact-reference reconciler only | bounded review artifact reference batch | REV | registered planned | `WS-XINT-003-08B` |
 | `review.projection.rebuild` | `operations.projection.rebuild` | fixed projection rebuilder only | derived review projection batch | REV | registered planned | `WS-XINT-003-08B` |
 
-The 19 registered `review.*` rows move from historical `AUTH_REV_*` planning labels to these exact XINT-003 waves only as planning custody. Their runtime `ActionOwner` values change with each later activation, never in 01.
+The 19 historically transferred `review.*` rows move from `AUTH_REV_*` planning labels to these exact XINT-003 waves only as planning custody. Their runtime `ActionOwner` values change with each later activation, never in 01.
 
 ## Fixed-service closure
 
@@ -78,6 +78,18 @@ Activation chunks may not add ActionIds, PermissionIds, service identities,
 resource-context classes, adapter protocols, lifecycle rules, or product routes.
 Any such discovery returns to 02C/02D planning.
 
+`WS-XINT-003-02D` publishes the code-level closed manifest in
+`backend/app/modules/authorization/review_contracts.py`. Its strict frozen
+models are inert integration contracts: scalar canonical IDs, closed action and
+mode discriminators, digests, bounded reasons, and timezone-aware timestamps.
+They are not runtime evaluators and do not make a planned action executable.
+REV owns row locking and final-fact composition; later XINT activation adapters
+must consume these exact families without adding another context family. The
+two fixed identities sharing `review.reconcile.run` are bound to disjoint
+server-derived modes. The two future evidence-ingest actions have explicit
+unsupported manifest rows with no resource model. XINT-002 artifact/submission
+actions remain reference-only external handoffs.
+
 | ActionId | Exact prerequisite behavior/manifest |
 |---|---|
 | `project.review_policy.update` | 02A immutable identity/lineage plus refreshed REV-03P/AUTH-12D2; activated only by `WS-XINT-003-02B` |

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md

@@ -152,3 +152,21 @@ The first hosted semantic lanes exposed the expected post-0049 public-schema
 fingerprint change before running product tests. The chunk contract now permits
 only that exact `tests/conftest.py` fingerprint update; no reset allow-list or
 schema-integrity behavior changed.
+
+## WS-XINT-003-02D AUTH PREP integration readiness
+
+Architecture, security/auth, product/operations, QA, senior engineering, CI
+integrity, reuse/dedup, test-delta, and docs reviewers examined the inert typed
+contract manifest. Valid findings split concealed no-work results from queue
+lineage, made initial and revised decisions mutually exclusive, bound exact
+revision predecessor/response facts, required lifecycle adjacency proof, and
+closed lease, preference, and revision-preparation state vocabularies.
+
+The manifest covers all 23 `review.*` actions while every row remains planned.
+The two future evidence-ingest actions remain unsupported, XINT-002 actions are
+reference-only, and no evaluator, route, background execution code, migration, or REV lifecycle
+behavior is added. Fifteen contract tests and three existing PREP regression
+tests pass; changed-module coverage is 100.00 percent. CodeRabbit's four valid
+findings corrected operator-read documentation, guide-repair fact wording,
+the true-only no-self-review proof, fixed-service execution-mode closure, and
+annotation-based inertness proof. Corrective exact-head CI remains required.

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md

@@ -2,9 +2,10 @@
 
 ## Current status
 
-WS-XINT-003-01, WS-XINT-003-02A, and WS-XINT-003-02B are merged. PR #248 merged
-02B as `25fc27c4` on 2026-08-03 after Backend, Agent Gates, and CodeRabbit passed
-on the final PR head. Exactly `project.review_policy.update` and
+WS-XINT-003-01, WS-XINT-003-02A, WS-XINT-003-02B, and WS-XINT-003-02C are
+merged. PR #255 merged 02C as `745d9c3f` on 2026-08-03 after Backend, Agent
+Gates, and CodeRabbit passed on the final PR head. Exactly
+`project.review_policy.update` and
 `project.revision_policy.update` are active; review/revision lifecycle actions
 remain planned or unavailable.
 
@@ -29,8 +30,9 @@ REV-owned semantics with AUTH-owned mutation authorization.
   materialization. Evidence binding remains planned/unavailable and 07B is
   reserved pending separate REV-owned intent.
 - All 23 registered review/revision lifecycle actions remain planned; 02C adds
-  the four recovery/lifecycle rows and six fixed-service identities without
-  provisioning or authority. The superseded 08R placeholder is never executable. The
+  the four recovery/lifecycle rows and provisions/admits six fixed-service
+  identities without execution authority because every associated lifecycle
+  action remains unavailable. The superseded 08R placeholder is never executable. The
   two policy mutation actions activated by 02B are setup authority, not
   lifecycle activation.
 
@@ -49,9 +51,10 @@ REV-owned semantics with AUTH-owned mutation authorization.
 
 ## Next step
 
-Complete WS-XINT-003-02C evidence and review, then merge it before 02D. 02C and
-02D front-load the complete unavailable catalogue, fixed-service matrix, and
-fail-closed PREP contracts that REV needs before it begins its full lifecycle
-implementation. Do not infer review lifecycle
+WS-XINT-003-02D implements the complete typed, fail-closed PREP/read contract
+handoff on top of merged 02C. Its merge permits REV to begin hidden lifecycle
+implementation against that stable surface. AUTH then returns to its independent
+agenda; later XINT activation waves reconnect only to exact merged REV behavior.
+Do not infer review lifecycle
 activation from readiness: later action activation still requires exact merged
 REV behavior and integrated proof.

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02D-auth-prep-integration-readiness.md

@@ -2,8 +2,7 @@
 
 ## Status
 
-Proposed planning contract after 02C. Refresh exact files and verification
-commands from current `main` before implementation.
+Implementation-ready contract refreshed from merged 02C at `745d9c3f`.
 
 ## Parent initiative
 
@@ -29,17 +28,21 @@ SLA.
 
 ## Allowed files
 
-Refresh to exact current-main paths within:
+Only these exact paths may change:
 
 ```text
-backend/app/modules/authorization/runtime.py
-backend/app/modules/authorization/prepared.py
-backend/app/modules/authorization/kernel.py
-backend/app/modules/authorization/<bounded REV integration contract modules>
-backend/tests/<bounded authorization and PREP tests>
+backend/app/modules/authorization/review_contracts.py
+backend/scripts/run_test_lanes.py
+backend/tests/test_review_authorization_contracts.py
 docs/spec_authorization_service.md
 docs/spec_review_lifecycle.md
-.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/**
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/ACTION_CUSTODY.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/STATUS.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/REVIEW_LOG.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/chunks/WS-XINT-003-02D-auth-prep-integration-readiness.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-02D-internal-review.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-02D-pr-trust-bundle.md
+.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-02D-external-review-response.md
 ```
 
 ## Not allowed changes
@@ -51,6 +54,68 @@ docs/spec_review_lifecycle.md
   serialized prepared handle.
 - No omnibus nullable resource context, generic dictionary/service locator,
   local REV policy engine, fallback authority, or role-only shortcut.
+- No edit to `runtime.py`, `prepared.py`, `kernel.py`, `catalogue.py`, service
+  identity registration, migrations, routes, background execution code, or REV
+  product code.
+- No XINT-002 contract implementation. Shared ART/submission rows are manifest
+  references only and retain their existing owners, types, and activation gates.
+
+## Closed contract families
+
+`review_contracts.py` publishes strict frozen Pydantic models containing only
+scalar identifiers, closed enums, digests, bounded reasons/timestamps and
+server-composed booleans/counts. It defines no repository, loader, evaluator,
+callback, ORM value, byte-bearing field, or authorization handle. The manifest
+maps every XINT-003 action below to exactly one family and execution mode.
+
+| Contract family | Exact XINT-003 actions | Required final facts |
+|---|---|---|
+| concealed queue | `review.queue.read` | a minimal `none` shape contains project, reviewer/grant, policy, phase and queue-state digest only; offer/active-lease shapes additionally bind queue entry/lease when present, task, assignment, Submission, CheckerRun admission, no-self-review actors and exact lineage |
+| claim | `review.claim` | concealed-queue facts plus claim operation, idempotency, queue generation, reviewer global active-lease count, reviewer contribution-policy identity/generation/digest, packet-manifest digest |
+| lease mutation | `review.release`, `review.lease_expiry.run`, `review.lease.force_release` | project, queue entry, lease/generation, reviewer, task, Submission, lease status/expiry, lifecycle phase, reason or due boundary, lease-state digest |
+| preference mutation | `review.decline_preference`, `review.preference_expiry.run` | project, queue entry, preference/generation, preferred reviewer, source Review, source Submission, status/expiry, reason or due boundary, preference-state digest |
+| reviewer reads | `review.context.read`, `review.chain.read` | project, task, assignment, exact active lease/reviewer, packet manifest, current Submission and binding, chain boundary/digest, lifecycle phase; chain read also binds requested subject actor and bounded cursor |
+| decision | `review.decision` | mutually exclusive `initial` and `revision` shapes both bind project, task, assignment, current Submission, CheckerRun admission, queue entry, active lease/reviewer, packet manifest, Review operation, decision, findings/resolution digest, ReviewPolicy and reviewer ContributionPolicy freezes, artifact hash and lifecycle digest; the revision shape additionally requires a distinct predecessor Review/Submission, revision episode, exact preparation head generation/digest, and finding-response lineage/count |
+| operator queue read | `review.queue.inspect` | bounded project/shard, filter digest, bounded cursor, redaction state, lifecycle phase/digest |
+| operator queue mutation | `review.queue.routing.override`, `review.queue.routing.correct`, `review.queue.close` | project, queue entry/generation, task, Submission, current routing/lease facts, requested mode, canonical reason, lifecycle phase/digest |
+| reconciliation | `review.reconcile.run` | fixed execution mode, project/shard, trigger, bounded cursor, finding IDs digest, observed watermark/time, lifecycle phase/digest |
+| artifact-reference reconciliation | `review.artifact_reference.reconcile` | project/shard, exact review/reference set digest, bounded cursor, reason, observed watermark, lifecycle phase/digest |
+| projection rebuild | `review.projection.rebuild` | named projection, project/shard, source watermark, bounded cursor, source-event digest, lifecycle phase/digest |
+| revision repair | `review.revision_context.repair` | project, task, source/current assignment, prior Submission, originating needs-revision Review, episode, exact head ID/digest/generation, canonical `kept`/`rebased`/`blocked` outcome and forward/backward direction, server-proven repairability, current guide ID/activation sequence and ReviewPolicy/RevisionPolicy identity triples, replacement assignment when any, canonical reason, lifecycle digest |
+| revision obligation close | `review.revision_obligation.close` | project, task, assignment, originating needs-revision Review, episode/head, frozen revision-policy identity/generation/digest, approved limit/deadline facts, exact reached cause, lifecycle digest |
+| legacy close | `review.revision_context.legacy_close` | reconciliation finding, project, task, assignment, optional queue, absence-of-recoverable-root proof digest, CheckerRun-remediation exclusion, canonical reason, lifecycle digest |
+| lifecycle activation | `review.lifecycle.activation.manage` | singleton, operation, expected generation/current phase, adjacent target phase, reviewed manifest digest, drain observations digest, bounded batch/deadline, canonical reason |
+
+The two future evidence-upload actions are manifest entries with execution mode
+`unsupported_future_intent`, no resource model, and no prepare/consume support:
+`review.finding_evidence.ingest` and
+`review.finding_response_evidence.ingest`.
+
+Every shared contract family carries its exact closed `action_id`; family-local
+mode/reason fields are action-specific and validated so sibling actions cannot
+substitute for one another. Every fixed-service model also carries the exact
+`service_identity` and a closed server-derived `execution_mode`. In particular,
+the two identities admitted for `review.reconcile.run` have disjoint modes and
+tests must reject either identity using the other's mode.
+
+Externally owned `artifact.review_packet.materialize`,
+`artifact.review_evidence.binding.create`, `artifact.submission_bundle.prepare`,
+and `submission.create` appear only in a closed external-handoff reference map.
+02D must not define replacement contexts or adapters for them.
+
+The already-active `project.review_policy.update` and
+`project.revision_policy.update` rows are closed references to their existing
+`ProjectReviewPolicyMutationResourceContext` and
+`ProjectRevisionPolicyMutationResourceContext`; 02D neither replaces nor
+changes those proven 02B contracts.
+
+Every mutation/service contract includes exact operation/idempotency/request
+binding through the existing `PreparedAuthorizationInput` and opaque
+`PreparedAuthorizationHandle`; those protocol values are deliberately not
+fields of the resource models. Read contracts use request-scoped evaluation,
+not PREP consumption. Later activation adapters must revalidate actor and exact
+identity link plus matched grant, or the exact fixed-service identity, before
+evaluating these final server-composed facts.
 
 ## Acceptance criteria
 
@@ -71,9 +136,11 @@ docs/spec_review_lifecycle.md
   single-use.
 - Unavailable actions fail closed at prepare and consume. Publishing a contract
   does not grant runtime authority.
-- Contract tests prove copied, reconstructed, serialized, replayed,
-  wrong-session, wrong-transaction, wrong-action, wrong-principal,
-  cross-project/resource, stale-digest, revoked, and unavailable denial.
+- Existing PREP regression tests continue to prove copied, reconstructed,
+  serialized, replayed, wrong-session, wrong-transaction, wrong-action,
+  wrong-principal, revoked, and unavailable denial. New contract tests prove
+  strict construction, action/mode/identity parity, cross-resource and stale-
+  digest distinction, handle exclusion, and serialization-safe scalar shapes.
 - Static scans prove Celery payloads cannot carry handles and AUTH does not
   import REV product repositories or implement lifecycle rules.
 - The interface includes enough exact fields for REV to implement every later
@@ -82,10 +149,23 @@ docs/spec_review_lifecycle.md
 
 ## Verification commands
 
-Refresh exact paths at implementation start, then include Ruff, focused PREP,
-kernel, serialization, parity and denial tests, changed-subsystem coverage at
-or above 90 percent, and hosted Backend coverage preserving the repository-wide
-78 percent floor.
+```bash
+cd backend
+ruff check app/modules/authorization/review_contracts.py tests/test_review_authorization_contracts.py
+mypy app/modules/authorization/review_contracts.py
+.venv/bin/pytest -q tests/test_review_authorization_contracts.py
+.venv/bin/coverage erase
+.venv/bin/coverage run -m pytest -q tests/test_review_authorization_contracts.py
+.venv/bin/coverage report --include='app/modules/authorization/review_contracts.py' --precision=2 --fail-under=90
+cd ..
+git diff --check
+python3 scripts/check_markdown_links.py
+python3 scripts/check_stale_review_contracts.py
+```
+
+The PR exact head must also pass GitHub `Backend` including all five PostgreSQL
+lanes and the aggregate repository-wide `coverage --fail-under=78`, plus Agent
+Gates. No local full-suite execution is required on the user machine.
 
 ## Required reviewers
 

.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/reviews/WS-XINT-003-02D-external-review-response.md

@@ -0,0 +1,48 @@
+# External Review Response: WS-XINT-003-02D
+
+## Current status
+
+CodeRabbit completed its review with four valid in-scope findings. This record
+captures their resolution and the exact-head checks. Internal review does not
+substitute for required human approval.
+
+The first PR head failed Agent Gates and the shared backend pre-test gate because
+two new planning records used the ambiguous human/product term `worker` for
+background execution code. The wording is corrected without changing a test,
+workflow, or threshold, and the exact local stale-authorization scan passes.
+
+The next hosted Backend run reached the unchanged docstring gate and reported
+that the new contract module documented only 26 of its 54 class/callable
+surfaces, reducing repository docstring coverage to 79.9 percent. Every missing
+new contract class now has a specific docstring. The unchanged local gate passes
+at 80.9 percent; no unrelated file, configuration, or threshold changed.
+
+The following run reached the canonical semantic-lane inventory and correctly
+rejected the new test module because it had not yet been assigned to a lane.
+`test_review_authorization_contracts.py` is now assigned exactly once to
+`shared_foundations`. The canonical collect-only runner and its focused CI
+contract tests pass locally; no lane validation or evidence rule was weakened.
+
+CodeRabbit then found four contract-quality mismatches. The operator queue
+documentation now separates the bounded `REQUEST_READ` inspection shape from
+the three `PREPARED_OPERATOR` mutations, and revision-repair documentation now
+states the implemented guide ID/activation-sequence facts. `no_self_review` is
+now a true-only server proof with a distinct validation error from actor
+identity equality. Every fixed-service `execution_mode` uses one importable
+closed enum. Finally, inertness tests recursively admit only scalar, enum,
+literal, or optional annotations, rejecting prepared handles, byte-bearing
+types, callbacks, and unbounded containers by type rather than field spelling.
+
+Comments addressed: four.
+
+Comments deferred: none.
+
+Human decisions needed: normal approval of PR #257 only.
+
+Commands rerun: Ruff, focused mypy, focused contract/PREP tests, changed-module
+coverage, docstring coverage, semantic-lane inventory, stale wording scans,
+Markdown links, and diff whitespace checks. Hosted exact-head checks must pass
+again after the corrective commit.
+
+Remaining risks: the contracts remain intentionally inert; later REV-owned
+composition must still prove transaction-bound runtime enforcement.