Rework of decider

.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "decikit",
+  "owner": {"name": "Capitec DSP"},
+  "description": "Claude Code plugin for building decision pipelines with the decider toolkit.",
+  "plugins": [
+    {
+      "name": "decikit",
+      "source": "./plugins/decikit",
+      "description": "Skill and MCP server for decider toolkit projects: pipelines, flow files, decision trees, decision tables, scorecards and params."
+    }
+  ]
+}

.dockerignore

@@ -1,11 +1,18 @@
 # Ignore everything then whitelist what the image actually needs
 *
 
-# Package source and build artefacts
-!/decider
-!/dist
+# Package source (the builder stage builds the wheel from these)
+!/decikit
 !/pyproject.toml
-!/uv.lock
+!/README.md
+
+# In-repo example projects (PROJECT=examples/<name>), without their tests and generators
+!/examples
+/examples/*/tests
+/examples/*/scripts
+
+# Docker helpers
+!/docker/bake.sh
 
 # Strip noise from allowed directories
 **/__pycache__

.gitattributes

@@ -2,4 +2,4 @@
 * text=auto
 
 # Mark generated version file so it survives `git archive --export-subst`
-decider/_version.py export-subst
+decikit/_version.py export-subst

.github/workflows/release.yml

@@ -5,8 +5,13 @@ on:
     tags:
       - 'v[0-9]*'
 
+# Jobs that need more ask for it themselves.
+permissions:
+  contents: read
+
 env:
   DOCKER_IMAGE: sjnarmstrong/pydecider
+  TREE_EDITOR_IMAGE: sjnarmstrong/decider-tree-editor
 
 jobs:
   # ── 1. Resolve version from git tags (hatch-vcs) ──────────────────────────
@@ -31,7 +36,7 @@ jobs:
         id: get
         run: |
           uv sync --group dev
-          VERSION=$(uv run python -c "from importlib.metadata import version; print(version('decider'))")
+          VERSION=$(uv run python -c "from importlib.metadata import version; print(version('decikit'))")
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
 
   # ── 2a. Build wheel → PyPI ─────────────────────────────────────────────────
@@ -40,7 +45,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: release
-      url: https://pypi.org/p/decider
+      url: https://pypi.org/p/decikit
     permissions:
       id-token: write     # OIDC trusted publishing — no token secret needed
     steps:
@@ -113,6 +118,7 @@ jobs:
           context: .
           file: docker/Dockerfile
           push: true
+          build-args: VERSION=${{ needs.version.outputs.version }}
           tags: ${{ env.DOCKER_IMAGE }}:${{ needs.version.outputs.version }}
           cache-from: type=gha
           cache-to:   type=gha,mode=max
@@ -123,9 +129,48 @@ jobs:
           context: .
           file: docker/Dockerfile
           push: true
+          build-args: VERSION=${{ needs.version.outputs.version }}
           tags: ${{ env.DOCKER_IMAGE }}:latest
           cache-from: type=gha
 
+  # ── 2b'. Build and push the tree-editor image ─────────────────────────────
+  publish-tree-editor:
+    needs: [version, publish-pypi]
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push tree-editor image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ui/tree-editor/Dockerfile
+          push: true
+          tags: |
+            ${{ env.TREE_EDITOR_IMAGE }}:${{ needs.version.outputs.version }}
+            ${{ env.TREE_EDITOR_IMAGE }}:latest
+          cache-from: type=gha,scope=tree-editor
+          cache-to:   type=gha,mode=max,scope=tree-editor
+
   # ── 2c. Build and deploy versioned docs to GitHub Pages ───────────────────
   publish-docs:
     needs: version
@@ -151,7 +196,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install docs dependencies
-        run: uv sync --extra docs
+        run: uv sync --group docs
 
       - name: Restore docs from previous release
         env:
@@ -162,7 +207,13 @@ jobs:
           if [ -n "$PREV" ]; then
             gh release download "$PREV" --pattern "docs-site.tar.gz" --dir /tmp/prev-docs 2>/dev/null || true
             if [ -f /tmp/prev-docs/docs-site.tar.gz ]; then
-              tar -xzf /tmp/prev-docs/docs-site.tar.gz -C _site
+              mkdir -p /tmp/prev-site
+              tar -xzf /tmp/prev-docs/docs-site.tar.gz -C /tmp/prev-site
+              # Only the earlier versions' folders: the root is this build, so pages it dropped don't linger there.
+              for v in $(jq -r '.[] | select(. != "latest")' /tmp/prev-site/versions.json); do
+                [ -d "/tmp/prev-site/$v" ] && cp -r "/tmp/prev-site/$v" _site/
+              done
+              cp /tmp/prev-site/versions.json _site/
               echo "Restored docs history from $PREV"
             fi
           fi
@@ -171,10 +222,11 @@ jobs:
         env:
           VERSION: ${{ needs.version.outputs.version }}
         run: |
-          uv run python -m sphinx docs docs/_build/html -b html
+          uv run jupyter nbconvert --to markdown docs/notebooks/*.ipynb --output-dir docs/tutorials
+          uv run zensical build --strict
           mkdir -p _site/$VERSION
-          cp -r docs/_build/html/. _site/$VERSION/
-          cp -r docs/_build/html/. _site/
+          cp -r site/. _site/$VERSION/
+          cp -r site/. _site/
 
       - name: Write versions.json
         env:
@@ -211,7 +263,7 @@ jobs:
 
   # ── 3. Tag and create GitHub Release (after all three deploys succeed) ─────
   github-release:
-    needs: [version, publish-pypi, publish-docker, publish-docs]
+    needs: [version, publish-pypi, publish-docker, publish-tree-editor, publish-docs]
     runs-on: ubuntu-latest
     environment:
       name: release

.github/workflows/tree-editor-merge-core.yml

@@ -0,0 +1,65 @@
+name: Tree editor merge core
+
+# Builds and tests ui/tree-editor/merge-core (the live-editing merge logic) as a Python wheel and as WebAssembly,
+# and runs the shared vectors against both. Publishes nothing.
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ui/tree-editor/merge-core/**
+      - ui/tree-editor/merge-core-bench/**
+      - .github/workflows/tree-editor-merge-core.yml
+
+permissions:
+  contents: read
+
+jobs:
+  merge-core:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui/tree-editor/merge-core
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust toolchain
+        run: |
+          rustup toolchain install 1.95.0 --profile minimal --target wasm32-unknown-unknown
+          rustup default 1.95.0
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/wasm-pack
+            ~/.cargo/registry
+            ~/.cargo/git
+            ui/tree-editor/merge-core/target
+          key: merge-core-${{ hashFiles('ui/tree-editor/merge-core/Cargo.lock') }}
+
+      - name: Install wasm-pack
+        run: command -v wasm-pack || cargo install --locked wasm-pack@0.15.0
+
+      - name: cargo test
+        run: cargo test
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build the wheel (abi3, manylinux_2_28)
+        run: uvx --from 'maturin[zig]==1.15.0' maturin build --release --zig --compatibility manylinux_2_28 -o dist
+
+      - name: Vectors against the wheel (oldest supported Python)
+        working-directory: ui/tree-editor/merge-core-bench
+        run: uv run --no-project --python 3.10 --with ../merge-core/dist/*.whl python run_vectors.py adapters/rust_py.py --strict
+
+      - name: Build pkg/ (WebAssembly)
+        run: wasm-pack build --target web --release --no-pack -- --features wasm
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Vectors against the WebAssembly
+        working-directory: ui/tree-editor/merge-core-bench
+        run: node run_vectors.mjs adapters/rust_wasm.mjs --strict

.gitignore

@@ -16,6 +16,8 @@ downloads/
 eggs/
 .eggs/
 lib/
+!ui/lib/
+!ui/tree-editor/ui/src/lib/
 lib64/
 parts/
 sdist/
@@ -27,6 +29,7 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+.impeccable/
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -71,6 +74,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/tutorials/
 docs/_autosummary/
 
 # PyBuilder
@@ -174,7 +178,15 @@ cython_debug/
 .python-version
 
 # hatch-vcs generated version file
-decider/_version.py
+decikit/_version.py
 
-# project-level extension configs (generated by decider_extensions)
-projects/*/configs/
+# project-level extension configs (generated by decikit_extensions)
+projects/*/configs/
+.scratch/
+
+
+# Benchmark output; the numbers that matter are in docs/design_decisions/experiments/.
+benchmarks/*.csv
+
+# decikit build output
+examples/*/decikit-cpu-target.json

CLAUDE.md

@@ -0,0 +1,85 @@
+# decikit
+
+Use `uv` for everything: `uv run pytest`, `uv run python`. Python 3.10+.
+
+To learn the API as a user: `uv run decikit guide` (`decikit/GUIDE.md`) and the
+docstrings. Every Python example in `GUIDE.md` runs in `tests/test_guide.py`;
+keep it that way.
+
+`docs/` is the docs site (nav in `zensical.toml`; `uv run --group docs zensical
+build`). `docs/design_decisions/` is not published: the decisions behind each
+area, the experiments behind them and `known-limitations.md`.
+Read an area's decision file before changing that area. `docs/design_specs/`
+(also unpublished) holds proposals for work not yet built, one folder per rework.
+
+## Comments and docstrings
+
+- Docstrings only on public API, written as user docs: a one-line summary, the
+  arguments that aren't obvious, and a short example.
+- Private helpers get no docstring unless the behaviour is non-obvious.
+- Inline comments explain why, never what.
+- Never reference docs, section numbers, stages, experiments, review findings or
+  "the agent" in code. No `doc 03`, `§4.2`, `EXPERIMENTS`.
+- Design rationale ("we chose X over Y because Y failed") goes in
+  `docs/design_decisions/decisions/<topic>.md` (a measurement as an experiment in
+  `docs/design_decisions/experiments/`), not in code. Key points only; an open
+  gap goes in `docs/design_decisions/known-limitations.md`.
+
+## Files
+
+- One purpose per file, under 500 lines. When a file grows past that, split it
+  into a package (`foo/__init__.py` plus files) instead.
+- A file-length exception goes in `ALLOWLIST` in `tests/test_conventions.py`;
+  import, `__all__` and layer exceptions go in `tests/conventions_allowlists.py`.
+  Each needs a reason, and stale entries fail the test.
+- `uv run pytest tests/test_conventions.py -q` enforces the line limit and the
+  banned references.
+
+## Writing code
+
+- Invoke the `ponytail:ponytail` skill in `ultra` mode and apply it throughout:
+  the simplest code that passes the tests, no speculative abstractions, stdlib
+  first.
+- If a simplification would change behaviour a test pins down, keep the
+  behaviour and leave a `# ponytail: <what could be simpler>` comment.
+- Tests go in `tests/<area>/`. Test names describe behaviour
+  (`test_missing_required_param_is_invalid`, not `test_case_3`).
+
+## Layout
+
+- `decikit/` is the package. Its layout, the layer map and where a new feature
+  goes: `docs/architecture/package-layout.md`. The code is the truth where they
+  differ.
+- `_engine/` imports nothing from `steps/trees|tables|scorecard`, `config/` or
+  `serving/`.
+- Packages import only downward per the layer map in `package-layout.md`;
+  `tests/test_conventions.py` enforces it.
+- `benchmarks/` holds plain scripts (`uv run python benchmarks/<name>.py`),
+  not tests. Each backs an experiment in `docs/design_decisions/experiments/`.
+
+## Contract
+
+- `docs/architecture/` plus the code describe the system (steps and IR: `steps-and-ir.md`,
+  `engine/ir.md`); `docs/design_decisions/` holds the why.
+- If the docs and the code disagree, or the intended behaviour is ambiguous, stop
+  and report. Don't guess.
+
+## Numeric and numba traps
+
+- No generated source: fused kernels are built in-process from LLVM IR, and
+  user steps use numba's disk cache with the key extended by content
+  (`fingerprint` plus `SALT`). Key compiled code by content, never by path or
+  name.
+- Serving kernels are `nogil=True`. `fastmath` is off by default.
+- Kernels use CPython-equal `round(x, n)` and `x ** n`; int64 still wraps silently. Money
+  is `Currency` / `Decimal[p, s]`: an int64 mantissa with the scale in the type, half-even
+  operators, `decikit.ops.decimal.round` for other modes. Running totals accumulate in float64.
+- Compile-time failures and steps compiled engines refuse fall back to Python per
+  step (with a warning; `FusedEngine(strict_compile=True)` raises). Runtime errors
+  always propagate.
+- Nested polymorphic pydantic fields need `SerializeAsAny`, or subclass fields
+  are silently dropped on dump.
+- Single-record calls take a dict, not keyword arguments. Cache converted params
+  bundles; conversion costs more than validation.
+- Each git worktree has its own numba cache, so the first test run in a fresh
+  worktree is slow.