Trust zones
The central structural decision in TWIRX is that authority only ever flows in one direction. An untrusted component may observe, extract, infer, and propose. It cannot grant itself canonical status, and nothing downstream may treat its output as though it had.
This is why the project is described as a compiler and trust architecture rather than a browser wrapper. A browser-driven scraper collapses all three zones into one process: the untrusted page, the interpretation of it, and the answer are produced together and are indistinguishable afterwards. TWIRX keeps them separable so that a result can be re-derived, disputed, and corrected.
The nine planes
The architecture separates concerns that are commonly fused. Each plane has one job and a defined relationship to the planes above and below it.
- Constitution and specification ImplementedThe invariants, charter, and normative wire schemas. This plane constrains every other one and can only be changed by public decision.
- Origin access ImplementedWhat may be retrieved, from where, under which policy. Read-only, bounded, revalidated across redirects.
- Observation and evidence ImplementedImmutable retrieved bytes under content addressing, bound to retrieval metadata in a deterministic envelope.
- Adapter compilation SpecifiedTurning a source's structure into a declared, reviewable extraction plan. Gate E1 admits adapters manually; automatic compilation is E3.
- Semantic canon SpecifiedA small stable kernel plus immutable modules and explicit mappings. Written as direction; no compiler exists.
- Typed Web intermediate representation ResearchThe operational typing layer between semantics and execution. Named in the architecture; the encoding is not settled.
- Deterministic execution ImplementedBounded, offline, no shell, no network, no model. The same evidence produces the same result.
- Agent-facing bindings PlannedMCP, WebMCP, OpenAPI, and SDK generation, downstream of a stable representation.
- Trust, security, and training evidence SpecifiedCross-cutting: authority states, admission, revocation, and the adjudication record that later research may learn from.
Reading the labels
Implemented means present in the repository and evidenced by the Gate E1 report. Specified means a normative schema, decision record, or written contract exists but code does not. Planned means an accepted direction with no specification yet. Research means an open question with no commitment that it will be built at all.
What each component is trusted to do
| Component | Implementation | Trust role |
|---|---|---|
| CLI and control path | Go | Orchestrates bounded local operations |
| Safe fetch | Go standard library | Produces untrusted response bytes under policy |
| Evidence store | Filesystem CAS | Preserves immutable body bytes by SHA-256 |
| Observation envelope | Deterministic CBOR | Binds retrieval metadata to the evidence digest |
| Primary verifier | Go | Validates the envelope and the stored body |
| Independent verifier | Restricted C | Independently validates the same canonical artefact; has no network and writes no canonical state |
| Adapter runtime | Deterministic Go JSON extraction | Creates source statements and semantic views offline |
| Controlled origin | Go test server | A reproducible fixture, not a production source |
Why two verifiers
A single implementation cannot tell you whether a rule belongs to the protocol or merely to the code that happens to enforce it. Before Gate E1, Go and C applied different text bounds, CBOR text was not validated as UTF-8, and JSON accepted duplicate keys with no explicit policy — which meant an implementation could have become normative by accident. The independent C verifier exists to make the specification, not the Go code, the thing that decides.
The full rationale is recorded in ADR 001 — Genesis validation profile.
Slow path and fast path
Compilation and execution are separate activities with opposite requirements. Conflating them is what makes browser-based agents both slow and unauditable.
Compilation — the slow path Planned
Run rarely. Allowed to be expensive.
- Isolated browsers for discovery
- Model-proposed candidate structures
- Semantic analysis and mapping proposals
- Extensive probing of a source
- Human review and admission
Execution — the fast path Implemented
Run constantly. Must be boring and deterministic.
- Direct structured access
- A compiled, declared extraction plan
- Bounded validation
- Provenance assembly
- No browser, no LLM, no open-ended reasoning, no dynamic code generation
Gate E1 implements the fast path and admits adapters by hand. Every later gate that adds intelligence adds it to the slow path, behind admission — never to the hot path. This is the property that makes the system auditable at scale: whatever cleverness produced an adapter, the thing that runs a million times is a declared plan that a reviewer can read.
Deferred components
Named in the architecture, deliberately absent from the implementation. Out of scope means unimplemented, not unimportant.
Storage and state
PostgreSQL control database, S3-compatible evidence store.
Adapter distribution
Canonical packages, signatures, and Wasm or TWABI isolation for adapter runtimes.
Semantics
Semantic module compiler and the Typed Web intermediate representation.
Agent transports
MCP, WebMCP, OpenAPI, and SDK generation.
Discovery
Isolated browser workers and model-assisted candidate induction.
Authority and settlement
Publisher verification, federation, action mandates, receipts, and optional chain anchoring.
The training-evidence ledger
The architecture will eventually accumulate something unusual: a record of observations, candidate structures, proposed mappings, accepted and rejected interpretations, drift events, adversarial examples, and repair history. That is a corpus of semantic adjudication — not of text, but of decisions about meaning and why they were made.
It may one day support research into semantic induction. It is listed here as a future data product Research and nothing more. No model exists, no model is planned for the canonical path, and no claim is made that such a model would work. Models may propose; they will not define the canon, authorise actions, or promote their own conclusions.
The constraint that makes this safe
A record of rejected interpretations is only valuable if rejections were real — which means admission has to stay slow, human, and documented for a long time before anything is learned from it. The ledger is a by-product of governance working, not a reason to weaken it.