Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/optional-product-feature-declarations.yml
Original file line number Diff line number Diff line change
@@ -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
371 changes: 371 additions & 0 deletions specs/optional-product-feature-declarations.md

Large diffs are not rendered by default.

27 changes: 27 additions & 0 deletions specs/optional-product-feature-declarations/controller.schema.json
Original file line number Diff line number Diff line change
@@ -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
}
}
}
32 changes: 32 additions & 0 deletions specs/optional-product-feature-declarations/examples.json
Original file line number Diff line number Diff line change
@@ -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"] }
}
40 changes: 40 additions & 0 deletions specs/optional-product-feature-declarations/features.schema.json
Original file line number Diff line number Diff line change
@@ -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
}
125 changes: 125 additions & 0 deletions specs/optional-product-feature-declarations/model.cjs
Original file line number Diff line number Diff line change
@@ -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 };
Loading
Loading