clawconnect-agent 0.1.39 → 0.1.41

package/dist/core/relay/reliable-relay-outbox-registry.js

@@ -0,0 +1,81 @@
+import { resolve } from "node:path";
+import { normalizeRelayServerIdentity } from "./file-upload-utils.js";
+import { ReliableRelayOutbox } from "./reliable-relay-outbox.js";
+import { reliableRelayOutboxStorageDirectory } from "./reliable-relay-outbox-store.js";
+export const RELIABLE_RELAY_OUTBOX_MAX_GATEWAYS = 64;
+const outboxesByNamespace = new Map();
+/**
+ * Relay、profile 存储目录和 gateway 共同定义唯一队列，禁止跨 Relay 误重放。
+ */
+export function reliableRelayOutboxForGateway(gatewayId, options = {}) {
+    const normalized = typeof gatewayId === "string" ? gatewayId.trim() : "";
+    if (!normalized) {
+        return rejectedLookup("gateway_id_required", "reliable_relay_gateway_id_required");
+    }
+    const relayIdentity = options.relayIdentity?.trim();
+    if (!relayIdentity) {
+        return rejectedLookup("relay_identity_required", "reliable_relay_relay_identity_required");
+    }
+    let canonicalRelayIdentity;
+    try {
+        canonicalRelayIdentity = normalizeRelayServerIdentity(relayIdentity);
+    }
+    catch (value) {
+        return rejectedLookup("relay_identity_required", `reliable_relay_relay_identity_invalid: ${asError(value).message}`);
+    }
+    const storageDirectory = options.storageDirectory ?? reliableRelayOutboxStorageDirectory();
+    const registryKey = `${resolve(storageDirectory)}\u0000${canonicalRelayIdentity}\u0000${normalized}`;
+    const existing = outboxesByNamespace.get(registryKey);
+    if (existing) {
+        outboxesByNamespace.delete(registryKey);
+        outboxesByNamespace.set(registryKey, existing);
+        return { status: "ready", outbox: existing };
+    }
+    pruneIdleOutboxes();
+    if (outboxesByNamespace.size >= RELIABLE_RELAY_OUTBOX_MAX_GATEWAYS) {
+        return rejectedLookup("gateway_limit_reached", "reliable_relay_gateway_outbox_limit_reached");
+    }
+    let created;
+    try {
+        created = new ReliableRelayOutbox(normalized, {
+            storageDirectory,
+            relayIdentity: canonicalRelayIdentity,
+        });
+    }
+    catch (value) {
+        const error = asError(value);
+        return rejectedLookup("storage_unavailable", `reliable_relay_outbox_storage_unavailable: ${error.message}`);
+    }
+    outboxesByNamespace.set(registryKey, created);
+    return { status: "ready", outbox: created };
+}
+export function clearReliableRelayOutboxesForTests() {
+    disposeReliableRelayOutboxes();
+}
+export function disposeReliableRelayOutboxes() {
+    for (const outbox of outboxesByNamespace.values())
+        outbox.dispose();
+    outboxesByNamespace.clear();
+}
+function rejectedLookup(reason, message) {
+    const error = new Error(message);
+    console.warn(`[relay] reliable outbox unavailable: ${message}`);
+    return { status: "rejected", reason, error };
+}
+function pruneIdleOutboxes() {
+    if (outboxesByNamespace.size < RELIABLE_RELAY_OUTBOX_MAX_GATEWAYS)
+        return;
+    for (const [namespace, outbox] of outboxesByNamespace) {
+        // 在线连接即使暂时为空也仍拥有该队列，不能为了容量回收关闭其持久化存储。
+        if (outbox.isIdleForRegistryEviction) {
+            outbox.dispose();
+            outboxesByNamespace.delete(namespace);
+            if (outboxesByNamespace.size < RELIABLE_RELAY_OUTBOX_MAX_GATEWAYS)
+                return;
+        }
+    }
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+//# sourceMappingURL=reliable-relay-outbox-registry.js.map

package/dist/core/relay/reliable-relay-outbox-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliable-relay-outbox-registry.js","sourceRoot":"","sources":["../../../src/core/relay/reliable-relay-outbox-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/relay/reliable-relay-outbox-store.d.ts

@@ -0,0 +1,67 @@
+export type StoredReliableRelayOutboxEntry = {
+    key: string;
+    message: unknown;
+    byteLength: number;
+    contentHash: string;
+    mode: "event_ack" | "response_ack";
+    deliveryId?: string;
+};
+export interface ReliableRelayOutboxStore {
+    load(): readonly StoredReliableRelayOutboxEntry[];
+    put(entry: StoredReliableRelayOutboxEntry): void;
+    remove(key: string): void;
+    close(): void;
+}
+export type FileReliableRelayOutboxStoreOptions = {
+    directory: string;
+    gatewayId: string;
+    relayIdentity: string;
+    onMaintenanceError?: (error: Error) => void;
+};
+/**
+ * Single-writer, append-only WAL for one profile/gateway outbox.
+ *
+ * Every mutation is fsync'd before returning. Compaction writes a complete,
+ * checkpointed next generation before retiring the previous one, so a crash
+ * can leave at most a truncated final record or an incomplete higher
+ * generation; startup safely falls back to the newest complete checkpoint.
+ *
+ * 每次变更返回前必须完成 fsync；压缩时先写完整的新代 checkpoint，再淘汰旧代，
+ * 因而崩溃只会留下可忽略的尾部残片或不完整的新代，不会覆盖最后一个有效状态。
+ */
+export declare class FileReliableRelayOutboxStore implements ReliableRelayOutboxStore {
+    private readonly options;
+    private readonly gatewayHash;
+    private readonly filePrefix;
+    private readonly lockPath;
+    private readonly operationLockPath;
+    private readonly lockToken;
+    private readonly onMaintenanceError?;
+    private readonly entries;
+    private lockFd?;
+    private journalFd?;
+    private journalPath;
+    private generation;
+    private journalBytes;
+    private closed;
+    private failed;
+    constructor(options: FileReliableRelayOutboxStoreOptions);
+    load(): readonly StoredReliableRelayOutboxEntry[];
+    put(entry: StoredReliableRelayOutboxEntry): void;
+    remove(key: string): void;
+    close(): void;
+    private acquireLock;
+    private acquireOperationLock;
+    private releaseOperationLock;
+    private openNewestGeneration;
+    private generationPaths;
+    private append;
+    private compactIfNeeded;
+    private activateNewGeneration;
+    private removeInactiveGenerations;
+    private nextGeneration;
+    private assertUsable;
+    private reportMaintenanceError;
+}
+export declare function reliableRelayOutboxStorageDirectory(profile?: string): string;
+export declare function clearReliableRelayOutboxStorage(profile?: string): void;

package/dist/core/relay/reliable-relay-outbox-store.js

@@ -0,0 +1,527 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fstatSync, fsyncSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { profileRoot } from "../../config/profile.js";
+import { setRestrictiveDirPermissions, setRestrictiveFilePermissions, } from "../../platform/service-manager-common.js";
+import { normalizeRelayServerIdentity } from "./file-upload-utils.js";
+const STORE_VERSION = 1;
+const STORE_DIR_NAME = "reliable-outbox-v1";
+const COMPACTION_MIN_BYTES = 1024 * 1024;
+const COMPACTION_HEADROOM_BYTES = 256 * 1024;
+const MAX_JOURNAL_BYTES = 256 * 1024 * 1024;
+/**
+ * Single-writer, append-only WAL for one profile/gateway outbox.
+ *
+ * Every mutation is fsync'd before returning. Compaction writes a complete,
+ * checkpointed next generation before retiring the previous one, so a crash
+ * can leave at most a truncated final record or an incomplete higher
+ * generation; startup safely falls back to the newest complete checkpoint.
+ *
+ * 每次变更返回前必须完成 fsync；压缩时先写完整的新代 checkpoint，再淘汰旧代，
+ * 因而崩溃只会留下可忽略的尾部残片或不完整的新代，不会覆盖最后一个有效状态。
+ */
+export class FileReliableRelayOutboxStore {
+    options;
+    gatewayHash;
+    filePrefix;
+    lockPath;
+    operationLockPath;
+    lockToken = randomUUID();
+    onMaintenanceError;
+    entries = new Map();
+    lockFd;
+    journalFd;
+    journalPath = "";
+    generation = 0;
+    journalBytes = 0;
+    closed = false;
+    failed = false;
+    constructor(options) {
+        this.options = options;
+        this.gatewayHash = createHash("sha256")
+            .update(normalizeRelayServerIdentity(options.relayIdentity))
+            .update("\u0000")
+            .update(options.gatewayId)
+            .digest("hex");
+        this.filePrefix = `${this.gatewayHash}.`;
+        this.lockPath = join(options.directory, `${this.gatewayHash}.lock`);
+        this.operationLockPath = operationLockPath(options.directory);
+        this.onMaintenanceError = options.onMaintenanceError;
+        try {
+            mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+            setRestrictiveDirPermissions(options.directory);
+            this.acquireOperationLock();
+            try {
+                this.acquireLock();
+                this.openNewestGeneration();
+            }
+            finally {
+                this.releaseOperationLock();
+            }
+        }
+        catch (error) {
+            this.close();
+            throw error;
+        }
+    }
+    load() {
+        this.assertUsable();
+        return [...this.entries.values()];
+    }
+    put(entry) {
+        this.assertUsable();
+        if (this.entries.has(entry.key)) {
+            throw new Error(`reliable_outbox_store_duplicate_put key=${entry.key}`);
+        }
+        this.append({ v: STORE_VERSION, kind: "put", entry });
+        this.entries.set(entry.key, entry);
+        this.compactIfNeeded();
+    }
+    remove(key) {
+        this.assertUsable();
+        if (!this.entries.has(key)) {
+            throw new Error(`reliable_outbox_store_missing_remove key=${key}`);
+        }
+        this.append({ v: STORE_VERSION, kind: "remove", key });
+        this.entries.delete(key);
+        this.compactIfNeeded();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.journalFd !== undefined) {
+            try {
+                closeSync(this.journalFd);
+            }
+            catch { /* best effort */ }
+            this.journalFd = undefined;
+        }
+        if (this.lockFd !== undefined) {
+            try {
+                closeSync(this.lockFd);
+            }
+            catch { /* best effort */ }
+            this.lockFd = undefined;
+        }
+        try {
+            const lock = JSON.parse(readFileSync(this.lockPath, "utf8"));
+            if (lock.token === this.lockToken)
+                unlinkSync(this.lockPath);
+        }
+        catch {
+            // A crashed process leaves a stale lock which the next owner repairs.
+        }
+    }
+    acquireLock() {
+        // 操作锁把“检查旧 owner → 删除陈旧锁 → 创建新 owner”串成单写者临界区，
+        // 防止两个重启进程同时清理同一把陈旧锁后双写 WAL。
+        if (existsSync(this.lockPath)) {
+            const owner = readLockOwner(this.lockPath);
+            if (owner.status !== "stale") {
+                throw new Error(`reliable_outbox_store_locked gatewayHash=${this.gatewayHash}`);
+            }
+            unlinkSync(this.lockPath);
+        }
+        let fd;
+        try {
+            fd = openSync(this.lockPath, "wx", 0o600);
+            writeAll(fd, Buffer.from(JSON.stringify({
+                v: STORE_VERSION,
+                pid: process.pid,
+                token: this.lockToken,
+                createdAt: Date.now(),
+            }), "utf8"));
+            fsyncSync(fd);
+            setRestrictiveFilePermissions(this.lockPath);
+            this.lockFd = fd;
+            fd = undefined;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch { /* best effort */ }
+                try {
+                    unlinkSync(this.lockPath);
+                }
+                catch { /* best effort */ }
+            }
+        }
+    }
+    acquireOperationLock() {
+        try {
+            mkdirSync(this.operationLockPath, { mode: 0o700 });
+            setRestrictiveDirPermissions(this.operationLockPath);
+        }
+        catch (error) {
+            if (errorCode(error) === "EEXIST") {
+                throw new Error("reliable_outbox_store_operation_locked");
+            }
+            throw error;
+        }
+    }
+    releaseOperationLock() {
+        try {
+            rmSync(this.operationLockPath, { recursive: true, force: true });
+        }
+        catch { /* fail closed next time */ }
+    }
+    openNewestGeneration() {
+        const candidates = this.generationPaths();
+        const parsed = [];
+        const errors = [];
+        for (const candidate of candidates) {
+            try {
+                parsed.push(parseGeneration(candidate.path, candidate.generation, this.gatewayHash));
+            }
+            catch (error) {
+                errors.push(asError(error));
+            }
+        }
+        parsed.sort((left, right) => right.generation - left.generation);
+        const newest = parsed[0];
+        if (!newest) {
+            if (candidates.length > 0) {
+                throw new Error(`reliable_outbox_store_corrupt: ${errors.map((error) => error.message).join("; ")}`);
+            }
+            this.activateNewGeneration(1, new Map());
+            return;
+        }
+        if (statSync(newest.path).size !== newest.validBytes) {
+            const repairFd = openSync(newest.path, "r+");
+            try {
+                ftruncateSync(repairFd, newest.validBytes);
+                fsyncSync(repairFd);
+            }
+            finally {
+                closeSync(repairFd);
+            }
+        }
+        this.entries.clear();
+        for (const [key, entry] of newest.entries)
+            this.entries.set(key, entry);
+        this.generation = newest.generation;
+        this.journalPath = newest.path;
+        this.journalFd = openSync(newest.path, "a");
+        this.journalBytes = newest.validBytes;
+        this.removeInactiveGenerations(newest.path);
+    }
+    generationPaths() {
+        const pattern = new RegExp(`^${this.gatewayHash}\\.(\\d+)\\.wal$`);
+        const result = [];
+        for (const name of readdirSync(this.options.directory)) {
+            const match = pattern.exec(name);
+            if (!match)
+                continue;
+            const generation = Number(match[1]);
+            if (!Number.isSafeInteger(generation) || generation < 1)
+                continue;
+            result.push({ path: join(this.options.directory, name), generation });
+        }
+        return result;
+    }
+    append(record) {
+        const fd = this.journalFd;
+        if (fd === undefined)
+            throw new Error("reliable_outbox_store_not_open");
+        const bytes = encodeRecord(record);
+        const previousBytes = this.journalBytes;
+        try {
+            writeAll(fd, bytes);
+            fsyncSync(fd);
+            this.journalBytes += bytes.byteLength;
+        }
+        catch (error) {
+            // 写入或 fsync 失败时回滚到上一次已提交边界；回滚也失败则永久停用本实例。
+            try {
+                ftruncateSync(fd, previousBytes);
+                fsyncSync(fd);
+            }
+            catch {
+                this.failed = true;
+            }
+            throw new Error(`reliable_outbox_store_write_failed: ${asError(error).message}`);
+        }
+    }
+    compactIfNeeded() {
+        const liveBytes = [...this.entries.values()].reduce((sum, entry) => sum + entry.byteLength, 0);
+        const threshold = Math.max(COMPACTION_MIN_BYTES, (liveBytes * 2) + COMPACTION_HEADROOM_BYTES);
+        if (this.entries.size > 0 && this.journalBytes <= threshold)
+            return;
+        try {
+            // 新代完整持久化后才切换 fd；压缩失败不撤销已经写入旧 WAL 的业务变更。
+            this.activateNewGeneration(this.nextGeneration(), this.entries);
+        }
+        catch (error) {
+            this.reportMaintenanceError(asError(error));
+        }
+    }
+    activateNewGeneration(generation, entries) {
+        const path = join(this.options.directory, `${this.filePrefix}${generation}.wal`);
+        let fd;
+        try {
+            fd = openSync(path, "ax", 0o600);
+            writeAll(fd, encodeRecord({
+                v: STORE_VERSION,
+                kind: "header",
+                gatewayHash: this.gatewayHash,
+                generation,
+            }));
+            for (const entry of entries.values()) {
+                writeAll(fd, encodeRecord({ v: STORE_VERSION, kind: "put", entry }));
+            }
+            writeAll(fd, encodeRecord({
+                v: STORE_VERSION,
+                kind: "checkpoint",
+                count: entries.size,
+                digest: stateDigest(entries),
+            }));
+            fsyncSync(fd);
+            setRestrictiveFilePermissions(path);
+            fsyncDirectory(this.options.directory);
+            const bytes = fstatSync(fd).size;
+            const oldFd = this.journalFd;
+            this.journalFd = fd;
+            this.journalPath = path;
+            this.journalBytes = bytes;
+            this.generation = generation;
+            fd = undefined;
+            if (oldFd !== undefined) {
+                try {
+                    closeSync(oldFd);
+                }
+                catch { /* the new generation is already durable */ }
+            }
+            this.removeInactiveGenerations(path);
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch { /* best effort */ }
+            }
+            try {
+                rmSync(path, { force: true });
+            }
+            catch { /* best effort */ }
+            throw error;
+        }
+    }
+    removeInactiveGenerations(activePath) {
+        const previous = this.generationPaths()
+            .filter((candidate) => candidate.path !== activePath && candidate.generation < this.generation)
+            .sort((left, right) => right.generation - left.generation)[0]?.path;
+        for (const candidate of this.generationPaths()) {
+            if (candidate.path === activePath || candidate.path === previous)
+                continue;
+            try {
+                unlinkSync(candidate.path);
+            }
+            catch { /* startup can retry */ }
+        }
+    }
+    nextGeneration() {
+        return Math.max(this.generation, ...this.generationPaths().map((candidate) => candidate.generation)) + 1;
+    }
+    assertUsable() {
+        if (this.closed)
+            throw new Error("reliable_outbox_store_closed");
+        if (this.failed)
+            throw new Error("reliable_outbox_store_failed");
+    }
+    reportMaintenanceError(error) {
+        if (this.onMaintenanceError) {
+            try {
+                this.onMaintenanceError(error);
+                return;
+            }
+            catch {
+                // Observability must not affect a mutation already committed to WAL.
+            }
+        }
+        console.warn(`[relay] reliable outbox compaction deferred: ${error.message}`);
+    }
+}
+export function reliableRelayOutboxStorageDirectory(profile) {
+    return join(profileRoot(profile), STORE_DIR_NAME);
+}
+export function clearReliableRelayOutboxStorage(profile) {
+    const directory = reliableRelayOutboxStorageDirectory(profile);
+    const lockPath = operationLockPath(directory);
+    mkdirSync(dirname(directory), { recursive: true, mode: 0o700 });
+    try {
+        mkdirSync(lockPath, { mode: 0o700 });
+        setRestrictiveDirPermissions(lockPath);
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST")
+            throw new Error("reliable_outbox_store_operation_locked");
+        throw error;
+    }
+    try {
+        if (!existsSync(directory))
+            return;
+        for (const name of readdirSync(directory)) {
+            if (!name.endsWith(".lock"))
+                continue;
+            const owner = readLockOwner(join(directory, name));
+            if (owner.status !== "stale") {
+                throw new Error(`reliable_outbox_store_in_use lock=${name}`);
+            }
+        }
+        rmSync(directory, { recursive: true, force: true });
+    }
+    finally {
+        try {
+            rmSync(lockPath, { recursive: true, force: true });
+        }
+        catch { /* fail closed */ }
+    }
+}
+function parseGeneration(path, generation, gatewayHash) {
+    if (statSync(path).size > MAX_JOURNAL_BYTES)
+        throw new Error(`journal_too_large generation=${generation}`);
+    const file = readFileSync(path);
+    const lastNewline = file.lastIndexOf(0x0a);
+    if (lastNewline < 0)
+        throw new Error(`journal_missing_header generation=${generation}`);
+    const validBytes = lastNewline + 1;
+    const lines = file.subarray(0, validBytes).toString("utf8").split("\n");
+    lines.pop();
+    const entries = new Map();
+    let checkpointSeen = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        let value;
+        try {
+            value = JSON.parse(lines[index]);
+        }
+        catch {
+            throw new Error(`journal_invalid_json generation=${generation} line=${index + 1}`);
+        }
+        const record = asRecord(value);
+        if (!record || record.v !== STORE_VERSION) {
+            throw new Error(`journal_invalid_version generation=${generation} line=${index + 1}`);
+        }
+        if (index === 0) {
+            if (record.kind !== "header" || record.gatewayHash !== gatewayHash || record.generation !== generation) {
+                throw new Error(`journal_invalid_header generation=${generation}`);
+            }
+            continue;
+        }
+        if (record.kind === "put") {
+            const entry = parseStoredEntry(record.entry, generation, index + 1);
+            if (entries.has(entry.key))
+                throw new Error(`journal_duplicate_put generation=${generation} key=${entry.key}`);
+            entries.set(entry.key, entry);
+            continue;
+        }
+        if (record.kind === "remove") {
+            if (!checkpointSeen || typeof record.key !== "string" || !entries.delete(record.key)) {
+                throw new Error(`journal_invalid_remove generation=${generation} line=${index + 1}`);
+            }
+            continue;
+        }
+        if (record.kind === "checkpoint") {
+            if (checkpointSeen || record.count !== entries.size || record.digest !== stateDigest(entries)) {
+                throw new Error(`journal_invalid_checkpoint generation=${generation}`);
+            }
+            checkpointSeen = true;
+            continue;
+        }
+        throw new Error(`journal_invalid_record generation=${generation} line=${index + 1}`);
+    }
+    if (!checkpointSeen)
+        throw new Error(`journal_incomplete_generation generation=${generation}`);
+    return { path, generation, entries, validBytes };
+}
+function parseStoredEntry(value, generation, line) {
+    const entry = asRecord(value);
+    if (!entry
+        || typeof entry.key !== "string"
+        || typeof entry.byteLength !== "number"
+        || typeof entry.contentHash !== "string"
+        || (entry.mode !== "event_ack" && entry.mode !== "response_ack")
+        || !Object.prototype.hasOwnProperty.call(entry, "message")
+        || (entry.deliveryId !== undefined && typeof entry.deliveryId !== "string")) {
+        throw new Error(`journal_invalid_entry generation=${generation} line=${line}`);
+    }
+    return entry;
+}
+function stateDigest(entries) {
+    return createHash("sha256")
+        .update(JSON.stringify([...entries.values()].map((entry) => [entry.key, entry.contentHash])))
+        .digest("hex");
+}
+function encodeRecord(record) {
+    return Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+}
+function writeAll(fd, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const written = writeSync(fd, bytes, offset, bytes.byteLength - offset);
+        if (written <= 0)
+            throw new Error("reliable_outbox_store_zero_byte_write");
+        offset += written;
+    }
+}
+function fsyncDirectory(directory) {
+    let fd;
+    try {
+        fd = openSync(directory, "r");
+        fsyncSync(fd);
+    }
+    catch {
+        // Windows does not consistently permit directory handles; file fsync is
+        // still honored there. POSIX platforms get the directory-entry barrier.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) !== "ESRCH";
+    }
+}
+function readLockOwner(path) {
+    try {
+        const lock = JSON.parse(readFileSync(path, "utf8"));
+        if (Number.isSafeInteger(lock.pid) && Number(lock.pid) > 0) {
+            return { status: processIsAlive(Number(lock.pid)) ? "active" : "stale" };
+        }
+    }
+    catch {
+        // Age check below distinguishes an in-progress write from stale garbage.
+    }
+    // 无法验证 owner 身份时必须 fail closed，不能猜测为陈旧锁后删除。
+    return { status: "unknown" };
+}
+function operationLockPath(directory) {
+    return join(dirname(directory), `${basename(directory)}.operation-lock`);
+}
+function errorCode(value) {
+    return value && typeof value === "object" && "code" in value
+        ? String(value.code)
+        : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+//# sourceMappingURL=reliable-relay-outbox-store.js.map