{
  "$schema": "https://json-schema.org/draft-07/schema",
  "$id": "https://agent-schema.com/schemas/fcs/4.0/shadow-ledger.schema.json",
  "title": "Shadow Impression Ledger",
  "description": "Counterfactual logging format for ad impressions (FCS 4.0 Component 1)",
  "type": "object",
  "required": [
    "impression_id",
    "query_cluster",
    "shown_ad",
    "not_shown_considered",
    "timestamp"
  ],
  "properties": {
    "impression_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique impression identifier"
    },
    "query_cluster": {
      "type": "string",
      "description": "Semantic cluster of the query"
    },
    "shown_ad": {
      "type": "object",
      "required": ["product_id", "score", "reason"],
      "properties": {
        "product_id": {
          "type": "string"
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "reason": {
          "type": "string",
          "description": "Why this ad was shown"
        }
      }
    },
    "not_shown_considered": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["product_id", "score", "reason_not_shown"],
        "properties": {
          "product_id": {
            "type": "string"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "reason_not_shown": {
            "type": "string",
            "description": "Why this ad was NOT shown"
          }
        }
      },
      "description": "Counterfactual: ads considered but not shown"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "context": {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string"
        },
        "user_id_hash": {
          "type": "string",
          "description": "Hashed user identifier for privacy"
        }
      }
    }
  }
}