META.scm

;; SPDX-License-Identifier: PMPL-1.0-or-later
;; META.scm — Meta-level information for IDApTIK monorepo
;; Media Type: application/meta+scheme
(meta
  (version "1.1.0")
  (last-updated "2026-02-27")

  (architecture-decisions
    (adr "ADR-001"
      (title "Monorepo consolidation")
      (status accepted)
      (date "2026-02-20")
      (context "IDApixiTIK, idaptiky, idaptik-level-architect, idaptik-developers were separate repos and partially in games & trivia monorepo")
      (decision "Consolidate all IDApTIK components into single idaptik monorepo")
      (consequences "Simplified CI/CD, shared git history, easier cross-component refactoring"))

    (adr "ADR-002"
      (title "ReScript as primary language")
      (status accepted)
      (date "2026-02-20")
      (context "Game engine needs type safety without TypeScript overhead")
      (decision "Use ReScript for all game logic, compile to JS, run on Deno")
      (consequences "Strong types, pattern matching, no TypeScript allowed"))

    (adr "ADR-003"
      (title "Reversible computation model")
      (status accepted)
      (date "2025-11-01")
      (context "Game puzzles require undo/redo of arbitrary instruction sequences")
      (decision "Every VM instruction has a provably correct inverse; state changes are fully reversible")
      (consequences "Enables puzzle mechanics, time-travel debugging, deterministic replay"))

    (adr "ADR-004"
      (title "Idris2 ABI for level architect")
      (status accepted)
      (date "2026-01-30")
      (context "Level editor needs formally verified interface between Tauri frontend and GPU engine")
      (decision "Use Idris2 dependent types for ABI definitions, Zig for FFI implementation")
      (consequences "Provable correctness of game engine interfaces, cross-platform ABI"))

    (adr "ADR-005"
      (title "Interactive puzzle REPL")
      (status accepted)
      (date "2026-02-20")
      (context "Puzzle system had 27 puzzles but no interactive solving mode")
      (decision "Build synchronous REPL using Deno prompt() with undo, hints, scoring")
      (consequences "Players can solve puzzles interactively with immediate feedback"))

    (adr "ADR-006"
      (title "Scripting complexity: sidebar list for MVP")
      (status proposed)
      (date "2026-02-20")
      (context "Level architect needs device behaviour scripting")
      (decision "Sidebar rule list for MVP, visual graph editor deferred to v2")
      (consequences "Faster MVP, forward-compatible data model"))

    (adr "ADR-007"
      (title "VeriSimDB temporal modalities")
      (status proposed)
      (date "2026-02-20")
      (context "Time-travel level design could leverage VeriSimDB modal queries")
      (decision "Optional per-level toggle, gated behind time-travel mode")
      (consequences "Core gameplay unblocked, temporal features additive"))

    (adr "ADR-008"
      (title "Guard intelligence: static patrols + elite heat maps")
      (status proposed)
      (date "2026-02-20")
      (context "Guard NPCs need alert response AI")
      (decision "Static patrols for most guards, heat map AI for elite guards only")
      (consequences "Predictable base gameplay, tension in high-security zones"))

    (adr "ADR-009"
      (title "VM expansion roadmap: 5-tier plan from puzzles to multiplayer")
      (status accepted)
      (date "2026-02-20")
      (context "VM is 85% as a puzzle engine but has no game integration; needs conditionals, stack, I/O, multi-VM")
      (decision "Expand in 5 tiers: conditionals, stack/memory, subroutines, I/O channels, multi-VM networking")
      (consequences "VM becomes central game mechanic, each tier independently shippable"))

    (adr "ADR-010"
      (title "Monorepo restructure: vm/ + dlc/ + main-game/")
      (status accepted)
      (date "2026-02-20")
      (context "idaptiky mixes VM core with puzzle content; IDApixiTIK name is confusing; VM should be shared dependency")
      (decision "Split into vm/ (pure library), dlc/idaptik-reversible/ (puzzles), main-game/ (browser), keep level-architect and developers")
      (consequences "Clear structure, VM reusable across components, DLC puzzle packs as content delivery"))

    (adr "ADR-011"
      (title "Reversibility as core gameplay mechanic")
      (status accepted)
      (date "2026-02-20")
      (context "Reversible computation is an academic VM property but not yet a gameplay mechanic")
      (decision "Three modes: puzzle (tutorial), hack/defend (core — undo IS defence), co-op asymmetric (endgame)")
      (consequences "Unique selling point: reversibility as competitive multiplayer; teaches CS through play"))

    (adr "ADR-012"
      (title "Hardware wiring challenges: physical device interaction")
      (status accepted)
      (date "2026-02-20")
      (context "Game has platforming and terminal hacking but no physical hardware manipulation; Barotrauma's junction box wiring is a proven mechanic")
      (decision "Five challenge types: patch panel rewiring, switch backplane, server rack, fibre splicing, PBX/comms; integrated with PowerManager, NetworkManager, FirewallDevice")
      (consequences "Third interaction pillar; visual/spatial gameplay complements terminal hacking; difficulty progression copper→fibre; hardware changes are reversible too"))

    (adr "ADR-013"
      (title "Inventory system: strict items with difficulty scaling")
      (status accepted)
      (date "2026-02-20")
      (context "Hardware wiring challenges need physical items; unlimited inventory undermines tension; Gunpoint's minimal tool list and Barotrauma's resource scarcity are proven models")
      (decision "Strict slot-based inventory with 3 difficulty tiers: universal cables (easy), typed cables with limited supplies (normal), everything in-game with opportunity cost (expert)")
      (consequences "Resource management layer atop hardware puzzles; pulling cables from devices creates cascading failures; multiplayer item-passing deepens co-op"))

    (adr "ADR-014"
      (title "Bebop connections: hidden high-speed network pathways")
      (status accepted)
      (date "2026-02-20")
      (context "Multi-hop routing is slow and monitored; real networks have hidden infrastructure (dark fibre, OOB management, legacy trunks); game needs exploration rewards and tactical shortcuts")
      (decision "Discoverable, activatable network edges that serve four functions: network shortcut (skip hops), stealth channel (bypass monitoring), power-up/collectible (exploration reward), and strategic level design objective. Seven connection types with distinct properties. VM integration via bebop: port prefix on SEND/RECV. Co-op requires physical+terminal activation.")
      (consequences "New overlay map system, new discovery mechanics, natural co-op objectives, level designer tool for multiple solution paths, difficulty scaling from marked-on-map to decoy honeypots"))

    (adr "ADR-015"
      (title "Platform support matrix: where IDApTIK runs")
      (status accepted)
      (date "2026-02-20")
      (context "Three deliverables (browser game, TUI, Tauri desktop) each have different platform constraints; need to define what we support vs best-effort vs exclude")
      (decision "Three-tier support model: Tier 1 (Linux/macOS/Windows x86_64+aarch64 — CI tested, release binaries), Tier 2 (ChromeOS, RISC-V, BSDs, SteamOS, mobile — community tested), Tier 3 (Minix, Haiku, Redox, Plan 9 — no support). Tauri 2 shell for native desktop. Container images for all deployable components.")
      (consequences "5 Tier 1 CI builds, 10 release artifacts, Tauri desktop wrapper as Phase 1 native target, RISC-V welcome but non-blocking, mobile as stretch goal"))

    (adr "ADR-016"
      (title "Multiplayer architecture: reversible co-op networking")
      (status accepted)
      (date "2026-02-20")
      (context "Multiplayer must deeply integrate with the reversible VM rather than being a superficial overlay. Traditional multiplayer suffers from desync, latency, shallow cooperation, cheating, and brutal reconnection")
      (decision "Phoenix Channels over WebSocket with pure ReScript client. Per-device VM instances with Lamport-clock causal ordering. Asymmetric roles (hacker/observer). Competitive undo with device locking. Cross-VM messaging via SEND/RECV ports. State serialisation for lossless reconnection. No consensus protocol needed — Horde shards sessions across nodes.")
      (consequences "Deeply integrated multiplayer, deterministic VM eliminates desync, genuine asymmetric cooperation, cheat resistance through VM verification, lossless reconnection via state serialisation"))

    (adr "ADR-017"
      (title "Device defence mechanics for level design")
      (status accepted)
      (date "2026-02-20")
      (context "Devices are passive targets; hackers face no traps, deception, or resistance. UPS can be trivially killed. No time pressure or instruction restrictions exist.")
      (decision "11 device defence flags: tamperProof, decoy, canary, oneWayMirror, killSwitch, failoverTarget, cascadeTrap, instructionWhitelist, timeBomb, mirrorTarget, undoImmunity. Set per-device in level JSON. Difficulty scaling from none (easy) to full suite (expert).")
      (consequences "11 new level-design toggles, UPS exploit fixed, reconnaissance required, VM restrictions create puzzle constraints, time pressure without artificial timers, zero impact on existing levels"))

    (adr "ADR-018"
      (title "Enemy hierarchy: guard ranks, specialists, and independent threats")
      (status accepted)
      (date "2026-02-20")
      (context "Two-tier guard system (ADR-0004) insufficient for varied gameplay. Need guard diversity, specialist anti-hackers as ONLY entities that can reverse-hack, competitor NPCs, and mysterious independent threats.")
      (decision "8-rank enemy hierarchy in 4 categories: security (BasicGuard, SecurityGuard, Sentinel, EliteGuard, SecurityChief), specialist (AntiHacker — ONLY reverser, cowardly, panics, flees mid-reversal), competitor (RivalHacker — races to complete objectives, sabotages player), unknown (Assassin — appears from hiding, deadly ambush, sets traps). SENTRY becomes dispatch coordinator — cannot undo without anti-hackers.")
      (consequences "Rich enemy diversity, anti-hacker management as core strategy, rival adds time pressure, assassin adds unpredictable tension, SENTRY neutered if all specialists flee")))

    (adr "ADR-019"
      (title "Coprocessor consolidation: 10 files to 3")
      (status accepted)
      (date "2026-02-27")
      (context "10 individual coprocessor backend files (Crypto, Maths, Vector, Tensor, Physics, Neural, Quantum, Audio, Graphics, IO) duplicated open/module/registration boilerplate; scattered across 4 build directories creating 36 stale copies")
      (decision "Consolidate by concern: Coprocessor_Compute.res (Maths+Vector+Tensor+Physics), Coprocessor_Security.res (Crypto+Neural+Quantum+Audio+Graphics), Coprocessor_IO.res (unchanged, per-device stateful). Each old file becomes a nested module. Coprocessor_Backends.res rewritten to use nested paths.")
      (consequences "3 files instead of 10; zero functionality change; cleaner imports; easier contributor onboarding; mirrors IDApTIK's 3-domain grouping (Compute, Security, IO)"))

    (adr "ADR-020"
      (title "Language stack finalization: 5 languages only")
      (status accepted)
      (date "2026-02-27")
      (context "Stack had accumulated V-lang (redundant web server), Chapel (heavy HPC runtime for simple parallel solvers), and Dragonfly (external cache when ETS is native to BEAM)")
      (decision "Final stack: ReScript (UI), Idris2 (ABI), Zig (FFI+solvers), Elixir (APIs+sync), Rust (Tauri shell). V-lang, Chapel, Dragonfly removed.")
      (consequences "5-language stack with clear separation; no redundant tools; contributors only need ReScript for game work; Elixir's BEAM provides caching natively (ETS/DETS)"))

    (adr "ADR-021"
      (title "AI-generated code audit: delete-on-discovery policy")
      (status accepted)
      (date "2026-02-27")
      (context "Multiple AI assistants (Gemini, Copilot) generated dead code from casual conversation — PATAOrchestrator, ConsensusCore, BondingHandler, PressureMonitor, ControlChannel — none of which was reviewed or requested")
      (decision "Delete all AI-generated dead code immediately on discovery. No attempt to salvage or refactor. Verify references are cleaned from supervisors, routers, and config files.")
      (consequences "Cleaner codebase; establishes that AI code must be reviewed before merging; prevents accumulation of confabulated features"))

  (development-practices
    (practice "All ReScript, no TypeScript or raw JavaScript")
    (practice "Deno runtime exclusively, no Node/npm/bun")
    (practice "Just as task runner for all build/test/run recipes")
    (practice "PMPL-1.0-or-later license on all original code")
    (practice "SCM checkpoint files in .machine_readable/ only")
    (practice "AI manifest (0-AI-MANIFEST.a2ml) as entry point for agents"))

  (design-rationale
    (rationale "asymmetric-coop"
      (summary "Asymmetric co-op gameplay where players have different abilities and views")
      (detail "One player sees the network topology, the other controls the reversible VM. Cooperation required to solve puzzles."))
    (rationale "stealth-puzzle-hybrid"
      (summary "Combines stealth mechanics with logic puzzles")
      (detail "Players must avoid detection while solving reversible computation challenges. Adaptive AI adjusts difficulty based on performance."))
    (rationale "reversibility-as-gameplay"
      (summary "Every VM operation's inverse creates emergent tactical depth")
      (detail "Undo IS the defence mechanic. Admin doesn't need to know what attacker did — just undoes everything since breach. But SWAP+ADD undo ordering creates exploitable state differences. This makes reversibility a competitive advantage, not just an academic property."))
    (rationale "vm-as-shared-engine"
      (summary "VM is a reusable library consumed by game, puzzles, level editor, and sync server")
      (detail "The VM should be importable by any component. Game loads puzzles from DLC packs. Level architect validates levels against VM. Sync server mediates multi-VM state. This requires the vm/ restructure.")))

  (vm-expansion-tiers
    (tier 0 (name "Register-based arithmetic") (status "90%") (instructions 13) (note "ADD SUB SWAP NEGATE NOOP XOR FLIP ROL ROR AND OR MUL DIV + game bridge"))
    (tier 1 (name "Conditional execution") (status "90%") (instructions 3) (note "IF_ZERO, IF_POS, LOOP — Janus-style reversible branches — IMPLEMENTED"))
    (tier 2 (name "Stack and memory") (status "90%") (instructions 4) (note "PUSH, POP, LOAD, STORE — Janus-style reversible stack + additive memory — IMPLEMENTED"))
    (tier 3 (name "Subroutines") (status "90%") (instructions 1) (note "CALL + SubroutineRegistry — compound reversal of full body — IMPLEMENTED"))
    (tier 4 (name "I/O channels") (status "90%") (instructions 2) (note "SEND, RECV — port buffer system for game device integration — IMPLEMENTED"))
    (tier 5 (name "Multi-VM networking") (status "0%") (note "Per-device VM instances, instruction injection, competitive undo — deferred to Section 3")))

  (completed-restructure
    (status completed)
    (date "2026-02-20")
    (layout "vm/ shared/ dlc/idaptik-reversible/ main-game/ escape-hatch/ containers/ idaptik-ums/ idaptik-developers/")
    (rationale "Separate VM core from puzzle content; shared types; containerized deployment; developer TUI portal"))

  (infrastructure
    (containers
      (image "idaptik-game" (base "cgr.dev/chainguard/nginx:latest") (port 8080) (note "Static browser game; 19.9 MB; immutable cache headers, SPA fallback, gzip"))
      (image "idaptik-escape-hatch" (base "cgr.dev/chainguard/wolfi-base:latest") (note "TUI — requires -it flag; Podman subprocess integration"))
      (image "idaptik-sync" (base "cgr.dev/chainguard/wolfi-base:latest") (port 4000) (note "Elixir OTP release; ETS cache (no external deps)")))
    (orchestration "podman-compose.yml" (services "game sync") (note "escape-hatch runs separately"))
    (dlc-bundler "shared/scripts/bundle-puzzles.js" (note "Build-time: scans DLC dir → main-game/src/generated/puzzle-bundle.json")))

  (platform-support
    (target "browser" (status "primary") (note "main-game/ — any modern browser with WebGL2"))
    (target "linux" (status "supported") (note "escape-hatch TUI + containers"))
    (target "macos" (status "supported") (note "escape-hatch TUI + containers"))
    (target "windows" (status "supported") (note "escape-hatch TUI + containers via WSL/Podman"))
    (target "chromeos" (status "supported") (note "Browser game works natively; TUI via Linux container"))))