[bokelley]

Implements the RFC in #8967. Refs #8501, #8230, #8246, #8537.

For the 3.3 RC (Mon 2026-11-16). static/schemas/source/** is Ladon-gated, so a human merges this.

Summary

A buyer can now choose specific installments of a product during negotiation, without adding anything to commercial_terms. It's experimental, under the new feature id media_buy.installment_refinement. The adopter is Availnet, a creator marketplace, through Apostra.

• The request side reuses the feat(media-buy): add installments to the canonical product and let a proposal buy named slots #8246 shape. installment_changes returns on media-buy/proposal-refinement.json, which fix(schemas): open the 3.3 schemas that were meant to be open #8866 opened. Each entry is { product_id, installment_ref, action }, and the entries are unique by (product_id, installment_ref). installment_ref is the closed core/canonical-installment-ref.json, and action is include or omit. It counts as a revise dimension, and finalize and extend_hold forbid it. The new files are core/installment-change.json (one entry) and core/installment-change-set.json (the list, with the uniqueness rule).
• The seller binds the choice with an ordinary product. For each named product, the selected set is its installments[] with every omit removed and every include added. A satisfying draft buys one product whose installments[] is exactly the selected set: the product itself, or one the seller offers for the selection in its place, such as creator_juniper_vale__2026-12-03. Under today's rule, buying a product buys its complete installment set, so terms_digest binds the choice through the product_id.
• Shortfalls are reported. unsatisfied_installment_changes on the refine_proposals result row repeats each unmet request entry and adds a required reason, on a partial or unable result with reason_code: "constraint_unsatisfiable". The partial invariant covers it: every draft satisfies every entry the list leaves out.
• A capability gates it. installment_changes joins media_buy.proposal_refinement.supported_dimensions. The capabilities schema requires media_buy.installment_refinement in experimental_features whenever a seller lists that dimension. Buyers send installment_changes only to such a seller, and any other seller rejects the omitted dimension with UNSUPPORTED_FEATURE under the existing supported_dimensions rule. media_buy.installment_selection isn't reused, because that id meant the signed field.

Normative rules

These are in the schema descriptions, in refine_proposals.mdx "Choose installments (experimental)" and in collections-and-installments.mdx "Choosing installments (experimental)".

• Fixed sets. A seller MUST NOT change the installments of a product it has offered; a different set is a different product_id. The digest binds the product_id, not the slots, so this rule keeps an accepted selection fixed.
• Buyer check. Before finalizing, the buyer compares each selected set with the returned product's installments[] and rejects a mismatch. After finalize, holds[] reads back the slots the hold covers.
• Membership first. The seller checks that each product_id is bought by the source proposal, or added by product_changes in the same request, before it resolves any reference, as feat(media-buy): add installments to the canonical product and let a proposal buy named slots #8246 required. The ordered checks are feat(media-buy): add installments to the canonical product and let a proposal buy named slots #8246's:
  • UNSUPPORTED_FEATURE for an undeclared dimension;
  • INVALID_REQUEST for a duplicate or contradictory entry, or a product outside the proposal or omitted by product_changes;
  • REFERENCE_NOT_FOUND for an unresolvable reference;
  • otherwise constraint_unsatisfiable with the entry listed.

Nothing in commercial_terms. product-purchase.json still carries no installments. Every new field is x-status: experimental and x-added-in: 3.3.0. 4.0 keeps the signed design (installment_selection_required_in_4_0), and the 4.0 page and registry now say what 3.3 offers in the meantime.

For reviewers

• No link field between a derived product and its source. The buyer identifies the answering purchase by its installments[] equalling the selected set, so there's no new field on the canonical product or inside the signed terms. feat(media-buy): add installments to the canonical product and let a proposal buy named slots #8246's rule that an include names one of the product's own declared installments is widened to "an installment of a collection the product's collections name". Without that, a buyer couldn't add a slot back to a derived product that dropped it.
• Per-entry reason is free text. The result row's reason_code already says constraint_unsatisfiable. A per-entry code can be added later on the open item if adopters want one.
• Measured figures:
  • The MCP analysis pins in tests/mcp-schema-analysis.test.cjs go from 711 to 714 definition instances and from 192 to 195 unique definitions: the two new files plus canonical-installment-ref, now reached from the refine_proposals input.
  • The capabilities worst case gains 50 bytes for the new enum value. On main after feat(schema): add media_buy.supported_delivery_types to capabilities #8458 (99,101,090) it measures 99,101,140, which is pinned in the test and in security.mdx.
  • The compact-discovery tools/list budget (162 KiB) and the projection bounds hold unchanged.
• Out of scope:
  • Training agent and storyboards. Its TYPED_DIMENSIONS doesn't list installment_changes, so it never advertises the dimension, and no storyboard sends it.
  • The 3.3 release pages. docs(reference): bring the 3.3 release docs to 3.3.0-rc.0 #8883 owns those.
• Coordination with RFC: Assign a creative to specific installments of a package #8968 (installment creative assignment): there's no selected-subset field, because the purchased product's installments[] is the selection. The only shared file is collections-and-installments.mdx, where the two PRs edit adjacent sections.

Testing

Rebased onto main 38a83d1d44 (after #8793 and #8458) as 6657af7001, with the worst case re-measured at 99,101,140 / 190 open positions. On the rebased tree these pass: lint:additive-minor, capabilities-structural-bounds, mcp-schema-analysis (714/195), test:mcp-schema-projection, product-discovery-schema-parity, the installment, withdrawn and canonical-installments tests, build:compliance -- --check, the hook guards, typecheck and the image check.

The full run below was on main a2a7d20fff plus this commit, run sequentially:

• npm run build:schemas: pass.
• npm run test:schemas: 1197/1197, plus premium-display 10/10 and geo-region 6/6. The new tests/installment-refinement.test.cjs has 9 tests:
  • Request: installment_changes alone is a valid revise, including a swap. Rejected are a missing action, action: "swap", an extra member inside the closed installment_ref, an empty list, an exact duplicate, and installment_changes on finalize or extend_hold. The change set declares unique_by.
  • Result row: a partial result whose only unsatisfied list is unsatisfied_installment_changes satisfies constraint_unsatisfiable. An entry without reason is rejected, and so is the list on a revised or finalized result.
  • Capabilities: the installment_changes dimension without media_buy.installment_refinement is rejected, and with it, accepted.
  • Metadata: every new node is experimental and 3.3.0.
  • Signed terms: product-purchase.json has no installments, and only the refinement id has an experimental-status row.
• Updated tests:
  • withdrawn-to-4-0.test.cjs keeps the signed purchases[].installments withdrawn and its 4.0 check, and stops asserting that the request-side pieces are absent.
  • canonical-installments.test.cjs now checks that media_buy.installment_selection has no registry row, and allows the new row's prose to name it.
• npm run test:mcp-schema-projection (pins re-measured as above), npm run test:examples and npm run test:contracts 506/506 pass. capabilities-structural-bounds passes, and product-discovery-schema-parity passes 4/4.
• These pass: npm run lint:additive-minor (2 recorded, 0 new), test:additive-minor, the 4.0 registry lint and test, audit-oneof --check, and build:compliance -- --check (1889 references, after regenerating the links for the new refine_proposals section). JSON-schema validation of the 7 changed docs pages and the changeset scope check pass too.
• Pre-push: version sync, changeset policy and docs validation pass. The local storyboard matrix was skipped with ADCP_SKIP_STORYBOARD_MATRIX=1 for host load, as the playbook allows; this PR's only compliance-path change is registry text in v4-compatibility.yaml. CI's training-agent-storyboards is the gate.

Local hook

Committed with HUSKY=0 under the release coordinator's standing approval for #8501-line PRs that touch no server file. The hook's server-unit stage times out at this host's load, so it was skipped. CI is the gate. I ran the other hook steps by hand:

• The dynamic-import, format-identity and callApi guards, npm run typecheck and the image check pass.
• npm run test:unit passed 1281/1284. The 3 misses were 10s load timeouts in addie/compliance-validate-input-gates and billing/stripe-client, which this PR doesn't touch, and those files pass 69/69 on their own.

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated paths touched without required approval.

This PR modifies the published protocol surface under static/schemas/source/** (7 gated files: installment-change-set.json, installment-change.json, proposal-refinement-reason.json, index.json, proposal-refinement.json, refine-proposals-response.json, get-adcp-capabilities-response.json). Those paths are under a hard, deterministic approval gate (gated_paths: true), and review_decision is REVIEW_REQUIRED — not APPROVED. Per decision-table row 2, a gated-path PR cannot auto-approve until a human/CODEOWNERS approval lands.

Escalation reasons

• Gated schema source files changed; human/CODEOWNERS review required before merge. Files: static/schemas/source/core/installment-change-set.json, static/schemas/source/core/installment-change.json, static/schemas/source/enums/proposal-refinement-reason.json, static/schemas/source/index.json, static/schemas/source/media-buy/proposal-refinement.json, static/schemas/source/media-buy/refine-proposals-response.json, static/schemas/source/protocol/get-adcp-capabilities-response.json.

The reviewer found no Critical/High/Medium findings: the change is additive (new feature id media_buy.installment_refinement), every new node is x-status: experimental / x-added-in: 3.3.0, carries a correct minor changeset, preserves schema↔docs coherence across all 7 doc pages, introduces no undiscriminated oneOf, breaks no released-artifact immutability, and leaves signed terms untouched. It is not breaking-class. Once a human approval satisfies the gate, this falls through to approve on the clean diff.

`

Why human review

• Gated paths touched (static/schemas/source/**) and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS approval required before merge. Files: installment-change-set.json, installment-change.json, proposal-refinement-reason.json, index.json, proposal-refinement.json, refine-proposals-response.json, get-adcp-capabilities-response.json.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/installment-change-set.json (added) matches static/schemas/source/**; static/schemas/source/core/installment-change.json (added) matches static/schemas/source/**; static/schemas/source/enums/proposal-refinement-reason.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/proposal-refinement.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/refine-proposals-response.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.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 schema paths require human/CODEOWNERS approval, and this PR introduces a new experimental protocol surface.

No blocking findings. Reviewer reports a clean pass: schema↔docs coherence verified across refine_proposals.mdx, collections-and-installments.mdx, experimental-status.mdx, v4-compatibility.mdx, and the capabilities doc; the minor changeset is protocol-scoped and correct (additive experimental fields); the response-shape not.anyOf/then.anyOf forbidding extensions match the new contract test; no new undiscriminated oneOf; withdrawn media_buy.installment_selection stays withdrawn. No Critical/High/Medium findings.

Why escalate (not approve): This PR touches files under the hard, deterministic approval gate (static/schemas/source/**) and review_decision is REVIEW_REQUIRED, not APPROVED. Decision-table row 2 forces escalate until a human/CODEOWNERS approval is recorded — a clean diff cannot lift this gate. Additionally, re-introducing the experimental media_buy.installment_refinement protocol surface is a governance/ratification matter that is a human act, reinforcing escalation.

Escalation reasons:

• Gated paths touched (static/schemas/source/**) with review_decision: REVIEW_REQUIRED — human/CODEOWNERS approval required before merge. Files: installment-change-set.json, installment-change.json, proposal-refinement-reason.json, index.json, proposal-refinement.json, refine-proposals-response.json, get-adcp-capabilities-response.json.
• New experimental protocol surface (installment_refinement) added — ratification is a human act.

This continues the prior escalate decision: the gate condition still holds (review_decision unchanged), so the escalation stands pending human sign-off. No code changes are requested.

Why human review

• Gated paths touched (static/schemas/source/**) and review_decision is REVIEW_REQUIRED, not APPROVED — human/CODEOWNERS approval required before merge. Files: installment-change-set.json, installment-change.json, proposal-refinement-reason.json, index.json, proposal-refinement.json, refine-proposals-response.json, get-adcp-capabilities-response.json.
• Re-introduces the experimental media_buy.installment_refinement protocol surface — ratification of a new protocol addition is a human act, not auto-approvable.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/installment-change-set.json (added) matches static/schemas/source/**; static/schemas/source/core/installment-change.json (added) matches static/schemas/source/**; static/schemas/source/enums/proposal-refinement-reason.json (modified) matches static/schemas/source/**; static/schemas/source/index.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/proposal-refinement.json (modified) matches static/schemas/source/**; static/schemas/source/media-buy/refine-proposals-response.json (modified) matches static/schemas/source/**; static/schemas/source/protocol/get-adcp-capabilities-response.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.