Architecture invariants

​

What invariants are, and what they aren’t

• Feature flags. Clawboo used to gate subsystems (board, executors, MCP, governance) behind CLAWBOO_* flags; that flag layer has been removed and every subsystem is always-on. Invariants are not toggleable; flags were.
• Style conventions. Where files live, how a component is named; those are conventions, enforced by review, not by structure.
• Behavioral guarantees. “The team chat never floods with 40 responses” is a behavior the cascade-prevention machinery upholds; it is verifiable but it is implemented across many files, not a single structural rule.

​

The model

​

The seven invariants

​

1. The registry is the source of truth for who exists; the Gateway for how OpenClaw runs

// apps/web/server/lib/agentSource/registry.ts
this.registry.register(this.source) // OpenClawAgentSource
// ...
this.registry.register(this.nativeSource) // ClawbooNativeAgentSource

// apps/web/server/lib/agentSource/openClawAgentSource.ts (upsertFromList)
.onConflictDoUpdate({
  target: agents.id,
  // GATEWAY-OWNED columns ONLY — never teamId / personality / execConfig /
  // avatarSeed / participantKind / runtime / capabilities / tenantId.
  set: { name, gatewayId, sourceAgentId, identityJson, archivedAt: null, updatedAt: now },
})

​

2. Same-origin WebSocket for the browser

// packages/gateway-client/src/helpers.ts
export const resolveProxyGatewayUrl = (): string => {
  if (typeof window === 'undefined') return 'ws://localhost:18790/api/gateway/ws'
  const protocol = window.location.protocol === 'https:' ? 'wss' : 'ws'
  return `${protocol}://${window.location.host}/api/gateway/ws`
}

// apps/web/server/index.ts
server.on('upgrade', (req, socket, head) => {
  if (resolvePathname(req.url) === '/api/gateway/ws') {
    proxy.handleUpgrade(req, socket, head)
    return
  }
  socket.destroy()
})

​

3. All Gateway events go Bridge → Policy → Handler

// packages/events/src/index.ts
export function processEvent(frame: EventFrame, handler: EventHandlerHandle): void {
  const classified: ClassifiedEvent = classifyEvent(frame) // Bridge
  const intents = derivePolicy(classified) // Policy
  handler.applyIntents(intents, classified) // Handler
}

// packages/events/src/policy/index.ts
export function derivePolicy(event: ClassifiedEvent): EventIntent[] {
  switch (event.kind) {
    case 'runtime-chat': {
      /* … */ return decideWorkChatEvent(event, payload)
    }
    case 'runtime-agent': {
      /* … */ return decideWorkAgentEvent(event, payload)
    }
    case 'approval':
      return decideTrustEvent(event)
    // …
  }
}

​

4. Packages never import apps

apps/web  ──imports──▶  @clawboo/db, @clawboo/events, @clawboo/executor, …
packages  ──never───▶  apps/

​

5. Every graph edge maps to real state, no decorative edges

• Dependency edges (Boo → Boo) come from parsing each agent’s AGENTS.md routing rules. buildGraphElements runs parseAgentsMd(files.agentsMd, agentNames) and emits one dependency edge per resolved @mention route, a real routing instruction the agent will act on.
• Skill edges and resource edges (Boo → tool) come from the unified capability inventory. They are built from files.capabilities, real CapabilityRecord entries from the capability registry, and the server-evaluated available flag drives whether a node renders greyed.

// apps/web/src/features/graph/useGraphData.ts
if (files?.agentsMd) {
  const bindings = parseAgentsMd(files.agentsMd, agentNames) // real routing
  // → one 'dependency' edge per binding
}
const caps = files?.capabilities // real inventory
// → 'skill' / 'resource' nodes + edges per capability

​

6. Every Boo is a real agent record

// apps/web/src/features/graph/useGraphData.ts
const booNodes: GraphNode[] = agents.map((agent) => ({
  id: `boo-${agent.id}`,
  type: 'boo',
  data: { agentId: agent.id, name: agent.name, status: agent.status ?? 'idle' /* … */ },
  position: { x: 0, y: 0 },
}))

// apps/web/server/api/agents.ts (cleanup-ghosts)
.where(eq(agents.sourceId, 'openclaw'))

​

7. The schema is idempotent and additive (the evolved “forward-only” rule)

// packages/db/src/schemaBootstrap.ts
// The SOLE schema-creation source: this block declares every table, index and
// trigger on a fresh DB outright. `schema.ts` is the Drizzle TYPE layer over the
// same tables (used for typed queries, NEVER migrations); schemaSource.test.ts
// guards the two against drift.

• The unapplied drizzle ladder must not ship or run. The @clawboo/db package’s files array excludes drizzle, and there are no db:migrate / db:generate scripts (only a read-only db:studio). A test pins this posture so a stray migration runner can’t be reintroduced.
• The type layer and the runtime DDL must agree. schemaSource.test.ts builds a real DB via createDb(':memory:') and asserts that every table and column in the Drizzle schema.ts type layer matches the live DDL, and vice versa.
• An existing database is reconciled up to the DDL, not assumed to match it. IF NOT EXISTS skips the whole CREATE TABLE when the table is present, so a new column would never reach a database created before it. reconcileSchema derives the declared column set from the same DDL and adds what is missing, before the DDL batch runs (an index over a new column cannot be created until the column exists). See Database schema.

​

Design rationale and trade-offs

​

Boundaries and non-goals

• Invariants are structural, not behavioral. They guarantee the shape of the system (who is canonical, who talks to whom, which way dependencies point). They do not, by themselves, guarantee that a feature behaves correctly; that is what tests and the cascade-prevention machinery are for.
• Some invariants are OpenClaw-specific and have generalized. Invariants 1, 2, 3, and 6 were originally phrased around the single OpenClaw runtime. As the multi-runtime board path became the default, they generalized: a teammate is now a RuntimeAdapter (not only an OpenClaw agent), and a future non-OpenClaw runtime emits a normalized lifecycle-event stream server-side rather than flowing through the Gateway WS bridge. The generalized forms above are the current ones.
• The schema invariant will likely evolve again. Preserving real data across an additive schema change is handled. Preserving it across a change that rewrites or removes a column is not, and is the next step whenever one is needed.

​

See also

• Gateway and events, the Bridge → Policy → Handler pipeline in depth (invariant 3)
• The agent model, Boo, Boo Zero, and the five runtime classes (invariants 1, 6)
• The board, the durable task substrate the multi-runtime direction is built on
• Capabilities, the capability inventory behind the graph’s skill/resource edges (invariant 5)
• AgentSource, registry of record, the sync discipline behind invariant 1
• Database schema, the tables the idempotent DDL declares (invariant 7)
• Glossary, canonical term definitions