# Helixwright 1.0 machine-readable documentation index

SDK: helixwright 1.0.0 (local release candidate)
Architecture: Helix Browser Desktop Local API + namespaced Browser RPC V6
Protocol: 6
Endpoint: /rpc/v6
Core contract: 0075
Semantic contract hash: 40DFB6DEDAA4CD9A1F56BCEBB019A08B1F57025A28069E79605945CA1FF60BE8
Trace schema: helixwright.trace.session / 4
Flow IR schema: 1

Canonical manifest:
http://66.154.125.146:8000/helixwright/ai/manifest.json

Read order:
1. Fetch the manifest and verify every selected document by size and SHA-256.
2. Always read rules and statemachine.
3. Read task-specific documents listed below.
4. Use only names present in api.md.

Documents:
- rules: http://66.154.125.146:8000/helixwright/ai/latest/rules.md
- quickstart: http://66.154.125.146:8000/helixwright/ai/latest/quickstart.md
- api: http://66.154.125.146:8000/helixwright/ai/latest/api.md
- locator: http://66.154.125.146:8000/helixwright/ai/latest/locator.md
- motion: http://66.154.125.146:8000/helixwright/ai/latest/motion.md
- statemachine: http://66.154.125.146:8000/helixwright/ai/latest/statemachine.md
- trace: http://66.154.125.146:8000/helixwright/ai/latest/trace.md
- errors: http://66.154.125.146:8000/helixwright/ai/latest/errors.md
- migration: http://66.154.125.146:8000/helixwright/ai/latest/migration.md
- examples: http://66.154.125.146:8000/helixwright/ai/latest/examples.md

Non-negotiable architecture:
- Desktop owns profile/fingerprint/proxy/browser/session lifecycle.
- Browser core owns immutable frame routing, target-owned scrolling, mechanical
  actionability, trusted input, default trajectory generation, final dispatch
  revalidation, action journal, and authoritative receipt.
- Helixwright owns the typed facade, structured readiness, action effects,
  event-first statecharts, private Trace/Authoring, and Flow IR.
- No CDP, WebDriver, Playwright, Selenium, direct Chromium launch, synthetic DOM
  actions, JavaScript action substitution, guessed coordinate fallback, fixed sleep,
  or blind mutation replay.

Public namespaces:
- helixwright: launch/attach, Page, Frame, Locator, Input, readiness, motion,
  effects, statecharts.
- helixwright.admin: Local API/profile/proxy/core/browser/session administration.
- helixwright.expert: immutable context/snapshot, Gesture, controllers,
  Trace/probe, Flow IR, offline evidence helpers.
- helixwright.signals: typed outcome signals.
- helixwright.errors: complete error hierarchy.

Action contract:
- Ordinary element actions use Locator and one element.await_ready_and_act
  transaction.
- Mechanical readiness is mandatory and cannot be disabled.
- Site-specific hydration/widget/network conditions are serializable
  ReadinessContract data evaluated in the same document epoch.
- Keep the RuntimeActionEffect returned by the exact action.
- Require dispatch_phase=completed and its own confirmed receipt.
- Unknown mutation dispatch is reconciled; it is never blindly replayed.
- A page-global latest effect is diagnostic only, not concurrent-safe authority.

Statechart contract:
- Signature is serializable; arbitrary matcher callbacks are forbidden.
- Classify all states from one state.snapshot epoch.
- Open a transition-owned events.subscribe cursor before action dispatch.
- Every non-terminal handler consumes its readiness contract and returns its exact
  RuntimeActionEffect.
- OutcomeContract uses exact built-in serializable signals.
- Unknown, ambiguous, mixed-epoch, malformed, foreign-receipt, event-gap,
  uncertain-dispatch, cancellation, deadline, and oscillation evidence fails closed.
- Child applications use child machines; overlays/concurrency use regions;
  frame applications use immutable frame scopes.

Private evidence contract:
- Trace/Authoring is owner-private and full-fidelity.
- Preserve raw passwords, proxy usernames/passwords, cookies, authorization,
  forms, storage, action arguments, request/response headers, duplicate ordered
  raw header lines, and request/response bodies when observed.
- No automatic masking/redaction/value downgrade.
- Access control is owner-only ACL + per-run isolation/lock + atomic writes.
- Evidence is local_only=true and upload=false; no automatic upload.
- Screenshots are supplementary; structured state/readiness/effect/receipt is primary.

Browser RPC semantic inventory:
- 41 exact namespaced methods, schema version 1 each.
- 11 exact integer capabilities, version >=1 each.
- 22 exact receipt fields.
- The canonical lists are embedded in manifest.runtime_requirements.browser_rpc and
  sourced from helixwright.rpc_contract.

Production delivery:
- flow.py
- closed persistent authoring run
- atomically written schema-1 AUTOMATION_FLOW.json from helixwright.expert.FlowIR
- AUTOMATION_REPORT.md with state/readiness/receipt/dispatch/outcome/evidence/
  framework-gap/test/risk sections

Stop and report a framework gap when the public SDK/core contract cannot represent or
execute the required selector, frame/shadow, scroll, readiness, trusted action,
motion, Trace, navigation, network, dialog, download/upload, or lifecycle behavior.