Skip to content
Merged
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
5 changes: 5 additions & 0 deletions .changeset/refine-proposals-expected-confirmation-at.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": minor
---

Add optional `expected_confirmation_at` (date-time) to the `submitted` response of `refine_proposals` (#8086). A seller whose finalize hold depends on a person's agreement, such as a creator, host or talent, MAY return `submitted` and SHOULD set it so the buyer can schedule a status check instead of polling tightly. It is an estimate, not a commitment, with the same semantics as on `create_media_buy`. Intended for a `submitted` response to a finalize-only request (sellers SHOULD NOT send it on revise); a `completed` response MUST NOT carry it. Stable optional field (`x-added-in: 3.3.0`); no change for sellers that omit it.
2 changes: 1 addition & 1 deletion docs/media-buy/task-reference/create_media_buy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,7 @@ Some confirmations are tied to a scheduled event rather than to processing time:
- The value is a point-in-time estimate from the response that carried it. A seller whose schedule slips MAY re-emit a revised `expected_confirmation_at` on a later `submitted` webhook. A seller SHOULD NOT send a timestamp in the past, and a buyer MUST NOT read one as meaningful.
- It is not an expiry. Deadlines that close a request window (for example the booking deadline on an installment) are separate fields on the product or installment.

For [`accept_proposal`](/docs/media-buy/task-reference/accept_proposal), the estimate MAY fall after the proposal's `expires_at`: acceptance consumes the hold, so the estimate describes confirmation, not the hold. [`buy_products`](/docs/media-buy/task-reference/buy_products) and `accept_proposal` carry the same optional field on their submitted arms. The shared compact envelope used by [`decline_proposals`](/docs/media-buy/task-reference/decline_proposals), [`control_media_buy`](/docs/media-buy/task-reference/control_media_buy), [`request_proposals`](/docs/media-buy/task-reference/request_proposals), and [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) does not, because those tasks do not confirm a purchase. [`get_products`](/docs/media-buy/task-reference/get_products) and [`get_signals`](/docs/signals/tasks/get_signals) submitted envelopes carry a separate `estimated_completion`, which estimates when a search finishes processing; `expected_confirmation_at` instead names the scheduled event that confirms a purchase.
For [`accept_proposal`](/docs/media-buy/task-reference/accept_proposal), the estimate MAY fall after the proposal's `expires_at`: acceptance consumes the hold, so the estimate describes confirmation, not the hold. [`buy_products`](/docs/media-buy/task-reference/buy_products), `accept_proposal`, and a [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) finalize carry the same optional field on their submitted arms. For a finalize it estimates when the seller expects to resolve the hold, for example when a creator or host must agree first; it is absent on revise requests. The shared compact envelope used by [`decline_proposals`](/docs/media-buy/task-reference/decline_proposals), [`control_media_buy`](/docs/media-buy/task-reference/control_media_buy), and [`request_proposals`](/docs/media-buy/task-reference/request_proposals) does not, because those tasks do not confirm a purchase or place a hold. [`get_products`](/docs/media-buy/task-reference/get_products) and [`get_signals`](/docs/signals/tasks/get_signals) submitted envelopes carry a separate `estimated_completion`, which estimates when a search finishes processing; `expected_confirmation_at` instead names the scheduled event that confirms a purchase.

**Note**: Responses are mutually exclusive across these three shapes. Dispatch on `status` first: `"submitted"` → async envelope, otherwise check `errors` before accessing success fields.

Expand Down
2 changes: 2 additions & 0 deletions docs/media-buy/task-reference/refine_proposals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,8 @@ the reservation has succeeded.

A request containing `finalize` must contain only finalize entries. Sellers validate the complete batch before creating any holds; multi-proposal finalization is atomic. When any hold cannot be created, no result is `finalized`: the failing entry returns `unable` with `reason_code: "hold_unavailable"`, and otherwise-eligible siblings return `unable` with `reason_code: "batch_aborted"`. Exact retries use the same idempotency key. A new key does not extend or recreate an existing hold: while a committed successor's hold is unexpired, finalizing the same draft again MUST fail at task level with [`INVALID_STATE`](/docs/building/verification/compliance-catalog#error-code-invalid-state) rather than minting a second hold; after expiry a new finalize MAY create a new one.

**Holds that wait on a person (added in 3.3).** A seller whose hold depends on someone's agreement, such as a creator, host, or talent, MAY return `submitted` for a finalize-only request and SHOULD set `expected_confirmation_at` on that response. It estimates when the seller expects to resolve the finalize. Buyers schedule a status check for that time instead of polling tightly. It carries the [same semantics](/docs/media-buy/task-reference/create_media_buy#expected-confirmation-time) as on [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy): an estimate, not a commitment, and not the hold's `expires_at`, which exists only on the committed proposal once the hold is placed. Sellers SHOULD NOT send it on a revise request; the response cannot see the request, so that is a seller obligation rather than a schema rule. A `completed` response MUST NOT carry it.

**Definition pins are verified before the hold.** Finalization re-resolves each entry in the source proposal's `commercial_terms.definition_pins[]` (see [Definition pins](/docs/media-buy/specification#definition-pins)) and takes no hold if any published definition no longer matches. The entry returns `unable` with `reason_code: "definition_changed"` and a required `drifted_pins[]`; each item carries the `pin` exactly as the draft carried it and the `current_content_digest` the definition resolves to now, omitted only when the entry was withdrawn from a successfully fetched, validated document. The seller verifies every entry's pins before creating any hold. A pin failure is an entry failure: that entry's `definition_changed` takes precedence over `batch_aborted`, and otherwise-eligible siblings in the finalize batch return `batch_aborted`. A source document that cannot be fetched or parsed is not drift; the seller returns [`SERVICE_UNAVAILABLE`](/docs/building/verification/compliance-catalog#error-code-service-unavailable) at task level without taking any hold. The buyer revises the proposal, which re-resolves the definitions and issues fresh pins, reviews the changed definition, and finalizes again. Only `commercial_terms` is frozen at finalize: `forecast` may differ between a draft and its committed successor, and a rename or other change outside the pin's projection is not drift.

Holds are a seller commitment against real inventory, so hold policy is the seller's. Sellers MAY decline any hold (`hold_unavailable`), MAY cap concurrent unexpired holds per buyer to prevent inventory squatting, and choose `expires_at` themselves — the hold window should be long enough to complete acceptance and short enough that unaccepted holds do not function as free inventory options. Nothing in this task obliges a seller to grant holds without whatever credit or relationship checks it applies to reservations generally; the async `submitted` path exists for exactly that re-underwriting.
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"verify:cdn-artifacts-cutover": "node scripts/verify-cdn-artifacts-cutover.mjs",
"typecheck": "tsc --project server/tsconfig.json --noEmit && npm run typecheck:fixed-trace-rollout-tests",
"typecheck:fixed-trace-rollout-tests": "node scripts/typecheck-fixed-trace-rollout-tests.mjs",
"test:schemas": "node tests/schema-validation.test.cjs && node --test tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/dooh-allocation.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/format-asset-type-parity.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/definition-pin-vectors.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
"test:schemas": "node tests/schema-validation.test.cjs && node --test tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/dooh-allocation.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/format-asset-type-parity.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/definition-pin-vectors.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
"test:performance-feedback": "node --test --test-force-exit --test-timeout=30000 tests/performance-feedback-contract.test.cjs",
"test:dist-schema-version-ids": "node --test --test-force-exit --test-timeout=30000 tests/dist-schema-version-ids.test.cjs",
"test:examples": "node tests/example-validation-simple.test.cjs && npm run test:tmp-context-merge",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,13 @@
"description": "Bounded submitted task envelope for refine_proposals when a complex revision requires upstream pricing or re-underwriting.",
"allOf": [
{ "$ref": "/schemas/core/compact-task-submitted.json" }
]
],
"properties": {
"expected_confirmation_at": {
"type": "string",
"format": "date-time",
"x-added-in": "3.3.0",
"description": "Optional estimate, on a submitted response to a finalize-only request, of when the seller expects to resolve the finalize, for example when a creator, host or talent must agree before the hold. Same semantics as on `create_media_buy`: an estimate, not a commitment or expiry; buyers SHOULD schedule a status check for it and MUST NOT treat a passed timestamp as failure. Sellers SHOULD NOT send it on revise requests."
}
}
}
11 changes: 10 additions & 1 deletion static/schemas/source/media-buy/refine-proposals-response.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,10 @@
"properties": { "status": { "type": "string", "const": "completed" } },
"required": ["results", "products"],
"not": {
"required": ["task_id"]
"anyOf": [
{ "required": ["task_id"] },
{ "required": ["expected_confirmation_at"] }
]
}
},
{
Expand Down Expand Up @@ -214,6 +217,12 @@
"status": { "type": "string", "enum": ["completed", "submitted"] },
"task_id": { "type": "string", "minLength": 1, "x-entity": "task" },
"message": { "type": "string", "maxLength": 2000 },
"expected_confirmation_at": {
"type": "string",
"format": "date-time",
"x-added-in": "3.3.0",
"description": "Optional estimate, on a submitted response to a finalize-only request, of when the seller expects to resolve the finalize, for example when a creator, host or talent must agree before the hold. Same semantics as on `create_media_buy`: an estimate, not a commitment or expiry; buyers SHOULD schedule a status check for it and MUST NOT treat a passed timestamp as failure. Sellers SHOULD NOT send it on revise requests."
},
"errors": { "type": "array", "items": { "$ref": "/schemas/core/error.json" } },
"context": { "$ref": "/schemas/core/context.json" },
"ext": { "$ref": "/schemas/core/ext.json" },
Expand Down
67 changes: 67 additions & 0 deletions tests/refine-proposals-expected-confirmation-at.test.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
const fs = require("node:fs");
const path = require("node:path");
const test = require("node:test");
const assert = require("node:assert/strict");
const Ajv = require("ajv");
const addFormats = require("ajv-formats");

const SCHEMA_ROOT = path.join(__dirname, "..", "static", "schemas", "source");

async function loadSchema(uri) {
const filename = path.resolve(SCHEMA_ROOT, uri.slice("/schemas/".length));
if (!filename.startsWith(`${SCHEMA_ROOT}${path.sep}`))
throw new Error(`Schema path escape: ${uri}`);
return JSON.parse(fs.readFileSync(filename, "utf8"));
}

async function compile(uri) {
const ajv = new Ajv({ allErrors: true, strict: false, discriminator: true, loadSchema });
addFormats(ajv);
return ajv.compileAsync(await loadSchema(uri));
}

const ESTIMATE = "2026-10-20T17:00:00Z";

test("refine_proposals submitted response accepts expected_confirmation_at", async () => {
const validate = await compile("/schemas/media-buy/refine-proposals-response.json");
const submitted = { status: "submitted", task_id: "task_finalize_1" };
assert.equal(validate(submitted), true, JSON.stringify(validate.errors));
const withEstimate = { ...submitted, expected_confirmation_at: ESTIMATE };
assert.equal(validate(withEstimate), true, JSON.stringify(validate.errors));
});

test("refine_proposals submitted response rejects a malformed expected_confirmation_at", async () => {
const validate = await compile("/schemas/media-buy/refine-proposals-response.json");
assert.equal(
validate({ status: "submitted", task_id: "task_finalize_1", expected_confirmation_at: "next week" }),
false
);
});

test("refine_proposals completed response must not carry expected_confirmation_at", async () => {
const validate = await compile("/schemas/media-buy/refine-proposals-response.json");
const completed = {
status: "completed",
results: [{ source_proposal_id: "prop_1", outcome: "unable", reason_code: "hold_unavailable", reason: "No inventory." }],
products: [],
};
assert.equal(validate(completed), true, JSON.stringify(validate.errors));
assert.equal(validate({ ...completed, expected_confirmation_at: ESTIMATE }), false);
assert.equal(
validate({ ...completed, task_id: "task_1", expected_confirmation_at: ESTIMATE }),
false
);
});

test("refine_proposals submitted async wrapper accepts expected_confirmation_at", async () => {
const validate = await compile("/schemas/media-buy/refine-proposals-async-response-submitted.json");
assert.equal(
validate({ status: "submitted", task_id: "task_finalize_1", expected_confirmation_at: ESTIMATE }),
true,
JSON.stringify(validate.errors)
);
assert.equal(
validate({ status: "submitted", task_id: "task_finalize_1", expected_confirmation_at: "soon" }),
false
);
});
Loading