feat(contribution): persist policy economic truth

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md

@@ -12,19 +12,20 @@ signed-loop records do not make behavior live.
 | `01` | Canonical specification and ADR 0016 | Merged PR #144 |
 | `02A` | Shared transactional outbox persistence/append | Merged PR #155; migration 0029 |
 | `03A` | Adapter-binding persistence | Merged PR #267; migration 0053 |
+| `PLAN5` | Complete-context human needs-revision rebase reconciliation | Merged PR #270 |
 
 ## Current reconciliation
 
 | Chunk | Goal | Risk | Status |
 |---|---|---:|---|
 | `PLAN4` | Reconcile current main, ART/AUTH/REV changes, open PRs, and end-to-end order | L1 | Merged PR #261 |
-| `PLAN5` | Reconcile complete-context human needs-revision rebase across guide, policy, REV, and CON contracts | L1 | Active specification chunk; no runtime |
+| `PLAN5` | Reconcile complete-context human needs-revision rebase across guide, policy, REV, and CON contracts | L1 | Merged PR #270; no runtime |
 
 ## Core runtime chunks
 
 | Chunk | Goal | Entry gate | Status |
 |---|---|---|---|
-| `03B` | Contribution-policy persistence | 03A | Proposed; unblocks REV-03A2 FK |
+| `03B` | Contribution-policy persistence | 03A | Implemented and internally reviewed; PR checkpoint; unblocks REV-03A2 FK after merge |
 | `02C` | Shared lifecycle-audit participant | PLAN4; current AuditEvent contract | Proposed; independent of dispatcher; required before REV-04B |
 | `04A` | Hidden adapter-binding service | 03A + exact AUTH registration/PREP contract | Blocked on AUTH registration |
 | `04B` | Hidden contribution-policy service | 03B + 04A + exact AUTH registration/PREP contract | Blocked on AUTH registration |
@@ -79,6 +80,7 @@ distributed-lane changes.
 
 ## Stop
 
-CON-03A stops at its PR checkpoint. It does not start 03B, expose binding
-creation/lifecycle behavior, or substitute existing ART/REV identities for the
-future AUTH-approved compensation adapter contract.
+CON-03B stops at this PR checkpoint. No later chunk starts until 03B passes its
+external checks and receives human merge approval. Binding creation/lifecycle
+behavior remains deferred and existing ART/REV identities do not substitute
+for the future AUTH-approved compensation adapter contract.

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md

@@ -2,8 +2,9 @@
 
 ## Reconciliation baseline
 
-- Current `main`: `cda59fc32e3a60e1e2c337cae7ebeaa94b95e12b`.
-- Current migration head: `0053_compensation_bindings`.
+- Reconciled `main`: `9550b3cdb8ac12dea72931277cf46ac1b8ffda7f`.
+- Current migration head on `main`: `0054_guide_sufficiency_authority`;
+  this branch advances it to `0055_contribution_policy`.
 - Current capability ledger: `docs/roadmap_status.md`.
 - Current contribution process: `AGENTS.md`, `CONTRIBUTING.md`, and
   `.agent-loop/README.md`. Historical signed-start and merge-intent records are

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md

@@ -2,13 +2,16 @@
 
 ## Current baseline
 
-- Reconciled main: `cda59fc32e3a60e1e2c337cae7ebeaa94b95e12b`.
-- Alembic head on main: `0053_compensation_bindings`.
+- Reconciled main: `9550b3cdb8ac12dea72931277cf46ac1b8ffda7f`.
+- Alembic head on main: `0054_guide_sufficiency_authority`; 03B advances the branch
+  to `0055_contribution_policy` after AUTH migration
+  `0054_guide_sufficiency_authority`.
 - CON-01, CON-02A, and CON-03A are merged; 03A merged in PR #267.
-- PLAN5 is the active documentation/specification reconciliation for the
-  human-confirmed complete-context `needs_revision` rebase rule.
-- Runtime contains shared outbox persistence and the schema-only compensation
-  binding foundation; contribution,
+- PLAN5 is merged in PR #270 and preserves the human-confirmed complete-context
+  `needs_revision` rebase rule.
+- Runtime on main contains shared outbox persistence and the schema-only
+  compensation binding foundation. 03B is complete on its bounded branch and
+  adds contribution-policy persistence; contribution-record,
   dispatcher, fulfillment, operations, and CON API behavior remain absent.
 - The pre-existing local deletion of the archival reference PDF is user-owned
   and excluded from this planning change.
@@ -70,7 +73,8 @@ schema work. Current dependency analysis yields:
 
 ## Immediate next action
 
-Finish PLAN5 canonical reconciliation and stop at its PR checkpoint. It changes
-no runtime. After human merge approval, 03B remains the next proposed runtime
-chunk; binding creation remains deferred to 04A after AUTH approves the exact
-adapter identity/capability contract.
+Publish 03B for external CI, CodeRabbit, and human review, then stop at its PR
+checkpoint. Do not begin another chunk automatically. After 03B merges it
+unblocks the stable policy-version FK required by REV-03A2; binding creation
+remains deferred to 04A after AUTH approves the exact adapter
+identity/capability contract.

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03B-contribution-policy-persistence.md

@@ -13,13 +13,17 @@ by REV `03A2` lease/policy-freeze persistence; it does not implement REV rows.
 ## Allowed files
 
 ```text
-backend/app/modules/contributions/{models,schemas,repository}.py
+backend/app/modules/contributions/{__init__,models,schemas,repository}.py
 backend/app/modules/projects/models.py only contribution-policy relationship
 backend/app/db/models.py
 backend/alembic/versions/<next>_contribution_policy.py
 backend/tests/{test_contributions,test_projects,test_alembic}.py
+backend/tests/conftest.py only canonical reset table inventory and schema fingerprint
+.github/workflows/backend.yml only fixed contribution subsystem coverage gate
+backend/scripts/run_test_lanes.py only assign test_contributions to shared_foundations
+docs/spec_contribution_compensation.md only configured-unit and exact-numeric persistence clarification
+docs/architecture_data_model.md only configured-unit and exact-numeric persistence clarification
 .agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/**
-.agent-loop/merge-intents/WS-CON-001-03B.json
 ```
 
 ## Not allowed
@@ -32,18 +36,40 @@ public API, background executor, dependency or CI weakening
 
 ## Acceptance criteria
 
-- [ ] One active ContributionPolicy per project points to one same-project
+- [x] One active ContributionPolicy per project points to one same-project
   published immutable ContributionPolicyVersion.
-- [ ] Every publishable version has exactly one accepted_submission and one
-  completed_review ContributionRule; each is unpaid or compensated.
-- [ ] Unpaid rules have no definition. Compensated rules have at least one and
+- [x] Every publishable version has exactly one accepted_submission and one
+  completed_review ContributionRule; each is unpaid or compensated. PostgreSQL
+  deferred validation enforces the complete graph before a published version
+  or active selector can commit; repository validation is not sufficient.
+- [x] Unpaid rules have no definition. Compensated rules have at least one and
   at most two ContributionAwardDefinitions: at most one money and at most one
-  project_points definition, each with exact positive decimal/unit/binding/
-  provenance constraints.
-- [ ] Published/retired content is immutable; missing policy has no fallback.
-- [ ] Legacy classification follows D10/CON-05 and rewrites no history.
-- [ ] Upgrade/downgrade and selector/version races use isolated PostgreSQL.
-- [ ] The migration is allocated from the then-current single head and exposes
+  project_points definition. Money units are uppercase project-enabled ISO 4217
+  codes; project-points units have `(project_id, unit_code)` identity. Every
+  definition matches its rule's project, version, contribution type, and unit,
+  and its adapter binding matches project and instrument.
+- [x] PostgreSQL rejects updates/deletes to published or retired versions and
+  their rules/definitions; missing policy has no fallback. Focused PostgreSQL
+  tests prove that child rows cannot rewrite published economic truth.
+- [x] Composite PostgreSQL keys prove same-project policy/version/rule/
+  definition lineage, expose stable `(version_id, project_id)` targets for
+  future REV freezes, and bind definitions to 03A ownership by
+  `(adapter_binding_id, project_id, instrument_type)`.
+- [x] Quantities use `NUMERIC(38,18)` and closed Pydantic decimal-string
+  validation with identical bounds. Float inputs, leading plus signs, exponent
+  notation, non-finite values, zero, negatives, overflow, excess precision,
+  and rounding are rejected.
+- [x] PostgreSQL stores the unrounded numeric input and applies the exact
+  `NUMERIC(38,18)` value envelope explicitly before persistence, avoiding
+  PostgreSQL typemod rounding; project-points quantities are whole numbers.
+- [x] A migration-owned immutable ISO 4217 List One registry and project-owned
+  compensation-unit rows make money enablement and `(project_id, unit_code)`
+  points identity durable; definitions use a composite unit foreign key.
+- [x] Legacy classification follows D10/CON-05 and rewrites no history.
+- [x] Upgrade/downgrade and selector/version races use isolated PostgreSQL.
+- [x] Isolated PostgreSQL proves concurrent active-selector and publishability
+  races cannot commit an invalid or mixed policy graph.
+- [x] The migration is allocated from the then-current single head and exposes
   a stable owner contract for the later REV foreign key.
 
 ## Verification and reviewers

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-03B-external-review-response.md

@@ -0,0 +1,50 @@
+# External Review Response: WS-CON-001-03B
+
+## Comments addressed
+
+- GitHub `project_lifecycle` lane failed because the `Project` mapper named
+  `ContributionPolicy` in a reverse ORM relationship even when a project-only
+  process had not imported the contributions module. The resulting mapper
+  initialization failure cascaded into actor-registry 503 responses.
+- Removed the unnecessary bidirectional ORM relationship. Database foreign
+  keys and composite same-project lineage remain authoritative and unchanged.
+- CodeRabbit's four actionable findings were accepted: the chunk-map stop
+  boundary and contract doc scope are current, migration check-constraint names
+  now follow metadata conventions, and the contribution migration round trip no
+  longer runs from the shared lane. The canonical partitioned Alembic test
+  already proves the same 0055 head downgrade/upgrade path.
+- Removed the redundant configured-unit unique index; its composite primary key
+  remains the award-definition FK target.
+
+## Comments deferred
+
+- CodeRabbit's whole-history graph-scan performance suggestion is deferred to
+  the later command/service chunk. PostgreSQL deferred constraint triggers are
+  necessarily row-level, and 03B intentionally favors a complete fail-closed
+  validation before scale behavior exists.
+- The ISO snapshot remains duplicated deliberately because migrations must be
+  immutable and self-contained; a parity test prevents application precheck
+  drift. Defensive Decimal post-regex checks remain explicit and harmless.
+- Additional policy-input unit cases are optional; the closed validators are
+  covered by the 95% subsystem gate and current negative tests.
+
+## Human decisions needed
+
+- None beyond normal PR review and merge approval.
+
+## Commands rerun
+
+```text
+project-only configure_mappers probe: passed
+isolated test_projects.py::test_active_guide_lookup_surfaces_duplicate_rows: passed
+semantic-lane integrity: 33 passed
+focused isolated contribution PostgreSQL suite: 44 passed
+canonical Alembic head upgrade/downgrade: 1 passed
+contribution subsystem coverage: 94.89%
+Ruff: passed
+git diff --check: passed
+```
+
+## Remaining risks
+
+GitHub CI and CodeRabbit must complete on the repaired commit.

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-03B-internal-review-evidence.md

@@ -0,0 +1,51 @@
+# Internal Review Evidence: WS-CON-001-03B
+
+## Scope
+
+03B adds schema-only contribution-policy persistence: policy/version/rule/
+award-definition lineage, project-configured compensation units, an immutable
+migration-owned ISO 4217 registry, exact quantity validation, and PostgreSQL
+guards. It adds no service, route, claim, award result, adapter execution,
+AUTH/ART behavior, or public API.
+
+Reconciled main baseline: `9550b3cdb8ac12dea72931277cf46ac1b8ffda7f`.
+The user-owned archival PDF deletion is excluded from this chunk.
+
+## Deterministic Evidence
+
+```text
+44 focused isolated PostgreSQL tests passed
+1 canonical Alembic head upgrade/downgrade test passed
+33 semantic-lane integrity tests passed
+contributions module coverage: 94.89% (required at least 90%)
+Ruff: passed
+git diff --check: passed
+Markdown links: passed
+stale Workstream/review/authorization/artifact scans: passed
+Alembic head: 0055_contribution_policy
+```
+
+The PostgreSQL proof covers complete and incomplete policy graphs, configured
+unit provenance, exact decimal boundaries without typemod rounding, whole
+project points, published/retired immutability, reparent rejection, truncate
+rejection, active-selector uniqueness, and publish/child-mutation races.
+
+## Review Results
+
+| Track | Result | Resolution |
+|---|---|---|
+| Senior engineering | PASS | Null ISO bypass closed; reparent and migration concerns resolved. |
+| QA/test | PASS | Independent graph, numeric, immutability, unit, and race proof added. |
+| Security | PASS | Truncate bypass closed across every economic/provenance table. |
+| Product/ops | PASS | Project-configured ISO/points semantics align with the canonical contract. |
+| Architecture | PASS | Schema-only boundary and future REV FK remain stable. |
+| Docs | PASS | Canonical spec, data model detail, and entity overview align. |
+| Reuse/dedup | PASS | Shared compensation instrument enum reused. |
+| Test delta | PASS | No removed, skipped, weakened, or masked coverage remains. |
+| CI integrity | PASS | Fixed 90% hosted coverage gate and exact shared-foundations lane assignment added. |
+
+## Deferred Boundary
+
+Authorized policy mutation belongs to 04B. Contribution records and awards
+remain in 03C after REV supplies stable Review, ReviewLease, and
+FinalAcceptance targets. No next chunk starts automatically.

.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-03B-pr-trust-bundle.md

@@ -0,0 +1,51 @@
+# PR Trust Bundle: WS-CON-001-03B
+
+## Outcome
+
+Adds migration `0055_contribution_policy` and the SQLAlchemy/Pydantic
+foundation for project-scoped contribution policies and immutable published
+economic rules.
+
+## Design And Boundaries
+
+- One active policy per project selects one same-policy published version.
+- Deferred PostgreSQL validation requires exactly the submission and review
+  rules and the correct unpaid/compensated definition graph.
+- Composite keys preserve same-project lineage through policy, version, rule,
+  configured unit, award definition, and the 03A adapter binding.
+- Money uses project-enabled current ISO 4217 codes; project points use a
+  project-scoped unit and whole-number quantities.
+- Exact numeric input is stored without PostgreSQL typemod rounding and checked
+  against the 20-integer/18-fractional-digit envelope.
+- Published/retired content, ISO registry rows, unit rows, and table contents
+  reject unauthorized mutation, deletion, reparenting, and truncation.
+- No command/service/API/AUTH/ART/REV behavior is introduced.
+
+## Verification
+
+- 44 focused isolated PostgreSQL tests passed, including the active-selector
+  negative regression.
+- Canonical head upgrade/downgrade passed.
+- Contribution subsystem coverage is 94.89%.
+- Hosted CI enforces at least 90% contribution-subsystem coverage.
+- The contribution test module is assigned exactly once to the
+  `shared_foundations` semantic lane; lane-integrity tests pass.
+- Ruff, diff hygiene, Markdown links, and all applicable stale scans pass.
+- Required internal reviewers pass after their valid findings were repaired.
+
+## Human Review Focus
+
+1. Confirm 0055 remains a linear child of AUTH 0054 on the reconciled main head.
+2. Confirm deferred graph validation and child locking prevent mixed published
+   economic truth.
+3. Confirm money/points unit provenance and exact numeric constraints match the
+   canonical specification.
+4. Confirm 03B remains schema-only and does not claim AUTH, ART, or REV behavior.
+
+## Remaining External Gate
+
+The first hosted project-lifecycle run exposed an import-order failure from an
+unnecessary reverse ORM relationship. That relationship was removed without
+changing database lineage, and the exact formerly failing project test passes
+in isolation. GitHub CI and CodeRabbit must pass on the repaired exact head.
+Human merge is required, and no subsequent chunk begins automatically.

.github/workflows/backend.yml

@@ -357,6 +357,10 @@ jobs:
         working-directory: backend
         run: coverage report --include='app/modules/audit/*' --precision=2 --fail-under=90
 
+      - name: Contribution subsystem coverage
+        working-directory: backend
+        run: coverage report --include='app/modules/contributions/*' --precision=2 --fail-under=90
+
       - name: API router composition coverage
         working-directory: backend
         run: coverage report --include='app/api/router.py' --precision=2 --fail-under=90