Merck · thevolatilebit · Sep 8, 2023 · Sep 8, 2023 · Sep 15, 2023 · Sep 16, 2023
diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -0,0 +1,7 @@
+# Revisions listed here are skipped by `git blame` (bulk mechanical changes that
+# would otherwise obscure real authorship). Enable locally with:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+# (GitHub honors this file automatically.)
+
+# style: reformat all Julia sources with Runic (2026-07-16)
+4262b3342af377f3e879dda238d8cfa51f7660ab
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,11 @@
+# Keep the GitHub Actions themselves current (CompatHelper handles Julia package deps; this
+# handles the `uses:` action versions in .github/workflows/).
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+      - github-actions
diff --git a/.gitignore b/.gitignore
@@ -1,12 +1,20 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
-docs/build_*
+docs/build/
 docs/site/
+docs/preview/
+docs/src/tutorials/
+docs/src/case_studies/
+docs/src/deep_dives/
 tmp.gif
 gks.*
 Manifest.toml
 .vscode/
 LocalPreferences.toml
 .DS_Store
-_*
+_*
+*.db
+*.db.wal
+dev/
+.claude/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,57 @@
+# CLAUDE.md — ReactiveDynamics.jl agent guide
+
+Agent-facing orientation for the `ref-agents` branch. Re-verify any `file:line` before acting — line numbers drift; grep to confirm.
+
+## What this project is
+
+ReactiveDynamics.jl (RD) is a timed, stochastic, resource-constrained Petri net / discrete-event engine for system-dynamics-style modeling of business / R&D processes (budgeting, ledgers, what-if, rNPV) — NOT a chemical reaction network, despite the Catalyst-derived DSL surface. A **transition** is a stateful recipe that spawns in-flight instances at a Poisson rate, occupies shared finite resources (**species**) over a cycle time, and completes with a terminal probability-of-success that emits RHS products. Resources carry a **modality** governing allocation (`:nonblock`/`:conserved`/`:rate`), and a cost/reward/valuation **ledger** accumulates into a per-step log. Structured/agentic **tokens** are first-class entities (a "project" is an agent with attributes, custom behavior, and history) that can be instantiated, selected by predicate, advanced through lifecycle phases, and audited per-program. RD is part of the DyVE family and sits ON TOP of [AlgebraicAgents.jl](https://github.com/Merck/AlgebraicAgents.jl) (AA): a `ReactionNetworkProblem` IS an AA `@aagent`, so a network is a node in a larger heterogeneous AA hierarchy.
+
+## Where the durable spec lives
+
+The durable engineering artifacts live under top-level **`spec/`**, kept separate from **`docs/`** — which is reserved for the Documenter.jl static-pages site (`docs/make.jl`, `docs/src/`, generated `docs/build/`). Do not put spec material in `docs/`.
+
+**[`spec/STATUS.md`](spec/STATUS.md) is the single entry point — start there.** It carries the authoritative catalog of every durable artifact (CONTRACT_DRAFT, adr/, PR_DRAFT, DOCS_CHARTER, INVENTORY, the retired/archived docs) so this guide need not duplicate it. The three you touch most:
+
+- **`spec/STATUS.md`** — "what is the state, what is left." The dashboard: feature→commit table, test tally, deferred items with gates.
+- **`spec/CONTRACT_DRAFT.md`** — the normative operational-semantics spec (§1–§15). The durable spine: *what the engine must do*.
+- **`spec/INVENTORY.md`** — the current-source map (module map, public-API audit, static store, stepping trace, AA touchpoints): *where it lives in the source*.
+- **`spec/adr/`** — Architecture Decision Records (append-only), status table in `spec/adr/README.md`. To change a decision, add a new ADR; do not rewrite history.
+
+## Current architecture (post-ADR-0015)
+
+The static authoring/IR store is a dependency-free typed struct-of-columns (ACSets and Catlab were dropped, ADR 0003). ADR 0015 retired the last ACSets-lineage vocabulary, so the CURRENT names are:
+
+- Store type **`ReactionNetwork`** (was `ReactionNetworkSchema`); the type-level object model is `const SCHEMA`.
+- Authoring macro **`@reaction_network`** (was `@ReactionNetworkSchema`).
+- Conventional variable **`net`** (was `acs`); the `ReactionNetworkProblem` field **`.network`** (was `.acs`); store fields **`.counts`**/**`.columns`** (were `.parts`/`.subparts`).
+- Store verbs renamed to store vocabulary AND UNEXPORTED (internal, `RD.`-qualified): `nrows`, `row_ids`, `col_row_ids`, `column`/`cell`, `set_cell!`, `add_row!`/`add_rows!`, `rem_rows!`, `find_rows` (a `findall`, NOT an FK follow), `merge_networks!`, `build_network_from_dict`.
+- Old names survive ONE release as `@deprecate`/`@deprecate_binding` shims (`src/ReactiveDynamics.jl:427-435`; the deprecated `@ReactionNetworkSchema` macro alias at `src/interface/create.jl:83`). GeneratedExpressions was dropped.
+
+Module layout (`src/`, include order orchestrated in `src/ReactiveDynamics.jl`): `state.jl` (live sim state, the `@aagent` structs), `exprnode.jl` (the closed eval-free `ExprNode` IR), `compilers.jl` (expr→closure), `interface/*` (the DSL: `create.jl`/`update.jl` macros, `agents.jl` structured tokens, `aa_coupling.jl` the AA read/coupling surface, `checkpoint.jl` dump/restore, `solve.jl` `@agentize`), `operators/*` (`joins.jl`/`equalize.jl`/`refine.jl`), `solvers.jl` (THE step loop + constructor + `_step!`/`_reinit!`/`_projected_to`), `predicates.jl` (`TokenPredicate`/`@select`), `actions.jl` (the closed action family + `Rule`), `ledger.jl` (per-program ledger), `serialize.jl` (single-JSON eval-free (de)serialization), `analysis.jl`/`export.jl`/`visualize.jl` (Phase-0.6 result-inspection layer). Extensions: `ext/RDPlotsExt.jl` (Plots recipes + `_draw`, weakdep), `ext/RDArrowExt.jl` (Arrow export, weakdep).
+
+Everything specified in the contract (§1–§15) and ADRs 0001–0015 is IMPLEMENTED and green. See `spec/STATUS.md` for the feature→commit table. There is no open non-deferred work: the suite is fully green with zero skips, and the only remaining items are deliberate deferrals (`dump_state`'s clean-tick-boundary constraint; entity-level refinement ADR 0009 §F; threaded ensemble backend; AA Opera implicit coupling) — plus the rejected/will-not-do ACSets interop view (ADR 0003 Phase 3).
+
+## Build / test / dev
+
+```bash
+julia --project=. -e 'using Pkg; Pkg.instantiate()'   # install deps
+julia --project=. -e 'using Pkg; Pkg.test()'          # run the semantic suite
+julia --project=. -e 'using ReactiveDynamics'         # load the package
+```
+
+Tests live in `test/semantic/*.jl` (entry `test/runtests.jl` → `test/semantic/runtests.jl`) under a two-tier scheme: **T1-characterization** (runs against the engine) and **T2-acceptance** (target behavior). The suite is FULLY green — 801 pass / 0 broken, no `@test_skip` placeholders and no `@test_broken` pins (the last skips, the §1.4 modality validators, landed in `53d1fac`). A few tests carry weakdep environment guards (Plots/Arrow/Graphviz) that skip only when the package is absent; in the full test env they run. `test/Project.toml` declares the test-only deps (Plots, Arrow, DataFrames, Distributions, …) that the main project keeps as weakdeps. AlgebraicAgents is the registered 0.4 release (no `[sources]` pin). Julia ≥ 1.12.
+
+Formatting is [Runic](https://github.com/fredrikekre/Runic.jl) (opinionated, non-configurable — no config file). Run `julia -m Runic --inplace src test ext dev docs/make.jl demo` before committing, or `julia -m Runic --check .` to verify. No CI is configured in this repo (no `.github/workflows/`) — run the suite and formatter locally. The bulk reformat commit is listed in `.git-blame-ignore-revs`; `git config blame.ignoreRevsFile .git-blame-ignore-revs` makes `git blame` skip it.
+
+## Dev-loop gotchas
+
+- **Determinism is contractual.** All stochasticity draws from a state-owned `rng`; a run is determined by `(model, seed)` (CONTRACT §4). Thread the seed; never reach for the global RNG. `_reinit!` restores the exact stream (and takes a `seed` kwarg for ensemble mode (b) reseed).
+- **Append-only store.** Compiled attribute closures hard-code each species/param position; runtime mutation is append-only + soft-deactivate (ADR 0004). Never reorder or delete rows on a live/stepping model; reindexing macros (`equalize!`, refinement) are authoring-time only.
+- **Eval-free everywhere.** The serializer and IR never `Meta.parse`/`eval` a model field — the closed `ExprNode`/action whitelist + `validate` is the trust boundary (ADR 0005/0006). Custom host functions go through the per-network registry, not `@eval`. Do not add runtime `eval`.
+- **Adding a new `src/` file** requires clearing the compiled cache; the `dev/` Revise test server (`dev/run.sh`) otherwise avoids recompilation across edits.
+- **`NodeRef`, not `Ref`**, in the IR; JSON alloc-strategy fields are Symbols. Structured-token iteration uses a `(species, creation_index)` total order for determinism.
+- **Worktrees** go under `~/worktrees/<repo-short>/<branch>` (never repo-siblings or nested inside the tree).
+
+## Working rules
+
+Source of truth for decisions is `spec/adr/`; the normative spec is `spec/CONTRACT_DRAFT.md`. When docs contradict code, the CODE is truth. Commit at the end of a coherent logical batch (not per-file). Do not hard-wrap prose in Markdown — one continuous line per paragraph/list-item.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,26 @@
+Thanks for taking the time to contribute — we appreciate it very much!
+
+We welcome contributions to the core engine of ReactiveDynamics.jl — refining and extending the modeling metalanguage, the resource allocator, and the analysis/observability layer for improved user experience and modeling expressivity — as well as to the documentation and the worked decision case studies.
+
+Please start with the design records under [`spec/`](spec), which document the engine's behavior and the reasoning behind it:
+
+- [`spec/STATUS.md`](spec/STATUS.md) — the single "what is the state, what is left" index. Start here.
+- [`spec/CONTRACT_DRAFT.md`](spec/CONTRACT_DRAFT.md) — the normative operational-semantics specification (§1–§15).
+- [`spec/adr/`](spec/adr) — the Architecture Decision Records: *why* the engine is the way it is.
+- [`spec/INVENTORY.md`](spec/INVENTORY.md) — the current-source map (module map, public-API audit, stepping trace, AlgebraicAgents touchpoints).
+
+Two conventions matter. Decisions are changed by **adding a new ADR**, not by rewriting an existing one — the record is append-only. And when documentation and code disagree, **the code is the source of truth**; fix the docs to match, or open an issue if the code looks wrong.
+
+Before submitting a pull request, please run the semantic test suite and the formatter locally (there is no CI in this repo):
+
+```bash
+julia --project=. -e 'using Pkg; Pkg.test()'          # the semantic suite
+julia -m Runic --check .                               # formatting (Runic — opinionated, no config)
+```
+
+[Runic](https://github.com/fredrikekre/Runic.jl) is non-configurable; `julia -m Runic --inplace src test ext dev docs/make.jl demo` applies the formatting in place.
+
+Contributions to ReactiveDynamics.jl are welcome in the following forms:
+
+- Modifying the code or documentation via a pull request.
+- Reporting bugs or suggesting enhancements in the project's [GitHub Issues](https://github.com/Merck/ReactiveDynamics.jl/issues). If you propose a feature for future development, we are happy to discuss and take on the implementation.
diff --git a/LICENSE b/LICENSE
@@ -1,8 +1,6 @@
-The MIT License
+MIT License
 
-Copyright © 2022 Merck & Co., Inc., Rahway, NJ, USA and its affiliates. All rights reserved.
-
-Jan Bima (MSD), Otto Ritter (MSD), Sean L. Wu (Merck)
+Copyright (c) 2023 Merck & Co., Inc., Rahway, NJ, USA and its affiliates
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -11,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/LICENSES_THIRD_PARTY b/LICENSES_THIRD_PARTY
@@ -1,40 +1,10 @@
-ReactiveDynamics.jl depends on third-party Julia packages which may be distributed under different licenses. We have listed all of these third party packages and their licenses below. For the most up-to-date information, see `Project.toml`.
+ReactiveDynamics.jl depends on third-party Julia packages, which may be distributed under various licenses. For the most recent list of these packages, refer to `Project.toml` and consult the license terms of the individual packages.
 
-You must agree to the terms of these licenses, in addition to the ReactiveDynamics source code license, in order to use this software.
+You must agree to the terms of these licenses, in addition to the ReactiveDynamics.jl source code license, in order to use this software.
 
 --------------------------------------------------
 Third party software listed by License type
 --------------------------------------------------
 
 MIT License (or adaptations) (https://www.opensource.org/licenses/MIT)
-  * The Julia Language - https://github.com/JuliaLang/julia/blob/master/LICENSE.md
-  * BenchmarkTools.jl - https://github.com/JuliaCI/BenchmarkTools.jl
-  * CSV - https://github.com/JuliaData/CSV.jl
-  * Catlab - https://github.com/AlgebraicJulia/Catlab.jl
-  * ComponentArrays.jl - https://github.com/jonniedie/ComponentArrays.jl
-  * Crayons - https://github.com/KristofferC/Crayons.jl
-  * DataFrames.jl - https://github.com/JuliaData/DataFrames.jl
-  * DiffEqBase.jl - https://github.com/SciML/DiffEqBase.jl
-  * DifferentialEquations.jl - https://github.com/SciML/DifferentialEquations.jl
-  * Distributions.jl - https://github.com/JuliaStats/Distributions.jl
-  * Documenter - https://github.com/JuliaDocs/Documenter.jl
-  * DocumenterMarkdown - https://github.com/JuliaDocs/DocumenterMarkdown.jl
-  * GeneratedExpressions.jl - https://github.com/Merck/GeneratedExpressions.jl
-  * IJulia - https://github.com/JuliaLang/IJulia.jl
-  * JLD2 - https://github.com/JuliaIO/JLD2.jl
-  * JSON.jl - https://github.com/JuliaIO/JSON.jl
-  * MacroTools.jl - https://github.com/FluxML/MacroTools.jl
-  * NLopt - https://github.com/JuliaOpt/NLopt.jl
-  * OrdinaryDiffEq - https://github.com/SciML/OrdinaryDiffEq.jl
-  * Plots - https://github.com/JuliaPlots/Plots.jl
-  * Pluto.jl - https://github.com/fonsp/Pluto.jl
-  * Reexport - https://github.com/simonster/Reexport.jl
-  * SafeTestsets - https://github.com/YingboMa/SafeTestsets.jl
-  * Statistics.jl - https://github.com/JuliaStats/Statistics.jl
-  * StatsFuns.jl - https://github.com/JuliaStats/StatsFuns.jl
-  * Symbolics.jl - https://github.com/JuliaSymbolics/Symbolics.jl
-  * TOML.jl - https://github.com/JuliaLang/TOML.jl
-  * Tables.jl - https://github.com/JuliaData/Tables.jl
-
-The Unlicense (https://opensource.org/licenses/unlicense)
-  * PlutoUI.jl - https://github.com/JuliaPluto/PlutoUI.jl
+  * The Julia Language - https://github.com/JuliaLang/julia/blob/master/LICENSE.md