clay-borg/specs/ArchitectureRuntime.md

# Clay-Borg Architecture — Runtime, Tooling, and Process

Second half of the architecture blueprint, split from
[ArchitectureBlueprint.md](ArchitectureBlueprint.md) on 2026-07-31 for
whole-file loadability. §1–8 (the layered stack, Clay Canon, runtime
substrate, simulation kernel, physics, world-building, tabletop domain
framework, game runtime) remain there; §9–15 are here.

Section numbering is continuous with the first half and deliberately
unchanged, so existing references keep resolving.

## 9. Rendering, input, and creation tools

Rust-first stack:

- `winit` — windows and platform input
- `wgpu` — GPU rendering (Vulkan / Metal / D3D / browser)
- `egui` — engine tools, inspectors, early editors
- Custom scene renderer for the game table
- **glTF** as the primary imported 3D format, wrapped in Clay-Borg asset
  metadata and provenance

Creator environment (grows over milestones): scene hierarchy, object
inspector, prototype browser, card-sheet importer, deck builder, zone and
snap-point editors, rule-state inspector, event timeline, player-view
switcher, hidden-information debugger, physics debugger, scenario recorder,
replay controls, package validator.

---

## 10. Networking and sessions

Authoritative session host:

```text
Client gesture
→ proposed command
→ session server validation
→ authoritative events
→ state update
→ player-specific projection
→ client animation
```

Capabilities: session discovery, auth and seat assignment, lobby/readiness,
command submission, commit/reveal windows, event-stream replication,
snapshot transfer, reconnection, state-hash verification, spectators,
player-specific redaction, host migration (later).

Transport: **Quinn** (QUIC) for native; browser transport is a separate
adapter (WebTransport or WebSockets). The canonical protocol is defined
independently of any transport:

```text
cb-session-protocol
├── CommandEnvelope
├── EventEnvelope
├── SnapshotEnvelope
├── CommitmentEnvelope
├── AssetRequest
└── CapabilityNegotiation
```

---

## 11. Agentic inner loop

Agentic coding is a first-class product surface. Optimize for small
capability boundaries, executable specifications, controlled work areas, and
replayable failures.

### Work packet (every agent task)

```yaml
task_id: CB-PHYS-0042
capability: tabletop.card-stacking
intent: Keep card stacks stable after drag release.
allowed_crates:
  - cb-physics-api
  - cb-physics-rapier
  - cb-tabletop-physics
forbidden_changes:
  - canonical game event schema
invariants:
  - semantic card order must not depend on collider order
scenarios:
  - scenarios/card-stack-20.yaml
benchmarks:
  - benches/card-stack-stability.yaml
acceptance:
  - all conformance tests pass
  - no state divergence over 10,000 ticks
  - benchmark regression below 3%
```

### CLI surface (`cb`)

```bash
cb inspect capability tabletop.card
cb task prepare CB-PHYS-0042
cb generate contracts
cb check --affected
cb test --affected            # supports --format json
cb sim ground scenarios/mutual-attack.yaml
cb play ground --players 4
cb replay artifacts/failure.cbreplay
cb compare physics-reference physics-rapier
cb bench --affected
cb evidence build CB-PHYS-0042
cb release assess CB-PHYS-0042
```

### Quality gates

Formatting/linting, dependency-policy check, unit tests, capability
conformance tests, property tests, golden scenario tests, replay
determinism, snapshot migration, performance and memory budgets, rendering
comparison where relevant, security/sandbox tests, documentation and schema
consistency.

Tooling: `cargo-nextest` (isolated parallel tests), Criterion
(regression-sensitive benchmarks), `sccache` (compile reuse), `tracing`
(structured diagnostics).

---

## 12. TargetRevenue integration

TargetRevenue governs **versioned capability improvements**, not the
monorepo as one indivisible target.

```toml
improvement_id = "CB-GROUND-001"
capability = "game.ground.simultaneous-resolution"
classification = "10x"

estimated_days = 4
daily_rate = 1000
target_revenue = 40000

phase = "commercial-recovery"
release_when_target_reached = "MIT"
trust_record = "required"
```

Components: improvement registry, workload ledger, cost model, revenue
attribution, dependency graph, phase license generator, revenue meter,
release gate, evidence bundle, trust service.

Economic rule:

> Optimized assimilations may be financed as independent improvements, while
> the canonical interface remains stable and reusable.

---

## 13. Repository structure

```text
clay-borg/
├── INTENT.md
├── SCOPE.md
├── ARCHITECTURE.md            # or specs/ArchitectureBlueprint.md (this file)
├── Cargo.toml
├── rust-toolchain.toml
│
├── canon/                     # entities, events, capabilities, schemas, terminology
├── crates/
│   ├── cb-kernel/  cb-ids/  cb-time/  cb-rng/  cb-events/
│   ├── cb-snapshot/  cb-capability/
│   ├── cb-world/  cb-world-api/  cb-ecs-bevy/
│   ├── cb-physics-api/  cb-physics-null/  cb-physics-reference/  cb-physics-rapier/
│   ├── cb-render-api/  cb-render-null/  cb-render-wgpu/
│   ├── cb-tabletop/  cb-tabletop-physics/  cb-tabletop-view/
│   ├── cb-game-runtime/  cb-game-protocol/  cb-game-wasm/
│   ├── cb-session/  cb-network-api/  cb-network-loopback/  cb-network-quic/
│   └── cb-assets/  cb-ui/  cb-editor/  cb-observe/  cb-evidence/
│
├── games/                     # ground/, fixture-cards/
├── tools/                     # cb-cli/, cb-agent/, cb-import/, cb-pack/
├── scenarios/
├── conformance/
├── benchmarks/
├── replays/
├── examples/
├── decisions/
├── assimilation/              # assimilation manifests
└── target-revenue/
```

Stay a monorepo during architectural formation. Extract a repository only
when a capability has a stable contract, an independent lifecycle, and a
genuine external consumer.

---

## 14. Milestones

| # | Milestone | Proves |
|---|---|---|
| 0 | Headless GROUND | Authoritative rules, commit/reveal, DARVO, replay — no rendering, no physics |
| 1 | Inspectable 2D table | Presentation bindings without 3D complexity |
| 2 | Physical 3D tabletop | wgpu + Rapier projection of semantic events |
| 3 | Networked sessions | Authoritative host, private projections, reconnection |
| 4 | Game creation framework | Editors, importers, Wasm game components |
| 5 | Second fixture game | Generality — abstractions promoted to Canon only after a second concrete use |

---

## 15. Governing design decisions

1. Build GROUND first, not a general engine first.
2. Keep rules independent from rendering and physics.
3. Use commands and events as the authoritative mutation mechanism.
4. Provide null, reference, and optimized implementations of important capabilities.
5. Never leak assimilated-library types into canonical interfaces.
6. Use server-authoritative physics and deterministic semantic rules.
7. Treat player visibility as a projection, not a UI afterthought.
8. Make every defect reproducible as a scenario and replay.
9. Give coding agents bounded work packets and stable commands.
10. Attach TargetRevenue phases to versioned improvements and evidence bundles.