apc-model-parser 0.1.0__tar.gz → 0.2.1__tar.gz

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/AGENTS.md

@@ -94,8 +94,8 @@ uv run mkdocs build --strict
 ### Pure logic vs. I/O separation
 
 **Pure modules** parse, normalize, validate, and lower — no filesystem,
-subprocess, or network access. Keep `ir/`, `frontends/`, `backends/`, and
-`validation/` pure and deterministic.
+subprocess, or network access. Keep `ir/`, `frontends/`, `backends/`,
+`semantic_diff.py`, and `validation/` pure and deterministic.
 
 **I/O modules** read/write files and implement the CLI. `io.py` and `cli.py` own
 filesystem access; the CLI must stay a thin shell over the pure functions.
@@ -133,7 +133,9 @@ never a serialized `System`. Generated Julia targets **MTK v11** idioms
 
 Re-running `parse`/`emit` on unchanged input must produce byte-identical output
 (stable ordering, stable number formatting). The content hash depends only on
-the semantic body.
+the semantic body. For `provenance.created_at`, when `SOURCE_DATE_EPOCH` is set
+(see reproducible-builds.org), the INI frontend uses that instant instead of the
+wall clock so regenerated IR JSON stays stable when semantics are unchanged.
 
 ### Status vocabulary and exit codes
 
@@ -149,7 +151,8 @@ CLI diagnostics use `OK` · `WARN` · `ERROR`. Exit codes:
 
 - Long options in kebab-case (`--from`, `--profile`, `--output`/`-o`).
 - The two core verbs are `parse` (authoring → IR) and `emit <target>` (IR →
-  view). Supporting commands: `validate`, `inspect`, `ast`, `schema`.
+  view). Supporting commands: `validate`, `inspect`, `diff`, `bump`, `ast`,
+  `schema`.
 - Breaking CLI changes require a SemVer bump and release notes.
 
 ## Scope guardrails
@@ -164,13 +167,16 @@ that *consume* the IR.
 If a change request conflicts with the design doc, stop and resolve via an
 explicit doc + ADR update — do not silently expand scope.
 
-## Work tracking (ADRs and issues)
+## Work tracking (ADRs, issues, and todos)
 
 - **ADRs:** numbered files under [`docs/decisions/`](docs/decisions/) (`NNNN-title.md`),
   indexed in [`docs/decisions/index.md`](docs/decisions/index.md). One decision per
   file; never delete — supersede with a newer ADR and update the index.
 - **Issues:** use GitHub issues for backlog items that are not yet an ADR; link
   ADRs from issue/PR text when a decision motivates the change.
+- **Todo briefs:** theme-sized notes under [`docs/todo/`](docs/todo/) (`index.md` +
+  one file per theme); promote into ADRs or design docs when behaviour is
+  decided. Not a substitute for issues or ADRs.
 - Prefer **small, reviewable slices** (one coherent feature, bugfix, or refactor
   per PR when practical). For larger work, split PRs and reference the same ADR
   or design section in each.
@@ -203,7 +209,7 @@ docs may stay in `julia/ModelParserJL/` README until unified.
 
 **Intended layout** (keep consistent with [`docs/design/model-parser.md`](docs/design/model-parser.md)):
 
-- `docs/index.md` or root `README.md` — overview, install (`uv`), quick `parse` /
+- `docs/index.md` or root `README.md` — overview, install (PyPI via `pipx` / `uv tool`, dev via `uv`), quick `parse` /
   `emit` examples (when expanded).
 - `docs/design/` — product spec (`model-parser.md`) and deep architecture notes.
 - `docs/decisions/` — ADRs (`NNNN-title.md`) + `index.md`.

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apc-model-parser
-Version: 0.1.0
+Version: 0.2.1
 Summary: Convert process-model definitions to and from a canonical intermediate representation.
 Project-URL: Repository, https://github.com/Advanced-Process-Control/model-parser
 Author: Advanced Process Control
@@ -50,7 +50,21 @@ in-memory, dynamic workflows. Both consume the *same* IR. See
 
 ## Install
 
-This project uses **[uv](https://docs.astral.sh/uv/)** for everything.
+### CLI from PyPI (end users)
+
+The package on PyPI is **`apc-model-parser`**; the installed command is **`model-parser`**.
+
+```bash
+pipx install apc-model-parser
+# or: uv tool install apc-model-parser
+model-parser --help
+```
+
+Use **`pipx`** or **`uv tool`** when you only need the CLI in an isolated environment.
+
+### From source (development)
+
+This repository uses **[uv](https://docs.astral.sh/uv/)** for environments and tasks.
 
 ```bash
 uv sync --all-groups    # include dev tools (ruff, pytest, mkdocs)
@@ -69,6 +83,8 @@ uv run model-parser emit julia monod.ir.json -o monod.jl
 # Supporting commands
 uv run model-parser validate monod.ir.json --profile julia-analysis
 uv run model-parser inspect  monod.ir.json
+uv run model-parser diff     monod.ir.json other.ir.json   # semantic IR diff
+uv run model-parser bump     monod.ir.json other.ir.json   # suggested SemVer bump
 uv run model-parser ast      examples/models/model_monod_simple.ini   # debug tree
 uv run model-parser schema   -o schemas/canonical-ir.schema.json      # export schema
 ```

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/README.md

@@ -37,7 +37,21 @@ in-memory, dynamic workflows. Both consume the *same* IR. See
 
 ## Install
 
-This project uses **[uv](https://docs.astral.sh/uv/)** for everything.
+### CLI from PyPI (end users)
+
+The package on PyPI is **`apc-model-parser`**; the installed command is **`model-parser`**.
+
+```bash
+pipx install apc-model-parser
+# or: uv tool install apc-model-parser
+model-parser --help
+```
+
+Use **`pipx`** or **`uv tool`** when you only need the CLI in an isolated environment.
+
+### From source (development)
+
+This repository uses **[uv](https://docs.astral.sh/uv/)** for environments and tasks.
 
 ```bash
 uv sync --all-groups    # include dev tools (ruff, pytest, mkdocs)
@@ -56,6 +70,8 @@ uv run model-parser emit julia monod.ir.json -o monod.jl
 # Supporting commands
 uv run model-parser validate monod.ir.json --profile julia-analysis
 uv run model-parser inspect  monod.ir.json
+uv run model-parser diff     monod.ir.json other.ir.json   # semantic IR diff
+uv run model-parser bump     monod.ir.json other.ir.json   # suggested SemVer bump
 uv run model-parser ast      examples/models/model_monod_simple.ini   # debug tree
 uv run model-parser schema   -o schemas/canonical-ir.schema.json      # export schema
 ```

apc_model_parser-0.2.1/docs/chatlogs/2026-06-01_docs-pipx-pypi-install.md

@@ -0,0 +1,62 @@
+---
+title: Document PyPI CLI install (pipx and uv tool)
+topic: docs-packaging
+date_added: 2026-06-01
+tags: [chatlogs]
+links:
+  - README.md
+  - docs/index.md
+  - docs/deployment/ci-cd.md
+  - AGENTS.md
+---
+
+## Commit helper
+
+- **SemVer / version bump:** **No bump** — documentation only; no change to the
+  published package API or CLI contract beyond how to install it.
+- **Tags / GitHub Release:** **None** — stack on `main`; releases remain tag-driven
+  when version/metadata changes warrant a new **`v*.*.*`**.
+- **Suggested commit message:** `docs: document pipx and uv tool install for apc-model-parser`
+- **Copy-paste git commands:**
+
+```bash
+git add README.md docs/index.md docs/deployment/ci-cd.md AGENTS.md \
+        docs/chatlogs/2026-06-01_docs-pipx-pypi-install.md
+git commit -m 'docs: document pipx and uv tool install for apc-model-parser'
+```
+
+- **Git order when tagging a release:** N/A this session.
+
+## How to try
+
+```bash
+pipx install apc-model-parser
+model-parser --help
+
+# Alternative (same CLI, different installer):
+# uv tool install apc-model-parser
+
+# Docs site (after deploy):
+# uv run mkdocs build --strict
+```
+
+## Session narrative
+
+**Goal.** After the first PyPI publish and manual **`v0.1.0`** tag, document that
+end users can install the CLI with **`pipx install apc-model-parser`**, not only
+**`uv tool install`**, while keeping **`apc-model-parser`** vs **`model-parser`**
+(dist name vs command) explicit.
+
+**Shipped surface.**
+
+- **`README.md`:** Install split into **CLI from PyPI** (`pipx` primary, `uv tool`
+  comment) and **from source** (`uv sync --all-groups`).
+- **`docs/index.md`:** Published site home — same dual path for PyPI installs;
+  short note that both are isolated env installs with `model-parser` on `PATH`.
+- **`docs/deployment/ci-cd.md`:** One line after the release job listing consumer
+  **`pipx`** / **`uv tool install`** post-publish.
+- **`AGENTS.md`:** Documentation layout bullet updated to mention PyPI install via
+  **`pipx` / `uv tool`** and dev via **`uv`**.
+
+**Follow-ups.** None required; optional future “Getting started” page could repeat
+install if the nav grows.

apc_model_parser-0.2.1/docs/chatlogs/2026-06-02_model-library-docs-diff-bump.md

@@ -0,0 +1,63 @@
+---
+title: Model library design, diff/bump CLI, and model-library bootstrap
+topic: documentation
+date_added: 2026-06-02
+tags: [chatlogs]
+links:
+  - AGENTS.md
+  - docs/design/model-parser.md
+  - docs/design/model-library-and-versioning.md
+  - src/model_parser/cli.py
+  - src/model_parser/semantic_diff.py
+  - src/model_parser/frontends/exprtk_ini.py
+---
+
+## Commit helper
+
+- **SemVer / version bump:** **MINOR** — user-visible CLI (`diff`, `bump`), new pure module `semantic_diff.py`, and `SOURCE_DATE_EPOCH` behaviour for `provenance.created_at` are new public behaviour (not docs-only).
+- **Tags / GitHub Release:** **None** — stack on default branch; tag when maintainers cut a release (existing `release.yml` on tag).
+- **Suggested commit message:** `feat(cli): add IR diff/bump and model-library design doc`
+- **Copy-paste git commands:**
+
+```bash
+git add AGENTS.md README.md docs/design/model-library-and-versioning.md \
+  docs/design/model-parser.md docs/design/ir-specification.md \
+  docs/index.md docs/chatlogs/2026-06-02_model-library-docs-diff-bump.md \
+  mkdocs.yml src/model_parser/cli.py src/model_parser/semantic_diff.py \
+  src/model_parser/frontends/exprtk_ini.py tests/test_cli.py tests/test_semantic_diff.py
+git commit -m "$(cat <<'EOF'
+feat(cli): add IR diff/bump and model-library design doc
+
+Add semantic comparison and advisory SemVer bump; document library workflows;
+honour SOURCE_DATE_EPOCH for reproducible IR provenance timestamps.
+EOF
+)"
+```
+
+- **Git order when tagging:** commit / push branch (with version bump if releasing) → annotated tag on that commit → push tag.
+
+## How to try
+
+```bash
+cd /path/to/model-parser
+uv sync --all-groups
+uv run model-parser parse examples/models/model_monod_simple.ini -o /tmp/a.ir.json
+uv run model-parser parse examples/models/model_monod_simple.ini -o /tmp/b.ir.json
+uv run model-parser diff /tmp/a.ir.json /tmp/b.ir.json
+uv run model-parser bump /tmp/a.ir.json /tmp/b.ir.json --json
+SOURCE_DATE_EPOCH=946684800 uv run model-parser parse examples/models/model_monod_simple.ini -o /tmp/c.ir.json
+uv run pytest tests/test_semantic_diff.py
+uv run mkdocs build --strict
+```
+
+Sibling repo `model-library`: set `MODEL_PARSER_VENV` to this repo’s `.venv` and run `./scripts/sync.sh` (see that repo’s README).
+
+## Session narrative
+
+**Goal:** Capture the prior design answer in-repo, add `diff` / `bump` to support a versioned model library, and bootstrap `Advanced-Process-Control/model-library` with the two existing example models.
+
+**Shipped:** New design page `docs/design/model-library-and-versioning.md` (hashes vs SemVer vs git, workflows, authoring vs parameter sets, optimal multi-file layout, reproducible timestamps); nav and cross-links (`mkdocs.yml`, `docs/index.md`, `model-parser.md`, `ir-specification.md`); `src/model_parser/semantic_diff.py` with conservative bump policy; CLI commands `diff` and `bump` (`--json`); INI frontend respects `SOURCE_DATE_EPOCH` for `provenance.created_at`; tests (`tests/test_semantic_diff.py`, CLI smoke); README and `AGENTS.md` updates.
+
+**model-library repo:** Added `models/monod_simple` and `models/thermal_tank` with copied authoring INIs, `scripts/sync.sh` + `scripts/update_lock.py`, committed generated `model.ir.json` / `views/model.jl`, `library.lock.json`, README, and GitHub Actions CI that installs `model-parser` from git `main` and fails on drift after sync.
+
+**Follow-ups:** Optional ADR for bump policy; `emit ini` and parameter-set JSON remain roadmap; publish a PyPI release so CI can pin a version instead of `main` if desired.

apc_model_parser-0.2.1/docs/chatlogs/2026-06-03_docs-todo-backlog-mkdocs.md

@@ -0,0 +1,47 @@
+---
+title: Tracked todo briefs under docs/todo and MkDocs nav
+topic: documentation
+date_added: 2026-06-03
+tags: [chatlogs]
+links:
+  - AGENTS.md
+  - docs/todo/index.md
+  - mkdocs.yml
+  - docs/index.md
+---
+
+## Commit helper
+
+- **SemVer / version bump:** **no bump** — documentation and contributor-guide updates only (`docs/todo/**`, `mkdocs.yml`, `docs/index.md`, `AGENTS.md`). No user-visible CLI or IR contract change.
+- **Tags / GitHub Release:** **None** — stack on default branch.
+- **Suggested commit message:** `docs: add tracked todo backlog under docs/todo`
+- **Copy-paste git commands:**
+
+```bash
+git add AGENTS.md docs/index.md docs/todo/ mkdocs.yml \
+  docs/chatlogs/2026-06-03_docs-todo-backlog-mkdocs.md
+git commit -m "$(cat <<'EOF'
+docs: add tracked todo backlog under docs/todo
+
+Add theme-sized future-work briefs, MkDocs Future work nav, and AGENTS work-tracking note.
+EOF
+)"
+```
+
+- **Git order when tagging:** N/A (no release in this slice).
+
+## How to try
+
+```bash
+cd /path/to/model-parser
+uv run mkdocs build --strict
+# optional: open docs/todo/index.md in the editor or browse site → Future work
+```
+
+## Session narrative
+
+**Goal:** Add a `docs/todo/` area with one Markdown file per major future implementation theme, wired into the published docs site, and record guidance on whether `model-library`’s `sync.sh` should auto-commit/push (recommendation: keep sync as regenerate-only; optional separate commit helper; avoid default auto-push).
+
+**Shipped:** `docs/todo/index.md` plus seven task files (`emit-ini-round-trip`, `emit-cpp-realtime-backend`, `ir-schema-migrations`, `parameter-set-contract-cli`, `conformance-fixtures-parity`, `ini-dimensions-inference`, `diff-bump-hardening`); `mkdocs.yml` **Future work** nav listing all pages (satisfies `--strict`); link from `docs/index.md`; `AGENTS.md` **Work tracking** section renamed to include todo briefs and clarify they complement ADRs/issues. MkDocs strict fixes: removed invalid links from `docs/` into `src/` / repo root; use code spans or in-repo doc links only.
+
+**Follow-ups:** Optional `model-library` script `sync-and-commit.sh` (opt-in commit, no default push) if maintainers want scripted commits; promote individual todo themes into GitHub issues or ADRs when scoped.

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/docs/deployment/ci-cd.md

@@ -41,6 +41,8 @@ The job:
 3. Creates a **GitHub Release** (with generated notes) and attaches the built files
 4. Publishes to **PyPI** using **trusted publishing (OIDC)** — no long-lived API token in secrets
 
+After publish, end users typically install the CLI with **`pipx install apc-model-parser`** or **`uv tool install apc-model-parser`** (command on `PATH`: **`model-parser`**).
+
 ### PyPI trusted publisher
 
 Configure the pending publisher on PyPI for:

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/docs/design/ir-specification.md

@@ -53,7 +53,9 @@ one namespace; duplicates are a validation error.
 
 `provenance.content_hash` is `sha256` over the canonical JSON of the IR body
 **excluding** `provenance`. Downstream artifacts reference a scaffold by this
-hash, not by file path.
+hash, not by file path. For how this interacts with a versioned model library,
+SemVer, and git, see
+[`model-library-and-versioning.md`](model-library-and-versioning.md).
 
 ## 3. Expression sub-language
 

apc_model_parser-0.2.1/docs/design/model-library-and-versioning.md

@@ -0,0 +1,147 @@
+# Model library, content hashing, and semantic versioning
+
+> How a **version-controlled model library** (for example the sibling repository
+> [`Advanced-Process-Control/model-library`](https://github.com/Advanced-Process-Control/model-library))
+> fits the ecosystem, how **`model-parser`** participates without becoming a
+> registry or deployment tool, and how **hashes**, **SemVer**, and **git** play
+> different roles.
+
+## 1. Three axes of “version”
+
+Do not collapse these into one number. They answer different questions.
+
+| Axis | Question | Mechanism | Analogy |
+|------|-----------|-----------|---------|
+| **Content hash** | Are two scaffolds *semantically identical*? Did anything meaningful change? | `provenance.content_hash` in the IR (`sha256` over the semantic body, excluding `provenance`) | Content-addressed blob id |
+| **Semantic model version** | Is this change backward-compatible for consumers of the scaffold API? | Human or tool-assigned SemVer (e.g. `model.source_version` plus release policy) | Library SemVer |
+| **History / lineage** | Who changed what, when, and why? How do we review, branch, and roll back? | Git commits, tags, PRs | Git history |
+
+The content hash is **identity and integrity**, not history. It supports deduplication, cache keys, cross-repository references (“this parameter set was fitted against scaffold `sha256:…`”), and CI checks that regenerated artifacts still match the IR. It does **not** replace git, and it is a poor user-facing release label.
+
+See also [`ir-specification.md`](ir-specification.md) (identity / `content_hash`) and [`storing-mtk-models.md`](storing-mtk-models.md) (durable IR + generated `.jl`).
+
+## 2. What the hash is good for
+
+- **Drift detection** — Re-emit Julia (or future backends) in CI and assert outputs match expectations, or compare to a lockfile that records per-artifact digests.
+- **Cache keys** — Compiled problems or other caches should key on `content_hash`, target profile, and relevant toolchain versions (see *Storing MTK models* §4).
+- **Pins without paths** — Downstream contracts reference the scaffold by hash, not by repository path (“hashes over file paths” org vocabulary).
+- **Equivalence** — Two authoring files that normalize to the same IR yield the same hash (useful for detecting accidental duplicates or proving a refactor was semantics-preserving).
+
+## 3. Semantic diff and inferred bumps
+
+Because expressions live in an **explicit tagged tree** in the IR (not strings; see [ADR 0003](../decisions/0003-explicit-expression-ir.md)), the tool can compare two IRs structurally and suggest a **SemVer bump** for the *model* (distinct from `ir_version`, which versions the IR schema).
+
+The CLI exposes:
+
+```text
+model-parser diff  <old.ir.json> <new.ir.json> [--json]
+model-parser bump  <old.ir.json> <new.ir.json> [--json]
+```
+
+`diff` lists human-readable changes. `bump` prints a suggested bump level:
+
+| Level | Typical meaning (conservative policy) |
+|-------|----------------------------------------|
+| `none` | Semantic bodies are identical (`content_hash` match). |
+| `patch` | Documentation-like or bootstrap tweaks only: e.g. `ModelInfo` description / `source_version` / `metadata`, variable `unit` / `description` / `roles`, `profiles`, or **only** numeric **defaults** on existing parameters (same names, same order). |
+| `minor` | **Additive** scaffold API: new parameters **appended** after all previous parameters, with unchanged names and defaults for all previous parameters, and no change to states, inputs, outputs, locals, or equations. |
+| `major` | Anything else: renamed model, changed state/input/output set, changed equations, changed local expressions, removed or reordered parameters, `ir_version` or `independent_variable` change, or any change not covered by `patch` / `minor`. |
+
+Policies can evolve; treat `bump` as **advisory** until your library documents stricter rules. When in doubt, the implementation prefers **major** over false compatibility.
+
+## 4. Where logic lives: parser vs library repository
+
+**Inside `model-parser` (IR contract, pure logic):**
+
+- `parse` / `emit` / `validate` / hashing / JSON Schema.
+- **`diff` and `bump`** — semantic comparison and bump *suggestion* (no git, no catalog).
+
+**Inside `model-library` (orchestration, I/O):**
+
+- Directory layout, **lockfile** / catalog, CI that regenerates artifacts and fails on drift.
+- Git tags, release notes, and human curation.
+
+This keeps `model-parser` small and standalone (see [`model-parser.md`](model-parser.md) §2 and *Non-goals*) while still enabling a “living” multi-representation library.
+
+## 5. Suggested `model-library` layout
+
+One directory per model; **one authoring file** is the human edit surface; IR and lowered views are **generated** and committed (or generated only in CI — your choice; the sibling repo defaults to committed artifacts for reviewability).
+
+```text
+models/<name>/
+  model.ini              # authoring (ExprTk INI today)
+  model.ir.json          # canonical IR (generated by model-parser parse)
+  views/
+    model.jl             # generated by model-parser emit julia
+library.lock.json        # index: names, paths, content_hash, optional view hashes
+```
+
+A thin driver (`scripts/sync.sh`, `just`, or Makefile) invokes the installed `model-parser`. CI runs the same pipeline with `--strict` checks (e.g. `git diff --exit-code` after sync).
+
+## 6. End-to-end workflow
+
+```mermaid
+flowchart TD
+    A[Edit models/foo/model.ini] --> B[model-parser parse → model.ir.json]
+    B --> C{content_hash changed vs baseline?}
+    C -- no --> Z[No semantic change; optional doc-only commit]
+    C -- yes --> D[model-parser diff / bump vs previous release IR]
+    D --> E[Regenerate views emit julia …]
+    E --> F[Update library.lock.json and changelog]
+    F --> G[Commit; tag if releasing]
+    G --> H[CI: re-sync or re-emit; fail on drift]
+```
+
+Do **not** hand-edit generated `.jl` files; they are compilation products (see [`storing-mtk-models.md`](storing-mtk-models.md)). Planned `emit ini` round-trip (product roadmap) will reduce the need to maintain two authoring encodings by hand.
+
+## 7. Scaffold vs parameter sets vs scenarios (authoring files)
+
+The IR intentionally describes the **scaffold** only: structure, equations, roles, units, parameter **declarations** (optional defaults for bootstrap). **Parameter sets** and **scenarios** are **sibling contracts** (fitted values, `x0`/`u0`, horizons) — not stored in the canonical IR as execution truth.
+
+### Current ExprTk INI
+
+Today’s frontend documents that **`[x0]` / `[u0]` are dropped** with a warning because they are scenario data ([`model-parser.md`](model-parser.md) §4). **`[Dimensions]`** is still required: it declares how many `x*`, `u*`, and `y*` slots exist before equations are parsed. In principle, counts could be **inferred** from the maximum indices appearing in `dx*`, `y*`, and `u*` references; that would be a **frontend enhancement**, not an IR change.
+
+### Should parameter *values* leave the INI?
+
+**Ideal split (org contracts):**
+
+- **Scaffold** — declares parameters (names, units, bounds later); optional defaults only for convenience / tests.
+- **Parameter set** — JSON (or similar) referencing the scaffold by **`content_hash`**, carrying the numeric values used for calibration or deployment.
+- **Scenario** — references scaffold (and optionally a parameter set), carries `x0`, `u0`, horizon, etc.
+
+Whether values also appear in the INI is a **workflow choice**:
+
+- Keeping numeric defaults in INI is convenient for quick `parse → emit` demos and matches legacy MPC files.
+- Moving values entirely into parameter sets is cleaner for **governance** (one hash-pinned scaffold, many value sets) and avoids duplicating “truth” in two places.
+
+`model-parser` does not yet ship a parameter-set file format; when the org standardizes one, the library should adopt it alongside the IR.
+
+### Optimal authoring format (if not tied to INI)
+
+A greenfield layout often works well as **two or three small files per model** (or one folder):
+
+1. **`scaffold.*`** — YAML or TOML: metadata, symbol tables, equations as structured expressions *or* as controlled strings parsed by the same expression grammar. YAML maps naturally to nested expression trees for tooling.
+2. **`parameters.default.json`** — optional; references `content_hash` of the IR once emitted, or references `model.name` + lockfile version for humans.
+3. **`scenario.*`** — initial conditions, setpoints, simulation horizon.
+
+The important part is not the concrete syntax but the **separation of concerns** and a single **semantic hub** (the IR) so backends stay renderers, not re-parsers.
+
+## 8. Reproducible provenance timestamps
+
+For committed IR JSON, `provenance.created_at` would otherwise change on every regeneration. When **`SOURCE_DATE_EPOCH`** is set (Unix epoch seconds, per [reproducible-builds.org](https://reproducible-builds.org/docs/source-date-epoch/)), the INI frontend uses it for `created_at` instead of the wall clock. Library sync scripts can export this variable so IR files stay byte-stable when semantics are unchanged.
+
+## 9. Larger roadmap (optional)
+
+- **Library lockfile** — pins each model’s `content_hash` and digests of generated views; CI verifies them.
+- **`emit ini` round-trip** — product roadmap item; reduces manual dual maintenance of INI and other views.
+- **`ir_version` migrations** — when the IR schema bumps, migration tooling plus ADRs ([`ir-specification.md`](ir-specification.md) §5).
+- **Composite models** — dependency graph of scaffolds; composite content hash derived from constituents (Merkle-style).
+- **Signing / extended provenance** — optional fields for signer identity, git commit SHA, parent scaffold hash (policy and ADR when needed).
+
+## 10. Related documents
+
+- [`model-parser.md`](model-parser.md) — product scope and CLI overview.
+- [`ir-specification.md`](ir-specification.md) — IR shape and `content_hash` definition.
+- [`storing-mtk-models.md`](storing-mtk-models.md) — IR + generated `.jl` as durable artifacts.
+- [`language-strategy.md`](language-strategy.md) — Python/Julia split at the IR file boundary.

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/docs/design/model-parser.md

@@ -85,6 +85,8 @@ model-parser parse   <authoring-file> [--from exprtk-ini] [-o out.ir.json]
 model-parser emit julia <model.ir.json>                     [-o out.jl]
 model-parser validate <model.ir.json | authoring-file> [--profile <name>]
 model-parser inspect  <model.ir.json | authoring-file>
+model-parser diff     <old.ir.json> <new.ir.json>         [--json]
+model-parser bump     <old.ir.json> <new.ir.json>         [--json]
 model-parser ast      <authoring-file>                      [-o out.json]
 model-parser schema                                         [-o schema.json]
 ```
@@ -97,6 +99,10 @@ model-parser schema                                         [-o schema.json]
   fly), and an optional `--profile`.
 - `inspect` prints a human summary; `ast` exports a debug tree; `schema` exports
   the JSON Schema.
+- `diff` compares two canonical IR files and lists semantic changes; `bump`
+  suggests a **SemVer bump** (`none` / `patch` / `minor` / `major`) for the model
+  using a conservative policy (see
+  [`model-library-and-versioning.md`](model-library-and-versioning.md)).
 
 Exit codes: `0` success · `1` validation errors · `2` usage/load failure.
 Diagnostics use the `OK` / `WARN` / `ERROR` vocabulary.
@@ -131,7 +137,8 @@ model can be valid for Julia analysis while being rejected for a PLC target.
 ## 8. Roadmap
 
 1. **Now (MVP):** ExprTk-INI frontend, canonical IR + schema, core validators,
-   Julia codegen backend, Julia in-memory loader, example pipeline.
+   Julia codegen backend, Julia in-memory loader, example pipeline; semantic
+   `diff` / `bump` for library workflows.
 2. **Conformance:** shared IR fixtures with expected Julia output and (later)
    expected trajectories, run by both the Python codegen and `ModelParserJL`.
 3. **Round-trip:** `emit ini` and `export` from a Julia/MTK view back to IR,

{apc_model_parser-0.1.0 → apc_model_parser-0.2.1}/docs/index.md

@@ -16,16 +16,24 @@ authoring (ExprTk INI)  --parse-->  AST  --normalize-->  canonical IR (JSON)
 ## Where to read next
 
 - **[Product specification](design/model-parser.md)** — authoritative scope, CLI, and behaviour.
+- **[Model library & versioning](design/model-library-and-versioning.md)** — hashes, SemVer, sibling `model-library`, authoring vs parameter sets.
+- **[Future work / todos](todo/index.md)** — tracked implementation themes (not a substitute for issues or ADRs).
 - **[IR specification](design/ir-specification.md)** — IR shape and expression language.
 - **[Decision log](decisions/index.md)** — ADRs for major design choices.
 - **[PyPI package `apc-model-parser`](https://pypi.org/project/apc-model-parser/)** — installable CLI (`model-parser`).
 
-## Install (uv)
+## Install from PyPI
+
+The distribution name is **`apc-model-parser`**; the CLI entry point is **`model-parser`**.
 
 ```bash
+pipx install apc-model-parser
+# or:
 uv tool install apc-model-parser
+
 model-parser --help
 ```
 
-For development, clone the repository and use `uv sync --all-groups` (see
-[CI/CD and releases](deployment/ci-cd.md)).
+**`pipx`** and **`uv tool`** both install the tool into an isolated environment and put `model-parser` on your `PATH`.
+
+For **development** from a clone, use **`uv sync --all-groups`** (see [CI/CD and releases](deployment/ci-cd.md)).

apc_model_parser-0.2.1/docs/todo/conformance-fixtures-parity.md

@@ -0,0 +1,29 @@
+# TODO: Conformance fixtures and cross-language parity
+
+## Goal
+
+Grow **shared IR fixtures** with **expected Julia codegen** (and later
+**expected trajectories** or numerical checks), executed in **Python** and
+**Julia** (`ModelParserJL`) so the two runtimes cannot drift silently.
+
+## Why
+
+- [`docs/design/language-strategy.md`](../design/language-strategy.md): the IR
+  file is the boundary; parity tests are the enforcement mechanism.
+- Reduces regression risk whenever MTK idioms or codegen change (see ADR 0004).
+
+## Scope hints
+
+- Start with golden `.jl` snippets or full files under `tests/` or `examples/`.
+- Julia side: documented `Pkg.test` or script in CI (may remain optional job
+  until Julia CI is wired).
+
+## References
+
+- [`docs/design/model-parser.md`](../design/model-parser.md) roadmap §2.
+- [ADR 0001](../decisions/0001-python-cli-with-julia-backend.md), [ADR 0004](../decisions/0004-target-mtk-v11-idioms.md).
+
+## Acceptance sketch
+
+- At least N≥2 fixtures with checked `emit julia` output.
+- Document how to refresh goldens when codegen intentionally changes.

apc_model_parser-0.2.1/docs/todo/diff-bump-hardening.md

@@ -0,0 +1,30 @@
+# TODO: Harden `diff` / `bump` for library CI
+
+## Goal
+
+Evolve **`model-parser diff`** and **`model-parser bump`** from advisory output
+into optional **CI gates**: stricter classification, exit codes, and documented
+policy for how `model-library` (and others) should interpret results.
+
+## Why
+
+- Libraries want “fail if this would be a MAJOR bump without version bump” or
+  similar policies.
+- Edge cases (e.g. floating-point literal normalization, metadata-only churn)
+  need explicit rules.
+
+## Scope hints
+
+- Flags sketch: `--fail-on major`, `--json` stable schema versioning.
+- Extend `src/model_parser/semantic_diff.py` with tests for each policy branch.
+- Cross-link from [`docs/design/model-library-and-versioning.md`](../design/model-library-and-versioning.md).
+
+## References
+
+- `src/model_parser/cli.py` (`diff`, `bump`).
+- `tests/test_semantic_diff.py`.
+
+## Acceptance sketch
+
+- Documented policy table + tests for CI-oriented flags.
+- Example GitHub Actions snippet in `model-library` or parser deployment docs.

apc_model_parser-0.2.1/docs/todo/emit-cpp-realtime-backend.md

@@ -0,0 +1,31 @@
+# TODO: `emit cpp` (real-time C++ backend)
+
+## Goal
+
+Implement **`model-parser emit cpp`** that lowers IR into a **deterministic,
+real-time-safe** C++ representation for PLC / embedded targets, aligned with the
+existing **`realtime-cpp`** validation profile.
+
+## Why
+
+- Second major consumer of the same IR after Julia, proving the hub-and-spoke
+  design (one expression tree, many renderers).
+- Org roadmap: trajectory or numerical parity checks against the Julia path
+  where feasible.
+
+## Scope hints
+
+- Constrain to profile-checked operators/functions only; reject or warn clearly.
+- Pure codegen in Python; no new runtime dependency for users who only need IR
+  or Julia.
+
+## References
+
+- [`docs/design/model-parser.md`](../design/model-parser.md) roadmap §4.
+- `src/model_parser/validation/validators.py` (profile behaviour).
+
+## Acceptance sketch
+
+- CLI: `emit cpp` with `-o` path.
+- Tests: small IR fixture and expected `.cpp` (or fragment) under `tests/` or
+  `examples/`.