Module reduce 

Compatibility facade for optional reversible reduction.

Modules

handoff

TR-9 (T24): /handoff as extreme projection — “Amp retired summarization-compaction for /handoff: spawn a new thread seeded with a drafted objective + curated relevant artifacts, old thread untouched.” (TOKEN-REDUCTION-TECHNIQUES.md@ad3f2a4 §T24). In supercode a handoff is NOT a new session lineage — it is a named ReductionLog snapshot over the SAME sidecar: the projected view collapses to (1) a handoff banner, (2) an objective paragraph, and (3) a curated keep-set, with EVERY OTHER turn covered by one ReductionKind::TurnsCleared span per contiguous gap between kept turns.

normalize

T30/TR-4 — terminal-noise normalization (ReductionKind::OutputNormalized): a small, deterministic line-buffer terminal simulator that collapses ANSI color/style codes and carriage-return/erase-line/cursor-up redraws down to the FINAL rendered content of each line — the same content a human watching the build would actually see, without the hundreds of intermediate redraws a captured progress bar otherwise leaves in the transcript.

rehydrate

T12 — model-invocable rehydration/retrieval over the sidecar (SPEC.md TR-1): the two agent intrinsics expand_reduction and sidecar_search. “The missing half of A7”: until this landed, only the USER could recover reduced content mid-flight (C4 /expand); the model itself had no way to ask for it back, which is exactly what capped how aggressive every other reducer could safely be.

stub

The C2 reduction stub: the one shared format/parse module every placeholder-emitting reduction (A7-A10, and any future kind) goes through.

summarize

TR-7 (T20): the injectable side-call that turns an A10 TurnsCleared span into a short LLM-written summary paragraph, instead of leaving it as the deterministic [turns cleared] stub — “what incumbents’ compaction writes, but with the original retained in the sidecar” (TR-7.md).

Structs

MessageAddr

Address in the CANONICAL full view (the Session reconstructed from the sidecar).

PreparedClearSummary

The output of prepare_cleared_turns_summary — one summarized span, ready for project_messages to apply IF (and only if) it independently recomputes the exact same (first, last) range for its own ReductionKind::TurnsCleared candidate this call. Threaded through ReductionPolicy::cleared_turns_summary; see that field’s doc comment for the full data-vs-config-knob split (mirrors ReadFreshness).

ReadFreshness

The output of probe_read_freshness (A8): per-message-index freshness verdicts, threaded into project_messages via ReductionPolicy::read_freshness. Opaque on purpose — build it only through probe_read_freshness; the empty Default means “nothing is fresh,” so a policy with elide_stale_reads set but no probe run against it elides nothing (fails closed).

ReadLogEntry

A record of a file read, kept in ReductionLog::read_log so an exporter or a later model can always answer “what was read” even when the read result itself was elided from the view (A8).

Reduction

One applied reduction: what kind it was, where it points, its stable id, and the exact placeholder text standing in for it in the reduced view.

ReductionAttribution

Durable aggregate for ReductionPassAttribution. Byte and token aggregates are marginal sums, never sums of overlapping standalone claims.

ReductionError

A reduction invariant failed or a reversible pointer could not be resolved.

ReductionLog

The persisted index of every reduction applied to a session, plus the A8 read-log. This is the <name>.reduction.json sidecar-family file (D1); invert needs it (with the sidecar) to reconstruct the full view.

ReductionPassAttribution

Durable, content-free accounting for one reduction pass. This is proof metadata only: inversion and projection depend exclusively on ReductionLog::reductions. Keeping it with the log lets an offline inspector distinguish a disabled pass, an enabled pass with no candidate, and a candidate later subsumed by a higher-order pass such as A10.

ReductionPolicy

Knobs controlling project_messages. Defaults match SPEC.md A5/A7, stacked per D14 with the levers that don’t need an external I/O probe to be safe on-by-default (redact_images; contrast elide_stale_reads, below).

SidecarPtr

A pointer from a reduced placeholder back to its original content in the sidecar.

SpanSummary

TR-7 (T20) audit metadata for a ReductionKind::TurnsCleared span whose placeholder carries an LLM-generated summary. Recorded on the reduction itself (persisted in the <name>.reduction.json sidecar-family file) so the audit trail survives independent of the exact placeholder rendering (SPEC.md TR-7 dev/04: “reduction log records model id, prompt version, and summary hash for every summarized span”).

Enums

EscalationAction

The decision a future escalation orchestrator (SPEC.md D13/wave-5 escalate() — not yet implemented in this codebase) should take for one existing ReductionKind::ToolInputElided stub, per TR-10’s freshness matrix (reused from A8’s probe_read_freshness pattern): does disk still match what was written?

ReductionKind

What kind of reduction produced a placeholder, and the data specific to that kind. String forms (for the stub grammar) map 1:1 onto these variants.

ToolOutcome

The structural outcome known for a tool-result message.

Constants

READ_TOOLS

Read-type tool names A8 elision applies to. A tool result is a candidate only when its paired assistant tool_calls entry names one of these (tools/builtins.rs:39-104’s read_file). B6 must keep this in sync with any built-in tool rename.

REDUCTION_METADATA_KEY

The reserved ChatMessage.metadata key carrying a reduced message’s Reduction::id (the sc. prefix is reserved for this reduction layer’s own bookkeeping).

REDUCTION_SENTINEL

The sentinel prefix every reduction placeholder starts with (D2).

TOOL_ERROR_METADATA_KEY

Canonical metadata key marking a tool result as a structured error.

TOOL_OUTCOME_UNKNOWN_METADATA_KEY

Canonical metadata key marking a tool result whose outcome is unknown.

Functions

content_hash

Hash helper used consistently across the reduction layer: blake3 hex digest of bytes. Used both for SidecarPtr::content_hash and ReadLogEntry::content_hash.

export_session

Export a live session from its full-fidelity sidecar.

export_session_spliced

Export a live session while replaying an imported native prefix verbatim.

export_session_spliced_with_overrides

Spliced sidecar export with an optional working-directory override.

invert

Reconstruct a full view from a reduced view and sidecar session.

invert_messages

Reconstruct the full view: every placeholder in reduced replaced by the original content resolved from sidecar_session (the ONE canonical model — a canonical message slice reconstructed from its sidecar), hash-verified against SidecarPtr::content_hash before ever substituting it in.

invert_one

Rehydrate one reduction by id against a sidecar session.

invert_one_messages

Rehydrate a single reduction by id (C4 /expand <id>; also used for per-range TurnsCleared expansion). Returns the updated view and a log with that record removed (an expanded reduction is no longer “applied”).

is_tool_error

Whether a message carries the canonical structured-error marker.

make_id

Build a Reduction::id: a zero-padded 4-digit ordinal plus the first 4 hex characters of a content hash (D2), e.g. "r0042-9f3c".

mark_tool_error

Stamp a tool-result message as a structured error.

mark_tool_outcome_unknown

Stamp a tool-result message as having no structurally known outcome.

prepare_cleared_turns_summary

TR-7’s one side-call site (SPEC.md: “an explicit, budgeted, injectable side-call… never blocking the main loop”). Call this against the exact same msgs slice about to be projected (mirrors probe_read_freshness’s own calling convention), thread the result through ReductionPolicy::cleared_turns_summary before calling project_messages. Only ever does anything when policy.summarize_cleared_turns is set; callers that never enable TR-7 can skip calling this entirely (dev/01: project_messages behaves identically either way when the policy gate is off).

prepare_read_freshness

Populate the external disk-probe input required by A8 before projecting msgs. All production projection/preflight sites route through this helper so the context guard and the eventual provider request judge the same stale-read savings. Other policy fields are untouched.

probe_read_freshness

The A8 disk-probe pre-pass, deliberately kept OUTSIDE project_messages so the pure projection core never touches the filesystem itself (SPEC.md A8’s purity requirement). Call this with the exact same msgs slice about to be projected — indices must line up — and thread the result through ReductionPolicy::read_freshness before calling project_messages (or project_messages); it is only ever consulted when policy.elide_stale_reads is set, so callers that never enable A8 can skip calling this entirely.

probe_tool_input_fresh

The A8-style disk probe behind tool_input_escalation_action: does the file at path currently on disk still hash to content_hash_hex? Unlike probe_read_freshness (which lossy-UTF8-decodes before hashing, to mirror read_file’s own transform), this hashes the RAW bytes directly — write_file writes content.as_bytes() with no transform, so the exact bytes on disk are the fairer comparison. Unreadable/deleted files are never fresh (fails closed, the same direction A8 fails in). A free function (no Reduction/ReductionLog coupling) so it composes with whatever wave-5 escalate() orchestration eventually calls it.

project

Pure function of (session, policy, prior): the compatibility entry point producing what the model sees (SPEC.md A5).

project_messages

Pure function of (msgs, policy, prior): the reduction engine’s actual body (SPEC.md A5, A7, A8, A9, A10, TR-2). A session adapter can delegate its canonical message slice here; a runtime agent loop calls this directly against history[1..] so a live agent can build the projected request view without needing a Session wrapper around its own history.

reduce_to_fit

PARITY-18 v3 — the “aggressive reduction” half of the fix (SPEC.md scaling-context-guard): apply project_messages with base_policy first, then, if fits says the projected view still doesn’t pass, retry with progressively tighter policies (see tighten) up to MAX_AGGRESSIVE_LEVELS times, then escalate to A10 turn-clearing, keeping whichever attempt is smallest. Never fails and never loops unboundedly — it always returns SOME projection (the caller’s own preflight guard is responsible for deciding whether even the tightest attempt still exceeds the target model’s context limit and refusing to send in that case, PARITY-18 dev/01).

reduction_id

Read back a message’s sc.reduction id, if it was reduced.

set_reduction_id

Stamp msg with the sc.reduction metadata key pointing at id. This is the one place a reduction’s id is attached to a message; every A/B emitter should go through this rather than writing the key by hand.

tool_input_escalation_action

TR-10’s freshness-matrix decision, given whether probe_tool_input_fresh found the file still matching: fresh -> EscalationAction::KeepStub, !fresh -> EscalationAction::RehydrateFromSidecar. Split from the probe itself (which does the actual disk I/O) so this half stays a pure, trivially-testable function — the same purity discipline A8’s probe_read_freshness/project_messages split follows.

tool_outcome

Return the canonical structural outcome for a tool-result message.

verify_log

Verify every reduction against a sidecar session.

verify_log_messages

Verify every reduction in log resolves against sidecar — the same hash-verify path invert/invert_one walk before ever substituting content back in, without needing an actual reduced view to substitute into. This is the user-facing detector for a broken transparency invariant (C2 contract 3): sessions show-reductions (C4) and convert (C7) both call this before doing anything else with a reduced session, so a corrupt/tampered/stale sidecar is reported — naming the offending record id — before any output is produced, rather than surfacing as a confusing downstream failure (or, worse, silently substituting the wrong content).

Type Aliases

ContentHash

A blake3 hex digest, as produced by content_hash. A type alias only (not a newtype) — matches every existing hash field in this module (SidecarPtr::content_hash, ReadLogEntry::content_hash), which stayed plain String rather than retrofit this alias in place (SPEC.md TR-3: “keep enum/match additions minimal and localized”).

ReductionResult

Explicitly named alias for callers that also import another crate’s Result.

Result

Result type for standalone reduction operations.