docs: fix inaccurate docstrings caught in contextual review
Initial docstring pass focused on syntax/style; this pass verified each docstring against actual function behavior. Found and corrected: WRONG (claimed behavior didn't match): - _cmd_verify: claimed Q&A/audit verification — actually round-trips Merkle proofs on N random documents - _cmd_snapshot_verify: claimed Merkle proof round-trip — actually re-derives snapshot root and checks for drift - _cmd_evict: claimed 'archive unused content' — actually NULLs content and removes FTS row; cores never evict - _cmd_stats: listed 'index size' which is not in stats() output OVERSTATEMENT (claim stronger than contract): - _cmd_ask: 'grounded answer' — verifier may return UNGROUNDED - _cmd_snapshot_list: 'named' — snapshots have hash roots, not names MISSING IMPORTANT BEHAVIOR: - _cmd_rehydrate: didn't mention drift-detection exit code - _cmd_mesh_status: didn't mention 'enabled' flag (most important field) - _cmd_distill: didn't mention recursive core→core distillation - MerkleTree.proof(): didn't mention IndexError on out-of-range VAGUE: - _cmd_search: 'Search the corpus with FTS5' → mention output formats Sphinx rebuild successful (29 warnings, down from 31).
This commit is contained in:
parent
49607a5997
commit
f5a216a335
8 changed files with 24 additions and 24 deletions
|
|
@ -172,7 +172,7 @@ def _cmd_ingest(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_search(args: argparse.Namespace) -> int:
|
||||
"""Search the corpus with FTS5."""
|
||||
"""FTS5 query against chunks; print hits as JSON or formatted text."""
|
||||
conn = (
|
||||
connect_query(args.db, shards_dir=args.global_shards_dir)
|
||||
if args.global_shards_dir
|
||||
|
|
@ -211,7 +211,7 @@ def _cmd_search(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_verify(args: argparse.Namespace) -> int:
|
||||
"""Verify Q&A cache records and audit chains."""
|
||||
"""Round-trip Merkle proofs on N random documents (chunk 0 each)."""
|
||||
conn = (
|
||||
connect_query(args.db, shards_dir=args.global_shards_dir)
|
||||
if args.global_shards_dir
|
||||
|
|
@ -226,7 +226,7 @@ def _cmd_verify(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_distill(args: argparse.Namespace) -> int:
|
||||
"""Distill surface documents into compressed cores."""
|
||||
"""Distill existing documents into cores (surface→core, or core→core+1)."""
|
||||
from aborist.distill import get_distiller
|
||||
from aborist.distill.runner import distill_existing
|
||||
from aborist.store import discover_shards
|
||||
|
|
@ -292,7 +292,7 @@ def _cmd_distill(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_ask(args: argparse.Namespace) -> int:
|
||||
"""Ask a question against one document and get a grounded answer."""
|
||||
"""Ask a question against one document; verifier classifies the answer."""
|
||||
import os
|
||||
|
||||
from aborist.qa import ask
|
||||
|
|
@ -2198,7 +2198,7 @@ def _cmd_emergent(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_evict(args: argparse.Namespace) -> int:
|
||||
"""Move hot chunks to cold tier (archive unused content)."""
|
||||
"""Demote surface chunks from hot to cold (NULL content). Cores never evict."""
|
||||
from aborist.evict import evict_to_cold
|
||||
|
||||
conn = (
|
||||
|
|
@ -2220,7 +2220,7 @@ def _cmd_evict(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_rehydrate(args: argparse.Namespace) -> int:
|
||||
"""Rehydrate cold chunks from source (inverse of evict)."""
|
||||
"""Rehydrate cold chunks from source; non-zero exit if drift detected."""
|
||||
from aborist.evict import rehydrate
|
||||
|
||||
conn = (
|
||||
|
|
@ -2427,7 +2427,7 @@ def _cmd_activity(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_stats(args: argparse.Namespace) -> int:
|
||||
"""Show corpus statistics (document count, chunk count, index size)."""
|
||||
"""Counts: documents, chunks (by tier), edges, providence, audit events."""
|
||||
conn = (
|
||||
connect_query(args.db, shards_dir=args.global_shards_dir)
|
||||
if args.global_shards_dir
|
||||
|
|
@ -2676,7 +2676,7 @@ def _cmd_snapshot_create(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_snapshot_list(args: argparse.Namespace) -> int:
|
||||
"""List named corpus snapshots (named roots)."""
|
||||
"""List recent corpus snapshots (newest first, --limit N)."""
|
||||
from aborist.snapshot import list_snapshots
|
||||
|
||||
conn = connect(args.db)
|
||||
|
|
@ -2689,7 +2689,7 @@ def _cmd_snapshot_list(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_snapshot_verify(args: argparse.Namespace) -> int:
|
||||
"""Verify snapshot integrity (round-trip Merkle proofs)."""
|
||||
"""Re-derive snapshot root from current corpus; non-zero exit on drift."""
|
||||
from aborist.snapshot import verify_snapshot
|
||||
|
||||
conn = (
|
||||
|
|
@ -2722,7 +2722,7 @@ def _cmd_snapshot_diff(args: argparse.Namespace) -> int:
|
|||
|
||||
|
||||
def _cmd_mesh_status(args: argparse.Namespace) -> int:
|
||||
"""Show mesh status (members, epochs, identity)."""
|
||||
"""Show mesh state: enabled flag, identity, current epoch, roster."""
|
||||
from aborist.mesh import current_epoch, is_enabled, load_identity
|
||||
from aborist.mesh.state import roster_at
|
||||
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@ class MerkleTree:
|
|||
return cls(layers=layers)
|
||||
|
||||
def proof(self, leaf_index: int) -> MerkleProof:
|
||||
"""Generate inclusion proof for the leaf at leaf_index."""
|
||||
"""Generate inclusion proof for leaf_index. Raises IndexError if out of range."""
|
||||
if not self.layers or not self.layers[0]:
|
||||
raise IndexError("empty tree has no proofs")
|
||||
if leaf_index < 0 or leaf_index >= len(self.layers[0]):
|
||||
|
|
|
|||
Binary file not shown.
Binary file not shown.
|
|
@ -395,7 +395,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_search</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Search the corpus with FTS5."""</span>
|
||||
<span class="w"> </span><span class="sd">"""FTS5 query against chunks; print hits as JSON or formatted text."""</span>
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
<span class="n">connect_query</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">db</span><span class="p">,</span> <span class="n">shards_dir</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span>
|
||||
|
|
@ -434,7 +434,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_verify</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Verify Q&A cache records and audit chains."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Round-trip Merkle proofs on N random documents (chunk 0 each)."""</span>
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
<span class="n">connect_query</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">db</span><span class="p">,</span> <span class="n">shards_dir</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span>
|
||||
|
|
@ -449,7 +449,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_distill</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Distill surface documents into compressed cores."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Distill existing documents into cores (surface→core, or core→core+1)."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.distill</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_distiller</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.distill.runner</span><span class="w"> </span><span class="kn">import</span> <span class="n">distill_existing</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.store</span><span class="w"> </span><span class="kn">import</span> <span class="n">discover_shards</span>
|
||||
|
|
@ -515,7 +515,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_ask</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Ask a question against one document and get a grounded answer."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Ask a question against one document; verifier classifies the answer."""</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
|
||||
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.qa</span><span class="w"> </span><span class="kn">import</span> <span class="n">ask</span>
|
||||
|
|
@ -2421,7 +2421,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_evict</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Move hot chunks to cold tier (archive unused content)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Demote surface chunks from hot to cold (NULL content). Cores never evict."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.evict</span><span class="w"> </span><span class="kn">import</span> <span class="n">evict_to_cold</span>
|
||||
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
|
|
@ -2443,7 +2443,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_rehydrate</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Rehydrate cold chunks from source (inverse of evict)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Rehydrate cold chunks from source; non-zero exit if drift detected."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.evict</span><span class="w"> </span><span class="kn">import</span> <span class="n">rehydrate</span>
|
||||
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
|
|
@ -2650,7 +2650,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_stats</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Show corpus statistics (document count, chunk count, index size)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Counts: documents, chunks (by tier), edges, providence, audit events."""</span>
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
<span class="n">connect_query</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">db</span><span class="p">,</span> <span class="n">shards_dir</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">global_shards_dir</span>
|
||||
|
|
@ -2899,7 +2899,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_snapshot_list</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""List named corpus snapshots (named roots)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""List recent corpus snapshots (newest first, --limit N)."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.snapshot</span><span class="w"> </span><span class="kn">import</span> <span class="n">list_snapshots</span>
|
||||
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="n">connect</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">db</span><span class="p">)</span>
|
||||
|
|
@ -2912,7 +2912,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_snapshot_verify</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Verify snapshot integrity (round-trip Merkle proofs)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Re-derive snapshot root from current corpus; non-zero exit on drift."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.snapshot</span><span class="w"> </span><span class="kn">import</span> <span class="n">verify_snapshot</span>
|
||||
|
||||
<span class="n">conn</span> <span class="o">=</span> <span class="p">(</span>
|
||||
|
|
@ -2945,7 +2945,7 @@
|
|||
|
||||
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">_cmd_mesh_status</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="n">argparse</span><span class="o">.</span><span class="n">Namespace</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Show mesh status (members, epochs, identity)."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Show mesh state: enabled flag, identity, current epoch, roster."""</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.mesh</span><span class="w"> </span><span class="kn">import</span> <span class="n">current_epoch</span><span class="p">,</span> <span class="n">is_enabled</span><span class="p">,</span> <span class="n">load_identity</span>
|
||||
<span class="kn">from</span><span class="w"> </span><span class="nn">aborist.mesh.state</span><span class="w"> </span><span class="kn">import</span> <span class="n">roster_at</span>
|
||||
|
||||
|
|
|
|||
|
|
@ -346,7 +346,7 @@
|
|||
<div class="viewcode-block" id="MerkleTree.proof">
|
||||
<a class="viewcode-back" href="../../api/substrate.html#aborist.merkle.MerkleTree.proof">[docs]</a>
|
||||
<span class="k">def</span><span class="w"> </span><span class="nf">proof</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">leaf_index</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">MerkleProof</span><span class="p">:</span>
|
||||
<span class="w"> </span><span class="sd">"""Generate inclusion proof for the leaf at leaf_index."""</span>
|
||||
<span class="w"> </span><span class="sd">"""Generate inclusion proof for leaf_index. Raises IndexError if out of range."""</span>
|
||||
<span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">layers</span> <span class="ow">or</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">layers</span><span class="p">[</span><span class="mi">0</span><span class="p">]:</span>
|
||||
<span class="k">raise</span> <span class="ne">IndexError</span><span class="p">(</span><span class="s2">"empty tree has no proofs"</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">leaf_index</span> <span class="o"><</span> <span class="mi">0</span> <span class="ow">or</span> <span class="n">leaf_index</span> <span class="o">>=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">layers</span><span class="p">[</span><span class="mi">0</span><span class="p">]):</span>
|
||||
|
|
|
|||
|
|
@ -382,7 +382,7 @@ verify_proof() recomputes the root by combining the leaf with siblings.</p>
|
|||
<dl class="py method">
|
||||
<dt class="sig sig-object py" id="aborist.merkle.MerkleTree.proof">
|
||||
<span class="sig-name descname"><span class="pre">proof</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">leaf_index</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/aborist/merkle.html#MerkleTree.proof"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#aborist.merkle.MerkleTree.proof" title="Link to this definition">¶</a></dt>
|
||||
<dd><p>Generate inclusion proof for the leaf at leaf_index.</p>
|
||||
<dd><p>Generate inclusion proof for leaf_index. Raises IndexError if out of range.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>leaf_index</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><em>int</em></a>)</p>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue