dsh-context-compression-improved 0.4.0-beta.1 → 0.5.0

package/packages/selector/src/runtime/tokenpilot/proposal.ts

@@ -15,6 +15,11 @@
  * expectedSaving = α·R·max(0, Ŝ − paybackTurns)    // Ŝ = estimated remaining turns
  * ```
  *
+ * The refill penalty only models mutations of already-cached context. A
+ * fresh-stage batch (shaped before its first request) is exempt via
+ * `refillPenaltyExempt`: payback is 0 and every reclaimed token saves from
+ * the very first turn.
+ *
  * `expectedSaving` is only produced when Ŝ is known (the estimator answered
  * with `expectedRemainingTurns`); it is never fabricated from a guess.
  */
@@ -36,6 +41,10 @@ export interface BenefitInput {
   readonly tailTokens: number
   /** Estimated remaining turns Ŝ; `undefined` keeps expectedSaving out of the result. */
   readonly remainingTurns?: number | undefined
+  /** True for fresh-stage batches: their content was never served, so it is
+   *  not in the KV cache and shaping it causes no cache break — no refill
+   *  penalty applies and the whole discounted recovery is pure gain. */
+  readonly refillPenaltyExempt?: boolean | undefined
 }
 
 export interface BenefitEstimate {
@@ -61,7 +70,7 @@ export function computeBenefit(candidates: readonly BenefitCandidate[], input: B
   for (const candidate of candidates) {
     recoveredTokens += Math.max(0, candidate.tokensBefore - candidate.tokensAfter)
   }
-  const penaltyTokens = (1 - alpha) * tailTokens
+  const penaltyTokens = input.refillPenaltyExempt === true ? 0 : (1 - alpha) * tailTokens
   const perTurnSaving = alpha * recoveredTokens
   if (perTurnSaving <= 0) {
     return remainingTurns === undefined
@@ -119,6 +128,10 @@ export interface TriageInput {
   readonly remainingTurns?: number | undefined
   /** Seqs whose reduction came from the estimator channel; overrides the kind. */
   readonly estimatorSeqs?: ReadonlySet<number> | undefined
+  /** Landing stage of the batch: `'fresh'` batches are priced without the
+   *  tail-refill penalty (first-exposure shaping causes no cache break);
+   *  `'history'` batches — already-served content — pay it in full. */
+  readonly stage?: 'fresh' | 'history' | undefined
 }
 
 /** One frozen item inside a review proposal: metadata and digest, never content. */
@@ -166,44 +179,74 @@ function proposalKindFor(candidate: ClassifiableCandidate, estimatorSeqs: Readon
 }
 
 /**
- * Triage planned replacements into the three review-mode buckets.
+ * Triage planned replacements into the three review-mode buckets, pricing the
+ * pass as ONE merged mutation (R1): the tail KV-cache refill penalty is a
+ * property of the landing event, not of any single candidate, so it must be
+ * paid exactly once per batch. Pricing per candidate overstates the payback
+ * N-fold and starves every real batch out of the auto path.
+ *
+ * Pipeline: zero/negative-recovery candidates are priced out first (they never
+ * make a batch look better), the surviving batch is priced once through
+ * `computeBenefit`, the verdict is a batch decision, and any high-impact
+ * candidate (`tokensBefore ≥ reviewHighImpactTokens`) covers the whole batch
+ * into review — splitting the batch would pay a second cache break that the
+ * accounting does not model. Review skeletons are grouped one proposal per
+ * kind; a proposal id covers every item digest.
  *
- * Per candidate (R is per candidate, never cross-credited):
- * - `tokensAfter ≥ tokensBefore` → drop (nothing to recover);
- * - `tokensBefore ≥ reviewHighImpactTokens` → review ("直接送审": high impact
- *   always waits for a human, even when the payback band would pass it);
+ * Batch verdict bands (identical thresholds to the per-candidate model):
+ * - any high-impact candidate, or α too small to price a payback → review;
  * - `paybackTurns ≤ 1`, or Ŝ known and `paybackTurns ≤ 0.25·Ŝ` → auto;
  * - Ŝ known and `paybackTurns ∈ (1, 3]` → review;
  * - everything else (Ŝ unknown with a slow payback) → drop.
+ *
+ * Stage asymmetry: a `'fresh'` batch is exempt from the tail-refill penalty
+ * (`refillPenaltyExempt`) — its content was never served, so compressing it
+ * breaks no cache and payback is 0 — while a `'history'` batch mutates
+ * already-cached context and pays `(1−α)·tailTokens` in full. Without this
+ * exemption every realistic fresh batch prices into the drop band and the
+ * auto bucket stays structurally unreachable.
  */
 export function classifyCandidates(
   candidates: readonly ClassifiableCandidate[],
   input: TriageInput,
 ): ClassificationResult {
-  const auto: ClassifiableCandidate[] = []
-  const review: ProposalSkeleton[] = []
   const drop: ClassifiableCandidate[] = []
+  const usable: ClassifiableCandidate[] = []
   for (const candidate of candidates) {
-    const benefit = computeBenefit([candidate], input)
-    if (benefit.recoveredTokens <= 0) {
+    if (Math.max(0, candidate.tokensBefore - candidate.tokensAfter) <= 0) {
       drop.push(candidate)
       continue
     }
-    const highImpact = candidate.tokensBefore >= input.reviewHighImpactTokens
-    const payback = benefit.paybackTurns
-    if (!highImpact && payback !== undefined) {
-      const clearlyProfitable = payback <= 1
-        || (input.remainingTurns !== undefined && payback <= 0.25 * input.remainingTurns)
-      if (clearlyProfitable) {
-        auto.push(candidate)
-        continue
-      }
-      const edgeBand = input.remainingTurns !== undefined && payback <= 3
-      if (!edgeBand) {
-        drop.push(candidate)
-        continue
-      }
-    }
+    usable.push(candidate)
+  }
+  if (usable.length === 0) return { auto: [], review: [], drop }
+
+  const benefit = computeBenefit(usable, {
+    alpha: input.alpha,
+    tailTokens: input.tailTokens,
+    ...input.remainingTurns !== undefined ? { remainingTurns: input.remainingTurns } : {},
+    refillPenaltyExempt: input.stage === 'fresh',
+  })
+  const payback = benefit.paybackTurns
+  const highImpact = usable.some(candidate => candidate.tokensBefore >= input.reviewHighImpactTokens)
+  let verdict: 'auto' | 'review' | 'drop'
+  if (highImpact || payback === undefined) {
+    // High impact covers the whole batch; α too small to price a payback has
+    // no discounted recovery to argue from, so a human decides.
+    verdict = 'review'
+  } else if (payback <= 1
+    || (input.remainingTurns !== undefined && payback <= 0.25 * input.remainingTurns)) {
+    verdict = 'auto'
+  } else if (input.remainingTurns !== undefined && payback <= 3) {
+    verdict = 'review'
+  } else {
+    verdict = 'drop'
+  }
+  if (verdict === 'auto') return { auto: usable, review: [], drop }
+  if (verdict === 'drop') return { auto: [], review: [], drop: [...drop, ...usable] }
+
+  const itemsByKind = new Map<ProposalKind, ProposalItem[]>()
+  for (const candidate of usable) {
     const item: ProposalItem = {
       seq: candidate.sourceSeq,
       component: candidate.component,
@@ -212,12 +255,13 @@ export function classifyCandidates(
       tokensAfter: candidate.tokensAfter,
       digest: contentDigest(candidate.content),
     }
-    review.push({
-      id: proposalId([item.digest]),
-      kind: item.kind,
-      items: [item],
-      benefit,
-    })
+    const bucket = itemsByKind.get(item.kind) ?? []
+    bucket.push(item)
+    itemsByKind.set(item.kind, bucket)
+  }
+  const review: ProposalSkeleton[] = []
+  for (const [kind, items] of itemsByKind) {
+    review.push({ id: proposalId(items.map(item => item.digest)), kind, items, benefit })
   }
-  return { auto, review, drop }
+  return { auto: [], review, drop }
 }

package/packages/selector/src/runtime/tokenpilot/read-state.ts

@@ -8,6 +8,7 @@
  * aggregate placeholder instead of the ordinary historical placeholder.
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { looksLikeDocument } from '../reducers.ts'
 
 /** Write-style tool names whose success supersedes earlier reads. */
 const WRITE_TOOLS = /(?:^|[-_])?(?:write|edit|apply_patch|file_write|file_edit|str_replace|replace|multiedit)(?:$|[-_])/i
@@ -53,13 +54,18 @@ export function isSupersededRead(
 /** Error/warning/info line classifiers used by the omission summary. */
 const ERROR_LINE = /\b(error|failed|failure|fatal|exception|traceback|cannot|unable|denied)\b/i
 const WARN_LINE = /\b(warn|warning|deprecated)\b/i
+const SECTION_HEADING = /^#{1,3}\s+(.{1,80})/
 
 /**
- * Cluster one omitted line-count into an error/warn/info census appended to a
- * placeholder marker, giving the model meta-knowledge about what was dropped.
+ * Cluster one omitted line-count into a summary appended to a placeholder
+ * marker, giving the model meta-knowledge about what was dropped. Document
+ * content (R8) swaps the error/warn/info census for a section-heading list —
+ * `0 error, 0 warn, N info` carries no information about a dropped document,
+ * while its heading list does.
  */
 export function clusterOmittedLines(text: string, omittedLines: number): string | undefined {
   if (omittedLines <= 0) return undefined
+  if (looksLikeDocument(text)) return documentCensus(text, omittedLines)
   let errors = 0
   let warns = 0
   let infos = 0
@@ -75,3 +81,18 @@ export function clusterOmittedLines(text: string, omittedLines: number): string
   if (parts.length === 0) return undefined
   return `${String(omittedLines)} lines omitted (${parts.join(', ')})`
 }
+
+/** Bounded section-heading list for an omitted document (R8 census). */
+function documentCensus(text: string, omittedLines: number): string {
+  const titles: string[] = []
+  for (const line of text.split('\n')) {
+    const match = SECTION_HEADING.exec(line)
+    if (match === null) continue
+    titles.push(match[1]!.trim())
+    if (titles.length >= 8) break
+  }
+  if (titles.length === 0) return `${String(omittedLines)} lines omitted (document content)`
+  let summary = titles.join(' · ')
+  if (summary.length > 240) summary = `${summary.slice(0, 240)}…`
+  return `${String(omittedLines)} lines omitted (sections: ${summary})`
+}

package/packages/selector/src/runtime/tokenpilot/review-registry.ts

@@ -0,0 +1,117 @@
+/**
+ * Scope-independent handle on the live review pipeline.
+ *
+ * The R4 HTTP routes are registered on the plugin's TOP-LEVEL fiber
+ * (`cordis.patch.yml` → `context-compression-improved-estimator-catalog`),
+ * but every `ToolResultPruner` is mounted inside an agent preset's isolated
+ * group — `canonicalCompressionRows()` declares
+ * `isolate: { compaction: true, toolResultPruner: true }` — so
+ * `ctx.get('toolResultPruner')` at the top level is always `undefined` and the
+ * queue route could only ever answer 503 "review pipeline unavailable".
+ *
+ * Ownership, not transport, was in the wrong place: the queue records are
+ * already keyed by session id, so the store belongs to the plugin rather than
+ * to one pruner instance. Every instance shares one store and publishes itself
+ * here, which lets a top-level reader reach whichever instance currently holds
+ * a session's proposals.
+ *
+ * The durable seam already behaves this way — `REVIEW_STORAGE_DOMAIN` /
+ * `REVIEW_STORAGE_TABLE` are constants, so every instance opens the same table.
+ * Only the in-memory fallback was per-instance, and that is what this module
+ * makes shared.
+ *
+ * @module dsh-context-compression-improved/review-registry
+ */
+
+import { MemoryReviewStore, type ReviewQueueStore } from './review-queue.ts'
+
+/**
+ * The review faces the HTTP routes consume — structural, so the concrete
+ * `ToolResultPruner` (a Cordis service with a far wider surface) satisfies it
+ * without this module depending on the runtime class.
+ */
+export interface ReviewPrunerFace {
+  listReviewProposals(session: unknown): readonly {
+    readonly id: string
+    readonly kind: string
+    readonly items: readonly {
+      readonly seq: number
+      readonly kind: string
+      readonly component: string
+      readonly tokensBefore: number
+      readonly tokensAfter: number
+    }[]
+    readonly benefit: {
+      readonly recoveredTokens: number
+      readonly penaltyTokens: number
+      readonly paybackTurns?: number
+      readonly expectedSaving?: number
+    }
+    readonly enqueuedTurn: number
+    readonly lastTurnIndex: number
+  }[]
+  decideReviewProposal(
+    session: unknown,
+    proposalId: string,
+    decision: 'approved' | 'rejected' | 'ignored',
+  ): { ok: true } | { ok: false, reason: string } | undefined
+  /** Aggregate pending read; absent on older builds (routes then degrade to 503). */
+  listAllReviewProposals?(): readonly {
+    readonly sessionId: string
+    readonly proposals: readonly {
+      readonly id: string
+      readonly kind: string
+      readonly items: readonly { readonly seq: number; readonly kind: string; readonly component: string; readonly tokensBefore: number; readonly tokensAfter: number }[]
+      readonly benefit: { readonly recoveredTokens: number; readonly penaltyTokens: number; readonly paybackTurns?: number; readonly expectedSaving?: number }
+      readonly enqueuedTurn: number
+      readonly lastTurnIndex: number
+    }[]
+  }[]
+  reviewSummary?(session: unknown): {
+    readonly autoApplied: number
+    readonly reviewApplied: number
+    readonly expired: number
+    readonly voided: number
+  }
+}
+
+/**
+ * The one in-memory fallback every pruner instance starts from. Session ids are
+ * globally unique and `ReviewSessionRecord` is keyed by them, so a single store
+ * is semantically identical to one store per instance — except that a reader
+ * reaching any instance now observes every session.
+ */
+const sharedStore: ReviewQueueStore = new MemoryReviewStore()
+
+const live = new Set<ReviewPrunerFace>()
+
+/** The process-wide review queue store shared by every pruner instance. */
+export function sharedReviewStore(): ReviewQueueStore {
+  return sharedStore
+}
+
+/**
+ * Publish one pruner instance for scope-independent readers.
+ * @param pruner - the instance to publish.
+ * @returns the disposer removing it, for `ctx.effect`.
+ */
+export function registerReviewPruner(pruner: ReviewPrunerFace): () => void {
+  live.add(pruner)
+  return () => {
+    live.delete(pruner)
+  }
+}
+
+/**
+ * Resolve a live pruner instance for the top-level routes.
+ *
+ * Any instance can serve an aggregate read because the store is shared, and a
+ * session-scoped read is answered from that same store. Instances that have
+ * upgraded to the durable seam read the same table, so the answer does not
+ * depend on which instance this happens to return.
+ *
+ * @returns a live instance, or `undefined` when no preset has been composed yet.
+ */
+export function resolveReviewPruner(): ReviewPrunerFace | undefined {
+  return live.values().next().value
+}

package/packages/selector/src/runtime/tokenpilot/sidechannel.ts

@@ -0,0 +1,303 @@
+/**
+ * TokenPilot-inspired side channel (Phases 10–13).
+ *
+ * The S1 relevance filters (S1a search nodes, S1b document sections) ride the
+ * SAME transports the estimator uses — `host` (the Harness `llm` service) or
+ * `direct` (OpenAI-compatible HTTP) — with `maxTokens: 256`,
+ * `temperature: 0`, `reasoningEffort: 'off'`. No second provider/model
+ * configuration surface exists; failures are fail-open (`undefined`, never a
+ * throw) and the mechanical fold is always the fallback.
+ *
+ * Layer rules: the side channel only changes SELECTION and ORDER; it never
+ * rewrites content and never removes a node's existence (L1 locators and
+ * section headings always survive). Every call is cost-gated: if everything
+ * fits the budget the channel is not called at all.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { PresetOptionsSettings } from '../types.ts'
+
+/** The minimal face of the Harness `llm` service this module consumes. */
+export interface HostLlmLike {
+  stream(request: {
+    provider: string
+    model: string
+    messages: readonly { readonly role: 'user', readonly content: readonly { readonly type: 'text', readonly text: string }[] }[]
+    system?: string
+    temperature?: number
+    reasoningEffort?: string
+    maxTokens?: number
+    signal?: AbortSignal
+  }): AsyncIterable<{ readonly type: string, readonly text?: string }>
+}
+
+/** Audit record of one side-channel call (Phase 13). All fields optional-safe. */
+export interface SideChannelAudit {
+  readonly ok: boolean
+  readonly latencyMs: number
+  /** host|direct plus the resolved provider/model identity. */
+  readonly channel?: string
+  /** L2 coverage: content shown N of node content total M. */
+  readonly coverage?: { readonly shown: number, readonly total: number }
+  readonly reason?: string
+}
+
+export interface SideChannelRequest {
+  readonly system: string
+  readonly user: string
+  readonly signal: AbortSignal
+}
+
+/** One bound side channel. `ask` resolves `undefined` on ANY failure. */
+export class SideChannel {
+  /**
+   * @param overrides - per-consumer overrides of the estimator-named options.
+   * The estimator itself never passes them (byte-identical behavior); the
+   * advisory advisor passes its own mode/timeout/output budget so both
+   * consumers share one transport without sharing one configuration.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly options: PresetOptionsSettings,
+    private readonly overrides?: {
+      readonly mode?: '' | 'host' | 'direct'
+      readonly timeoutMs?: number
+      readonly maxTokens?: number
+    },
+  ) {}
+
+  private get mode(): '' | 'host' | 'direct' {
+    return this.overrides?.mode ?? this.options.estimatorMode ?? ''
+  }
+
+  get enabled(): boolean {
+    return this.mode === 'host' || this.mode === 'direct'
+  }
+
+  async ask(request: SideChannelRequest): Promise<string | undefined> {
+    const timeoutMs = this.overrides?.timeoutMs ?? this.options.estimatorTimeoutMs ?? 3_000
+    const timeout = AbortSignal.timeout(timeoutMs)
+    const signal = typeof AbortSignal.any === 'function' ? AbortSignal.any([request.signal, timeout]) : timeout
+    try {
+      if (this.mode === 'host') return await this.askHost(request.system, request.user, signal)
+      if (this.mode === 'direct') return await this.askDirect(request.system, request.user, signal)
+      return undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Failure-open wrapper that also records one audit record per call. */
+  async askAudited(request: SideChannelRequest): Promise<{ text?: string, audit: SideChannelAudit }> {
+    const now = Date.now()
+    const text = await this.ask(request)
+    const audit: SideChannelAudit = {
+      ok: text !== undefined,
+      latencyMs: Date.now() - now,
+      ...this.identity() !== undefined ? { channel: this.identity()! } : {},
+      ...(text === undefined ? { reason: 'channel returned no content (timeout, non-2xx, parse failure, or reasoning ate the output-token budget)' } : {}),
+    }
+    return { ...(text === undefined ? {} : { text }), audit }
+  }
+
+  identity(): string | undefined {
+    if (this.mode === 'direct') {
+      return `direct:${this.options.estimatorModel ?? ''}`
+    }
+    if (this.mode === 'host') {
+      const route = this.resolveHostRoute()
+      return route === undefined ? 'host' : `host:${route.provider}/${route.model}`
+    }
+    return undefined
+  }
+
+  /** Same host-route resolution as the estimator: explicit, then host default. */
+  private resolveHostRoute(): { provider: string, model: string } | undefined {
+    const provider = this.options.estimatorProvider ?? ''
+    const model = this.options.estimatorModel ?? ''
+    if (provider.length > 0 && model.length > 0) return { provider, model }
+    try {
+      const defaults = this.ctx.get('agentDefaultModel' as never) as
+        | { currentSelection?: () => { provider?: string, model?: string } | undefined }
+        | undefined
+      const selected = defaults?.currentSelection?.()
+      const selectedProvider = selected?.provider ?? ''
+      const selectedModel = selected?.model ?? ''
+      if (selectedProvider.length > 0 && selectedModel.length > 0) {
+        return {
+          provider: provider.length > 0 ? provider : selectedProvider,
+          model: model.length > 0 ? model : selectedModel,
+        }
+      }
+    } catch {
+      // optional service; absence must not throw
+    }
+    return undefined
+  }
+
+  private async askHost(system: string, user: string, signal: AbortSignal): Promise<string | undefined> {
+    let llm: HostLlmLike | undefined
+    try {
+      llm = this.ctx.get('llm' as never) as HostLlmLike | undefined
+    } catch {
+      return undefined
+    }
+    if (llm?.stream === undefined) return undefined
+    const route = this.resolveHostRoute()
+    if (route === undefined) return undefined
+    let text = ''
+    const stream = llm.stream({
+      provider: route.provider,
+      model: route.model,
+      messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+      system,
+      temperature: 0,
+      reasoningEffort: 'off',
+      maxTokens: this.overrides?.maxTokens ?? 256,
+      signal,
+    })
+    for await (const chunk of stream) {
+      // reasoningEffort 'off' is a request, not a guarantee: if reasoning still
+      // eats the 256-token budget, `content` stays empty and the caller falls
+      // back to the mechanical fold (text.trim() check below).
+      if (chunk.type === 'text-delta' && typeof chunk.text === 'string') {
+        text += chunk.text
+      } else if (chunk.type === 'finish' && chunk.text === undefined) {
+        break
+      }
+    }
+    return text.trim().length > 0 ? text : undefined
+  }
+
+  private async askDirect(system: string, user: string, signal: AbortSignal): Promise<string | undefined> {
+    const baseUrl = this.options.estimatorBaseUrl
+    if (baseUrl === undefined || baseUrl.length === 0) return undefined
+    const headers: Record<string, string> = { 'content-type': 'application/json' }
+    if (this.options.estimatorApiKey !== undefined && this.options.estimatorApiKey.length > 0) {
+      headers.authorization = `Bearer ${this.options.estimatorApiKey}`
+    }
+    const model = this.options.estimatorModel ?? ''
+    if (model.length === 0) return undefined
+    const response = await fetch(`${baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: system },
+          { role: 'user', content: user },
+        ],
+        temperature: 0,
+        max_tokens: this.overrides?.maxTokens ?? 256,
+      }),
+      signal,
+    })
+    if (!response.ok) return undefined
+    const payload = (await response.json()) as {
+      choices?: { message?: { content?: string } }[]
+    }
+    const text = payload.choices?.[0]?.message?.content
+    return typeof text === 'string' && text.trim().length > 0 ? text : undefined
+  }
+}
+
+/**
+ * Rank-then-cut (TS4): ONE call sorts and filters. The prompt carries the
+ * query, the main LLM's reasoning summary (the intent lives there — AD11),
+ * and per-node summaries with identifier + count + ONE content sample.
+ */
+export function buildRankSystemPrompt(kind: 'search' | 'document'): string {
+  const what = kind === 'search' ? 'files' : 'document sections'
+  return [
+    'You rank session artifacts by relevance to an agent query.',
+    `You are given numbered ${what} with a short sample each.`,
+    `Answer with ONLY the identifiers of the ${what} that matter, most relevant first,`,
+    'as a comma-separated list. Omit identifiers you consider irrelevant.',
+    'Never invent identifiers; never add commentary.',
+  ].join(' ')
+}
+
+export function parseRanking(text: string | undefined, validIds: ReadonlySet<string>): string[] | undefined {
+  if (text === undefined || text.trim().length === 0) return undefined
+  const ranked: string[] = []
+  const seen = new Set<string>()
+  for (const token of text.split(/[\s,;]+/)) {
+    const id = token.replace(/[^\w./:#-]/gu, '')
+    if (id.length === 0 || !validIds.has(id) || seen.has(id)) continue
+    seen.add(id)
+    ranked.push(id)
+  }
+  return ranked.length > 0 ? ranked : undefined
+}
+
+/** Nodes mentioned by the LM keep their rank; the rest are appended in order (SC-existence). */
+export function mergeRanking<T extends { readonly id: string }>(nodes: readonly T[], ranking: readonly string[] | undefined): readonly T[] {
+  if (ranking === undefined) return nodes
+  const byId = new Map(nodes.map(node => [node.id, node]))
+  const ordered: T[] = []
+  for (const id of ranking) {
+    const node = byId.get(id)
+    if (node !== undefined) ordered.push(node)
+  }
+  for (const node of nodes) {
+    if (!ordered.includes(node)) ordered.push(node)
+  }
+  return ordered
+}
+
+/** Cost gate (R-10): call only when something must be dropped and there is more than one node. */
+export function sideChannelGate(fitsBudget: boolean, nodeCount: number): boolean {
+  return !fitsBudget && nodeCount > 1
+}
+
+/** One node face offered to the rank prompt: id + count/mass + ONE content sample. */
+export interface RankedNode { readonly id: string, readonly detail: string, readonly sample: string }
+
+export function buildRankUserPrompt(
+  nodes: readonly RankedNode[],
+  query: string,
+  reasoningSummary: string | undefined,
+): string {
+  const lines = [
+    ...(query.trim().length > 0 ? [`query: ${query.trim().slice(0, 300)}`] : []),
+    ...(reasoningSummary !== undefined && reasoningSummary.trim().length > 0
+      ? [`reasoning: ${reasoningSummary.trim().slice(0, 300)}`] : []),
+    ...nodes.map(node => `${node.id} | ${node.detail} | ${node.sample.replace(/\s+/gu, ' ')}`),
+  ]
+  return lines.join('\n')
+}
+
+export interface RankOutcome {
+  /** Ranked ids the LM returned; `undefined` on any failure (fail-open). */
+  readonly ranking?: readonly string[]
+  readonly audit: SideChannelAudit
+}
+
+/**
+ * S1 orchestrator: gate → ONE channel call → parse → merge. Every failure
+ * path (gate closed, channel undefined, garbage answer) resolves with
+ * `ranking: undefined`, which the mechanical fold reproduces byte-for-byte.
+ */
+export async function rankNodes(
+  nodes: readonly RankedNode[],
+  validIds: ReadonlySet<string>,
+  query: string,
+  reasoningSummary: string | undefined,
+  channel: Pick<SideChannel, 'ask' | 'askAudited' | 'identity'>,
+  signal: AbortSignal,
+): Promise<RankOutcome> {
+  if (nodes.length <= 1 || query.trim().length === 0) {
+    return { audit: { ok: false, latencyMs: 0, reason: 'gate closed: single node or empty query' } }
+  }
+  const { text, audit } = await channel.askAudited({
+    system: buildRankSystemPrompt('search'),
+    user: buildRankUserPrompt(nodes, query, reasoningSummary),
+    signal,
+  })
+  const ranking = parseRanking(text, validIds)
+  return {
+    ...(ranking === undefined ? {} : { ranking }),
+    audit: ranking === undefined
+      ? { ...audit, ok: false, reason: 'unparseable or empty ranking; falling back to the mechanical fold' }
+      : audit,
+  }
+}