@anionex/dsh-turn-rewind 0.1.0

package/src/types.ts

@@ -0,0 +1,195 @@
+/** Durable format version. Readers reject every other version. */
+export const LEDGER_FORMAT_VERSION = 1 as const
+
+/** A persisted restore-point identifier. */
+export type RestorePointId = string
+
+/** A persisted restore-operation identifier. */
+export type RestoreOperationId = string
+
+/** An in-memory, expiring restore-plan identifier. */
+export type RestorePlanId = string
+
+/** One regular-file snapshot. */
+export interface FileSnapshotEntry {
+  readonly kind: 'file'
+  readonly blob: string
+  readonly size: number
+  readonly mode: number
+}
+
+/** One symbolic-link snapshot. */
+export interface SymlinkSnapshotEntry {
+  readonly kind: 'symlink'
+  readonly target: string
+  readonly mode: number
+}
+
+/** One path captured by a restore point. */
+export type SnapshotEntry = FileSnapshotEntry | SymlinkSnapshotEntry
+
+/** Git facts that fence a restore point to the repository state it observed. */
+export interface RepositoryState {
+  readonly root: string
+  readonly commonDir: string
+  readonly head?: string
+  readonly branch?: string
+  readonly operation?: string
+  readonly stagedPaths: readonly string[]
+}
+
+/** Why a restore point exists. */
+export type RestorePointKind = 'user' | 'rescue' | 'turn'
+
+/** Durable workspace restore point. */
+export interface RestorePointManifest {
+  readonly version: typeof LEDGER_FORMAT_VERSION
+  readonly id: RestorePointId
+  readonly kind: RestorePointKind
+  readonly workspace: string
+  readonly repository: RepositoryState
+  readonly sessionId?: string
+  readonly label?: string
+  readonly parentRestorePoint?: RestorePointId
+  /** DSH turn whose opening user request owns this automatic Web rewind checkpoint. */
+  readonly turn?: number
+  /** Inclusive `turn/start` event sequence; the snapshot was captured before the turn entered its first step. */
+  readonly turnStartSeq?: number
+  /** Legacy inclusive `turn/end` event sequence used by checkpoints created before prompt-anchored rewind. */
+  readonly turnEndSeq?: number
+  readonly createdAt: number
+  readonly treeHash: string
+  readonly fileCount: number
+  readonly totalBytes: number
+  readonly entries: Readonly<Record<string, SnapshotEntry>>
+  readonly restoreCount: number
+  readonly lastRestoredAt?: number
+}
+
+/** Observable difference between a restore point and the current workspace. */
+export interface WorkspaceChange {
+  readonly path: string
+  readonly kind: 'added' | 'deleted' | 'modified' | 'mode-changed' | 'type-changed'
+  readonly before?: SnapshotEntry
+  readonly after?: SnapshotEntry
+}
+
+/** Result of comparing one restore point with its workspace. */
+export interface RestorePointInspection {
+  readonly restorePoint: RestorePointSummary
+  readonly currentTreeHash: string
+  readonly currentRepository: RepositoryState
+  readonly currentHead?: string
+  readonly currentBranch?: string
+  readonly currentOperation?: string
+  readonly headChanged: boolean
+  readonly operationChanged: boolean
+  readonly changes: readonly WorkspaceChange[]
+}
+
+/** Compact restore-point metadata for lists and tool results. */
+export interface RestorePointSummary {
+  readonly id: RestorePointId
+  readonly kind: RestorePointKind
+  readonly workspace: string
+  readonly sessionId?: string
+  readonly label?: string
+  readonly parentRestorePoint?: RestorePointId
+  readonly turn?: number
+  readonly turnStartSeq?: number
+  readonly turnEndSeq?: number
+  readonly createdAt: number
+  readonly treeHash: string
+  readonly fileCount: number
+  readonly totalBytes: number
+  readonly restoreCount: number
+  readonly lastRestoredAt?: number
+  readonly head?: string
+  readonly branch?: string
+  readonly operation?: string
+  readonly stagedPathCount: number
+}
+
+/** An expiring restore plan whose confirmation must be echoed exactly. */
+export interface RestorePlan {
+  readonly id: RestorePlanId
+  readonly restorePointId: RestorePointId
+  readonly workspace: string
+  readonly repository: RepositoryState
+  readonly sessionId?: string
+  readonly createdAt: number
+  readonly expiresAt: number
+  readonly confirmation: string
+  readonly allowHeadChange: boolean
+  readonly paths: readonly string[]
+  readonly changes: readonly WorkspaceChange[]
+  readonly expected: Readonly<Record<string, SnapshotEntry | null>>
+}
+
+/** Durable journal for one attempted restore. */
+export interface RestoreOperation {
+  readonly version: typeof LEDGER_FORMAT_VERSION
+  readonly id: RestoreOperationId
+  readonly workspace: string
+  readonly restorePointId: RestorePointId
+  readonly rescuePointId: RestorePointId
+  readonly sessionId?: string
+  readonly paths: readonly string[]
+  readonly startedAt: number
+  readonly finishedAt?: number
+  readonly state: 'running' | 'rollback-running' | 'completed' | 'rolled-back' | 'interrupted' | 'recovery-required'
+  readonly error?: string
+  readonly rollbackError?: string
+}
+
+/** A completed restore result. */
+export interface RestoreResult {
+  readonly operationId: RestoreOperationId
+  readonly restorePointId: RestorePointId
+  readonly rescuePointId: RestorePointId
+  readonly restoredPaths: readonly string[]
+}
+
+/** Public plugin configuration. */
+export interface ChangeLedgerConfig {
+  /** State directory. Must live outside every managed workspace. */
+  readonly storageDir?: string
+  /** Maximum user and rescue restore points retained per workspace. */
+  readonly maxRestorePoints?: number
+  /** Maximum automatic turn checkpoints retained per session. */
+  readonly maxTurnCheckpointsPerSession?: number
+  /** Maximum number of files in one restore point. */
+  readonly maxFiles?: number
+  /** Maximum bytes read from one regular file. */
+  readonly maxFileBytes?: number
+  /** Maximum aggregate regular-file bytes in one restore point. */
+  readonly maxSnapshotBytes?: number
+  /** Restore-plan lifetime in milliseconds. */
+  readonly planTtlMs?: number
+  /** Age after which a lock whose owner is gone may be reclaimed. */
+  readonly staleLockMs?: number
+}
+
+/** Fully resolved plugin configuration. */
+export interface ResolvedChangeLedgerConfig {
+  readonly storageDir: string
+  readonly maxRestorePoints: number
+  readonly maxTurnCheckpointsPerSession: number
+  readonly maxFiles: number
+  readonly maxFileBytes: number
+  readonly maxSnapshotBytes: number
+  readonly planTtlMs: number
+  readonly staleLockMs: number
+}
+
+/** Current incomplete restore operation. */
+export interface RecoverySummary {
+  readonly operationId: RestoreOperationId
+  readonly restorePointId: RestorePointId
+  readonly rescuePointId: RestorePointId
+  readonly state: 'interrupted' | 'recovery-required'
+  readonly paths: readonly string[]
+  readonly startedAt: number
+  readonly error?: string
+  readonly rollbackError?: string
+}

package/src/validate.ts

@@ -0,0 +1,245 @@
+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,
+  type RepositoryState,
+  type RestoreOperation,
+  type RestorePointManifest,
+  type SnapshotEntry,
+} 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}$/
+
+/** Validate a restore-point id before using it in a filesystem path. */
+export function validateRestorePointId(value: string): string {
+  if (!ID_PATTERN.test(value) || !value.startsWith('rp_')) {
+    throw new ChangeLedgerError('INVALID_RESTORE_POINT_ID', `invalid restore-point id ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/** Validate a restore-operation id before using it in a filesystem path. */
+export function validateOperationId(value: string): string {
+  if (!ID_PATTERN.test(value) || !value.startsWith('op_')) {
+    throw new ChangeLedgerError('INVALID_OPERATION_ID', `invalid restore-operation id ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+/** 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 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 workspace = absoluteString(record, 'workspace')
+  const repository = parseRepository(record.repository)
+  if (repository.root !== workspace) corrupt('repository.root must equal workspace')
+  const entriesRecord = objectRecord(record.entries, 'restore-point entries')
+  const entries: Record<string, SnapshotEntry> = Object.create(null) as Record<string, SnapshotEntry>
+  let totalBytes = 0
+  for (const [path, entryValue] of Object.entries(entriesRecord)) {
+    validateRelativePath(path)
+    const entry = parseEntry(entryValue, path)
+    entries[path] = entry
+    if (entry.kind === 'file') totalBytes += entry.size
+  }
+  const fileCount = nonNegativeInteger(record, 'fileCount')
+  if (fileCount !== Object.keys(entries).length) corrupt('restore-point fileCount does not match entries')
+  const storedTotal = nonNegativeInteger(record, 'totalBytes')
+  if (storedTotal !== totalBytes) corrupt('restore-point totalBytes does not match entries')
+  const treeHash = hashField(record, 'treeHash')
+  if (treeHash !== hashTree(entries)) corrupt('restore-point treeHash does not match entries')
+  const createdAt = nonNegativeInteger(record, 'createdAt')
+  const restoreCount = nonNegativeInteger(record, 'restoreCount')
+  const sessionId = optionalString(record, 'sessionId')
+  const label = optionalString(record, 'label')
+  const parentRestorePoint = optionalString(record, 'parentRestorePoint')
+  if (parentRestorePoint !== undefined) validateRestorePointId(parentRestorePoint)
+  const turn = optionalNonNegativeInteger(record, 'turn')
+  const turnStartSeq = optionalNonNegativeInteger(record, 'turnStartSeq')
+  const turnEndSeq = optionalNonNegativeInteger(record, 'turnEndSeq')
+  if (kind === 'turn') {
+    if (sessionId === undefined || turn === undefined || (turnStartSeq === undefined) === (turnEndSeq === undefined)) {
+      corrupt('turn restore points require sessionId, turn, and exactly one turn boundary')
+    }
+  } else if (turn !== undefined || turnStartSeq !== undefined || turnEndSeq !== undefined) {
+    corrupt('only turn restore points may carry turn metadata')
+  }
+  const lastRestoredAt = optionalNonNegativeInteger(record, 'lastRestoredAt')
+  return {
+    version: LEDGER_FORMAT_VERSION,
+    id,
+    kind,
+    workspace,
+    repository,
+    ...(sessionId === undefined ? {} : { sessionId }),
+    ...(label === undefined ? {} : { label }),
+    ...(parentRestorePoint === undefined ? {} : { parentRestorePoint }),
+    ...(turn === undefined ? {} : { turn }),
+    ...(turnStartSeq === undefined ? {} : { turnStartSeq }),
+    ...(turnEndSeq === undefined ? {} : { turnEndSeq }),
+    createdAt,
+    treeHash,
+    fileCount,
+    totalBytes,
+    entries,
+    restoreCount,
+    ...(lastRestoredAt === undefined ? {} : { lastRestoredAt }),
+  }
+}
+
+/** Parse an untrusted durable restore-operation journal. */
+export function parseOperation(value: unknown): RestoreOperation {
+  const record = objectRecord(value, 'restore operation')
+  if (record.version !== LEDGER_FORMAT_VERSION) corrupt(`unsupported restore-operation version ${String(record.version)}`)
+  const id = stringField(record, 'id')
+  validateOperationId(id)
+  const restorePointId = stringField(record, 'restorePointId')
+  const rescuePointId = stringField(record, 'rescuePointId')
+  validateRestorePointId(restorePointId)
+  validateRestorePointId(rescuePointId)
+  const workspace = absoluteString(record, 'workspace')
+  const pathsValue = record.paths
+  if (!Array.isArray(pathsValue)) corrupt('restore-operation paths must be an array')
+  const paths = pathsValue.map((path) => validateRelativePath(requireString(path, 'restore-operation path')))
+  if (new Set(paths).size !== paths.length) corrupt('restore-operation paths contain duplicates')
+  const state = record.state
+  if (state !== 'running'
+    && state !== 'rollback-running'
+    && state !== 'completed'
+    && state !== 'rolled-back'
+    && state !== 'interrupted'
+    && state !== 'recovery-required') {
+    corrupt(`invalid restore-operation state ${JSON.stringify(state)}`)
+  }
+  const sessionId = optionalString(record, 'sessionId')
+  const startedAt = nonNegativeInteger(record, 'startedAt')
+  const finishedAt = optionalNonNegativeInteger(record, 'finishedAt')
+  const error = optionalString(record, 'error')
+  const rollbackError = optionalString(record, 'rollbackError')
+  return {
+    version: LEDGER_FORMAT_VERSION,
+    id,
+    workspace,
+    restorePointId,
+    rescuePointId,
+    ...(sessionId === undefined ? {} : { sessionId }),
+    paths,
+    startedAt,
+    ...(finishedAt === undefined ? {} : { finishedAt }),
+    state,
+    ...(error === undefined ? {} : { error }),
+    ...(rollbackError === undefined ? {} : { rollbackError }),
+  }
+}
+
+/** Validate one SHA-256 blob name. */
+export function validateBlobHash(value: string): string {
+  if (!HASH_PATTERN.test(value)) {
+    throw new ChangeLedgerError('STATE_CORRUPT', `invalid blob hash ${JSON.stringify(value)}`)
+  }
+  return value
+}
+
+function parseRepository(value: unknown): RepositoryState {
+  const record = objectRecord(value, 'repository state')
+  const root = absoluteString(record, 'root')
+  const commonDir = absoluteString(record, 'commonDir')
+  const head = optionalHash(record, 'head')
+  const branch = optionalString(record, 'branch')
+  const operation = optionalString(record, 'operation')
+  const stagedValue = record.stagedPaths
+  if (!Array.isArray(stagedValue)) corrupt('repository stagedPaths must be an array')
+  const stagedPaths = stagedValue.map((path) => validateRelativePath(requireString(path, 'staged path')))
+  return {
+    root,
+    commonDir,
+    ...(head === undefined ? {} : { head }),
+    ...(branch === undefined ? {} : { branch }),
+    ...(operation === undefined ? {} : { operation }),
+    stagedPaths,
+  }
+}
+
+function parseEntry(value: unknown, path: string): 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') {
+    return {
+      kind,
+      blob: validateBlobHash(stringField(record, 'blob')),
+      size: nonNegativeInteger(record, 'size'),
+      mode,
+    }
+  }
+  if (kind === 'symlink') {
+    const target = stringField(record, 'target')
+    if (target.includes('\0')) corrupt(`snapshot symlink target contains a NUL byte for ${JSON.stringify(path)}`)
+    return { kind, target, mode }
+  }
+  corrupt(`invalid snapshot entry kind for ${JSON.stringify(path)}`)
+}
+
+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)
+  if (prototype !== Object.prototype && prototype !== null) corrupt(`${label} must be a plain object`)
+  return value as Record<string, unknown>
+}
+
+function stringField(record: Record<string, unknown>, key: string): string {
+  return requireString(record[key], key)
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value === '') corrupt(`${label} must be a non-empty string`)
+  return value
+}
+
+function optionalString(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key]
+  return value === undefined ? undefined : requireString(value, key)
+}
+
+function absoluteString(record: Record<string, unknown>, key: string): string {
+  const value = stringField(record, key)
+  if (!isAbsolute(value)) corrupt(`${key} must be an absolute path`)
+  return value
+}
+
+function hashField(record: Record<string, unknown>, key: string): string {
+  return validateBlobHash(stringField(record, key))
+}
+
+function optionalHash(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key]
+  if (value === undefined) return undefined
+  const hash = requireString(value, key)
+  if (!GIT_OBJECT_PATTERN.test(hash)) corrupt(`${key} must be a Git object id`)
+  return hash
+}
+
+function nonNegativeInteger(record: Record<string, unknown>, key: string): number {
+  const value = record[key]
+  if (!Number.isSafeInteger(value) || (value as number) < 0) corrupt(`${key} must be a non-negative safe integer`)
+  return value as number
+}
+
+function optionalNonNegativeInteger(record: Record<string, unknown>, key: string): number | undefined {
+  return record[key] === undefined ? undefined : nonNegativeInteger(record, key)
+}
+
+function corrupt(message: string): never {
+  throw new ChangeLedgerError('STATE_CORRUPT', message)
+}