clay-borg/INTENT.md

# 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.