#Architecture from first principles

The core problem is not making a model click a page. It is preserving a trustworthy chain from human intent to the exact interface state, the action that ran, the source that owns the result, and the evidence that proves the outcome.

A3S Test treats each link as a separate technical contract.

#Constraints that shape the system

#The complete evidence path

human intent / PRD / design
             |
             v
     reviewed expectation
             |
browser render + accessibility + Test Kit
             |
             v
   revision-bound observation
             |
     one typed action proposal
             |
       Core admission gate
 schema + capability + policy + origin
             |
             v
      Web / GUI / TUI driver
             |
             v
 events + assertions + owned artifacts
             |
 explicit human repair authorization
             |
             v
 source edit -> newer rendered revision
             |
             v
 fresh verification -> ACL regression

No arrow is implicit. An observation cannot authorize an edit. A model candidate cannot set a verdict. A source span cannot prove that the new page is correct. Verification must read the changed page again.

#Four implementation layers

CLI and MCP are entry points into these layers, not new authorities. Core never branches on a backend name. A deployment injects a typed SurfaceDriver; the adapter owns only the capabilities it can prove. Unsupported behavior fails closed.

#Understanding happens after rendering

The browser has already solved layout. Test Kit reads a bounded projection of that result.

browser render
  ├── accessibility snapshot   role, name, native state
  ├── Page Context             component, locator, source, geometry, facts
  └── UI understanding         style, layout graph, clipping, state, motion
                                      |
                                      v
                           one admitted observation

Protocol a3s.test.page-context/1 is exposed through a non-enumerable, Symbol-addressed bridge. Private node identities live in a WeakMap, not in product DOM attributes. Mutation, resize, route, viewport, scroll, and form-state signals advance a monotonic revision. Snapshot detail, scope, time, node count, string size, and encoded bytes are bounded.

a3s.test.page-context-diff/1 hashes one bounded projection across revisions. It reports exact node, component, page, facts, and UI invalidation. Missing history or metadata that cannot fit the byte ceiling becomes reset_required, never an incomplete “no change.” The Web adapter validates that claim again in Rust. Core persists only a domain-separated SHA-256 fingerprint of private node identity before retaining an unaffected stable locator.

Public refs express authority instead of leaking private identity:

Rendered-node source mapping follows the same rule. A3STestBoundary may provide a coarse source hint. Framework adapters may explicitly register a DOM owner and an encoded Source Map v3. Test Kit ranks the resulting candidates but never reads framework private state, downloads a source map, or grants file authority.

#Two planning entries, one execution core

calling coding agent                   closed ACL suite
 observe -> decide -> one action        admit -> execute -> assert
               \                       /
                    typed A3S Test Core
             Action · Policy · Evidence · Lifecycle

A persistent agent session is useful while the path is unknown. The calling coding agent chooses one action from each fresh observation. ACL is useful after the path is understood. It closes the allowed actions, waits, assertions, and evidence before execution. Both routes use the same driver and result contracts, so exploration does not need a second automation model to become regression coverage.

#Four independent authorities

1. Rendered facts come from surface observations, Test Kit context, deterministic assertions, file digests, and owned evidence.
2. Model advice may propose visual locations, design findings, or contract candidates with provenance, confidence, and budgets.
3. Human authorization chooses the target, expected result, conflicts, and single or batch repair scope.
4. Workspace execution belongs to the coding agent that already owns the workspace; A3S Test verifies its result in a newer browser revision.

Projecting a report into the Review Overlay never changes a runner verdict. Opening an editor or saving a draft never enters the repair ledger. Only explicit submission crosses that boundary.

#Runtime and evidence ownership

Every launched program belongs to an A3S Test process group, Windows Job, or equivalent owned tree. Cancellation and timeout kill and reap the complete tree through bounded graceful and emergency paths. An existing developer server or unrelated browser session remains untouched.

Web sessions use an isolated namespace and non-zero idle timeout. Artifact paths must resolve to fresh regular files inside the session root. Traversal, symlinks, reparse points, stale output, oversized evidence, and unsupported payloads fail before they can impersonate a successful capture.

#Surface and provider boundaries

Optional LLM, grounding, and design providers are typed injected objects. HTTP adapters disable redirects and environment proxies, require HTTPS except for explicit loopback HTTP, bound bodies and deadlines, and redact authorization values. Provider output remains advice until the surrounding deterministic and human boundaries admit it.

Continue with Page Context fields and lifecycle for the browser-side protocol, or Authority and safety for admission and failure behavior.