From ccf478157bb93ed0e185f43abdb8c182c10b76a1 Mon Sep 17 00:00:00 2001 From: lukasz-pubx Date: Sat, 14 Nov 2026 08:17:22 +0000 Subject: [PATCH] fix(governance): accept an omitted human_review_required and state two sync_plans validation rules PR 3 of 3 for #8733. - B2: drop "required" from both then branches of sync-plans-request.json and keep const true, so an omitted flag is valid and the governance agent derives it; an explicit false is still rejected - B2: remove "default": false from human_review_required; schema defaults are never applied to the plan_hash preimage - B2: prose says "rejects" a caller-supplied false; known-limitations and the trust page name the field the schema constrains - C4.1: flight.end must be later than flight.start - C4.2: policy IDs must not repeat or collide with custom_policies - C4.1 and C4.2 are prose plus x-adcp-validation annotations; schema tightening is deferred to 4.0 (#8756) Refs #8733 Co-Authored-By: Claude Fable 5.2 --- .../sync-plans-human-review-omission.md | 13 +++ docs/governance/campaign/specification.mdx | 6 +- docs/governance/campaign/tasks/sync_plans.mdx | 9 +- docs/governance/policy-registry-sync.mdx | 2 +- docs/reference/known-limitations.mdx | 2 +- docs/trust.mdx | 2 +- package.json | 2 +- .../src/training-agent/governance-handlers.ts | 2 +- server/tests/unit/training-agent.test.ts | 63 +++++++++- .../004b-human-review-explicit-null.json | 2 +- .../source/governance/sync-plans-request.json | 46 +++++--- tests/sync-plans-human-review.test.cjs | 110 ++++++++++++++++++ ...sync-plans-validation-annotations.test.cjs | 84 +++++++++++++ 13 files changed, 316 insertions(+), 27 deletions(-) create mode 100644 .changeset/sync-plans-human-review-omission.md create mode 100644 tests/sync-plans-human-review.test.cjs create mode 100644 tests/sync-plans-validation-annotations.test.cjs diff --git a/.changeset/sync-plans-human-review-omission.md b/.changeset/sync-plans-human-review-omission.md new file mode 100644 index 00000000000..d8963a2ede0 --- /dev/null +++ b/.changeset/sync-plans-human-review-omission.md @@ -0,0 +1,13 @@ +--- +"adcontextprotocol": minor +--- + +Campaign governance (experimental `governance.campaign`): accept an omitted `human_review_required`, and state two `sync_plans` validation rules (adcp#8733, PR 3 of 3). This widens what `sync-plans-request.json` accepts and changes no `plan_hash` rule. + +- **Omitted flag.** A plan that declares a regulated policy category (`fair_housing`, `fair_lending`, `fair_employment`, `pharmaceutical_advertising`) or `eu_ai_act_annex_iii`, and omits `human_review_required`, is now schema-valid. The governance agent derives the flag from the plan's resolved policies and policy categories. Before, both `then` branches required the field, so the specification's "sets it automatically" could never apply. An explicit `false` is still rejected by `const: true`. +- **No schema default.** `"default": false` is removed from `human_review_required`. A consumer that applied the default turned a valid omitted field into an explicit `false`, which the schema rejects. Schema `default` annotations are never applied to the `plan_hash` preimage, and a value the governance agent derives is not written into it. +- **Prose.** The specification says the governance agent rejects, not overrides, a caller-supplied `false`. `known-limitations` and the trust page name the field the schema constrains. +- **Flight order.** `flight.end` must be later than `flight.start`, else `INVALID_REQUEST`. +- **Policy ID uniqueness.** An ID must not repeat in `policy_ids`, and a `custom_policies[].policy_id` must not equal an ID in `policy_ids`, else `INVALID_REQUEST`. + +The two validation rules are stated in prose and as `x-adcp-validation` annotations. The schema does not enforce them in 3.x; tightening it is deferred to 4.0 (adcp#8756). The plan-hash vector `004b` gains a note that it exercises canonicalization only. diff --git a/docs/governance/campaign/specification.mdx b/docs/governance/campaign/specification.mdx index 57ed00bc654..358dd343d11 100644 --- a/docs/governance/campaign/specification.mdx +++ b/docs/governance/campaign/specification.mdx @@ -149,7 +149,7 @@ Periods are optional and additive. A plan without them behaves exactly as before ### Human review required -`human_review_required` is a plan-level boolean (default `false`) that mandates human oversight of every action on the plan, independent of budget reallocation autonomy. +`human_review_required` is an optional plan-level boolean that mandates human oversight of every action on the plan, independent of budget reallocation autonomy. When a plan omits it, the governance agent derives the value from the plan's resolved policies and policy categories. The governance agent sets `human_review_required: true` automatically when any resolved policy or policy_category on the plan carries `requires_human_review: true`. This includes regulated verticals such as `fair_housing`, `fair_lending`, `fair_employment`, and `pharmaceutical_advertising`, and the `eu_ai_act_annex_iii` policy covering decisions in Annex III use cases. @@ -162,7 +162,7 @@ This field is distinct from `budget.reallocation_threshold`: | `budget.reallocation_threshold` | Operational | Controls agent autonomy for budget reallocation within the plan | | `human_review_required` | Regulatory | Mandates human review of decisions affecting individuals (e.g., GDPR Art 22, EU AI Act Annex III) | -Callers MAY set `human_review_required: true` explicitly on a plan even when no triggering policy is present. Callers MUST NOT set it to `false` to override a policy that requires human review — the governance agent re-evaluates the flag from resolved policies on every sync and overrides a caller-supplied `false` when a triggering policy is present. +Callers MAY set `human_review_required: true` explicitly on a plan even when no triggering policy is present. Callers MUST NOT set it to `false` to override a policy that requires human review — the governance agent re-evaluates the flag from resolved policies on every sync and rejects a caller-supplied `false` when a triggering policy is present. ### Spend-commit invocation @@ -916,7 +916,7 @@ What the claim delivers: `plan_hash = base64url_no_pad(SHA-256(JCS(plan_payload)))` where: -- `JCS` is [RFC 8785 JSON Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785) — the same scheme used for [idempotency payload equivalence](/docs/building/by-layer/L1/security#payload-equivalence). Governance agents and auditor verifiers SHOULD use the same library implementations listed there. JCS sorts object keys lexicographically by code point (caller key order in the `sync_plans` request does not affect the hash) and preserves the distinction between an omitted optional field and an explicit `null` (these produce different hashes). Governance agents MUST hash the plan as-supplied; they MUST NOT synthesize omitted optionals to default values and MUST NOT drop explicit nulls. +- `JCS` is [RFC 8785 JSON Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785) — the same scheme used for [idempotency payload equivalence](/docs/building/by-layer/L1/security#payload-equivalence). Governance agents and auditor verifiers SHOULD use the same library implementations listed there. JCS sorts object keys lexicographically by code point (caller key order in the `sync_plans` request does not affect the hash) and preserves the distinction between an omitted optional field and an explicit `null` (these produce different hashes). Governance agents MUST hash the plan as-supplied; they MUST NOT synthesize omitted optionals to default values and MUST NOT drop explicit nulls. Schema `default` annotations are never applied to the preimage: a field the buyer omitted stays omitted, and a value the governance agent derives for itself, such as `human_review_required`, is not written into it. - `plan_payload` is **one element of the `plans[]` array as supplied on `sync_plans`** — a single plan object, not the `sync_plans` request envelope and not the `plans` wrapper array. The preimage is the current plan-revision state at the time of attestation, i.e., the plan object the governance agent just evaluated. Implementations constructing the preimage start from the plan-revision object and remove the closed set of bookkeeping fields listed below. - `base64url_no_pad` follows RFC 4648 §5 with trailing `=` padding stripped — consistent with `jti` and other base64url values in the JWS profile. Governance agents MUST emit the unpadded form. Verifiers (governance agents re-verifying their own tokens, auditors, buyer-side compliance tooling) MUST compare by base64url-decoding both sides to the raw 32-byte SHA-256 digest and comparing bytes — NOT by string equality of the encoded form — so padding, case, or alphabet variation is rejected as a decode failure rather than producing a false non-match. A `plan_hash` that does not decode to exactly 32 bytes MUST be rejected. diff --git a/docs/governance/campaign/tasks/sync_plans.mdx b/docs/governance/campaign/tasks/sync_plans.mdx index 1bd55860912..a93b9f7b5e9 100644 --- a/docs/governance/campaign/tasks/sync_plans.mdx +++ b/docs/governance/campaign/tasks/sync_plans.mdx @@ -196,7 +196,7 @@ Each plan item a buyer supplies here is the preimage the governance agent hashes | `plans[].budget.periods[].end` | date-time | Yes | Period end, exclusive. Later than `start`. | | `plans[].budget.periods[].amount` | number | Yes | Maximum budget committed to dated actions in this period, in `budget.currency`. Minimum 0. | | `plans[].channels` | object | No | Channel constraints. If omitted, all channels are allowed. | -| `plans[].flight` | object | Yes | Authorized flight dates. Governed actions with dates outside this window are rejected. | +| `plans[].flight` | object | Yes | Authorized flight dates. `end` MUST be later than `start`. Governed actions with dates outside this window are rejected. | | `plans[].countries` | array | No | ISO 3166-1 alpha-2 country codes for authorized markets. The governance agent rejects governed actions targeting outside these countries and resolves applicable policies by matching against policy jurisdictions. | | `plans[].regions` | array | No | ISO 3166-2 subdivision codes for authorized sub-national markets (e.g., `US-MA`). When present, restricts buys to these regions rather than the full country. | | `plans[].policy_categories` | array | No | Regulatory categories that apply to this campaign (e.g., `children_directed`, `fair_housing`). Determines which policy regimes the governance agent enforces. When omitted, governance agents MAY infer from the brand's industries and campaign objectives. | @@ -204,8 +204,9 @@ Each plan item a buyer supplies here is the preimage the governance agent hashes | `plans[].restricted_attributes` | array | No | Personal data categories that must not be used for targeting (e.g., `health_data`, `racial_ethnic_origin`, `sex_gender`). Includes GDPR Article 9 special categories and other policy-sensitive attributes. The governance agent flags any effective audience targeting referencing these attributes. `sex_gender` is available in AdCP 3.3. | | `plans[].restricted_attributes_custom` | array | No | Additional restricted attributes not covered by the enum. Freeform strings for jurisdiction-specific restrictions (e.g., `financial_status`). | | `plans[].min_audience_size` | integer | No | Minimum audience segment size for k-anonymity. Applies to the estimated intersection audience when multiple criteria are used. | -| `plans[].policy_ids` | array | No | Registry policy IDs to enforce for this plan. Intersected with the plan's countries/regions to activate only geographically relevant policies. | -| `plans[].custom_policies` | array | No | Campaign-specific policies using the `PolicyEntry` shape (`policy_id`, `enforcement`, `policy` text required). Additive only — cannot relax or override registry-sourced policies. See [policy resolution](/docs/governance/campaign/specification#policy-resolution). | +| `plans[].human_review_required` | boolean | No | When `true`, the governance agent escalates every action on the plan for human review. When omitted, the governance agent derives the value from the plan's resolved policies and policy categories. `false` is rejected when any of them requires human review. See [specification](/docs/governance/campaign/specification#human-review-required). | +| `plans[].policy_ids` | array | No | Registry policy IDs to enforce for this plan. Each ID MUST appear at most once. Intersected with the plan's countries/regions to activate only geographically relevant policies. | +| `plans[].custom_policies` | array | No | Campaign-specific policies using the `PolicyEntry` shape (`policy_id`, `enforcement`, `policy` text required). Additive only — cannot relax or override registry-sourced policies. A `policy_id` MUST NOT equal an ID in `policy_ids`. See [policy resolution](/docs/governance/campaign/specification#policy-resolution). | | `plans[].approved_sellers` | array/null | No | List of approved seller agent URLs. `null` means any seller. | | `plans[].delegations` | array | No | Agents authorized to execute against this plan. See [specification](/docs/governance/campaign/specification#delegations). | | `plans[].delegations[].agent_url` | string | Yes | URL of the delegated agent. | @@ -286,7 +287,7 @@ Policy categories are distinct from `brand.industries`. Industries describe what | Code | Recovery | Description | |------|----------|-------------| -| [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) | correctable | Plan is missing required fields or has invalid values. For `budget.periods`, this covers a duplicate `budget_period_id`, overlapping or empty windows, a window outside `flight`, amounts above `budget.total`, and more than 366 periods. `error.field` identifies the offending plan field. | +| [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) | correctable | Plan is missing required fields or has invalid values, including a `flight.end` that is not later than `flight.start`, a repeated ID in `policy_ids`, and a `custom_policies[].policy_id` that equals an ID in `policy_ids`. For `budget.periods`, this covers a duplicate `budget_period_id`, overlapping or empty windows, a window outside `flight`, amounts above `budget.total`, and more than 366 periods. `error.field` identifies the offending plan field. | | [`REFERENCE_NOT_FOUND`](/docs/building/verification/compliance-catalog#error-code-reference-not-found) | correctable | Brand domain could not be resolved via the Brand Protocol. The governance agent cannot determine applicable compliance policies without a valid brand reference. `error.field` MUST identify the brand field that failed to resolve. | | [`VALIDATION_ERROR`](/docs/building/verification/compliance-catalog#error-code-validation-error) | correctable | Cannot reduce budget below the amount already committed (on plan update), leave a dated commitment outside every budget period, or set a period `amount` below what is already committed to it. `error.field` identifies the budget field. | diff --git a/docs/governance/policy-registry-sync.mdx b/docs/governance/policy-registry-sync.mdx index 77a97f4969e..b7c2b769810 100644 --- a/docs/governance/policy-registry-sync.mdx +++ b/docs/governance/policy-registry-sync.mdx @@ -47,7 +47,7 @@ When a deterministic policy text is required — a regulator pre-clearance, a fr } ``` -**Use a different `policy_id` from the registry one.** If the buyer reuses the canonical ID `alcohol_advertising` in `custom_policies`, governance-agent behavior is undefined by the spec — the [policy-entry schema](https://adcontextprotocol.org/schemas/v3/governance/policy-entry.json)'s additive-only rule pins registry text as authoritative for that ID. A pinning ID like `alcohol_advertising_pinned_2026Q4` (or your internal versioning convention) sidesteps the conflict. +**Use a different `policy_id` from the registry one.** If the buyer reuses the canonical ID `alcohol_advertising` in `custom_policies` and also lists it in `policy_ids`, the governance agent rejects the sync with [`INVALID_REQUEST`](/docs/governance/campaign/tasks/sync_plans#error-codes). If the plan does not list it in `policy_ids`, governance-agent behavior is undefined by the spec — the [policy-entry schema](https://adcontextprotocol.org/schemas/v3/governance/policy-entry.json)'s additive-only rule pins registry text as authoritative for that ID. A pinning ID like `alcohol_advertising_pinned_2026Q4` (or your internal versioning convention) sidesteps the conflict. The plan revision now carries the frozen text. The `version` field on the inline policy is informational — the text is what gets evaluated — but worth setting for forensic traceability so an auditor can correlate the inline copy back to a specific registry release. diff --git a/docs/reference/known-limitations.mdx b/docs/reference/known-limitations.mdx index 197775a2e5f..40b7bf310c6 100644 --- a/docs/reference/known-limitations.mdx +++ b/docs/reference/known-limitations.mdx @@ -77,7 +77,7 @@ Request-specific configured offers are not a gap: canonical products carry no `i ## Governance -- **Regulated-category human review is enforced at the schema level for four named categories, at the governance-agent level for everything else.** AdCP rejects `authority_level: agent_full` at the schema level on campaigns that declare `fair_housing`, `fair_lending`, `fair_employment`, or `pharmaceutical_advertising` (the original three shipped via [#2310](https://github.com/adcontextprotocol/adcp/issues/2310)). Any other regulated category — political, gambling, alcohol, tobacco, financial, crypto, cannabis/CBD, firearms, dietary-supplement health claims, child-directed — relies on the governance-agent implementation rather than a category-specific schema invariant. +- **Regulated-category human review is enforced at the schema level for four named categories, at the governance-agent level for everything else.** AdCP rejects `human_review_required: false` at the schema level on campaigns that declare `fair_housing`, `fair_lending`, `fair_employment`, or `pharmaceutical_advertising` (the original three shipped via [#2310](https://github.com/adcontextprotocol/adcp/issues/2310)). A plan that omits the flag passes the schema, and the governance agent sets it. Any other regulated category — political, gambling, alcohol, tobacco, financial, crypto, cannabis/CBD, firearms, dietary-supplement health claims, child-directed — relies on the governance-agent implementation rather than a category-specific schema invariant. - **No protocol-mandated HITL on `sync_catalogs` or `sync_creatives`.** The universal task-lifecycle mechanism is available; no normative rule requires a human gate. `acquire_rights` is governed via the campaign-governance path ([purchase phase](/docs/governance/campaign/specification#governance-phases)) when the buyer's plan is configured for it. See [How human-in-the-loop enters the protocol](/docs/governance/embedded-human-judgment#how-human-in-the-loop-enters-the-protocol) for the two channels and the EHJ register for the normative rules on `check_governance`, `TERMS_REJECTED`, and lifecycle tasks. - **Other regulated categories have no category-specific schema treatment.** Political advertising, gambling, alcohol, tobacco, financial promotions (including crypto and digital assets), cannabis/CBD, firearms, dietary-supplement health claims, and advertising directed at children rely on the general [campaign-governance](/docs/governance/campaign/specification) mechanism (HITL gates, governance tasks) rather than category-specific schema rules. `pharmaceutical_advertising` is the exception: it joins housing, lending, and employment in the schema-level human-review constraint. Regionally specific disclosure requirements (e.g., UK FCA s.21, EU MiCA, political ad registries, COPPA, the UK Children's Code, GDPR Article 8) sit in the seller's delivery stack and the buyer's compliance posture, not the protocol. diff --git a/docs/trust.mdx b/docs/trust.mdx index d364161ad8e..5a47cc4bf9f 100644 --- a/docs/trust.mdx +++ b/docs/trust.mdx @@ -116,7 +116,7 @@ These are the wire-level hooks deployers implement. They are seams, not guarante | Contestation contact point | `brand.data_subject_contestation` | Discoverable endpoint; deployer operates the process | | Request signing | RFC 9421 `Signature` / `Signature-Input` headers | Normative in 3.1; allowed in 3.0 | | Governance attestation | JWS-signed `governance_context` on `create_media_buy` | Verifiable by seller independently | -| Regulated-category block | Schema-level rejection of `authority_level: agent_full` on `fair_housing`, `fair_lending`, `fair_employment` | Three categories only; others require governance-agent implementation | +| Regulated-category block | Schema-level rejection of `human_review_required: false` on `fair_housing`, `fair_lending`, `fair_employment` | Three categories only; others require governance-agent implementation | | Brand identity declaration | `brand.json` `house`, `brands[]`, `authorized_operators[]`, house-level `trademarks[]` | Discoverable; deployer / ecosystem resolves against public registries | | Mutual-assertion trust state | `brand.json` `house_domain` ↔ `brand_refs[]` (RFC #3533) | `relationship_trust` signal; deployer policy decides what's required | | Agent identity | `brand.json` `agents[].jwks_uri` (RFC 9421 profile, deprecated in 3.3), or the agent origin's key directory plus a trust.json listing (Web Bot Auth profile, experimental in 3.3); `adagents.json` `signing_keys` | Verifiable signing keys; key-transparency layer is 4.0 | diff --git a/package.json b/package.json index 4e14434ac6a..b00f9fcd671 100644 --- a/package.json +++ b/package.json @@ -33,7 +33,7 @@ "verify:schema-discovery": "node scripts/verify-schema-discovery.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/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs 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/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.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/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.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/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.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/collection-mechanism.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/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-report-definition-vectors.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/installment-refinement.test.cjs tests/installment-creative-assignment.test.cjs tests/get-products-deprecated-withdrawals.test.cjs tests/deprecated-task-withdrawals.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-probe.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-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/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/sync-plans-human-review.test.cjs tests/sync-plans-validation-annotations.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs 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/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.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/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.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/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.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/collection-mechanism.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/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-report-definition-vectors.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/installment-refinement.test.cjs tests/installment-creative-assignment.test.cjs tests/get-products-deprecated-withdrawals.test.cjs tests/deprecated-task-withdrawals.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-probe.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-vectors.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/server/src/training-agent/governance-handlers.ts b/server/src/training-agent/governance-handlers.ts index 8f358bdb38b..dfbe841ca00 100644 --- a/server/src/training-agent/governance-handlers.ts +++ b/server/src/training-agent/governance-handlers.ts @@ -766,7 +766,7 @@ export const GOVERNANCE_TOOLS = [ }, required: ['total', 'currency'], }, - human_review_required: { type: 'boolean', description: 'When true, every plan action escalates for human review. MUST be true when policy_categories contains a regulated vertical (fair_housing, fair_lending, fair_employment, pharmaceutical_advertising) or policy_ids contains eu_ai_act_annex_iii.' }, + human_review_required: { type: 'boolean', description: 'When true, every plan action escalates for human review. Omit it to let the governance agent derive it. false is rejected when policy_categories contains a regulated vertical (fair_housing, fair_lending, fair_employment, pharmaceutical_advertising) or policy_ids contains eu_ai_act_annex_iii.' }, human_override: { type: 'object', description: 'Required to downgrade an existing plan from human_review_required=true to false. Training agent requires approver (email) and reason (>=20 chars); production agents should bind to signed identity.', diff --git a/server/tests/unit/training-agent.test.ts b/server/tests/unit/training-agent.test.ts index e497b676507..ff75bc5f773 100644 --- a/server/tests/unit/training-agent.test.ts +++ b/server/tests/unit/training-agent.test.ts @@ -73,6 +73,7 @@ function futureFlight(): { start_time: string; end_time: string } { } import { getAgentUrl } from '../../src/training-agent/config.js'; import { computeDeliveryStatementDigest } from '../../src/training-agent/governance-payload-hash.js'; +import { computePlanHash } from '../../src/training-agent/plan-hash.js'; import { CANONICAL_GOV_ISS, clearGovernanceTokenReplayRegistry, @@ -25391,11 +25392,71 @@ describe('human_review_required auto-flip and enforcement', () => { it('auto-flips human_review_required when policy_categories contains fair_lending', async () => { const server = createTrainingAgentServer(DEFAULT_CTX); + const account = { brand: { domain: 'derived.example' }, operator: 'test.example' }; + // The plan omits the flag; the governance agent derives it from the category. const { result, isError } = await simulateCallTool(server, 'sync_plans', { - plans: [{ ...PLAN_BASE, policy_categories: ['fair_lending'], human_review_required: true }], + account, + plans: [{ + ...PLAN_BASE, + brand: { ...PLAN_BASE.brand, domain: 'derived.example' }, + policy_categories: ['fair_lending'], + }], }); expect(isError).toBeFalsy(); expect((result.plans as Array<{ status: string }>)[0].status).toBe('active'); + + const { result: check } = await simulateCallTool(server, 'check_governance', { + account, + plan_id: PLAN_BASE.plan_id, + caller: 'https://buyer.example', + tool: 'create_media_buy', + payload: { type: 'media_buy', account, total_budget: 20 }, + }); + expect(check.status).toBe('denied'); + const findings = check.findings as Array<{ category_id: string; severity: string }>; + expect(findings.find(f => f.category_id === 'human_review')?.severity).toBe('critical'); + }); + + it('keeps the derived flag out of the plan_hash preimage', async () => { + const server = createTrainingAgentServer(DEFAULT_CTX); + const account = { brand: { domain: 'preimage.example' }, operator: 'test.example' }; + const plan = { + ...PLAN_BASE, + brand: { ...PLAN_BASE.brand, domain: 'preimage.example' }, + policy_categories: ['fair_lending'], + }; + await simulateCallTool(server, 'sync_plans', { account, plans: [plan] }); + + const payload = { type: 'media_buy', account, total_budget: 20 }; + const { result: denied } = await simulateCallTool(server, 'check_governance', { + account, + plan_id: PLAN_BASE.plan_id, + caller: 'https://buyer.example', + tool: 'create_media_buy', + payload, + }); + expect(denied.status).toBe('denied'); + + const { result: approved } = await simulateCallTool(server, 'check_governance', { + account, + plan_id: PLAN_BASE.plan_id, + caller: 'https://buyer.example', + tool: 'create_media_buy', + ext: { + human_approval: { + approved_by: 'human-reviewer-1', + approved_at: '2099-03-15T12:00:00Z', + approval_reference: denied.check_id, + }, + }, + payload, + }); + expect(approved.status).toBe('approved'); + + const token = approved.governance_context as string; + const claims = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString()) as { plan_hash: string }; + expect(claims.plan_hash).toBe(computePlanHash(plan)); + expect(claims.plan_hash).not.toBe(computePlanHash({ ...plan, human_review_required: true })); }); it('rejects plan that sets human_review_required=false with fair_housing category', async () => { diff --git a/static/compliance/source/test-vectors/plan-hash/004b-human-review-explicit-null.json b/static/compliance/source/test-vectors/plan-hash/004b-human-review-explicit-null.json index 6d27fd0c6fd..bc9f8836818 100644 --- a/static/compliance/source/test-vectors/plan-hash/004b-human-review-explicit-null.json +++ b/static/compliance/source/test-vectors/plan-hash/004b-human-review-explicit-null.json @@ -1,7 +1,7 @@ { "name": "human_review_required explicitly null", "spec_reference": "#plan-state-binding (JCS preserves omitted vs null)", - "description": "Paired with 004a. Expected hash differs from 004a — explicit null is a distinct encoding.", + "description": "Paired with 004a. Expected hash differs from 004a — explicit null is a distinct encoding. Canonicalization only: plan_as_supplied is not a schema-valid sync_plans plan item, because human_review_required is typed boolean and null fails that type. A harness that validates plans against sync-plans-request.json before hashing should skip that validation for this vector.", "cross_reference": { "differs_from": "004a-human-review-omitted", "rationale": "Explicit null produces \"human_review_required\":null in JCS output; omitted produces no key at all. Distinct preimages → distinct hashes." diff --git a/static/schemas/source/governance/sync-plans-request.json b/static/schemas/source/governance/sync-plans-request.json index 51df934a931..627dbd9fe29 100644 --- a/static/schemas/source/governance/sync-plans-request.json +++ b/static/schemas/source/governance/sync-plans-request.json @@ -214,6 +214,15 @@ "flight": { "type": "object", "description": "Authorized flight dates. Governed actions with dates outside this window are rejected.", + "x-adcp-validation": { + "verifier_constraints": { + "flight_order": { + "end": "later_than_start", + "on_violation": "INVALID_REQUEST" + } + }, + "spec": "docs/governance/campaign/tasks/sync_plans.mdx#error-codes" + }, "properties": { "start": { "type": "string", @@ -223,7 +232,7 @@ "end": { "type": "string", "format": "date-time", - "description": "Flight end (ISO 8601)." + "description": "Flight end (ISO 8601). MUST be later than `start`." } }, "required": [ @@ -254,7 +263,16 @@ "type": "string", "x-entity": "governance_registry_policy" }, - "description": "Registry policy IDs to enforce for this plan. The governance agent resolves full policy definitions from the registry and evaluates actions against them. Intersected with the plan's countries/regions to activate only geographically relevant policies." + "description": "Registry policy IDs to enforce for this plan. Each ID MUST appear at most once. The governance agent resolves full policy definitions from the registry and evaluates actions against them. Intersected with the plan's countries/regions to activate only geographically relevant policies.", + "x-adcp-validation": { + "verifier_constraints": { + "unique_policy_ids": { + "policy_ids": "unique", + "on_violation": "INVALID_REQUEST" + } + }, + "spec": "docs/governance/campaign/tasks/sync_plans.mdx#error-codes" + } }, "policy_categories": { "type": "array", @@ -291,15 +309,23 @@ }, "human_review_required": { "type": "boolean", - "default": false, - "description": "When true, the governance agent MUST escalate any action on this plan for human review before execution — regardless of budget. Required by regulations that prohibit solely automated decisions affecting data subjects (GDPR Art 22, EU AI Act Annex III): credit, insurance pricing, recruitment, housing allocation. Governance agents MUST set this to true automatically when any resolved policy or policy_category has requires_human_review: true. Distinct from budget.reallocation_threshold, which only governs budget reallocation autonomy — human_review_required covers decisions affecting individuals (targeting, creative, delivery)." + "description": "When true, the governance agent MUST escalate any action on this plan for human review before execution — regardless of budget. Required by regulations that prohibit solely automated decisions affecting data subjects (GDPR Art 22, EU AI Act Annex III): credit, insurance pricing, recruitment, housing allocation. Governance agents MUST set this to true automatically when any resolved policy or policy_category has requires_human_review: true. When a plan omits this field, the governance agent derives it from the plan's resolved policies and policy categories; a caller-supplied false is rejected when any of them requires human review. Distinct from budget.reallocation_threshold, which only governs budget reallocation autonomy — human_review_required covers decisions affecting individuals (targeting, creative, delivery)." }, "custom_policies": { "type": "array", "items": { "$ref": "/schemas/governance/policy-entry.json" }, - "description": "Bespoke policies specific to this campaign, using the same shape as registry entries. Each policy has a policy_id, enforcement (must|should), and natural-language policy text. Governance findings reference policy_id to identify which policy triggered. For quick authoring, omit version/name/category — servers default them." + "description": "Bespoke policies specific to this campaign, using the same shape as registry entries. Each policy has a policy_id, enforcement (must|should), and natural-language policy text. A policy_id MUST NOT equal an ID in policy_ids. Governance findings reference policy_id to identify which policy triggered. For quick authoring, omit version/name/category — servers default them.", + "x-adcp-validation": { + "verifier_constraints": { + "registry_id_collision": { + "policy_id": "not_in_policy_ids", + "on_violation": "INVALID_REQUEST" + } + }, + "spec": "docs/governance/campaign/tasks/sync_plans.mdx#error-codes" + } }, "approved_sellers": { "type": [ @@ -450,10 +476,7 @@ "human_review_required": { "const": true } - }, - "required": [ - "human_review_required" - ] + } } }, { @@ -475,10 +498,7 @@ "human_review_required": { "const": true } - }, - "required": [ - "human_review_required" - ] + } } } ], diff --git a/tests/sync-plans-human-review.test.cjs b/tests/sync-plans-human-review.test.cjs new file mode 100644 index 00000000000..39c5abd6139 --- /dev/null +++ b/tests/sync-plans-human-review.test.cjs @@ -0,0 +1,110 @@ +const assert = require('node:assert/strict'); +const test = require('node:test'); +const Ajv = require('ajv'); +const addFormats = require('ajv-formats'); +const { ensureBuiltSchemas, readBuiltSchema } = require('../scripts/built-schemas.cjs'); + +ensureBuiltSchemas(); + +const readSchema = (relativePath) => readBuiltSchema(`/schemas/${relativePath}`); + +async function compile(options = {}) { + const ajv = new Ajv({ + allErrors: true, + strict: false, + discriminator: true, + loadSchema: async (uri) => readSchema(uri.replace('/schemas/', '')), + ...options, + }); + addFormats(ajv); + return ajv.compileAsync(readSchema('governance/sync-plans-request.json')); +} + +const errors = (validate) => JSON.stringify(validate.errors, null, 2); + +const request = (planFields = {}) => ({ + idempotency_key: 'human-review-plan-1', + plans: [{ + plan_id: 'human_review_campaign', + brand: { domain: 'acme.example' }, + objectives: 'Reach a broad audience.', + budget: { total: 1000, currency: 'USD', reallocation_threshold: 0 }, + flight: { start: '2026-10-01T00:00:00Z', end: '2026-11-01T00:00:00Z' }, + ...planFields, + }], +}); + +// Every input the schema's two if/then branches recognise as requiring human +// review (docs/governance/campaign/specification.mdx#human-review-required). +const TRIGGERS = { + 'policy_categories fair_housing': { policy_categories: ['fair_housing'] }, + 'policy_categories fair_lending': { policy_categories: ['fair_lending'] }, + 'policy_categories fair_employment': { policy_categories: ['fair_employment'] }, + 'policy_categories pharmaceutical_advertising': { policy_categories: ['pharmaceutical_advertising'] }, + 'policy_ids eu_ai_act_annex_iii': { policy_ids: ['eu_ai_act_annex_iii'] }, +}; + +const planItem = () => readSchema('governance/sync-plans-request.json').properties.plans.items; + +for (const [name, trigger] of Object.entries(TRIGGERS)) { + test(`a plan with ${name} that omits human_review_required validates`, async () => { + const validate = await compile(); + assert.equal(validate(request(trigger)), true, errors(validate)); + }); + + test(`a plan with ${name} and human_review_required true validates`, async () => { + const validate = await compile(); + assert.equal(validate(request({ ...trigger, human_review_required: true })), true, errors(validate)); + }); + + test(`a plan with ${name} and human_review_required false is rejected by const`, async () => { + const validate = await compile(); + assert.equal(validate(request({ ...trigger, human_review_required: false })), false, name); + assert.ok( + validate.errors.some( + (error) => error.keyword === 'const' && error.schemaPath.includes('/then/properties/human_review_required'), + ), + `${name}: ${errors(validate)}`, + ); + }); +} + +test('a plan with no trigger validates with the flag omitted, false or true', async () => { + const validate = await compile(); + assert.equal(validate(request()), true, errors(validate)); + assert.equal(validate(request({ human_review_required: false })), true, errors(validate)); + assert.equal(validate(request({ human_review_required: true })), true, errors(validate)); + assert.equal( + validate(request({ policy_categories: ['children_directed'], human_review_required: false })), + true, + errors(validate), + ); +}); + +test('human_review_required carries no default and says an omitted flag is derived', () => { + const field = planItem().properties.human_review_required; + assert.equal(field.type, 'boolean'); + assert.equal('default' in field, false, 'an omitted flag is derived by the governance agent, not defaulted'); + assert.match(field.description, /When a plan omits this field, the governance agent derives it/); + assert.match(field.description, /caller-supplied false is rejected/); +}); + +test('neither then branch requires the flag; both keep const true', () => { + const branches = planItem().allOf.filter((branch) => branch.then?.properties?.human_review_required); + assert.equal(branches.length, 2); + for (const branch of branches) { + assert.equal('required' in branch.then, false); + assert.equal(branch.then.properties.human_review_required.const, true); + } +}); + +// adcontextprotocol/adcp-client-python#1852: a consumer that applies schema +// defaults must not turn a valid omitted flag into a rejected explicit false. +test('a default-materializing consumer leaves an omitted flag omitted on a regulated plan', async () => { + const fillDefaults = await compile({ useDefaults: true }); + for (const [name, trigger] of Object.entries(TRIGGERS)) { + const instance = request(trigger); + assert.equal(fillDefaults(instance), true, `${name}: ${errors(fillDefaults)}`); + assert.equal('human_review_required' in instance.plans[0], false, name); + } +}); diff --git a/tests/sync-plans-validation-annotations.test.cjs b/tests/sync-plans-validation-annotations.test.cjs new file mode 100644 index 00000000000..1ef49128897 --- /dev/null +++ b/tests/sync-plans-validation-annotations.test.cjs @@ -0,0 +1,84 @@ +const assert = require('node:assert/strict'); +const test = require('node:test'); +const Ajv = require('ajv'); +const addFormats = require('ajv-formats'); +const { ensureBuiltSchemas, readBuiltSchema } = require('../scripts/built-schemas.cjs'); + +ensureBuiltSchemas(); + +const readSchema = (relativePath) => readBuiltSchema(`/schemas/${relativePath}`); + +async function compile() { + const ajv = new Ajv({ + allErrors: true, + strict: false, + discriminator: true, + loadSchema: async (uri) => readSchema(uri.replace('/schemas/', '')), + }); + addFormats(ajv); + return ajv.compileAsync(readSchema('governance/sync-plans-request.json')); +} + +const errors = (validate) => JSON.stringify(validate.errors, null, 2); + +const request = (planFields = {}) => ({ + idempotency_key: 'validation-annotations-plan-1', + plans: [{ + plan_id: 'validation_annotations_campaign', + brand: { domain: 'acme.example' }, + objectives: 'Reach a broad audience.', + budget: { total: 1000, currency: 'USD', reallocation_threshold: 0 }, + flight: { start: '2026-10-01T00:00:00Z', end: '2026-11-01T00:00:00Z' }, + ...planFields, + }], +}); + +const CUSTOM_POLICY = { policy_id: 'us_coppa', enforcement: 'must', policy: 'Do not target children under 13.' }; +const SPEC = 'docs/governance/campaign/tasks/sync_plans.mdx#error-codes'; + +const planProperties = () => readSchema('governance/sync-plans-request.json').properties.plans.items.properties; + +// The three rules are prose plus x-adcp-validation in 3.x. A governance agent +// rejects these plans with INVALID_REQUEST; the schema does not. +test('the schema still accepts the plans the three annotated rules reject', async () => { + const validate = await compile(); + assert.equal( + validate(request({ flight: { start: '2026-11-01T00:00:00Z', end: '2026-10-01T00:00:00Z' } })), + true, + errors(validate), + ); + assert.equal(validate(request({ policy_ids: ['us_coppa', 'us_coppa'] })), true, errors(validate)); + assert.equal( + validate(request({ policy_ids: ['us_coppa'], custom_policies: [CUSTOM_POLICY] })), + true, + errors(validate), + ); +}); + +test('flight carries the ordering rule and flight.end states it', () => { + const { flight } = planProperties(); + assert.deepEqual(flight['x-adcp-validation'], { + verifier_constraints: { flight_order: { end: 'later_than_start', on_violation: 'INVALID_REQUEST' } }, + spec: SPEC, + }); + assert.match(flight.properties.end.description, /MUST be later than `start`/); +}); + +test('policy_ids carries the uniqueness rule as an annotation, not as uniqueItems', () => { + const { policy_ids: policyIds } = planProperties(); + assert.deepEqual(policyIds['x-adcp-validation'], { + verifier_constraints: { unique_policy_ids: { policy_ids: 'unique', on_violation: 'INVALID_REQUEST' } }, + spec: SPEC, + }); + assert.equal('uniqueItems' in policyIds, false); + assert.match(policyIds.description, /Each ID MUST appear at most once/); +}); + +test('custom_policies carries the registry-id collision rule', () => { + const { custom_policies: customPolicies } = planProperties(); + assert.deepEqual(customPolicies['x-adcp-validation'], { + verifier_constraints: { registry_id_collision: { policy_id: 'not_in_policy_ids', on_violation: 'INVALID_REQUEST' } }, + spec: SPEC, + }); + assert.match(customPolicies.description, /A policy_id MUST NOT equal an ID in policy_ids/); +});