diff --git a/.agent-loop/REVIEW_LOG.md b/.agent-loop/REVIEW_LOG.md index 1e8aa608b..4f605c510 100644 --- a/.agent-loop/REVIEW_LOG.md +++ b/.agent-loop/REVIEW_LOG.md @@ -2966,3 +2966,37 @@ superseded `609be24d` revision as current and proposed omitting signed PR #201 from the first-parent recovery chain. The external-review response records why final code review is bound to `f3eab24e` and why exact PR #201 reconciliation is mandatory rather than expanded authority. + +## 2026-08-03 - WS-CON-001-PLAN4 Current-Main Reconciliation + +The planning refresh reconciles CON with current ART, AUTH, REV, and XINT +boundaries, initially at main `10720382` with merged REV PLAN4 PR #258 and then +refreshed through main `2feaf47d` with merged ART PR #249 and Alembic head +`0050_guide_source_v2`. Review +repair removed false `02C` coupling, +neutralized mutable open-PR status, replaced the obsolete dispatcher-first +canonical sequence with the current partial order, corrected the legacy +decision reference and verification command, tightened receipt data +minimization, and removed stale AUTH vocabulary/counts. + +Final architecture, security/auth, product/ops, QA/test/CI, docs, and senior +engineering/reuse review have no open actionable findings. QA's sole condition +is mechanical: the pre-existing user-owned reference-PDF deletion must remain +excluded from any PLAN4 commit or PR. Deterministic diff, link, stale wording, +stale authorization, and lightweight gate checks pass. No runtime chunk starts +as part of PLAN4. + +PR #261 Agent Gates and CodeRabbit pass. Hosted Backend has one AUTH +actor-profile concurrency failure independently reproduced on current main; +publication still requires a green rerun or upstream AUTH repair. CodeRabbit +raised four initial valid planning gaps covering receipt quantity/digest provenance, strict AUTH-owned +registration evidence, the receipt-risk exclusion list, and omitted dependency +edges. The repair closes all four in the `03D` contract, conformance/risk +records, canonical specification, and chunk map; refreshed external review is +the remaining PR gate. + +CodeRabbit's refreshed review raised two additional dependency-specific gaps: +the `08A` executable contract omitted `CON-03D`, and canonical dependency views +used broad REV persistence labels. The repair adds the explicit `03D -> 08A` +gate and names exact merged `REV-04B` runtime +`Review`/`ReviewLease`/`FinalAcceptance` targets. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/ACTIVE_DOC_INVENTORY.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/ACTIVE_DOC_INVENTORY.md index 86f8c6bed..5f723c59c 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/ACTIVE_DOC_INVENTORY.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/ACTIVE_DOC_INVENTORY.md @@ -1,120 +1,40 @@ -# Active Documentation Inventory: WS-CON-001-01 - -## Purpose - -This inventory records the active-document scope reviewed before implementing -the canonical specification and ADR. It separates target architecture from -historical/current-runtime documentation so this specification chunk does not -pretend the legacy runtime migration has already occurred. - -## Direct chunk changes - -| File | Reason | -|---|---| -| `docs/spec_contribution_compensation.md` | New canonical target specification. | -| `docs/decision_0016_contribution_compensation_boundary.md` | New architecture decision. | -| `README.md` | One canonical specification link, ADR link, and precedence note. | -| `docs/architecture_data_model.md` | Canonicalize the TaskAssignment heading, correct FinalAcceptance aliases to merged REV-owned names, and mirror fixed-point/receipt data-minimization rules. | -| `.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/**` | Chunk status, evidence, review, and trust artifacts. | -| `.agent-loop/merge-intents/WS-CON-001-01.json` | Immutable same-initiative successor declaration. | - -## Current-main reconciliation - -Before the PR human checkpoint, AUTH-09B PR #143 merged as trusted main -`053242b`. The canonical specification and active CON planning/handoff artifacts -therefore adopt the 74-permission/65-action/10-active/55-planned baseline and -the controlled `actor.service.provision` route. Historical review artifacts -retain their exact earlier SHAs and observations. No AUTH runtime file is -changed by this CON reconciliation. - -Before CON-02A review, trusted main advanced through ART PR #141 and AUTH-09C -PR #146 to `0ffdabf`. The live catalogue is now -74-permission/65-action/12-active/53-planned because AUTH-09C activates only -`actor.profile.read` and `actor.identity_link.read`; it adds no CON/outbox -identifier or migration. Historical CON-01 evidence above remains exact. -Trusted main then advanced to `b2b9016` through REV-01 PR #145, which publishes -the canonical review specification without changing the backend migration head -or the CON-02A outbox boundary. -REV-02 PR #147 then advanced trusted main to `f18b620` with planning-only chunk -decomposition and no backend, migration, or 02A boundary change. -AUTH-09D-A PR #148 then advanced trusted main to `99ae4c96`, activated only -three actor-profile lifecycle actions, and added AUTH-owned -`0026_actor_profile_lifecycle`. CON-02A therefore rebases its linear migration -to `0027_shared_transactional_outbox`; the merge adds no CON/outbox action, -permission, evaluator, service identity, or runtime admission. -REV PLAN2 PR #150 then advanced trusted main to `983b9e53` with a -planning/specification-only runtime-readiness refresh. It preserves the -FinalAcceptance-sourced submitter contribution, reviewer contribution on all -three decisions, REV-owned single commit, and shared outbox staging. Its split -future REV child gates are reconciled in CON planning; it changes no backend, -migration, AUTH catalogue, or CON-02A implementation. -ART-02B1 PR #151 then advanced trusted main to `1b5422fc` with the -S3-compatible ArtifactStore adapter, real MinIO integration, inactive AWS -profile support, dependency pins, CI changes, and substantial tests. It adds no -migration or outbox seam and does not change CON-02A behavior, but it requires -fresh repository-wide evidence on the combined tree. -AUTH-09D-B PR #152 then advanced trusted main to `93dd3924`, activating only -identity-link revoke/reactivate and expanding AUTH lifecycle proof. It adds no -migration, CON/task-claim identifier, fixed-service admission, or outbox seam; -at that historical point the contributor foundation and AUTH-09E remained -later gates. -Contributor-foundation PR #153 then advanced trusted main to `8d5eb15b`. It -clean-cuts TaskAssignment and Submission attribution to canonical human -`contributor_id`, adds writer revalidation, and owns -`0027_contributor_foundation`. It adds no CON/outbox identifier, service -admission, dispatcher, review lifecycle, or authority change. CON-02A is now -the linear `0028_shared_transactional_outbox` child; AUTH-09E remains a later -gate. -ART-02C1 PR #154 then advanced trusted main to `44f2467c`. It owns -`0028_artifact_admission` and adds durable artifact-admission and prepared-put -state without changing the generic outbox boundary. CON-02A is therefore the -linear `0029_shared_transactional_outbox` child; ART remains absent from the -outbox append path. - -## Inspected and already aligned - -The following active documents already describe ContributionPolicy, -FinalAcceptance, contribution lineage, no core ART call, and the no-adjudication -shipping boundary consistently enough that this chunk does not rewrite them: - -- `docs/glossary.md` -- `docs/architecture_lockdown.md` -- `docs/architecture_lifecycle_state_machine.md` -- `docs/architecture_system_architecture.md` -- `docs/operations_operator_workflow.md` -- `docs/operations_reviewer_workflow.md` -- `docs/operations_payment_reputation.md` -- `docs/operations_queue_policy.md` -- `docs/product_first_user_flows.md` -- `docs/template_project_guide.md` -- `docs/template_review_packet.md` -- `docs/template_submission_packet.md` -- `docs/template_task.md` - -## Historical/current-runtime documents intentionally unchanged - -Older implementation chunk specifications and roadmaps still mention the -retired guide-bound economic aggregate or its locked version fields because -those fields remain in the current backend. They are subordinate to the new -target specification but remain accurate implementation history until -CON-05A/05B. This chunk does not rewrite them: - -- `docs/spec_chunk_3_project_guide_foundation.md` -- `docs/spec_chunk_4_task_queue_assignment.md` -- `docs/spec_chunk_5_submission_packet_foundation.md` -- `docs/spec_chunk_6_checker_contract_records.md` -- `docs/spec_chunk_9_pre_review_gate.md` -- `docs/spec_week2_checker_framework.md` -- `docs/roadmap_week1_backend_plan.md` -- `docs/roadmap_30_day_master_plan.md` -- `docs/roadmap_day_by_day_execution_plan.md` - -Keeping these files unchanged also avoids an unauthorized roadmap/export -change. CON-05A/05B own the semantic and physical cleanup plus the final -stale-consumer scan. - -## Immutable archival inputs - -All `docs/reference_specs/**` files remain archival inputs. This chunk does not -edit, rename, restore, or stage them and preserves the user's pre-existing -reference-PDF deletion state. +# Active Documentation Inventory: WS-CON-001-PLAN4 + +## Direct reconciliation scope + +This planning refresh updates the WS-CON-001 initiative package plus the stale +Required Implementation Order in the canonical contribution specification. It +does not change runtime code, migrations, other specification sections, +roadmaps, exports, workflows, or another initiative's files. + +The active package is: + +- `INTENT.md`, `DISCOVERY.md`, `PLAN.md`, `CHUNK_MAP.md`, and `STATUS.md`; +- `DECISIONS.md`, `RISKS.md`, and `SOURCE_MANIFEST.md`; +- `CONFORMANCE_MATRIX.md` and `RUNTIME_VERIFICATION.md`; +- `AUTHORIZATION_HANDOFF.md` and `JOINT_RELEASE_HANDOFF.md`; +- the PLAN4 contract and the reconciled `02B`, `02C`, `03A`, `03B`, `03C`, + `03D`, `04B`, and `08A` contracts. +- `docs/spec_contribution_compensation.md` only to replace the obsolete linear + dispatcher-first order with the reconciled partial order. + +## Reconciled current-state sources + +- current contribution/governance instructions in `AGENTS.md`, + `CONTRIBUTING.md`, and `.agent-loop/README.md`; +- current capability truth in `docs/roadmap_status.md`; +- merged AUTH, ART, REV, XINT, and CON history through `2feaf47d`; +- current backend modules and migration graph; +- merged ART #249 runtime evidence and merged + REV PLAN4 PR #258. + +## Intentionally unchanged + +Other canonical product specification sections remain aligned and are not +rewritten merely to restate this plan. Historical chunk evidence remains historical. Other +initiatives retain ownership of their own plans and runtime contracts. Local +roadmap XLSX/CSV exports are not changed because the roadmap is not changed. + +The pre-existing deletion of +`docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.pdf` +is user-owned and remains untouched and unstaged. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md index dfd1cd631..f4fcf446e 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/AUTHORIZATION_HANDOFF.md @@ -2,290 +2,83 @@ ## Current baseline -Trusted `main` is `8d5eb15b` after contributor-foundation PR #153, AUTH-09D-B PR #152, ART-02B1 PR #151, -planning-only REV PLAN2 PR #150, AUTH-09D-A PR #148, REV-02 PR #147 and -REV-01 PR #145, layered on AUTH-09C PR #146, ART PR #141, AUTH-09B PR #143, -merged REV planning PR #128, AUTH-09A/AUTH PR #140, and the earlier WS-XINT PR -#139 boundary. The runtime catalogue contains 74 PermissionIds and 65 ActionIds: -17 active and 48 planned. AUTH-09B activates only `actor.service.provision`; -AUTH-09C activates only `actor.profile.read` and `actor.identity_link.read`; -AUTH-09D-A activates only the three actor-profile lifecycle actions; -AUTH-09D-B activates only identity-link revoke/reactivate. PR #153 changes -TaskAssignment/Submission attribution and canonical-human writer validation -only; it adds no action, permission, grant, evaluator, availability, -fixed-service admission, or review runtime. No -WS-CON-specific or task-claim ActionId below is registered. PR #140 still defines the -prepared/custody plan; it does not implement AUTH-PREP, transfer ART/REV custody, -register a CON action, or activate a CON feature action. +Current `main` is `2feaf47dd5bb448db076179d96751caa55fb0994` with the AUTH +actor, grant, fixed-service, prepared-mutation, project-guide, policy-mutation, +and REV-readiness foundations plus merged REV PLAN4 and ART foundations. The +database is at migration `0050_guide_source_v2`. These foundations do +not create CON runtime, activate CON behavior, or give an outbox dispatcher +feature authority. -AUTH owns identifiers, stable mappings, activation custody, typed resource and -principal contexts, grants, fixed ServiceIdentity/static matrix, AUTH-09E -admission, prepared mutation handles, evaluator dispatch, decision evidence, -availability, and parity. CON owns canonical product loaders, typed resource -facts, lifecycle guards, hidden behavior, and feature tests. Neither side -imports the other's repositories or mutates the other's state. +AUTH owns identifiers, stable permission mappings, principals, grants, +fixed-service identities and matrix rows, prepared authorization, evaluators, +availability, and activation. CON owns canonical contribution and compensation +resource loaders, policy and binding facts, lifecycle guards, hidden behavior, +and feature tests. Neither subsystem imports the other's repositories or +mutates the other's records. -## Required delivery sequence +## Required delivery pattern -Every protected CON surface follows: +Every protected CON boundary follows: ```text -AUTH registration checkpoint - planned ActionId + stable PermissionId + AUTH ActionOwner - principal class + typed context + prepared protocol when mutating --> CON hidden-behavior checkpoint - canonical resource loader + guards + behavior, real kernel still denies --> AUTH activation checkpoint - exact evaluator + matched authority + negative proof + active availability --> joint release checkpoint +AUTH registers the exact planned action and authority contract +-> CON merges canonical hidden behavior using AUTH-owned ports +-> AUTH integrates the exact evaluator and activates the action +-> cross-initiative release proof enables the surface ``` -Registration, provisioning, matrix membership, feature behavior, and activation -are distinct. A provisioned service cannot execute a planned action. CON cannot -turn a fake/test decision into a production allow path. - -## Principal models - -### Human - -- task.claim: exact active same-project `submitter` ProjectRoleGrant; -- review.claim and review.decision: exact active same-project `reviewer` - ProjectRoleGrant plus no-self-review and lifecycle guards; -- contribution self/award self: exact actor-self relationship; -- administrative policy, binding, project reads, and operations: one exact - eligible AdminRoleGrant selected by the action evaluator. - -The shipping path consumes exact `submitter` and `reviewer` grants. There is no -combined grant and no unrelated project/admin grant substitutes. WS-CON adds no -adjudication grant or action and has no adjudication readiness dependency; any -separate global project-role catalogue state remains AUTH-owned and outside -this transaction. - -FinalAcceptance creation has no ActionId. It is an internal REV-owned -consequence of an already-authorized `review.decision` with `accept`; CON only -validates and consumes the locked fact when creating `accepted_submission`. - -### Fixed service - -The only service admission path is: - -```text -verified service token --> active ActorIdentityLink --> active service ActorProfile --> immutable closed ServiceIdentity --> exact static service-action matrix membership --> AUTH-09E typed service AuthorizationContext --> CON-composed canonical ResourceContext --> decision -``` - -There is no database service grant or action-assignment row. AUTH locks the -profile/link and validates unchanged ServiceIdentity, static membership, and -active action. Human grants cannot satisfy service actions and services cannot -use human grant candidates. Missing provisioned rows deny the request and block -release readiness, but do not fail application startup or provisioning. - -AUTH-09B now exposes `POST /api/v1/service-actors` to an effective system Access -Administrator. It binds the configured issuer and opaque subject to one -already-approved closed ServiceIdentity and creates only the service -ActorProfile/ActorIdentityLink plus bounded authorization, audit, invalidation, -and idempotency evidence. It creates no role, grant, assignment, service-token -admission, or executable service authority. The current seven identities and -eleven static rows are ART-only. Each proposed CON fixed service requires a -separate reviewed identity/action/static-row contract before provisioning and -still waits for AUTH-09E admission and exact action activation. - -## Prepared mutation protocol - -For `T` actions AUTH locks canonical current human actor/link/exact-grant or -fixed-service actor/link authority first and returns one opaque, -non-serializable `PreparedAuthorizationHandle`. The handle is bound exactly to -the caller session, ActionId, actor-reference kind, actor reference, -idempotency key, and canonical request digest. ServiceIdentity, static matrix -membership, and availability are code-owned validations after profile/link -locks, never database lock targets. CON or the owning feature then locks -product rows in the canonical order and recomposes final typed facts; AUTH -consumes the handle, evaluates once, and stages decision evidence. AUTH and all -feature participants flush only; the route/executor/callback command commits -once. Reused, serialized, caller-constructed, cross-session/action/actor/ -request, binding-mismatched, or authority-lost handles deny before product -mutation. A failed substitution attempt does not consume an otherwise valid -handle. - -`Q` reads use request-scoped require plus canonical CON loaders, pre-filtered -pagination, and concealment. No authorization result or grant cache survives a -request. - -## Proposed core action mappings - -These 22 feature-surface mappings preserve existing stable PermissionIds except -for the two explicitly proposed service-only PermissionIds. They are product -proposals, not registered runtime, and they are not a final action count until -the protected execution boundaries are approved. Policy ActionIds use the -canonical `contribution.policy.*` namespace while retaining stable -`compensation.policy.manage` PermissionId compatibility. - -| Proposed ActionId | PermissionId | Principal / target | Protocol | Feature owner | -|---|---|---|---:|---| -| `outbox.dispatch` | proposed `outbox.dispatch` | fixed outbox dispatcher / claimed event | T | shared outbox 02B | -| `compensation.adapter_binding.read` | `compensation.adapter_binding.manage` | Finance / ProjectCompensationAdapterBinding | Q | CON-04A | -| `compensation.adapter_binding.create` | `compensation.adapter_binding.manage` | Finance / project binding collection | T | CON-04A | -| `compensation.adapter_binding.suspend` | `compensation.adapter_binding.manage` | Finance / active binding | T | CON-04A | -| `compensation.adapter_binding.resume` | `compensation.adapter_binding.manage` | Finance / suspended binding | T | CON-04A | -| `compensation.adapter_binding.retire` | `compensation.adapter_binding.manage` | Finance / dependency-free binding | T | CON-10B | -| `contribution.policy.read` | `compensation.policy.manage` | Finance / ContributionPolicyVersion | Q | CON-04B | -| `contribution.policy.create_draft` | `compensation.policy.manage` | Finance / project policy collection | T | CON-04B | -| `contribution.policy.update_draft` | `compensation.policy.manage` | Finance / draft version | T | CON-04B | -| `contribution.policy.publish` | `compensation.policy.manage` | Finance / complete draft version | T | CON-04B | -| `contribution.policy.retire` | `compensation.policy.manage` | Finance / published version | T | CON-04B | -| `compensation.fulfillment.report` | proposed `compensation.fulfillment.report` | exact bound service / award and binding | T | CON-08B | -| `contribution.read_self` | `contribution.read_self` | contributor / own record | Q | CON-10A | -| `contribution.read_project` | `contribution.read_project` | exact eligible AdminRole / project collection | Q | CON-10A | -| `compensation.award.read_self` | `contribution.read_self` | beneficiary / own award | Q | CON-10A | -| `compensation.award.read_project` | `compensation.award.read` | D11 role set / project award collection | Q | CON-10A | -| `compensation.delivery.reconcile` | `compensation.delivery.reconcile` | D11 role set / delivery request | T | CON-10B | -| `compensation.status.read` | `operations.status.read` | Operator / bounded status | Q | CON-10B | -| `compensation.reconcile.run` | `operations.reconcile.run` | reason-bound Operator / durable request | T | CON-10B | -| `contribution.projection.rebuild` | `operations.projection.rebuild` | reason-bound Operator / durable request | T | CON-10B | -| `audit.read` | `audit.read` | D11 role set / bounded WS-CON audit | Q | CON-10B | -| `audit.export` | `audit.export` | D11 role set / bounded export | T | CON-10B | - -PR #140 approves no `AUTH_CON_*` owner identifiers. After a complete -feature-owned manifest exists, AUTH must assign each registered action to one -exact future `WS-AUTH-001-*` activation chunk and prove unchanged mapping plus -planned availability. CON must not predict or add ActionOwner enum values. - -## Core resource guards - -- Policy publish locks one active ContributionPolicy selector, draft version, - both exact ContributionRules, award definitions, and referenced active same- - project/instrument bindings. Published content is immutable. -- Binding create validates canonical service actor, approved adapter capability, - project/instrument, and non-secret route identity. Suspend blocks new freezes - and deliveries but preserves valid callbacks for already-issued awards. -- Binding retire denies any active policy reference, unfinished frozen - assignment/lease, or unfulfilled award. After retirement only exact replay of - a previously accepted receipt may be acknowledged. -- Contribution self/project and award self/project reads use canonical record - ownership, pre-filtered project scope, stable pagination, and concealment. - They expose no provider reference, secret, balance, or ledger data. -- Callback requires exact actor/link/ServiceIdentity/static row, binding route, - award, project, instrument, and receipt-state match. Rate limits bind actor - plus binding, not shared IP alone. -- Reconciliation/rebuild create bounded durable requests and never repair - immutable contribution, award, or receipt truth. - -## Service execution gaps that must be closed - -The 22 mappings above cover human/public queries, management requests, the -callback, and generic outbox dispatch. They do not authorize protected feature -handler execution. `workstream.outbox.dispatcher` with `outbox.dispatch` can -only claim, invoke, and finalize events; it cannot transitively receive every -handler's mutation/provider authority. - -Before CON-02B/08A/10C protected execution, AUTH and the human must approve -exact ServiceIdentity/ActionId/static-row contracts. CON-08B independently -requires the authenticated callback identity/action/static-row contract: - -| Boundary | Discovery candidate identity | Discovery candidate action | Required result | -|---|---|---|---| -| outbox mechanics | `workstream.outbox.dispatcher` | `outbox.dispatch` | exact closed identity and singleton static row | -| outbound fulfillment delivery | `workstream.compensation.delivery` | `compensation.delivery.execute` | independent feature authority; never inherited from dispatcher | -| async compensation reconciliation | `workstream.compensation.reconciler` | `compensation.reconcile.execute` | exact bounded execution action or approved dual-principal evaluator | -| async contribution projection rebuild | `workstream.contribution.projection_rebuilder` | `contribution.projection.rebuild.execute` | exact bounded execution action or approved dual-principal evaluator | -| fulfillment callback | `workstream.compensation.fulfillment_reporter` | `compensation.fulfillment.report` | one approved fixed identity/static row or an explicitly specified closed set | - -Candidate strings are not approved identifiers. If AUTH reuses an existing -request ActionId for fixed-service execution, it must specify a closed dual- -principal evaluator and prove human/service isolation. CON must not infer that -design. Each new identity requires closed enum/static-matrix changes, controlled -ActorProfile/ActorIdentityLink provisioning, service_identity constraint -migration custody, AUTH-09E admission, exact cross-service negative tests, and -activation only after hidden behavior merges. - -## Upstream review and task actions - -Only the stable `task.claim` PermissionId exists on trusted main; there is no -registered task-claim ActionId among the 65 actions. AUTH-PREP, the exact -submitter grant, and the task-owned claim seam precede CON-05A's hidden freeze -participant. CON-05A and task-owned composition must merge first. AUTH-13 then -enumerates/registers the exact task-claim ActionId, integrates its evaluator, -and activates only after the immutable ContributionPolicyVersion freeze and -rollback proof exist. -`review.claim` and `review.decision` are current planned actions; CON-06/07 -provide hidden participants, REV supplies canonical composition, and AUTH -activates only after the complete behavior merges. - -### Required AUTH follow-up from PR #140 - -- The current `WS-AUTH-001-13` contract owns future task-claim ActionId - enumeration/registration, activation, and exact submitter-grant evaluation, - but it does not yet name the CON-05A TaskAssignment - ContributionPolicyVersion freeze as a prerequisite. Its executable refresh - must consume the merged CON-05A manifest and prove task-owned participant - composition before it registers/activates that action. -- Future CON registration contracts must choose exact `WS-AUTH-001-*` - activation custodians from complete feature manifests. The removed - `AUTH_CON_*` planning labels are not approved ActionOwner values. -- `review.claim` activation must consume CON-06 through REV's hidden claim - composition. PR #140 already states that `review.decision` activation - requires the merged mandatory CON participant and one rollback-safe REV+CON - transaction; no additional FinalAcceptance action is needed. - -These are upstream AUTH contract gates. CON does not edit AUTH files, register -identifiers, integrate evaluators, or change availability. - -AUTH must reconcile all 19 current review actions as one complete activation- -custody transfer under `WS-XINT-001/AUTH_REV_HANDOFF.md`. WS-CON declares only -its two dependencies and must not remove or retain individual REV ActionOwner -members locally. The four proposed additive review actions remain absent until -their own registration contract. - -Likewise, the complete 25-action ART transfer belongs to -`WS-XINT-001/AUTH_ART_HANDOFF.md`. WS-CON has no core ART dependency and does not -repeat an eleven-action subset. - -## Optional evidence action - -If optional contribution-evidence projection is separately approved, one -additional action may be proposed: - -```text -artifact.contribution_evidence.binding.create - -> existing artifact.binding.create - -> existing workstream.artifact.binding ServiceIdentity -``` - -AUTH would extend that identity's static row by exactly this action only after a -reviewed ART capability contract exists. This optional action is outside the 22 -core proposal and outside release readiness. It cannot be used to authorize -core ContributionRecord creation or reads. - -## D11 AdminRole decisions - -Before CON-10A/10B registration, the human must choose exact candidates for: - -- Project Manager inclusion in project award detail; -- reason-bound Operator delivery recovery in addition to Finance Authority; -- audit read/export role sets. - -Any difference from merged AUTH definitions is implemented by AUTH through an -action-owned closed role intersection before grant query. Mixed eligible and -excluded grants select only the eligible grant. CON receives matched decision -evidence and contains no role branch. - -## Activation and release proof - -AUTH proof must cover planned denial, exactly one custodian per action, -PermissionId parity, evaluator/context completeness, exact human grants, -ServiceIdentity/static-matrix membership, AUTH-09E admission, cross-service -denial, same-token revocation, prepared-handle misuse, transaction-time -revalidation, and decision-evidence failure. Feature proof covers canonical -facts, lifecycle guards, commit/rollback, and no AUTH persistence import. - -Startup may fail on closed code/catalogue/static-matrix/evaluator/active- -behavior drift. Runtime and release readiness deny on missing provisioned -service rows. Administrative provisioning remains available. - -This handoff changes no AUTH runtime and starts no AUTH or CON chunk. +Registration and provisioning do not imply activation. A dispatcher action +does not confer any handler's feature authority. Query paths use request-scoped +authorization plus canonical loaders; mutation paths use the prepared-mutation +protocol and one caller-owned commit. + +## AUTH deliveries required by CON + +| CON boundary | Required AUTH delivery | Current disposition | +|---|---|---| +| `03A` binding persistence | none; schema stores only canonical actor identity and non-secret route facts | CON may proceed | +| `03B` policy persistence | none; no command or protected route | CON may proceed | +| `02C` lifecycle audit participant | none; caller supplies already-authorized typed facts | CON may proceed | +| `04A` binding commands | `compensation.adapter_binding.{read,create,suspend,resume,retire}` mapped to `compensation.adapter_binding.manage` with exact Finance authority | register before hidden service; activate after it | +| `04B` policy commands | `contribution.policy.{read,create_draft,update_draft,publish,retire}` mapped to `compensation.policy.manage` with exact Finance authority | register before hidden service; activate after it | +| `05A` task claim/freeze | exact task-owned claim action, submitter authority, and prepared mutation | final identifier must follow the task-owned contract | +| `06` review claim freeze | existing planned `review.claim` contract | REV composes CON policy result; AUTH later activates | +| `07` review decision participant | existing planned `review.decision` contract | REV owns composition/commit; AUTH later activates | +| `02B` dispatcher | `outbox.dispatch`, closed dispatcher identity, singleton matrix row, provisioning, admission, typed context, evaluator, and availability | blocked; schedule after AUTH delivery | +| `08B` fulfillment callback | independently approved reporter identity/action/matrix contract | not inherited from dispatcher | +| `08A` and `10C` executors | an exact feature identity/action/matrix contract for each executor | not inherited from dispatcher | +| `10A/10B` reads and operations | exact self/project/operations actions and evaluators | register from the final route manifest | + +The proposed action names are interface inputs for AUTH planning, not runtime +registration by CON. AUTH chooses the exact activation custodian and proves +principal isolation, stable mappings, negative cases, and hidden-to-active +transition. CON does not add AUTH enums, owners, grants, service identities, +matrix rows, or evaluators. + +## Principal and transaction invariants + +- Human contribution and award reads use actor-self or one exact eligible + same-project administrative grant; concealment and pre-filtering are owned by + the product loader. +- Task claim uses the exact active same-project submitter authority. +- Review claim and decision use the exact active same-project reviewer + authority plus REV-owned no-self-review and lifecycle facts. +- FinalAcceptance creation is an internal consequence of an authorized + `review.decision=accept`; it has no separate public action. +- Fixed services require a verified token, active canonical actor/link, closed + ServiceIdentity, exact static row, active action, and canonical resource + context. Database grants never substitute for that path. +- AUTH and feature participants flush only. The owning route, service command, + or callback commits once. +- Provider credentials, opaque provider references, balances, and ledger data + never enter authorization contexts or audit payloads. + +## Immediate AUTH ask + +No AUTH change blocks planning or CON `03A`, `03B`, or `02C`. Before CON `04A` +or `04B`, AUTH must publish the exact registration contracts above. Before CON +`02B`, AUTH must deliver the complete dispatcher identity/admission/action +contract. That later dispatcher work must not delay the persistence and +transaction-participant foundations now needed by REV. + +This handoff authorizes no implementation and starts no chunk. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md index 5d5068b6f..d063a18ce 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CHUNK_MAP.md @@ -1,147 +1,82 @@ -# Chunk Map: WS-CON-001 Contribution Record And Compensation Boundary - -## Rule - -One chunk maps to one reviewable PR. No runtime chunk starts until its exact -AUTH, REV, outbox, migration, and human gates are satisfied on trusted `main`. -AUTH owns activation custody; feature ownership never supplies a second -availability writer. Optional evidence chunks are not part of the core order. - -## Chunks - -| Chunk | Title | Risk | Gate | Status | -|---|---|---:|---|---| -| `WS-CON-001-PLAN` | Contribution And Compensation Planning | L0 | None | Complete; unpublished | -| `WS-CON-001-PLAN2` | Final Acceptance Reconciliation | L0 | Human FinalAcceptance/no-adjudication direction | Complete; unpublished | -| `WS-CON-001-PLAN3` | AUTH/REV Current-Main Reconciliation | L0/L1 | Merged AUTH PR #140 plus AUTH-09A and REV PR #128 at `0302bcf` | Complete; unpublished | -| `WS-CON-001-01` | Canonical Contract Adoption And Architecture Decision | L0/L1 | Reconciled plan and human decisions approved | Complete; merged in PR #144 | -| `WS-CON-001-02A` | Shared Transactional Outbox Persistence | L1 | 01 merged at `e118e33`; trusted head refreshed through contributor-foundation PR #153 and ART-02C1 PR #154 at `44f2467c`; explicitly started by human | Reconciled as `0029` after ART `0028`; bounded proof, exact-SHA review, and GitHub full-suite pending | -| `WS-CON-001-02B` | Shared Outbox Dispatcher And Recovery | L1 | 02A; AUTH registers `outbox.dispatch`, approved `workstream.outbox.dispatcher` ServiceIdentity/static row, AUTH-09E admission, prepared protocol; dispatcher remains disabled until AUTH activation | Proposed | -| `WS-CON-001-02C` | Shared Lifecycle Audit Participant | L1 | 02B; current AuditEvent contract refreshed | Proposed | -| `WS-CON-001-03A` | Project Compensation Adapter-Binding Persistence | L1 | 02C; migration head refreshed | Proposed | -| `WS-CON-001-03B` | Contribution Policy Persistence | L1 | 03A; legacy-data rule; must precede REV-03 ReviewLease FK | Proposed | -| `WS-CON-001-03C` | Contribution And Award Persistence | L1 | 03B; merged REV-04B runtime FinalAcceptance/Review/ReviewLease FK targets | Proposed | -| `WS-CON-001-03D` | Delivery, Receipt, And Status Persistence | L1 | 03C; immutable fulfillment root ordinal/generation contract | Proposed | -| `WS-CON-001-04A` | Hidden Adapter-Binding Service | L1 | 03A; planned AUTH binding actions/contexts/prepared protocol; callback ServiceIdentity/action/static row approved but inactive | Proposed | -| `WS-CON-001-04B` | Hidden Contribution-Policy Service | L1 | 03B, 04A; binding activation merged; planned `contribution.policy.*` actions/contexts/prepared protocol | Proposed | -| `WS-CON-001-05A` | Legacy Economic Terms Cutover And Task Freeze | L1 | 04B; exact Submission/TaskAssignment lineage; AUTH-10 exact submitter grants and AUTH-PREP merged; task.claim PermissionId exists but ActionId remains absent; stable task-owned claim seam; legacy rule | Proposed | -| `WS-CON-001-05B` | Legacy Economic Schema Removal | L1 | 05A; zero-consumer scan; removal migration approval | Proposed | -| `WS-CON-001-06` | Review-Lease Contribution-Policy Freeze Capability | L1 | REV lease schema; 05B; AUTH-PREP; planned review.claim typed contract; exact reviewer grant facts stable | Proposed | -| `WS-CON-001-07` | Atomic Contribution/Award Decision Participant | L1 | 03C-D, 05A, 06; AUTH-PREP and complete REV custody transfer; REV-04 FinalAcceptance plus REV-09B locked lineage; shared audit/outbox; planned review.decision typed contract; two ordered operation-specific inputs | Proposed | -| `WS-CON-001-08A` | Outbound Compensation Delivery Handler | L1 | 07, 02B; exact delivery ServiceIdentity/ActionId/static row registered but planned; AUTH-09E typed context/prepared protocol; ADR 0014 adapter foundation; lifecycle-fence port | Proposed | -| `WS-CON-001-08R` | Bound-Service Callback Rate Control | L1 | 08A; shared API-control contract | Proposed | -| `WS-CON-001-08B` | Inbound Fulfillment Callback | L1 | 08R; exact callback ServiceIdentity/ActionId/static row, AUTH-09E context, prepared protocol, and callback-fence port | Proposed | -| `WS-CON-001-09A` | Optional Contribution Evidence Projection Write | L1 | Separate human approval; refreshed ART/AUTH contract and chunk review | Deferred optional | -| `WS-CON-001-09B` | Optional Authorized Contribution Evidence Read | L1 | 09A plus separate approval; refreshed disclosure contract | Deferred optional | -| `WS-CON-001-10A` | Contribution And Award Product Reads | L1 | 08B; D11 award-role outcome; planned contribution/award read actions and typed contexts | Proposed | -| `WS-CON-001-10B` | Operations Requests, Reads, And Fulfillment Drain Observation | L1 | 10A; D11 complete; operations request/read actions/contexts/prepared protocol; outbox observation port | Proposed | -| `WS-CON-001-10C` | Reconciliation And Projection Executors | L1 | 10B; exact executor identities/actions/static rows; AUTH-09E; hidden behavior then AUTH activation | Proposed | -| `WS-CON-001-11` | Hidden Release Readiness And Dependency Manifest | L1 | 10C; merged REV-10 decision integration; exact AUTH evaluator/action/service manifest; every obligation-writer/dispatch/callback hook; monotonic root ordinal; same-session cutoff/drain port | Proposed | - -## Core dependency order +# Chunk Map: WS-CON-001 Contribution And Compensation + +Each implementation chunk is independently bounded and reviewed. Current +status comes from merged code/tests and `docs/roadmap_status.md`; historical +signed-loop records do not make behavior live. + +## Completed + +| Chunk | Outcome | Status | +|---|---|---| +| `PLAN`-`PLAN3` | Original boundary and cross-initiative planning | Historical planning | +| `01` | Canonical specification and ADR 0016 | Merged PR #144 | +| `02A` | Shared transactional outbox persistence/append | Merged PR #155; migration 0029 | + +## Current reconciliation + +| Chunk | Goal | Risk | Status | +|---|---|---:|---| +| `PLAN4` | Reconcile current main, ART/AUTH/REV changes, open PRs, and end-to-end order | L1 | Proposed planning-only change | + +## Core runtime chunks + +| Chunk | Goal | Entry gate | Status | +|---|---|---|---| +| `03A` | Adapter-binding persistence | PLAN4 accepted; refresh current migration head | Recommended first runtime chunk | +| `03B` | Contribution-policy persistence | 03A | Proposed; unblocks REV-03A2 FK | +| `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 | +| `05A` | Legacy semantic cutover + TaskAssignment policy freeze | 04B + task/assignment authority contract + row-classification decision | Proposed | +| `05B` | Legacy economic schema removal | 05A zero-consumer proof | Proposed | +| `06` | Reviewer policy lookup/freeze participant | 05B + REV lease contract/caller facts | Proposed; CON never owns lease | +| `03C` | ContributionRecord/CompensationAward persistence | 03B + merged REV Review/ReviewLease/FinalAcceptance targets | Proposed after REV-04B | +| `03D` | Delivery/receipt/status persistence | 03C | Proposed | +| `07` | Atomic flush-only review contribution/award participant | 03C/03D + 05A + 06 + stable REV revision lineage | Proposed; consumed by REV-10 | +| `02B` | Generic outbox dispatcher/recovery | AUTH dispatcher identity/action/matrix/context/PREP registration | Blocked on AUTH; required later, not before 03A/03B | +| `08A` | Outbound compensation delivery | 03D + 07 + 02B + 04A/04B + independent delivery authority | Proposed | +| `08R` | Bound callback rate control | 08A | Proposed | +| `08B` | Inbound fulfillment callback | 08R + independent callback authority/fence | Proposed | +| `10A` | Contribution/award product reads | 08B + exact AUTH read contracts | Proposed | +| `10B` | Operations requests/reads/drain observation | 10A | Proposed | +| `10C` | Reconciliation/projection executors | 10B + exact executor identities/actions | Proposed | +| `11` | Hidden release readiness and dependency manifest | 10C + REV/ART/AUTH integration gates | Proposed | + +Deferred optional work: + +| Chunk | Goal | Status | +|---|---|---| +| `09A` | Contribution evidence projection write | Deferred; requires new current ART/AUTH contract | +| `09B` | Authorized evidence read | Deferred after 09A; replacement contract required | + +## Dependency view ```text -PLAN -> PLAN2 -> PLAN3 -> 01 -> 02A -> 02B -> 02C -> 03A -> 03B -> 03C -> 03D --> 04A -> 04B -> 05A -> 05B -> 06 -> 07 -> 08A -> 08R -> 08B --> 10A -> 10B -> 10C -> 11 -``` +PLAN4 + -> 03A -> 03B ---------------------------> REV-03A2 + -> 04A -> 04B -> 05A -> 05B + -> 02C ----------------------------------> REV-04B -Optional successor, not a branch in the core release: +REV-04B + 03B -> 03C -> 03D +05B + REV lease/caller facts -> 06 +REV revision lineage + 03C/03D + 05A + 06 -> 07 -> REV-10 -```text -separate human approval -> refreshed ART/AUTH handoff -> 09A -> 09B +AUTH dispatcher registration -> 02B +03D + 07 + 02B + 04A/04B -> 08A -> 08R -> 08B -> 10A -> 10B -> 10C -> 11 ``` -## Cross-initiative gates +ART-03C is merged baseline evidence. Remaining ART submission/reviewer custody +and REV-03A1 may progress concurrently in their own branches; any open PRs are +integration input, not merged gates. -```text -AUTH registration -> CON hidden behavior -> AUTH activation -> later consumer/release -``` +## Review requirements + +All CON runtime chunks require senior engineering, QA/test, security/auth, +product/ops, architecture, docs, reuse/dedup, and test-delta review. Add CI +integrity for workflows, dependencies, test configuration, coverage, or +distributed-lane changes. + +## Stop -- AUTH-09A through 09D-B are merged; AUTH-09B activates only the human - administrative provisioning route, AUTH-09C activates only actor/profile - administrative reads, AUTH-09D-A activates only actor-profile lifecycle, and - AUTH-09D-B activates only identity-link revoke/reactivate. None grants - service execution. The contributor foundation is merged; AUTH-09E must still precede protected - fixed-service execution. New CON - ServiceIdentity/static-row additions require separate reviewed AUTH contracts - before provisioning; no existing ART identity or provisioning result may be - reused as CON authority. -- The outbox dispatcher owns only claim/invoke/finalize under - `outbox.dispatch`. Each protected handler has independent approved authority. -- Task claim requires AUTH-PREP and one exact active same-project submitter - grant. CON-05A first lands the hidden freeze participant; task-owned claim - composition consumes it after task/assignment locks; `WS-AUTH-001-13` then - enumerates/registers the exact ActionId, integrates its evaluator, and - activates. Registration/activation before that freeze proof is prohibited. -- Review claim requires one exact active same-project reviewer grant. CON-06 - supplies only the freeze port; REV supplies hidden claim composition; AUTH - activates review.claim after both merge. -- Review decision requires the reviewer grant and no-self-review/lifecycle - guards. CON-07 starts only after the TaskAssignment submitter freeze and REV - ReviewLease reviewer freeze plus accept-only FinalAcceptance persistence and - locked decision-lineage contract are merged with non-null policy-version - lineage. CON-07 then supplies the flush-only participant with no ART/evidence - work; REV consumes that participant in hidden decision composition, stages - shared audit/outbox, and owns the single commit. AUTH activates - `review.decision` only after that hidden REV composition merges. -- CON-07 creates contributions and applicable awards in the Review transaction. - Reviewer work is sourced from Review; submitter work is sourced only from - REV-owned FinalAcceptance. REV stages shared audit/outbox rows, owns the - single commit, and supplies stabilized artifact-hash lineage; no ART call is - made. -- Merged REV PR #128 plus PLAN2 PR #150 are planning authority, not runtime - readiness. CON-03B precedes REV-03A; CON-02A/02C precede REV-04B; REV-04B - precedes CON-03C; CON-06 precedes REV-06A; REV-09B plus CON-03C/07 precede - REV-10; the CON-02B dispatcher/handler registry precedes REV-12P1; CON's - 03D/08A/08B/10B/11 hooks precede REV-12A3; and CON-11 precedes REV-13C. -- CON-08A/B and 10C cannot reuse outbox dispatcher authority for delivery, - callback, reconciliation, or rebuild execution. -- CON-10A owns core PostgreSQL contribution/award reads directly; it does not - wait for optional evidence reads. -- CON-11 has no ART or evidence-projection prerequisite. It hands mandatory - obligation-writer, dispatch, callback, maximum-ordinal, and drain-observation - seams to REV-12A1/12A3's single shared lifecycle controller and registers no - route. -- AUTH PR #140's complete ART and REV activation-custody transfer contracts are - consumed by reference to AUTH/WS-XINT handoffs. The runtime transfers remain - upstream gates; WS-CON does not define partial subsets. - -## Chunk boundaries - -- 01 owns current specification/ADR adoption and scanner-safe active wording; - it does not edit archival inputs. -- 02A owns persistence/append; 02B owns generic dispatcher mechanics only; 02C - owns the shared caller-transaction audit participant. -- 03A uses `ProjectCompensationAdapterBinding`; 03B owns ContributionPolicy, - versions, rules, and award definitions; 03C/D own contribution/award and - downstream fulfillment records respectively. 03C references but never owns - REV's FinalAcceptance. -- 04A/04B add hidden binding and policy services while AUTH actions remain - planned. -- 05A removes semantic consumers and freezes task assignments; 05B removes dead - physical schema. -- 06 exposes only a CON policy-freeze capability; REV owns ReviewLease schema - and wiring. -- 07 exposes only the flush-only decision participant; REV owns Review, - FinalAcceptance, shared audit/outbox staging, and the single commit. No - evidence projection is staged. -- 08A is a feature handler with its own protected execution boundary; 08R owns - rate-control scope; 08B owns callback authentication/composition. -- 09A/09B are deferred optional projection chunks and must be re-reviewed if - activated later. -- 10A owns core PostgreSQL product reads; 10B owns bounded operations requests - and typed drain observation; 10C owns independently authorized executors. -- 11 proves hidden readiness and blocks runtime requests on missing provisioned - service rows while leaving application startup and provisioning available. - -## Required reviewer tracks - -Every chunk: senior engineering, QA/test, security/auth, product/ops, -architecture, docs, and reuse/dedup. Runtime/test chunks add test-delta. Add CI -integrity for workflows, scripts, dependencies, test configuration, or coverage. - -## Stop condition - -Planning ends after required plan review and human discussion. Do not start 01, -09A, or any runtime chunk automatically. +This planning change stops before runtime. The recommended next bounded change +after human approval is CON-03A only. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md index 254659c7c..6857d50ac 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/CONFORMANCE_MATRIX.md @@ -5,7 +5,7 @@ | Canonical policy model | 01,03B,04B | ContributionPolicy/version/rules/definitions; explicit unpaid; immutable publish; one active policy; NUMERIC(38,18) decimal-string bounds; ISO 4217 money units; project-scoped points units; stable binding references | CON-11 | | Adapter binding | 03A,04A,10B | one active binding per project/instrument; policy definitions and awards reference a binding with matching project/instrument identity while the binding stores no policy/award identifiers; non-secret route; suspend/resume and existing-award callback/replay behavior; retirement refuses active policy, unfinished frozen work, or unfulfilled award dependencies | CON-11 + joint live drill | | Legacy clean cut | 05A,05B | zero semantic consumers before schema removal; deterministic row treatment; no alias/fallback; migration upgrade/downgrade | CON-11 | -| Authorization | AUTH + each feature | current 74 PermissionId / 65 ActionId / 17 active / 48 planned baseline after AUTH-09D-B; contributor-foundation PR #153 changes human attribution and write revalidation only; provisioning grants no service execution or admission; all CON mappings/identities/static rows remain unregistered; full ART/REV custody referenced; one future AUTH custodian; planned denial; exact grant/static row; AUTH-09E; prepared handle bound to session/action/actor-ref/idempotency/request digest with substitution non-consumption; no local role logic | AUTH activation + CON-11 | +| Authorization | AUTH + each feature | current AUTH actor/grant/fixed-service/PREP and REV-readiness foundations, with current repository migrations through ART-owned `0050`; provisioning grants no service execution; CON mappings, identities, and static rows are absent on current main; every future artifact requires exact AUTH-owned registration and activation evidence, exact grant/static row, fixed-service admission, prepared handle bound to session/action/actor-ref/idempotency/request digest with substitution non-consumption, planned denial, and no local role logic | AUTH activation + CON-11 | | Final acceptance | REV + 03C,07 | accept creates one immutable FinalAcceptance per task/Review/Submission; needs_revision/reject create none; no create API/action, reopen, replacement, or adjudication path | joint live drill | | Contribution cardinality | 03C,07 + REV | one completed_review per valid Review with direct Review/lease lineage; one accepted_submission per FinalAcceptance with assignment lineage; mutually exclusive sources; revision Reviews distinct; automated outcomes create none | joint live drill | | Policy freeze | 05A,06 + task/REV | exact submitter/reviewer fields; published version; no drift; publish/suspend races both orders | joint live drill | diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md index e256c6124..ee9e19b29 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DECISIONS.md @@ -1,326 +1,74 @@ -# Decisions: WS-CON-001 Contribution Record And Compensation Boundary +# Decisions: WS-CON-001 Contribution And Compensation -## D1 - Canonical Contract Is Repository-Owned +## D1 — Canonical authority -**Status:** accepted. +Code, migrations, tests, accepted ADRs, canonical subsystem specifications, +`docs/roadmap_status.md`, and merged history establish current behavior. +Imported references, old status snapshots, signed-loop records, and open PRs +are historical or in-progress evidence, not proof that behavior is live. -The supplied reference files are archival inputs. The active implementation -contract is `docs/spec_contribution_compensation.md` plus ADR 0016, produced by -CON-01 and reconciled with trusted `main`, including AUTH PR #140, merged -AUTH-09B PR #143, and WS-XINT-001 PR #139. Archival files are not edited or -treated as runtime authority. +## D2 — Contribution sources -## D2 - ContributionPolicy Is The Only Award-Eligibility Policy +Every committed human Review creates exactly one reviewer `completed_review`. +Only REV-owned FinalAcceptance creates one submitter `accepted_submission`. +Needs-revision and reject never create submitter contributions. -**Status:** accepted; supersedes the older WS-CON naming. +## D3 — Award policy -The canonical aggregate is `ContributionPolicy`, immutable -`ContributionPolicyVersion`, `ContributionRule`, and -`ContributionAwardDefinition`. It decides whether a ContributionRecord is -unpaid or creates money and/or project-points CompensationAwards. The retired -guide-bound economic schema is completely removed in CON-05A/05B. There is no -alias, automatic conversion, historical fallback, or second executable policy. +ContributionPolicyVersion is the sole award-policy authority. Explicit unpaid +rules create no award; compensated rules create only immutable configured +money/project-points awards. No fallback economic model exists. -## D3 - Existing Submission Is The Version Identity +## D4 — Transaction ownership -**Status:** accepted. +REV owns review orchestration and the single commit. CON receives the caller +AsyncSession, stages and flushes exact rows, and never commits or repairs a +partial review afterward. -Existing `Submission` plus its `version` and `supersedes_submission_id` is the -versioned identity. ContributionRecord uses `submission_id` and the stabilized -artifact-hash lineage supplied by REV. WS-CON does not add a -`SubmissionVersion` table or reload artifact bytes through ART. +## D5 — Lease ownership -## D4 - AUTH Owns Registration, Evaluation, And Activation +CON owns policy lookup; REV owns ReviewLease persistence and transitions. The +lease stores a non-null CON policy-version FK, but that dependency transfers no +lease authority to CON. -**Status:** accepted by WS-XINT-001 D1/D2. +## D6 — Artifact boundary -WS-CON proposes product actions and typed facts, but AUTH owns ActionId, -PermissionId mapping, ActionOwner activation custody, typed resource contexts, -principal admission, evaluator dispatch, decision evidence, grants, the fixed -service static matrix, and availability. Each action follows planned -registration -> hidden feature behavior -> AUTH evaluator integration and -activation. CON never changes availability or implements a local role fallback. +CON copies stable accepted Submission/binding/hash lineage supplied by REV. +Core contribution creation has no ART repository, capability, provider, bytes, +scratch, or credential dependency. -The stable PermissionIds may retain older broad namespace strings. New policy -ActionIds use `contribution.policy.*` and map to existing -`compensation.policy.manage`; the PermissionId string does not rename the -canonical product model. +## D7 — Corrected implementation order -## D5 - Derived Contributions And Awards Are Review Participants +CON-03A/03B proceed before the dispatcher because they are independent and +03B unblocks REV lease persistence. CON-02C proceeds before REV-04B without +waiting for dispatch. CON-02B moves later, before projection/fulfillment +consumers, after exact AUTH registration. -**Status:** accepted by WS-XINT-001 D7 and the REV/CON handoff. +## D8 — Authorization custody -The authorized `review.decision` transaction invokes one mandatory CON -participant in the caller's AsyncSession. It creates a reviewer -`completed_review` for every committed Review. For accept only, REV first -creates FinalAcceptance and CON creates `accepted_submission` from that locked -fact, never directly from Review.decision. CON evaluates each applicable frozen -ContributionRule, stages applicable contribution/award rows, returns typed -audit/outbox inputs to REV, flushes, and never commits. REV stages the shared -audit/outbox records and owns the single commit. There is no `contribution.materialize` or -`compensation.award.materialize` action and no no-op production participant. +AUTH owns every CON-related permission/action mapping, principal, context, +prepared capability, evaluator, evidence constraint, and activation. CON may +publish feature manifests and consume typed decisions; it may not add a second +authorization path. -## D6 - ART Is Not A Core Contribution Dependency +## D9 — Dispatcher isolation -**Status:** accepted by WS-XINT-001 D7; supersedes the prior mandatory evidence -design. +`outbox.dispatch` permits generic claim/invoke/finalize mechanics only. A +handler must present its own approved identity/action/context. Dispatch never +confers feature or provider authority. -Core contribution creation performs no ART capability call, artifact -authorization, provider I/O, or evidence projection. CON copies the stabilized -Submission/packet digest supplied by REV into -`ContributionRecord.artifact_hash` and does not verify or rederive it. +## D10 — Legacy migration -An evidence document may be proposed later only as an optional asynchronous -projection with independent status/failure semantics, a separately reviewed ART -capability, and a separate AUTH action. Its failure cannot alter Review, -ContributionRecord, CompensationAward, fulfillment receipt, or status truth. +Retired economic rows require a deterministic human-approved classification. +Ambiguity fails migration. Planning never reserves Alembic revision numbers. -## D7 - Shared Outbox Is A Prerequisite +## D11 — Evidence projection -**Status:** accepted through ADR 0016 and explicit CON-01 start. +Contribution evidence is optional preservation for future reputation +projection. It cannot gate core PostgreSQL truth, reads, release, or +fulfillment. Runtime reputation scoring remains deferred. -One generic shared outbox owns append, claim, retry, dead-letter, replay, and -finalization mechanics. Feature handlers return typed outcomes and do not query -or mutate outbox persistence directly. No review-private or compensation- -private dispatcher is allowed. +## D12 — Planning stop -## D8 - Coherent Public Activation - -**Status:** accepted through ADR 0016 and explicit CON-01 start. - -Contribution-policy, binding, contribution, award, callback, and operations -routes remain hidden until exact AUTH actions/evaluators/principals, required -REV participants, outbox/audit, migrations, and release proof are complete. -Optional contribution-evidence projection is not a release dependency. - -## D9 - External Rails Fulfill Awards But Never Decide Eligibility - -**Status:** accepted. - -Workstream persists immutable awards, exact outbound instructions, delivery -evidence, immutable fulfillment receipts, and rebuildable status. External -money settlement and project-points adapters own provider execution, accounts, -balances, and ledger entries. They cannot create, change, void, or infer award -eligibility. - -## D10 - AUTH Owns Prepared Cross-Domain Mutation Authorization - -**Status:** required architecture contract. - -AUTH locks and revalidates human actor/link/grant rows or fixed-service -actor/link rows first. Fixed services additionally require immutable -ServiceIdentity, exact static service-action matrix membership, AUTH-09E typed -admission, and active action as code-owned validations rather than lock targets. -AUTH returns one opaque, single-use `PreparedAuthorizationHandle` bound exactly -to session, ActionId, actor-reference kind/reference, idempotency key, and -canonical request digest. The feature then locks product rows and recomposes -final typed facts; AUTH consumes the handle, evaluates exactly once, and stages -decision evidence. AUTH and feature participants flush only; the route or -service command commits once. - -Missing, reused, serialized, caller-constructed, cross-session/action/actor/ -request, binding-mismatched, or authority-lost handles fail closed before -feature mutation. A failed substitution does not consume an otherwise valid -handle. Product-first locks, unlocked resource snapshots, double decisions, -and feature-side catalogue changes are rejected. - -## D11 - Project Roles Are Independent; Admin Candidate Differences Remain Exact - -**Status:** project-role model resolved by ADR 0015; AdminRole surface choices -remain human gates before CON-10A/10B. - -The current shipping path requires exact `submitter` for task claim and exact -`reviewer` plus no-self-review for review claim/decision. Any unrelated project -or administrative grant does not substitute. The existing global AUTH project- -role catalogue remains AUTH-owned, but WS-CON adds no adjudication grant, -action, invalidation consumer, or readiness dependency. - -Merged AUTH currently gives Finance Authority -`compensation.delivery.reconcile` but not Operator, while the earlier WS-CON -candidate also proposed reason-bound Operator recovery. Merged Project Manager -has `compensation.award.read`, while the earlier candidate narrowed award -detail. Audit candidates also differ. The human must select each exact action -candidate set before registration. Any change is AUTH-owned and evaluator- -closed; CON never queries roles or infers access from PermissionId membership. - -## D12 - ActionOwner Is AUTH Activation Custody - -**Status:** resolved by WS-XINT-001 D1-D3; no local alternative remains. - -AUTH must provide one exact activation custodian for each proposed CON action -and complete, not partially repeat, the canonical transfers for all current ART -and REV actions. Every ActionId-to-PermissionId mapping is preserved, and closed -typed/SQL/audit/definition-owner parity rejects dual, missing, unused, or extra -owners. WS-CON depends on review.claim/review.decision but does not prescribe a -two-action REV transfer or an eleven-action ART subset. - -## D13 - Fixed Service Admission Uses Static Matrix Membership - -**Status:** accepted architecture; exact new identities/actions remain an -AUTH/human registration gate. - -There is no database service-grant or service-action-assignment model. A fixed -service uses verified token -> ActorIdentityLink -> service ActorProfile -> -immutable closed ServiceIdentity -> exact static ActionId row -> AUTH-09E typed -context -> feature resource facts -> decision. - -The shared outbox dispatcher may only claim/invoke/finalize outbox work under -`outbox.dispatch`; it does not inherit protected handler or provider authority. -Outbound delivery, asynchronous reconciliation, contribution projection -rebuild, and fulfillment callback each require an exact approved service -identity/action/static row or an explicitly approved closed dual-principal -evaluator before implementation. Missing provisioned rows deny runtime but do -not prevent application startup or administrative provisioning. - -## D14 - Optional Evidence Is A Deferred Successor - -**Status:** deferred and not approved for implementation. - -CON-09A/09B are outside the core dependency order. If the human later approves -them, their chunk contracts must be refreshed against then-current ART/AUTH -contracts and internally reviewed again. The optional evidence action is not -counted as a core release action and cannot gate product reads or release. - -## D15 - FinalAcceptance Is The Sole Submitter-Acceptance Source - -**Status:** accepted by explicit human direction on 2026-07-17; REV merge is an -upstream implementation gate. - -REV owns immutable FinalAcceptance and creates it only inside an authorized -`Review(accept)` transaction. There is no manual/public create API and no -separate authorization action: creation is a lifecycle consequence of the -already-authorized review operation. `needs_revision` and `reject` create none. - -The non-accept effects follow REV's canonical lifecycle: `needs_revision` sets -the Task to `needs_revision` and keeps its TaskAssignment `active`; `reject` -sets the Task to `rejected` with a bounded human reason and blocks only the -same-task TaskAssignment with its source Review. Reject changes no grant or -unrelated task. The archival `closed/review_rejected` wording is not adopted. - -The repository's existing immutable `Submission` row is already the submission -version identity. Therefore FinalAcceptance stores canonical `submission_id`, -not `submission_version_id`, and enforces unique task, source Review, and -Submission lineage. Merged REV-04 retains `policy_context_ref` as the foreign -key to canonical immutable `ReviewPolicy.id` and retains `recorded_by` as the -reviewer ActorProfile field; REV proves the locked same-chain lineage. CON adds -no aliases and does not interpret review policy as contribution policy or use -it to decide awards. - -`completed_review` keeps direct Review/ReviewLease lineage and is unique per -Review. `accepted_submission` requires `source_final_acceptance_id` plus the -exact TaskAssignment and is unique per FinalAcceptance; its direct -`source_review_id` is null because the FinalAcceptance already owns that link. -Database checks enforce the mutually exclusive source shapes. - -REV creates Review and optional FinalAcceptance, applies task/assignment -effects, invokes the mandatory CON flush-only participant, stages shared audit/ -outbox records, and commits once. CON failure rolls the entire unit back. ART -and provider calls remain absent; fulfillment begins asynchronously after -commit. V0.1 has no adjudication policy, queue, lease, state, decision, -contribution type, branch, action, readiness check, or initiative dependency. - -## D16 - AUTH Planning And Provisioning Do Not Activate CON - -**Status:** accepted by merged AUTH PR #140, AUTH-09B PR #143, AUTH-09C PR -#146, AUTH-09D-A PR #148, AUTH-09D-B PR #152, and contributor-foundation PR -#153 through current main `8d5eb15b`; REV PLAN2 PR #150 and ART-02B1 PR #151 change no AUTH catalogue -fact. - -Trusted main `8d5eb15b` after contributor-foundation PR #153 has 74 -PermissionIds, 65 ActionIds, 17 -active actions, and 48 planned actions, with no registered CON or task-claim -ActionId. AUTH-09B activates only `actor.service.provision`; its controlled -human-administrator route can create the ActorProfile/ActorIdentityLink for an -already-approved closed ServiceIdentity but grants no service execution, -runtime admission, role, grant, or database action assignment. AUTH-09C -activates only administrative `actor.profile.read` and -`actor.identity_link.read`. AUTH-09D-A activates only the three actor-profile -lifecycle actions; AUTH-09D-B activates only identity-link revoke/reactivate. -The contributor foundation is merged and changes attribution/write identity -validation without changing authorization availability. Fixed-service -admission remains planned. PR #140 supplies -the exact prepared protocol, complete ART/REV custody maps, and feature-manifest -activation rule; those runtime implementations remain upstream work. - -CON removes speculative `AUTH_CON_*` owner labels. Its proposed action mappings -remain unregistered and non-final until each complete feature manifest exists -and AUTH assigns an exact `WS-AUTH-001-*` custodian. Only the `task.claim` -PermissionId exists today; AUTH-13 must not register or activate a task-claim -ActionId before task-owned composition consumes CON-05A's immutable -TaskAssignment policy freeze. `review.claim` similarly consumes CON-06 through -REV, and `review.decision` consumes CON-07 through the rollback-safe REV-owned -transaction. AUTH alone registers/evaluates/activates; CON alone supplies its -hidden facts and participants. Future CON fixed services require new reviewed -ServiceIdentity/static-matrix additions and later AUTH-09E admission; AUTH-09B -does not make the current ART-only fixed identity set reusable by CON. - -## D17 - Review Contribution Integration Uses Two Ordered Operations - -**Status:** accepted from merged REV PR #128 on 2026-07-17. - -One mandatory CON participant exposes two operation-specific flush-only methods -in REV's caller session. The reviewer method runs after immutable Review/ -finding/resolution creation plus lease/queue closure and before the decision -branch. It accepts no FinalAcceptance, submitter source, or submitter policy. -The submitter method exists only after `accept` creates FinalAcceptance and -applies accepted Task/TaskAssignment effects. It accepts no direct Review/ -ReviewLease contribution-source shape. An omnibus input with nullable -FinalAcceptance or both actors' policy contexts is prohibited. - -Each method evaluates only its frozen ContributionRule, creates its own -contribution and eligible awards, returns typed shared-audit/outbox inputs, and -never commits. REV collects the invoked results, stages the shared rows, and -the request route or service command commits once. - -## D18 - REV Owns One Joint Controller; CON Supplies Fenced Fulfillment Hooks - -**Status:** accepted from merged REV PR #128 on 2026-07-17. - -REV-12A1 owns the sole PostgreSQL `JointLifecycleReleaseControl`, and REV-12A3 -composes CON against the shared `JointLifecycleMutationFence`. CON creates no -parallel phase/controller. Every -fulfillment-obligation root creation, requeue, successor, and repair writer -must acquire that fence before it allocates one immutable, monotonically -increasing root ordinal or locks obligation rows. - -CON's same-session drain observation returns outbox/fulfillment counts and the -current maximum ordinal. REV atomically persists that value as the generation -cutoff after admitted writers drain. During `delivery_draining`, dispatch and -callback may finalize only a same-generation root at or below the cutoff and -cannot create follow-on obligations. Provider I/O occurs after the fenced -pre-I/O transaction commits and releases every database/advisory lock. - -## D19 - Economic Quantities And Provider Receipts Are Bounded Canonical Facts - -**Status:** accepted through ADR 0016 security review. - -All policy definitions, immutable awards, and fulfilled quantities use -`NUMERIC(38, 18)` with canonical decimal-string input, common Pydantic, -application, and PostgreSQL bounds, and no binary float, exponent, rounding, or -conversion path. Money units are enabled uppercase ISO 4217 codes; -project-points unit identity is `(project_id, unit_code)`. - -Immutable fulfillment receipts store only closed status/failure facts, -binding-scoped bounded non-secret opaque event/reference identifiers, exact -quantities, and canonical digests. Raw provider secrets, authentication tokens, -unbounded bodies, free-form messages/codes, headers, signatures, endpoints, -credentials, URLs, markup, or metadata are never persisted, logged, emitted, -exported, or returned. The bounded receipt identifiers are not authentication -tokens and may appear only in their canonical receipt/status fields. Unknown -provider failures map to the closed generic failure code before persistence. - -## D20 - Repository-Wide Runtime Proof Runs In GitHub CI - -**Status:** accepted by human direction for CON-02A and later runtime chunks. - -Repository-wide tests and repository coverage run in the existing GitHub -Backend full-suite job after a full PR is pushed. Agents do not run the -multi-hour repository suite locally. Local proof remains bounded to the active -chunk's focused real-service tests, subsystem coverage floor, Ruff, migration -head, documentation links, stale-contract scans, and agent-loop gates. - -This changes execution location, not proof strength. GitHub must still run the -unchanged full test selection with isolated PostgreSQL, real MinIO where -required, and the repository 78 percent coverage floor. A focused local pass -cannot waive a missing or failing GitHub result, and the subsystem 90 percent -coverage floor remains required. +PLAN4 changes planning records only. The recommended next implementation is +03A, and it begins only after human approval from then-current main. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DISCOVERY.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DISCOVERY.md index 04a96f8c8..07084a8fa 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DISCOVERY.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/DISCOVERY.md @@ -1,290 +1,125 @@ -# Discovery: WS-CON-001 Contribution Record And Compensation Boundary +# Discovery: WS-CON-001 Current-Main Reconciliation -## Baseline inspected +## Baseline -- trusted `origin/main` refreshed to `8d5eb15b`, including contributor-foundation - PR #153, AUTH-09D-B PR #152, - ART-02B1 PR #151, planning-only REV PLAN2 PR #150, AUTH-09D-A PR #148, REV-02 PR #147, - REV-01 PR #145, AUTH-09C PR #146, ART PR #141, CON-01 PR #144, AUTH-09B PR - #143, REV planning PR #128, AUTH-09A, AUTH PR #140, and the earlier WS-XINT - PR #139 boundary; -- complete WS-XINT intent, decisions, plan, REV/CON, AUTH/role-service, - AUTH/REV, AUTH/ART, and ART/REV handoffs; -- current WS-CON initiative package and archival reference inputs; -- canonical README, glossary, architecture lockdown/data model/lifecycle, - authorization spec, artifact spec, roles/operations docs, and ADRs 0012-0015; -- current backend project/task/submission/checker, AUTH, audit, artifact, and - migration code/tests; -- human-approved 2026-07-17 FinalAcceptance/no-adjudication direction and the - complete merged WS-REV-001 planning package; -- stale wording, authorization, artifact, link, loop-memory, and agent-gate - scanners/tests. +- Protected `main`: `2feaf47dd5bb448db076179d96751caa55fb0994`. +- Latest Backend run for that SHA failed one unrelated AUTH actor-profile + concurrency test in `shared_foundations`; the same failure also occurred on + the prior PR head. This planning diff changes no AUTH/runtime/test/CI files. +- Current Alembic head: `0050_guide_source_v2`. +- ART PR #249 merged the guide-source v2 cutover. No CON migration number is + reserved before a fresh main update at implementation start. +- CON-01 merged in PR #144; CON-02A merged in PR #155 as migration + `0029_shared_transactional_outbox`. +- Current runtime has generic outbox persistence/append but no dispatcher, + contribution, compensation, award, delivery, or fulfillment modules. -## Current runtime observations +## Repository process -- The backend stops before the human Review/ContributionRecord implementation. -- Project code still has the retired guide-bound economic schema. There is no - canonical ContributionPolicy aggregate, ContributionRecord, - CompensationAward, fulfillment receipt, or status projection runtime. -- Existing Submission rows carry `version` and supersession lineage. A separate - SubmissionVersion model would duplicate current identity. The handoff field - named `submission_version_id` therefore maps to canonical `Submission.id` and - is stored as `submission_id`. -- No FinalAcceptance runtime exists yet. Merged REV PR #128 plus PLAN2 PR #150 - are reviewed planning authority and define the exact schema/transaction, but - CON-03C still waits for the REV-04B runtime target. -- The merged AUTH catalogue has 74 PermissionIds and 65 ActionIds. Seventeen - actions are active and 48 are planned. AUTH-09B activates only - `actor.service.provision`; AUTH-09C activates only `actor.profile.read` and - `actor.identity_link.read`; AUTH-09D-A activates only the three actor-profile - lifecycle actions; AUTH-09D-B activates only `actor.identity_link.revoke` - and `actor.identity_link.reactivate`. No WS-CON or task-claim ActionId is - registered. The contributor-field/canonical-human foundation is merged: - TaskAssignment and Submission now expose `contributor_id`, enforce canonical - human ActorProfile lineage, and revalidate active human writers. AUTH-09E - fixed-service admission remains proposed. -- Current AUTH supports actor-self, AdminRoleGrant evaluation, and controlled - human-administrator provisioning of an approved fixed service - ActorProfile/ActorIdentityLink. Independent ProjectRoleGrant runtime, - fixed-service runtime admission, CON evaluators, ART/REV custody transfer, and - the cross-domain prepared mutation protocol remain future AUTH work. PR #140 - adds their reviewed plans, not runtime. -- AUTH's static service-action matrix is typed code; it is not a database grant - table. AUTH-09E is the required runtime admission path. -- PR #129 added inactive ART preparation/source values only. It added no - contribution-evidence capability, ART admission/provider execution, binding, - action, permission, or CON dependency. -- No shared transactional outbox exists with the required generic dispatcher, - claim fencing, replay, and typed handler outcome contract. +Current repository entry documents use the simple engineering loop in +`CONTRIBUTING.md` and treat `.agent-loop` records as durable planning context, +not product state. Code, migrations, tests, canonical specifications, current +capability status, and merged history establish implemented behavior. -## CON-02A focused discovery +The old authored CON status and signed-loop narrative are historical. They do +not show live runtime behavior and must not be used to restart CON-02A. -- Trusted `main` at `8d5eb15b` ends its migration chain at AUTH-owned - `0027_contributor_foundation`; CON-02A owns linear revision - `0028_shared_transactional_outbox` and must import its model through - `backend/app/db/models.py` so metadata and migration truth agree. -- `app.core.hashing.canonical_json_hash` is the only repository canonical JSON - encoder. It sorts object keys, rejects non-finite numbers, uses compact UTF-8 - JSON, and returns a `sha256:` digest. The outbox must call it directly and - must not introduce another serializer or digest helper. -- `AuthorityIdempotencyRepository` establishes the local concurrency pattern: - insert with PostgreSQL `ON CONFLICT DO NOTHING`, lock the existing namespace - row, compare the canonical digest, and complete through the caller's - `AsyncSession` without committing. Outbox append can reuse this sequence - without importing AUTH or creating a second generic idempotency framework. -- The common event envelope requires stable event ID, type, version, producer, - project, correlation, causation, idempotency key, canonical object payload, - and database-authoritative occurrence time. Delivery attempt/state fields - are operational metadata and must be independently mutable without allowing - immutable envelope drift. -- CON-02B has no migration allowance. CON-02A must therefore land the complete - feature-neutral persistence shape needed later for pending/claimed/retryable/ - acknowledged/dead-letter dispatch, claim generation/lease, attempts, - eligibility, bounded failure evidence, and retention while exposing only - append/replay behavior in this chunk. -- Existing audit and AUTH repositories flush and refresh on the supplied - session but never commit or publish. PostgreSQL triggers are already used for - append-only/immutable custody and guarded downgrade checks; the shared outbox - should follow those repository conventions. -- ART PR #141 adds artifact adapters, startup wiring, and an artifact delivery - executor but no shared outbox module, outbox route, dispatcher registry, - broker publication seam, or outbox permission. CON-02A therefore remains - feature-neutral and authorization-neutral and does not call ART. -- AUTH-09C PR #146 adds serialized administrative actor/profile reads and - activates their already-canonical action/permission pairs. It adds no - migration, CON/outbox identifier, service admission, or dispatcher seam. -- REV-01 PR #145 canonically publishes the Review/revision lifecycle and keeps - REV transaction ownership, ordered CON flush-only participation, - FinalAcceptance source integrity, and shared audit/outbox staging intact. It - changes documentation/gates only and adds no runtime outbox consumer. -- REV-02 PR #147 is planning-only chunk decomposition for future guide, - ReviewPolicy/task, and submission-attribution work. It adds no backend, - migration, test-runner, CON, or outbox behavior. -- REV PLAN2 PR #150 is a planning/specification-only runtime-readiness refresh. - It preserves the two ordered CON operations and REV-owned atomic decision - transaction while splitting future runtime gates: CON-03B precedes REV-03A, - CON-02A/02C precede REV-04B, CON-03C/07 precede REV-10, the shared outbox - dispatcher/handler registry precedes REV-12P1, CON lifecycle hooks precede - REV-12A3, and CON-11 precedes the sole product release in REV-13C. It changes - no 02A runtime or migration. -- ART-02B1 PR #151 adds the S3-compatible adapter, MinIO/AWS configuration, - exact SDK pins, CI MinIO service, and substantial artifact/configuration test - coverage. It adds no migration, outbox import, shared dispatcher seam, or - core CON dependency. It therefore leaves 02A's implementation boundary - unchanged while requiring fresh repository-wide evidence on the larger - dependency and test tree. -- AUTH-09D-B PR #152 activates exactly the two identity-link lifecycle - mutations and expands AUTH routes/tests without adding a migration, CON - action, task-claim action, fixed-service admission, or outbox seam. The - at that point the reviewed contributor foundation followed it; AUTH-09E - remains a later gate. -- Contributor-foundation PR #153 clean-cuts TaskAssignment and Submission - attribution to `contributor_id`, installs database-enforced - canonical-human lineage, and adds transaction-local active-human write - revalidation. It owns migration `0027_contributor_foundation` and therefore - moves CON-02A to linear child `0028_shared_transactional_outbox`. It changes - no ActionId, PermissionId, availability, grant, evaluator, service admission, - review lifecycle, dispatcher seam, or outbox behavior. -- ART-02C1 PR #154 owns `0028_artifact_admission` on trusted main `44f2467c`. - It adds no outbox seam or CON authority, so CON-02A moves unchanged to the - linear child `0029_shared_transactional_outbox`. +## AUTH findings -## Canonical merged changes affecting CON +Merged AUTH/XINT work now provides: -1. `ContributionPolicy`, `ContributionPolicyVersion`, `ContributionRule`, and - `ContributionAwardDefinition` decide award eligibility. CompensationAward - is the evaluated downstream result. -2. Every valid Review creates reviewer `completed_review`. REV creates exactly - one FinalAcceptance for `accept`; submitter `accepted_submission` consumes - FinalAcceptance rather than inferring acceptance from Review.decision. -3. Core contribution creation is a flush-only CON participant in the REV-owned - transaction. It performs no ART call or evidence projection. -4. CON copies the stabilized versioned Submission/packet digest supplied by REV - into `ContributionRecord.artifact_hash`; it does not verify or rederive it. -5. The current shipping path consumes exact submitter and reviewer grants only. - The separate global AUTH role catalogue is not expanded here; no adjudication - behavior or readiness dependency enters WS-CON. -6. ActionOwner is AUTH activation custody. ART and REV transfers must be - complete across their full current catalogues; WS-CON cannot prescribe - partial subsets. -7. Fixed services use provisioned ActorProfile/ActorIdentityLink, immutable - ServiceIdentity, exact static ActionId row, and AUTH-09E admission. -8. The shared outbox dispatcher cannot inherit protected feature-handler - authority. Delivery, reconciliation, rebuild, and callback boundaries need - exact approved service contracts. -9. REV owns FinalAcceptance persistence, Review/task effects, shared audit/ - outbox staging, and the single commit. CON validates the locked acceptance - fact, flushes contributions/awards, returns a typed result, and never commits. -10. PR #140 fixes the prepared handle to exact session, ActionId, - actor-reference kind/reference, idempotency key, and canonical request - digest bindings. Final resource facts are recomposed after feature locks; - AUTH consumes the handle, evaluates once, and stages evidence. -11. PR #140 publishes complete 25-ART/19-REV custody-transfer maps, but those - availability-neutral runtime transfers remain proposed. CON depends on the - complete REV transfer and never restates a two-action subset. -12. Trusted main has stable PermissionId `task.claim` but no task-claim - ActionId. CON-05A's hidden TaskAssignment policy freeze must merge into - task-owned claim composition before AUTH-13 enumerates/registers and - activates that action. -13. Merged REV rejects the prior omnibus CON decision input. One mandatory - participant exposes a reviewer operation before the decision branch and an - accept-only submitter operation after FinalAcceptance and accepted task - effects. Neither input carries nullable cross-actor source/policy facts. -14. REV-12A1/12A3 require one shared `JointLifecycleMutationFence`. Every CON - fulfillment-obligation creation/requeue/successor/repair writer must fence - before allocating an immutable monotonic root ordinal. CON must expose the - current maximum ordinal with drain counts; delivery-draining dispatch and - callback may complete only same-generation roots at or below REV's cutoff. +- canonical actors, project-role grants, fixed-service runtime admission, and + prepared authorization foundations; +- project create/guide mutation/read foundations; +- immutable review/revision policy identity and active policy mutations; +- all approved REV actions, principals, typed resource/PREP/read contracts, + and PostgreSQL readiness evidence through PRs #242, #248, #255, and #257. -## Relevant files and symbols +Still absent from runtime: -| Source | Observation | -|---|---| -| `docs/architecture_data_model.md` | Canonical policy/rule/definition, binding, contribution, award, receipt, and projection names/fields | -| `docs/decision_0015_project_contributor_roles_are_independent.md` | Exact project role values and independent revocation | -| `docs/spec_authorization_service.md` | Stable permissions, current actions, ActionOwner semantics, static service matrix, AUTH-09E order | -| `WS-AUTH-001/ACTIVATION_CUSTODY.md` | Exact complete custody transfers, feature-manifest activation gates, and mandatory CON participant prerequisite for review.decision | -| `WS-AUTH-001-PREP` chunk | Exact prepared-handle bindings, authority-first locks, single use, caller-owned commit, and concurrency/rollback proof | -| `WS-AUTH-001-13` chunk | Future task-claim ActionId enumeration, registration, evaluator integration, and activation owner; exact submitter grant, task-owned resource composition, and AUTH-PREP dependency | -| `WS-AUTH-001-16` chunk | Aggregate proof that active review.decision uses one rollback-safe REV+CON transaction with no ART/fallback | -| `WS-XINT-001/REV_CON_HANDOFF.md` | Exact core participant sequence and optional-evidence boundary | -| `WS-REV-001/CON_INTEGRATION_REVIEW.md` | Merged two-operation participant, exact lineage, interleaving, and release-control dependencies | -| `WS-REV-001-08/10` chunks | Decision input freeze followed by first hidden canonical Review commit only after exact CON participant merge | -| `WS-REV-001-12A1/12A3` planning children | Single shared lifecycle fence, obligation-writer ordinal order, cutoff capture, and drain-phase behavior required from CON | -| `WS-XINT-001/AUTH_ROLE_SERVICE_HANDOFF.md` | Fixed service and project grant contract | -| `WS-XINT-001/AUTH_REV_HANDOFF.md` | Full review activation-custody/hidden behavior sequence | -| `WS-XINT-001/AUTH_ART_HANDOFF.md` | Full 25-action ART transfer; not a core CON gate | -| `backend/app/modules/projects/{models,schemas,repository,service}.py` | Current guide-bound economic fields and consumers to cut over/remove | -| `backend/app/modules/tasks/**` | TaskAssignment creation and future submitter policy freeze seam | -| `backend/app/modules/tasks/models.py::Submission` | Existing immutable version identity: `id`, integer `version`, and `supersedes_submission_id`; no SubmissionVersion table | -| `backend/app/modules/authorization/{catalogue,policy,kernel,schemas}.py` | Current 74/65/17/48 runtime and stable PermissionIds; only AUTH administrative actor/profile/service/link lifecycle actions are active; no CON/task-claim ActionId | -| `backend/app/modules/audit/**` | Shared append-only audit extension point | -| `backend/app/modules/artifacts/{preparation,sources}.py` | Inactive ART-only preparation; no core CON import | +- PermissionId and ActionId `outbox.dispatch`; +- ServiceIdentity `workstream.outbox.dispatcher` and its singleton matrix row; +- fixed-service prepared claim support for the outbox event context; +- CON policy, binding, contribution, award, delivery, callback, operations, + executor, and read ActionIds/evaluators/activations. -## Existing tests and gaps +The existing `operations.outbox.retry` permission is an Operator recovery +permission and is not dispatcher authority. -- Project/task tests cover current setup/claim/submission behavior but not - ContributionPolicy freezes or retirement of the legacy economic schema. -- AUTH tests cover catalogue parity, planned denial, actor-self/admin grants, - decision digest, scope evidence, and route commit/rollback. PR #140 changes - planning/tests for documentation gates but does not implement CON contexts, - independent project grants at CON call sites, AUTH-09E CON identities, - custody transfer, or prepared cross-domain mutations. -- ART tests prove preparation only. No optional evidence projection capability - exists or is needed for core contribution tests. -- No tests yet cover ContributionRecord cardinality, frozen rule evaluation, - money/points award uniqueness, fulfillment callback, delivery replay, - shared-outbox handler isolation, or REV/CON atomic rollback. -- No tests yet cover FinalAcceptance one-per-task/Review/Submission constraints, - accept-only creation, source-lineage exclusivity, or rollback when CON fails. -- No tests yet cover the two ordered CON operation inputs, reviewer-before- - branch fault boundaries, immutable fulfillment root ordinals, every writer - versus cutoff capture, or same-generation pre-cutoff drain completion. +## ART findings -## Dependencies +Merged ART now owns verified guide-source byte ingest, binding generation, +materialization, bounded PDF/DOCX/PPTX/XLSX/image extraction, and sufficiency +continuation. AUTH guide binding/read activation merged through PR #245. -- AUTH: AUTH-10 independent project grants, AUTH-09A-E fixed-service sequence, - complete ART/REV custody transfers, AUTH-PREP, reviewed CON registration and - later activation chunks, exact CON service identities/static rows, and - action-specific evaluators. Task claim activation must consume the merged - CON-05A freeze participant; review.decision activation must consume CON-07. -- REV: ReviewLease reviewer policy FK; canonical claim/decision composition; - REV-owned FinalAcceptance with exact policy-context typing; stabilized - artifact-hash facts; mandatory CON participant injection; REV-staged shared - audit/outbox; single route commit; and no no-op fallback. -- REV release control: CON writer/dispatch/callback hooks, immutable root - ordinal allocation under the shared fence, and same-session maximum-ordinal/ - drain observation must merge before REV-12A3. -- Task/Submission: submitter policy freeze and stable assignment/version lineage. -- Shared outbox/audit: caller-transaction append and feature-neutral dispatch. -- ADR 0014 adapters: typed capability port, factory, and composition-root - registration for external fulfillment. -- ART: no core dependency; optional projection only after separate approval. +ART PR #249 merged the verified guide-source clean cut and migration `0050`. +Its guide setup continuation and verified-source contracts are current runtime +evidence; they do not implement CON behavior or alter CON ownership. -## Risks +ART's remaining submission/reviewer work preserves the CON boundary: -| Risk | Mitigation | -|---|---| -| Two award-eligibility models | Clean semantic then physical cutover; no fallback | -| Contribution missing after Review | Mandatory flush-only participant and one caller commit | -| Reviewer contribution ordered after branch | Two operation-specific inputs; reviewer operation always precedes branch and cannot depend on branch effects | -| Submitter contribution inferred from Review decision | REV-owned immutable FinalAcceptance is the only submitter source; exact one-to-one constraints and lineage checks | -| ART outage suppresses contribution | No core ART/evidence operation | -| Wrong policy version | Assignment/lease freeze before work; immutable published versions | -| Cross-domain deadlock | AUTH-first lock order and two-order PostgreSQL tests | -| Dispatcher gains feature authority | Exact dispatcher-only action plus independent handler authorization | -| Dynamic/broad service access | Closed ServiceIdentity/static rows, AUTH-09E, cross-service denial | -| Role coupling | Independent grants and role-specific invalidation consumers | -| Partial activation transfer | Consume complete WS-XINT AUTH handoffs, never local subsets | -| Legacy row ambiguity | Human-approved deterministic rebuild/classification before migration | -| Premature public surface | Hidden behavior until AUTH activation and joint release proof | -| Shutdown loses or admits fulfillment work | Shared fence before every writer ordinal; immutable cutoff; same-generation pre-cutoff completion only; exact drain counts | -| Adjudication leaks into v0.1 | No adjudication type/action/state/queue/readiness dependency; reject and accept remain terminal | +- one verified Submission/binding identity reaches REV and CON; +- ART-07B will hand accepted Submission/ART identity to CON without provider + I/O in the review transaction; +- evidence upload is outside the approved v0.1 reviewer workflow. -## Resolved FinalAcceptance policy lineage +## REV findings -Merged REV-04 retains the handoff's `policy_context_ref` field as a foreign key -to canonical immutable `ReviewPolicy.id` and retains `recorded_by` for the -reviewer ActorProfile. REV must enforce that exact locked policy and its same -project/task/Submission/Review lineage. CON adds no renamed aliases and does not -interpret review policy as contribution policy or award authority. +Main contains REV policy/AUTH readiness but no runtime ReviewQueueEntry, +ReviewLease, Review, finding, FinalAcceptance, or revision tables/services. -## Open questions +Merged REV PLAN4 PR #258 is a planning-only current-main refresh. Its reviewed +dependency shape is aligned with CON ownership: -- Exact D11 AdminRole candidates for award detail, delivery recovery, and audit. -- Exact ServiceIdentity/ActionId/static-row contracts for delivery, - reconciliation, projection rebuild, and callback execution. -- Deterministic treatment of pre-production legacy rows. -- Whether optional evidence projection is ever approved; it is not part of the - current core plan. +- REV-03A1 queue/admission persistence can start independently; +- REV-03A2 owns ReviewLease persistence but needs CON-03B's + ContributionPolicyVersion table as a non-null FK target; +- REV-04B needs CON-02C shared lifecycle-audit participant and then enables + CON-03C to reference Review/ReviewLease/FinalAcceptance; +- REV-06A consumes CON-06's policy lookup result without transferring lease + ownership; +- REV-10 consumes CON-07's flush-only contribution/award participant and owns + the single commit; +- REV-12P1 needs the shared dispatcher only much later. -## Conventions to preserve +PR #258 merged as `10720382`. It is current planning evidence, not runtime +Review behavior and does not satisfy any runtime predecessor by itself. -- Review decisions are only `accept`, `needs_revision`, and `reject`. -- PostgreSQL owns canonical contribution/award/receipt truth. -- External I/O occurs only after commit and outside lifecycle/database locks. -- Domain participants flush and never commit. -- AUTH and feature repositories never cross-import. -- Fixed service identity is authorization; Celery executor/generation is - separate execution fencing. -- `/api/v1` is the only public prefix. +## Existing CON runtime and tests + +Relevant current files: + +- `backend/app/modules/outbox/**` — persistence and caller-transaction append; +- `backend/tests/test_outbox.py` — validation, idempotency, custody, migration, + and negative no-dispatch proof; +- `backend/alembic/versions/0029_shared_transactional_outbox.py`; +- `docs/spec_contribution_compensation.md` and ADR 0016 — canonical target. + +Absent files are meaningful: there is no `backend/app/modules/contributions`, +`backend/app/modules/compensation`, dispatcher executor, or CON API. + +## Planning correction + +The old linear order `02B -> 02C -> 03A -> 03B` is no longer useful: + +- 03A adapter-binding persistence is independent of dispatcher mechanics; +- 03B policy persistence depends on 03A and unblocks REV-03A2; +- 02C audit participation is independent of dispatcher and is needed only + before REV-04B; +- 02B remains blocked on exact AUTH dispatcher registration and is needed much + later for REV projection and CON fulfillment execution. + +Therefore the first useful CON path is `03A -> 03B`, with 02C scheduled before +REV-04B and 02B deferred until AUTH supplies its exact service authority. + +## Risks and unknowns + +- Later migration-bearing merges may change the migration head; every + implementation chunk must refresh current main. REV PLAN4 is merged, but + each REV child still refreshes its exact runtime contract. +- The deterministic classification of legacy economic rows remains a human + data-migration decision before CON-05A/05B. +- Exact CON ActionIds, service identities, dual-principal behavior, and + activation owners require separate AUTH review; CON cannot invent them. +- Provider fulfillment and callback authentication remain design inputs, not + implemented behavior. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md index f1a35aa62..4b9751549 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/INTENT.md @@ -1,94 +1,66 @@ -# Intent: WS-CON-001 Contribution Record And Compensation Boundary +# Intent: WS-CON-001 Contribution And Compensation -## Human-level goal +## Goal -Implement the canonical contribution-policy, ContributionRecord, -CompensationAward, fulfillment, and operations boundary that participates -atomically in human Review without taking ownership of authentication, -authorization, review decisions, artifact storage, external settlement, a -points ledger, or reputation scoring. +Complete the backend contribution and conditional-compensation boundary on +current `main` without taking ownership of review judgment, authorization, +artifact custody, external settlement, or reputation scoring. -The supplied WS-CON reference pair is input to reconcile, not authority to -accept blindly. The active contract follows trusted repository decisions and -current main `8d5eb15b`, including the contributor foundation in AUTH PR #153, -AUTH-09D-B PR #152, ART-02B1 PR #151, REV PLAN2 PR #150, AUTH-09D-A PR #148, -REV-02 PR #147, REV-01 PR #145, AUTH-09C PR #146, ART PR #141, AUTH-09B PR -#143, REV planning PR #128, AUTH PR #140, and the underlying WS-XINT-001 -boundary from PR #139. PR #153 establishes canonical human `contributor_id` -lineage for TaskAssignment and Submission; it does not add CON authority, -service admission, review behavior, or outbox execution. +Workstream must turn authorized human review into immutable facts: -## Success state - -- Every valid recorded human Review creates one immutable reviewer - `completed_review` contribution. -- REV creates one immutable `FinalAcceptance` only for `Review(accept)`. - `accepted_submission` consumes that FinalAcceptance; it is never inferred - directly from `Review.decision`. `needs_revision` and `reject` create neither. -- TaskAssignment and ReviewLease freeze independent published - ContributionPolicyVersions before work is performed. -- Explicit unpaid rules create no award; compensated rules create at most one - money and one project-points CompensationAward. -- REV owns the request and single commit: Review/task effects, optional - FinalAcceptance, CON-flushed contributions/awards, and REV-staged shared - audit/outbox rows commit or roll back together. -- One mandatory CON participant exposes a reviewer operation before the - decision branch and an accept-only submitter operation after FinalAcceptance - and accepted task effects; no nullable cross-actor omnibus input exists. -- Core contribution creation copies stabilized artifact-hash lineage supplied - by REV and has no ART or provider dependency. -- Downstream adapters fulfill awards but never determine eligibility. -- Every fulfillment-obligation writer uses the one shared lifecycle fence - composed with CON by REV-12A3 before monotonic root-ordinal allocation; drain - dispatch/callback completes only same-generation roots at or below the - persisted cutoff. -- Every protected human/service surface uses AUTH's exact grant or - ServiceIdentity/static-matrix path, prepared mutation protocol when needed, - and AUTH-owned activation. -- Public APIs use `/api/v1` only. +- every committed human Review creates one reviewer `completed_review` + ContributionRecord; +- only an accepted Review creates REV-owned `FinalAcceptance`, which is the + source of one submitter `accepted_submission` ContributionRecord; +- locked ContributionPolicy rules decide whether either contribution creates + no award or immutable money/project-points CompensationAwards; +- fulfillment happens asynchronously and never controls lifecycle truth. -## Non-goals +## Current-main reason for PLAN4 -- Workstream-owned login, sessions, passwords, or token-role authority. -- AUTH catalogue, grant, static-matrix, evaluator, or activation implementation. -- REV models, routes, lifecycle decisions, or commits. -- Mandatory contribution-evidence artifacts. A future projection is optional - and separately approved. -- Provider-specific settlement SDKs, attempts, payout batches, accounts, - balances, points ledgers, credits, or blockchain work. -- Reputation scores, aggregates, adjudication, appeals, reversals, or mutable - contribution/award truth. V0.1 has no adjudication policy, action, queue, - lease, state, decision, contribution, branch, readiness gate, or initiative - dependency. -- A second artifact store, raw provider references, or ArtifactStore injection. -- Frontend work before backend contracts and guards stabilize. +The original plan stopped at the July 2026 outbox-persistence milestone. Since +then AUTH, ART, REV/XINT, project-policy, CI, and repository contribution rules +changed materially. The authored CON status still described CON-02A as active, +AUTH-09E/PREP as future, and an obsolete migration head. PLAN4 replaces those +operational claims with a capability-ordered plan, now refreshed through +`main` `2feaf47d`. -## Context +## Success state -Workstream certifies useful human work independently from external fulfillment. -Reviewer work is a contribution for every valid Review. ContributionPolicy -decides what that work earns. FinalAcceptance is the stable REV-owned fact that -allows CON to recognize accepted submitter work without treating the mutable -shape of a Review decision as its source. Immutable awards record the result; -adapters carry out fulfillment later. +- ContributionPolicyVersion is the only award-policy authority. +- TaskAssignment freezes the submitter policy version before work. +- REV-owned ReviewLease freezes the reviewer policy version before review. +- ContributionRecord and CompensationAward rows are immutable and replay-safe. +- REV owns Review, FinalAcceptance, task/assignment effects, audit/outbox + staging, and the single transaction commit. +- CON exposes narrow caller-session participants and never commits REV work. +- ART supplies stable accepted Submission/binding identity; CON performs no + provider read or write in the decision transaction. +- AUTH owns every PermissionId, ActionId, ServiceIdentity, matrix row, + evaluator, prepared-authority capability, and action activation. +- Delivery, callbacks, reconciliation, and projection executors each use their + own authority; dispatcher authority never transfers to a handler. +- Optional contribution-evidence projection remains separate from core + PostgreSQL contribution and award truth. -## Human judgment required +## Non-goals -1. Approve the repository-owned active specification while preserving archival - reference inputs. -2. The complete removal of the retired guide-bound economic schema remains - approved; choose only the deterministic pre-production row classification - for migration. -3. Resolve D11 action-specific AdminRole candidates for award detail, delivery - recovery, and audit. -4. Approve exact ServiceIdentity/ActionId/static-row boundaries for dispatcher, - delivery, reconciliation, projection rebuild, and callback execution. The - shared dispatcher cannot inherit handler authority. -5. Optional contribution-evidence projection remains deferred unless separately - approved. +- Workstream login, password, session, or token issuance. +- Review queue, lease, judgment, finding, revision, or FinalAcceptance + ownership. +- Artifact bytes, provider credentials, scratch paths, or storage decisions. +- Payment accounts, balances, payout ledgers, KYC, blockchain settlement, or + provider SDK integration. +- Reputation scoring or runtime reputation projection. +- Adjudication, appeals, reversals, or mutable contribution history in v0.1. +- Frontend work before the backend contracts and lifecycle guards are stable. -## Risk class +## Human decisions retained -L0 for planning/contract reconciliation. Each runtime chunk is L1 because it -touches authorization, economic records, schema, lifecycle, audit, or cross- -domain transactions. +- Review decisions remain exactly `accept`, `needs_revision`, and `reject`. +- Reviewer contribution exists for all three valid decisions. +- Submitter contribution exists only through FinalAcceptance on accept. +- Explicit unpaid rules create no CompensationAward. +- Optional evidence projection is not a release prerequisite. +- Each implementation chunk remains separately bounded and stops at its own + human merge checkpoint. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/JOINT_RELEASE_HANDOFF.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/JOINT_RELEASE_HANDOFF.md index 1fcb319e2..af35d8531 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/JOINT_RELEASE_HANDOFF.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/JOINT_RELEASE_HANDOFF.md @@ -1,162 +1,95 @@ -# Joint REV/CON Release Handoff - -## Boundary - -REV owns Review decisions, FinalAcceptance, queue/lease/task effects, shared -audit/outbox staging for the decision transaction, release-control state, and -the single route commit. CON owns ContributionPolicy, ContributionRecord, -CompensationAward, fulfillment behavior, and CON projections. AUTH owns all -authorization and activation. - -The canonical cross-boundary source is merged -`WS-XINT-001/REV_CON_HANDOFF.md`. Merged REV PR #128 originally landed at -`0302bcf`; REV-01 PR #145 canonically published it, REV-02 PR #147 decomposed -the first runtime parent, and planning-only REV PLAN2 PR #150 refreshed the -remaining runtime child gates. They remain the reviewed owner contract in -current main `8d5eb15b`; ART-02B1 PR #151 changes ArtifactStore provider -implementation and proof only, while AUTH-09D-B PR #152 changes administrative -identity-link lifecycle only. Contributor-foundation PR #153 changes canonical -TaskAssignment/Submission attribution to `contributor_id` and enforces human -lineage/write identity but adds no review or contribution transaction behavior; -none enters this transaction; -runtime REV behavior remains -unimplemented. - -## Required decision composition +# Joint ART/AUTH/REV/CON Release Handoff + +## Ownership + +- ART owns immutable artifact admission, submission evidence, guide-source + processing, and the future typed packet-membership contract. +- AUTH owns identities, permissions, evaluators, prepared authorization, + availability, and activation. +- REV owns review policy, queue, lease, Review, FinalAcceptance, review/task + effects, cross-domain composition, and the single decision-route commit. +- CON owns ContributionPolicy, adapter bindings, ContributionRecord, + CompensationAward, fulfillment truth, and CON projections. + +The core review transaction performs no ART provider I/O. It consumes only +already-persisted canonical identities and stabilized hashes supplied by the +owner contracts. + +## Current cross-initiative state + +At current `main` (`2feaf47d`), AUTH readiness, ART guide foundations and v2 +guide-source cutover, and REV PLAN4 are merged, but the live REV lifecycle and +CON runtime are not implemented. ART PR #249 and migration `0050` are current +runtime evidence. REV PR #258 is merged planning evidence, not runtime +behavior. Re-read the current migration head before implementation and refresh +each REV child contract against its exact gate. + +## Correct dependency sequence ```text -AUTH locks exact reviewer authority and prepares review.decision handle bound to -session/action/actor reference/idempotency key/canonical request digest --> REV locks and recomposes canonical facts --> AUTH consumes the handle, evaluates once, and stages decision evidence --> REV stages Review/findings/resolutions, consumes ReviewLease, closes queue --> CON reviewer operation creates completed_review from Review/ReviewLease, - evaluates only the lease-frozen reviewer rule, and returns typed staging inputs --> on accept, REV creates immutable FinalAcceptance linked to Review, - canonical Submission, Task, submitter, reviewer and locked ReviewPolicy - then accepts Task and completes TaskAssignment - -> CON submitter operation creates accepted_submission from FinalAcceptance - and TaskAssignment, evaluates only the assignment-frozen submitter rule, - and returns typed staging inputs --> on needs_revision, REV sets Task to needs_revision and keeps TaskAssignment active --> on reject, REV sets Task to rejected with a bounded human reason and blocks - only the same-task TaskAssignment with its source Review --> REV stages shared audit/outbox rows from the typed participant result --> request route or service command commits once -``` +CON 03A adapter-binding persistence +-> CON 03B ContributionPolicy persistence + -> enables REV 03A2 lease/policy-freeze persistence + +CON 02C lifecycle audit participant +-> REV 04B FinalAcceptance/audit/outbox transaction foundation +-> CON 03C ContributionRecord/CompensationAward persistence +-> CON 03D delivery/receipt/status and ordinal persistence -The participant is one mandatory interface with two ordered operation-specific -inputs. The reviewer input never carries nullable FinalAcceptance or submitter -policy/source facts. The submitter input does not exist outside `accept` and -never uses direct Review/ReviewLease contribution-source fields. +REV lease schema/caller facts + CON 04B policy service +-> CON 06 claim-time policy lookup/freeze participant -No no-op participant, post-commit repair, ART call, evidence projection, or -provider I/O exists in this transaction. CON copies stabilized artifact-hash -lineage from REV facts. +stable REV revision lineage + CON 03C/03D + CON 05A + CON 06 +-> CON 07 mandatory review-decision participant +-> REV 10 hidden contribution composition + +AUTH dispatcher registration/admission contract +-> CON 02B hidden outbox dispatcher +-> later fulfillment/projection executor work +``` -## FinalAcceptance contract +REV `03A1` queue/admission may proceed independently. REV owns +ReviewLease/preference; CON never owns or duplicates it. REV `03B` depends on +an ART-owned typed packet-membership contract, not on ART provider calls. -The external shorthand `submission_version_id` means canonical -`Submission.id`; the repository stores `submission_id` because each immutable -Submission row is already one version. Merged REV-04 retains -`policy_context_ref` as the foreign key to the exact locked `ReviewPolicy.id` -and retains `recorded_by` for the canonical reviewer ActorProfile. CON consumes -those owner-defined names without aliases. REV owns this record and the -composite same-chain constraints. +## Decision transaction ```text -FinalAcceptance - id - project_id - task_id UNIQUE - submission_id UNIQUE - source_review_id UNIQUE - accepted_submitter_id - accepted_at - recorded_by - policy_context_ref +AUTH prepares exact review.decision authority +-> REV locks ReviewLease, Submission, Task, assignment, and policy facts +-> AUTH evaluates once and stages decision evidence +-> REV stages Review and task/lease effects +-> CON stages completed_review contribution inputs +-> on accept, REV creates immutable FinalAcceptance and completes task/assignment +-> CON stages accepted_submission contribution and conditional awards +-> shared audit and outbox participants flush in the same session +-> REV route commits once ``` -It is created only inside `Review(accept)`. There is no public/manual creation -API and no separate authorization action. `needs_revision` and `reject` create -none. Accept/reject are terminal in v0.1; there is no adjudication, appeal, -replacement acceptance, or reopen path. - -For `needs_revision`, REV keeps the same TaskAssignment `active`. For `reject`, -REV blocks only that same-task TaskAssignment, binds the block to the reject -Review, and sets the Task to canonical `rejected` with its bounded human reason; -it changes no grant or unrelated task. The archival `closed/review_rejected` -wording is not a lifecycle token. - -Optional reviewer-quality sampling is non-mutating audit only. It does not -delay or replace FinalAcceptance and cannot change Review/task/contribution -truth. - -`completed_review` binds directly to Review and ReviewLease and is unique per -Review. `accepted_submission` binds to FinalAcceptance and TaskAssignment and -is unique per FinalAcceptance. Database checks make those source shapes -mutually exclusive; CON never infers a submitter record by reading -Review.decision. - -## Release prerequisites - -- ContributionPolicy publish/freeze and adapter-binding behavior are merged. -- TaskAssignment and ReviewLease carry exact frozen policy-version IDs. -- REV-04B FinalAcceptance persistence and its locked decision-lineage contract - are merged, including exact task/Review/Submission uniqueness and - ReviewPolicy lineage. -- Shared outbox/audit participants and CON-07 are mandatory and merged. -- REV hidden claim/decision composition then consumes CON-06/07 and has no - fallback. -- AUTH complete REV custody transfer, exact evaluators, reviewer grant path, - prepared protocol, and activation are merged. The transfer is the complete - PR #140 19-action map, not a local review.claim/review.decision subset. -- Every public/service CON action has exact AUTH registration, evaluator, - principal path, and activation after hidden behavior. -- Protected outbox handlers have their own exact service authority; dispatcher - authority is not inherited. -- Every CON fulfillment-obligation creation, requeue, successor, and repair - writer exposes a mandatory hook that acquires REV-12A3's shared - `JointLifecycleMutationFence` before allocating an immutable monotonically - increasing root ordinal or locking obligation rows. -- CON dispatch and callback hooks consume that shared fence. In - `delivery_draining`, they may complete only the same generation and a root - ordinal at or below REV's persisted cutoff; they cannot create successor, - retry-root, repair, or other follow-on obligations. -- `FulfillmentLifecycleDrainObservationPort` is same-session/read-only and - returns pending/claimed/retryable/in-flight counts, nonterminal delivery and - callback obligations, and the current maximum root ordinal through typed - shared-outbox capability. REV imports no CON/outbox repository. -- Exact migrations, handler registry, task IDs, route inventory, and retained - tests are bound to merged SHAs. - -ART storage and optional contribution-evidence projection are not prerequisites. - -## Startup and readiness - -Startup fails on closed catalogue/static-matrix/context/evaluator/active-feature -parity drift. Missing provisioned fixed-service ActorProfile/link rows do not -stop startup or administrative provisioning, but runtime calls deny and release -readiness remains false until exact rows exist. - -## Joint live proof - -The release drill covers accept with exactly one FinalAcceptance, accepted Task, -completed Assignment, and submitter contribution; needs_revision with an active -Assignment and neither acceptance fact nor submitter contribution; reject with -canonical rejected Task, same-task blocked Assignment/source Review, and neither -acceptance fact nor submitter contribution; one reviewer contribution per -Review, explicit unpaid, money+points, frozen-version changes, -repeated/revision Reviews, no-self-review, grant revocation, source-shape and -uniqueness conflicts, atomic rollback, adapter outage/replay, -callback-before-ack, failure then fulfillment, reconciliation, every obligation -writer versus cutoff capture in both orders, same-generation pre-cutoff -dispatch/callback completion, post-cutoff denial before provider I/O, drain -fencing, and hidden-to-active route transition. It asserts zero ART calls and -no adjudication action/state/queue/readiness dependency. - -## Ownership and stop - -CON-11 publishes the hidden dependency manifest but registers no route. -REV-13A consumes it in preflight and REV-13C owns the sole public product -release and final HTTP proof. This handoff starts no chunk automatically. +`needs_revision` creates no FinalAcceptance and keeps the assignment active. +`reject` creates no FinalAcceptance and blocks only the same-task assignment +with the source Review. Stored decisions remain exactly `accept`, +`needs_revision`, and `reject`. There is no adjudication, appeal, replacement +acceptance, no-op CON participant, post-commit repair, or second ledger. + +## Release gates + +- ContributionPolicy and adapter-binding schemas and hidden services are + merged; tasks and review leases freeze the exact policy version. +- REV FinalAcceptance persistence is merged with exact Review, Submission, + Task, submitter, reviewer, and locked ReviewPolicy lineage. +- Shared audit and outbox append participants are mandatory and flush-only. +- CON review participants are mandatory, typed, and rollback-safe. +- AUTH exact evaluators and activations occur only after hidden behavior. +- Each protected executor/callback has independent fixed-service authority; it + cannot borrow `outbox.dispatch`. +- ART packet facts cross via typed ports; review/contribution code imports no + ART repositories and performs no provider I/O. +- One integrated PostgreSQL proof covers all three review decisions, + uniqueness, frozen-policy behavior, no-self-review, rollback, retry/replay, + and negative authority cases. + +## Stop + +This handoff is dependency documentation only. It starts no ART, AUTH, REV, or +CON implementation and does not treat an open PR as merged evidence. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md index 744a54e09..8561e28e0 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/PLAN.md @@ -1,468 +1,150 @@ -# Plan: WS-CON-001 Contribution Record And Compensation Boundary - -## Proposed approach - -Adopt contributor-foundation PR #153, AUTH-09D-B PR #152, ART-02B1 PR #151, planning-only REV PLAN2 PR #150, AUTH-09D-A PR #148, -merged REV-02 PR #147, REV-01 PR #145, and the underlying REV planning PR #128 -plus trusted main `8d5eb15b`, including -AUTH-09C PR #146, ART PR #141, AUTH-09A, AUTH-09B PR #143, AUTH PR #140, and -the underlying WS-XINT PR #139 boundary before runtime work, then deliver WS-CON through -hidden, reviewable chunks. The -core path is PostgreSQL-local and has no ART dependency: +# Plan: WS-CON-001 Contribution And Compensation + +## Strategy + +Build the canonical PostgreSQL truth first, then integrate it into REV's +caller-owned transaction, and only afterward expose asynchronous fulfillment, +operations, and release surfaces. Do not let the missing dispatcher block +independent policy persistence needed by REV. + +## Ownership model + +| Owner | Owns | CON receives | CON never takes | +|---|---|---|---| +| AUTH | actors, grants, catalogue, typed contexts, PREP, service identities/matrices, evaluators, activation | authorized decisions/capabilities and exact resource facts | catalogue, grants, provisioning, evaluator, activation | +| ART | bytes, bindings, verified content, provider access, accepted artifact identity | stable accepted Submission/binding/hash lineage | provider I/O, credentials, scratch, byte custody | +| REV | queue, ReviewLease, Review, findings, revisions, FinalAcceptance, lifecycle effects, orchestration, single commit | caller session and locked Review/lease/FinalAcceptance facts | lease/decision/FinalAcceptance ownership or commit | +| CON | policy, contribution, award, fulfillment truth and narrow participants | — | review judgment, artifact custody, settlement truth | + +## Corrected delivery order + +### Phase A — current planning and independent schema foundations + +1. `PLAN4` reconciles current main, merged ART #249 plus remaining ART gates, + merged REV PLAN4, boundaries, and chunk order. It changes no runtime. +2. `03A` persists project compensation adapter-binding identity/lifecycle with + no provider behavior or credentials. +3. `03B` persists ContributionPolicy, immutable versions/rules/definitions, + and the project selector. This is the required FK target for REV-03A2. +4. `02C` adds the generic caller-transaction lifecycle-audit participant before + REV-04B. It no longer waits for dispatcher mechanics. + +REV-03A1 may proceed concurrently after merged REV PLAN4. REV-03A2 waits for +CON-03B, while later REV-04B waits for CON-02C. + +### Phase B — hidden policy behavior and legacy clean cut + +5. `04A` adds hidden adapter-binding service behavior after AUTH registers the + exact binding actions/contexts and keeps them unavailable until hidden proof. +6. `04B` adds hidden contribution-policy behavior under the same + registration-before-behavior-before-activation sequence. +7. `05A` removes semantic use of retired guide-bound economic terms and freezes + the submitter ContributionPolicyVersion on TaskAssignment. +8. `05B` removes the now-unreachable legacy economic schema after an approved + deterministic row classification and zero-consumer proof. + +### Phase C — REV integration foundations + +9. `06` supplies only claim-time reviewer policy lookup/freeze facts. REV owns + the ReviewLease row and lifecycle. +10. REV proceeds through its queue/lease/packet/Review persistence sequence. +11. After REV-04B supplies stable Review, ReviewLease, and FinalAcceptance FK + targets, `03C` persists immutable ContributionRecord and CompensationAward. +12. `03D` persists delivery, receipt, status, ordinal, and generation truth. +13. After REV revision lineage is stable, `07` supplies the mandatory two-step + flush-only participant for reviewer work and accept-only submitter work. +14. REV-10 owns the atomic Review/FinalAcceptance/TASK/CON/audit/outbox commit. + +### Phase D — dispatcher and fulfillment + +15. AUTH registers `outbox.dispatch`, `workstream.outbox.dispatcher`, exact + static membership, typed event context, and fixed-service prepared claim + support. Registration remains unavailable until hidden behavior exists. +16. `02B` implements generic claim/invoke/finalize, retry, dead-letter, replay, + retention, registry, and drain mechanics. It grants no handler authority. +17. AUTH activates only dispatcher mechanics after reviewing merged 02B. +18. `08A` adds outbound compensation delivery under an independent delivery + identity/action; `08R` adds callback rate control; `08B` adds authenticated + inbound fulfillment reporting. None inherits dispatcher authority. + +### Phase E — reads, operations, and release + +19. `10A` exposes bounded PostgreSQL contribution/award reads after exact AUTH + read actions and concealment rules. +20. `10B` adds operations requests/reads and same-session drain observation. +21. `10C` adds independently authorized reconciliation and projection + executors. +22. `11` proves dependency, cutoff/drain, service provisioning, activation, + failure, and recovery readiness before public release. + +Optional evidence projection `09A/09B` remains outside this core order and +requires a fresh ART/AUTH disclosure plan if ever selected. + +## Canonical review transaction ```text -AUTH prepares review.decision and locks reviewer authority --> REV locks and recomposes canonical Review/Submission facts --> AUTH evaluates once and stages decision evidence --> REV stages Review/findings/resolutions, consumes ReviewLease, and closes queue --> CON reviewer operation creates completed_review and applicable reviewer awards --> on accept, REV creates immutable FinalAcceptance, accepts Task, and completes Assignment - -> CON submitter operation creates accepted_submission and applicable submitter awards --> on needs_revision, REV sets Task to needs_revision and keeps Assignment active --> on reject, REV sets Task to rejected with a bounded human reason and blocks - only the same-task Assignment with its source Review --> REV stages shared audit and outbox rows --> request route or service command commits once +AUTH prepares review.decision +-> REV locks/recomposes canonical Review/Submission/lease facts +-> AUTH consumes/evaluates once +-> REV appends Review/findings/resolutions and closes lease/queue +-> CON reviewer operation stages completed_review and applicable awards +-> branch: + accept -> REV creates FinalAcceptance + task/assignment effects + -> CON submitter operation stages accepted_submission and awards + needs_revision -> REV applies revision effects; no submitter contribution + reject -> REV applies bounded rejection effects; no submitter contribution +-> REV stages shared audit/outbox +-> REV commits once ``` -Public contribution, policy, award, fulfillment, and operations surfaces stay -hidden until their exact AUTH registration -> feature behavior -> AUTH -activation sequence and the joint REV/CON release gate pass. - -## Canonical product model - -- `ContributionRecord` is immutable. Every valid recorded human Review creates - one reviewer `completed_review`. REV creates `FinalAcceptance` only for - `accept`; one submitter `accepted_submission` consumes that stable fact. -- `FinalAcceptance` is an immutable REV-owned internal derived fact, not a - public resource command. It has no independent authorization action or manual - creation API. -- Existing `Submission` plus its `version` and `supersedes_submission_id` is the - versioned submission identity. WS-CON does not add `SubmissionVersion`. -- `ContributionPolicy` is the stable project aggregate. It has one active - policy per project and points to an immutable published - `ContributionPolicyVersion`. -- Each published version has exactly one `ContributionRule` for - `accepted_submission` and one for `completed_review`. A rule is explicitly - `unpaid` or `compensated`. -- An unpaid rule creates no award. A compensated rule references one or two - immutable `ContributionAwardDefinition` rows: at most one `money` and one - `project_points` definition. -- `CompensationAward` is the immutable evaluated result. Delivery, - acknowledgement, immutable `CompensationFulfillmentReceipt`, and rebuildable - `CompensationStatusProjection` are downstream fulfillment concerns and never - decide eligibility. -- `ProjectCompensationAdapterBinding` binds one project/instrument to a - non-secret adapter route and canonical service actor. Credentials and - provider endpoints remain deployment configuration. -- The retired guide-bound economic schema and every semantic consumer are - removed in two fail-closed chunks. No alias, automatic conversion, or - executable fallback survives. - -## Review and contribution boundary - -One mandatory `ContributionCompensationDecisionParticipant` exposes two ordered -operation-specific methods in the caller-owned `AsyncSession`; it does not -accept one omnibus request with nullable FinalAcceptance or both actors' policy -contexts. - -The reviewer operation is required for every valid decision after REV appends -Review/findings/resolutions, consumes ReviewLease, and closes the queue but -before REV applies the decision branch. Its typed input contains only exact -locked Review, ReviewLease, versioned Submission, project/task, reviewer, -lease-frozen reviewer `ContributionPolicyVersion`, originating allowed -`review.decision` AuthorizationDecision, request/correlation references, and -the stabilized server-derived `Submission.artifact_hash`. It contains no -FinalAcceptance, TaskAssignment source field, submitter, or submitter policy. - -The submitter operation exists only after the `accept` branch creates -FinalAcceptance and applies Task `accepted` plus TaskAssignment `completed`. Its -typed input contains exact locked FinalAcceptance, TaskAssignment, versioned -Submission, project/task, submitter, assignment-frozen submitter -`ContributionPolicyVersion`, the same authorization/request/correlation -references, and stabilized artifact hash. It contains no direct Review or -ReviewLease contribution-source fields and is unavailable for `needs_revision` -or `reject`. - -Each operation validates only its supplied locked lineage, copies the stabilized -digest into `ContributionRecord.artifact_hash`, evaluates its matching frozen -`ContributionRule`, stages applicable contribution/award rows, returns typed -audit/outbox inputs to REV, flushes, and never commits. CON never reads REV or -AUTH repositories, evaluates `review.decision`, calls ART, rehashes artifact -bytes, performs provider I/O, or offers a no-op production participant. Any CON -failure rolls back the complete Review decision. - -`needs_revision` and `reject` still create the reviewer contribution and any -award earned by its frozen reviewer rule. They create no FinalAcceptance or -submitter contribution. Automated checker outcomes create neither contribution -type. - -The REV-owned lifecycle effects are exact and remain inputs to CON rather than -CON behavior: `needs_revision` sets `Task.status = needs_revision` and keeps the -same TaskAssignment `active`; `reject` sets `Task.status = rejected` with the -bounded human reason and sets only the same-task TaskAssignment to `blocked` -with its reject Review reference. Reject changes no actor grant and no other -task or assignment. The archival `closed/review_rejected` wording is not a -canonical status. - -### FinalAcceptance lineage - -REV persists the minimal same-chain fact: +CON copies the stable artifact hash/identity supplied by REV. It neither loads +bytes nor calls ART. -```text -FinalAcceptance - id - project_id - task_id - submission_id - source_review_id - accepted_submitter_id - accepted_at - recorded_by - policy_context_ref -``` +## Authorization sequence -The external handoff's `submission_version_id` maps to `submission_id` because -the existing immutable Submission row is already the version identity. Merged -REV-04 retains `policy_context_ref` as the foreign key to the exact locked -`ReviewPolicy.id` and `recorded_by` as the reviewer ActorProfile field; CON adds -no alias. REV must prove the Review, policy, project, task, Submission, -submitter and reviewer chain. PostgreSQL enforces `UNIQUE(task_id)`, -`UNIQUE(source_review_id)`, and -`UNIQUE(submission_id)`. There is no reopen, replacement, adjudication, or -second acceptance path in v0.1. - -Any reviewer-quality sampling is a non-mutating audit after the transaction. It -does not delay FinalAcceptance, create a second Review decision, or alter -acceptance/contribution truth. - -Reviewer contributions require direct `source_review_id` and -`source_review_lease_id`, with `source_final_acceptance_id` null. Submitter -contributions require `source_final_acceptance_id` and -`source_task_assignment_id`, with direct `source_review_id` and -`source_review_lease_id` null. Partial unique constraints enforce one -`completed_review` per Review and one `accepted_submission` per -FinalAcceptance; checks reject mixed or missing source shapes. - -## Contribution-policy freezing - -TaskAssignment freezes `submitter_contribution_policy_version_id` during an -authorized task claim. ReviewLease freezes -`reviewer_contribution_policy_version_id` during an authorized review claim. -Both use a narrow CON-owned lookup/freeze participant, lock the active -`ContributionPolicy` and current published version plus referenced award -definitions and adapter bindings, return one exact version ID, flush only their -own state, and never commit. - -Later policy publication changes only new assignments or leases. Retired frozen -versions remain valid for started work. Missing policy configuration is not an -implicit unpaid rule. - -TaskAssignment and task-claim wiring remain task-owned. ReviewLease and review- -claim wiring remain REV-owned. CON supplies typed participants, not foreign -models, routes, lifecycle decisions, or commits. - -## Authorization boundary - -Trusted `main` is `8d5eb15b`, merging contributor-foundation PR #153 after -AUTH-09D-B PR #152 and ART-02B1 PR #151 and after planning-only REV -PLAN2 PR #150, AUTH-09D-A PR #148 and REV-02 PR #147, -REV-01 PR #145, AUTH-09C PR #146, ART PR #141, AUTH-09B PR #143, REV planning -PR #128, AUTH-09A, AUTH PR #140, and WS-XINT PR #139. -Runtime catalogue counts are 74 PermissionIds, 65 ActionIds, 17 active actions, -and 48 planned actions. No WS-CON or task-claim ActionId is registered. AUTH-09B -activates only the controlled human `actor.service.provision` operation; -AUTH-09C activates only administrative `actor.profile.read` and -`actor.identity_link.read`; AUTH-09D-A activates only the three actor-profile -lifecycle actions; AUTH-09D-B activates only identity-link revoke/reactivate. -None grants service execution or runtime admission. The contributor foundation -is merged: TaskAssignment and Submission now use canonical human -`contributor_id`, and contributor writes revalidate an active human profile and -identity link. It changes no ActionId, PermissionId, grant, evaluator, service -admission, or review lifecycle. AUTH-09E remains proposed. PR #140 adds reviewed AUTH -custody/PREP/activation contracts only; the custody transfers and prepared -protocol remain proposed runtime work. - -WS-XINT D1/D2 is final for this plan: `ActionOwner` is the exact AUTH activation -custodian. Each protected surface follows: +For each protected CON surface: ```text -AUTH registers planned ActionId, stable PermissionId mapping, typed context, -principal path, and activation custodian --> CON merges hidden canonical resource composition, guards, and behavior --> AUTH integrates the evaluator and alone changes planned to active --> joint release exposes the surface +feature manifest +-> AUTH registers exact action/context/principal while unavailable +-> CON merges hidden behavior and negative proof +-> AUTH integrates evaluator and activates exact action +-> later composition/release consumes it ``` -CON never reads grants, imports AUTH repositories, constructs PermissionIds or -roles, changes availability, or supplies a production allow fallback. AUTH -never imports CON repositories or mutates contribution/award state. - -PR #140's complete ART and REV custody-transfer contracts are AUTH-owned -coordination work; their runtime transfers have not yet merged. WS-CON -references the canonical AUTH `ACTIVATION_CUSTODY.md` plus WS-XINT -`AUTH_ART_HANDOFF.md` and `AUTH_REV_HANDOFF.md`; it does not prescribe a partial -transfer. CON depends on `review.claim` and `review.decision`, but AUTH must -transfer every current REV action as one complete boundary. The four proposed -additive REV actions remain unregistered until their own reviewed registration -contract. - -### Human project grants - -The shipping path consumes exactly two project authorities: task claim requires -one active exact-project `submitter` grant, while review claim/decision require -one active exact-project `reviewer` grant plus no-self-review and lifecycle -guards. Any unrelated project or administrative grant does not substitute. -WS-CON introduces no adjudicator grant/action, adjudication invalidation -consumer, or readiness dependency; the separate global AUTH role catalogue is -outside this lifecycle contract. - -### Prepared mutation protocol - -For mutations, AUTH first locks and revalidates either human actor/link/exact- -grant rows or fixed-service actor/link rows. It returns an opaque, single-use, -non-serializable `PreparedAuthorizationHandle` bound exactly to session, -ActionId, actor-reference kind/reference, idempotency key, and canonical -request digest. A fixed service additionally requires closed ServiceIdentity, -exact static service-action matrix membership, AUTH-09E admission, and active -action as code-owned validations after profile/link locks, not database lock -targets. The feature then locks canonical rows and recomposes final typed -facts; AUTH consumes the handle, evaluates once, and stages decision evidence. -AUTH and feature participants flush only; the route or service command commits -once. Substitution/reuse denial does not consume an otherwise valid handle. -Reads use request-scoped `require()` and canonical feature loaders. - -Missing provisioned service ActorProfile/ActorIdentityLink rows deny that -runtime request and block release readiness, but do not fail application startup -or the Access Administrator provisioning surface. Startup may fail on closed -catalogue/matrix/context/evaluator/active-behavior parity drift. - -### Fixed services and handler authority - -The shared outbox dispatcher is not a catch-all feature executor. -`workstream.outbox.dispatcher` with exact `outbox.dispatch` static membership -may claim, invoke, and finalize outbox work only. It cannot inherit compensation -delivery, reconciliation, contribution projection, callback, ART, or provider -authority from an event type. - -Before a protected feature handler is implemented, its owning specification and -AUTH must approve one exact ServiceIdentity/ActionId/static-row contract. The -current candidate boundaries requiring decisions are: - -- outbound compensation delivery execution; -- asynchronous compensation reconciliation; -- asynchronous contribution projection rebuild; -- fulfillment result reporting by the bound external service; -- optional contribution-evidence binding, if that projection is later adopted. - -Suggested semantic identifiers are discovery candidates only, not approved -catalogue strings: `workstream.compensation.delivery`, -`workstream.compensation.reconciler`, -`workstream.contribution.projection_rebuilder`, and -`workstream.compensation.fulfillment_reporter`. AUTH may instead approve a -closed dual-principal evaluator for an existing action, but CON must not infer -one. Therefore the previously proposed 22 core WS-CON ActionIds are not a final -closed runtime count until these service execution boundaries are decided. - -The callback path requires a verified service token, provisioned service -ActorProfile/ActorIdentityLink, immutable approved ServiceIdentity, its exact -static matrix row, matching `ProjectCompensationAdapterBinding`, and AUTH-09E. -It never uses a human role or dynamic service grant. - -## Operation-specific lock and commit order - -There is no global sequence that moves CON policy rows ahead of REV lifecycle -rows. Every mutation first locks AUTH human actor/link/grant or fixed-service -actor/link authority, then its idempotency row and applicable lifecycle fence. -After that common prefix, the owning operation uses one explicit order: - -- `review.decision`: REV follows its canonical idempotency/fence, queue, lease, - task, assignment, Submission, predecessor Review, finding/resolution order; - the reviewer operation then locks only the lease-frozen policy/rule/definition/ - binding and reviewer contribution/award rows. REV applies the branch. For - accept, REV creates FinalAcceptance and applies accepted task/assignment - effects before the submitter operation locks only the assignment-frozen - policy/rule/definition/binding and submitter contribution/award rows. REV then - stages shared audit and outbox rows; -- task/review claim freeze: the owning task/assignment/Submission or REV - queue/lease rows first, then the selected published policy version, - rule/definition and referenced binding, then the frozen lineage write; -- binding retirement or reconciliation that inspects task/assignment/lease - dependencies: affected lifecycle rows in the same task/REV order first, then - binding/policy and CON delivery/receipt/projection rows. If the bounded rows - cannot be enumerated before locking, the operation takes its approved - project-scoped advisory fence before either family and still locks lifecycle - rows before policy/binding rows; -- an outbox handler: immutable claim-generation validation without handler - ownership of outbox transitions, then its feature-owned award, binding, - delivery, receipt, request, finding, or rebuildable projection rows. - -Pure policy/binding administration that does not inspect lifecycle dependencies -locks Project and its own aggregate only. Rows of one type lock by ascending -primary key/UUID. Missing classes are skipped without reordering. Provider or -external I/O happens only after durable pre-I/O state commits and every database -transaction/fence is released. - -The dispatcher owns claim, retry, dead-letter, and finalization transitions. -Feature handlers validate the committed claim generation through a typed port, -stage feature state, perform post-commit I/O under their own exact authority, -and return a typed outcome. They do not lock or mutate OutboxEvent rows. - -## Optional contribution-evidence projection - -A deterministic contribution-evidence document is optional later work. It is -not written or requested by CON-07, does not gate ContributionRecord creation, -and is excluded from core reads, operations, release readiness, and the joint -live drill. - -If separately approved, CON-09A/09B may implement an asynchronous projection -with independent status/failure semantics through a separately reviewed ART -capability and AUTH action. Storage failure cannot change Review, -ContributionRecord, CompensationAward, fulfillment receipt, or status -projection truth. The future contract must revalidate the then-current ART and -AUTH boundaries, exact media/schema/retention/disclosure rules, and service -identity. CON never receives ArtifactStore, scratch/preparation types, provider -references, or ART repositories. PR #129's preparation foundation does not -approve this capability. - -Core contribution and award reads move directly to CON-10A and read PostgreSQL -truth. They do not depend on an evidence artifact or ART read port. - -## Shared outbox - -CON-02A provides generic PostgreSQL persistence and caller-transaction append. -CON-02B provides the feature-neutral dispatcher, stable task IDs, claim fencing, -retry/dead-letter/replay, retention, explicit handler registry, -`OutboxClaimValidationPort`, and same-session drain observation. The outbox -subsystem owns no contribution, award, adapter, review, or provider semantics. - -## Rollout - -1. CON-01 adopts the merged WS-XINT contract and publishes the active - contribution/compensation specification without altering archival inputs. -2. CON-02A/B/C land shared outbox persistence/dispatch and shared lifecycle - audit participation, with outbox execution still disabled until its AUTH - registration, static service identity, AUTH-09E admission, hidden behavior, - and activation gates pass. -3. CON-03A-D add inactive policy, binding, contribution, award, delivery, - receipt, and status persistence using the canonical names and boundaries. - CON-03C lands only after REV's FinalAcceptance persistence target is merged. -4. CON-04A/B add hidden binding and ContributionPolicy behavior behind planned - AUTH actions. -5. After AUTH-PREP, exact-project submitter grants, and the planned task-claim - contract exist, CON-05A removes retired semantic consumers and lands the - hidden participant that freezes the published ContributionPolicyVersion on - new TaskAssignments. Task-owned claim composition consumes it before - `WS-AUTH-001-13` enumerates/registers the task-claim ActionId, integrates its - evaluator, and activates; 05B then drops unreachable physical schema after - zero-consumer proof. -6. CON-06 supplies reviewer policy freeze; the REV owner wires it into hidden - review claim behavior before AUTH activates `review.claim`. -7. CON-07 supplies the flush-only decision participant that consumes REV-owned - FinalAcceptance for submitter work; the REV owner wires it into the complete - hidden decision path and owns audit/outbox staging before AUTH activates - `review.decision`. -8. CON-08A/R/B add fulfillment delivery and callback behavior only after exact - service execution/callback identities, actions, static rows, AUTH-09E, and - lifecycle fencing are approved. Every fulfillment-obligation root writer, - requeue, successor, and repair path acquires the shared lifecycle fence - before allocating its immutable monotonic ordinal. Dispatch and callback - composition exposes same-generation/pre-cutoff completion behavior without - provider I/O under the fence. -9. CON-10A/B add PostgreSQL product reads and bounded operation requests; 10C - adds independently authorized reconciliation/rebuild executors. Optional - 09A/09B remain outside the core dependency sequence. -10. CON-11 proves hidden readiness. It enumerates every obligation writer and - supplies mandatory dispatch/callback hooks plus a same-session observation - port returning outbox/fulfillment counts and the maximum root ordinal. REV- - 12A injects the one shared `JointLifecycleMutationFence`, persists the - generation cutoff, and owns release-control state; CON creates no second - controller. REV-13C owns final public release and the joint live drill. - -Every chunk refreshes trusted-main SHA, migration custody, exact port/action -symbols, and merged dependency evidence. No cross-initiative successor starts -automatically. - -`REV-12A` and `REV-13` are canonical non-executable parent split records. Their -concrete runtime children control this plan: REV-12A1 persists the sole joint -controller, REV-12A3 composes the CON writer/dispatcher/callback/cutoff/drain -fences, and REV-13C alone releases the public product surface. - -### Merged REV interleaving - -Merged REV PR #128 fixes cross-initiative gates without starting either -initiative automatically: - -```text -REV-02 immutable Submission/TaskAssignment attribution - -> CON-05A/B task freeze and retired-field cutover +No catch-all CON service, dynamic plugin registry, generic service locator, +compatibility alias, or dispatcher-authority inheritance is permitted. -CON-03B ContributionPolicyVersion persistence - -> REV-03A ReviewLease foreign key +## Migration strategy -CON-02A shared outbox + CON-02C lifecycle audit participant - -> REV-04B Review/FinalAcceptance persistence - -> CON-03C exact contribution source schema +- Never reserve migration numbers in planning. +- Each implementation refreshes `main` immediately before editing and uses the + then-current single head. +- Every migration proves fresh install, PostgreSQL upgrade, guarded downgrade, + and exact constraint parity. +- Legacy economic rows are never guessed or silently backfilled. -CON-06 reviewer policy freeze - -> REV-06A claim composition +## Verification strategy -REV-09B stable lineage + CON-03C schema + CON-07 two-operation participant - -> REV-10 first canonical Review-committing transaction +Every runtime chunk must run its focused tests, Ruff/type checks as applicable, +PostgreSQL migration proof, changed-subsystem coverage at least 90%, and the +repository-wide 78% floor in hosted CI. High-risk auth/payment/architecture +chunks require senior, QA, security, product/ops, architecture, docs, +reuse/dedup, test-delta, and CI-integrity review as applicable. -CON-02B dispatcher/handler registry -> REV-12P1 projection handler +## Alternatives rejected -CON-11 writer/dispatch/callback/ordinal/drain manifest + REV-12P3 observations - -> REV-12A1 controller persistence -> REV-12A3 CON fence composition - -> AUTH action-specific activation - -> REV-13C joint release -``` +- Waiting for the dispatcher before creating policy tables: blocks REV for no + technical reason. +- Letting REV own ContributionPolicyVersion or ReviewLease policy selection: + crosses product ownership. +- Letting CON create ReviewLease or FinalAcceptance: transfers judgment state. +- Calling ART/provider services in the review transaction: creates availability + coupling and breaks atomicity. +- Treating plans/open PRs as implemented behavior: contradicts the current + capability ledger. -The merged REV plan proves ownership and ordering only. Each arrow still waits -for the exact runtime predecessor on then-current trusted main. - -## Verification strategy +## Stop -- Isolated PostgreSQL migration, constraint, rollback, idempotency, and both- - order concurrency tests. -- Bounded local focused coverage for each new/materially changed subsystem at - or above 90 percent; after PR push, GitHub CI runs the repository-wide suite - and enforces repository coverage at or above 78 percent. -- Exact contribution cardinality for all three decisions and repeated/revision - Reviews; accept-only FinalAcceptance one-to-one constraints; mutually - exclusive reviewer/submitter source shapes; automated checks create none. -- Policy publication/freeze races, explicit unpaid rules, immutable published - versions, and at most one award per contribution/instrument. -- Participant fault injection proving Review/FinalAcceptance/task/contribution/ - award/audit/outbox atomic rollback and no ART call. -- AUTH tests for planned denial, exact grant/static-matrix candidates, prepared - handle misuse, role-specific revocation, cross-service denial, and one - activation custodian per action. -- Outbox tests proving the dispatcher cannot execute feature authority and each - protected handler has an approved independent authorization path. -- Callback/delivery/reconciliation tests with no provider I/O under database - locks and immutable receipt/award identities under replay. -- Hidden OpenAPI proof before release; exact `/api/v1` inventory at release. -- Stale wording, stale authorization/artifact contracts, Markdown links, loop - memory, `git diff --check`, and one-sheet roadmap checks when local sheets are - present. - -## Open human/AUTH decisions - -- D11 exact AdminRole candidate sets for award detail, delivery recovery, and - WS-CON audit actions. -- Exact ServiceIdentity/ActionId/static-row design for each protected feature - handler and fulfillment callback; proposed strings are not executable until - approved and registered by AUTH. -- Legacy pre-production row classification before CON-05A/05B migration. -- Optional evidence projection remains deferred unless separately approved. -- No adjudication decision remains: v0.1 accept/reject are terminal and no - adjudication initiative or readiness gate may enter the core order. - -## Review and stop - -Planning and every specification/runtime chunk require senior engineering, -QA/test, security/auth, product/ops, architecture, docs, and reuse/dedup. -Runtime/test chunks add test-delta; background-execution/script/config/CI changes add CI -integrity. Stop after planning reconciliation. Do not start CON-01 or another -initiative without explicit human instruction. +PLAN4 is planning only. Do not begin 03A, 03B, 02C, or any runtime chunk in +this planning change. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md index 4be86f606..3b0712e3d 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/RISKS.md @@ -1,26 +1,16 @@ -# Risks: WS-CON-001 Contribution Record And Compensation Boundary +# Risks: WS-CON-001 Contribution And Compensation -| Risk | Impact | Mitigation | Owner | -|---|---|---|---| -| Competing award-eligibility models | Critical | ContributionPolicy is sole authority; semantic then physical clean cut with no fallback | CON-05A/B | -| Review commits without contribution | Critical | Mandatory flush-only participant and one REV-owned commit; fault-injection rollback | CON-07 + REV | -| Reviewer contribution depends on branch state | Critical | Required reviewer operation precedes every branch and has no FinalAcceptance/submitter input; separate accept-only submitter operation | CON-07 + REV-08/10 | -| Submitter contribution inferred from mutable decision shape | Critical | REV-owned immutable FinalAcceptance is the sole accepted_submission source; unique task/Review/Submission and source-shape constraints | REV + CON-03C/07 | -| Mandatory ART projection blocks product truth | Critical | No ART/evidence work in core transaction or release; optional successor only | CON-07/09/11 | -| Wrong frozen policy | Critical | Assignment/lease freeze before work; immutable versions; concurrency proof | CON-05A/06 | -| task.claim activates before submitter policy freeze | Critical | AUTH-PREP + task seam -> CON-05A hidden participant -> task-owned composition -> AUTH-13 activation; pre-activation real-kernel denial | AUTH + task + CON-05A | -| Dispatcher inherits handler authority | Critical | Dispatcher-only action; exact independent service authority for protected handlers | CON-02B/08A/10C + AUTH | -| Release cutoff misses admitted fulfillment work | Critical | Shared fence before every writer ordinal; maximum-ordinal same-session observation; both-order cutoff races; completion-only drain | CON-03D/08/10B/C/11 + REV-12A | -| Operations request authority leaks into execution | Critical | 10B persists bounded human requests only; 10C uses exact fixed-service actions, cross-executor denial, replay/finding proof, and projection-only mutation | CON-10B/10C + AUTH | -| Broad or dynamic service access | Critical | Closed ServiceIdentity/static rows, controlled provisioning, AUTH-09E, cross-service denial | AUTH + CON | -| Partial ART/REV custody transfer | High | Reference complete WS-XINT handoffs; no local subset or dual writer | AUTH | -| Cross-domain deadlock/partial commit | Critical | AUTH-first common prefix; operation-specific REV/task lifecycle-before-policy order; one session/commit; both-order PostgreSQL tests | AUTH + REV + CON | -| Prepared handle substitution or stale authority | Critical | Exact session/action/actor-ref/idempotency/request-digest binding; AUTH consumption after final-fact recomposition; single use and non-consumption on rejected substitution | AUTH + each mutation owner | -| Wrong grant substitutes for shipping authority | High | Exact submitter and reviewer grants only; unrelated project/admin grants deny; no adjudication dependency | AUTH + task/REV | -| Provider I/O under locks | Critical | Durable pre-I/O state; release transaction/fence before adapter call | CON-08A/outbox | -| Callback spoofing/replay | Critical | Exact service identity/static row, binding match, prepared protocol, idempotent receipt | CON-08B + AUTH | -| Legacy row ambiguity | High | Human-approved deterministic rebuild/classification; migration fails closed | Human + CON-05 | -| Premature public release | High | Hidden OpenAPI, exact manifest, AUTH activation, joint REV/CON gate | CON-11 + REV | -| Adjudication scope leaks into v0.1 | High | Accept/reject are terminal; no adjudication model/action/queue/state/contribution/readiness or initiative gate | REV + CON | - -No runtime work starts while a blocking decision or prerequisite remains open. +| Risk | Impact | Mitigation | +|---|---|---| +| Old status is treated as current behavior | Duplicate or misordered work | PLAN4 binds current code, migration head, capability ledger, and PR state; dated evidence stays historical. | +| Dispatcher blocks independent policy work | REV lease persistence remains unnecessarily blocked | Move 03A/03B ahead of 02B; defer dispatcher until its actual consumers and AUTH contract. | +| CON invents AUTH identifiers or authority | Privilege escalation and dual authorization paths | AUTH exclusively registers contexts, actions, identities, matrices, evaluators, PREP, and activation. | +| REV/CON ownership blurs at policy freeze | CON could own ReviewLease or REV could own contribution policy | CON returns a policy-version lookup result; REV alone writes and transitions its lease. | +| ART/provider work enters review transaction | Availability coupling and broken atomicity | REV supplies stable artifact identity/hash; CON performs zero provider or ART calls. | +| Planning evidence is treated as runtime | Wrong migration or dependency assumptions | Treat ART #249 as merged ART runtime and REV #258 as merged planning evidence only; refresh main before every implementation. | +| Migration collision with ART/REV | Broken linear history | Allocate only from the then-current Alembic head; no number is reserved in planning. | +| Legacy economic rows are guessed | Corrupted award policy lineage | Require explicit deterministic classification or fail closed before 05A/05B. | +| Dispatcher authority leaks to handlers | Cross-feature service privilege | Dispatcher owns mechanics only; every protected handler has independent identity/action/context. | +| Optional evidence becomes core availability dependency | ART outage blocks contribution truth | Keep 09A/09B deferred and PostgreSQL reads authoritative. | +| Provider receipt leaks secrets | Security/privacy incident | Persist only bounded non-sensitive receipt facts; explicitly deny provider bodies, secrets, tokens, signatures, URLs, PII, balances, ledgers, settlement data, and digests derived from any forbidden input. | +| Review decision and contribution partially commit | Canonical truth divergence | REV owns one transaction and commit; CON participants flush only with fault-injection proof. | diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md index 709436ff2..4b7994a1b 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/SOURCE_MANIFEST.md @@ -1,127 +1,69 @@ -# Source Manifest: WS-CON-001 Contribution Record And Compensation Boundary +# Source Manifest: WS-CON-001 -## Reference inputs - -| File | SHA-256 | Status | -|---|---|---| -| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.md` | `cddbe20f4fadf5307f68519347bdd9520ef49b23fb0b92cad24c31fc9b34c640` | Working transcription; not canonical | -| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification(2).pdf` | `ce65e208076769f0bafb09779d60ab6f5fc0c596514d4e8f4cc03690c6e6d457` | Revised archival input; not runtime authority | -| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.pdf` | `34c4337f27e42a5b0ed5e153fe8ccd492ecede202c2764506a930d109aef66c1` | Original archival input; pre-existing user deletion remains untouched | - -## Trusted baseline +## Reconciliation baseline -- `origin/main` at `8d5eb15b384fd75787ce98a099400a1d335d2560`, merging - contributor-foundation PR #153 after AUTH-09D-B PR #152 and ART-02B1 PR #151 - after planning-only REV PLAN2 PR #150, - AUTH-09D-A PR #148, REV-02 - PR #147, REV-01 PR #145, AUTH-09C PR #146, ART PR #141, AUTH-09B PR #143, - reviewed REV planning PR #128, AUTH-09A, AUTH PR #140, and WS-XINT PR #139. -- PR #128 remains planning authority, not Review runtime implementation. -- REV PLAN2 PR #150 is the current runtime-readiness planning authority. It - splits future REV parent records into executable children but changes no - backend runtime, migration, AUTH catalogue, or 02A outbox contract. -- ART-02B1 PR #151 adds the S3-compatible ArtifactStore adapter and real MinIO - proof plus inactive AWS-profile support. It adds no migration or outbox seam, - and remains outside the core Review-to-CON transaction. -- Runtime AUTH is 74 PermissionIds, 65 ActionIds, 17 active, 48 planned. - AUTH-09B activates only `actor.service.provision`; AUTH-09C activates only - `actor.profile.read` and `actor.identity_link.read`; AUTH-09D-A activates - only the three actor-profile lifecycle actions; AUTH-09D-B activates only - identity-link revoke/reactivate. Contributor-foundation PR #153 clean-cuts - TaskAssignment and Submission attribution to canonical human - `contributor_id` and adds write revalidation without changing catalogue or - availability. Fixed-service admission remains planned. No CON or task-claim ActionId exists, - and these administrative operations grant no service runtime authority. -- PR #140 remains the source for AUTH activation-custody, prepared-protocol, - revised chunk, - operations, and verification contracts. It changes no runtime CON behavior, - registers no CON action, and activates no feature action. -- AUTH-09B provides the controlled human provisioning path for an approved - closed fixed ServiceIdentity but does not implement AUTH-09E admission or add - any CON identity/static row. +- Current `main`: `2feaf47dd5bb448db076179d96751caa55fb0994`. +- Current migration head: `0050_guide_source_v2`. +- 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 + context, not current authorization or runtime state. -## Human boundary amendment +## Canonical product sources -- On 2026-07-17 the human fixed the v0.1 shipping path as - `Review(accept) -> FinalAcceptance -> accepted_submission` and explicitly - excluded adjudication lifecycle/actions/readiness. -- Merged REV PR #128 and its PLAN2 PR #150 refresh plan FinalAcceptance, exact - `accepted`/`needs_revision`/`rejected` effects, two ordered CON participant - operations, and REV-12A lifecycle-control hooks. WS-CON implementation still - waits for each exact runtime chunk and consumes no sibling-worktree behavior. -- The amendment's `submission_version_id` is normalized to canonical - `Submission.id` / `submission_id`; current runtime already stores each - immutable version as a Submission row. -- Planned REV-04B retains `policy_context_ref` as the foreign key to exact locked - `ReviewPolicy.id` and `recorded_by` as the reviewer ActorProfile field; CON - consumes those names and REV owns/proves the lineage. -- `docs/review_closure.md`, `docs/review_final_adversarial_review.md`, and - `docs/review_adversarial_quality_review.md` are historical internal-review - recommendations, not live lifecycle specifications. Their older “second - review” or “overturned” proposals cannot delay FinalAcceptance, add a second - decision, or gate CON readiness. PLAN2 updates active operations/templates - only and preserves those review records as historical evidence. - -## Normative repository sources - -- `AGENTS.md` - `README.md` - `docs/glossary.md` - `docs/architecture_lockdown.md` - `docs/architecture_data_model.md` - `docs/architecture_lifecycle_state_machine.md` -- `docs/decision_0005_postgres_is_the_record_database.md` -- `docs/decision_0007_async_first_execution.md` +- `docs/roadmap_status.md` +- `docs/spec_contribution_compensation.md` +- `docs/spec_authorization_service.md` +- `docs/spec_artifact_storage_service.md` - `docs/decision_0009_review_decisions_are_canonical.md` -- `docs/decision_0010_revision_context_rebase.md` - `docs/decision_0012_workstream_authorization_service.md` - `docs/decision_0013_immutable_artifact_storage_boundary.md` - `docs/decision_0014_external_service_adapter_convention.md` -- `docs/decision_0015_project_contributor_roles_are_independent.md` -- `docs/spec_authorization_service.md` -- `docs/spec_artifact_storage_service.md` -- `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/ACTIVATION_CUSTODY.md` -- `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-PREP-prepared-mutation-protocol.md` -- `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-13-task-assignment-cutover.md` -- `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-16-evidence-live-proof.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/CON_INTEGRATION_REVIEW.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/DECISIONS.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/PLAN.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-08-immutable-decision-kernel.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-10-contribution-integration-hidden-composition.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-12A-joint-lifecycle-release-control.md` -- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/chunks/WS-REV-001-PLAN2-runtime-readiness-plan-refresh.md` -- `.agent-loop/policies/*` +- `docs/decision_0016_contribution_compensation_boundary.md` -## Normative WS-XINT handoffs +## Current implementation evidence -- `WS-XINT-001/REV_CON_HANDOFF.md`: core contribution participant, frozen - ContributionPolicyVersion, no core ART dependency. -- `WS-XINT-001/AUTH_ROLE_SERVICE_HANDOFF.md`: independent project grants, - fixed-service static matrix, AUTH-09E admission. -- `WS-XINT-001/AUTH_REV_HANDOFF.md`: complete REV activation-custody and hidden - behavior choreography. -- `WS-XINT-001/AUTH_ART_HANDOFF.md`: complete 25-action ART custody transfer; - referenced only, not a core CON dependency. -- `WS-XINT-001/DECISIONS.md`: D1-D13 ownership and transaction rules. +- `backend/app/modules/authorization/**`: actor/grant/fixed-service/PREP and + typed REV readiness contracts. +- `backend/app/modules/artifacts/**`: artifact admission, binding, extraction, + guide sufficiency, and guide read/binding foundations. +- `backend/app/modules/outbox/**` and migration `0029`: shared outbox + persistence/append only; no dispatcher exists. +- `backend/app/modules/audit/**`: existing shared audit foundation; no typed + lifecycle participant yet. +- No `backend/app/modules/contributions/**` or compensation runtime exists. +- No live ReviewQueueEntry, ReviewLease, Review, or FinalAcceptance lifecycle + implementation exists. -## Runtime observations +## Current initiative evidence -- Current code still contains the retired guide-bound economic schema; CON-05A - and 05B own semantic then physical removal after a human migration decision. -- No ContributionPolicy, ContributionRecord, CompensationAward, fulfillment, or - WS-CON action runtime exists yet. -- No FinalAcceptance runtime exists yet; merged planning assigns it to REV-04B - and makes that exact schema a prerequisite for CON-03C/07. -- Existing `Submission` is the versioned identity; no new SubmissionVersion is - required. -- ART preparation from PR #129 is inactive foundation only and does not approve - optional contribution-evidence projection. -- Sibling worktrees remain discovery evidence only. Merged REV planning is - authoritative for sequencing but does not satisfy its own runtime gates. +- `.agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/**` +- `.agent-loop/initiatives/WS-ART-001-immutable-artifact-storage/**` +- `.agent-loop/initiatives/WS-REV-001-review-revision-lifecycle/**` +- `.agent-loop/initiatives/WS-XINT-001-lifecycle-boundary-reconciliation/**` +- `.agent-loop/initiatives/WS-XINT-002-art-auth-end-to-end/**` +- `.agent-loop/initiatives/WS-XINT-003-rev-auth-end-to-end/**` +- Merged ART PR #249: guide-source v2 cutover and migration `0050`; current ART + runtime evidence, not CON implementation. +- Merged REV PR #258: current PLAN4 planning refresh; not runtime and does not + satisfy a runtime gate by itself. + +Open-PR check and merge states are intentionally not persisted as durable plan +truth. Re-read them immediately before implementation or publication. + +## Reference inputs -## Adoption note +| File | Status | +|---|---| +| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.md` | transcription; not canonical | +| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification(2).pdf` | archival input; not runtime authority | +| `docs/reference_specs/WS-CON-001-contribution-record-and-compensation-boundary-specification.pdf` | pre-existing user-owned deletion; deliberately untouched | -The reference inputs contain useful invariants but do not override merged -repository decisions. CON-01 writes the active specification after explicit -approval and leaves archival inputs unchanged. +The reference inputs preserve design evidence but cannot override merged +repository decisions. Old SHAs and signed-loop projections in historical +planning records describe their time; they are not current-state evidence. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md index 1d314329c..d6f52206e 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/STATUS.md @@ -1,201 +1,76 @@ -# Status: WS-CON-001 Contribution Record And Compensation Boundary - -## Current status - -`WS-CON-001-01` merged through PR #144 at trusted-main SHA `e118e33`. The -generated post-merge state on `automation/loop-memory` was signature-verified -against that exact main SHA. The human explicitly started `WS-CON-001-02A` on -2026-07-18. CON-02A is now the only active chunk and is limited to generic -PostgreSQL outbox persistence plus append/replay in a caller-owned transaction. -It introduces no route, dispatcher, delivery executor, Celery registration, -protected handler, feature authority, contribution, compensation, review, or -artifact behavior. Trusted `main` then advanced through ART PR #141 at -`a10d901` and AUTH-09C PR #146 at `0ffdabf`. CON-02A initially followed -ART-owned `0025_artifact_store_v2`; ART's adapter, storage, startup, and -delivery-executor changes do not add an outbox seam or change this boundary. -AUTH-09C activates only the canonical administrative -`actor.profile.read`/`actor.identity_link.read` actions; it adds no CON or -outbox identifier and does not change 02A's authorization-neutral boundary. -Trusted `main` then advanced to `b2b9016` through REV-01 PR #145. Its canonical -review specification preserves the two ordered CON flush-only operations, -accept-only FinalAcceptance source, REV-owned single commit, and same-transaction -shared outbox staging. It adds no backend runtime or migration and therefore -does not change the 02A implementation boundary. -Trusted `main` then advanced to `f18b620` through REV-02 PR #147. That -planning-only merge splits future guide activation, ReviewPolicy/task -lifecycle, and submission attribution work into explicit REV chunks. It adds no -backend runtime, migration, or shared outbox behavior and leaves CON-02A -unchanged. -Trusted `main` then advanced to `99ae4c96` through AUTH-09D-A PR #148. That -merge activates only three actor-profile lifecycle actions and adds AUTH-owned -`0026_actor_profile_lifecycle`; it adds no CON/outbox identifier, evaluator, -service identity, static row, or fixed-service admission. CON-02A is therefore -rebased as linear `0027_shared_transactional_outbox` after AUTH's revision. -Trusted `main` then advanced to `983b9e53` through planning-only REV PLAN2 PR -#150. It splits future REV runtime parents into executable children and updates -their exact CON gates, while preserving the ordered reviewer/submitter -operations, accept-only FinalAcceptance, REV-owned audit/outbox staging, and -single commit. It adds no backend runtime, migration, AUTH catalogue entry, or -02A behavior. CON-02A therefore remains the same `0027` implementation. -Trusted `main` then advanced to `1b5422fc` through ART-02B1 PR #151. That merge -adds the S3-compatible ArtifactStore adapter, MinIO/AWS configuration, exact SDK -pins, CI MinIO service, and substantial backend tests. It adds no migration, -outbox seam, CON identifier, or core transaction dependency, so CON-02A remains -the same `0027` implementation. Because it materially changes dependencies, -CI, and repository tests, the pushed PR must receive fresh GitHub full-suite -evidence. -Trusted `main` then advanced to `93dd3924` through AUTH-09D-B PR #152. It -activates exactly `actor.identity_link.revoke` and -`actor.identity_link.reactivate`, expands AUTH routes/tests, and adds the -reviewed but inactive contributor-foundation contract. It adds no migration, -CON/task-claim action, fixed-service admission, or outbox seam. CON-02A remains -the same `0027` implementation, but repository-wide evidence must rerun in -GitHub CI after the full PR is pushed. -Trusted `main` then advanced to `8d5eb15b` through contributor-foundation PR -#153. That merge clean-cuts TaskAssignment and Submission human attribution to -`contributor_id`, adds canonical-human database lineage and active-human writer -revalidation, and owns `0027_contributor_foundation`. It changes no ActionId, -PermissionId, grant, evaluator, action availability, fixed-service admission, -review lifecycle, dispatcher seam, or outbox behavior. CON-02A therefore moves -to the linear child `0028_shared_transactional_outbox`; its generic, -authorization-neutral behavior is otherwise unchanged. Repository-wide proof -remains GitHub CI-owned. -Trusted `main` then advanced to `44f2467c` through ART-02C1 PR #154. ART owns -`0028_artifact_admission`; it adds no outbox seam or CON authority. CON-02A -therefore moves unchanged to the linear child -`0029_shared_transactional_outbox`. Fresh bounded and exact-SHA review evidence -must bind this reconciliation before PR #155 is republished. -Trusted `main` then advanced to `3b1d6379` through planning-only REV-02A PR -#156. It adds no migration, runtime outbox seam, or CON authority; CON remains -the linear `0029_shared_transactional_outbox` child of ART `0028`. - -`WS-CON-001-PLAN3` completed its pre-external-review exact-SHA review at -`e968430b0c3b5f1432899c9aa31ef209b774eae0` after current-main reconciliation -with merged REV PR #128 at `0302bcf`, which also contains AUTH-09A after AUTH PR -#140. The prior planning snapshot `09128ee1aed941682c7cb59ca04698de496de682` -remains historical and no longer controls publication. The reviewed refresh -corrects the AUTH catalogue baseline, replaces the obsolete omnibus nullable CON -decision input with two ordered operations, and adopts REV-12A's exact -obligation-writer/ordinal/cutoff hooks. PLAN2's human-approved v0.1 -`Review(accept) -> FinalAcceptance -> accepted_submission` boundary remains -intact. Runtime code is unchanged. -CodeRabbit then opened five consolidated contract-quality threads. PLAN3's -planning-only repair added executable verification gates, restored exact AUTH -prerequisite ownership, moved optional CON-09B to a deferred proposal, aligned -the PR trust bundle, and recorded the external response/review log. All required -tracks passed exact SHA `a69fad3a32ad47e3bd60a79cd75f5867eefc52b3`. -The prior plan is superseded where it used the older policy aggregate, made ART -evidence mandatory, described service action rows as persisted assignments, -allowed partial activation-custody transfer, or let outbox dispatch imply -feature-handler authority. -CON-01 then published the canonical active specification and ADR 0016. Internal -review required explicit `NUMERIC(38, 18)` and project-scoped unit semantics, -bounded/redacted immutable provider receipt facts, plus complete conformance -rows for adapter binding, lifecycle audit, and ADR 0014. Those findings were -repaired without changing runtime, CI, tests, dependencies, or archival inputs. -CodeRabbit then identified two contract ambiguities: the adapter-binding row -could imply forbidden reverse policy/award identifiers, and the receipt wording -did not distinguish authentication tokens from bounded non-secret receipt -identifiers. Both were corrected at `c027a4b`; all eight required internal tracks -passed the exact repaired SHA with no findings. -Before the human checkpoint, trusted `main` advanced to `053242b` through merged -AUTH-09B PR #143. CON-01 now adopts its controlled service-provisioning route, -74/65/10/55 catalogue baseline, and explicit separation between provisioning -and runtime service admission without changing the contribution lifecycle. -All eight required internal tracks passed the exact reconciled SHA `a6a88fb` -with no findings. Both prior CodeRabbit threads remain resolved and outdated. - -## Corrected boundary - -- ContributionPolicyVersion and ContributionRule decide award eligibility. -- Core Review -> ContributionRecord/Award is one PostgreSQL transaction with no - ART call or evidence projection. -- REV creates FinalAcceptance only for accept. Reviewer contributions source - Review directly; submitter contributions source FinalAcceptance only. -- Shipping authority uses exact submitter and reviewer grants only; unrelated - grants do not substitute and WS-CON has no adjudication dependency. -- Fixed services require closed ServiceIdentity, exact static matrix membership, - provisioned ActorProfile/link, AUTH-09E admission, and active action. -- ActionOwner is AUTH activation custody. Complete ART/REV transfers are - referenced from WS-XINT and not partially restated by CON. -- Outbox dispatch owns outbox mechanics only. Protected handlers need exact - independent authority. -- CON-09A/09B are deferred optional successors and do not gate the core release. -- AUTH PR #140 registers no CON ActionId and activates no feature action. Its - exact custody and prepared-protocol contracts remain upstream gates. -- Current main has 74 PermissionIds and 65 ActionIds: 17 active and 48 planned. - AUTH-09B activates only `actor.service.provision`; AUTH-09C activates only - `actor.profile.read` and `actor.identity_link.read`; AUTH-09D-A activates only - the three actor-profile lifecycle actions; AUTH-09D-B activates only - identity-link revoke/reactivate. These administrative capabilities - grant no fixed-service runtime admission or feature authority. - No CON or task-claim ActionId exists, and the current fixed identities are - ART-only. -- `task.claim` activation must follow, not precede, the CON-05A hidden - TaskAssignment contribution-policy freeze. -- Merged REV planning requires the CON reviewer operation before the decision - branch and the accept-only submitter operation afterward; it rejects one - nullable omnibus participant input. -- REV-12A3 requires every CON fulfillment-obligation writer to fence before - monotonic ordinal allocation and requires same-session maximum-ordinal/drain - observation for the immutable delivery cutoff. REV-12A is only the canonical - non-executable parent split record; REV-12A1 persists the sole controller. - -## Active chunk - -`WS-CON-001-02A` implementation is reconciled with trusted main `3b1d6379` -after the explicit human start. It adds one linear -`0029_shared_transactional_outbox` migration after ART-owned -`0028_artifact_admission`, the shared outbox model/schema/repository/service, -metadata registration, and PostgreSQL-focused migration/append tests. Fresh -bounded proof passes 73 selected tests with 32 deselected after the Proxy repair and -95.90 percent outbox coverage; the exact AUTH revision-specific lifecycle test -and assertion-helper regression suite also remain recorded independently. A -GitHub full-suite run reached 87.19 percent coverage and 1665 passing tests, -then exposed a mutable-dictionary race in that assertion helper; exact repair -candidate `9be9c88a` snapshots entries, distinguishes real dict storage from -framework Mapping proxies, adds deterministic regression coverage, and passes -all nine internal tracks. GitHub CI must rerun the full repository -suite and 78 percent coverage gate after publication. The first reconciled -full-suite attempt was stopped after two hours solely because PR #150 advanced -trusted main; a second attempt was stopped after 3 hours 7 minutes solely -because ART PR #151 advanced trusted main; a third was stopped after one hour -solely because AUTH PR #152 advanced trusted main. None is counted as evidence. -A fourth current-head local attempt was stopped after approximately 4 hours 15 -minutes by human direction that repository-wide suites run in GitHub CI; its -metadata was removed and it is not evidence. -It stops before dispatcher mechanics and CON-02B. - -| Chunk | Status | Notes | -|---|---|---| -| `WS-CON-001-PLAN` | Complete; superseded baseline | Based on PR #139 / `5d353b6`; reviewed content `c4242e0` | -| `WS-CON-001-PLAN2` | Complete; unpublished | FinalAcceptance is REV-owned; CON trigger changes only; all required internal tracks pass | -| `WS-CON-001-PLAN3` | Complete; externally repaired and internally reviewed | CodeRabbit gates/AUTH scope/09B/trust repairs pass at `a69fad3` | -| `WS-CON-001-01` | Complete; merged | PR #144 merged at `e118e33` | -| `WS-CON-001-02A` | PR #155 CI repair ready to publish | Generic persistence/append only; exact repair SHA passes all nine internal tracks; GitHub full-suite and CodeRabbit must rerun; retention remains deferred to 02B | -| `WS-CON-001-02B` through `08B`, `10A` through `11` | Proposed | Separate explicit start required after predecessor merge and upstream refresh | -| `WS-CON-001-09A/09B` | Deferred optional | Separate approval and fresh ART/AUTH review required | - -## Open gates - -| Gate | Owner | Required action | -|---|---|---| -| FinalAcceptance and decision integration | REV + CON | REV-04B runtime persistence -> CON-03C; REV-09B lineage + CON-07 two-operation participant -> REV-10 hidden single-commit composition -> AUTH activation | -| Active specification/archive handling | Complete | CON-01 merged in PR #144; archival inputs remain untouched | -| Pre-production legacy rows | Human | Choose deterministic rebuild or explicit classified migration before 05A/05B | -| D11 AdminRole candidates | Human + AUTH | Fix award-detail, delivery-recovery, and audit candidates before registration | -| Core WS-CON action registration/activation | AUTH | Add reviewed registration and later activation chunks; CON remains hidden | -| Fixed service runtime | AUTH | AUTH-09A through 09D-B and the contributor foundation are merged; approve/register any new CON identity/static row, then complete AUTH-09E before protected service calls | -| Feature handler authority | Human + AUTH + CON | Approve exact identities/actions/static rows; no dispatcher inheritance | -| AUTH prepared protocol | AUTH | Merge AUTH-PREP after AUTH-09E; all CON-sensitive mutations consume its exact opaque handle contract | -| task.claim | AUTH + task + CON | Only PermissionId exists; after AUTH-10/PREP and stable task seam, merge CON-05A freeze and task-owned composition; AUTH-13 enumerates/registers/evaluates/activates afterward | -| review.claim/review.decision | AUTH + REV + CON | Complete REV custody transfer and AUTH-PREP; merge hidden CON participants and REV composition; AUTH-REV-06/08 activate afterward | -| Shared outbox | CON-02A/B | Land generic persistence/dispatcher after approval | -| Joint release | REV + CON + AUTH | Consume exact hidden manifest; optional evidence and ART are not prerequisites | -| Fulfillment cutoff/drain | CON + REV-12A1/12A3 | CON-03D ordinal; all writer/dispatch/callback hooks; CON-10B observation; CON-11 manifest -> REV-12A1 controller persistence -> REV-12A3 CON fence composition | - -## Stop condition - -Implement and review only CON-02A. Stop at its specific PR human checkpoint; -do not begin CON-02B, and do not merge without explicit approval for the -specific CON-02A PR. +# Status: WS-CON-001 Contribution And Compensation + +## Current baseline + +- Reconciled main: `2feaf47dd5bb448db076179d96751caa55fb0994`. +- Backend CI for that SHA: failing one AUTH actor-profile concurrency test in + `shared_foundations`; the planning diff changes no AUTH/runtime/test/CI files. +- Alembic head on main: `0050_guide_source_v2`. +- CON-01 and CON-02A are merged. +- No CON runtime chunk is active in this worktree. +- Runtime contains shared outbox persistence only; contribution, compensation, + 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. + +## Current external work inspected + +### AUTH/XINT + +Merged through PR #257: + +- review/revision policy identity and mutations; +- complete planned REV action/principal catalogue; +- typed fail-closed REV resource, PREP, and read contracts. + +This is readiness for hidden REV implementation, not a live review lifecycle. +CON dispatcher and protected CON surface identifiers remain unregistered. + +### ART + +Guide byte ingest, binding, extraction, sufficiency foundations, and the +verified guide-source v2 cutover are merged. AUTH guide binding/read activation +is merged. ART PR #249 and migration `0050_guide_source_v2` are now part +of main; their contracts remain ART-owned inputs rather than CON behavior. + +### REV + +REV PR #258 is merged planning-only end-to-end evidence. It correctly +preserves CON ownership and identifies CON-03B as +the policy FK prerequisite for REV-03A2. + +## Corrected CON priority + +The old plan incorrectly made dispatcher work the predecessor of all CON +schema work. Current dependency analysis yields: + +1. PLAN4 planning reconciliation. +2. CON-03A adapter-binding persistence. +3. CON-03B contribution-policy persistence, unblocking REV-03A2. +4. CON-02C lifecycle-audit participant before REV-04B. +5. Hidden policy/binding behavior and legacy clean cut as AUTH contracts become + available. +6. Contribution/award persistence after REV provides stable FK targets. +7. Atomic REV/CON participant after both sides' lineage exists. +8. Dispatcher and fulfillment later, after exact AUTH service registration. + +## Current blockers + +- CON-02B: missing `outbox.dispatch`, `workstream.outbox.dispatcher`, exact + matrix/context/PREP support, and AUTH activation plan. +- CON-04A/04B and later protected surfaces: exact AUTH manifests are not yet + registered. +- CON-05A/05B: deterministic legacy-row classification remains a human data + decision. +- CON-03C: REV Review/ReviewLease/FinalAcceptance tables are not implemented. +- CON-06/07: corresponding REV lease/decision caller contracts are future. +- Migration allocation: refresh after any later migration-bearing merge; do + not assume `0051` remains available. + +## Immediate next action + +Publish the reviewed PLAN4 planning repair without the user-owned PDF deletion +and obtain a green rerun or upstream AUTH repair for the concurrency failure. +After PLAN4 merges and the human approves implementation, refresh main and +implement only CON-03A. Stop at its PR checkpoint; do not start 03B or another +CON chunk automatically. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02B-shared-outbox-dispatcher.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02B-shared-outbox-dispatcher.md index c47234b69..026c6483e 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02B-shared-outbox-dispatcher.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02B-shared-outbox-dispatcher.md @@ -6,6 +6,10 @@ Implement feature-neutral claim/invoke/finalize, retry, dead-letter, replay, retention, typed handler registry, claim validation, and drain observation. L1 background-execution/operations/auth risk. +This is a later execution-foundation chunk. It is not a prerequisite for +`03A`, `03B`, `02C`, or REV persistence, and it must not start until AUTH has +merged the complete dispatcher contract below. + ## Allowed files ```text diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02C-shared-lifecycle-audit-participant.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02C-shared-lifecycle-audit-participant.md index 816a992ce..22b1057ca 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02C-shared-lifecycle-audit-participant.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-02C-shared-lifecycle-audit-participant.md @@ -6,6 +6,11 @@ Extend the existing shared AuditEvent repository/service with one typed caller-transaction lifecycle participant required by REV and CON. L1 audit/ cross-domain-transaction risk. +This feature-neutral participant is independent of policy persistence and the +outbox dispatcher. It may proceed after PLAN4 against the current AuditEvent +contract and must merge before the REV FinalAcceptance decision transaction +that consumes it. + ## Allowed files ```text diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03A-adapter-binding-persistence.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03A-adapter-binding-persistence.md index dc54e53f1..21066536c 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03A-adapter-binding-persistence.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03A-adapter-binding-persistence.md @@ -5,6 +5,11 @@ Persist immutable `ProjectCompensationAdapterBinding` identity/lifecycle without adapter behavior. L1 economic/auth/data risk. +This is the recommended first runtime chunk after PLAN4. It depends on merged +outbox persistence only for repository-wide baseline coherence; it does not +depend on the dispatcher, lifecycle audit participant, or AUTH action +registration. + ## Allowed files ```text @@ -34,6 +39,9 @@ credentials, secrets, raw provider refs, dependency or CI weakening - [ ] Schema supports callback guards but creates no ActorProfile, identity link, ServiceIdentity, static row, adapter, route, or delivery behavior. - [ ] Upgrade/downgrade and duplicate/state races use isolated PostgreSQL. +- [ ] The migration is allocated from the then-current single head; no fixed + revision number is reserved until current main is refreshed at chunk start; + ART #249 has consumed migration `0050`. ## Verification and reviewers diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03B-contribution-policy-persistence.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03B-contribution-policy-persistence.md index 60395b8e2..4205f1cd7 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03B-contribution-policy-persistence.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03B-contribution-policy-persistence.md @@ -6,6 +6,10 @@ Persist `ContributionPolicy`, immutable versions, exact rules, award definitions, and one-active-policy-per-project without commands. L1 economic/ data risk. +This chunk follows `03A`. Its published immutable +`ContributionPolicyVersion` identity is the non-null foreign-key target needed +by REV `03A2` lease/policy-freeze persistence; it does not implement REV rows. + ## Allowed files ```text @@ -37,8 +41,10 @@ public API, background executor, dependency or CI weakening 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 D2/CON-05 and rewrites no history. +- [ ] 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 + a stable owner contract for the later REV foreign key. ## Verification and reviewers diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03C-contribution-award-persistence.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03C-contribution-award-persistence.md index 367e2b535..127d7c5fb 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03C-contribution-award-persistence.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03C-contribution-award-persistence.md @@ -6,6 +6,12 @@ Persist immutable contribution/award truth against exact merged FinalAcceptance, Review, ReviewLease, TaskAssignment, and Submission targets. L1 history/economic risk. +## Prerequisites + +- CON-03B ContributionPolicyVersion/rule/definition persistence is merged. +- REV-04B runtime FinalAcceptance, Review, and ReviewLease targets are merged. +- Planning records alone satisfy neither gate. + ## Allowed files ```text @@ -61,5 +67,5 @@ mutable/void/delete/adjust path, dependency or CI weakening Execute CON-03C in `../RUNTIME_VERIFICATION.md`; changed subsystems are at least 90 percent. Senior engineering, QA/test, security/auth, product/ops, architecture, docs, reuse/dedup and test-delta are required. Stop if exact -REV-04 runtime FinalAcceptance/Review/ReviewLease targets are not merged. Merged -REV PR #128 is planning authority only and does not satisfy that runtime gate. +CON-03B policy targets or REV-04B runtime FinalAcceptance/Review/ReviewLease +targets are not merged. Merged REV planning does not satisfy that runtime gate. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03D-delivery-receipt-status-persistence.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03D-delivery-receipt-status-persistence.md index 0ed7cb0c6..53304d627 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03D-delivery-receipt-status-persistence.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-03D-delivery-receipt-status-persistence.md @@ -21,6 +21,8 @@ backend/tests/{test_compensation,test_alembic}.py ```text background executor, callback, adapter, router or reconciliation behavior provider request/attempt/balance, points ledger or settlement data +raw callback bodies, headers, signatures, URLs/endpoints, auth tokens, +unbounded provider messages/codes, opaque provider references or PII AUTH/ART edit, dependency or CI weakening ``` @@ -45,6 +47,15 @@ AUTH/ART edit, dependency or CI weakening - [ ] Status is rebuildable and cannot overwrite award/receipt truth. - [ ] Callback-before-ack, duplicate exact receipt and changed receipt are representable without provider-attempt/balance/ledger data. +- [ ] Receipt storage is a closed allowlist: bounded binding-scoped non-secret + event/reference identifiers, the exact canonical award quantity and binding + unit, closed statuses/failure codes, platform-generated digests derived only + from approved stored receipt fields, and timestamps. Digests derived from + provider bodies, tokens, signatures, URLs, PII, balances, ledgers, settlement + data, or any other forbidden input are rejected. Raw bodies, headers, signatures, + URLs/endpoints, tokens, unbounded strings, PII, balances, ledgers, settlement + data, and opaque provider references are rejected rather than redacted into + durable truth. - [ ] State constraints permit failed then fulfilled, prohibit any transition away from fulfilled, prohibit partial fulfillment, and preserve every failed receipt without allowing it to mutate award quantity or truth. @@ -52,6 +63,8 @@ AUTH/ART edit, dependency or CI weakening ## Verification and reviewers -Execute CON-03D in `../RUNTIME_VERIFICATION.md`; changed compensation code is at -least 90 percent. Senior engineering, QA/test, security/auth, product/ops, +Execute CON-03D in `../RUNTIME_VERIFICATION.md`; include rejection tests for +every forbidden receipt field, every forbidden digest input, quantity/unit +mismatch, and read/export non-disclosure proof. Changed +compensation code is at least 90 percent. Senior engineering, QA/test, security/auth, product/ops, architecture, docs, reuse/dedup and test-delta are required. Stop after schema. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-04B-hidden-contribution-policy-service.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-04B-hidden-contribution-policy-service.md index 190a3ae77..859ba61da 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-04B-hidden-contribution-policy-service.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-04B-hidden-contribution-policy-service.md @@ -28,6 +28,9 @@ legacy fallback, dependency or CI weakening ## Approved AUTH prerequisites and deferred activation gate +- CON-03B policy persistence and CON-04A hidden adapter-binding service must be + merged first. Policy publication consumes the canonical binding lifecycle + guards; neither prerequisite is inferred from planning prose. - Before this chunk starts, AUTH must merge reviewed registration of the planned `contribution.policy.*` actions, stable permission mapping, typed contexts, ActionOwner custody, and PR #140 prepared-mutation ports. The diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-08A-outbound-compensation-delivery.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-08A-outbound-compensation-delivery.md index 75793e223..0cadd2274 100644 --- a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-08A-outbound-compensation-delivery.md +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-08A-outbound-compensation-delivery.md @@ -8,7 +8,8 @@ outcome. L1 economic/external-service/auth risk. ## Prerequisites -- CON-07 and shared outbox merged; +- CON-03D delivery-receipt status persistence, CON-04A binding behavior, + CON-04B policy behavior, CON-07, and shared outbox dispatcher are merged; - exact outbound-delivery ServiceIdentity and ActionId/static row approved and registered as planned by AUTH, or an explicitly approved closed dual-principal design; diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN4-current-main-reconciliation.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN4-current-main-reconciliation.md new file mode 100644 index 000000000..a02caa85d --- /dev/null +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/chunks/WS-CON-001-PLAN4-current-main-reconciliation.md @@ -0,0 +1,61 @@ +# Chunk Contract: WS-CON-001-PLAN4 - Current-Main Reconciliation + +## Goal and risk + +Reconcile WS-CON-001 planning with current merged ART, AUTH, REV, XINT, and CON +state; remove stale sequencing; and publish the next bounded runtime contracts. +Planning/documentation risk only. No implementation is authorized by this +chunk. + +## Allowed files + +```text +.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/** +.agent-loop/merge-intents/WS-CON-001-PLAN4.json +.agent-loop/REVIEW_LOG.md only WS-CON-001-PLAN4 review result +docs/spec_contribution_compensation.md only Required Implementation Order +``` + +## Not allowed + +```text +backend or frontend runtime +migrations, workflows, CI, dependencies, unrelated specification sections +AUTH, ART, REV, or XINT initiative files +roadmap/export files or archival reference inputs +``` + +## Acceptance criteria + +- [ ] Baseline is current `main` and distinguishes merged runtime from open PRs + and historical planning. +- [ ] ART, AUTH, REV, and CON ownership and runtime gaps are explicit. +- [ ] The chunk map no longer makes the dispatcher a prerequisite for + persistence or the flush-only lifecycle audit participant. +- [ ] `03B` explicitly supplies the policy-version FK target needed by REV + lease persistence, while `02C` precedes the REV FinalAcceptance transaction. +- [ ] Dispatcher and protected executors remain blocked on independent AUTH + fixed-service action/admission contracts. +- [ ] Immediate runtime work is bounded to `03A`; no later chunk starts + automatically. +- [ ] The pre-existing reference-PDF deletion is not modified or staged. + +## Verification + +```bash +git diff --check +python3 scripts/check_markdown_links.py +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_stale_authorization_docs.py +python3 -m unittest -v scripts.test_lightweight_agent_gates +``` + +Inspect the diff for scope, current SHAs, mutable PR language, dependency +direction, and the absence of runtime edits. + +## Review and stop + +Required review covers senior engineering, QA, security/auth, product/ops, +architecture, docs, reuse, CI integrity, and test delta. Resolve or record every +valid finding. Stop after the reviewed planning package; do not implement +`03A` in this chunk. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-external-review-response.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-external-review-response.md new file mode 100644 index 000000000..0c77ecd45 --- /dev/null +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-external-review-response.md @@ -0,0 +1,63 @@ +# External Review Response: WS-CON-001-PLAN4 + +## Comments addressed + +CodeRabbit raised four initial findings and two refreshed-review findings on +PR #261: + +1. Receipt quantities/units and digest provenance were under-specified. The + `03D` contract now permits only the canonical award quantity/binding unit and + platform-generated digests derived exclusively from approved receipt fields, + with explicit negative tests for forbidden digest inputs. +2. The authorization conformance row allowed a runtime-inspection exception. + It now records current CON AUTH artifacts as absent and requires exact + AUTH-owned registration and activation evidence for every future artifact. +3. The provider-receipt risk mitigation used an incomplete exclusion list. It + now denies provider bodies, secrets, tokens, signatures, URLs, PII, balances, + ledgers, settlement data, and digests derived from forbidden inputs. +4. Dependency summaries omitted `04A -> 04B`, `03B -> 03C`, and `04A/04B -> + 08A` gates. The canonical specification, chunk map, and executable `04B`, + `03C`, and `08A` child contracts now include them. +5. The `08A` child contract omitted its explicit `03D` receipt-persistence + prerequisite. Its executable prerequisite gate now includes `CON-03D`. +6. Two canonical dependency views used broad REV persistence labels. Both now + require the exact merged `REV-04B` runtime `Review`, `ReviewLease`, and + `FinalAcceptance` targets required by the `03C` child contract. + +Internal repair review then found the canonical receipt section still allowed +ambiguous request/payload digests. The specification now matches `03D`: only +platform-generated digests over approved stored receipt fields are allowed, +and digests over any forbidden provider/sensitive input are rejected. + +The PR description warning is also addressed by publishing the complete trust- +bundle sections in the PR body. + +## Comments deferred + +None. + +## Hosted CI triage + +Backend run `30848526550` failed only +`tests/test_auth.py::test_actor_profile_lifecycle_real_postgres_concurrency` +in `shared_foundations` after 2,210 tests passed. The same AUTH concurrency test +failed on current main run `30871111339`. PLAN4 changes no AUTH runtime, tests, +workflow, or CI configuration. The branch was refreshed through current main; +publication still requires a green rerun or an AUTH-owned upstream repair. + +## Human decisions needed + +No new decision. Human review and merge ownership remain unchanged. + +## Commands rerun + +- `git diff --check` +- `python3 scripts/check_markdown_links.py` +- `python3 scripts/check_stale_workstream_wording.py` +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 -m unittest -v scripts.test_lightweight_agent_gates` + +## Remaining risks + +ART #249 is merged. Migration allocation and all future AUTH, REV, provider, +callback, and legacy-row gates must be refreshed at their owning chunk. diff --git a/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-pr-trust-bundle.md b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-pr-trust-bundle.md new file mode 100644 index 000000000..a5e9a8990 --- /dev/null +++ b/.agent-loop/initiatives/WS-CON-001-contribution-compensation-boundary/reviews/WS-CON-001-PLAN4-pr-trust-bundle.md @@ -0,0 +1,86 @@ +# PR Trust Bundle: WS-CON-001-PLAN4 + +## Chunk + +`WS-CON-001-PLAN4` — Current-Main Reconciliation. + +## Goal and human-approved intent + +Refresh the complete CON plan after merged ART, AUTH, REV, XINT, and CON work; +repair stale documents and dependency order; and identify the next bounded CON +runtime change without starting implementation. + +## What changed and why + +- Refreshed the planning baseline through main `2feaf47d`, including merged REV + PLAN4 PR #258 and merged ART runtime PR #249. +- Replaced the obsolete dispatcher-first linear order with a capability-based + partial order: `03A -> 03B`, independent `02C`, then exact REV/CON gates. +- Deferred `02B` until AUTH supplies the complete dispatcher + identity/action/matrix/context/PREP contract. +- Aligned the CON map, canonical specification, AUTH handoff, joint handoff, + conformance matrix, risks, decisions, source manifest, and immediate chunk + contracts. +- Tightened future receipt persistence against raw callback/provider/secret/PII + storage. + +## Design and alternatives + +The plan preserves subsystem ownership and one-commit orchestration: AUTH owns +authority, ART owns bytes/provider access, REV owns review lifecycle and the +decision commit, and CON owns policy/contribution/award/fulfillment facts. +Waiting for the dispatcher before independent persistence and moving foreign +behavior into CON were rejected. + +## Scope control and product behavior + +This is planning/specification work only. It changes no runtime, migration, +route, action availability, workflow, dependency, CI configuration, or test. +The pre-existing user-owned reference-PDF deletion is excluded. Product +behavior remains unchanged. + +## Acceptance proof and checks + +- Current baseline, runtime absences, open/merged PR state, and migration head + are recorded from repository/GitHub evidence. +- Canonical and initiative dependency graphs agree with merged REV PLAN4. +- `git diff --check` +- `python3 scripts/check_markdown_links.py` +- `python3 scripts/check_stale_workstream_wording.py` +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 -m unittest -v scripts.test_lightweight_agent_gates` + +All listed local checks pass. Hosted Backend currently has the independently +reproduced AUTH concurrency failure described below. No tests or CI controls +changed. + +## Reviewer results + +- Architecture: PASS after dependency-handoff repair. +- Security/auth: PASS. +- Product/ops: PASS after merged-REV risk wording repair. +- QA/test/CI: PASS WITH CONDITIONS; the user-owned PDF deletion remains + excluded, and hosted Backend must become green after the current-main push. +- Docs: PASS after correcting source-manifest paths. +- Senior engineering/reuse: PASS after aligning the `06` gate and `03D` scope. + +## External review, remaining risks, and follow-up + +Agent Gates and CodeRabbit pass on PR #261. The old Backend run failed one AUTH +actor-profile concurrency test also failing on current main; the refreshed +current-main head requires a green rerun or upstream AUTH repair. Six valid +CodeRabbit findings, including the final `03D -> 08A` and exact REV-04B runtime +gate corrections, were repaired and recorded in +`WS-CON-001-PLAN4-external-review-response.md`; the refreshed external review +is pending. Migration numbering must be refreshed at implementation start. AUTH registrations, +legacy-row classification, REV runtime targets, and provider/callback contracts +remain future explicit gates. + +After PLAN4 merges and human approval, the only recommended implementation is +CON-03A adapter-binding persistence. No later chunk starts automatically. + +## Human review focus and merge ownership + +Review the corrected partial order, AUTH dispatcher deferral, REV lease and +FinalAcceptance dependencies, receipt data minimization, and excluded PDF. +Only the human may approve and merge this PR. diff --git a/.agent-loop/merge-intents/WS-CON-001-PLAN4.json b/.agent-loop/merge-intents/WS-CON-001-PLAN4.json new file mode 100644 index 000000000..6d0c50068 --- /dev/null +++ b/.agent-loop/merge-intents/WS-CON-001-PLAN4.json @@ -0,0 +1,9 @@ +{ + "schema_version": 2, + "chunk_id": "WS-CON-001-PLAN4", + "chunk_title": "Current-Main Reconciliation", + "initiative_id": "WS-CON-001", + "next_chunk_id": "WS-CON-001-03A", + "next_chunk_title": "Project Compensation Adapter-Binding Persistence", + "next_requires_explicit_start": true +} diff --git a/docs/spec_contribution_compensation.md b/docs/spec_contribution_compensation.md index 85c60d46c..69022c3b0 100644 --- a/docs/spec_contribution_compensation.md +++ b/docs/spec_contribution_compensation.md @@ -325,8 +325,9 @@ null or a non-secret opaque token with the same length and character bounds; it is required for `fulfilled` and null for `failed`. Neither value is returned by contributor/product reads or emitted in integration events. -A fulfilled receipt requires the exact award `NUMERIC(38, 18)` quantity and a -bounded fulfillment time. A failed receipt requires one closed Workstream code: +A fulfilled receipt requires the exact award `NUMERIC(38, 18)` quantity, the +exact binding unit, and a bounded fulfillment time. A failed receipt requires +one closed Workstream code: `ADAPTER_REJECTED`, `DESTINATION_UNAVAILABLE`, `PROVIDER_UNAVAILABLE`, `PROVIDER_TIMEOUT`, or `UNKNOWN_PROVIDER_FAILURE`; unknown provider values map to the last code before persistence. Failed receipts have null quantity, @@ -335,13 +336,17 @@ receipt. A conflicting replay fails closed. Raw provider secrets, authentication tokens, unbounded callback bodies, free-form messages/codes, headers, signatures, endpoints, credentials, URLs, -markup, and provider metadata MUST NOT be persisted, logged, emitted, exported, +markup, provider metadata, PII, balances, ledgers, and settlement data MUST NOT +be persisted, logged, emitted, exported, or returned. This prohibition does not include the bounded non-secret opaque `external_event_id` and `external_reference` identifiers defined above; those may be stored only in their canonical receipt/status fields and remain excluded from product reads and integration events. Only closed canonical facts, those -bounded identifiers, and canonical request/payload digests may cross into -receipt, audit, outbox, or diagnostic records. +bounded identifiers, and platform-generated digests derived exclusively from +approved stored receipt fields may cross into receipt, audit, outbox, or +diagnostic records. Digests derived from provider bodies, tokens, signatures, +URLs, PII, balances, ledgers, settlement data, or any other forbidden input are +themselves forbidden and MUST be rejected before persistence. ### CompensationStatusProjection @@ -883,20 +888,29 @@ No dependent chunk may treat an unresolved gate as an implicit default. ## Required Implementation Order -The core dependency order is: +The core dependency order is a partial order. Persistence and flush-only +transaction participants do not wait for generic dispatch: ```text -CON-01 --> CON-02A -> CON-02B -> CON-02C --> CON-03A -> CON-03B -> CON-03C -> CON-03D --> CON-04A -> CON-04B --> CON-05A -> CON-05B --> CON-06 -> CON-07 --> CON-08A -> CON-08R -> CON-08B --> CON-10A -> CON-10B -> CON-10C --> CON-11 +CON-01 -> CON-02A +CON-03A -> CON-03B -> REV lease/policy-freeze persistence +CON-02C -> REV Review/FinalAcceptance transaction foundation +REV-04B runtime Review/ReviewLease/FinalAcceptance -> CON-03C -> CON-03D +CON-03A -> CON-04A +CON-03B + CON-04A -> CON-04B -> CON-05A -> CON-05B -> CON-06 +stable REV revision lineage + CON-03C/03D + CON-05A + CON-06 -> CON-07 -> REV-10 +AUTH dispatcher contract -> CON-02B +CON-02B + CON-03D + CON-04A/B + CON-07 -> CON-08A -> CON-08R -> CON-08B +CON-08B -> CON-10A -> CON-10B +CON-02B + CON-10B -> CON-10C +all required hidden behavior and cross-initiative gates -> CON-11 ``` +Independent branches may be scheduled separately, but each chunk remains +bounded by its reviewed contract. CON-02B is intentionally later because it +requires the exact AUTH dispatcher identity/action/admission contract; it is +not a prerequisite for CON-02C, CON-03A, or CON-03B. + Cross-initiative interleaving is mandatory: ```text @@ -906,12 +920,13 @@ REV-02 exact Submission/TaskAssignment attribution CON-03B ContributionPolicyVersion persistence -> REV-03 ReviewLease foreign key -CON-02A outbox + CON-02C audit - -> REV-04 Review/FinalAcceptance persistence +CON-02A outbox persistence + CON-02C audit + -> REV-04B runtime Review/ReviewLease/FinalAcceptance +REV-04B runtime Review/ReviewLease/FinalAcceptance + CON-03B -> CON-03C exact contribution source schema -CON-06 reviewer freeze - -> REV-06 claim composition +REV lease schema/caller facts + CON-06 reviewer freeze + -> REV-06A claim composition REV-09B stable lineage + CON-03C + CON-07 -> REV-10 first canonical Review-committing transaction