@myagentroam/agent 0.11.32 → 0.11.34

package/dist/session/store/jsonl/records.js

@@ -0,0 +1,313 @@
+import { open, readFile } from 'node:fs/promises';
+import { AgentError } from '../../../error.js';
+import { admitV1RecordVersion } from './jsonl-admission.js';
+import { decodeJsonlRecord, decodeJsonlValue } from './jsonl-codec.js';
+export const MAX_SEGMENT_BYTES = 16 * 1024 * 1024;
+const REVERSE_READ_CHUNK_BYTES = 64 * 1024;
+const MAX_HISTORY_PAGE_FILES = 32;
+const MAX_HISTORY_PAGE_OFFSETS = 128;
+/** Read only the prefix needed by discovery; never load the entire transcript. */
+export async function* readRecordsFromHead(path, encoding = 1) {
+    const handle = await open(path, 'r');
+    try {
+        const { size } = await handle.stat();
+        let position = 0;
+        let pending = [];
+        while (position < size) {
+            const chunk = Buffer.allocUnsafe(Math.min(REVERSE_READ_CHUNK_BYTES, size - position));
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, size - position), position);
+            if (bytesRead === 0)
+                break;
+            position += bytesRead;
+            const data = chunk.subarray(0, bytesRead);
+            let start = 0;
+            for (;;) {
+                const end = data.indexOf(0x0a, start);
+                if (end < 0)
+                    break;
+                const part = data.subarray(start, end);
+                const line = (pending.length === 0 ? part : Buffer.concat([...pending, part])).toString('utf8');
+                pending = [];
+                start = end + 1;
+                if (!line)
+                    continue;
+                let record;
+                try {
+                    record = decodeJsonlRecord(line, encoding);
+                }
+                catch (cause) {
+                    if (cause instanceof AgentError)
+                        throw cause;
+                    throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
+                        cause
+                    });
+                }
+                yield record;
+            }
+            if (start < data.length)
+                pending.push(data.subarray(start));
+        }
+        if (pending.length > 0) {
+            let record;
+            const tail = Buffer.concat(pending).toString('utf8');
+            let value;
+            try {
+                value = JSON.parse(tail);
+            }
+            catch {
+                return; // Readers ignore only an interrupted final line.
+            }
+            record = decodeJsonlValue(value, encoding);
+            yield record;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readRecords(path, encoding = 1) {
+    const value = await readFile(path, 'utf8');
+    const lines = value.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    const records = [];
+    for (const [index, line] of lines.entries()) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (cause) {
+            if (index === lines.length - 1 && !value.endsWith('\n'))
+                break;
+            throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
+                cause
+            });
+        }
+        records.push(decodeJsonlValue(parsed, encoding));
+    }
+    return records;
+}
+/** Repair only the final record under the Session writer lock; never skip middle damage. */
+export async function repairSegmentTail(path, encoding = 1) {
+    const data = await readFile(path);
+    if (data.length === 0 || data.at(-1) === 10)
+        return;
+    const boundary = data.lastIndexOf(10);
+    let complete = false;
+    try {
+        const tail = data.subarray(boundary + 1).toString('utf8');
+        const record = JSON.parse(tail);
+        // A complete future-version record must not be mistaken for an interrupted v1 tail.
+        if (encoding === 1) {
+            admitV1RecordVersion(tail);
+            complete =
+                record?.schemaVersion === 1 &&
+                    Number.isSafeInteger(record.sequence) &&
+                    typeof record.sessionId === 'string' &&
+                    typeof record.type === 'string';
+        }
+        else {
+            decodeJsonlRecord(tail, encoding);
+            complete = true;
+        }
+    }
+    catch (error) {
+        if (error instanceof AgentError && error.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw error;
+        // An interrupted final line is discarded before another record can be appended.
+    }
+    const handle = await open(path, 'r+');
+    try {
+        if (complete) {
+            const { bytesWritten } = await handle.write(Buffer.from('\n'), 0, 1, data.length);
+            if (bytesWritten !== 1)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session tail repair is incomplete.');
+        }
+        else
+            await handle.truncate(boundary + 1);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readRecordPageFromTail(path, beforeSequence, limit, positions, encoding) {
+    const newestFirst = [];
+    for await (const record of readRecordsFromTail(path, { beforeSequence, limit, positions }, encoding)) {
+        if (!(record.sequence < beforeSequence))
+            continue;
+        newestFirst.push(record);
+        if (newestFirst.length > limit)
+            break;
+    }
+    return {
+        records: newestFirst.slice(0, limit).reverse(),
+        hasEarlier: newestFirst.length > limit
+    };
+}
+/** Decode complete records newest-first, releasing the file as soon as a reader stops. */
+export async function* readRecordsFromTail(path, page, encoding = 1) {
+    const handle = await open(path, 'r');
+    try {
+        const metadata = await handle.stat({ bigint: true });
+        const size = Number(metadata.size);
+        let position = size;
+        let cached;
+        if (page !== undefined) {
+            const signature = `${metadata.dev}:${metadata.ino}:${metadata.size}:${metadata.mtimeNs}:${metadata.ctimeNs}`;
+            const previous = page.positions.get(path);
+            cached = previous?.signature === signature ? previous : { signature, offsets: new Map() };
+            page.positions.delete(path);
+            page.positions.set(path, cached);
+            if (page.positions.size > MAX_HISTORY_PAGE_FILES)
+                page.positions.delete(page.positions.keys().next().value);
+            let nearestSequence = Number.POSITIVE_INFINITY;
+            for (const [sequence, offset] of cached.offsets) {
+                if (sequence >= page.beforeSequence && sequence < nearestSequence) {
+                    nearestSequence = sequence;
+                    position = offset;
+                }
+            }
+        }
+        let accepted = 0;
+        const remember = (record, offset) => {
+            if (page === undefined || cached === undefined || record.sequence >= page.beforeSequence)
+                return;
+            if (++accepted !== page.limit)
+                return;
+            cached.offsets.set(record.sequence, offset);
+            if (cached.offsets.size > MAX_HISTORY_PAGE_OFFSETS)
+                cached.offsets.delete(cached.offsets.keys().next().value);
+        };
+        let pendingLineParts = [];
+        let invalidFinalLineMayBeIgnored = false;
+        let inspectedFileEnd = position !== size;
+        const decode = (line, allowInvalidFinalLine) => {
+            if (line.length === 0)
+                return undefined;
+            const text = line.toString('utf8');
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (cause) {
+                if (allowInvalidFinalLine)
+                    return undefined;
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session history is corrupt.', {
+                    cause
+                });
+            }
+            return decodeJsonlValue(parsed, encoding);
+        };
+        while (position > 0) {
+            const start = Math.max(0, position - REVERSE_READ_CHUNK_BYTES);
+            const chunk = Buffer.allocUnsafe(position - start);
+            let bytesRead = 0;
+            while (bytesRead < chunk.length) {
+                const result = await handle.read(chunk, bytesRead, chunk.length - bytesRead, start + bytesRead);
+                if (result.bytesRead === 0)
+                    break;
+                bytesRead += result.bytesRead;
+            }
+            const value = chunk.subarray(0, bytesRead);
+            if (!inspectedFileEnd) {
+                inspectedFileEnd = true;
+                invalidFinalLineMayBeIgnored = value.at(-1) !== 0x0a;
+            }
+            let lineEnd = value.length;
+            for (let index = value.length - 1; index >= 0; index--) {
+                if (value[index] !== 0x0a)
+                    continue;
+                const currentPart = value.subarray(index + 1, lineEnd);
+                const line = pendingLineParts.length === 0
+                    ? currentPart
+                    : Buffer.concat([currentPart, ...pendingLineParts.reverse()]);
+                const record = decode(line, invalidFinalLineMayBeIgnored);
+                invalidFinalLineMayBeIgnored = false;
+                pendingLineParts = [];
+                lineEnd = index;
+                if (record !== undefined) {
+                    remember(record, start + index + 1);
+                    yield record;
+                }
+            }
+            if (lineEnd > 0)
+                pendingLineParts.push(value.subarray(0, lineEnd));
+            position = start;
+        }
+        if (pendingLineParts.length > 0) {
+            const record = decode(Buffer.concat(pendingLineParts.reverse()), invalidFinalLineMayBeIgnored);
+            if (record !== undefined) {
+                remember(record, 0);
+                yield record;
+            }
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function segmentNumberFromPath(path) {
+    const match = /events-(\d{6})\.jsonl$/.exec(path);
+    return match === null ? undefined : Number(match[1]);
+}
+/** Owns bounded reverse-read positions for the shared Store domain. */
+export class SessionHistoryPageReader {
+    #positions = new Map();
+    async read(meta, input, segmentPaths) {
+        const before = input.beforeSequence ?? Number.POSITIVE_INFINITY;
+        const limit = Math.min(1000, Math.max(1, input.limit ?? 100));
+        const page = [];
+        let hasEarlier = false;
+        const paths = (await segmentPaths()).reverse();
+        for (const [pathIndex, path] of paths.entries()) {
+            const segmentNumber = segmentNumberFromPath(path);
+            const segment = meta.segments?.find((item) => item.number === segmentNumber);
+            if (segment !== undefined && segment.firstSequence >= before)
+                continue;
+            const window = await readRecordPageFromTail(path, before, limit - page.length, this.#positions, meta.storage?.encoding ?? 1);
+            page.unshift(...window.records);
+            if (window.hasEarlier) {
+                hasEarlier = true;
+                break;
+            }
+            if (page.length >= limit) {
+                hasEarlier = pathIndex < paths.length - 1;
+                break;
+            }
+        }
+        const previousBeforeSequence = hasEarlier ? page[0]?.sequence : undefined;
+        return { records: page, ...(previousBeforeSequence ? { previousBeforeSequence } : {}) };
+    }
+}
+export async function appendRecordBytes(path, serialized, onWriteFailure) {
+    const bytes = Buffer.from(serialized);
+    const handle = await open(path, 'a', 0o600);
+    let failure;
+    try {
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+            if (bytesWritten === 0)
+                throw new AgentError('MAR_AGENT_SESSION_CORRUPT', 'Session append is incomplete.');
+            offset += bytesWritten;
+        }
+        await handle.sync();
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        failure ??= { error };
+    }
+    if (failure) {
+        // Opening/encoding failures cannot have appended bytes; write/sync/close failures can.
+        onWriteFailure(failure.error);
+        throw failure.error;
+    }
+}

package/dist/session/store/jsonl/resources.d.ts

@@ -0,0 +1,19 @@
+import { type ModelImage } from '../../../model/image.js';
+import type { SessionRecord } from '../types.js';
+import type { SessionResource } from '../../resource-contract.js';
+export type { SessionResource } from '../../resource-contract.js';
+export declare function resourceMetadata(directory: string, resourceId: string): Promise<SessionResource | undefined>;
+export declare function persistResource(directory: string, image: ModelImage): Promise<SessionResource>;
+export declare function setResourceUrl(directory: string, resourceId: string, published: {
+    url: string;
+    urlExpiresAt: number;
+}): Promise<SessionResource>;
+export declare function readResource(directory: string, resourceId: string): Promise<{
+    mimeType: string;
+    dataBase64: string;
+} | undefined>;
+/** Resource identities are SDK-owned metadata, never interpreted as file paths. */
+export declare function resourceFiles(records: readonly SessionRecord[]): Set<string>;
+export declare function copyResources(source: string, target: string, records: readonly SessionRecord[]): Promise<void>;
+export declare function completeResources(directory: string, record: SessionRecord): Promise<void>;
+export declare function recoverResources(directory: string, readHistory: () => Promise<SessionRecord[]>): Promise<void>;

package/dist/session/store/jsonl/resources.js

@@ -0,0 +1,209 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { AgentError } from '../../../error.js';
+import { isModelImageUrl } from '../../../model/image.js';
+import { readInputImageBytes } from './images.js';
+import { admitResourceMetadataVersion } from './jsonl-admission.js';
+const idPattern = /^[a-f0-9]{64}$/u;
+const mimeTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+function resourceIdentity(mimeType, sha256) {
+    return createHash('sha256').update(mimeType).update('\0').update(sha256).digest('hex');
+}
+export async function resourceMetadata(directory, resourceId) {
+    if (!idPattern.test(resourceId))
+        return undefined;
+    try {
+        const value = JSON.parse(await readFile(join(directory, `${resourceId}.json`), 'utf8'));
+        const resource = value;
+        admitResourceMetadataVersion(value);
+        if (!value ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            typeof resource.resourceId !== 'string' ||
+            typeof resource.mimeType !== 'string' ||
+            typeof resource.byteSize !== 'number' ||
+            typeof resource.sha256 !== 'string' ||
+            (resource.url !== undefined &&
+                (typeof resource.url !== 'string' ||
+                    !isModelImageUrl(resource.url) ||
+                    !Number.isSafeInteger(resource.urlExpiresAt) ||
+                    resource.urlExpiresAt <= 0)) ||
+            (resource.url === undefined && resource.urlExpiresAt !== undefined))
+            throw new Error('Invalid Session image resource metadata.');
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof AgentError && cause.code === 'MAR_AGENT_SESSION_VERSION_UNSUPPORTED')
+            throw cause;
+        if (cause.code === 'ENOENT')
+            return undefined;
+        throw new AgentError('MAR_AGENT_IMAGE_UNAVAILABLE', 'Session image resource is unavailable.', {
+            cause
+        });
+    }
+}
+export async function persistResource(directory, image) {
+    if (image.resourceId !== undefined && image.dataBase64 === undefined) {
+        const existing = await resourceMetadata(directory, image.resourceId);
+        if (existing !== undefined && existing.mimeType === image.mimeType)
+            return existing;
+        throw new AgentError('MAR_AGENT_IMAGE_UNAVAILABLE', 'Session image resource is missing.');
+    }
+    const data = Buffer.from(image.dataBase64 ?? '', 'base64');
+    if (data.toString('base64') !== image.dataBase64)
+        throw new AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Image resource data is not canonical base64.');
+    if (!mimeTypes.has(image.mimeType) || data.length === 0 || data.length > 20 * 1024 * 1024)
+        throw new AgentError('MAR_AGENT_HOST_LIMIT_EXCEEDED', 'Image resource exceeds supported limits.');
+    const sha256 = createHash('sha256').update(data).digest('hex');
+    const resourceId = resourceIdentity(image.mimeType, sha256);
+    if (image.resourceId !== undefined && image.resourceId !== resourceId)
+        throw new AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Image resource identity does not match its bytes.');
+    let existing;
+    try {
+        existing = await resourceMetadata(directory, resourceId);
+    }
+    catch (error) {
+        if (!(error instanceof AgentError) || error.code !== 'MAR_AGENT_IMAGE_UNAVAILABLE')
+            throw error;
+    }
+    const resource = {
+        ...existing,
+        resourceInputVersion: 1,
+        resourceId,
+        mimeType: image.mimeType,
+        byteSize: data.length,
+        sha256
+    };
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(join(directory, `.${resourceId}.pending`), '', { mode: 0o600, flush: true });
+    await atomicWrite(join(directory, `${resourceId}.bin`), data);
+    await atomicWrite(join(directory, `${resourceId}.json`), JSON.stringify(resource));
+    return resource;
+}
+export async function setResourceUrl(directory, resourceId, published) {
+    const resource = await resourceMetadata(directory, resourceId);
+    if (!resource)
+        throw new AgentError('MAR_AGENT_IMAGE_UNAVAILABLE', 'Session image resource is missing.');
+    if (resource.url !== undefined)
+        return resource;
+    if (!isModelImageUrl(published.url) ||
+        !Number.isSafeInteger(published.urlExpiresAt) ||
+        published.urlExpiresAt <= 0)
+        throw new AgentError('MAR_AGENT_IMAGE_PUBLICATION_FAILED', 'Image URL publication failed.');
+    const result = { ...resource, url: published.url, urlExpiresAt: published.urlExpiresAt };
+    await atomicWrite(join(directory, `${resourceId}.json`), JSON.stringify(result));
+    return result;
+}
+export async function readResource(directory, resourceId) {
+    const resource = await resourceMetadata(directory, resourceId);
+    if (!resource)
+        return undefined;
+    const bytes = await readInputImageBytes(directory, {
+        ...resource,
+        name: 'image',
+        fileName: `${resourceId}.bin`
+    });
+    return { mimeType: resource.mimeType, dataBase64: bytes.toString('base64') };
+}
+/** Resource identities are SDK-owned metadata, never interpreted as file paths. */
+export function resourceFiles(records) {
+    const ids = new Set();
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const item = value;
+        if (item.resourceInputVersion === 1 &&
+            typeof item.resourceId === 'string' &&
+            idPattern.test(item.resourceId))
+            ids.add(item.resourceId);
+        for (const key of ['images', 'input', 'pendingInputs', 'payload', 'retainedModelContext'])
+            if (item[key] !== undefined)
+                visit(item[key]);
+    };
+    for (const record of records)
+        visit(record.payload);
+    return new Set([...ids].flatMap((id) => [`${id}.bin`, `${id}.json`]));
+}
+export async function copyResources(source, target, records) {
+    const files = resourceFiles(records);
+    if (!files.size)
+        return;
+    await mkdir(join(target, 'resources'), { recursive: true, mode: 0o700 });
+    for (const file of files) {
+        if (!file.endsWith('.bin'))
+            continue;
+        const resourceId = file.slice(0, -4);
+        const resource = await resourceMetadata(join(source, 'resources'), resourceId);
+        if (resource === undefined)
+            continue;
+        let bytes;
+        try {
+            bytes = await readInputImageBytes(join(source, 'resources'), {
+                ...resource,
+                name: 'image',
+                fileName: file
+            });
+        }
+        catch (error) {
+            if (error instanceof AgentError && error.code === 'MAR_AGENT_IMAGE_UNAVAILABLE')
+                continue;
+            throw error;
+        }
+        await writeFile(join(target, 'resources', file), bytes, {
+            mode: 0o600,
+            flag: 'wx',
+            flush: true
+        });
+        await writeFile(join(target, 'resources', `${resourceId}.json`), JSON.stringify(resource), {
+            mode: 0o600,
+            flag: 'wx',
+            flush: true
+        });
+    }
+}
+export async function completeResources(directory, record) {
+    for (const file of resourceFiles([record]))
+        if (file.endsWith('.bin'))
+            await rm(join(directory, `.${file.slice(0, -4)}.pending`), { force: true });
+}
+export async function recoverResources(directory, readHistory) {
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const pending = names.filter((name) => /^\.[a-f0-9]{64}\.pending$/u.test(name));
+    if (pending.length) {
+        const retained = resourceFiles(await readHistory());
+        for (const name of pending) {
+            const id = name.slice(1, -8);
+            if (!retained.has(`${id}.bin`))
+                for (const suffix of ['bin', 'json'])
+                    await rm(join(directory, `${id}.${suffix}`), { force: true });
+            await rm(join(directory, name), { force: true });
+        }
+    }
+    for (const name of names)
+        if (/^\.[a-f0-9]{64}\.(?:bin|json)\.[a-f0-9-]{36}\.tmp$/u.test(name))
+            await rm(join(directory, name), { force: true });
+}
+async function atomicWrite(path, data) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, data, { mode: 0o600, flag: 'wx', flush: true });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/session/store/jsonl/store-pool.d.ts

@@ -0,0 +1,12 @@
+interface PooledStore {
+    readonly root: string;
+    references: number;
+    closed: boolean;
+}
+/** Shares a storage domain across handles while keeping their close responsibilities separate. */
+export declare class JsonlStorePool<T extends PooledStore> {
+    #private;
+    acquire(root: string, open: () => Promise<T>): Promise<T>;
+    release(shared: T, beforeLastClose: () => Promise<void> | undefined): Promise<void>;
+}
+export {};

package/dist/session/store/jsonl/store-pool.js

@@ -0,0 +1,55 @@
+/** Shares a storage domain across handles while keeping their close responsibilities separate. */
+export class JsonlStorePool {
+    #instances = new Map();
+    #opening = new Map();
+    #closing = new Map();
+    async acquire(root, open) {
+        const closing = this.#closing.get(root);
+        if (closing) {
+            await closing;
+            return this.acquire(root, open);
+        }
+        const existing = this.#instances.get(root);
+        if (existing) {
+            existing.references++;
+            return existing;
+        }
+        const pending = this.#opening.get(root);
+        if (pending) {
+            const shared = await pending;
+            shared.references++;
+            return shared;
+        }
+        const opening = open();
+        this.#opening.set(root, opening);
+        try {
+            const shared = await opening;
+            this.#instances.set(root, shared);
+            return shared;
+        }
+        finally {
+            this.#opening.delete(root);
+        }
+    }
+    async release(shared, beforeLastClose) {
+        shared.references--;
+        if (shared.references > 0)
+            return;
+        const flush = beforeLastClose();
+        if (flush) {
+            const closing = flush.then(() => {
+                shared.closed = true;
+                this.#instances.delete(shared.root);
+                this.#closing.delete(shared.root);
+            }, (error) => {
+                this.#closing.delete(shared.root);
+                throw error;
+            });
+            this.#closing.set(shared.root, closing);
+            await closing;
+            return;
+        }
+        shared.closed = true;
+        this.#instances.delete(shared.root);
+    }
+}

package/dist/session/store/jsonl/transaction-recovery.d.ts

@@ -0,0 +1,48 @@
+/** One authoritative journal for an entire Session tree; markers only locate it. */
+export interface SessionTreeDeleteTransaction {
+    readonly version: 1;
+    readonly kind: 'delete';
+    readonly id: string;
+    readonly phase?: 'preparing' | 'ready' | 'restored';
+    readonly members: readonly {
+        readonly id: string;
+        readonly existed: boolean;
+        readonly identity: {
+            readonly createdAt: string;
+            readonly workspace: string;
+            readonly source?: unknown;
+            readonly storage?: unknown;
+            readonly storageTransactionId?: string;
+            readonly nextSequence: number;
+        };
+    }[];
+}
+export declare function treeDeleteMarker(root: string, sessionId: string): string;
+export declare function readTreeDeleteTransaction(root: string, sessionId: string): Promise<SessionTreeDeleteTransaction | undefined>;
+export declare function beginTreeDeleteTransaction(root: string, transaction: SessionTreeDeleteTransaction, sync: (path: string) => Promise<void>): Promise<void>;
+/** Called only with all tree writers and read gates held. */
+export declare function stageTreeDelete(root: string, transaction: SessionTreeDeleteTransaction, sync: (path: string) => Promise<void>): Promise<void>;
+/** Index membership selects restore versus retirement; never infer commit from file presence. */
+export declare function finishTreeDelete(root: string, transaction: SessionTreeDeleteTransaction, committed: boolean, sync: (path: string) => Promise<void>): Promise<void>;
+/** Remove only markers owned by the preparing or fully restored transaction. */
+export declare function finishTreeDeletePreparation(root: string, transaction: SessionTreeDeleteTransaction, sync: (path: string) => Promise<void>): Promise<void>;
+export declare function isUnjournaledTransactionFile(name: string): boolean;
+export interface SessionStorageTransaction {
+    readonly version: 1;
+    readonly id: string;
+    readonly kind: 'rollback' | 'clear';
+    readonly originalSegments: readonly string[];
+    readonly stagedSegments: readonly {
+        readonly path: string;
+        readonly temporary: string;
+    }[];
+    readonly sidecarBackup: string;
+    readonly retiredPaths?: readonly string[];
+    readonly targetGeneration?: string;
+}
+/** Deterministic names make a partially staged retirement recoverable from the same journal. */
+export declare function retiredSessionTrashPath(root: string, path: string, transactionId: string): string;
+/** The index's transaction ID, not the journal's existence, decides the commit side. */
+export declare function beginSessionStorageTransaction(directory: string, transaction: SessionStorageTransaction): Promise<void>;
+/** Must run under the corresponding Session writer lock. Safe to repeat after interruption. */
+export declare function recoverSessionStorageTransaction(directory: string, committedTransactionId?: string, sessionDirectory?: string): Promise<void>;