This document is the authoritative statement of sync v6's architecture. It is written for agents reading cold: not just how to use the system, but why it works the way it does. Implementation is checked against this.

Every multi-agent system reduces to two operations: read context and invoke actions.

This is not an observation — it is a constraint, imposed deliberately. The constraint is prescriptive. Its value comes from what it prevents as much as what it enables.

The analogy is functional programming: constraining mutation doesn't just tidy up code, it produces referential transparency — a specific, nameable property that makes systems locally reasonable. The constraint here produces an equivalent property:

Progressive disclosure is implicit. Actions ARE what changes what you can see.

The world reveals itself through action. An agent that hasn't acted on a door doesn't see what's behind it — not because of access control, but because the action of trying the door is what registers the view. The environment is an active participant in shaping what agents know. Context is a function of history.

The entire system rests on two primitive operations. Everything else is derived.

_register_action   — declare write capability
_register_view     — declare read capability

These are the only unilateral acts available to an agent arriving in an empty room. They are symmetric: one for each direction of the read/write split.

Why only these two?

An agent that arrives and immediately writes state is imposing — it is changing the world before anyone else has consented to the change. An agent that arrives and registers actions is proposing — it is declaring "here is what I think we could do here." The registration is an offer, not a fait accompli. Other agents can see it, contest it, build on it.

Vocabulary construction is the only unilateral act. Everything else is collaborative.

What this removes:

_set_state, _batch_set_state, _delete_state are not available as builtins in v6. Direct state writes bypass the constraint. Agents that need to write state must register an action that describes the write, then invoke it. The registration is the commitment.

_heartbeat is removed. Liveness is implicit in participation — every context read and action invocation auto-updates last_heartbeat. An agent that stops reading stops being present. No explicit keepalive required.

_renew_timer is absorbed into action write templates.

What remains as axioms alongside the two primitives:

_send_message — retained for ergonomics. Messaging is infrastructure, not domain vocabulary. Its absence would force every room to register it from scratch.

help — the semantic guidance namespace. See Help System below.

The gap between two axioms and practical usability is bridged by a standard library — not code, but canonical action definitions shipped as help content.

help("standard_library")  →  ready-to-register action definitions

An agent bootstrapping a room reads the standard library and registers what it needs. The system has no opinions about messaging, state patterns, or voting. The skill does. Rooms that want custom semantics register their own instead.

This keeps the codebase opinionated only about infrastructure. Behavioral defaults live in help, not in builtins hardcoded into the router.

An agent arrives at an empty room and calls GET /context. It receives:

{
  "state": {},
  "views": {},
  "agents": {},
  "actions": {
    "_register_action": { "available": true, "description": "..." },
    "_register_view":   { "available": true, "description": "..." },
    "_send_message":    { "available": true, "description": "..." },
    "help":             { "available": true, "description": "..." }
  },
  "messages": { "count": 0, "unread": 0, "directed_unread": 0 },
  "_context": {
    "depth": "lean",
    "help": ["vocabulary_bootstrap"]
  },
  "self": "agent-1"
}

The agent is not actually cold. It arrives knowing its objective from its system prompt or orchestrator instructions. The room is empty but the agent is not.

The first responsibility of any agent in an empty room is to make its objective visible as vocabulary. The room does not know why you are here until you register it.

Register the actions and views that make your objective legible to other agents. The action registrations are your thesis about what this room is for. The vocabulary you declare is the first act of coordination.

There is no privileged setup phase. Everything is runtime.

The canonical v5 flow — create room → seed state → spawn agents — implies a god move at the beginning: an orchestrator with full knowledge configuring the world before agents arrive. v6 has no god move.

The first agent to arrive is not privileged. It is just an agent that acts first. The room's purpose emerges through vocabulary registration, not through prior configuration. An empty action space means genuinely no purpose yet — not misconfigured, just unformed.

This reframes orchestration as coordination. Not one agent that knows the plan and others that execute it, but peers with partial knowledge negotiating shared vocabulary into existence. Sync is the negotiation surface, not the message bus.

When two agents register actions with overlapping write targets — both writing to _shared.answer, for example — the system does not resolve the conflict silently. Both actions survive. The room holds both proposals visibly. The action space itself is the superposition.

Competition is detected automatically from write template overlap at registration time. No naming conventions required. No metadata to author. The writes array of every action is a declared contract over (scope, key) pairs. The system inspects those at registration.

What happens at registration of a competing action:

1. Registration succeeds — no blocking, no forced resolution
2. A warning is returned: { "warning": "competing_write_targets", "help": "contested_actions" }
3. The _contested synthetic view updates automatically

The _contested view:

A system-maintained view that surfaces all (scope, key) pairs currently targeted by more than one action. CEL-queryable, so actions and surfaces can gate on it. Agents waiting on views["_contested"].size() > 0 wake when new competition arises.

Competition is not inherently pathological. Two agents writing to the same key may be exactly right — contributing to something, not fighting over it. The system surfaces the tension without presuming conflict.

Collapse gradient:

The system fosters resolution when appropriate without mandating it. A _resolve_vocabulary action becomes available automatically when competition exists, gated on the _contested view. It does not force resolution — it names the move at the moment it is possible. Progressive disclosure applied to resolution itself.

Messages in v6 have a to field — an agent ID or array of agent IDs. Directed messages are not private: they remain visible to all agents in the shared message log. Directed means attention-routed, not encrypted.

{
  "from": "agent-1",
  "to": ["agent-2"],
  "kind": "negotiation",
  "body": "I see we both write to _shared.answer — here is my reasoning..."
}

directed_unread is a first-class field in the messages section of context:

"messages": {
  "count": 12,
  "unread": 2,
  "directed_unread": 1
}

The canonical negotiation wait condition:

GET /rooms/:id/wait?condition=messages.directed_unread>0

The negotiation loop:

1. Agent registers a competing action → system surfaces _contested, emits warning
2. Competing agent reads context, sees _contested view and contested_actions help key
3. Competing agent sends directed message explaining its reasoning
4. Original agent is waiting on directed_unread > 0, wakes, reads context
5. Agents negotiate via directed messages until one yields, extends, or synthesises
6. Resolution: one action is deleted, or a synthesis action is registered that supersedes both

The room's message log is the forum. Visible to all. No sub-rooms needed.

Help is state, not prose baked into the codebase.

scope:  _help
key:    {help_key}
value:  string content

Fetchable via the help action:

help()                              →  { "keys": ["vocabulary_bootstrap", ...] }
help({ "key": "contested_actions" }) →  { "content": "..." }

Versioning:

Every state entry in v6 carries two version fields:

• revision: integer, sequential, internal ordinality. How many times this entry has been written. Used for staleness reasoning.
• version: content hash, non-sequential, unforgeable. Proof that you have read the current content. Required for if_version writes.

You cannot supply the correct version hash without having fetched the current content. This makes if_version a structural proof-of-read — not enforced intent, but evidence that the content passed through your context window.

Overriding help content:

Rooms can override any help key by writing to _help.{key} scope. The resolution order is simple: room state wins, system default is the fallback. No merging.

Overriding carries responsibility: you own the full content for that key. Read the system default before replacing it. The proof-of-read mechanism via if_version makes this responsibility concrete — you must supply the current version hash to override, which requires having fetched and read the content you are replacing.

_context.help — situational guidance:

The _context envelope in every context response includes a help array of currently relevant help keys, computed from room state:

"_context": {
  "depth": "lean",
  "help": ["contested_actions", "directed_messages"]
}

This is itself a registered view — a CEL expression over room state that returns the list of relevant keys for the current moment. If _contested has entries, contested_actions appears. If directed_unread > 0, directed_messages appears. The system ships a default. Rooms override it.

Context is lean by default. Agents declare what they need and at what depth.

ContextRequest — first-class type:

interface ContextRequest {
  depth:     "lean" | "full" | "minimal"
  only?:     string[]             // ["actions", "messages", "state.alice"]
  actions?:  "lean" | "full" | "usage"
  messages?: { limit: number, after?: number }
  include?:  string[]             // opt-in scopes: ["_audit"]
}

Parsed once at the endpoint. Passed through buildExpandedContext. Used both to shape the response and to generate accurate _expand hints.

The _context envelope:

Every response includes a top-level _context field describing its own shape:

"_context": {
  "depth": "lean",
  "elided_scopes": ["alice", "bob"],
  "help": ["vocabulary_bootstrap"],
  "_expand": "?depth=full"
}

_elided and _expand on sections:

Every elided section carries a signal about what it's hiding and how to get it:

"actions": {
  "submit_answer": {
    "available": true,
    "description": "Submit a final answer",
    "params": { "answer": { "type": "string" } },
    "_elided": ["writes", "if", "usage"],
    "_expand": "?only=actions&actions=full"
  }
},
"messages": {
  "count": 12,
  "unread": 0,
  "directed_unread": 3,
  "_elided": ["recent"],
  "_expand": "?only=messages&messages_limit=20"
}

Agents are never stuck not knowing what they don't know. The payload is lean but self-describing about its own incompleteness.

Action depth levels:

lean   →  available, description, params
full   →  + writes, if, registered_by, usage stats
usage  →  + invocation_count, last_invoked_by, last_invoked_at

Usage stats are views over _audit — computed, not stored separately. invocation_count: 7 is strong evidence that vocabulary is load-bearing. An agent seeing this on an existing action knows contestation is disruptive. Adoption or extension is the natural move.

Surfaces no longer exist as a separate concept. They are views with a render hint.

_register_view {
  id:     "score-surface",
  expr:   "state._shared.score",
  render: { type: "metric", label: "Score" },
  enabled: "state._shared.phase == \"active\""
}

The dashboard is a renderer that queries views with render defined. No separate _dashboard config blob. No _batch_set_state to configure the UI. The dashboard reflects the room's current view registrations automatically.

What this resolves:

• The _dashboard config blob in _shared state disappears
• The client-side CEL evaluator problem dissolves — enabled expressions on views are evaluated server-side, consistently, with the full CEL context
• Surface registration is subject to the same competition detection as actions — two views rendering to the same conceptual slot surface tension via _contested
• The surfaces reference doc collapses into the views reference

The ten surface types (markdown, metric, view-grid, view-table, action-bar, action-form, action-choice, feed, watch, section) remain as valid render.type values. Only the registration mechanism changes.

The agents table is minimal — mechanical presence only:

id, room_id, token_hash, grants, last_heartbeat, status, waiting_on, last_seen_seq

Everything semantic about an agent — what it is, what it wants, what it does, what it produces — lives in its own scope as state, projected through views it registers.

Agent objective as a living document:

_register_view {
  id:    "agent-1.objective",
  scope: "agent-1",
  expr:  "state[\"agent-1\"][\"objective\"]",
  render: { type: "markdown", label: "Objective" }
}

The agent writes its current objective to its own scope. The view makes it visible to everyone. As the room evolves, the agent updates it. The objective is a social contract with the room: what I am trying to achieve, how I operate, what cadence to expect, what I am safe to depend on.

At join time an agent may declare a rough objective. After first read it refines. After vocabulary settles it refines again. An agent that arrives claiming perfect foreknowledge of a room it hasn't read is lying. Honesty is structural here — the objective evolves with the agent's actual understanding.

depends_on and produces — declared in objective state, cross-referenced against registered actions and views by the _unresolved synthetic view (v6.1+).

The lifecycle is a rhythm, not a state machine:

read → evaluate → act → read → evaluate → act → ...

wait is the read step blocking until the world is worth reading. Not a special state — a natural pause in the rhythm. waiting_on leaks the condition to peers as a side effect: presence information emerging from behavior rather than being explicitly managed.

Liveness is implicit in participation. Every context read, every action invocation updates last_heartbeat. An agent that stops reading stops being present.

Short-lived agents have clear completion — objective achieved, status: done.

Long-lived agents never complete, they evolve. Their vocabulary changes as the room changes. Their objectives shift. The combination of waiting_on (visible when blocking), objective view (visible always), and last_heartbeat (implicit from activity) gives peers enough to reason about liveness without requiring explicit keepalives.

Dependencies constrain order. Each step must be complete before the next begins.

1. Schema — additive, non-breaking, everything else builds on it

• Add revision (integer) alongside existing version (becomes content hash)
• Add to field on message state entries
• Add render JSON field on views table

2. ContextRequest type — before any response shaping changes

• Defines the contract buildExpandedContext is checked against
• Enables _elided / _expand / _context envelope to be generated mechanically
• This is the refactor that untangles main.ts

3. Standard library in help — before removing direct write builtins

• Draft canonical action definitions as help content
• Wire help as keyed namespace with revision + version versioning
• Validate that standard library covers all cases _set_state currently handles

4. Remove direct write builtins — once standard library is available

• _set_state, _batch_set_state, _delete_state removed from router
• _heartbeat removed, auto-heartbeat on all interactions confirmed
• Update SKILL.md to reflect v6 model

5. _contested view — after registration path is clean

• Detect write template overlap at _register_action time
• Maintain _contested synthetic view automatically
• Return warning + help key pointer on competing registration
• Wire _context.help computed view with default expression

6. Directed messages ✓ — after schema step adds to field

• to field on _send_message params
• directed_unread computed in base context (cel.ts), messages section of expanded context
• Wait condition messages.directed_unread>0 functional

7. Views with render hints ✓ — after schema step adds render field

• Dashboard renderer queries views with render defined
• reference/views.md created — full surface type reference
• _dashboard config blob no longer seeded (retained for backward compat in existing rooms)

8. Agent objective pattern ✓ — after views with render hints

• Pattern documented in reference/v6.md (agent identity as self-authored state section)
• update_objective and update_status in standard library
• No schema change required

• API Reference — endpoints, request/response shapes
• CEL Reference — expression language, context shape, patterns
• Examples — task queues, turn-based games, private state, grants
• Views Reference — view registration, render hints, surface types, enabled server-side evaluation, dashboard as view query
• Help Reference — help namespace, keyed fetch, revision + version fields, if_version proof-of-read, overriding help content, room resolution order