diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index e499b51..ceb80a8 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -100,7 +100,7 @@ VeriSimDB (8-modality octads) -- container/verisimdb/ - **Cross-language ABI**: `abi_layout.zig` asserts (at compile time + `zig build test`) that the 8 `extern struct`s match the proven `Layout.idr` offsets/sizes; `abi_serde.zig` implements the offset readers/emitters so those offsets are a live runtime contract (was the open HIGH proof item) - **VeriSimDB**: Main on 8090 (built, running), backup on 8091 (game saves) - **Container**: Containerfile wired with real Zig build, entrypoint.sh execs gsa -- **Guix**: guix.scm has real build/install phases (flake.nix removed in the nix→guix migration) +- **Guix**: guix.scm has real build/install phases (flake.guix removed in the guix→guix migration) - **Release CI**: release.yml builds Zig, packages tarball, uploads artifacts - **Groove**: Full manifest with probe/config/drift/alert capabilities - **Icon**: SVG + 256px PNG in assets/ diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5636537..c6bb67b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,8 +2,8 @@ git clone https://github/hyperpolymath/game-server-admin.git cd game-server-admin -# Using Nix (recommended for reproducibility) -nix develop +# Using Guix (recommended for reproducibility) +guix develop # Or using toolbox/distrobox toolbox create game-server-admin-dev @@ -45,7 +45,7 @@ game-server-admin/ ├── MAINTAINERS.md ├── README.adoc ├── SECURITY.md -├── flake.nix # Nix flake — fallback (Perimeter 1) +├── flake.guix # Guix flake — fallback (Perimeter 1) ├── guix.scm # Guix package — primary (Perimeter 1) └── Justfile # Task runner (Perimeter 1) ``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 97b7994..c52883a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -33,7 +33,7 @@ ## Banned Languages -- No TypeScript (use ReScript) +- No TypeScript (use AffineScript) - No Node.js / npm / bun (use Deno) - No Go (use Rust) - No Python (use Julia or Rust) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d5cd4e9..045cb8f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -41,8 +41,8 @@ updates: schedule: interval: "weekly" - # Nix flakes - - package-ecosystem: "nix" + # Guix flakes + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index cc62f6c..f6e8fcf 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -3,7 +3,7 @@ # in hyperpolymath/standards instead of carrying per-repo copies. # # Replaces the per-repo governance scaffolding removed in the same commit: -# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, +# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, # security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml, # workflow-linter.yml # diff --git a/.machine_readable/ai/PLACEHOLDERS.adoc b/.machine_readable/ai/PLACEHOLDERS.adoc index f5466a2..872d07b 100644 --- a/.machine_readable/ai/PLACEHOLDERS.adoc +++ b/.machine_readable/ai/PLACEHOLDERS.adoc @@ -48,8 +48,8 @@ sed -i "s/2026-03-22/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-22' .) | Placeholder | Description | Example | Files | |---|---|---|---| -| `game-server-admin` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `Universal game server probe, config management, and administration via Gossamer + VeriSimDB` | One-line description | `A tool for X` | flake.nix | +| `game-server-admin` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.guix, devcontainer.json | +| `Universal game server probe, config management, and administration via Gossamer + VeriSimDB` | One-line description | `A tool for X` | flake.guix | | `GameServerAdmin` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/interface/abi/*.idr, src/interface/ffi/*.zig | | `game-server-admin` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, src/interface/ffi/*.zig | | `game-server-admin` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | @@ -133,7 +133,7 @@ After replacing all placeholders, verify none remain: ```bash grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='Justfile' --include='*.guix' --include='*.toml' --include='*.yml' \ --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ --include='*.json' --include='Containerfile' --include='dep5' \ | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' diff --git a/.machine_readable/descriptiles/META.a2ml b/.machine_readable/descriptiles/META.a2ml index 4aa7b0f..ffca186 100644 --- a/.machine_readable/descriptiles/META.a2ml +++ b/.machine_readable/descriptiles/META.a2ml @@ -26,7 +26,7 @@ author = "Jonathan D.A. Jewell (hyperpolymath)" build-tool = "just" container-runtime = "podman" ci-platform = "github-actions" -package-manager = "guix" # guix | nix | cargo | mix +package-manager = "guix" # guix | guix | cargo | mix [maintenance-axes] scoping-first = true @@ -50,7 +50,7 @@ perfective-source = "axis-1 honest state after corrective/adaptive updates" [axis-3-audit-rules] audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed" compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks" -drift-risk-example = "single exception broadening into policy violation (e.g. ReScript->TypeScript spread)" +drift-risk-example = "single exception broadening into policy violation (e.g. AffineScript->TypeScript spread)" effects-evidence = "benchmark execution/results and maintainer status dialogue/review" [design-rationale] diff --git a/.machine_readable/descriptiles/STATE.a2ml b/.machine_readable/descriptiles/STATE.a2ml index 2accc16..fbc4595 100644 --- a/.machine_readable/descriptiles/STATE.a2ml +++ b/.machine_readable/descriptiles/STATE.a2ml @@ -62,12 +62,12 @@ sessions = [ { date = "2026-07-07b", summary = "Chain-test truth pass. VERIFIED the 'Ephapax parser gaps' v1.0 gate is STALE: ephapax 0.1.0 (γ-languages/ephapax) passes both step-6 probe programs (let and let! linear binding) — the parser caught up since 2026-03. Ran the full Gossamer chain test: 17/18, sole failure = libgossamer.so unbuilt in this environment (gossamer FFI needs gtk+-3.0 + webkit2gtk-4.1 dev libraries; sudo unavailable to this session — owner installs, then zig build in gossamer/src/interface/ffi). Fixed the dead /var/mnt/eclipse default paths in gossamer-integration-test.sh (now REPOS_ROOT=~/developer/repos, env-overridable) and rewrote its stale known-gaps messaging. Corrected the parser-gaps claims in CLAUDE.md, ROADMAP, STATE. Also confirmed standards#472 (merged 2026-07-07) fixed the Secret Scanner at source for standards itself + canonical example — the ~281-repo wrapper sweep remains the estate-level remainder." }, { date = "2026-03-22", summary = "Created repo — 412 files, 28901 lines. Full ABI/FFI/Core/GUI/Profiles/Clades/VeriSimDB. Pushed to GitHub + GitLab. PanLL integration committed." }, { date = "2026-03-29", summary = "Marathon session: Zig 0.15.2 full compat (all 9 FFI modules incl. cli.zig + groove_client), 24 exported symbols via comptime hints, standalone CLI executable (gsa binary — status/probe/profiles/version), VeriSimDB health check fix (healthy not ok), VeriSimDB container built/running (8090), backup instance (8091), e2e test 8/8 against live VeriSimDB, StorageRegenerator in verisimdb repo (real OctadStore, 68 tests), Lua nested table parser (8 levels), 17 enriched game clades, icon SVG+PNG, Gossamer integration test 23/25, Ephapax parser extended (module/--comments/qualified imports/linear types/const bindings), GSA Containerfile wired with Zig build, Justfile run/gui recipes wired to real binary, all docs reconciled." }, - { date = "2026-03-29", summary = "Completion session: filled all template TODOs in Containerfile (real Zig build), entrypoint.sh (exec gsa), flake.nix (Zig devshell + package), guix.scm (Zig build/check/install phases), Justfile (fmt/lint/deps/install recipes), release.yml (real build + artifact upload). Enriched Groove manifest with probe/config/drift/alert capabilities, produces field, VeriSimDB port map, and panel list. Updated STATE.a2ml to 100%." }, + { date = "2026-03-29", summary = "Completion session: filled all template TODOs in Containerfile (real Zig build), entrypoint.sh (exec gsa), flake.guix (Zig devshell + package), guix.scm (Zig build/check/install phases), Justfile (fmt/lint/deps/install recipes), release.yml (real build + artifact upload). Enriched Groove manifest with probe/config/drift/alert capabilities, produces field, VeriSimDB port map, and panel list. Updated STATE.a2ml to 100%." }, { date = "2026-04-03", summary = "Blitz session: 112 Zig tests (was ~40). 30 new unit tests across server_actions (8 security/injection), config_extract (12 parser edge cases + detectFormat regression), groove_client (4 overflow/truncation), a2ml_emit (7 diff/redaction). Fixed 7 pre-existing Zig 0.15.2 compat bugs: std.json.stringify→json.fmt, std.fs.exists→fileExists helper, createFile sig, broken multiline string, stack-returning helpers (UB), missing catch, detectFormat [n...] false positive. Idris2 Layout.idr: replaced postulate alignUpProducesAligned with constructive proof (alignUpCeil + alignUpCeilIsMultiple via IsMultipleOf witness). Removed fake fuzz placeholder. All docs updated." }, { date = "2026-04-04", summary = "CryoFall server + Steam integration session: deployed CryoFall container stack (Containerfile, entrypoint.sh, Settings.xml, gsa-cryofall.container Quadlet, backup.sh, manifest.toml). Schema-driven provisioner (scripts/provision-server.sh — 9-step: preflight→build→volumes→firewall→quadlet→start→verify→VeriSimDB→report). Steam integration: steam_client.zig (resolveVanityUrl, getPlayerSummary, checkOwnership — 3 C ABI exports, 5 tests), wired into main.zig+cli.zig as 'gsa steam resolve/player'. Fire-and-forget wizard (scripts/wizard.sh — 7 steps, interactive+unattended). Self-healing watchdog (scripts/self-heal.sh — container/port/disk/XML checks, auto-restart, Groove alerts). SteamCMD stage script (scripts/steam-stage.sh — auth token persistence, interactive Steam Guard, rsync to volume/remote). Cloudflare: cryofall.jewell.nexus → 209.42.26.106 grey-cloud DNS live. Verpex: UDP 6000+6001 firewall opened, container image built. Operator Steam IDs resolved: pengie5=76561198149527024, hyperpolymath=76561198141836018. Blocking: game files need authenticated SteamCMD stage (B4)." }, { date = "2026-04-03b", summary = "Security hardening: replaced 427 AGPL-3.0-or-later headers with MPL-2.0, replaced LICENSE with PMPL text. Fixed critical vuln (executeSSH shell injection — refactored to argv slice + -- separator). Fixed temp-file TOCTOU in gossamer-integration-test.sh (mktemp). Removed dangling-ref getWriter function. Replaced hardcoded test credentials. Added escapeXml to fli-gauge.js, escapeHtml+data-tip escaping to fli-tooltip.js, DOM node clone in fli-editable.js cancelEdit. Eliminated all 8 @ptrCast calls across FFI layer (string literals + [N:0]u8 sentinel buffers). Filled K9 template-hunt.k9.ncl TODO placeholders with GSA deployment content. All 111 Zig tests pass. panic-attack: 0 weak points (was 21)." }, { date = "2026-04-04b", summary = "Nexus Setup GUI panel: full 7-step graphical wizard added as nav item 2 in Gossamer GUI (between Server Browser and Config Editor). src/gui/panels/nexus-setup/panel.html — profile card grid, Steam vanity→Steam64 resolution inline, typed server config form (toggles/sliders/text), SSH deployment target, Steam credentials + live terminal for staging, provisioner live terminal, verify+report with connect string/watchdog CTA. src/gui/panels/nexus-setup/nexus-setup.eph — IPC contract docs. src/core/Bridge.eph — 5 new handlers: handleSteamResolveVanity, handleSteamPlayerInfo, handleNexusStageFiles, handleNexusProvision, handleNexusVerify. src/gui/host.html — wired at 4 locations (nav, container, panels array, switch case + FLI traits + status list). Operator slots pre-filled: pengie5 + hyperpolymath. Committed f26deda, pushed to GitHub." }, { date = "2026-06-20", summary = "Maintenance pass (axis-1 must>intend>like, axis-2 corrective>adaptive>perfective). CORRECTIVE: re-stamped 24 .zig/.idr source SPDX headers MPL-2.0 -> AGPL-3.0-or-later to match LICENSE + META.a2ml + steam_client.zig (machine-readable .a2ml/.contractile stay MPL by carve-out); filled INTENT.contractile (was raw template — purpose/anti-purpose/architectural-invariants/ask-before-touching/ecosystem). ADAPTIVE: exported-symbol count 24/22 -> 27 (Steam +3, Nexus run_script/write_server_config +2) in CLAUDE.md + ROADMAP; completion 100% -> honest 93% to match ROADMAP; struck stale critical-next-action (Nexus FFI exports already exist at server_actions.zig:573/:713), replaced with the real open item (Ephapax parser gaps); refreshed ROADMAP revdate + April additions. Test counts (111/112, integration 36/39) left for a verified 'zig build test' run — zig not installed in this container." }, - { date = "2026-07-07", summary = "Production-gap sweep + AffineScript interface session. GAP: fixed Secret Scanner startup_failure on main (estate Bug B — reusable's gitleaks job requests pull-requests:write/actions:read above the caller's contents:read cap; granted matching job-level perms in the wrapper and repinned d135b05->891b1ed, same pattern as the green Scorecard wrapper from PR #41). Migrated deprecated metadata names per estate mandate: .machine_readable/6a2/ -> descriptiles/, agent_instructions/ -> bot_directives/, all path references rewritten (docs/INDEX, 3 maintainer guides, .claude/CLAUDE.md). Triaged all 8 issue-#20 panic-attack findings with file:line evidence — every one fixed or false-positive (fli escaping, scoped deno perms, prompted-not-hardcoded Steam creds, flake.nix removed in nix->guix) — issue close is owner-gated (permission layer). Verified suites on main: 140 tests (unit 94, integration 41, smoke 5), all passing. Refreshed STATE/ROADMAP/CLAUDE.md to v0.9.0 reality (PRs #61-#63: hardening phases 4-8, tri-license + version SSOT, HTTP capability gateway + wiki). Instant Sync red is B5 (dead FARM_DISPATCH_TOKEN, owner-gated). AFFINESCRIPT: developed the interface from disconnected TEA skeleton into the real any-game surface — new src/ui/tea/gsa_ffi.affine binds all 38 libgsa C ABI exports (typed externs + opaque GsaPtr + ResultCode enum mirroring Types.idr 0-17 + cmd_* effect layer with / IO rows); gsa_gui.affine reworked (8 panels incl NexusSetup, GameProfile registry model = 18 games + generic auto-detect fallback, 15 Msg variants closing the host feedback loop, result-code status surface, subs for log/health polling). Both files typecheck against the affinescript compiler (core face; note: 'handle' is a reserved word, record spread fails on nominal structs, module resolution is cwd-relative — check from src/ui/tea). Guard rails: scripts/affine-ffi-contract-check.sh (declared ⊆ exported + 27-symbol core coverage), affine-ffi-contract job in abi-contract.yml, just affine-check / affine-contract recipes, affine-contract wired into just quality." }, + { date = "2026-07-07", summary = "Production-gap sweep + AffineScript interface session. GAP: fixed Secret Scanner startup_failure on main (estate Bug B — reusable's gitleaks job requests pull-requests:write/actions:read above the caller's contents:read cap; granted matching job-level perms in the wrapper and repinned d135b05->891b1ed, same pattern as the green Scorecard wrapper from PR #41). Migrated deprecated metadata names per estate mandate: .machine_readable/6a2/ -> descriptiles/, agent_instructions/ -> bot_directives/, all path references rewritten (docs/INDEX, 3 maintainer guides, .claude/CLAUDE.md). Triaged all 8 issue-#20 panic-attack findings with file:line evidence — every one fixed or false-positive (fli escaping, scoped deno perms, prompted-not-hardcoded Steam creds, flake.guix removed in guix->guix) — issue close is owner-gated (permission layer). Verified suites on main: 140 tests (unit 94, integration 41, smoke 5), all passing. Refreshed STATE/ROADMAP/CLAUDE.md to v0.9.0 reality (PRs #61-#63: hardening phases 4-8, tri-license + version SSOT, HTTP capability gateway + wiki). Instant Sync red is B5 (dead FARM_DISPATCH_TOKEN, owner-gated). AFFINESCRIPT: developed the interface from disconnected TEA skeleton into the real any-game surface — new src/ui/tea/gsa_ffi.affine binds all 38 libgsa C ABI exports (typed externs + opaque GsaPtr + ResultCode enum mirroring Types.idr 0-17 + cmd_* effect layer with / IO rows); gsa_gui.affine reworked (8 panels incl NexusSetup, GameProfile registry model = 18 games + generic auto-detect fallback, 15 Msg variants closing the host feedback loop, result-code status surface, subs for log/health polling). Both files typecheck against the affinescript compiler (core face; note: 'handle' is a reserved word, record spread fails on nominal structs, module resolution is cwd-relative — check from src/ui/tea). Guard rails: scripts/affine-ffi-contract-check.sh (declared ⊆ exported + 27-symbol core coverage), affine-ffi-contract job in abi-contract.yml, just affine-check / affine-contract recipes, affine-contract wired into just quality." }, { date = "2026-06-21", summary = "CI/governance + Hypatia advisory sweep (PRs #41-#45). #41: hardened workflows — explicit Scorecard wrapper job permissions (contents:read/security-events:write/id-token:write), presence-gated instant-sync repository-dispatch on FARM_DISPATCH_TOKEN, added CodeQL actions language, scoped run.js/Justfile deno perms (allow-read/run/env), fli-editable.js innerHTML to replaceChildren. #42: refreshed standards reusable pins; fixed a staleness-check grep bug (a reusable-pin token in a comment double-matched the single-pin SHA compare). #43: replaced the inert .hypatia-baseline.json (hypatia scan never applies it — only excludes the file itself) with a working .hypatia-ignore suppressing 7 reviewed false positives (2 test-fixture secrets, 3 escaped-markup innerHTML, loopback HTTP, syscall bitCast). #44: stopped .hypatia-ignore tripping its own secret scanner (self-exempt entry + reworded comments). #45: corrected 7 docs that still referenced the pre-rename ABI directory, now pointing at src/interface/abi/ (SD022); bumped pins to 4ddc926. Result: advisory scan critical=0/high=0, governance staleness green, Validate-Baseline green-by-skip. Verified .hypatia-ignore matching + the staleness script locally (no Zig/Elixir/Hypatia in container). Outstanding: 10 merged branches need manual git push --delete (the git proxy 403s deletions here); estate-standardization-20260607 (2026-06-07, pre-#38) is stale/superseded (its AGPL migration already landed 2026-06-20) — reconcile before any merge; documentation gaps (user panel guides, dev extension guide, maintainer CI/release runbooks) tracked in docs/INDEX.adoc." }, ] diff --git a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml index eaee720..698f4d0 100644 --- a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml +++ b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml @@ -67,7 +67,7 @@ compliance-seams-check = true exception-register-required = true exception-bounded-scope-required = true policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad ReScript->TypeScript migration" +example-drift-risk = "single TypeScript exception causing broad AffineScript->TypeScript migration" compliance-tooling = "panic-attack" effects-tooling = "ecological checking with sustainabot guidance" diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..ca1c652 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONFIG-CHANGES.adoc b/CONFIG-CHANGES.adoc new file mode 100644 index 0000000..6724646 --- /dev/null +++ b/CONFIG-CHANGES.adoc @@ -0,0 +1,191 @@ +== Configuration System Changes + +=== Summary + +This document summarizes the changes made to the Game Server Admin (GSA) +configuration system to support user-configurable server IP/port +settings and favorites management. + +=== Changes Made + +==== 1. New Configuration File + +* *File*: `+user-config.ncl.template+` +* *Purpose*: Template for user-specific configuration +* *Format*: Nickel language (`+.ncl+`) +* *Status*: Gitignored (template only) + +==== 2. User Configuration File + +* *File*: `+user-config.ncl+` +* *Purpose*: User-specific settings including: +** Default server connection (host, port, profile_id, rcon_password) +** Favorite servers list +** UI preferences (theme, default panel, advanced options) +** Connection settings (timeout, retries, logging) +** VeriSimDB settings (URL, auto-submit) +* *Status*: Gitignored (contains sensitive data) + +==== 3. CLI Enhancements + +Added new `+config+` subcommands to the CLI: + +===== `+gsa config init+` + +* Creates `+user-config.ncl+` from the template +* Prevents overwriting existing config +* Shows byte count and success message + +===== `+gsa config show+` + +* Displays current user configuration +* Shows full file contents +* Helps users verify their settings + +===== `+gsa config set-default +` + +* Updates the default server connection +* Modifies `+user-config.ncl+` in-place +* Validates input parameters + +===== `+gsa config add-favorite +` + +* Adds a server to the favorites list +* Appends to the favorites array in config +* Supports named servers for easy identification + +===== `+gsa config list-favorites+` + +* Lists favorite servers +* Currently shows config file location +* Future: Parse and display formatted list + +==== 4. Documentation + +* *USER-CONFIG.md*: Comprehensive user guide +* *README.adoc*: Updated with configuration section +* *CONFIG-CHANGES.md*: This file + +==== 5. Git Configuration + +Updated `+.gitignore+` to exclude: - `+user-config.ncl+` (user +configuration) - Ensures sensitive data is never committed + +=== Technical Implementation + +==== CLI Implementation + +* *File*: `+src/interface/ffi/src/cli.zig+` +* *Changes*: +** Added config command parsing +** Implemented 5 new subcommands +** Added helper functions for file manipulation +** Updated usage message + +==== Configuration Format + +Uses Nickel language for: - Type safety - Easy editing - Future +extensibility - Integration with Gossamer panels + +==== Security Considerations + +[arabic] +. *Git Ignore*: User config never committed +. *Template*: Safe default values only +. *Permissions*: File operations check permissions +. *Error Handling*: Graceful failure messages + +=== Usage Examples + +==== Initialize Configuration + +[source,bash] +---- +./gsa config init +---- + +==== Set Default Server + +[source,bash] +---- +./gsa config set-default mc.example.com 25565 +---- + +==== Add Favorite Servers + +[source,bash] +---- +./gsa config add-favorite "My Minecraft" mc.example.com 25565 +./gsa config add-favorite "CS2 Server" cs2.example.com 27015 +---- + +==== View Configuration + +[source,bash] +---- +./gsa config show +---- + +=== Future Enhancements + +Planned improvements: + +[arabic] +. *Profile Integration*: Link favorites to game profiles +. *Connection Testing*: Validate servers from CLI +. *Import/Export*: Backup and restore config +. *Encryption*: Secure sensitive data +. *GUI Editor*: Visual configuration interface + +=== Migration Guide + +==== For Existing Users + +[arabic] +. Run `+./gsa config init+` to create template +. Edit `+user-config.ncl+` manually +. Add your servers to the favorites list +. Set your preferred default server + +==== For New Users + +[arabic] +. Configuration is optional +. Default values work out-of-the-box +. Use CLI commands to customize +. See `+USER-CONFIG.md+` for details + +=== Testing + +The implementation includes: + +* Basic file operation validation +* Input parameter checking +* Error handling for common cases +* Success/failure messages + +=== Compatibility + +* *Backward Compatible*: Existing functionality unchanged +* *Optional*: Configuration is not required +* *Safe Defaults*: Template provides sensible defaults + +=== Files Modified + +[arabic] +. `+src/interface/ffi/src/cli.zig+` - Added config commands +. `+.gitignore+` - Added user-config.ncl +. `+README.adoc+` - Added configuration section +. `+USER-CONFIG.md+` - Created (new file) +. `+user-config.ncl.template+` - Created (new file) +. `+CONFIG-CHANGES.md+` - Created (this file) + +=== Files Created + +* `+user-config.ncl.template+` +* `+USER-CONFIG.md+` +* `+CONFIG-CHANGES.md+` + +=== Files Ignored (Git) + +* `+user-config.ncl+` diff --git a/CONFIG-CHANGES.md b/CONFIG-CHANGES.md deleted file mode 100644 index 13d5459..0000000 --- a/CONFIG-CHANGES.md +++ /dev/null @@ -1,179 +0,0 @@ -# Configuration System Changes - -## Summary - -This document summarizes the changes made to the Game Server Admin (GSA) configuration system to support user-configurable server IP/port settings and favorites management. - -## Changes Made - -### 1. New Configuration File - -- **File**: `user-config.ncl.template` -- **Purpose**: Template for user-specific configuration -- **Format**: Nickel language (`.ncl`) -- **Status**: Gitignored (template only) - -### 2. User Configuration File - -- **File**: `user-config.ncl` -- **Purpose**: User-specific settings including: - - Default server connection (host, port, profile_id, rcon_password) - - Favorite servers list - - UI preferences (theme, default panel, advanced options) - - Connection settings (timeout, retries, logging) - - VeriSimDB settings (URL, auto-submit) -- **Status**: Gitignored (contains sensitive data) - -### 3. CLI Enhancements - -Added new `config` subcommands to the CLI: - -#### `gsa config init` -- Creates `user-config.ncl` from the template -- Prevents overwriting existing config -- Shows byte count and success message - -#### `gsa config show` -- Displays current user configuration -- Shows full file contents -- Helps users verify their settings - -#### `gsa config set-default ` -- Updates the default server connection -- Modifies `user-config.ncl` in-place -- Validates input parameters - -#### `gsa config add-favorite ` -- Adds a server to the favorites list -- Appends to the favorites array in config -- Supports named servers for easy identification - -#### `gsa config list-favorites` -- Lists favorite servers -- Currently shows config file location -- Future: Parse and display formatted list - -### 4. Documentation - -- **USER-CONFIG.md**: Comprehensive user guide -- **README.adoc**: Updated with configuration section -- **CONFIG-CHANGES.md**: This file - -### 5. Git Configuration - -Updated `.gitignore` to exclude: -- `user-config.ncl` (user configuration) -- Ensures sensitive data is never committed - -## Technical Implementation - -### CLI Implementation - -- **File**: `src/interface/ffi/src/cli.zig` -- **Changes**: - - Added config command parsing - - Implemented 5 new subcommands - - Added helper functions for file manipulation - - Updated usage message - -### Configuration Format - -Uses Nickel language for: -- Type safety -- Easy editing -- Future extensibility -- Integration with Gossamer panels - -### Security Considerations - -1. **Git Ignore**: User config never committed -2. **Template**: Safe default values only -3. **Permissions**: File operations check permissions -4. **Error Handling**: Graceful failure messages - -## Usage Examples - -### Initialize Configuration - -```bash -./gsa config init -``` - -### Set Default Server - -```bash -./gsa config set-default mc.example.com 25565 -``` - -### Add Favorite Servers - -```bash -./gsa config add-favorite "My Minecraft" mc.example.com 25565 -./gsa config add-favorite "CS2 Server" cs2.example.com 27015 -``` - -### View Configuration - -```bash -./gsa config show -``` - -## Future Enhancements - -Planned improvements: - -1. **Profile Integration**: Link favorites to game profiles -2. **Connection Testing**: Validate servers from CLI -3. **Import/Export**: Backup and restore config -4. **Encryption**: Secure sensitive data -5. **GUI Editor**: Visual configuration interface - -## Migration Guide - -### For Existing Users - -1. Run `./gsa config init` to create template -2. Edit `user-config.ncl` manually -3. Add your servers to the favorites list -4. Set your preferred default server - -### For New Users - -1. Configuration is optional -2. Default values work out-of-the-box -3. Use CLI commands to customize -4. See `USER-CONFIG.md` for details - -## Testing - -The implementation includes: - -- Basic file operation validation -- Input parameter checking -- Error handling for common cases -- Success/failure messages - -## Compatibility - -- **Backward Compatible**: Existing functionality unchanged -- **Optional**: Configuration is not required -- **Safe Defaults**: Template provides sensible defaults - -## Files Modified - -1. `src/interface/ffi/src/cli.zig` - Added config commands -2. `.gitignore` - Added user-config.ncl -3. `README.adoc` - Added configuration section -4. `USER-CONFIG.md` - Created (new file) -5. `user-config.ncl.template` - Created (new file) -6. `CONFIG-CHANGES.md` - Created (this file) - -## Files Created - -- `user-config.ncl.template` -- `USER-CONFIG.md` -- `CONFIG-CHANGES.md` - -## Files Ignored (Git) - -- `user-config.ncl` diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..dd089ae --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+guix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/Justfile b/Justfile index c487b4c..7efa24f 100644 --- a/Justfile +++ b/Justfile @@ -233,7 +233,7 @@ init: # Check for remaining placeholders PATTERN="${LB}[A-Z_]*${RB}" - REMAINING=$(grep -rl "$PATTERN" . --include='*.md' --include='*.adoc' --include='*.yml' --include='*.yaml' --include='*.a2ml' --include='*.toml' --include='*.scm' --include='*.ncl' --include='*.nix' --include='*.json' --include='*.sh' 2>/dev/null | grep -v '.git/' | grep -v '.machine_readable/ai/PLACEHOLDERS.adoc' || true) + REMAINING=$(grep -rl "$PATTERN" . --include='*.md' --include='*.adoc' --include='*.yml' --include='*.yaml' --include='*.a2ml' --include='*.toml' --include='*.scm' --include='*.ncl' --include='*.guix' --include='*.json' --include='*.sh' 2>/dev/null | grep -v '.git/' | grep -v '.machine_readable/ai/PLACEHOLDERS.adoc' || true) if [ -n "$REMAINING" ]; then echo "WARNING: Remaining placeholders in:" echo "$REMAINING" | sed 's/^/ /' @@ -1103,7 +1103,7 @@ state-phase: @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" # ═══════════════════════════════════════════════════════════════════════════════ -# GUIX & NIX +# GUIX & GUIX # ═══════════════════════════════════════════════════════════════════════════════ # Enter Guix development shell (primary) @@ -1114,9 +1114,9 @@ guix-shell: guix-build: guix build -f guix.scm -# Enter Nix development shell (fallback) -nix-shell: - @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi +# Enter Guix development shell (fallback) +guix-shell: + @if [ -f "flake.guix" ]; then guix develop; else echo "No flake.guix"; fi # ═══════════════════════════════════════════════════════════════════════════════ # HYBRID AUTOMATION diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..c117230 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,124 @@ +== Proof Requirements + +=== Current State (2026-06-21 — verified with Idris2 0.7.0 + Zig 0.15.2) + +The ABI package typechecks end-to-end (all modules `+%default total+`, +no `+postulate+` / `+believe_me+` / `+assert_total+`), and the +hand-written Idris layout constants are now cross-checked against the +real C layout the Zig compiler emits (see _Cross-language ABI_ below): + +[source,bash] +---- +cd src/interface/abi && idris2 --typecheck gsa-abi.ipkg +# 1/3: Building Types (Types.idr) +# 2/3: Building Layout (Layout.idr) +# 3/3: Building Foreign (Foreign.idr) +---- + +Toolchain: Idris2 0.7.0, Chez backend (`+.tool-versions+` pins +`+idris2 0.7.0+`). + +=== What is proven (machine-checked) + +==== Memory layout (`+Layout.idr+`) + +For every one of the 8 ABI structs — ServerHandle, ProbeResult, +ConfigField, A2MLConfig, GameProfile, ServerOctad, Fingerprint, +DriftReport — all four layout properties are proven: + +[width="100%",cols="53%,47%",options="header",] +|=== +|Property |Meaning +|`+NoOverlap+` |no two fields’ `+[offset, offset+size)+` ranges overlap + +|`+AllFieldsAligned+` |every field offset is a multiple of its alignment + +|`+SizeAligned+` |total struct size is a multiple of the struct +alignment + +|`+SizeCoversFields+` |total size ≥ sum of field sizes (padding +accounted) +|=== + +Discharged by decision procedures (`+decNoOverlap+`, `+decAllAligned+`, +`+decSizeAligned+`, `+decSizeCovers+`) extracted via `+getYes+`; each +proof typechecks only because its `+Dec+` reduces to `+Yes+` for that +concrete layout — i.e. a malformed layout would fail to compile. + +Also still proven: the per-type size/alignment `+Refl+` proofs, the +`+SizeOf+`↔layout agreement (`+LayoutMatchesSizeOf+`), and +cross-platform x86_64 ≡ aarch64 equivalence. + +==== Alignment (`+Layout.idr+`) + +* `+alignUpCeil offset a = ceilDiv offset a * a+` (via an in-module +total `+ceilDiv+`). +* `+alignUpCeilIsMultiple+` — constructive `+Refl+` proof that the +result is `+k * a+`. + +____ +Correction to the prior version of this file: the earlier +`+alignUpCeilIsMultiple+` did *not* typecheck (the `+case+` form left +the goal stuck). It was rewritten via `+ceilDiv+` so the witness is a +direct `+Refl+`. There is no remaining `+alignUpEquiv+` postulate — the +proven path uses `+alignUpCeil+`/`+ceilDiv+` directly, so that +obligation is moot. +____ + +==== Domain validators (`+Types.idr+`) + +Decidable `+portInRange+`, `+nonEmptyId+`, `+configFieldCountPositive+`, +`+allPortsValid+`, the `+Valid*+` smart constructors, and the linear +`+ServerHandle+` with its erased non-null witness. + +==== Cross-language ABI (`+abi_layout.zig+` / `+abi_serde.zig+`) + +The Idris proofs above show the _model_ is internally consistent; the +Zig side now checks that model against reality and makes it a live +runtime contract. + +* *Layout cross-check (was the open HIGH item).* Each of the 8 structs +is declared as a Zig `+extern struct+` (`+abi_layout.zig+`). A comptime +block asserts `+@offsetOf+` / `+@sizeOf+` / `+@alignOf+` of every field +equals the proven Idris constant — lifted verbatim from `+Layout.idr+` +into `+abi_layout_expected.zig+` by `+scripts/gen_abi_expected.zig+`. +Any divergence is a *compile error*, so the library cannot build against +a layout the proofs do not describe. A negative test (perturbing one +offset) confirms the guard bites; the check also runs under +`+zig build test+`. +* *Live offset contract.* The previously-unimplemented FFI readers that +`+GSA.ABI.Foreign+` binds are now real (`+abi_serde.zig+`): `+read_int+` +/ `+read_double+` / `+read_ptr+` decode fields at a byte offset; +`+read_string+`, `+array_len+`, `+array_get_string+`, `+is_null+`, +`+free+` handle strings/arrays; `+apply_config+` / `+close_handle+` +round out the surface. Emitters (`+serializeDriftReport+` / +`+serializeFingerprint+` / `+serializeStringArray+`) write the wire +structs, and `+gossamer_gsa_drift_struct+` exports one. Round-trip tests +read each field back at its *proven* `+Layout.idr+` offset, standing in +for the Idris reader — so agreement is an end-to-end cross-language +guarantee. +* *Idris consumer.* `+Foreign.getDrift+` now decodes a `+DriftReport+` +at offsets taken from `+offsetOf … driftReportLayout+` (not the +previous, wrong hand-tuned `+0/4/12/20/28+`), via `+prim__driftStruct+` ++ `+prim__readPtr+`/`+readInt+`/`+readDouble+`. + +____ +Regenerate the expected table whenever `+Layout.idr+` changes: +`+zig run scripts/gen_abi_expected.zig+` (then the Zig cross-check +re-validates). +____ + +=== What still needs proving + +* *Server probe safety (MEDIUM).* Prove probes cause no side effects on +targets. Needs a specification first. +* *Configuration drift-detection completeness (LOW).* Needs a richer +spec. +* *Access control for admin panels (LOW).* Needs a specification. + +=== Notes + +* `+Foreign.idr+`’s linear `+ServerHandle+` wrappers now typecheck: each +handle is consumed by a pattern match and rebuilt for the borrow-return, +so linearity is respected (previously they used the handle twice and did +not compile). diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index feea1c7..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,97 +0,0 @@ -# Proof Requirements - -## Current State (2026-06-21 — verified with Idris2 0.7.0 + Zig 0.15.2) - -The ABI package typechecks end-to-end (all modules `%default total`, no -`postulate` / `believe_me` / `assert_total`), and the hand-written Idris layout -constants are now cross-checked against the real C layout the Zig compiler emits -(see *Cross-language ABI* below): - -```bash -cd src/interface/abi && idris2 --typecheck gsa-abi.ipkg -# 1/3: Building Types (Types.idr) -# 2/3: Building Layout (Layout.idr) -# 3/3: Building Foreign (Foreign.idr) -``` - -Toolchain: Idris2 0.7.0, Chez backend (`.tool-versions` pins `idris2 0.7.0`). - -## What is proven (machine-checked) - -### Memory layout (`Layout.idr`) -For every one of the 8 ABI structs — ServerHandle, ProbeResult, ConfigField, -A2MLConfig, GameProfile, ServerOctad, Fingerprint, DriftReport — all four -layout properties are proven: - -| Property | Meaning | -|----------|---------| -| `NoOverlap` | no two fields' `[offset, offset+size)` ranges overlap | -| `AllFieldsAligned` | every field offset is a multiple of its alignment | -| `SizeAligned` | total struct size is a multiple of the struct alignment | -| `SizeCoversFields` | total size ≥ sum of field sizes (padding accounted) | - -Discharged by decision procedures (`decNoOverlap`, `decAllAligned`, -`decSizeAligned`, `decSizeCovers`) extracted via `getYes`; each proof -typechecks only because its `Dec` reduces to `Yes` for that concrete layout — -i.e. a malformed layout would fail to compile. - -Also still proven: the per-type size/alignment `Refl` proofs, the -`SizeOf`↔layout agreement (`LayoutMatchesSizeOf`), and cross-platform -x86_64 ≡ aarch64 equivalence. - -### Alignment (`Layout.idr`) -- `alignUpCeil offset a = ceilDiv offset a * a` (via an in-module total - `ceilDiv`). -- `alignUpCeilIsMultiple` — constructive `Refl` proof that the result is - `k * a`. - -> Correction to the prior version of this file: the earlier -> `alignUpCeilIsMultiple` did **not** typecheck (the `case` form left the -> goal stuck). It was rewritten via `ceilDiv` so the witness is a direct -> `Refl`. There is no remaining `alignUpEquiv` postulate — the proven path -> uses `alignUpCeil`/`ceilDiv` directly, so that obligation is moot. - -### Domain validators (`Types.idr`) -Decidable `portInRange`, `nonEmptyId`, `configFieldCountPositive`, -`allPortsValid`, the `Valid*` smart constructors, and the linear -`ServerHandle` with its erased non-null witness. - -### Cross-language ABI (`abi_layout.zig` / `abi_serde.zig`) -The Idris proofs above show the *model* is internally consistent; the Zig side -now checks that model against reality and makes it a live runtime contract. - -- **Layout cross-check (was the open HIGH item).** Each of the 8 structs is - declared as a Zig `extern struct` (`abi_layout.zig`). A comptime block asserts - `@offsetOf` / `@sizeOf` / `@alignOf` of every field equals the proven Idris - constant — lifted verbatim from `Layout.idr` into `abi_layout_expected.zig` by - `scripts/gen_abi_expected.zig`. Any divergence is a **compile error**, so the - library cannot build against a layout the proofs do not describe. A negative - test (perturbing one offset) confirms the guard bites; the check also runs - under `zig build test`. -- **Live offset contract.** The previously-unimplemented FFI readers that - `GSA.ABI.Foreign` binds are now real (`abi_serde.zig`): `read_int` / - `read_double` / `read_ptr` decode fields at a byte offset; `read_string`, - `array_len`, `array_get_string`, `is_null`, `free` handle strings/arrays; - `apply_config` / `close_handle` round out the surface. Emitters - (`serializeDriftReport` / `serializeFingerprint` / `serializeStringArray`) - write the wire structs, and `gossamer_gsa_drift_struct` exports one. Round-trip - tests read each field back at its **proven** `Layout.idr` offset, standing in - for the Idris reader — so agreement is an end-to-end cross-language guarantee. -- **Idris consumer.** `Foreign.getDrift` now decodes a `DriftReport` at offsets - taken from `offsetOf … driftReportLayout` (not the previous, wrong hand-tuned - `0/4/12/20/28`), via `prim__driftStruct` + `prim__readPtr`/`readInt`/`readDouble`. - -> Regenerate the expected table whenever `Layout.idr` changes: -> `zig run scripts/gen_abi_expected.zig` (then the Zig cross-check re-validates). - -## What still needs proving - -- **Server probe safety (MEDIUM).** Prove probes cause no side effects on - targets. Needs a specification first. -- **Configuration drift-detection completeness (LOW).** Needs a richer spec. -- **Access control for admin panels (LOW).** Needs a specification. - -## Notes -- `Foreign.idr`'s linear `ServerHandle` wrappers now typecheck: each handle is - consumed by a pattern match and rebuilt for the borrow-return, so linearity - is respected (previously they used the handle twice and did not compile). diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..1374cc5 --- /dev/null +++ b/README.adoc @@ -0,0 +1,208 @@ +Jonathan D.A. Jewell + +____ +[!TIP] *AI-Assisted Install:* Just tell any AI assistant: + +`+Set+` `+up+` `+game-server-admin+` `+from+` +https://github.com/hyperpolymath/game-server-admin[`+https://github.com/hyperpolymath/game-server-admin+`] + +The AI reads the manifest, asks you a few questions, and handles +everything. +____ + +== Overview + +*Universal game server probe, configuration management, and +administration* — built on Gossamer (linearly-typed webview shell) with +VeriSimDB (8-modality database) underpinning. + +GSA can attach to _any_ game server, fingerprint it via protocol +probing, extract its configuration into A2ML format, and provide a rich +GUI for viewing, editing, and tracking config changes with full +provenance. + +*New in this version:* User-configurable server connections with support +for default servers and favorites list. See Configuration for details. + +=== Architecture + +.... +┌─────────────────────────────────────────────────┐ +│ Gossamer GUI (Ephapax + HTML/JS) │ +│ 8 panels, each a Clade citizen with inheritance │ +└────────────────────┬────────────────────────────┘ + │ IPC (gossamer:// bridge) +┌────────────────────┴────────────────────────────┐ +│ Probe Engine (Ephapax + Zig FFI) │ +│ Protocol fingerprint → game profile → config │ +└────────────────────┬────────────────────────────┘ + │ REST (localhost:8090) +┌────────────────────┴────────────────────────────┐ +│ VeriSimDB Instance (gsa-verisimdb) │ +│ 8 modalities per server, drift detection │ +└─────────────────────────────────────────────────┘ +.... + +=== Panels + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Panel |Kind |Description +|Server Browser |inspector |Discover/fingerprint servers, add to +management + +|Config Editor |editor |A2ML-aware form generation with type validation + +|Server Actions |terminal |Start/stop/restart with confirmation + +|Live Logs |terminal |Real-time log streaming with ANSI color + +|Health Dashboard |scanner |VeriSimDB drift detection and health gauges + +|Config History |database |Temporal version timeline with diff viewer + +|Cross-Server Search |database |VQL full-text + vector search across +configs +|=== + +All panels are registered in the PanLL Clade system with full +inheritance. The cladogram grows automatically as new game profiles are +added. + +=== Supported Games (Initial) + +Valheim, Barotrauma, Don’t Starve Together, Minecraft Java/Bedrock, +Factorio, Terraria, ARK, Rust (game), CS2, Garry’s Mod, Project Zomboid, +Starbound, DayZ, Void Expanse — plus IDApTIK and Burble. + +== Quick Start + +[source,bash] +---- +# Start the VeriSimDB instance +just verisimdb-up + +# Build and run the CLI +just run status # system status, VeriSimDB health, loaded profiles +just run probe [port] # fingerprint a game server (default port 27015) +just run profiles # list all 18 supported game profiles + +# Or build and launch the GUI +just build && just gui +---- + +=== CLI Reference + +The `+gsa+` binary is built automatically by `+zig+` `+build+` and lives +at `+src/interface/ffi/zig-out/bin/gsa+`. + +[width="100%",cols="50%,50%",options="header",] +|=== +|Command |Description +|`+gsa+` `+status+` |VeriSimDB health, build info, loaded game profiles + +|`+gsa+` `+probe+` `++` `+[port]+` |Fingerprint a game server +(Steam, Minecraft, RCON, HTTP, TCP banner) + +|`+gsa+` `+profiles+` |JSON listing of all supported games with +engine/port/config details + +|`+gsa+` `+version+` |Print version string + +|`+gsa+` `+help+` |Usage information +|=== + +Environment variables: `+GSA_VERISIMDB_URL+` (default +http://localhost:8090[`+http://localhost:8090+`]), `+GSA_PROFILES_DIR+` +(default `+./profiles+`). + +== Adding a Game Profile + +Create a new `+.a2ml+` file in `+profiles/+`: + +.... +@game-profile(id="my-game", name="My Game", engine="custom"): + @ports(query=27015, game=27016):@end + @protocol(type="steam-query", version="a2s"):@end + @config(format="json", path="/config/server.json"): + @field(key="name", type="string", label="Server Name"):@end + @end + @clade(inherits="gsa-game", kind="game-profile"):@end +@end +.... + +Then run `+just+` `+generate-clades+` — the cladogram updates +automatically. + +== ABI/FFI Standard + +* *ABI (Idris2):* `+src/interface/abi/+` — formal type specs with +dependent type proofs +* *FFI (Zig):* `+src/interface/ffi/+` — C-compatible implementation +* *Core (Ephapax):* `+src/core/+` — linear type enforcement for resource +safety + +== VeriSimDB Integration + +Each managed server is a VeriSimDB octad with all 8 modalities: + +* *Graph:* server→game-profile, server→cluster edges +* *Vector:* config embedding for similarity search +* *Tensor:* performance metrics over time +* *Semantic:* game type, version, mods, status +* *Document:* full config text (A2ML, full-text indexed) +* *Temporal:* every config version with timestamp +* *Provenance:* who changed what, when, why (hash-chain) +* *Spatial:* datacenter geolocation + +Dedicated instance on port 8090 with persistent storage and 15s drift +detection. + +== Configuration + +GSA now supports user-specific configuration through a Nickel (`+.ncl+`) +configuration file. This allows you to: + +* Set a default server IP and port +* Maintain a list of favorite servers +* Customize UI preferences +* Configure connection settings + +=== Initial Setup + +To create a default configuration file: + +[source,bash] +---- +./gsa config init +---- + +This creates `+user-config.ncl+` from the template. + +=== Configuration Commands + +[source,bash] +---- +# Show current configuration +./gsa config show + +# Set default server +./gsa config set-default mc.example.com 25565 + +# Add a favorite server +./gsa config add-favorite "My Minecraft" mc.example.com 25565 + +# List favorite servers +./gsa config list-favorites +---- + +=== Configuration File + +The configuration file (`+user-config.ncl+`) is *gitignored* to ensure +your server credentials remain private. See `+USER-CONFIG.md+` for +complete documentation. + +== License + +SPDX-License-Identifier: CC-BY-SA-4.0 + +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + diff --git a/README.md b/README.md deleted file mode 100644 index c6f3dae..0000000 --- a/README.md +++ /dev/null @@ -1,200 +0,0 @@ - - -Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> - -> [!TIP] -> **AI-Assisted Install:** Just tell any AI assistant:\ -> `Set` `up` `game-server-admin` `from` -> [`https://github.com/hyperpolymath/game-server-admin`](https://github.com/hyperpolymath/game-server-admin)\ -> The AI reads the manifest, asks you a few questions, and handles -> everything. - -# Overview - -**Universal game server probe, configuration management, and -administration** — built on Gossamer (linearly-typed webview shell) with -VeriSimDB (8-modality database) underpinning. - -GSA can attach to *any* game server, fingerprint it via protocol -probing, extract its configuration into A2ML format, and provide a rich -GUI for viewing, editing, and tracking config changes with full -provenance. - -**New in this version:** User-configurable server connections with -support for default servers and favorites list. See -Configuration for -details. - -## Architecture - - ┌─────────────────────────────────────────────────┐ - │ Gossamer GUI (Ephapax + HTML/JS) │ - │ 8 panels, each a Clade citizen with inheritance │ - └────────────────────┬────────────────────────────┘ - │ IPC (gossamer:// bridge) - ┌────────────────────┴────────────────────────────┐ - │ Probe Engine (Ephapax + Zig FFI) │ - │ Protocol fingerprint → game profile → config │ - └────────────────────┬────────────────────────────┘ - │ REST (localhost:8090) - ┌────────────────────┴────────────────────────────┐ - │ VeriSimDB Instance (gsa-verisimdb) │ - │ 8 modalities per server, drift detection │ - └─────────────────────────────────────────────────┘ - -## Panels - -| Panel | Kind | Description | -|----|----|----| -| Server Browser | inspector | Discover/fingerprint servers, add to management | -| Config Editor | editor | A2ML-aware form generation with type validation | -| Server Actions | terminal | Start/stop/restart with confirmation | -| Live Logs | terminal | Real-time log streaming with ANSI color | -| Health Dashboard | scanner | VeriSimDB drift detection and health gauges | -| Config History | database | Temporal version timeline with diff viewer | -| Cross-Server Search | database | VQL full-text + vector search across configs | - -All panels are registered in the PanLL Clade system with full -inheritance. The cladogram grows automatically as new game profiles are -added. - -## Supported Games (Initial) - -Valheim, Barotrauma, Don’t Starve Together, Minecraft Java/Bedrock, -Factorio, Terraria, ARK, Rust (game), CS2, Garry’s Mod, Project Zomboid, -Starbound, DayZ, Void Expanse — plus IDApTIK and Burble. - -# Quick Start - -```bash -# Start the VeriSimDB instance -just verisimdb-up - -# Build and run the CLI -just run status # system status, VeriSimDB health, loaded profiles -just run probe [port] # fingerprint a game server (default port 27015) -just run profiles # list all 18 supported game profiles - -# Or build and launch the GUI -just build && just gui -``` - -## CLI Reference - -The `gsa` binary is built automatically by `zig` `build` and lives at -`src/interface/ffi/zig-out/bin/gsa`. - -| Command | Description | -|----|----| -| `gsa` `status` | VeriSimDB health, build info, loaded game profiles | -| `gsa` `probe` `` `[port]` | Fingerprint a game server (Steam, Minecraft, RCON, HTTP, TCP banner) | -| `gsa` `profiles` | JSON listing of all supported games with engine/port/config details | -| `gsa` `version` | Print version string | -| `gsa` `help` | Usage information | - -Environment variables: `GSA_VERISIMDB_URL` (default -[`http://localhost:8090`](http://localhost:8090)), `GSA_PROFILES_DIR` -(default `./profiles`). - -# Adding a Game Profile - -Create a new `.a2ml` file in `profiles/`: - - @game-profile(id="my-game", name="My Game", engine="custom"): - @ports(query=27015, game=27016):@end - @protocol(type="steam-query", version="a2s"):@end - @config(format="json", path="/config/server.json"): - @field(key="name", type="string", label="Server Name"):@end - @end - @clade(inherits="gsa-game", kind="game-profile"):@end - @end - -Then run `just` `generate-clades` — the cladogram updates automatically. - -# ABI/FFI Standard - -- **ABI (Idris2):** `src/interface/abi/` — formal type specs with - dependent type proofs - -- **FFI (Zig):** `src/interface/ffi/` — C-compatible implementation - -- **Core (Ephapax):** `src/core/` — linear type enforcement for resource - safety - -# VeriSimDB Integration - -Each managed server is a VeriSimDB octad with all 8 modalities: - -- **Graph:** server→game-profile, server→cluster edges - -- **Vector:** config embedding for similarity search - -- **Tensor:** performance metrics over time - -- **Semantic:** game type, version, mods, status - -- **Document:** full config text (A2ML, full-text indexed) - -- **Temporal:** every config version with timestamp - -- **Provenance:** who changed what, when, why (hash-chain) - -- **Spatial:** datacenter geolocation - -Dedicated instance on port 8090 with persistent storage and 15s drift -detection. - -# Configuration - -GSA now supports user-specific configuration through a Nickel (`.ncl`) -configuration file. This allows you to: - -- Set a default server IP and port - -- Maintain a list of favorite servers - -- Customize UI preferences - -- Configure connection settings - -## Initial Setup - -To create a default configuration file: - -```bash -./gsa config init -``` - -This creates `user-config.ncl` from the template. - -## Configuration Commands - -```bash -# Show current configuration -./gsa config show - -# Set default server -./gsa config set-default mc.example.com 25565 - -# Add a favorite server -./gsa config add-favorite "My Minecraft" mc.example.com 25565 - -# List favorite servers -./gsa config list-favorites -``` - -## Configuration File - -The configuration file (`user-config.ncl`) is **gitignored** to ensure -your server credentials remain private. See `USER-CONFIG.md` for -complete documentation. - -# License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -\<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..9e71066 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,200 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Test Suite Summary + +[width="100%",cols="20%,18%,27%,35%",options="header",] +|=== +|Suite |Count |Location |Run command +|Unit tests |67 |`+src/interface/ffi/src/*.zig+` (inline `+test+` +blocks) |`+zig build test+` + +|Integration tests |39 |`+src/interface/ffi/test/integration_test.zig+` +|`+zig build test-integration+` + +|Smoke tests |5 |`+src/interface/ffi/test/smoke_test.zig+` +|`+zig build test-smoke+` + +|*Property tests* |*14* |`+src/interface/ffi/test/property_test.zig+` +|`+zig build test-property+` + +|*Total tests* |*125* | | +|=== + +*Benchmarks*: 15 scenarios across 7 benchmark groups in +`+src/interface/ffi/bench/bench_main.zig+` Run with: `+zig build bench+` + +=== CRG C Requirements — Status + +[width="100%",cols="47%,28%,25%",options="header",] +|=== +|Requirement |Status |Notes +|Unit tests |DONE |67 tests across 8 modules +|Smoke tests |DONE |5 end-to-end pipeline tests +|Build |DONE |`+zig build+` clean (all 3 artefacts) +|Property-based (P2P) |*DONE* |14 invariant tests, P1–P14 +|E2E |DONE |smoke_test.zig covers full pipeline +|Reflexive |DONE |result code mapping, enum exhaustiveness +|Contract |DONE |ABI integer mapping, secret redaction +|Aspect |DONE |Security tests (command injection, injection strings) +|Benchmarks |*DONE* |15 scenarios, B1–B7 +|=== + +=== Property Tests Added (2026-04-04) + +File: `+src/interface/ffi/test/property_test.zig+` + +14 property/invariant tests covering: + +* *P1* `+detectFormat+` is total — never panics on any byte sequence in +a 40-entry corpus +* *P2* `+detectFormat+` is deterministic — same input always yields same +output +* *P3* `+parseAuto+` is total — never panics on valid or malformed +inputs +* *P4* `+parseAuto+` field count is always >= 0 (consistent internal +state) +* *P5* Config field keys are always non-empty after `+addField+` +* *P6* `+getField+` returns the exact value supplied to `+addField+` +(insertion/lookup consistency) +* *P7* `+ActionKind+` values are injective — no two variants share an +integer +* *P7b* `+ActionKind+` covers all 8 expected action types by name +* *P8* `+GrooveTarget+` fixed buffers never overflow on any input +(clamping verified) +* *P9* `+GrooveTarget+` name/host round-trip for inputs that fit the +buffer +* *P10* `+ProfileRegistry.listProfiles+` always returns valid JSON +(empty or populated) +* *P11* Every inserted key is retrievable regardless of insertion order +* *P12* `+field_type+` is preserved exactly by `+addField+` (including +empty string case) +* *P13* `+ConfigFormat+` values are injective — no two variants share a +u8 value +* *P14* `+parseAuto+` is deterministic — two parses of the same input +produce identical field lists + +=== Benchmarks Added (2026-04-04) + +File: `+src/interface/ffi/bench/bench_main.zig+` + +15 benchmark scenarios in 7 groups: + +==== B1 — Config format detection throughput + +* B1a `+detectFormat+` small KV payload (~50 B): 100 000 iterations +* B1b `+detectFormat+` medium JSON payload (~300 B): 100 000 iterations +* B1c `+detectFormat+` large Lua payload (~2 KB): 100 000 iterations + +==== B2 — parseAuto dispatch latency per format + +* B2a `+parseAuto+` KeyValue (small): 5 000 iterations +* B2b `+parseAuto+` JSON (medium): 5 000 iterations +* B2c `+parseAuto+` Lua (large): 5 000 iterations +* B2d `+parseAuto+` INI (medium): 5 000 iterations +* B2e `+parseAuto+` XML (medium): 5 000 iterations + +==== B3 — isLocalhost-equivalent batch validation + +* B3 batch of ~80 addresses (including injection strings): 100 000 +iterations + +==== B4 & B5 — ParsedConfig field operations + +* B4 `+addField+` × 5 fields: 5 000 iterations +* B5 `+getField+` × 4 lookups (best/average/worst/miss): 100 000 +iterations + +==== B6 — GrooveTarget buffer operations + +* B6a `+setName+` + `+setHost+` + read (fits 64/256 B buffers): 100 000 +iterations +* B6b Same ops with oversized strings (clamping path): 100 000 +iterations + +==== B7 — ProfileRegistry serialisation + +* B7a `+listProfiles+` on empty registry: 5 000 iterations +* B7b `+listProfiles+` with 1 registered profile: 5 000 iterations + +=== Current State (2026-04-04) + +* *Completion*: 100% (all 15 phases complete) +* *Tests*: 125 Zig tests across 4 suites (unit: 67, integration: 39, +smoke: 5, property: 14). All passing. +* *Benchmarks*: 15 scenarios across `+bench/bench_main.zig+`. +`+zig build bench+` wired. +* *Build step*: `+zig build test-property+` and `+zig build bench+` both +registered in `+build.zig+`. + +=== What Was Added (2026-04-03) + +==== Security Tests (server_actions.zig — 8 new tests) + +* isLocalhost edge cases: IPv6, injection strings, whitespace, case +* parseAndDispatch: invalid JSON, empty JSON, unknown action/runtime +* ActionKind integer mapping verification +* executeAction: local podman, systemd journalctl paths + +==== Config Parser Edge Cases (config_extract.zig — 11 new tests) + +* Empty/whitespace input handling +* XML self-closing and element patterns +* JSON nested object flattening, booleans, nulls +* parseAuto dispatch verification +* Secret detection for password/token/secret keys +* ParsedConfig.getField null for missing keys +* isNumeric edge cases + +==== Groove Client Tests (groove_client.zig — 4 new tests) + +* Target registry overflow (MAX_TARGETS = 8) +* Buffer truncation for oversized name/host +* TargetStatus enum completeness +* Empty name/host edge cases + +==== A2ML Tests (a2ml_emit.zig — 7 new tests) + +* applyDiff: key-value Modified/Added/Removed +* extractA2MLAttr and extractQuotedValue edge cases +* Secret redaction verification + +==== Bug Fixes + +* Fixed `+std.json.stringify+` -> `+std.json.fmt+` (Zig 0.15.2 compat) +* Fixed `+std.fs.exists+` -> `+fileExists+` helper (Zig 0.15.2 compat) +* Fixed `+std.fs.cwd().createFile+` signature (Zig 0.15.2 compat) +* Fixed broken multiline string in CLI usage text +* Fixed stack-returning helper functions (undefined behavior) +* Fixed multiple missing `+catch {}+` on writeAll calls + +=== What’s Still Missing (Post CRG-C) + +==== Ephapax / GUI Tests + +* Core: Types.eph, Capabilities.eph, Shell.eph, Bridge.eph, +GrooveClient.eph +* GUI: main.eph, 7 panel .eph files +* JavaScript: 5 bridge/glue files +* These require Ephapax compiler + Gossamer runtime + +==== Idris2 ABI Tests + +* Layout.idr postulate replaced with constructive proof (`+alignUpCeil+` ++ `+alignUpCeilIsMultiple+`) +* No compile-time Idris2 tests wired into CI yet + +==== End-to-End (E2E) with Live Services + +* [ ] Game server lifecycle: discover -> connect -> configure -> monitor +-> restart +* [ ] Panel system: load panels -> display -> interact +* [ ] Groove integration: discover services -> negotiate capabilities +* [ ] VeriSimDB integration: store -> query -> dashboard + +==== Fuzz Harness + +* No AFL/libFuzzer harness yet (placeholder removed) +* Priority targets: `+detectFormat+`, `+parseAuto+`, +`+parseA2MLProfile+` diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 991563e..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,149 +0,0 @@ -# Test & Benchmark Requirements -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Test Suite Summary - -| Suite | Count | Location | Run command | -|-------|-------|----------|-------------| -| Unit tests | 67 | `src/interface/ffi/src/*.zig` (inline `test` blocks) | `zig build test` | -| Integration tests | 39 | `src/interface/ffi/test/integration_test.zig` | `zig build test-integration` | -| Smoke tests | 5 | `src/interface/ffi/test/smoke_test.zig` | `zig build test-smoke` | -| **Property tests** | **14** | `src/interface/ffi/test/property_test.zig` | `zig build test-property` | -| **Total tests** | **125** | | | - -**Benchmarks**: 15 scenarios across 7 benchmark groups in `src/interface/ffi/bench/bench_main.zig` -Run with: `zig build bench` - -## CRG C Requirements — Status - -| Requirement | Status | Notes | -|-------------|--------|-------| -| Unit tests | DONE | 67 tests across 8 modules | -| Smoke tests | DONE | 5 end-to-end pipeline tests | -| Build | DONE | `zig build` clean (all 3 artefacts) | -| Property-based (P2P) | **DONE** | 14 invariant tests, P1–P14 | -| E2E | DONE | smoke_test.zig covers full pipeline | -| Reflexive | DONE | result code mapping, enum exhaustiveness | -| Contract | DONE | ABI integer mapping, secret redaction | -| Aspect | DONE | Security tests (command injection, injection strings) | -| Benchmarks | **DONE** | 15 scenarios, B1–B7 | - -## Property Tests Added (2026-04-04) - -File: `src/interface/ffi/test/property_test.zig` - -14 property/invariant tests covering: - -- **P1** `detectFormat` is total — never panics on any byte sequence in a 40-entry corpus -- **P2** `detectFormat` is deterministic — same input always yields same output -- **P3** `parseAuto` is total — never panics on valid or malformed inputs -- **P4** `parseAuto` field count is always >= 0 (consistent internal state) -- **P5** Config field keys are always non-empty after `addField` -- **P6** `getField` returns the exact value supplied to `addField` (insertion/lookup consistency) -- **P7** `ActionKind` values are injective — no two variants share an integer -- **P7b** `ActionKind` covers all 8 expected action types by name -- **P8** `GrooveTarget` fixed buffers never overflow on any input (clamping verified) -- **P9** `GrooveTarget` name/host round-trip for inputs that fit the buffer -- **P10** `ProfileRegistry.listProfiles` always returns valid JSON (empty or populated) -- **P11** Every inserted key is retrievable regardless of insertion order -- **P12** `field_type` is preserved exactly by `addField` (including empty string case) -- **P13** `ConfigFormat` values are injective — no two variants share a u8 value -- **P14** `parseAuto` is deterministic — two parses of the same input produce identical field lists - -## Benchmarks Added (2026-04-04) - -File: `src/interface/ffi/bench/bench_main.zig` - -15 benchmark scenarios in 7 groups: - -### B1 — Config format detection throughput -- B1a `detectFormat` small KV payload (~50 B): 100 000 iterations -- B1b `detectFormat` medium JSON payload (~300 B): 100 000 iterations -- B1c `detectFormat` large Lua payload (~2 KB): 100 000 iterations - -### B2 — parseAuto dispatch latency per format -- B2a `parseAuto` KeyValue (small): 5 000 iterations -- B2b `parseAuto` JSON (medium): 5 000 iterations -- B2c `parseAuto` Lua (large): 5 000 iterations -- B2d `parseAuto` INI (medium): 5 000 iterations -- B2e `parseAuto` XML (medium): 5 000 iterations - -### B3 — isLocalhost-equivalent batch validation -- B3 batch of ~80 addresses (including injection strings): 100 000 iterations - -### B4 & B5 — ParsedConfig field operations -- B4 `addField` × 5 fields: 5 000 iterations -- B5 `getField` × 4 lookups (best/average/worst/miss): 100 000 iterations - -### B6 — GrooveTarget buffer operations -- B6a `setName` + `setHost` + read (fits 64/256 B buffers): 100 000 iterations -- B6b Same ops with oversized strings (clamping path): 100 000 iterations - -### B7 — ProfileRegistry serialisation -- B7a `listProfiles` on empty registry: 5 000 iterations -- B7b `listProfiles` with 1 registered profile: 5 000 iterations - -## Current State (2026-04-04) - -- **Completion**: 100% (all 15 phases complete) -- **Tests**: 125 Zig tests across 4 suites (unit: 67, integration: 39, smoke: 5, property: 14). All passing. -- **Benchmarks**: 15 scenarios across `bench/bench_main.zig`. `zig build bench` wired. -- **Build step**: `zig build test-property` and `zig build bench` both registered in `build.zig`. - -## What Was Added (2026-04-03) - -### Security Tests (server_actions.zig — 8 new tests) -- isLocalhost edge cases: IPv6, injection strings, whitespace, case -- parseAndDispatch: invalid JSON, empty JSON, unknown action/runtime -- ActionKind integer mapping verification -- executeAction: local podman, systemd journalctl paths - -### Config Parser Edge Cases (config_extract.zig — 11 new tests) -- Empty/whitespace input handling -- XML self-closing and element patterns -- JSON nested object flattening, booleans, nulls -- parseAuto dispatch verification -- Secret detection for password/token/secret keys -- ParsedConfig.getField null for missing keys -- isNumeric edge cases - -### Groove Client Tests (groove_client.zig — 4 new tests) -- Target registry overflow (MAX_TARGETS = 8) -- Buffer truncation for oversized name/host -- TargetStatus enum completeness -- Empty name/host edge cases - -### A2ML Tests (a2ml_emit.zig — 7 new tests) -- applyDiff: key-value Modified/Added/Removed -- extractA2MLAttr and extractQuotedValue edge cases -- Secret redaction verification - -### Bug Fixes -- Fixed `std.json.stringify` -> `std.json.fmt` (Zig 0.15.2 compat) -- Fixed `std.fs.exists` -> `fileExists` helper (Zig 0.15.2 compat) -- Fixed `std.fs.cwd().createFile` signature (Zig 0.15.2 compat) -- Fixed broken multiline string in CLI usage text -- Fixed stack-returning helper functions (undefined behavior) -- Fixed multiple missing `catch {}` on writeAll calls - -## What's Still Missing (Post CRG-C) - -### Ephapax / GUI Tests -- Core: Types.eph, Capabilities.eph, Shell.eph, Bridge.eph, GrooveClient.eph -- GUI: main.eph, 7 panel .eph files -- JavaScript: 5 bridge/glue files -- These require Ephapax compiler + Gossamer runtime - -### Idris2 ABI Tests -- Layout.idr postulate replaced with constructive proof (`alignUpCeil` + `alignUpCeilIsMultiple`) -- No compile-time Idris2 tests wired into CI yet - -### End-to-End (E2E) with Live Services -- [ ] Game server lifecycle: discover -> connect -> configure -> monitor -> restart -- [ ] Panel system: load panels -> display -> interact -- [ ] Groove integration: discover services -> negotiate capabilities -- [ ] VeriSimDB integration: store -> query -> dashboard - -### Fuzz Harness -- No AFL/libFuzzer harness yet (placeholder removed) -- Priority targets: `detectFormat`, `parseAuto`, `parseA2MLProfile` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 63% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index aced2c1..aae1994 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,14 +1,17 @@ - - -# TOPOLOGY.md — game-server-admin +== TOPOLOGY.md — game-server-admin -## Purpose +=== Purpose -Universal game server probe, configuration management, and administration panel. Attaches to any game server, fingerprints it via protocol probing, extracts its configuration into A2ML format, and provides a rich GUI for viewing, editing, and tracking config changes with full provenance. Built on Gossamer (linearly-typed webview shell) with VeriSimDB underpinning. +Universal game server probe, configuration management, and +administration panel. Attaches to any game server, fingerprints it via +protocol probing, extracts its configuration into A2ML format, and +provides a rich GUI for viewing, editing, and tracking config changes +with full provenance. Built on Gossamer (linearly-typed webview shell) +with VeriSimDB underpinning. -## Module Map +=== Module Map -``` +.... game-server-admin/ ├── src/ │ ├── gui/ # Gossamer GUI layer (Ephapax + HTML/JS) @@ -21,14 +24,14 @@ game-server-admin/ ├── assets/ # Icons and static assets ├── docs/ # Architecture and usage docs └── game-server-admin.desktop # Linux desktop integration -``` +.... -## Data Flow +=== Data Flow -``` +.... [Game server] ──► [Protocol probe] ──► [Config extraction] ──► [A2ML format] │ [VeriSimDB storage] │ [Gossamer GUI / panels] ──► [User] -``` +.... diff --git a/USER-CONFIG.adoc b/USER-CONFIG.adoc new file mode 100644 index 0000000..33c128a --- /dev/null +++ b/USER-CONFIG.adoc @@ -0,0 +1,225 @@ +== Game Server Admin - User Configuration + +=== Overview + +The Game Server Admin (GSA) now supports user-specific configuration +through a Nickel (`+.ncl+`) configuration file. This allows you to: + +* Set a default server IP and port +* Maintain a list of favorite servers +* Customize UI preferences +* Configure connection settings + +=== Configuration File + +The user configuration is stored in `+user-config.ncl+`, which is +*gitignored* to ensure your server credentials and preferences remain +private. + +==== Initializing Configuration + +To create a default configuration file: + +[source,bash] +---- +./gsa config init +---- + +This creates `+user-config.ncl+` from the template +`+user-config.ncl.template+`. + +==== Configuration Structure + +The configuration file uses Nickel language syntax and includes the +following sections: + +[source,nickel] +---- +{ + # Default server connection + default_server = { + host = "localhost", # Hostname or IP address + port = 25565, # Port number + profile_id = "minecraft-java", # Optional: game profile ID + rcon_password = "", # Optional: RCON password + }, + + # Favorite servers list + favorites = [ + { + name = "My Minecraft Server", + host = "mc.example.com", + port = 25565, + profile_id = "minecraft-java", + rcon_password = "", + }, + # Add more favorites as needed + ], + + # UI preferences + ui = { + theme = "system", # "light", "dark", or "system" + default_panel = "gsa-browser", + show_advanced = false, + }, + + # Connection settings + connection = { + timeout_ms = 5000, # Timeout in milliseconds + max_retries = 3, # Maximum retries + verbose_logging = false, + }, + + # VeriSimDB settings + verisimdb = { + url = "http://localhost:8090", + auto_submit = true, + }, +} +---- + +=== Command Line Interface + +==== Show Current Configuration + +[source,bash] +---- +./gsa config show +---- + +Displays the current user configuration. + +==== Set Default Server + +[source,bash] +---- +./gsa config set-default +---- + +Example: + +[source,bash] +---- +./gsa config set-default mc.example.com 25565 +---- + +==== Add Favorite Server + +[source,bash] +---- +./gsa config add-favorite +---- + +Example: + +[source,bash] +---- +./gsa config add-favorite "My Minecraft" mc.example.com 25565 +./gsa config add-favorite "CS2 Server" cs2.example.com 27015 +---- + +==== List Favorite Servers + +[source,bash] +---- +./gsa config list-favorites +---- + +=== Using Configuration in the Application + +==== Default Server + +When you run commands without specifying a server, the default server +from your configuration will be used: + +[source,bash] +---- +# Uses the default server from user-config.ncl +./gsa probe +---- + +==== Favorite Servers + +Favorite servers can be quickly selected from the UI. The configuration +file stores all your favorite server connections for easy access. + +=== Security + +* `+user-config.ncl+` is *gitignored* and will never be committed to +version control +* The file is added to `+.gitignore+` to prevent accidental commits +* Sensitive information like RCON passwords should be handled with care +* The template file (`+user-config.ncl.template+`) contains no sensitive +data + +=== Best Practices + +[arabic] +. *Never commit your config*: The `+.gitignore+` file prevents this, but +double-check +. *Use strong passwords*: If storing RCON passwords, use strong, unique +passwords +. *Backup your config*: Consider backing up your config file separately +. *Review before sharing*: If sharing your project, ensure +`+user-config.ncl+` is not included + +=== Advanced Usage + +==== Manual Editing + +You can manually edit `+user-config.ncl+` to: - Add multiple favorite +servers - Customize UI preferences - Adjust connection timeouts - +Configure VeriSimDB settings + +==== Environment Variables + +The configuration system respects these environment variables: + +* `+GSA_VERISIMDB_URL+`: Override the VeriSimDB URL +* `+GSA_PROFILES_DIR+`: Override the profiles directory + +==== Integration with Profiles + +The `+profile_id+` field in server configurations should match the +`+id+` attribute in game profile files (`+.a2ml+` files in the +`+profiles/+` directory). + +=== Troubleshooting + +==== Config file not found + +[source,bash] +---- +✗ No config file found. Run `gsa config init` to create one. +---- + +Solution: Run `+./gsa config init+` to create the configuration file. + +==== File already exists + +[source,bash] +---- +✗ Config file already exists at user-config.ncl +---- + +Solution: Either edit the existing file or back it up before +re-initializing. + +==== Permission denied + +[source,bash] +---- +✗ Failed to write config: permission denied +---- + +Solution: Check file permissions and ensure you have write access. + +=== Future Enhancements + +Planned features for the configuration system: + +* Profile-specific default servers +* Server connection testing from CLI +* Import/export configuration +* Encrypted storage for sensitive data +* GUI configuration editor diff --git a/USER-CONFIG.md b/USER-CONFIG.md deleted file mode 100644 index 140e3eb..0000000 --- a/USER-CONFIG.md +++ /dev/null @@ -1,197 +0,0 @@ -# Game Server Admin - User Configuration - -## Overview - -The Game Server Admin (GSA) now supports user-specific configuration through a Nickel (`.ncl`) configuration file. This allows you to: - -- Set a default server IP and port -- Maintain a list of favorite servers -- Customize UI preferences -- Configure connection settings - -## Configuration File - -The user configuration is stored in `user-config.ncl`, which is **gitignored** to ensure your server credentials and preferences remain private. - -### Initializing Configuration - -To create a default configuration file: - -```bash -./gsa config init -``` - -This creates `user-config.ncl` from the template `user-config.ncl.template`. - -### Configuration Structure - -The configuration file uses Nickel language syntax and includes the following sections: - -```nickel -{ - # Default server connection - default_server = { - host = "localhost", # Hostname or IP address - port = 25565, # Port number - profile_id = "minecraft-java", # Optional: game profile ID - rcon_password = "", # Optional: RCON password - }, - - # Favorite servers list - favorites = [ - { - name = "My Minecraft Server", - host = "mc.example.com", - port = 25565, - profile_id = "minecraft-java", - rcon_password = "", - }, - # Add more favorites as needed - ], - - # UI preferences - ui = { - theme = "system", # "light", "dark", or "system" - default_panel = "gsa-browser", - show_advanced = false, - }, - - # Connection settings - connection = { - timeout_ms = 5000, # Timeout in milliseconds - max_retries = 3, # Maximum retries - verbose_logging = false, - }, - - # VeriSimDB settings - verisimdb = { - url = "http://localhost:8090", - auto_submit = true, - }, -} -``` - -## Command Line Interface - -### Show Current Configuration - -```bash -./gsa config show -``` - -Displays the current user configuration. - -### Set Default Server - -```bash -./gsa config set-default -``` - -Example: -```bash -./gsa config set-default mc.example.com 25565 -``` - -### Add Favorite Server - -```bash -./gsa config add-favorite -``` - -Example: -```bash -./gsa config add-favorite "My Minecraft" mc.example.com 25565 -./gsa config add-favorite "CS2 Server" cs2.example.com 27015 -``` - -### List Favorite Servers - -```bash -./gsa config list-favorites -``` - -## Using Configuration in the Application - -### Default Server - -When you run commands without specifying a server, the default server from your configuration will be used: - -```bash -# Uses the default server from user-config.ncl -./gsa probe -``` - -### Favorite Servers - -Favorite servers can be quickly selected from the UI. The configuration file stores all your favorite server connections for easy access. - -## Security - -- `user-config.ncl` is **gitignored** and will never be committed to version control -- The file is added to `.gitignore` to prevent accidental commits -- Sensitive information like RCON passwords should be handled with care -- The template file (`user-config.ncl.template`) contains no sensitive data - -## Best Practices - -1. **Never commit your config**: The `.gitignore` file prevents this, but double-check -2. **Use strong passwords**: If storing RCON passwords, use strong, unique passwords -3. **Backup your config**: Consider backing up your config file separately -4. **Review before sharing**: If sharing your project, ensure `user-config.ncl` is not included - -## Advanced Usage - -### Manual Editing - -You can manually edit `user-config.ncl` to: -- Add multiple favorite servers -- Customize UI preferences -- Adjust connection timeouts -- Configure VeriSimDB settings - -### Environment Variables - -The configuration system respects these environment variables: - -- `GSA_VERISIMDB_URL`: Override the VeriSimDB URL -- `GSA_PROFILES_DIR`: Override the profiles directory - -### Integration with Profiles - -The `profile_id` field in server configurations should match the `id` attribute in game profile files (`.a2ml` files in the `profiles/` directory). - -## Troubleshooting - -### Config file not found - -```bash -✗ No config file found. Run `gsa config init` to create one. -``` - -Solution: Run `./gsa config init` to create the configuration file. - -### File already exists - -```bash -✗ Config file already exists at user-config.ncl -``` - -Solution: Either edit the existing file or back it up before re-initializing. - -### Permission denied - -```bash -✗ Failed to write config: permission denied -``` - -Solution: Check file permissions and ensure you have write access. - -## Future Enhancements - -Planned features for the configuration system: - -- Profile-specific default servers -- Server connection testing from CLI -- Import/export configuration -- Encrypted storage for sensitive data -- GUI configuration editor diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index 8ad958e..2ca4499 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -204,8 +204,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript, Gleam -* **Tier 2** (Silver): Nickel, Guile Scheme, Nix, Idris2, OCaml +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript, Gleam +* **Tier 2** (Silver): Nickel, Guile Scheme, Guix, Idris2, OCaml * **Infrastructure**: Guix channels, derivations, Julia batch scripts === Required Files @@ -219,12 +219,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) * npm, Bun, pnpm, yarn (use Deno) diff --git a/docs/STATE-VISUALIZER.adoc b/docs/STATE-VISUALIZER.adoc index 2af3297..f60a9d9 100644 --- a/docs/STATE-VISUALIZER.adoc +++ b/docs/STATE-VISUALIZER.adoc @@ -46,7 +46,7 @@ ┌─────────────────────────────────────────┐ │ PLATFORM INTEGRATION │ │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ GitHub │ │ GitLab │ │ Nix / ││ + │ │ GitHub │ │ GitLab │ │ Guix / ││ │ │ Workflows │ │ CI/CD │ │ Guix ││ │ └───────────┘ └───────────┘ └───────┘│ └─────────────────────────────────────────┘ @@ -88,7 +88,7 @@ CONTAINER ECOSYSTEM (Phase 2) REPO INFRASTRUCTURE .machine_readable/ ██████████ 100% STATE/META/ECOSYSTEM active Governance & License ██████████ 100% PMPL & Ethical use verified - Development Shells (Nix/Guix) ██████████ 100% Reproducible env stable + Development Shells (Guix/Guix) ██████████ 100% Reproducible env stable ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% RSR Template Stable & Certified diff --git a/docs/developer/ABI-FFI-README.adoc b/docs/developer/ABI-FFI-README.adoc index b571365..467e58e 100644 --- a/docs/developer/ABI-FFI-README.adoc +++ b/docs/developer/ABI-FFI-README.adoc @@ -44,7 +44,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ ``` @@ -76,7 +76,7 @@ game-server-admin/ │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ ``` diff --git a/docs/governance/MAINTENANCE-CHECKLIST.a2ml b/docs/governance/MAINTENANCE-CHECKLIST.a2ml index eaee720..698f4d0 100644 --- a/docs/governance/MAINTENANCE-CHECKLIST.a2ml +++ b/docs/governance/MAINTENANCE-CHECKLIST.a2ml @@ -67,7 +67,7 @@ compliance-seams-check = true exception-register-required = true exception-bounded-scope-required = true policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad ReScript->TypeScript migration" +example-drift-risk = "single TypeScript exception causing broad AffineScript->TypeScript migration" compliance-tooling = "panic-attack" effects-tooling = "ecological checking with sustainabot guidance" diff --git a/docs/maintainer/CI-CD-GUIDE.adoc b/docs/maintainer/CI-CD-GUIDE.adoc index 4f181ad..162ef37 100644 --- a/docs/maintainer/CI-CD-GUIDE.adoc +++ b/docs/maintainer/CI-CD-GUIDE.adoc @@ -98,7 +98,7 @@ contents (not inferred from the name). | push to `main`/`master`, PR (any), manual dispatch | Single wrapper call into the estate `governance-reusable.yml`. Replaces eight per-repo governance workflows removed in the same commit (quality, - guix/nix policy, npm/bun blocker, ts blocker, security policy, RSR + guix/guix policy, npm/bun blocker, ts blocker, security policy, RSR anti-pattern, well-known enforcement, workflow linter) — those checks now live centrally in `standards`. diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc index 7cad894..c49a724 100644 --- a/docs/practice/AI-CONVENTIONS.adoc +++ b/docs/practice/AI-CONVENTIONS.adoc @@ -53,7 +53,7 @@ MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the reposit | Banned | Use Instead | |---------------------|--------------------| -| TypeScript | ReScript | +| TypeScript | AffineScript | | Node.js / npm / bun | Deno | | Go | Rust | | Python | Julia / Rust | diff --git a/docs/wikis/08-Deployment-Topology.md b/docs/wikis/08-Deployment-Topology.md index 885ca02..ebb2c3e 100644 --- a/docs/wikis/08-Deployment-Topology.md +++ b/docs/wikis/08-Deployment-Topology.md @@ -97,9 +97,9 @@ It expects `gsa-verisimdb` reachable on `:8090` (override with | `container/compose.toml`, `compose.example.toml` | compose reference (quadlets are canonical) | | `container/deploy.k9.ncl` | Nickel deployment descriptor | -## Nix / Guix +## Guix / Guix -Both `flake.nix` and `guix.scm` carry **real** build/install phases (not stubs), +Both `flake.guix` and `guix.scm` carry **real** build/install phases (not stubs), so GSA can also be built reproducibly outside containers. ## Reality check diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..64e91cb --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — game-server-admin (Developer) + +=== What is game-server-admin? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: AGPL-3.0-or-later +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 439ba4d..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — game-server-admin (Developer) - -## What is game-server-admin? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: AGPL-3.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..1013af9 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — game-server-admin (User) + +=== What is game-server-admin? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: AGPL-3.0-or-later +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 2727ea2..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — game-server-admin (User) - -## What is game-server-admin? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: AGPL-3.0-or-later -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/tests/fuzz/README.adoc b/tests/fuzz/README.adoc new file mode 100644 index 0000000..bcf30ce --- /dev/null +++ b/tests/fuzz/README.adoc @@ -0,0 +1,18 @@ +== Fuzz Testing + +Fuzz harnesses for Game Server Admin are not yet implemented. + +=== Planned Targets + +* A2ML parser (`+a2ml_emit.parseA2ML+`) — malformed A2ML input +* Config format detection (`+config_extract.detectFormat+`) — arbitrary +byte sequences +* Game profile parser (`+game_profiles.parseA2MLProfile+`) — malformed +profile A2ML +* Lua config parser (`+config_extract.parseLua+`) — adversarial Lua +table syntax + +=== Status + +No fuzz harness exists yet. The previous `+placeholder.txt+` was removed +as it created a false impression of fuzz coverage. diff --git a/tests/fuzz/README.md b/tests/fuzz/README.md deleted file mode 100644 index 18585f5..0000000 --- a/tests/fuzz/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Fuzz Testing - -Fuzz harnesses for Game Server Admin are not yet implemented. - -## Planned Targets - -- A2ML parser (`a2ml_emit.parseA2ML`) — malformed A2ML input -- Config format detection (`config_extract.detectFormat`) — arbitrary byte sequences -- Game profile parser (`game_profiles.parseA2MLProfile`) — malformed profile A2ML -- Lua config parser (`config_extract.parseLua`) — adversarial Lua table syntax - -## Status - -No fuzz harness exists yet. The previous `placeholder.txt` was removed as it -created a false impression of fuzz coverage.