graphed-histogram 0.0.1__tar.gz

graphed_histogram-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # the former core/debug/frontend/numpy/awkward siblings are now one consolidated package
+  GRAPHED: "graphed[awkward,numpy] @ git+https://github.com/graphed-org/graphed@main"
+  # exec-local stays a separate package (used by the M23 process-executor integration tests)
+  EXECLOCAL: "graphed-executors @ git+https://github.com/graphed-org/graphed-executors@main"
+
+jobs:
+  test:
+    name: test ${{ matrix.os }} py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install deps + this package
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "${{ env.GRAPHED }}" "${{ env.EXECLOCAL }}"
+          python -m pip install -e ".[dev]"
+      - uses: astral-sh/setup-uv@v5
+      - name: Lint + types (pre-commit hooks via prek)
+        run: uvx prek@0.4.5 run --all-files --show-diff-on-failure
+      - name: Pytest + coverage gate (>=90%)
+        run: pytest tests/frozen --cov=graphed_histogram --cov-branch --cov-report=term-missing
+
+  # Free-threaded / bleeding-edge Pythons (plan A.5): genuinely exercises concurrency under no-GIL.
+  # Experimental + non-blocking (awkward wheels may lag on 3.14 / 3.14t).
+  test-experimental:
+    name: test (experimental) py${{ matrix.python }}
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.14t"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "${{ env.GRAPHED }}" "${{ env.EXECLOCAL }}"
+          python -m pip install -e ".[dev]"
+          pytest tests/frozen
+
+  docs:
+    name: docs (sphinx -W)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          # runtime deps include the consolidated graphed package (git, not on PyPI)
+          python -m pip install "${{ env.GRAPHED }}"
+          python -m pip install -e ".[docs]"
+          sphinx-build -W -b html docs docs/_build/html

graphed_histogram-0.0.1/.github/workflows/wheels.yml

@@ -0,0 +1,35 @@
+name: wheels
+
+# Build-only release artifacts (plan A.5 / M0): a pure-Python wheel + sdist, validated with
+# `twine check` and uploaded as a CI artifact. There is intentionally NO publish step — nothing
+# is uploaded to PyPI from CI.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: sdist + wheel (pure Python)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+      - name: Validate metadata
+        run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

graphed_histogram-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+dist/
+build/
+_build/
+docs/generated/
+.DS_Store

graphed_histogram-0.0.1/.graphed/M23/attempts.md

@@ -0,0 +1,62 @@
+# M23 attempts — graphed-histogram (deferred histogram filling; P0.1)
+
+## Iteration 0 — M0 spine + TEST_AUTHORING/TEST_SANITY/IMPLEMENTING — 2026-06-10 (freeze-M23-0)
+
+- Repo created per the lazy-repo recipe (spine adapted from graphed-checkpoint: CI matrix,
+  tooling, Sphinx + improvements.rst, CONTRIBUTING, distilled CLAUDE.md).
+- frozen suite tests/frozen/m23 (14 tests); NON-VACUOUS (10/10 initial tests fail on the missing
+  package; 4 coverage tests added pre-freeze, recorded).
+- Design (user-confirmed plan): fills are External nodes recorded via graphed M23's
+  record_external(descriptor=, form=) — backends know nothing about histograms; identity =
+  SHA-256 of the canonical versioned axes/storage spec (declarative JSON; growth axes rejected
+  as Phase 2); evaluators resolve through evaluate_ir(externals=); compute() = partition-wise
+  fill through the compiled IR over the PartitionedSource protocol (whole-dataset loader never
+  invoked, counter-witnessed) + native `+` tree-combine; in-memory sources via materialize;
+  plan() exports the R15.4 task graph (ProcessExecutor pin). dask-histogram-parity surface:
+  boost.Histogram / factory / histogram / histogram2d / histogramdd.
+- gates: frozen 14/14 PASS · coverage 95.07% (>=90, branch) · ruff+format clean · mypy --strict
+  clean · sphinx -W clean · IR byte-determinism pinned in-suite.
+
+## Iteration 1 — the hist.graphed integration surface — 2026-06-10
+
+- `_wrap_result` hook: compute() converts to the subclass's `_in_memory_type` when declared
+  (the hist.dask convention) — `hist.graphed.Hist.compute()` returns a real `hist.Hist`.
+- Axis identity metadata: boost axes carry user attributes (hist's name/label) in `__dict__`,
+  not in a `metadata=` kwarg — the canonical spec now captures/restores `__dict__` entries, so
+  names and labels survive record -> compute -> wrap. Spec encode/rebuild remains a fixed point
+  (pinned).
+
+## Iteration 2 — USER-DIRECTED: no compute() helper (graphed idiom) — 2026-06-11 (freeze-M23-1)
+
+- USER: "graphed has its own [idioms] ... we have materialize and the executors for that.
+  Remove compute() from graphed-histogram."
+- Histogram.compute() and the _wrap_result/_in_memory_type machinery are REMOVED. Evaluation is
+  graphed's: plan() (R15.4) + any R7 executor's run(plan).value IS the aggregated histogram;
+  the reference session.materialize(fill_node) evaluates one fill eagerly (multi-fill in-memory:
+  zero_of + add_histograms over per-fill materializes — pinned).
+- frozen m23 respun under this authorization (executor/materialize idiom; same pins otherwise);
+  freeze tag bumped freeze-M23-0 -> freeze-M23-1.
+- gates: 14/14 · coverage 94.85% · ruff/mypy/sphinx clean.
+
+## Iteration 3 — USER-DIRECTED process-boundary witnesses (freeze-M23-2) — 2026-06-11
+
+- USER: weighted fills are HEP's most common case; behavior loss plagued dask-awkward — control
+  both early. New frozen file test_process_executor_witnesses.py (+behavior_toy.py, an
+  importable toy behavior): a Weight-storage weighted fill through the SPAWNED process pool ==
+  sequential EXACTLY (values AND variances) == eager; a ragged awkward fill through the pool ==
+  its eager twin; a behavior-carrying session under the DEFAULT plan() FAILS LOUDLY in workers
+  (bare backend — behaviors are never silently dropped; pinned); and the supported path:
+  plan(backend="module:attr") — workers IMPORT the factory, no behavior dict is ever pickled —
+  reproduces the sequential result bit for bit.
+- Implementation: _resolve_backend (str refs resolved IN the worker); plan(backend=) accepts
+  factory/class OR "module:attr". Sanity: 3/4 witnesses passed pre-implementation (they pin
+  already-true behavior, including the loud failure); the import-ref test failed on the missing
+  feature. CI + dev deps gain graphed-awkward so the ragged/behavior witnesses run in CI.
+- gates: frozen 18/18 · coverage >=90 · ruff/mypy/sphinx clean.
+
+## Iteration 4 — plan(partitions=) (ADL P2 entry-target seam) — 2026-06-11
+
+- Additive: plan() accepts explicit partitions (a caller-shaped partitioning — absolute
+  entry-count chunks for the benchmark sweep) instead of the source's steps_per_file split.
+  Frozen test added (explicit eager partitions tile the dataset; counts bit-for-bit; the
+  whole-dataset loader still never runs). 19/19 green.

graphed_histogram-0.0.1/.graphed/M29/attempts.md

@@ -0,0 +1,46 @@
+# M29 attempts — graphed-histogram (multiple multiplicative weights)
+
+## Iteration 0 — 2026-06-12 (freeze-M29-0)
+
+- The M27 replay contract (preserve eval_histogram n_weights) had no producer. Now fill()
+  accepts weight= as a SEQUENCE of graphed Arrays: each factor is a real graph input; params
+  gain n_weights ONLY when >1 (single-weight node identity byte-for-byte unchanged — pinned);
+  FillEvaluator gains n_weights (default 1: old pickles/evaluators valid) and multiplies the
+  factors elementwise before filling — the package's OWN plan()/executor path agrees with the
+  preserve replay by sharing the evaluator.
+- frozen m29 (5): two-weight materialize == eager (values AND variances, Weight storage);
+  the plan()/SequentialRunner path (per-partition fills: deterministic byte-identical across
+  runs, allclose(rtol=1e-12) vs single-pass eager — float summation ORDER differs across
+  partitions, an honest pin); three weights + the params contract (n_weights=3, 4 graph
+  inputs); single-weight unchanged (no n_weights param); jagged weight factors flatten
+  consistently. Non-vacuous: weight=[w1,w2] crashed recording pre-impl.
+- Gates: 24 passed · coverage 95.71% · ruff/format/mypy/sphinx clean. Cross-repo: preserve
+  frozen m30 pins the bundle replay; the full 11-repo + 3-fork sweep ran green pre-commit.
+
+## Iteration 1 — 2026-06-12
+
+- CI exposed a test-dependency gap invisible to the local cross-repo sweep: the frozen m29
+  plan-path test builds its partitioned source with ak.to_parquet -> pyarrow, present locally
+  but not in this repo's CI install. pyarrow added to the dev extra (the frozen test is
+  untouched). Lesson: a green local sweep validates code, not CI environments — new frozen
+  tests must declare their dependencies in the repo they land in.
+
+## Iteration 2 — 2026-06-12 (freeze-M29-1)
+
+- CI round 2: ak.to_parquet routes through pyarrow's PANDAS SHIM -> ModuleNotFoundError in CI
+  (pandas exists locally only; this ecosystem is deliberately pandas-free). FREEZE AMENDMENT
+  (sanctioned, dispute-correction path): the plan-path test's fixture now writes parquet via
+  pure pyarrow (pq.write_table) — the assertions are byte-identical, only the fixture I/O
+  changed. Re-frozen as freeze-M29-1.
+- Iteration 1's pyarrow dev-dep edit ALSO shipped invalid TOML (a regex grabbed the wrong
+  bracket; the tomllib check ran but its failure was swallowed by statement chaining). Both
+  failure modes are now ENCODED in graphed-orchestrator's new pre-commit gate
+  (python -m graphed_orchestrator.precommit, commit 4f0abf5), which gated THIS commit:
+  toml-valid ok, integrity-scan REFREEZE:tests/frozen/m29/... (loud, sanctioned), full suite ok.
+
+## Iteration 3 — 2026-06-12
+
+- CI round 3: the pandas dependency is in awkward ITSELF (arrow form derivation calls
+  pyarrow's to_pandas_dtype on every from_parquet schema read) — the fixture's write side was
+  never the whole story. graphed-awkward's dev extra carries pyarrow+pandas for exactly this
+  reason (the established precedent); this repo's dev extra now matches. No test changes.

graphed_histogram-0.0.1/.graphed/state.json

@@ -0,0 +1,76 @@
+{
+  "current": "M23",
+  "milestones": {
+    "M23": {
+      "dispute_count": 0,
+      "escalated": false,
+      "freeze_tag": "freeze-M23-2",
+      "gates": {
+        "benchmark": null,
+        "coverage": true,
+        "determinism": true,
+        "frozen_tests": true,
+        "integrity_scan": true,
+        "lint": true,
+        "types": true
+      },
+      "incident": null,
+      "l0_count": 0,
+      "metrics_history": [
+        {
+          "benchmark_ok": null,
+          "coverage_ok": true,
+          "determinism_ok": true,
+          "diff_lines": 0,
+          "fail_set_hash": "e3b0c44298fc1c14",
+          "integrity_ok": true,
+          "iteration_index": 0,
+          "lint_ok": true,
+          "pass_count": 18,
+          "tokens_spent": 0,
+          "tree_hash": "local",
+          "types_ok": true,
+          "wall_clock_s": 0.0
+        }
+      ],
+      "phase": "DONE",
+      "reject_count": 0
+    },
+    "M29": {
+      "dispute_count": 0,
+      "escalated": false,
+      "freeze_tag": "freeze-M29-0",
+      "gates": {
+        "benchmark": null,
+        "coverage": true,
+        "determinism": true,
+        "frozen_tests": true,
+        "integrity_scan": true,
+        "lint": true,
+        "types": true
+      },
+      "incident": null,
+      "l0_count": 0,
+      "metrics_history": [
+        {
+          "benchmark_ok": null,
+          "coverage_ok": true,
+          "determinism_ok": true,
+          "diff_lines": 0,
+          "fail_set_hash": "e3b0c44298fc1c14",
+          "integrity_ok": true,
+          "iteration_index": 0,
+          "lint_ok": true,
+          "pass_count": 24,
+          "tokens_spent": 0,
+          "tree_hash": "local",
+          "types_ok": true,
+          "wall_clock_s": 0.0
+        }
+      ],
+      "phase": "DONE",
+      "reject_count": 0
+    }
+  },
+  "updated_at": "2026-06-12T19:48:11Z"
+}

graphed_histogram-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+# Lint + type-check hooks, run by prek (https://github.com/j178/prek).
+#
+# These commands live here ONCE and are consumed by every gate: CI (`uvx prek run
+# --all-files`), the graphed-orchestrator pre-commit gate, and a developer's local
+# `prek install`. No more hand-rolled `ruff`/`mypy` shell chains duplicated per workflow.
+#
+# ruff and mypy are `system` hooks on purpose: they use the versions already installed in
+# the project's env (the `dev` extra, intentionally unpinned), so there is a single source
+# of truth for tool versions rather than a second set pinned here that could drift.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: ruff check --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: ruff format
+        entry: ruff format --check --force-exclude
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: mypy
+        name: mypy (strict)
+        entry: mypy
+        language: system
+        pass_filenames: false
+        always_run: true

graphed_histogram-0.0.1/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md — graphed-histogram
+
+Defers to the root **`graphed-project/CLAUDE.md`**; the **project plan
+(`graphed-project-plan-gated.md`) always wins.** This file distills milestone **M23**
+(P0.1 of the ADL-benchmarks port, user-confirmed 2026-06-10).
+
+## What this repo is
+
+**Deferred boost-histogram/hist filling on graphed task graphs** — the `dask-histogram`
+analogue. A `.fill(...)` RECORDS instead of executing: each fill is an **External node** in the
+graphed IR (the M3 correctionlib/ONNX family), carrying a `PayloadDescriptor` whose
+`content_hash` is the SHA-256 of the **canonical axes/storage spec** (declarative params — never
+cloudpickle; UHI in, UHI out, invent no formats). Backends know NOTHING about histograms: fills
+record through `record_external(descriptor=, form=)` (graphed M23) and evaluate through
+`evaluate_ir`'s `externals=` registry.
+
+Aggregation rides the M7/M8 seam with graphed's OWN evaluation idiom (no `compute()` helper —
+user-directed, 2026-06-11): `plan()` builds the `Plan(process=fill-partition-through-the-
+compiled-IR, combine=histogram add, empty=zero-hist)`; an R7 executor's `run(plan).value` IS the
+aggregated histogram; the reference `session.materialize(fill_node)` evaluates a fill eagerly.
+Sources implementing `graphed.write.PartitionedSource` are filled partition by partition (their
+whole-dataset loader is NEVER invoked); Int64 counts are exact under any combine tree, float
+storages are deterministic per fixed-tree executor configuration.
+
+## Surface (dask-histogram parity)
+
+- `graphed_histogram.boost.Histogram` — deferred `boost_histogram.Histogram`: `.fill()` records
+  and returns self (multiple fills accumulate); `.plan()` exports the task graph.
+- `factory(*arrays, histref=, weight=, sample=)`.
+- numpy-like `histogram` / `histogram2d` / `histogramdd`.
+- All standard boost storages (combine is native `+`); axes Regular/Variable/Integer/
+  IntCategory/StrCategory/Boolean. **Phase 2 (do NOT build):** growth axes, dask-style
+  persist/delayed beyond Plan export.
+
+## Hard rules
+
+Frozen tests under `tests/frozen/m23/` — never weakened. One source family per histogram
+(PartitionedSource or in-memory; mixtures rejected). Ragged fill values flatten at fill time.
+The canonical spec encoding is VERSIONED and byte-stable (the content hash is identity).
+
+Gates: ruff + ruff format · mypy --strict · pytest (>=90% branch coverage) · sphinx -W.
+Status: see `.graphed/state.json`.

graphed_histogram-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to graphed-histogram
+
+Part of the `graphed` project, governed by the gated three-role pipeline. The root
+[`graphed-project/CLAUDE.md`](https://github.com/graphed-org/graphed-project-mvp) and the project plan
+are authoritative; the plan always wins.
+
+## Guardrails (M8)
+
+- **Local filesystem store only** (no distributed store in MVP); **single machine**.
+- M8 is checkpoint/resume — analysis **preservation** is M9, not here.
+- The canonical durable form is the **serializable IR** (`graphed_core.DurablePlan`), never
+  cloudpickle except for genuinely opaque callables (flagged `opaque=True`).
+- Resume must be correct under interruption: **no double-count, no lost partition**; a resumed run
+  matches an uninterrupted one bit-for-bit. `task_id` must stay content-addressed (cache-poisoning-safe).
+
+## Integrity rules — NON-NEGOTIABLE (plan A.7 / B.6)
+
+Never edit/skip/weaken `tests/frozen/**`; never lower a threshold or relax CI; never stub the thing
+under test. Dispute a frozen test via `.graphed/<Mx>/disputes/<test_id>.md`.
+
+## Local gates
+
+```bash
+pip install "graphed[awkward,numpy] @ git+https://github.com/graphed-org/graphed@main"   # needs Rust
+pip install "graphed-executors @ git+https://github.com/graphed-org/graphed-executors@main"
+pip install -e ".[dev,docs]"
+ruff check . && ruff format --check . && mypy
+pytest tests/frozen --cov=graphed_histogram --cov-branch
+sphinx-build -W -b html docs docs/_build/html
+```

graphed_histogram-0.0.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: graphed-histogram
+Version: 0.0.1
+Summary: Deferred boost-histogram/hist filling on graphed task graphs (the dask-histogram analogue)
+Project-URL: Homepage, https://github.com/graphed-org/graphed-histogram
+Author: graphed-org
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: boost-histogram>=1.4
+Requires-Dist: graphed
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: awkward>=2.6; extra == 'dev'
+Requires-Dist: graphed-executors; extra == 'dev'
+Requires-Dist: graphed[awkward,numpy]; extra == 'dev'
+Requires-Dist: hist>=2.7; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pyarrow; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# graphed-histogram
+
+Deferred [boost-histogram](https://github.com/scikit-hep/boost-histogram) /
+[hist](https://github.com/scikit-hep/hist) filling on [graphed](https://github.com/graphed-org)
+task graphs — the [dask-histogram](https://github.com/dask-contrib/dask-histogram) analogue, built
+on graphed's own evaluation idiom (milestone **M23**; P0.1 of the ADL-benchmarks port).
+
+A `.fill(...)` **records** instead of executing. Each fill becomes an **External node** in the
+graphed IR (the same M3 family as correctionlib and ONNX nodes): a call into foreign machinery,
+carried in the IR with reproducibility metadata, evaluated later by a registered evaluator.
+Backends know nothing about histograms — fills record through the frontend's
+`record_external(descriptor=, form=)` seam and resolve through `evaluate_ir`'s `externals=`
+registry.
+
+## The deferred histogram in one example
+
+```python
+import boost_histogram as bh
+import graphed_histogram as gh
+from graphed_core.execution import SequentialRunner
+
+h = gh.boost.Histogram(bh.axis.Regular(20, 0.0, 10.0), storage=bh.storage.Int64())
+h.fill(x)                 # x is a graphed Array: RECORDS a fill node, returns h
+h.fill(x * 0.5 + 1.0)     # fills accumulate — more nodes, same histogram
+
+plan   = h.plan(steps_per_file=4)            # the deferred task graph
+result = SequentialRunner().run(plan).value  # a CONCRETE boost histogram
+# any R7 executor accepts the same plan:
+#   ProcessExecutor(max_workers=4, persistent=True).run(plan).value
+```
+
+The eager boost API stays available on `h` (axes, storage, views of the empty state); what
+changes is that filling stages graph nodes and evaluation belongs to executors.
+
+## Why it is built this way
+
+- **Fills are External nodes.** The package supplies a `PayloadDescriptor`
+  (`kind="histogram"`, `content_hash=sha256(spec)`, `io_schema="uhi"`) and an opaque histogram
+  form; the backend is never consulted. Nothing in graphed-core, graphed, or any backend mentions
+  histograms.
+- **The canonical spec is the identity.** A histogram's identity is the SHA-256 of its
+  **canonical, versioned axes/storage spec** — key-sorted JSON covering every supported axis and
+  storage (declarative params, never cloudpickle; UHI in, UHI out, no invented formats). Identical
+  fills intern to one graph node; the spec string is the fill's preservation payload; a plan
+  re-run on another machine resolves its evaluator by the same hash. `spec_of(h)` reads it;
+  `zero_of(spec)` rebuilds the empty histogram anywhere.
+- **Aggregation is plans and executors, not `compute()`.** There is deliberately no `compute()`
+  method — evaluation is graphed's machinery. `h.plan(...)` builds a
+  `Plan(process=fill-partition-through-the-compiled-IR, combine=native +, empty=zero)`, and any R7
+  executor's `run(plan).value` **is** the aggregated histogram. Histograms form a monoid under
+  native `+` for every standard storage, so the executor's fixed combine tree applies unchanged:
+  Int64 counts are exact under any tree, float storages are deterministic per fixed-tree executor
+  configuration. The reference path for in-memory sources is `session.materialize(fill_node)`.
+
+## Public surface
+
+| | |
+|---|---|
+| `graphed_histogram.boost.Histogram` | deferred `boost_histogram.Histogram`; `.fill()` records and returns self (fills accumulate), `.plan()` exports the task graph |
+| `factory(*arrays, histref=, weight=, sample=)` | a deferred histogram from a reference histogram's axes/storage plus one staged fill (the dask-histogram `factory` shape) |
+| `histogram` / `histogram2d` / `histogramdd` | numpy-like deferred entry points (explicit bins + range) |
+| `plan(histograms, ...)` | one plan aggregating **several** deferred histograms that share a source in a **single pass** (the `compute(dict_of_hists)` analogue) |
+| `spec_of` / `zero_of` / `content_hash` | the canonical-spec helpers |
+| `evaluators(*histograms)` | merged content-hash -> evaluator registry for `evaluate_ir(externals=...)` |
+| `add_histograms` | native-`+` combine helper for multi-fill sums |
+
+All standard boost storages (combine is native `+`); axes
+Regular/Variable/Integer/IntCategory/StrCategory/Boolean. Sources implementing
+`graphed.write.PartitionedSource` are filled partition by partition — their whole-dataset loader is
+never invoked. One source family per histogram (PartitionedSource or in-memory; mixtures rejected).
+Ragged fill values flatten completely at fill time.
+
+### Multiplicative weights (M29)
+
+HEP event weights arrive as several factors (generator weight x pileup x trigger SFs ...).
+`fill(weight=...)` accepts `weight=` as a **sequence** of graphed Arrays, a first-class fill
+signature: each weight is recorded as a real graph input and evaluation multiplies them
+elementwise into the single fill weight.
+
+```python
+h.fill(g.pt, weight=[g.genweight, g.pileup_sf, g.trigger_sf])
+```
+
+A single weight records exactly as before — no `n_weights` param — so pre-M29 node identities,
+specs, and preservation bundles are untouched.
+
+### One pass over several histograms
+
+`plan(histograms, ...)` compiles all the fills of several histograms into **one** multi-output IR,
+so a sub-graph feeding multiple histograms (e.g. a trijet selection feeding both a pT and a b-tag
+histogram) is read and evaluated **once** — not once per histogram. `run(plan).value` is the
+matching `{label: histogram}` mapping (string keys for a `Mapping`, `"0"`, `"1"`, ... for a plain
+sequence). Column projection covers the union of all the histograms' fills.
+
+### Worker backends
+
+`plan(backend=...)` accepts a zero-arg factory/class or an importable `"module:attr"` string
+resolved **in the worker** — the required form for behavior-carrying backends, because behavior
+dicts contain lambdas and do not pickle. A worker built without required behaviors fails loudly; it
+never silently fills the wrong thing.
+
+## The hist integration
+
+`hist.graphed` (in the `hist` fork) supplies `Hist`/`NamedHist` as thin MRO sandwiches over this
+package's `Histogram`: the familiar QuickConstruct
+(`Hist.new.Reg(100, 0, 200, name="met").Double()`) and named-axis fills record deferred; executor
+results wrap back into in-memory `hist.Hist` objects with names and labels intact (they ride the
+canonical spec). The eight ADL benchmark queries run on exactly this surface.
+
+## Phase 2 (deliberately not built)
+
+Growth axes (combining grown category axes across partitions needs a category-union merge,
+rejected at spec time for now); dask-style collection protocols (`persist`, `to_delayed`) — the
+durable artifact is the compiled IR / `Plan`; behavior-reference forwarding by default.
+
+## Status and gates
+
+Frozen tests under `tests/frozen/m23/` and `tests/frozen/m29/` — never weakened. Gates: ruff +
+ruff format · `mypy --strict` · pytest (>= 90% branch coverage) · `sphinx -W`. See `CLAUDE.md`
+for the milestone digest, `docs/design.rst` for the engineering walkthrough, and
+`.graphed/state.json` for current status.