From 2b4908b2ad6dc53229f6a5600b364cb18a291c12 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 19 Oct 2026 11:24:45 +0000 Subject: [PATCH 1/5] docs(protocol): propose seller-wide product-feature commitments --- .../optional-product-feature-declarations.yml | 30 ++ .../optional-product-feature-declarations.md | 362 ++++++++++++++++++ .../controller.schema.json | 27 ++ .../examples.json | 28 ++ .../features.schema.json | 13 + .../model.cjs | 104 +++++ .../probes.test.cjs | 272 +++++++++++++ .../review.md | 81 ++++ 8 files changed, 917 insertions(+) create mode 100644 .github/workflows/optional-product-feature-declarations.yml create mode 100644 specs/optional-product-feature-declarations.md create mode 100644 specs/optional-product-feature-declarations/controller.schema.json create mode 100644 specs/optional-product-feature-declarations/examples.json create mode 100644 specs/optional-product-feature-declarations/features.schema.json create mode 100644 specs/optional-product-feature-declarations/model.cjs create mode 100644 specs/optional-product-feature-declarations/probes.test.cjs create mode 100644 specs/optional-product-feature-declarations/review.md diff --git a/.github/workflows/optional-product-feature-declarations.yml b/.github/workflows/optional-product-feature-declarations.yml new file mode 100644 index 00000000000..514aadc17c0 --- /dev/null +++ b/.github/workflows/optional-product-feature-declarations.yml @@ -0,0 +1,30 @@ +name: Optional product feature declaration proposal evidence + +on: + pull_request: + paths: + - 'specs/optional-product-feature-declarations.md' + - 'specs/optional-product-feature-declarations/**' + - '.github/workflows/optional-product-feature-declarations.yml' + - 'static/schemas/source/**' + - 'package.json' + - 'package-lock.json' + +permissions: + contents: read + +jobs: + contract-probes: + name: Product feature commitment proposal probes + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 + with: + node-version: '24' + cache: npm + - run: npm ci + env: + PUPPETEER_SKIP_DOWNLOAD: 'true' + - run: node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs diff --git a/specs/optional-product-feature-declarations.md b/specs/optional-product-feature-declarations.md new file mode 100644 index 00000000000..ffd0667c6ed --- /dev/null +++ b/specs/optional-product-feature-declarations.md @@ -0,0 +1,362 @@ +--- +title: Seller-wide optional product-feature commitments +class: normative +status: proposed +date: 2026-10-19 +refs: ["#8254", "PR #8259", "PR #7982", "PR #7973", "DR-0001", "DR-0009", "DR-0010"] +dissent: Pending independent review; human/WG decision outstanding +--- + +## Decision + +**Nonoperative future-minor proposal.** Approving investigation or opening this +PR does not ratify these clauses. This memo uses the decision-record format; +a DR number and decision provenance are assigned only through human review. +No production schema, storyboard, hosted disposition, or released artifact is +changed. The isolated schemas and executable model below are proposal evidence. + +Recommend five optional booleans under `media_buy.features`, with no defaults: + +| Field | Commitment and qualifying product | Independent consumers | +| --- | --- | --- | +| `supports_collection_selection` | At least one product with nonempty explicit `collections`, `collection_targeting_allowed: true`, and at least two distinct collection identities so proper-subset selection can be tested. | Direct structured selection, default full-bundle materialization, persisted readback, invalid-selector rejection. | +| `supports_fixed_collection_bundles` | At least one multi-collection product with `collection_targeting_allowed` false or omitted (existing default false). | Exact full-bundle restatement, default materialization, proper-subset rejection. | +| `supports_owner_sold_channel_carriage` | At least one channel-owner offer referencing that owner's canonical channel collection and a different host publisher's property. | Owner/host selector boundary checks; buyer-side host authorization verification remains separate. | +| `supports_format_breakdown` | At least one product with `reporting_capabilities.supports_format_breakdown: true`. | Requested `format` dimension, `by_format`, truncation and applied-sort echoes; no required observations. | +| `supports_time_based_views` | At least one product listing `time_based_views` in `reporting_capabilities.available_metrics`. | Metric availability and narrowing, schema-valid threshold entries when observed, committed-array presence when contracted. | + +These are existential seller support commitments, never assertions about every +product. Selection/default belong together because the existing targeting +contract already requires concrete default readback on a selectable product; +there is no meaningful conformant "selects but cannot materialize default" +path to declare independently. Fixed products have their own default path and +must not depend on a selectable companion. Owner-sold offers can be fixed or +selectable: declaring owner-sold does not imply either of the other flags. +The owner-sold fixture uses the product's actual fixed/selectable behavior. +Format and time declarations are unrelated to each other or to creative-grain +reporting. Baseline requested-metric narrowing stays independently graded. + +The shared `media-buy-features.json` also types `get_products` +`filters.required_features`. Using these flags there selects **sellers**, as +existing property rollups do; it never filters to qualifying products, provisions +a fixture, or implies every returned product supports the feature. Buyers still +inspect product declarations. No new filter mechanism is proposed. + +The direct `collection_selection` path is distinct from hosted `collection_list` +and exclusion-list support. Their existing declarations continue to govern them; +these flags do not imply list-service, collection-card, placement-selection, +property-reporting, installment-reporting, or any new delivery-mode support. + +## Rationale + +Catalog-only applicability cannot certify support reachable only after sandbox +setup or through a brief. Generic `seed_product` accepting authored feature fields +does not establish native support. This proposal adds a clear support promise +and a separately specified setup commitment, rather than using seed refusal as +an unsupported-feature negotiation mechanism. + +Controlling authority: + +- [DR-0001](../governance/decisions/DR-0001-conformance-assertions-normative-basis.md): grade only normative/schema obligations. This memo is not yet such authority. +- [DR-0009](../governance/decisions/DR-0009-additional-properties-default-true.md): preserve existing object boundaries; validate known fields strictly. + `media-buy-features.json` specifically allows unknown **boolean** flags; do not + widen this to arbitrary objects. +- [DR-0010](../governance/decisions/DR-0010-fixture-handles-and-resolution.md): real seller identities, explicit strategies, pinned bindings, terminal supported-operation failures, visible exhausted-strategy gaps. +- [Product](../static/schemas/source/core/product.json), [targeting](../static/schemas/source/core/targeting.json), [collection selection](../static/schemas/source/core/collection-selection.json), [reporting capabilities](../static/schemas/source/core/reporting-capabilities.json) remain the product authority. +- [Delivery request](../static/schemas/source/media-buy/get-media-buy-delivery-request.json), [delivery metrics](../static/schemas/source/core/delivery-metrics.json), and [controller](../docs/building/by-layer/L3/comply-test-controller.mdx) bound what reporting evidence can prove. + +### Main, release, and adjacent-work inventory + +Verified on 2026-10-19 against main `c2f01a50f2133b016fc73ca74019c4c021f2256e`: +root package `3.2.1` is release machinery metadata, SDK pin **15.9.5**, +`.changeset/pre.json` is beta mode, stable latest is **v3.2.5**, and both +`changeset-release/main` (#7897) and `changeset-release/3.2.x` (#8274) are open. +The playbook says main is the future 3.3 line after GA; do not derive a release +number from root package metadata. The actual minor/train for this proposal is +**unassigned**, subject to WG and release-owner scheduling. No 3.2.x backport. + +| Work | Verified disposition and relationship | +| --- | --- | +| [#8254](https://github.com/adcontextprotocol/adcp/issues/8254), [#8259](https://github.com/adcontextprotocol/adcp/pull/8259) | Open; full proposal and discussion read. Catalog owner retains three existing YAMLs, independent fixed/time YAMLs, media-buy index, compliance docs/tests, patch changeset and proposal reconciliation. Owner coordination confirmed before edits. Catalog implementation lands main first; maintenance qualification stays separate. | +| [#7982](https://github.com/adcontextprotocol/adcp/pull/7982) | Merged 2026-10-07. Reuse `media_buy.features`, independent matching product flags, and empty-array/companion discipline. Its absent/false mean "no rollup claim," not "no products"; keep that compatibility. Do not copy rollup-only gating, which hides undeclared catalog evidence, or its specific property-row injection/suppression exemption into format/time support. | +| [#7973](https://github.com/adcontextprotocol/adcp/pull/7973) | Open draft held for 3.4. Delivery modes are a different axis. Do not import its parent-object/schema-default dependence, compound fail-closed gates, coverage removal from required specialisms, or low-coverage baseline substitution. No files shared. | +| [#7134](https://github.com/adcontextprotocol/adcp/pull/7134), [#8201](https://github.com/adcontextprotocol/adcp/issues/8201) | Collection storyboards and fixture-resolution prior art. Current source and shipping SDK inspected; no changes to their shared contracts here. SDK currently accepts only seed/discover resolution strategies, despite source discussion of construct. | +| [#7958](https://github.com/adcontextprotocol/adcp/pull/7958), [#8061](https://github.com/adcontextprotocol/adcp/pull/8061), [#8246](https://github.com/adcontextprotocol/adcp/pull/8246) | Open composable-breakdown, collection-list and installment-product proposals. Preserve current product vocabulary; recheck before any later source promotion. | +| [#8117](https://github.com/adcontextprotocol/adcp/pull/8117), [#8156](https://github.com/adcontextprotocol/adcp/pull/8156), [#7934](https://github.com/adcontextprotocol/adcp/pull/7934) | Open negotiated-response-version, undefined-property reporting and per-account readiness work. Do not presume their proposed rules are operative or infer entitlement from this technical support declaration. | + +All listed open adjacent proposals are authored by @bokelley. The scoped catalog +owner and root coordinator were contacted directly in their existing sessions; +this PR touches only its own proposal namespace and scoped evidence workflow. +Any later source overlap requires renewed file coordination with those owners. + +## Proposed normative language + +The following MUST/SHOULD text is conditional on adoption in an assigned minor. + +1. A seller MAY emit any subset of the five fields. Every emitted known value + MUST be a boolean. Omitted fields, including an omitted `features` or + `media_buy` parent, mean **no seller-wide claim / unknown**, not unsupported. + `false` explicitly declines the seller-wide commitment; it does not deny + individual supporting products. `true` declares native technical support + and the sandbox fixture commitment below. Unknown future boolean keys MUST NOT be + interpreted as a known feature; existing feature-object compatibility is preserved. +2. A true declaration MUST be backed by at least one qualifying, bookable + sandbox offer through the seller's normal execution path. Initially empty, + nonqualifying wholesale, seeded-only and brief-only catalogs are permitted. + A seller MUST implement `prepare_product_feature` for every true feature, + advertise that scenario through `list_scenarios` when supported, and supply + a valid qualifying fixture on request. A fixture-only echo path that accepts + unsupported authored fields does not satisfy native execution support. +3. Each product remains authoritative for its own feature support. A seller + MUST honor every product-level declaration on a selected product regardless + of an absent or false seller-wide field. A supporting product alongside a + false rollup is not a contradiction. A true rollup alongside ordinary, + non-supporting products is also not a contradiction. A declaration is + contradicted when its promised setup cannot supply a qualifying fixture, + or selected qualifying behavior violates its existing product contract. +4. A runner MUST preserve catalog-based testing for absent/false declarations. + It MUST NOT replace that route with an equals-true gate over the whole + storyboard or infer schema defaults through missing parents. A true + declaration selects commitment testing even when initial catalog evidence + is empty. Catalog discovery is attempted only when wholesale is actually + supported; brief-only support cannot be wholesale-gated away. +5. Setup and behavior evidence MUST be reported separately. Harness inability + to dispatch a negotiated operation is an explicit untested/setup gap. A + promised operation advertised by the seller that refuses, malforms, returns + `UNKNOWN_SCENARIO`/`INVALID_PARAMS` on valid input, or supplies a nonqualifying + fixture is a producer commitment violation. It MUST NOT become + `not_applicable`, a pass, or fallback success. Missing promised operation + confirmed from the seller's tool/scenario surface is a commitment violation; + failure to inspect that surface is a harness gap. Harness errors and + malformed runner input MUST NOT be blamed on the producer. +6. No field conveys account authorization, commercial access, availability for + a particular buyer, or entitlement. Existing auth/account checks remain in + force. Fixtures use a prearranged, authorized, **feature-eligible** sandbox account; + a runner lacking one records that precondition gap. Establish eligibility + through ordinary account onboarding/operator setup evidence, not these + flags. A documented access denial before those preconditions hold is a + precondition gap; once they hold, setup refusal violates the promise. A bare + `INVALID_PARAMS` or post-failure assertion of ineligibility cannot alone + establish that gap or cancel the commitment. Metadata contains no credentials, tokens, + endpoint overrides, or entitlement assertions. Seller-provided terms, + account eligibility and selected pricing govern the fixture buy. + +### Applicability and fixture state table + +Evaluate each feature independently; never require a companion feature product. +Catalog availability below means a valid, fully paginated wholesale scan is +possible. A transport/protocol/schema/pagination failure after a supported scan +starts is terminal under DR-0010, not a no-match or a setup fallback. + +| Declaration | Catalog / precondition | Required next action | Outcome / evidence | +| --- | --- | --- | --- | +| absent, false, unknown key, or old seller | Qualifying catalog product | Pin real product and execute feature | Product obligations graded; seller-wide promise not inferred. | +| absent or false | Valid catalog, no qualifying product | No generic feature seed | `fixture_unsatisfied` coverage gap; N/A projection is no proof of nonsupport. | +| absent or false | Brief-only, no defined construction route | Do not invent wholesale or construct | Explicit discovery-precondition gap; unknown support. | +| true | Qualifying catalog product | Verify promised setup operation exists; pin and exercise product | Product feature graded; preparation explicitly untested until its separate commitment probe runs. | +| true | Empty/nonqualifying catalog or brief-only | Call negotiated feature setup, pin returned product | Grade normal purchase/readback/reporting independent of wholesale. | +| true | Setup operation absent, or valid advertised setup refused | Preserve failed response and commitment result | Producer violation, never N/A or fallback. | +| true | Setup succeeds with malformed/nonqualifying product | Stop before purchase | Producer violation with exact schema/qualification evidence. | +| true or selected product | Broken selected behavior | Retain validation/protocol failure | Producer behavior violation; no fallback or applicability reclassification. | +| any | Runner lacks new setup contract/schema, feature-eligible sandbox access, or required harness tool | Record missing precondition | Harness/setup gap, no compliance pass or producer accusation. | +| malformed known declaration | e.g. string `"true"`, null, array | Fail capability validation for known field | Invalid producer declaration; never coerce or ignore as false. | + +The reference model returns local evidence labels (`commitment_violation`, +`harness_gap`, `coverage_gap`, `behavior_violation`, `applicable`). These are +**not new wire errors or shipping runner-output enums**. Current hosted +[step disposition](../server/src/compliance/step-disposition.ts) maps synthetic +controller setup failures to `setup_gap` and unsupported seeds to N/A. Adoption +requires a separate assertion of the declaration obligation, with the failed +setup evidence attached. Global grading guards and baseline floors stay intact. +A missing runner contract or confirmed missing preparation operation cannot +silently remove existing product tests. Catalog behavior evidence and commitment +evidence are separate axes: a passing catalog path with preparation untested +MUST NOT certify the seller-wide commitment. Before certifying a true flag, a +runner MUST also execute valid preparation and exercise its returned fixture, +even when another product already qualified through catalog discovery. + +## Additional controller contract requiring a WG decision + +Current `seed_product` accepts permissive authored exemplars; `list_scenarios` +only identifies operation names. Neither negotiates native feature support or +returns a feature-qualified seller-owned offer. `simulate_delivery` supports +property-row injection but does not inject observed format rows or time-view +measurements. The shipping resolver accepts only seed/discover, so `construct` +is not an executable escape hatch here. + +Propose one additional sandbox scenario, **`prepare_product_feature`**, within +`comply_test_controller`, using its existing account and success/error envelope: + +- Params: `feature` (one of the five scope identifiers below) and `fixture_id` + (nonempty run-scoped idempotency key, maximum 128 characters). No authored + product fields, selector strings, observed metrics, or credentials. +- Success: `success: true`, `simulated: {feature, fixture_id, product}`. `product` + MUST validate against current `core/product.json`, qualify for the requested + feature, and carry seller-issued identities and a usable pricing option. + The response does not supply trusted authorization attestations. Owner-sold + qualification also requires independent owner channel/host evidence from + canonical discovery/fixtures; the product alone cannot prove channel kind or + host authorization. +- Setup establishes an offer in the seller's real sandbox adapter path, with + disclosed product terms and sufficient test inventory. It may expose it only + through a brief; the returned full product is the binding input and purchases + use its seller-issued IDs. Wholesale listing is not newly required. Re-read + through the normal buyer lifecycle; do not grade only the controller echo. +- `fixture_id` is scoped by authenticated principal and sandbox account; the + feature is immutable request content, not part of the key namespace. + An exact retry returns the same offer and terms during the run; reusing a key + for a different feature is `INVALID_PARAMS` with no mutation. Runners MUST + generate fresh, run-unique fixture IDs. Isolation is enforced across principals + and accounts; reusing the same key in the same principal/account namespace is + a retry, not a separately isolated run. Setup validates before mutation. Cleanup follows + normal sandbox TTL/ownership rules, never a production reset. +- False/absent commitments do not require this scenario. Unknown scenario names + retain `UNKNOWN_SCENARIO`. A known scenario with unknown feature or malformed + params returns `INVALID_PARAMS`; that code still means invalid input or unmet + precondition, never "feature unsupported." A true feature's valid setup refusal + is evidence of a violated promise, not a new interpretation of the error. + An uncommitted feature is not probed through this operation. +- Scope identifiers: `collection_selection`, `fixed_collection_bundles`, + `owner_sold_channel_carriage`, `format_breakdown`, `time_based_views`. + +The isolated [declaration schema](optional-product-feature-declarations/features.schema.json) +is the proposed additive `core/media-buy-features.json` properties fragment. +It is merged into the existing properties for evidence validation, preserving +existing structured features and the unknown-boolean constraint. +The [controller schema](optional-product-feature-declarations/controller.schema.json) +defines the proposed params and `simulated` payload, referencing the real product +schema. It is not installed into the published controller schema. A runner must +explicitly advertise/enable a future `product_feature_commitments_v1` harness +contract before using this route; its eventual runner-output representation and +SDK implementation are still required. This name is a proposal, not a working +SDK contract. There is no storyboards-schema edit in this PR. + +### Reporting limits + +A declaration and prepared product establish technical support and a valid +execution fixture, not observed reporting grains. Format checks require the +requested supported array (possibly empty), truncation disclosure and actual +applied-sort echoes. Never require a video format, first-row identity, positive +row count, or `truncated: true` from generic delivery simulation. Sorting remains +before requested-metric narrowing; existing fallback rules apply. + +Time-view thresholds may be any positive seller-defined number; two/six seconds +are recommendations. A valid three-second `in_view` entry is acceptable. Check +unique `(threshold_seconds, basis)` pairs when entries exist and do not sum +bases. `available_metrics` alone does not guarantee every uncommitted metric +is measurable on every report. Missing values follow existing omission and +`missing_metrics` rules. Contracting `time_based_views` binds array presence, +including an empty observed array; it does not bind particular thresholds. +The two reporting probes below exercise these limits without injecting grains. + +If the WG wants deterministic nonempty observations, it needs a **separate** +controller amendment specifying package attribution, accepted format/threshold +rows, replace/add semantics, dates, reconciliation, suppression, idempotency, +validation and request-narrowing behavior. This PR neither chooses nor requires +that amendment; #7982's property-specific injection is not such a contract. + +## Compatibility, migration and implementation plan + +Major-version negotiation remains unchanged: `adcp_major_version` chooses a +major; feature checks determine minor additions. Do not invent a minor request +pin, use deployment version strings as capability gates, or treat #8117 as law. +A new client with an old seller keeps catalog testing when these fields are +absent. An old client validates new fields through open objects and ignores +unknown keys. An old runner cannot certify the new commitment; it keeps its +existing catalog coverage and must not issue unknown setup calls. A seller on +an older release is not required to emit these fields or add a `media_buy` +parent. Unknown future capability keys are not proof of this contract. +After adoption, emitting a standardized field as `true` is the explicit producer +opt-in, regardless of self-reported implementation minor. There is no hidden +handshake or second version marker. Historical snapshots from before adoption +are not retroactively certified; older implementations with a colliding custom +boolean name must remove it or adopt this contract before opting in. An old +schema accepting that boolean is not itself semantic certification. + +1. Keep the separately owned catalog fix and any qualified 3.2.x backport moving. + Retain its independent feature graphs, seller-derived selectors/pricing, + omitted-false bundle handling and current reporting guarantees. +2. Ratify exact fields, existential semantics and setup commitment. Assign a + future minor after the release owner confirms the train; do not copy #7973's + 3.4 hold as a release assignment for this design. New stable optional fields + plus new opt-in MUSTs are Normative/minor, not patch errata. Sellers making + no claim keep their existing contracts. +3. In a coordinated implementation PR add five properties to + `static/schemas/source/core/media-buy-features.json`, document the clauses in + `docs/protocol/get_adcp_capabilities.mdx`, add the controller scenario/params + and docs, implement native fixture preparation in the reference seller, and + qualify schema/MCP projection without changing dependency pins or limits. + Use a real descriptive `.changeset/optional-product-feature-commitments.md`: + + ```yaml + --- + "adcontextprotocol": minor + --- + Add optional seller-wide product-feature commitments and sandbox feature-qualified fixture preparation. Preserve catalog-based coverage for undeclared sellers. + ``` + + That changeset is intentionally **not active in this proposal-only PR**; + policy forbids versioning a nonoperative spec experiment as shipped protocol. +4. Add the runner setup/evidence contract in its owning SDK, qualify the actual + pinned SDK and real source storyboards, and integrate a declaration assertion + that cannot be hidden by controller prerequisites. Coordinate shared files + with #8254 before promotion. Do not create equals-true or compound gates that + exclude undeclared sellers or remove required-specialism coverage. +5. During rollout, use catalog evidence for absent/false and commitment setup + for true/no-catalog. Deduplicate execution when both routes select the same + feature/product. Test unrelated product declarations even when the rollup + declines a claim. Display harness gaps, violations and catalog limitations + separately. After SDK qualification, sellers opt in per independent feature; + registries/buyers gain pre-discovery routing hints but still inspect products. +6. Run source schema/docs parity, controller unit/integration and MCP projection + checks, source-storyboard contract tests, hosted disposition tests, normal + matrix and required CI on the exact implementation head. Do not change + global guards/floors, immutable records, maintenance branches or release + automation. Human/WG/path review remains mandatory; no automatic merge. + +Existing sellers pay no mandatory migration cost. Opted-in sellers implement +one preparation scenario with a branch per true feature plus normal product +execution. Buyers may ignore the flags; certifiers and SDK owners pay the +routing/evidence cost. The setup obligation is deliberately stronger than a +passive rollup and makes empty-catalog support testable. A remote assertion +cannot prove how a producer implemented its adapter; lifecycle probes catch +wire-visible divergence, while native-support honesty remains an attestation. + +## Executable evidence and review boundary + +Run from the repository root: + +```bash +node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs +``` + +[Probes](optional-product-feature-declarations/probes.test.cjs) combine an +isolated proposed commitment state machine with real source-schema validation +and separate SDK 15.9.5 runner and old-controller behavior checks. The model uses injected in-memory +sellers. It is **not** an implemented SDK feature, actual repaired storyboard, +hosted certification run, production adapter test or 3.2.x qualification. +Tests cover declarations, mixed feature subsets, valid catalog and empty/brief +setup, honest harness gaps versus refusal/invalid setup, selected-path failures, +old clients/servers, schema openness, reporting emptiness and threshold freedom. +The SDK probes pin present gate/default and unsupported-setup hazards rather +than claiming the proposed routing already exists. Exact review findings and +commands are recorded in [review evidence](optional-product-feature-declarations/review.md). + +## Unresolved normative choices for human/WG review + +1. Adopt the five field names and grouping, including default materialization + within selectable/fixed paths and owner-sold independent of selectability? +2. Adopt existential native support **plus** mandatory feature-qualified sandbox + preparation for true declarations, or split technical-support rollups from + an independently advertised fixture commitment? Recommendation: one explicit + opt-in commitment per feature as specified; passive rollups leave the original + seeded-only certification gap unresolved. +3. Adopt the exact `prepare_product_feature` params/result, retry scope and + violation treatment? Its native-offer promise and new runner assertion require + WG approval and SDK implementation; existing error semantics stay intact. +4. Keep reporting observations optional under current guarantees, or commission + a separate deterministic grain-injection design? Recommendation: keep current + guarantees; injection must not block this commitment design. +5. Confirm release scheduling, evidence representation and the point at which + opting in becomes certifiable after real SDK/source-storyboard qualification. + No agent review substitutes for WG ratification, human/path approval or CI. diff --git a/specs/optional-product-feature-declarations/controller.schema.json b/specs/optional-product-feature-declarations/controller.schema.json new file mode 100644 index 00000000000..959f58a03a8 --- /dev/null +++ b/specs/optional-product-feature-declarations/controller.schema.json @@ -0,0 +1,27 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "PROPOSED prepare_product_feature payload fragments; not published", + "definitions": { + "feature": { "type": "string", "enum": ["collection_selection", "fixed_collection_bundles", "owner_sold_channel_carriage", "format_breakdown", "time_based_views"] }, + "fixture_id": { "type": "string", "minLength": 1, "maxLength": 128, "x-entity": "product_feature_fixture" }, + "params": { + "type": "object", + "properties": { + "feature": { "$ref": "#/definitions/feature" }, + "fixture_id": { "$ref": "#/definitions/fixture_id" } + }, + "required": ["feature", "fixture_id"], + "additionalProperties": true + }, + "simulated": { + "type": "object", + "properties": { + "feature": { "$ref": "#/definitions/feature" }, + "fixture_id": { "$ref": "#/definitions/fixture_id" }, + "product": { "$ref": "/schemas/core/product.json" } + }, + "required": ["feature", "fixture_id", "product"], + "additionalProperties": true + } + } +} diff --git a/specs/optional-product-feature-declarations/examples.json b/specs/optional-product-feature-declarations/examples.json new file mode 100644 index 00000000000..11de042a8d1 --- /dev/null +++ b/specs/optional-product-feature-declarations/examples.json @@ -0,0 +1,28 @@ +{ + "note": "Isolated proposal vectors; fields are not published or certified. Collection readbacks below are semantic fragments, not complete task envelopes.", + "declarations": { + "supports_collection_selection": true, + "supports_fixed_collection_bundles": false, + "supports_owner_sold_channel_carriage": true, + "supports_format_breakdown": false, + "supports_time_based_views": true + }, + "prepare_params": { "feature": "collection_selection", "fixture_id": "run-example-selectable" }, + "collection_vectors": [ + { "name": "selected subset", "selectable": true, "request": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news"] }] }, "readback": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news"] }] } }, + { "name": "materialized default", "selectable": true, "request": { "mode": "default" }, "readback": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news", "music"] }] } }, + { "name": "fixed default", "selectable": false, "request": { "mode": "default" }, "readback": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news", "music"] }] } }, + { "name": "fixed exact restatement", "selectable": false, "request": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["music", "news"] }] }, "readback": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news", "music"] }] } }, + { "name": "fixed subset rejected", "selectable": false, "request": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news"] }] }, "error": "UNSUPPORTED_FEATURE" }, + { "name": "unknown owner rejected", "selectable": true, "request": { "mode": "selected", "collections": [{ "publisher_domain": "other.example", "collection_ids": ["news"] }] }, "error": "REFERENCE_NOT_FOUND" }, + { "name": "missing concrete ids", "selectable": true, "request": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example" }] }, "error": "INVALID_REQUEST" } + ], + "empty_format_package": { + "package_id": "sandbox-package", "impressions": 0, "spend": 0, "pricing_model": "cpm", "rate": 10, "currency": "USD", + "by_format": [], "by_format_truncated": false, "by_format_sorted_by": "spend", "by_format_sort_direction": "desc" + }, + "empty_contracted_time_metric": { "time_based_views": [] }, + "three_second_metric": { "time_based_views": [{ "threshold_seconds": 3, "basis": "in_view", "views": 4 }] }, + "narrowed_metrics": { "impressions": 10, "spend": 1 }, + "format_request": { "reporting_dimensions": { "format": { "limit": 1, "sort_by": "spend" } }, "requested_metrics": ["impressions", "spend"] } +} diff --git a/specs/optional-product-feature-declarations/features.schema.json b/specs/optional-product-feature-declarations/features.schema.json new file mode 100644 index 00000000000..11ce08a5148 --- /dev/null +++ b/specs/optional-product-feature-declarations/features.schema.json @@ -0,0 +1,13 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "PROPOSED additions to media_buy.features; not published", + "type": "object", + "properties": { + "supports_collection_selection": { "type": "boolean", "description": "Opt-in native selectable-collection support and qualified sandbox fixture commitment, including default materialization; not every product." }, + "supports_fixed_collection_bundles": { "type": "boolean", "description": "Opt-in native fixed-collection bundle support and qualified sandbox fixture commitment; independent of selectable products." }, + "supports_owner_sold_channel_carriage": { "type": "boolean", "description": "Opt-in native owner-sold channel carriage support and qualified sandbox fixture commitment; no entitlement or authorization assertion." }, + "supports_format_breakdown": { "type": "boolean", "description": "Opt-in native format-grain reporting support and qualified sandbox fixture commitment; no required observed rows." }, + "supports_time_based_views": { "type": "boolean", "description": "Opt-in native time-threshold view reporting support and qualified sandbox fixture commitment; no prescribed thresholds or observations." } + }, + "additionalProperties": true +} diff --git a/specs/optional-product-feature-declarations/model.cjs b/specs/optional-product-feature-declarations/model.cjs new file mode 100644 index 00000000000..ce7afba496b --- /dev/null +++ b/specs/optional-product-feature-declarations/model.cjs @@ -0,0 +1,104 @@ +// Nonoperative proposal model. No shipping runner/output contract is changed. +'use strict'; +const fs = require('node:fs'); +const path = require('node:path'); +const Ajv = require('ajv'); +const addFormats = require('ajv-formats'); +const featureSchema = require('./features.schema.json'); +const controllerSchema = require('./controller.schema.json'); +const features = Object.keys(featureSchema.properties).map(name => name.slice('supports_'.length)); + +async function validators() { + const ajv = new Ajv({ strict: false, allErrors: true, loadSchema: async uri => { + const released = 'https://adcontextprotocol.org/schemas/3.2.5/'; + if (uri.startsWith(released) && !uri.includes('..')) return JSON.parse(fs.readFileSync(path.join(__dirname, '../../dist/schemas/3.2.5', uri.slice(released.length)), 'utf8')); + if (!uri.startsWith('/schemas/') || uri.includes('..')) throw new Error(`Unrecognized source schema: ${uri}`); + return JSON.parse(fs.readFileSync(path.join(__dirname, '../../static/schemas/source', uri.slice('/schemas/'.length)), 'utf8')); + } }); + addFormats(ajv); + const product = await ajv.compileAsync({ $ref: '/schemas/core/product.json' }); + const simulated = await ajv.compileAsync({ ...controllerSchema, $ref: '#/definitions/simulated' }); + return { + declaration: await ajv.compileAsync({ + ...require('../../static/schemas/source/core/media-buy-features.json'), + $id: undefined, + properties: { ...require('../../static/schemas/source/core/media-buy-features.json').properties, ...featureSchema.properties }, + }), product, simulated, + collectionSelection: await ajv.compileAsync({ $ref: '/schemas/core/collection-selection.json' }), + deliveryMetrics: await ajv.compileAsync({ $ref: '/schemas/core/delivery-metrics.json' }), + deliveryRequest: await ajv.compileAsync({ $ref: '/schemas/media-buy/get-media-buy-delivery-request.json' }), + formatPackage: await ajv.compileAsync(require('../../static/schemas/source/media-buy/get-media-buy-delivery-response.json') + .properties.media_buy_deliveries.items.properties.by_package.items), + oldFeatures: await ajv.compileAsync(require('../../dist/schemas/3.2.5/core/media-buy-features.json')), + params: ajv.compile({ ...controllerSchema, $ref: '#/definitions/params' }), + }; +} + +function collectionCount(product) { + return new Set((product.collections ?? []).flatMap(selector => + (selector.collection_ids ?? []).map(id => `${selector.publisher_domain}\0${id}`))).size; +} + +// These predicates are proposed fixture qualification, not universal new product +// requirements. Owner channel/host evidence is separate from the product shape. +function qualifies(feature, product, ownerEvidence) { + const report = product.reporting_capabilities ?? {}; + switch (feature) { + case 'collection_selection': return collectionCount(product) >= 2 && product.collection_targeting_allowed === true; + case 'fixed_collection_bundles': return collectionCount(product) >= 2 && product.collection_targeting_allowed !== true; + case 'owner_sold_channel_carriage': return Boolean(ownerEvidence + && ownerEvidence.product_id === product.product_id + && ownerEvidence.kind === 'channel' + && ownerEvidence.owner_domain !== ownerEvidence.host_domain + && product.collections?.some(s => s.publisher_domain === ownerEvidence.owner_domain && s.collection_ids.includes(ownerEvidence.collection_id)) + && product.publisher_properties?.some(s => s.publisher_domain === ownerEvidence.host_domain)); + case 'format_breakdown': return report.supports_format_breakdown === true; + case 'time_based_views': return report.available_metrics?.includes('time_based_views') === true; + default: return false; + } +} + +// Catalog may be null when no wholesale surface exists. Exceptions after an +// attempted advertised operation are terminal; this model never falls back. +async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidence, + harness = true, sandbox = true, operation = true, prepare, exercise = async () => true, validate }) { + if (!features.includes(feature)) throw new Error('Unknown model feature'); + if (capabilities.media_buy !== undefined && (!capabilities.media_buy || typeof capabilities.media_buy !== 'object' || Array.isArray(capabilities.media_buy))) { + return { state: 'commitment_violation', reason: 'invalid_declaration' }; + } + const declarations = capabilities.media_buy?.features === undefined ? {} : capabilities.media_buy.features; + if (!validate.declaration(declarations)) return { state: 'commitment_violation', reason: 'invalid_declaration' }; + if (!sandbox) return { state: 'harness_gap', reason: 'sandbox_precondition' }; + const promised = declarations[`supports_${feature}`] === true; + if (catalog && catalog.some(p => !validate.product(p))) return { state: 'behavior_violation', reason: 'invalid_catalog' }; + let product = catalog?.filter(p => qualifies(feature, p, ownerEvidence)) + .sort((a, b) => Buffer.compare(Buffer.from(a.product_id), Buffer.from(b.product_id)))[0]; + let route = 'catalog'; + if (!product && !promised) return { state: 'coverage_gap', reason: catalog === null ? 'no_wholesale_surface' : 'fixture_unsatisfied' }; + if (!product) { + if (!harness || typeof prepare !== 'function') return { state: 'harness_gap', reason: 'missing_runner_contract' }; + if (!operation) return { state: 'commitment_violation', reason: 'missing_promised_operation' }; + route = 'prepared'; + const params = { feature, fixture_id: `proposal-${feature}` }; + let response; + try { response = await prepare(params); } + catch { return { state: 'commitment_violation', reason: 'setup_transport' }; } + if (response?.success !== true) return { state: 'commitment_violation', reason: 'setup_refused', response }; + if (!validate.simulated(response.simulated) + || response.simulated.feature !== feature || response.simulated.fixture_id !== params.fixture_id + || !qualifies(feature, response.simulated.product, ownerEvidence)) { + return { state: 'commitment_violation', reason: 'invalid_qualified_setup' }; + } + product = response.simulated.product; + } + const commitment = !promised || route === 'prepared' ? undefined + : !harness || typeof prepare !== 'function' ? 'unverified_missing_runner_contract' + : !operation ? 'violation_missing_promised_operation' : 'untested_preparation'; + try { + return await exercise(product) ? { state: 'applicable', route, product_id: product.product_id, + ...(commitment && { commitment }) } + : { state: 'behavior_violation', reason: 'selected_behavior', route, ...(commitment && { commitment }) }; + } catch { return { state: 'behavior_violation', reason: 'selected_protocol', route, ...(commitment && { commitment }) }; } +} + +module.exports = { features, validators, qualifies, evaluate }; diff --git a/specs/optional-product-feature-declarations/probes.test.cjs b/specs/optional-product-feature-declarations/probes.test.cjs new file mode 100644 index 00000000000..332eec2301a --- /dev/null +++ b/specs/optional-product-feature-declarations/probes.test.cjs @@ -0,0 +1,272 @@ +// Proposal evidence only: model decisions, real schemas, and shipping SDK hazards. +'use strict'; +const test = require('node:test'); +const assert = require('node:assert/strict'); +const Ajv = require('ajv'); +const { runStoryboard } = require('@adcp/sdk/testing'); +const { features, validators, qualifies, evaluate } = require('./model.cjs'); +let validate; +test.before(async () => { validate = await validators(); }); + +function product(feature, extra = {}) { + const value = { + product_id: 'seller-offer', name: 'Pinnacle sandbox offer', description: 'Native execution fixture, proposal evidence only.', + publisher_properties: [{ publisher_domain: 'host.example', selection_type: 'all' }], + channels: ['ctv'], delivery_type: 'non_guaranteed', + format_options: [{ format_option_id: 'native-video', format_kind: 'video_hosted', params: { duration_ms_exact: 30000 } }], + pricing_options: [{ pricing_option_id: 'native-cpm', pricing_model: 'cpm', currency: 'USD', fixed_price: 10 }], + reporting_capabilities: { available_reporting_frequencies: ['daily'], expected_delay_minutes: 0, + timezone: 'UTC', supports_webhooks: false, available_metrics: ['impressions', 'spend'], date_range_support: 'date_range' }, + }; + if (['collection_selection', 'fixed_collection_bundles', 'owner_sold_channel_carriage'].includes(feature)) { + value.collections = [{ publisher_domain: 'owner.example', collection_ids: ['news', 'music'] }]; + if (feature === 'collection_selection') value.collection_targeting_allowed = true; + } + if (feature === 'format_breakdown') value.reporting_capabilities.supports_format_breakdown = true; + if (feature === 'time_based_views') value.reporting_capabilities.available_metrics.push('time_based_views'); + return { ...value, ...extra }; +} +const ownerEvidence = { product_id: 'seller-offer', kind: 'channel', owner_domain: 'owner.example', host_domain: 'host.example', collection_id: 'news' }; +const capability = (feature, value) => ({ media_buy: { features: { [`supports_${feature}`]: value } } }); +function setup(feature, options = {}) { + const calls = []; + return { calls, args: { + feature, capabilities: capability(feature, true), validate, ownerEvidence, + prepare: async params => { calls.push(params); return { success: true, simulated: { ...params, product: product(feature) } }; }, + ...options, + } }; +} + +for (const feature of features) { + test(`${feature}: absent and false preserve supporting catalog evidence; true also selects it`, async () => { + for (const capabilities of [{}, { media_buy: {} }, { media_buy: { features: {} } }, capability(feature, false), capability(feature, true)]) { + const { args, calls } = setup(feature, { capabilities, catalog: [product(feature)] }); + let selected; + args.exercise = async p => { selected = p; return true; }; + const result = await evaluate(args); + assert.equal(result.state, 'applicable'); assert.equal(result.route, 'catalog'); + assert.equal(selected.product_id, 'seller-offer'); assert.equal(calls.length, 0); + } + }); + test(`${feature}: unsupported/undeclared no-match never seeds a feature into existence`, async () => { + for (const catalog of [[], [product()], null]) for (const capabilities of [{}, capability(feature, false)]) { + const { args, calls } = setup(feature, { catalog, capabilities }); + assert.equal((await evaluate(args)).state, 'coverage_gap'); assert.equal(calls.length, 0); + } + }); + test(`${feature}: declared empty, nonqualifying and brief-only catalogs prepare a real qualifying product`, async () => { + for (const catalog of [[], [product()], null]) { + const { args, calls } = setup(feature, { catalog }); + let executed = 0; args.exercise = async p => { assert.equal(validate.product(p), true); executed++; return true; }; + assert.deepEqual(await evaluate(args), { state: 'applicable', route: 'prepared', product_id: 'seller-offer' }); + assert.equal(calls.length, 1); assert.equal(executed, 1); assert.equal(validate.params(calls[0]), true); + } + }); + test(`${feature}: valid promised setup refusals/unknown scenario/transport remain violations`, async () => { + for (const error of ['INVALID_PARAMS', 'UNKNOWN_SCENARIO', 'INTERNAL_ERROR']) { + const { args } = setup(feature, { prepare: async () => ({ success: false, error }) }); + assert.equal((await evaluate(args)).state, 'commitment_violation'); + } + const { args } = setup(feature, { prepare: async () => { throw new Error('transport'); } }); + assert.equal((await evaluate(args)).reason, 'setup_transport'); + }); + test(`${feature}: missing runner/access is a gap; confirmed missing promised operation is a violation`, async () => { + for (const option of [{ harness: false }, { sandbox: false }]) { + const { args, calls } = setup(feature, option); + assert.equal((await evaluate(args)).state, 'harness_gap'); assert.equal(calls.length, 0); + } + const { args } = setup(feature, { operation: false }); + assert.equal((await evaluate(args)).reason, 'missing_promised_operation'); + }); + test(`${feature}: malformed, nonqualifying and mismatched setup cannot purchase or fall back`, async () => { + for (const simulated of [{}, { feature, fixture_id: `proposal-${feature}`, product: product() }, + { feature, fixture_id: 'wrong-run', product: product(feature) }, + { feature, fixture_id: `proposal-${feature}`, product: { product_id: 'broken' } }]) { + const { args } = setup(feature, { prepare: async () => ({ success: true, simulated }), exercise: async () => { assert.fail('invalid setup must not purchase'); } }); + assert.equal((await evaluate(args)).reason, 'invalid_qualified_setup'); + } + }); + test(`${feature}: broken selected behavior stays a violation after catalog or setup selection`, async () => { + for (const catalog of [[product(feature)], []]) for (const exercise of [async () => false, async () => { throw new Error('selected protocol failure'); }]) { + const { args } = setup(feature, { catalog, exercise }); + assert.equal((await evaluate(args)).state, 'behavior_violation'); + } + }); +} + +test('all 32 independent declaration combinations select only the promised empty-catalog paths', async () => { + for (let mask = 0; mask < 32; mask++) { + const declarations = Object.fromEntries(features.map((feature, i) => [`supports_${feature}`, Boolean(mask & (1 << i))])); + for (let i = 0; i < features.length; i++) { + const { args, calls } = setup(features[i], { capabilities: { media_buy: { features: declarations } } }); + const expected = Boolean(mask & (1 << i)); + assert.equal((await evaluate(args)).state, expected ? 'applicable' : 'coverage_gap'); + assert.equal(calls.length, Number(expected)); + } + } +}); +test('missing new runner contract preserves catalog execution and reports separate unverified promise', async () => { + const { args } = setup('format_breakdown', { harness: false, catalog: [product('format_breakdown')] }); + const result = await evaluate(args); + assert.equal(result.state, 'applicable'); assert.equal(result.route, 'catalog'); + assert.equal(result.commitment, 'unverified_missing_runner_contract'); +}); +test('missing promised operation preserves catalog behavior with a separate commitment violation', async () => { + const { args } = setup('format_breakdown', { operation: false, catalog: [product('format_breakdown')] }); + const result = await evaluate(args); assert.equal(result.state, 'applicable'); + assert.equal(result.commitment, 'violation_missing_promised_operation'); +}); +test('catalog behavior alone never certifies the true preparation promise', async () => { + const { args } = setup('format_breakdown', { catalog: [product('format_breakdown')] }); + assert.equal((await evaluate(args)).commitment, 'untested_preparation'); + const empty = setup('format_breakdown', { prepare: undefined }); + assert.equal((await evaluate(empty.args)).state, 'harness_gap'); +}); +test('invalid parent blocks are declarations errors rather than absent support', async () => { + for (const capabilities of [{ media_buy: null }, { media_buy: [] }, { media_buy: { features: null } }]) { + const { args } = setup('format_breakdown', { capabilities }); + assert.equal((await evaluate(args)).reason, 'invalid_declaration'); + } +}); +test('invalid known declarations fail; unknown future keys remain open without claiming support', async () => { + for (const feature of features) for (const value of ['true', 1, null, [], {}]) { + const { args } = setup(feature, { capabilities: capability(feature, value) }); + assert.equal((await evaluate(args)).reason, 'invalid_declaration'); + } + assert.equal(validate.declaration({ future_feature: true }), true); + assert.equal(validate.declaration({ future_feature: { version: 2 } }), false); + const { args } = setup('format_breakdown', { capabilities: { media_buy: { features: { future_feature: true } } } }); + assert.equal((await evaluate(args)).state, 'coverage_gap'); +}); +test('fixed omitted/false flags qualify; owner carriage needs separate channel evidence and no selectable flag', () => { + for (const flag of [undefined, false]) { + const p = product('fixed_collection_bundles'); if (flag !== undefined) p.collection_targeting_allowed = flag; + assert.equal(validate.product(p), true); assert.equal(qualifies('fixed_collection_bundles', p), true); + assert.equal(qualifies('collection_selection', p), false); + } + const p = product('owner_sold_channel_carriage'); + assert.equal(qualifies('owner_sold_channel_carriage', p), false); + assert.equal(qualifies('owner_sold_channel_carriage', p, ownerEvidence), true); + assert.equal(qualifies('owner_sold_channel_carriage', p, { ...ownerEvidence, kind: 'show' }), false); +}); +test('new fields pass old open schemas; old sellers and omitted parents validate the fragment', () => { + const fresh = Object.fromEntries(features.map(f => [`supports_${f}`, true])); + assert.equal(validate.oldFeatures(fresh), true); assert.equal(validate.declaration({}), true); + assert.equal(validate.oldFeatures({ unknown_future: { version: 2 } }), false); + for (const p of Object.values(require('./features.schema.json').properties)) assert.equal(Object.hasOwn(p, 'default'), false); +}); +test('source time-view schema permits empty arrays and arbitrary positive thresholds; rejects invalid entries', () => { + const schema = require('../../static/schemas/source/core/delivery-metrics.json').properties.time_based_views; + const ajv = new Ajv({ strict: false }); + ajv.addSchema(require('../../static/schemas/source/enums/view-threshold-basis.json')); + ajv.addSchema(require('../../static/schemas/source/enums/viewability-standard.json')); + const valid = ajv.compile(schema); + for (const entries of [[], [{ threshold_seconds: 3, basis: 'in_view', views: 4 }]]) assert.equal(valid(entries), true); + for (const entries of [[{ threshold_seconds: 0, basis: 'in_view', views: 4 }], [{ threshold_seconds: 3, views: 4 }]]) assert.equal(valid(entries), false); +}); +test('current controller cannot demand new observed format/time grains from a feature declaration', () => { + const controller = require('../../static/schemas/source/compliance/comply-test-controller-request.json'); + const text = JSON.stringify(controller); + assert.equal(text.includes('prepare_product_feature'), false); + const delivery = require('../../static/schemas/source/media-buy/get-media-buy-delivery-request.json'); + assert.match(delivery.properties.reporting_dimensions.description, /possibly empty/); + assert.match(delivery.properties.requested_metrics.description, /omitted from the response without error/); +}); + +function sdkStoryboard(gated = false) { + return { id: 'proposal/commitment_hazard', version: '1.0', title: 'Shipping SDK hazard evidence', category: 'media_buy_seller', + summary: 'Evidence only', narrative: 'No implementation claim', agent: { interaction_model: 'media_buy_seller', capabilities: [] }, caller: { role: 'buyer_agent' }, + ...(gated && { requires_capability: { path: 'media_buy.features.supports_format_breakdown', equals: true } }), + phases: [{ id: 'exercise', title: 'Exercise', steps: [{ id: 'selected', title: 'Selected path', task: 'create_media_buy', + sample_request: {}, validations: [{ check: 'field_present', path: 'media_buy_id', description: 'Sentinel, not full lifecycle coverage' }] }] }] }; +} +test('SDK 15.9.5: equals-true gating would hide undeclared catalogs, including absent parent objects', async () => { + assert.equal(require('@adcp/sdk/package.json').version, '15.9.5'); + for (const capabilities of [{}, { media_buy: {} }, { media_buy: { features: {} } }]) { + let calls = 0; + const result = await runStoryboard('https://seller.example/mcp', sdkStoryboard(true), { + agentTools: ['create_media_buy'], _profile: { tools: ['create_media_buy'], raw_capabilities: capabilities }, + _client: { resetContext() {}, async createMediaBuy() { calls++; return { success: true, data: { media_buy_id: 'native-buy' } }; } }, + }); + assert.equal(calls, 0); assert.ok(result.phases.flatMap(p => p.steps).some(s => s.skip_reason === 'capability_unsupported')); + } +}); +test('SDK 15.9.5: old catalog path remains runnable with unknown declaration keys; selected failures stay failed', async () => { + for (const broken of [false, true]) { + let calls = 0; + const result = await runStoryboard('https://seller.example/mcp', sdkStoryboard(), { + agentTools: ['create_media_buy'], _profile: { tools: ['create_media_buy'], raw_capabilities: capability('format_breakdown', true) }, + _client: { resetContext() {}, async createMediaBuy() { calls++; return { success: true, data: broken ? {} : { media_buy_id: 'native-buy' } }; } }, + }); + assert.equal(calls, 1); assert.equal(result.phases[0].steps[0].passed, !broken); + } +}); + +const examples = require('./examples.json'); +const identities = selectors => selectors.flatMap(s => s.collection_ids.map(id => `${s.publisher_domain}\0${id}`)).sort(); +// An isolated assertion oracle over concrete vectors, not a seller implementation. +function selectionEvidence(vector) { + if (!validate.collectionSelection(vector.request)) return 'INVALID_REQUEST'; + const full = ['owner.example\0music', 'owner.example\0news']; + const selected = vector.request.mode === 'default' ? full : identities(vector.request.collections); + if (selected.some(id => !full.includes(id))) return 'REFERENCE_NOT_FOUND'; + if (!vector.selectable && JSON.stringify(selected) !== JSON.stringify(full)) return 'UNSUPPORTED_FEATURE'; + if (!validate.collectionSelection(vector.readback) || vector.readback.mode !== 'selected') return 'broken_readback'; + return JSON.stringify(identities(vector.readback.collections)) === JSON.stringify(selected) ? 'valid' : 'broken_readback'; +} +test('concrete source-schema vectors exercise selection, materialized defaults, fixed restatement and rejections', () => { + assert.equal(validate.declaration(examples.declarations), true); assert.equal(validate.params(examples.prepare_params), true); + for (const vector of examples.collection_vectors) assert.equal(selectionEvidence(vector), vector.error ?? 'valid', vector.name); + const selected = examples.collection_vectors[0]; + assert.equal(selectionEvidence({ ...selected, readback: { mode: 'default' } }), 'broken_readback'); + assert.equal(selectionEvidence({ ...selected, readback: examples.collection_vectors[1].readback }), 'broken_readback'); +}); +test('concrete source-schema reporting vectors permit empty observed arrays with companions and three-second views', () => { + assert.equal(validate.formatPackage(examples.empty_format_package), true); + assert.equal(validate.deliveryRequest(examples.format_request), true); + for (const metrics of [examples.empty_contracted_time_metric, examples.three_second_metric, examples.narrowed_metrics]) { + assert.equal(validate.deliveryMetrics(metrics), true, JSON.stringify(validate.deliveryMetrics.errors)); + } + const requiredCompanions = ['by_format', 'by_format_truncated', 'by_format_sorted_by', 'by_format_sort_direction']; + const observedContract = value => requiredCompanions.every(key => Object.hasOwn(value, key)) && validate.formatPackage(value); + assert.equal(observedContract(examples.empty_format_package), true); + for (const field of requiredCompanions) { + const broken = { ...examples.empty_format_package }; delete broken[field]; + assert.equal(observedContract(broken), false, `Missing requested-dimension companion ${field}`); + } + const narrowed = value => Object.keys(value).every(key => ['impressions', 'spend'].includes(key)); + assert.equal(narrowed(examples.narrowed_metrics), true); + assert.equal(narrowed({ ...examples.narrowed_metrics, clicks: 1 }), false); +}); + +test('failed catalog behavior preserves its independent missing-commitment evidence', async () => { + for (const option of [{ harness: false }, { operation: false }]) for (const exercise of [async () => false, async () => { throw new Error('broken'); }]) { + const { args } = setup('format_breakdown', { catalog: [product('format_breakdown')], ...option, exercise }); + const result = await evaluate(args); assert.equal(result.state, 'behavior_violation'); + assert.equal(result.commitment, option.harness === false ? 'unverified_missing_runner_contract' : 'violation_missing_promised_operation'); + } +}); +test('a seller rollup neither qualifies its plain products nor mutates a mixed catalog', async () => { + const plain = product(undefined, { product_id: 'a-plain-offer' }); + const supporting = product('format_breakdown', { product_id: 'z-format-offer' }); + const catalog = [plain, supporting]; const before = JSON.stringify(catalog); + const { args, calls } = setup('format_breakdown', { catalog }); + const result = await evaluate(args); assert.equal(result.product_id, 'z-format-offer'); + assert.equal(qualifies('format_breakdown', plain), false); assert.equal(JSON.stringify(catalog), before); assert.equal(calls.length, 0); +}); + +test('full source format-package schema rejects malformed inherited metrics', () => { + assert.equal(validate.formatPackage({ ...examples.empty_format_package, impressions: 'bad', spend: -1 }), false); +}); +test('proposed controller params reject malformed or unknown scopes without coercion', () => { + for (const params of [{}, { feature: 'format_breakdown', fixture_id: '' }, { feature: 'unknown_future_feature', fixture_id: 'run' }, { feature: true, fixture_id: 'run' }]) { + assert.equal(validate.params(params), false); + } +}); +test('SDK 15.9.5: an old controller returns UNKNOWN_SCENARIO for the proposed operation without mutation', async () => { + const { handleTestControllerRequest } = require('@adcp/sdk'); + const store = {}; + const response = await handleTestControllerRequest(store, { scenario: 'prepare_product_feature', params: examples.prepare_params }); + assert.equal(response.success, false); assert.equal(response.error, 'UNKNOWN_SCENARIO'); + assert.deepEqual(store, {}); +}); diff --git a/specs/optional-product-feature-declarations/review.md b/specs/optional-product-feature-declarations/review.md new file mode 100644 index 00000000000..686c6009e2b --- /dev/null +++ b/specs/optional-product-feature-declarations/review.md @@ -0,0 +1,81 @@ +# Proposal review and evidence + +This record describes agent analysis, not human approval, WG ratification, +shipping implementation, hosted certification, or release qualification. +The decision memo remains `status: proposed`; the PR must remain draft/unmerged. + +## Reproduce + +From main base `c2f01a50f2133b016fc73ca74019c4c021f2256e`, with its existing +SDK 15.9.5 and lockfile: + +```bash +node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs +``` + +The isolated suite has **54 tests**, including all 32 independent feature subsets. +It compiles actual current product/selection/reporting schemas and the actual +immutable 3.2.5 feature schema for old-reader acceptance, without editing them. +Three tests execute the real pinned SDK: two runner probes with injected clients +and an old controller dispatch probe. They prove +equals-true gates hide absent declarations, and a legacy ungated execution path +continues to run and retain selected-path failures, and an old controller +returns `UNKNOWN_SCENARIO` without mutation for the proposed operation. They do not implement the +proposed routing or exercise production sellers. + +The proposal model tests native-fixture qualification decisions, empty and +brief-only catalog routes, explicit false/no-claim behavior, missing harness +versus confirmed promised-operation violations, malformed declarations/setup, +independent feature combinations, catalog behavior plus separate preparation +evidence, and no whole-feature bypass through unsupported setup. + +Concrete vectors cover selected subset, default materialization, fixed default +and exact restatement, fixed-subset refusal, unknown-owner and malformed-selector +rejection, dropped/widened readback, empty format arrays with mandatory companions, +empty contracted time arrays, arbitrary positive thresholds, and requested-metric +narrowing. These are schema-backed assertion oracles over isolated vectors, +not executed source storyboards or a new reference-seller implementation. + +## Independent review synthesis + +The WG panel instructions require source-code, protocol and buyer/seller workflow +review. Three independent reviewers were run in one parallel batch, with +conceptual and end-to-end workflow checks. Findings retained here: + +- **Protocol:** preserve boolean-only unknown feature keys and real released-ref + loading; declare standardized true as the producer opt-in; keep catalog tests + when the new runner contract is absent; separate missing adapter from seller + transport failure; define retry keys consistently; specify seller-filter use. +- **Product/docs:** require a feature-eligible sandbox account without inferring + entitlement; do not certify setup from a catalog pass; clarify shared filter + semantics; add concrete selection/readback/reporting vectors; retain thresholds + and empty observed arrays under current guarantees. +- **Code:** preserve independent commitment evidence when selected behavior fails; + retain old-schema bounds; validate missing parent blocks; add mixed-catalog and + missing-operation/harness combinations; no active changeset for nonoperative + proposal assets. +- **Final code follow-up:** compile the complete format-package `allOf` so + inherited metric types are validated, and reject a malformed-metrics vector. + Clarify run-unique fixture IDs versus exact retries in the same principal/account + namespace; isolation is across principals/accounts, not an unstated run identity. + +Each finding above was addressed in the proposal and probes. Protocol and +product/docs reviewers found no remaining blocking/actionable findings for scoped +draft human review (independent 51/51 reruns before the three final negative/SDK +probes). The code reviewer inspected all eight final scoped files and independently +reran **54/54** probes plus `git diff --check`: **Ready to push**, with no blockers, +issues or nits. Normal precommit passed 79 unit files / 1260 tests, boundary suites +and typecheck; its server-unit scope check correctly skipped unrelated server +coverage. No full source-storyboard matrix or hosted implementation run is claimed. +No reviewer can approve +the normative field/fixture semantics for the WG or waive gated-path approval. + +## Still required for adoption + +The five normative choices at the end of the memo remain for humans/WG. Real +implementation needs source schema/docs/controller changes, SDK setup and evidence +support, current-source-storyboard qualification, hosted disposition integration, +minor changeset and assigned release train. The suite supplies no coverage for +real native adapter behavior, owner/host HTTPS authorization, fixture retry/TTL +implementation, production account eligibility, observed-grain injection, or a +3.2.x backport. Existing guards, baseline floors and release records are untouched. From f05e0ac99c348faf5f71a2431e259ba9383bf47f Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 19 Oct 2026 12:53:51 +0000 Subject: [PATCH 2/5] docs(protocol): separate default and subset commitments --- .../optional-product-feature-declarations.md | 107 ++++++++++++++---- .../controller.schema.json | 2 +- .../examples.json | 2 + .../features.schema.json | 3 +- .../model.cjs | 30 +++-- .../probes.test.cjs | 84 ++++++++++++-- .../review.md | 36 +++++- 7 files changed, 225 insertions(+), 39 deletions(-) diff --git a/specs/optional-product-feature-declarations.md b/specs/optional-product-feature-declarations.md index ffd0667c6ed..fadf299c490 100644 --- a/specs/optional-product-feature-declarations.md +++ b/specs/optional-product-feature-declarations.md @@ -3,8 +3,8 @@ title: Seller-wide optional product-feature commitments class: normative status: proposed date: 2026-10-19 -refs: ["#8254", "PR #8259", "PR #7982", "PR #7973", "DR-0001", "DR-0009", "DR-0010"] -dissent: Pending independent review; human/WG decision outstanding +refs: ["#8254", "PR #8259", "PR #8336", "PR #7982", "PR #7973", "DR-0001", "DR-0009", "DR-0010"] +dissent: Human/WG decision outstanding; agent review is not ratification --- ## Decision @@ -15,21 +15,25 @@ a DR number and decision provenance are assigned only through human review. No production schema, storyboard, hosted disposition, or released artifact is changed. The isolated schemas and executable model below are proposal evidence. -Recommend five optional booleans under `media_buy.features`, with no defaults: +Recommend six optional booleans under `media_buy.features`, with no defaults: | Field | Commitment and qualifying product | Independent consumers | | --- | --- | --- | -| `supports_collection_selection` | At least one product with nonempty explicit `collections`, `collection_targeting_allowed: true`, and at least two distinct collection identities so proper-subset selection can be tested. | Direct structured selection, default full-bundle materialization, persisted readback, invalid-selector rejection. | +| `supports_collection_selection` | At least one product with nonempty explicit `collections`, `collection_targeting_allowed: true`, and at least two distinct domain-qualified collection pairs so proper-subset selection can be tested. | Strict-subset structured selection, persisted readback and invalid-selector rejection. Existing default obligations still bind on the product. | +| `supports_collection_default_materialization` | At least one product with one distinct `(publisher_domain, collection_id)` pair in explicit `collections`, regardless of selectable/fixed mode. | `mode: default` full-bundle materialization and persisted concrete readback; independent of a strict-subset fixture. | | `supports_fixed_collection_bundles` | At least one multi-collection product with `collection_targeting_allowed` false or omitted (existing default false). | Exact full-bundle restatement, default materialization, proper-subset rejection. | | `supports_owner_sold_channel_carriage` | At least one channel-owner offer referencing that owner's canonical channel collection and a different host publisher's property. | Owner/host selector boundary checks; buyer-side host authorization verification remains separate. | | `supports_format_breakdown` | At least one product with `reporting_capabilities.supports_format_breakdown: true`. | Requested `format` dimension, `by_format`, truncation and applied-sort echoes; no required observations. | | `supports_time_based_views` | At least one product listing `time_based_views` in `reporting_capabilities.available_metrics`. | Metric availability and narrowing, schema-valid threshold entries when observed, committed-array presence when contracted. | These are existential seller support commitments, never assertions about every -product. Selection/default belong together because the existing targeting -contract already requires concrete default readback on a selectable product; -there is no meaningful conformant "selects but cannot materialize default" -path to declare independently. Fixed products have their own default path and +product. Default materialization and strict-subset selection qualify +independently: one distinct pair suffices for default coverage, while a genuine +strict subset needs two distinct pairs. Missing a two-pair fixture MUST NOT +suppress a one-pair default path. The two declarations do not make existing +readback obligations optional: a selected product's default/readback contract +still binds even when the separate seller-wide default commitment is absent or +false. Fixed-bundle subset enforcement needs its own two-pair fixed product and must not depend on a selectable companion. Owner-sold offers can be fixed or selectable: declaring owner-sold does not imply either of the other flags. The owner-sold fixture uses the product's actual fixed/selectable behavior. @@ -89,11 +93,69 @@ owner and root coordinator were contacted directly in their existing sessions; this PR touches only its own proposal namespace and scoped evidence workflow. Any later source overlap requires renewed file coordination with those owners. +### Reconciled catalog prerequisites (nonoperative) + +The current foundation review packet is [#8259 at +`ce8a65d6bd192c105ef3175091f29c7f296e47b9`](https://github.com/adcontextprotocol/adcp/blob/ce8a65d6bd192c105ef3175091f29c7f296e47b9/specs/optional-product-feature-applicability/collection-prerequisite.md). +It supersedes earlier proposal-head references for this reconciliation; its new +exact-head CI must be observed separately. The owner reports 70 local probes, +code-review rerun of 70 and protocol rerun of 36. Those are owner/reviewer reports, +not reruns by this declarations workspace or implemented SDK qualification. + +The selected-fixture contract must normalize schema-valid atomic +`(publisher_domain, collection_id)` pairs before eligibility and deterministic +parent selection. Default/full-bundle materialization needs one distinct pair; +strict-subset and fixed-subset enforcement need two. Fixed accepts literal false +or the existing omitted-false default, not null/wrong types. Optional declared +cross-domain owner/host relations must qualify before selection and retain the +same selected product, scoped price and relation witness. Full concrete bundle, +real singleton strict subset and collision-checked absent-ID/absent-domain +negatives must derive from that complete selected set. One normalizer serves +eligibility, witnesses and namespace-set validation; schema-valid redundant pairs +normalize as a set, while schema-invalid duplicate outer selected objects fail. +Empty string collection IDs remain legal under current schemas. Wire-declared +relations do not verify ownership or host authorization. Added collection +scenario IDs remain provisional; this proposal adopts no new source filename. + +Protected captures need the proposed atomic write/delete/metadata funnel across +all context-write paths, detached immutable preparation state and deep-cloned +views against alias mutation, plus authenticated every-lookup tenant/caller/run/ +grant/revocation checks. These are separate, **unimplemented foundation +surfaces**. Main-line implementation assignment is **NONE RECORDED / unconfirmed**; +reviewer-only work is not an assignment. This PR implements no SDK/DSL, protected +state or authenticated lookup. Its small pair normalizer is an isolated model +helper, not a foundation API or evidence of implemented capture/state safety. + +Held reporting [#8336 at +`8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`](https://github.com/adcontextprotocol/adcp/pull/8336) +has exactly two current actual-source IDs: `media_buy_seller/advanced_delivery_reporting` +(format-only, literal product format-support true) and +`media_buy_seller/time_based_delivery_reporting` (time metric independently present). +Both discover native non-guaranteed products with compatible fixed CPM options, +resolve pricing from the same product graph, and fully validate/paginate before +selection. Only the isolated account is seeded; no feature products/prices are +seeded. No-match is an explicit coverage gap, never a pass or nonsupport proof. +Seeded-only, brief-only and commercial coverage limits remain disclosed. + +Commercial snapshot/minimum-spend, mature committed-time value-or-disclosure, +caller-brand, full/standalone and hosted disposition limits keep that draft held. +The owner reports 48 actual-source/public/hosted tests and 38 successful exact-head +checks plus five skips; the draft storyboard matrix is skipped. These counts do +not qualify runtime behavior or authorize shipping. The later #8259 public +evidence shows bounded same-read returned-row ordering and time value-or-disclosure +are already downstream-authorable, with timestamp/measurability/live-fallback, +standalone-flow and unobserved-population limits. They are not reasons to invent +new reporting observations or deterministic grain injection. Main 15.9.5 and a +disposable pristine 15.9.6 comparison remain separately scoped; no dependency +adoption follows. #8254 stays open. Maintenance qualification/merge, draft Version +Packages refresh (including #8274), publication and production actions remain held; +the #8302-only refresh exception does not extend to these drafts. + ## Proposed normative language The following MUST/SHOULD text is conditional on adoption in an assigned minor. -1. A seller MAY emit any subset of the five fields. Every emitted known value +1. A seller MAY emit any subset of the six fields. Every emitted known value MUST be a boolean. Omitted fields, including an omitted `features` or `media_buy` parent, mean **no seller-wide claim / unknown**, not unsupported. `false` explicitly declines the seller-wide commitment; it does not deny @@ -187,7 +249,7 @@ is not an executable escape hatch here. Propose one additional sandbox scenario, **`prepare_product_feature`**, within `comply_test_controller`, using its existing account and success/error envelope: -- Params: `feature` (one of the five scope identifiers below) and `fixture_id` +- Params: `feature` (one of the six scope identifiers below) and `fixture_id` (nonempty run-scoped idempotency key, maximum 128 characters). No authored product fields, selector strings, observed metrics, or credentials. - Success: `success: true`, `simulated: {feature, fixture_id, product}`. `product` @@ -216,7 +278,8 @@ Propose one additional sandbox scenario, **`prepare_product_feature`**, within precondition, never "feature unsupported." A true feature's valid setup refusal is evidence of a violated promise, not a new interpretation of the error. An uncommitted feature is not probed through this operation. -- Scope identifiers: `collection_selection`, `fixed_collection_bundles`, +- Scope identifiers: `collection_selection`, `collection_default_materialization`, + `fixed_collection_bundles`, `owner_sold_channel_carriage`, `format_breakdown`, `time_based_views`. The isolated [declaration schema](optional-product-feature-declarations/features.schema.json) @@ -245,9 +308,12 @@ are recommendations. A valid three-second `in_view` entry is acceptable. Check unique `(threshold_seconds, basis)` pairs when entries exist and do not sum bases. `available_metrics` alone does not guarantee every uncommitted metric is measurable on every report. Missing values follow existing omission and -`missing_metrics` rules. Contracting `time_based_views` binds array presence, -including an empty observed array; it does not bind particular thresholds. -The two reporting probes below exercise these limits without injecting grains. +`missing_metrics` rules. Contracting `time_based_views` binds accountability for its array carrier or +the applicable `missing_metrics` disclosure under existing maturity/measurability +rules; it does not force observations or bind particular thresholds. An empty +observed array remains valid where the carrier is appropriate. A feature +declaration alone supplies neither a matured commitment nor its timestamp. +The isolated reporting probes exercise these limits without injecting grains. If the WG wants deterministic nonempty observations, it needs a **separate** controller amendment specifying package attribution, accepted format/threshold @@ -273,7 +339,8 @@ are not retroactively certified; older implementations with a colliding custom boolean name must remove it or adopt this contract before opting in. An old schema accepting that boolean is not itself semantic certification. -1. Keep the separately owned catalog fix and any qualified 3.2.x backport moving. +1. Preserve the separately owned held catalog drafts and their qualification holds; + a 3.2.x backport requires a qualified main merge and separate actual-pin review. Retain its independent feature graphs, seller-derived selectors/pricing, omitted-false bundle handling and current reporting guarantees. 2. Ratify exact fields, existential semantics and setup commitment. Assign a @@ -281,7 +348,7 @@ schema accepting that boolean is not itself semantic certification. 3.4 hold as a release assignment for this design. New stable optional fields plus new opt-in MUSTs are Normative/minor, not patch errata. Sellers making no claim keep their existing contracts. -3. In a coordinated implementation PR add five properties to +3. In a coordinated implementation PR add six properties to `static/schemas/source/core/media-buy-features.json`, document the clauses in `docs/protocol/get_adcp_capabilities.mdx`, add the controller scenario/params and docs, implement native fixture preparation in the reference seller, and @@ -297,7 +364,8 @@ schema accepting that boolean is not itself semantic certification. That changeset is intentionally **not active in this proposal-only PR**; policy forbids versioning a nonoperative spec experiment as shipped protocol. -4. Add the runner setup/evidence contract in its owning SDK, qualify the actual +4. After explicit implementation assignment and contract approval, add the + runner setup/evidence contract in its owning SDK and qualify the actual pinned SDK and real source storyboards, and integrate a declaration assertion that cannot be hidden by controller prerequisites. Coordinate shared files with #8254 before promotion. Do not create equals-true or compound gates that @@ -344,8 +412,9 @@ commands are recorded in [review evidence](optional-product-feature-declarations ## Unresolved normative choices for human/WG review -1. Adopt the five field names and grouping, including default materialization - within selectable/fixed paths and owner-sold independent of selectability? +1. Adopt the six field names and independent qualification, including a one-pair + default path separate from two-pair subset selection and owner-sold independent + of selectability? 2. Adopt existential native support **plus** mandatory feature-qualified sandbox preparation for true declarations, or split technical-support rollups from an independently advertised fixture commitment? Recommendation: one explicit diff --git a/specs/optional-product-feature-declarations/controller.schema.json b/specs/optional-product-feature-declarations/controller.schema.json index 959f58a03a8..ada1f9cf9ca 100644 --- a/specs/optional-product-feature-declarations/controller.schema.json +++ b/specs/optional-product-feature-declarations/controller.schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "title": "PROPOSED prepare_product_feature payload fragments; not published", "definitions": { - "feature": { "type": "string", "enum": ["collection_selection", "fixed_collection_bundles", "owner_sold_channel_carriage", "format_breakdown", "time_based_views"] }, + "feature": { "type": "string", "enum": ["collection_selection", "collection_default_materialization", "fixed_collection_bundles", "owner_sold_channel_carriage", "format_breakdown", "time_based_views"] }, "fixture_id": { "type": "string", "minLength": 1, "maxLength": 128, "x-entity": "product_feature_fixture" }, "params": { "type": "object", diff --git a/specs/optional-product-feature-declarations/examples.json b/specs/optional-product-feature-declarations/examples.json index 11de042a8d1..2cfa744a183 100644 --- a/specs/optional-product-feature-declarations/examples.json +++ b/specs/optional-product-feature-declarations/examples.json @@ -2,11 +2,13 @@ "note": "Isolated proposal vectors; fields are not published or certified. Collection readbacks below are semantic fragments, not complete task envelopes.", "declarations": { "supports_collection_selection": true, + "supports_collection_default_materialization": true, "supports_fixed_collection_bundles": false, "supports_owner_sold_channel_carriage": true, "supports_format_breakdown": false, "supports_time_based_views": true }, + "default_only_declarations": { "supports_collection_default_materialization": true, "supports_collection_selection": false }, "prepare_params": { "feature": "collection_selection", "fixture_id": "run-example-selectable" }, "collection_vectors": [ { "name": "selected subset", "selectable": true, "request": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news"] }] }, "readback": { "mode": "selected", "collections": [{ "publisher_domain": "owner.example", "collection_ids": ["news"] }] } }, diff --git a/specs/optional-product-feature-declarations/features.schema.json b/specs/optional-product-feature-declarations/features.schema.json index 11ce08a5148..950c8e24a36 100644 --- a/specs/optional-product-feature-declarations/features.schema.json +++ b/specs/optional-product-feature-declarations/features.schema.json @@ -3,7 +3,8 @@ "title": "PROPOSED additions to media_buy.features; not published", "type": "object", "properties": { - "supports_collection_selection": { "type": "boolean", "description": "Opt-in native selectable-collection support and qualified sandbox fixture commitment, including default materialization; not every product." }, + "supports_collection_selection": { "type": "boolean", "description": "Opt-in native strict-subset selection and qualified sandbox fixture commitment with at least two distinct domain-qualified pairs; existing product default-readback obligations still bind." }, + "supports_collection_default_materialization": { "type": "boolean", "description": "Opt-in native full-bundle default materialization and qualified sandbox fixture commitment with at least one distinct domain-qualified pair; independent of strict-subset fixtures." }, "supports_fixed_collection_bundles": { "type": "boolean", "description": "Opt-in native fixed-collection bundle support and qualified sandbox fixture commitment; independent of selectable products." }, "supports_owner_sold_channel_carriage": { "type": "boolean", "description": "Opt-in native owner-sold channel carriage support and qualified sandbox fixture commitment; no entitlement or authorization assertion." }, "supports_format_breakdown": { "type": "boolean", "description": "Opt-in native format-grain reporting support and qualified sandbox fixture commitment; no required observed rows." }, diff --git a/specs/optional-product-feature-declarations/model.cjs b/specs/optional-product-feature-declarations/model.cjs index ce7afba496b..1efbfd15f44 100644 --- a/specs/optional-product-feature-declarations/model.cjs +++ b/specs/optional-product-feature-declarations/model.cjs @@ -34,9 +34,22 @@ async function validators() { }; } -function collectionCount(product) { - return new Set((product.collections ?? []).flatMap(selector => - (selector.collection_ids ?? []).map(id => `${selector.publisher_domain}\0${id}`))).size; +// UTF-8 ordering with a lossless tie-break for schema-valid lone-surrogate +// strings that Buffer encodes to the same replacement bytes. No ID rewriting. +function compareWireStrings(a, b) { + return Buffer.compare(Buffer.from(a), Buffer.from(b)) || (a < b ? -1 : a > b ? 1 : 0); +} + +// Evidence-only normalizer for schema-valid concrete selectors. This is not an +// SDK predicate/capture API or qualification of the proposed foundation contract. +function collectionPairs(selectors) { + const pairs = new Map(); + for (const selector of selectors ?? []) for (const id of selector.collection_ids ?? []) { + const pair = [selector.publisher_domain, id]; + pairs.set(JSON.stringify(pair), pair); + } + return [...pairs.values()].sort((a, b) => + compareWireStrings(a[0], b[0]) || compareWireStrings(a[1], b[1])); } // These predicates are proposed fixture qualification, not universal new product @@ -44,13 +57,14 @@ function collectionCount(product) { function qualifies(feature, product, ownerEvidence) { const report = product.reporting_capabilities ?? {}; switch (feature) { - case 'collection_selection': return collectionCount(product) >= 2 && product.collection_targeting_allowed === true; - case 'fixed_collection_bundles': return collectionCount(product) >= 2 && product.collection_targeting_allowed !== true; + case 'collection_selection': return collectionPairs(product.collections).length >= 2 && product.collection_targeting_allowed === true; + case 'collection_default_materialization': return collectionPairs(product.collections).length >= 1; + case 'fixed_collection_bundles': return collectionPairs(product.collections).length >= 2 && product.collection_targeting_allowed !== true; case 'owner_sold_channel_carriage': return Boolean(ownerEvidence && ownerEvidence.product_id === product.product_id && ownerEvidence.kind === 'channel' && ownerEvidence.owner_domain !== ownerEvidence.host_domain - && product.collections?.some(s => s.publisher_domain === ownerEvidence.owner_domain && s.collection_ids.includes(ownerEvidence.collection_id)) + && collectionPairs(product.collections).some(([domain, id]) => domain === ownerEvidence.owner_domain && id === ownerEvidence.collection_id) && product.publisher_properties?.some(s => s.publisher_domain === ownerEvidence.host_domain)); case 'format_breakdown': return report.supports_format_breakdown === true; case 'time_based_views': return report.available_metrics?.includes('time_based_views') === true; @@ -72,7 +86,7 @@ async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidenc const promised = declarations[`supports_${feature}`] === true; if (catalog && catalog.some(p => !validate.product(p))) return { state: 'behavior_violation', reason: 'invalid_catalog' }; let product = catalog?.filter(p => qualifies(feature, p, ownerEvidence)) - .sort((a, b) => Buffer.compare(Buffer.from(a.product_id), Buffer.from(b.product_id)))[0]; + .sort((a, b) => compareWireStrings(a.product_id, b.product_id))[0]; let route = 'catalog'; if (!product && !promised) return { state: 'coverage_gap', reason: catalog === null ? 'no_wholesale_surface' : 'fixture_unsatisfied' }; if (!product) { @@ -101,4 +115,4 @@ async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidenc } catch { return { state: 'behavior_violation', reason: 'selected_protocol', route, ...(commitment && { commitment }) }; } } -module.exports = { features, validators, qualifies, evaluate }; +module.exports = { features, validators, collectionPairs, qualifies, evaluate }; diff --git a/specs/optional-product-feature-declarations/probes.test.cjs b/specs/optional-product-feature-declarations/probes.test.cjs index 332eec2301a..e4f0b47734e 100644 --- a/specs/optional-product-feature-declarations/probes.test.cjs +++ b/specs/optional-product-feature-declarations/probes.test.cjs @@ -4,7 +4,7 @@ const test = require('node:test'); const assert = require('node:assert/strict'); const Ajv = require('ajv'); const { runStoryboard } = require('@adcp/sdk/testing'); -const { features, validators, qualifies, evaluate } = require('./model.cjs'); +const { features, validators, collectionPairs, qualifies, evaluate } = require('./model.cjs'); let validate; test.before(async () => { validate = await validators(); }); @@ -18,9 +18,10 @@ function product(feature, extra = {}) { reporting_capabilities: { available_reporting_frequencies: ['daily'], expected_delay_minutes: 0, timezone: 'UTC', supports_webhooks: false, available_metrics: ['impressions', 'spend'], date_range_support: 'date_range' }, }; - if (['collection_selection', 'fixed_collection_bundles', 'owner_sold_channel_carriage'].includes(feature)) { + if (['collection_selection', 'collection_default_materialization', 'fixed_collection_bundles', 'owner_sold_channel_carriage'].includes(feature)) { value.collections = [{ publisher_domain: 'owner.example', collection_ids: ['news', 'music'] }]; - if (feature === 'collection_selection') value.collection_targeting_allowed = true; + if (feature === 'collection_selection' || feature === 'collection_default_materialization') value.collection_targeting_allowed = true; + if (feature === 'collection_default_materialization') value.collections[0].collection_ids = ['news']; } if (feature === 'format_breakdown') value.reporting_capabilities.supports_format_breakdown = true; if (feature === 'time_based_views') value.reporting_capabilities.available_metrics.push('time_based_views'); @@ -94,8 +95,8 @@ for (const feature of features) { }); } -test('all 32 independent declaration combinations select only the promised empty-catalog paths', async () => { - for (let mask = 0; mask < 32; mask++) { +test('all 64 independent declaration combinations select only the promised empty-catalog paths', async () => { + for (let mask = 0; mask < 2 ** features.length; mask++) { const declarations = Object.fromEntries(features.map((feature, i) => [`supports_${feature}`, Boolean(mask & (1 << i))])); for (let i = 0; i < features.length; i++) { const { args, calls } = setup(features[i], { capabilities: { media_buy: { features: declarations } } }); @@ -203,13 +204,13 @@ test('SDK 15.9.5: old catalog path remains runnable with unknown declaration key }); const examples = require('./examples.json'); -const identities = selectors => selectors.flatMap(s => s.collection_ids.map(id => `${s.publisher_domain}\0${id}`)).sort(); +const identities = selectors => collectionPairs(selectors); // An isolated assertion oracle over concrete vectors, not a seller implementation. function selectionEvidence(vector) { if (!validate.collectionSelection(vector.request)) return 'INVALID_REQUEST'; - const full = ['owner.example\0music', 'owner.example\0news']; + const full = [['owner.example', 'music'], ['owner.example', 'news']]; const selected = vector.request.mode === 'default' ? full : identities(vector.request.collections); - if (selected.some(id => !full.includes(id))) return 'REFERENCE_NOT_FOUND'; + if (selected.some(pair => !full.some(expected => JSON.stringify(pair) === JSON.stringify(expected)))) return 'REFERENCE_NOT_FOUND'; if (!vector.selectable && JSON.stringify(selected) !== JSON.stringify(full)) return 'UNSUPPORTED_FEATURE'; if (!validate.collectionSelection(vector.readback) || vector.readback.mode !== 'selected') return 'broken_readback'; return JSON.stringify(identities(vector.readback.collections)) === JSON.stringify(selected) ? 'valid' : 'broken_readback'; @@ -270,3 +271,70 @@ test('SDK 15.9.5: an old controller returns UNKNOWN_SCENARIO for the proposed op assert.equal(response.success, false); assert.equal(response.error, 'UNKNOWN_SCENARIO'); assert.deepEqual(store, {}); }); + +test('one-pair default-only catalog coverage survives an unavailable strict-subset fixture', async () => { + const single = product('collection_default_materialization'); + assert.equal(validate.product(single), true); + const capabilities = { media_buy: { features: examples.default_only_declarations } }; + const defaults = setup('collection_default_materialization', { capabilities, catalog: [single] }); + const subsets = setup('collection_selection', { capabilities, catalog: [single] }); + assert.equal((await evaluate(defaults.args)).state, 'applicable'); + assert.equal((await evaluate(subsets.args)).state, 'coverage_gap'); + assert.equal(defaults.calls.length, 0); assert.equal(subsets.calls.length, 0); +}); +test('a broken promised subset fixture does not suppress a separately qualifying default path', async () => { + const single = product('collection_default_materialization'); + const capabilities = { media_buy: { features: { supports_collection_selection: true, supports_collection_default_materialization: true } } }; + const subsets = setup('collection_selection', { capabilities, catalog: [single], + prepare: async params => ({ success: true, simulated: { ...params, product: single } }) }); + assert.equal((await evaluate(subsets.args)).reason, 'invalid_qualified_setup'); + const defaults = setup('collection_default_materialization', { capabilities, catalog: [single] }); + assert.equal((await evaluate(defaults.args)).state, 'applicable'); +}); +test('one-pair defaults qualify in selectable and omitted-or-false fixed modes', () => { + for (const mode of [undefined, false, true]) { + const single = product('collection_default_materialization'); + if (mode === undefined) delete single.collection_targeting_allowed; + else single.collection_targeting_allowed = mode; + assert.equal(validate.product(single), true); + assert.equal(qualifies('collection_default_materialization', single), true); + assert.equal(qualifies('collection_selection', single), false); + assert.equal(qualifies('fixed_collection_bundles', single), false); + } +}); +test('one evidence normalizer preserves namespaces and schema-valid redundant/empty IDs without inventing pairs', () => { + const repeated = product('collection_selection', { collections: [ + { publisher_domain: 'owner.example', collection_ids: ['shared', 'shared', ''] }, + { publisher_domain: 'owner.example', collection_ids: ['', 'shared'] }, + { publisher_domain: 'other.example', collection_ids: ['shared'] }, + ] }); + assert.equal(validate.product(repeated), true); + const normalized = collectionPairs(repeated.collections); + assert.deepEqual(normalized, [['other.example', 'shared'], ['owner.example', ''], ['owner.example', 'shared']]); + assert.equal(qualifies('collection_selection', repeated), true); + const one = product('collection_selection', { collections: [ + { publisher_domain: 'owner.example', collection_ids: ['news', 'news'] }, + { publisher_domain: 'owner.example', collection_ids: ['news'] }, + ] }); + assert.equal(validate.product(one), true); + assert.equal(qualifies('collection_selection', one), false); + assert.equal(qualifies('collection_default_materialization', one), true); +}); +test('set-equivalent regrouping passes semantic equality while schema-invalid duplicate selected objects fail', () => { + const grouped = [{ publisher_domain: 'owner.example', collection_ids: ['news', 'music'] }]; + const regrouped = [{ publisher_domain: 'owner.example', collection_ids: ['music', 'news', 'news'] }, + { publisher_domain: 'owner.example', collection_ids: ['news'] }]; + assert.equal(validate.collectionSelection({ mode: 'selected', collections: regrouped }), true); + assert.deepEqual(collectionPairs(grouped), collectionPairs(regrouped)); + assert.equal(validate.collectionSelection({ mode: 'selected', collections: [grouped[0], grouped[0]] }), false); + assert.notDeepEqual(collectionPairs(grouped), collectionPairs([{ publisher_domain: 'other.example', collection_ids: ['news', 'music'] }])); +}); + +test('schema-valid distinct IDs with equal UTF-8 replacement bytes normalize losslessly in either order', () => { + const a = [{ publisher_domain: 'owner.example', collection_ids: ['\ud800', '\ud801'] }]; + const b = [{ publisher_domain: 'owner.example', collection_ids: ['\ud801', '\ud800'] }]; + assert.equal(validate.collectionSelection({ mode: 'selected', collections: a }), true); + assert.equal(validate.collectionSelection({ mode: 'selected', collections: b }), true); + assert.deepEqual(collectionPairs(a), collectionPairs(b)); + assert.equal(collectionPairs(a).length, 2); +}); diff --git a/specs/optional-product-feature-declarations/review.md b/specs/optional-product-feature-declarations/review.md index 686c6009e2b..08694938182 100644 --- a/specs/optional-product-feature-declarations/review.md +++ b/specs/optional-product-feature-declarations/review.md @@ -13,7 +13,7 @@ SDK 15.9.5 and lockfile: node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs ``` -The isolated suite has **54 tests**, including all 32 independent feature subsets. +The isolated suite has **67 tests**, including all 64 independent feature subsets. It compiles actual current product/selection/reporting schemas and the actual immutable 3.2.5 feature schema for old-reader acceptance, without editing them. Three tests execute the real pinned SDK: two runner probes with injected clients @@ -36,7 +36,7 @@ empty contracted time arrays, arbitrary positive thresholds, and requested-metri narrowing. These are schema-backed assertion oracles over isolated vectors, not executed source storyboards or a new reference-seller implementation. -## Independent review synthesis +## Initial review synthesis (head `2b4908b2`) The WG panel instructions require source-code, protocol and buyer/seller workflow review. Three independent reviewers were run in one parallel batch, with @@ -70,6 +70,38 @@ coverage. No full source-storyboard matrix or hosted implementation run is claim No reviewer can approve the normative field/fixture semantics for the WG or waive gated-path approval. +## Reconciliation with independent default coverage + +The revised candidate adds a sixth proposed default-materialization field and +controller scope. One schema-valid distinct pair qualifies independently from +the two pairs required for genuine strict-subset selection. Six new probes +cover default-only coverage, a broken subset promise alongside a valid default, +all fixed/selectable one-pair modes, namespace-preserving normalization of +schema-valid redundant/empty IDs, and regrouping versus schema-invalid duplicate +selected objects, plus lossless ordering of schema-valid distinct IDs whose +UTF-8 replacement bytes tie. All 64 declaration subsets execute; generic per-feature probes +also cover the sixth scope. This is isolated evidence, not an SDK/DSL change. + +The proposal now cites #8259 at `ce8a65d6bd192c105ef3175091f29c7f296e47b9` +and held reporting #8336 at `8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`. +Upstream counts and reviews are explicitly owner/reviewer reports; this workspace +has not rerun those suites. The declared relation, same-selected snapshot, +protected write/delete/metadata funnel, alias-safe prepared state and authenticated +every-lookup grant/revocation requirements remain proposed foundation surfaces, +with implementation assignment NONE RECORDED / unconfirmed. Reporting IDs are +limited to the two actual-source reporting scenarios; new collection IDs remain +provisional. Green draft CI or counterexample tests do not qualify shipping. + +Fresh independent protocol and product/docs reviews each reran **66/66** and +found no blocking/actionable findings in the scope correction. Final independent +code review inspected all seven changed files (the existing scoped workflow is +unchanged), corrected a schema-valid Unicode ordering edge case, and reran +**67/67**, zero failures/skips, plus `git diff --check`: **Ready to push**, with no +remaining findings. The new regression preserves distinct IDs when UTF-8 +replacement bytes tie; it adds no schema restriction. The current isolated suite +passes 67/67 locally; new exact-head CI will be observed separately. These fresh +reviews support continued draft human review, not ratification or runtime safety. + ## Still required for adoption The five normative choices at the end of the memo remain for humans/WG. Real From 39f1050d5227796a98adff40f50830e3cf13452f Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 19 Oct 2026 20:46:32 +0000 Subject: [PATCH 3/5] docs(protocol): record assigned catalog foundation owner --- .../optional-product-feature-declarations.md | 24 +++++++++++++++---- .../review.md | 10 ++++++-- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/specs/optional-product-feature-declarations.md b/specs/optional-product-feature-declarations.md index fadf299c490..9b3e989e649 100644 --- a/specs/optional-product-feature-declarations.md +++ b/specs/optional-product-feature-declarations.md @@ -120,11 +120,25 @@ scenario IDs remain provisional; this proposal adopts no new source filename. Protected captures need the proposed atomic write/delete/metadata funnel across all context-write paths, detached immutable preparation state and deep-cloned views against alias mutation, plus authenticated every-lookup tenant/caller/run/ -grant/revocation checks. These are separate, **unimplemented foundation -surfaces**. Main-line implementation assignment is **NONE RECORDED / unconfirmed**; -reviewer-only work is not an assignment. This PR implements no SDK/DSL, protected -state or authenticated lookup. Its small pair normalizer is an isolated model -helper, not a foundation API or evidence of implemented capture/state safety. +grant/revocation checks. These are separate foundation surfaces. The earlier +**NONE RECORDED / unconfirmed** ownership status is superseded by root's explicit +assignment of the focused #8259 implementation in `adcontextprotocol/adcp-client` +to [SDK catalog fixture foundation #8259](conductor://workspace?id=9bed7f0a-da60-44d8-a102-3586db378a8a), +session `7d85de47-008e-484b-8f14-2601c34f5725`, based on fresh main. Its authorized +output is a reviewed draft SDK source implementation for the contract at +`ce8a65d6bd192c105ef3175091f29c7f296e47b9`, with public integration and exact-head +contract/security evidence. Assignment is not implementation qualification: +this proposal has not reviewed an actual candidate implementation head. The +existing stable session remains reviewer-only; other owners retain their scopes. + +That focused foundation assignment does not authorize this proposal's capability +fields, `prepare_product_feature` controller wire contract, final collection IDs, +protocol dependency/lock/bridge adoption, maintenance changes, merge, publication +or release. Those remain separate decisions and qualification work. This PR +implements no SDK/DSL, protected state or authenticated lookup. Its small pair +normalizer is an isolated model helper, not a foundation API or evidence of +implemented capture/state safety. The declarations owner contacted the new SDK +owner directly to preserve this boundary before any shared API finalization. Held reporting [#8336 at `8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`](https://github.com/adcontextprotocol/adcp/pull/8336) diff --git a/specs/optional-product-feature-declarations/review.md b/specs/optional-product-feature-declarations/review.md index 08694938182..2afe581a1a0 100644 --- a/specs/optional-product-feature-declarations/review.md +++ b/specs/optional-product-feature-declarations/review.md @@ -87,8 +87,14 @@ and held reporting #8336 at `8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`. Upstream counts and reviews are explicitly owner/reviewer reports; this workspace has not rerun those suites. The declared relation, same-selected snapshot, protected write/delete/metadata funnel, alias-safe prepared state and authenticated -every-lookup grant/revocation requirements remain proposed foundation surfaces, -with implementation assignment NONE RECORDED / unconfirmed. Reporting IDs are +every-lookup grant/revocation requirements remain separately qualified foundation +surfaces. At that reconciliation, assignment was NONE RECORDED / unconfirmed; +root has since assigned the focused #8259 SDK implementation to workspace +`9bed7f0a-da60-44d8-a102-3586db378a8a`, session +`7d85de47-008e-484b-8f14-2601c34f5725`. This ownership update supersedes that status +only; no candidate source head has been reviewed or qualified by this proposal. +The metadata-only correction changes no field, fixture or model semantics. +Reporting IDs are limited to the two actual-source reporting scenarios; new collection IDs remain provisional. Green draft CI or counterexample tests do not qualify shipping. From 4f5795e8369bab14b4357c186a838e7cb8eec53b Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 19 Oct 2026 22:57:22 +0000 Subject: [PATCH 4/5] docs(protocol): clarify fixture API readiness and product bounds --- .../optional-product-feature-declarations.md | 69 ++++++++++++++++++- .../probes.test.cjs | 29 ++++++++ .../review.md | 32 ++++++++- 3 files changed, 128 insertions(+), 2 deletions(-) diff --git a/specs/optional-product-feature-declarations.md b/specs/optional-product-feature-declarations.md index 9b3e989e649..8726d17abe8 100644 --- a/specs/optional-product-feature-declarations.md +++ b/specs/optional-product-feature-declarations.md @@ -117,6 +117,14 @@ Empty string collection IDs remain legal under current schemas. Wire-declared relations do not verify ownership or host authorization. Added collection scenario IDs remain provisional; this proposal adopts no new source filename. +Product qualification retains two existing schema boundaries: every +`collections[]` entry on a product MUST carry explicit `collection_ids`; a +domain-only bulk grant is authorization scoping, not product composition. +Product `publisher_properties[]` entries MUST use singular `publisher_domain`; +`publisher_domains[]` is forbidden even when a singular domain is also present. +Do not fan it out or discard invalid entries to salvage a qualifying subset. +These are existing product requirements, not new declaration obligations. + Protected captures need the proposed atomic write/delete/metadata funnel across all context-write paths, detached immutable preparation state and deep-cloned views against alias mutation, plus authenticated every-lookup tenant/caller/run/ @@ -140,6 +148,65 @@ normalizer is an isolated model helper, not a foundation API or evidence of implemented capture/state safety. The declarations owner contacted the new SDK owner directly to preserve this boundary before any shared API finalization. +### Candidate SDK API readiness — implementation-head review pending + +The assigned SDK draft is [adcp-client #3354](https://github.com/adcontextprotocol/adcp-client/pull/3354), +based on SDK main `1977a1ba`, package `16.0.0-beta.9` in beta pre-mode, wire +`ADCP_VERSION: 3.2.5`. The owner reports re-establishing all 13 baseline +limitations on that base before implementation; its baseline file is a local +`.context` artifact, while repaired expectations are in four committed suites. +Those are owner reports, not reruns by this declarations workspace. Installed +protocol-main 15.9.5 evidence and the disposable pristine 15.9.6 comparison stay +separate; neither establishes a 16-beta limitation. SDK 14/9 remain unqualified. + +The first implementation was reported to have two confirmed security defects +and is superseded. **Await the exact review-fix SHA before any disposable build, +execution or candidate qualification.** No candidate SDK is installed here and +no dependency pin, lockfile or bridge changes. The following public API shape is +an owner-reported review input, not final code approval or a release dependency: + +| Surface reported by the SDK owner | Possible reuse after exact-head qualification | Remaining boundary | +| --- | --- | --- | +| `collection_selection_satisfies` with mode, optional minimum pairs and external-owner operand; shared normalization/witness helpers | Independent one-pair defaults, two-pair strict subsets, omitted-false fixed products and declared owner/host relations | No new collection IDs, seller capability fields, reporting scope or external authorization proof. | +| `fixture_resolution[].context_outputs` under the protected fixture namespace, exactly one of path or witness | Capture the same selected product/scoped price/relation after the complete graph resolves | Capture safety and schema legality require separate qualification; ordinary response context is not preparation authority. | +| `collection_set_equals_context` | Compare concrete namespace-qualified sets against protected expected state | New authored check kind must be adopted in the protocol authoring/output contracts before published use. | +| `prepareStoryboardFixtures`, `PreparedStoryboardFixtures`, trust checks and contract version; full/standalone `prepared_fixtures` options | Share qualified preparation with content/route/schema/scope/run bindings | Every lookup, direct state and opaque reference alike, requires live trusted authorization. Preparation alone does not fix standalone phase skipping. | + +The public CJS/ESM exports and disposable instructions are reported by the SDK +owner: build its exact safe candidate in ignored scratch space, pack it, and +resolve it in an isolated test root. Do not adopt its package in this workspace. +Coordinate exact exports and build instructions with that owner before consumer +source edits. Authored versus resolved selector types must preserve explicit +operand defaults; do not infer a new wire or negotiation meaning from them. + +The SDK candidate is not sufficient authoring authority by itself. An upstream +AdCP PR must amend the closed match-operator set and fixture-resolution capture +shape in `static/compliance/source/universal/storyboard-schema.yaml`, and add +`collection_set_equals_context` to `runner-output-contract.yaml` authored check +kinds before published storyboards can legally use them. These files remain with +their coordinated owners; this proposal edits none. Old-runner load rejection +must be qualified as the downgrade behavior, not a successful skipped feature. + +Trust is reported as SDK-owned runtime object identity: direct construction, +look-alikes, copied public bindings, frozen clones and JSON rehydration must not +acquire preparation authority. A process-local HMAC binds nonsecret credential +identity; tokens do not enter evidence and immutability is not portable trust. +Cross-process/serialized reuse requires authenticated reconstruction or a host +reference lookup with live scope checks. Host tenant/org session resolution and +grant/revocation storage remain host responsibilities behind the trusted +authorizer. Separate exact-head security evidence must verify both write/alias +isolation and authority on every direct/opaque lookup. No such implementation +safety is certified by this proposal or by an exported API list. + +This foundation changes no seller/controller wire and does not implement +`prepare_product_feature` or a seller-wide commitment. Future reuse still needs +an approved way to bind a native feature-qualified prepared offer, including a +brief-only/initially-empty seller, into the execution fixture graph. The current +API report is not proof that this additional route is implemented; it remains +part of #8333's WG/controller/runner decisions. Format/time reporting, commercial +context, branding, accounting and standalone `phase.skip_if` remain separately +qualified consumer work; no observations or grain injection follow. + Held reporting [#8336 at `8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`](https://github.com/adcontextprotocol/adcp/pull/8336) has exactly two current actual-source IDs: `media_buy_seller/advanced_delivery_reporting` @@ -257,7 +324,7 @@ Current `seed_product` accepts permissive authored exemplars; `list_scenarios` only identifies operation names. Neither negotiates native feature support or returns a feature-qualified seller-owned offer. `simulate_delivery` supports property-row injection but does not inject observed format rows or time-view -measurements. The shipping resolver accepts only seed/discover, so `construct` +measurements. The pinned protocol-main SDK 15.9.5 resolver accepts only seed/discover, so `construct` is not an executable escape hatch here. Propose one additional sandbox scenario, **`prepare_product_feature`**, within diff --git a/specs/optional-product-feature-declarations/probes.test.cjs b/specs/optional-product-feature-declarations/probes.test.cjs index e4f0b47734e..23677bb7579 100644 --- a/specs/optional-product-feature-declarations/probes.test.cjs +++ b/specs/optional-product-feature-declarations/probes.test.cjs @@ -338,3 +338,32 @@ test('schema-valid distinct IDs with equal UTF-8 replacement bytes normalize los assert.deepEqual(collectionPairs(a), collectionPairs(b)); assert.equal(collectionPairs(a).length, 2); }); + +test('real product schema forbids publisher_domains on products, including alongside a singular domain', async () => { + for (const property of [ + { publisher_domains: ['host.example'], selection_type: 'all' }, + { publisher_domain: 'host.example', publisher_domains: ['other.example'], selection_type: 'all' }, + ]) { + const invalid = product('owner_sold_channel_carriage', { publisher_properties: [property] }); + assert.equal(validate.product(invalid), false); + const catalog = setup('owner_sold_channel_carriage', { catalog: [invalid] }); + assert.equal((await evaluate(catalog.args)).reason, 'invalid_catalog'); + const prepared = setup('owner_sold_channel_carriage', { + prepare: async params => ({ success: true, simulated: { ...params, product: invalid } }), + }); + assert.equal((await evaluate(prepared.args)).reason, 'invalid_qualified_setup'); + } +}); +test('domain-only product collection entries fail even when another concrete entry could otherwise qualify', async () => { + const invalid = product('collection_default_materialization', { collections: [ + { publisher_domain: 'owner.example' }, + { publisher_domain: 'owner.example', collection_ids: ['news'] }, + ] }); + assert.equal(validate.product(invalid), false); + const catalog = setup('collection_default_materialization', { catalog: [invalid] }); + assert.equal((await evaluate(catalog.args)).reason, 'invalid_catalog'); + const prepared = setup('collection_default_materialization', { + prepare: async params => ({ success: true, simulated: { ...params, product: invalid } }), + }); + assert.equal((await evaluate(prepared.args)).reason, 'invalid_qualified_setup'); +}); diff --git a/specs/optional-product-feature-declarations/review.md b/specs/optional-product-feature-declarations/review.md index 2afe581a1a0..716d891a23d 100644 --- a/specs/optional-product-feature-declarations/review.md +++ b/specs/optional-product-feature-declarations/review.md @@ -13,7 +13,7 @@ SDK 15.9.5 and lockfile: node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs ``` -The isolated suite has **67 tests**, including all 64 independent feature subsets. +The isolated suite has **69 tests**, including all 64 independent feature subsets. It compiles actual current product/selection/reporting schemas and the actual immutable 3.2.5 feature schema for old-reader acceptance, without editing them. Three tests execute the real pinned SDK: two runner probes with injected clients @@ -108,6 +108,36 @@ replacement bytes tie; it adds no schema restriction. The current isolated suite passes 67/67 locally; new exact-head CI will be observed separately. These fresh reviews support continued draft human review, not ratification or runtime safety. +## SDK API readiness and existing product-schema boundaries + +The owner reported draft adcp-client #3354 public exports and disposable build +instructions, plus 13 limitations re-established on SDK main `1977a1ba` / +`16.0.0-beta.9` before implementation. The first source head was reported to +contain two confirmed security defects and is superseded. This workspace has +read PR metadata/API reports only, has not installed or executed that candidate, +and awaits the exact review-fix SHA before disposable candidate qualification. +Owner baseline/fixed-suite counts remain reports, distinct from local installed +15.9.5 evidence and the separate pristine 15.9.6 comparison. + +Two new real-source-schema probes explicitly reject product `publisher_domains` +even alongside a singular domain, and domain-only collection entries even beside +a concrete otherwise-qualifying selector. Catalog and prepared setup failures +are retained; no fan-out or invalid-row salvage occurs. Local evidence is +**69/69**, including all 64 proposed declaration combinations. No field, controller, +model or SDK dependency implementation changed. + +The API-readiness table is conditional on exact-head qualification and upstream +AdCP authoring/operator/capture/check-kind amendments. It preserves every-lookup +direct/opaque authority and process-local identity/host-grant boundaries. Native +qualified-offer binding for the future seller-wide commitment remains an +additional WG/controller/runner decision; the catalog foundation alone does not +implement it. Fresh independent protocol, product/docs and code reviewers each +reran **69/69**, with no blocking/actionable findings; final code review of the +three changed files also passed `git diff --check` and returned **Ready to push**. +None fetched, installed, executed or reviewed candidate SDK source. Prior review +results retain their explicitly recorded earlier scope. These reviews qualify +only the proposal packet, not SDK implementation safety or WG ratification. + ## Still required for adoption The five normative choices at the end of the memo remain for humans/WG. Real From cd884d0b720e349e6ff1d29217e765c8bbbe9462 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Fri, 23 Oct 2026 05:58:22 +0000 Subject: [PATCH 5/5] docs(protocol): align fixture commitments with independent scopes --- .../optional-product-feature-declarations.md | 837 ++++++++---------- .../controller.schema.json | 2 +- .../examples.json | 6 +- .../features.schema.json | 38 +- .../model.cjs | 39 +- .../probes.test.cjs | 120 ++- .../review.md | 45 +- 7 files changed, 548 insertions(+), 539 deletions(-) diff --git a/specs/optional-product-feature-declarations.md b/specs/optional-product-feature-declarations.md index 8726d17abe8..a324fe573de 100644 --- a/specs/optional-product-feature-declarations.md +++ b/specs/optional-product-feature-declarations.md @@ -2,511 +2,370 @@ title: Seller-wide optional product-feature commitments class: normative status: proposed -date: 2026-10-19 -refs: ["#8254", "PR #8259", "PR #8336", "PR #7982", "PR #7973", "DR-0001", "DR-0009", "DR-0010"] +date: 2026-10-23 +refs: ["#8254", "PR #8428", "PR #8336", "PR #8259", "PR #8376", "DR-0001", "DR-0009", "DR-0010"] dissent: Human/WG decision outstanding; agent review is not ratification --- ## Decision -**Nonoperative future-minor proposal.** Approving investigation or opening this -PR does not ratify these clauses. This memo uses the decision-record format; -a DR number and decision provenance are assigned only through human review. -No production schema, storyboard, hosted disposition, or released artifact is -changed. The isolated schemas and executable model below are proposal evidence. +**Nonoperative future-minor proposal.** No capability/controller wire, +implementation assignment, release train or WG decision is adopted here. +The memo, schemas, examples and executable model are isolated proposal evidence. +A DR number and decision provenance require human review. Kickoff authorization, +source scenario IDs and merges of related work do not ratify this proposal. -Recommend six optional booleans under `media_buy.features`, with no defaults: +Recommend **eight** optional booleans under `media_buy.features`, with no defaults: -| Field | Commitment and qualifying product | Independent consumers | +| Proposed field | Qualifying native sandbox offer | Independent core consumer | | --- | --- | --- | -| `supports_collection_selection` | At least one product with nonempty explicit `collections`, `collection_targeting_allowed: true`, and at least two distinct domain-qualified collection pairs so proper-subset selection can be tested. | Strict-subset structured selection, persisted readback and invalid-selector rejection. Existing default obligations still bind on the product. | -| `supports_collection_default_materialization` | At least one product with one distinct `(publisher_domain, collection_id)` pair in explicit `collections`, regardless of selectable/fixed mode. | `mode: default` full-bundle materialization and persisted concrete readback; independent of a strict-subset fixture. | -| `supports_fixed_collection_bundles` | At least one multi-collection product with `collection_targeting_allowed` false or omitted (existing default false). | Exact full-bundle restatement, default materialization, proper-subset rejection. | -| `supports_owner_sold_channel_carriage` | At least one channel-owner offer referencing that owner's canonical channel collection and a different host publisher's property. | Owner/host selector boundary checks; buyer-side host authorization verification remains separate. | -| `supports_format_breakdown` | At least one product with `reporting_capabilities.supports_format_breakdown: true`. | Requested `format` dimension, `by_format`, truncation and applied-sort echoes; no required observations. | -| `supports_time_based_views` | At least one product listing `time_based_views` in `reporting_capabilities.available_metrics`. | Metric availability and narrowing, schema-valid threshold entries when observed, committed-array presence when contracted. | - -These are existential seller support commitments, never assertions about every -product. Default materialization and strict-subset selection qualify -independently: one distinct pair suffices for default coverage, while a genuine -strict subset needs two distinct pairs. Missing a two-pair fixture MUST NOT -suppress a one-pair default path. The two declarations do not make existing -readback obligations optional: a selected product's default/readback contract -still binds even when the separate seller-wide default commitment is absent or -false. Fixed-bundle subset enforcement needs its own two-pair fixed product and -must not depend on a selectable companion. Owner-sold offers can be fixed or -selectable: declaring owner-sold does not imply either of the other flags. -The owner-sold fixture uses the product's actual fixed/selectable behavior. -Format and time declarations are unrelated to each other or to creative-grain -reporting. Baseline requested-metric narrowing stays independently graded. - -The shared `media-buy-features.json` also types `get_products` -`filters.required_features`. Using these flags there selects **sellers**, as -existing property rollups do; it never filters to qualifying products, provisions -a fixture, or implies every returned product supports the feature. Buyers still -inspect product declarations. No new filter mechanism is proposed. - -The direct `collection_selection` path is distinct from hosted `collection_list` -and exclusion-list support. Their existing declarations continue to govern them; -these flags do not imply list-service, collection-card, placement-selection, -property-reporting, installment-reporting, or any new delivery-mode support. - -## Rationale - -Catalog-only applicability cannot certify support reachable only after sandbox -setup or through a brief. Generic `seed_product` accepting authored feature fields -does not establish native support. This proposal adds a clear support promise -and a separately specified setup commitment, rather than using seed refusal as -an unsupported-feature negotiation mechanism. - -Controlling authority: - -- [DR-0001](../governance/decisions/DR-0001-conformance-assertions-normative-basis.md): grade only normative/schema obligations. This memo is not yet such authority. -- [DR-0009](../governance/decisions/DR-0009-additional-properties-default-true.md): preserve existing object boundaries; validate known fields strictly. - `media-buy-features.json` specifically allows unknown **boolean** flags; do not - widen this to arbitrary objects. -- [DR-0010](../governance/decisions/DR-0010-fixture-handles-and-resolution.md): real seller identities, explicit strategies, pinned bindings, terminal supported-operation failures, visible exhausted-strategy gaps. -- [Product](../static/schemas/source/core/product.json), [targeting](../static/schemas/source/core/targeting.json), [collection selection](../static/schemas/source/core/collection-selection.json), [reporting capabilities](../static/schemas/source/core/reporting-capabilities.json) remain the product authority. -- [Delivery request](../static/schemas/source/media-buy/get-media-buy-delivery-request.json), [delivery metrics](../static/schemas/source/core/delivery-metrics.json), and [controller](../docs/building/by-layer/L3/comply-test-controller.mdx) bound what reporting evidence can prove. - -### Main, release, and adjacent-work inventory - -Verified on 2026-10-19 against main `c2f01a50f2133b016fc73ca74019c4c021f2256e`: -root package `3.2.1` is release machinery metadata, SDK pin **15.9.5**, -`.changeset/pre.json` is beta mode, stable latest is **v3.2.5**, and both -`changeset-release/main` (#7897) and `changeset-release/3.2.x` (#8274) are open. -The playbook says main is the future 3.3 line after GA; do not derive a release -number from root package metadata. The actual minor/train for this proposal is -**unassigned**, subject to WG and release-owner scheduling. No 3.2.x backport. - -| Work | Verified disposition and relationship | -| --- | --- | -| [#8254](https://github.com/adcontextprotocol/adcp/issues/8254), [#8259](https://github.com/adcontextprotocol/adcp/pull/8259) | Open; full proposal and discussion read. Catalog owner retains three existing YAMLs, independent fixed/time YAMLs, media-buy index, compliance docs/tests, patch changeset and proposal reconciliation. Owner coordination confirmed before edits. Catalog implementation lands main first; maintenance qualification stays separate. | -| [#7982](https://github.com/adcontextprotocol/adcp/pull/7982) | Merged 2026-10-07. Reuse `media_buy.features`, independent matching product flags, and empty-array/companion discipline. Its absent/false mean "no rollup claim," not "no products"; keep that compatibility. Do not copy rollup-only gating, which hides undeclared catalog evidence, or its specific property-row injection/suppression exemption into format/time support. | -| [#7973](https://github.com/adcontextprotocol/adcp/pull/7973) | Open draft held for 3.4. Delivery modes are a different axis. Do not import its parent-object/schema-default dependence, compound fail-closed gates, coverage removal from required specialisms, or low-coverage baseline substitution. No files shared. | -| [#7134](https://github.com/adcontextprotocol/adcp/pull/7134), [#8201](https://github.com/adcontextprotocol/adcp/issues/8201) | Collection storyboards and fixture-resolution prior art. Current source and shipping SDK inspected; no changes to their shared contracts here. SDK currently accepts only seed/discover resolution strategies, despite source discussion of construct. | -| [#7958](https://github.com/adcontextprotocol/adcp/pull/7958), [#8061](https://github.com/adcontextprotocol/adcp/pull/8061), [#8246](https://github.com/adcontextprotocol/adcp/pull/8246) | Open composable-breakdown, collection-list and installment-product proposals. Preserve current product vocabulary; recheck before any later source promotion. | -| [#8117](https://github.com/adcontextprotocol/adcp/pull/8117), [#8156](https://github.com/adcontextprotocol/adcp/pull/8156), [#7934](https://github.com/adcontextprotocol/adcp/pull/7934) | Open negotiated-response-version, undefined-property reporting and per-account readiness work. Do not presume their proposed rules are operative or infer entitlement from this technical support declaration. | - -All listed open adjacent proposals are authored by @bokelley. The scoped catalog -owner and root coordinator were contacted directly in their existing sessions; -this PR touches only its own proposal namespace and scoped evidence workflow. -Any later source overlap requires renewed file coordination with those owners. - -### Reconciled catalog prerequisites (nonoperative) - -The current foundation review packet is [#8259 at -`ce8a65d6bd192c105ef3175091f29c7f296e47b9`](https://github.com/adcontextprotocol/adcp/blob/ce8a65d6bd192c105ef3175091f29c7f296e47b9/specs/optional-product-feature-applicability/collection-prerequisite.md). -It supersedes earlier proposal-head references for this reconciliation; its new -exact-head CI must be observed separately. The owner reports 70 local probes, -code-review rerun of 70 and protocol rerun of 36. Those are owner/reviewer reports, -not reruns by this declarations workspace or implemented SDK qualification. - -The selected-fixture contract must normalize schema-valid atomic -`(publisher_domain, collection_id)` pairs before eligibility and deterministic -parent selection. Default/full-bundle materialization needs one distinct pair; -strict-subset and fixed-subset enforcement need two. Fixed accepts literal false -or the existing omitted-false default, not null/wrong types. Optional declared -cross-domain owner/host relations must qualify before selection and retain the -same selected product, scoped price and relation witness. Full concrete bundle, -real singleton strict subset and collision-checked absent-ID/absent-domain -negatives must derive from that complete selected set. One normalizer serves -eligibility, witnesses and namespace-set validation; schema-valid redundant pairs -normalize as a set, while schema-invalid duplicate outer selected objects fail. -Empty string collection IDs remain legal under current schemas. Wire-declared -relations do not verify ownership or host authorization. Added collection -scenario IDs remain provisional; this proposal adopts no new source filename. - -Product qualification retains two existing schema boundaries: every -`collections[]` entry on a product MUST carry explicit `collection_ids`; a -domain-only bulk grant is authorization scoping, not product composition. -Product `publisher_properties[]` entries MUST use singular `publisher_domain`; -`publisher_domains[]` is forbidden even when a singular domain is also present. -Do not fan it out or discard invalid entries to salvage a qualifying subset. -These are existing product requirements, not new declaration obligations. - -Protected captures need the proposed atomic write/delete/metadata funnel across -all context-write paths, detached immutable preparation state and deep-cloned -views against alias mutation, plus authenticated every-lookup tenant/caller/run/ -grant/revocation checks. These are separate foundation surfaces. The earlier -**NONE RECORDED / unconfirmed** ownership status is superseded by root's explicit -assignment of the focused #8259 implementation in `adcontextprotocol/adcp-client` -to [SDK catalog fixture foundation #8259](conductor://workspace?id=9bed7f0a-da60-44d8-a102-3586db378a8a), -session `7d85de47-008e-484b-8f14-2601c34f5725`, based on fresh main. Its authorized -output is a reviewed draft SDK source implementation for the contract at -`ce8a65d6bd192c105ef3175091f29c7f296e47b9`, with public integration and exact-head -contract/security evidence. Assignment is not implementation qualification: -this proposal has not reviewed an actual candidate implementation head. The -existing stable session remains reviewer-only; other owners retain their scopes. - -That focused foundation assignment does not authorize this proposal's capability -fields, `prepare_product_feature` controller wire contract, final collection IDs, -protocol dependency/lock/bridge adoption, maintenance changes, merge, publication -or release. Those remain separate decisions and qualification work. This PR -implements no SDK/DSL, protected state or authenticated lookup. Its small pair -normalizer is an isolated model helper, not a foundation API or evidence of -implemented capture/state safety. The declarations owner contacted the new SDK -owner directly to preserve this boundary before any shared API finalization. - -### Candidate SDK API readiness — implementation-head review pending - -The assigned SDK draft is [adcp-client #3354](https://github.com/adcontextprotocol/adcp-client/pull/3354), -based on SDK main `1977a1ba`, package `16.0.0-beta.9` in beta pre-mode, wire -`ADCP_VERSION: 3.2.5`. The owner reports re-establishing all 13 baseline -limitations on that base before implementation; its baseline file is a local -`.context` artifact, while repaired expectations are in four committed suites. -Those are owner reports, not reruns by this declarations workspace. Installed -protocol-main 15.9.5 evidence and the disposable pristine 15.9.6 comparison stay -separate; neither establishes a 16-beta limitation. SDK 14/9 remain unqualified. - -The first implementation was reported to have two confirmed security defects -and is superseded. **Await the exact review-fix SHA before any disposable build, -execution or candidate qualification.** No candidate SDK is installed here and -no dependency pin, lockfile or bridge changes. The following public API shape is -an owner-reported review input, not final code approval or a release dependency: - -| Surface reported by the SDK owner | Possible reuse after exact-head qualification | Remaining boundary | -| --- | --- | --- | -| `collection_selection_satisfies` with mode, optional minimum pairs and external-owner operand; shared normalization/witness helpers | Independent one-pair defaults, two-pair strict subsets, omitted-false fixed products and declared owner/host relations | No new collection IDs, seller capability fields, reporting scope or external authorization proof. | -| `fixture_resolution[].context_outputs` under the protected fixture namespace, exactly one of path or witness | Capture the same selected product/scoped price/relation after the complete graph resolves | Capture safety and schema legality require separate qualification; ordinary response context is not preparation authority. | -| `collection_set_equals_context` | Compare concrete namespace-qualified sets against protected expected state | New authored check kind must be adopted in the protocol authoring/output contracts before published use. | -| `prepareStoryboardFixtures`, `PreparedStoryboardFixtures`, trust checks and contract version; full/standalone `prepared_fixtures` options | Share qualified preparation with content/route/schema/scope/run bindings | Every lookup, direct state and opaque reference alike, requires live trusted authorization. Preparation alone does not fix standalone phase skipping. | - -The public CJS/ESM exports and disposable instructions are reported by the SDK -owner: build its exact safe candidate in ignored scratch space, pack it, and -resolve it in an isolated test root. Do not adopt its package in this workspace. -Coordinate exact exports and build instructions with that owner before consumer -source edits. Authored versus resolved selector types must preserve explicit -operand defaults; do not infer a new wire or negotiation meaning from them. - -The SDK candidate is not sufficient authoring authority by itself. An upstream -AdCP PR must amend the closed match-operator set and fixture-resolution capture -shape in `static/compliance/source/universal/storyboard-schema.yaml`, and add -`collection_set_equals_context` to `runner-output-contract.yaml` authored check -kinds before published storyboards can legally use them. These files remain with -their coordinated owners; this proposal edits none. Old-runner load rejection -must be qualified as the downgrade behavior, not a successful skipped feature. - -Trust is reported as SDK-owned runtime object identity: direct construction, -look-alikes, copied public bindings, frozen clones and JSON rehydration must not -acquire preparation authority. A process-local HMAC binds nonsecret credential -identity; tokens do not enter evidence and immutability is not portable trust. -Cross-process/serialized reuse requires authenticated reconstruction or a host -reference lookup with live scope checks. Host tenant/org session resolution and -grant/revocation storage remain host responsibilities behind the trusted -authorizer. Separate exact-head security evidence must verify both write/alias -isolation and authority on every direct/opaque lookup. No such implementation -safety is certified by this proposal or by an exported API list. - -This foundation changes no seller/controller wire and does not implement -`prepare_product_feature` or a seller-wide commitment. Future reuse still needs -an approved way to bind a native feature-qualified prepared offer, including a -brief-only/initially-empty seller, into the execution fixture graph. The current -API report is not proof that this additional route is implemented; it remains -part of #8333's WG/controller/runner decisions. Format/time reporting, commercial -context, branding, accounting and standalone `phase.skip_if` remain separately -qualified consumer work; no observations or grain injection follow. - -Held reporting [#8336 at -`8ccc1d62194b9b8e2a9b8d3b2543b20d145f67f6`](https://github.com/adcontextprotocol/adcp/pull/8336) -has exactly two current actual-source IDs: `media_buy_seller/advanced_delivery_reporting` -(format-only, literal product format-support true) and -`media_buy_seller/time_based_delivery_reporting` (time metric independently present). -Both discover native non-guaranteed products with compatible fixed CPM options, -resolve pricing from the same product graph, and fully validate/paginate before -selection. Only the isolated account is seeded; no feature products/prices are -seeded. No-match is an explicit coverage gap, never a pass or nonsupport proof. -Seeded-only, brief-only and commercial coverage limits remain disclosed. - -Commercial snapshot/minimum-spend, mature committed-time value-or-disclosure, -caller-brand, full/standalone and hosted disposition limits keep that draft held. -The owner reports 48 actual-source/public/hosted tests and 38 successful exact-head -checks plus five skips; the draft storyboard matrix is skipped. These counts do -not qualify runtime behavior or authorize shipping. The later #8259 public -evidence shows bounded same-read returned-row ordering and time value-or-disclosure -are already downstream-authorable, with timestamp/measurability/live-fallback, -standalone-flow and unobserved-population limits. They are not reasons to invent -new reporting observations or deterministic grain injection. Main 15.9.5 and a -disposable pristine 15.9.6 comparison remain separately scoped; no dependency -adoption follows. #8254 stays open. Maintenance qualification/merge, draft Version -Packages refresh (including #8274), publication and production actions remain held; -the #8302-only refresh exception does not extend to these drafts. +| `supports_collection_selection` | Selectable; at least two distinct domain-qualified pairs | `collection_selection`: strict subset and undeclared-selector rejection | +| `supports_collection_default_materialization` | Any collection mode; at least one pair | `collection_default_materialization`: concrete full-bundle default | +| `supports_fixed_bundle_enforcement` | Omitted/false selection flag; at least two pairs | `fixed_bundle_enforcement`: full set accepted, strict subset rejected | +| `supports_fixed_bundle_restatement` | Omitted/false selection flag; at least one pair | `fixed_bundle_restatement`: exact full-set restatement | +| `supports_cross_publisher_collection_restatement` | Any collection mode; at least one cross-publisher pair | `owner_sold_channel_carriage`: full set and selector boundaries | +| `supports_cross_publisher_collection_subset` | Selectable; at least two TOTAL pairs, including a cross-publisher pair | `owner_sold_channel_subset`: strict subset retains the external pair | +| `supports_format_breakdown` | Product `reporting_capabilities.supports_format_breakdown: true` | `advanced_delivery_reporting`: requested format breakdown | +| `supports_time_based_views` | Product metrics include `time_based_views` | `time_based_delivery_reporting`: metric accountability/narrowing | + +Consumer IDs above have the `media_buy_seller/` prefix. They identify independently +qualified behavior; their existence does not adopt these declaration fields. + +The earlier six-field draft grouped fixed restatement with enforcement and +ordinary declared carriage with selectable carriage subset. Those need different +fixture promises. A fixed one-pair supporter cannot provide a genuine strict +subset; a fixed or one-pair cross-publisher supporter cannot prove selectable +cross-publisher subset behavior. One smaller prepared offer must not certify the +larger path, and a missing larger fixture must not suppress smaller-path coverage. +This revision replaces the **unpublished provisional** +`supports_fixed_collection_bundles` with separate enforcement/restatement fields +and adds the subset commitment. Cross-publisher field names describe structural +restatement/subset behavior instead of the earlier provisional owner/channel +wording; the historical source IDs stay unchanged. This renames no published +field and needs no alias. +The eight-field choice is an exact recommendation for WG review, not adopted policy. + +All promises are existential, never claims that every product supports a feature. +False means no seller-wide promise, not product nonsupport. A product's own +obligations remain binding even when another rollup is absent/false. Thus a +selectable offer still owes default/readback behavior, an enforcement offer owes +full-set acceptance, and a cross-publisher subset offer still owes selector boundaries. +Independent booleans do not grant permission to violate related product MUSTs. + +The two optional readers, `collection_selection_readback` and +`collection_default_materialization_readback`, inherit the matching fixture scope +but have their own root `get_media_buys` gate. They need no new declaration. +A missing reader leaves core create coverage intact; an advertised broken reader +fails. A read requires trusted successful create history and exact buy/package/ +product/committed-selector identity. Failed-step context is not proof of success. +No new compulsory reader, portable grant, cross-request trust or retired-catalog +state guarantee is implied. + +These direct collection paths do not imply hosted collection lists, collection +cards, placement selection, property reporting, delivery modes or authorization. +Format/time promises are independent; baseline requested-metric narrowing stays +independently graded. In `get_products.filters.required_features`, the shared +feature fields select **sellers**, never qualifying products or fixture mutation. + +## Rationale and authority + +Catalog-only applicability cannot certify seeded-only/brief-only supporters +whose initial wholesale catalogs have no qualifying product. A generic +`seed_product` echo does not establish native support. The proposal adds an +explicit native-support and controlled-fixture promise, rather than turning seed +refusal into an unsupported-feature negotiation mechanism. + +- [DR-0001](../governance/decisions/DR-0001-conformance-assertions-normative-basis.md): grade only schema/normative obligations; this proposal is not operative authority. +- [DR-0009](../governance/decisions/DR-0009-additional-properties-default-true.md): preserve existing object boundaries. `media-buy-features.json` permits unknown **boolean** keys, not arbitrary unknown objects. +- [DR-0010](../governance/decisions/DR-0010-fixture-handles-and-resolution.md): pin seller-issued identities and whole graphs; supported discovery/setup failures are terminal; exhausted unavailable strategies leave visible coverage gaps. +- [Product](../static/schemas/source/core/product.json), [collection selection](../static/schemas/source/core/collection-selection.json), [targeting](../static/schemas/source/core/targeting.json) and [reporting capabilities](../static/schemas/source/core/reporting-capabilities.json) remain product authority. +- [Delivery request](../static/schemas/source/media-buy/get-media-buy-delivery-request.json), [metrics](../static/schemas/source/core/delivery-metrics.json) and [controller](../docs/building/by-layer/L3/comply-test-controller.mdx) bound what fixtures/reporting can prove. + +### Current source and release reconciliation + +The current collection implementation record is [#8428 at +`10e88cd4c68df8a9db3bc1ba6c79ceb61e52a8bd`](https://github.com/adcontextprotocol/adcp/blob/10e88cd4c68df8a9db3bc1ba6c79ceb61e52a8bd/specs/optional-product-collection-qualification.md), +based on reporting merge `3e94f5e376bae2911fe26373a8ff506908f1a765`. +It is non-draft with exact-head CI/reviews still to be assessed; this workspace +has read the memo, not rerun its actual-source or public SDK qualification. +Root owns the ordinary merge decision. The catalog owner retains all source, +grammar/output, caller, hosted, dependency/lock and checkpoint work. + +[#8259](https://github.com/adcontextprotocol/adcp/pull/8259) is closed as superseded; +its original `ce8a65d6bd192c105ef3175091f29c7f296e47b9` remains historical. +The SDK [foundation #3354](https://github.com/adcontextprotocol/adcp-client/pull/3354) +merged as `37d308768b01b99f4650800d5af7cfc051b40e9e` and the protocol +[authoring/output contract #8376](https://github.com/adcontextprotocol/adcp/pull/8376) +merged as `277e0a53517976726bbc69d1485de57944a284d4`. Earlier capacity holds, +provisional names and unimplemented-foundation descriptions are not current +readiness claims. Neither merge implements seller declarations or the new native +fixture commitment proposed below. Historical reviews do not qualify later code. + +The #8428 tree reports package `3.3.0-beta.0` and installed SDK **16.3.0**. +The original isolated proposal checkout/evidence baseline is main `c2f01a50f` +with SDK **15.9.5**; no dependency, lockfile or bridge is changed here. Probe names +print their actual installed SDK and verify the repository pin. Local results, +merge-check CI and upstream SDK probes must each retain their own version/head. +15.9.5 observations do not establish current 16.3 limitations. No SDK14/9 or +maintenance qualification is inferred. This feature's **future minor is +unassigned**; source package metadata is not a release decision. + +Reporting [#8336](https://github.com/adcontextprotocol/adcp/pull/8336) merged at +`3e94f5e376bae2911fe26373a8ff506908f1a765`. Native zero-row +`fixture_unsatisfied` artifacts are coverage gaps, not positive support evidence. +Format/time independence and current reporting limits remain. The collection +memo replaces the old catalog proposal as source-consumer authority; #8254 stays +open until its owner's remaining work is resolved. No maintenance, VP or release +action follows from this proposal. + +Adjacent [property rollups #7982](https://github.com/adcontextprotocol/adcp/pull/7982) +provide a sound placement/per-product-authority pattern. Do not inherit their +rollup-only absent/false N/A gating, which would hide catalog evidence, or apply +their property-specific injection/suppression rules to format/time. +[Delivery-mode #7973](https://github.com/adcontextprotocol/adcp/pull/7973) is a +separate proposal held to 3.4: avoid its missing-parent/schema-default and compound +fail-closed hazards, reduced specialism coverage and baseline substitution. +Other composable-breakdown, collection-list, installment and response-version +proposals must be rechecked with their owners before any later overlapping +source change; they are not authority for this draft's new semantics. + +### Selected graph, namespace and public SDK boundaries + +Use schema-valid atomic `(publisher_domain, collection_id)` pairs. Fixed accepts +only omitted or literal false flags; null/wrong types are schema failures. +Normalize legal grouping/order/redundancy as sets without erasing domains or +inventing nonempty-ID restrictions. Identical duplicate outer selected objects +still fail their schema. Every product collection entry requires explicit +`collection_ids`; authorization bulk grants are not product composition. +Product property selectors forbid `publisher_domains`, even alongside singular +`publisher_domain`. Do not fan out, skip malformed entries or salvage partial data. + +A structural cross-publisher relation exists only when a collection domain lies +outside **all** singular property publisher domains of the same product. Traverse +all selectors. Two total pairs may be one local and one external pair; the strict +subset retains the external pair. Historical `owner_sold_channel_*` names imply +neither channel kind, beneficial ownership, AOR, rights nor host authorization. +Those checks remain external. The model no longer invents a channel-kind witness +or proves a relation by comparing against just one property domain. + +SDK16.3's merged vocabulary uses the single direct `path: ''` +`collection_selection_satisfies` operand with `collection_targeting`, +`minimum_pairs`, `require_cross_publisher_collection`; witness vocabulary includes +`declared_selectors`, `strict_subset`, +`undeclared_collection_id_selectors`, `undeclared_publisher_domain_selectors`, +`cross_publisher_relation`, `distinct_pairs`, and `snapshot: selected_entity`. +The raw same-selected graph stays protected. Normalize full wire arrays outside +that raw capture, retain same-product/relation-qualified negative arrays, and +capture the SAME scoped pricing entity. A missing optional minimum stays absent; +no blanket `min_spend: present` applicability filter is valid. The caller can use +its budget intent with `max(intent, min_spend_per_package ?? 0)`, without inventing +seller terms or currency. + +The current catalog slice is native wholesale, non-guaranteed fixed-price CPM. +It does not qualify guaranteed/auction/brief-only/seeded-only offerings. Future +commitments must name a valid seller-supported commercial path; they do not +universally require that catalog slice. A valid offer outside a harness's +commercial/approval profile is an honest harness/precondition gap, not proof of +producer nonsupport or a setup-refusal excuse after agreed prerequisites hold. + +The #8428 memo retains durable repaired-behavior probes for SDK issues +[#3395](https://github.com/adcontextprotocol/adcp-client/issues/3395), +[#3396](https://github.com/adcontextprotocol/adcp-client/issues/3396) and +[#3397](https://github.com/adcontextprotocol/adcp-client/issues/3397): optional +resource-lifecycle false failure, missing authored context-key evidence, and +buyer feed restart. Their assertions fail naturally on the reported SDK16.3 +version. This workspace has not executed them; a failing repaired-behavior probe +is not a passing conformance regression. #3389 host-authorizer refusal, bare +standalone gate/phase behavior, #3382 caller projection/branding and #8416 hosted +coverage presentation remain separately bounded work. No new SDK assignment or +adoption is made here. ## Proposed normative language -The following MUST/SHOULD text is conditional on adoption in an assigned minor. - -1. A seller MAY emit any subset of the six fields. Every emitted known value - MUST be a boolean. Omitted fields, including an omitted `features` or - `media_buy` parent, mean **no seller-wide claim / unknown**, not unsupported. - `false` explicitly declines the seller-wide commitment; it does not deny - individual supporting products. `true` declares native technical support - and the sandbox fixture commitment below. Unknown future boolean keys MUST NOT be - interpreted as a known feature; existing feature-object compatibility is preserved. -2. A true declaration MUST be backed by at least one qualifying, bookable - sandbox offer through the seller's normal execution path. Initially empty, - nonqualifying wholesale, seeded-only and brief-only catalogs are permitted. - A seller MUST implement `prepare_product_feature` for every true feature, - advertise that scenario through `list_scenarios` when supported, and supply - a valid qualifying fixture on request. A fixture-only echo path that accepts - unsupported authored fields does not satisfy native execution support. -3. Each product remains authoritative for its own feature support. A seller - MUST honor every product-level declaration on a selected product regardless - of an absent or false seller-wide field. A supporting product alongside a - false rollup is not a contradiction. A true rollup alongside ordinary, - non-supporting products is also not a contradiction. A declaration is - contradicted when its promised setup cannot supply a qualifying fixture, - or selected qualifying behavior violates its existing product contract. -4. A runner MUST preserve catalog-based testing for absent/false declarations. - It MUST NOT replace that route with an equals-true gate over the whole - storyboard or infer schema defaults through missing parents. A true - declaration selects commitment testing even when initial catalog evidence - is empty. Catalog discovery is attempted only when wholesale is actually - supported; brief-only support cannot be wholesale-gated away. -5. Setup and behavior evidence MUST be reported separately. Harness inability - to dispatch a negotiated operation is an explicit untested/setup gap. A - promised operation advertised by the seller that refuses, malforms, returns - `UNKNOWN_SCENARIO`/`INVALID_PARAMS` on valid input, or supplies a nonqualifying - fixture is a producer commitment violation. It MUST NOT become - `not_applicable`, a pass, or fallback success. Missing promised operation - confirmed from the seller's tool/scenario surface is a commitment violation; - failure to inspect that surface is a harness gap. Harness errors and - malformed runner input MUST NOT be blamed on the producer. -6. No field conveys account authorization, commercial access, availability for - a particular buyer, or entitlement. Existing auth/account checks remain in - force. Fixtures use a prearranged, authorized, **feature-eligible** sandbox account; - a runner lacking one records that precondition gap. Establish eligibility - through ordinary account onboarding/operator setup evidence, not these - flags. A documented access denial before those preconditions hold is a - precondition gap; once they hold, setup refusal violates the promise. A bare - `INVALID_PARAMS` or post-failure assertion of ineligibility cannot alone - establish that gap or cancel the commitment. Metadata contains no credentials, tokens, - endpoint overrides, or entitlement assertions. Seller-provided terms, - account eligibility and selected pricing govern the fixture buy. +These clauses become normative only after adoption in an assigned minor. + +1. Sellers MAY emit any subset of the eight booleans. Absent fields or parents + mean **no seller-wide claim / unknown**, not unsupported. False declines a + seller-wide commitment without denying product support. True is explicit + producer opt-in to the feature and fixture promise after adoption, regardless + of self-reported implementation minor. Unknown boolean keys are ignored as + unknown features. Known non-booleans fail validation, never coercing to false. +2. Every true feature MUST be backed by at least one qualifying bookable offer + in the normal native sandbox execution path, and MUST support the proposed + `prepare_product_feature` operation for that scope. Initially empty and + brief-only catalogs are allowed. A fixture-only feature echo does not satisfy + native support. Historical extension collisions must be removed or adopted; + old schema acceptance alone is not semantic certification. +3. Product declarations remain authoritative on every selected product, + independent of rollups. A supporting product with absent/false rollup is not + a contradiction; nor is an ordinary product beside a true rollup. Failure to + supply a promised qualified offer or violation of selected product behavior + is a producer violation. It MUST NOT become unsupported/N/A or fallback success. +4. Runners MUST retain catalog testing for absent/false flags. A true flag with + no catalog match selects the commitment route without a wholesale gate. + Never equals-true-gate an entire existing product scenario or infer defaults + through missing capability parents. Each fixture graph qualifies independently. +5. Setup commitment and product behavior MUST have separate evidence. Missing + new runner capability cannot suppress existing catalog execution. Confirmed + missing promised operations violate the promise; inability to inspect or + dispatch is an honest harness gap. Even when catalog behavior passes, a + commitment is untested until valid preparation and its normal lifecycle run. +6. No flag conveys authorization, eligibility, availability or entitlement. + Establish a prearranged feature-eligible sandbox account and executable + commercial profile using ordinary onboarding/operator evidence, without + credentials or entitlement assertions in metadata. A documented unmet + precondition is a gap. After prerequisites hold, valid advertised refusal is + a commitment violation; a bare `INVALID_PARAMS` or post-failure assertion of + ineligibility cannot cancel the promise. Harness-authored malformed input + and unsupported execution profiles are not producer failures. ### Applicability and fixture state table -Evaluate each feature independently; never require a companion feature product. -Catalog availability below means a valid, fully paginated wholesale scan is -possible. A transport/protocol/schema/pagination failure after a supported scan -starts is terminal under DR-0010, not a no-match or a setup fallback. - -| Declaration | Catalog / precondition | Required next action | Outcome / evidence | -| --- | --- | --- | --- | -| absent, false, unknown key, or old seller | Qualifying catalog product | Pin real product and execute feature | Product obligations graded; seller-wide promise not inferred. | -| absent or false | Valid catalog, no qualifying product | No generic feature seed | `fixture_unsatisfied` coverage gap; N/A projection is no proof of nonsupport. | -| absent or false | Brief-only, no defined construction route | Do not invent wholesale or construct | Explicit discovery-precondition gap; unknown support. | -| true | Qualifying catalog product | Verify promised setup operation exists; pin and exercise product | Product feature graded; preparation explicitly untested until its separate commitment probe runs. | -| true | Empty/nonqualifying catalog or brief-only | Call negotiated feature setup, pin returned product | Grade normal purchase/readback/reporting independent of wholesale. | -| true | Setup operation absent, or valid advertised setup refused | Preserve failed response and commitment result | Producer violation, never N/A or fallback. | -| true | Setup succeeds with malformed/nonqualifying product | Stop before purchase | Producer violation with exact schema/qualification evidence. | -| true or selected product | Broken selected behavior | Retain validation/protocol failure | Producer behavior violation; no fallback or applicability reclassification. | -| any | Runner lacks new setup contract/schema, feature-eligible sandbox access, or required harness tool | Record missing precondition | Harness/setup gap, no compliance pass or producer accusation. | -| malformed known declaration | e.g. string `"true"`, null, array | Fail capability validation for known field | Invalid producer declaration; never coerce or ignore as false. | - -The reference model returns local evidence labels (`commitment_violation`, -`harness_gap`, `coverage_gap`, `behavior_violation`, `applicable`). These are -**not new wire errors or shipping runner-output enums**. Current hosted -[step disposition](../server/src/compliance/step-disposition.ts) maps synthetic -controller setup failures to `setup_gap` and unsupported seeds to N/A. Adoption -requires a separate assertion of the declaration obligation, with the failed -setup evidence attached. Global grading guards and baseline floors stay intact. -A missing runner contract or confirmed missing preparation operation cannot -silently remove existing product tests. Catalog behavior evidence and commitment -evidence are separate axes: a passing catalog path with preparation untested -MUST NOT certify the seller-wide commitment. Before certifying a true flag, a -runner MUST also execute valid preparation and exercise its returned fixture, -even when another product already qualified through catalog discovery. - -## Additional controller contract requiring a WG decision - -Current `seed_product` accepts permissive authored exemplars; `list_scenarios` -only identifies operation names. Neither negotiates native feature support or -returns a feature-qualified seller-owned offer. `simulate_delivery` supports -property-row injection but does not inject observed format rows or time-view -measurements. The pinned protocol-main SDK 15.9.5 resolver accepts only seed/discover, so `construct` -is not an executable escape hatch here. - -Propose one additional sandbox scenario, **`prepare_product_feature`**, within -`comply_test_controller`, using its existing account and success/error envelope: - -- Params: `feature` (one of the six scope identifiers below) and `fixture_id` - (nonempty run-scoped idempotency key, maximum 128 characters). No authored - product fields, selector strings, observed metrics, or credentials. -- Success: `success: true`, `simulated: {feature, fixture_id, product}`. `product` - MUST validate against current `core/product.json`, qualify for the requested - feature, and carry seller-issued identities and a usable pricing option. - The response does not supply trusted authorization attestations. Owner-sold - qualification also requires independent owner channel/host evidence from - canonical discovery/fixtures; the product alone cannot prove channel kind or - host authorization. -- Setup establishes an offer in the seller's real sandbox adapter path, with - disclosed product terms and sufficient test inventory. It may expose it only - through a brief; the returned full product is the binding input and purchases - use its seller-issued IDs. Wholesale listing is not newly required. Re-read - through the normal buyer lifecycle; do not grade only the controller echo. -- `fixture_id` is scoped by authenticated principal and sandbox account; the - feature is immutable request content, not part of the key namespace. - An exact retry returns the same offer and terms during the run; reusing a key - for a different feature is `INVALID_PARAMS` with no mutation. Runners MUST - generate fresh, run-unique fixture IDs. Isolation is enforced across principals - and accounts; reusing the same key in the same principal/account namespace is - a retry, not a separately isolated run. Setup validates before mutation. Cleanup follows - normal sandbox TTL/ownership rules, never a production reset. -- False/absent commitments do not require this scenario. Unknown scenario names - retain `UNKNOWN_SCENARIO`. A known scenario with unknown feature or malformed - params returns `INVALID_PARAMS`; that code still means invalid input or unmet - precondition, never "feature unsupported." A true feature's valid setup refusal - is evidence of a violated promise, not a new interpretation of the error. - An uncommitted feature is not probed through this operation. -- Scope identifiers: `collection_selection`, `collection_default_materialization`, - `fixed_collection_bundles`, - `owner_sold_channel_carriage`, `format_breakdown`, `time_based_views`. - -The isolated [declaration schema](optional-product-feature-declarations/features.schema.json) -is the proposed additive `core/media-buy-features.json` properties fragment. -It is merged into the existing properties for evidence validation, preserving -existing structured features and the unknown-boolean constraint. -The [controller schema](optional-product-feature-declarations/controller.schema.json) -defines the proposed params and `simulated` payload, referencing the real product -schema. It is not installed into the published controller schema. A runner must -explicitly advertise/enable a future `product_feature_commitments_v1` harness -contract before using this route; its eventual runner-output representation and -SDK implementation are still required. This name is a proposal, not a working -SDK contract. There is no storyboards-schema edit in this PR. - -### Reporting limits - -A declaration and prepared product establish technical support and a valid -execution fixture, not observed reporting grains. Format checks require the -requested supported array (possibly empty), truncation disclosure and actual -applied-sort echoes. Never require a video format, first-row identity, positive -row count, or `truncated: true` from generic delivery simulation. Sorting remains -before requested-metric narrowing; existing fallback rules apply. - -Time-view thresholds may be any positive seller-defined number; two/six seconds -are recommendations. A valid three-second `in_view` entry is acceptable. Check -unique `(threshold_seconds, basis)` pairs when entries exist and do not sum -bases. `available_metrics` alone does not guarantee every uncommitted metric -is measurable on every report. Missing values follow existing omission and -`missing_metrics` rules. Contracting `time_based_views` binds accountability for its array carrier or -the applicable `missing_metrics` disclosure under existing maturity/measurability -rules; it does not force observations or bind particular thresholds. An empty -observed array remains valid where the carrier is appropriate. A feature -declaration alone supplies neither a matured commitment nor its timestamp. -The isolated reporting probes exercise these limits without injecting grains. - -If the WG wants deterministic nonempty observations, it needs a **separate** -controller amendment specifying package attribution, accepted format/threshold -rows, replace/add semantics, dates, reconciliation, suppression, idempotency, -validation and request-narrowing behavior. This PR neither chooses nor requires -that amendment; #7982's property-specific injection is not such a contract. - -## Compatibility, migration and implementation plan - -Major-version negotiation remains unchanged: `adcp_major_version` chooses a -major; feature checks determine minor additions. Do not invent a minor request -pin, use deployment version strings as capability gates, or treat #8117 as law. -A new client with an old seller keeps catalog testing when these fields are -absent. An old client validates new fields through open objects and ignores -unknown keys. An old runner cannot certify the new commitment; it keeps its -existing catalog coverage and must not issue unknown setup calls. A seller on -an older release is not required to emit these fields or add a `media_buy` -parent. Unknown future capability keys are not proof of this contract. -After adoption, emitting a standardized field as `true` is the explicit producer -opt-in, regardless of self-reported implementation minor. There is no hidden -handshake or second version marker. Historical snapshots from before adoption -are not retroactively certified; older implementations with a colliding custom -boolean name must remove it or adopt this contract before opting in. An old -schema accepting that boolean is not itself semantic certification. - -1. Preserve the separately owned held catalog drafts and their qualification holds; - a 3.2.x backport requires a qualified main merge and separate actual-pin review. - Retain its independent feature graphs, seller-derived selectors/pricing, - omitted-false bundle handling and current reporting guarantees. -2. Ratify exact fields, existential semantics and setup commitment. Assign a - future minor after the release owner confirms the train; do not copy #7973's - 3.4 hold as a release assignment for this design. New stable optional fields - plus new opt-in MUSTs are Normative/minor, not patch errata. Sellers making - no claim keep their existing contracts. -3. In a coordinated implementation PR add six properties to - `static/schemas/source/core/media-buy-features.json`, document the clauses in - `docs/protocol/get_adcp_capabilities.mdx`, add the controller scenario/params - and docs, implement native fixture preparation in the reference seller, and - qualify schema/MCP projection without changing dependency pins or limits. - Use a real descriptive `.changeset/optional-product-feature-commitments.md`: - - ```yaml - --- - "adcontextprotocol": minor - --- - Add optional seller-wide product-feature commitments and sandbox feature-qualified fixture preparation. Preserve catalog-based coverage for undeclared sellers. - ``` - - That changeset is intentionally **not active in this proposal-only PR**; - policy forbids versioning a nonoperative spec experiment as shipped protocol. -4. After explicit implementation assignment and contract approval, add the - runner setup/evidence contract in its owning SDK and qualify the actual - pinned SDK and real source storyboards, and integrate a declaration assertion - that cannot be hidden by controller prerequisites. Coordinate shared files - with #8254 before promotion. Do not create equals-true or compound gates that - exclude undeclared sellers or remove required-specialism coverage. -5. During rollout, use catalog evidence for absent/false and commitment setup - for true/no-catalog. Deduplicate execution when both routes select the same - feature/product. Test unrelated product declarations even when the rollup - declines a claim. Display harness gaps, violations and catalog limitations - separately. After SDK qualification, sellers opt in per independent feature; - registries/buyers gain pre-discovery routing hints but still inspect products. -6. Run source schema/docs parity, controller unit/integration and MCP projection - checks, source-storyboard contract tests, hosted disposition tests, normal - matrix and required CI on the exact implementation head. Do not change - global guards/floors, immutable records, maintenance branches or release - automation. Human/WG/path review remains mandatory; no automatic merge. - -Existing sellers pay no mandatory migration cost. Opted-in sellers implement -one preparation scenario with a branch per true feature plus normal product -execution. Buyers may ignore the flags; certifiers and SDK owners pay the -routing/evidence cost. The setup obligation is deliberately stronger than a -passive rollup and makes empty-catalog support testable. A remote assertion -cannot prove how a producer implemented its adapter; lifecycle probes catch -wire-visible divergence, while native-support honesty remains an attestation. - -## Executable evidence and review boundary - -Run from the repository root: +Evaluate every scope independently. Valid, complete wholesale no-match differs +from unavailable wholesale. A transport/protocol/schema/pagination/capture failure +after supported discovery starts is terminal under DR-0010, not a no-match. + +| Declaration / condition | Action | Evidence | +| --- | --- | --- | +| Absent/false; qualifying catalog | Pin same graph and exercise product | Existing product obligations graded | +| Absent/false; valid complete no-match | No invented feature seed | `fixture_unsatisfied` coverage gap, no nonsupport proof | +| Absent/false; brief-only and no defined construction | Do not force wholesale | Discovery-precondition gap, unknown support | +| True; qualifying catalog | Run product and separate preparation probe | Catalog pass alone leaves preparation untested | +| True; empty/nonqualifying/brief-only | Prepare exact feature scope, then execute normal lifecycle | Independent feature/commitment evidence | +| True; advertised valid setup refusal, transport failure or confirmed missing operation | Preserve response/operation evidence | Producer commitment violation, no fallback/N/A | +| True; malformed/nonqualifying prepared offer | Stop before purchase | Producer violation with exact schema/qualification cause | +| Any selected offer; broken selected behavior | Retain failure | Behavior violation; no applicability reclassification | +| Any; missing harness/access/commercial profile/trusted read history | Stop affected operation, retain independent core tests | Honest precondition gap; no pass or producer accusation | +| Known declaration has null/string/array/object value | Fail known-field validation | Invalid producer declaration | +| Optional reader absent / advertised reader broken | Root-gate reader only / retain reader failure | Core coverage survives / behavior violation | + +Model labels such as `commitment_violation`, `harness_gap`, `coverage_gap` and +`behavior_violation` are local proposal evidence, not new wire errors or shipping +runner-output kinds. Current hosted setup projection is not rewritten here. +Adoption needs an explicit declaration assertion retaining setup evidence rather +than silently relying on a setup-gap/N/A projection. Global guards/floors stay intact. + +## Proposed controller and runner addition + +The merged foundation can resolve catalog products and prices and protect +preparation. It still does not negotiate native feature support or supply an +initially absent, feature-qualified offer. Generic `seed_product` and +`list_scenarios` do not close this gap. No existing error code is repurposed. + +Propose one additional sandbox scenario `prepare_product_feature`: + +- Params: `feature` (one of the eight proposed field names without `supports_`) + and `fixture_id` (nonempty run-unique key, at most 128 characters). No authored + product, selectors, observations, credentials or endpoint overrides. +- Success retains the existing controller envelope: + `success: true, simulated: {feature, fixture_id, product}`. Product MUST be a + complete valid product with seller-issued identities and usable scoped price, + native support and sufficient agreed test inventory. It may be brief-only. + Normal purchase/readback must use its actual selectors/commercial terms. +- `fixture_id` is namespaced by authenticated principal and sandbox account; + feature is immutable content. Exact retries return the same offer/terms during + the run. Same key/different feature is `INVALID_PARAMS` without mutation. + Another run needs a fresh key; cross-principal/account isolation is mandatory. + Validation precedes mutation, cleanup uses sandbox ownership/TTL, never reset. +- False/absent flags do not require this operation. Unknown scenario names keep + `UNKNOWN_SCENARIO`; malformed/unknown feature params keep `INVALID_PARAMS`. + A true scope's valid refusal violates the promise; neither code means optional + support negotiation. Uncommitted scopes are not probed through this operation. + +The [features fragment](optional-product-feature-declarations/features.schema.json) +and [controller fragment](optional-product-feature-declarations/controller.schema.json) +are not installed into production schemas. Validation merges the former with +existing structured fields and unknown-boolean bounds. A future runner contract, +provisionally `product_feature_commitments_v1`, must bind the native returned +offer into the same pinned graph without requiring wholesale rediscovery that +would exclude brief-only products. Its authenticated preparation, evidence and +failure semantics need WG/SDK/caller review. No new assignment or implementation +is implied by naming that contract. + +Reuse qualified same-selected capture/set semantics and per-lookup scope checks, +without asserting a host grant service, portable authenticated JSON or durable +cross-request trust. Direct state and opaque references need their real authority +boundaries. #8428's successful-create and invocation-local semantics do not +certify retired catalog reuse. Reader companions remain optional by tool. + +### Reporting guarantees + +A feature declaration/fixture does not inject observed reporting grains. +Requested supported format arrays may be empty, with required truncation and +applied-sort companions. Do not demand a format kind, first row, positive count, +forced truncation or selection from an unobserved larger population. Sorting +precedes metric narrowing under existing rules; narrowing stays independently +binding across metrics-bearing containers. + +Time thresholds may be any positive seller-defined value; two/six seconds are +recommendations. A valid three-second `in_view` entry is acceptable, and +`(threshold_seconds, basis)` pairs are unique when emitted. Do not sum bases. +`available_metrics` is not proof of a matured commitment or timestamp. Contracted +arrays require the carrier or applicable missing-metric disclosure under current +maturity/measurability rules; empty observations remain legal where appropriate. + +Deterministic nonempty format/time injection would require a separate controller +design specifying attribution, dates, replace/add, reconciliation, suppression, +validation and narrowing. #7982 property injection is not that design, and this +proposal neither chooses nor requires it. + +## Implementation, compatibility and WG decisions + +Major-version negotiation stays unchanged; no minor request pin is invented. +Old sellers need no new parent/flags; new clients keep their catalog route. +Old clients accept unknown boolean additions, and old runners retain existing +coverage without certifying the new promise. Unsupported future runner contracts +must leave visible gaps; unknown check load behavior must not become a pass. + +1. Ratify eight scopes/names and the combined native-support/fixture promise, + or choose a separately advertised fixture commitment. Passive rollups alone + leave the seeded-only/brief-only certification gap. +2. Ratify exact controller retry/qualification/evidence semantics and the native + offer-binding runner route, including honest commercial/profile gaps. +3. Schedule a future minor with release owners. Optional fields and new opt-in + MUSTs are Normative/minor, not patch errata or a 3.2.x backport. No changeset + is active in this nonoperative proposal; an implementation needs a descriptive + `.changeset/optional-product-feature-commitments.md` with + `"adcontextprotocol": minor`. +4. Coordinate an implementation touching only approved source schemas/docs, + controller and qualified caller/SDK paths. Preserve #8428 independent graphs, + optional reader roots, same-product prices and current reporting guarantees. + Do not reopen its merge/SDK/pin/checkpoint ownership from this workspace. +5. During rollout, keep catalog evidence for absent/false and exact commitment + setup for true/no-match. Deduplicate only actual same-feature/same-product + execution; do not suppress independent smaller/larger paths. Display gaps, + violations and untested commercial/catalog slices separately. +6. Qualify actual source schema/docs/controller, public full/standalone caller, + exact pinned SDK, hosted disposition and CI. Treat #3395/#3396/#3397 and + other bounded limitations honestly; no accounting or baseline weakening. + +Existing sellers incur no mandatory migration. Opted-in sellers implement one +operation branch per true scope plus native execution. Buyers may ignore flags; +certifiers/SDK/caller owners pay routing/evidence costs. Eight booleans make +independent coverage explicit; whether that adoption cost warrants a smaller +profile/array surface is a WG choice, not hidden by a broad six-flag claim. +Wire-visible tests cannot prove internal native implementation: that remains an +attestation backed by lifecycle evidence, not generic seed acceptance. + +Exact unresolved choices: the eight field names/granularity versus a reviewed +alternative; coupling support and fixtures; the native offer-binding/evidence +contract; retaining current reporting guarantees versus separate grain injection; +and release/certification activation after real implementation qualification. +Human/WG/path approval is still required; no agent review substitutes for it. + +## Executable proposal evidence ```bash node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs ``` -[Probes](optional-product-feature-declarations/probes.test.cjs) combine an -isolated proposed commitment state machine with real source-schema validation -and separate SDK 15.9.5 runner and old-controller behavior checks. The model uses injected in-memory -sellers. It is **not** an implemented SDK feature, actual repaired storyboard, -hosted certification run, production adapter test or 3.2.x qualification. -Tests cover declarations, mixed feature subsets, valid catalog and empty/brief -setup, honest harness gaps versus refusal/invalid setup, selected-path failures, -old clients/servers, schema openness, reporting emptiness and threshold freedom. -The SDK probes pin present gate/default and unsupported-setup hazards rather -than claiming the proposed routing already exists. Exact review findings and -commands are recorded in [review evidence](optional-product-feature-declarations/review.md). - -## Unresolved normative choices for human/WG review - -1. Adopt the six field names and independent qualification, including a one-pair - default path separate from two-pair subset selection and owner-sold independent - of selectability? -2. Adopt existential native support **plus** mandatory feature-qualified sandbox - preparation for true declarations, or split technical-support rollups from - an independently advertised fixture commitment? Recommendation: one explicit - opt-in commitment per feature as specified; passive rollups leave the original - seeded-only certification gap unresolved. -3. Adopt the exact `prepare_product_feature` params/result, retry scope and - violation treatment? Its native-offer promise and new runner assertion require - WG approval and SDK implementation; existing error semantics stay intact. -4. Keep reporting observations optional under current guarantees, or commission - a separate deterministic grain-injection design? Recommendation: keep current - guarantees; injection must not block this commitment design. -5. Confirm release scheduling, evidence representation and the point at which - opting in becomes certifiable after real SDK/source-storyboard qualification. - No agent review substitutes for WG ratification, human/path approval or CI. +[Probes](optional-product-feature-declarations/probes.test.cjs) use real local +source/released schemas, an isolated proposed state machine and injected-client +SDK checks. All 256 field combinations are exercised. They do not execute #8428's +actual source/caller suite or implement the new controller/native route. Concrete +vectors cover selection/default/readback shape, fixed rejection, schema boundaries, +empty reporting and threshold freedom. SDK gates are labeled with actual runtime +version; this checkout's local pin remains 15.9.5, while upstream source uses16.3. +No candidate build/install, dependency change or SDK defect qualification occurs. +Exact commands, counts, versions and independent findings are in the +[review record](optional-product-feature-declarations/review.md). diff --git a/specs/optional-product-feature-declarations/controller.schema.json b/specs/optional-product-feature-declarations/controller.schema.json index ada1f9cf9ca..bd12d2ac044 100644 --- a/specs/optional-product-feature-declarations/controller.schema.json +++ b/specs/optional-product-feature-declarations/controller.schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "title": "PROPOSED prepare_product_feature payload fragments; not published", "definitions": { - "feature": { "type": "string", "enum": ["collection_selection", "collection_default_materialization", "fixed_collection_bundles", "owner_sold_channel_carriage", "format_breakdown", "time_based_views"] }, + "feature": { "type": "string", "enum": ["collection_selection", "collection_default_materialization", "fixed_bundle_enforcement", "fixed_bundle_restatement", "cross_publisher_collection_restatement", "cross_publisher_collection_subset", "format_breakdown", "time_based_views"] }, "fixture_id": { "type": "string", "minLength": 1, "maxLength": 128, "x-entity": "product_feature_fixture" }, "params": { "type": "object", diff --git a/specs/optional-product-feature-declarations/examples.json b/specs/optional-product-feature-declarations/examples.json index 2cfa744a183..7c75612c678 100644 --- a/specs/optional-product-feature-declarations/examples.json +++ b/specs/optional-product-feature-declarations/examples.json @@ -3,8 +3,10 @@ "declarations": { "supports_collection_selection": true, "supports_collection_default_materialization": true, - "supports_fixed_collection_bundles": false, - "supports_owner_sold_channel_carriage": true, + "supports_fixed_bundle_enforcement": false, + "supports_fixed_bundle_restatement": true, + "supports_cross_publisher_collection_restatement": true, + "supports_cross_publisher_collection_subset": false, "supports_format_breakdown": false, "supports_time_based_views": true }, diff --git a/specs/optional-product-feature-declarations/features.schema.json b/specs/optional-product-feature-declarations/features.schema.json index 950c8e24a36..a8fb0a72ea6 100644 --- a/specs/optional-product-feature-declarations/features.schema.json +++ b/specs/optional-product-feature-declarations/features.schema.json @@ -3,12 +3,38 @@ "title": "PROPOSED additions to media_buy.features; not published", "type": "object", "properties": { - "supports_collection_selection": { "type": "boolean", "description": "Opt-in native strict-subset selection and qualified sandbox fixture commitment with at least two distinct domain-qualified pairs; existing product default-readback obligations still bind." }, - "supports_collection_default_materialization": { "type": "boolean", "description": "Opt-in native full-bundle default materialization and qualified sandbox fixture commitment with at least one distinct domain-qualified pair; independent of strict-subset fixtures." }, - "supports_fixed_collection_bundles": { "type": "boolean", "description": "Opt-in native fixed-collection bundle support and qualified sandbox fixture commitment; independent of selectable products." }, - "supports_owner_sold_channel_carriage": { "type": "boolean", "description": "Opt-in native owner-sold channel carriage support and qualified sandbox fixture commitment; no entitlement or authorization assertion." }, - "supports_format_breakdown": { "type": "boolean", "description": "Opt-in native format-grain reporting support and qualified sandbox fixture commitment; no required observed rows." }, - "supports_time_based_views": { "type": "boolean", "description": "Opt-in native time-threshold view reporting support and qualified sandbox fixture commitment; no prescribed thresholds or observations." } + "supports_collection_selection": { + "type": "boolean", + "description": "Opt-in native strict-subset selection and qualified sandbox fixture commitment with at least two distinct domain-qualified pairs; existing product default-readback obligations still bind." + }, + "supports_collection_default_materialization": { + "type": "boolean", + "description": "Opt-in native full-bundle default materialization and qualified sandbox fixture commitment with at least one distinct domain-qualified pair; independent of strict-subset fixtures." + }, + "supports_fixed_bundle_enforcement": { + "type": "boolean", + "description": "Opt-in fixed-bundle strict-subset enforcement and qualified sandbox fixture commitment with at least two distinct domain-qualified pairs; independent of one-pair restatement." + }, + "supports_fixed_bundle_restatement": { + "type": "boolean", + "description": "Opt-in fixed full-bundle restatement and qualified sandbox fixture commitment with at least one distinct domain-qualified pair; independent of two-pair enforcement." + }, + "supports_cross_publisher_collection_restatement": { + "type": "boolean", + "description": "Opt-in full-set restatement and selector-boundary behavior for cross-publisher collections, with a qualified sandbox fixture commitment with at least one pair outside every product property publisher domain; no ownership or authorization proof." + }, + "supports_cross_publisher_collection_subset": { + "type": "boolean", + "description": "Opt-in selectable cross-publisher strict-subset behavior and qualified sandbox fixture commitment with two total distinct pairs, retaining an external pair; no ownership or authorization proof." + }, + "supports_format_breakdown": { + "type": "boolean", + "description": "Opt-in native format-grain reporting support and qualified sandbox fixture commitment; no required observed rows." + }, + "supports_time_based_views": { + "type": "boolean", + "description": "Opt-in native time-threshold view reporting support and qualified sandbox fixture commitment; no prescribed thresholds or observations." + } }, "additionalProperties": true } diff --git a/specs/optional-product-feature-declarations/model.cjs b/specs/optional-product-feature-declarations/model.cjs index 1efbfd15f44..a8c6ac19b27 100644 --- a/specs/optional-product-feature-declarations/model.cjs +++ b/specs/optional-product-feature-declarations/model.cjs @@ -52,20 +52,27 @@ function collectionPairs(selectors) { compareWireStrings(a[0], b[0]) || compareWireStrings(a[1], b[1])); } -// These predicates are proposed fixture qualification, not universal new product -// requirements. Owner channel/host evidence is separate from the product shape. -function qualifies(feature, product, ownerEvidence) { +// A structural declared relation, not ownership, channel-kind or authorization +// evidence. The collection domain must be outside ALL same-product domains. +function crossPublisherPair(product) { + const domains = new Set((product.publisher_properties ?? []).map(p => p.publisher_domain)); + if (!domains.size) return undefined; + return collectionPairs(product.collections).find(([domain]) => !domains.has(domain)); +} + +// Proposed fixture qualification over a schema-valid product. No new universal +// product requirements or public SDK matcher implementation is supplied here. +function qualifies(feature, product) { const report = product.reporting_capabilities ?? {}; + const count = collectionPairs(product.collections).length; + const fixed = product.collection_targeting_allowed === undefined || product.collection_targeting_allowed === false; switch (feature) { - case 'collection_selection': return collectionPairs(product.collections).length >= 2 && product.collection_targeting_allowed === true; - case 'collection_default_materialization': return collectionPairs(product.collections).length >= 1; - case 'fixed_collection_bundles': return collectionPairs(product.collections).length >= 2 && product.collection_targeting_allowed !== true; - case 'owner_sold_channel_carriage': return Boolean(ownerEvidence - && ownerEvidence.product_id === product.product_id - && ownerEvidence.kind === 'channel' - && ownerEvidence.owner_domain !== ownerEvidence.host_domain - && collectionPairs(product.collections).some(([domain, id]) => domain === ownerEvidence.owner_domain && id === ownerEvidence.collection_id) - && product.publisher_properties?.some(s => s.publisher_domain === ownerEvidence.host_domain)); + case 'collection_selection': return count >= 2 && product.collection_targeting_allowed === true; + case 'collection_default_materialization': return count >= 1; + case 'fixed_bundle_enforcement': return count >= 2 && fixed; + case 'fixed_bundle_restatement': return count >= 1 && fixed; + case 'cross_publisher_collection_restatement': return Boolean(count >= 1 && crossPublisherPair(product)); + case 'cross_publisher_collection_subset': return Boolean(count >= 2 && product.collection_targeting_allowed === true && crossPublisherPair(product)); case 'format_breakdown': return report.supports_format_breakdown === true; case 'time_based_views': return report.available_metrics?.includes('time_based_views') === true; default: return false; @@ -74,7 +81,7 @@ function qualifies(feature, product, ownerEvidence) { // Catalog may be null when no wholesale surface exists. Exceptions after an // attempted advertised operation are terminal; this model never falls back. -async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidence, +async function evaluate({ feature, capabilities = {}, catalog = [], harness = true, sandbox = true, operation = true, prepare, exercise = async () => true, validate }) { if (!features.includes(feature)) throw new Error('Unknown model feature'); if (capabilities.media_buy !== undefined && (!capabilities.media_buy || typeof capabilities.media_buy !== 'object' || Array.isArray(capabilities.media_buy))) { @@ -85,7 +92,7 @@ async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidenc if (!sandbox) return { state: 'harness_gap', reason: 'sandbox_precondition' }; const promised = declarations[`supports_${feature}`] === true; if (catalog && catalog.some(p => !validate.product(p))) return { state: 'behavior_violation', reason: 'invalid_catalog' }; - let product = catalog?.filter(p => qualifies(feature, p, ownerEvidence)) + let product = catalog?.filter(p => qualifies(feature, p)) .sort((a, b) => compareWireStrings(a.product_id, b.product_id))[0]; let route = 'catalog'; if (!product && !promised) return { state: 'coverage_gap', reason: catalog === null ? 'no_wholesale_surface' : 'fixture_unsatisfied' }; @@ -100,7 +107,7 @@ async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidenc if (response?.success !== true) return { state: 'commitment_violation', reason: 'setup_refused', response }; if (!validate.simulated(response.simulated) || response.simulated.feature !== feature || response.simulated.fixture_id !== params.fixture_id - || !qualifies(feature, response.simulated.product, ownerEvidence)) { + || !qualifies(feature, response.simulated.product)) { return { state: 'commitment_violation', reason: 'invalid_qualified_setup' }; } product = response.simulated.product; @@ -115,4 +122,4 @@ async function evaluate({ feature, capabilities = {}, catalog = [], ownerEvidenc } catch { return { state: 'behavior_violation', reason: 'selected_protocol', route, ...(commitment && { commitment }) }; } } -module.exports = { features, validators, collectionPairs, qualifies, evaluate }; +module.exports = { features, validators, collectionPairs, crossPublisherPair, qualifies, evaluate }; diff --git a/specs/optional-product-feature-declarations/probes.test.cjs b/specs/optional-product-feature-declarations/probes.test.cjs index 23677bb7579..df3239e99e9 100644 --- a/specs/optional-product-feature-declarations/probes.test.cjs +++ b/specs/optional-product-feature-declarations/probes.test.cjs @@ -4,7 +4,8 @@ const test = require('node:test'); const assert = require('node:assert/strict'); const Ajv = require('ajv'); const { runStoryboard } = require('@adcp/sdk/testing'); -const { features, validators, collectionPairs, qualifies, evaluate } = require('./model.cjs'); +const sdkVersion = require('@adcp/sdk/package.json').version; +const { features, validators, collectionPairs, crossPublisherPair, qualifies, evaluate } = require('./model.cjs'); let validate; test.before(async () => { validate = await validators(); }); @@ -18,21 +19,20 @@ function product(feature, extra = {}) { reporting_capabilities: { available_reporting_frequencies: ['daily'], expected_delay_minutes: 0, timezone: 'UTC', supports_webhooks: false, available_metrics: ['impressions', 'spend'], date_range_support: 'date_range' }, }; - if (['collection_selection', 'collection_default_materialization', 'fixed_collection_bundles', 'owner_sold_channel_carriage'].includes(feature)) { + if (['collection_selection', 'collection_default_materialization', 'fixed_bundle_enforcement', 'fixed_bundle_restatement', 'cross_publisher_collection_restatement', 'cross_publisher_collection_subset'].includes(feature)) { value.collections = [{ publisher_domain: 'owner.example', collection_ids: ['news', 'music'] }]; - if (feature === 'collection_selection' || feature === 'collection_default_materialization') value.collection_targeting_allowed = true; - if (feature === 'collection_default_materialization') value.collections[0].collection_ids = ['news']; + if (feature === 'collection_selection' || feature === 'collection_default_materialization' || feature === 'cross_publisher_collection_subset') value.collection_targeting_allowed = true; + if (['collection_default_materialization', 'fixed_bundle_restatement', 'cross_publisher_collection_restatement'].includes(feature)) value.collections[0].collection_ids = ['news']; } if (feature === 'format_breakdown') value.reporting_capabilities.supports_format_breakdown = true; if (feature === 'time_based_views') value.reporting_capabilities.available_metrics.push('time_based_views'); return { ...value, ...extra }; } -const ownerEvidence = { product_id: 'seller-offer', kind: 'channel', owner_domain: 'owner.example', host_domain: 'host.example', collection_id: 'news' }; const capability = (feature, value) => ({ media_buy: { features: { [`supports_${feature}`]: value } } }); function setup(feature, options = {}) { const calls = []; return { calls, args: { - feature, capabilities: capability(feature, true), validate, ownerEvidence, + feature, capabilities: capability(feature, true), validate, prepare: async params => { calls.push(params); return { success: true, simulated: { ...params, product: product(feature) } }; }, ...options, } }; @@ -95,7 +95,7 @@ for (const feature of features) { }); } -test('all 64 independent declaration combinations select only the promised empty-catalog paths', async () => { +test('all 256 independent declaration combinations select only the promised empty-catalog paths', async () => { for (let mask = 0; mask < 2 ** features.length; mask++) { const declarations = Object.fromEntries(features.map((feature, i) => [`supports_${feature}`, Boolean(mask & (1 << i))])); for (let i = 0; i < features.length; i++) { @@ -139,16 +139,16 @@ test('invalid known declarations fail; unknown future keys remain open without c const { args } = setup('format_breakdown', { capabilities: { media_buy: { features: { future_feature: true } } } }); assert.equal((await evaluate(args)).state, 'coverage_gap'); }); -test('fixed omitted/false flags qualify; owner carriage needs separate channel evidence and no selectable flag', () => { +test('omitted/false fixed flags qualify; declared carriage is a structural same-product relation only', () => { for (const flag of [undefined, false]) { - const p = product('fixed_collection_bundles'); if (flag !== undefined) p.collection_targeting_allowed = flag; - assert.equal(validate.product(p), true); assert.equal(qualifies('fixed_collection_bundles', p), true); + const p = product('fixed_bundle_enforcement'); if (flag !== undefined) p.collection_targeting_allowed = flag; + assert.equal(validate.product(p), true); assert.equal(qualifies('fixed_bundle_enforcement', p), true); assert.equal(qualifies('collection_selection', p), false); } - const p = product('owner_sold_channel_carriage'); - assert.equal(qualifies('owner_sold_channel_carriage', p), false); - assert.equal(qualifies('owner_sold_channel_carriage', p, ownerEvidence), true); - assert.equal(qualifies('owner_sold_channel_carriage', p, { ...ownerEvidence, kind: 'show' }), false); + const p = product('cross_publisher_collection_restatement'); + assert.equal(qualifies('cross_publisher_collection_restatement', p), true); + assert.deepEqual(crossPublisherPair(p), ['owner.example', 'news']); + assert.equal(qualifies('cross_publisher_collection_subset', p), false); }); test('new fields pass old open schemas; old sellers and omitted parents validate the fragment', () => { const fresh = Object.fromEntries(features.map(f => [`supports_${f}`, true])); @@ -181,8 +181,8 @@ function sdkStoryboard(gated = false) { phases: [{ id: 'exercise', title: 'Exercise', steps: [{ id: 'selected', title: 'Selected path', task: 'create_media_buy', sample_request: {}, validations: [{ check: 'field_present', path: 'media_buy_id', description: 'Sentinel, not full lifecycle coverage' }] }] }] }; } -test('SDK 15.9.5: equals-true gating would hide undeclared catalogs, including absent parent objects', async () => { - assert.equal(require('@adcp/sdk/package.json').version, '15.9.5'); +test(`installed SDK ${sdkVersion}: equals-true gating would hide undeclared catalogs, including absent parent objects`, async () => { + assert.equal(sdkVersion, require('../../package.json').dependencies['@adcp/sdk'], 'evidence must use the repository pin'); for (const capabilities of [{}, { media_buy: {} }, { media_buy: { features: {} } }]) { let calls = 0; const result = await runStoryboard('https://seller.example/mcp', sdkStoryboard(true), { @@ -192,7 +192,7 @@ test('SDK 15.9.5: equals-true gating would hide undeclared catalogs, including a assert.equal(calls, 0); assert.ok(result.phases.flatMap(p => p.steps).some(s => s.skip_reason === 'capability_unsupported')); } }); -test('SDK 15.9.5: old catalog path remains runnable with unknown declaration keys; selected failures stay failed', async () => { +test(`installed SDK ${sdkVersion}: catalog path remains runnable with unknown declaration keys; selected failures stay failed`, async () => { for (const broken of [false, true]) { let calls = 0; const result = await runStoryboard('https://seller.example/mcp', sdkStoryboard(), { @@ -264,7 +264,7 @@ test('proposed controller params reject malformed or unknown scopes without coer assert.equal(validate.params(params), false); } }); -test('SDK 15.9.5: an old controller returns UNKNOWN_SCENARIO for the proposed operation without mutation', async () => { +test(`installed SDK ${sdkVersion}: controller returns UNKNOWN_SCENARIO for the proposed operation without mutation`, async () => { const { handleTestControllerRequest } = require('@adcp/sdk'); const store = {}; const response = await handleTestControllerRequest(store, { scenario: 'prepare_product_feature', params: examples.prepare_params }); @@ -299,7 +299,7 @@ test('one-pair defaults qualify in selectable and omitted-or-false fixed modes', assert.equal(validate.product(single), true); assert.equal(qualifies('collection_default_materialization', single), true); assert.equal(qualifies('collection_selection', single), false); - assert.equal(qualifies('fixed_collection_bundles', single), false); + assert.equal(qualifies('fixed_bundle_enforcement', single), false); } }); test('one evidence normalizer preserves namespaces and schema-valid redundant/empty IDs without inventing pairs', () => { @@ -344,11 +344,11 @@ test('real product schema forbids publisher_domains on products, including along { publisher_domains: ['host.example'], selection_type: 'all' }, { publisher_domain: 'host.example', publisher_domains: ['other.example'], selection_type: 'all' }, ]) { - const invalid = product('owner_sold_channel_carriage', { publisher_properties: [property] }); + const invalid = product('cross_publisher_collection_restatement', { publisher_properties: [property] }); assert.equal(validate.product(invalid), false); - const catalog = setup('owner_sold_channel_carriage', { catalog: [invalid] }); + const catalog = setup('cross_publisher_collection_restatement', { catalog: [invalid] }); assert.equal((await evaluate(catalog.args)).reason, 'invalid_catalog'); - const prepared = setup('owner_sold_channel_carriage', { + const prepared = setup('cross_publisher_collection_restatement', { prepare: async params => ({ success: true, simulated: { ...params, product: invalid } }), }); assert.equal((await evaluate(prepared.args)).reason, 'invalid_qualified_setup'); @@ -367,3 +367,79 @@ test('domain-only product collection entries fail even when another concrete ent }); assert.equal((await evaluate(prepared.args)).reason, 'invalid_qualified_setup'); }); + +test('one-pair fixed restatement stays independent from two-pair fixed enforcement', async () => { + const single = product('fixed_bundle_restatement'); + assert.equal(qualifies('fixed_bundle_restatement', single), true); + assert.equal(qualifies('fixed_bundle_enforcement', single), false); + const capabilities = { media_buy: { features: { supports_fixed_bundle_restatement: true, supports_fixed_bundle_enforcement: true } } }; + const enforcement = setup('fixed_bundle_enforcement', { capabilities, catalog: [single], + prepare: async params => ({ success: true, simulated: { ...params, product: single } }) }); + assert.equal((await evaluate(enforcement.args)).reason, 'invalid_qualified_setup'); + const restatement = setup('fixed_bundle_restatement', { capabilities, catalog: [single] }); + assert.equal((await evaluate(restatement.args)).state, 'applicable'); +}); +test('one-pair declared carriage stays independent from selectable cross-publisher subset', async () => { + const single = product('cross_publisher_collection_restatement'); + const capabilities = { media_buy: { features: { supports_cross_publisher_collection_restatement: true, supports_cross_publisher_collection_subset: true } } }; + const subset = setup('cross_publisher_collection_subset', { capabilities, catalog: [single], + prepare: async params => ({ success: true, simulated: { ...params, product: single } }) }); + assert.equal((await evaluate(subset.args)).reason, 'invalid_qualified_setup'); + const carriage = setup('cross_publisher_collection_restatement', { capabilities, catalog: [single] }); + assert.equal((await evaluate(carriage.args)).state, 'applicable'); +}); +test('declared cross-publisher relation lies outside ALL product property domains and traverses all selectors', () => { + const local = product('cross_publisher_collection_restatement', { publisher_properties: [ + { publisher_domain: 'host.example', selection_type: 'all' }, + { publisher_domain: 'owner.example', selection_type: 'all' }, + ] }); + assert.equal(validate.product(local), true); + assert.equal(qualifies('cross_publisher_collection_restatement', local), false); + const cross = { ...local, collections: [...local.collections, + { publisher_domain: 'external.example', collection_ids: ['external'] }] }; + assert.equal(validate.product(cross), true); + assert.deepEqual(crossPublisherPair(cross), ['external.example', 'external']); + assert.equal(qualifies('cross_publisher_collection_restatement', cross), true); +}); +test('cross-publisher subset needs two TOTAL pairs and retains the external singleton', () => { + const mixed = product('cross_publisher_collection_subset', { collections: [ + { publisher_domain: 'host.example', collection_ids: ['local'] }, + { publisher_domain: 'external.example', collection_ids: ['external'] }, + ] }); + assert.equal(validate.product(mixed), true); + assert.equal(qualifies('cross_publisher_collection_subset', mixed), true); + const external = crossPublisherPair(mixed); + assert.deepEqual(external, ['external.example', 'external']); + assert.equal(collectionPairs(mixed.collections).some(pair => JSON.stringify(pair) === JSON.stringify(external)), true); + assert.equal(1 < collectionPairs(mixed.collections).length, true); + assert.equal(qualifies('cross_publisher_collection_subset', { ...mixed, collection_targeting_allowed: false }), false); +}); +test(`installed SDK ${sdkVersion}: optional reader companion cannot suppress an independent core flow`, async () => { + let creates = 0; let reads = 0; + const core = sdkStoryboard(); + const companion = { ...sdkStoryboard(), id: 'proposal/readback_companion', required_tools: ['get_media_buys'], + phases: [{ id: 'readback', title: 'Readback sentinel', steps: [{ id: 'read', title: 'Read', task: 'get_media_buys', + sample_request: {}, validations: [{ check: 'field_present', path: 'media_buys', description: 'Gate evidence only, not identity qualification' }] }] }] }; + const tools = ['create_media_buy']; + const options = { agentTools: tools, _profile: { tools, raw_capabilities: {} }, + _client: { resetContext() {}, + async createMediaBuy() { creates++; return { success: true, data: { media_buy_id: 'native-buy' } }; }, + async getMediaBuys() { reads++; throw new Error('unadvertised reader must not execute'); }, + } }; + const coreResult = await runStoryboard('https://seller.example/mcp', core, options); + const readResult = await runStoryboard('https://seller.example/mcp', companion, options); + assert.equal(coreResult.phases[0].steps[0].passed, true); + assert.equal(creates, 1); assert.equal(reads, 0); + assert.ok(readResult.phases.flatMap(p => p.steps).some(step => step.skip_reason === 'missing_tool')); +}); +test(`installed SDK ${sdkVersion}: advertised broken reader retains a failure`, async () => { + const tools = ['get_media_buys']; + const companion = { ...sdkStoryboard(), required_tools: ['get_media_buys'], phases: [{ id: 'readback', title: 'Readback sentinel', + steps: [{ id: 'read', title: 'Read', task: 'get_media_buys', sample_request: {}, + validations: [{ check: 'field_present', path: 'media_buys', description: 'Reader gate evidence only' }] }] }] }; + const result = await runStoryboard('https://seller.example/mcp', companion, { + agentTools: tools, _profile: { tools, raw_capabilities: {} }, + _client: { resetContext() {}, async getMediaBuys() { return { success: false, error: 'advertised reader failed' }; } }, + }); + assert.ok(result.failed_count > 0); +}); diff --git a/specs/optional-product-feature-declarations/review.md b/specs/optional-product-feature-declarations/review.md index 716d891a23d..86c02a7e561 100644 --- a/specs/optional-product-feature-declarations/review.md +++ b/specs/optional-product-feature-declarations/review.md @@ -13,11 +13,12 @@ SDK 15.9.5 and lockfile: node --test --test-timeout=30000 specs/optional-product-feature-declarations/probes.test.cjs ``` -The isolated suite has **69 tests**, including all 64 independent feature subsets. +The isolated suite has **89 tests**, including all 256 independent proposed field subsets. It compiles actual current product/selection/reporting schemas and the actual immutable 3.2.5 feature schema for old-reader acceptance, without editing them. -Three tests execute the real pinned SDK: two runner probes with injected clients -and an old controller dispatch probe. They prove +Five tests execute the installed SDK: four small runner/gate probes with injected +clients and a controller dispatch probe, labeled with the actual runtime version. +The original three prove equals-true gates hide absent declarations, and a legacy ungated execution path continues to run and retain selected-path failures, and an old controller returns `UNKNOWN_SCENARIO` without mutation for the proposed operation. They do not implement the @@ -138,6 +139,44 @@ None fetched, installed, executed or reviewed candidate SDK source. Prior review results retain their explicitly recorded earlier scope. These reviews qualify only the proposal packet, not SDK implementation safety or WG ratification. +## Reconciliation with settled #8428 source consumers (2026-10-23) + +Read the exact qualification memo at #8428 head +`10e88cd4c68df8a9db3bc1ba6c79ceb61e52a8bd`, base +`3e94f5e376bae2911fe26373a8ff506908f1a765`. This workspace did not rerun its +actual-source/public/caller suite or take over catalog merge qualification. +#8259 is closed as superseded; #3354/#8376 are merged and the source package pin +is SDK16.3.0. Obsolete execution-capacity and provisional API notes are removed +from the current memo, retained above only as historical review context. + +The current recommendation is eight proposed commitments: six independent core +collection scopes plus separate format/time. It separates one-pair fixed +restatement from two-pair fixed enforcement, and any-mode one-pair cross-publisher full-set restatement from selectable +two-total-pair cross-publisher subset. Provisional wire fields use structural +`cross_publisher_collection_*` names, while historical source IDs remain unchanged. The prior +unpublished fixed-bundle field is replaced; no public wire rename/alias occurs. +Optional reader companions stay tool-gated without new declarations. These are +recommendations to review, not requirements adopted by source scenario IDs. + +The model now uses only the declared cross-publisher structure outside ALL +same-product property domains; no invented channel-kind/ownership witness. +New probes preserve small-path coverage under missing/broken larger promises, +local-plus-external subset eligibility and independent optional reader gates. +All 256 field combinations execute; **89/89 pass locally on SDK15.9.5**. +Probe labels/checks use the actual repository pin so a later merge-check run on +SDK16.3 reports its own evidence rather than claiming the legacy runtime. No +SDK/dependency/lock/bridge installation or change occurred here. + +Fresh independent protocol, product/docs and code reviewers each reran +**89/89**, all 256 combinations, on installed SDK15.9.5, with clean diff checks. +A naming issue was resolved by using structural cross-publisher field/scope names +while retaining historical source-ID mappings. Final code review verified all +eight schema/controller/model cases agree: **Ready to push**, no remaining +findings. Eight fields are a defensible WG recommendation, not an adopted or +uniquely minimal wire design. No earlier 69-probe review is substituted for this +review. New exact-head CI must be observed independently. #8428 merge/source +duties and SDK #3395/#3396/#3397 defect triage remain with existing owners. + ## Still required for adoption The five normative choices at the end of the memo remain for humans/WG. Real