dsh-retrace 0.3.0

package/lib/projection/versions.js

@@ -0,0 +1,69 @@
+/**
+ * dsh-retrace — `retrace/versions` projection unit definition.
+ *
+ * Registered on the official `ctx.sessionProjections` registry
+ * (`@deepseek-ai/dsh-session-projection`), per PLAN.md §4.1. The framework
+ * owns the single `session/event` subscription, the per-session watermark
+ * cache, checkpoint persistence (`dsh-session-projection-cache`) and cold
+ * reads; this unit contributes only the pure state machine:
+ *
+ *   - `init`   — empty fold state (see lib/version-index.js),
+ *   - `apply`  — deterministic fold over one committed event (same reference
+ *                when nothing changed — `Object.is` gates the change feed),
+ *   - `view`   — the client-visible wire value (version list summary served
+ *                in `session/projection` push frames and `snapshot()`).
+ *
+ * The unit schema validates the VIEW value (the registry parses `view(state)`
+ * before serving); the raw fold state is plain JSON so the projection cache
+ * can persist it (`z.json()` at the durable boundary).
+ */
+import { z } from 'zod'
+import {
+  VERSION_LIMIT,
+  applyVersionIndex,
+  createVersionIndexState,
+  viewVersionIndex,
+} from '../version-index.js'
+
+const VERSION_KINDS = ['recall', 'edit', 'regenerate', 'restore', 'compaction', 'replace']
+const FILE_MODES = ['created', 'modified', 'deleted']
+
+const fileChangeSchema = z.object({
+  path: z.string(),
+  mode: z.enum(FILE_MODES),
+})
+
+const versionSummarySchema = z.object({
+  versionId: z.string(),
+  boundarySeq: z.number().int().nonnegative(),
+  createdAt: z.number().int().nonnegative(),
+  kind: z.enum(VERSION_KINDS),
+  markerText: z.string(),
+  messageCount: z.number().int().nonnegative(),
+  fileCounts: z.object({
+    created: z.number().int().nonnegative(),
+    modified: z.number().int().nonnegative(),
+    deleted: z.number().int().nonnegative(),
+  }),
+  touchedFiles: z.array(fileChangeSchema),
+  git: z.null(),
+})
+
+/** The wire view schema (what the registry validates and clients receive). */
+export const versionsViewSchema = z.object({
+  versions: z.array(versionSummarySchema).max(VERSION_LIMIT),
+})
+
+/**
+ * The `retrace/versions` unit — register via
+ * `ctx.sessionProjections.register(versionsProjectionDefinition)`.
+ */
+export const versionsProjectionDefinition = {
+  key: 'retrace/versions',
+  schema: versionsViewSchema,
+  init: () => createVersionIndexState(),
+  apply: (state, event) => applyVersionIndex(state, event),
+  view: (state) => viewVersionIndex(state),
+  /** Bump when the serialized fold state or fold semantics change. */
+  stateVersion: 1,
+}

package/lib/types/client.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Client entry type stub. The client half is plain ESM importing React and
+ * registering `slots`, `locale` and `conversationEvents` services.
+ */
+export const name: 'dsh-retrace'
+export const inject: string[]
+export function apply(ctx: unknown): void
+
+/**
+ * Swap the transport the client uses to reach the Host. The published client
+ * defaults to the same-origin HTTP route; the generated dynamic client
+ * (scripts/generate-dynamic.mjs) installs a `host.call` wire before apply.
+ */
+export function __setMessageEditorWire(fn: ((op: string, payload: unknown) => Promise<unknown>) | null): void

package/lib/types/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * dsh-retrace type surface.
+ * The runtime implementation is dependency-free plain ESM; these types describe
+ * the public entry points for TypeScript consumers.
+ */
+
+export interface EditorOpFailure {
+  ok: false
+  error: { code: string; message: string }
+}
+
+export interface RecallResult {
+  op: 'recall'
+  messageId: string
+  seq: number
+  markerSeq: number
+  shadowed: number
+  /** Durable text of the recalled message (echoed into the composer). */
+  text: string
+}
+
+export interface EditResult {
+  op: 'edit'
+  messageId: string
+  seq: number
+  markerSeq: number
+  shadowed: number
+  resendMessageId: string
+  text: string
+  originalText: string
+  fromScratch: boolean
+}
+
+export interface RegenerateResult {
+  op: 'regenerate'
+  messageId: string
+  seq: number
+  markerSeq: number
+  shadowed: number
+  resendMessageId: string
+}
+
+export type EditorOpResult =
+  | { ok: true; value: RecallResult }
+  | { ok: true; value: EditResult }
+  | { ok: true; value: RegenerateResult }
+
+export type EditorOpResponse = EditorOpResult | EditorOpFailure
+
+export interface RecallArgs {
+  sessionId: string
+  messageId: string
+}
+
+export interface EditAndResendArgs extends RecallArgs {
+  text: string
+  /** Rewind the whole surface first (new-conversation semantics). */
+  fromScratch?: boolean
+}
+
+export interface EditorApi {
+  recall(args: RecallArgs): Promise<EditorOpResponse>
+  editAndResend(args: EditAndResendArgs): Promise<EditorOpResponse>
+  regenerate(args: RecallArgs): Promise<EditorOpResponse>
+}

package/lib/version-index.js

@@ -0,0 +1,310 @@
+/**
+ * dsh-retrace — Version index fold (pure, zero imports).
+ *
+ * Rewritten per PLAN.md v0.3 (2026-08-20 revision): the old "hand-written
+ * VersionIndex service + custom jsonl index" design is scrapped. This module
+ * is the pure fold consumed by the official `ctx.sessionProjections`
+ * projection unit (lib/projection/versions.js) — the framework owns the
+ * session/event subscription, the per-session watermark cache, checkpoint
+ * persistence and cold-read restore; this file owns only deterministic state
+ * transitions over one session's committed events.
+ *
+ * Boundary semantics mirror the official surface fold (`foldSurface` in
+ * `@deepseek-ai/dsh-session/surface`): an append pushes the event seq onto
+ * the surface; a replace splices [start..end] out and inserts the
+ * replacement's own seq. Every replacement event closes a "version" — our
+ * markers (recall / edit / regenerate / restore), compaction checkpoints, or
+ * any other future surface replacer. Between two boundaries the fold also
+ * accumulates the session's touched files (parsing tool calls and tool
+ * results), so each version records what artifacts changed in its window.
+ *
+ * The state is plain JSON only (arrays, no Set/Map) so the projection cache
+ * can persist it verbatim (`dsh-session-projection-cache` validates rows
+ * with `z.json()`).
+ */
+
+export const MARKER_ID_PREFIX = 'retrace'
+
+/** Timeline keeps the most recent N versions; full history stays replayable from the log. */
+export const VERSION_LIMIT = 200
+
+// ---------------------------------------------------------------------------
+// Official-equivalent predicates
+// ---------------------------------------------------------------------------
+// Semantics copied from the official contracts (not code) and locked by unit
+// tests, so this module stays import-free and runnable in every realm:
+//   isReplacementSurfaceEvent — @deepseek-ai/dsh-session/surface
+//   isCompactCheckpointSource — @deepseek-ai/dsh-compaction/checkpoint
+
+const SURFACE_EVENT_TYPES = new Set(['user/message', 'assistant/message', 'tool/result'])
+
+/** Whether an event is surface-eligible AND carries a surfaceOp marker. */
+export function isSurfaceEvent(event) {
+  return SURFACE_EVENT_TYPES.has(event?.type) && event.surfaceOp !== undefined
+}
+
+/** Whether an event shadowed an existing surface range (append is the only non-replacement). */
+export function isReplacementSurfaceEvent(event) {
+  return isSurfaceEvent(event) && event.surfaceOp !== 'append'
+}
+
+/** Whether a message source identifies a compaction checkpoint (`plugin: compact`). */
+export function isCompactCheckpointSource(source) {
+  return Boolean(source) && source.kind === 'plugin' && source.plugin === 'compact'
+}
+
+/** Map a marker event id prefix to a user-facing version kind. */
+export function kindFromMarkerId(id) {
+  if (typeof id !== 'string') return 'edit'
+  const prefix = `${MARKER_ID_PREFIX}-`
+  if (!id.startsWith(prefix)) return 'edit'
+  const op = id.slice(prefix.length).split('-')[0]
+  if (op === 'recall' || op === 'edit' || op === 'regenerate' || op === 'restore') return op
+  return 'edit'
+}
+
+/**
+ * Classify a replacement boundary event into a version kind.
+ * 1. our markers carry `data.editor` (assistant/message, id `retrace-<op>-…`);
+ * 2. compaction checkpoints are user/message with the `plugin: compact` source;
+ * 3. anything else is a generic `replace`.
+ */
+export function classifyBoundaryKind(event) {
+  if (event?.data?.editor) return kindFromMarkerId(event.data?.message?.id)
+  if (isCompactCheckpointSource(event?.data?.source)) return 'compaction'
+  return 'replace'
+}
+
+// ---------------------------------------------------------------------------
+// Touched-file extraction (pure)
+// ---------------------------------------------------------------------------
+
+/** Tool name → write intent. Unknown tools are ignored unless meta.path says otherwise. */
+const WRITE_TOOLS = /(?:^|\.)(fs\.(?:write|edit|create|append)|edit|patch|apply-patch)(?:$|\.)/i
+const DELETE_TOOLS = /(?:^|\.)(fs\.(?:remove|delete|rename)|rm|del)(?:$|\.)/i
+
+function classifyToolIntent(name) {
+  if (typeof name !== 'string') return null
+  if (DELETE_TOOLS.test(name)) return 'delete'
+  if (WRITE_TOOLS.test(name)) return 'write'
+  return null
+}
+
+/** Pull path-like strings out of a tool-call arguments JSON (best effort). */
+export function pathsFromToolCallArguments(name, argumentsJson) {
+  if (typeof argumentsJson !== 'string' || argumentsJson.length === 0) return []
+  let args
+  try {
+    args = JSON.parse(argumentsJson)
+  } catch {
+    return []
+  }
+  if (typeof args !== 'object' || args === null) return []
+  const found = new Set()
+  // Values under these keys are paths by contract — accepted even without a
+  // slash (`README.md`); free-floating strings elsewhere need a slash to be
+  // considered path-like (avoids capturing prose like "hello world").
+  const PATH_KEYS = new Set(['path', 'paths', 'file_path', 'filepath', 'cwd', 'dirname'])
+  const visit = (value, underPathKey) => {
+    if (typeof value === 'string') {
+      const looksLikePath = underPathKey
+        ? value.length > 0 && value !== '.' && value !== '..'
+        : value.includes('/') && value.length > 1
+      if (looksLikePath) found.add(value)
+      return
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, underPathKey)
+      return
+    }
+    if (typeof value === 'object' && value !== null) {
+      for (const key of Object.keys(value)) {
+        if (PATH_KEYS.has(key)) visit(value[key], true)
+        else if (typeof value[key] === 'object' && value[key] !== null) visit(value[key], underPathKey)
+      }
+    }
+  }
+  visit(args, false)
+  return [...found]
+}
+
+/**
+ * Parse one event's touched-file contribution.
+ * @returns {Array<{path: string, intent: 'write'|'delete'|'unknown'}>}
+ */
+export function touchedFilesFromEvent(event) {
+  if (!event) return []
+  const { type, data } = event
+  const out = []
+  if (type === 'tool/call' && data && typeof data.arguments === 'string') {
+    const intent = classifyToolIntent(data.name)
+    if (intent !== null) {
+      for (const path of pathsFromToolCallArguments(data.name, data.arguments)) {
+        out.push({ path, intent })
+      }
+    }
+  }
+  if (type === 'tool/result' && data) {
+    const failed = Boolean(data.error)
+    const metaPath = data.meta && typeof data.meta.path === 'string' ? data.meta.path : null
+    if (metaPath && !failed) out.push({ path: metaPath, intent: 'write' })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Version index fold
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} VersionFile
+ * @property {string} path        — canonical path relative to the session cwd.
+ * @property {'created'|'modified'|'deleted'} mode
+ */
+
+/**
+ * @typedef {object} VersionRecord
+ * @property {string} versionId          — `v<boundarySeq>`.
+ * @property {number} boundarySeq        — the replacement event's seq.
+ * @property {number} createdAt          — event time (ms), keeps the fold replayable.
+ * @property {'recall'|'edit'|'regenerate'|'restore'|'compaction'|'replace'} kind
+ * @property {string} markerText         — replaced-content summary (editor.text) or ''.
+ * @property {VersionFile[]} touchedFiles
+ * @property {number} messageCount       — surface node count at the boundary.
+ * @property {null} git                  — P1: { headHash, dirty, diffSha }.
+ */
+
+/** Create the empty per-session fold state (plain JSON only). */
+export function createVersionIndexState() {
+  return {
+    versions: [],
+    /** path → { intent, lastSeq } — files touched since the last boundary. */
+    windowFiles: {},
+    /** paths that appeared in any already-finalized version (for created/modified). */
+    knownFiles: [],
+    /** current surface node seqs (mirrors foldSurface). */
+    surface: [],
+  }
+}
+
+/** Map a window file entry to its version mode against the previous versions. */
+function fileMode(state, path, window) {
+  if (window.intent === 'delete') return 'deleted'
+  return state.knownFiles.includes(path) ? 'modified' : 'created'
+}
+
+function extractMarkerText(event, kind) {
+  if (kind === 'compaction') return ''
+  const text = event?.data?.editor?.text
+  return typeof text === 'string' ? text : ''
+}
+
+/** Close a version at a replacement boundary (window files frozen, window cleared). */
+function freezeVersion(state, event) {
+  const boundarySeq = event.seq
+  const kind = classifyBoundaryKind(event)
+  const files = Object.entries(state.windowFiles)
+    .map(([path, window]) => ({ path, mode: fileMode(state, path, window) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  const record = {
+    versionId: `v${boundarySeq}`,
+    boundarySeq,
+    createdAt: typeof event.time === 'number' ? event.time : 0,
+    kind,
+    markerText: extractMarkerText(event, kind),
+    touchedFiles: files,
+    messageCount: state.surface.length,
+    git: null,
+  }
+  const versions = [...state.versions, record]
+  if (versions.length > VERSION_LIMIT) versions.splice(0, versions.length - VERSION_LIMIT)
+  const knownFiles = [...state.knownFiles]
+  for (const file of files) {
+    if (!knownFiles.includes(file.path)) knownFiles.push(file.path)
+  }
+  return { versions, windowFiles: {}, knownFiles, surface: state.surface }
+}
+
+/**
+ * Fold one committed event into the version index state.
+ *
+ * Performance contract (load-bearing for the projection registry): when the
+ * event changes nothing — not surface, not files, not a boundary — the SAME
+ * state reference is returned (`Object.is` gates the change feed, so a new
+ * object means a downstream snapshot/push).
+ *
+ * @param {ReturnType<typeof createVersionIndexState>} state
+ * @param {object} event
+ * @returns the next state (same reference when nothing changed).
+ */
+export function applyVersionIndex(state, event) {
+  if (!event || typeof event.seq !== 'number') return state
+  let next = state
+
+  // 1. Surface fold (mirror foldSurface): append → push; replace → splice.
+  if (isSurfaceEvent(event)) {
+    const op = event.surfaceOp
+    if (op === 'append') {
+      next = { ...next, surface: [...next.surface, event.seq] }
+    } else if (op && op.op === 'replace') {
+      const startIdx = next.surface.indexOf(op.start)
+      const endIdx = next.surface.indexOf(op.end)
+      if (startIdx !== -1 && endIdx !== -1 && startIdx <= endIdx) {
+        const surface = next.surface.slice()
+        surface.splice(startIdx, endIdx - startIdx + 1, event.seq)
+        next = { ...next, surface }
+      }
+    }
+  }
+
+  // 2. Touched-file window.
+  const touched = touchedFilesFromEvent(event)
+  if (touched.length > 0) {
+    const windowFiles = { ...next.windowFiles }
+    for (const { path, intent } of touched) {
+      const prev = windowFiles[path]
+      if (!prev || event.seq > prev.lastSeq) windowFiles[path] = { intent, lastSeq: event.seq }
+    }
+    next = { ...next, windowFiles }
+  }
+
+  // 3. Version boundary.
+  if (isReplacementSurfaceEvent(event)) {
+    next = freezeVersion(next, event)
+  }
+
+  return next
+}
+
+/** Count file modes of one version's touched files (timeline badge input). */
+export function countFileModes(touchedFiles) {
+  const counts = { created: 0, modified: 0, deleted: 0 }
+  for (const file of touchedFiles) {
+    if (file.mode === 'created') counts.created += 1
+    else if (file.mode === 'modified') counts.modified += 1
+    else if (file.mode === 'deleted') counts.deleted += 1
+  }
+  return counts
+}
+
+/**
+ * The client-visible wire value (what `ctx.sessionProjections` serves in
+ * `session/projection` frames and `snapshot()`). Compact per-version summary
+ * plus the full touched-file list (the HTTP `/versions` route serves this
+ * same shape; rollback/detail reads files lazily in P1).
+ */
+export function viewVersionIndex(state) {
+  return {
+    versions: state.versions.map((record) => ({
+      versionId: record.versionId,
+      boundarySeq: record.boundarySeq,
+      createdAt: record.createdAt,
+      kind: record.kind,
+      markerText: record.markerText,
+      messageCount: record.messageCount,
+      fileCounts: countFileModes(record.touchedFiles),
+      touchedFiles: record.touchedFiles,
+      git: record.git,
+    })),
+  }
+}

package/lib/versioning.js

@@ -0,0 +1,193 @@
+/**
+ * dsh-retrace — the versioning seam: projection unit registration, artifact
+ * snapshot side effects, the `retrace` storageDomain, and the per-session
+ * config view.
+ *
+ * PLAN.md §4.1/§4.3/§4.6. Everything here lives behind `ctx.inject(...)` so
+ * headless compositions without `sessionProjections`/`sessionQuery`/
+ * `storageDomain` simply never activate it — the plugin degrades to plain L1
+ * (recall / edit / regenerate) with no versioning surface, exactly like
+ * 0.2.x.
+ *
+ * The projection unit is registered unconditionally once the seam is
+ * available (pure fold, framework-owned cache, negligible cost). The
+ * "versioning off" switch is honored at the side-effect and HTTP surface:
+ * no snapshots are written and `/versions` reports `enabled: false` — the
+ * user-visible behavior is identical to 0.2.x either way.
+ */
+import { join } from 'node:path'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import {
+  createArtifactStore,
+  refFor,
+  retraceDomainSpec,
+} from './artifact-store.js'
+import { versionsProjectionDefinition } from './projection/versions.js'
+
+/** Max bytes snapshotted per touched file (over → file skipped, version kept). */
+const MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024
+/** NUL-byte probe window for binary detection. */
+const BINARY_PROBE_BYTES = 1024
+
+/** Default per-session config (client may override per request). */
+export const DEFAULT_RETRACE_CONFIG = { versioning: true, git: true, retentionLimit: 50 }
+
+function isBinary(bytes) {
+  const probe = bytes.subarray(0, BINARY_PROBE_BYTES)
+  for (const byte of probe) if (byte === 0) return true
+  return false
+}
+
+/**
+ * Create the versioning seam for one plugin context.
+ * `register()` must run synchronously inside `apply` so the `ctx.inject`
+ * effects attach to the plugin fiber.
+ * @param {object} options - `storeRoot` overrides the artifact root
+ *   (defaults to `$DSH_HOME/dsh-retrace`); tests use a temp directory.
+ */
+export function createVersioningSeam(ctx, log = () => {}, options = {}) {
+  let registered = false
+  let seamCtx = null
+  let domain = null
+  let store = null
+  const disposers = []
+  /** Per-session request-carried config; seeded from the domain global when ready. */
+  const configs = new Map()
+
+  function configFor(sessionId) {
+    return configs.get(sessionId) ?? { ...DEFAULT_RETRACE_CONFIG }
+  }
+
+  function setConfig(sessionId, config) {
+    configs.set(sessionId, { ...DEFAULT_RETRACE_CONFIG, ...config })
+  }
+
+  /** Versioning surface availability (false in headless/minimal compositions). */
+  function available() {
+    return seamCtx !== null
+  }
+
+  /** Read one touched file through the sandboxed fs and snapshot it. */
+  async function snapshotOne(session, record, file) {
+    const cwd = session.header?.cwd
+    if (typeof cwd !== 'string' || cwd.length === 0) return
+    try {
+      const target = await ctx.fs.resolve(file.path, { cwd })
+      const workspaceTarget = await ctx.fs.resolve('.', { cwd })
+      if (!ctx.fs.contains(workspaceTarget, target)) return // outside the workspace
+      const bytes = await ctx.fs.readBytes(target, undefined, MAX_SNAPSHOT_BYTES)
+      if (isBinary(bytes)) return
+      const { sha256, sizeBytes } = await store.save(bytes)
+      const refsTable = domain.table('refcounts')
+      const ref = refFor(record.versionId, file.path)
+      const prev = refsTable.get(sha256)
+      if (prev && !prev.refs.includes(ref)) {
+        await refsTable.put(sha256, { ...prev, refs: [...prev.refs, ref] })
+      } else if (!prev) {
+        await refsTable.put(sha256, {
+          refs: [ref],
+          sizeBytes,
+          createdAt: typeof record.createdAt === 'number' ? record.createdAt : Date.now(),
+        })
+      }
+    } catch (error) {
+      log(`retrace: snapshot skipped for ${file.path}: ${String(error)}`)
+    }
+  }
+
+  /** Side effect: snapshot every non-deleted touched file of a new version. */
+  async function snapshotVersionFiles(session, record) {
+    if (!domain || !store || !configFor(session.id).versioning) return
+    await Promise.allSettled(
+      record.touchedFiles
+        .filter((file) => file.mode !== 'deleted')
+        .map((file) => snapshotOne(session, record, file)),
+    )
+  }
+
+  /**
+   * Register the projection unit, open the domain and wire the change feed.
+   * Idempotent; safe to call from apply.
+   */
+  function register() {
+    if (registered) return
+    registered = true
+    ctx.inject(['sessionProjections', 'sessionQuery', 'storageDomain'], (seam) => {
+      seamCtx = seam
+      disposers.push(seam.sessionProjections.register(versionsProjectionDefinition))
+      disposers.push(
+        seam.sessionProjections.onChanged((session, key, value, seq) => {
+          if (key !== 'retrace/versions') return
+          const latest = value.versions.at(-1)
+          if (!latest || latest.boundarySeq !== seq) return // only NEW boundaries
+          void snapshotVersionFiles(session, latest)
+        }),
+      )
+      // Domain open is async; versioning degrades to L1 if it fails.
+      void seam.storageDomain
+        .open(retraceDomainSpec)
+        .then((opened) => {
+          domain = opened
+          const root = options.storeRoot ?? join(resolveDshHome(), 'dsh-retrace')
+          store = createArtifactStore(root)
+          disposers.push(() => void domain.close())
+          const global = opened.global.get()
+          if (global) {
+            // Seed session configs with the durable defaults (per-request overrides win).
+            for (const [id, config] of configs) setConfig(id, { ...config, ...global })
+          }
+        })
+        .catch((error) => log(`retrace: versioning disabled: ${String(error)}`))
+    })
+    ctx.effect(() => () => {
+      for (const dispose of disposers) dispose()
+    }, 'dsh-retrace: versioning seam')
+  }
+
+  /** HTTP fallback channel: the live projection snapshot for one session. */
+  function snapshot(sessionId) {
+    if (!available()) {
+      return { enabled: false, versions: [] }
+    }
+    const session = ctx.sessions.get(sessionId)
+    if (!session) {
+      const error = new Error(`session "${sessionId}" not found`)
+      error.code = 'session-not-found'
+      throw error
+    }
+    const cut = seamCtx.sessionProjections.snapshot(session)
+    const value = cut.values['retrace/versions']
+    if (!value) return { enabled: false, versions: [] }
+    return { enabled: configFor(sessionId).versioning, ...value }
+  }
+
+  /** readEvent passthrough (timeline detail drawer). */
+  async function readEvent(request) {
+    if (!available()) {
+      const error = new Error('versioning surface unavailable')
+      error.code = 'versioning-unavailable'
+      throw error
+    }
+    return seamCtx.sessionQuery.readEvent(request)
+  }
+
+  /** readSurface passthrough. */
+  async function readSurface(sessionId) {
+    if (!available()) {
+      const error = new Error('versioning surface unavailable')
+      error.code = 'versioning-unavailable'
+      throw error
+    }
+    return seamCtx.sessionQuery.readSurface(sessionId)
+  }
+
+  return {
+    register,
+    available,
+    configFor,
+    setConfig,
+    snapshot,
+    readEvent,
+    readSurface,
+  }
+}