Merge pull request #111 from BlockScience/dev

Release: merge dev into main

Author: rororowyourboat

docs/business/getting-started.md

@@ -68,11 +68,11 @@ model = SupplyChainModel(
         SupplyNode(name="Retailer", initial_inventory=100),
     ],
     shipments=[
-        Shipment(name="F->D", source_node="Factory", target_node="Distributor"),
-        Shipment(name="D->R", source_node="Distributor", target_node="Retailer"),
+        Shipment(name="F->D", source="Factory", target="Distributor"),
+        Shipment(name="D->R", source="Distributor", target="Retailer"),
     ],
     demand_sources=[
-        DemandSource(name="Customer", target_node="Retailer"),
+        DemandSource(name="Customer", target="Retailer"),
     ],
     order_policies=[
         OrderPolicy(name="Retailer Policy", node="Retailer", inputs=["Retailer"]),

docs/business/guide/diagram-types.md

@@ -103,10 +103,10 @@ model = SupplyChainModel(
         SupplyNode(name="Retail", initial_inventory=50),
     ],
     shipments=[
-        Shipment(name="W->R", source_node="Warehouse", target_node="Retail", lead_time=2.0),
+        Shipment(name="W->R", source="Warehouse", target="Retail", lead_time=2.0),
     ],
     demand_sources=[
-        DemandSource(name="Customer Demand", target_node="Retail"),
+        DemandSource(name="Customer Demand", target="Retail"),
     ],
     order_policies=[
         OrderPolicy(name="Retail Reorder", node="Retail", inputs=["Retail"]),

docs/business/guide/verification.md

@@ -63,8 +63,8 @@ Self-loops (a variable causing itself) are structurally invalid:
 | ID | Name | Severity | What it checks |
 |----|------|----------|----------------|
 | SCN-001 | Network connectivity | WARNING | All nodes reachable via BFS from demand/supply paths |
-| SCN-002 | Shipment node validity | ERROR | source_node and target_node exist |
-| SCN-003 | Demand target validity | ERROR | target_node exists |
+| SCN-002 | Shipment node validity | ERROR | source and target exist |
+| SCN-003 | Demand target validity | ERROR | target exists |
 | SCN-004 | No orphan nodes | WARNING | Every node in at least one shipment or demand |
 
 ### SCN-001: Network Connectivity

docs/business/index.md

@@ -78,10 +78,10 @@ scn = SupplyChainModel(
         SupplyNode(name="Retailer", initial_inventory=100),
     ],
     shipments=[
-        Shipment(name="F->R", source_node="Factory", target_node="Retailer"),
+        Shipment(name="F->R", source="Factory", target="Retailer"),
     ],
     demand_sources=[
-        DemandSource(name="Customer", target_node="Retailer"),
+        DemandSource(name="Customer", target="Retailer"),
     ],
     order_policies=[
         OrderPolicy(name="Reorder", node="Retailer", inputs=["Retailer"]),

docs/framework/ecosystem.md

@@ -4,39 +4,53 @@ The GDS ecosystem is a family of composable packages for specifying, visualizing
 
 ## Packages
 
-| Package | Description | Docs | PyPI |
-|---|---|---|---|
-| **gds-framework** | Foundation — typed compositional specifications | [Docs](https://blockscience.github.io/gds-framework) | [PyPI](https://pypi.org/project/gds-framework/) |
-| **gds-viz** | Mermaid diagram renderers for GDS specifications | [Docs](https://blockscience.github.io/gds-viz) | [PyPI](https://pypi.org/project/gds-viz/) |
-| **gds-games** | Typed DSL for compositional game theory | [Docs](https://blockscience.github.io/gds-games) | [PyPI](https://pypi.org/project/gds-games/) |
-| **gds-examples** | Six tutorial models demonstrating every framework feature | [Docs](https://blockscience.github.io/gds-examples) | [PyPI](https://pypi.org/project/gds-examples/) |
+| Package | Import | Description |
+|---|---|---|
+| **gds-framework** | `gds` | Core engine — blocks, composition algebra, compiler, verification |
+| **gds-viz** | `gds_viz` | Mermaid diagram renderers for GDS specifications |
+| **gds-stockflow** | `stockflow` | Declarative stock-flow DSL over GDS semantics |
+| **gds-control** | `gds_control` | State-space control DSL over GDS semantics |
+| **gds-games** | `ogs` | Typed DSL for compositional game theory (Open Games) |
+| **gds-software** | `gds_software` | Software architecture DSL (DFD, state machine, C4, ERD, etc.) |
+| **gds-business** | `gds_business` | Business dynamics DSL (CLD, supply chain, value stream map) |
+| **gds-sim** | `gds_sim` | Simulation engine (standalone, Pydantic-only) |
+| **gds-examples** | — | Tutorial models demonstrating framework features |
 
 ## Dependency Graph
 
 ```mermaid
 graph TD
     F[gds-framework] --> V[gds-viz]
     F --> G[gds-games]
+    F --> SF[gds-stockflow]
+    F --> C[gds-control]
+    F --> SW[gds-software]
+    F --> B[gds-business]
     F --> E[gds-examples]
     V --> E
+    G --> E
+    SF --> E
+    C --> E
+    SW --> E
+    B --> E
+    SIM[gds-sim]
 ```
 
 ## Architecture
 
 ```
-gds-framework (foundation)
-│
-│  Domain-neutral composition algebra, typed spaces,
-│  state model, verification engine, flat IR compiler.
-│
-├── gds-viz (visualization)
-│   └── 6 Mermaid diagram views of GDS specifications
-│
-├── gds-games (game theory DSL)
-│   └── Open games, pattern composition, verification, reports, CLI
-│
-└── gds-examples (tutorials)
-    └── 6 complete domain models with tests and visualizations
+gds-framework  ←  core engine (no GDS dependencies)
+    ↑
+gds-viz        ←  visualization (depends on gds-framework)
+gds-games      ←  game theory DSL (depends on gds-framework)
+gds-stockflow  ←  stock-flow DSL (depends on gds-framework)
+gds-control    ←  control systems DSL (depends on gds-framework)
+gds-software   ←  software architecture DSL (depends on gds-framework)
+gds-business   ←  business dynamics DSL (depends on gds-framework)
+    ↑
+gds-examples   ←  tutorials (depends on gds-framework + gds-viz + all DSLs)
+
+gds-sim        ←  simulation engine (standalone — no gds-framework dep, only pydantic)
 ```
 
 ## Links

docs/framework/guide/architecture.md

@@ -10,6 +10,14 @@ Blocks with bidirectional typed interfaces, composed via four operators (`>>`, `
 
 TypeDef with runtime constraints, typed Spaces, Entities with StateVariables, Block roles (BoundaryAction/Policy/Mechanism/ControlAction), GDSSpec registry, ParameterSchema (Θ), canonical projection (CanonicalGDS), Tagged mixin, semantic verification (SC-001..SC-007), SpecQuery for dependency analysis, and JSON serialization.
 
+### Why Two Layers?
+
+Layer 0 is domain-neutral by design. It knows about blocks with typed ports, four composition operators, and structural topology — nothing about games, stocks, or controllers. This neutrality is what allows five different DSLs to compile to the same IR.
+
+Domain judgment enters at Layer 1: when a modeler decides "this is a Mechanism, not a Policy" or "this variable is part of the system state." Layer 0 cannot make these decisions because they require knowledge of the problem being modeled. The three-stage compiler (flatten, wire, extract hierarchy) is pure algebra. The role annotations (BoundaryAction, Policy, Mechanism) are domain commitments.
+
+This separation means Layer 0 specifications stay verifiable without knowing anything about the domain — they can be composed and checked formally. Layer 1 adds the meaning that makes a specification useful for a particular problem.
+
 ## Foundation + Domain Packages
 
 ```

docs/guides/best-practices.md

@@ -49,6 +49,20 @@ Policy(name="Process", ...)
 
 ---
 
+## Modeling Decisions
+
+Before writing any composition, three choices shape the entire specification:
+
+**Role assignment.** Which processes become BoundaryActions (exogenous inputs), Policies (decision/observation logic), or Mechanisms (state updates)? This determines the canonical decomposition `h = f . g`. A temperature sensor could be a BoundaryAction (external data arrives) or a Policy (compute reading from state) — the right answer depends on what you want to verify, not on the physics alone.
+
+**State identification.** Which quantities are state variables and which are derived? An SIR model with three state variables (S, I, R) produces a different canonical form than one that derives R = N - S - I and tracks only two. Finer state identification lets SC-001 catch orphan variables; coarser identification creates fewer obligations.
+
+**Block granularity.** One large block or several small ones? The algebra composes anything with compatible ports, but finer granularity makes the [hierarchy tree](../framework/guide/composition.md) more informative and gives verification more to check. A single-block model passes all structural checks trivially.
+
+These are design choices, not discoveries. Different choices lead to different verifiable specifications — neither is "wrong." Start from the question you want to answer ("Does this system avoid write conflicts on state?") and design roles backward from there.
+
+---
+
 ## Composition Patterns
 
 ### The Three-Tier Pipeline

docs/guides/choosing-a-dsl.md

@@ -4,6 +4,16 @@ Five domain-specific languages compile to the same GDS core. This guide helps yo
 
 ---
 
+## Starting from the Problem
+
+The Decision Matrix below is a technical reference — it assumes you already know your primitives. In practice, most modelers start earlier: with a domain question.
+
+The same system can often be modeled with more than one DSL. An epidemic could be stockflow (if you care about accumulation rates) or raw framework (if you just need a state transition). A supply chain could be stockflow (stocks and flows), CLD (causal influences), or SCN (inventory and topology). The DSL choice depends on **what you want to verify**, not just what domain you are in.
+
+The natural workflow is: **Problem → What do I want to check? → DSL**. Once you pick a DSL, roles and block structure follow more naturally because the DSL embeds domain conventions about what matters.
+
+---
+
 ## Decision Matrix
 
 | If your system has... | Use | Package | Why |

docs/guides/getting-started.md

@@ -425,30 +425,30 @@ From here, explore the [example models](../examples/index.md) or the [Rosetta St
 ## Interactive Notebook
 
 /// marimo-embed-file
-    filepath: packages/gds-examples/guides/getting_started/notebook.py
+    filepath: packages/gds-examples/notebooks/getting_started.py
     height: 800px
     mode: read
 ///
 
 To run the notebook locally:
 
 ```bash
-uv run marimo run packages/gds-examples/guides/getting_started/notebook.py
+uv run marimo run packages/gds-examples/notebooks/getting_started.py
 ```
 
 Run the test suite:
 
 ```bash
-uv run --package gds-examples pytest packages/gds-examples/guides/getting_started/ -v
+uv run --package gds-examples pytest packages/gds-examples/tests/test_getting_started.py -v
 ```
 
 ## Source Files
 
 | File | Purpose |
 |------|---------|
-| [`stage1_minimal.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/stage1_minimal.py) | Minimal heater model |
-| [`stage2_feedback.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/stage2_feedback.py) | Feedback loop with policies |
-| [`stage3_dsl.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/stage3_dsl.py) | gds-control DSL version |
-| [`stage4_verify_viz.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/stage4_verify_viz.py) | Verification and visualization |
-| [`stage5_query.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/stage5_query.py) | SpecQuery API |
-| [`notebook.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/guides/getting_started/notebook.py) | Interactive marimo notebook |
+| [`stage1_minimal.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/gds_examples/getting_started/stage1_minimal.py) | Minimal heater model |
+| [`stage2_feedback.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/gds_examples/getting_started/stage2_feedback.py) | Feedback loop with policies |
+| [`stage3_dsl.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/gds_examples/getting_started/stage3_dsl.py) | gds-control DSL version |
+| [`stage4_verify_viz.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/gds_examples/getting_started/stage4_verify_viz.py) | Verification and visualization |
+| [`stage5_query.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/gds_examples/getting_started/stage5_query.py) | SpecQuery API |
+| [`getting_started.py`](https://github.com/BlockScience/gds-core/blob/main/packages/gds-examples/notebooks/getting_started.py) | Interactive marimo notebook |

docs/guides/interoperability.md

@@ -235,7 +235,7 @@ This validates GDS as an **interoperability substrate**, not just a modeling fra
 ### Nash Equilibrium Analysis
 
 /// marimo-embed-file
-    filepath: packages/gds-examples/guides/nash_equilibrium/notebook.py
+    filepath: packages/gds-examples/notebooks/nash_equilibrium.py
     height: 800px
     mode: read
 ///
@@ -244,8 +244,7 @@ To run locally:
 
 ```bash
 uv sync --all-packages --extra nash
-cd packages/gds-examples && \
-    uv run marimo run guides/nash_equilibrium/notebook.py
+uv run marimo run packages/gds-examples/notebooks/nash_equilibrium.py
 ```
 
 ```bash
@@ -257,16 +256,15 @@ uv run --package gds-examples pytest \
 ### Evolution of Trust Simulation
 
 /// marimo-embed-file
-    filepath: packages/gds-examples/guides/evolution_of_trust/notebook.py
+    filepath: packages/gds-examples/notebooks/evolution_of_trust.py
     height: 800px
     mode: read
 ///
 
 To run locally:
 
 ```bash
-cd packages/gds-examples && \
-    uv run marimo run guides/evolution_of_trust/notebook.py
+uv run marimo run packages/gds-examples/notebooks/evolution_of_trust.py
 ```
 
 ```bash
@@ -283,8 +281,8 @@ uv run --package gds-examples pytest \
 | `games/evolution_of_trust/model.py` | OGS structure with Nicky Case payoffs |
 | `games/evolution_of_trust/strategies.py` | 8 strategy implementations |
 | `games/evolution_of_trust/tournament.py` | Match, tournament, evolutionary dynamics |
-| `guides/nash_equilibrium/notebook.py` | Interactive Nash analysis notebook |
-| `guides/evolution_of_trust/notebook.py` | Interactive simulation notebook |
+| `notebooks/nash_equilibrium.py` | Interactive Nash analysis notebook |
+| `notebooks/evolution_of_trust.py` | Interactive simulation notebook |
 
 All paths relative to `packages/gds-examples/`.