sealkeep 0.8.1 → 0.11.0

package/dist/src/reclaim-transaction.d.ts

@@ -0,0 +1,156 @@
+export interface ExpectedFile {
+    bytes: number;
+    sha256: string;
+}
+export interface FileFingerprint extends ExpectedFile {
+    dev: string;
+    ino: string;
+    /** Filesystem blocks attributed to this inode (st_blocks * 512). */
+    allocatedBytes: number;
+    /** Link count at the instant of the fingerprint. */
+    links: number;
+    mtimeNs: string;
+    ctimeNs: string;
+}
+export interface ReclaimSourceLock {
+    readonly dataDir: string;
+    readonly sourcePath: string;
+    readonly lockPath: string;
+    readonly token: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface AcquireReclaimSourceLockOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+    malformedStaleMs?: number;
+    signal?: AbortSignal;
+}
+/** Cooperative checkpoint used by unattended reclaim while hashing large files. */
+export interface ReclaimIoOptions {
+    onYield?: () => void | Promise<void>;
+    /** Test-only ordering seam invoked while the synced inode is still open. */
+    afterFileSync?: (path: string) => void | Promise<void>;
+    /** Test-only race seam after the final staged-inode snapshot, before unlink. */
+    afterPurgeSnapshot?: (path: string) => void | Promise<void>;
+}
+export type ReclaimTransactionStage = "prepared" | "source-moved" | "replacement-installed" | "metadata-committed" | "purge-authorized";
+interface ReclaimJournalWire {
+    version: 1;
+    id: string;
+    sourcePath: string;
+    trashPath: string;
+    createdAt: string;
+    updatedAt: string;
+    stage: ReclaimTransactionStage;
+    original: FileFingerprint;
+    /** Codex keeps a tiny same-id resume pointer; other agents need no replacement. */
+    replacement: (FileFingerprint & {
+        tempPath: string;
+    }) | null;
+}
+export interface ReclaimTransaction extends ReclaimJournalWire {
+    dataDir: string;
+    journalPath: string;
+}
+export interface BeginReclaimTransactionInput {
+    sourcePath: string;
+    original: ExpectedFile;
+    replacement?: (ExpectedFile & {
+        tempPath: string;
+    }) | null;
+    transactionId?: string;
+}
+export interface ReconcileReclaimTransactionsOptions {
+    /**
+     * Required trust-boundary check for the journal's source and temp paths.
+     * Callers should validate sourcePath against their native session roots with
+     * validateNoFollowPath(..., { leaf: "missing-or-file" }).
+     */
+    validateTransaction(transaction: ReclaimTransaction): void | Promise<void>;
+    /**
+     * Upgrade-sensitive source-format gate, evaluated only after structural path
+     * validation. A rejection while original bytes still survive rolls the
+     * transaction back instead of letting an older prepared decision purge.
+     */
+    validatePurgeCandidate?(transaction: ReclaimTransaction): void | Promise<void>;
+    isMetadataCommitted(transaction: ReclaimTransaction): boolean | Promise<boolean>;
+    clearMetadataCommit?(transaction: ReclaimTransaction): void | Promise<void>;
+    /**
+     * Persist the append-only audit decision before irreversible deletion. This
+     * may be called again after a crash, so the audit payload must carry the
+     * transaction id and consumers must tolerate a duplicate decision record.
+     */
+    ensureAuditCommitted?(transaction: ReclaimTransaction): void | Promise<void>;
+    /**
+     * Repeat the external durability proof immediately before unlinking a staged
+     * original. This is required even for an already purge-authorized journal:
+     * authorization may have survived a power loss for days while the remote
+     * object was deleted in the meantime.
+     */
+    verifyPurgeStillSafe?(transaction: ReclaimTransaction): void | Promise<void>;
+    /** Persist the final, truthful "bytes purged" metadata before the journal leaves. */
+    onPurged?(transaction: ReclaimTransaction, freedBytes: number): void | Promise<void>;
+    lock?: AcquireReclaimSourceLockOptions;
+    io?: ReclaimIoOptions;
+}
+export interface ReconcileReclaimOutcome {
+    id: string;
+    sourcePath?: string;
+    status: "cleaned" | "rolled-back" | "completed" | "conflict";
+    detail: string;
+}
+export interface ValidateNoFollowPathOptions {
+    leaf?: "file" | "missing-or-file";
+}
+export declare class ReclaimConflictError extends Error {
+    readonly code = "RECLAIM_CONFLICT";
+    constructor(message: string);
+}
+export declare function reclaimSourceLockPath(dataDir: string, sourcePath: string): string;
+export declare function acquireReclaimSourceLock(dataDir: string, sourcePath: string, options?: AcquireReclaimSourceLockOptions): Promise<ReclaimSourceLock>;
+/**
+ * Publish a private, complete temp file at destination using create-if-absent
+ * semantics. Both paths must be on the same filesystem. EEXIST never removes
+ * or overwrites the destination.
+ */
+export declare function publishTempCreateIfAbsent(tempPath: string, destinationPath: string, expected: ExpectedFile, io?: ReclaimIoOptions): Promise<FileFingerprint>;
+/**
+ * Move an existing file to a unique park path without overwriting either name,
+ * then validate its content. On a digest mismatch the function restores the
+ * source name when possible and otherwise leaves the parked bytes intact.
+ */
+export declare function parkExistingPathNoClobber(sourcePath: string, parkPath: string, expected: ExpectedFile, io?: ReclaimIoOptions): Promise<FileFingerprint>;
+/** Restore a parked regular file at destination with create-if-absent semantics. */
+export declare function restoreParkedCreateIfAbsent(parkPath: string, destinationPath: string, expected?: ExpectedFile, io?: ReclaimIoOptions): Promise<FileFingerprint>;
+export declare function reclaimJournalPath(dataDir: string, transactionId: string): string;
+export declare function reclaimTrashPath(dataDir: string, transactionId: string, sourcePath: string): string;
+export declare function beginReclaimTransaction(dataDir: string, lock: ReclaimSourceLock, input: BeginReclaimTransactionInput, io?: ReclaimIoOptions): Promise<ReclaimTransaction>;
+export declare function moveReclaimSource(transaction: ReclaimTransaction, lock: ReclaimSourceLock, io?: ReclaimIoOptions): Promise<ReclaimTransaction>;
+export declare function installReclaimReplacement(transaction: ReclaimTransaction, lock: ReclaimSourceLock, io?: ReclaimIoOptions): Promise<ReclaimTransaction>;
+export declare function markReclaimMetadataCommitted(transaction: ReclaimTransaction, lock: ReclaimSourceLock): Promise<ReclaimTransaction>;
+/**
+ * Durable point of no return. Call this only after record metadata and the
+ * append-only audit decision have both committed successfully.
+ */
+export declare function markReclaimPurgeAuthorized(transaction: ReclaimTransaction, lock: ReclaimSourceLock): Promise<ReclaimTransaction>;
+export declare function finalizeReclaimTransaction(transaction: ReclaimTransaction, lock: ReclaimSourceLock, options?: {
+    onPurged?: (transaction: ReclaimTransaction, freedBytes: number) => void | Promise<void>;
+    verifyPurgeStillSafe?: (transaction: ReclaimTransaction) => void | Promise<void>;
+    io?: ReclaimIoOptions;
+}): Promise<{
+    freedBytes: number;
+}>;
+export declare function rollbackReclaimTransaction(transaction: ReclaimTransaction, lock: ReclaimSourceLock, options?: {
+    io?: ReclaimIoOptions;
+    /** Test seam for an append through an fd opened before pointer parking. */
+    afterReplacementParked?: (parkPath: string) => void | Promise<void>;
+}): Promise<void>;
+export declare function reconcileReclaimTransactions(dataDir: string, options: ReconcileReclaimTransactionsOptions): Promise<ReconcileReclaimOutcome[]>;
+/**
+ * Resolve a native-session path beneath an allowed root while rejecting
+ * symlinks in the root or any existing descendant component. The canonical
+ * root must equal its lexical path, so a symlinked native root is not trusted.
+ */
+export declare function validateNoFollowPath(candidatePath: string, roots: readonly string[], options?: ValidateNoFollowPathOptions): Promise<string>;
+export {};