|
22 | 22 | ; understand a MUST, read INTENT first. |
23 | 23 | ; - TRUST: The "ask-before-touching" section in INTENT maps directly |
24 | 24 | ; to TRUST.trust-deny for the most sensitive areas. |
25 | | -; - ADJUST: INTENT's anti-purpose should include "this software is |
26 | | -; NOT only for users with perfect vision/hearing/mobility." |
| 25 | +; - ADJUST: INTENT's anti-purpose includes "this software is NOT only |
| 26 | +; for users with perfect vision/hearing/mobility." |
27 | 27 | ; - DUST: When INTENT changes (repo pivots), related DUST entries |
28 | 28 | ; should be created for the abandoned direction. |
29 | 29 | ; |
|
35 | 35 |
|
36 | 36 | ; === Purpose (what this repo IS) === |
37 | 37 | (purpose |
38 | | - "{{ONE_PARAGRAPH_PURPOSE}}" |
| 38 | + "game-server-admin (GSA) is a universal game-server probe, configuration-management, and administration tool. It fingerprints running game servers across 8 wire protocols, extracts their on-disk configuration out of 8 formats (XML/INI/JSON/ENV/YAML/TOML/Lua/KV) into provenance-tracked A2ML, stores probe data and config octads in a dedicated VeriSimDB instance, and drives lifecycle actions (start/stop/restart/logs, schema-driven provisioning, Steam file staging) through a Zig FFI core. That core is exposed both to a Gossamer webview GUI (Ephapax .eph panels) and a standalone gsa CLI. An Idris2 ABI layer formally specifies the C-ABI seam — memory layout and the 13 result codes — that the GUI and CLI depend on." |
39 | 39 | ) |
40 | 40 |
|
41 | 41 | ; === Anti-Purpose (what this repo is NOT — prevents scope creep) === |
42 | 42 | (anti-purpose |
43 | | - "{{ONE_PARAGRAPH_ANTI_PURPOSE}}" |
44 | | - ; Examples: |
45 | | - ; "This is NOT a general-purpose database — it solves one specific problem." |
46 | | - ; "This is NOT a framework — it is a library with a focused API." |
47 | | - ; "This does NOT handle authentication — that is delegated to [other repo]." |
| 43 | + "GSA is NOT a game client, game launcher, or matchmaking/lobby service — it administers servers, it does not play or broker games. It is NOT a general-purpose configuration database (persistence is delegated to VeriSimDB), NOT a general TTS/notification platform (voice alerting is delegated to Groove via .well-known), and NOT a GUI toolkit (the webview shell is Gossamer). It does not ship its own storage engine, auth system, or container runtime — those are external dependencies. It is NOT only for sighted, able-bodied operators on modern hardware: every surface (GUI, CLI, docs) must satisfy ADJUST / WCAG-2.2-AA." |
48 | 44 | ) |
49 | 45 |
|
50 | 46 | ; === Key Architectural Decisions That Must Not Be Reversed === |
51 | 47 | (architectural-invariants |
52 | | - ; *REMINDER: List the foundational decisions* |
53 | | - ; ("Idris2 for ABI definitions — dependent types prove interface correctness") |
54 | | - ; ("Zig for FFI — zero-cost C ABI compatibility") |
55 | | - ; ("Elixir for supervision — OTP fault tolerance") |
| 48 | + ("Idris2 for the ABI — dependent types specify and prove the C-ABI layout and result-code contract; no believe_me / assert_total") |
| 49 | + ("Zig for the FFI bridge — zero-cost C ABI; every export is prefixed gossamer_gsa_ and uses pub export fn ... callconv(.c)") |
| 50 | + ("The 13 result codes are contractual — the Zig FFI MUST match src/interface/abi/Types.idr") |
| 51 | + ("Config is emitted as A2ML with full provenance; secrets are redacted as [REDACTED] in A2ML output and octad JSON") |
| 52 | + ("Backing store is VeriSimDB on dedicated instances — main on 8090 (config/probe/octads), backup on 8091 (save metadata); never co-located with the VeriSimDB source repo") |
| 53 | + ("GUI is a Gossamer webview driven by Ephapax .eph; the CLI is the standalone gsa binary — both call the same FFI exports") |
| 54 | + ("Containers use Chainguard Wolfi base, Podman, Containerfile, and selur-compose — never Docker / docker-compose") |
56 | 55 | ) |
57 | 56 |
|
58 | 57 | ; === Sensitive Areas (if in doubt, ask) === |
59 | 58 | (ask-before-touching |
60 | | - ; *REMINDER: List areas where LLMs should check before modifying* |
61 | | - ; "src/abi/ — formal proofs, changes require re-verification" |
62 | | - ; "ffi/zig/ — C ABI boundary, changes affect all language bindings" |
63 | | - ; ".machine_readable/ — checkpoint files, format is specified" |
| 59 | + "src/interface/abi/ — Idris2 formal proofs (e.g. alignUpCeil / alignUpCeilIsMultiple); changes require re-verification" |
| 60 | + "the gossamer_gsa_ C-ABI surface and the 13 result codes — changes ripple to the GUI, the CLI, and every binding" |
| 61 | + "src/interface/ffi/src/server_actions.zig — command construction; argv-slice + -- discipline prevents shell injection" |
| 62 | + "LICENSE and per-file SPDX headers — AGPL-3.0-or-later for code; legal implications" |
| 63 | + ".machine_readable/ — checkpoint, contractile, and policy files; canonical and format-specified" |
64 | 64 | ) |
65 | 65 |
|
66 | 66 | ; === Ecosystem Position === |
67 | 67 | (ecosystem |
68 | | - (belongs-to "{{MONOREPO_OR_STANDALONE}}") |
69 | | - (depends-on ("{{DEP1}}" "{{DEP2}}")) |
70 | | - (depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}")) |
| 68 | + (belongs-to "standalone repo within the hyperpolymath ecosystem") |
| 69 | + (depends-on ("Gossamer (webview GUI runtime)" "VeriSimDB (backing store)" "Idris2 0.7.0 (ABI)" "Zig 0.15.2 (FFI)" "Groove (voice alerting)" "Podman + Chainguard Wolfi (containers)")) |
| 70 | + (depended-on-by ("game-server operators (humans, via GUI and CLI)" "Groove alert consumers")) |
71 | 71 | ) |
72 | 72 | ) |
0 commit comments