Architecture
This is the whole system on one page, for anyone joining the build: how WilsonOS is wired today, how it should be wired in about ninety days, and an honest reading of how far each part has got. The one thing to hold onto is that WilsonOS is a thin control plane over a replaceable engine. It owns the brands, the records, the review path, the memory and the guardrails, and it treats the model runtime as something you could swap without any of that changing. Almost every choice below follows from that.
Today to target, in short
Section titled “Today to target, in short”The target is mostly consolidation, not invention. Almost every box on the target board already exists in part; the work is making the strongest existing pattern the only one.
- One core instead of three write paths. Each kind of record has one sanctioned writer, but today that rule is kept separately by the app, the provider door and the writer tools. In the target the app’s service layer is the only thing that writes, and every tool, agent and screen asks it.
- The agent sandbox becomes the rule for everyone. A conversation runtime already has the strongest boundary in the system: its own account on the server, a read-only view of the files, a scoped pass and no keys. Scheduled runs and terminal tools move inside the same boundary.
- Documents join media in one object store. Documents get ids and versions the way images already do, so a version number always means the same bytes. Accepted as a decision; not yet built.
- The outside world can wake an agent. Today only you or a schedule starts work. An event door lets a customer reply, a spend alert or a form fill land as a recorded event routed to the right agent or engine.
- Engines become one service with one cockpit template, so turning on a new channel gives you its screens.
- The brain moves from “you and one agent” to “the brand”, with every entry stamped with who added it.
The board
Section titled “The board”Read it top to bottom. The top row is everyone and everything that can start work. The second band is the agent harness: the always-on bridge for each agent, the runtime that does the work in one conversation, the scheduled runner, and the writer tools. Below the trust boundary are the app’s doors, each with the check it performs, then the core where the logic lives, then the stores and the outside services. A dashed box is missing today; a dashed arrow is an alternate or partial path. A red tag marks a gap the target closes, a green tag is new in the target, and an amber tag is a direction leaning-decided rather than signed. The two boards share one grid, so switching between them shows exactly which boxes change. The target shows direction, not availability; what you can use today is in What works today.
Four design choices carry the weight:
- Work always enters the same way. A message, a schedule and a signal are three doors onto one recorded path, with the same scope rules. See Agents.
- The runtime is a boundary, not a process detail. Each conversation gets its own working area and short-lived pass, so two conversations with the same agent run at once and neither can read the other. See how an agent runs.
- Nothing reaches the outside world directly. Generation, publishing, memory and provider reads each go through one door that holds the real credential and writes the receipt. A runtime that wanted to skip the door could not: it never had the key. See Capabilities.
- The loop closes. What a run produced is reviewed, the rating is learned from, and what is learned changes what the next piece of work loads. See the eight stations, each with the files and tables behind it.
Each subsystem, honestly
Section titled “Each subsystem, honestly”Each Today cell ends with its evidence type, the same vocabulary What works today uses, so every reading says what kind of check stands behind it. This is a reading of the architecture’s own contracts, not an availability table and not a roadmap with dates.
| Subsystem | Today | Target | What closes the gap |
|---|---|---|---|
| Triggers | Built Three doors — message, schedule, signal — onto one recorded path. Runtime check | Unchanged | — |
| Agent runtime | Acceptance in progress One isolated runtime per conversation, with its own working area and pass. Reported deployment | The same, with recovery for work in flight stated and tested | Live acceptance of the isolation boundary, and a stated recovery contract |
| Model engine | One engine behind it The boundary is drawn so the engine is replaceable; one is wired. Written design | A second engine on the same contract, proving the boundary | An adapter at the runtime boundary, and assembling the start-up bundle explicitly |
| Capability catalogue | Built Skills and workflows catalogued, discoverable, credited to the runs that used them. Runtime check | Unchanged | — |
| Doors | Built Generation, media, memory and providers each have one door holding the credential. Runtime acceptance | Unchanged | — |
| Brand boundary | Recorded, not refused Every call through a door records its brand. Instruction audit | A call for the wrong brand is rejected | Enforcement at the door, not only on the record |
| Artifacts | Built, known defects The registry identifies records; versions are appended through one writer. Runtime check | Registry-owned identity throughout | A decided design, waiting on one upstream feed |
| Review | Being rewritten Versions are reviewable and rateable. Runtime check | One consolidated review surface | The surface rewrite already scoped as its own work |
| Learn | Input thin Ratings feed skill scoring. Runtime check | Enough rated reviews for scores to mean something | Rating reviews habitually — a practice gap, not a code gap |
| Measure | Middle missing Sources land with provenance; some derived numbers are computed inside the screens that show them. Written design | A named layer where derived metrics live as records | Building that middle layer as a store |
| Identity & access | Partly built Records carry their workspace and creator. Written design | Access rules audited end to end, multi-customer | An audit of the access policies, not new schema |
| Data governance | Contract unsigned One canon, one writer is enforced in the tooling. Instruction audit | The same, with the policy signed off | Sign-off on the draft policy |
| Write paths | Three paths The one-writer rule is kept separately by the app, the provider door and the writer tools, some of which reach the database directly. Instruction audit | One service layer every door calls | Consolidating the writers behind the app; tools become thin clients |
| Scheduled runs | Outside the sandbox A scheduled run executes outside the per-conversation boundary. Instruction audit | Every scheduled run in its own isolated runtime | Handing scheduled runs to the conversation runtime path |
| Document storage | Decided, not built Media is in the object store; documents still live in the repository. Instruction audit | Media and documents in one store, by id | Moving documents onto the registry media already uses |
| Outside events | No door Only you or a schedule can start work. Instruction audit | An event door, recorded and routed | An events record and one inbound route |
| Engine service | Built twice Predict, act, measure and learn exist separately in each built engine; neither closes its learn step. Instruction audit | One engine service, three types, one cockpit template | The engine contract built once, with today’s engines as its first two types |
| Shared brain | Person-scoped Memory is scoped to one person and one agent. Runtime check | Brand-scoped memory, stamped with who added it | A brand scope on memory reads and writes |
| Ingestion | One exception Most sources run through the shared adapter interface. Runtime check | Every source through it | Moving the advertising ingest onto the shared pattern |
The specific gaps. Two record clusters have tables with no writer — one is read to avoid re-proposing something already rejected but nothing inserts into it, the other has live schema for a computation never built — and both need a decision, not a guess. One cluster has two writers with no documented split, which may be a deliberate stage-then-apply lifecycle or an accidental second writer. The derived-metrics layer is a contract, not yet a store. The target design is proposed, not signed, which is why parts of the target column carry written design. And the replaceable engine is unproven: a boundary that has only ever had one thing behind it is a claim, not a property.
Where the records live
Section titled “Where the records live”More than a hundred tables group into thirteen clusters and six areas. Every record carries the workspace and brand it belongs to, which is what makes access rules enforceable rather than advisory.
| Cluster | Area | Pillar | What it holds | Maturity |
|---|---|---|---|---|
| Identity and tenancy | Identity & access | Foundations | Workspaces, brands, people, and the grants connecting them | Done |
| Tasks and versions | Work & artifacts | 02 Goals, tasks, artifacts | A unit of work, its versions, reviews and ratings | Done |
| Conversations | Work & artifacts | 01 Agents | Threads, messages, attachments, who is in a room | Done |
| Content loop | Work & artifacts | 05 Engines (goals: 02) | Goals, signals, ideas, hooks, scripts, productions, posts, performance | Daily use |
| Media registry | Work & artifacts | 02 Goals, tasks, artifacts | The identity of every generated or imported file, its bytes, labels and publications | Done |
| Canon indexes | Work & artifacts | 03 · 04 | Searchable indexes of skills, workflows, agents, wiki pages and distilled memory | Daily use |
| Integrations | Connected data & channels | 03 Capabilities | Per-account connections and what each service reported | Daily use |
| Advertising and royalties | Connected data & channels | 05 Engines | Campaigns, keywords, bids, spend, royalty reports, the decisions taken | Daily use |
| Channel learning | Connected data & channels | 05 Engines | What a channel engine tried, what happened, what it concluded | MVP |
| Platform build | Platform build & health | not yet homed | The system’s own projects, features and work packages | MVP |
| Platform health | Platform build & health | Foundations | Resource samples, process events, errors the app threw | Daily use |
| Studio and configuration | Studio & configuration | 02 · 04 | Folders, scratchpads, saved views, dashboards, design choices | Daily use |
| External surfaces | External surfaces | outside the pillars | Records belonging to a public-facing app | MVP |
Maturity uses the system’s own ladder — Done, Daily use, MVP, Proposed — and describes the cluster’s records, not the features built on them. Every cluster obeys one canon, one writer: each kind of data has exactly one place it lives authoritatively and one path that writes it, an agent and a person reach that same writer through a tool and an app action respectively, and a hand-edited record is treated as corruption, not a shortcut. The page names no tables or columns on purpose: they are the most changeable thing in the system, and developers read the generated inventory that ships with the code.
Reading a gap honestly
Section titled “Reading a gap honestly”- A document is not evidence. A claim moves up on a check in the running system or a dated acceptance, never on a merged change or a written intent.
- No data is not zero. A surface with nothing behind it says not wired yet, and an incomplete calculation never carries a complete name.
- The newest dated evidence wins. Where a contract, a status table and a page disagree, the most recently verified one is right. Several gaps above were found exactly that way.
Related
Sources: docs/architecture/overview.md (incl. §Contract status), docs/architecture/views/system-map.html, docs/architecture/concept-map.json, docs/architecture/data-model.md (inventory by group; §Findings — no confirmed writer), docs/architecture/data-governance.md (canon policy, writer paths), docs/architecture/target-design.md (PROPOSED 2026-09-20), docs/architecture/engine.md; docs/architecture/measure.md §5, docs/wilsonos-app/capabilities.md (the maturity ladder), docs/DECISIONS.md (ADR-018, ADR-026, ADR-028) · Last verified 2026-10-06

