@anionex/dsh-turn-rewind 0.1.1 → 0.2.0

package/src/types.ts

@@ -1,6 +1,9 @@
 /** Durable format version. Readers reject every other version. */
 export const LEDGER_FORMAT_VERSION = 1 as const
 
+/** Git-native checkpoint format used by bounded automatic turn capture. */
+export const GIT_CHECKPOINT_FORMAT_VERSION = 2 as const
+
 /** A persisted restore-point identifier. */
 export type RestorePointId = string
 
@@ -16,6 +19,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. */
@@ -42,7 +47,7 @@ export interface RepositoryState {
 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
@@ -66,6 +71,34 @@ export interface RestorePointManifest {
   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
@@ -89,6 +122,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
@@ -108,6 +142,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. */
@@ -168,6 +203,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. */
@@ -180,6 +223,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. */
@@ -193,3 +240,24 @@ 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/src/validate.ts

@@ -3,9 +3,11 @@ import { isAbsolute } from 'node:path'
 import { validateRelativePath } from './path-utils.js'
 import { hashTree } from './snapshot.js'
 import {
+  GIT_CHECKPOINT_FORMAT_VERSION,
   LEDGER_FORMAT_VERSION,
   type RepositoryState,
   type RestoreOperation,
+  type RestorePointKind,
   type RestorePointManifest,
   type SnapshotEntry,
 } from './types.js'
@@ -33,13 +35,17 @@ export function validateOperationId(value: string): string {
 /** Parse an untrusted durable restore-point manifest. */
 export function parseManifest(value: unknown): RestorePointManifest {
   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: RestorePointKind = kind
   const workspace = absoluteString(record, 'workspace')
   const repository = parseRepository(record.repository)
   if (repository.root !== workspace) corrupt('repository.root must equal workspace')
@@ -48,7 +54,7 @@ export function parseManifest(value: unknown): RestorePointManifest {
   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
   }
@@ -75,10 +81,9 @@ export function parseManifest(value: unknown): RestorePointManifest {
     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 }),
@@ -95,6 +100,9 @@ export function parseManifest(value: unknown): RestorePointManifest {
     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. */
@@ -170,17 +178,25 @@ function parseRepository(value: unknown): RepositoryState {
   }
 }
 
-function parseEntry(value: unknown, path: string): SnapshotEntry {
+function parseEntry(
+  value: unknown,
+  path: string,
+  version: typeof LEDGER_FORMAT_VERSION | typeof GIT_CHECKPOINT_FORMAT_VERSION,
+): SnapshotEntry {
   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' as const } : {}),
     }
   }
   if (kind === 'symlink') {
@@ -191,6 +207,50 @@ function parseEntry(value: unknown, path: string): SnapshotEntry {
   corrupt(`invalid snapshot entry kind for ${JSON.stringify(path)}`)
 }
 
+function parseGitCheckpoint(value: unknown, restorePointId: string) {
+  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: string) => {
+    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'),
+  } as const
+}
+
+function hexIdentifier(record: Record<string, unknown>, key: string): string {
+  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: string): string {
+  if (!GIT_OBJECT_PATTERN.test(value)) corrupt('invalid Git object id')
+  return value
+}
+
 function objectRecord(value: unknown, label: string): Record<string, unknown> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) corrupt(`${label} must be an object`)
   const prototype = Object.getPrototypeOf(value)