clay-borg/specs/ArchitectureRuntime.md

Clay-Borg Architecture — Runtime, Tooling, and Process

Second half of the architecture blueprint, split from 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:

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:

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)

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)

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.

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

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.