docs: post-merge corrections on PR #452 + #453 architecture docs

Two follow-up doc fixes after PR #452 and #453 merged. Reviewers
flagged real bugs the doc-only PRs landed with; these corrections
bring main in line with the post-review state.

== CLUSTER_ASYMMETRY.md ==

Drop the vort/vart adaptive-radix-trie citation; cite shipped
NiblePath + Lance versions() instead. A workspace scan across all
Cargo.toml files confirms vart is NOT a dependency in this
repository; le-domino's own seam-map documents it as 'doc-prose
only'. Citing a non-existent crate in a public architecture doc
misleads adopters into looking for a crate that they cannot find.

The role the bullet described (HHTL-prefix dedup) is actually:

- lance-graph-contract::hhtl::NiblePath (shipped) for the identity
  primitive (16-fan-out nibble path packed into a u64)
- Lance versions() (shipped) for the time-axis (cross-session index
  of which identity positions changed when)

Adopters can derive an adaptive radix-trie index over NiblePath
addresses themselves; that data structure is consumer code, not a
lance-graph dep. The corrected bullet cites the two shipped surfaces
and flags the radix-shaped consumer pattern as proposed.

== APPEND_ONLY_RAFT_DOVETAIL.md ==

Apply the same critique class codex raised on PR #453's companion doc:

- Scope caveat: peer-Raft + Lance-local is an EXTERNAL architecture
  pattern (bardioc B1 substrate-b), NOT a built-in lance-graph
  feature. Adopters provide the Raft layer themselves (openraft /
  surreal-cluster / external TiKV). Lance-graph contributes the
  storage-append/consensus-append dovetail property that MAKES the
  pattern cheap; not the pattern itself. Added a scope banner
  immediately after the TL;DR.
- Compaction honesty: Lance has compaction TOO via
  DatasetOptimizer.compact_files for fragment layout. The doc
  previously said 'Lance has no compaction' which is wrong for
  append-heavy deployments. Rewrote section 1 to distinguish LSM
  tombstone-reclaim+run-merge compaction from Lance file-layout
  compaction. Both exist; only LSM coordinates with replication.
- Consensus-tax-lands-once section also updated to acknowledge that
  Lance file compaction runs INDEPENDENTLY of consensus (the storage
  commit tax and the consensus tax are the same write; the LAYOUT
  OPTIMIZATION cycle is a separate concern that does not couple).

Both files were merged earlier (PR #452, #453); these corrections
land in main as a follow-up so adopters reading the docs today see
the honest scope + correct citations. No code changes; doc-only.

Author: AdaWorldAPI

docs/APPEND_ONLY_RAFT_DOVETAIL.md

@@ -12,6 +12,24 @@ or any other model where storage mutates state in place.
 This doc names the property explicitly + lists the operational
 consequences so adopters can choose the right deployment shape.
 
+> ### Scope: external architecture pattern, not a built-in lance-graph feature
+>
+> Post-merge correction (paralleling peer review on the companion doc
+> PR #453): the deployment shape described below ("peer-Raft +
+> Lance-local-per-node") is an EXTERNAL ARCHITECTURE PATTERN adopters
+> can build on top of lance-graph, NOT a built-in lance-graph
+> capability. Lance-graph provides the append-only columnar storage +
+> the DataFusion query path + the encoding crates; the Raft layer +
+> the substrate binary + the consensus-replication path are
+> downstream consumer code (e.g. `openraft` or `surreal-cluster`).
+> Adopters who only consume lance-graph's columnar + DataFusion path
+> should NOT assume their data is automatically replicated.
+>
+> The doc documents WHY this pattern works well WHEN built on
+> lance-graph — the storage-append/consensus-append dovetail property
+> — not a feature lance-graph itself ships.
+
+
 ## The two write shapes that have to align
 
 A distributed Lance deployment has two write paths:
@@ -35,15 +53,16 @@ Compare this with the conventional alternatives:
 |---|---|---|
 | **LSM-tree (Cassandra)** | Paxos-light / gossip | Storage AND consensus both have their own append-then-mutate cycles. Compaction in storage interacts with hinted handoff in consensus. Coordination headaches. |
 | **B-tree (PostgreSQL)** | 2PC (citus-like) | Storage in-place updates fight with 2PC's append-log. Vacuum interacts with commit-log replay. More headaches. |
-| **Append-only Lance** | Append-only Raft | One write shape. Storage commit = consensus log entry. No interaction problems. |
+| **Append-only Lance** | Append-only Raft | One write shape. Storage commit = consensus log entry. No interaction problems. (Lance does have its own file-layout compaction via `DatasetOptimizer.compact_files`, but it runs INDEPENDENTLY of consensus — see Operational consequence #1.) |
 
 ## Operational consequences
 
-### 1. No compaction storms
+### 1. Compaction is qualitatively different, not absent
 
-Cassandra clusters periodically run compaction (rewrite SSTables to
-reclaim space + maintain read performance). Each node compacts on
-its own schedule. During compaction:
+Cassandra clusters periodically run LSM compaction (rewrite SSTables
+to reclaim tombstones + merge sorted runs to maintain read
+performance). Each node compacts on its own schedule. During
+compaction:
 
 - The compacting node's CPU spikes
 - Its disk write bandwidth spikes
@@ -56,15 +75,31 @@ The cluster operator's job is partly to schedule compactions across
 nodes so that not too many compact simultaneously. This is a
 significant operational burden.
 
-Lance has no compaction. The version log IS the truth; old fragments
-can be reclaimed by version-based GC (a much simpler operation than
-SSTable compaction) but the GC is local-only, doesn't interact with
-replication, and doesn't reorder anything.
+Lance has compaction TOO, but of a qualitatively different shape:
+`DatasetOptimizer.compact_files` merges small fragments into larger
+ones to optimize query layout (many small appends produce many small
+fragments which slow scans). It is NOT a tombstone-reclaim cycle —
+Lance is append-only at the version level, so there are no tombstones
+to reclaim in the LSM sense. File compaction takes existing
+append-only fragments and produces new append-only fragments at a
+better layout.
+
+Operationally:
+
+- Compaction runs INDEPENDENTLY of consensus replication — file
+  compaction does not block writes, does not affect Raft log shipping,
+  does not coordinate across nodes
+- Per-node compaction is local-only; each node compacts its own
+  Lance dataset on its own schedule without affecting peers
+- The failure modes are smaller (a partial compaction is recoverable;
+  no in-flight tombstones to lose; correctness is unaffected)
 
 A peer-Raft + Lance deployment therefore has uniform per-node
-behavior. Each node is doing the same work at the same time, with
-the same shape. The operations runbook is simpler because the
-failure modes are simpler.
+behavior under both consensus and compaction. Operators still plan
+for file compaction (it consumes CPU + IO when it runs), but the
+cluster-wide coordination burden is significantly lower than
+Cassandra's LSM compaction scheduling. (Per post-merge correction
+on PR #452.)
 
 ### 2. Anti-entropy is a hash compare, not a Merkle-tree walk
 
@@ -109,19 +144,25 @@ footprint depends on which columns mutated, whether the row was new
 or updated, whether the column had a previous value. Cross-DC
 replication budget is harder to plan.
 
-### 5. The consensus tax lands once, not twice
-
-This is the unifying point: with non-append-only storage, an
-application that wants linearizable writes pays the consensus tax
-TWICE. Once for the consensus protocol shipping operations to
-replicas. Once for the storage layer doing per-node compaction +
-mutation bookkeeping. The two taxes interact (a compaction storm
-delays consensus catch-up; a Raft snapshot has to materialize the
-LSM-tree state).
-
-With Lance + Raft, the consensus tax and the storage tax are the
-SAME tax. The append IS both the consensus log entry and the storage
-commit. You pay it once.
+### 5. The consensus tax and the storage-COMMIT tax are the same tax
+
+This is the unifying point: with LSM-tree storage, an application
+that wants linearizable writes pays the consensus tax TWICE. Once
+for the consensus protocol shipping operations to replicas. Once for
+the storage layer doing per-node tombstone-reclaim + run-merge
+compaction. The two taxes interact (a compaction storm delays
+consensus catch-up; a Raft snapshot has to materialize the LSM-tree
+state).
+
+With Lance + Raft, the consensus tax and the storage-COMMIT tax are
+the SAME tax — the append IS both the consensus log entry and the
+storage commit; you pay it once. Lance does have its own file-
+compaction cycle (`DatasetOptimizer.compact_files`), but it runs
+INDEPENDENTLY of consensus — file compaction takes existing
+append-only fragments and rewrites them into bigger append-only
+fragments without tombstones to reclaim and without coordinating
+with replication. So the LAYOUT-OPTIMIZATION cycle exists but does
+not interact with the consensus tax.
 
 ## What this implies for deployment shape
 

docs/CLUSTER_ASYMMETRY.md

@@ -95,12 +95,21 @@ by 1-3 orders of magnitude vs LSM-tree wide-column representations:
   reduces ANN scan space by ~16× under empirical intra-family
   locality (98.6% per the `lance-graph` PR #444 probe).
 
-- **vort/vart adaptive radix trie**: structural deduplication of
-  shared HHTL prefixes. The heel + hip nibbles common across many
-  entities are stored ONCE per path segment, not N times. Adaptive
-  Radix Tree shape: O(k) lookup, prefix-sharing storage. The same
-  structure also serves as the time-axis index over Lance
-  `versions()` for cold-path queries.
+- **`lance-graph-contract::hhtl::NiblePath` (shipped) + Lance
+  `versions()` (shipped)**: HHTL identity is a 16ⁿ nibble path packed
+  into a `u64` (`FAN_OUT = 16`, `MAX_DEPTH = 16`). Adopters who want
+  to dedupe shared HHTL prefixes in memory typically derive an
+  adaptive radix-trie index over `NiblePath` addresses — heel + hip
+  nibbles common across many entities can be stored once per path
+  segment via consumer-side structures (O(k) lookup, prefix-sharing).
+  **The dedup-by-prefix data structure itself is consumer code, not
+  a built-in lance-graph crate.** Lance's own `versions()` log is the
+  time-axis (cross-session index of which identity positions changed
+  when). An earlier version of this doc cited `vort/vart` as if it
+  were a shipped crate; corrected per peer review — the radix-shaped
+  trie at the cognitive layer is a proposed pattern (no shipped crate
+  name) and the identity primitive + the time-axis are the two
+  shipped surfaces this bullet should have cited from the start.
 
 Concrete example: Wikidata (~115M entities). In Cassandra+JG, the
 indexed graph form is multi-TB with replication factor 3 → multi-TB