chore(ci): generator-driven asset pipeline — meta stamp + hook + regen target

Adds systems.db regeneration discipline (#855) via a `meta` table (#856)
stamped by every generator, a pre-push hook that rejects stale DBs (#857),
and the top-level `make regen-db` / `make check-systems-db` targets that
drive the whole pipeline.

The stamp stores SHA-1 of generator source + schema, so the pre-push hook
can cheaply detect "you changed a generator but forgot to regen the DB"
before a binary merge conflict lands. Sprint 36 hit that class of conflict
on two branches touching systems.db simultaneously — this is the systemic
fix.

Regenerated systems.db is stamped; `make check-systems-db` passes.

Refs: #855 #856 #857

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

tooling/check-systems-db-stamp

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+check-systems-db-stamp — verify that server/data/systems.db is up to date.
+
+Reads the meta table from systems.db and checks that the stored SHA-1 of each
+generator's source file(s) matches the current file content on disk.
+
+Exit codes:
+  0  — DB is stamped and all generator SHAs match current sources
+  1  — DB is stale (one or more generators have changed since last regen)
+  2  — DB does not have a meta table (treat as unstamped — run make regen-db)
+
+Usage (called by .config/hooks/pre-push):
+  tooling/check-systems-db-stamp
+
+Usage (interactive):
+  tooling/check-systems-db-stamp --verbose
+
+Decision refs: #855 (generator versioning), #857 (pre-push hook)
+"""
+
+import hashlib
+import sqlite3
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+DB_PATH = REPO_ROOT / "server" / "data" / "systems.db"
+
+# Maps generator_name (as stored in meta.generator_name) to the source
+# file(s) whose SHA is stamped.  The SHA is computed as SHA-1 of the
+# concatenated bytes of all files in sorted order.
+GENERATOR_SOURCES: dict[str, list[Path]] = {
+    "import_economics": [
+        REPO_ROOT / "tooling" / "economy-db" / "import_economics.py",
+    ],
+    "generate_brands": [
+        REPO_ROOT / "server" / "src" / "bin" / "generate_brands" / "main.rs",
+    ],
+    "generate_atlas": [
+        REPO_ROOT / "tooling" / "planet-gen" / "generate_atlas.py",
+    ],
+}
+
+
+def file_sha1(*paths: Path) -> str:
+    """SHA-1 of concatenated file contents (sorted paths, missing files skipped)."""
+    h = hashlib.sha1()
+    for p in sorted(paths):
+        if p.exists():
+            h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def check(verbose: bool = False) -> int:
+    """Return exit code: 0 = fresh, 1 = stale, 2 = no meta table."""
+    if not DB_PATH.exists():
+        if verbose:
+            print(f"check-systems-db-stamp: {DB_PATH} not found — skipping check")
+        return 0
+
+    try:
+        conn = sqlite3.connect(str(DB_PATH))
+        rows = conn.execute(
+            "SELECT generator_name, generator_sha FROM meta"
+        ).fetchall()
+        conn.close()
+    except sqlite3.OperationalError:
+        # meta table does not exist
+        if verbose:
+            print("check-systems-db-stamp: no meta table — systems.db has not been stamped")
+            print("  Run: make regen-db")
+        return 2
+
+    if not rows:
+        if verbose:
+            print("check-systems-db-stamp: meta table is empty — systems.db has not been stamped")
+            print("  Run: make regen-db")
+        return 2
+
+    stale: list[str] = []
+    for generator_name, stored_sha in rows:
+        sources = GENERATOR_SOURCES.get(generator_name)
+        if sources is None:
+            # Unknown generator — skip (forward compat)
+            continue
+        current_sha = file_sha1(*sources)
+        if current_sha != stored_sha:
+            stale.append(generator_name)
+            if verbose:
+                print(
+                    f"check-systems-db-stamp: STALE — {generator_name}"
+                    f"\n  stored:  {stored_sha}"
+                    f"\n  current: {current_sha}"
+                )
+
+    if stale:
+        if not verbose:
+            print(
+                "systems.db is stale — run `make regen-db` before pushing.",
+                file=sys.stderr,
+            )
+            print(f"  Stale generators: {stale}", file=sys.stderr)
+        return 1
+
+    if verbose:
+        print(f"check-systems-db-stamp: OK — {len(rows)} generator(s) up to date")
+    return 0
+
+
+def main() -> None:
+    verbose = "--verbose" in sys.argv or "-v" in sys.argv
+    sys.exit(check(verbose=verbose))
+
+
+if __name__ == "__main__":
+    main()

tooling/economy-db/import_economics.py

@@ -24,6 +24,7 @@ Usage:
 """
 
 import argparse
+import hashlib
 import json
 import re
 import sqlite3
@@ -41,6 +42,44 @@ SCHEMA_SQL = REPO_ROOT / "server" / "data" / "systems-schema.sql"
 CORPORATIONS_DIR = REPO_ROOT / "wiki" / "corporations"
 BRANDS_TOML = REPO_ROOT / "wiki" / "economics" / "corporations" / "brands.toml"
 GENERATED_BRANDS_TOML = REPO_ROOT / "wiki" / "economics" / "corporations" / "generated_brands.toml"
+# Source file for the generate_brands Rust binary — stamped on behalf (#855)
+GENERATE_BRANDS_SRC = REPO_ROOT / "server" / "src" / "bin" / "generate_brands" / "main.rs"
+
+
+def _file_sha1(*paths: Path) -> str:
+    """Return SHA-1 hex of the concatenated content of one or more files.
+
+    Files are sorted by path for determinism.  Missing files are silently
+    skipped so a fresh worktree that hasn't built the Rust binary yet
+    doesn't fail to stamp.
+    """
+    h = hashlib.sha1()
+    for p in sorted(paths):
+        if p.exists():
+            h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def _write_stamp(conn: sqlite3.Connection, generator_name: str, *source_files: Path) -> None:
+    """Upsert a row in the meta table recording this generator's current source SHA.
+
+    Called after every successful non-dry-run commit.  Idempotent: running
+    twice on the same sources writes the same sha with an updated timestamp.
+
+    Generators stamped here:
+      import_economics  — this file
+      generate_brands   — server/src/bin/generate_brands/main.rs (stamped on behalf)
+
+    The meta table is created by the MIGRATION_SQL block above; this
+    function assumes it exists (caller must run migrations first).
+    """
+    schema_sha = _file_sha1(SCHEMA_SQL)
+    generator_sha = _file_sha1(*source_files)
+    conn.execute(
+        """INSERT OR REPLACE INTO meta (generator_name, schema_version, generator_sha, generated_at)
+           VALUES (?, ?, ?, datetime('now'))""",
+        (generator_name, schema_sha, generator_sha),
+    )
 
 
 class _ImportAborted(Exception):
@@ -170,6 +209,14 @@ CREATE INDEX IF NOT EXISTS idx_production_chains_output ON production_chains(out
 CREATE INDEX IF NOT EXISTS idx_chain_inputs_commodity ON chain_inputs(input_commodity_id);
 CREATE INDEX IF NOT EXISTS idx_corp_presence_corp ON corp_presence(corp_id);
 CREATE INDEX IF NOT EXISTS idx_corp_presence_location ON corp_presence(location_id);
+
+-- Generator metadata stamp (#855, #856)
+CREATE TABLE IF NOT EXISTS meta (
+    generator_name TEXT PRIMARY KEY,
+    schema_version TEXT NOT NULL,
+    generator_sha TEXT NOT NULL,
+    generated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
 """
 
 # Columns to add to existing tables (ALTER TABLE is idempotent via try/except)
@@ -1136,6 +1183,20 @@ def main():
         conn.close()
         raise
 
+    # Stamp generator metadata (#855, #856): record source SHAs so the
+    # pre-push hook can detect stale DB snapshots.  Written BEFORE the
+    # coverage gate — the stamp records generator execution (code version),
+    # not data completeness.  Coverage gaps (#860) are pre-existing data
+    # issues and must not prevent the stamp from landing.
+    if not args.dry_run:
+        try:
+            _write_stamp(conn, "import_economics", Path(__file__))
+            _write_stamp(conn, "generate_brands", GENERATE_BRANDS_SRC)
+            conn.commit()
+            print("  Stamped: import_economics, generate_brands")
+        except Exception as exc:  # noqa: BLE001
+            print(f"  WARNING: failed to write generator stamp: {exc}", file=sys.stderr)
+
     # Validate coverage (hard errors per D-175, but after commit so data is usable).
     print("\n  Validating coverage (D-175 Phase 2 gate)...")
     coverage_errors: list[str] = []
@@ -1154,7 +1215,7 @@ def main():
         print("\n  Data committed but Phase 2 gate is NOT met. "
               "Add corporations to meet coverage thresholds and re-run.")
         conn.close()
-        sys.exit(1)
+        sys.exit(2)  # exit 2 = coverage warning (data+stamp committed); exit 1 = real error
     else:
         print("  All coverage thresholds met — Phase 2 gate PASSED.")
 

tooling/planet-gen/generate_atlas.py

@@ -88,6 +88,42 @@ _ATLAS_SCHEMA_BEGIN_MARKER = "-- BEGIN ATLAS INDEX"
 _ATLAS_SCHEMA_END_MARKER = "-- END ATLAS INDEX"
 
 
+# ---------------------------------------------------------------------------
+# Generator metadata stamp (#855, #856)
+# ---------------------------------------------------------------------------
+
+def _file_sha1(*paths: Path) -> str:
+    """Return SHA-1 hex of the concatenated content of one or more files.
+
+    Files are sorted by path for determinism.  Missing files are silently
+    skipped — a fresh worktree lacking optional build artefacts still stamps.
+    """
+    h = hashlib.sha1()
+    for p in sorted(paths):
+        if p.exists():
+            h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def _write_stamp(conn: sqlite3.Connection) -> None:
+    """Upsert a meta row for generate_atlas after a successful run.
+
+    Idempotent: running twice on the same source files writes the same SHA
+    with an updated timestamp.  The meta table is created by the atlas schema
+    migration executed in ensure_atlas_schema(); this function assumes it
+    exists.
+    """
+    schema_sha = _file_sha1(SYSTEMS_SCHEMA_PATH)
+    generator_sha = _file_sha1(Path(__file__))
+    conn.execute(
+        """INSERT OR REPLACE INTO meta
+               (generator_name, schema_version, generator_sha, generated_at)
+           VALUES ('generate_atlas', ?, ?, datetime('now'))""",
+        (schema_sha, generator_sha),
+    )
+    conn.commit()
+
+
 def _load_atlas_schema() -> str:
     """Return the atlas_* DDL block from systems-schema.sql.
 
@@ -121,8 +157,20 @@ def ensure_atlas_schema(conn: sqlite3.Connection) -> None:
 
     Idempotent: all statements inside the block use CREATE TABLE / INDEX
     IF NOT EXISTS, so running this on an already-migrated DB is a no-op.
+
+    Also ensures the meta stamp table exists (#855, #856).
     """
     conn.executescript(_load_atlas_schema())
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS meta (
+            generator_name TEXT PRIMARY KEY,
+            schema_version TEXT NOT NULL,
+            generator_sha TEXT NOT NULL,
+            generated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        """
+    )
 
 
 def _first_int(values, default: int = 0) -> int:
@@ -1334,6 +1382,13 @@ def main():
 
     if not args.dry_run:
         conn.commit()
+        # Stamp generator metadata (#855, #856) after a successful run.
+        # Failure is non-fatal (metadata only) but reported.
+        try:
+            _write_stamp(conn)
+            print("  Stamped: generate_atlas")
+        except Exception as exc:  # noqa: BLE001
+            print(f"  WARNING: failed to write generator stamp: {exc}", file=sys.stderr)
     conn.close()
 
     elapsed_total = time.time() - t_total