feat(governance): reconcile delivery and plan adjustments

[bokelley]

Summary

• define fact-specific authority for the buyer, seller, and buyer-appointed governance agent instead of treating any one party as authoritative for every fact
• add canonical, seller-authenticated delivery statements and separately attributed buyer delivery observations, with explicit mismatch and append-only reconciliation behavior
• allow the plan owner to close an operational governance period without turning governance into the source of truth for final billing
• make report_plan_adjustment bilateral: the seller reports immutable evidence and the authenticated plan owner accepts or disputes it before any economic or ledger effect
• expose gross commitment, verified adjustments, economic net cost, restored headroom, conservative delivery exposure, reporting-period state, and reconciliation status in audit logs
• add gross_commitment (default) and opt-in verified_net_cost accounting modes while retaining original commitments for anti-fragmentation thresholds

Why

The original adjustment design left an important trust question implicit: a seller could report one delivery amount to governance and another to the buyer, then attempt to use an adjustment to manufacture headroom. The protocol needs to preserve who asserted each fact, detect disagreement, and prevent either side's later report from silently overwriting the other.

Governance is an operational control plane, not a billing ledger. The governance ledger is authoritative for authorization and headroom; it is not independent proof of physical delivery, a refund, or the final payable amount. Seller delivery is a seller-attributed statement, buyer measurement is a buyer-attributed observation, and a commercial adjustment becomes verified only through seller report plus plan-owner review.

Behavior and impact

• seller delivery statements carry an immutable seller-scoped ID, monotonic action sequence, RFC 8785/JCS SHA-256 digest, period, cumulative spend, and currency; the exact digest-bearing payload is retained for audit
• buyer delivery observations identify the exact seller delivery check and remain separately attributed; open mismatches are marked disputed, retain both values, and use the higher credible amount as conservative_exposure
• an open dispute blocks adjustment acceptance until it is reconciled or the authenticated plan owner explicitly closes that governance period
• closing an unresolved period records closed_unresolved, freezes both parties' evidence for that period, and stops the historical mismatch from blocking later governance; it does not settle an invoice or assert billing truth
• a different subsequent seller reporting period starts open and unmatched, without carrying the old buyer observation into the current-period summary
• adjustment reporting alone cannot reduce net cost or restore headroom; only the authenticated plan owner can verify or dispute the exact record
• seller adjustment and evidence IDs are immutable, cumulative adjustments cannot exceed the original commitment, and cumulative verified decommitments cannot exceed the latest undelivered obligation
• verified refunds and credits reduce economic net cost; they restore headroom only in verified_net_cost mode. Makegoods never restore cash headroom
• delivery observations do not add the already-authorized spend to the commitment ledger a second time

Proposed WG resolutions

Issue #6304 carried needs-wg-review on three structural questions. This PR proposes specific resolutions so ratification is explicit rather than incidental to merge:

1. Separate report_plan_adjustment task — yes; the bilateral report/review lifecycle is distinct enough from report_plan_outcome to warrant its own task surface.
2. Authority split — seller uses action: "report" to submit evidence; the authenticated plan owner uses action: "review" to accept or dispute. Neither party is unilaterally authoritative.
3. Accounting mode — per-plan budget.accounting_mode field; default is gross_commitment (headroom restored only for decommitments); opt-in verified_net_cost restores headroom for refunds and credits as well.

Validation

• 78 focused governance tests
• 570 training-agent tests
• npm run test:schemas (28 schema checks plus deprecation metadata), including explicit period-close request/response cases
• npm run test:storyboard-sample-request-schema
• npm run test:examples (75 examples)
• npm run test:docs-nav
• npm run test:oneof-discriminators
• changeset protocol-scope and Changesets status checks
• TypeScript compiler output contained no errors in changed governance/training-agent files; the repository-wide typecheck still has unrelated baseline errors outside this diff

Closes #6304

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths modified without required approval.

This PR touches multiple files under static/schemas/source/** (gated paths), and review_decision is REVIEW_REQUIRED — not APPROVED. Per decision-table row 2, a gated-paths PR cannot auto-approve until a human/CODEOWNERS approval lands.

The reviewer found no Critical, High, or Medium findings: the AdCP 3.2 campaign-governance addition (new report_plan_adjustment task, attributed delivery reconciliation, gross_commitment/verified_net_cost accounting, expanded audit state) is coherent across schema and docs, the double-charge guard and adjustment attribution/authorization logic are correct, and the minor changeset is right because every governance schema is x-status: experimental. Extensive new test coverage is present. Only one Low note (delivery-metrics block ordering before the plan-existence guard, unreachable in practice) — left out of the gate.

Absent blocking findings this would approve, but the hard gated-paths gate requires explicit human/CODEOWNERS review before merge.

Escalation reasons:

• Gated files under static/schemas/source/** modified/added (governance schemas + core x-entity-types + index) with review_decision: REVIEW_REQUIRED — human/CODEOWNERS approval required before merge.

Why human review

• Gated paths touched (static/schemas/source/** — governance schemas, x-entity-types.json, index.json) and review_decision is REVIEW_REQUIRED, not APPROVED — hard approval gate requires human/CODEOWNERS review before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/x-entity-types.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/get-plan-audit-logs-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-request.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-response.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/sync-plans-request.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[lukasz-pubx]

Proposal review

Reviewed at 1b17e74bf3414ceeb77adc1514286c11e5e08195 (tree: governance schemas + report_plan_adjustment/report_plan_outcome/check_governance/get_plan_audit_logs/specification docs, compliance specialisms, training-agent reference impl & tests; baseline: repo base 502b22dbc + live docs build 3.1.2 — report_plan_outcome, reference/experimental-status).

Verdict

The tree delivers every claim in the description, and the design quality is high: the new two-action report_plan_adjustment task is fully wired (index.json, docs.json nav, x-entity types and field map), seller-attributed delivery statements, buyer observations, reconciliation states, period closure, accounting_mode, and the expanded audit surface all match the description.

Named merits:

• The worked digest example is real. I recomputed the RFC 8785/JCS SHA-256 in the check_governance example and got 4b55f115…4633 exactly. Spec examples that actually verify are rare and valuable.
• The decommitment cap is anchored to seller-attested spend ("Its amount cannot exceed authoritative commitment - latest cumulative seller spend"), so a buyer cannot use its own lower observation to manufacture headroom — the design resists both directions of abuse.
• Anti-fragmentation stickiness is preserved and explicitly reconciled with the existing "Commitments are sticky within the window" convention, closing the commit-adjust-commit loophole.
• The committed → net_committed → ledger_committed alias strategy keeps legacy readers coherent instead of silently changing one field.

The minor changeset is defensible since every touched governance schema is x-status: experimental — but see finding 2 on the migration-note obligation that status carries.

Findings

1. warning — exact-match comparison makes disputed the steady state for real buyer measurement

The spec defines disagreement implicitly as inequality: governance "compares period, cumulative spend, currency" and "If the records disagree, governance MUST: mark the governed action disputed … reject adjustment acceptance while the disputed governance period remains open" (specification.mdx, Evidence authority section). The reference implementation confirms the strict reading — observation.cumulative_spend !== sellerStatement.cumulativeSpend || … reporting_period.start !== … (governance-handlers.ts), including exact string equality on period timestamps.

Failure narrative: a buyer's ad server measures $12,489.37 against the seller's $12,500 statement — a routine sub-1% discrepancy that is the norm in delivery measurement, not evidence of equivocation. Every buyer_measurement observation disputes; every open dispute blocks all adjustment acceptance for the action; buyers learn to routinely close periods closed_unresolved. The audit state built to flag seller equivocation becomes indistinguishable from measurement noise, and the escape valve becomes the main road.

Ask — any of: (a) define a materiality rule (e.g., plan-configurable discrepancy_tolerance with a stated default) below which the state is consistent or a new non-blocking status; (b) scope acceptance-blocking to seller_statement_copy ID/digest mismatches — true equivocation — while buyer_measurement variance produces a recorded-but-non-blocking status; or (c) state normatively that exact match is intentional, buyer_measurement is expected to yield disputed in normal operation, and period closure is the routine resolution path.

2. warning — breaking reshape of experimental surfaces without the migration note the experimental contract requires

Two surfaces change incompatibly: the base delivery object was "deprecated": true with additionalProperties: true and no required fields; the PR makes six fields required with additionalProperties: false — the schema test flips accordingly ("legacy unbound delivery snapshots must be rejected"). Likewise check_governance delivery_metrics goes from one required field (reporting_period) to eight. This is permitted for experimental surfaces, but the contract says breaking changes require "At least 6 weeks published in release notes and the changelog" and "A migration note describing the change, with before/after examples where possible" (reference/experimental-status). The changeset contains neither.

Failure narrative: an existing delivery-phase seller upgrades and every delivery report is schema-rejected with no in-repo migration guidance.

Ask — add a migration note (before/after payloads for both surfaces) in the changeset or a docs migration section, or state in the PR that the note and 6-week notice will ship with the 3.2 release notes.

3. warning — new normative surface has zero agent-observable compliance coverage

Issue #6304's acceptance criteria: "Cover cancellation, partial decommitment, refund, credit, makegood, duplicate replay, conflicting replay, over-adjustment, and unauthorized reporter cases in conformance tests." The PR covers these well in training-agent unit tests (661 lines), but grep -rn report_plan_adjustment static/compliance/source/ returns nothing — the only compliance change updates governance-delivery-monitor to satisfy the new required fields. No storyboard probes the adjustment report→review lifecycle, the dispute-blocks-acceptance rule, or closed_unresolved closure. (Conceded: report_plan_outcome delivery observations had no specialism coverage before this PR either — that part is inherited — but report_plan_adjustment is brand-new surface.) Unit tests prove the reference implementation behaves; storyboards are what prove a seller behaves.

Ask — add storyboard scenarios (adjustment happy path + at least the over-adjustment and unauthorized-reporter rejections, and one dispute/closure probe in the delivery-monitor specialism), or declare the deferral and its tracking issue in the PR.

4. warning — the headline use case (cancellation before delivery) has an undocumented prerequisite

"A decommitment also requires a canonical seller delivery statement" (report_plan_adjustment.mdx); the reference impl returns CONFLICT: "A canonical seller delivery statement is required before decommitment can be verified" (governance-handlers.ts). But #6304's motivating case is releasing commitment "after cancellation" — and a buy cancelled before flight start has no delivery statement. The implied flow (seller first submits a zero-spend phase: "delivery" statement, then reports the decommitment) is sound — it forces the seller to attest zero delivery — but it is stated nowhere.

Ask — document the zero-statement pre-flight-cancellation flow with an example, or explicitly define the disposition when no statement exists.

5. note — "credible" in conservative_exposure is undefined

Schema: "Maximum credible seller or buyer amount while evidence is unresolved"; prose: "use the highest credible reported amount." If the rule is max(seller_reported_spend, buyer_observed_spend), say max — "credible" invites governance-agent discretion and divergent exposure numbers across implementations. Ask — replace with the defined rule, or define the credibility test.

6. note — seller correction path while a period is open is implicit

Reconciliation is specified buyer-side ("The buyer submits a newer observation against the applicable canonical seller statement"), and closure prohibits new statements for a closed period — but whether a seller may issue a corrected statement (new statement_id, higher sequence) for the same open period, and that the latest statement then becomes "the applicable canonical" one (as seller_reported_spend = "Latest canonical seller cumulative spend" implies), is never stated. Ask — one sentence confirming the seller correction path and which statement an observation should bind to after a correction.

7. note — this PR decides all three questions #6304 explicitly reserved for the WG

Separate task (yes), roles (seller reports / plan owner reviews), and gross-vs-net accounting (per-plan accounting_mode, default gross_commitment) are all answered here while the issue still carries needs-wg-review. All three answers look right — but the PR should say these are the proposed WG resolutions so ratification is explicit rather than incidental.

---

No blockers: the internal docs↔schema↔example↔test coherence is unusually good (digest math, schema conditionals, and x-entity wiring all check out).

[bokelley]

Thanks @lukasz-pubx — the digest-math verification and authority-table analysis are exactly the kind of independent review this surface needed. Surfacing these for @bokelley below, organized by what needs a design decision vs. what's a ready-to-apply text fix.

---

Finding 1 — Dispute semantics for buyer_measurement (design decision needed)

The exact-match check is the most consequential open question. Sub-1% delivery variance between a buyer's ad-server measurement and the seller's statement is the industry norm, not evidence of equivocation. As written, every buyer_measurement observation that doesn't happen to match the seller's figure to the cent will produce disputed, and period closure becomes the routine path rather than the escape valve.

Three paths, @bokelley's call:

Option (a) — Materiality tolerance

// plan synced with a discrepancy band
{
  "governance_config": {
    "discrepancy_tolerance": { "relative": 0.02 }
  }
}
// observations within ±2% → status: "consistent", not "disputed"

Adds per-plan configurability; introduces a new field and logic branch.

Option (b) — Source-type split

// seller_statement_copy: ID/digest mismatch → "disputed" (blocks acceptance)
// buyer_measurement: spend variance → "measurement_variance" (recorded, non-blocking)

Maps most cleanly to the PR's own authority table — seller-copy mismatch is true equivocation; buyer-measurement variance is expected noise. Requires a new enum value and spec language.

Option (c) — Document intent explicitly (lowest friction)
Add one normative sentence to specification.mdx ▸ Evidence authority:

Exact match is required. buyer_measurement observations that differ from the seller statement are expected to produce disputed in normal operation; period closure is the routine operational resolution path, not a signal of dispute in the commercial sense.

No schema change. Closes the ambiguity without new surface.

If the design intent was always "period closure is the normal path," (c) is the right answer. If measurement variance blocking adjustment acceptance is a real operational concern for the target adopters, (b) is the cleanest architectural resolution.

---

Finding 2 — Migration note missing from changeset (required by experimental contract)

experimental-status.mdx requires "a migration note describing the change, with before/after examples" for breaking changes to experimental surfaces. add-governance-adjustments.md has none. Two surfaces break incompatibly:

delivery object (check-governance-response.json / get-plan-audit-logs-response.json):

- "deprecated": true, "additionalProperties": true  // no required fields
+ "additionalProperties": false                      // six fields now required

check_governance delivery_metrics: from reporting_period-only required → 8 required fields (statement_id, sequence, statement_digest, reporting_period, cumulative_spend, currency, seller_reference, plus canonical_payload).

Suggested addition to the changeset body (or a ## Migration section in specification.mdx):

delivery schema — The deprecated unbound delivery snapshot is superseded. Before: additionalProperties: true, no required fields. After: six required fields (statement_id, sequence, statement_digest, reporting_period, cumulative_spend, currency), additionalProperties: false. delivery_metrics — Required fields expand from 1 (reporting_period) to 8; before/after examples in check_governance.mdx show both shapes. Since this lands in the first 3.2 beta, the beta publication is the 6-week-notice vehicle — note that explicitly.

---

Finding 3 — Compliance storyboard gap

No static/compliance/source/ storyboard covers the adjustment flow. Options:

• Add storyboards (happy path + over-adjustment + unauthorized-reporter rejections + one dispute/closure probe in the delivery-monitor specialism) before merge.
• Or note the deferral explicitly in the PR body with a tracking issue reference so it resurfaces before 3.2 ships.

The deferral path is lower friction if storyboards aren't blocking merge; note that report_plan_outcome delivery observations also had no specialism coverage before this PR, so this isn't introducing a new gap so much as not closing an existing one for the new surface.

---

Findings 4–6 — Ready-to-apply text fixes

Finding 4 — In report_plan_adjustment.mdx, after "A decommitment also requires a canonical seller delivery statement. Its amount cannot exceed…", add:

For actions cancelled before any delivery occurs, the seller first submits a check_governance delivery phase with cumulative_spend: 0 and the applicable reporting_period. This attests zero delivery and satisfies the statement prerequisite before a decommitment can be reviewed.

Finding 5 — In specification.mdx, replace "use the highest credible reported amount as conservative_exposure" with:

use max(seller_reported_spend, buyer_observed_spend) as conservative_exposure

And update the conservative_exposure schema description in get-plan-audit-logs-response.json from "Maximum credible seller or buyer amount while evidence is unresolved" to "Greater of seller-reported and buyer-observed spend while evidence is unresolved."

Finding 6 — In specification.mdx, in the "Reconciliation is append-only" paragraph, add:

A seller may also issue a corrected statement for the same open period by submitting a new check_governance delivery call with a higher sequence. The latest in-sequence statement becomes the applicable canonical statement; the buyer's next observation SHOULD bind to it. Earlier statements remain in the audit trail.

---

Finding 7 — WG ratification

Issue #6304 still carries needs-wg-review on the three structural questions (separate report_plan_adjustment task, seller-reports/plan-owner-reviews authority split, and accounting_mode default to gross_commitment). The PR body should call out that these are the proposed WG resolutions so ratification is explicit rather than incidental to merge.

---

Generated by Claude Code

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — hard approval gate (gated paths) unsatisfied, and a Breaking-class protocol change is present.

This PR modifies published protocol source under static/schemas/source/** (governance schemas, x-entity-types.json, index.json), which is under a hard, non-overridable approval gate. gated_paths: true and review_decision: REVIEW_REQUIRED (not APPROVED) → decision-table row 2 forces escalate. Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

Additionally, the reviewer notes the changeset's Migration section justifies "Breaking downgrades to Normative" for two x-status: experimental surfaces via a minor changeset. Per the repo's "Breaking-class changes are never auto-approved" hard gate, ratification is a human act — escalate unless review is APPROVED.

Escalation reasons

• Gated paths touched (static/schemas/source/** — governance schemas, x-entity-types.json, index.json) and review_decision is REVIEW_REQUIRED, not APPROVED. Human/CODEOWNERS review required before merge.
• Breaking-class protocol change to experimental surfaces (per changeset Migration section) is never auto-approved; requires human ratification.

Findings
No critical/high/medium findings this pass. Delta is confined to documentation clarifications (conservative_exposure wording, corrected-statement paragraph, cancel-before-delivery prerequisite) and a Migration section — all internally consistent. The escalation is driven by the deterministic gate and the breaking-change governance gate, not by any actionable code defect.

Why human review

• Gated paths touched (static/schemas/source/** — governance schemas, x-entity-types.json, index.json) and review_decision is REVIEW_REQUIRED, not APPROVED — hard approval gate requires human/CODEOWNERS review before merge.
• Changeset Migration section documents Breaking-class changes to two x-status: experimental surfaces (Breaking downgrades to Normative); Breaking-class changes are never auto-approved and require human ratification unless review_decision is APPROVED.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/x-entity-types.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/get-plan-audit-logs-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-request.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-response.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/sync-plans-request.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated paths touched without an approving review.

This PR modifies/adds files under static/schemas/source/** (governance schemas, core/x-entity-types.json, index.json), which sit under a hard, non-overridable approval gate (gated_paths: true). The current GitHub review_decision is REVIEW_REQUIRED, not APPROVED, so decision-table row 2 fires and the outcome must be escalate.

The reviewer's delta pass surfaced no critical/high/medium findings — the only change since the prior escalate touches scripts/lint-storyboard-scoping.cjs, adding report_plan_adjustment to the exempt set, and its exemption rationale (plan_id unconditionally required) matches the new schema. The diff is mechanically clean, but a clean diff does not lift the gate.

Additionally, per the repo's "Breaking-class changes are never auto-approved" hard gate, the prior pass noted Breaking-class changes to x-status: experimental surfaces documented in the changeset Migration section. Ratification is a human act and requires review_decision: APPROVED.

Escalation reasons

• Gated paths (static/schemas/source/**) touched and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS approval required before merge.
• Breaking-class protocol changes require human ratification unless review_decision is APPROVED.

Human/CODEOWNERS approval will lift the gate and allow this to fall through to a normal approve on the next pass.

Why human review

• Gated paths touched (static/schemas/source/** — governance schemas, core/x-entity-types.json, index.json) and review_decision is REVIEW_REQUIRED, not APPROVED — hard approval gate requires human/CODEOWNERS review before merge.
• Breaking-class changes to x-status: experimental surfaces (per changeset Migration section) are never auto-approved; ratification requires human approval unless review_decision is APPROVED.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/x-entity-types.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/check-governance-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/get-plan-audit-logs-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-request.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-adjustment-response.json (added) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-request.json (modified) matches static/schemas/source/**; static/schemas/source/governance/report-plan-outcome-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/sync-plans-request.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.