docs: document topology graph v0.2 contract

README.md

@@ -7,18 +7,24 @@ The project intentionally does not include an LLM, a generic browser agent, or a
 ## Current Scope
 
 - Open a URL or local HTML file with Playwright.
+- Capture reproducibility metadata: browser, viewport, locale, auth mode, crawl session id, input fingerprint, and policy/scoring versions.
 - Capture one page state with DOM and visible-text fingerprints.
 - Extract actionable elements: buttons, links, inputs, selects, textareas, roles, tab stops, and click handlers.
-- Generate locator candidates with scores.
-- Optionally explore low-risk click actions from the entry state.
-- Record state nodes, elements, locators, action edges, and basic effects in JSON.
+- Generate locator candidates with scores, context scopes, identity checks, and verification evidence.
+- Optionally run low-risk one-hop click exploration from a clean entry state.
+- Replay actions from the entry state and record observed state transitions with snapshot-diff effects.
+- Record state-local skipped default-exploration actions when risk policy blocks them.
+- Record failed observations instead of turning failed locators or failed actions into successful edges.
+- Emit state nodes, elements, locators, action edges, skipped actions, failed observations, and metadata in JSON.
 
 ## Non-Goals
 
 - No LLM decision making.
 - No natural-language task planner.
 - No high-risk automatic actions.
-- No attempt to fully recover frontend business functions in the first version.
+- No full crawler or breadth-first site exploration.
+- No general browser agent or workflow orchestration platform.
+- No attempt to fully recover frontend business functions in this engine.
 
 ## Install
 
@@ -34,6 +40,12 @@ Static scan:
 npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json
 ```
 
+Tests:
+
+```bash
+npm run test
+```
+
 Entry-state low-risk exploration:
 
 ```bash
@@ -52,12 +64,15 @@ The output JSON follows the schema described in [schemas/topology-graph.schema.m
 
 Key objects:
 
-- `StateNode`: URL, route, title, state hashes, modal stack, and entry metadata.
-- `ActionableElement`: element semantics, visibility, bounding box, and locator candidates.
-- `LocatorCandidate`: Playwright-friendly locator descriptors plus score and verification status.
-- `ActionEdge`: action from one state to another through an element, with effects and risk.
+- `TopologyGraph.metadata`: artifact version, input URL, entry URL, generated timestamp, engine version, mode, non-deterministic crawl session id, deterministic input fingerprint, runtime context, site, and policy/scoring versions.
+- `StateNode`: URL, route, title, canonical key, language, viewport, state hashes, modal stack, lifecycle, evidence, and first observed `openedByEdgeId`.
+- `ActionableElement`: state-local element semantics, visibility/interactability, bounding box, context anchors, parameter surface, evidence, and locator candidates.
+- `LocatorCandidate`: Playwright-friendly locator descriptors plus score, verification status, context `scopes`, identity evidence, and failure count.
+- `ActionEdge`: low-risk replayed action from one state to another through an element, with `riskCategory`, `riskLevel`, and snapshot-diff `effects`.
+- `EffectRecord`: snapshot-diff record for `url`, `dom`, `visibleText`, or `actionableInventory`, with `before` and `after` values.
+- `SkippedAction`: risk-policy default exploration refusal with risk category, reason, state id, element id, and evidence.
+- `FailedObservation`: locator, actionability, action, or effect failure with machine-readable reason and diagnostic evidence.
 
 ## Source Notes
 
 The originating ChatGPT share conversation is preserved in [docs/source/chatgpt-share-6a30e583.md](docs/source/chatgpt-share-6a30e583.md).
-