diff --git a/.changeset/refine-proposals-expected-confirmation-at.md b/.changeset/refine-proposals-expected-confirmation-at.md new file mode 100644 index 00000000000..6dbd1860287 --- /dev/null +++ b/.changeset/refine-proposals-expected-confirmation-at.md @@ -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. diff --git a/docs/media-buy/task-reference/create_media_buy.mdx b/docs/media-buy/task-reference/create_media_buy.mdx index f95d931f2b4..c814c9d746a 100644 --- a/docs/media-buy/task-reference/create_media_buy.mdx +++ b/docs/media-buy/task-reference/create_media_buy.mdx @@ -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. diff --git a/docs/media-buy/task-reference/refine_proposals.mdx b/docs/media-buy/task-reference/refine_proposals.mdx index ab1d14290a8..ce5b2d5ec48 100644 --- a/docs/media-buy/task-reference/refine_proposals.mdx +++ b/docs/media-buy/task-reference/refine_proposals.mdx @@ -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. diff --git a/package.json b/package.json index 58384ab0244..d4689007a2b 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/static/schemas/source/media-buy/refine-proposals-async-response-submitted.json b/static/schemas/source/media-buy/refine-proposals-async-response-submitted.json index 23b8b7728f0..7690623bcb8 100644 --- a/static/schemas/source/media-buy/refine-proposals-async-response-submitted.json +++ b/static/schemas/source/media-buy/refine-proposals-async-response-submitted.json @@ -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." + } + } } diff --git a/static/schemas/source/media-buy/refine-proposals-response.json b/static/schemas/source/media-buy/refine-proposals-response.json index ad3a8f785be..892049048be 100644 --- a/static/schemas/source/media-buy/refine-proposals-response.json +++ b/static/schemas/source/media-buy/refine-proposals-response.json @@ -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"] } + ] } }, { @@ -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" }, diff --git a/tests/refine-proposals-expected-confirmation-at.test.cjs b/tests/refine-proposals-expected-confirmation-at.test.cjs new file mode 100644 index 00000000000..29a11e7089a --- /dev/null +++ b/tests/refine-proposals-expected-confirmation-at.test.cjs @@ -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 + ); +});