@anionex/dsh-turn-rewind 0.1.2 → 0.2.0

package/lib/engine.js

@@ -25,17 +25,32 @@ const DEFAULTS = {
 };
 /** Persistent workspace change-set engine, independent of the DSH tool adapter. */
 export class ChangeLedgerEngine {
-    config;
+    currentConfig;
     store;
     plans = new Map();
     activePlans = new Set();
     ready;
     /** Build an engine and start crash-journal reconciliation. */
     constructor(config = {}) {
-        this.config = resolveConfig(config);
-        this.store = new LedgerStore(this.config);
+        this.currentConfig = resolveConfig(config);
+        this.store = new LedgerStore(this.currentConfig);
         this.ready = this.initializeStore();
     }
+    /** Currently resolved configuration; runtime-tunable fields update in place. */
+    get config() {
+        return this.currentConfig;
+    }
+    /**
+     * Swap runtime-tunable configuration (limits, modes, timeouts, trust) in place.
+     * The storage root must never move once the engine owns locks and journals.
+     */
+    updateConfig(config) {
+        const resolved = resolveConfig(config);
+        if (resolved.storageDir !== this.currentConfig.storageDir) {
+            throw new ChangeLedgerError('INVALID_CONFIG', 'storageDir cannot change while the engine is running');
+        }
+        Object.assign(this.currentConfig, resolved);
+    }
     /** Wait for startup reconciliation and return the number of interrupted journals found. */
     async initialize() {
         return this.ready;
@@ -615,6 +630,128 @@ export class ChangeLedgerEngine {
             await release();
         }
     }
+    /** Inventory every workspace this storage root has ever persisted state for. */
+    async listWorkspaces(options = {}) {
+        await this.ready;
+        const groups = new Map();
+        const groupOf = (workspace) => {
+            const existing = groups.get(workspace);
+            if (existing !== undefined)
+                return existing;
+            const created = { restorePoints: [], recoveryCount: 0 };
+            groups.set(workspace, created);
+            return created;
+        };
+        for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+            for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+                groupOf(manifest.workspace).restorePoints.push(summarize(manifest));
+            }
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+                if (operation.state === 'interrupted' || operation.state === 'recovery-required') {
+                    groupOf(operation.workspace).recoveryCount += 1;
+                }
+            }
+        }
+        return [...groups.entries()]
+            .map(([workspace, group]) => ({
+            workspace,
+            restorePoints: [...group.restorePoints].sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id)),
+            totalBytes: group.restorePoints.reduce((total, point) => total + point.totalBytes, 0),
+            recoveryCount: group.recoveryCount,
+        }))
+            .sort((left, right) => left.workspace.localeCompare(right.workspace));
+    }
+    /** Delete unprotected restore points recorded for one workspace and collect unused blobs. */
+    async purgeWorkspace(options) {
+        await this.ready;
+        const restorePointIds = options.restorePointIds === undefined ? undefined : new Set(options.restorePointIds);
+        const targetDirs = new Set();
+        for (const workspaceDir of await this.store.listWorkspaceDirs(options.signal)) {
+            for (const manifest of await this.store.listManifestsInDir(workspaceDir, options.signal)) {
+                if (manifest.workspace === options.workspace
+                    && (restorePointIds === undefined || restorePointIds.has(manifest.id))) {
+                    targetDirs.add(workspaceDir);
+                }
+            }
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, options.signal)) {
+                if (operation.workspace === options.workspace)
+                    targetDirs.add(workspaceDir);
+            }
+        }
+        let deletedRestorePoints = 0;
+        let retainedRestorePoints = 0;
+        let deletedBlobs = 0;
+        let retainedBlobs = 0;
+        for (const workspaceDir of targetDirs) {
+            const result = await this.purgeWorkspaceDir(workspaceDir, options.workspace, restorePointIds, options.signal);
+            deletedRestorePoints += result.deletedRestorePoints;
+            retainedRestorePoints += result.retainedRestorePoints;
+            deletedBlobs += result.deletedBlobs;
+            retainedBlobs += result.retainedBlobs;
+        }
+        return { workspace: options.workspace, deletedRestorePoints, retainedRestorePoints, deletedBlobs, retainedBlobs };
+    }
+    async purgeWorkspaceDir(workspaceDir, workspace, restorePointIds, signal) {
+        // A live repository needs both its shared Git lock and durable directory lock.
+        // A missing path, or one now nested under a different repository, cannot expose
+        // its old Git namespace but still takes the durable lock before storage cleanup.
+        let liveRepository = false;
+        let release;
+        try {
+            const root = await discoverRepositoryRoot(workspace, signal);
+            if (root === workspace) {
+                await this.assertStorageSeparated(root);
+                release = await this.acquireWorkspace(root, signal);
+                liveRepository = true;
+            }
+            else {
+                release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ChangeLedgerError) || error.code !== 'WORKSPACE_NOT_FOUND')
+                throw error;
+            release = await this.store.acquireWorkspaceDir(workspaceDir, workspace, signal);
+        }
+        let deletedRestorePoints = 0;
+        let retainedRestorePoints = 0;
+        try {
+            const manifests = (await this.store.listManifestsInDir(workspaceDir, signal))
+                .filter((manifest) => manifest.workspace === workspace
+                && (restorePointIds === undefined || restorePointIds.has(manifest.id)));
+            const protectedIds = new Set();
+            for (const operation of await this.store.listOperationsInDir(workspaceDir, signal)) {
+                if (operation.state === 'running' || operation.state === 'rollback-running'
+                    || operation.state === 'interrupted' || operation.state === 'recovery-required') {
+                    protectedIds.add(operation.restorePointId);
+                    protectedIds.add(operation.rescuePointId);
+                }
+            }
+            for (const journal of await this.store.listGitCheckpointJournalsInDir(workspaceDir, signal)) {
+                protectedIds.add(journal.restorePointId);
+            }
+            for (const manifest of manifests) {
+                if (protectedIds.has(manifest.id)) {
+                    retainedRestorePoints += 1;
+                    continue;
+                }
+                if (liveRepository) {
+                    await this.deleteManifestWithGit(manifest, signal);
+                }
+                else {
+                    await this.store.deleteManifestInDir(workspaceDir, manifest.id);
+                }
+                deletedRestorePoints += 1;
+            }
+            if (restorePointIds === undefined)
+                await this.store.clearTurnOutcomesInDir(workspaceDir);
+            const gc = await this.store.collectGarbageInDir(workspaceDir, signal);
+            return { deletedRestorePoints, retainedRestorePoints, ...gc };
+        }
+        finally {
+            await release();
+        }
+    }
     async createLocked(options) {
         const existing = await this.store.listManifests(options.cwd);
         const durableUserPoints = existing.filter(point => point.kind !== 'turn');

package/lib/index.js

@@ -1,8 +1,10 @@
 import { ChangeLedgerEngine } from './engine.js';
-import { installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js';
+import { installManageHttp, installRewindHttp, TurnCheckpointCoordinator } from './rewind-host.js';
+import { installTurnRewindSettings } from './settings.js';
 export * from './engine.js';
 export * from './errors.js';
 export * from './rewind-host.js';
+export * from './settings.js';
 export * from './types.js';
 /** Cordis service exposed as `ctx.changeLedger` for other DSH plugins. */
 export class ChangeLedgerService {
@@ -15,7 +17,9 @@ export class ChangeLedgerService {
         ctx.inject(['agents'], (scope) => { checkpoints.install(scope); });
         ctx.inject(['webServer', 'sessions', 'sessionQuery', 'apiProxy', 'agents'], (scope) => {
             installRewindHttp(scope, this.engine, checkpoints);
+            installManageHttp(scope, this.engine);
         });
+        installTurnRewindSettings(ctx, config, this.engine);
         void this.engine.initialize().then((reconciled) => {
             if (reconciled > 0) {
                 ctx.logger.warn(`[change-ledger] reconciled ${reconciled} interrupted durable operation(s)`);
@@ -67,5 +71,17 @@ export class ChangeLedgerService {
     listRecovery(options) {
         return this.engine.listRecovery(options);
     }
+    /** Inventory every workspace this storage root has persisted state for. */
+    listWorkspaces(options) {
+        return this.engine.listWorkspaces(options);
+    }
+    /** Delete unprotected restore points recorded for one workspace. */
+    purgeWorkspace(options) {
+        return this.engine.purgeWorkspace(options);
+    }
+    /** Swap runtime-tunable configuration; the storage root must stay fixed. */
+    updateConfig(config) {
+        this.engine.updateConfig(config);
+    }
 }
 export default ChangeLedgerService;

package/lib/rewind-host.js

@@ -182,6 +182,95 @@ export function installRewindHttp(ctx, engine, coordinator) {
         handler: createRewindHttpHandler(ctx, engine, coordinator),
     }), '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, engine) {
+    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) {
+    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 = [];
+                    const failures = [];
+                    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, engine, coordinator) {
     return async (request, response) => {
@@ -193,7 +282,17 @@ export function createRewindHttpHandler(ctx, engine, coordinator) {
                 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;
+                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) {
                     const durableSkip = await engine.findTurnCheckpointSkip({
                         cwd: target.cwd,
@@ -249,11 +348,20 @@ export function createRewindHttpHandler(ctx, engine, coordinator) {
             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);
@@ -311,15 +419,18 @@ async function readSession(ctx, sessionId) {
     const stored = await ctx.sessionQuery.readSession(sessionId);
     return { id: sessionId, header: stored.session, events: stored.events };
 }
-async function resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq) {
-    let current = await readSession(ctx, sessionId);
-    const target = messageTarget(current, messageSeq);
+async function resolveMessageTarget(ctx, sessionId, messageSeq) {
+    const session = await readSession(ctx, sessionId);
+    return { session, target: messageTarget(session, messageSeq) };
+}
+async function resolveMessageCheckpoint(ctx, engine, sessionId, source, target) {
+    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([sessionId]);
     while (true) {
@@ -330,7 +441,7 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq) {
         }
         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');
@@ -342,7 +453,7 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq) {
         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) {
@@ -354,11 +465,12 @@ async function resolveMessageCheckpoint(ctx, engine, sessionId, messageSeq) {
         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 };
     }
 }
 async function checkpointForRequest(ctx, engine, sessionId, messageSeq, requestedId) {
-    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`);
     }
@@ -367,22 +479,22 @@ async function checkpointForRequest(ctx, engine, sessionId, messageSeq, requeste
     }
     return checkpoint;
 }
-async function createConversationRestart(ctx, sourceId, checkpoint) {
+async function createConversationRestart(ctx, sourceId, target) {
     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/lib/settings.js

@@ -0,0 +1,58 @@
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+import { resolveConfig } from './engine.js';
+/** Namespace join key shared by the host section and the browser settings card. */
+export const TURN_REWIND_SETTINGS_NAMESPACE = settingsNamespace('turn-rewind');
+/** Schemastery schema for the `turn-rewind` settings namespace. */
+export const TurnRewindSettingsSchema = (() => {
+    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) {
+    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, config, engine) {
+    let source = () => 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)}`);
+            }
+        },
+    });
+}