@papillon6814/copi 0.1.0 → 0.2.0

package/dist/src/storage-root-lease.js

@@ -0,0 +1,92 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import path from "node:path";
+const macOsExclusiveLock = 0x20;
+function sameRootIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.isDirectory() && right.isDirectory() &&
+        !left.isSymbolicLink() && !right.isSymbolicLink();
+}
+function sameRoot(left, right) {
+    return sameRootIdentity(left, right) && left.mode === right.mode;
+}
+/** Holds a crash-released macOS O_EXLOCK on the library root directory descriptor. */
+export async function acquireRootLease(root, waitMilliseconds = 0) {
+    if (process.platform !== "darwin") {
+        throw new Error("Copi storage mutation requires the macOS root O_EXLOCK lease; no fallback is available.");
+    }
+    if (!path.isAbsolute(root) || path.resolve(root) !== root || await realpath(root) !== root) {
+        throw new Error("Copi storage root must be a canonical absolute directory for its O_EXLOCK lease.");
+    }
+    const before = await lstat(root, { bigint: true });
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+        throw new Error("Copi storage root is unsafe; refusing to acquire its O_EXLOCK lease.");
+    }
+    if (!Number.isSafeInteger(waitMilliseconds) || waitMilliseconds < 0)
+        throw new Error("O_EXLOCK wait duration must be a nonnegative safe integer.");
+    let handle;
+    const deadline = Date.now() + waitMilliseconds;
+    while (!handle) {
+        try {
+            handle = await open(root, constants.O_RDONLY | macOsExclusiveLock | constants.O_NONBLOCK);
+        }
+        catch (error) {
+            const code = error.code;
+            if ((code === "EAGAIN" || code === "EWOULDBLOCK") && Date.now() < deadline) {
+                await delay(Math.min(10, deadline - Date.now()));
+                continue;
+            }
+            if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+                throw new Error("Copi storage root remained leased by another process until the acquisition deadline; refusing mutation.", { cause: error });
+            }
+            throw new Error("Copi storage root O_EXLOCK lease is unavailable; refusing mutation without fallback.", { cause: error });
+        }
+    }
+    try {
+        const [opened, after, canonical] = await Promise.all([
+            handle.stat({ bigint: true }),
+            lstat(root, { bigint: true }),
+            realpath(root),
+        ]);
+        if (canonical !== root || !sameRoot(before, opened) || !sameRoot(opened, after)) {
+            throw new Error("Copi storage root identity changed while acquiring its O_EXLOCK lease.");
+        }
+        let expectedRoot = opened;
+        let closed = false;
+        return {
+            async assertCurrent() {
+                if (closed)
+                    throw new Error("Copi storage root O_EXLOCK lease is closed.");
+                const [currentHandle, currentPath, currentCanonical] = await Promise.all([
+                    handle.stat({ bigint: true }), lstat(root, { bigint: true }), realpath(root),
+                ]);
+                if (currentCanonical !== root || !sameRoot(expectedRoot, currentHandle) || !sameRoot(expectedRoot, currentPath)) {
+                    throw new Error("Copi storage root identity changed while its O_EXLOCK lease was held.");
+                }
+            },
+            async updateExpectedMode(mode) {
+                if (closed || !Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) {
+                    throw new Error("Copi storage root lease expected mode is invalid or closed.");
+                }
+                const [currentHandle, currentPath, currentCanonical] = await Promise.all([
+                    handle.stat({ bigint: true }), lstat(root, { bigint: true }), realpath(root),
+                ]);
+                if (currentCanonical !== root || !sameRootIdentity(expectedRoot, currentHandle) || !sameRootIdentity(expectedRoot, currentPath) ||
+                    currentHandle.mode !== currentPath.mode || Number(currentHandle.mode & 4095n) !== mode) {
+                    throw new Error("Copi storage root identity or requested mode changed before its lease baseline update.");
+                }
+                expectedRoot = currentHandle;
+            },
+            async close() {
+                if (closed)
+                    return;
+                closed = true;
+                await handle.close();
+            },
+        };
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}

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

@@ -0,0 +1,100 @@
+import type { InspectionWarning } from "./types.ts";
+import type { PreparedMigration } from "./migration.ts";
+export interface StorageFile {
+    readonly path: string;
+    readonly bytes: Buffer;
+    readonly mode: number;
+}
+export interface StorageReplacement {
+    readonly itemId: string;
+    readonly files: readonly StorageFile[];
+}
+export interface LegacyMigrationInput extends StorageFile {
+    readonly sha256: string;
+    readonly dev: string;
+    readonly ino: string;
+}
+declare const legacyMigrationReviewBrand: unique symbol;
+export interface LegacyMigrationReview {
+    readonly [legacyMigrationReviewBrand]: true;
+    readonly reviewId: string;
+}
+export interface LegacyMigrationApproval {
+    readonly reviewId: string;
+    readonly confirmed: boolean;
+    readonly approvedSensitivePaths: readonly string[];
+}
+declare const storageReviewBrand: unique symbol;
+export interface StorageReview {
+    readonly [storageReviewBrand]: true;
+    readonly reviewId: string;
+}
+export interface StorageReviewView {
+    readonly sensitivePaths: readonly string[];
+    readonly warnings: readonly InspectionWarning[];
+}
+export interface StorageAuthorization {
+    readonly review: StorageReview;
+    readonly approval: {
+        readonly reviewId: string;
+        readonly confirmed: boolean;
+        readonly approvedSensitivePaths: readonly string[];
+    };
+}
+export interface StorageRevision {
+    readonly root: string;
+    readonly catalog: string | null;
+    readonly catalogIdentity: string | null;
+    readonly format: "v1" | "v2";
+    readonly tree: string;
+}
+export type StorageCheckpoint = "stage-write" | "stage-sync" | "journal" | "before-swap" | "old-renamed" | "new-renamed" | "before-catalog" | "catalog-held" | "catalog-renamed" | "directory-sync" | "committed" | "rollback-started" | "rollback-displaced" | "rollback-restored" | "rollback-catalog-held" | "finalized" | "rollback-finalized";
+export interface StorageOptions {
+    checkpoint?: (point: StorageCheckpoint, root: string) => void | Promise<void>;
+    waitMilliseconds?: number;
+}
+interface StorageRunOptions {
+    requiresNativePlacement: boolean;
+}
+export declare function safeStoragePath(value: string): boolean;
+export declare function privateStoragePath(value: string): boolean;
+/** @internal Opaque review for callers of the generalized transaction adapter. Fixed bytes, no approval bypass flags. */
+export declare function prepareStorageReview(catalog: Buffer, replacements: readonly StorageReplacement[]): StorageReview;
+export declare function readStorageReview(review: StorageReview): StorageReviewView;
+/** @internal Returns a detached copy for the caller's private diff state, never a public review view. */
+export declare function readStorageBeforeReviewFiles(review: StorageReview, itemId: string): readonly StorageFile[];
+/** @internal Plan-bound bridge; the request is checked against the opaque public preview before issuance. */
+export declare function prepareLegacyMigrationReview(plan: PreparedMigration, value: unknown): Promise<LegacyMigrationReview>;
+export declare function absentStorageRevision(libraryDir: string): Promise<StorageRevision>;
+/** @internal Generalized fixed-byte persistence adapter. Inspection/approval are enforced here too; instance-bound faults cannot disable checks. */
+export declare class StorageTransactions {
+    private readonly options;
+    constructor(options?: StorageOptions);
+    run<T>(libraryDir: string, create: boolean, operation: (session: StorageSession | undefined) => Promise<T>, runOptions: StorageRunOptions): Promise<T>;
+    private recoverDead;
+}
+export declare class StorageSession {
+    #private;
+    readonly root: string;
+    private readonly lock;
+    private readonly token;
+    private readonly checkpoint?;
+    private readonly checkLegacyItems;
+    constructor(root: string, lock: string, token: string, checkpoint?: StorageOptions["checkpoint"], checkLegacyItems?: boolean);
+    private assertLease;
+    capture(): Promise<StorageRevision>;
+    assertRevision(expected: StorageRevision): Promise<void>;
+    /** @internal Captures a private, lease-bound before state for an explicitly confirmed sources review. */
+    prepareSourcesReview(expected: StorageRevision, catalog: Buffer, replacements: readonly StorageReplacement[]): Promise<StorageReview>;
+    commit(expected: StorageRevision, catalog: Buffer, replacements?: readonly StorageReplacement[], authorization?: StorageAuthorization): Promise<void>;
+    /** @internal Dedicated v1-to-v2 adopt-only path. Ordinary commit() deliberately remains v2-only. */
+    commitLegacyMigration(review: LegacyMigrationReview, approvalValue: LegacyMigrationApproval): Promise<void>;
+    private markFinalized;
+    private verifyFinalized;
+    private recoverNewSources;
+    private recoverCatalogOnly;
+    private recoverSources;
+    recover(rollback: boolean): Promise<void>;
+}
+export declare const storageTransactions: StorageTransactions;
+export {};