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

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

@@ -64,6 +64,9 @@ export function buildEstimatorSystemPrompt(): string {
     'reference that exact file state again later in the session. Reads whose file was',
     'already rewritten, or whose task has visibly moved on, are expired.',
     'Answer with ONLY a JSON array: [{"seq":<number>,"expired":<boolean>}].',
+    'Optionally, if you can estimate how many user turns remain in this session, answer',
+    'with {"expectedRemainingTurns":<number>,"items":[{"seq":<number>,"expired":<boolean>}]}',
+    'instead; omit the field when you cannot estimate it.',
   ].join(' ')
 }
 
@@ -73,27 +76,71 @@ export function buildEstimatorUserPrompt(samples: readonly EstimatorSample[]): s
   return lines.join('\n')
 }
 
-/** Parse the estimator answer; anything malformed yields no verdicts. */
-export function parseEstimatorAnswer(text: string): EstimatorVerdict[] {
+/** One estimator answer: per-read verdicts plus the optional session-level Ŝ. */
+export interface EstimatorAnswer {
+  readonly verdicts: EstimatorVerdict[]
+  /**
+   * Estimator-reported remaining turns Ŝ for the benefit model. `undefined`
+   * whenever the model stayed on the legacy array format, omitted the field,
+   * or produced anything non-numeric — it is never guessed here.
+   */
+  readonly expectedRemainingTurns?: number
+}
+
+function parseVerdictArray(value: unknown): EstimatorVerdict[] {
+  if (!Array.isArray(value)) return []
+  const verdicts: EstimatorVerdict[] = []
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const record = entry as { seq?: unknown, expired?: unknown }
+    if (typeof record.seq !== 'number' || typeof record.expired !== 'boolean') continue
+    verdicts.push({ seq: record.seq, expired: record.expired })
+  }
+  return verdicts
+}
+
+/**
+ * Parse the estimator answer including the optional session-level
+ * `expectedRemainingTurns`. Accepts both the legacy bare verdict array and the
+ * extended object form; anything malformed yields no verdicts and no Ŝ.
+ */
+export function parseEstimatorAnswerDetailed(text: string): EstimatorAnswer {
+  const objectStart = text.indexOf('{')
+  const objectEnd = text.lastIndexOf('}')
+  if (objectStart >= 0 && objectEnd > objectStart) {
+    try {
+      const parsed: unknown = JSON.parse(text.slice(objectStart, objectEnd + 1))
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        const record = parsed as { expectedRemainingTurns?: unknown, verdicts?: unknown, items?: unknown }
+        const verdicts = parseVerdictArray(record.verdicts ?? record.items)
+        if (verdicts.length > 0) {
+          const turns = record.expectedRemainingTurns
+          if (typeof turns === 'number' && Number.isFinite(turns) && turns >= 0) {
+            return { verdicts, expectedRemainingTurns: Math.floor(turns) }
+          }
+          return { verdicts }
+        }
+      }
+    } catch {
+      // Fall through to the legacy array extraction.
+    }
+  }
   const start = text.indexOf('[')
   const end = text.lastIndexOf(']')
-  if (start < 0 || end <= start) return []
+  if (start < 0 || end <= start) return { verdicts: [] }
   try {
     const parsed: unknown = JSON.parse(text.slice(start, end + 1))
-    if (!Array.isArray(parsed)) return []
-    const verdicts: EstimatorVerdict[] = []
-    for (const entry of parsed) {
-      if (typeof entry !== 'object' || entry === null) continue
-      const record = entry as { seq?: unknown, expired?: unknown }
-      if (typeof record.seq !== 'number' || typeof record.expired !== 'boolean') continue
-      verdicts.push({ seq: record.seq, expired: record.expired })
-    }
-    return verdicts
+    return { verdicts: parseVerdictArray(parsed) }
   } catch {
-    return []
+    return { verdicts: [] }
   }
 }
 
+/** Parse the estimator verdicts; the optional Ŝ rides on the Detailed variant. */
+export function parseEstimatorAnswer(text: string): EstimatorVerdict[] {
+  return parseEstimatorAnswerDetailed(text).verdicts
+}
+
 /** One channel-bound estimator. `ask` resolves undefined on any failure. */
 export class Estimator {
   constructor(

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

@@ -0,0 +1,223 @@
+/**
+ * TokenPilot-inspired R4: benefit model for the human-gated review pipeline.
+ *
+ * Pure functions only: the classifier needs no I/O, no session state, and no
+ * host services, so every decision is unit-testable and audit-replayable.
+ *
+ * The cost model follows the TokenPilot paper's cache-accounting view: one
+ * merged mutation pays a one-time tail KV-cache refill penalty of
+ * `(1−α)·tailTokens`, and every later turn recovers the reclaimed tokens at
+ * the cache-hit discount `α`:
+ *
+ * ```
+ * R              = Σ(tokensBefore − tokensAfter)   // net reclaimed tokens
+ * paybackTurns   = (1−α)·tailTokens / (α·R)        // one-time refill / per-turn saving
+ * expectedSaving = α·R·max(0, Ŝ − paybackTurns)    // Ŝ = estimated remaining turns
+ * ```
+ *
+ * `expectedSaving` is only produced when Ŝ is known (the estimator answered
+ * with `expectedRemainingTurns`); it is never fabricated from a guess.
+ */
+import { createHash } from 'node:crypto'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { dedupeHash, flattenPlainText } from './dedup.ts'
+
+/** The minimal per-candidate face the benefit model consumes. */
+export interface BenefitCandidate {
+  readonly sourceSeq: number
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+}
+
+export interface BenefitInput {
+  /** Cache-hit discount rate α ∈ (0,1); validated upstream by config parsing. */
+  readonly alpha: number
+  /** Token mass of the protected tail that must be refilled after a mutation. */
+  readonly tailTokens: number
+  /** Estimated remaining turns Ŝ; `undefined` keeps expectedSaving out of the result. */
+  readonly remainingTurns?: number | undefined
+}
+
+export interface BenefitEstimate {
+  /** Net reclaimed tokens across the batch; may be ≤ 0 when a batch is not worth it. */
+  readonly recoveredTokens: number
+  /** The one-time cache-refill penalty the merged mutation pays: (1−α)·tailTokens. */
+  readonly penaltyTokens: number
+  /** Turns of discounted recovery needed to recoup the penalty; `undefined` when α·R ≤ 0. */
+  readonly paybackTurns?: number
+  /** Discounted net benefit over the remaining session; omitted when Ŝ is unknown. */
+  readonly expectedSaving?: number
+}
+
+/**
+ * Aggregate the batch-level benefit of a set of reduction candidates.
+ *
+ * Individual candidates whose replacement would grow the context contribute
+ * zero recovery (they never make a batch look better than dropping them).
+ */
+export function computeBenefit(candidates: readonly BenefitCandidate[], input: BenefitInput): BenefitEstimate {
+  const { alpha, tailTokens, remainingTurns } = input
+  let recoveredTokens = 0
+  for (const candidate of candidates) {
+    recoveredTokens += Math.max(0, candidate.tokensBefore - candidate.tokensAfter)
+  }
+  const penaltyTokens = (1 - alpha) * tailTokens
+  const perTurnSaving = alpha * recoveredTokens
+  if (perTurnSaving <= 0) {
+    return remainingTurns === undefined
+      ? { recoveredTokens, penaltyTokens }
+      : { recoveredTokens, penaltyTokens, expectedSaving: -penaltyTokens }
+  }
+  const paybackTurns = penaltyTokens / perTurnSaving
+  if (remainingTurns === undefined) {
+    return { recoveredTokens, penaltyTokens, paybackTurns }
+  }
+  return {
+    recoveredTokens,
+    penaltyTokens,
+    paybackTurns,
+    expectedSaving: perTurnSaving * Math.max(0, remainingTurns - paybackTurns),
+  }
+}
+
+/**
+ * Stable proposal identity: the sha-256 of the serialized item digests, cut to
+ * 12 hex chars. Stable across re-enqueues of the same content so a repeated
+ * classification cannot duplicate a pending proposal.
+ */
+export function proposalId(itemDigests: readonly string[]): string {
+  const hash = createHash('sha256')
+  for (const digest of itemDigests) hash.update(digest)
+  hash.update(String(itemDigests.length))
+  return hash.digest('hex').slice(0, 12)
+}
+
+/** Human-facing reduction kind carried by every review proposal. */
+export type ProposalKind = 'estimator' | 'dedup' | 'read-state'
+
+/** The minimal candidate face the triage classifier consumes. */
+export interface ClassifiableCandidate {
+  readonly sourceSeq: number
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  /** Compression primitive that planned this replacement. */
+  readonly component: string
+  /** Reducer id (`dedupe-pointer`, `superseded-read-whole-result`, …). */
+  readonly reducer: string
+  /** Content to freeze into the proposal digest. */
+  readonly content: readonly ContentBlock[]
+}
+
+export interface TriageInput {
+  /** Cache-hit discount rate α ∈ (0,1); validated upstream by config parsing. */
+  readonly alpha: number
+  /** Token mass of the protected tail that must be refilled after a mutation. */
+  readonly tailTokens: number
+  /** Candidates at or above this token impact skip triage and always enter review. */
+  readonly reviewHighImpactTokens: number
+  /** Estimated remaining turns Ŝ; `undefined` keeps the edge band closed. */
+  readonly remainingTurns?: number | undefined
+  /** Seqs whose reduction came from the estimator channel; overrides the kind. */
+  readonly estimatorSeqs?: ReadonlySet<number> | undefined
+}
+
+/** One frozen item inside a review proposal: metadata and digest, never content. */
+export interface ProposalItem {
+  readonly seq: number
+  readonly component: string
+  readonly kind: ProposalKind
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  /** Content sha-256 frozen at enqueue time and re-checked at the apply point. */
+  readonly digest: string
+}
+
+/** Proposal fields derivable at classification time; queue fields attach at enqueue. */
+export interface ProposalSkeleton {
+  readonly id: string
+  readonly kind: ProposalKind
+  readonly items: readonly ProposalItem[]
+  readonly benefit: BenefitEstimate
+}
+
+export interface ClassificationResult {
+  /** Clearly profitable candidates that keep the existing automatic path. */
+  readonly auto: readonly ClassifiableCandidate[]
+  /** Edge-band or high-impact candidates folded into review proposal skeletons. */
+  readonly review: readonly ProposalSkeleton[]
+  /** Negative-benefit candidates the pipeline keeps discarding. */
+  readonly drop: readonly ClassifiableCandidate[]
+}
+
+/**
+ * Canonical content digest reused from the dedup hash: plain-text results hash
+ * through the dedupe canonicalization; rich blocks fall back to canonical JSON
+ * so every candidate is freezable.
+ */
+export function contentDigest(content: readonly ContentBlock[]): string {
+  const text = flattenPlainText(content)
+  return dedupeHash(text ?? JSON.stringify(content), 'trim-eol')
+}
+
+function proposalKindFor(candidate: ClassifiableCandidate, estimatorSeqs: ReadonlySet<number> | undefined): ProposalKind {
+  if (estimatorSeqs?.has(candidate.sourceSeq) === true) return 'estimator'
+  if (candidate.reducer === 'dedupe-pointer') return 'dedup'
+  return 'read-state'
+}
+
+/**
+ * Triage planned replacements into the three review-mode buckets.
+ *
+ * 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);
+ * - `paybackTurns ≤ 1`, or Ŝ known and `paybackTurns ≤ 0.25·Ŝ` → auto;
+ * - Ŝ known and `paybackTurns ∈ (1, 3]` → review;
+ * - everything else (Ŝ unknown with a slow payback) → drop.
+ */
+export function classifyCandidates(
+  candidates: readonly ClassifiableCandidate[],
+  input: TriageInput,
+): ClassificationResult {
+  const auto: ClassifiableCandidate[] = []
+  const review: ProposalSkeleton[] = []
+  const drop: ClassifiableCandidate[] = []
+  for (const candidate of candidates) {
+    const benefit = computeBenefit([candidate], input)
+    if (benefit.recoveredTokens <= 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
+      }
+    }
+    const item: ProposalItem = {
+      seq: candidate.sourceSeq,
+      component: candidate.component,
+      kind: proposalKindFor(candidate, input.estimatorSeqs),
+      tokensBefore: candidate.tokensBefore,
+      tokensAfter: candidate.tokensAfter,
+      digest: contentDigest(candidate.content),
+    }
+    review.push({
+      id: proposalId([item.digest]),
+      kind: item.kind,
+      items: [item],
+      benefit,
+    })
+  }
+  return { auto, review, drop }
+}

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

@@ -0,0 +1,231 @@
+/**
+ * TokenPilot-inspired R4: the human-gated review queue.
+ *
+ * One durable session record per session holds every live proposal (pending or
+ * approved). Records carry metadata only — ids, seqs, digests, token counts,
+ * statuses, and reason codes — never message content, mirroring the upstream
+ * Cleaner persistence rule. The store face is a minimal KV pair so the queue
+ * is host-agnostic: the runtime wiring attempts the `storageDomain` seam and
+ * degrades to an in-memory Map (restart-lossy, acceptable for a short-lived
+ * pending queue) whenever the seam is absent or fails.
+ *
+ * The human-side status set is `pending / approved / rejected / ignored /
+ * expired`, orthogonal to the execution-side receipt states
+ * (`applied / deferred`) recorded when an approved batch actually lands.
+ */
+import type { ProposalKind, ProposalSkeleton } from './proposal.ts'
+
+/** Human-side proposal status. */
+export type ReviewProposalStatus = 'pending' | 'approved' | 'rejected' | 'ignored' | 'expired'
+
+/** Execution-side receipt built only from real mutation evidence (never estimated). */
+export interface ReviewReceipt {
+  readonly status: 'applied' | 'deferred'
+  /** Reason code for deferred receipts, aligned with the upstream naming. */
+  readonly reasonCode?: string
+  /** Predicted recovery from the benefit model at enqueue time. */
+  readonly estimatedTokens: number
+  /** Measured recovery of the landed mutation; present only on applied. */
+  readonly appliedTokens?: number
+  /** Canonical ISO timestamp of the execution evidence. */
+  readonly updatedAt: string
+}
+
+/** One queued proposal: persisted metadata, never content. */
+export interface ReviewProposalRecord {
+  readonly id: string
+  readonly sessionId: string
+  readonly kind: ProposalKind
+  readonly items: readonly {
+    readonly seq: number
+    readonly component: string
+    readonly kind: ProposalKind
+    readonly tokensBefore: number
+    readonly tokensAfter: number
+    readonly digest: string
+  }[]
+  readonly benefit: {
+    readonly recoveredTokens: number
+    readonly penaltyTokens: number
+    readonly paybackTurns?: number
+    readonly expectedSaving?: number
+  }
+  status: ReviewProposalStatus
+  readonly enqueuedTurn: number
+  lastTurnIndex: number
+}
+
+/** Whole-session record: one durable KV value per session. */
+export interface ReviewSessionRecord {
+  readonly version: 1
+  readonly proposals: readonly ReviewProposalRecord[]
+}
+
+/** A settled proposal: the live record plus its execution receipt. */
+export interface ReviewReceiptRecord extends ReviewProposalRecord {
+  readonly receipt: ReviewReceipt
+}
+
+/** Minimal KV face the queue persists through. */
+export interface ReviewQueueStore {
+  load(sessionId: string): ReviewSessionRecord | undefined
+  save(sessionId: string, record: ReviewSessionRecord): void
+  /** Session ids with live records; optional (aggregate reads degrade to none). */
+  ids?(): readonly string[]
+}
+
+/** In-memory store: the fail-open fallback when no durable seam is available. */
+export class MemoryReviewStore implements ReviewQueueStore {
+  private readonly sessions = new Map<string, ReviewSessionRecord>()
+
+  load(sessionId: string): ReviewSessionRecord | undefined {
+    return this.sessions.get(sessionId)
+  }
+
+  save(sessionId: string, record: ReviewSessionRecord): void {
+    this.sessions.set(sessionId, record)
+  }
+
+  ids(): readonly string[] {
+    return [...this.sessions.keys()]
+  }
+}
+
+export interface ReviewQueueOptions {
+  /** Pending proposals older than this many turns (since lastTurnIndex) expire. */
+  readonly timeoutTurns: number
+}
+
+/** Decision outcomes for one decide call. */
+export type DecideOutcome =
+  | { readonly ok: true }
+  | { readonly ok: false, readonly reason: 'unknown-proposal' | 'not-pending' }
+
+export class ReviewQueue {
+  constructor(
+    private readonly store: ReviewQueueStore,
+    private readonly options: ReviewQueueOptions,
+  ) {}
+
+  /**
+   * Fail-open store access: a throwing seam must never break the compression
+   * pipeline. Reads degrade to "no stored record"; writes degrade to losing
+   * durability for that call (the store itself is expected to warn).
+   */
+  private safeLoad(sessionId: string): ReviewSessionRecord | undefined {
+    try {
+      return this.store.load(sessionId)
+    } catch {
+      return undefined
+    }
+  }
+
+  private safeSave(sessionId: string, record: ReviewSessionRecord): void {
+    try {
+      this.store.save(sessionId, record)
+    } catch {
+      // Durability lost for this write; the queue stays functional in memory.
+    }
+  }
+
+  private sessionRecord(sessionId: string): ReviewSessionRecord {
+    return this.safeLoad(sessionId) ?? { version: 1, proposals: [] }
+  }
+
+  /**
+   * Queue one classified proposal. A repeated classification of the same
+   * content re-does nothing but refresh the patience clock, so re-enqueue
+   * cannot duplicate a live proposal.
+   * @returns `false` when an identical live proposal already exists.
+   */
+  enqueue(sessionId: string, skeleton: ProposalSkeleton, turnIndex: number): boolean {
+    const record = this.sessionRecord(sessionId)
+    const existing = record.proposals.find(entry => entry.id === skeleton.id)
+    if (existing !== undefined && existing.status !== 'expired') {
+      existing.lastTurnIndex = turnIndex
+      this.safeSave(sessionId, record)
+      return false
+    }
+    const proposal: ReviewProposalRecord = {
+      id: skeleton.id,
+      sessionId,
+      kind: skeleton.kind,
+      items: skeleton.items.map(item => ({ ...item })),
+      benefit: { ...skeleton.benefit },
+      status: 'pending',
+      enqueuedTurn: turnIndex,
+      lastTurnIndex: turnIndex,
+    }
+    this.safeSave(sessionId, {
+      version: 1,
+      // Expired duplicates are dropped: the fresh skeleton re-enters as pending.
+      proposals: [...record.proposals.filter(entry => entry.id !== skeleton.id), proposal],
+    })
+    return true
+  }
+
+  /** Live pending proposals of one session, oldest enqueue first. */
+  listPending(sessionId: string): readonly ReviewProposalRecord[] {
+    return this.sessionRecord(sessionId).proposals
+      .filter(entry => entry.status === 'pending')
+      .sort((left, right) => left.enqueuedTurn - right.enqueuedTurn)
+  }
+
+  /** Approved proposals waiting for the next turn-boundary batch. */
+  listApproved(sessionId: string): readonly ReviewProposalRecord[] {
+    return this.sessionRecord(sessionId).proposals
+      .filter(entry => entry.status === 'approved')
+      .sort((left, right) => left.enqueuedTurn - right.enqueuedTurn)
+  }
+
+  /**
+   * Transition one pending proposal. Idempotent: deciding an unknown id or a
+   * non-pending proposal changes nothing and reports the miss.
+   */
+  decide(sessionId: string, id: string, decision: 'approved' | 'rejected' | 'ignored'): DecideOutcome {
+    const record = this.sessionRecord(sessionId)
+    const proposal = record.proposals.find(entry => entry.id === id)
+    if (proposal === undefined) return { ok: false, reason: 'unknown-proposal' }
+    if (proposal.status !== 'pending') return { ok: false, reason: 'not-pending' }
+    proposal.status = decision
+    this.safeSave(sessionId, record)
+    return { ok: true }
+  }
+
+  /**
+   * Expire every pending proposal whose patience has run out at this turn
+   * boundary. Expired proposals are removed from the store (the summary view
+   * aggregates them from the audit log instead).
+   * @returns the expired proposals, for the caller's audit emission.
+   */
+  expireTurn(sessionId: string, turnIndex: number): readonly ReviewProposalRecord[] {
+    const record = this.sessionRecord(sessionId)
+    const keep: ReviewProposalRecord[] = []
+    const expired: ReviewProposalRecord[] = []
+    for (const proposal of record.proposals) {
+      if (proposal.status === 'pending' && turnIndex - proposal.lastTurnIndex > this.options.timeoutTurns) {
+        expired.push({ ...proposal, status: 'expired' })
+        continue
+      }
+      keep.push(proposal)
+    }
+    if (expired.length > 0) this.safeSave(sessionId, { version: 1, proposals: keep })
+    return expired
+  }
+
+  /**
+   * Settle an approved proposal with its execution receipt and retire it from
+   * the live store. The caller is responsible for auditing the receipt; the
+   * queue only records which proposal left and why.
+   */
+  recordReceipt(sessionId: string, id: string, receipt: ReviewReceipt): ReviewReceiptRecord | undefined {
+    const record = this.sessionRecord(sessionId)
+    const proposal = record.proposals.find(entry => entry.id === id)
+    if (proposal === undefined || proposal.status !== 'approved') return undefined
+    this.safeSave(sessionId, {
+      version: 1,
+      proposals: record.proposals.filter(entry => entry.id !== id),
+    })
+    return { ...proposal, receipt }
+  }
+}

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

@@ -0,0 +1,122 @@
+/**
+ * TokenPilot-inspired R4: the storageDomain adapter for the review queue.
+ *
+ * The `storageDomain` seam is resolved OPTIONALLY at runtime (`ctx.get`), never
+ * declared as a hard plugin inject: a host without storage backends must load
+ * the plugin anyway and serve the review queue from its in-memory fallback.
+ * Any open failure degrades the same way — the caller receives `undefined` and
+ * logs one warning.
+ *
+ * The domain spec is a plain structural object with a hand-rolled `safeParse`
+ * validator, so the plugin carries no runtime dependency on
+ * `@deepseek-ai/dsh-storage-domain` (or on a compatible zod instance); hosts
+ * that reject the structural spec simply fall into the same degrade path.
+ */
+import type { ReviewQueueStore, ReviewSessionRecord } from './review-queue.ts'
+
+/** Domain name — `UNIT_NAME_RE` (`/^[a-z][a-z0-9_]*$/`) allows no hyphens. */
+export const REVIEW_STORAGE_DOMAIN = 'context_compression_review'
+
+/** The one declared table: one record per session id. */
+export const REVIEW_STORAGE_TABLE = 'sessions'
+
+/** Minimal structural face of one opened domain table (sync reads, durable writes). */
+interface ReviewStorageTableLike {
+  get(key: string): unknown
+  put(key: string, value: unknown): Promise<void>
+  keys(): IterableIterator<string>
+}
+
+/** Minimal structural face of the `storageDomain` service. */
+interface StorageDomainServiceLike {
+  open(spec: unknown): Promise<{ table(name: string): ReviewStorageTableLike }>
+}
+
+/** Structural validator: accepts exactly the shape this module persists. */
+function reviewSessionRecordValidator(): { safeParse(value: unknown): { success: boolean, data?: ReviewSessionRecord } } {
+  return {
+    safeParse(value: unknown): { success: boolean, data?: ReviewSessionRecord } {
+      if (typeof value !== 'object' || value === null) return { success: false }
+      const record = value as { version?: unknown, proposals?: unknown }
+      if (record.version !== 1 || !Array.isArray(record.proposals)) return { success: false }
+      for (const proposal of record.proposals) {
+        if (typeof proposal !== 'object' || proposal === null) return { success: false }
+        const entry = proposal as {
+          id?: unknown, sessionId?: unknown, kind?: unknown, status?: unknown,
+          items?: unknown, benefit?: unknown, enqueuedTurn?: unknown, lastTurnIndex?: unknown,
+        }
+        if (typeof entry.id !== 'string' || typeof entry.sessionId !== 'string') return { success: false }
+        if (entry.kind !== 'estimator' && entry.kind !== 'dedup' && entry.kind !== 'read-state') {
+          return { success: false }
+        }
+        if (entry.status !== 'pending' && entry.status !== 'approved') return { success: false }
+        if (!Number.isSafeInteger(entry.enqueuedTurn) || !Number.isSafeInteger(entry.lastTurnIndex)) {
+          return { success: false }
+        }
+        if (!Array.isArray(entry.items) || typeof entry.benefit !== 'object' || entry.benefit === null) {
+          return { success: false }
+        }
+        for (const item of entry.items) {
+          if (typeof item !== 'object' || item === null) return { success: false }
+          const one = item as { seq?: unknown, digest?: unknown }
+          if (!Number.isSafeInteger(one.seq) || typeof one.digest !== 'string') return { success: false }
+        }
+      }
+      return { success: true, data: value as ReviewSessionRecord }
+    },
+  }
+}
+
+function reviewStorageSpec(): unknown {
+  return {
+    name: REVIEW_STORAGE_DOMAIN,
+    version: 1,
+    layout: 'per-record',
+    tables: {
+      [REVIEW_STORAGE_TABLE]: { valueSchema: reviewSessionRecordValidator() },
+    },
+  }
+}
+
+/** Adapter presenting the sync KV face the queue expects over the domain table. */
+class StorageDomainReviewStore implements ReviewQueueStore {
+  constructor(private readonly table: ReviewStorageTableLike) {}
+
+  load(sessionId: string): ReviewSessionRecord | undefined {
+    const value = this.table.get(sessionId)
+    return typeof value === 'object' && value !== null ? value as ReviewSessionRecord : undefined
+  }
+
+  save(sessionId: string, record: ReviewSessionRecord): void {
+    // Durability is fire-and-forget: the domain's write chain lands the record
+    // while the queue proceeds; failures are logged by the host backend and
+    // the in-memory state still serves reads.
+    void this.table.put(sessionId, record).catch(() => undefined)
+  }
+
+  ids(): readonly string[] {
+    return [...this.table.keys()]
+  }
+}
+
+/**
+ * Attempt to open the review storage domain through the optional
+ * `storageDomain` seam.
+ * @param getService - resolved once with the seam name; `undefined` means the
+ * host lacks the service.
+ * @returns the durable store, or `undefined` when the seam is absent or fails
+ * (the caller falls back to the in-memory store and logs one warning).
+ */
+export async function openReviewStorage(
+  getService: (name: string) => unknown,
+): Promise<ReviewQueueStore | undefined> {
+  let service: unknown
+  try {
+    service = getService('storageDomain')
+  } catch {
+    return undefined
+  }
+  if (service === undefined || service === null) return undefined
+  const domain = await (service as StorageDomainServiceLike).open(reviewStorageSpec())
+  return new StorageDomainReviewStore(domain.table(REVIEW_STORAGE_TABLE))
+}