tegwick
580081ef71
one clause short
Nine decisions. Two were not on T03's list; both are the review's.
D2: specs/GroundRules.md §Underdetermined IS the register. C4 pointed out
it was never evaluated as a candidate, and against the survey's own five
benchmarks it already delivers four -- including the Magic Oracle property
("a ruling flips the scenario, not the kernel", :231-233) that the survey
travelled to Magic to discover and we had written down ourselves eight
days earlier. What it lacks is reproductions. So this pass extends a
section rather than building a register: no new file, no new schema, and
no second mechanism to disagree with the first.
D3: admissibility is three clauses. It exists; it has the ruled shape
(GROUND-WP-0004 T02's row-level table, never a sum -- promoted from a T04
addendum because two of three wrong premises were sums without tables);
and it CAN FAIL. The third is C1's. GR-E01's scenario went green when the
edition landed, and the finding stayed admissible and stayed queued for
transmission, because nothing in the rule said a passing artifact was a
signal. A green reproduction is an alarm, not a reassurance.
D1 applied: INTENT gains a fourth property, Instrument, worded as a
mechanism rather than an ambition and carrying its own falsifier -- if a
pass tolerates an undecided rule by quietly picking a default, the
property is false.
D4 five kinds, each forced by an existing finding; a sixth during backfill
means the taxonomy was invented. D5 lifecycle where `applied` means the
source changed, the queue empties while the log accumulates, and
withdrawals are reported rather than deleted -- GR-E01 is why. D6 notes
admitted but never reportable, 30-day expiry on the existing age
machinery; refusing them would discard the only class of finding the
engine cannot produce itself, which is CB-WP-0025's whole input. D7 no
engine-evolution register, on an inventory C5 corrected -- narrowed, not
settled. D8 design-baseline.py retired, kept as a dated snapshot because
deleting it erases the evidence for how 33% got in. D9 the artifact stays
here, ground-game gets a generated file under its own workplan.
loop-lint: no findings. facts-check: no findings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
114 lines
5.7 KiB
Markdown
114 lines
5.7 KiB
Markdown
# Intent
|
||
|
||
Clay-Borg is a rebuild-from-scratch simulation and games engine framework: it
|
||
assimilates and optimizes techniques and implementations useful for games,
|
||
simulations, and robotics.
|
||
|
||
It is not another monolithic game engine. It is a capability-assimilating
|
||
development engine with four distinct properties:
|
||
|
||
1. **Clay** — its canonical models, contracts, rules, and tools remain malleable.
|
||
2. **Borg** — mature, optimized libraries are assimilated behind controlled
|
||
interfaces rather than copied or exposed directly.
|
||
3. **Product-driven evolution** — abstractions are extracted from working
|
||
games, beginning with **GROUND — A Game of Bonds and Rivalry: DARVO
|
||
Edition**, rather than invented in isolation.
|
||
4. **Instrument** — the engine is rigorous enough that it cannot proceed
|
||
past a rule that does not decide. What it cannot execute, it reports:
|
||
findings about the *game's* design are a product of building the
|
||
simulator, not a side activity, and they are carried back to the game's
|
||
owner with the artifact that produced them. *(ADR-0012. A restatement of
|
||
what has already happened six times, made a duty. If a pass ever
|
||
tolerates an undecided rule by quietly picking a default and not raising
|
||
it, this property is false.)*
|
||
|
||
The central rule:
|
||
|
||
> **Own the semantics; assimilate the implementation.**
|
||
|
||
Clay-Borg owns what an entity, object, command, event, card, zone,
|
||
relationship, game, simulation, asset, plugin, and capability *mean*.
|
||
External libraries (wgpu, Rapier, Bevy ECS, Wasmtime, Quinn, egui, Serde,
|
||
tracing, …) provide optimized implementations of rendering, physics,
|
||
networking, serialization, and similar functions behind canonical ports. No
|
||
external library type should leak across a canonical interface.
|
||
|
||
## Why GROUND first
|
||
|
||
GROUND requires modest physics but sophisticated social state, simultaneous
|
||
decisions, and constrained sequences (a binding DARVO deny/attack/reverse
|
||
state machine, a typed relationship graph, commit/reveal simultaneous
|
||
resolution). It must stay playable headless — no rendering, no rigid-body
|
||
simulation required to run or test the rules. The 3D tabletop is a
|
||
projection and interaction surface for the game, not the definition of the
|
||
game.
|
||
|
||
## The most important 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.
|
||
|
||
## First product
|
||
|
||
> A headless, replayable, and agent-readable GROUND rules engine that can be
|
||
> projected onto an increasingly physical virtual tabletop, while every new
|
||
> capability remains replaceable, measurable, and financeable through
|
||
> TargetRevenue.
|
||
|
||
## Implementation order
|
||
|
||
0. **Headless GROUND** — full authoritative state, 2–6 players,
|
||
commit/reveal, relationships, DARVO, GROUND practice, CLI player, replay
|
||
and scenario tests, simple bots. No rendering, no physics.
|
||
1. **Inspectable 2D table** — card/token/hand/relationship-graph
|
||
visualization, drag-to-propose, debug inspector, hot-seat play.
|
||
*Open on one human verification, and every run of it so far has found
|
||
something no test could. 2026-08-02, run 1: the drag was broken — drop
|
||
targets were `id`s, which must be unique, so the graph circle held
|
||
`seat-0` and the seat card had none (CB-WP-0016). Run 2: the drag
|
||
worked but the page was **wrong about which moves exist**, showing 5
|
||
cards each claiming all three target kinds where 9 specific commands
|
||
were legal, with no way to see what was pickable, held, or droppable
|
||
(CB-WP-0017). Both fixed. What remains is perceptual and unreachable
|
||
from here by construction (ADR-0010 D5): run `cb-play --serve 0` and
|
||
confirm you can see what can be picked up, what you are holding, and
|
||
where it may go.*
|
||
2. **Physical 3D tabletop** — wgpu renderer, Rapier-backed physics, camera
|
||
and pointer controls, snap zones, asset importer.
|
||
3. **Networked sessions** — authoritative host, private projections,
|
||
commit/reveal protocol, reconnection, replay verification, spectator mode.
|
||
4. **Game creation framework** — object prototypes, scene/zone editors,
|
||
card/deck importer, package validation, Wasm game components.
|
||
5. **Prove generality** — implement one deliberately different fixture game;
|
||
only then promote duplicated GROUND abstractions into the stable Clay
|
||
Canon.
|
||
|
||
> No concept becomes canonical merely because it looks general. It becomes
|
||
> canonical after surviving a second concrete use.
|
||
|
||
## Sister repositories
|
||
|
||
- **`ground-game`** — the authoritative home of the GROUND boardgame itself
|
||
(rules, editions, content). Clay-Borg implements the engine that simulates
|
||
it; game-semantics questions defer to that repo.
|
||
- **`target-revenue`** — the canonical home of the Target Revenue Framework
|
||
and the TRSL license text this repo is released under.
|
||
|
||
## Provenance
|
||
|
||
This intent is distilled from the fuller architectural exploration in
|
||
[`history/260730-InitialExploration.md`](history/260730-InitialExploration.md),
|
||
which also covers the runtime substrate, simulation kernel, physics
|
||
subsystem, world-building layer, tabletop domain framework, networking
|
||
architecture, the agentic inner loop (work packets, CLI surface, quality
|
||
gates), and the TargetRevenue business-control model in full detail.
|