--- title: "Architecture" description: "System boundaries, the headless operating model, account holons, and the reference implementations." navLabel: "Architecture" order: 30 nav: true eyebrow: "System map" status: "canonical" theme: "main" visibility: "public" --- ## Layer map ```text Pre identity, custody, provenance, authority, respect | +-- Pre Account -- governed custody, authority, billing, export | +-- Presertion -- knowing | +-- HARnest ---- doing | +-- Har -- realtime relational membrane | +-- Stow ------- encounter and local capability | +-- pre CLI ---- shell and local participant interface | +-- *.pre.bi --- network bindings and surface projections ``` External services and substrates remain replaceable: ```text Linear work projection Brevo mail transport, inbound parsing, and delivery evidence Gmail external communications source and transport Microsoft external communications source and transport GitHub code and versioned artifacts Vercel serverless application execution and delivery Instant current hosted relational and persistence implementation OpenRouter optional evanescent model-compute gateway Cloudflare DNS, edge, routing, and abuse controls Backblaze durable object storage ``` ## Headless, stateless operating model Pre is a substrate-independent operating system for persistent relational identity, knowledge, and agency. It is **headless** because no interface is privileged. It is **stateless at the execution edge** because a function, model, browser session, controller, or CLI process may disappear after leaving attributable durable records. The world itself remains durable. ```text instantiate -> identify -> resolve account and record scope -> retrieve bounded context -> resolve authority -> perform one action -> preserve events, evidence, result, and receipt -> terminate ``` ## Pre Account boundary A Pre Account is an independently addressable holon and the default top-level boundary for custody, authority, billing, export, restore, and succession. ```text account: | +-- bindings | +-- .pre.bi | +-- custom domain | +-- provider tenant IDs | +-- memberships and identity bindings +-- custody and retention policy +-- workspaces and rooms +-- records, artifacts, evidence, and assertions +-- tasks, runs, approvals, verdicts, and receipts +-- communications and relationship projections +-- engagements, entitlements, quotas, and external payment bindings +-- exports, restores, and succession ``` A hostname, organization name, person name, repository, database row, billing account, or provider tenant is not the canonical account identity. Each may be an external binding. A person may participate in several accounts. An account may represent a person, family, organization, archive, community, or separately governed initiative. Cross-account access requires an explicit bounded context grant or capability. ## `*.pre.bi` resolution A request to an account surface follows this shape: ```text request host -> trusted hostname normalization -> admitted external-binding lookup -> canonical account candidate -> authenticated identity -> account membership and capability resolution -> field-scoped projection or action ``` The hostname selects a candidate account; it does not grant access. Client-supplied account IDs, slugs, hosts, headers, roles, or memberships are untrusted input. Reserved infrastructure labels include `main`, `api`, `reply`, `assets`, `status`, `admin`, and `work`. ## Account surfaces One account may project through several paths and interfaces: ```text / public or member presence /inbox relationship-centered communications /records Presertion knowledge, evidence, and chronology /work HARnest tasks, approvals, evidence, receipts, and handoffs /people people, organizations, and relationships /files artifacts, renditions, provenance, and custody /ask later bounded account or avatar mediation /settings membership, transports, retention, usage, billing, export ``` Public and authenticated surfaces may differ in visible fields and available actions while remaining projections over the same governed account world. No surface receives authority merely because it can display a record. ## Deployment topologies The account contract survives several implementation stages. ### Isolated manual account ```text one exact hostname binding one account configuration one isolated canonical store or data namespace one object-storage namespace one steward one complete export ``` Use this topology for the first paid and lighthouse accounts while HARnest persistence and authorization are still being normalized. ### Shared wildcard platform ```text *.pre.bi -> trusted account resolver -> account-scoped store queries -> account-scoped authorization -> typed account surface ``` Standard accounts may share application code and infrastructure only after unrelated writers cannot overwrite one another, every query is account-scoped, tenant isolation is tested, and backup and restore are accepted. ### Dedicated or federated account Sensitive, sovereign, institutional, or local-first accounts may use dedicated stores, deployments, regions, object custody, or self-hosted conforming implementations. Migration must preserve account address, provenance, authority history, protocol semantics, and exportability. ## Relational stored-program architecture Instructions, data, identity, authority, context, evidence, and interface descriptions may all be addressable records. That does not make every record executable. The safety boundary remains explicit: ```text message != execution identity != authority account address != membership hostname != account authority record != command schema validity != trust evidence != verdict process completion != objective completion model invocation != participant succession != authority transfer ``` ## Protocol reference kernel Step 1 separates semantic contracts from persistence: ```text ActionEnvelope | v trusted protocol kernel - durable request claim - identity + account + authority resolution - attenuating capability/context chains - trusted risk classification - bounded executor - ordered events - evidence - optional objective evaluator - ResultEnvelope + immutable Receipt | v ProtocolJournal / storage adapter ``` The reference implementation uses in-memory authority, journal, and resource stores. `ProtocolJournal` permits synchronous or asynchronous persistence without allowing storage mechanics to redefine observable semantics. A Har, Instant, SQL, local-first, filesystem, or other implementation must preserve: - only admitted authority state is trusted; - account scope is resolved before account-owned state is read or mutated; - delegation cannot escalate; - idempotent replay cannot duplicate effects; - changed input cannot masquerade as replay; - incomplete requests remain recoverable; - evidence and verdicts stay distinct; - verified verdicts cite attributable evidence; - external projections do not own canonical objects; - succession does not inherit authority. ## HARnest Step 2 implementation The first real product implementation lives in repository `prepace/harnest`, not in this canonical-map repository. ```text Browser / operator | v HARnest on Vercel - SSR public/private projections - operator and controller authentication - server-resolved domain policy - canonical action/result/receipt boundary | +---------------------------+ | | v v Instant Local controller - inherited domain - local repository authority checkpoint - fixed Git reads - request-scoped - allowlisted verification scripts protocol documents - detailed local-only artifacts - idempotency - optional OpenRouter synthesis - events/evidence - sanitized remote summaries - verdicts/receipts ``` The web server does not receive shell authority, Git credentials, local repository paths, raw command output, or OpenRouter credentials. The controller may request and record bounded work. It does not issue its own objective verdict or gain write authority through messages or model output. The optional model invocation sees only sanitized evidence. The durable participant is `agent:pre:repo-auditor-01`; gateway, requested model, actual model, provider, usage, and cost belong to the invocation record. The first copy-safe handoff is account-unbound. It identifies implementation provenance and workspace, room, task, and run scope without claiming an account that the current product has not admitted. ## Durable protocol spine versus domain projection The supplied HARnest implementation persisted its complete domain ledger as one server-only checkpoint. Step 2 preserves that projection for compatibility while adding independently keyed canonical protocol documents: ```text idempotency claim request bundle event evidence objective verdict receipt ``` This means accepted actions and evidence no longer exist only inside the mutable checkpoint. It does not make the checkpoint a final relational design. The next persistence boundary is to migrate tasks, runs, assignments, events, evidence, approvals, and related domain state into independently transacted normalized entities or another conforming HarStore. Account implementation must build on that normalized boundary rather than place unrelated accounts in one checkpoint. The canonical protocol export and conformance suite serve as the migration oracle. ## Communications as an account projection Email and other communications are account-bound records, not provider-owned inbox truth. ```text external transport -> authenticated adapter event -> account and relationship resolution -> canonical message, delivery, attachment, and provenance records -> /inbox projection ``` Brevo may provide sending, inbound parsing, and delivery evidence. Gmail, Microsoft, direct SMTP, SMS, and voice may provide other transports. Provider message IDs remain external bindings. The account retains the canonical relationship, conversation, task, evidence, and retention context. ## Content reference implementation Step 0 applies the same architecture to this site: ```text ContentSource -> Markdown record -> trusted compiler -> PageDocument v1 -> renderer -> HTML / JSON / Markdown projection ``` The current `FilesystemContentSource` reads a catalog and canonical Markdown files. A future `HarContentSource` can replace it while retaining the source-record and projection contracts. Presentation is bounded: 1. content selects a semantic theme name; 2. trusted code resolves that name to known class strings; 3. the compiled JSON carries the resolved strings; 4. the renderer consumes the projection without accepting arbitrary executable markup. ## Repository ownership `prepace/main:main` owns: - the canonical map; - protocol constitution; - schemas and conformance fixtures; - the Pre Account and network-binding decision; - architectural decisions and cross-workstream status. `prepace/harnest:main` owns: - task rooms and agency projections; - operator and controller boundaries; - domain persistence adapters; - account-scoped HARnest implementation; - local bounded executors; - model-gateway integration; - live operational acceptance. Customer and account records belong in governed runtime stores, not either Git repository.