A controller needs to find candidates before deciding which source bodies to inspect. Separate search from read: search returns candidate metadata; read returns the exact text of a selected passage. With two operations, the recorded search and read results show which candidates a controller chose and which source text it read.
A handle identifies a candidate issued by a particular search against a particular corpus. It carries the metadata needed to resolve that passage later. A handle points to a result. It does not mean that the result answers the question, and it does not give the caller general read permission.
When you need this. Use this boundary when a caller should choose among candidates before receiving source bodies, and every read must refer to a passage returned by a matching search.
Follow one example. Search the pinned documentation with the supported literal term overwritten and version 3.12. Select one returned handle, then pass it to read in the same tool instance. The read returns the paragraph and its provenance. If you change a bound field in the handle, read refuses it instead of returning a different passage.
You add these two operations on top of the existing local lexical index. The lab calls the tools directly; no model chooses a tool or generates a response. A controller must validate each read result before it accepts the text as source text.
Search for a handle, then read its exact text
- Search eligible passages.
- Return ranked handles without source bodies.
- Read a selected issued handle.
- Return its exact source text.
- Refuse an invalid search request.
- Refuse an invalid handle.
Separate candidate selection from source reading
A passage is one versioned paragraph in the supplied snapshot. The snapshot holds original teaching summaries that link to the primary documents; it is not a fresh crawl. Before the index is built, the loader compares the snapshot file with its pinned hash and applies the inherited snapshot validation rules.
search accepts a bounded alphanumeric query term, a requested documentation version and a result limit. It does not parse natural-language questions. The lexical index ranks every match. The tool then keeps only passages with the exact requested version, and only after that applies the caller’s result limit. Filter by version before you apply the limit; otherwise higher-ranked passages from other versions can fill the limit and hide an eligible passage. Fetching every candidate is practical only because the tools refuse a corpus of more than 100 passages.
Search returns handles: structured metadata containing the corpus identity, search-request identity, passage identity, version, revision, span, text hash, planned text bytes and rank. It does not include the source text or the source URL. To check how many bytes of passage text a read will return, call read_cost. It validates the handle and returns its byte_count without reading the text.
Read only a handle issued by this tool instance
read looks up a selected handle in the search results that the current tool instance stored when it issued them. The read result contains the paragraph text from the snapshot, its URL and a result hash. The line span and hashes tie the returned text to the pinned snapshot.
Changed handle. If a caller edits a handle’s version, passage identity, score or any other bound field, read refuses it. Recomputing the handle’s read_token does not help, because read compares the whole handle with its stored copy. A handle from an earlier corpus or an unissued search cannot select a different passage. These checks are local consistency rules. They are not permissions or publisher authentication, and they do not protect against code that can modify the running process.
Changed result. validate_read rebuilds the expected read result for that handle and compares it with the complete result it receives. A plausible URL, a text of the right length or a recomputed result_sha256 does not pass that comparison. The controller must call this check before it accepts a read observation.
Inspect empty and ineligible searches
A search with no lexical match returns an empty candidate list. So does a search whose matches all have a different version. The caller can tell those searches apart from a read refusal by keeping the query, version and actual result.
| Operation | Observed result |
|---|---|
| Matched search | 1 issued handles |
| Resolved reads | path-write |
| No lexical match | 0 candidates |
| Requested version absent | 0 candidates |
| Edited handle | invalid_read_handle |
An empty result means this search returned no eligible passages; relevant documents may exist elsewhere. A validated read result matches the supplied snapshot but does not guarantee that a future answer will be correct.
Execute both tool operations
Download the complete search/read lab. It includes the pinned corpus, reused lexical index and version checks, tool implementation, failure tests and execution record. Python needs SQLite with FTS5 enabled; no provider SDK or downloaded model is required.
"""Bounded documentation search handles and receipt-bound passage reads."""
import copy
import hashlib
import json
from pathlib import Path
import re
from bm25 import LexicalIndex
from version_documents import validate_snapshot,canonical_hash
SNAPSHOT_SHA256='56bbeff06b0349186c3e5999d2b4fe634c6355f3bc267d6e07c47bf2d5e32b19'
class ToolError(ValueError):pass
def load_snapshot(root=None):
path=(root or Path(__file__).parent/'fixtures')/'snapshot.json'
raw=path.read_bytes()
if hashlib.sha256(raw).hexdigest()!=SNAPSHOT_SHA256:raise ToolError('snapshot_file_hash_mismatch')
snapshot=json.loads(raw);validate_snapshot(snapshot);return snapshot
class DocumentationTools:
def __init__(self,snapshot):
validate_snapshot(snapshot)
self.snapshot=copy.deepcopy(snapshot);self.corpus_id=snapshot['snapshot_id'];self.rows={};self.receipts={};self.closed=False
for source in self.snapshot['documents']:
for chunk in source['chunks']:
self.rows[chunk['chunk_id']]={'passage_id':chunk['chunk_id'],'source_id':source['source_id'],'version':source['version'],'document_revision':source['document_revision'],'source_sha256':source['sha256'],'start_line':chunk['start_line'],'end_line':chunk['end_line'],'text_sha256':chunk['text_sha256'],'byte_count':len(chunk['text'].encode('utf-8')),'text':chunk['text'],'url':source['url']}
if not self.rows or len(self.rows)>100:raise ToolError('unsupported_corpus_size')
self.index=LexicalIndex(self.snapshot)
def close(self):
if not self.closed:self.index.close();self.closed=True
def available(self):
if self.closed:raise ToolError('tools_closed')
def search(self,query,k=2,version='3.12'):
self.available()
if type(k) is not int or not 1<=k<=10:raise ToolError('invalid_k')
if not isinstance(query,str) or re.fullmatch(r'[A-Za-z0-9]{1,64}',query) is None:raise ToolError('invalid_query')
if not isinstance(version,str) or re.fullmatch(r'[0-9]+\.[0-9]+',version) is None:raise ToolError('invalid_version')
query=query.lower()
request={'corpus_id':self.corpus_id,'query':query,'version':version,'k':k}
request_id=canonical_hash(request)
# Corpus is capped at 100. Fetch all native ranks, then version-filter
# before applying the caller's k, without losing eligible candidates.
ranked=self.index.search(query,limit=100)['results']
eligible=[row for row in ranked if row['version']==version][:k]
handles=[]
for rank,row in enumerate(eligible,1):
source=self.rows[row['chunk_id']]
handle={'corpus_id':self.corpus_id,'search_request_id':request_id,**{key:value for key,value in source.items() if key not in ('text','url')},'native_score':row['native_score'],'rank':rank}
handle['read_token']=canonical_hash(handle);handles.append(handle)
result={'corpus_id':self.corpus_id,'search_request_id':request_id,'query':query,'version':version,'k':k,'results':handles}
self.receipts[request_id]=copy.deepcopy(result)
return copy.deepcopy(result)
def validate_handle(self,handle):
self.available()
if not isinstance(handle,dict):raise ToolError('invalid_read_handle')
if handle.get('corpus_id')!=self.corpus_id:raise ToolError('stale_corpus')
passage=handle.get('passage_id')
if not isinstance(passage,str) or passage not in self.rows:raise ToolError('unknown_passage')
request=handle.get('search_request_id')
if not isinstance(request,str) or request not in self.receipts:raise ToolError('unissued_search_receipt')
expected=next((row for row in self.receipts[request]['results'] if row['passage_id']==passage),None)
try:equal=expected is not None and canonical_hash(handle)==canonical_hash(expected)
except (ValueError,TypeError,OverflowError):equal=False
if not equal:raise ToolError('invalid_read_handle')
return copy.deepcopy(expected)
def read_cost(self,handle):return self.validate_handle(handle)['byte_count']
def _read_payload(self,handle):
handle=self.validate_handle(handle);source=self.rows[handle['passage_id']]
body={**handle,'text':source['text'],'url':source['url'],'read_request_id':canonical_hash({'search_request_id':handle['search_request_id'],'read_token':handle['read_token']})}
return {**body,'result_sha256':canonical_hash(body)}
def read(self,handle):return self._read_payload(handle)
def validate_read(self,result,handle):
expected=self._read_payload(handle)
try:equal=canonical_hash(result)==canonical_hash(expected)
except (ValueError,TypeError,OverflowError):equal=False
if not equal:raise ToolError('invalid_read_result')
return copy.deepcopy(expected)python run.py --output scratch-result.json
python -m unittest discover -v{
"changed_handle_refusal": "invalid_read_handle",
"empty_eligible_count": 0,
"execution_mode": "offline-native-document-search-and-read",
"no_match_count": 0,
"read_source_ids": [
"path-write"
],
"search_results": 1
}This program runs as a local CLI. To call these methods across a service boundary, add request decoding, authorization and transport checks. Issued search results are kept in memory by one tool object; another instance refuses a handle it did not issue (unissued_search_receipt). Durable replay and sharing across processes are not implemented. Corpus-size caps and result limits are guards, not throughput measurements.
View the complete local execution JSON
{
"execution_mode": "offline-native-document-search-and-read",
"model_called": false,
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search": {
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search_request_id": "aeffc68efdee46b8d23c597f651143424c575c0c1a4699ab08a48734d011f127",
"query": "overwritten",
"version": "3.12",
"k": 2,
"results": [
{
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search_request_id": "aeffc68efdee46b8d23c597f651143424c575c0c1a4699ab08a48734d011f127",
"passage_id": "c66643a4609c6ee157458bf4353f7446b9c6a200a3ef453846d6a18d5b5069a7",
"source_id": "path-write",
"version": "3.12",
"document_revision": "28c6349eaf80b629322edb310bb871dc45a04af9fad3b752bc75d12f0d7314e7",
"source_sha256": "a48b4b9f763cd6309ebe32af19c5a814adcf810c2259683da9f328ccee46948e",
"start_line": 1,
"end_line": 1,
"text_sha256": "a48b4b9f763cd6309ebe32af19c5a814adcf810c2259683da9f328ccee46948e",
"byte_count": 224,
"native_score": -0.7992166451067193,
"rank": 1,
"read_token": "08b866d8cf00533f3484aac4d78ac512bd4df8767c9ea11fbd2e817eeeb1dd75"
}
]
},
"reads": [
{
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search_request_id": "aeffc68efdee46b8d23c597f651143424c575c0c1a4699ab08a48734d011f127",
"passage_id": "c66643a4609c6ee157458bf4353f7446b9c6a200a3ef453846d6a18d5b5069a7",
"source_id": "path-write",
"version": "3.12",
"document_revision": "28c6349eaf80b629322edb310bb871dc45a04af9fad3b752bc75d12f0d7314e7",
"source_sha256": "a48b4b9f763cd6309ebe32af19c5a814adcf810c2259683da9f328ccee46948e",
"start_line": 1,
"end_line": 1,
"text_sha256": "a48b4b9f763cd6309ebe32af19c5a814adcf810c2259683da9f328ccee46948e",
"byte_count": 224,
"native_score": -0.7992166451067193,
"rank": 1,
"read_token": "08b866d8cf00533f3484aac4d78ac512bd4df8767c9ea11fbd2e817eeeb1dd75",
"text": "Path.write_text(data, encoding=None, errors=None, newline=None) writes text to a file and closes it. Set encoding=\"utf-8\" to select UTF-8. An existing file is overwritten. The method returns the number of characters written.",
"url": "https://docs.python.org/3.12/library/pathlib.html#pathlib.Path.write_text",
"read_request_id": "a9ec642e4ed3206ac85e5dd03d4de9ff57de3167e134079eafe4a31de23cec67",
"result_sha256": "662c96d3b972224ac1549f9a6c3ad495b3ed885b6db477d52aeb7527ec1dbbb7"
}
],
"no_match": {
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search_request_id": "f76beff608c3023ea069dea052656317ac6e5fbf4654fa39daeaaeed927c000f",
"query": "xyznotindexed",
"version": "3.12",
"k": 2,
"results": []
},
"empty_eligible_version": {
"corpus_id": "0615d22a3315e97c0a88c6c566c546877304f5a28a97e83f68dd36881d4bbd0e",
"search_request_id": "98f1cba586c00f8d9a3de99a7735dd9e5e453c850a0cff0ef67d2e2589eac672",
"query": "overwritten",
"version": "3.13",
"k": 2,
"results": []
},
"changed_handle_refusal": "invalid_read_handle",
"interpretation": "Tool contract checks and native retrieval only; no model selection, answer generation or permission system."
}The printed summary contains one issued result, the path-write read and the invalid-handle refusal; both empty searches return zero candidates. The output is from the saved offline run (offline-native-document-search-and-read) and checks only the tool contract.
Follow a handle back to its paragraph
Run the program and choose a returned handle. Compare its passage identity, version, span and text hash with the read result. Change its version and run the failure test. Explain why search metadata can select a passage but cannot stand in for reading its text.
Read the explanation
Handle consistency does not provide authorization or prove that a source supports every answer claim.
What’s next
Continue with Refine Queries and Search Again.
References
SQLite FTS5, checked on 23 October 2026, documents the inherited native lexical ranking. The Python copy documentation explains the defensive copying used for returned dictionaries. Search-result validation and version eligibility are application policies defined by the supplied code. The earlier RAG baseline supplies the original developer-document task context.