{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://action-topology-engine.local/schemas/topology-graph.schema.json",
  "title": "TopologyGraph",
  "type": "object",
  "required": [
    "schemaVersion",
    "metadata",
    "states",
    "elements",
    "edges",
    "skippedActions",
    "failedObservations",
    "summary"
  ],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": { "const": "0.2" },
    "metadata": { "$ref": "#/$defs/metadata" },
    "states": { "type": "array", "items": { "$ref": "#/$defs/stateNode" } },
    "elements": { "type": "array", "items": { "$ref": "#/$defs/actionableElement" } },
    "edges": { "type": "array", "items": { "$ref": "#/$defs/actionEdge" } },
    "skippedActions": { "type": "array", "items": { "$ref": "#/$defs/skippedAction" } },
    "failedObservations": { "type": "array", "items": { "$ref": "#/$defs/failedObservation" } },
    "summary": { "$ref": "#/$defs/graphSummary" }
  },
  "$defs": {
    "metadata": {
      "type": "object",
      "required": [
        "artifactVersion",
        "inputUrl",
        "entryUrl",
        "generatedAt",
        "engineVersion",
        "mode",
        "crawlSessionId",
        "inputSeed",
        "inputFingerprint",
        "runtimeContext",
        "site",
        "riskPolicyVersion",
        "normalizationRuleVersion",
        "locatorScoringVersion"
      ],
      "additionalProperties": false,
      "properties": {
        "artifactVersion": { "const": "topology-graph-v0.2" },
        "inputUrl": { "type": "string" },
        "entryUrl": { "type": "string" },
        "generatedAt": { "type": "string" },
        "engineVersion": { "const": "0.2.2" },
        "mode": { "enum": ["scan", "explore"] },
        "crawlSessionId": { "type": "string", "pattern": "^crawl_" },
        "inputSeed": { "type": "string" },
        "inputFingerprint": { "type": "string", "pattern": "^input_" },
        "runtimeContext": {
          "type": "object",
          "required": ["browserName", "viewport", "locale", "timezoneId", "authContext"],
          "additionalProperties": false,
          "properties": {
            "browserName": { "const": "chromium" },
            "viewport": { "$ref": "#/$defs/viewport" },
            "locale": { "type": "string" },
            "timezoneId": { "type": ["string", "null"] },
            "authContext": { "enum": ["anonymous", "storage_state"] }
          }
        },
        "site": {
          "type": "object",
          "required": ["baseUrl", "entryUrl"],
          "additionalProperties": false,
          "properties": {
            "baseUrl": { "type": "string" },
            "entryUrl": { "type": "string" }
          }
        },
        "riskPolicyVersion": { "const": "risk-policy-v0.2" },
        "normalizationRuleVersion": { "const": "normalization-v0.2" },
        "locatorScoringVersion": { "const": "locator-scoring-v0.2" }
      }
    },
    "stateNode": {
      "type": "object",
      "required": [
        "stateId",
        "url",
        "route",
        "title",
        "frameContext",
        "stateHash",
        "domHash",
        "visibleTextHash",
        "actionableSignatureHash",
        "modalStack",
        "openedByEdgeId",
        "createdAt",
        "lifecycle",
        "urlCanonicalKey",
        "language",
        "viewport",
        "evidence"
      ],
      "additionalProperties": false,
      "properties": {
        "stateId": { "type": "string", "pattern": "^state_" },
        "url": { "type": "string" },
        "route": { "type": "string" },
        "title": { "type": "string" },
        "frameContext": { "type": "array", "items": { "type": "string" } },
        "stateHash": { "type": "string" },
        "domHash": { "type": "string" },
        "visibleTextHash": { "type": "string" },
        "actionableSignatureHash": { "type": "string" },
        "modalStack": { "type": "array", "items": { "type": "string" } },
        "openedByEdgeId": { "type": ["string", "null"] },
        "createdAt": { "type": "string" },
        "lifecycle": { "enum": ["observed", "fingerprinted", "verified", "stale", "deprecated", "conflicted"] },
        "urlCanonicalKey": { "type": "string" },
        "language": { "type": ["string", "null"] },
        "viewport": { "$ref": "#/$defs/viewport" },
        "evidence": { "$ref": "#/$defs/evidenceList" }
      }
    },
    "actionableElement": {
      "type": "object",
      "required": [
        "elementId",
        "stateId",
        "tag",
        "role",
        "accessibleName",
        "text",
        "label",
        "placeholder",
        "attributes",
        "bbox",
        "framePath",
        "shadowPath",
        "interactability",
        "locators",
        "context",
        "parameterSurface",
        "evidence"
      ],
      "additionalProperties": false,
      "properties": {
        "elementId": { "type": "string", "pattern": "^el_" },
        "stateId": { "type": "string", "pattern": "^state_" },
        "tag": { "type": "string" },
        "role": { "type": ["string", "null"] },
        "accessibleName": { "type": ["string", "null"] },
        "text": { "type": ["string", "null"] },
        "label": { "type": ["string", "null"] },
        "placeholder": { "type": ["string", "null"] },
        "attributes": { "type": "object", "additionalProperties": { "type": "string" } },
        "bbox": { "anyOf": [{ "$ref": "#/$defs/boundingBox" }, { "type": "null" }] },
        "framePath": { "type": "array", "items": { "type": "string" } },
        "shadowPath": { "type": "array", "items": { "type": "string" } },
        "interactability": { "$ref": "#/$defs/interactability" },
        "locators": { "type": "array", "items": { "$ref": "#/$defs/locatorCandidate" } },
        "context": { "$ref": "#/$defs/elementContext" },
        "parameterSurface": { "anyOf": [{ "$ref": "#/$defs/parameterSurface" }, { "type": "null" }] },
        "evidence": { "$ref": "#/$defs/evidenceList" }
      }
    },
    "locatorCandidate": {
      "type": "object",
      "required": [
        "locatorId",
        "elementId",
        "framework",
        "strategy",
        "descriptor",
        "expression",
        "score",
        "reason",
        "verified",
        "scopes",
        "identity",
        "evidence",
        "failureCount"
      ],
      "additionalProperties": false,
      "properties": {
        "locatorId": { "type": "string", "pattern": "^loc_" },
        "elementId": { "type": "string", "pattern": "^el_" },
        "framework": { "enum": ["playwright", "css"] },
        "strategy": { "enum": ["role", "label", "placeholder", "text", "testId", "css", "scoped"] },
        "descriptor": { "$ref": "#/$defs/locatorDescriptor" },
        "expression": { "type": "string" },
        "score": { "type": "number" },
        "reason": { "type": "string" },
        "verified": { "type": "boolean" },
        "lastVerifiedAt": { "type": "string" },
        "matchCount": { "type": "integer", "minimum": 0 },
        "scopes": { "type": "array", "items": { "$ref": "#/$defs/locatorScope" } },
        "identity": { "anyOf": [{ "$ref": "#/$defs/locatorIdentity" }, { "type": "null" }] },
        "evidence": { "$ref": "#/$defs/evidenceList" },
        "failureCount": { "type": "integer", "minimum": 0 }
      }
    },
    "locatorDescriptor": {
      "oneOf": [
        { "$ref": "#/$defs/baseLocatorDescriptor" },
        {
          "type": "object",
          "required": ["kind", "scope", "target"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "scoped" },
            "scope": { "$ref": "#/$defs/locatorScope" },
            "target": { "$ref": "#/$defs/baseLocatorDescriptor" }
          }
        }
      ]
    },
    "baseLocatorDescriptor": {
      "oneOf": [
        {
          "type": "object",
          "required": ["kind", "role"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "role" },
            "role": { "type": "string" },
            "name": { "type": "string" }
          }
        },
        {
          "type": "object",
          "required": ["kind", "label"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "label" },
            "label": { "type": "string" }
          }
        },
        {
          "type": "object",
          "required": ["kind", "placeholder"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "placeholder" },
            "placeholder": { "type": "string" }
          }
        },
        {
          "type": "object",
          "required": ["kind", "text", "exact"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "text" },
            "text": { "type": "string" },
            "exact": { "type": "boolean" }
          }
        },
        {
          "type": "object",
          "required": ["kind", "testId"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "testId" },
            "testId": { "type": "string" }
          }
        },
        {
          "type": "object",
          "required": ["kind", "selector"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "css" },
            "selector": { "type": "string" }
          }
        }
      ]
    },
    "actionEdge": {
      "type": "object",
      "required": [
        "edgeId",
        "fromStateId",
        "toStateId",
        "elementId",
        "actionType",
        "actionParams",
        "preconditions",
        "effects",
        "parameterSpecs",
        "riskLevel",
        "riskCategory",
        "confidence",
        "createdAt"
      ],
      "additionalProperties": false,
      "properties": {
        "edgeId": { "type": "string", "pattern": "^edge_" },
        "fromStateId": { "type": "string", "pattern": "^state_" },
        "toStateId": { "type": ["string", "null"] },
        "elementId": { "type": "string", "pattern": "^el_" },
        "actionType": { "$ref": "#/$defs/actionType" },
        "actionParams": { "type": "object" },
        "preconditions": { "type": "array", "items": { "type": "string" } },
        "effects": { "type": "array", "items": { "$ref": "#/$defs/effectRecord" } },
        "parameterSpecs": { "type": "array", "items": { "$ref": "#/$defs/parameterSpec" } },
        "riskLevel": { "$ref": "#/$defs/riskLevel" },
        "riskCategory": { "$ref": "#/$defs/riskCategory" },
        "confidence": { "type": "number" },
        "createdAt": { "type": "string" }
      }
    },
    "effectRecord": {
      "type": "object",
      "required": ["type", "description"],
      "additionalProperties": false,
      "properties": {
        "type": { "enum": ["url", "dom", "visibleText", "actionableInventory"] },
        "before": { "type": "string" },
        "after": { "type": "string" },
        "description": { "type": "string" }
      }
    },
    "skippedAction": {
      "type": "object",
      "required": ["skippedActionId", "stateId", "elementId", "actionType", "riskLevel", "riskCategory", "reason", "evidence", "createdAt"],
      "additionalProperties": false,
      "properties": {
        "skippedActionId": { "type": "string", "pattern": "^skip_" },
        "stateId": { "type": "string", "pattern": "^state_" },
        "elementId": { "type": "string", "pattern": "^el_" },
        "actionType": { "$ref": "#/$defs/actionType" },
        "riskLevel": { "$ref": "#/$defs/riskLevel" },
        "riskCategory": { "$ref": "#/$defs/riskCategory" },
        "reason": { "type": "string" },
        "evidence": { "$ref": "#/$defs/evidenceList" },
        "createdAt": { "type": "string" }
      }
    },
    "failedObservation": {
      "type": "object",
      "required": ["failedObservationId", "stateId", "elementId", "actionType", "reason", "message", "evidence", "createdAt"],
      "additionalProperties": false,
      "properties": {
        "failedObservationId": { "type": "string", "pattern": "^fail_" },
        "stateId": { "type": ["string", "null"] },
        "elementId": { "type": ["string", "null"] },
        "actionType": { "anyOf": [{ "$ref": "#/$defs/actionType" }, { "type": "null" }] },
        "reason": { "$ref": "#/$defs/failedObservationReason" },
        "message": { "type": "string" },
        "evidence": { "$ref": "#/$defs/evidenceList" },
        "createdAt": { "type": "string" }
      }
    },
    "graphSummary": {
      "type": "object",
      "required": [
        "states",
        "elements",
        "edges",
        "skippedActions",
        "failedObservations",
        "failedObservationsByReason",
        "skippedActionsByRiskCategory",
        "edgesByRiskCategory"
      ],
      "additionalProperties": false,
      "properties": {
        "states": { "type": "integer", "minimum": 0 },
        "elements": { "type": "integer", "minimum": 0 },
        "edges": { "type": "integer", "minimum": 0 },
        "skippedActions": { "type": "integer", "minimum": 0 },
        "failedObservations": { "type": "integer", "minimum": 0 },
        "failedObservationsByReason": { "$ref": "#/$defs/countMap" },
        "skippedActionsByRiskCategory": { "$ref": "#/$defs/countMap" },
        "edgesByRiskCategory": { "$ref": "#/$defs/countMap" }
      }
    },
    "parameterSpec": {
      "type": "object",
      "required": ["name", "type", "required"],
      "additionalProperties": false,
      "properties": {
        "name": { "type": "string" },
        "type": { "enum": ["string", "number", "boolean", "enum", "date", "unknown"] },
        "required": { "type": "boolean" },
        "enumValues": { "type": "array", "items": { "type": "string" } },
        "pattern": { "type": "string" },
        "examples": { "type": "array", "items": { "type": "string" } }
      }
    },
    "parameterSurface": {
      "type": "object",
      "required": ["name", "inputType", "required", "readonly", "disabled", "pattern", "min", "max", "maxLength", "options"],
      "additionalProperties": false,
      "properties": {
        "name": { "type": ["string", "null"] },
        "inputType": { "type": ["string", "null"] },
        "required": { "type": "boolean" },
        "readonly": { "type": "boolean" },
        "disabled": { "type": "boolean" },
        "pattern": { "type": ["string", "null"] },
        "min": { "type": ["string", "null"] },
        "max": { "type": ["string", "null"] },
        "maxLength": { "type": ["integer", "null"] },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["label", "value", "disabled", "selected"],
            "additionalProperties": false,
            "properties": {
              "label": { "type": "string" },
              "value": { "type": "string" },
              "disabled": { "type": "boolean" },
              "selected": { "type": "boolean" }
            }
          }
        }
      }
    },
    "elementContext": {
      "type": "object",
      "required": ["dialog", "form", "section", "row", "landmark", "listitem"],
      "additionalProperties": false,
      "properties": {
        "dialog": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] },
        "form": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] },
        "section": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] },
        "row": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] },
        "landmark": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] },
        "listitem": { "anyOf": [{ "$ref": "#/$defs/contextAnchor" }, { "type": "null" }] }
      }
    },
    "contextAnchor": {
      "type": "object",
      "required": ["kind", "name", "text"],
      "additionalProperties": false,
      "properties": {
        "kind": { "enum": ["dialog", "form", "section", "row", "landmark", "listitem"] },
        "name": { "type": ["string", "null"] },
        "text": { "type": ["string", "null"] }
      }
    },
    "locatorScope": {
      "type": "object",
      "required": ["kind", "name", "text"],
      "additionalProperties": false,
      "properties": {
        "kind": { "enum": ["dialog", "form", "section", "row", "landmark", "listitem"] },
        "name": { "type": ["string", "null"] },
        "text": { "type": ["string", "null"] }
      }
    },
    "locatorIdentity": {
      "type": "object",
      "required": ["sameTag", "sameRole", "sameAccessibleName", "sameText", "sameVisibility"],
      "additionalProperties": false,
      "properties": {
        "sameTag": { "type": "boolean" },
        "sameRole": { "type": "boolean" },
        "sameAccessibleName": { "type": "boolean" },
        "sameText": { "type": "boolean" },
        "sameVisibility": { "type": "boolean" }
      }
    },
    "interactability": {
      "type": "object",
      "required": ["visible", "enabled", "editable", "receivesEvents"],
      "additionalProperties": false,
      "properties": {
        "visible": { "type": "boolean" },
        "enabled": { "type": "boolean" },
        "editable": { "type": "boolean" },
        "receivesEvents": { "type": "boolean" }
      }
    },
    "boundingBox": {
      "type": "object",
      "required": ["x", "y", "width", "height"],
      "additionalProperties": false,
      "properties": {
        "x": { "type": "number" },
        "y": { "type": "number" },
        "width": { "type": "number" },
        "height": { "type": "number" }
      }
    },
    "viewport": {
      "type": "object",
      "required": ["width", "height"],
      "additionalProperties": false,
      "properties": {
        "width": { "type": "integer" },
        "height": { "type": "integer" }
      }
    },
    "evidenceList": {
      "type": "array",
      "items": { "$ref": "#/$defs/evidenceRecord" }
    },
    "evidenceRecord": {
      "type": "object",
      "required": ["level", "source", "description"],
      "additionalProperties": false,
      "properties": {
        "level": { "enum": ["observed", "derived", "verified", "heuristic", "external"] },
        "source": { "type": "string" },
        "description": { "type": "string" }
      }
    },
    "actionType": { "enum": ["click", "fill", "select", "check", "uncheck", "navigate"] },
    "riskLevel": { "enum": ["low", "medium", "high"] },
    "riskCategory": {
      "enum": [
        "read_only",
        "navigation",
        "ui_reveal",
        "input_edit",
        "form_submit",
        "data_mutation",
        "destructive",
        "auth_sensitive",
        "payment_sensitive",
        "unknown"
      ]
    },
    "failedObservationReason": {
      "enum": [
        "locator_not_found",
        "locator_not_unique",
        "element_hidden",
        "element_disabled",
        "element_obscured",
        "state_precondition_missing",
        "frame_inaccessible",
        "shadow_root_closed",
        "navigation_timeout",
        "network_error",
        "permission_denied",
        "auth_required",
        "captcha_or_challenge",
        "risk_policy_blocked",
        "effect_not_observed",
        "unexpected_state"
      ]
    },
    "countMap": {
      "type": "object",
      "additionalProperties": { "type": "integer", "minimum": 0 }
    }
  }
}