@adcp/sdk 6.9.0 → 6.11.0

package/compliance/cache/3.0.6.previous/specialisms/property-lists/index.yaml

@@ -0,0 +1,482 @@
+id: property_lists
+version: "1.0.0"
+title: "Property lists"
+protocol: governance
+category: property_lists
+summary: "Curated property lists for inventory grouping, targeting governance, and delivery compliance — create, query, update, delete, and validate."
+track: governance
+required_tools:
+  - create_property_list
+
+# Cross-step assertion (adcp#2664). status.monotonic rejects resource
+# status transitions observed across steps that aren't on the spec
+# lifecycle graph. Silent on property-list-only runs (no tracked
+# lifecycle resource), but wired so phases that touch media_buy /
+# account status (e.g. via a validation run against delivery) are
+# automatically gated.
+invariants:
+  - status.monotonic
+
+narrative: |
+  You run a governance agent that manages property lists for brand safety. Buyers create
+  inclusion and exclusion lists that define where their ads can and cannot appear. Your
+  agent stores these lists, lets buyers query and update them, and validates that actual
+  ad delivery complied with the property constraints.
+
+  Property governance is how brands control their environment. An inclusion list says
+  "only show my ads on these properties." An exclusion list says "never show my ads here."
+  The validation step checks after the fact: did the seller actually respect the lists?
+
+  This storyboard covers the full property list lifecycle: creating lists, querying them,
+  updating and deleting, and validating that delivery matched the constraints.
+
+agent:
+  interaction_model: governance_agent
+  capabilities:
+    - property_lists
+    - brand_safety
+  examples:
+    - "IAS"
+    - "DoubleVerify"
+    - "GARM-aligned platforms"
+    - "Brand safety services"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity and property domain knowledge. The test kit
+    provides a sample brand with campaign context.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: capability_discovery
+    title: "Capability discovery"
+    narrative: |
+      The buyer calls get_adcp_capabilities to confirm the agent supports governance before registering plans or checking compliance.
+
+    steps:
+      - id: get_capabilities
+        title: "Check agent capabilities"
+        narrative: |
+          Verify that the agent declares the expected protocol support before
+          proceeding with domain-specific operations.
+        task: get_adcp_capabilities
+        schema_ref: "protocol/get-adcp-capabilities-request.json"
+        response_schema_ref: "protocol/get-adcp-capabilities-response.json"
+        doc_ref: "/protocol/get_adcp_capabilities"
+        comply_scenario: capability_discovery
+        stateful: false
+        expected: |
+          Return capabilities declaring governance in supported_protocols, confirming the agent provides governance services.
+        sample_request:
+          context:
+            correlation_id: "property_lists--get_capabilities"
+        validations:
+          - check: response_schema
+            description: "Response matches get-adcp-capabilities-response.json schema"
+          - check: field_present
+            path: "supported_protocols"
+            description: "Agent declares supported protocols"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--get_capabilities"
+            description: "Context correlation_id returned unchanged"
+  - id: create_list
+    title: "Create property lists"
+    narrative: |
+      The buyer creates inclusion and exclusion property lists for the campaign. These
+      define the safe and unsafe environments for the brand's ads.
+
+    steps:
+      - id: create_inclusion_list
+        title: "Create an inclusion list"
+        narrative: |
+          The buyer creates an inclusion list specifying which properties (domains,
+          apps, channels) are approved for ad placement.
+        task: create_property_list
+        schema_ref: "property/create-property-list-request.json"
+        response_schema_ref: "property/create-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the created property list:
+          - list_id: platform-assigned identifier
+          - list_type: inclusion
+          - Properties registered
+          - Status: active
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          brand:
+            domain: "acmeoutdoor.example"
+          name: "Acme Outdoor approved properties"
+          base_properties:
+            - selection_type: "identifiers"
+              identifiers:
+                - type: "domain"
+                  value: "outdoormagazine.example"
+                - type: "domain"
+                  value: "hikingtrails.example"
+                - type: "domain"
+                  value: "campinggear.example"
+
+          idempotency_key: "$generate:uuid_v4#property_lists_create_list_create_inclusion_list"
+          context:
+            correlation_id: "property_lists--create_inclusion_list"
+        context_outputs:
+          - path: "list.list_id"
+            key: "property_list_id"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-property-list-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--create_inclusion_list"
+            description: "Context correlation_id returned unchanged"
+          - check: field_present
+            path: "list.list_id"
+            description: "Governance agent assigns list_id — must be echoed in get/update/delete"
+  - id: list_and_get
+    title: "Query property lists"
+    narrative: |
+      The buyer lists all property lists for the account and retrieves a specific list
+      to inspect its contents.
+
+    steps:
+      - id: list_property_lists
+        title: "List all property lists"
+        narrative: |
+          The buyer lists all property lists for the brand. The response includes list
+          metadata (name, type, property count) without full property details.
+        task: list_property_lists
+        schema_ref: "property/list-property-lists-request.json"
+        response_schema_ref: "property/list-property-lists-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: property_list_filters
+        stateful: true
+        expected: |
+          Return property list summaries:
+          - Array of lists with list_id, name, list_type, property_count
+          - Includes both inclusion and exclusion lists
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          name_contains: "Acme Outdoor"
+
+          context:
+            correlation_id: "property_lists--list_property_lists"
+        validations:
+          - check: response_schema
+            description: "Response matches list-property-lists-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--list_property_lists"
+            description: "Context correlation_id returned unchanged"
+      - id: get_property_list
+        title: "Get a specific property list"
+        narrative: |
+          The buyer retrieves the full details of a specific property list, including
+          all properties in the list.
+        task: get_property_list
+        schema_ref: "property/get-property-list-request.json"
+        response_schema_ref: "property/get-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the full property list:
+          - list_id, name, list_type
+          - All properties in the list with their details
+
+        sample_request:
+          list_id: "$context.property_list_id"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          context:
+            correlation_id: "property_lists--get_property_list"
+        validations:
+          - check: response_schema
+            description: "Response matches get-property-list-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--get_property_list"
+            description: "Context correlation_id returned unchanged"
+  - id: update_list
+    title: "Update property lists"
+    narrative: |
+      The buyer modifies an existing property list — replacing the base properties
+      as brand safety requirements evolve.
+
+    steps:
+      - id: update_property_list
+        title: "Update a property list"
+        narrative: |
+          The buyer replaces the base properties on an existing list with a new set.
+        task: update_property_list
+        schema_ref: "property/update-property-list-request.json"
+        response_schema_ref: "property/update-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return the updated property list:
+          - Updated property count
+          - Confirmation of the replaced base properties
+
+        sample_request:
+          list_id: "$context.property_list_id"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          base_properties:
+            - selection_type: "identifiers"
+              identifiers:
+                - type: "domain"
+                  value: "outdoormagazine.example"
+                - type: "domain"
+                  value: "hikingtrails.example"
+                - type: "domain"
+                  value: "mountaineering.example"
+
+          idempotency_key: "$generate:uuid_v4#property_lists_update_list_update_property_list"
+          context:
+            correlation_id: "property_lists--update_property_list"
+        validations:
+          - check: response_schema
+            description: "Response matches update-property-list-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--update_property_list"
+            description: "Context correlation_id returned unchanged"
+  - id: delivery_validation
+    title: "Validate delivery compliance"
+    narrative: |
+      After ads have been delivered, the buyer validates that the seller respected the
+      property lists. The governance agent checks actual delivery data against the
+      inclusion/exclusion constraints.
+
+    steps:
+      - id: validate_property_delivery
+        title: "Validate property compliance"
+        narrative: |
+          The buyer submits delivery data and the governance agent checks whether all
+          placements complied with the property lists. Non-compliant placements are
+          flagged with details.
+        task: validate_property_delivery
+        schema_ref: "property/validate-property-delivery-request.json"
+        response_schema_ref: "property/validate-property-delivery-response.json"
+        doc_ref: "/governance/property/tasks/validate_property_delivery"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return validation results:
+          - compliant: boolean overall status
+          - summary aggregates compliant/non_compliant/not_covered/unidentified counts
+          - Per-placement compliance status
+          - features[] entries on each non_compliant record explaining the breach
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          list_id: "$context.property_list_id"
+          records:
+            - record_id: "delivery_outdoor_001"
+              identifier:
+                type: "domain"
+                value: "outdoormagazine.example"
+              impressions: 50000
+            - record_id: "delivery_random_001"
+              identifier:
+                type: "domain"
+                value: "randomsite.example"
+              impressions: 200
+
+          context:
+            correlation_id: "property_lists--validate_property_delivery"
+        validations:
+          - check: response_schema
+            description: "Response matches validate-property-delivery-response.json schema"
+          - check: field_value
+            path: "compliant"
+            value: false
+            description: "Overall compliance is false when randomsite.example violates inclusion list"
+
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--validate_property_delivery"
+            description: "Context correlation_id returned unchanged"
+
+  - id: enforcement
+    title: "Property list enforcement"
+    narrative: |
+      These steps test behavioral compliance beyond schema validation. An agent that
+      returns well-shaped responses but does not actually enforce property constraints
+      would pass CRUD tests but fail here.
+
+    steps:
+      - id: validate_all_compliant_delivery
+        title: "Validate fully compliant delivery"
+        narrative: |
+          The buyer submits delivery data where all properties are on the inclusion list.
+          The governance agent must return records with status: compliant and no failed features.
+        task: validate_property_delivery
+        schema_ref: "property/validate-property-delivery-request.json"
+        response_schema_ref: "property/validate-property-delivery-response.json"
+        doc_ref: "/governance/property/tasks/validate_property_delivery"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return validation results:
+          - record status: compliant
+          - No failed or warning features
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          list_id: "$context.property_list_id"
+          records:
+            - record_id: "delivery_outdoor_001"
+              identifier:
+                type: "domain"
+                value: "outdoormagazine.example"
+              impressions: 50000
+            - record_id: "delivery_hiking_001"
+              identifier:
+                type: "domain"
+                value: "hikingtrails.example"
+              impressions: 30000
+
+        validations:
+          - check: response_schema
+            description: "Response matches validate-property-delivery-response.json schema"
+          - check: field_value
+            path: "compliant"
+            value: true
+            description: "Delivery is compliant when all properties are on inclusion list"
+
+      - id: validate_unauthorized_publisher
+        title: "Reject delivery on unlisted domain"
+        narrative: |
+          The buyer submits delivery data that includes randomsite.example — a domain
+          not on the inclusion list. The governance agent must flag this as a violation
+          with specific violation details, not just return a generic failure.
+        task: validate_property_delivery
+        schema_ref: "property/validate-property-delivery-request.json"
+        response_schema_ref: "property/validate-property-delivery-response.json"
+        doc_ref: "/governance/property/tasks/validate_property_delivery"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Return validation results:
+          - record status: non_compliant
+          - features array with at least one failed feature entry for randomsite.example
+          - feature entry references the inclusion list that was breached (via policy_id or code)
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+          list_id: "$context.property_list_id"
+          records:
+            - record_id: "delivery_random_001"
+              identifier:
+                type: "domain"
+                value: "randomsite.example"
+              impressions: 500
+
+        validations:
+          - check: response_schema
+            description: "Response matches validate-property-delivery-response.json schema"
+          - check: field_value
+            path: "compliant"
+            value: false
+            description: "Delivery is non-compliant for unlisted domain"
+
+  - id: delete_list
+    title: "Delete a property list"
+    narrative: |
+      The buyer removes a property list that is no longer needed. Delete runs after
+      validation phases so they can reference the list created earlier.
+
+    steps:
+      - id: delete_property_list
+        title: "Delete a property list"
+        narrative: |
+          The buyer deletes a property list. The governance agent removes the list and
+          returns confirmation.
+        task: delete_property_list
+        schema_ref: "property/delete-property-list-request.json"
+        response_schema_ref: "property/delete-property-list-response.json"
+        doc_ref: "/governance/property/tasks/property_lists"
+        comply_scenario: governance_property_lists
+        stateful: true
+        expected: |
+          Confirm deletion:
+          - list_id: the deleted list
+          - status: deleted
+
+        sample_request:
+          list_id: "$context.property_list_id"
+          account:
+            brand:
+              domain: "acmeoutdoor.example"
+            operator: "pinnacle-agency.example"
+
+          idempotency_key: "$generate:uuid_v4#property_lists_delete_list_delete_property_list"
+          context:
+            correlation_id: "property_lists--delete_property_list"
+        validations:
+          - check: response_schema
+            description: "Response matches delete-property-list-response.json schema"
+
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "property_lists--delete_property_list"
+            description: "Context correlation_id returned unchanged"