Document Policy Registry sync pattern: version pinning, change handling, effective_date transitions

[bokelley]

Problem

The governance working group asked how to maintain a "clear, easy-to-synchronize Policy Registry" alongside per-counterparty thresholds. The Policy Registry already supports the underlying mechanics (semver version, effective_date, sunset_date, enforcement levels, requires_human_review), but the docs don't lay out the operational pattern for buyers and sellers to:

1. Pin policy versions at plan creation time so a campaign's policy set is deterministic for the duration of the buy
2. Handle registry version bumps mid-campaign (do running buys re-evaluate? does only report_plan_outcome continue under the pinned version?)
3. Use effective_date for "minimal restrictions initially" — publish a policy with a future date so it surfaces as informational findings until enforcement begins
4. Detect and react to sunset_date so a sunsetted policy stops being enforced cleanly
5. Layer inline custom_policies with the additive-only invariant (cannot relax registry policies)

Proposed scope

Extend docs/governance/policy-registry.mdx with a new "Sync and versioning" section. Should include:

• Pinning pattern (which field on the plan binds to a specific policy version)
• Behavior on registry version bump for active plans
• The effective_date informational pattern with a worked example
• Inline policies under the additive-only invariant — what's allowed, what's not
• A short FAQ for the questions that come up (per-jurisdiction overrides, brand-specific extensions, sunset handling)

Why now

Without this guidance, working groups land on bespoke synchronization patterns and the protocol's existing primitives go unused. This is a docs-only change; no protocol work required.

References

• [Governance WG discussion summary] (Slack, 2026-04-25)
• Policy Registry
• Policy Entry schema

[bokelley]

Triage

Classification: Feature request (doc extension)
Bucket(s): web / site / docs
Status: drafting-pr

What the experts said:

• docs-expert: version pinning and additive-only invariant belong in specification.mdx, not policy-registry.mdx; effective_date worked example should expand the existing Temporal enforcement section in place; custom_policies plain-string examples in two files are schema-invalid (PolicyEntry[] required)
• ad-tech-protocol-expert: plan-level policy_ids carries no version field — pinning only works via policy-ref.json in brand compliance config; mid-campaign re-resolution semantics are protocol-undefined (must not invent an answer); requires_human_review fires immediately on policy resolution regardless of effective_date; sunset is pull-based wall-clock, no push notification

My take: All five topics from the issue are covered, distributed across the files where they land cleanest. Also bundles a pre-existing schema mismatch fix: custom_policies and shared_exclusions examples showed plain strings but the schema requires PolicyEntry objects throughout.

Drafting PR #3143.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01XuqvXPFRgFRL9tWA9drHCM

---

Generated by Claude Code