T01: audit every InnerLoop rule, and make the checkable ones executable
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>
This commit is contained in:
parent
ee1ee485b2
commit
fed422a3a3
10 changed files with 827 additions and 242 deletions
221
specs/ArchitectureRuntime.md
Normal file
221
specs/ArchitectureRuntime.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue