@adcp/sdk 7.10.2 → 7.11.1

package/compliance/cache/3.1.0-rc.2/protocols/brand/scenarios/distributed_brand_resolution.yaml

@@ -0,0 +1,415 @@
+id: brand/distributed_brand_resolution
+version: "1.0.0"
+title: "Distributed brand.json mutual assertion resolves identity and relationship trust"
+category: brand_baseline
+summary: "Consumer-under-test storyboard for AdCP 3.1 distributed brand.json: a house portfolio points at a child Brand Canonical Document, the child points back with house_domain, mutual assertion unlocks relationship trust, one-sided claims do not, identity stays brand-authored, compliance merges strictest-of, managed_by is directory metadata, and typed trademarks validate at the static-file layer."
+track: brand
+required_tools:
+  - comply_test_controller
+
+narrative: |
+  AdCP 3.1 adds the distributed `brand.json` path: a house can keep portfolio
+  authority through `brand_refs[]` while a child brand self-publishes its own
+  Brand Canonical Document. Consumers have to resolve two separate trust
+  questions:
+
+  1. Identity trust: the leaf's TLS-served canonical document is authoritative
+     for the leaf's own identity fields.
+  2. Relationship trust: the parent/child relationship becomes trust-extending
+     only when the leaf's `house_domain` and the house's `brand_refs[]` entry
+     reciprocate.
+
+  This storyboard grades a CONSUMER of distributed `brand.json` resolution, not
+  a brand-agent task implementation. The runner hosts fixture static documents
+  and dispatches the consumer under test through the opt-in
+  `evaluate_distributed_brand_resolution` controller scenario documented in
+  `test-kits/distributed-brand-runner.yaml`.
+
+  The consumer reports its resolution decision to the runner's observation
+  endpoint. The runner then applies `upstream_traffic` assertions to prove the
+  decision distinguished identity trust from relationship trust, applied the
+  strictest-of compliance merge, ignored `managed_by` as a trust edge, and
+  rejected schema-invalid typed trademark fixtures. Consumers that do not
+  advertise the runner contract grade `not_applicable`; consumers that opt in
+  but report a contradictory decision fail.
+
+agent:
+  interaction_model: brand_resolution_consumer
+  capabilities: []
+  examples:
+    - "AgenticAdvertising.org registry crawler resolving distributed brand.json documents"
+    - "Buyer-side DSP or governance platform deciding whether portfolio trust can propagate from a house to a self-published child brand"
+    - "Membership or billing system evaluating whether a child brand can inherit house-level governance posture"
+
+caller:
+  role: compliance_runner
+  example: "AdCP Verified runner with distributed brand.json consumer-under-test dispatch capability"
+
+prerequisites:
+  description: |
+    The runner hosts the fixture static `brand.json` documents and result
+    observation endpoint documented in `test-kits/distributed-brand-runner.yaml`.
+    The consumer under test advertises a comply_test_controller scenario named
+    `evaluate_distributed_brand_resolution`. Consumers that do not advertise
+    this scenario grade every step `not_applicable`, avoiding false failures
+    until the consumer-dispatch primitive is implemented by adopters.
+  test_kit: "test-kits/distributed-brand-runner.yaml"
+
+phases:
+  - id: mutual_assertion_happy_path
+    title: "Mutual assertion establishes relationship trust"
+    narrative: |
+      The fixture house `nova-house.example` publishes `brand_refs[]` pointing
+      at `leaf-brand.example`. The leaf publishes a Brand Canonical Document
+      whose `house_domain` points back to `nova-house.example`. The consumer
+      must fetch both documents, treat identity fields as leaf-authored, and
+      upgrade the relationship edge to `mutual`.
+
+    steps:
+      - id: resolve_mutual_assertion
+        title: "Resolve reciprocal house and child documents"
+        narrative: |
+          The runner dispatches the consumer under test with the reciprocal
+          fixture pair. A passing consumer fetches both documents, reports
+          `relationship.trust_tier: mutual`, uses the leaf document as the
+          identity source, merges house and leaf compliance fields
+          strictest-of, and keeps `managed_by` out of the trust decision.
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        requires_contract: distributed_brand_runner
+        sample_request_skip_schema: true
+        stateful: true
+        expected: |
+          The consumer resolves a mutual assertion and reports a decision
+          showing relationship trust, leaf-authored identity, strictest-of
+          compliance merge, and non-trust treatment for managed_by.
+        sample_request:
+          scenario: evaluate_distributed_brand_resolution
+          account:
+            sandbox: true
+          params:
+            variant: mutual_assertion
+            house_domain: "nova-house.example"
+            house_brand_json_url: "https://nova-house.example/.well-known/brand.json"
+            leaf_domain: "leaf-brand.example"
+            leaf_brand_json_url: "https://leaf-brand.example/.well-known/brand.json"
+            brand_id: "leaf_brand"
+            result_endpoint: "https://runner.example/distributed-brand-resolution/result"
+          context:
+            correlation_id: "brand--distributed_brand--mutual--dispatch"
+        validations:
+          - check: upstream_traffic
+            description: "Consumer fetched the house portfolio document"
+            endpoint_pattern: "GET *nova-house.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.house_domain"
+          - check: upstream_traffic
+            description: "Consumer fetched the leaf Brand Canonical Document"
+            endpoint_pattern: "GET *leaf-brand.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.leaf_domain"
+          - check: upstream_traffic
+            description: "Consumer reported mutual relationship trust and leaf-authored identity"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "variant"
+                match: equals
+                value: "mutual_assertion"
+              - path: "relationship.trust_tier"
+                match: equals
+                value: "mutual"
+              - path: "relationship.trust_extending"
+                match: equals
+                value: true
+              - path: "identity.source_domain"
+                match: equals
+                value: "leaf-brand.example"
+              - path: "identity.brand_id"
+                match: equals
+                value: "leaf_brand"
+              - path: "identity.tagline"
+                match: equals
+                value: "Built by Leaf Brand"
+              - path: "relationship.managed_by_trust_edge"
+                match: equals
+                value: false
+            identifier_paths:
+              - "params.house_domain"
+              - "params.leaf_domain"
+              - "params.brand_id"
+          - check: upstream_traffic
+            description: "Consumer reported strictest-of compliance union from both house and leaf"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "compliance.policy_ids[*]"
+                match: equals
+                value: "house_art22_review"
+              - path: "compliance.policy_ids[*]"
+                match: equals
+                value: "leaf_no_sensitive_segments"
+              - path: "compliance.data_subject_contestation_contacts[*].domain"
+                match: equals
+                value: "nova-house.example"
+              - path: "compliance.data_subject_contestation_contacts[*].domain"
+                match: equals
+                value: "leaf-brand.example"
+          - check: upstream_traffic
+            description: "Consumer accepted valid typed brand-level trademark values"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "trademark_validation.valid_fixture_schema"
+                match: equals
+                value: true
+              - path: "trademarks[*].mark"
+                match: equals
+                value: "LEAF BRAND"
+              - path: "trademarks[*].status"
+                match: equals
+                value: "active"
+              - path: "trademarks[*].countries[*]"
+                match: equals
+                value: "US"
+              - path: "trademarks[*].nice_classes[*]"
+                match: equals
+                value: 35
+
+  - id: one_sided_assertions
+    title: "One-sided assertions keep identity trust but block relationship trust"
+    narrative: |
+      Distributed brand resolution is intentionally asymmetric. The leaf can
+      prove its own identity by serving a Brand Canonical Document over TLS,
+      but it cannot cause the house relationship to become trust-extending
+      unless the house reciprocates. Likewise, a house-side `brand_refs[]`
+      entry or `managed_by` directory metadata cannot substitute for the leaf's
+      `house_domain`.
+
+    steps:
+      - id: resolve_leaf_only_assertion
+        title: "Reject relationship trust when the house is silent"
+        narrative: |
+          The leaf fixture claims `house_domain: nova-house.example`, but the
+          house fixture omits the leaf from `brand_refs[]`. The consumer must
+          preserve identity trust for the leaf's own fields and block
+          governance or billing trust propagation.
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        requires_contract: distributed_brand_runner
+        sample_request_skip_schema: true
+        stateful: true
+        expected: |
+          The consumer reports identity_trusted: true but relationship trust
+          unverified, and no trust-extension side effects fire.
+        sample_request:
+          scenario: evaluate_distributed_brand_resolution
+          account:
+            sandbox: true
+          params:
+            variant: leaf_only
+            house_domain: "nova-house.example"
+            house_brand_json_url: "https://nova-house.example/.well-known/brand.json"
+            leaf_domain: "leaf-only-brand.example"
+            leaf_brand_json_url: "https://leaf-only-brand.example/.well-known/brand.json"
+            brand_id: "leaf_only_brand"
+            result_endpoint: "https://runner.example/distributed-brand-resolution/result"
+          context:
+            correlation_id: "brand--distributed_brand--leaf_only--dispatch"
+        validations:
+          - check: upstream_traffic
+            description: "Consumer fetched the leaf document before rejecting relationship trust"
+            endpoint_pattern: "GET *leaf-only-brand.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.leaf_domain"
+          - check: upstream_traffic
+            description: "Consumer fetched the house portfolio document before rejecting relationship trust"
+            endpoint_pattern: "GET *nova-house.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.house_domain"
+          - check: upstream_traffic
+            description: "Consumer reported trusted identity but unverified relationship"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "variant"
+                match: equals
+                value: "leaf_only"
+              - path: "identity.trusted"
+                match: equals
+                value: true
+              - path: "identity.source_domain"
+                match: equals
+                value: "leaf-only-brand.example"
+              - path: "relationship.trust_tier"
+                match: equals
+                value: "leaf_only"
+              - path: "relationship.trust_extending"
+                match: equals
+                value: false
+          - check: upstream_traffic
+            description: "Consumer did not extend governance trust for leaf-only assertion"
+            endpoint_pattern: "POST */governance/contexts"
+            min_count: 0
+          - check: upstream_traffic
+            description: "Consumer did not auto-add the leaf to billable house scope"
+            endpoint_pattern: "POST */billing/seats/auto-add"
+            min_count: 0
+
+      - id: resolve_managed_by_only_assertion
+        title: "Do not treat managed_by as a trust edge"
+        narrative: |
+          The house fixture lists `managed_by: aurora-agency.example` on a
+          `brand_refs[]` entry while the leaf fixture has no reciprocal
+          `house_domain`. The consumer may expose the manager as directory
+          metadata, but relationship trust remains blocked.
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        requires_contract: distributed_brand_runner
+        sample_request_skip_schema: true
+        stateful: true
+        expected: |
+          The consumer reports managed_by as directory metadata only and does
+          not use the manager domain to complete relationship trust.
+        sample_request:
+          scenario: evaluate_distributed_brand_resolution
+          account:
+            sandbox: true
+          params:
+            variant: managed_by_only
+            house_domain: "nova-house.example"
+            house_brand_json_url: "https://nova-house.example/.well-known/brand.json"
+            leaf_domain: "managed-leaf.example"
+            leaf_brand_json_url: "https://managed-leaf.example/.well-known/brand.json"
+            brand_id: "managed_leaf"
+            manager_domain: "aurora-agency.example"
+            result_endpoint: "https://runner.example/distributed-brand-resolution/result"
+          context:
+            correlation_id: "brand--distributed_brand--managed_by--dispatch"
+        validations:
+          - check: upstream_traffic
+            description: "Consumer fetched the house-side managed_by directory entry"
+            endpoint_pattern: "GET *nova-house.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.house_domain"
+          - check: upstream_traffic
+            description: "Consumer fetched the leaf document to confirm no reciprocal house_domain"
+            endpoint_pattern: "GET *managed-leaf.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.leaf_domain"
+          - check: upstream_traffic
+            description: "Consumer reported managed_by without upgrading trust"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "variant"
+                match: equals
+                value: "managed_by_only"
+              - path: "directory.managed_by"
+                match: equals
+                value: "aurora-agency.example"
+              - path: "relationship.trust_tier"
+                match: equals
+                value: "house_only"
+              - path: "relationship.trust_extending"
+                match: equals
+                value: false
+              - path: "relationship.managed_by_trust_edge"
+                match: equals
+                value: false
+            identifier_paths:
+              - "params.manager_domain"
+          - check: upstream_traffic
+            description: "Consumer did not treat the manager as a governance-trust authority"
+            endpoint_pattern: "POST */governance/auto-provision"
+            min_count: 0
+
+  - id: typed_trademark_rejection
+    title: "Invalid typed trademarks are rejected"
+    narrative: |
+      Brand-level `trademarks[]` now have typed enum and range constraints. A
+      consumer that accepts the valid fixture must also reject invalid enum,
+      country, and Nice Classification values instead of silently promoting
+      them into the resolved brand graph.
+
+    steps:
+      - id: reject_invalid_trademark_fixture
+        title: "Reject schema-invalid trademark values"
+        narrative: |
+          The invalid fixture uses a non-enum `status`, a non-ISO
+          `countries[]` entry, and an out-of-range `nice_classes[]` value.
+          The consumer reports these as static-file schema failures and does
+          not extend relationship trust from the invalid document.
+        task: comply_test_controller
+        schema_ref: "compliance/comply-test-controller-request.json"
+        response_schema_ref: "compliance/comply-test-controller-response.json"
+        doc_ref: "/building/implementation/comply-test-controller"
+        requires_contract: distributed_brand_runner
+        sample_request_skip_schema: true
+        stateful: true
+        expected: |
+          The consumer reports trademark validation failure paths and does not
+          treat the invalid leaf document as a trust-extending relationship
+          edge.
+        sample_request:
+          scenario: evaluate_distributed_brand_resolution
+          account:
+            sandbox: true
+          params:
+            variant: invalid_trademark
+            house_domain: "nova-house.example"
+            house_brand_json_url: "https://nova-house.example/.well-known/brand.json"
+            leaf_domain: "invalid-mark-brand.example"
+            leaf_brand_json_url: "https://invalid-mark-brand.example/.well-known/brand.json"
+            brand_id: "invalid_mark_brand"
+            result_endpoint: "https://runner.example/distributed-brand-resolution/result"
+          context:
+            correlation_id: "brand--distributed_brand--invalid_trademark--dispatch"
+        validations:
+          - check: upstream_traffic
+            description: "Consumer fetched the invalid trademark fixture"
+            endpoint_pattern: "GET *invalid-mark-brand.example/.well-known/brand.json"
+            min_count: 1
+            identifier_paths:
+              - "params.leaf_domain"
+          - check: upstream_traffic
+            description: "Consumer reported schema failures for typed trademark fields"
+            endpoint_pattern: "POST */distributed-brand-resolution/result"
+            min_count: 1
+            attestation_mode_required: "raw"
+            payload_must_contain:
+              - path: "variant"
+                match: equals
+                value: "invalid_trademark"
+              - path: "trademark_validation.valid_fixture_schema"
+                match: equals
+                value: false
+              - path: "trademark_validation.error_paths[*]"
+                match: equals
+                value: "trademarks[0].status"
+              - path: "trademark_validation.error_paths[*]"
+                match: equals
+                value: "trademarks[0].countries[0]"
+              - path: "trademark_validation.error_paths[*]"
+                match: equals
+                value: "trademarks[0].nice_classes[0]"
+              - path: "relationship.trust_extending"
+                match: equals
+                value: false