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..a324fe573de --- /dev/null +++ b/specs/optional-product-feature-declarations.md @@ -0,0 +1,371 @@ +--- +title: Seller-wide optional product-feature commitments +class: normative +status: proposed +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.** 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 **eight** optional booleans under `media_buy.features`, with no defaults: + +| Proposed field | Qualifying native sandbox offer | Independent core consumer | +| --- | --- | --- | +| `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 + +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 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) 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 new file mode 100644 index 00000000000..bd12d2ac044 --- /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", "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", + "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..7c75612c678 --- /dev/null +++ b/specs/optional-product-feature-declarations/examples.json @@ -0,0 +1,32 @@ +{ + "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_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 + }, + "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"] }] } }, + { "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..a8fb0a72ea6 --- /dev/null +++ b/specs/optional-product-feature-declarations/features.schema.json @@ -0,0 +1,40 @@ +{ + "$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 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 new file mode 100644 index 00000000000..a8c6ac19b27 --- /dev/null +++ b/specs/optional-product-feature-declarations/model.cjs @@ -0,0 +1,125 @@ +// 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' }), + }; +} + +// 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])); +} + +// 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 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; + } +} + +// 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 = [], + 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)) + .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) { + 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)) { + 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, collectionPairs, crossPublisherPair, 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..df3239e99e9 --- /dev/null +++ b/specs/optional-product-feature-declarations/probes.test.cjs @@ -0,0 +1,445 @@ +// 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 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(); }); + +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', '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' || 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 capability = (feature, value) => ({ media_buy: { features: { [`supports_${feature}`]: value } } }); +function setup(feature, options = {}) { + const calls = []; + return { calls, args: { + feature, capabilities: capability(feature, true), validate, + 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 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++) { + 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('omitted/false fixed flags qualify; declared carriage is a structural same-product relation only', () => { + for (const flag of [undefined, false]) { + 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('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])); + 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(`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), { + 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(`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(), { + 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 => 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', 'music'], ['owner.example', 'news']]; + const selected = vector.request.mode === 'default' ? full : identities(vector.request.collections); + 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'; +} +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(`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 }); + 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_bundle_enforcement', 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); +}); + +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('cross_publisher_collection_restatement', { publisher_properties: [property] }); + assert.equal(validate.product(invalid), false); + const catalog = setup('cross_publisher_collection_restatement', { catalog: [invalid] }); + assert.equal((await evaluate(catalog.args)).reason, 'invalid_catalog'); + 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'); + } +}); +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'); +}); + +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 new file mode 100644 index 00000000000..86c02a7e561 --- /dev/null +++ b/specs/optional-product-feature-declarations/review.md @@ -0,0 +1,188 @@ +# 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 **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. +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 +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. + +## 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 +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. + +## 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 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. + +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. + +## 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. + +## 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 +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.