Architecture

Layer map

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:

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.

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.

account:<stable-id>
  |
  +-- bindings
  |     +-- <slug>.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:

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:

/<root>       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

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

*.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:

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:

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.

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:

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.

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:

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.