chore(meta): docs/build sweep + tooling test gate (T-1069, T-1066)

- make test-tooling: planet-gen determinism guard + import_economics
  --dry-run, wired into pre-push on TOOLING_CHANGED; ruff widened to
  E4/E7/E9/F/W (90 safe auto-fixes applied; E402/E702/F841 ignored with
  documented counts)
- one-generator reality fixed in DEVOPS.md, asset-pipeline rule, CLAUDE.md
  (import_economics sole generator since #951/D-223); dead check-protocol
  target deleted; DEVOPS hook/config sections rewritten from the actual
  hook sources; team-patterns gate description updated (client+tooling)
- project.yaml: 0.2.0 → 0.4.0 per the 0.{phase}.{n} scheme, description
  refreshed from the v0.1 Sova narration to cascade reality
- stale comment sweep: voxel.rs stub claims (all 8 families implemented),
  cascade.rs TODO recited to T-1044, main.rs D-192 handshake claim,
  relationships.rs/chunk_streaming.rs version targets → phase language
- gitignore: client/settings.db* e2e-run artifacts

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-12 16:22:55 +02:00
co-authored by Claude Fable 5
parent 0bd895fcac
commit 346d87df7a
47 changed files with 280 additions and 180 deletions
+19 -10
View File
@@ -11,7 +11,8 @@ client can ship it without a build step, but **it is never the source of truth**
> **Edit sources, not the DB.**
If you need to change economics data, modify the TOML/JSON source files.
If you need to change atlas markers, modify the `markers.json` files.
If you need to change the atlas city-name pool, modify the names-only
`markers.json` files (D-223 — they carry no geometry or population).
Never run `UPDATE` or `INSERT` directly on `server/data/systems.db` outside of a
migration — those changes will be silently overwritten by the next `make regen-db`.
@@ -19,12 +20,12 @@ migration — those changes will be silently overwritten by the next `make regen
## What produces systems.db
Two generators write to `systems.db`:
| Generator | Command | Source files (all contribute to the meta stamp SHA) |
|-----------|---------|--------------|
| `import_economics` | `python3 tooling/economy-db/import_economics.py` | `tooling/economy-db/import_economics.py` + the Rust brand binary sources it invokes: `server/src/bin/generate_brands/main.rs`, `server/src/bin/generate_brands/names.rs`, `tooling/generate-brands` + shared `tooling/schema_version.py` |
| `generate_atlas` | `python3 tooling/planet-gen/generate_atlas.py --seed 42` | `tooling/planet-gen/generate_atlas.py` + shared `tooling/schema_version.py` |
**One generator** writes to `systems.db`: `import_economics`
(`python3 tooling/economy-db/import_economics.py`, run via `make regen-db`).
The former atlas geometry generator (`generate_atlas`) was retired in #951
(D-223); `import_economics` now also owns the atlas index — it loads the
names-only `markers.json` city pool into `atlas_city_names` and empties the
geometry tables (the server cascade fills them, Phase 4).
`import_economics` shells out to the Rust `generate_brands` binary as its first
step to refresh `wiki/economics/corporations/generated_brands.toml`, then reads
@@ -33,17 +34,25 @@ of the Python importer, not an independent generator — changes to its source
invalidate the `import_economics` meta stamp even though the Python file
itself didn't change.
`make regen-db` runs both in the correct order (economics first, atlas second).
The full set of source files contributing to the meta stamp SHA (the Python
importer, the Rust brand binary sources, `tooling/schema_version.py`, and the
authored economics TOMLs) is registered in the `GENERATOR_SOURCES` dict at the
top of `tooling/check-systems-db-stamp` — that dict is the single source of
truth, mirrored by `IMPORT_ECONOMICS_SOURCES` in `import_economics.py`.
The surviving planet-gen importers (`import_heightmaps`,
`import_province_boundaries`) are one-time build imports baked into the
committed DB — not part of `make regen-db`, and intentionally not stamped.
---
## The meta table stamp (T-855, T-856)
After every successful non-dry-run, each generator writes a row to the `meta` table:
After every successful non-dry-run, the generator writes a row to the `meta` table:
```sql
CREATE TABLE meta (
generator_name TEXT PRIMARY KEY, -- 'import_economics' | 'generate_atlas'
generator_name TEXT PRIMARY KEY, -- 'import_economics' (sole generator since #951/D-223)
schema_version TEXT NOT NULL, -- monotonic semver string (e.g. "1.0.0") — see T-888
schema_sha TEXT, -- SHA-1 of server/data/systems-schema.sql (tamper detection)
generator_sha TEXT NOT NULL, -- SHA-1 of the generator source file(s)
+6 -4
View File
@@ -34,10 +34,12 @@ When leading a team (workshop, batch, or any multi-agent session):
## Agent verification — don't duplicate the push gate
The pre-push hook (`.config/hooks/pre-push`) is the source of truth for Rust
verification and **runs on every push the lead makes** when `server/` changed:
`cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test`
(plus `cargo deny`, ruff, JSON validation, systems.db stamp). There is no CI (no
The pre-push hook (`.config/hooks/pre-push`) is the source of truth for
verification and **runs on every push the lead makes**: when `server/` changed —
`cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test`;
when `client/` changed — the full gdUnit4 suite via `tests/run-godot` (T-1065);
when `tooling/` changed — `make test-tooling` (plus `cargo deny`, ruff, JSON
validation, systems.db stamp). There is no CI (no
`.gitea`/`.github`/`.forgejo` workflows) — the push gate is the only automatic
verification, so it is deliberately comprehensive.