mecord-connect 1.0.0

package/runtime/app/src/capabilities/filesystem.js

@@ -0,0 +1,264 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { PathScope } from './path-scope.js';
+
+function sha256(buffer            )         {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+const DEFAULT_MAX_READ_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_WRITE_BYTES = 2 * 1024 * 1024;
+const MAX_CONFIGURED_IO_BYTES = 64 * 1024 * 1024;
+
+const SCORE                  = {
+  reliability: 0.98,
+  latency: 0.97,
+  determinism: 0.99,
+  security: 0.96,
+  reversibility: 0.78,
+  informationQuality: 0.99,
+  interactionCost: 0.01
+};
+
+export class FilesystemProvider                               {
+           name = 'filesystem.native';
+  #scope           ;
+  #maxReadBytes        ;
+  #maxWriteBytes        ;
+  #replaceClaimHook                                             ;
+  #pathLeaseHook                                                                 ;
+
+  constructor(options   
+                           
+                          
+                           
+                                                                  
+                                                                                   
+                                        
+   ) {
+    this.#scope = new PathScope(options.allowedRoots, { windowsPathLeaseExecutable: options.windowsPathLeaseExecutable });
+    this.#maxReadBytes = boundedBytes(options.maxReadBytes, DEFAULT_MAX_READ_BYTES);
+    this.#maxWriteBytes = boundedBytes(options.maxWriteBytes, DEFAULT_MAX_WRITE_BYTES);
+    this.#replaceClaimHook = options.replaceClaimHook;
+    this.#pathLeaseHook = options.pathLeaseHook;
+  }
+
+  supports(action               )          {
+    return ['file.read', 'file.list', 'file.write', 'file.create', 'file.replace'].includes(action.capability);
+  }
+
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    try {
+      if (action.capability === 'file.read') return await this.#read(action, started);
+      if (action.capability === 'file.list') return await this.#list(action, started);
+      if (['file.write', 'file.create', 'file.replace'].includes(action.capability)) return await this.#write(action, started);
+      throw new OperatorError('UNSUPPORTED_ACTION', action.capability);
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('FILESYSTEM_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('filesystem', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  async #read(action               , started        )                        {
+    const requested = requiredString(action.input.path, 'path');
+    return await this.#scope.withExisting(requested, async (filePath) => {
+      await this.#pathLeaseHook?.(action.capability, filePath);
+      const stat = await fs.stat(filePath);
+      if (!stat.isFile()) throw new OperatorError('NOT_A_FILE', 'Requested path is not a file.');
+      if (stat.size > this.#maxReadBytes) {
+        throw new OperatorError('READ_TOO_LARGE', `File exceeds ${this.#maxReadBytes} byte read limit.`, { details: { size: stat.size } });
+      }
+      const data = await fs.readFile(filePath);
+      const encoding = action.input.encoding === 'base64' ? 'base64' : 'utf8';
+      const digest = sha256(data);
+      return {
+        ok: true,
+        capability: action.capability,
+        provider: this.name,
+        output: { path: filePath, size: data.byteLength, sha256: digest, content: data.toString(encoding) },
+        evidence: [evidence('file_read', 'pass', 'File read from authorized scope.', { path: filePath, size: data.byteLength, sha256: digest })],
+        durationMs: Math.round(performance.now() - started)
+      };
+    });
+  }
+
+  async #list(action               , started        )                        {
+    const requested = requiredString(action.input.path, 'path');
+    return await this.#scope.withExisting(requested, async (dirPath) => {
+      await this.#pathLeaseHook?.(action.capability, dirPath);
+      const stat = await fs.stat(dirPath);
+      if (!stat.isDirectory()) throw new OperatorError('NOT_A_DIRECTORY', 'Requested path is not a directory.');
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      const bounded = entries.slice(0, 500).map((entry) => ({
+        name: entry.name,
+        type: entry.isDirectory() ? 'directory' : entry.isFile() ? 'file' : entry.isSymbolicLink() ? 'symlink' : 'other'
+      }));
+      return {
+        ok: true,
+        capability: action.capability,
+        provider: this.name,
+        output: { path: dirPath, entries: bounded, truncated: entries.length > bounded.length },
+        evidence: [evidence('directory_list', 'pass', 'Directory listed from authorized scope.', { path: dirPath, count: bounded.length })],
+        durationMs: Math.round(performance.now() - started)
+      };
+    });
+  }
+
+  async #write(action               , started        )                        {
+    const requested = requiredString(action.input.path, 'path');
+    if (typeof action.input.content !== 'string') throw new OperatorError('WRITE_CONTENT_INVALID', 'File content must be a string.');
+    const content = action.input.content;
+    const contentBytes = Buffer.byteLength(content, 'utf8');
+    if (contentBytes > this.#maxWriteBytes) {
+      throw new OperatorError('WRITE_TOO_LARGE', `Content exceeds ${this.#maxWriteBytes} byte write limit.`, { details: { size: contentBytes } });
+    }
+    const expectedSha = normalizeExpectedSha(action.input.expectedSha256);
+    const mode = action.capability === 'file.create' ? 'create' : action.capability === 'file.replace' ? 'replace' : 'write';
+    if (mode === 'replace' && !expectedSha) {
+      throw new OperatorError('PRECONDITION_REQUIRED', 'file.replace requires expectedSha256 from a fresh file.read.');
+    }
+
+    return await this.#scope.withForWrite(requested, async (filePath) => {
+      await this.#pathLeaseHook?.(action.capability, filePath);
+      let beforeSha                = null;
+      try {
+        const targetStat = await fs.lstat(filePath);
+        if (targetStat.isSymbolicLink()) {
+          throw new OperatorError('WRITE_SYMLINK_DENIED', 'Refusing to write through or replace an existing symbolic link.');
+        }
+        if (!targetStat.isFile()) throw new OperatorError('NOT_A_FILE', 'Existing write target is not a regular file.');
+        if (mode === 'create') throw new OperatorError('TARGET_EXISTS', 'file.create refuses to overwrite an existing file.');
+        const before = await fs.readFile(filePath);
+        beforeSha = sha256(before);
+        if (expectedSha && expectedSha !== beforeSha) {
+          throw new OperatorError('PRECONDITION_FAILED', 'File changed since it was inspected.', { details: { expectedSha, actualSha: beforeSha } });
+        }
+      } catch (error) {
+        if (error instanceof OperatorError) throw error;
+        const code = (error                         ).code;
+        if (code !== 'ENOENT') throw error;
+        if (mode === 'replace') throw new OperatorError('TARGET_MISSING', 'file.replace requires an existing file.');
+        if (expectedSha) throw new OperatorError('PRECONDITION_FAILED', 'Expected existing file is missing.');
+      }
+
+      const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.operator-${crypto.randomUUID()}.tmp`);
+      let renamed = false;
+      try {
+        await fs.writeFile(tempPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        if (mode === 'create') {
+          await fs.writeFile(filePath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+          await fs.rm(tempPath, { force: true });
+        } else if (mode === 'replace') {
+          beforeSha = await replaceWithExpectedSha(filePath, tempPath, expectedSha , this.#replaceClaimHook);
+        } else {
+          await fs.rename(tempPath, filePath);
+        }
+        renamed = true;
+      } finally {
+        if (!renamed) await fs.rm(tempPath, { force: true }).catch(() => undefined);
+      }
+
+      const after = await fs.readFile(filePath);
+      const afterSha = sha256(after);
+      if (afterSha !== sha256(Buffer.from(content, 'utf8'))) {
+        throw new OperatorError('WRITE_POSTCONDITION_FAILED', 'Written bytes do not match requested content.');
+      }
+
+      return {
+        ok: true,
+        capability: action.capability,
+        provider: this.name,
+        output: { path: filePath, bytes: after.byteLength, beforeSha256: beforeSha, afterSha256: afterSha },
+        evidence: [
+          evidence('file_write', 'pass', 'Atomic file write completed inside authorized scope.', { path: filePath }),
+          evidence('postcondition', 'pass', 'Written bytes match requested content.', { afterSha256: afterSha, bytes: after.byteLength })
+        ],
+        durationMs: Math.round(performance.now() - started)
+      };
+    });
+  }
+}
+
+function requiredString(value         , field        )         {
+  if (typeof value !== 'string' || value.length === 0 || value.includes('\0')) {
+    throw new OperatorError('FILESYSTEM_INPUT_INVALID', `${field} must be a non-empty string without NUL bytes.`);
+  }
+  return value;
+}
+
+function normalizeExpectedSha(value         )                     {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' || !/^[0-9a-f]{64}$/i.test(value)) {
+    throw new OperatorError('PRECONDITION_INVALID', 'expectedSha256 must be exactly 64 hexadecimal characters.');
+  }
+  return value.toLowerCase();
+}
+
+function boundedBytes(value         , fallback        )         {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(Math.max(Math.trunc(parsed), 1), MAX_CONFIGURED_IO_BYTES);
+}
+
+async function replaceWithExpectedSha(
+  filePath        ,
+  tempPath        ,
+  expectedSha        ,
+  afterClaim                                             
+)                  {
+  const backupPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.operator-${crypto.randomUUID()}.bak`);
+  let claimed = false;
+  try {
+    try { await fs.rename(filePath, backupPath); claimed = true; }
+    catch (error) {
+      if ((error                         ).code === 'ENOENT') throw new OperatorError('TARGET_MISSING', 'file.replace requires an existing file.');
+      throw error;
+    }
+    const stat = await fs.lstat(backupPath);
+    if (stat.isSymbolicLink()) throw new OperatorError('WRITE_SYMLINK_DENIED', 'Refusing to replace a symbolic link.');
+    if (!stat.isFile()) throw new OperatorError('NOT_A_FILE', 'Existing write target is not a regular file.');
+    const before = await fs.readFile(backupPath);
+    const beforeSha = sha256(before);
+    if (beforeSha !== expectedSha) throw new OperatorError('PRECONDITION_FAILED', 'File changed since it was inspected.', { details: { expectedSha, actualSha: beforeSha } });
+    await afterClaim?.(filePath);
+    try { await fs.link(tempPath, filePath); }
+    catch (error) {
+      if ((error                         ).code === 'EEXIST') throw new OperatorError('PRECONDITION_FAILED', 'File changed during replacement.');
+      throw error;
+    }
+    await fs.rm(tempPath, { force: true });
+    await fs.rm(backupPath, { force: true });
+    claimed = false;
+    return beforeSha;
+  } finally {
+    if (claimed) await restoreClaimedPath(backupPath, filePath);
+  }
+}
+async function restoreClaimedPath(backupPath        , filePath        )                {
+  try {
+    await fs.link(backupPath, filePath);
+  } catch (error) {
+    if ((error                         ).code !== 'EEXIST') {
+      throw new OperatorError('WRITE_RECOVERY_FAILED', 'Could not restore the claimed file after a failed replacement.');
+    }
+  } finally {
+    await fs.rm(backupPath, { force: true });
+  }
+}

package/runtime/app/src/capabilities/git-checkpoint.js

@@ -0,0 +1,415 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+                                                                                                         
+import { evidence } from '../core/evidence.js';
+import { OperatorError } from '../core/errors.js';
+import { resolveSupportedGitExecutable } from '../core/trusted-executable.js';
+import { PathScope } from './path-scope.js';
+
+const SCORE                  = {
+  reliability: 0.99,
+  latency: 0.92,
+  determinism: 0.99,
+  security: 0.98,
+  reversibility: 0.99,
+  informationQuality: 0.99,
+  interactionCost: 0.01
+};
+
+const REF_PREFIX = 'refs/operator/checkpoints/';
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const DISABLED_HOOKS_PATH = process.platform === 'win32' ? 'NUL' : '/dev/null';
+const SAFE_GIT_PREFIX = ['--no-pager', '--no-lazy-fetch', '-c', 'core.fsmonitor=false', '-c', `core.hooksPath=${DISABLED_HOOKS_PATH}`];
+
+                  
+               
+                
+                    
+                       
+                      
+  
+
+                                     
+             
+              
+                 
+                    
+                 
+  
+
+                  
+               
+                 
+                 
+  
+
+export class GitCheckpointProvider                               {
+           name = 'git.checkpoint.native';
+  #scope           ;
+
+  constructor(options                            ) {
+    this.#scope = new PathScope(options.allowedRoots);
+  }
+
+  supports(action               )          {
+    return ['git.checkpoint.create', 'git.checkpoint.inspect', 'git.checkpoint.restore'].includes(action.capability);
+  }
+
+  advertises(action               )          {
+    if (!this.supports(action)) return false;
+    try { resolveSupportedGitExecutable(gitEnvironment({})); return true; } catch { return false; }
+  }
+
+  score()                  { return SCORE; }
+
+  async execute(action               )                        {
+    const started = performance.now();
+    try {
+      resolveSupportedGitExecutable(gitEnvironment({}));
+      if (action.capability === 'git.checkpoint.create') return await this.#create(action, started);
+      if (action.capability === 'git.checkpoint.inspect') return await this.#inspect(action, started);
+      if (action.capability === 'git.checkpoint.restore') return await this.#restore(action, started);
+      throw new OperatorError('UNSUPPORTED_ACTION', action.capability);
+    } catch (error) {
+      const op = error instanceof OperatorError
+        ? error
+        : new OperatorError('GIT_CHECKPOINT_ERROR', error instanceof Error ? error.message : String(error));
+      return {
+        ok: false,
+        capability: action.capability,
+        provider: this.name,
+        evidence: [evidence('git_checkpoint', 'fail', op.message, { code: op.code })],
+        error: { code: op.code, message: op.message, retryable: op.retryable },
+        durationMs: Math.round(performance.now() - started)
+      };
+    }
+  }
+
+  async #create(action               , started        )                        {
+    const cwd = String(action.input.cwd ?? '');
+    const label = typeof action.input.label === 'string' ? action.input.label.trim().slice(0, 160) : undefined;
+    const checkpoint = await this.#createCheckpoint(cwd, label);
+    return {
+      ok: true,
+      capability: action.capability,
+      provider: this.name,
+      output: checkpoint,
+      evidence: [
+        evidence('git_checkpoint', 'pass', 'Checkpoint stored in the repository object database without moving HEAD, branch, index, or working tree.', {
+          checkpointId: checkpoint.id,
+          commit: checkpoint.commit,
+          head: checkpoint.head,
+          indexTree: checkpoint.indexTree,
+          worktreeTree: checkpoint.worktreeTree
+        }),
+        evidence('git_execution_boundary', 'pass', 'Repository-local clean/smudge/process filters were absent before Git materialized the checkpoint tree.'),
+        evidence('postcondition', 'pass', 'Repository state fingerprint is unchanged after checkpoint creation.', { fingerprint: checkpoint.fingerprint })
+      ],
+      durationMs: Math.round(performance.now() - started)
+    };
+  }
+
+  async #inspect(action               , started        )                        {
+    const cwd = String(action.input.cwd ?? '');
+    const state = await this.#captureState(cwd);
+    const refs = await runGit(state.root, ['for-each-ref', '--format=%(refname)%00%(objectname)%00%(creatordate:iso-strict)', REF_PREFIX], {});
+    const checkpoints = refs.stdout
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(0, 200)
+      .flatMap((line) => {
+        const [ref, commit, createdAt] = line.split('\0');
+        if (!ref?.startsWith(REF_PREFIX) || !commit) return [];
+        return [{ id: ref.slice(REF_PREFIX.length), ref, commit, createdAt: createdAt ?? '' }];
+      });
+    return {
+      ok: true,
+      capability: action.capability,
+      provider: this.name,
+      output: { current: state, checkpoints },
+      evidence: [evidence('git_checkpoint_state', 'pass', 'Current repository snapshot fingerprint and bounded checkpoint refs inspected.', {
+        fingerprint: state.fingerprint,
+        checkpointCount: checkpoints.length
+      })],
+      durationMs: Math.round(performance.now() - started)
+    };
+  }
+
+  async #restore(action               , started        )                        {
+    const cwd = String(action.input.cwd ?? '');
+    const checkpointId = validateCheckpointId(String(action.input.checkpointId ?? ''));
+    const expectedCurrentFingerprint = String(action.input.expectedCurrentFingerprint ?? '');
+    if (!/^[0-9a-f]{64}$/i.test(expectedCurrentFingerprint)) {
+      throw new OperatorError('CHECKPOINT_FINGERPRINT_REQUIRED', 'expectedCurrentFingerprint from git.checkpoint.inspect is required for restore.');
+    }
+
+    const current = await this.#captureState(cwd);
+    if (current.fingerprint !== expectedCurrentFingerprint) {
+      throw new OperatorError('CHECKPOINT_STATE_CHANGED', 'Repository state changed after the supplied restore precondition was captured.', {
+        retryable: true,
+        details: { expectedCurrentFingerprint, actualCurrentFingerprint: current.fingerprint }
+      });
+    }
+
+    const target = await this.#readCheckpoint(current.root, checkpointId);
+    if (target.head !== current.head) {
+      throw new OperatorError('CHECKPOINT_HEAD_CHANGED', 'Current HEAD differs from the checkpoint base HEAD; refusing to overwrite a different revision.', {
+        details: { checkpointHead: target.head, currentHead: current.head }
+      });
+    }
+
+    const recovery = await this.#createCheckpoint(current.root, `automatic recovery before restore ${checkpointId}`);
+    try {
+      await this.#restoreState(current.root, target);
+      const restored = await this.#captureState(current.root);
+      if (restored.head !== target.head || restored.indexTree !== target.indexTree || restored.worktreeTree !== target.worktreeTree) {
+        throw new OperatorError('CHECKPOINT_RESTORE_POSTCONDITION_FAILED', 'Git restore completed but repository trees do not match the checkpoint.', {
+          details: { expected: target, actual: restored }
+        });
+      }
+      return {
+        ok: true,
+        capability: action.capability,
+        provider: this.name,
+        output: {
+          checkpointId,
+          restored,
+          recoveryCheckpointId: recovery.id,
+          recoveryFingerprint: recovery.fingerprint
+        },
+        evidence: [
+          evidence('git_checkpoint_restore', 'pass', 'Working tree and index restored to the checkpoint while HEAD remained unchanged.', {
+            checkpointId,
+            head: restored.head,
+            indexTree: restored.indexTree,
+            worktreeTree: restored.worktreeTree
+          }),
+          evidence('recovery_checkpoint', 'pass', 'A pre-restore recovery checkpoint was retained so the restore itself can be undone.', { recoveryCheckpointId: recovery.id }),
+          evidence('postcondition', 'pass', 'Restored index and working-tree tree hashes exactly match the checkpoint.', { fingerprint: restored.fingerprint })
+        ],
+        durationMs: Math.round(performance.now() - started)
+      };
+    } catch (error) {
+      try {
+        await this.#restoreState(current.root, recovery);
+        throw new OperatorError('CHECKPOINT_RESTORE_FAILED_RECOVERED', error instanceof Error ? error.message : String(error), {
+          retryable: true,
+          details: { recoveryCheckpointId: recovery.id }
+        });
+      } catch (rollbackError) {
+        if (rollbackError instanceof OperatorError && rollbackError.code === 'CHECKPOINT_RESTORE_FAILED_RECOVERED') throw rollbackError;
+        throw new OperatorError('CHECKPOINT_RESTORE_AND_RECOVERY_FAILED', 'Checkpoint restore failed and automatic recovery could not be verified.', {
+          details: {
+            restoreError: error instanceof Error ? error.message : String(error),
+            recoveryError: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+            recoveryCheckpointId: recovery.id
+          }
+        });
+      }
+    }
+  }
+
+  async #createCheckpoint(cwd        , label         )                            {
+    const before = await this.#captureState(cwd);
+    const id = crypto.randomUUID();
+    const createdAt = new Date().toISOString();
+    const message = [
+      `Operator checkpoint ${id}`,
+      '',
+      `Operator-Checkpoint-Version: 1`,
+      `Operator-Index-Tree: ${before.indexTree}`,
+      `Operator-Base-Head: ${before.head ?? 'UNBORN'}`,
+      `Operator-Created-At: ${createdAt}`,
+      ...(label ? [`Operator-Label: ${label.replace(/[\r\n]+/g, ' ')}`] : [])
+    ].join('\n');
+    const args = ['commit-tree', before.worktreeTree];
+    if (before.head) args.push('-p', before.head);
+    args.push('-m', message);
+    const commit = (await runGit(before.root, args, checkpointIdentityEnv())).stdout.trim();
+    if (!/^[0-9a-f]{40,64}$/i.test(commit)) throw new OperatorError('CHECKPOINT_COMMIT_FAILED', 'Git did not return a checkpoint commit object.');
+    const ref = `${REF_PREFIX}${id}`;
+    await runGit(before.root, ['update-ref', ref, commit], {});
+    const after = await this.#captureState(before.root);
+    if (after.fingerprint !== before.fingerprint) {
+      throw new OperatorError('CHECKPOINT_MUTATED_WORKTREE', 'Checkpoint creation unexpectedly changed repository state.');
+    }
+    return { ...before, id, ref, commit, createdAt, label };
+  }
+
+  async #captureState(cwd        )                     {
+    const requested = await this.#scope.resolveExisting(cwd);
+    const rootResult = await runGit(requested, ['rev-parse', '--show-toplevel'], {});
+    const root = await this.#scope.resolveExisting(rootResult.stdout.trim());
+    await assertNoRepoLocalContentFilters(root);
+    const headResult = await runGit(root, ['rev-parse', '--verify', 'HEAD'], {}, true);
+    const head = headResult.code === 0 ? headResult.stdout.trim() : undefined;
+    const indexTree = (await runGit(root, ['write-tree'], {})).stdout.trim();
+    const worktreeTree = await snapshotWorktreeTree(root, head);
+    const fingerprint = crypto.createHash('sha256').update(`${head ?? 'UNBORN'}\0${indexTree}\0${worktreeTree}`).digest('hex');
+    return { root, head, indexTree, worktreeTree, fingerprint };
+  }
+
+  async #readCheckpoint(root        , id        )                            {
+    const ref = `${REF_PREFIX}${id}`;
+    const commitResult = await runGit(root, ['rev-parse', '--verify', `${ref}^{commit}`], {}, true);
+    if (commitResult.code !== 0) throw new OperatorError('CHECKPOINT_NOT_FOUND', `Checkpoint ${id} was not found.`);
+    const commit = commitResult.stdout.trim();
+    const raw = (await runGit(root, ['cat-file', 'commit', commit], {})).stdout;
+    const [headers, ...messageParts] = raw.split('\n\n');
+    const tree = headers.split(/\r?\n/).find((line) => line.startsWith('tree '))?.slice(5).trim();
+    const parent = headers.split(/\r?\n/).find((line) => line.startsWith('parent '))?.slice(7).trim();
+    const message = messageParts.join('\n\n');
+    const indexTree = trailer(message, 'Operator-Index-Tree');
+    const baseHead = trailer(message, 'Operator-Base-Head');
+    const createdAt = trailer(message, 'Operator-Created-At');
+    const label = trailer(message, 'Operator-Label');
+    if (!tree || !indexTree || !baseHead || !createdAt) throw new OperatorError('CHECKPOINT_METADATA_INVALID', 'Checkpoint metadata is incomplete.');
+    const head = baseHead === 'UNBORN' ? undefined : baseHead;
+    if ((head ?? undefined) !== (parent ?? undefined)) throw new OperatorError('CHECKPOINT_METADATA_INVALID', 'Checkpoint parent does not match recorded base HEAD.');
+    const fingerprint = crypto.createHash('sha256').update(`${head ?? 'UNBORN'}\0${indexTree}\0${tree}`).digest('hex');
+    return { root, head, indexTree, worktreeTree: tree, fingerprint, id, ref, commit, createdAt, label };
+  }
+
+  async #restoreState(root        , state                                               )                {
+    await assertNoRepoLocalContentFilters(root);
+    const current = await this.#captureState(root);
+    const diff = await runGit(root, ['diff', '--name-status', '-z', '--no-renames', '--no-ext-diff', '--no-textconv', state.worktreeTree, current.worktreeTree], {});
+    for (const item of parseNameStatus(diff.stdout)) {
+      const absolute = path.resolve(root, item.path);
+      const relative = path.relative(root, absolute);
+      if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new OperatorError('CHECKPOINT_PATH_ESCAPE', 'Git diff returned an unsafe restore path.');
+      try {
+        const stat = await fs.lstat(absolute);
+        if (stat.isDirectory() && !stat.isSymbolicLink()) {
+          throw new OperatorError('CHECKPOINT_DIRECTORY_CONFLICT', `Refusing to recursively delete directory ${item.path} during restore.`);
+        }
+        await fs.rm(absolute, { force: true });
+      } catch (error) {
+        if ((error                         ).code !== 'ENOENT') throw error;
+      }
+    }
+    await runGit(root, ['read-tree', '--reset', '-u', state.worktreeTree], {});
+    await runGit(root, ['read-tree', state.indexTree], {});
+  }
+}
+
+function validateCheckpointId(value        )         {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) throw new OperatorError('INVALID_CHECKPOINT_ID', 'checkpointId is invalid.');
+  return value;
+}
+
+function trailer(message        , key        )                     {
+  const prefix = `${key}: `;
+  return message.split(/\r?\n/).find((line) => line.startsWith(prefix))?.slice(prefix.length).trim() || undefined;
+}
+
+function parseNameStatus(raw        )                                          {
+  const fields = raw.split('\0').filter(Boolean);
+  const output                                          = [];
+  for (let index = 0; index + 1 < fields.length; index += 2) {
+    const status = fields[index] ?? '';
+    const file = fields[index + 1] ?? '';
+    if (!/^[AMD]$/.test(status) || !file) throw new OperatorError('CHECKPOINT_DIFF_INVALID', 'Unexpected Git name-status output during restore.');
+    output.push({ status, path: file });
+  }
+  return output;
+}
+
+async function assertNoRepoLocalContentFilters(root        )                {
+  const configured = await runGit(root, ['config', '--name-only', '--get-regexp', '^filter\\..*\\.(clean|smudge|process)$'], {}, true);
+  if (configured.code === 0 && configured.stdout.trim()) {
+    throw new OperatorError('GIT_LOCAL_FILTER_DENIED', 'Repository-local Git clean/smudge/process filters are disabled for checkpoint operations because they can execute arbitrary commands.', {
+      details: { keys: configured.stdout.split(/\r?\n/).filter(Boolean).slice(0, 50) }
+    });
+  }
+  if (![0, 1].includes(configured.code)) {
+    throw new OperatorError('GIT_CONFIG_INSPECTION_FAILED', configured.stderr.trim() || 'Unable to inspect repository-local Git filter configuration.');
+  }
+}
+
+async function snapshotWorktreeTree(root        , head         )                  {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'operator-git-index-'));
+  const indexPath = path.join(tempDir, 'index');
+  const env = { GIT_INDEX_FILE: indexPath };
+  try {
+    if (head) await runGit(root, ['read-tree', head], env);
+    else await runGit(root, ['read-tree', '--empty'], env);
+    await runGit(root, ['add', '-A', '--', '.'], env);
+    return (await runGit(root, ['write-tree'], env)).stdout.trim();
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+function checkpointIdentityEnv()                    {
+  return {
+    GIT_AUTHOR_NAME: 'Operator Checkpoint',
+    GIT_AUTHOR_EMAIL: 'operator@local.invalid',
+    GIT_COMMITTER_NAME: 'Operator Checkpoint',
+    GIT_COMMITTER_EMAIL: 'operator@local.invalid'
+  };
+}
+
+function gitEnvironment(extraEnv                   )                    {
+  const nullConfig = process.platform === 'win32' ? 'NUL' : '/dev/null';
+  const env                    = {
+    GIT_PAGER: '',
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_GLOBAL: nullConfig,
+    GIT_CONFIG_SYSTEM: nullConfig,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_NO_LAZY_FETCH: '1'
+  };
+  for (const key of ['PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'USER', 'USERNAME', 'LOGNAME', 'TMP', 'TEMP', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE']) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(extraEnv)) {
+    if (value !== undefined) env[key] = value;
+  }
+  return env;
+}
+
+async function runGit(cwd        , args          , extraEnv                   , allowNonZero = false)                     {
+  return await new Promise((resolve, reject) => {
+    const safeArgs = [...SAFE_GIT_PREFIX, ...args];
+    const environment = gitEnvironment(extraEnv);
+    const gitExecutable = resolveSupportedGitExecutable(environment);
+    const child = spawn(gitExecutable, safeArgs, {
+      cwd,
+      shell: false,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: environment
+    });
+    const stdout           = [];
+    const stderr           = [];
+    let bytes = 0;
+    const capture = (bucket          ) => (chunk        ) => {
+      if (bytes >= MAX_OUTPUT_BYTES) return;
+      const remaining = MAX_OUTPUT_BYTES - bytes;
+      const sliced = chunk.subarray(0, remaining);
+      bucket.push(sliced);
+      bytes += sliced.byteLength;
+    };
+    child.stdout.on('data', capture(stdout));
+    child.stderr.on('data', capture(stderr));
+    child.once('error', reject);
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 1_000).unref();
+    }, 30_000);
+    timer.unref();
+    child.once('close', (code) => {
+      clearTimeout(timer);
+      const result = { code: code ?? -1, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') };
+      if (result.code !== 0 && !allowNonZero) {
+        reject(new OperatorError('GIT_COMMAND_FAILED', `git ${args[0] ?? ''} failed: ${result.stderr.trim().slice(0, 1000) || `exit ${result.code}`}`));
+        return;
+      }
+      resolve(result);
+    });
+  });
+}