@anionex/dsh-turn-rewind 0.1.0

package/lib/types/rewind-host.d.ts

@@ -0,0 +1,137 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChangeLedgerEngine } from './engine.js';
+interface SessionEventLike {
+    readonly type: string;
+    readonly seq: number;
+    readonly data: Record<string, unknown>;
+}
+interface SessionHeaderLike {
+    readonly cwd?: string;
+    readonly parentSession?: string;
+    readonly seedLength?: number;
+}
+interface SessionLike {
+    readonly id: string;
+    readonly header: SessionHeaderLike;
+    readonly events: readonly SessionEventLike[];
+}
+interface AgentLike {
+    readonly id: string;
+    readonly status: 'idle' | 'running';
+    readonly session: SessionLike;
+}
+interface AgentsLike {
+    list(): AgentLike[];
+}
+interface SessionsLike {
+    get(id: string): SessionLike | undefined;
+}
+interface SessionQueryLike {
+    readSession(id: string): Promise<{
+        readonly session: SessionHeaderLike;
+        readonly events: readonly SessionEventLike[];
+    }>;
+}
+interface HttpRequestLike {
+    method?: string;
+    url?: string;
+    on(event: 'data', listener: (chunk: Uint8Array | string) => void): this;
+    on(event: 'end', listener: () => void): this;
+    on(event: 'error', listener: (error: unknown) => void): this;
+}
+interface HttpResponseLike {
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    end(body?: string): void;
+}
+interface HttpServerLike {
+    register(route: {
+        kind: 'exact';
+        path: string;
+        handler: (request: HttpRequestLike, response: HttpResponseLike) => void | Promise<void>;
+    }): () => void;
+}
+interface ApiProxyLike {
+    readonly sessions: {
+        create(request: {
+            readonly rpcId: string;
+            readonly payload: {
+                readonly cwd: string;
+            };
+        }): Promise<{
+            readonly result: {
+                readonly ok: true;
+                readonly value: {
+                    readonly sessionId: string;
+                };
+            } | {
+                readonly ok: false;
+                readonly error: {
+                    readonly message: string;
+                };
+            };
+        }>;
+        fork(request: {
+            readonly rpcId: string;
+            readonly payload: {
+                readonly sessionId: string;
+                readonly atSeq: number;
+            };
+        }): Promise<{
+            readonly result: {
+                readonly ok: true;
+                readonly value: {
+                    readonly sessionId: string;
+                };
+            } | {
+                readonly ok: false;
+                readonly error: {
+                    readonly message: string;
+                };
+            };
+        }>;
+    };
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agents: AgentsLike;
+        sessions: SessionsLike;
+        sessionQuery: SessionQueryLike;
+        webServer: HttpServerLike;
+        apiProxy: ApiProxyLike;
+    }
+    interface Events {
+        'agent/pre-step'(payload: {
+            readonly agent: AgentLike;
+            readonly turn: number;
+            readonly step: number;
+            readonly signal: AbortSignal;
+        }, next: () => Promise<unknown>): Promise<unknown>;
+    }
+}
+export declare const REWIND_HTTP_PATH = "/turn-rewind";
+/** Capture each turn before its opening user message can trigger model or tool work. */
+export declare class TurnCheckpointCoordinator {
+    private readonly engine;
+    private readonly captures;
+    private readonly pending;
+    private readonly failures;
+    private readonly workspaceTails;
+    constructor(engine: ChangeLedgerEngine);
+    /** Install the first-step gate; checkpoint failures are recorded but never reject the user turn. */
+    install(ctx: Context): void;
+    /** 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;
+    };
+    private capture;
+    private serializeWorkspace;
+    private recordFailure;
+}
+/** Register the same-origin preview/apply endpoint consumed by the browser half. */
+export declare function installRewindHttp(ctx: Context, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): void;
+/** Build the exact-route handler as a testable unit. */
+export declare function createRewindHttpHandler(ctx: Pick<Context, 'sessions' | 'sessionQuery' | 'apiProxy'> & {
+    readonly agents?: AgentsLike;
+}, engine: ChangeLedgerEngine, coordinator: TurnCheckpointCoordinator): (request: HttpRequestLike, response: HttpResponseLike) => Promise<void>;
+export {};

package/lib/types/snapshot.d.ts

@@ -0,0 +1,35 @@
+import { type RepositorySnapshotSource } from './git.js';
+import type { LedgerStore } from './store.js';
+import type { ResolvedChangeLedgerConfig, SnapshotEntry, WorkspaceChange } from './types.js';
+/** One captured tree, optionally persisted into the blob store. */
+export interface CapturedTree {
+    readonly source: RepositorySnapshotSource;
+    readonly entries: Readonly<Record<string, SnapshotEntry>>;
+    readonly treeHash: string;
+    readonly fileCount: number;
+    readonly totalBytes: number;
+}
+/** Capture the current tracked and non-ignored Git working tree. */
+export declare function captureTree(options: {
+    readonly cwd: string;
+    readonly config: ResolvedChangeLedgerConfig;
+    readonly store?: LedgerStore;
+    readonly signal?: AbortSignal;
+}): Promise<CapturedTree>;
+/**
+ * Capture the complete tree twice and accept it only when both path/content and
+ * repository fences agree. This prevents a point from silently mixing files
+ * observed at incompatible moments while another process is editing the tree.
+ */
+export declare function captureStableTree(options: {
+    readonly cwd: string;
+    readonly config: ResolvedChangeLedgerConfig;
+    readonly store?: LedgerStore;
+    readonly signal?: AbortSignal;
+}): Promise<CapturedTree>;
+/** Compute stable path-level differences between two captured trees. */
+export declare function diffTrees(before: Readonly<Record<string, SnapshotEntry>>, after: Readonly<Record<string, SnapshotEntry>>): WorkspaceChange[];
+/** Return whether two snapshot entries are byte/type/mode equivalent. */
+export declare function entriesEqual(left: SnapshotEntry | undefined, right: SnapshotEntry | undefined): boolean;
+/** Hash a complete path map into a deterministic tree identity. */
+export declare function hashTree(entries: Readonly<Record<string, SnapshotEntry>>): string;

package/lib/types/store.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedChangeLedgerConfig, RestoreOperation, RestorePointManifest } from './types.js';
+/** Durable content-addressed storage and per-workspace locking. */
+export declare class LedgerStore {
+    readonly config: ResolvedChangeLedgerConfig;
+    constructor(config: ResolvedChangeLedgerConfig);
+    /** Create the state root and reconcile crash-interrupted operations. */
+    initialize(): Promise<number>;
+    /** Acquire the exclusive lock for one canonical workspace. */
+    acquire(workspace: string): Promise<() => Promise<void>>;
+    /** Persist a blob if it is not already present, and verify existing content. */
+    putBlob(workspace: string, hash: string, content: Buffer): Promise<void>;
+    /** Read and verify one content-addressed blob. */
+    readBlob(workspace: string, hash: string): Promise<Buffer>;
+    /** Write one restore-point manifest atomically. */
+    writeManifest(manifest: RestorePointManifest): Promise<void>;
+    /** Load and validate one restore-point manifest. */
+    readManifest(workspace: string, id: string): Promise<RestorePointManifest>;
+    /** List all validated restore points for one workspace, newest first. */
+    listManifests(workspace: string): Promise<RestorePointManifest[]>;
+    /** Delete one restore-point manifest. Blobs remain until garbage collection succeeds. */
+    deleteManifest(workspace: string, id: string): Promise<void>;
+    /** Persist one restore-operation journal. */
+    writeOperation(operation: RestoreOperation): Promise<void>;
+    /** List validated restore operations for one workspace. */
+    listOperations(workspace: string): Promise<RestoreOperation[]>;
+    /** Return whether an incomplete operation still references a restore point. */
+    isReferencedByRecovery(workspace: string, restorePointId: string): Promise<boolean>;
+    /** Delete blobs not referenced by any remaining manifest. */
+    collectGarbage(workspace: string, additionalReferenced?: Iterable<string>): Promise<{
+        deletedBlobs: number;
+        retainedBlobs: number;
+    }>;
+    private workspaceDir;
+    private manifestPath;
+    private operationPath;
+    private blobPath;
+    private reclaimStaleLock;
+    private workspaceAppearsActive;
+}

package/lib/types/types.d.ts

@@ -0,0 +1,177 @@
+/** Durable format version. Readers reject every other version. */
+export declare const LEDGER_FORMAT_VERSION: 1;
+/** 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/lib/types/validate.d.ts

@@ -0,0 +1,11 @@
+import { type RestoreOperation, type RestorePointManifest } from './types.js';
+/** Validate a restore-point id before using it in a filesystem path. */
+export declare function validateRestorePointId(value: string): string;
+/** Validate a restore-operation id before using it in a filesystem path. */
+export declare function validateOperationId(value: string): string;
+/** Parse an untrusted durable restore-point manifest. */
+export declare function parseManifest(value: unknown): RestorePointManifest;
+/** Parse an untrusted durable restore-operation journal. */
+export declare function parseOperation(value: unknown): RestoreOperation;
+/** Validate one SHA-256 blob name. */
+export declare function validateBlobHash(value: string): string;

package/lib/types.js

@@ -0,0 +1,2 @@
+/** Durable format version. Readers reject every other version. */
+export const LEDGER_FORMAT_VERSION = 1;

package/lib/validate.js

@@ -0,0 +1,242 @@
+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';
+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) {
+    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) {
+    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) {
+    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 = Object.create(null);
+    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) {
+    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) {
+    if (!HASH_PATTERN.test(value)) {
+        throw new ChangeLedgerError('STATE_CORRUPT', `invalid blob hash ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseRepository(value) {
+    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, path) {
+    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, label) {
+    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;
+}
+function stringField(record, key) {
+    return requireString(record[key], key);
+}
+function requireString(value, label) {
+    if (typeof value !== 'string' || value === '')
+        corrupt(`${label} must be a non-empty string`);
+    return value;
+}
+function optionalString(record, key) {
+    const value = record[key];
+    return value === undefined ? undefined : requireString(value, key);
+}
+function absoluteString(record, key) {
+    const value = stringField(record, key);
+    if (!isAbsolute(value))
+        corrupt(`${key} must be an absolute path`);
+    return value;
+}
+function hashField(record, key) {
+    return validateBlobHash(stringField(record, key));
+}
+function optionalHash(record, key) {
+    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, key) {
+    const value = record[key];
+    if (!Number.isSafeInteger(value) || value < 0)
+        corrupt(`${key} must be a non-negative safe integer`);
+    return value;
+}
+function optionalNonNegativeInteger(record, key) {
+    return record[key] === undefined ? undefined : nonNegativeInteger(record, key);
+}
+function corrupt(message) {
+    throw new ChangeLedgerError('STATE_CORRUPT', message);
+}