@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/src/rewind-host.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from 'node:crypto'
 import type { Context } from '@deepseek-ai/cordis'
+import { createDeadline } from './deadline.js'
 import { ChangeLedgerError, errorMessage } from './errors.js'
 import type { ChangeLedgerEngine } from './engine.js'
 import { discoverRepositoryRoot } from './git.js'
+import type { WorkspacePurgeReport } from './types.js'
 
 interface SessionEventLike {
   readonly type: string
@@ -114,6 +116,7 @@ export class TurnCheckpointCoordinator {
   private readonly captures = new Map<string, Promise<void>>()
   private readonly pending = new Set<string>()
   private readonly failures = new Map<string, string>()
+  private readonly skips = new Map<string, string>()
   private readonly workspaceTails = new Map<string, Promise<void>>()
 
   constructor(private readonly engine: ChangeLedgerEngine) {}
@@ -127,9 +130,11 @@ export class TurnCheckpointCoordinator {
   }
 
   /** Current capture state for a session turn when no durable checkpoint exists yet. */
-  state(sessionId: string, turn: number): { readonly status: 'pending' | 'failed' | 'missing'; readonly error?: string } {
+  state(sessionId: string, turn: number): { readonly status: 'pending' | 'failed' | 'skipped' | 'missing'; readonly error?: string; readonly reason?: string } {
     const key = checkpointKey(sessionId, turn)
     if (this.pending.has(key)) return { status: 'pending' }
+    const reason = this.skips.get(key)
+    if (reason !== undefined) return { status: 'skipped', reason }
     const error = this.failures.get(key)
     return error === undefined ? { status: 'missing' } : { status: 'failed', error }
   }
@@ -141,48 +146,88 @@ export class TurnCheckpointCoordinator {
     signal: AbortSignal,
   ): Promise<void> {
     const key = checkpointKey(agent.id, turn)
-    const existing = this.captures.get(key)
-    if (existing !== undefined) {
-      await existing
-      return
-    }
     const cwd = agent.session.header.cwd
     if (cwd === undefined) return
     const start = agent.session.events.findLast(event => event.type === 'turn/start' && event.data.turn === turn)
     if (start === undefined) {
-      this.recordFailure(ctx, agent.id, turn, new Error('turn/start is unavailable before the first step'))
+      await this.recordFailure(ctx, agent.id, turn, new Error('turn/start is unavailable before the first step'))
       return
     }
-    this.pending.add(key)
-    this.failures.delete(key)
-    const capture = (async () => {
-      try {
-        const workspace = await discoverRepositoryRoot(cwd, signal)
-        await this.serializeWorkspace(workspace, signal, async () => {
-          await this.engine.createTurnCheckpoint({
-            cwd: workspace,
-            sessionId: agent.id,
-            turn,
-            turnStartSeq: start.seq,
-            signal,
+    const timeoutMs = this.engine.config.turnCheckpointTimeoutMs
+    const outcomeDeadline = createDeadline(timeoutMs)
+    const outcomeSignal = AbortSignal.any([signal, outcomeDeadline.signal])
+    const reserveMs = Math.min(250, Math.max(10, Math.ceil(timeoutMs / 5)))
+    const captureDeadline = createDeadline(Math.max(1, timeoutMs - reserveMs))
+    const captureSignal = AbortSignal.any([signal, captureDeadline.signal])
+    try {
+      const existing = this.captures.get(key)
+      if (existing !== undefined) {
+        await waitWithSignal(existing, captureSignal).catch(() => undefined)
+        return
+      }
+      this.pending.add(key)
+      this.failures.delete(key)
+      this.skips.delete(key)
+      const capture = (async () => {
+        try {
+          const workspace = await discoverRepositoryRoot(cwd, captureSignal)
+          await this.serializeWorkspace(workspace, captureSignal, async () => {
+            try {
+              await this.engine.createTurnCheckpoint({
+                cwd: workspace,
+                sessionId: agent.id,
+                turn,
+                turnStartSeq: start.seq,
+                signal: captureSignal,
+              })
+            } catch (error) {
+              await this.recordFailure(
+                ctx,
+                agent.id,
+                turn,
+                checkpointTimeoutError(error, timeoutMs, captureDeadline.signal, signal),
+                { cwd: workspace, turnStartSeq: start.seq },
+              )
+            }
           })
-        })
+        } catch (error) {
+          await this.recordFailure(
+            ctx,
+            agent.id,
+            turn,
+            checkpointTimeoutError(error, timeoutMs, captureDeadline.signal, signal),
+            { cwd, turnStartSeq: start.seq },
+          )
+        } finally {
+          this.pending.delete(key)
+        }
+      })()
+      this.captures.set(key, capture)
+      try {
+        await waitWithSignal(capture, outcomeSignal)
       } catch (error) {
-        this.recordFailure(ctx, agent.id, turn, error)
-      } finally {
+        const bounded = checkpointTimeoutError(error, timeoutMs, outcomeDeadline.signal, signal)
+        const message = errorMessage(bounded)
         this.pending.delete(key)
+        if (bounded instanceof ChangeLedgerError && isCheckpointSkip(bounded.code)) {
+          this.skips.set(key, message)
+        } else {
+          this.failures.set(key, message)
+        }
       }
-    })()
-    this.captures.set(key, capture)
-    await capture
+    } finally {
+      captureDeadline.cancel()
+      outcomeDeadline.cancel()
+    }
   }
 
   private async serializeWorkspace(workspace: string, signal: AbortSignal, task: () => Promise<void>): Promise<void> {
     const previous = this.workspaceTails.get(workspace) ?? Promise.resolve()
-    const current = previous.catch(() => undefined).then(async () => {
+    const current = (async () => {
+      await waitWithSignal(previous.catch(() => undefined), signal)
       signal.throwIfAborted()
       await task()
-    })
+    })()
     this.workspaceTails.set(workspace, current)
     try {
       await current
@@ -191,18 +236,70 @@ export class TurnCheckpointCoordinator {
     }
   }
 
-  private recordFailure(
+  private async recordFailure(
     ctx: Pick<Context, 'logger'>,
     sessionId: string,
     turn: number,
     error: unknown,
-  ): void {
+    skipContext?: { readonly cwd: string; readonly turnStartSeq: number },
+  ): Promise<void> {
     const message = errorMessage(error)
+    if (error instanceof ChangeLedgerError && isCheckpointSkip(error.code)) {
+      this.skips.set(checkpointKey(sessionId, turn), message)
+      if (skipContext !== undefined) {
+        try {
+          await this.engine.recordTurnCheckpointSkip({
+            cwd: skipContext.cwd,
+            sessionId,
+            turn,
+            turnStartSeq: skipContext.turnStartSeq,
+            reason: message,
+          })
+        } catch (persistError) {
+          ctx.logger.warn(`[turn-rewind] could not persist checkpoint skip for ${sessionId} turn ${String(turn)}: ${errorMessage(persistError)}`)
+        }
+      }
+      ctx.logger.warn(`[turn-rewind] checkpoint skipped for ${sessionId} turn ${String(turn)}: ${message}`)
+      return
+    }
     this.failures.set(checkpointKey(sessionId, turn), message)
     ctx.logger.warn(`[turn-rewind] checkpoint failed for ${sessionId} turn ${String(turn)}: ${message}`)
   }
 }
 
+function isCheckpointSkip(code: string): boolean {
+  return code === 'TURN_CHECKPOINT_DISABLED'
+    || code === 'TURN_CHECKPOINT_TIMEOUT'
+    || code === 'TURN_CHECKPOINT_NEW_CONTENT_LIMIT'
+    || code === 'GIT_OBJECT_STORE_UNSUPPORTED'
+    || code === 'GIT_INDEX_UNSUPPORTED'
+}
+
+async function waitWithSignal<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted()
+  let rejectAbort: ((reason?: unknown) => void) | undefined
+  const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject })
+  const onAbort = () => rejectAbort?.(signal.reason)
+  signal.addEventListener('abort', onAbort, { once: true })
+  try {
+    return await Promise.race([promise, aborted])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
+function checkpointTimeoutError(
+  error: unknown,
+  timeoutMs: number,
+  deadline: AbortSignal,
+  callerSignal: AbortSignal,
+): unknown {
+  if (!callerSignal.aborted && deadline.aborted) {
+    return new ChangeLedgerError('TURN_CHECKPOINT_TIMEOUT', `automatic checkpoint exceeded ${timeoutMs} ms`, { cause: error })
+  }
+  return error
+}
+
 /** Register the same-origin preview/apply endpoint consumed by the browser half. */
 export function installRewindHttp(
   ctx: Context,
@@ -216,6 +313,101 @@ export function installRewindHttp(
   }), 'change-ledger.rewindHttp')
 }
 
+export const MANAGE_HTTP_PATH = '/turn-rewind/manage'
+
+/** Register the same-origin storage-management endpoint consumed by the settings card. */
+export function installManageHttp(ctx: Context, engine: ChangeLedgerEngine): void {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: MANAGE_HTTP_PATH,
+    handler: createManageHttpHandler(engine),
+  }), 'change-ledger.manageHttp')
+}
+
+/** Build the storage-management route as a testable unit. */
+export function createManageHttpHandler(
+  engine: ChangeLedgerEngine,
+): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void> {
+  return async (request, response) => {
+    try {
+      if (request.method === 'GET') {
+        const workspaces = await engine.listWorkspaces()
+        json(response, 200, {
+          storageDir: engine.config.storageDir,
+          totalBytes: workspaces.reduce((total, workspace) => total + workspace.totalBytes, 0),
+          workspaces: workspaces.map((workspace) => ({
+            workspace: workspace.workspace,
+            totalBytes: workspace.totalBytes,
+            recoveryCount: workspace.recoveryCount,
+            restorePoints: workspace.restorePoints.map((point) => ({
+              id: point.id,
+              kind: point.kind,
+              format: point.format,
+              createdAt: point.createdAt,
+              totalBytes: point.totalBytes,
+              fileCount: point.fileCount,
+              ...(point.sessionId === undefined ? {} : { sessionId: point.sessionId }),
+              ...(point.turn === undefined ? {} : { turn: point.turn }),
+              ...(point.label === undefined ? {} : { label: point.label }),
+            })),
+          })),
+        })
+        return
+      }
+      if (request.method === 'POST') {
+        const body = objectBody(await readBody(request))
+        const action = requiredText(body.action, 'action')
+        if (action === 'delete') {
+          const workspace = requiredText(body.workspace, 'workspace')
+          const restorePointId = requiredText(body.restorePointId, 'restorePointId')
+          const report = await engine.purgeWorkspace({ workspace, restorePointIds: [restorePointId] })
+          if (report.deletedRestorePoints === 0) {
+            throw new ChangeLedgerError(
+              report.retainedRestorePoints > 0 ? 'RECOVERY_REFERENCE' : 'RESTORE_POINT_NOT_FOUND',
+              report.retainedRestorePoints > 0
+                ? 'restore point is required by an incomplete recovery journal'
+                : `restore point ${restorePointId} does not exist`,
+            )
+          }
+          json(response, 200, { status: 'completed', action, ...report })
+          return
+        }
+        if (action === 'clear-workspace') {
+          const workspace = requiredText(body.workspace, 'workspace')
+          json(response, 200, { status: 'completed', action, ...await engine.purgeWorkspace({ workspace }) })
+          return
+        }
+        if (action === 'clear-all') {
+          const reports: WorkspacePurgeReport[] = []
+          const failures: { readonly workspace: string; readonly error: string }[] = []
+          for (const overview of await engine.listWorkspaces()) {
+            try {
+              reports.push(await engine.purgeWorkspace({ workspace: overview.workspace }))
+            } catch (error) {
+              failures.push({ workspace: overview.workspace, error: errorMessage(error) })
+            }
+          }
+          json(response, 200, {
+            status: failures.length > 0 ? 'partial' : 'completed',
+            action,
+            reports,
+            ...(failures.length > 0 ? { failures } : {}),
+          })
+          return
+        }
+        throw new ChangeLedgerError('INVALID_ARGUMENTS', 'action must be "delete", "clear-workspace", or "clear-all"')
+      }
+      json(response, 405, { error: 'method not allowed' })
+    } catch (error) {
+      const status = error instanceof ChangeLedgerError && error.code === 'RESTORE_POINT_NOT_FOUND' ? 404 : 409
+      json(response, status, {
+        error: errorMessage(error),
+        code: error instanceof ChangeLedgerError ? error.code : 'MANAGE_FAILED',
+      })
+    }
+  }
+}
+
 /** Build the exact-route handler as a testable unit. */
 export function createRewindHttpHandler(
   ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'> & { readonly agents?: AgentsLike },
@@ -231,9 +423,26 @@ export function createRewindHttpHandler(
         const detailsOnly = url.searchParams.get('details') === '1'
         const offset = nonNegativeInteger(url.searchParams.get('offset') ?? '0', 'offset')
         const limit = pageSize(url.searchParams.get('limit'), detailsOnly ? MAX_CHANGE_PAGE_SIZE : INITIAL_CHANGE_PREVIEW_LIMIT)
-        const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq)
+        const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+        let checkpoint: MessageCheckpoint | undefined
+        try {
+          checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target)
+        } catch (error) {
+          // File-checkpoint discovery is allowed to fail independently: the dialog
+          // must still expose message-only rewind for a valid Session boundary.
+          json(response, 200, { status: 'failed', error: errorMessage(error) })
+          return
+        }
         if (checkpoint === undefined) {
-          json(response, 200, coordinator.state(sessionId, target.turn))
+          const durableSkip = await engine.findTurnCheckpointSkip({
+            cwd: target.cwd,
+            sessionId,
+            turn: target.turn,
+            turnStartSeq: target.turnStartSeq,
+          })
+          json(response, 200, durableSkip === undefined
+            ? coordinator.state(sessionId, target.turn)
+            : { status: 'skipped', reason: durableSkip.reason })
           return
         }
         const inspection = await engine.inspect({ cwd: checkpoint.cwd, restorePointId: checkpoint.id })
@@ -279,11 +488,20 @@ export function createRewindHttpHandler(
       if (request.method === 'POST') {
         const body = objectBody(await readBody(request))
         const mode = body.mode
-        if (mode !== 'code' && mode !== 'both') {
-          throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code" or "both"')
+        if (mode !== 'code' && mode !== 'both' && mode !== 'messages') {
+          throw new ChangeLedgerError('INVALID_ARGUMENTS', 'mode must be "code", "both", or "messages"')
         }
         const sessionId = requiredText(body.sessionId, 'sessionId')
         const messageSeq = nonNegativeInteger(body.messageSeq, 'messageSeq')
+        if (mode === 'messages') {
+          // Message-only rewind never mutates project files, so no checkpoint, no
+          // restore plan, and no shared-workspace gate apply; the conversation
+          // restart revalidates the message boundary itself.
+          const { target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+          const fork = await createConversationRestart(ctx, sessionId, target)
+          json(response, 200, { status: 'completed', mode, sessionId: fork.sessionId })
+          return
+        }
         const checkpointId = requiredText(body.checkpointId, 'checkpointId')
         const checkpoint = await checkpointForRequest(ctx, engine, sessionId, messageSeq, checkpointId)
         const activeSessionIds = await sharedWorkspaceSessions(ctx.agents, checkpoint.cwd)
@@ -361,20 +579,29 @@ interface MessageCheckpoint extends MessageTarget {
   readonly id: string
 }
 
+async function resolveMessageTarget(
+  ctx: Pick<Context, 'sessions' | 'sessionQuery'>,
+  sessionId: string,
+  messageSeq: number,
+): Promise<{ readonly session: SessionLike; readonly target: MessageTarget }> {
+  const session = await readSession(ctx, sessionId)
+  return { session, target: messageTarget(session, messageSeq) }
+}
+
 async function resolveMessageCheckpoint(
   ctx: Pick<Context, 'sessions' | 'sessionQuery'>,
   engine: ChangeLedgerEngine,
   sessionId: string,
-  messageSeq: number,
-): Promise<{ readonly target: MessageTarget; readonly checkpoint?: MessageCheckpoint }> {
-  let current = await readSession(ctx, sessionId)
-  const target = messageTarget(current, messageSeq)
+  source: SessionLike,
+  target: MessageTarget,
+): Promise<MessageCheckpoint | undefined> {
+  let current = source
   const direct = await engine.findTurnCheckpoint({ cwd: target.cwd, sessionId, turn: target.turn })
   if (direct !== undefined) {
     if (direct.turnStartSeq !== target.turnStartSeq) {
       throw new ChangeLedgerError('PLAN_STALE', 'the message checkpoint no longer matches its turn start')
     }
-    return { target, checkpoint: { ...target, id: direct.id } }
+    return { ...target, id: direct.id }
   }
 
   const seen = new Set<string>([sessionId])
@@ -386,7 +613,7 @@ async function resolveMessageCheckpoint(
     }
     if (parentId === undefined || seedLength === undefined
       || target.messageSeq >= seedLength || target.turnStartSeq >= seedLength) {
-      return { target }
+      return undefined
     }
     if (seen.has(parentId)) {
       throw new ChangeLedgerError('PLAN_STALE', 'session fork lineage contains a cycle')
@@ -397,7 +624,7 @@ async function resolveMessageCheckpoint(
     } catch (error) {
       throw new ChangeLedgerError('PLAN_STALE', `parent session ${parentId} is unavailable`, { cause: error })
     }
-    const parentTarget = messageTarget(current, messageSeq)
+    const parentTarget = messageTarget(current, target.messageSeq)
     if (parentTarget.turn !== target.turn
       || parentTarget.turnStartSeq !== target.turnStartSeq
       || parentTarget.previousTurnEndSeq !== target.previousTurnEndSeq) {
@@ -408,7 +635,7 @@ async function resolveMessageCheckpoint(
     if (inherited.turnStartSeq !== target.turnStartSeq) {
       throw new ChangeLedgerError('PLAN_STALE', 'the inherited message checkpoint no longer matches the fork boundary')
     }
-    return { target, checkpoint: { ...target, id: inherited.id } }
+    return { ...target, id: inherited.id }
   }
 }
 
@@ -419,7 +646,8 @@ async function checkpointForRequest(
   messageSeq: number,
   requestedId: string,
 ): Promise<MessageCheckpoint> {
-  const { target, checkpoint } = await resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq)
+  const { session, target } = await resolveMessageTarget(ctx, sessionId, messageSeq)
+  const checkpoint = await resolveMessageCheckpoint(ctx, engine, sessionId, session, target)
   if (checkpoint === undefined) {
     throw new ChangeLedgerError('RESTORE_POINT_NOT_FOUND', `message ${String(target.messageSeq)} has no rewind checkpoint`)
   }
@@ -432,23 +660,23 @@ async function checkpointForRequest(
 async function createConversationRestart(
   ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'>,
   sourceId: string,
-  checkpoint: MessageCheckpoint,
+  target: MessageTarget,
 ): Promise<{ readonly sessionId: string }> {
   const source = await readSession(ctx, sourceId)
-  const current = messageTarget(source, checkpoint.messageSeq)
-  if (current.turn !== checkpoint.turn
-    || current.turnStartSeq !== checkpoint.turnStartSeq
-    || current.previousTurnEndSeq !== checkpoint.previousTurnEndSeq) {
+  const current = messageTarget(source, target.messageSeq)
+  if (current.turn !== target.turn
+    || current.turnStartSeq !== target.turnStartSeq
+    || current.previousTurnEndSeq !== target.previousTurnEndSeq) {
     throw new ChangeLedgerError('PLAN_STALE', 'the session no longer contains the selected message boundary')
   }
-  const response = checkpoint.previousTurnEndSeq === undefined
+  const response = target.previousTurnEndSeq === undefined
     ? await ctx.apiProxy.sessions.create({
         rpcId: randomUUID(),
-        payload: { cwd: checkpoint.cwd },
+        payload: { cwd: target.cwd },
       })
     : await ctx.apiProxy.sessions.fork({
         rpcId: randomUUID(),
-        payload: { sessionId: sourceId, atSeq: checkpoint.previousTurnEndSeq },
+        payload: { sessionId: sourceId, atSeq: target.previousTurnEndSeq },
       })
   if (!response.result.ok) {
     throw new ChangeLedgerError('CONVERSATION_REWIND_FAILED', response.result.error.message)

package/src/settings.ts

@@ -0,0 +1,93 @@
+/**
+ * Runtime settings surface for Turn Rewind on the DSH web settings page.
+ * @module @anionex/dsh-turn-rewind
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+import { resolveConfig, type ChangeLedgerEngine } from './engine.js'
+import type { ChangeLedgerConfig, ResolvedChangeLedgerConfig } from './types.js'
+
+/** Namespace join key shared by the host section and the browser settings card. */
+export const TURN_REWIND_SETTINGS_NAMESPACE = settingsNamespace('turn-rewind')
+
+/** Every runtime-tunable field of {@link ChangeLedgerConfig}; `storageDir` stays config-layer only. */
+export interface TurnRewindSettings {
+  /** Maximum user and rescue restore points retained per workspace. */
+  maxRestorePoints: number
+  /** Maximum automatic turn checkpoints retained per session. */
+  maxTurnCheckpointsPerSession: number
+  /** Maximum number of files in one restore point. */
+  maxFiles: number
+  /** Maximum bytes read from one regular file. */
+  maxFileBytes: number
+  /** Maximum aggregate regular-file bytes in one restore point. */
+  maxSnapshotBytes: number
+  /** Restore-plan lifetime in milliseconds. */
+  planTtlMs: number
+  /** Age after which a lock whose owner is gone may be reclaimed. */
+  staleLockMs: number
+  /** Automatic turn-checkpoint implementation; `off` records durable skips instead. */
+  turnCheckpointMode: 'off' | 'git-native' | 'legacy'
+  /** Maximum time one automatic checkpoint may block the first Agent step. */
+  turnCheckpointTimeoutMs: number
+  /** Maximum uncached worktree bytes read by one automatic Git-native checkpoint. */
+  turnCheckpointMaxNewBytes: number
+  /** Fast trusts fenced Git/stat metadata; strict rereads every eligible path. */
+  turnCheckpointTrust: 'fast' | 'strict'
+}
+
+/** Schemastery schema for the `turn-rewind` settings namespace. */
+export const TurnRewindSettingsSchema: z<TurnRewindSettings> = (() => {
+  const defaults = tunableSettings(resolveConfig({}))
+  return z.object({
+    maxRestorePoints: z.number().step(1).min(1).default(defaults.maxRestorePoints),
+    maxTurnCheckpointsPerSession: z.number().step(1).min(1).default(defaults.maxTurnCheckpointsPerSession),
+    maxFiles: z.number().step(1).min(1).default(defaults.maxFiles),
+    maxFileBytes: z.number().step(1).min(1).default(defaults.maxFileBytes),
+    maxSnapshotBytes: z.number().step(1).min(1).default(defaults.maxSnapshotBytes),
+    planTtlMs: z.number().step(1).min(1).default(defaults.planTtlMs),
+    staleLockMs: z.number().step(1).min(1).default(defaults.staleLockMs),
+    turnCheckpointMode: z.union(['off', 'git-native', 'legacy']).default(defaults.turnCheckpointMode),
+    turnCheckpointTimeoutMs: z.number().step(1).min(1).default(defaults.turnCheckpointTimeoutMs),
+    turnCheckpointMaxNewBytes: z.number().step(1).min(1).default(defaults.turnCheckpointMaxNewBytes),
+    turnCheckpointTrust: z.union(['fast', 'strict']).default(defaults.turnCheckpointTrust),
+  })
+})()
+
+/** Project one resolved configuration onto the settings namespace subset. */
+function tunableSettings(resolved: ResolvedChangeLedgerConfig): TurnRewindSettings {
+  return {
+    maxRestorePoints: resolved.maxRestorePoints,
+    maxTurnCheckpointsPerSession: resolved.maxTurnCheckpointsPerSession,
+    maxFiles: resolved.maxFiles,
+    maxFileBytes: resolved.maxFileBytes,
+    maxSnapshotBytes: resolved.maxSnapshotBytes,
+    planTtlMs: resolved.planTtlMs,
+    staleLockMs: resolved.staleLockMs,
+    turnCheckpointMode: resolved.turnCheckpointMode,
+    turnCheckpointTimeoutMs: resolved.turnCheckpointTimeoutMs,
+    turnCheckpointMaxNewBytes: resolved.turnCheckpointMaxNewBytes,
+    turnCheckpointTrust: resolved.turnCheckpointTrust,
+  }
+}
+
+/**
+ * Register the `turn-rewind` settings namespace and apply its resolved value to the
+ * running engine. The composition entry (from `cordis.patch.yml`) is the base layer;
+ * the user layer persists through the DSH settings provider. `storageDir` is never
+ * carried by the namespace: the storage root must not move while the engine runs.
+ */
+export function installTurnRewindSettings(ctx: Context, config: ChangeLedgerConfig, engine: ChangeLedgerEngine): void {
+  let source: () => TurnRewindSettings = () => tunableSettings(resolveConfig(config))
+  installSettingsSection(ctx, TURN_REWIND_SETTINGS_NAMESPACE, TurnRewindSettingsSchema, source(), {
+    setSource: (current) => { source = current },
+    onChange: () => {
+      try {
+        engine.updateConfig({ ...config, ...source() })
+      } catch (error) {
+        ctx.logger.warn(`[turn-rewind] could not apply settings update: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    },
+  })
+}