Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
83 lines (58 loc) · 7.27 KB

ARCHITECTURE.md

File metadata and controls

83 lines (58 loc) · 7.27 KB
Raw

Architecture

This document owns MAWR's durable system boundaries. The dependency-free M1 domain types, M2 native HTTP(S) transport, M3 static HTML semantic extractor, M4 bounded local state store, M5 complete observation builder, M6 deterministic relevance/budget selector, M7 authorized static action executor, M8 bounded batch executor, and M9 semantic differ exist; encoding and every later layer remain contracts for later MVP implementation rather than claims about shipped behavior. See CORE-CONTRACTS.md, NATIVE-STATIC-ENGINE.md, SEMANTIC-HTML.md, STATE-STORE.md, OBSERVATIONS.md, DIFFS.md, RELEVANCE.md, ACTIONS.md, and BATCHES.md for the exact implemented boundaries.

Core flow

authorized web input
        |
        v
BrowserEngine -----> capability and structured failure
        |
        v
typed semantic state <---- bounded local state store
        |
        v
deterministic relevance ranking
        |
        v
complete-unit token selection
        |
        v
typed Observation -----> ObservationEncoder
        |                       |
        v                       v
      agent              compact JSON (MVP)
        |
        v
typed action batch + expected state
        |
        v
engine execution -----> new state -----> meaningful diff

Layers and ownership

Core contracts

mawr-core owns serialization-independent identity, capability, semantic, observation, action, transition, failure, and measurement values. It validates session and cross-field invariants without depending on an engine, parser, transport, or external protocol. Its internal Rust API remains intentionally evolvable while later milestones supply real producers and consumers.

Engines

Engines acquire and mutate page state. The mandatory native static engine implements bounded HTTP(S) document acquisition, redirects, URL resolution, session cookies, URL-encoded GET/POST form transport, and explicit safe downloads. M3 turns its static DocumentInput into bounded semantic text and controls, while M7 executes the supported static mutations and returns through extraction/state. The boundary excludes JavaScript, layout, visual rendering, screenshots, Canvas, WebGL, and media playback.

Optional dynamic engines may extend capabilities but remain outside the core model. MAWR does not initially fork Obscura. No adapter may silently launch Chromium or leak vendor types into core contracts. ENGINE-CONTRACT.md owns this boundary.

Semantic model

The implemented static semantic model represents page, region, heading, text, link, form, textbox, checkbox, radio, select, option, button, table, row, cell, list, list item, and alert roles. It retains names, descriptions, values, state, relationships, HTTP(S) destinations, source-node provenance, and action affordances without making the raw DOM the normal agent interface. Its standards subset and CSS/script limitations are documented in SEMANTIC-HTML.md.

M3 source-node IDs are deterministic only for one parsed document and are not action references. M4 maps them to compact ElementRef values that survive a defined conservative set of transitions when semantic identity is unique. References remain scoped to one session, are never recycled in that session, and do not become CSS selectors or globally durable identifiers.

Local state and semantic diffs

mawr-state retains full semantic documents locally behind explicit state and page identities. Retention is bounded by both state count and total semantic units. Current-state reference lookup distinguishes stale states, missing references, and session mismatches; evicted history is never silently addressed. M9 compares retained same-page states by stable reference, emits additions, full replacement units for updates, removals, and optional summary/order replacement, and otherwise returns an explicit full reset. STATE-STORE.md owns lifecycle; DIFFS.md owns reconstruction.

Relevance and budgeting

The implemented M6 ranker is deterministic and local for fixed inputs. Its versioned configurable weights combine goal overlap in names, descriptions, and values; structural and interactive roles; caller-supplied changed-unit hints; alert and invalid-state priority; dependency context; and repeated-text/navigation penalties. Stable references break score ties.

Budgeting selects complete semantic units and their structural/label dependencies before encoding. The page, alerts, invalid controls, and their dependencies are essential: they may explicitly overshoot a tiny budget rather than disappear. Every other omission is counted as budget or irrelevance. Tokenizer identity/version and exact-versus-estimated quality are retained; the built-in UTF-8 heuristic is always estimated. No model is invoked. RELEVANCE.md owns this boundary.

Observation and action boundary

The observation boundary contains state/page/engine identity, bounded summary, capabilities, zero-omission metadata, and construction measurements. Full/reset output contains every semantic unit; incremental output contains only added and updated units plus typed removals and changed summary/order payloads. M6 derives selected observations only from complete/reset input. M7 executes one authorized typed action, and M8 preflights bounded ordered batches with exact partial results. OBSERVATIONS.md owns construction, DIFFS.md owns deltas, RELEVANCE.md owns selection, ACTIONS.md owns single-action execution, BATCHES.md owns batch execution, and PROTOCOL.md owns the future external agent contract.

Encoding boundary

Typed observations and actions are independent of transport. Compact JSON is the MVP encoding. Alternative encoders are future measured additions and cannot require engine, semantic, state, ranking, or action changes. ENCODING.md owns encoding rules.

Future architectural directions

These directions are durable boundaries, not implementation sequencing:

  • A network semantic layer may use authorized structured responses when it preserves origin, authorization, provenance, and action semantics and never bypasses access controls.
  • Identity may add encrypted local profiles, cookies, storage, OAuth grants, and secret isolation; secret values stay out of model context unless strictly required and authorized.
  • Official service connectors may use authorized APIs when they are safer or more efficient than UI automation.
  • Workflow recall may record a verified procedure, replay it with state assertions, repair locally, and escalate to a model only when reasoning is required.
  • Observation may escalate from semantics to geometry, targeted regions, and only then full visual data when the workload justifies it.
  • Native capabilities may later add events, JavaScript, fetch/XHR, dynamic DOM, storage, selective layout, and selective paint only when benchmarks justify each step.
  • Scale may add isolated session pooling, scheduling, resource budgets, suspension, serialization, and safe cache sharing.

Security authorization applies across every layer; see SECURITY-MODEL.md.