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
13 changes: 13 additions & 0 deletions .changeset/sync-plans-human-review-omission.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 3 additions & 3 deletions docs/governance/campaign/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down
9 changes: 5 additions & 4 deletions docs/governance/campaign/tasks/sync_plans.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -196,16 +196,17 @@ 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. |
| `plans[].audience` | object | No | Audience targeting constraints. Defines who the campaign should reach (include) and must not reach (exclude). See [audience constraints](#audience-constraints). |
| `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. |
Expand Down Expand Up @@ -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. |

Expand Down
2 changes: 1 addition & 1 deletion docs/governance/policy-registry-sync.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/known-limitations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/trust.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Loading
Loading