tegwick
bff64053ca
The maintainer's observation decided the design: aspects partition the GAME, strata partition our apparatus, and they are orthogonal. A module is one coordinate change in aspect space with an obligation in every stratum. So aspect identity must NOT be Rust types -- an aspect ground-game adds would make clay-borg fail to parse a configuration rather than fail to run it, welding the two coordinate systems at the one place they must stay independent. Chosen: identity as data (Configuration round-trips anything the catalog names), behaviour exhaustive (Rules, no catch-all), resolve() between. Decisive argument: the catalog ALREADY ships modules with a rules_delta and status: proposed, so a per-aspect enum would report them as "unknown module" -- indistinguishable from a typo, a false statement about the edition, and this project's signature failure shape. Two facts need two errors. Federating design authority is permanent, so the representation must outlive the implementation. Legacy ids alias forever through the catalog's own legacy_experiment_id, on the standard-Np precedent: 26 recordings name them and the expansion is exact, so there is nothing to deprecate. T00 done: the schema-2 mirror had arrived with no digests (19 files) and edition-check was red. Digests are now generated by WALKING editions/, not typed -- two reviews already found hand-written lists that made their own controls vacuous, and a mirror that grows a directory is what breaks a maintained list. PROVENANCE-catalog.md was a file inside the mirrored tree that upstream does not have; folded into our own PROVENANCE.md, since provenance about the mirror does not belong inside the thing it describes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
141 lines
5.9 KiB
Markdown
141 lines
5.9 KiB
Markdown
# Edition & rules catalog (schema 2 — composable modules by **aspect**)
|
||
|
||
**Authority:** this file + [`catalog.yaml`](catalog.yaml) on `main`.
|
||
**Aspect map:** [`ASPECTS.md`](ASPECTS.md) — full design-space dimensionality for GROUND.
|
||
**Simulator research:** clay-borg `research/CB-RES-0010-game-aspects-and-design-space.md`
|
||
|
||
**Purpose:** pin **baseline content** and **independent rules modules** so humans and **clay-borg** can run any module alone or in combination, measure, keep, or reject — without silent baseline edits.
|
||
|
||
---
|
||
|
||
## Model
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ baseline content │ editions/ground-darvo-rN/
|
||
│ (CSVs, print data) │
|
||
└──────────┬──────────┘
|
||
│
|
||
┌─────────────────────┼─────────────────────┐
|
||
▼ ▼ ▼
|
||
problem_stress attack_relief end_condition …
|
||
(≤1 module) (≤1 module) (≤1 module)
|
||
▲ ▲ ▲
|
||
└────────── aspects of the game ────────────┘
|
||
```
|
||
|
||
| Concept | Meaning |
|
||
|---------|---------|
|
||
| **Aspect** | An orthogonal **design dimension** of the game (how stress is routed, how the game ends, how Problems enter play, …). Full list: [ASPECTS.md](ASPECTS.md). |
|
||
| **Baseline** | Edition **data** package (`Problems.csv`, modes, …). Frozen columns still require `rN→rN+1` (GROUND-WP-0002 T01). |
|
||
| **Module** | One implementable choice on **one aspect**. Defaults are named modules with no delta. |
|
||
| **Profile** | Named list of modules (convenience). **Not** a third rules source — expands to baseline + modules. |
|
||
| **Configuration** | Baseline + resolved module list = what is actually played. |
|
||
| **Composition** | At most **one module per aspect**. Missing aspects use `default_module`. |
|
||
|
||
**Independence rule:** a module may only declare rules on its **own aspect**. Cross-aspect effects belong in a **profile** (explicit combo) or a new aspect — never silent coupling inside one module.
|
||
|
||
**Legacy experiments** (`editions/experiments/h1-…`, `h2-…`) remain on disk as measured packages; they map to **profiles**. Prefer `module_id` / `profile_id` going forward.
|
||
|
||
**Synonym:** older docs said *axis* for aspect. Machine field is `aspect:`.
|
||
|
||
---
|
||
|
||
## Aspects with modules (registered)
|
||
|
||
| Aspect | Default | Other modules |
|
||
|--------|---------|----------------|
|
||
| `problem_stress` | `none` | `flat_any_open` (H1-A, reject), `scoped` (H2, keep) |
|
||
| `attack_relief` | `none` | `self_soothe_ge4` (H1-B) |
|
||
| `end_condition` | `fixed_rounds_5` | `hybrid_clear_collapse` (**proposed**) |
|
||
| `problem_deal` | `fixed_setup` | `pressure_deck` (**proposed**) |
|
||
|
||
Many other aspects exist but are **fixed in r0** until a competing design appears (see ASPECTS.md § full map).
|
||
|
||
---
|
||
|
||
## Selection (clay-borg / trials)
|
||
|
||
### Preferred API
|
||
|
||
```yaml
|
||
baseline: ground-darvo-r0
|
||
modules:
|
||
- problem_stress.scoped
|
||
- end_condition.hybrid_clear_collapse # when implemented
|
||
# other aspects → defaults
|
||
```
|
||
|
||
Or:
|
||
|
||
```yaml
|
||
profile: h2
|
||
# expands to modules: [problem_stress.scoped]
|
||
```
|
||
|
||
Or multi-aspect:
|
||
|
||
```yaml
|
||
profile: scoped_plus_attack_soothe
|
||
# problem_stress.scoped + attack_relief.self_soothe_ge4
|
||
```
|
||
|
||
### Validation
|
||
|
||
1. Every `module_id` exists and `selectable: true`.
|
||
2. No two modules share the same **aspect**.
|
||
3. `status: proposed` modules may be selected only if the host declares `allow_proposed: true` (kernel may no-op or refuse).
|
||
4. State / recordings must store the **resolved module list** (and baseline id), not only a legacy experiment string — so A/B names the **point in design space**.
|
||
|
||
### Implementation
|
||
|
||
- Baseline CSVs: vendor as today.
|
||
- Each module: apply `rules_delta` + optional `data_overlays` from its `path`.
|
||
- Apply modules in **aspect order** listed in `catalog.yaml` `aspects:` (stable, documented).
|
||
- Conflict: refuse composition rather than last-write-wins.
|
||
|
||
---
|
||
|
||
## Profiles (named combos)
|
||
|
||
| profile_id | modules | note |
|
||
|------------|---------|------|
|
||
| `baseline` | (defaults) | Pure r0 |
|
||
| `h1` | flat + attack soothe | Legacy H1; reject-as-baseline |
|
||
| `h2` | scoped | Legacy H2; keep-as-experiment |
|
||
| `scoped_plus_attack_soothe` | scoped + soothe | Unmeasured combo |
|
||
| `scoped_plus_hybrid_end` | scoped + hybrid end | Needs kernel for end |
|
||
| `scoped_plus_pressure_deck` | scoped + pressure deck | Needs kernel for deal |
|
||
|
||
---
|
||
|
||
## Adding a module (checklist)
|
||
|
||
1. Confirm the **aspect** exists in [ASPECTS.md](ASPECTS.md); add the aspect first if needed.
|
||
2. Create `editions/modules/<aspect>/<slug>/` with `MODULE.md` and, if non-default, `rules_delta.yaml` (+ CSV overlays if needed).
|
||
3. Register under `modules:` with `aspect`, `path`, `status`, `decision`.
|
||
4. Optionally add a **profile** that includes it alone and/or with other modules.
|
||
5. Message clay-borg: `module_id`, aspect, delta path, compose examples.
|
||
6. Measure **alone** first when possible; then measure interesting **profiles**.
|
||
7. Update `utility_estimate` / `decision` per module (and per profile if combo-specific).
|
||
|
||
### What must not happen
|
||
|
||
- Silent edit of frozen baseline columns inside `ground-darvo-r0`.
|
||
- A new mega-experiment that re-bundles three aspects into one non-decomposable id (use a profile instead).
|
||
- Modules that hard-require another aspect’s module without documenting a profile.
|
||
|
||
---
|
||
|
||
## Git
|
||
|
||
**main + catalog** is discovery; commits pin digests; branches optional for WIP. Modules live as directories on `main`.
|
||
|
||
---
|
||
|
||
## Legacy map
|
||
|
||
| Old experiment | Prefer |
|
||
|----------------|--------|
|
||
| `h1-problem-stress` | profile `h1` or modules `problem_stress.flat_any_open` + `attack_relief.self_soothe_ge4` |
|
||
| `h2-scoped-problem-stress` | profile `h2` or module `problem_stress.scoped` |
|