dsh-context-compression-improved 0.5.1 → 0.5.3

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

@@ -1,231 +0,0 @@
-/**
- * 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-registry.ts

@@ -1,117 +0,0 @@
-/**
- * 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/review-storage.ts

@@ -1,122 +0,0 @@
-/**
- * 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))
-}

package/packages/selector/tests/review-overlay.client.spec.tsx

@@ -1,118 +0,0 @@
-// @vitest-environment jsdom
-
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { ReviewOverlay } from '../src/client/ReviewOverlay.tsx'
-import type { SettingsScopeLike } from '../src/client/review-scope.ts'
-
-afterEach(() => {
-  cleanup()
-  vi.unstubAllGlobals()
-})
-
-const QUEUE_ROUTE = '/api/dsh-context-compression-improved/review-queue'
-const DECIDE_ROUTE = '/api/dsh-context-compression-improved/review-decide'
-
-const PROPOSAL = {
-  sessionId: 's1',
-  id: 'abc123def456',
-  kind: 'read-state',
-  items: [{ seq: 6, tokensBefore: 2401, tokensAfter: 134 }],
-  benefit: { recoveredTokens: 400, paybackTurns: 2.25, expectedSaving: 312 },
-}
-
-function scopeStub(reviewMode: boolean): SettingsScopeLike {
-  return {
-    getSnapshot: () => ({
-      status: 'ready',
-      value: { presetOptions: { reviewMode } },
-    }),
-    subscribe: () => () => {},
-  }
-}
-
-type FetchCall = { input: string | URL | Request, init?: RequestInit | undefined }
-
-function stubFetch(responses: Array<{ match: (input: string) => boolean, body: unknown, status?: number }>): {
-  calls: FetchCall[]
-} {
-  const calls: FetchCall[] = []
-  vi.stubGlobal('fetch', vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
-    calls.push({ input, init })
-    const url = String(input)
-    const match = responses.find(entry => entry.match(url))
-    return {
-      ok: (match?.status ?? 200) < 400,
-      status: match?.status ?? 200,
-      json: async () => match?.body,
-    } as Response
-  }))
-  return { calls }
-}
-
-const queueBody = {
-  ok: true,
-  total: 1,
-  pending: [PROPOSAL],
-  summary: { autoApplied: 2, reviewApplied: 1, expired: 3, voided: 0 },
-}
-
-describe('review overlay (client)', () => {
-  it('renders the pending list and the four-state summary row', async () => {
-    stubFetch([{ match: url => url.includes(QUEUE_ROUTE), body: queueBody }])
-    render(<ReviewOverlay scope={scopeStub(true)} t={key => key} />)
-
-    await waitFor(() => { expect(screen.getByText('review.badge 1')).toBeDefined() })
-    fireEvent.click(screen.getByText('review.badge 1'))
-    expect(screen.getByText('review.title')).toBeDefined()
-    expect(screen.getByText(/review.summary.autoApplied: 2/)).toBeDefined()
-    expect(screen.getByText(/review.summary.expired: 3/)).toBeDefined()
-    // Estimated saving is labelled as an estimate.
-    expect(screen.getByText(/review.row.estimated/)).toBeDefined()
-  })
-
-  it('posts the three decisions through the decide route and refreshes', async () => {
-    const { calls } = stubFetch([
-      { match: url => url.includes(QUEUE_ROUTE), body: queueBody },
-      { match: url => url.includes(DECIDE_ROUTE), body: { ok: true } },
-    ])
-    render(<ReviewOverlay scope={scopeStub(true)} t={key => key} />)
-    await waitFor(() => { expect(screen.getByText('review.badge 1')).toBeDefined() })
-    fireEvent.click(screen.getByText('review.badge 1'))
-
-    fireEvent.click(screen.getByText('review.action.approve'))
-    await waitFor(() => {
-      expect(calls.some(call => String(call.input) === DECIDE_ROUTE && call.init?.method === 'POST')).toBe(true)
-    })
-    const posted = JSON.parse(String(calls.find(call => call.init?.method === 'POST')?.init?.body))
-    expect(posted).toEqual({ sessionId: 's1', proposalId: 'abc123def456', decision: 'approved' })
-
-    fireEvent.click(screen.getByText('review.action.reject'))
-    await waitFor(() => {
-      expect(calls.some(call => String(call.input) === DECIDE_ROUTE
-        && JSON.parse(String(call.init?.body)).decision === 'rejected')).toBe(true)
-    })
-    fireEvent.click(screen.getByText('review.action.ignore'))
-    await waitFor(() => {
-      expect(calls.some(call => String(call.input) === DECIDE_ROUTE
-        && JSON.parse(String(call.init?.body)).decision === 'ignored')).toBe(true)
-    })
-  })
-
-  it('renders nothing while nothing is pending', async () => {
-    stubFetch([{ match: url => url.includes(QUEUE_ROUTE), body: { ok: true, total: 0, pending: [] } }])
-    const { container } = render(<ReviewOverlay scope={scopeStub(true)} t={key => key} />)
-    await waitFor(() => {
-      expect((container.querySelector('.dsh-cc-review-badge'))).toBeNull()
-    })
-  })
-
-  it('renders nothing while review mode is off', async () => {
-    const fetchMock = vi.fn()
-    vi.stubGlobal('fetch', fetchMock)
-    const { container } = render(<ReviewOverlay scope={scopeStub(false)} t={key => key} />)
-    await new Promise(resolve => setTimeout(resolve, 30))
-    expect(container.querySelector('.dsh-cc-review-badge')).toBeNull()
-    expect(fetchMock).not.toHaveBeenCalled()
-  })
-})