# Topology Graph Schema

This document describes the JSON shape emitted by the engine. A formal JSON Schema is also provided in `schemas/topology-graph.schema.json`.

## `TopologyGraph`

- `schemaVersion`: currently `0.2`.
- `metadata.artifactVersion`: currently `topology-graph-v0.2`.
- `metadata.inputUrl`: raw URL or file path supplied by the caller.
- `metadata.entryUrl`: entry URL after Playwright navigation.
- `metadata.generatedAt`: ISO timestamp for this artifact generation.
- `metadata.engineVersion`: engine implementation version that emitted the artifact.
- `metadata.mode`: `scan` or `explore`.
- `metadata.crawlSessionId`: unique non-deterministic identifier for this graph generation session. It is intentionally different across runs.
- `metadata.inputSeed`: caller-supplied input seed. In v0.2 this is the raw `inputUrl`.
- `metadata.inputFingerprint`: deterministic hash of input URL, mode, and policy/scoring versions.
- `metadata.runtimeContext`: browser engine, viewport, locale, timezone, and auth context.
- `metadata.site`: base URL and entry URL.
- `metadata.riskPolicyVersion`: currently `risk-policy-v0.2`.
- `metadata.normalizationRuleVersion`: currently `normalization-v0.2`.
- `metadata.locatorScoringVersion`: currently `locator-scoring-v0.2`.
- `states`: page states.
- `elements`: actionable elements bound to a state.
- `edges`: observed actions from one state to another.
- `skippedActions`: state-local default-explorer actions that risk policy refused to execute.
- `failedObservations`: failed locator, actionability, action, or effect observations recorded as evidence.
- `summary`: machine-readable artifact counts and grouped counts.

## Evidence Levels

- `observed`: directly captured browser fact.
- `derived`: deterministic rule output from observed facts.
- `verified`: re-resolved or replay-verified claim.
- `heuristic`: conservative inference such as risk classification.
- `external`: human or downstream annotation.

## `StateNode`

- `stateId`: stable id derived from URL, normalized state hashes, and actionable signatures.
- `lifecycle`: `observed`, `fingerprinted`, `verified`, `stale`, `deprecated`, or `conflicted`.
- `url`, `route`, `urlCanonicalKey`, `title`, `language`, `viewport`: browser-visible and normalized state identity.
- `stateHash`, `domHash`, `visibleTextHash`, `actionableSignatureHash`: deterministic state fingerprints.
- `modalStack`: visible modal context.
- `frameContext`: reserved frame context path. In v0.2.1 this is emitted as an empty array.
- `openedByEdgeId`: first edge that observed this state in the current run. It is not the only possible predecessor.
- `createdAt`: ISO timestamp for state capture.
- `evidence`: observed and derived state facts.

## `ActionableElement`

- `elementId`: state-local element id. It encodes state identity and must not be treated as a global DOM node id.
- `stateId`: owning state.
- `tag`, `role`, `accessibleName`, `text`, `label`, `placeholder`: semantic identity.
- `attributes`: selected stable attributes such as test id, id, name, type, href, and ARIA fields.
- `bbox`: geometry.
- `framePath`, `shadowPath`: reserved containment paths. In v0.2.1 these are emitted as empty arrays.
- `interactability`: visibility, enabled/editable status, and whether the element receives events.
- `context`: nearest dialog, form, section, row, landmark, and list item anchors.
- `parameterSurface`: input/select/textarea constraints, options, required state, pattern, min/max, and maxLength.
- `locators`: scored locator candidates.
- `evidence`: observed and derived element facts.

## `LocatorCandidate`

- `locatorId`: locator candidate id.
- `elementId`: parent element id. This must equal the containing `ActionableElement.elementId`.
- `framework`: `playwright` or `css`.
- `strategy`: locator strategy such as role, label, placeholder, text, test id, CSS, or scoped.
- `descriptor`: structured locator descriptor.
- `expression`: human-readable locator expression.
- `score`, `reason`, `verified`, `matchCount`, `failureCount`, `lastVerifiedAt`: ranking and verification metadata.
- `scopes`: context-scope evidence such as row, dialog, form, or section anchors.
- `descriptor.kind: "scoped"`: executable scoped locator descriptor. In v0.2.2 this contains a scope descriptor plus a base target descriptor, with row, dialog, form, and list-item scopes used for execution when available.
- `identity`: semantic identity checks for tag, role, accessible name, text, and visibility.
- `evidence`: generation and verification facts.

## `ActionEdge`

- `edgeId`: action edge id.
- `fromStateId`, `toStateId`, `elementId`, `actionType`: source state, resulting state if observed, target element, and action kind.
- `actionParams`, `preconditions`, `parameterSpecs`: action payload and future replay metadata.
- `effects`: snapshot-diff effects observed after replay.
- `riskLevel`, `riskCategory`: risk classification used by default exploration.
- `confidence`: confidence in observed edge replayability.
- `createdAt`: ISO timestamp for edge capture.
- In v0.2.1 default exploration replays each edge from a clean entry-state context.
- Navigation timeout during entry or replay can be recorded as `FailedObservation` instead of aborting artifact generation.

## `EffectRecord`

- `type`: exactly one of `url`, `dom`, `visibleText`, or `actionableInventory`.
- `before`, `after`: populated for v0.2.1 snapshot-diff effects.
- `description`: human-readable effect summary.
- v0.2.1 emits snapshot-diff effects only: URL, DOM hash, visible text hash, and actionable inventory hash.
- Network, storage, download, and dialog event buffers are not emitted in v0.2.1 and are future work, not current contract.

## `SkippedAction`

- `skippedActionId`, `stateId`, `elementId`, `actionType`: state-local skipped action identity.
- `riskLevel`, `riskCategory`: risk-policy classification.
- `reason`: policy decision string such as `blocked:destructive`.
- `evidence`: risk-policy evidence explaining why the action was skipped.
- `createdAt`: ISO timestamp for the skip record.
- `SkippedAction` is only for risk-policy default-explorer refusals. Hidden, disabled, obscured, duplicate-locator, locator-not-found, action, and effect failures are `FailedObservation`.

## `FailedObservation`

- `failedObservationId`, `stateId`, optional `elementId`, optional `actionType`: failed observation identity.
- `stateId` may be `null` for graph-level failures such as entry navigation timeout before any state exists.
- `reason`: machine-readable failure code.
- `message`: diagnostic message.
- `evidence`: observed facts explaining the failure.
- `createdAt`: ISO timestamp for the failure record.
- `FailedObservation` covers hidden, disabled, obscured, locator, action, and effect failures. Risk-policy default-explorer refusals belong in `SkippedAction`.

## `summary`

- `states`, `elements`, `edges`, `skippedActions`, `failedObservations`: total counts for the artifact.
- `failedObservationsByReason`: count map keyed by `FailedObservation.reason`.
- `skippedActionsByRiskCategory`: count map keyed by skipped action risk category.
- `edgesByRiskCategory`: count map keyed by executed edge risk category.