Merge dev: Tier 0 + Tier 1 complete

Author: rohan

CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 2026-04-03 — Tier 0 + Tier 1 Complete
+
+Driven by external reviews from Zargham and Jamsheed (Shorish) against the
+GDS paper (Zargham & Shorish 2022). The reviews identified foundational gaps
+in notation alignment, formal property statements, ControlAction semantics,
+temporal agnosticism documentation, and execution contract formalization.
+This release closes all Tier 0 and Tier 1 roadmap items.
+
+### gds-framework v0.3.0
+
+**Breaking:** `CanonicalGDS.input_ports` now contains only controlled inputs (U_c);
+disturbance-tagged BoundaryAction ports are in the new `disturbance_ports` field.
+
+New capabilities:
+- **ExecutionContract** — DSL-layer time model declaration (`discrete`, `continuous`,
+  `event`, `atemporal`) with Moore/Mealy ordering. Attached as optional field on
+  GDSSpec. A spec without a contract remains valid for structural verification.
+- **ControlAction canonical projection** — `CanonicalGDS` now extracts output ports
+  (Y) and renders the output map `y = C(x, d)` in the formula.
+- **Disturbance input partition** — `disturbance_ports` on `CanonicalGDS` separates
+  policy-bypassing exogenous inputs (W) from controlled inputs (U_c) via
+  `tags={"role": "disturbance"}` on BoundaryAction.
+- **TypeDef.constraint_kind** — optional named constraint pattern (`non_negative`,
+  `positive`, `probability`, `bounded`, `enum`) enabling round-trip export via SHACL.
+
+New verification checks:
+- **SC-010** — ControlAction outputs must not feed the g pathway (Policy/BoundaryAction)
+- **SC-011** — ExecutionContract well-formedness
+- **DST-001** — Disturbance-tagged BoundaryAction must not wire to Policy
+
+Documentation:
+- Formal property statements for all 15 core checks (G-001..G-006, SC-001..SC-009)
+- Requirement traceability markers on all verification tests
+- Tests for SC-005..SC-009 (previously untested)
+- Controller-plant duality design document
+- Temporal agnosticism invariant with three-layer stack diagram
+- Audit of 30+ docs replacing "timestep" with temporally neutral vocabulary
+- Assurance claims document with verification passport template
+- Execution semantics design document with DSL contract mapping
+- Disturbance formalization design document
+- Notation harmonized with Zargham & Shorish (2022)
+
+### gds-owl v0.2.0
+
+- **SHACL constraint promotion** — `TypeDef.constraint_kind` metadata exports as SHACL
+  property shapes (`sh:minInclusive`, `sh:maxInclusive`, `sh:minExclusive`, `sh:in`).
+  Constraints with a `constraint_kind` are now R2 round-trippable; those without remain
+  R3 lossy. Import reconstructs Python callable constraints from SHACL metadata.
+- New ontology properties: `constraintKind`, `constraintLow`, `constraintHigh`, `constraintValue`
+- New `build_constraint_shapes()` public API
+
+### gds-psuu v0.2.1
+
+- **Parameter schema validation** — `ParameterSpace.from_parameter_schema()` creates
+  sweep dimensions from declared ParameterDef entries. `validate_against_schema()`
+  catches missing params, type mismatches, and out-of-bounds sweeps.
+- **PSUU-001 check** following the GDS Finding pattern
+- Sweep runner validates against schema when `parameter_schema` is provided
+
+### gds-stockflow v0.1.1
+
+- Emit `ExecutionContract(time_domain="discrete")` from `compile_model()`
+
+### gds-control v0.1.1
+
+- Emit `ExecutionContract(time_domain="discrete")` from `compile_model()`
+
+### gds-games v0.3.2
+
+- Emit `ExecutionContract(time_domain="atemporal")` from `compile_pattern_to_spec()`
+
+### gds-software v0.1.1
+
+- Emit `ExecutionContract` from all 6 compilers: `atemporal` for DFD, C4, component,
+  ERD, dependency; `discrete` for state machines
+
+### gds-business v0.1.1
+
+- Emit `ExecutionContract` from all 3 compilers: `discrete` for CLD and supply chain,
+  `atemporal` for value stream maps
+
+### gds-analysis v0.1.1
+
+- Guard `gds-continuous` import in `backward_reachability.py` (previously caused
+  ImportError when gds-continuous wasn't installed)
+
 ## gds-framework v0.2.3
 
 - Add `StructuralWiring` to public API (compiler intermediate for domain DSL wiring emitters)

CLAUDE.md

@@ -114,7 +114,7 @@ Five domain DSLs (stockflow, control, games, software, business) compile to GDS.
    - `compile_to_system(model)` → `SystemIR` (builds composition tree, delegates to `gds.compiler.compile.compile_system`)
 4. **Verification** — domain-specific checks on the model, plus optional delegation to G-001..G-006 via SystemIR
 
-All DSLs map to the same GDS roles: exogenous inputs → `BoundaryAction`, decision/observation logic → `Policy`, state updates → `Mechanism` + `Entity`. `ControlAction` is unused across all DSLs. Canonical `h = f ∘ g` holds cleanly for all three domains.
+All DSLs map to the same GDS roles: exogenous inputs → `BoundaryAction`, decision/observation logic → `Policy`, state updates → `Mechanism` + `Entity`. `ControlAction` is unused by DSL compilers (all non-state-updating blocks resolve to Policy). It is available for hand-built models as the output map y = C(x, d). See docs/framework/design/controller-plant-duality.md. Canonical `h = f ∘ g` holds cleanly for all three domains.
 
 The composition tree follows a convergent tiered pattern:
 ```
@@ -149,8 +149,8 @@ Only 5 concrete Block types exist — domain packages subclass `AtomicBlock` onl
 - `AtomicBlock` — leaf node
 - `StackComposition` (`>>`) — sequential, validates token overlap
 - `ParallelComposition` (`|`) — independent, no validation
-- `FeedbackLoop` (`.feedback()`) — backward within timestep, CONTRAVARIANT
-- `TemporalLoop` (`.loop()`) — forward across timesteps, COVARIANT only
+- `FeedbackLoop` (`.feedback()`) — backward within evaluation, CONTRAVARIANT
+- `TemporalLoop` (`.loop()`) — forward across temporal boundaries, COVARIANT only
 
 Block roles (`BoundaryAction`, `Policy`, `Mechanism`, `ControlAction`) subclass `AtomicBlock` and enforce constraints at construction via `@model_validator`.
 

docs/control/index.md

@@ -69,7 +69,7 @@ The compiler builds a tiered composition tree:
 - **Across tiers:** sequential composition (`>>`) -- sensors feed controllers, controllers feed state dynamics
 - **Temporal recurrence:** `.loop()` -- state outputs at timestep *t* feed back to sensors at timestep *t+1*
 
-**Design decision:** All non-state-updating blocks use `Policy`. `ControlAction` is deliberately not used -- it sits outside the canonical *g* partition, which would break the clean `(A, B, C, D) <-> (X, U, g, f)` mapping.
+**Design decision:** All non-state-updating blocks use `Policy`. gds-control deliberately maps everything to the `(A, B, C, D) -> (X, Z, g, f)` state-space decomposition, where sensors and controllers both contribute to the input map `g`. The `ControlAction` role (output map `y = C(x, d)`) is orthogonal to this mapping -- it models inter-system output, not internal control flow. See [Controller-Plant Duality](../framework/design/controller-plant-duality.md).
 
 ## Canonical Form
 

docs/examples/building-models.md

@@ -29,7 +29,7 @@ Count = typedef("Count", int,
 
 ### 2. Define Entities (state space X)
 
-What persists across timesteps.
+What persists across temporal boundaries.
 
 ```python
 from gds import entity, state_var
@@ -40,7 +40,7 @@ agent = entity("Agent",
 
 ### 3. Define Spaces (communication channels)
 
-Transient signals within a timestep — NOT state.
+Transient signals within an evaluation -- NOT state.
 
 ```python
 from gds import space
@@ -104,7 +104,7 @@ def build_system():
 | State vs Signal | State persists (Entity). Signals are transient (Space). |
 | Parameter vs Input | Parameters fixed per run (Θ). Inputs vary per step (BoundaryAction). |
 | Which operator | Linear → `>>`. Independent → `\|`. Backward → `.feedback()`. Iteration → `.loop()`. |
-| ControlAction vs Policy | Policy = decision logic (g). ControlAction = admissibility constraint (d). |
+| ControlAction vs Policy | Policy = decision logic g(x, z) → d. ControlAction = output observable y = C(x, d). |
 
 ## Role Constraints
 

docs/examples/examples/insurance.md

@@ -29,13 +29,13 @@ flowchart LR
 
 ## What You'll Learn
 
-- **ControlAction** role — the 4th block role, for admissibility/control decisions
+- **ControlAction** role — the 4th block role, for output observables
 - Complete 4-role taxonomy: BoundaryAction → Policy → ControlAction → Mechanism
-- ControlAction vs Policy: Policy is core decision logic (g), ControlAction constrains the action space (d)
-- `params_used` on ControlAction — parameterized admissibility rules
+- ControlAction vs Policy: Policy is decision logic g(x, z) → d, ControlAction is the output observable y = C(x, d)
+- `params_used` on ControlAction — parameterized output computation
 
 !!! note "Key distinction"
-    Premium Calculation is **ControlAction** because it enforces admissibility constraints — it decides what's *allowed*, not what to do.
+    Premium Calculation is **ControlAction** because it computes an observable output signal — the premium rate that downstream mechanisms consume. It maps state and decisions to an output, rather than making the core risk assessment decision.
 
 ## Files
 

docs/examples/examples/lotka-volterra.md

@@ -1,6 +1,6 @@
 # Lotka-Volterra
 
-**Adds temporal loops** — forward iteration across timesteps.
+**Adds temporal loops** -- structural recurrence across temporal boundaries.
 
 ## GDS Decomposition
 
@@ -31,11 +31,11 @@ flowchart TD
 
 ## What You'll Learn
 
-- `.loop()` composition for cross-timestep temporal feedback
+- `.loop()` composition for cross-boundary temporal recurrence
 - **COVARIANT** flow direction — mandatory for `.loop()` (CONTRAVARIANT raises GDSTypeError)
 - Mechanism with `forward_out` — emitting signals after state update
 - `exit_condition` parameter for loop termination
-- Contrast with `.feedback()`: within-timestep vs across-timestep
+- Contrast with `.feedback()`: within-evaluation vs across-boundary
 
 !!! note "Key distinction"
     Temporal wirings must be **COVARIANT** — `.loop()` enforces this at construction time.

docs/examples/examples/thermostat.md

@@ -1,6 +1,6 @@
 # Thermostat PID
 
-**Adds feedback** — backward information flow within a single timestep.
+**Adds feedback** -- backward information flow within a single evaluation.
 
 ## GDS Decomposition
 

docs/examples/learning-path.md

@@ -12,13 +12,13 @@ The foundation. Learn TypeDef, Entity, Space, BoundaryAction, Policy, Mechanism,
 
 ### 2. [Thermostat PID](examples/thermostat.md) — Feedback
 
-Adds `.feedback()` for within-timestep backward information flow. Introduces CONTRAVARIANT flow direction and the ControlAction role.
+Adds `.feedback()` for within-evaluation backward information flow. Introduces CONTRAVARIANT flow direction and the ControlAction role.
 
 **New:** `.feedback()`, backward ports, ControlAction
 
 ### 3. [Lotka-Volterra](examples/lotka-volterra.md) — Temporal Loops
 
-Adds `.loop()` for cross-timestep iteration. Introduces COVARIANT temporal wiring and Mechanism with `forward_out`.
+Adds `.loop()` for cross-boundary recurrence. Introduces COVARIANT temporal wiring and Mechanism with `forward_out`.
 
 **New:** `.loop()`, temporal wiring, exit conditions