@openclaw/signal 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-acquire.js

@@ -0,0 +1,442 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { openSidecarRoot } from "./sidecar-lock-root.js";
+import { createNativeExclusiveFile } from "./native-operations.js";
+import { sidecarLockRetryDelay, sidecarLockTimeout, isTransientLockFileDenial, maxTransientLockDenials, validateSidecarLockStaleMs, validateSidecarLockRetryOptions, validateSidecarLockCompromiseCheckIntervalMs, validateSidecarLockTimeoutMs, } from "./sidecar-lock-policy.js";
+import { relativeSidecarLockPath, removeSidecarLockIfUnchanged, serializeSidecarLockPayload, sidecarReclaimGuardExists, } from "./sidecar-lock-reclaim.js";
+import { awaitSidecarAdmissionBoundary, conditionalSidecarLockParser, observeHeldSidecarParser, observeSidecarLockParser, runSidecarAdmissionBoundary, } from "./sidecar-lock-admission-parser.js";
+import { handleStaleSidecarAdmission, } from "./sidecar-lock-stale-admission.js";
+import { ancestryHasSidecarAdmission, captureSidecarAdmissionAncestry, createSidecarAdmissionController, } from "./sidecar-lock-admission-context.js";
+import { resolveSidecarLockPaths } from "./sidecar-lock-target.js";
+import { createSuppressedError } from "./suppressed-error.js";
+import { sleep } from "./timing.js";
+import { sidecarExclusiveCreate } from "./root-create-input.js";
+import { stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
+export async function acquireSidecarLock(options, context) {
+    const admissionAncestry = captureSidecarAdmissionAncestry();
+    const retainOnExit = options.retainOnExit;
+    context.assertRetainOnExitSupported(retainOnExit);
+    const retry = options.retry ?? {};
+    const timeoutMs = options.timeoutMs;
+    const staleMs = options.staleMs;
+    const compromiseCheckIntervalMs = options.compromiseCheckIntervalMs;
+    validateSidecarLockRetryOptions(retry);
+    validateSidecarLockTimeoutMs(timeoutMs);
+    validateSidecarLockStaleMs(staleMs);
+    validateSidecarLockCompromiseCheckIntervalMs(compromiseCheckIntervalMs);
+    const targetPath = options.targetPath;
+    const explicitLockPath = options.lockPath;
+    const lockRoot = options.lockRoot;
+    const requestedReentrantOwner = options.reentrantOwner;
+    const { lockPath, normalizedTargetPath } = await resolveSidecarLockPaths(targetPath, explicitLockPath, lockRoot);
+    const activeDescendant = ancestryHasSidecarAdmission(admissionAncestry, context.admissions, normalizedTargetPath);
+    const isReentrant = (candidate) => !!candidate &&
+        requestedReentrantOwner !== undefined &&
+        candidate.reentrantOwner !== undefined &&
+        requestedReentrantOwner === candidate.reentrantOwner;
+    const reuseHeldLock = (candidate) => {
+        const lifecycle = context.ensureExitCleanupRegistered();
+        context.assertRetainOnExitSupported(retainOnExit);
+        if (context.held.get(normalizedTargetPath) !== candidate || candidate.releasePromise)
+            return undefined;
+        candidate.refCount = (candidate.refCount ?? 1) + 1;
+        // Any same-owner request upgrades exit retention; later requests never revoke it.
+        if (retainOnExit === true)
+            candidate.retainOnExit = true;
+        const returnedHandle = context.handleForHeldLock(normalizedTargetPath, candidate);
+        context.armExitCleanup(lifecycle);
+        return returnedHandle;
+    };
+    let held = context.held.get(normalizedTargetPath);
+    if (isReentrant(held)) {
+        // Join a final release before deciding whether this completed owner remains.
+        // Successful cleanup requires a fresh acquisition; failed cleanup can retry.
+        if (held.releasePromise) {
+            if (activeDescendant)
+                throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+            await held.releasePromise.catch(() => undefined);
+            held = context.held.get(normalizedTargetPath);
+        }
+        if (isReentrant(held)) {
+            const reused = reuseHeldLock(held);
+            if (reused)
+                return reused;
+        }
+    }
+    if (activeDescendant)
+        throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+    const admission = createSidecarAdmissionController(admissionAncestry, context.admissions, normalizedTargetPath);
+    const startedAt = performance.now();
+    const reclaimGuardPath = `${lockPath}.reclaim`;
+    let reclaimGuard;
+    const releaseReclaimGuard = async () => {
+        if (!reclaimGuard)
+            return;
+        await admission.run(() => reclaimGuard.release());
+        reclaimGuard = undefined;
+    };
+    let attempt = 0;
+    // Bounded so a genuine denial still surfaces as EPERM, not a lock timeout.
+    let transientDenials = 0;
+    let payloadCallback;
+    let metadata = undefined;
+    let metadataObserved = false;
+    let onCompromised = undefined;
+    let onCompromisedObserved = false;
+    const staleOptionsState = {};
+    const withinDenialBudget = () => ++transientDenials <= maxTransientLockDenials;
+    const waitForRetry = async () => {
+        admission.release();
+        const delay = sidecarLockRetryDelay(retry, timeoutMs === Number.POSITIVE_INFINITY ? undefined : timeoutMs, performance.now() - startedAt, attempt);
+        if (delay === undefined)
+            throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+        attempt += 1;
+        await sleep(delay);
+    };
+    // Preserve a denial diagnosis if contention backoff has no remaining budget.
+    const retryOrRethrowDenial = async (denial) => {
+        try {
+            await waitForRetry();
+        }
+        catch (waitError) {
+            if (waitError?.code === "file_lock_timeout")
+                throw denial;
+            throw waitError;
+        }
+    };
+    const assertAdmissionToken = () => {
+        if (!admission.hasToken())
+            throw sidecarLockTimeout(lockPath, normalizedTargetPath);
+    };
+    try {
+        while (true) {
+            if (!admission.owns) {
+                held = context.held.get(normalizedTargetPath);
+                if (isReentrant(held)) {
+                    if (held.releasePromise) {
+                        await held.releasePromise.catch(() => undefined);
+                        held = context.held.get(normalizedTargetPath);
+                    }
+                    if (isReentrant(held)) {
+                        const reused = reuseHeldLock(held);
+                        if (reused)
+                            return reused;
+                        continue;
+                    }
+                }
+                if (context.admissions.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+                admission.reserve();
+            }
+            const attemptHeld = context.held.get(normalizedTargetPath);
+            const holderWasReplaced = () => {
+                const current = context.held.get(normalizedTargetPath);
+                return current !== undefined && current !== attemptHeld;
+            };
+            const lifecycle = admission.run(() => context.ensureExitCleanupRegistered());
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            admission.run(() => context.assertRetainOnExitSupported(retainOnExit));
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            if (reclaimGuard?.assertHeld)
+                await admission.run(() => reclaimGuard.assertHeld());
+            const reclaimGuardExists = !reclaimGuard && (await (lockRoot
+                ? admission.run(() => sidecarReclaimGuardExists(reclaimGuardPath, lockRoot))
+                : sidecarReclaimGuardExists(reclaimGuardPath)));
+            assertAdmissionToken();
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            if (reclaimGuardExists) {
+                await waitForRetry();
+                continue;
+            }
+            let handle = null;
+            let createdSnapshot = null, createdHeld;
+            let admissionConflict = false;
+            let exclusiveCreateConflict = false;
+            let lockFileCreateDenied = false;
+            const parserState = { observed: false };
+            if (!payloadCallback)
+                payloadCallback = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.payload);
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            const { value: payload } = await awaitSidecarAdmissionBoundary(admission, assertAdmissionToken, () => Reflect.apply(payloadCallback, options, []));
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            const { raw, ownershipToken } = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => serializeSidecarLockPayload(payload));
+            if (holderWasReplaced()) {
+                await waitForRetry();
+                continue;
+            }
+            held = context.held.get(normalizedTargetPath);
+            if (held?.releasePromise) {
+                // Release cleanup never acquires this admission; retaining it here lets
+                // the serialized attempt continue without another callback or retry.
+                await held.releasePromise.catch(() => undefined);
+                assertAdmissionToken();
+                held = context.held.get(normalizedTargetPath);
+            }
+            if (held?.lockPath === lockPath) {
+                const observedHeld = held;
+                const observation = await observeHeldSidecarParser({
+                    admission, assertToken: assertAdmissionToken,
+                    currentHeld: () => context.held.get(normalizedTargetPath), held: observedHeld,
+                    lockPath, lockRoot, parserState,
+                    parserAccessor: () => options.parsePayload,
+                    isTransientDenial: (error) => isTransientLockFileDenial(error, lockPath),
+                });
+                assertAdmissionToken();
+                held = context.held.get(normalizedTargetPath);
+                if (held !== observedHeld || observedHeld.releasePromise) {
+                    await waitForRetry();
+                    continue;
+                }
+                if (observation.kind === "read-error") {
+                    if (!observation.transientDenial || !withinDenialBudget())
+                        throw observation.error;
+                    await retryOrRethrowDenial(observation.error);
+                    continue;
+                }
+            }
+            if (held) {
+                await waitForRetry();
+                continue;
+            }
+            if (!metadataObserved) {
+                metadata = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.metadata);
+                metadataObserved = true;
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+            }
+            if (!onCompromisedObserved) {
+                onCompromised = runSidecarAdmissionBoundary(admission, assertAdmissionToken, () => options.onCompromised);
+                onCompromisedObserved = true;
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+            }
+            assertAdmissionToken();
+            if (context.held.has(normalizedTargetPath)) {
+                await waitForRetry();
+                continue;
+            }
+            try {
+                if (lockRoot) {
+                    const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
+                    const observation = fileObservation();
+                    try {
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { ...sidecarExclusiveCreate, mkdir: true, mode: 0o600 }));
+                    }
+                    catch (error) {
+                        // Only this invocation's failed exclusive open grants denial retry authority.
+                        lockFileCreateDenied = observation.has(error, `exclusive-create:${lockPath}`) &&
+                            isTransientLockFileDenial(error, lockPath);
+                        if (error instanceof FsSafeError && error.code === "already-exists") {
+                            exclusiveCreateConflict = true;
+                            throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
+                        }
+                        throw error;
+                    }
+                    createdSnapshot = { raw, payload, ownershipToken };
+                    const opened = await openSidecarRoot(lockRoot, relativeLockPath, "unlinked");
+                    if (!opened) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    try {
+                        // Root.open admits the current file, not necessarily the one we created.
+                        const currentRaw = await readFileHandleBounded(opened.handle, Buffer.byteLength(raw));
+                        if (!currentRaw.equals(Buffer.from(raw))) {
+                            throw new FsSafeError("path-mismatch", "created sidecar lock changed before admission");
+                        }
+                    }
+                    catch (error) {
+                        await opened.handle.close().catch(() => undefined);
+                        throw error;
+                    }
+                    handle = opened.handle;
+                }
+                else {
+                    try {
+                        handle =
+                            (await createNativeExclusiveFile(lockPath, 0o600)) ??
+                                (await fs.open(lockPath, "wx", 0o600));
+                    }
+                    catch (createError) {
+                        lockFileCreateDenied = isTransientLockFileDenial(createError, lockPath);
+                        exclusiveCreateConflict = createError.code === "EEXIST";
+                        throw createError;
+                    }
+                    await handle.writeFile(raw, "utf8");
+                }
+                const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd, { bigint: true }), ownershipToken };
+                createdSnapshot = snapshot;
+                if (snapshot.stat.nlink === 0n) {
+                    await handle.close();
+                    handle = null;
+                    await waitForRetry();
+                    continue;
+                }
+                observeSidecarLockParser(parserState, admission, () => options.parsePayload, assertAdmissionToken);
+                if (context.held.has(normalizedTargetPath)) {
+                    admissionConflict = true;
+                    throw Object.assign(new Error("sidecar lock admission changed"), { code: "EEXIST" });
+                }
+                createdHeld = {
+                    refCount: 1,
+                    reentrantOwner: requestedReentrantOwner,
+                    handle,
+                    lockPath,
+                    snapshot,
+                    acquiredAt: Date.now(),
+                    metadata: metadata ?? {},
+                    lockRoot,
+                    retainOnExit,
+                    parsePayload: parserState.parser,
+                };
+                const candidateHeld = createdHeld;
+                if (reclaimGuard)
+                    await releaseReclaimGuard();
+                const returnedHandle = admission.run(() => context.handleForHeldLock(normalizedTargetPath, candidateHeld));
+                if (onCompromised &&
+                    compromiseCheckIntervalMs !== undefined &&
+                    compromiseCheckIntervalMs > 0) {
+                    const compromisedCallback = onCompromised;
+                    let compromiseCheckInFlight = false;
+                    candidateHeld.compromiseTimer = admission.run(() => setInterval(() => {
+                        if (compromiseCheckInFlight)
+                            return;
+                        compromiseCheckInFlight = true;
+                        void returnedHandle
+                            .verifyStillHeld()
+                            .catch(() => false)
+                            .then((stillHeld) => {
+                            if (!stillHeld && candidateHeld.compromiseTimer) {
+                                stopSidecarLockMonitoring(candidateHeld);
+                                Reflect.apply(compromisedCallback, options, [{ lockPath, normalizedTargetPath }]);
+                            }
+                        })
+                            .finally(() => {
+                            compromiseCheckInFlight = false;
+                        });
+                    }, compromiseCheckIntervalMs));
+                    admission.run(() => candidateHeld.compromiseTimer?.unref());
+                }
+                if (!admission.hasToken() ||
+                    context.held.has(normalizedTargetPath)) {
+                    admissionConflict = true;
+                    throw Object.assign(new Error("sidecar lock admission changed"), { code: "EEXIST" });
+                }
+                context.held.set(normalizedTargetPath, candidateHeld);
+                admission.release();
+                context.armExitCleanup(lifecycle);
+                return returnedHandle;
+            }
+            catch (err) {
+                try {
+                    if (createdHeld)
+                        stopSidecarLockMonitoring(createdHeld);
+                    let failedSnapshot = createdSnapshot;
+                    if (handle) {
+                        failedSnapshot ??= { payload: null };
+                        try {
+                            failedSnapshot.stat = fsSync.fstatSync(handle.fd, { bigint: true });
+                        }
+                        catch {
+                            // Best-effort cleanup of a failed exclusive create.
+                        }
+                        const current = context.held.get(normalizedTargetPath);
+                        if (createdHeld && current === createdHeld) {
+                            context.held.delete(normalizedTargetPath);
+                        }
+                        await handle.close().catch(() => undefined);
+                    }
+                    // Root records use the creator receipt; partial raw writes use fd identity.
+                    if (failedSnapshot) {
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
+                            lockRoot,
+                            parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),
+                        });
+                    }
+                }
+                catch (cleanupError) {
+                    throw createSuppressedError(cleanupError, err, "file lock acquisition and cleanup both failed");
+                }
+                if (admissionConflict) {
+                    await waitForRetry();
+                    continue;
+                }
+                if (lockFileCreateDenied) {
+                    assertAdmissionToken();
+                    if (context.held.has(normalizedTargetPath)) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    if (withinDenialBudget()) {
+                        await retryOrRethrowDenial(err);
+                        continue;
+                    }
+                    throw err;
+                }
+                if (!exclusiveCreateConflict)
+                    throw err;
+                assertAdmissionToken();
+                if (context.held.has(normalizedTargetPath)) {
+                    await waitForRetry();
+                    continue;
+                }
+                if (reclaimGuard) {
+                    await releaseReclaimGuard();
+                    await waitForRetry();
+                    continue;
+                }
+                await handleStaleSidecarAdmission({
+                    admission,
+                    assertToken: assertAdmissionToken,
+                    currentHeld: () => context.held.get(normalizedTargetPath),
+                    lockPath,
+                    lockRoot,
+                    normalizedTargetPath,
+                    options,
+                    parserState,
+                    reclaimGuardPath,
+                    reclaimGuards: context.reclaimGuards,
+                    setReclaimGuard: (guard) => { reclaimGuard = guard; },
+                    releaseReclaimGuard,
+                    staleOptionsState,
+                    staleMs,
+                    withinDenialBudget,
+                    retryOrRethrowDenial,
+                    waitForRetry,
+                });
+                continue;
+            }
+        }
+    }
+    finally {
+        if (reclaimGuard)
+            await releaseReclaimGuard().catch(() => undefined);
+        admission.release();
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-context.d.ts

@@ -0,0 +1,18 @@
+type AdmissionIdentity = {
+    active: boolean;
+    admissions: Map<string, object>;
+    normalizedTargetPath: string;
+    token: object;
+};
+type SidecarAdmissionAncestry = readonly AdmissionIdentity[];
+/** Capture active ancestry now; later lifecycle changes cannot reclassify this call. */
+export declare function captureSidecarAdmissionAncestry(): SidecarAdmissionAncestry;
+export declare function ancestryHasSidecarAdmission(ancestry: SidecarAdmissionAncestry, admissions: Map<string, object>, normalizedTargetPath: string): boolean;
+export declare function createSidecarAdmissionController(ancestry: SidecarAdmissionAncestry, admissions: Map<string, object>, normalizedTargetPath: string): {
+    readonly owns: boolean;
+    hasToken: () => boolean;
+    release(): void;
+    reserve(): void;
+    run<T>(callback: () => T): T;
+};
+export {};

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-context.js

@@ -0,0 +1,60 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const EMPTY_ANCESTRY = Object.freeze([]);
+const GLOBAL_CONTEXT_KEY = Symbol.for("fsSafe.sidecarLockAdmissionAsyncContext");
+function admissionContext() {
+    const shared = globalThis;
+    return shared[GLOBAL_CONTEXT_KEY] ??=
+        new AsyncLocalStorage();
+}
+/** Capture active ancestry now; later lifecycle changes cannot reclassify this call. */
+export function captureSidecarAdmissionAncestry() {
+    const current = admissionContext().getStore();
+    if (!current)
+        return EMPTY_ANCESTRY;
+    const active = current.ancestry.filter((entry) => entry.active);
+    if (current.active)
+        active.push(current);
+    return active.length === 0 ? EMPTY_ANCESTRY : active;
+}
+export function ancestryHasSidecarAdmission(ancestry, admissions, normalizedTargetPath) {
+    return ancestry.some((entry) => entry.admissions === admissions && entry.normalizedTargetPath === normalizedTargetPath);
+}
+function createSidecarAdmissionScope(ancestry, admissions, normalizedTargetPath, token) {
+    return { active: false, admissions, ancestry, normalizedTargetPath, started: false, token };
+}
+function activateSidecarAdmissionScope(scope) {
+    if (scope.started)
+        throw new Error("sidecar admission scope cannot be reactivated");
+    scope.started = true;
+    scope.active = true;
+}
+function deactivateSidecarAdmissionScope(scope) {
+    if (scope)
+        scope.active = false;
+}
+function runInSidecarAdmissionScope(scope, callback) {
+    return scope?.active ? admissionContext().run(scope, callback) : callback();
+}
+export function createSidecarAdmissionController(ancestry, admissions, normalizedTargetPath) {
+    let scope;
+    const hasToken = () => scope !== undefined && admissions.get(normalizedTargetPath) === scope.token;
+    return {
+        get owns() { return scope !== undefined; },
+        hasToken,
+        release() {
+            deactivateSidecarAdmissionScope(scope);
+            if (hasToken())
+                admissions.delete(normalizedTargetPath);
+            scope = undefined;
+        },
+        reserve() {
+            const token = {};
+            scope = createSidecarAdmissionScope(ancestry, admissions, normalizedTargetPath, token);
+            admissions.set(normalizedTargetPath, token);
+            activateSidecarAdmissionScope(scope);
+        },
+        run(callback) {
+            return runInSidecarAdmissionScope(scope, callback);
+        },
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-parser.d.ts

@@ -0,0 +1,41 @@
+import type { Root } from "./root-impl.js";
+import type { HeldSidecarLock } from "./sidecar-lock-admission.js";
+import { readSidecarLockRawSnapshot, type SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
+export type SidecarAdmissionRunner = {
+    hasToken(): boolean;
+    run<T>(callback: () => T): T;
+};
+export declare function runSidecarAdmissionBoundary<T>(admission: SidecarAdmissionRunner, assertCurrent: () => void, callback: () => T): T;
+export declare function awaitSidecarAdmissionBoundary<T>(admission: SidecarAdmissionRunner, assertCurrent: () => void, callback: () => T | PromiseLike<T>): Promise<{
+    readonly value: Awaited<T>;
+}>;
+export type SidecarLockParserState = {
+    observed: boolean;
+    parser?: (raw: string) => unknown;
+};
+export declare function observeSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, accessor: () => ((raw: string) => unknown) | undefined, assertCurrent: () => void): void;
+export declare function scopedSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, assertCurrent: () => void): ((raw: string) => unknown) | undefined;
+/** Cleanup may outlive its reservation; never invoke user code after authority is lost. */
+export declare function conditionalSidecarLockParser(state: SidecarLockParserState, admission: SidecarAdmissionRunner, isCurrent: () => boolean): ((raw: string) => unknown) | undefined;
+export declare function parseSidecarLockSnapshotUnderAdmission(raw: Awaited<ReturnType<typeof readSidecarLockRawSnapshot>>, state: SidecarLockParserState, admission: SidecarAdmissionRunner, assertCurrent: () => void): SidecarLockSnapshot | null;
+export type HeldSidecarParserObservation = {
+    kind: "observed";
+} | {
+    kind: "holder-changed";
+} | {
+    kind: "read-error";
+    error: unknown;
+    transientDenial: boolean;
+};
+/** Emulate the historical EEXIST read/parser boundary without opening another sidecar. */
+export declare function observeHeldSidecarParser(params: {
+    admission: SidecarAdmissionRunner;
+    assertToken(): void;
+    currentHeld(): HeldSidecarLock | undefined;
+    held: HeldSidecarLock;
+    lockPath: string;
+    lockRoot?: Root;
+    parserState: SidecarLockParserState;
+    parserAccessor(): ((raw: string) => unknown) | undefined;
+    isTransientDenial(error: unknown): boolean;
+}): Promise<HeldSidecarParserObservation>;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission-parser.js

@@ -0,0 +1,113 @@
+import { parseSidecarLockSnapshot, readSidecarLockRawSnapshot, } from "./sidecar-lock-reclaim.js";
+export function runSidecarAdmissionBoundary(admission, assertCurrent, callback) {
+    assertCurrent();
+    try {
+        return admission.run(callback);
+    }
+    finally {
+        assertCurrent();
+    }
+}
+export async function awaitSidecarAdmissionBoundary(admission, assertCurrent, callback) {
+    assertCurrent();
+    try {
+        return await admission.run(async () => {
+            const boxed = Object.create(null);
+            Object.defineProperty(boxed, "value", {
+                value: undefined, enumerable: true, writable: true,
+            });
+            boxed.value = await callback();
+            return boxed;
+        });
+    }
+    finally {
+        assertCurrent();
+    }
+}
+export function observeSidecarLockParser(state, admission, accessor, assertCurrent) {
+    assertCurrent();
+    if (state.observed)
+        return;
+    try {
+        state.parser = admission.run(accessor);
+    }
+    finally {
+        assertCurrent();
+    }
+    state.observed = true;
+}
+export function scopedSidecarLockParser(state, admission, assertCurrent) {
+    const parser = state.parser;
+    return parser && ((raw) => admission.run(() => {
+        assertCurrent();
+        try {
+            return Reflect.apply(parser, undefined, [raw]);
+        }
+        finally {
+            assertCurrent();
+        }
+    }));
+}
+/** Cleanup may outlive its reservation; never invoke user code after authority is lost. */
+export function conditionalSidecarLockParser(state, admission, isCurrent) {
+    const parser = state.parser;
+    return parser && ((raw) => {
+        if (!isCurrent())
+            return undefined;
+        return admission.run(() => {
+            if (!isCurrent())
+                return undefined;
+            let parsed;
+            try {
+                parsed = Reflect.apply(parser, undefined, [raw]);
+            }
+            catch (error) {
+                if (!isCurrent())
+                    return undefined;
+                throw error;
+            }
+            return isCurrent() ? parsed : undefined;
+        });
+    });
+}
+export function parseSidecarLockSnapshotUnderAdmission(raw, state, admission, assertCurrent) {
+    return parseSidecarLockSnapshot(raw, scopedSidecarLockParser(state, admission, assertCurrent));
+}
+/** Emulate the historical EEXIST read/parser boundary without opening another sidecar. */
+export async function observeHeldSidecarParser(params) {
+    const holderChanged = {};
+    const assertCurrentHolder = () => {
+        params.assertToken();
+        if (params.currentHeld() !== params.held || params.held.releasePromise) {
+            throw holderChanged;
+        }
+    };
+    let transientDenial = false;
+    let raw;
+    try {
+        raw = await params.admission.run(async () => await readSidecarLockRawSnapshot(params.lockPath, {
+            lockRoot: params.lockRoot,
+            rejectNonFile: true,
+            discardObservation: "changed",
+            onOpenFailure: (error) => { transientDenial = params.isTransientDenial(error); },
+        }));
+    }
+    catch (error) {
+        return { kind: "read-error", error, transientDenial };
+    }
+    params.assertToken();
+    if (params.currentHeld() !== params.held || params.held.releasePromise) {
+        return { kind: "holder-changed" };
+    }
+    try {
+        observeSidecarLockParser(params.parserState, params.admission, params.parserAccessor, assertCurrentHolder);
+        parseSidecarLockSnapshotUnderAdmission(raw, params.parserState, params.admission, assertCurrentHolder);
+        assertCurrentHolder();
+    }
+    catch (error) {
+        if (error === holderChanged)
+            return { kind: "holder-changed" };
+        throw error;
+    }
+    return { kind: "observed" };
+}