Stage v0.2 reconciliation and approved JSON representation

.codex/plans/2026-10-10-finish-ges-v02.md

@@ -0,0 +1,51 @@
+# Finish GES v0.2
+
+Binding specification: the owner's 2026-10-10 `PLEASE IMPLEMENT THIS PLAN: Finish GES v0.2` message in Codex thread 01a12707-22ff-7f52-b05b-937b45b7ce0c.
+
+Deliver accepted six-source synthesis, exact-file publication clearance and an observed public native pilot. Private support remains unverified; estate rollout and broader EES remain separate. No approval, rights decision or semantic judgment is inferred from a count or test pass.
+
+## Execution and preservation
+
+Reuse the retained isolated `ges-wave-20261009` checkout, starting at a9ab644a9577083fc130c9efa4ec249632a22dda; one integrator, read-only helpers. The user's implementation request authorizes this continuation, not fabricated reviewer grants. Preserve all old claim documents, envelopes, candidate f628db26 and private failures. PR #495 is already an ancestor of #496.
+
+Current execution lease: 21ff4851dc504fab8c0a4a527c5ffde2, owner ges-v02-finish-20261010, native surface codex:01a12707-22ff-7f52-b05b-937b45b7ce0c, 2026-10-10T19:07:12Z to 19:37:12Z. Initial tracked tree clean; scoped cwd inspection found no resident process. This is a current observed boundary, not proof of historical writer release. No worker checkout is assigned for writing.
+
+Limen's named GES continuation exception permits successive <=30-minute tranches, <=10-minute verification. Historical cumulative correction usage remains UNKNOWN with retained partial meters; this tranche is additive and must not reset them. Limen's separate verification allowance is not used. Heavy admission was denied for swap-fraction 0.612255; no full corpus/authentication/full-suite work until separately admitted. No broker run or policy change is implied.
+
+## Task 1: Five successors and authority package
+
+Add unique successor claims in the consumed `*-claims.json` format. Validate source provenance, exact statements and IDs. Prepare SUPERSEDED predecessor and SPECIALIZE successor proposals, full current input digests and unchanged-subject carryforward proof. Obtain authentic reconciliation authority and independent review before replacement envelopes. Report raw growth, superseded predecessors and repaired logical claims separately.
+
+Verification: bounded correction and receipt tests; authenticated corpus accounting only when admitted. Expected: five new unique subjects, preserved historical bytes, no unauthorised validated decisions.
+
+## Task 2: Publication amendment
+
+Prepare a narrow versioned JSON representation contract with raw source/output digests, explicit full-context decoding, separate decoded comparison and independent rights decision. Present concrete owner approval text; only implement after approval. The two held fields and old candidate remain held.
+
+Verification: proposed adversarial cases cover escaping, substantive changes, malformed context and raw-mode compatibility. Expected: amendment reviewable, no implied clearance.
+
+## Task 3: Synthesis and evidence adapters
+
+Continue WA/GHQR corrections and existing six-source queues in <=250-proposition batches with independent omission review. Authenticate retained 18,019-body cache before reacquisition; resolve source-identity/version/include/rendering gaps. Implement fail-closed structured-occurrence, generalization, adoption, binding and native adapters using paired evidence/policy CLI inputs, exact subjects, authority, independence, chronology and full denominators. Missing evidence remains unresolved. Owner adoption packages <=20 controls; scanner predicates require implementations or reviewed limitations and alternatives.
+
+Verification: stale digest, duplicate/missing subjects, unauthorized review, bad chronology, altered evidence, partial denominator and false completion; legacy report compatibility. Expected: supplied valid evidence can count, absent evidence never passes.
+
+## Task 4: Public native pilot and publication candidate
+
+Record public target approval; confirm run 37560956698 attempt 3 publisher/SHA. Read classic/inherited rules and bypass, activate only approved rule 24619160 after preflight. Observe passing and failed/absent/cancelled/skipped integration, direct/force/delete and bypass, rollback/restoration/reapply/idempotence. No visibility or spending change. Bind all observations to exact revisions. Preserve private failures.
+
+From the completed revision, create a new immutable GES_V0_2 candidate and inventory actual files. Complete expression/attribution/obligation reviews, independent audits and authentic human/distribution decisions on final bytes. Subsequent changes invalidate affected approvals.
+
+## Task 5: Acceptance
+
+Fresh whole-branch independent review; human code review, applicable security sign-off, owner adoption and acceptance. Use existing exact-head merge process. Run all six governance checks on merged main and confirm required CI on main. Confirm cleared candidate matches release files, obtain distribution authorization, and tag only the accepted commit. Never call a partial tranche the release.
+
+## Shared interfaces and rulings
+
+- Claims -> receipts: adding subjects invalidates the full input envelope; no copy-forward without exact subject equality and new authority binding.
+- Receipts -> recovery: adapters may validate evidence but cannot appoint reviewers or substitute generic assertions for observed native behavior.
+- Final bytes -> publication: no mutable output root can inherit old clearance.
+- Pilot -> native adapter: tests validate the adapter; only observed GitHub behavior validates the pilot.
+- Execution -> acceptance: bounded local tests are not the six merged-main checks.
+
+Progress and exact commands will be recorded in evidence/v02-finish-20261010; this plan remains immutable.

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
           python-version: ${{ matrix.python }}
       - run: python -m pip install -r requirements.txt
       - run: python -m unittest discover -s tests -v
-      - name: Reproduce current workload and preserve historical accounting
+      - name: Reproduce preserved workload membership and historical accounting
         run: >-
           python -m ges.claim_workload
           --reviews evidence/source-reviews
@@ -32,6 +32,18 @@ jobs:
           --check evidence/claim-workload-current-inventory.json
           --historical evidence/claim-workload-inventory.json
           --provenance evidence/claim-workload-current-provenance.json
+          --recorded-membership
+      - name: Reproduce complete current workload and exact approved transition
+        run: >-
+          python -m ges.claim_workload_migration
+          --reviews evidence/source-reviews
+          --artifacts evidence/claim-workload-inputs/artifacts.jsonl.gz
+          --reconciliation evidence/provider-oidc-reconciliation.json
+          --baseline evidence/claim-workload-current-inventory.json
+          --historical evidence/claim-workload-inventory.json
+          --provenance evidence/claim-workload-current-provenance.json
+          --transition evidence/claim-workload-v02-transition.json
+          --check evidence/claim-workload-v02-inventory.json
       - run: python -m ges validate
       - run: python -m ges compile
       - name: Generated views match the canonical catalog

docs/claim-workload-audit.md

@@ -1,5 +1,46 @@
 # Claim workload audit
 
+## Current five-successor migration
+
+The current metadata workload is recorded separately in
+`evidence/claim-workload-v02-inventory.json`: 61,941 claims in 655 documents,
+4,651 advisory families, and the same 474 source-bound workload receipt subjects.
+The original 61,936-claim reports and their provenance remain immutable.
+`claim-workload-current-inventory.json` retains its historical filename; it is the
+preserved October 7 metadata baseline, not the complete current claim directory.
+
+The transition contract in `evidence/claim-workload-v02-transition.json` binds
+both preserved reports, the new report, provenance, compressed metadata and frozen
+workload receipts to exact hashes. The validator pins that contract independently
+in code. It checks every old document byte, exact full current membership, the
+five reviewed successor IDs and their predecessor links, and unchanged historical
+family and receipt memberships. Changing totals or rebinding a mutable contract
+cannot authorize a different migration. New additions require a separately
+reviewed transition; the default full-directory inventory never ignores them.
+
+Both commands are required and run in Toolkit validation:
+
+```sh
+python -m ges.claim_workload --reviews evidence/source-reviews --artifacts evidence/claim-workload-inputs/artifacts.jsonl.gz --reconciliation evidence/provider-oidc-reconciliation.json --check evidence/claim-workload-current-inventory.json --historical evidence/claim-workload-inventory.json --provenance evidence/claim-workload-current-provenance.json --recorded-membership
+python -m ges.claim_workload_migration --reviews evidence/source-reviews --artifacts evidence/claim-workload-inputs/artifacts.jsonl.gz --reconciliation evidence/provider-oidc-reconciliation.json --baseline evidence/claim-workload-current-inventory.json --historical evidence/claim-workload-inventory.json --provenance evidence/claim-workload-current-provenance.json --transition evidence/claim-workload-v02-transition.json --check evidence/claim-workload-v02-inventory.json
+```
+
+`--recorded-membership` is an explicit preserved-snapshot check. It does not
+establish current coverage. The second command replays the complete directory
+and the preservation checks together, with an outer input-stability check.
+Missing files, symlinks, unsafe names, duplicate membership, changed bytes,
+unrelated additions, stale report hashes and altered predecessor pairs fail.
+
+This remains metadata accounting: 61,467 records lack a workload receipt, with
+zero new review or reconciliation credit. The separate broader ledger's 2,164
+historically validated dispositions and conditional 2,174-disposition expectation
+belong to authenticated claim reconciliation. Neither is a workload result.
+Original source-cache restoration, full authenticated provenance replay, semantic
+review, replacement envelopes and all acceptance decisions retain their own gates.
+See [the migration evidence](../evidence/v02-workload-migration-20261012/README.md).
+
+## Preserved baseline audit
+
 The committed audit's 61,936 denominator counts recorded source-reference claims, not
 61,936 distinct obligations. The audit preserves every occurrence and leaves
 the unique actionable-obligation count unknown. Its frozen reconciliation input
@@ -59,21 +100,21 @@ review hours or a claim that all remaining source review has been enumerated.
 
 ## Reproduction
 
-Two committed reports retain distinct provenance:
+Two preserved baseline reports retain distinct provenance:
 
 | Report | Input and scope |
 |---|---|
 | `evidence/claim-workload-inventory.json` | Historical report bound to the original private artifact inventory. Original-input byte replay is **UNAVAILABLE**. Existing review and source-table receipts retain this report's unchanged hash. |
 | `evidence/claim-workload-current-inventory.json` | Newly observed October 7 workflow metadata, preserved under `evidence/claim-workload-inputs/`. This report can be reproduced locally without network access. |
 
-The current report preserves every historical field except
+The preserved October 7 report preserves every historical field except
 `inputs.artifacts_sha256`. Neither report grants additional review credit.
-The Toolkit validation workflow requires exact current-report reproduction and
-historical accounting equivalence on every push and pull request, for both
-supported Python versions. Run the same command locally:
+Toolkit validation reproduces this baseline using its exact recorded membership,
+then checks the separate full current transition above, for both supported Python
+versions. Run the preserved-baseline command locally:
 
 ```sh
-python -m ges.claim_workload --reviews evidence/source-reviews --artifacts evidence/claim-workload-inputs/artifacts.jsonl.gz --reconciliation evidence/provider-oidc-reconciliation.json --check evidence/claim-workload-current-inventory.json --historical evidence/claim-workload-inventory.json --provenance evidence/claim-workload-current-provenance.json
+python -m ges.claim_workload --reviews evidence/source-reviews --artifacts evidence/claim-workload-inputs/artifacts.jsonl.gz --reconciliation evidence/provider-oidc-reconciliation.json --check evidence/claim-workload-current-inventory.json --historical evidence/claim-workload-inventory.json --provenance evidence/claim-workload-current-provenance.json --recorded-membership
 ```
 
 The gzip input contains only artifact metadata from workflow run
@@ -82,13 +123,13 @@ artifact `11460399285`. Its decompressed SHA256 is
 `86225491fb70197b893a0bfb1fa96ebfc1f5a6e33c21c86ab874d9d34f5db9a2`.
 The downloaded ZIP matched GitHub's recorded SHA256
 `33456e7d2d64f24eae94a4331603fe4aa48e6c36f8d4265148ffcda17f3bdf70`.
-The new [provenance record](../evidence/claim-workload-current-provenance.json)
+The preserved [provenance record](../evidence/claim-workload-current-provenance.json)
 binds both report files, the compressed and decompressed metadata, the source
 identity reference, acquisition timestamps and the observed workflow origin.
-This is a new acquisition observation; it does not restore the original cache.
+This is the recorded acquisition observation; it does not restore the original cache.
 
-The check first requires the current input's exact decompressed SHA256 and
-reproduces the current report byte for byte. It then requires every historical
+The baseline check first requires the preserved input's exact decompressed SHA256 and
+reproduces the preserved October 7 report byte for byte. It then requires every historical
 report field to match except the artifact input hash. Changes to denominators,
 memberships, document hashes, reconciliation bindings, JSON types or credit
 fields fail. Provenance validation preserves the historical report's exact byte

docs/publication-json-representation-amendment-v2-proposed.md

@@ -0,0 +1,76 @@
+# Proposed amendment: JSON string representation, version 2
+
+Status: OWNER_APPROVAL_PENDING. This proposal does not change the v1 validator,
+classify any use, grant rights, or authorize distribution. Preserve all historical
+candidate bytes and approvals, including candidate f628db26.
+
+## Owner decision requested
+
+Approve implementation of an opt-in v2 publication-use contract which distinguishes
+JSON string encoding from changes to the decoded expression. Retain raw source and
+output digest binding and all existing independent rights, audit, human acceptance
+and distribution gates. Approval of this engineering amendment is not approval of
+any individual expression use or release.
+
+## Exact interface
+
+Keep v1 records and raw-byte comparison unchanged. A v2 use record adds exactly
+one `representation` object with:
+
+- `mode`: `RAW` or `JSON_STRING`.
+- For `RAW`, no additional fields; current byte equality applies.
+- For `JSON_STRING`, `json_pointer`, `token_start_byte`, `token_end_byte`, and
+  `decoded_expression_sha256`. The token bounds include both JSON quote delimiters;
+  existing output expression bounds still identify the encoded token interior.
+
+Use UTF-8 byte offsets into the digest-bound complete output file, never character
+indices. Parse the complete JSON document with duplicate object keys rejected.
+Resolve the RFC 6901 pointer, including array indices, to a string. Parse the
+complete token with a standards-conforming JSON decoder and require it to be the
+specific string token selected by that pointer, not another equal-valued occurrence.
+Require the expression bounds to equal the interior of that token. Reject trailing
+garbage, unpaired surrogates, malformed UTF-8, ambiguous paths and nonstring values.
+
+Keep existing raw source/output span hashes and whole-file hashes. Separately hash
+the UTF-8 encoding of the decoded expression. Compare that decoded expression with
+the exact source-span UTF-8 expression, without whitespace normalization, Unicode
+normalization, case folding or punctuation rewriting. Record both raw and decoded
+equality outcomes. Do not rewrite source bytes to resemble output serialization.
+
+`LICENSED_COPY` in `JSON_STRING` mode requires decoded equality AND a separately
+reviewed lawful-use decision, attribution and obligation satisfaction. A substantive
+decoded change remains an adaptation question; it is never excused as encoding.
+Reference/paraphrase classification and whole-output audit requirements remain
+unchanged. New v2 policy approval must bind the complete manifest and use register.
+
+## The two held fields
+
+The historical publication review identifies two GES-OPS-008 fields whose JSON
+serialization adds two escape bytes: raw output is 170 bytes while decoded source
+expression is 168 bytes. Their locations and exact digests remain in
+`evidence/wave-20261009/publication/primary-review.json` and
+`evidence/wave-20261009-correction-01/publication/`.
+
+Proposed rights-review package for EACH field:
+
+1. Exact source repository, pin, artifact/full-file/span hashes and byte bounds.
+2. Exact candidate revision, output path/full-file/span hashes, pointer and token.
+3. Raw comparison failure and decoded comparison result, each independently replayed.
+4. Accountable reviewer decision on expression kind, applicable upstream license,
+   attribution, notices, obligations and any unresolved restrictions.
+5. Distinct independent use audit, complete inventory audit, human acceptance and
+   distribution approval on the new immutable candidate; no inferred approvals.
+
+These fields remain HOLD until that package is populated and accepted. A corrected
+validator cannot clear either field by itself.
+
+## Acceptance tests before implementation is accepted
+
+Escaped quotes/backslashes/control characters and valid Unicode escapes must decode
+without altering wording; literal UTF-8 and escaped Unicode must compare by decoded
+expression. Reject substantive wording/whitespace/punctuation changes, wrong pointer,
+equal string at a different location, duplicate keys, incomplete tokens, misaligned
+multibyte offsets, strings nested in arrays, surrogate errors, stale raw hashes,
+changed output files, unauthorized rights reviewers and missing audit subjects.
+Unmodified v1 fixtures must retain their current behavior, including rejection of
+raw unequal `LICENSED_COPY`. JSON representation never bypasses independent rights.