A streamed line-window read (#811): only the requested span’s raw lines,
plus the file’s true total line count for the header — the rest of the
file is never buffered.
One-line explainer appended whenever a lines: payload uses a comma —
comma means multi-select, and a caller who meant a N-M span must be able
to see that from the output (limitations #7). Shared with the CLI arm.
Build graph-related hints (callers/callees) — exported for the registered
handler to call in a background thread after releasing the cache lock (#1098).
Whether a read of path in mode must be served as full because the
file carries agent instructions: every agent needs its complete text, so a
compressed view is re-read in full right away (a guaranteed bounce).
Lossless and pinned views — full, raw, anchored, diff, lines: —
keep the requested mode: they never withhold content the caller asked for.
Whether path is an instruction document that must always be read complete:
a built-in agent instruction file, or a path the user listed in
redirect_exclude / LEAN_CTX_HOOK_EXCLUDE (see is_user_excluded).
Whether the user excluded path from lean-ctx rewriting: redirect_exclude
globs in config, or LEAN_CTX_HOOK_EXCLUDE (comma-separated, takes
precedence). Native reads of such paths skip the hook redirect, and
automatic ctx_read modes deliver them in full.
Marker for a map/signatures view that extracted nothing — a language with
no grammar/regex coverage must be distinguishable from a file with no API
(limitations audit, #4). Shared with the CLI arms.
The rooted no-follow open on its own, for a source that is not read as
text (a history database, core::import::database): one open, relative to
the root’s descriptor, no link followed in any component on Unix, a regular
file. The caller has made the path decision and runs every further check
on the returned descriptor.
Open path under root for tool for a read in admitted units. Same
refusals as read_file_for_tool_rooted_admitted before its first byte:
PermissionDenied for a path rule, any other error for a source that is
not a readable regular file inside the root — or when the caller holds no
source view: without a pinned pack nothing is admitted in units. gateway
is the caller’s ONE snapshot of the gateway rules for this source.
Parses an anchored: window payload for the disk-streaming short-circuit
below. Only the dash form ("N-M") is fast-pathed — anchored_lines_mode
(the registered handler) always emits it, using the 999999 EOF sentinel
rather than a bare "N". A hand-typed bare payload (meaning “N to EOF”)
returns None and falls through to the normal full-read path instead of
guessing a total line count up front.
Acquire an original source under its project authority through a rooted descriptor.
Parsing and derived metadata must use the returned, admitted content.
The common rooted read: descriptor-based path jail, budget charged on the
original bytes, and one admission decided on the ORIGINAL decoded source.
Returns the delivered text together with the outcome of that original
admission, so a derived or stored item inherits the source’s
classification, storability and completeness instead of re-inferring them
from text a project rule or the gateway has already rewritten.
read_file_for_tool_rooted_admitted — the same read in every respect —
with the gateway rules of a snapshot the caller captured (Some) instead
of the configuration as it is at this moment (None): a caller that
judges several things under one snapshot has its sources judged under
that snapshot too.
Reads a file as UTF-8 with lossy fallback, enforcing binary detection and max read size limit.
Defense-in-depth: verifies that the canonical path stays within the process’s project root
(if determinable) even though callers SHOULD have already jail-checked the path.
Read and admit the original source for the CLI adapter. Unlike the generic
unscoped reader, this explicit agent-facing path always applies the Gateway
and carries the decoder’s completeness into the admission decision.
Streams path line-by-line and extracts only [start, end] (1-based,
inclusive) without ever holding the whole file in memory — the
anchored-window counterpart to read_file_lossy (#811). Every line is
still counted (one cheap UTF-8 pass, no per-line allocation outside the
requested window) so the caller can report the true total. Returns None
on anything that isn’t a clean streamed text read (I/O error, a binary
file, invalid UTF-8 anywhere in the file) so the caller can fall back to
the existing, more permissive read_file_lossy path — behaviour never
regresses, it just doesn’t always get the fast path.
Hand process_mode to the engine’s conformance scorecard
(core::conformance), whose read-mode accuracy checks measure it. The CLI
calls this at start-up; the first registration wins.
Whether a unit ends INSIDE a built-in rule whose match the whole-file
admission would continue in the following text — the built-in rules whose
reach across lines no window bounds: