1  ;; SPDX-License-Identifier: AGPL-3.0-or-later
  2  ;; SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell
  3  ;;
  4  ;; Reposystem Meta-Level Information
  5  ;; ==================================
  6  ;; Philosophy, governance, architectural decisions
  7  
  8  (define-module (reposystem meta)
  9    #:export (meta-info architecture-decisions development-practices))
 10  
 11  (define meta-info
 12    '((media-type . "application/meta+scheme")
 13      (version . "1.0")
 14      (project . "reposystem")))
 15  
 16  (define architecture-decisions
 17    '(;; ADR-001: Railway Yard Mental Model
 18      ((id . "adr-001")
 19       (title . "Railway Yard Mental Model")
 20       (status . "accepted")
 21       (date . "2025-12-31")
 22       (context . "Need intuitive model for multi-repo component wiring that supports visual representation and switching between providers")
 23       (decision . "Adopt railway yard metaphor: repos as yards, edges as tracks, switches as points")
 24       (consequences
 25        (positive
 26         ("Intuitive visual representation"
 27          "Natural fit for switching semantics"
 28          "Supports contingency/fallback routing"))
 29        (negative
 30         ("May need to explain metaphor to new users"))))
 31  
 32      ;; ADR-002: Aspect Tagging as Orthogonal Layer
 33      ((id . "adr-002")
 34       (title . "Aspect Tagging as Orthogonal Layer")
 35       (status . "accepted")
 36       (date . "2025-12-31")
 37       (context . "Need to view graph through multiple lenses (security, reliability, etc.) without restructuring")
 38       (decision . "Implement aspects as annotations on existing graph, not separate graphs")
 39       (consequences
 40        (positive
 41         ("Single source of truth for structure"
 42          "Flip views without losing context"
 43          "Composable - multiple aspects per node/edge"))
 44        (negative
 45         ("More complex query model"))))
 46  
 47      ;; ADR-003: Scenarios as Deltas, Not Copies
 48      ((id . "adr-003")
 49       (title . "Scenarios as Deltas, Not Full Copies")
 50       (status . "accepted")
 51       (date . "2025-12-31")
 52       (context . "Need A/B testing of configurations without duplicating entire graph")
 53       (decision . "Scenarios are ChangeSets of operations applied to baseline graph")
 54       (consequences
 55        (positive
 56         ("Minimal storage"
 57          "Clear diff between scenarios"
 58          "Baseline remains immutable"))
 59        (negative
 60         ("Must compute derived graph on demand"))))
 61  
 62      ;; ADR-004: Manual-First, Guarded Automation
 63      ((id . "adr-004")
 64       (title . "Manual-First, Guarded Automation")
 65       (status . "accepted")
 66       (date . "2025-12-31")
 67       (context . "Auto-detection of dependencies can create invisible/unexplained edges")
 68       (decision . "Manual edges are truth; auto-detection only proposes with evidence")
 69       (consequences
 70        (positive
 71         ("Every edge is explainable"
 72          "User maintains control"
 73          "No surprise connections"))
 74        (negative
 75         ("More initial setup effort"
 76          "May miss some connections"))))
 77  
 78      ;; ADR-005: ReScript + Deno, Rust CLI
 79      ((id . "adr-005")
 80       (title . "ReScript Core with Rust CLI")
 81       (status . "accepted")
 82       (date . "2025-12-31")
 83       (context . "Need type-safe core logic with fast cross-platform CLI")
 84       (decision . "ReScript for core data model/logic, Rust for CLI, Deno as runtime")
 85       (consequences
 86        (positive
 87         ("Type safety from ReScript"
 88          "Fast CLI from Rust"
 89          "No Node.js/npm dependencies"))
 90        (negative
 91         ("Two-language boundary to manage"))))
 92  
 93      ;; ADR-006: DOT + JSON as Primary Export Formats
 94      ((id . "adr-006")
 95       (title . "DOT and JSON as Primary Export Formats")
 96       (status . "accepted")
 97       (date . "2025-12-31")
 98       (context . "Need interoperability with visualization tools and other systems")
 99       (decision . "Export to Graphviz DOT for visualization, JSON for machine consumption")
100       (consequences
101        (positive
102         ("Wide tooling support"
103          "Human-readable DOT"
104          "Machine-parseable JSON"))
105        (negative
106         ("Must maintain two exporters"))))))
107  
108  (define development-practices
109    '((code-style
110       (languages . (rescript rust guile-scheme nickel))
111       (formatter . "deno fmt for JS, rustfmt for Rust")
112       (linter . "deno lint, clippy"))
113  
114      (security
115       (supply-chain . "pin all dependencies")
116       (secrets . "never commit secrets")
117       (permissions . "explicit workflow permissions"))
118  
119      (testing
120       (unit . "per-module tests")
121       (integration . "end-to-end CLI tests")
122       (property . "consider for graph invariants"))
123  
124      (versioning
125       (scheme . "semver")
126       (breaking-changes . "major version bump")
127       (changelog . "keep-a-changelog format"))
128  
129      (documentation
130       (format . "asciidoc")
131       (api-docs . "generated from source")
132       (examples . "in docs/examples/"))
133  
134      (branching
135       (main . "stable, always green")
136       (feature . "feature/* branches")
137       (release . "tag-based releases"))))
138  
139  (define design-rationale
140    '((why-railway-yard
141       "The railway yard metaphor provides intuitive understanding of how repos connect
142        and how traffic (data, artifacts, control) flows between them. Switches at
143        junctions make the substitution model concrete and visual.")
144  
145      (why-aspect-tagging
146       "Traditional dependency graphs show structure but not meaning. Aspect tagging
147        adds the 'why does this matter' layer, enabling focused views for security
148        review, reliability analysis, or supply chain audit.")
149  
150      (why-scenarios-not-branches
151       "Git branches are for code versions. Scenarios are for configuration variants.
152        You want to compare 'what if I used my container runtime vs theirs' without
153        creating git branches everywhere.")
154  
155      (why-manual-first
156       "LLM-assisted detection is powerful but opaque. By requiring manual confirmation
157        of all edges, we ensure the graph remains a governance tool, not a guess.")))