Architecture Principles

Architecture Principles

CW borrows from classic systems engineering without trying to become a literal Unix clone.

The design mantra:

Small kernel.
Explicit state.
Composable pipes.
Isolated workers.
Verifier-gated commits.

1. Everything Important Is State

Important workflow events become inspectable state:

• prompt
• task
• dispatch
• worker result
• error
• verifier decision
• candidate score
• candidate selection
• schedule
• routine trigger
• commit
• topology run
• coordinator decision
• trust audit event

State should be inspectable, replayable where possible, comparable, and usable as report evidence.

2. Small Kernel

The runtime owns stable system calls:

plan()
dispatch()
recordResult()
score()
select()
verify()
commit()
report()
schedule()
trigger()

Domain behavior belongs in workflow apps, workers, verifier logic, and topology recipes. It should not leak into host-specific skills or wrappers.

3. Pipelines Over Monoliths

The canonical pipeline is:

workflow definition
-> validated input
-> task files
-> dispatch manifest
-> worker result
-> result envelope
-> candidate scoring
-> verifier gate
-> verifier-gated commit or explicit checkpoint
-> report

Each step should produce an artifact or state record.

4. Isolated Workers

Worker failure should not corrupt the kernel.

Isolation appears in:

• task prompt boundaries
• worker output directories
• result envelopes
• sandbox profiles
• candidate scoring
• fanout/fanin evidence
• host-enforced process, network, path, and environment controls

CW validates and records policy. The agent host still enforces OS/process, network, and environment isolation.

5. Verifier-Gated Commits

The final rule:

only verified state becomes committed state

Unverified outputs remain candidates, results, or explicit checkpoints. They do not become committed state by accident.

6. Mechanism Separate From Policy (v0.1.53)

The capability registry is one declared table — mechanism. Which capabilities exist and what they do is declared separately as data — policy. Both front doors read the table and route through one shared core entry per capability:

BUILTIN_CAPABILITIES: CapabilityDescriptor[]  ← mechanism (one declared table)
  each row names ONE shared core `entry`      ← the single source both surfaces use
  the row's `cli` and `mcp` bindings          ← policy (two renderings of that entry)

Same for topologies:

Map<string, TopologyDefinition> ← mechanism
  OFFICIAL_TOPOLOGIES           ← built-in policy
  registerTopology()            ← user-registered policy

New capabilities auto-work across all three surfaces (CLI, MCP, Workbench) because the mechanism is uniform. Fail-closed on unknown ids.