AUTH-10A: add project role grant data and evidence foundation

.agent-loop/REVIEW_LOG.md

@@ -2763,6 +2763,18 @@ activates them with routes, records the complete PREP/idempotency/advisory-lock
 issue order, and makes `/api/v1` the sole endpoint namespace. Exact-SHA internal
 review and fresh external checks remain.
 
+## 2026-07-21 - WS-AUTH-001-10A Internal Implementation Review
+
+AUTH-10A implementation SHA `e8d9c37e` establishes immutable qualification
+snapshots, independent submitter/reviewer/adjudicator grant history, exact typed
+and PostgreSQL evidence parity, and five planned future actions without exposing
+runtime behavior. Two internal repair loops closed timestamp/truncate custody,
+ORM and UUID parity, exhaustive migration refusal/no-mutation proof, composite
+ownership proof, unrelated-history preservation, and operator preflight gaps.
+Senior engineering, architecture, reuse/dedup, security/auth, QA/test,
+test-delta, product/ops, CI integrity, and docs all pass the exact SHA. GitHub
+full CI/coverage, CodeRabbit, and human review remain.
+
 ## 2026-07-21 - WS-ENG-004-01 Writer-Directed Starts
 
 The user confirmed ordinary engineering starts must work for current repository

.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-10A-project-role-grant-data-evidence.md

@@ -6,8 +6,10 @@
 
 ## Status and prerequisite
 
-Proposed and inactive. Start only after planning parent AUTH-10 merges, signed
-memory names 10A, and a fresh explicit start event activates this exact child.
+Active. Planning parent AUTH-10 merged through PR #168 as
+`70f9c7bcdb63680e545f661a956929379df138e4`; signed memory named 10A, and
+explicit start workflow run `29828847015` activated this exact child on
+2026-07-21.
 
 ## Goal
 
@@ -35,11 +37,13 @@ backend/app/modules/authorization/models.py
 backend/app/modules/authorization/schemas.py
 backend/app/modules/authorization/repository.py
 backend/app/modules/authorization/catalogue.py
+backend/app/modules/authorization/service.py
 backend/app/modules/audit/**
 backend/app/db/models.py
 backend/alembic/versions/0031_project_role_grants.py
 backend/tests/test_authorization.py
 backend/tests/test_alembic.py
+backend/tests/test_audit.py
 docs/operations_authorization_service.md
 docs/spec_authorization_service.md
 .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/**
@@ -99,9 +103,26 @@ transition may mutate lifecycle fields.
 - Partial uniqueness permits one active actor/project/exact-role row while all
   three distinct roles may coexist.
 - Regrant after revocation creates a new row; issuance provenance is immutable.
-- Typed and PostgreSQL audit/idempotency validators accept only the three exact
-  roles and issued/revoked success events. Replacement fields/events/reasons
-  and `both` are absent.
+- Typed and PostgreSQL audit validators retain exactly
+  `ProjectRoleQualificationSnapshotCaptured`, `ProjectRoleGrantIssued`, and
+  `ProjectRoleGrantRevoked` for project-role success, plus the existing generic
+  linked `AuthorityInvalidationRequested` event. Snapshot capture has a null
+  `idempotency_reference` and is transaction-correlated to issuance by the same
+  actor, target actor, project, request ID, and correlation ID; the grant-issued
+  event carries the pending issue idempotency reference. Grant revocation and
+  its linked invalidation carry the pending revoke idempotency reference.
+  Typed/PostgreSQL validators accept only the three exact roles.
+  `ProjectRoleGrantReplaced`, `authority_replacement`, replacement fields, and
+  `both` are absent. Audit tests convert former replacement positives into
+  negative rejection cases while preserving complete event-enum coverage.
+- The existing dormant `AuthorityMutationService` is changed only to remove
+  replacement-event selection and `replaced_grant_id` matching: a project-role
+  issue can validate only `ProjectRoleGrantIssued`, with no matched prior grant.
+  This is availability-neutral evidence cleanup, not an issue/revoke product
+  service or callable behavior; no route invokes it until 10C. A dedicated
+  `test_project_role_*` regression proves issued-only success, null prior-grant
+  matching, and rejection of replacement fields/events so focused selection
+  cannot omit this service cleanup.
 - 10A adds the five `ActionId` enum members and closed `ActionDefinition` rows
   below with `ActionAvailability.PLANNED`; it adds exact `ActionOwner.AUTH_10B`
   and `ActionOwner.AUTH_10C` enum values and assigns each row to its named
@@ -137,18 +158,29 @@ transition may mutate lifecycle fields.
   independent-role request safely. No other replacement/supersession key or
   fuzzy reason search is implied.
 - Downgrade refuses before DDL when either new table contains any row or an
-  authority audit row has `before_facts->>'role'='adjudicator'` or
-  `after_facts->>'role'='adjudicator'`. Each individual predicate and their
-  combined form have transaction-level no-mutation proof.
+  `audit_events` row with `event_domain='authority'` has
+  `before_facts->>'role'='adjudicator'`,
+  `after_facts->>'role'='adjudicator'`, `action_id` equal to any of the five
+  10A-registered action IDs, or `denial_code` equal to
+  `project_role_grant_already_revoked` or
+  `project_role_grant_replay_state_changed`. Each individual predicate and
+  their combined form have transaction-level no-mutation proof before any table
+  or validator DDL is changed.
+- PostgreSQL checks/triggers, not only Pydantic, enforce availability-object
+  grammar and cardinality, available/unavailable cross-field rules, reference
+  bounds, Python-strip-equivalent reason byte bounds and control exclusion,
+  composite snapshot ownership, status/version coupling, snapshot and issuance
+  immutability, and the sole active-v1 to revoked-v2 lifecycle transition.
 - Fresh install, prior-head upgrade, downgrade/refusal, replay, constraints,
   immutability, and preserved unrelated history are proven on PostgreSQL.
 - No migration, model, schema, or fixture accepts automated creation.
 
 ## Verification commands
 
 ```bash
-(cd backend && .venv/bin/python -m ruff check app/modules/authorization app/modules/audit tests/test_authorization.py tests/test_alembic.py)
+(cd backend && .venv/bin/python -m ruff check app/modules/authorization app/modules/audit tests/test_authorization.py tests/test_alembic.py tests/test_audit.py)
 (cd backend && WORKSTREAM_TEST_ADMIN_DATABASE_URL=<admin-db> .venv/bin/python scripts/run_isolated_tests.py --metadata-json <path> --timeout-seconds 300 -- .venv/bin/python -m pytest -q tests/test_alembic.py tests/test_authorization.py -k 'project_role or qualification')
+(cd backend && WORKSTREAM_TEST_ADMIN_DATABASE_URL=<admin-db> .venv/bin/python scripts/run_isolated_tests.py --metadata-json <path> --timeout-seconds 300 -- .venv/bin/python -m pytest -q tests/test_audit.py)
 python3 scripts/check_stale_authorization_docs.py
 python3 scripts/check_markdown_links.py
 git diff --check

.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10A-internal-review-evidence.md

@@ -0,0 +1,105 @@
+# WS-AUTH-001-10A Internal Review Evidence
+
+Reviewed code SHA: `90a2f98667ab6bd0419665f185e05b7acd669688`
+
+Reviewed implementation SHA: `e8d9c37e6fd552439ff9f0db8b2972337a3b019f`
+
+Reviewed against trusted main: `dd4a454b9ab8735a3c4aa8e85e7e64b1e7222b0a`
+
+Reviewed at: `2026-07-21T14:34:49Z`
+
+Reviewer run IDs: `auth10_plan_core`, `auth10_plan_security_qa`,
+`auth10_plan_ops_ci_docs`
+
+Reviewer tracks: senior engineering, QA/test, security/auth, product/ops,
+architecture, CI integrity, docs, reuse/dedup, and test delta
+
+## Scope
+
+AUTH-10A adds the project-role qualification and immutable grant data/evidence
+foundation only. It adds no route, active action, kernel/PREP behavior, or
+callable read/issue/revoke service.
+
+## Deterministic evidence
+
+- Ruff passed for authorization, audit, migration, and focused test files.
+- Fresh install and full downgrade passed through migration `0031`.
+- Focused PostgreSQL migration tests passed for exact-role coexistence,
+  constraints, timestamps, immutability, lifecycle, action/denial parity, every
+  upgrade/downgrade refusal predicate, combined blockers, and no-mutation row
+  preservation.
+- `tests/test_audit.py`: 12 passed.
+- Focused typed catalogue/schema tests passed.
+- Stale authorization wording, Markdown links, and `git diff --check` passed.
+- Full suite, shards, aggregate 78 percent coverage, authorization 90 percent
+  coverage, API E2E, and Agent Gates are delegated to GitHub Actions.
+
+One combined local selector was interrupted when the local Postgres container
+process segfaulted and recovered. Its product assertions were rerun in isolated
+groups successfully; this is not recorded as a passing test run.
+
+## Reviewer Results
+
+All tracks reviewed exact SHA `e8d9c37e` and passed after two repair loops:
+
+| Reviewer | Result | Blocking findings | Notes |
+|---|---|---|---|
+| senior engineering | PASS AFTER FIXES | none | Immutable history, timestamps, refusal preservation, and bounded scope are coherent. |
+| QA/test | PASS AFTER FIXES | none | Focused proof reaches every declared migration, ownership, and lifecycle boundary. |
+| security/auth | PASS AFTER FIXES | none | Privacy shapes, exact-role ownership, and fail-closed upgrade/downgrade behavior pass. |
+| product/ops | PASS | none | Independent roles coexist and no product route or behavior activates. |
+| architecture | PASS AFTER FIXES | none | 10A remains data/evidence-only; 10B/10C ownership is preserved. |
+| CI integrity | PASS AFTER FIXES | none | Generic round-trip is restored; no workflow, threshold, shard, or script weakened. |
+| docs | PASS AFTER FIXES | none | Exact preflight, lock impact, and forward recovery are documented. |
+| reuse/dedup | PASS | none | Existing authority, catalogue, audit, and migration conventions are reused. |
+| test delta | PASS AFTER FIXES | none | Tests are additive; no assertion, selector, skip, or threshold was weakened. |
+
+The repair loops added database-owned timestamps, truncate guards, ORM/schema
+parity, general UUID parity, exhaustive refusal and row-preservation proof,
+existing-row composite ownership proof, successful unrelated-history
+preservation, and executable operator preflight queries.
+
+Valid findings addressed: yes
+
+All tracks then re-reviewed the exact integrated and repaired SHA `933f17f7`
+after trusted main advanced. The integration preserved the reviewed AUTH-10A
+implementation byte-for-byte. One new fail-closed validator finding was fixed:
+the merge intent successor title now exactly matches the reviewed 10B contract
+heading. Senior engineering, architecture, reuse/dedup, security/auth, QA/test,
+test delta, product/ops, CI integrity, and docs all passed the repaired SHA.
+
+All tracks also reviewed CI repair SHA `3e6ba3db`. The repair keeps the
+historical 0021 action-parity test scoped to actions present at that revision
+and extends the transaction-scoped privileged test reset to clear the two new
+immutable role-history tables without weakening their production guards. The
+dedicated 0031 tests retain proof of all five new action pairs. All tracks
+passed with no open finding.
+
+All tracks reviewed follow-up CI repair SHA `12fe910a`. It applies the same
+revision-ownership boundary to the historical 0022 parity test; the dedicated
+0031 selector still asserts and exercises exactly five AUTH-10 action pairs.
+The previously failing focused bootstrap migration test passed. All tracks
+passed with no open finding.
+
+All tracks reviewed CI compatibility repair SHA `5152c336`; the actor legacy
+activation test now recognizes the 0031 tables while proving it writes zero
+grant and qualification facts. The exact focused test passed.
+
+All tracks then reviewed CodeRabbit repair SHA `07bb38a9`. The valid finding
+was resolved by matching the ORM to migration 0031 for composite `RESTRICT`,
+identifier widths, and database-owned status/version/method defaults. Direct
+metadata verification and Ruff passed. All tracks passed with no open finding.
+
+All tracks re-reviewed final integration merge SHA `90a2f986` after trusted
+main advanced through PR #171. AUTH-10A remained byte-identical to its reviewed
+parent, both review histories were preserved, the updated merge-intent
+validator passed, and the incoming loop-recovery tooling did not alter AUTH
+behavior, tests, migration, thresholds, or successor semantics. All tracks
+passed with no open finding.
+
+Open sub-agent sessions: none
+
+## Remaining external gates
+
+GitHub full CI/coverage, CodeRabbit, and the human checkpoint remain. The user
+retains merge ownership.

.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-10A-pr-trust-bundle.md

@@ -0,0 +1,74 @@
+# WS-AUTH-001-10A PR Trust Bundle
+
+## Chunk
+
+`WS-AUTH-001-10A` — Project Role Grant Data And Evidence Foundation
+
+## Goal and approved intent
+
+Establish immutable, privacy-bounded qualification snapshots and independent
+submitter/reviewer/adjudicator grant truth before shipping reads or mutations.
+The user approved the sequential 10A/10B/10C design and explicitly started 10A.
+
+## What changed and why
+
+- Migration `0031` creates qualification-snapshot and exact-role grant history.
+- PostgreSQL enforces bounded opaque evidence, composite ownership, manual-only
+  issuance, database timestamps, exact active-v1/revoked-v2 lifecycle, and
+  immutable history.
+- Typed and SQL audit vocabularies remove `both` and replacement evidence while
+  retaining captured/issued/revoked events.
+- Five future project-role actions and two denial codes are registered; every
+  action remains planned and non-executable under its 10B/10C owner.
+- The dormant authority mutation evidence matcher now accepts issued-only
+  project-role success with no prior matched grant.
+- Operator docs provide exact upgrade/downgrade preflight and lock/recovery
+  guidance.
+
+## Design and alternatives
+
+One immutable row represents one actor/project/exact-role grant. Multiple roles
+coexist; revocation never replaces another role, and regrant creates a new row.
+Automatic inference, combined roles, replacement conversion, free-form evidence,
+and shipping routes together with schema were rejected.
+
+## Scope and product behavior
+
+All changed files are contract-allowed. No route/OpenAPI, active action,
+candidate/read API, mutation service, kernel/PREP, or product lifecycle behavior
+was added. Current runtime behavior is unchanged.
+
+## Acceptance proof and tests
+
+Focused PostgreSQL proof covers fresh/previous-head migration, clean downgrade,
+each and combined refusal predicate, exact no-mutation preservation, unrelated
+history preservation, evidence bounds, composite ownership, role coexistence,
+uniqueness, timestamps, immutable update/delete/truncate, lifecycle transitions,
+five action pairs, and two denial codes. Typed schema/catalogue and complete
+audit-event tests pass. Ruff, stale wording, Markdown links, and diff integrity
+pass. Full coverage and E2E run in GitHub Actions per the approved fast-CI policy.
+
+## Test delta and CI integrity
+
+The generic Alembic round-trip test remains intact. Tests are additive; none are
+skipped, deleted, or weakened. No workflow, package script, dependency, shard,
+or coverage threshold changed.
+
+## Reviewer and external results
+
+Senior, architecture, reuse, security, QA, test-delta, product/ops, CI, and docs
+all pass reviewed SHA `e8d9c37e`. GitHub Actions, CodeRabbit, and human review
+remain external gates.
+
+## Remaining risks and follow-up
+
+The migration takes ACCESS EXCLUSIVE authority-table locks and refuses ambiguous
+legacy evidence; operators must use the documented maintenance preflight.
+AUTH-10B owns reads, and AUTH-10C owns PREP-bound mutations. Neither starts from
+this merge without its explicit protected start event.
+
+## Human review focus and merge ownership
+
+Review privacy shapes, composite snapshot ownership, independent-role
+uniqueness, immutability, refusal predicates, and the absence of exposed
+behavior. The user retains approval for this specific PR and merge.

.agent-loop/merge-intents/WS-AUTH-001-10A.json

@@ -0,0 +1,9 @@
+{
+  "chunk_id": "WS-AUTH-001-10A",
+  "chunk_title": "Project Role Grant Data And Evidence Foundation",
+  "initiative_id": "WS-AUTH-001",
+  "next_chunk_id": "WS-AUTH-001-10B",
+  "next_chunk_title": "Project Role Grant Read And Candidate Surfaces",
+  "next_requires_explicit_start": true,
+  "schema_version": 2
+}