open-multi-agent-kit 0.97.0 → 0.98.0

package/dist/core/recovery-checkpoint.d.ts

@@ -1,196 +0,0 @@
-/**
- * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/
- * conversation recovery checkpoints.
- *
- * This module is intentionally side-effect free: it never reads the filesystem,
- * never shells out to git, and never mutates a worktree. It validates a
- * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against
- * an externally-observed worktree snapshot, decides how OMK-created untracked
- * files should be disposed (delete vs quarantine), and produces a
- * conversation/code/both restore plan. The caller is responsible for gathering
- * the observed state (git status, per-file hashes) and for executing the plan.
- *
- * Derived clean-room from the lane C plan
- * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the
- * adoption algorithm plan; no legacy package source is imported or copied.
- *
- * Dependency-free apart from `node:path` (pure path math, no I/O).
- */
-export declare const RECOVERY_CHECKPOINT_SCHEMA_VERSION = "omk.recovery.checkpoint.v1";
-export type RecoveryVcs = "git" | "none";
-export type TouchedFileMode = "tracked" | "untracked" | "deleted";
-export interface RecoveryCheckpointSession {
-    readonly sessionFile?: string;
-    readonly leafId: string | null;
-    readonly branchPathIds: readonly string[];
-    readonly contextHash: string;
-}
-export interface RecoveryTouchedFile {
-    readonly path: string;
-    readonly beforeSha256?: string;
-    readonly afterSha256?: string;
-    readonly mode: TouchedFileMode;
-}
-export interface RecoveryCheckpointWorkspace {
-    readonly repoRoot: string;
-    readonly vcs: RecoveryVcs;
-    readonly head?: string;
-    readonly statusPorcelainSha256: string;
-    readonly touchedFiles: readonly RecoveryTouchedFile[];
-    readonly reversePatchArtifact?: string;
-}
-export interface RecoveryCheckpointTool {
-    readonly turnIndex: number;
-    readonly beforeToolCallId?: string;
-    readonly afterToolCallId?: string;
-    readonly mutatingTools: readonly string[];
-}
-export interface RecoveryCheckpointLedger {
-    readonly eventId: string;
-    readonly previousEventHash: string;
-    readonly eventHash: string;
-}
-export interface RecoveryCheckpoint {
-    readonly schemaVersion: typeof RECOVERY_CHECKPOINT_SCHEMA_VERSION;
-    readonly checkpointId: string;
-    readonly createdAt: string;
-    readonly session: RecoveryCheckpointSession;
-    readonly workspace: RecoveryCheckpointWorkspace;
-    readonly tool?: RecoveryCheckpointTool;
-    readonly ledger: RecoveryCheckpointLedger;
-}
-export interface RecoveryCheckpointValidation {
-    readonly ok: boolean;
-    readonly errors: readonly string[];
-    readonly checkpoint?: RecoveryCheckpoint;
-}
-/** A touched-file path must be repo-relative and must not escape the repo root. */
-export declare function isUnsafeTouchedPath(path: unknown): boolean;
-/**
- * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and
- * fail-closed: any structural problem yields `ok: false` with explicit errors
- * and no `checkpoint` payload.
- */
-export declare function validateRecoveryCheckpoint(value: unknown): RecoveryCheckpointValidation;
-/**
- * The ledger anchor as independently re-read from the hash-chained ledger.
- * Compared against the checkpoint's embedded anchor before any mutation.
- */
-export interface ObservedLedgerAnchor {
-    readonly eventId: string;
-    readonly previousEventHash: string;
-    readonly eventHash: string;
-}
-export interface LedgerAnchorVerification {
-    readonly ok: boolean;
-    readonly mismatches: readonly string[];
-}
-/**
- * Compare a checkpoint's embedded ledger anchor with the anchor observed in the
- * live ledger. A mismatch means the checkpoint references an event that no
- * longer matches the durable audit trail (tamper or divergence) and the restore
- * must fail closed.
- */
-export declare function verifyCheckpointLedgerAnchor(checkpoint: RecoveryCheckpoint, observed: ObservedLedgerAnchor): LedgerAnchorVerification;
-export interface ObservedTouchedFile {
-    readonly path: string;
-    readonly exists: boolean;
-    readonly sha256?: string;
-    readonly isSymlink?: boolean;
-    /** True when the path (or its symlink target) resolves outside the repo root. */
-    readonly escapesRepo?: boolean;
-}
-export interface ObservedWorktree {
-    readonly head?: string;
-    readonly statusPorcelainSha256?: string;
-    /** Current dirty paths (repo-relative) from `git status --porcelain`. */
-    readonly dirtyPaths: readonly string[];
-    readonly touchedFiles: readonly ObservedTouchedFile[];
-}
-export interface RestorePreflightOptions {
-    /** Allow restoring even though HEAD moved since the checkpoint. */
-    readonly allowNonHeadRestore?: boolean;
-}
-export type RestorePreflightVerdict = "clean" | "blocked";
-export type RestorePreflightIssueCode = "unrelated-dirty-path" | "touched-hash-mismatch" | "missing-touched-file" | "symlink-escape" | "head-mismatch";
-export interface RestorePreflightIssue {
-    readonly code: RestorePreflightIssueCode;
-    readonly path?: string;
-    readonly detail: string;
-}
-export interface RestorePreflightResult {
-    readonly verdict: RestorePreflightVerdict;
-    readonly issues: readonly RestorePreflightIssue[];
-    readonly unrelatedDirtyPaths: readonly string[];
-    readonly hashMismatches: readonly string[];
-    readonly symlinkEscapes: readonly string[];
-    readonly headChanged: boolean;
-}
-/**
- * Classify whether a code restore can proceed against the live worktree.
- *
- * Fail-closed rules (from the lane C restore algorithm):
- *  - any dirty path outside the recorded touched set blocks the restore;
- *  - any touched file whose current hash differs from the recorded `afterSha256`
- *    blocks the restore;
- *  - any symlink escaping the repo root blocks the restore;
- *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.
- */
-export declare function classifyRestorePreflight(checkpoint: RecoveryCheckpoint, observed: ObservedWorktree, options?: RestorePreflightOptions): RestorePreflightResult;
-export type UntrackedDisposition = "delete" | "quarantine" | "skip";
-export interface UntrackedDispositionDecision {
-    readonly disposition: UntrackedDisposition;
-    readonly reason: string;
-}
-export interface ObservedUntrackedFile {
-    readonly exists: boolean;
-    readonly sha256?: string;
-}
-/**
- * Decide how an OMK-created untracked file should be handled on restore.
- *
- *  - `skip`: the file is already gone, nothing to undo.
- *  - `delete`: the file still exactly matches what OMK created, safe to remove.
- *  - `quarantine`: the file changed since OMK created it; move it under the
- *    recovery quarantine directory rather than destroying user edits.
- */
-export declare function decideUntrackedDisposition(touched: RecoveryTouchedFile, observed: ObservedUntrackedFile): UntrackedDispositionDecision;
-export type RestoreMode = "conversation" | "code" | "both";
-export type RestorePhaseKind = "conversation" | "code";
-export type RestorePhaseAction = "navigate-tree" | "apply-reverse-patch";
-export interface RestorePlanPhase {
-    readonly phase: RestorePhaseKind;
-    readonly action: RestorePhaseAction;
-    readonly targetLeafId?: string | null;
-    readonly recordedPaths?: readonly string[];
-}
-export interface RestorePlan {
-    readonly mode: RestoreMode;
-    readonly status: "ready" | "blocked";
-    readonly phases: readonly RestorePlanPhase[];
-    readonly blockers: readonly string[];
-    /** For `both`: the leaf to keep if the conversation phase fails after code restore. */
-    readonly preservePreviousLeafId?: string | null;
-    readonly inDoubtPolicy?: "preserve-previous-leaf";
-}
-export interface PlanRestoreInput {
-    readonly mode: RestoreMode;
-    readonly checkpoint: RecoveryCheckpoint;
-    /** Required for `code` and `both` modes. */
-    readonly preflight?: RestorePreflightResult;
-    /** The current session leaf, preserved for manual recovery in `both` mode. */
-    readonly currentLeafId?: string | null;
-}
-/**
- * Build a restore plan for the requested mode.
- *
- *  - `conversation`: navigate the session tree to the checkpoint leaf; no file
- *    writes, so no worktree preflight is required.
- *  - `code`: apply the recorded reverse patch path-by-path; requires a clean
- *    preflight.
- *  - `both`: restore code first, then navigate the tree; requires a clean
- *    preflight. If the second (conversation) phase fails at execution time the
- *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.
- */
-export declare function planRestore(input: PlanRestoreInput): RestorePlan;
-//# sourceMappingURL=recovery-checkpoint.d.ts.map

package/dist/core/recovery-checkpoint.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"recovery-checkpoint.d.ts","sourceRoot":"","sources":["../../src/core/recovery-checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/\n * conversation recovery checkpoints.\n *\n * This module is intentionally side-effect free: it never reads the filesystem,\n * never shells out to git, and never mutates a worktree. It validates a\n * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against\n * an externally-observed worktree snapshot, decides how OMK-created untracked\n * files should be disposed (delete vs quarantine), and produces a\n * conversation/code/both restore plan. The caller is responsible for gathering\n * the observed state (git status, per-file hashes) and for executing the plan.\n *\n * Derived clean-room from the lane C plan\n * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the\n * adoption algorithm plan; no legacy package source is imported or copied.\n *\n * Dependency-free apart from `node:path` (pure path math, no I/O).\n */\n\nimport { isAbsolute } from \"node:path\";\n\nexport const RECOVERY_CHECKPOINT_SCHEMA_VERSION = \"omk.recovery.checkpoint.v1\";\n\nexport type RecoveryVcs = \"git\" | \"none\";\nexport type TouchedFileMode = \"tracked\" | \"untracked\" | \"deleted\";\n\nexport interface RecoveryCheckpointSession {\n\treadonly sessionFile?: string;\n\treadonly leafId: string | null;\n\treadonly branchPathIds: readonly string[];\n\treadonly contextHash: string;\n}\n\nexport interface RecoveryTouchedFile {\n\treadonly path: string;\n\treadonly beforeSha256?: string;\n\treadonly afterSha256?: string;\n\treadonly mode: TouchedFileMode;\n}\n\nexport interface RecoveryCheckpointWorkspace {\n\treadonly repoRoot: string;\n\treadonly vcs: RecoveryVcs;\n\treadonly head?: string;\n\treadonly statusPorcelainSha256: string;\n\treadonly touchedFiles: readonly RecoveryTouchedFile[];\n\treadonly reversePatchArtifact?: string;\n}\n\nexport interface RecoveryCheckpointTool {\n\treadonly turnIndex: number;\n\treadonly beforeToolCallId?: string;\n\treadonly afterToolCallId?: string;\n\treadonly mutatingTools: readonly string[];\n}\n\nexport interface RecoveryCheckpointLedger {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface RecoveryCheckpoint {\n\treadonly schemaVersion: typeof RECOVERY_CHECKPOINT_SCHEMA_VERSION;\n\treadonly checkpointId: string;\n\treadonly createdAt: string;\n\treadonly session: RecoveryCheckpointSession;\n\treadonly workspace: RecoveryCheckpointWorkspace;\n\treadonly tool?: RecoveryCheckpointTool;\n\treadonly ledger: RecoveryCheckpointLedger;\n}\n\nexport interface RecoveryCheckpointValidation {\n\treadonly ok: boolean;\n\treadonly errors: readonly string[];\n\treadonly checkpoint?: RecoveryCheckpoint;\n}\n\nconst HEX64 = /^[0-9a-f]{64}$/i;\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0;\n}\n\nfunction isHex64(value: unknown): value is string {\n\treturn typeof value === \"string\" && HEX64.test(value);\n}\n\nfunction isIsoTimestamp(value: unknown): value is string {\n\treturn typeof value === \"string\" && value.length > 0 && !Number.isNaN(Date.parse(value));\n}\n\n/** A touched-file path must be repo-relative and must not escape the repo root. */\nexport function isUnsafeTouchedPath(path: unknown): boolean {\n\tif (typeof path !== \"string\" || path.length === 0) return true;\n\tif (isAbsolute(path)) return true;\n\tconst normalized = path.replace(/\\\\/g, \"/\");\n\treturn normalized.split(\"/\").some((segment) => segment === \"..\");\n}\n\nfunction normalizeRelPath(path: string): string {\n\treturn path.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\");\n}\n\nfunction validateTouchedFile(value: unknown, index: number, errors: string[]): void {\n\tconst label = `workspace.touchedFiles[${index}]`;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(`${label} must be an object`);\n\t\treturn;\n\t}\n\tif (isUnsafeTouchedPath(value.path)) {\n\t\terrors.push(`${label}.path must be a repo-relative path without '..' segments`);\n\t}\n\tconst mode = value.mode;\n\tif (mode !== \"tracked\" && mode !== \"untracked\" && mode !== \"deleted\") {\n\t\terrors.push(`${label}.mode must be one of tracked|untracked|deleted`);\n\t\treturn;\n\t}\n\tif (value.beforeSha256 !== undefined && !isHex64(value.beforeSha256)) {\n\t\terrors.push(`${label}.beforeSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (value.afterSha256 !== undefined && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 must be a 64-char hex digest when present`);\n\t}\n\tif (mode === \"untracked\") {\n\t\tif (!isHex64(value.afterSha256)) errors.push(`${label}.afterSha256 is required for untracked files`);\n\t\tif (value.beforeSha256 !== undefined) errors.push(`${label}.beforeSha256 must be absent for untracked files`);\n\t}\n\tif (mode === \"deleted\") {\n\t\tif (!isHex64(value.beforeSha256)) errors.push(`${label}.beforeSha256 is required for deleted files`);\n\t\tif (value.afterSha256 !== undefined) errors.push(`${label}.afterSha256 must be absent for deleted files`);\n\t}\n\tif (mode === \"tracked\" && !isHex64(value.afterSha256)) {\n\t\terrors.push(`${label}.afterSha256 is required for tracked files`);\n\t}\n}\n\nfunction validateSession(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"session must be an object\");\n\t\treturn;\n\t}\n\tif (value.leafId !== null && typeof value.leafId !== \"string\") {\n\t\terrors.push(\"session.leafId must be a string or null\");\n\t}\n\tif (!Array.isArray(value.branchPathIds) || value.branchPathIds.some((id) => typeof id !== \"string\")) {\n\t\terrors.push(\"session.branchPathIds must be an array of strings\");\n\t}\n\tif (!isHex64(value.contextHash)) {\n\t\terrors.push(\"session.contextHash must be a 64-char hex digest\");\n\t}\n\tif (value.sessionFile !== undefined && typeof value.sessionFile !== \"string\") {\n\t\terrors.push(\"session.sessionFile must be a string when present\");\n\t}\n}\n\nfunction validateWorkspace(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"workspace must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.repoRoot)) errors.push(\"workspace.repoRoot must be a non-empty string\");\n\tif (value.vcs !== \"git\" && value.vcs !== \"none\") errors.push(\"workspace.vcs must be one of git|none\");\n\tif (value.head !== undefined && typeof value.head !== \"string\") {\n\t\terrors.push(\"workspace.head must be a string when present\");\n\t}\n\tif (!isHex64(value.statusPorcelainSha256)) {\n\t\terrors.push(\"workspace.statusPorcelainSha256 must be a 64-char hex digest\");\n\t}\n\tif (value.reversePatchArtifact !== undefined && typeof value.reversePatchArtifact !== \"string\") {\n\t\terrors.push(\"workspace.reversePatchArtifact must be a string when present\");\n\t}\n\tif (!Array.isArray(value.touchedFiles)) {\n\t\terrors.push(\"workspace.touchedFiles must be an array\");\n\t\treturn;\n\t}\n\tvalue.touchedFiles.forEach((entry, index) => {\n\t\tvalidateTouchedFile(entry, index, errors);\n\t});\n}\n\nfunction validateTool(value: unknown, errors: string[]): void {\n\tif (value === undefined) return;\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"tool must be an object when present\");\n\t\treturn;\n\t}\n\tif (typeof value.turnIndex !== \"number\" || !Number.isInteger(value.turnIndex) || value.turnIndex < 0) {\n\t\terrors.push(\"tool.turnIndex must be a non-negative integer\");\n\t}\n\tif (!Array.isArray(value.mutatingTools) || value.mutatingTools.some((t) => typeof t !== \"string\")) {\n\t\terrors.push(\"tool.mutatingTools must be an array of strings\");\n\t}\n\tif (value.beforeToolCallId !== undefined && typeof value.beforeToolCallId !== \"string\") {\n\t\terrors.push(\"tool.beforeToolCallId must be a string when present\");\n\t}\n\tif (value.afterToolCallId !== undefined && typeof value.afterToolCallId !== \"string\") {\n\t\terrors.push(\"tool.afterToolCallId must be a string when present\");\n\t}\n}\n\nfunction validateLedger(value: unknown, errors: string[]): void {\n\tif (!isPlainObject(value)) {\n\t\terrors.push(\"ledger must be an object\");\n\t\treturn;\n\t}\n\tif (!isNonEmptyString(value.eventId)) errors.push(\"ledger.eventId must be a non-empty string\");\n\tif (!isHex64(value.previousEventHash)) errors.push(\"ledger.previousEventHash must be a 64-char hex digest\");\n\tif (!isHex64(value.eventHash)) errors.push(\"ledger.eventHash must be a 64-char hex digest\");\n}\n\n/**\n * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and\n * fail-closed: any structural problem yields `ok: false` with explicit errors\n * and no `checkpoint` payload.\n */\nexport function validateRecoveryCheckpoint(value: unknown): RecoveryCheckpointValidation {\n\tconst errors: string[] = [];\n\tif (!isPlainObject(value)) {\n\t\treturn { ok: false, errors: [\"checkpoint must be an object\"] };\n\t}\n\tif (value.schemaVersion !== RECOVERY_CHECKPOINT_SCHEMA_VERSION) {\n\t\terrors.push(`schemaVersion must be ${RECOVERY_CHECKPOINT_SCHEMA_VERSION}`);\n\t}\n\tif (!isNonEmptyString(value.checkpointId)) errors.push(\"checkpointId must be a non-empty string\");\n\tif (!isIsoTimestamp(value.createdAt)) errors.push(\"createdAt must be an ISO-8601 timestamp\");\n\tvalidateSession(value.session, errors);\n\tvalidateWorkspace(value.workspace, errors);\n\tvalidateTool(value.tool, errors);\n\tvalidateLedger(value.ledger, errors);\n\n\tif (errors.length > 0) return { ok: false, errors };\n\treturn { ok: true, errors: [], checkpoint: value as unknown as RecoveryCheckpoint };\n}\n\n/**\n * The ledger anchor as independently re-read from the hash-chained ledger.\n * Compared against the checkpoint's embedded anchor before any mutation.\n */\nexport interface ObservedLedgerAnchor {\n\treadonly eventId: string;\n\treadonly previousEventHash: string;\n\treadonly eventHash: string;\n}\n\nexport interface LedgerAnchorVerification {\n\treadonly ok: boolean;\n\treadonly mismatches: readonly string[];\n}\n\n/**\n * Compare a checkpoint's embedded ledger anchor with the anchor observed in the\n * live ledger. A mismatch means the checkpoint references an event that no\n * longer matches the durable audit trail (tamper or divergence) and the restore\n * must fail closed.\n */\nexport function verifyCheckpointLedgerAnchor(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedLedgerAnchor,\n): LedgerAnchorVerification {\n\tconst mismatches: string[] = [];\n\tif (checkpoint.ledger.eventId !== observed.eventId) {\n\t\tmismatches.push(`eventId mismatch: checkpoint=${checkpoint.ledger.eventId} ledger=${observed.eventId}`);\n\t}\n\tif (checkpoint.ledger.previousEventHash !== observed.previousEventHash) {\n\t\tmismatches.push(\"previousEventHash mismatch between checkpoint and ledger\");\n\t}\n\tif (checkpoint.ledger.eventHash !== observed.eventHash) {\n\t\tmismatches.push(\"eventHash mismatch between checkpoint and ledger\");\n\t}\n\treturn { ok: mismatches.length === 0, mismatches };\n}\n\nexport interface ObservedTouchedFile {\n\treadonly path: string;\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n\treadonly isSymlink?: boolean;\n\t/** True when the path (or its symlink target) resolves outside the repo root. */\n\treadonly escapesRepo?: boolean;\n}\n\nexport interface ObservedWorktree {\n\treadonly head?: string;\n\treadonly statusPorcelainSha256?: string;\n\t/** Current dirty paths (repo-relative) from `git status --porcelain`. */\n\treadonly dirtyPaths: readonly string[];\n\treadonly touchedFiles: readonly ObservedTouchedFile[];\n}\n\nexport interface RestorePreflightOptions {\n\t/** Allow restoring even though HEAD moved since the checkpoint. */\n\treadonly allowNonHeadRestore?: boolean;\n}\n\nexport type RestorePreflightVerdict = \"clean\" | \"blocked\";\n\nexport type RestorePreflightIssueCode =\n\t| \"unrelated-dirty-path\"\n\t| \"touched-hash-mismatch\"\n\t| \"missing-touched-file\"\n\t| \"symlink-escape\"\n\t| \"head-mismatch\";\n\nexport interface RestorePreflightIssue {\n\treadonly code: RestorePreflightIssueCode;\n\treadonly path?: string;\n\treadonly detail: string;\n}\n\nexport interface RestorePreflightResult {\n\treadonly verdict: RestorePreflightVerdict;\n\treadonly issues: readonly RestorePreflightIssue[];\n\treadonly unrelatedDirtyPaths: readonly string[];\n\treadonly hashMismatches: readonly string[];\n\treadonly symlinkEscapes: readonly string[];\n\treadonly headChanged: boolean;\n}\n\n/**\n * Classify whether a code restore can proceed against the live worktree.\n *\n * Fail-closed rules (from the lane C restore algorithm):\n *  - any dirty path outside the recorded touched set blocks the restore;\n *  - any touched file whose current hash differs from the recorded `afterSha256`\n *    blocks the restore;\n *  - any symlink escaping the repo root blocks the restore;\n *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.\n */\nexport function classifyRestorePreflight(\n\tcheckpoint: RecoveryCheckpoint,\n\tobserved: ObservedWorktree,\n\toptions: RestorePreflightOptions = {},\n): RestorePreflightResult {\n\tconst issues: RestorePreflightIssue[] = [];\n\tconst touchedByPath = new Map<string, RecoveryTouchedFile>();\n\tfor (const file of checkpoint.workspace.touchedFiles) {\n\t\ttouchedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst unrelatedDirtyPaths: string[] = [];\n\tfor (const dirty of observed.dirtyPaths) {\n\t\tif (!touchedByPath.has(normalizeRelPath(dirty))) {\n\t\t\tunrelatedDirtyPaths.push(dirty);\n\t\t\tissues.push({\n\t\t\t\tcode: \"unrelated-dirty-path\",\n\t\t\t\tpath: dirty,\n\t\t\t\tdetail: \"dirty path is outside the checkpoint's recorded touched files\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst observedByPath = new Map<string, ObservedTouchedFile>();\n\tfor (const file of observed.touchedFiles) {\n\t\tobservedByPath.set(normalizeRelPath(file.path), file);\n\t}\n\n\tconst hashMismatches: string[] = [];\n\tconst symlinkEscapes: string[] = [];\n\tfor (const expected of checkpoint.workspace.touchedFiles) {\n\t\tconst key = normalizeRelPath(expected.path);\n\t\tconst current = observedByPath.get(key);\n\t\tif (!current) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"no observed state was provided for a recorded touched file\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.escapesRepo === true || (current.isSymlink === true && current.escapesRepo !== false)) {\n\t\t\tsymlinkEscapes.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"symlink-escape\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"touched path is a symlink resolving outside the repo root\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (expected.mode === \"deleted\") {\n\t\t\tif (current.exists) {\n\t\t\t\thashMismatches.push(expected.path);\n\t\t\t\tissues.push({\n\t\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\t\tpath: expected.path,\n\t\t\t\t\tdetail: \"expected a deleted file to be absent but it is present\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (!current.exists) {\n\t\t\tissues.push({\n\t\t\t\tcode: \"missing-touched-file\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"recorded touched file is missing from the worktree\",\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\tif (current.sha256 !== expected.afterSha256) {\n\t\t\thashMismatches.push(expected.path);\n\t\t\tissues.push({\n\t\t\t\tcode: \"touched-hash-mismatch\",\n\t\t\t\tpath: expected.path,\n\t\t\t\tdetail: \"current file hash differs from the recorded post-edit hash\",\n\t\t\t});\n\t\t}\n\t}\n\n\tconst headChanged =\n\t\tcheckpoint.workspace.vcs === \"git\" &&\n\t\tcheckpoint.workspace.head !== undefined &&\n\t\tobserved.head !== undefined &&\n\t\tcheckpoint.workspace.head !== observed.head;\n\tif (headChanged && options.allowNonHeadRestore !== true) {\n\t\tissues.push({\n\t\t\tcode: \"head-mismatch\",\n\t\t\tdetail: \"HEAD moved since the checkpoint; pass allowNonHeadRestore to override\",\n\t\t});\n\t}\n\n\treturn {\n\t\tverdict: issues.length === 0 ? \"clean\" : \"blocked\",\n\t\tissues,\n\t\tunrelatedDirtyPaths,\n\t\thashMismatches,\n\t\tsymlinkEscapes,\n\t\theadChanged,\n\t};\n}\n\nexport type UntrackedDisposition = \"delete\" | \"quarantine\" | \"skip\";\n\nexport interface UntrackedDispositionDecision {\n\treadonly disposition: UntrackedDisposition;\n\treadonly reason: string;\n}\n\nexport interface ObservedUntrackedFile {\n\treadonly exists: boolean;\n\treadonly sha256?: string;\n}\n\n/**\n * Decide how an OMK-created untracked file should be handled on restore.\n *\n *  - `skip`: the file is already gone, nothing to undo.\n *  - `delete`: the file still exactly matches what OMK created, safe to remove.\n *  - `quarantine`: the file changed since OMK created it; move it under the\n *    recovery quarantine directory rather than destroying user edits.\n */\nexport function decideUntrackedDisposition(\n\ttouched: RecoveryTouchedFile,\n\tobserved: ObservedUntrackedFile,\n): UntrackedDispositionDecision {\n\tif (touched.mode !== \"untracked\") {\n\t\treturn { disposition: \"skip\", reason: \"disposition only applies to untracked files\" };\n\t}\n\tif (!observed.exists) {\n\t\treturn { disposition: \"skip\", reason: \"untracked file is already absent\" };\n\t}\n\tif (isHex64(touched.afterSha256) && observed.sha256 === touched.afterSha256) {\n\t\treturn { disposition: \"delete\", reason: \"current hash matches the OMK-created hash\" };\n\t}\n\treturn { disposition: \"quarantine\", reason: \"current hash differs from the OMK-created hash\" };\n}\n\nexport type RestoreMode = \"conversation\" | \"code\" | \"both\";\n\nexport type RestorePhaseKind = \"conversation\" | \"code\";\nexport type RestorePhaseAction = \"navigate-tree\" | \"apply-reverse-patch\";\n\nexport interface RestorePlanPhase {\n\treadonly phase: RestorePhaseKind;\n\treadonly action: RestorePhaseAction;\n\treadonly targetLeafId?: string | null;\n\treadonly recordedPaths?: readonly string[];\n}\n\nexport interface RestorePlan {\n\treadonly mode: RestoreMode;\n\treadonly status: \"ready\" | \"blocked\";\n\treadonly phases: readonly RestorePlanPhase[];\n\treadonly blockers: readonly string[];\n\t/** For `both`: the leaf to keep if the conversation phase fails after code restore. */\n\treadonly preservePreviousLeafId?: string | null;\n\treadonly inDoubtPolicy?: \"preserve-previous-leaf\";\n}\n\nexport interface PlanRestoreInput {\n\treadonly mode: RestoreMode;\n\treadonly checkpoint: RecoveryCheckpoint;\n\t/** Required for `code` and `both` modes. */\n\treadonly preflight?: RestorePreflightResult;\n\t/** The current session leaf, preserved for manual recovery in `both` mode. */\n\treadonly currentLeafId?: string | null;\n}\n\nfunction codePhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn {\n\t\tphase: \"code\",\n\t\taction: \"apply-reverse-patch\",\n\t\trecordedPaths: checkpoint.workspace.touchedFiles.map((file) => file.path),\n\t};\n}\n\nfunction conversationPhase(checkpoint: RecoveryCheckpoint): RestorePlanPhase {\n\treturn { phase: \"conversation\", action: \"navigate-tree\", targetLeafId: checkpoint.session.leafId };\n}\n\nfunction collectPreflightBlockers(preflight: RestorePreflightResult | undefined): string[] {\n\tif (!preflight) return [\"code restore requires a preflight classification\"];\n\tif (preflight.verdict === \"clean\") return [];\n\treturn preflight.issues.map((issue) => (issue.path ? `${issue.code}: ${issue.path}` : issue.code));\n}\n\n/**\n * Build a restore plan for the requested mode.\n *\n *  - `conversation`: navigate the session tree to the checkpoint leaf; no file\n *    writes, so no worktree preflight is required.\n *  - `code`: apply the recorded reverse patch path-by-path; requires a clean\n *    preflight.\n *  - `both`: restore code first, then navigate the tree; requires a clean\n *    preflight. If the second (conversation) phase fails at execution time the\n *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.\n */\nexport function planRestore(input: PlanRestoreInput): RestorePlan {\n\tconst { mode, checkpoint, preflight } = input;\n\tif (mode === \"conversation\") {\n\t\treturn { mode, status: \"ready\", phases: [conversationPhase(checkpoint)], blockers: [] };\n\t}\n\n\tconst blockers = collectPreflightBlockers(preflight);\n\tif (mode === \"code\") {\n\t\tif (blockers.length > 0) return { mode, status: \"blocked\", phases: [], blockers };\n\t\treturn { mode, status: \"ready\", phases: [codePhase(checkpoint)], blockers: [] };\n\t}\n\n\t// mode === \"both\"\n\tconst preservePreviousLeafId = input.currentLeafId ?? null;\n\tif (blockers.length > 0) {\n\t\treturn {\n\t\t\tmode,\n\t\t\tstatus: \"blocked\",\n\t\t\tphases: [],\n\t\t\tblockers,\n\t\t\tpreservePreviousLeafId,\n\t\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t\t};\n\t}\n\treturn {\n\t\tmode,\n\t\tstatus: \"ready\",\n\t\tphases: [codePhase(checkpoint), conversationPhase(checkpoint)],\n\t\tblockers: [],\n\t\tpreservePreviousLeafId,\n\t\tinDoubtPolicy: \"preserve-previous-leaf\",\n\t};\n}\n"]}

package/dist/core/recovery-checkpoint.js

@@ -1,382 +0,0 @@
-/**
- * `omk.recovery.checkpoint` — pure decision algorithms for native worktree/
- * conversation recovery checkpoints.
- *
- * This module is intentionally side-effect free: it never reads the filesystem,
- * never shells out to git, and never mutates a worktree. It validates a
- * file-backed {@link RecoveryCheckpoint}, classifies a restore preflight against
- * an externally-observed worktree snapshot, decides how OMK-created untracked
- * files should be disposed (delete vs quarantine), and produces a
- * conversation/code/both restore plan. The caller is responsible for gathering
- * the observed state (git status, per-file hashes) and for executing the plan.
- *
- * Derived clean-room from the lane C plan
- * (`.omk/runs/omk-package-hardening-plan/recovery-readseek.md`) and the
- * adoption algorithm plan; no legacy package source is imported or copied.
- *
- * Dependency-free apart from `node:path` (pure path math, no I/O).
- */
-import { isAbsolute } from "node:path";
-export const RECOVERY_CHECKPOINT_SCHEMA_VERSION = "omk.recovery.checkpoint.v1";
-const HEX64 = /^[0-9a-f]{64}$/i;
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-    return typeof value === "string" && value.length > 0;
-}
-function isHex64(value) {
-    return typeof value === "string" && HEX64.test(value);
-}
-function isIsoTimestamp(value) {
-    return typeof value === "string" && value.length > 0 && !Number.isNaN(Date.parse(value));
-}
-/** A touched-file path must be repo-relative and must not escape the repo root. */
-export function isUnsafeTouchedPath(path) {
-    if (typeof path !== "string" || path.length === 0)
-        return true;
-    if (isAbsolute(path))
-        return true;
-    const normalized = path.replace(/\\/g, "/");
-    return normalized.split("/").some((segment) => segment === "..");
-}
-function normalizeRelPath(path) {
-    return path.replace(/\\/g, "/").replace(/^\.\//, "");
-}
-function validateTouchedFile(value, index, errors) {
-    const label = `workspace.touchedFiles[${index}]`;
-    if (!isPlainObject(value)) {
-        errors.push(`${label} must be an object`);
-        return;
-    }
-    if (isUnsafeTouchedPath(value.path)) {
-        errors.push(`${label}.path must be a repo-relative path without '..' segments`);
-    }
-    const mode = value.mode;
-    if (mode !== "tracked" && mode !== "untracked" && mode !== "deleted") {
-        errors.push(`${label}.mode must be one of tracked|untracked|deleted`);
-        return;
-    }
-    if (value.beforeSha256 !== undefined && !isHex64(value.beforeSha256)) {
-        errors.push(`${label}.beforeSha256 must be a 64-char hex digest when present`);
-    }
-    if (value.afterSha256 !== undefined && !isHex64(value.afterSha256)) {
-        errors.push(`${label}.afterSha256 must be a 64-char hex digest when present`);
-    }
-    if (mode === "untracked") {
-        if (!isHex64(value.afterSha256))
-            errors.push(`${label}.afterSha256 is required for untracked files`);
-        if (value.beforeSha256 !== undefined)
-            errors.push(`${label}.beforeSha256 must be absent for untracked files`);
-    }
-    if (mode === "deleted") {
-        if (!isHex64(value.beforeSha256))
-            errors.push(`${label}.beforeSha256 is required for deleted files`);
-        if (value.afterSha256 !== undefined)
-            errors.push(`${label}.afterSha256 must be absent for deleted files`);
-    }
-    if (mode === "tracked" && !isHex64(value.afterSha256)) {
-        errors.push(`${label}.afterSha256 is required for tracked files`);
-    }
-}
-function validateSession(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("session must be an object");
-        return;
-    }
-    if (value.leafId !== null && typeof value.leafId !== "string") {
-        errors.push("session.leafId must be a string or null");
-    }
-    if (!Array.isArray(value.branchPathIds) || value.branchPathIds.some((id) => typeof id !== "string")) {
-        errors.push("session.branchPathIds must be an array of strings");
-    }
-    if (!isHex64(value.contextHash)) {
-        errors.push("session.contextHash must be a 64-char hex digest");
-    }
-    if (value.sessionFile !== undefined && typeof value.sessionFile !== "string") {
-        errors.push("session.sessionFile must be a string when present");
-    }
-}
-function validateWorkspace(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("workspace must be an object");
-        return;
-    }
-    if (!isNonEmptyString(value.repoRoot))
-        errors.push("workspace.repoRoot must be a non-empty string");
-    if (value.vcs !== "git" && value.vcs !== "none")
-        errors.push("workspace.vcs must be one of git|none");
-    if (value.head !== undefined && typeof value.head !== "string") {
-        errors.push("workspace.head must be a string when present");
-    }
-    if (!isHex64(value.statusPorcelainSha256)) {
-        errors.push("workspace.statusPorcelainSha256 must be a 64-char hex digest");
-    }
-    if (value.reversePatchArtifact !== undefined && typeof value.reversePatchArtifact !== "string") {
-        errors.push("workspace.reversePatchArtifact must be a string when present");
-    }
-    if (!Array.isArray(value.touchedFiles)) {
-        errors.push("workspace.touchedFiles must be an array");
-        return;
-    }
-    value.touchedFiles.forEach((entry, index) => {
-        validateTouchedFile(entry, index, errors);
-    });
-}
-function validateTool(value, errors) {
-    if (value === undefined)
-        return;
-    if (!isPlainObject(value)) {
-        errors.push("tool must be an object when present");
-        return;
-    }
-    if (typeof value.turnIndex !== "number" || !Number.isInteger(value.turnIndex) || value.turnIndex < 0) {
-        errors.push("tool.turnIndex must be a non-negative integer");
-    }
-    if (!Array.isArray(value.mutatingTools) || value.mutatingTools.some((t) => typeof t !== "string")) {
-        errors.push("tool.mutatingTools must be an array of strings");
-    }
-    if (value.beforeToolCallId !== undefined && typeof value.beforeToolCallId !== "string") {
-        errors.push("tool.beforeToolCallId must be a string when present");
-    }
-    if (value.afterToolCallId !== undefined && typeof value.afterToolCallId !== "string") {
-        errors.push("tool.afterToolCallId must be a string when present");
-    }
-}
-function validateLedger(value, errors) {
-    if (!isPlainObject(value)) {
-        errors.push("ledger must be an object");
-        return;
-    }
-    if (!isNonEmptyString(value.eventId))
-        errors.push("ledger.eventId must be a non-empty string");
-    if (!isHex64(value.previousEventHash))
-        errors.push("ledger.previousEventHash must be a 64-char hex digest");
-    if (!isHex64(value.eventHash))
-        errors.push("ledger.eventHash must be a 64-char hex digest");
-}
-/**
- * Validate an untrusted value as a {@link RecoveryCheckpoint}. Pure and
- * fail-closed: any structural problem yields `ok: false` with explicit errors
- * and no `checkpoint` payload.
- */
-export function validateRecoveryCheckpoint(value) {
-    const errors = [];
-    if (!isPlainObject(value)) {
-        return { ok: false, errors: ["checkpoint must be an object"] };
-    }
-    if (value.schemaVersion !== RECOVERY_CHECKPOINT_SCHEMA_VERSION) {
-        errors.push(`schemaVersion must be ${RECOVERY_CHECKPOINT_SCHEMA_VERSION}`);
-    }
-    if (!isNonEmptyString(value.checkpointId))
-        errors.push("checkpointId must be a non-empty string");
-    if (!isIsoTimestamp(value.createdAt))
-        errors.push("createdAt must be an ISO-8601 timestamp");
-    validateSession(value.session, errors);
-    validateWorkspace(value.workspace, errors);
-    validateTool(value.tool, errors);
-    validateLedger(value.ledger, errors);
-    if (errors.length > 0)
-        return { ok: false, errors };
-    return { ok: true, errors: [], checkpoint: value };
-}
-/**
- * Compare a checkpoint's embedded ledger anchor with the anchor observed in the
- * live ledger. A mismatch means the checkpoint references an event that no
- * longer matches the durable audit trail (tamper or divergence) and the restore
- * must fail closed.
- */
-export function verifyCheckpointLedgerAnchor(checkpoint, observed) {
-    const mismatches = [];
-    if (checkpoint.ledger.eventId !== observed.eventId) {
-        mismatches.push(`eventId mismatch: checkpoint=${checkpoint.ledger.eventId} ledger=${observed.eventId}`);
-    }
-    if (checkpoint.ledger.previousEventHash !== observed.previousEventHash) {
-        mismatches.push("previousEventHash mismatch between checkpoint and ledger");
-    }
-    if (checkpoint.ledger.eventHash !== observed.eventHash) {
-        mismatches.push("eventHash mismatch between checkpoint and ledger");
-    }
-    return { ok: mismatches.length === 0, mismatches };
-}
-/**
- * Classify whether a code restore can proceed against the live worktree.
- *
- * Fail-closed rules (from the lane C restore algorithm):
- *  - any dirty path outside the recorded touched set blocks the restore;
- *  - any touched file whose current hash differs from the recorded `afterSha256`
- *    blocks the restore;
- *  - any symlink escaping the repo root blocks the restore;
- *  - a moved HEAD blocks the restore unless `allowNonHeadRestore` is set.
- */
-export function classifyRestorePreflight(checkpoint, observed, options = {}) {
-    const issues = [];
-    const touchedByPath = new Map();
-    for (const file of checkpoint.workspace.touchedFiles) {
-        touchedByPath.set(normalizeRelPath(file.path), file);
-    }
-    const unrelatedDirtyPaths = [];
-    for (const dirty of observed.dirtyPaths) {
-        if (!touchedByPath.has(normalizeRelPath(dirty))) {
-            unrelatedDirtyPaths.push(dirty);
-            issues.push({
-                code: "unrelated-dirty-path",
-                path: dirty,
-                detail: "dirty path is outside the checkpoint's recorded touched files",
-            });
-        }
-    }
-    const observedByPath = new Map();
-    for (const file of observed.touchedFiles) {
-        observedByPath.set(normalizeRelPath(file.path), file);
-    }
-    const hashMismatches = [];
-    const symlinkEscapes = [];
-    for (const expected of checkpoint.workspace.touchedFiles) {
-        const key = normalizeRelPath(expected.path);
-        const current = observedByPath.get(key);
-        if (!current) {
-            issues.push({
-                code: "missing-touched-file",
-                path: expected.path,
-                detail: "no observed state was provided for a recorded touched file",
-            });
-            continue;
-        }
-        if (current.escapesRepo === true || (current.isSymlink === true && current.escapesRepo !== false)) {
-            symlinkEscapes.push(expected.path);
-            issues.push({
-                code: "symlink-escape",
-                path: expected.path,
-                detail: "touched path is a symlink resolving outside the repo root",
-            });
-            continue;
-        }
-        if (expected.mode === "deleted") {
-            if (current.exists) {
-                hashMismatches.push(expected.path);
-                issues.push({
-                    code: "touched-hash-mismatch",
-                    path: expected.path,
-                    detail: "expected a deleted file to be absent but it is present",
-                });
-            }
-            continue;
-        }
-        if (!current.exists) {
-            issues.push({
-                code: "missing-touched-file",
-                path: expected.path,
-                detail: "recorded touched file is missing from the worktree",
-            });
-            continue;
-        }
-        if (current.sha256 !== expected.afterSha256) {
-            hashMismatches.push(expected.path);
-            issues.push({
-                code: "touched-hash-mismatch",
-                path: expected.path,
-                detail: "current file hash differs from the recorded post-edit hash",
-            });
-        }
-    }
-    const headChanged = checkpoint.workspace.vcs === "git" &&
-        checkpoint.workspace.head !== undefined &&
-        observed.head !== undefined &&
-        checkpoint.workspace.head !== observed.head;
-    if (headChanged && options.allowNonHeadRestore !== true) {
-        issues.push({
-            code: "head-mismatch",
-            detail: "HEAD moved since the checkpoint; pass allowNonHeadRestore to override",
-        });
-    }
-    return {
-        verdict: issues.length === 0 ? "clean" : "blocked",
-        issues,
-        unrelatedDirtyPaths,
-        hashMismatches,
-        symlinkEscapes,
-        headChanged,
-    };
-}
-/**
- * Decide how an OMK-created untracked file should be handled on restore.
- *
- *  - `skip`: the file is already gone, nothing to undo.
- *  - `delete`: the file still exactly matches what OMK created, safe to remove.
- *  - `quarantine`: the file changed since OMK created it; move it under the
- *    recovery quarantine directory rather than destroying user edits.
- */
-export function decideUntrackedDisposition(touched, observed) {
-    if (touched.mode !== "untracked") {
-        return { disposition: "skip", reason: "disposition only applies to untracked files" };
-    }
-    if (!observed.exists) {
-        return { disposition: "skip", reason: "untracked file is already absent" };
-    }
-    if (isHex64(touched.afterSha256) && observed.sha256 === touched.afterSha256) {
-        return { disposition: "delete", reason: "current hash matches the OMK-created hash" };
-    }
-    return { disposition: "quarantine", reason: "current hash differs from the OMK-created hash" };
-}
-function codePhase(checkpoint) {
-    return {
-        phase: "code",
-        action: "apply-reverse-patch",
-        recordedPaths: checkpoint.workspace.touchedFiles.map((file) => file.path),
-    };
-}
-function conversationPhase(checkpoint) {
-    return { phase: "conversation", action: "navigate-tree", targetLeafId: checkpoint.session.leafId };
-}
-function collectPreflightBlockers(preflight) {
-    if (!preflight)
-        return ["code restore requires a preflight classification"];
-    if (preflight.verdict === "clean")
-        return [];
-    return preflight.issues.map((issue) => (issue.path ? `${issue.code}: ${issue.path}` : issue.code));
-}
-/**
- * Build a restore plan for the requested mode.
- *
- *  - `conversation`: navigate the session tree to the checkpoint leaf; no file
- *    writes, so no worktree preflight is required.
- *  - `code`: apply the recorded reverse patch path-by-path; requires a clean
- *    preflight.
- *  - `both`: restore code first, then navigate the tree; requires a clean
- *    preflight. If the second (conversation) phase fails at execution time the
- *    caller marks the operation `in_doubt` and keeps `preservePreviousLeafId`.
- */
-export function planRestore(input) {
-    const { mode, checkpoint, preflight } = input;
-    if (mode === "conversation") {
-        return { mode, status: "ready", phases: [conversationPhase(checkpoint)], blockers: [] };
-    }
-    const blockers = collectPreflightBlockers(preflight);
-    if (mode === "code") {
-        if (blockers.length > 0)
-            return { mode, status: "blocked", phases: [], blockers };
-        return { mode, status: "ready", phases: [codePhase(checkpoint)], blockers: [] };
-    }
-    // mode === "both"
-    const preservePreviousLeafId = input.currentLeafId ?? null;
-    if (blockers.length > 0) {
-        return {
-            mode,
-            status: "blocked",
-            phases: [],
-            blockers,
-            preservePreviousLeafId,
-            inDoubtPolicy: "preserve-previous-leaf",
-        };
-    }
-    return {
-        mode,
-        status: "ready",
-        phases: [codePhase(checkpoint), conversationPhase(checkpoint)],
-        blockers: [],
-        preservePreviousLeafId,
-        inDoubtPolicy: "preserve-previous-leaf",
-    };
-}
-//# sourceMappingURL=recovery-checkpoint.js.map