Document provenance writers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PEAxNzhDCaTrntX3o1JqMV

Author: wmayner

ROADMAP.md

@@ -633,9 +633,13 @@ extending B1's bound-certificate assertions.
   is gone. Spec: `docs/superpowers/specs/2026-07-19-result-serialization-design.md`.
 - **Thread-backend progress (M13).** The thread backend discards the progress policy on entry
   (an in-code deferral note); hook the progress bar into its futures loop.
-- **Script-facing provenance writer (M14).** `provenance.save_json`/`save_npz` with git SHA,
-  parameters encoded in the filename, and no-clobber versioning — consolidating the pattern
-  that experiment scripts repeatedly re-implement.
+- **Script-facing provenance writer (M14).** *Landed 2026-07-20:*
+  `provenance.save_json`/`save_npz`/`save_dataframe` (parquet, per the DataFrame-output
+  convention) with `format_stem` filename encoding, `unique_path` no-clobber versioning, an
+  embedded `Provenance` record, and `read_metadata` to read it back; the three benchmark
+  scripts with hand-rolled copies now import the shared helpers (the cross-generation
+  harness keeps a fallback for the pre-refactor side). Spec:
+  `docs/superpowers/specs/2026-07-20-provenance-writers-design.md`.
 
 Already tracked elsewhere (verified during the triage): the Wave 7 ii-gate (M4), the
 intervention/lesion surface (N14 ← M8), the Φ-structure distance surface (N16 ← M6), the

changelog.d/provenance-writers.feature.md

@@ -0,0 +1 @@
+Added script-facing provenance writers: `pyphi.provenance.save_json`, `save_npz`, and `save_dataframe` (parquet) encode parameters in the filename, never overwrite existing files (`_v2`/`_v3` versioning), and embed a full `Provenance` record (git SHA, seed, versions) in every output; `read_metadata` reads it back from any of the three formats.

docs/howto/save-load.md

@@ -133,6 +133,44 @@ except TypeError as error:
     print(error)
 ```
 
+## Experiment provenance writers
+
+Experiment scripts need two things beyond `pyphi.save`: output files that
+never overwrite earlier runs, and a record of how each file was produced.
+The writers in `pyphi.provenance` provide both. Parameters are encoded
+into the filename, a repeated save lands in a `_v2` file instead of
+clobbering the first, and every file embeds a full provenance record —
+pyphi version, git commit, timestamp, and seed.
+
+```{code-cell} python
+from pyphi import provenance
+
+path = provenance.save_json(
+    {"phi": 0.133873},
+    out,
+    "sweep_study",
+    params={"seed": 42, "trials": 60},
+)
+path.name
+```
+
+```{code-cell} python
+provenance.save_json(
+    {"phi": 0.5}, out, "sweep_study", params={"seed": 42, "trials": 60}
+).name
+```
+
+`save_npz` does the same for arrays of raw per-trial data, and
+`save_dataframe` writes a DataFrame as parquet — the format used for
+DataFrame outputs throughout PyPhi — with the metadata embedded in the
+parquet schema. `read_metadata` recovers the provenance and parameters
+from any of the three formats:
+
+```{code-cell} python
+metadata = provenance.read_metadata(path)
+{key: metadata["provenance"][key] for key in ("seed", "pyphi_version")}
+```
+
 ## Compatibility note
 
 This serializer is a deliberate format break from the `jsonify` layer used in