@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/lib/types/types.d.ts

@@ -1,5 +1,7 @@
 /** Durable format version. Readers reject every other version. */
 export declare const LEDGER_FORMAT_VERSION: 1;
+/** Git-native checkpoint format used by bounded automatic turn capture. */
+export declare const GIT_CHECKPOINT_FORMAT_VERSION: 2;
 /** A persisted restore-point identifier. */
 export type RestorePointId = string;
 /** A persisted restore-operation identifier. */
@@ -12,6 +14,8 @@ export interface FileSnapshotEntry {
     readonly blob: string;
     readonly size: number;
     readonly mode: number;
+    /** Absent for v1 Ledger blobs; `git` means `blob` is a Git object ID. */
+    readonly provider?: 'git';
 }
 /** One symbolic-link snapshot. */
 export interface SymlinkSnapshotEntry {
@@ -33,7 +37,7 @@ export interface RepositoryState {
 /** Why a restore point exists. */
 export type RestorePointKind = 'user' | 'rescue' | 'turn';
 /** Durable workspace restore point. */
-export interface RestorePointManifest {
+export interface RestorePointManifestV1 {
     readonly version: typeof LEDGER_FORMAT_VERSION;
     readonly id: RestorePointId;
     readonly kind: RestorePointKind;
@@ -56,6 +60,31 @@ export interface RestorePointManifest {
     readonly restoreCount: number;
     readonly lastRestoredAt?: number;
 }
+/** Git-native metadata pinned by a private ref. */
+export interface GitCheckpointMetadata {
+    readonly objectFormat: 'sha1' | 'sha256';
+    readonly trust: 'metadata-fenced' | 'byte-verified';
+    /** Stable owner of refs created by one Change Ledger storage root. */
+    readonly storeId: string;
+    /** Durable identity stored inside this specific Git worktree metadata directory. */
+    readonly worktreeId: string;
+    readonly headTree: string;
+    readonly indexTree: string;
+    readonly worktreeTree: string;
+    readonly envelopeTree: string;
+    readonly commit: string;
+    readonly ref: string;
+    readonly newlyStoredBytes: number;
+}
+/** Automatic turn checkpoint whose content is stored in the repository object database. */
+export interface RestorePointManifestV2 extends Omit<RestorePointManifestV1, 'version' | 'treeHash'> {
+    readonly version: typeof GIT_CHECKPOINT_FORMAT_VERSION;
+    /** Deterministic sidecar identity; Git tree integrity is verified separately. */
+    readonly treeHash: string;
+    readonly git: GitCheckpointMetadata;
+}
+/** Durable workspace restore point in either supported format. */
+export type RestorePointManifest = RestorePointManifestV1 | RestorePointManifestV2;
 /** Observable difference between a restore point and the current workspace. */
 export interface WorkspaceChange {
     readonly path: string;
@@ -77,6 +106,7 @@ export interface RestorePointInspection {
 }
 /** Compact restore-point metadata for lists and tool results. */
 export interface RestorePointSummary {
+    readonly format: typeof LEDGER_FORMAT_VERSION | typeof GIT_CHECKPOINT_FORMAT_VERSION;
     readonly id: RestorePointId;
     readonly kind: RestorePointKind;
     readonly workspace: string;
@@ -96,6 +126,7 @@ export interface RestorePointSummary {
     readonly branch?: string;
     readonly operation?: string;
     readonly stagedPathCount: number;
+    readonly trust?: GitCheckpointMetadata['trust'];
 }
 /** An expiring restore plan whose confirmation must be echoed exactly. */
 export interface RestorePlan {
@@ -152,6 +183,14 @@ export interface ChangeLedgerConfig {
     readonly planTtlMs?: number;
     /** Age after which a lock whose owner is gone may be reclaimed. */
     readonly staleLockMs?: number;
+    /** Automatic turn-checkpoint implementation. Git-native is bounded and avoids rereading clean tracked content. */
+    readonly turnCheckpointMode?: 'off' | 'git-native' | 'legacy';
+    /** Maximum time one automatic checkpoint may block the first Agent step. */
+    readonly turnCheckpointTimeoutMs?: number;
+    /** Maximum uncached worktree bytes read by one automatic Git-native checkpoint. */
+    readonly turnCheckpointMaxNewBytes?: number;
+    /** Fast trusts fenced Git/stat metadata; strict rereads every eligible path. */
+    readonly turnCheckpointTrust?: 'fast' | 'strict';
 }
 /** Fully resolved plugin configuration. */
 export interface ResolvedChangeLedgerConfig {
@@ -163,6 +202,10 @@ export interface ResolvedChangeLedgerConfig {
     readonly maxSnapshotBytes: number;
     readonly planTtlMs: number;
     readonly staleLockMs: number;
+    readonly turnCheckpointMode: 'off' | 'git-native' | 'legacy';
+    readonly turnCheckpointTimeoutMs: number;
+    readonly turnCheckpointMaxNewBytes: number;
+    readonly turnCheckpointTrust: 'fast' | 'strict';
 }
 /** Current incomplete restore operation. */
 export interface RecoverySummary {
@@ -175,3 +218,22 @@ export interface RecoverySummary {
     readonly error?: string;
     readonly rollbackError?: string;
 }
+/** Aggregated checkpoint inventory for one workspace, addressed by its recorded path. */
+export interface WorkspaceOverview {
+    /** Canonical workspace path recorded in the persisted manifests. */
+    readonly workspace: string;
+    /** Every restore point stored for the workspace, newest first. */
+    readonly restorePoints: readonly RestorePointSummary[];
+    /** Sum of every restore point's logical bytes. */
+    readonly totalBytes: number;
+    /** Incomplete restore operations that still reference this workspace's points. */
+    readonly recoveryCount: number;
+}
+/** Aggregate cleanup report for one workspace purge. */
+export interface WorkspacePurgeReport {
+    readonly workspace: string;
+    readonly deletedRestorePoints: number;
+    readonly retainedRestorePoints: number;
+    readonly deletedBlobs: number;
+    readonly retainedBlobs: number;
+}

package/lib/types.js

@@ -1,2 +1,4 @@
 /** Durable format version. Readers reject every other version. */
 export const LEDGER_FORMAT_VERSION = 1;
+/** Git-native checkpoint format used by bounded automatic turn capture. */
+export const GIT_CHECKPOINT_FORMAT_VERSION = 2;

package/lib/validate.js

@@ -2,7 +2,7 @@ import { ChangeLedgerError } from './errors.js';
 import { isAbsolute } from 'node:path';
 import { validateRelativePath } from './path-utils.js';
 import { hashTree } from './snapshot.js';
-import { LEDGER_FORMAT_VERSION, } from './types.js';
+import { GIT_CHECKPOINT_FORMAT_VERSION, LEDGER_FORMAT_VERSION, } from './types.js';
 const HASH_PATTERN = /^[0-9a-f]{64}$/;
 const GIT_OBJECT_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const ID_PATTERN = /^(?:rp|op)_[0-9a-z]+_[0-9a-f]{12}$/;
@@ -23,14 +23,17 @@ export function validateOperationId(value) {
 /** Parse an untrusted durable restore-point manifest. */
 export function parseManifest(value) {
     const record = objectRecord(value, 'restore-point manifest');
-    if (record.version !== LEDGER_FORMAT_VERSION)
-        corrupt(`unsupported restore-point version ${String(record.version)}`);
+    const version = record.version;
+    if (version !== LEDGER_FORMAT_VERSION && version !== GIT_CHECKPOINT_FORMAT_VERSION) {
+        corrupt(`unsupported restore-point version ${String(version)}`);
+    }
     const id = stringField(record, 'id');
     validateRestorePointId(id);
     const kind = record.kind;
     if (kind !== 'user' && kind !== 'rescue' && kind !== 'turn') {
         corrupt('restore-point kind must be "user", "rescue", or "turn"');
     }
+    const restorePointKind = kind;
     const workspace = absoluteString(record, 'workspace');
     const repository = parseRepository(record.repository);
     if (repository.root !== workspace)
@@ -40,7 +43,7 @@ export function parseManifest(value) {
     let totalBytes = 0;
     for (const [path, entryValue] of Object.entries(entriesRecord)) {
         validateRelativePath(path);
-        const entry = parseEntry(entryValue, path);
+        const entry = parseEntry(entryValue, path, version);
         entries[path] = entry;
         if (entry.kind === 'file')
             totalBytes += entry.size;
@@ -73,10 +76,9 @@ export function parseManifest(value) {
         corrupt('only turn restore points may carry turn metadata');
     }
     const lastRestoredAt = optionalNonNegativeInteger(record, 'lastRestoredAt');
-    return {
-        version: LEDGER_FORMAT_VERSION,
+    const common = {
         id,
-        kind,
+        kind: restorePointKind,
         workspace,
         repository,
         ...(sessionId === undefined ? {} : { sessionId }),
@@ -93,6 +95,11 @@ export function parseManifest(value) {
         restoreCount,
         ...(lastRestoredAt === undefined ? {} : { lastRestoredAt }),
     };
+    if (version === LEDGER_FORMAT_VERSION)
+        return { version, ...common };
+    if (restorePointKind !== 'turn')
+        corrupt('Git-native v2 restore points are automatic turn checkpoints');
+    return { version, ...common, git: parseGitCheckpoint(record.git, id) };
 }
 /** Parse an untrusted durable restore-operation journal. */
 export function parseOperation(value) {
@@ -168,18 +175,24 @@ function parseRepository(value) {
         stagedPaths,
     };
 }
-function parseEntry(value, path) {
+function parseEntry(value, path, version) {
     const record = objectRecord(value, `snapshot entry ${JSON.stringify(path)}`);
     const kind = record.kind;
     const mode = nonNegativeInteger(record, 'mode');
     if (mode > 0o777)
         corrupt(`snapshot mode is out of range for ${JSON.stringify(path)}`);
     if (kind === 'file') {
+        const blob = stringField(record, 'blob');
+        if (version === LEDGER_FORMAT_VERSION)
+            validateBlobHash(blob);
+        else
+            validateGitObject(blob);
         return {
             kind,
-            blob: validateBlobHash(stringField(record, 'blob')),
+            blob,
             size: nonNegativeInteger(record, 'size'),
             mode,
+            ...(version === GIT_CHECKPOINT_FORMAT_VERSION ? { provider: 'git' } : {}),
         };
     }
     if (kind === 'symlink') {
@@ -190,6 +203,52 @@ function parseEntry(value, path) {
     }
     corrupt(`invalid snapshot entry kind for ${JSON.stringify(path)}`);
 }
+function parseGitCheckpoint(value, restorePointId) {
+    const record = objectRecord(value, 'Git checkpoint metadata');
+    const objectFormat = record.objectFormat;
+    if (objectFormat !== 'sha1' && objectFormat !== 'sha256')
+        corrupt('Git checkpoint objectFormat must be sha1 or sha256');
+    const trust = record.trust;
+    if (trust !== 'metadata-fenced' && trust !== 'byte-verified')
+        corrupt('Git checkpoint trust is invalid');
+    const expectedLength = objectFormat === 'sha1' ? 40 : 64;
+    const object = (key) => {
+        const oid = validateGitObject(stringField(record, key));
+        if (oid.length !== expectedLength)
+            corrupt(`${key} length does not match Git object format`);
+        return oid;
+    };
+    const storeId = hexIdentifier(record, 'storeId');
+    const worktreeId = hexIdentifier(record, 'worktreeId');
+    const ref = stringField(record, 'ref');
+    if (ref !== `refs/dsh-turn-rewind/v2/${storeId}/${worktreeId}/${restorePointId}`) {
+        corrupt('Git checkpoint ref does not match its durable store/worktree/restore-point identity');
+    }
+    return {
+        objectFormat,
+        trust,
+        storeId,
+        worktreeId,
+        headTree: object('headTree'),
+        indexTree: object('indexTree'),
+        worktreeTree: object('worktreeTree'),
+        envelopeTree: object('envelopeTree'),
+        commit: object('commit'),
+        ref,
+        newlyStoredBytes: nonNegativeInteger(record, 'newlyStoredBytes'),
+    };
+}
+function hexIdentifier(record, key) {
+    const value = stringField(record, key);
+    if (!/^[0-9a-f]{32}$/.test(value))
+        corrupt(`${key} must be a 128-bit lowercase hexadecimal identifier`);
+    return value;
+}
+function validateGitObject(value) {
+    if (!GIT_OBJECT_PATTERN.test(value))
+        corrupt('invalid Git object id');
+    return value;
+}
 function objectRecord(value, label) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         corrupt(`${label} must be an object`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-turn-rewind",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Turn-level conversation and workspace rewind for DeepSeek Harness, powered by a persistent Change Ledger",
   "repository": {
     "type": "git",
@@ -39,6 +39,7 @@
   "files": [
     "lib",
     "src",
+    "scripts",
     "docs",
     "cordis.patch.yml",
     "README.md",
@@ -54,11 +55,24 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.1.0-rc.8 <0.2.0",
+      "dshReleases": {
+        "0.1.0-rc.8": "compatible",
+        "0.1.1-rc.1": "compatible",
+        "0.1.1-rc.2": "compatible"
+      },
+      "profiles": [
+        "web"
       ]
     }
   },
   "scripts": {
+    "benchmark:git-checkpoint": "pnpm run build && node scripts/benchmark-git-checkpoint.mjs",
     "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.client.json && node scripts/wrap-client.mjs",
     "check": "tsc -p tsconfig.json && pnpm run build && node --test tests/*.test.mjs && pnpm pack --dry-run",
     "prepack": "pnpm run build",
@@ -75,10 +89,14 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "@types/node": "^24.0.0",
     "@types/react": "18.3.28",
     "react": "18.3.1",

package/scripts/benchmark-git-checkpoint.mjs

@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { promisify } from 'node:util'
+import { ChangeLedgerEngine } from '../lib/index.js'
+
+const execFileAsync = promisify(execFile)
+const options = parseArgs(process.argv.slice(2))
+const outer = await mkdtemp(join(tmpdir(), 'dsh-turn-rewind-bench-'))
+const workspace = join(outer, 'workspace')
+const storageDir = join(outer, 'state')
+const result = {
+  fixture: options,
+  status: 'running',
+  captures: [],
+}
+
+try {
+  await mkdir(workspace)
+  await git(workspace, 'init', '-b', 'main')
+  await git(workspace, 'config', 'user.name', 'Turn Rewind Benchmark')
+  await git(workspace, 'config', 'user.email', 'turn-rewind-benchmark@example.invalid')
+  const content = Buffer.alloc(options.bytesPerFile, 0x61)
+  await parallelRange(options.files, 64, async (index) => {
+    const directory = join(workspace, 'fixture', String(Math.floor(index / 250)).padStart(4, '0'))
+    await mkdir(directory, { recursive: true })
+    await writeFile(join(directory, `${String(index).padStart(6, '0')}.bin`), content)
+  })
+  await git(workspace, 'add', '--all')
+  await git(workspace, 'commit', '-m', 'benchmark fixture')
+
+  const engine = new ChangeLedgerEngine({
+    storageDir,
+    turnCheckpointMode: 'git-native',
+    maxFiles: options.files + 100,
+    maxSnapshotBytes: options.files * options.bytesPerFile + 1024 * 1024,
+    turnCheckpointTimeoutMs: options.timeoutMs,
+    turnCheckpointMaxNewBytes: Math.max(options.dirtyFiles * options.bytesPerFile * 2, 1024 * 1024),
+  })
+  await engine.initialize()
+  result.captures.push(await measure(engine, workspace, 'clean', 1))
+  await parallelRange(options.dirtyFiles, 32, async (index) => {
+    const path = join(workspace, 'fixture', String(Math.floor(index / 250)).padStart(4, '0'), `${String(index).padStart(6, '0')}.bin`)
+    await writeFile(path, Buffer.alloc(options.bytesPerFile, 0x62))
+  })
+  result.captures.push(await measure(engine, workspace, 'dirty-cold-cache', 2))
+  result.captures.push(await measure(engine, workspace, 'dirty-warm-cache', 3))
+  const warmPoint = await engine.findTurnCheckpoint({ cwd: workspace, sessionId: 'benchmark-session', turn: 3 })
+  assert.notEqual(warmPoint, undefined)
+  const comparisonStarted = performance.now()
+  const inspection = await engine.inspect({ cwd: workspace, restorePointId: warmPoint.id })
+  assert.deepEqual(inspection.changes, [])
+  result.comparison = {
+    label: 'warm-checkpoint-vs-unchanged-worktree',
+    wallMs: Math.round((performance.now() - comparisonStarted) * 100) / 100,
+    changeCount: inspection.changes.length,
+  }
+
+  result.status = 'passed'
+} catch (error) {
+  result.status = 'failed'
+  result.error = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+  process.exitCode = 1
+} finally {
+  try {
+    await rm(outer, { recursive: true, force: true })
+    result.cleanup = 'passed'
+  } catch (error) {
+    result.cleanup = 'failed'
+    result.cleanupError = error instanceof Error ? error.message : String(error)
+    process.exitCode = 1
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+}
+
+async function measure(engine, workspace, label, turn) {
+  const statusBefore = await git(workspace, 'status', '--porcelain=v2', '--untracked-files=all')
+  const headsBefore = await git(workspace, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads')
+  const indexBefore = await readFile(join(workspace, '.git', 'index'))
+  const started = performance.now()
+  const point = await engine.createTurnCheckpoint({
+    cwd: workspace,
+    sessionId: 'benchmark-session',
+    turn,
+    turnStartSeq: turn * 4 - 3,
+  })
+  const manifest = await engine.store.readManifest(point.workspace, point.id)
+  assert.equal(manifest.version, 2)
+  assert.equal(await git(workspace, 'status', '--porcelain=v2', '--untracked-files=all'), statusBefore)
+  assert.equal(await git(workspace, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads'), headsBefore)
+  assert.deepEqual(await readFile(join(workspace, '.git', 'index')), indexBefore)
+  return {
+    label,
+    wallMs: Math.round((performance.now() - started) * 100) / 100,
+    fileCount: manifest.fileCount,
+    logicalBytes: manifest.totalBytes,
+    worktreeBytesRead: manifest.git.newlyStoredBytes,
+  }
+}
+
+async function git(cwd, ...args) {
+  const { stdout } = await execFileAsync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+  })
+  return stdout.trim()
+}
+
+async function parallelRange(count, concurrency, task) {
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(count, concurrency) }, async () => {
+    while (next < count) {
+      const current = next
+      next += 1
+      await task(current)
+    }
+  }))
+}
+
+function parseArgs(args) {
+  if (args[0] === '--') args = args.slice(1)
+  const values = { files: 15_500, bytesPerFile: 24 * 1024, dirtyFiles: 10, timeoutMs: 5_000 }
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index]
+    const raw = args[index + 1]
+    const key = {
+      '--files': 'files',
+      '--bytes-per-file': 'bytesPerFile',
+      '--dirty-files': 'dirtyFiles',
+      '--timeout-ms': 'timeoutMs',
+    }[flag]
+    if (key === undefined || raw === undefined || !/^\d+$/.test(raw)) usage()
+    values[key] = Number(raw)
+  }
+  if (!Number.isSafeInteger(values.files) || values.files <= 0
+    || !Number.isSafeInteger(values.bytesPerFile) || values.bytesPerFile <= 0
+    || !Number.isSafeInteger(values.dirtyFiles) || values.dirtyFiles < 0 || values.dirtyFiles > values.files
+    || !Number.isSafeInteger(values.timeoutMs) || values.timeoutMs <= 0) usage()
+  return values
+}
+
+function usage() {
+  process.stderr.write('usage: pnpm benchmark:git-checkpoint -- [--files N] [--bytes-per-file N] [--dirty-files N] [--timeout-ms N]\n')
+  process.exit(2)
+}

package/scripts/wrap-client.mjs

@@ -0,0 +1,18 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const built = new URL('../.client-build/index.js', import.meta.url)
+const builtMap = new URL('../.client-build/index.js.map', import.meta.url)
+const lib = new URL('../lib/', import.meta.url)
+const source = (await readFile(built, 'utf8')).replace(/\n?\/\/# sourceMappingURL=.*\n?$/, '\n')
+const sourceMap = JSON.parse(await readFile(builtMap, 'utf8'))
+sourceMap.file = 'client.js'
+sourceMap.sources = sourceMap.sources.map(sourcePath => `../src/client/${sourcePath.replace(/^\.\.\//, '')}`)
+const banner = 'window.__ModuleLoader__.load({ id: "@anionex/dsh-turn-rewind", factory: (require) => {\nvar module = { exports: {} }; var exports = module.exports;\n'
+const footer = '\nreturn module.exports; } });\n//# sourceMappingURL=client.js.map\n'
+
+await mkdir(lib, { recursive: true })
+await writeFile(join(fileURLToPath(lib), 'client.js'), `${banner}${source}${footer}`)
+await writeFile(join(fileURLToPath(lib), 'client.js.map'), `${JSON.stringify(sourceMap)}\n`)
+await rm(new URL('../.client-build/', import.meta.url), { recursive: true, force: true })