Release: gds-owl v0.1.0 + Paper Defs 2.5/2.7 bridge

.github/workflows/security.yml

@@ -15,4 +15,7 @@ jobs:
         with:
           python-version: "3.12"
       - run: uv sync --all-packages
-      - run: uv tool run pip-audit
+      # CVE-2026-4539: pygments 2.19.2 (latest) — no fix available yet.
+      # Transitive dep from pytest, mkdocs-material, marimo, rich.
+      # Remove this ignore when pygments releases a patched version.
+      - run: uv tool run pip-audit --ignore-vuln CVE-2026-4539

CLAUDE.md

@@ -80,7 +80,7 @@ gds-sim        ←  simulation engine (standalone — no gds-framework dep, only
 Domain-neutral engine. Blocks with bidirectional typed interfaces, composed via four operators (`>>`, `|`, `.feedback()`, `.loop()`). A 3-stage compiler flattens composition trees into flat IR (blocks + wirings + hierarchy). Six generic verification checks (G-001..G-006) validate structural properties on the IR.
 
 **Layer 1 — Specification Framework** (`spec.py`, `canonical.py`, `state.py`, `spaces.py`, `types/`):
-Where GDS theory lives. `GDSSpec` is the central registry for types, spaces, entities, blocks, wirings, and parameters. `project_canonical()` derives the formal `h = f ∘ g` decomposition. Seven semantic checks (SC-001..SC-007) validate domain properties on the spec.
+Where GDS theory lives. `GDSSpec` is the central registry for types, spaces, entities, blocks, wirings, and parameters. `project_canonical()` derives the formal `h = f ∘ g` decomposition. Nine semantic checks (SC-001..SC-009) validate domain properties on the spec.
 
 These layers are loosely coupled — you can use the composition algebra without `GDSSpec`, and `GDSSpec` does not depend on the compiler.
 
@@ -140,7 +140,7 @@ Block roles (`BoundaryAction`, `Policy`, `Mechanism`, `ControlAction`) subclass
 Both use the pluggable pattern: `Callable[[T], list[Finding]]`.
 
 - **Generic checks (G-001..G-006)** operate on `SystemIR` — structural topology only
-- **Semantic checks (SC-001..SC-007)** operate on `GDSSpec` — domain properties (completeness, determinism, reachability, type safety, parameter references, canonical wellformedness)
+- **Semantic checks (SC-001..SC-009)** operate on `GDSSpec` — domain properties (completeness, determinism, reachability, type safety, parameter references, canonical wellformedness, admissibility references, transition read consistency)
 - **Domain checks** operate on domain models (e.g., `StockFlowModel`, `ControlModel`) — pre-compilation structural validation
 
 ### Branching Workflow

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/blockscience/gds-core",
+  "public_key": "pk_LRmzAzjZYKfatA1uULFnD"
+}

docs/guides/verification.md

@@ -7,7 +7,7 @@ A hands-on walkthrough of the three verification layers in GDS, using deliberate
 | Layer | Checks | Operates on | Catches |
 |-------|--------|-------------|---------|
 | **Generic** | G-001..G-006 | `SystemIR` | Structural topology errors |
-| **Semantic** | SC-001..SC-007 | `GDSSpec` | Domain property violations |
+| **Semantic** | SC-001..SC-009 | `GDSSpec` | Domain property violations |
 | **Domain** | SF-001..SF-005 | DSL model | DSL-specific errors |
 
 Each layer operates on a different representation, and the layers are complementary: a model can pass all generic checks but fail semantic checks (and vice versa).
@@ -357,6 +357,8 @@ gds_findings = [f for f in report.findings if f.check_id.startswith("G-")]
 | SC-005 | Parameter refs | Unregistered params |
 | SC-006 | Canonical f | No mechanisms |
 | SC-007 | Canonical X | No state space |
+| SC-008 | Admissibility refs | Invalid boundary block or state deps |
+| SC-009 | Transition reads | Invalid mechanism reads or block deps |
 
 ### Domain Checks (StockFlowModel)
 

docs/owl/api/export.md

@@ -0,0 +1,5 @@
+# gds_owl.export
+
+Pydantic to RDF graph export functions.
+
+::: gds_owl.export

docs/owl/api/import.md

@@ -0,0 +1,5 @@
+# gds_owl.import_
+
+RDF graph to Pydantic import functions.
+
+::: gds_owl.import_

docs/owl/api/init.md

@@ -0,0 +1,8 @@
+# gds_owl
+
+Public API -- top-level exports.
+
+::: gds_owl
+    options:
+      show_submodules: false
+      members: false

docs/owl/api/ontology.md

@@ -0,0 +1,5 @@
+# gds_owl.ontology
+
+OWL class hierarchy (TBox) -- core schema definitions.
+
+::: gds_owl.ontology

docs/owl/api/serialize.md

@@ -0,0 +1,5 @@
+# gds_owl.serialize
+
+RDF serialization utilities (Turtle format).
+
+::: gds_owl.serialize

docs/owl/api/shacl.md

@@ -0,0 +1,5 @@
+# gds_owl.shacl
+
+SHACL shape library for validating GDS RDF graphs.
+
+::: gds_owl.shacl

docs/owl/api/sparql.md

@@ -0,0 +1,5 @@
+# gds_owl.sparql
+
+SPARQL query templates for GDS analysis.
+
+::: gds_owl.sparql

docs/owl/getting-started.md

@@ -0,0 +1,99 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install gds-owl
+```
+
+For SHACL validation:
+
+```bash
+pip install gds-owl[shacl]
+```
+
+## Build an Ontology
+
+The core ontology defines OWL classes and properties for all GDS concepts:
+
+```python
+from gds_owl import build_core_ontology, to_turtle
+
+ontology = build_core_ontology()
+print(to_turtle(ontology))
+```
+
+This produces a Turtle document with classes like `gds-core:GDSSpec`, `gds-core:Mechanism`, `gds-core:Policy`, etc.
+
+## Export a Spec to RDF
+
+```python
+from gds import GDSSpec, typedef, entity, state_var
+from gds.blocks.roles import Mechanism
+from gds.types.interface import Interface, port
+from gds_owl import spec_to_graph, to_turtle
+
+# Build a minimal spec
+Float = typedef("Float", float)
+spec = GDSSpec(name="Example")
+spec.collect(
+    Float,
+    entity("Tank", level=state_var(Float)),
+    Mechanism(
+        name="Fill",
+        interface=Interface(forward_in=(port("Flow Rate"),)),
+        updates=[("Tank", "level")],
+    ),
+)
+
+# Export to RDF
+graph = spec_to_graph(spec)
+print(to_turtle(graph))
+```
+
+## Import Back from RDF
+
+```python
+from rdflib import Graph
+from gds_owl import graph_to_spec, to_turtle, spec_to_graph
+
+# Round-trip: Pydantic -> Turtle -> Pydantic
+graph = spec_to_graph(spec)
+turtle_str = to_turtle(graph)
+
+g2 = Graph()
+g2.parse(data=turtle_str, format="turtle")
+spec2 = graph_to_spec(g2)
+
+assert spec2.name == "Example"
+assert "Tank" in spec2.entities
+```
+
+## Validate with SHACL
+
+```python
+from gds_owl import build_all_shapes, validate_graph, spec_to_graph
+
+graph = spec_to_graph(spec)
+shapes = build_all_shapes()
+
+conforms, results_graph, results_text = validate_graph(graph, shapes)
+print(f"Conforms: {conforms}")
+if not conforms:
+    print(results_text)
+```
+
+## Query with SPARQL
+
+```python
+from gds_owl import TEMPLATES, spec_to_graph
+
+graph = spec_to_graph(spec)
+
+# List all blocks
+for template in TEMPLATES:
+    if template.name == "list_blocks":
+        results = graph.query(template.query)
+        for row in results:
+            print(row)
+```