@evomap/evolver-core 2.0.0-beta.2 → 2.0.0-beta.3

package/dist/assetstore/assetStoreHealth.js

@@ -0,0 +1,277 @@
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { validateWire, verifyAssetId } from '../wire/index.js';
+import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
+import { assertOptionalRegularFile, isReliableAssetStoreLockRelease, readUtf8Regular, UnsafeAssetStorePathError, } from './assetStoreStorage.js';
+import { parseAssetSyncRecord, parseProvenanceRecord, parseReviewRecord, parseSidecarJsonl, } from './assetSidecarRecords.js';
+export const DEFAULT_ASSET_HEALTH_MAX_FILE_BYTES = 64 * 1024 * 1024;
+const LOCAL_ASSET_SIDECARS = [
+    { kind: 'provenance', file: 'provenance.jsonl', parseRecord: parseProvenanceRecord },
+    { kind: 'review', file: 'review.jsonl', parseRecord: parseReviewRecord },
+    { kind: 'asset-sync', file: 'asset-sync.jsonl', parseRecord: parseAssetSyncRecord },
+];
+function healthScanLimit(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return DEFAULT_ASSET_HEALTH_MAX_FILE_BYTES;
+    return Math.min(DEFAULT_ASSET_HEALTH_MAX_FILE_BYTES, Math.max(1, Math.floor(value)));
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function emptyFile(kind, file, status, reason) {
+    return {
+        kind,
+        file,
+        status,
+        bytes: 0,
+        rows: 0,
+        validRows: 0,
+        uniqueAssets: 0,
+        duplicateRows: 0,
+        corruptRows: 0,
+        hashMismatchRows: 0,
+        schemaInvalidRows: 0,
+        unterminated: false,
+        ...(reason ? { reason } : {}),
+    };
+}
+function allFiles(status, reason) {
+    return Object.entries(LOCAL_ASSET_FILES)
+        .map(([kind, file]) => emptyFile(kind, file, status, reason));
+}
+function emptySidecar(kind, file, status, reason) {
+    return {
+        kind,
+        file,
+        status,
+        bytes: 0,
+        rows: 0,
+        validRows: 0,
+        corruptRows: 0,
+        unterminated: false,
+        ...(reason ? { reason } : {}),
+    };
+}
+function allSidecars(status, reason) {
+    return LOCAL_ASSET_SIDECARS.map(({ kind, file }) => emptySidecar(kind, file, status, reason));
+}
+function summarize(files, sidecars) {
+    const totals = {
+        files: files.length,
+        missingFiles: files.filter((file) => file.status === 'missing').length,
+        unsafeFiles: files.filter((file) => file.status === 'unsafe').length,
+        unavailableFiles: files.filter((file) => file.status === 'unavailable').length,
+        bytes: files.reduce((sum, file) => sum + file.bytes, 0),
+        rows: files.reduce((sum, file) => sum + file.rows, 0),
+        validRows: files.reduce((sum, file) => sum + file.validRows, 0),
+        uniqueAssets: files.reduce((sum, file) => sum + file.uniqueAssets, 0),
+        duplicateRows: files.reduce((sum, file) => sum + file.duplicateRows, 0),
+        corruptRows: files.reduce((sum, file) => sum + file.corruptRows, 0),
+        hashMismatchRows: files.reduce((sum, file) => sum + file.hashMismatchRows, 0),
+        schemaInvalidRows: files.reduce((sum, file) => sum + file.schemaInvalidRows, 0),
+        unterminatedFiles: files.filter((file) => file.unterminated).length,
+    };
+    const sidecarTotals = {
+        files: sidecars.length,
+        missingFiles: sidecars.filter((file) => file.status === 'missing').length,
+        unsafeFiles: sidecars.filter((file) => file.status === 'unsafe').length,
+        unavailableFiles: sidecars.filter((file) => file.status === 'unavailable').length,
+        bytes: sidecars.reduce((sum, file) => sum + file.bytes, 0),
+        rows: sidecars.reduce((sum, file) => sum + file.rows, 0),
+        validRows: sidecars.reduce((sum, file) => sum + file.validRows, 0),
+        corruptRows: sidecars.reduce((sum, file) => sum + file.corruptRows, 0),
+        unterminatedFiles: sidecars.filter((file) => file.unterminated).length,
+    };
+    const status = totals.unsafeFiles > 0 || sidecarTotals.unsafeFiles > 0
+        ? 'unsafe'
+        : totals.unavailableFiles > 0 || sidecarTotals.unavailableFiles > 0
+            ? 'unavailable'
+            : totals.duplicateRows > 0
+                || totals.corruptRows > 0
+                || totals.hashMismatchRows > 0
+                || totals.schemaInvalidRows > 0
+                || totals.unterminatedFiles > 0
+                || sidecarTotals.corruptRows > 0
+                || sidecarTotals.unterminatedFiles > 0
+                ? 'degraded'
+                : 'healthy';
+    return {
+        ok: status === 'healthy',
+        status,
+        totals,
+        files: [...files],
+        sidecarTotals,
+        sidecars: [...sidecars],
+    };
+}
+function inspectFile(baseDir, kind, file, maxFileBytes) {
+    try {
+        const path = join(baseDir, file);
+        const stat = assertOptionalRegularFile(path);
+        if (stat === null)
+            return emptyFile(kind, file, 'missing');
+        if (stat.size > maxFileBytes) {
+            return { ...emptyFile(kind, file, 'unavailable', 'scan_limit_exceeded'), bytes: stat.size };
+        }
+        const raw = readUtf8Regular(path);
+        if (raw === null)
+            return emptyFile(kind, file, 'unavailable', 'read_unavailable');
+        const rows = raw.split('\n').filter((line) => line.trim().length > 0);
+        const seen = new Set();
+        let validRows = 0;
+        let duplicateRows = 0;
+        let corruptRows = 0;
+        let hashMismatchRows = 0;
+        let schemaInvalidRows = 0;
+        for (const line of rows) {
+            try {
+                const value = JSON.parse(line);
+                if (!value || typeof value !== 'object' || Array.isArray(value)) {
+                    corruptRows += 1;
+                    continue;
+                }
+                const record = value;
+                const assetId = typeof record['asset_id'] === 'string' ? record['asset_id'].trim() : '';
+                if (!assetId || record['type'] !== kind) {
+                    corruptRows += 1;
+                    continue;
+                }
+                if (seen.has(assetId))
+                    duplicateRows += 1;
+                else
+                    seen.add(assetId);
+                if (!verifyAssetId(record)) {
+                    hashMismatchRows += 1;
+                    continue;
+                }
+                if (kind !== 'AntiGene' && !validateWire(record).ok) {
+                    schemaInvalidRows += 1;
+                    continue;
+                }
+                validRows += 1;
+            }
+            catch {
+                corruptRows += 1;
+            }
+        }
+        const unterminated = raw.length > 0 && !raw.endsWith('\n');
+        const status = duplicateRows > 0
+            || corruptRows > 0
+            || hashMismatchRows > 0
+            || schemaInvalidRows > 0
+            || unterminated
+            ? 'degraded'
+            : 'ok';
+        return {
+            kind,
+            file,
+            status,
+            bytes: Buffer.byteLength(raw, 'utf8'),
+            rows: rows.length,
+            validRows,
+            uniqueAssets: seen.size,
+            duplicateRows,
+            corruptRows,
+            hashMismatchRows,
+            schemaInvalidRows,
+            unterminated,
+        };
+    }
+    catch (error) {
+        if (error instanceof UnsafeAssetStorePathError)
+            return emptyFile(kind, file, 'unsafe', error.reason);
+        return emptyFile(kind, file, 'unavailable', 'read_unavailable');
+    }
+}
+function inspectSidecar(baseDir, definition, maxFileBytes) {
+    const { kind, file, parseRecord } = definition;
+    try {
+        const path = join(baseDir, file);
+        const stat = assertOptionalRegularFile(path);
+        if (stat === null)
+            return emptySidecar(kind, file, 'missing');
+        if (stat.size > maxFileBytes) {
+            return { ...emptySidecar(kind, file, 'unavailable', 'scan_limit_exceeded'), bytes: stat.size };
+        }
+        const raw = readUtf8Regular(path);
+        if (raw === null)
+            return emptySidecar(kind, file, 'unavailable', 'read_unavailable');
+        const parsed = parseSidecarJsonl(raw, parseRecord);
+        const status = parsed.corruptRows > 0 || parsed.unterminated ? 'degraded' : 'ok';
+        return {
+            kind,
+            file,
+            status,
+            bytes: Buffer.byteLength(raw, 'utf8'),
+            rows: parsed.rows,
+            validRows: parsed.validRows,
+            corruptRows: parsed.corruptRows,
+            unterminated: parsed.unterminated,
+        };
+    }
+    catch (error) {
+        if (error instanceof UnsafeAssetStorePathError)
+            return emptySidecar(kind, file, 'unsafe', error.reason);
+        return emptySidecar(kind, file, 'unavailable', 'read_unavailable');
+    }
+}
+function directoryState(baseDir) {
+    try {
+        const stat = lstatSync(baseDir);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return 'unsafe';
+        return 'safe';
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 'missing';
+        return 'unavailable';
+    }
+}
+export function inspectLocalAssetStore(baseDir, opts = {}, deps = {}) {
+    const state = directoryState(baseDir);
+    if (state === 'missing')
+        return summarize(allFiles('missing'), allSidecars('missing'));
+    if (state === 'unsafe') {
+        return summarize(allFiles('unsafe', 'base_directory'), allSidecars('unsafe', 'base_directory'));
+    }
+    if (state === 'unavailable') {
+        return summarize(allFiles('unavailable', 'read_unavailable'), allSidecars('unavailable', 'read_unavailable'));
+    }
+    const lockPath = join(baseDir, '.assetstore.lock');
+    try {
+        assertOptionalRegularFile(lockPath, 'lock_file');
+    }
+    catch (error) {
+        if (error instanceof UnsafeAssetStorePathError) {
+            return summarize(allFiles('unsafe', error.reason), allSidecars('unsafe', error.reason));
+        }
+        return summarize(allFiles('unavailable', 'lock_unavailable'), allSidecars('unavailable', 'lock_unavailable'));
+    }
+    try {
+        (deps.acquireLock ?? acquireLock)(lockPath);
+    }
+    catch {
+        return summarize(allFiles('unavailable', 'lock_unavailable'), allSidecars('unavailable', 'lock_unavailable'));
+    }
+    const maxFileBytes = healthScanLimit(opts.maxFileBytes);
+    let report;
+    try {
+        report = summarize(Object.entries(LOCAL_ASSET_FILES)
+            .map(([kind, file]) => inspectFile(baseDir, kind, file, maxFileBytes)), LOCAL_ASSET_SIDECARS.map((definition) => inspectSidecar(baseDir, definition, maxFileBytes)));
+    }
+    catch {
+        report = summarize(allFiles('unavailable', 'read_unavailable'), allSidecars('unavailable', 'read_unavailable'));
+    }
+    try {
+        const released = (deps.releaseLock ?? releaseLock)(lockPath);
+        if (!isReliableAssetStoreLockRelease(released)) {
+            return summarize(allFiles('unavailable', 'lock_unavailable'), allSidecars('unavailable', 'lock_unavailable'));
+        }
+    }
+    catch {
+        return summarize(allFiles('unavailable', 'lock_unavailable'), allSidecars('unavailable', 'lock_unavailable'));
+    }
+    return report;
+}

package/dist/assetstore/assetStoreLayout.d.ts

@@ -0,0 +1,2 @@
+import type { AssetKind } from './provider.js';
+export declare const LOCAL_ASSET_FILES: Readonly<Record<AssetKind, string>>;

package/dist/assetstore/assetStoreLayout.js

@@ -0,0 +1,6 @@
+export const LOCAL_ASSET_FILES = {
+    Gene: 'genes.jsonl',
+    Capsule: 'capsules.jsonl',
+    EvolutionEvent: 'events.jsonl',
+    AntiGene: 'anti-genes.jsonl',
+};

package/dist/assetstore/assetStoreStorage.d.ts

@@ -0,0 +1,42 @@
+import type { Stats } from 'node:fs';
+import { acquireLock, releaseLock, type ReleaseLockResult } from '../util/fileLock.js';
+export type UnsafeAssetStorePathReason = 'symlink' | 'not_directory' | 'not_regular_file' | 'path_changed';
+export type AssetStorePathRole = 'base_directory' | 'asset_file' | 'lock_file' | 'temp_file';
+export declare class UnsafeAssetStorePathError extends Error {
+    readonly role: AssetStorePathRole;
+    readonly reason: UnsafeAssetStorePathReason;
+    readonly code = "UNSAFE_ASSET_STORE_PATH";
+    constructor(role: AssetStorePathRole, reason: UnsafeAssetStorePathReason);
+}
+export declare class AssetStoreReadLimitError extends Error {
+    readonly code = "ASSET_STORE_READ_LIMIT";
+    constructor();
+}
+export interface DurableWriteOptions {
+    syncFile?: (fd: number) => void;
+    syncDirectory?: (path: string) => void;
+    onTempPath?: (path: string) => void;
+}
+export interface AssetStoreLockDeps {
+    acquireLock?: typeof acquireLock;
+    releaseLock?: typeof releaseLock;
+}
+export declare function ensureAssetStoreDirectory(path: string): void;
+/** Validate an existing store root without recreating a deleted or unmounted path. */
+export declare function assertAssetStoreDirectory(path: string): void;
+export declare function isReliableAssetStoreLockRelease(result: ReleaseLockResult): boolean;
+/**
+ * Run one synchronous asset-store critical section without hiding its primary failure.
+ * A release failure is surfaced only after a successful operation; when both fail, the operation error wins.
+ */
+export declare function withAssetStoreLock<T>(lockPath: string, operation: () => T, deps?: AssetStoreLockDeps): T;
+export declare function assertOptionalRegularFile(path: string, role?: AssetStorePathRole): Stats | null;
+export declare function regularFileFingerprint(path: string): string;
+export declare function readRegularBuffer(path: string, maxBytes?: number): Buffer | null;
+export declare function readUtf8Regular(path: string): string | null;
+export declare function createBufferDurableExclusive(path: string, value: Buffer, opts?: DurableWriteOptions): void;
+export declare function fsyncDirectoryBestEffort(path: string): void;
+export declare function appendUtf8Durable(path: string, value: string, opts?: DurableWriteOptions): void;
+export declare function replaceUtf8Durable(path: string, value: string, opts?: DurableWriteOptions): void;
+/** Remove one exact UTF-8 suffix and fsync the new file length; false means the suffix was not current. */
+export declare function truncateUtf8SuffixDurable(path: string, suffix: string, opts?: Pick<DurableWriteOptions, 'syncFile'>): boolean;

package/dist/assetstore/assetStoreStorage.js

@@ -0,0 +1,318 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { acquireLock, LockReleaseError, releaseLock, } from '../util/fileLock.js';
+export class UnsafeAssetStorePathError extends Error {
+    role;
+    reason;
+    code = 'UNSAFE_ASSET_STORE_PATH';
+    constructor(role, reason) {
+        super(`unsafe asset store ${role}: ${reason}`);
+        this.role = role;
+        this.reason = reason;
+        this.name = 'UnsafeAssetStorePathError';
+    }
+}
+export class AssetStoreReadLimitError extends Error {
+    code = 'ASSET_STORE_READ_LIMIT';
+    constructor() {
+        super('asset store file exceeds the configured read limit');
+        this.name = 'AssetStoreReadLimitError';
+    }
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function noFollowFlag() {
+    return constants['O_NOFOLLOW'] ?? 0;
+}
+function statOrNull(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        throw error;
+    }
+}
+function assertRegularStat(stat, role) {
+    if (stat.isSymbolicLink())
+        throw new UnsafeAssetStorePathError(role, 'symlink');
+    if (!stat.isFile())
+        throw new UnsafeAssetStorePathError(role, 'not_regular_file');
+    return stat;
+}
+export function ensureAssetStoreDirectory(path) {
+    let stat = statOrNull(path);
+    if (stat === null) {
+        mkdirSync(path, { recursive: true, mode: 0o700 });
+        stat = statOrNull(path);
+    }
+    assertAssetStoreDirectoryStat(stat);
+}
+function assertAssetStoreDirectoryStat(stat) {
+    if (stat === null)
+        throw new UnsafeAssetStorePathError('base_directory', 'not_directory');
+    if (stat.isSymbolicLink())
+        throw new UnsafeAssetStorePathError('base_directory', 'symlink');
+    if (!stat.isDirectory())
+        throw new UnsafeAssetStorePathError('base_directory', 'not_directory');
+}
+/** Validate an existing store root without recreating a deleted or unmounted path. */
+export function assertAssetStoreDirectory(path) {
+    assertAssetStoreDirectoryStat(statOrNull(path));
+}
+export function isReliableAssetStoreLockRelease(result) {
+    return result.released
+        && (result.reason === 'released' || result.reason === 'released_with_cleanup_error');
+}
+/**
+ * Run one synchronous asset-store critical section without hiding its primary failure.
+ * A release failure is surfaced only after a successful operation; when both fail, the operation error wins.
+ */
+export function withAssetStoreLock(lockPath, operation, deps = {}) {
+    assertOptionalRegularFile(lockPath, 'lock_file');
+    (deps.acquireLock ?? acquireLock)(lockPath);
+    let value;
+    let operationError;
+    let operationFailed = false;
+    try {
+        value = operation();
+    }
+    catch (error) {
+        operationFailed = true;
+        operationError = error;
+    }
+    let releaseError;
+    try {
+        const released = (deps.releaseLock ?? releaseLock)(lockPath);
+        if (!isReliableAssetStoreLockRelease(released))
+            releaseError = new LockReleaseError(released.reason);
+    }
+    catch (error) {
+        releaseError = error;
+    }
+    if (operationFailed)
+        throw operationError;
+    if (releaseError !== undefined)
+        throw releaseError;
+    return value;
+}
+export function assertOptionalRegularFile(path, role = 'asset_file') {
+    const stat = statOrNull(path);
+    return stat === null ? null : assertRegularStat(stat, role);
+}
+export function regularFileFingerprint(path) {
+    try {
+        const stat = lstatSync(path, { bigint: true });
+        if (stat.isSymbolicLink())
+            throw new UnsafeAssetStorePathError('asset_file', 'symlink');
+        if (!stat.isFile())
+            throw new UnsafeAssetStorePathError('asset_file', 'not_regular_file');
+        return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 'missing';
+        throw error;
+    }
+}
+function assertOpenedPathMatches(fd, path, role) {
+    const opened = fstatSync(fd, { bigint: true });
+    if (!opened.isFile())
+        throw new UnsafeAssetStorePathError(role, 'not_regular_file');
+    let current;
+    try {
+        current = lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            throw new UnsafeAssetStorePathError(role, 'path_changed');
+        throw error;
+    }
+    if (current.isSymbolicLink())
+        throw new UnsafeAssetStorePathError(role, 'symlink');
+    if (!current.isFile())
+        throw new UnsafeAssetStorePathError(role, 'not_regular_file');
+    if (opened.dev !== current.dev || opened.ino !== current.ino) {
+        throw new UnsafeAssetStorePathError(role, 'path_changed');
+    }
+}
+function openNoFollow(path, flags, mode) {
+    return mode === undefined
+        ? openSync(path, flags | noFollowFlag())
+        : openSync(path, flags | noFollowFlag(), mode);
+}
+export function readRegularBuffer(path, maxBytes = Number.MAX_SAFE_INTEGER) {
+    if (assertOptionalRegularFile(path) === null)
+        return null;
+    const fd = openNoFollow(path, constants.O_RDONLY);
+    try {
+        assertOpenedPathMatches(fd, path, 'asset_file');
+        if (fstatSync(fd).size > maxBytes)
+            throw new AssetStoreReadLimitError();
+        const value = readFileSync(fd);
+        if (value.byteLength > maxBytes)
+            throw new AssetStoreReadLimitError();
+        return value;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readUtf8Regular(path) {
+    return readRegularBuffer(path)?.toString('utf8') ?? null;
+}
+function writeAll(fd, value) {
+    const bytes = typeof value === 'string' ? Buffer.from(value, 'utf8') : value;
+    let offset = 0;
+    while (offset < bytes.length) {
+        const written = writeSync(fd, bytes, offset, bytes.length - offset);
+        if (written <= 0)
+            throw new Error('asset store write made no progress');
+        offset += written;
+    }
+}
+export function createBufferDurableExclusive(path, value, opts = {}) {
+    const parent = dirname(path);
+    assertAssetStoreDirectory(parent);
+    const fd = openNoFollow(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    let operationError;
+    let openedIdentity;
+    try {
+        assertOpenedPathMatches(fd, path, 'asset_file');
+        const opened = fstatSync(fd, { bigint: true });
+        openedIdentity = { dev: opened.dev, ino: opened.ino };
+        writeAll(fd, value);
+        (opts.syncFile ?? fsyncSync)(fd);
+    }
+    catch (error) {
+        operationError = error;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch (error) {
+            if (operationError === undefined)
+                operationError = error;
+        }
+    }
+    if (operationError !== undefined) {
+        try {
+            const current = lstatSync(path, { bigint: true });
+            if (openedIdentity
+                && !current.isSymbolicLink()
+                && current.isFile()
+                && current.dev === openedIdentity.dev
+                && current.ino === openedIdentity.ino) {
+                unlinkSync(path);
+            }
+        }
+        catch { /* preserve the primary write/fsync failure */ }
+        throw operationError;
+    }
+    (opts.syncDirectory ?? fsyncDirectoryBestEffort)(parent);
+}
+export function fsyncDirectoryBestEffort(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY);
+        fsyncSync(fd);
+    }
+    catch {
+        // Windows and some filesystems do not support syncing directory handles.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best-effort directory sync must stay best-effort */ }
+        }
+    }
+}
+export function appendUtf8Durable(path, value, opts = {}) {
+    const parent = dirname(path);
+    assertAssetStoreDirectory(parent);
+    const existed = assertOptionalRegularFile(path) !== null;
+    const fd = openNoFollow(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT, 0o600);
+    try {
+        assertOpenedPathMatches(fd, path, 'asset_file');
+        writeAll(fd, value);
+        (opts.syncFile ?? fsyncSync)(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!existed)
+        (opts.syncDirectory ?? fsyncDirectoryBestEffort)(parent);
+}
+function removeTemp(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+    }
+}
+export function replaceUtf8Durable(path, value, opts = {}) {
+    const parent = dirname(path);
+    assertAssetStoreDirectory(parent);
+    assertOptionalRegularFile(path);
+    const tempPath = join(parent, `.${basename(path)}.compact.${process.pid}.${randomUUID()}.tmp`);
+    opts.onTempPath?.(tempPath);
+    let renamed = false;
+    try {
+        const fd = openNoFollow(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        try {
+            assertOpenedPathMatches(fd, tempPath, 'temp_file');
+            writeAll(fd, value);
+            (opts.syncFile ?? fsyncSync)(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        assertOptionalRegularFile(path);
+        renameSync(tempPath, path);
+        renamed = true;
+        (opts.syncDirectory ?? fsyncDirectoryBestEffort)(parent);
+    }
+    finally {
+        if (!renamed)
+            removeTemp(tempPath);
+    }
+}
+/** Remove one exact UTF-8 suffix and fsync the new file length; false means the suffix was not current. */
+export function truncateUtf8SuffixDurable(path, suffix, opts = {}) {
+    if (assertOptionalRegularFile(path) === null)
+        return false;
+    const expected = Buffer.from(suffix, 'utf8');
+    if (expected.length === 0)
+        return false;
+    const fd = openNoFollow(path, constants.O_RDWR);
+    try {
+        assertOpenedPathMatches(fd, path, 'asset_file');
+        const stat = fstatSync(fd);
+        if (stat.size < expected.length)
+            return false;
+        const actual = Buffer.alloc(expected.length);
+        let offset = 0;
+        while (offset < actual.length) {
+            const read = readSync(fd, actual, offset, actual.length - offset, stat.size - actual.length + offset);
+            if (read === 0)
+                return false;
+            offset += read;
+        }
+        if (!actual.equals(expected))
+            return false;
+        ftruncateSync(fd, stat.size - expected.length);
+        (opts.syncFile ?? fsyncSync)(fd);
+        return true;
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/assetstore/assetSyncLedger.d.ts

@@ -16,7 +16,9 @@ export interface AssetSyncRecord {
 export declare class AssetSyncLedger {
     private readonly now;
     private readonly path;
+    private readonly lockPath;
     private readonly index;
+    private fileState;
     private loaded;
     constructor(baseDir: string, now?: () => number);
     append(rec: Omit<AssetSyncRecord, 'syncedAt'> & {
@@ -24,5 +26,7 @@ export declare class AssetSyncLedger {
     }): AssetSyncRecord;
     get(assetId: string): AssetSyncRecord | null;
     list(): AssetSyncRecord[];
-    private load;
+    private rebuildIndex;
+    private refreshUnderLock;
+    private withFreshRead;
 }