Module adcp.types.domains.governance.check_governance_response

Classes

class ActionBinding (**data: Any)

Expand source code

class ActionBinding(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    action_type: Annotated[
        Literal['https://adcontextprotocol.org/actions/governance-check'],
        Field(
            description='Absolute URI naming the action vocabulary, such as an AdCP governance-check or audience-evidence snapshot type.'
        ),
    ] = 'https://adcontextprotocol.org/actions/governance-check'
    action_id: Annotated[
        str,
        Field(
            description="Stable identifier of the consuming action within the domain consumer's namespace.",
            max_length=1024,
            min_length=1,
        ),
    ]
    action_digest: Annotated[
        str | None,
        Field(
            description='SHA-256 digest of the domain-defined canonical action preimage.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var action_digest : str | None

var action_id : str

var action_type : Literal['https://adcontextprotocol.org/actions/governance-check']

var model_config

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CanonicalPayload (**data: Any)

Expand source code

class CanonicalPayload(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    seller_reference: str
    delivery_metrics: dict[str, Any]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var delivery_metrics : dict[str, typing.Any]

var model_config

var seller_reference : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class CheckGovernanceResponse (**data: Any)

Expand source code

class CheckGovernanceResponse(AdcpResponse, AdcpVersionEnvelope):
    @model_validator(mode='before')
    @classmethod
    def _status_to_verdict(cls, data: Any) -> Any:
        if isinstance(data, dict) and 'verdict' not in data and 'status' in data:
            data = dict(data)
            data['verdict'] = data['status']
        return data

    model_config = ConfigDict(
        extra='allow',
    )
    check_id: Annotated[
        str,
        Field(
            description='Unique identifier for this governance check record. Use in report_plan_outcome to link outcomes to the check that authorized them.'
        ),
    ]
    verdict: Annotated[
        governance_decision.GovernanceDecision,
        Field(
            description='Governance verdict: approved | denied | conditions. Renamed from `status` in 3.1 to free the top-level `status` key for the envelope task-status (TaskStatus) under MCP flat-on-the-wire serialization. The enum values are unchanged; only the property name moved.'
        ),
    ]
    check_type: Annotated[
        CheckType | None,
        Field(
            description='Check shape that produced the verdict. Required for the cross-role governance_enforcement contract. Its presence selects the modern verdict-specific response rules; its absence selects the deprecated legacy 3.x compatibility shape. Intent checks may return conditions; execution checks are binary approved or denied.'
        ),
    ] = None
    plan_id: Annotated[
        str | None,
        Field(
            description='Plan identifier echoed on an initial plan-addressed check. Optional on continuation checks addressed by governance_context; services do not need this value and MUST treat the token binding as authoritative.'
        ),
    ] = None
    explanation: Annotated[
        str, Field(description='Human-readable explanation of the governance decision.')
    ]
    findings: Annotated[
        list[Finding] | None,
        Field(
            description="Specific issues found during the governance check. Present when verdict is 'denied' or 'conditions'. MAY also be present on 'approved' for informational findings (e.g., budget approaching limit)."
        ),
    ] = None
    conditions: Annotated[
        list[Condition] | None,
        Field(
            description="Intent-phase counterproposal. Present only when verdict is 'conditions'. It does not authorize execution and MUST NOT be returned for execution or lifecycle checks. Each field path is rooted at the complete check_governance request arguments, so both payload.* and proposed_commitment.* can be addressed. After applying conditions, the caller MUST re-call check_governance with the adjusted parameters and receive approved before proceeding."
        ),
    ] = None
    consultation_context: Annotated[
        str | None,
        Field(
            description='Opaque negotiation handle present only with modern conditions responses. It carries no authorization and MUST NOT be sent to a downstream service. The governance agent MUST bind it server-side to the authenticated principal, caller, plan, tool, purchase type, and target audience, and reject a re-check if any binding changes. The buyer returns it only on the adjusted intent re-check.',
            max_length=255,
            min_length=1,
            pattern='^[A-Za-z0-9_.:-]+$',
        ),
    ] = None
    expires_at: Annotated[
        AwareDatetime | None,
        Field(
            description="When this approval expires. In the cross-role shape, present only when verdict is 'approved'. Deprecated legacy conditions responses may also carry it for 3.x compatibility. The caller must act before this time or re-call check_governance. A lapsed approval is no approval."
        ),
    ] = None
    next_check: Annotated[
        AwareDatetime | None,
        Field(
            description='When the seller should next call check_governance with delivery metrics. Present when the governance agent expects ongoing delivery reporting.'
        ),
    ] = None
    delivery_statement: Annotated[
        DeliveryStatement | None,
        Field(
            description='Canonical seller-attributed delivery statement retained by governance. Present on delivery execution checks. The buyer binds any later observation to this exact statement through report_plan_outcome.'
        ),
    ] = None
    categories_evaluated: Annotated[
        list[str] | None,
        Field(
            description="Governance categories evaluated during this check. Each value is an **agent-internal** label (e.g., `budget_authority`, `regulatory_compliance`, or any internal-reviewer key the agent's policy model defines) — not a protocol-level enum. Since one governance agent per account composes all specialist review behind its single endpoint, `categories_evaluated` is how that internal decomposition surfaces to auditors. Consumers MUST treat values as opaque labels for display and audit, not as a machine-level contract."
        ),
    ] = None
    policies_evaluated: Annotated[
        list[str] | None,
        Field(
            description="Policy IDs evaluated during this check. Includes registry policy IDs (resolved via the policy registry) and any inline `policy_id`s declared in the plan's `custom_policies`."
        ),
    ] = None
    mode: Annotated[
        governance_mode.GovernanceMode | None,
        Field(
            description='Governance enforcement mode active when this check was evaluated. Allows counterparties, regulators, and auditors to distinguish whether a finding blocked execution (enforce) or was logged silently (audit).'
        ),
    ] = None
    runtime_attestation_evaluations: Annotated[
        list[RuntimeAttestationEvaluation] | None,
        Field(
            description="Evaluator-of-record results for request runtime_attestations[], in the same order and with exactly one result per presentation. Each result is the shared AttestationEvaluation and MUST bind to this response's check_id through action_binding.action_type = https://adcontextprotocol.org/actions/governance-check and action_binding.action_id = check_id. The signed governance_context MUST bind the same reference_digest/outcome pairs; large evidence stays in the audit log rather than the token.",
            max_length=10,
            min_length=1,
        ),
    ] = None
    runtime_attestation_binding_digest: Annotated[
        str | None,
        Field(
            description='SHA-256 of RFC 8785 JCS({ evaluations: runtime_attestation_evaluations, findings: attestation_bound_findings }), where attestation_bound_findings is the response findings[] subset carrying attestation_reference_digest, preserved in response order. Required whenever runtime_attestation_evaluations is present. The governance_context JWS carries this exact value as runtime_attestation_binding_digest; get_plan_audit_logs retains ordered {reference, evaluation} pairs so auditors can first recompute every reference_digest and then prove which evaluations and findings the signed decision relied on.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ] = None
    governance_context: Annotated[
        str | None,
        Field(
            description='Opaque authorization context for this governed action. Present only when verdict is approved; denied and conditions responses MUST NOT carry it. The buyer attaches it to the protocol envelope when sending the governed request. The service persists and forwards it on subsequent execution and lifecycle checks without requiring plan_id.\n\nGovernance agents MUST emit a compact JWS per the AdCP JWS profile. Verifiers validate the standard authorization claims but MUST NOT interpret embedded governance state for business logic. The issuing governance agent uses the token to recover its internal plan and decision state.',
            max_length=4096,
            min_length=1,
            pattern='^[\\x20-\\x7E]+$',
        ),
    ] = None
    context: context_1.ContextObject | None = None
    ext: ext_1.ExtensionObject | None = None

The response message of a task in the pinned bundle's task registry.

A consumer holding one can route on task state, pick up an async task_id, split envelope from payload and log uniformly, before knowing which tool answered. Which makes one generic poll-to-terminal loop possible for all 77 tasks, where today each arm has no common type at all.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdcpResponse
• adcp.types.base._AdcpMessage
• AdcpVersionEnvelope
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var categories_evaluated : list[str] | None

var check_id : str

var check_type : CheckType | None

var conditions : list[Condition] | None

var consultation_context : str | None

var context : ContextObject | None

var delivery_statement : DeliveryStatement | None

var expires_at : pydantic.types.AwareDatetime | None

var explanation : str

var ext : ExtensionObject | None

var findings : list[Finding] | None

var governance_context : str | None

var mode : GovernanceMode | None

var model_config

var next_check : pydantic.types.AwareDatetime | None

var plan_id : str | None

var policies_evaluated : list[str] | None

var runtime_attestation_binding_digest : str | None

var runtime_attestation_evaluations : list[RuntimeAttestationEvaluation] | None

var verdict : GovernanceDecision

Inherited members

• AdcpResponse:
  • get_adcp_error
  • get_context
  • get_message
  • get_replayed
  • get_status
  • get_task_id
• AdcpVersionEnvelope:
  • model_dump
  • model_dump_json
  • model_summary

class CheckType (*args, **kwds)

Expand source code

class CheckType(StrEnum):
    intent = 'intent'
    execution = 'execution'

Enum where members are also (and must be) strings

Ancestors

• enum.StrEnum
• builtins.str
• enum.ReprEnum
• enum.Enum

Class variables

var execution

var intent

class Condition (**data: Any)

Expand source code

class Condition(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    field: Annotated[
        str,
        Field(
            description='Dot-path rooted at the complete check_governance request arguments (for example payload.total_budget.amount or proposed_commitment.amount). Conditions are not valid for committed execution checks.'
        ),
    ]
    required_value: Annotated[
        Any | None,
        Field(
            description='The value the field must have for approval. When present, the condition is machine-actionable. When absent, the condition is advisory.'
        ),
    ] = None
    reason: Annotated[str, Field(description='Why this condition is required.')]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var field : str

var model_config

var reason : str

var required_value : typing.Any | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class DeliveryStatement (**data: Any)

Expand source code

class DeliveryStatement(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    statement_id: str
    statement_digest: Annotated[str, Field(pattern='^sha256:[a-f0-9]{64}$')]
    sequence: Annotated[SchemaInt, Field(ge=1)]
    issued_at: AwareDatetime
    seller_reference: str
    reporting_period: ReportingPeriod
    cumulative_spend: Annotated[StrictFloat, Field(ge=0.0)]
    currency: Annotated[str, Field(pattern='^[A-Z]{3}$')]
    canonical_payload: Annotated[
        CanonicalPayload,
        Field(
            description='Exact retained digest-bearing payload. To verify statement_digest, apply RFC 8785 JCS after removing delivery_metrics.statement_digest.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var canonical_payload : CanonicalPayload

var cumulative_spend : float

var currency : str

var issued_at : pydantic.types.AwareDatetime

var model_config

var reporting_period : ReportingPeriod

var seller_reference : str

var sequence : int

var statement_digest : str

var statement_id : str

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class Finding (**data: Any)

Expand source code

class Finding(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    category_id: Annotated[
        str,
        Field(
            description="Validation category that flagged the issue (e.g., 'budget_compliance', 'regulatory_compliance', 'brand_safety'). This is an **agent-internal** taxonomy: the string is defined by the governance agent's own policy model and is not constrained to any protocol-level enum. Sellers and buyers MUST NOT pattern-match `category_id` values against a fixed list — treat them as opaque labels with human-readable significance for audit but no machine-level contract. See the Campaign Governance specification for how an agent composes internal specialist review behind one endpoint."
        ),
    ]
    policy_id: Annotated[
        str | None,
        Field(
            description="ID of the policy that triggered this finding. May reference a registry policy (with source: registry) or a bespoke inline policy (with source: inline). Bespoke policy_ids are unique within their authoring container; use source_plan_id when findings aggregate across multiple plans (e.g., portfolio evaluations). When the violation traces to a producer-tagged surface (feature-requirement, creative-feature-result, or validation-result feature) carrying policy_id, governance agents SHOULD echo that policy_id here for end-to-end traceability, and MUST NOT invent a policy_id that wasn't present on the originating surface. See /docs/governance/policy-attribution."
        ),
    ] = None
    source_plan_id: Annotated[
        str | None,
        Field(
            description="For portfolio or aggregated evaluations where findings draw on bespoke policies from multiple member plans: identifies the plan whose policy triggered this finding. Omit when the finding's policy_id is unambiguous within the response context (e.g., single-plan check_governance)."
        ),
    ] = None
    severity: escalation_severity.EscalationSeverity
    explanation: Annotated[str, Field(description='Human-readable description of the issue.')]
    details: Annotated[
        dict[str, Any] | None, Field(description='Structured details for programmatic consumption.')
    ] = None
    confidence: Annotated[
        StrictFloat | None,
        Field(
            description="Confidence score (0-1) in this finding. Distinguishes 'this definitely violates the policy' (0.95) from 'this might violate depending on how audience segments resolve' (0.6). When absent, the finding is presented without a confidence qualifier.",
            ge=0.0,
            le=1.0,
        ),
    ] = None
    uncertainty_reason: Annotated[
        str | None,
        Field(
            description="Explanation of why confidence is below 1.0 (e.g., 'Targeting includes regions that partially overlap jurisdiction boundaries'). Present when confidence is below a governance-agent-defined threshold."
        ),
    ] = None
    attestation_reference_digest: Annotated[
        str | None,
        Field(
            description='When this finding relies on or reports a runtime attestation evaluation, the reference_digest of the exact AttestationReference in runtime_attestation_evaluations[]. Findings MUST NOT copy credential bodies or treat a presenter assertion as verified evidence.',
            pattern='^sha256:[a-f0-9]{64}$',
        ),
    ] = None

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var attestation_reference_digest : str | None

var category_id : str

var confidence : float | None

var details : dict[str, typing.Any] | None

var explanation : str

var model_config

var policy_id : str | None

var severity : EscalationSeverity

var source_plan_id : str | None

var uncertainty_reason : str | None

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class ReportingPeriod (**data: Any)

Expand source code

class ReportingPeriod(AdCPBaseModel):
    model_config = ConfigDict(
        extra='forbid',
    )
    start: AwareDatetime
    end: AwareDatetime

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var end : pydantic.types.AwareDatetime

var model_config

var start : pydantic.types.AwareDatetime

Inherited members

• AdCPBaseModel:
  • model_dump
  • model_dump_json
  • model_summary

class RuntimeAttestationEvaluation (**data: Any)

Expand source code

class RuntimeAttestationEvaluation(AttestationEvaluation):
    action_binding: Annotated[
        ActionBinding,
        Field(
            description='Optional binding to the consuming action or readback. Domain consumers that rely on an evaluation MUST carry either an action id or an action digest so the result cannot be transplanted to an unrelated decision.'
        ),
    ]

Base model for AdCP types with spec-compliant serialization.

Defaults to extra='ignore' so unknown fields from newer spec versions are silently dropped rather than causing validation errors. Generated types whose schemas set additionalProperties: true override this with extra='allow' in their own model_config.

Set ADCP_STRICT_VALIDATION=1 in the environment ("1", "true", "yes", "on" are accepted) to flip the default to extra='forbid'. Use this during spec upgrades to catch silently-dropped renamed fields in tests. See :func:_resolve_extra_policy.

Important

The env var is resolved once at module import time. Set it in your shell or CI environment before import adcp runs — mutating os.environ["ADCP_STRICT_VALIDATION"] after the first adcp import has no effect on already-imported model classes (they captured the policy at class-body evaluation).

Consumers who want per-model strict validation can override model_config on their subclass.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

• AttestationEvaluation
• AdCPBaseModel
• pydantic.main.BaseModel

Class variables

var action_binding : ActionBinding

var model_config

Inherited members

• AttestationEvaluation:
  • model_dump
  • model_dump_json
  • model_summary