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.

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.

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.

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.

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.

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.

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.

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.

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.