Initialize action topology engine

schemas/topology-graph.schema.md

@@ -0,0 +1,51 @@
+# Topology Graph Schema
+
+This document describes the JSON shape emitted by the engine. It is a practical schema note, not yet a formal JSON Schema file.
+
+## `TopologyGraph`
+
+- `schemaVersion`: currently `0.1`.
+- `metadata.entryUrl`: entry URL after Playwright navigation.
+- `metadata.mode`: `scan` or `explore`.
+- `states`: page states.
+- `elements`: actionable elements bound to a state.
+- `edges`: observed actions from one state to another.
+
+## `StateNode`
+
+- `stateId`: stable id derived from URL, DOM hash, visible text hash, and actionable signature hash.
+- `url`, `route`, `title`: browser-visible state identity.
+- `domHash`: hash of full `document.documentElement.outerHTML`.
+- `visibleTextHash`: hash of normalized visible body text.
+- `actionableSignatureHash`: hash of actionable element signatures.
+- `modalStack`: visible dialogs or modal-like surfaces.
+- `openedByEdgeId`: edge that opened this state, if known.
+
+## `ActionableElement`
+
+- `elementId`: stable id within the captured state.
+- `stateId`: owning state.
+- `tag`, `role`, `accessibleName`, `text`, `label`, `placeholder`: semantic identity.
+- `attributes`: selected stable attributes such as `data-testid`, `id`, `name`, `type`, `href`, and ARIA fields.
+- `bbox`: page-space bounding box.
+- `interactability`: visibility, enabled/editable status, and whether the element receives events.
+- `locators`: scored locator candidates.
+
+## `LocatorCandidate`
+
+- `descriptor`: structured Playwright locator descriptor.
+- `expression`: human-readable locator expression.
+- `score`: ranking score.
+- `verified`: whether it resolved to exactly one element during capture.
+- `matchCount`: observed locator match count.
+
+## `ActionEdge`
+
+- `fromStateId`, `toStateId`: source and resulting states.
+- `elementId`: action target.
+- `actionType`: currently focused on `click`, with type support for future `fill`, `select`, and navigation actions.
+- `preconditions`: reserved for stored open paths.
+- `effects`: URL, visible text, network, download, dialog, storage, or DOM effects.
+- `riskLevel`: `low`, `medium`, or `high`.
+- `confidence`: confidence in observed edge replayability.
+