tegwick
fed422a3a3
41 rules classified executable / checkable / decorative, each tagged with
the failure class it catches. Counts: 11 executable, 22 checkable, 4
decorative (one of them dead policy).
Audit: history/260731-inner-loop-rule-audit.md
New tools/loop-lint.py makes 7 rules executable (tier declared, chaos
roll recorded, tier-L review trail, unmeasured-in-evidence, whole-file
loadability, reporting tools expose --self-test). It found three real
violations on its first run, none previously visible:
- specs/ArchitectureBlueprint.md was 543 lines against a ~400 limit
the loop has stated since v0.2 and never measured. Split at its own
section boundaries into Blueprint (1-8) + Runtime (9-15).
- tools/dep-weight.py and tools/rule-coverage.py had positive-control
logic and no --self-test, so nothing verified the control worked.
Adding rule-coverage's self-test exposed a latent instance of the exact
class this workplan is about: if the spec regex stopped matching, rules
was empty, missing was empty, and the tool exited 0 reporting "0/0" --
a silent pass, in the tool that reports our headline AM-1 number. Both
tools now assert they found something before reporting.
Two demotions applied in the spec rather than left implicit: "structured
over prose" is marked guidance (nothing can check it), and the 8k/10k
token budget is struck through and marked DEAD POLICY pointing at T05.
The audit's uncomfortable finding: rule 13 (re-derive inherited numbers)
has no mechanical form, is deliberately left decorative, and caught the
LARGEST error in CB-WP-0002. That is a counter-example to this
workplan's own hypothesis. "A rule that cannot be executed is not a
rule" is wrong as stated; the defensible version is that such a rule
cannot be relied on to fire, so it must not be the only defence for a
class that matters.
Class coverage: harness-does-nothing has five executable rules;
trusted-arithmetic has ZERO and produced the largest single error.
make loop-lint and make self-tests wired into `make all` and CI.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
221 lines
7.1 KiB
Markdown
221 lines
7.1 KiB
Markdown
# 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.
|