docs: reflect PR #137 — result digest as a row multiset, tallyman_read_csv

Rewrite the Result digest concept: it is now snapshot_file_digest (SHA-256
of the baked snapshot parquet, ordered by original_row_order) — a row
multiset, recorded for worthy entries only; cheap entries record none.
Replaces the per-row repr()+sha256 description.

Index the three docs PR #137 added: the canonical-ordering ADR (under
ADRs) and the two digest-investigation findings (datafusion scan order,
result_digest vs xorq staleness). Note tallyman_read_csv as the fourth
in-code data-sourcing helper in the MCP authoring section.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: paddymul

docs/architecture.md

@@ -211,11 +211,17 @@ unique by construction, Buckaroo sessions are keyed globally by content hash,
 not per project. The source-identity mode (`off` / `cas` / `salt`, default
 `cas`) is decided in [adr-source-identity-content-hash.md](../plans/adr-source-identity-content-hash.md).
 
-**Result digest.** A second identity axis. The content hash keys the expression
-graph; the `result_digest` (a content hash of the executed rows, in order) keys
-the executed bytes. A mismatch during a cache self-heal points at execution
-nondeterminism (sampling, `now()`, unordered limits, impure UDFs) rather than a
-structural change.
+**Result digest.** A second identity axis, recorded for *worthy* (snapshot-baking)
+entries only. The content hash keys the expression graph; the `result_digest`
+keys the executed *bytes* as a row **multiset**, not a sequence. It is the
+SHA-256 of the entry's baked snapshot parquet (`snapshot_file_digest`), which the
+bake writes after sorting on a synthetic `original_row_order` and pinning the
+parquet write settings, so the bytes are reproducible run-to-run and the file
+hash is order-insensitive. Cheap, row-preserving entries record no digest — they
+have no snapshot to hash and recompute live. A mismatch when an evicted snapshot
+self-heals points at execution nondeterminism (sampling, `now()`, an impure UDF,
+source drift), not the unordered-scan row reshuffling the canonical ordering now
+absorbs. Design: [adr-result-digest-canonical-ordering.md](../plans/adr-result-digest-canonical-ordering.md).
 
 **Alias and V_n versions.** An alias is a named, mutable pointer (for example
 `sales`) to the latest content hash of a logical entry. Each alias carries an
@@ -385,6 +391,11 @@ when in doubt, the code wins.
   a *proposed* cost-vs-size cache rubric. **Partially stale / not adopted:** the
   structural `cache_worthy` admission test it proposes to remove is still the
   live gatekeeper, and `ensure_result` it names was removed (#73).
+- [adr-result-digest-canonical-ordering.md](../plans/adr-result-digest-canonical-ordering.md)
+  — `result_digest` as a row multiset via a canonically-ordered snapshot hash,
+  replacing the per-row Python digest (#137). **Current** (implemented: the
+  digest is now `snapshot_file_digest`, and `tallyman_read_csv` injects
+  `original_row_order`).
 
 ### Plans (`plans/`)
 
@@ -412,6 +423,14 @@ when in doubt, the code wins.
 
 ### Research notes / experiment logs (`plans/`, `demo/`) — point-in-time records
 
+The digest investigation behind #137 (current):
+[datafusion-scan-order-findings.md](../plans/datafusion-scan-order-findings.md)
+— why a parallel datafusion scan emits rows in a different order each run, and
+the polars-ingest decision — and
+[result-digest-vs-xorq-staleness.md](../plans/result-digest-vs-xorq-staleness.md)
+— why `result_digest` can't reuse xorq's content-aware cache staleness.
+
+Older, historical:
 [eda-prompt-research.md](../plans/eda-prompt-research.md),
 [eda-codegen-run1.md](../plans/eda-codegen-run1.md),
 [haiku-codegen-findings.md](../plans/haiku-codegen-findings.md),

docs/mcp-server.md

@@ -143,6 +143,13 @@ The compile-and-persist family. The `code` argument is a self-contained Python
 script that binds a top-level `expr` to a xorq/ibis expression;
 `catalog_run`'s docstring is the canonical cookbook for writing it (namespaces,
 the datafusion-only backend, data sourcing, and the `xorq.ml` MODELING section).
+Data sourcing inside `code` uses four helpers from `tallyman_xorq.io`:
+`tracked_expr_from_alias` (a catalog entry, recorded as a lineage parent),
+`pinned_expr_from_alias` (a catalog entry by alias or hash, no following),
+`read_project_file` (a raw parquet under `data/`), and `tallyman_read_csv` (CSV
+ingest — injects an `original_row_order` column so the baked snapshot is
+byte-stable across builds; use it for all CSV reads instead of
+`xo.deferred_read_csv`, #137).
 
 ### `catalog_run(code, prompt="") -> dict`
 Execute an expression and persist it as an **unnamed (scratch)** entry. Claude's