feat: self-model, paper alignment notes, Mermaid architecture, marimo notebook

docs/index.md

@@ -65,28 +65,52 @@ Install just what you need: `uv add gds-core[control,continuous]`
 
 ## Architecture
 
+```mermaid
+graph TD
+    classDef core fill:#e0e7ff,stroke:#4f46e5,stroke-width:2px,color:#1e1b4b
+    classDef dsl fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#78350f
+    classDef sim fill:#d1fae5,stroke:#059669,stroke-width:2px,color:#064e3b
+    classDef tool fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px,color:#4c1d95
+    classDef ext fill:#e5e7eb,stroke:#6b7280,stroke-width:1px,color:#374151
+
+    FW["gds-framework<br/><small>core engine (pydantic only)</small>"]:::core
+
+    VIZ["gds-viz<br/><small>Mermaid + phase portraits</small>"]:::tool
+    OWL["gds-owl<br/><small>OWL / SHACL / SPARQL</small>"]:::tool
+
+    GAMES["gds-games<br/><small>game theory DSL</small>"]:::dsl
+    SF["gds-stockflow<br/><small>stock-flow DSL</small>"]:::dsl
+    CTRL["gds-control<br/><small>control systems DSL</small>"]:::dsl
+    SW["gds-software<br/><small>software architecture DSL</small>"]:::dsl
+    BIZ["gds-business<br/><small>business dynamics DSL</small>"]:::dsl
+
+    SYM["gds-symbolic<br/><small>SymPy + Hamiltonian</small>"]:::tool
+    EX["gds-examples<br/><small>tutorials + notebooks</small>"]:::ext
+
+    SIM["gds-sim<br/><small>discrete-time simulation</small>"]:::sim
+    AN["gds-analysis<br/><small>reachability + metrics</small>"]:::sim
+    PSUU["gds-psuu<br/><small>parameter sweep</small>"]:::sim
+
+    CONT["gds-continuous<br/><small>ODE engine (scipy)</small>"]:::sim
+
+    FW --> VIZ
+    FW --> OWL
+    FW --> GAMES
+    FW --> SF
+    FW --> CTRL
+    FW --> SW
+    FW --> BIZ
+    CTRL --> SYM
+    FW --> EX
+    VIZ --> EX
+
+    FW --> AN
+    SIM --> AN
+    SIM --> PSUU
+    CONT --> AN
 ```
-gds-framework  ←  core engine (pydantic only)
-    ↑
-    ├── gds-viz        ←  Mermaid diagrams + phase portraits [matplotlib]
-    ├── gds-games      ←  game theory DSL + Nash equilibrium [nashpy]
-    ├── gds-stockflow  ←  stock-flow DSL
-    ├── gds-control    ←  control systems DSL
-    ├── gds-software   ←  software architecture DSL
-    ├── gds-business   ←  business dynamics DSL (CLD, SCN, VSM)
-    └── gds-owl        ←  OWL/SHACL/SPARQL export (rdflib, pyshacl)
-         ↑
-    gds-symbolic       ←  SymPy bridge (extends gds-control) [sympy]
-         ↑
-    gds-examples       ←  tutorials (depends on most DSLs + viz)
-
-gds-sim            ←  discrete-time simulation (standalone, pydantic only)
-    ↑
-    ├── gds-analysis   ←  spec→sim bridge, reachability
-    └── gds-psuu       ←  parameter sweep + Optuna
-
-gds-continuous     ←  continuous-time ODE engine (standalone) [scipy]
-```
+
+**Legend:** :blue_square: Core | :yellow_square: Domain DSLs | :green_square: Simulation & Analysis | :purple_square: Tooling
 
 ## License
 

docs/research/formal-representability.md

@@ -118,6 +118,14 @@ specifications: you can represent everything about a system except what
 its programs actually do. The canonical decomposition h = f ∘ g makes this
 boundary explicit and exploitable.
 
+> **Paper alignment note.** Rice's theorem applies here because the
+> *software implementation* uses arbitrary Python callables for f_behav.
+> The paper's mathematical proofs (Theorem 3.6, existence) assume the
+> constraint set is compact, convex, and continuous (Assumption 3.5) —
+> a much more restricted class than Turing-complete programs. The R3
+> boundary reflects the implementation's scope, not the paper's
+> mathematical scope.
+
 ---
 
 ## 1. Preliminaries
@@ -132,6 +140,14 @@ construction, but the full categorical axioms (interchange law, coherence
 conditions, traced monoidal structure for feedback) have not been formally
 verified.
 
+> **Paper alignment note.** The foundational paper (Zargham & Shorish 2022)
+> defines GDS via standard function composition h(x) = f(x, g(x)) and does
+> not mandate categorical structure. The paper explicitly contrasts ACT
+> (Applied Category Theory) with GDS, noting ACT "can be difficult to
+> implement computationally." The categorical semantics here are a
+> *framework design choice* for compositionality, not a mathematical
+> requirement of the paper's GDS definition.
+
 The components are:
 
 - **Objects** are Interfaces: I = (F_in, F_out, B_in, B_out), each a tuple
@@ -516,6 +532,13 @@ semantics (what h actually computes given inputs) is R3.
 pattern).** An AdmissibleInputConstraint (Paper Def 2.5: U_x) decomposes
 as:
 
+> **Paper alignment note.** The paper defines the Admissible Input Map as
+> a single function U: X -> P(U) (Def 2.5) with no structural/behavioral
+> decomposition. The split below into U_x_struct (dependency graph) and
+> U_x_behav (constraint predicate) is a *framework design choice* for
+> ontological representation, enabling the dependency graph to be
+> serialized as R1 while the predicate remains R3.
+
 ```
 U_x_struct : A -> P(E x V)
     The dependency relation: "BoundaryAction B's admissible outputs
@@ -538,6 +561,11 @@ is a BoundaryAction, depends_on references valid entity.variable pairs).
 **Property 4.6 (Transition Signatures follow the same pattern).**
 A TransitionSignature (Paper Def 2.7: f|_x) provides:
 
+> **Paper alignment note.** The paper defines f|_x : U_x -> X (Def 2.7) as
+> a single restricted map. The decomposition into f_read (which variables
+> are read) and f_block_deps (which blocks feed this mechanism) is a
+> *framework design choice* to capture data-flow dependencies structurally.
+
 ```
 f_read : Sig -> P(E x V)
     The read dependency relation: "Mechanism M reads Entity E variable V."
@@ -643,7 +671,7 @@ G_struct concepts and their tiers:
 - Space/entity structure: R1 (Property 4.1)
 - Admissibility dependency graph (U_x_struct): R1 (Property 4.5)
 - Transition read dependencies (f_read): R1 (Property 4.6)
-- State metric variable declarations (d_X_struct): R1 (Assumption 3.2)
+- State metric variable declarations (d_X_struct): R1 (Assumption 3.2) [*]
 - Acyclicity: R2 (Section 5.1, G-006)
 - Completeness/determinism: R2 (Section 5.2, SC-001, SC-002)
 - Reference validation (dangling wirings): R2 (Section 5.1, G-004)
@@ -652,8 +680,14 @@ G_behav concepts and their tiers:
 - Transition functions: R3 (Property 4.4, f_behav)
 - Constraint predicates: R3 (Property 4.2, general case)
 - Admissibility predicates (U_x_behav): R3 (Property 4.5)
-- State metric distance callable (d_X_behav): R3 (Assumption 3.2)
+- State metric distance callable (d_X_behav): R3 (Assumption 3.2) [*]
 - Auto-wiring process: R3 (Property 3.2)
+
+> [*] **Paper alignment note.** The paper defines d_X : X x X -> R
+> (Assumption 3.2) as a single metric with no structural/behavioral
+> decomposition. The split into variable declarations (R1) and distance
+> callable (R3) follows the same framework pattern as Properties 4.5-4.6
+> — an ontological design choice, not a paper requirement.
 - Construction validation: R3 (Proposition 3.4)
 - Scheduling semantics: R3 (not stored in GDSSpec — external)
 

packages/gds-examples/software/gds_ecosystem/dfd_pipeline.py

@@ -0,0 +1,195 @@
+"""GDS User Pipeline — modeled as a Data Flow Diagram.
+
+Models the actual data transformation pipeline a user follows:
+User → define spec → compile → verify → export to OWL → simulate → analyze
+
+This DFD reveals the data flows between GDS subsystems and identifies
+where data transforms (processes) vs where it persists (data stores).
+
+GDS Decomposition:
+    X  = {GDSSpec, SystemIR, VerificationReport, RDFGraph, Trajectory}
+    U  = {User, DSL Definitions}
+    g  = {Compile, Verify, Export, Adapt}
+    f  = {Simulate, Analyze} (state-updating processes)
+"""
+
+from gds import project_canonical, verify
+from gds.ir.models import SystemIR
+from gds.spec import GDSSpec
+from gds_software.dfd.compile import compile_dfd, compile_dfd_to_system
+from gds_software.dfd.elements import DataFlow, DataStore, ExternalEntity, Process
+from gds_software.dfd.model import DFDModel
+from gds_viz import system_to_mermaid
+
+
+def build_dfd_model() -> DFDModel:
+    """Build the GDS user pipeline as a DFD."""
+    return DFDModel(
+        name="GDS User Pipeline",
+        description="Data flow through the GDS ecosystem from spec to analysis",
+        external_entities=[
+            ExternalEntity(name="User", description="Modeler defining a system"),
+            ExternalEntity(
+                name="DSL",
+                description="Domain-specific language (stockflow, control, etc.)",
+            ),
+        ],
+        processes=[
+            Process(
+                name="Register Spec",
+                description="Build GDSSpec from types, entities, blocks, wirings",
+            ),
+            Process(
+                name="Compile",
+                description="Flatten composition tree to SystemIR",
+            ),
+            Process(
+                name="Verify",
+                description="Run G-001..G-006 + SC-001..SC-009 checks",
+            ),
+            Process(
+                name="Export to OWL",
+                description="Serialize GDSSpec to RDF/Turtle via gds-owl",
+            ),
+            Process(
+                name="Adapt to Sim",
+                description="Bridge spec to gds-sim Model via gds-analysis",
+            ),
+            Process(
+                name="Simulate",
+                description="Execute trajectories via gds-sim or gds-continuous",
+            ),
+            Process(
+                name="Analyze",
+                description="Compute reachability, metrics, distances",
+            ),
+        ],
+        data_stores=[
+            DataStore(name="GDSSpec Store", description="Structural specification"),
+            DataStore(name="SystemIR Store", description="Flat IR"),
+            DataStore(name="RDF Graph", description="OWL/Turtle serialization"),
+            DataStore(name="Trajectory Store", description="Simulation results"),
+        ],
+        data_flows=[
+            # User inputs
+            DataFlow(
+                name="types + entities",
+                source="User",
+                target="Register Spec",
+                data="TypeDefs, Entities, Blocks",
+            ),
+            DataFlow(
+                name="DSL model",
+                source="DSL",
+                target="Register Spec",
+                data="Domain model (StockFlowModel, ControlModel, etc.)",
+            ),
+            # Spec registration
+            DataFlow(
+                name="spec",
+                source="Register Spec",
+                target="GDSSpec Store",
+                data="GDSSpec",
+            ),
+            # Compilation
+            DataFlow(
+                name="spec to compile",
+                source="GDSSpec Store",
+                target="Compile",
+                data="GDSSpec + Block tree",
+            ),
+            DataFlow(
+                name="system ir",
+                source="Compile",
+                target="SystemIR Store",
+                data="SystemIR",
+            ),
+            # Verification
+            DataFlow(
+                name="ir to verify",
+                source="SystemIR Store",
+                target="Verify",
+                data="SystemIR",
+            ),
+            DataFlow(
+                name="report",
+                source="Verify",
+                target="User",
+                data="VerificationReport",
+            ),
+            # OWL export
+            DataFlow(
+                name="spec to owl",
+                source="GDSSpec Store",
+                target="Export to OWL",
+                data="GDSSpec",
+            ),
+            DataFlow(
+                name="rdf",
+                source="Export to OWL",
+                target="RDF Graph",
+                data="Turtle/RDF",
+            ),
+            # Simulation
+            DataFlow(
+                name="spec to adapter",
+                source="GDSSpec Store",
+                target="Adapt to Sim",
+                data="GDSSpec + policies + SUFs",
+            ),
+            DataFlow(
+                name="model",
+                source="Adapt to Sim",
+                target="Simulate",
+                data="gds_sim.Model",
+            ),
+            DataFlow(
+                name="trajectory",
+                source="Simulate",
+                target="Trajectory Store",
+                data="Results (trajectory rows)",
+            ),
+            # Analysis
+            DataFlow(
+                name="trajectory to analyze",
+                source="Trajectory Store",
+                target="Analyze",
+                data="Trajectory + StateMetric",
+            ),
+            DataFlow(
+                name="analysis results",
+                source="Analyze",
+                target="User",
+                data="Distances, R(x), X_C",
+            ),
+        ],
+    )
+
+
+def build_dfd_spec() -> GDSSpec:
+    return compile_dfd(build_dfd_model())
+
+
+def build_dfd_system() -> SystemIR:
+    return compile_dfd_to_system(build_dfd_model())
+
+
+if __name__ == "__main__":
+    model = build_dfd_model()
+    spec = build_dfd_spec()
+    ir = build_dfd_system()
+    report = verify(ir)
+    canonical = project_canonical(spec)
+
+    print("=== GDS User Pipeline (DFD) ===")
+    print(f"Blocks: {len(spec.blocks)}")
+    print(f"Wirings: {len(spec.wirings)}")
+    print(f"Verification: {report.errors} errors")
+    print("")
+    print(f"=== Canonical: {canonical.formula} ===")
+    print(f"U: {canonical.boundary_blocks}")
+    print(f"g: {canonical.policy_blocks}")
+    print(f"f: {canonical.mechanism_blocks}")
+    print(f"X: {canonical.state_variables}")
+    print("")
+    print(system_to_mermaid(ir))