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

package/dist/assetstore/assetSidecarRecovery.js

@@ -0,0 +1,288 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { canonicalize } from '../wire/index.js';
+import { LockReleaseError } from '../util/fileLock.js';
+import { AssetStoreReadLimitError, assertAssetStoreDirectory, createBufferDurableExclusive, fsyncDirectoryBestEffort, readRegularBuffer, regularFileFingerprint, replaceUtf8Durable, withAssetStoreLock, } from './assetStoreStorage.js';
+import { parseAssetSyncSidecarRecord, parseProvenanceRecord, parseReviewRecord, } from './assetSidecarRecords.js';
+export class AssetSidecarRecoveryError extends Error {
+    reason;
+    code = 'ASSET_SIDECAR_RECOVERY_FAILED';
+    constructor(reason) {
+        super(`asset sidecar recovery failed: ${reason}`);
+        this.reason = reason;
+        this.name = 'AssetSidecarRecoveryError';
+    }
+}
+export const DEFAULT_SIDECAR_RECOVERY_MAX_FILE_BYTES = 64 * 1024 * 1024;
+function recoveryFileLimit(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return DEFAULT_SIDECAR_RECOVERY_MAX_FILE_BYTES;
+    return Math.min(DEFAULT_SIDECAR_RECOVERY_MAX_FILE_BYTES, Math.max(1, Math.floor(value)));
+}
+const SIDECAR_FILES = {
+    provenance: 'provenance.jsonl',
+    review: 'review.jsonl',
+    'asset-sync': 'asset-sync.jsonl',
+};
+const RECORD_PARSERS = {
+    provenance: parseProvenanceRecord,
+    review: parseReviewRecord,
+    'asset-sync': parseAssetSyncSidecarRecord,
+};
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function readBounded(path, limit, role) {
+    try {
+        const before = regularFileFingerprint(path);
+        if (before === 'missing') {
+            throw new AssetSidecarRecoveryError(role === 'sidecar' ? 'sidecar_missing' : 'replacement_missing');
+        }
+        const value = readRegularBuffer(path, limit);
+        if (value === null) {
+            throw new AssetSidecarRecoveryError(role === 'sidecar' ? 'sidecar_missing' : 'replacement_missing');
+        }
+        const after = regularFileFingerprint(path);
+        if (before !== after) {
+            throw new AssetSidecarRecoveryError(role === 'sidecar' ? 'sidecar_changed' : 'replacement_changed');
+        }
+        return { bytes: value, fingerprint: after };
+    }
+    catch (error) {
+        if (error instanceof AssetStoreReadLimitError) {
+            throw new AssetSidecarRecoveryError(role === 'sidecar' ? 'sidecar_too_large' : 'replacement_too_large');
+        }
+        throw error;
+    }
+}
+function parseCurrent(bytes, sidecar) {
+    const hex = digest(bytes);
+    try {
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return { bytes, text, parsed: parseRecoveryJsonl(text, RECORD_PARSERS[sidecar]), digest: `sha256:${hex}` };
+    }
+    catch {
+        return {
+            bytes,
+            text: null,
+            parsed: {
+                records: [],
+                rows: bytes.length > 0 ? 1 : 0,
+                validRows: 0,
+                corruptRows: bytes.length > 0 ? 1 : 0,
+                unterminated: bytes.length > 0 && bytes[bytes.length - 1] !== 0x0a,
+            },
+            digest: `sha256:${hex}`,
+        };
+    }
+}
+function parseReplacement(bytes, sidecar) {
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new AssetSidecarRecoveryError('replacement_invalid_utf8');
+    }
+    const parsed = parseRecoveryJsonl(text, RECORD_PARSERS[sidecar]);
+    if (parsed.corruptRows > 0)
+        throw new AssetSidecarRecoveryError('replacement_invalid');
+    if (parsed.unterminated)
+        throw new AssetSidecarRecoveryError('replacement_unterminated');
+    return { bytes, text, parsed, digest: `sha256:${digest(bytes)}` };
+}
+function parseRecoveryJsonl(raw, parseRecord) {
+    const records = [];
+    let rows = 0;
+    let corruptRows = 0;
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        rows += 1;
+        try {
+            const original = JSON.parse(line);
+            const normalized = parseRecord(original);
+            if (normalized)
+                records.push({ original, normalized });
+            else
+                corruptRows += 1;
+        }
+        catch {
+            corruptRows += 1;
+        }
+    }
+    return {
+        records,
+        rows,
+        validRows: records.length,
+        corruptRows,
+        unterminated: raw.length > 0 && !raw.endsWith('\n'),
+    };
+}
+function canonicalRecords(records) {
+    return records.map((record) => canonicalize(record.original));
+}
+function compareHistory(currentRecords, replacementRecords) {
+    const current = canonicalRecords(currentRecords);
+    const replacement = canonicalRecords(replacementRecords);
+    if (current.some((record, index) => replacement[index] !== record)) {
+        throw new AssetSidecarRecoveryError('valid_history_missing');
+    }
+    const extra = replacement.slice(current.length);
+    const existing = new Set(current);
+    return {
+        preservedValidRows: current.length,
+        addedRecords: extra.length,
+        correctiveRecords: extra.filter((record) => !existing.has(record)).length,
+        added: replacementRecords.slice(current.length),
+    };
+}
+function isSafeCorrectiveRecord(sidecar, value) {
+    if (sidecar === 'asset-sync')
+        return true;
+    if (!value.normalized || typeof value.normalized !== 'object' || Array.isArray(value.normalized))
+        return false;
+    const record = value.normalized;
+    return sidecar === 'provenance'
+        ? record['trusted'] === false
+        : record['state'] === 'quarantined' || record['state'] === 'rejected';
+}
+function fileReport(file) {
+    return {
+        rows: file.parsed.rows,
+        validRows: file.parsed.validRows,
+        corruptRows: file.parsed.corruptRows,
+        unterminated: file.parsed.unterminated,
+        digest: file.digest,
+    };
+}
+function ensureExactBackup(baseDir, sidecar, current) {
+    const backupDir = join(baseDir, 'sidecar-backups');
+    assertAssetStoreDirectory(baseDir);
+    let backupDirCreated = false;
+    if (!existsSync(backupDir)) {
+        try {
+            mkdirSync(backupDir, { recursive: false, mode: 0o700 });
+            backupDirCreated = true;
+        }
+        catch (error) {
+            if (!isErrno(error, 'EEXIST'))
+                throw error;
+        }
+    }
+    assertAssetStoreDirectory(backupDir);
+    if (backupDirCreated)
+        fsyncDirectoryBestEffort(baseDir);
+    const hex = current.digest.slice('sha256:'.length);
+    const backupId = `${sidecar}-${hex}.jsonl`;
+    const backupPath = join(backupDir, backupId);
+    try {
+        createBufferDurableExclusive(backupPath, current.bytes);
+    }
+    catch (error) {
+        if (!isErrno(error, 'EEXIST'))
+            throw error;
+        let existing;
+        try {
+            existing = readRegularBuffer(backupPath, current.bytes.length);
+        }
+        catch (readError) {
+            if (readError instanceof AssetStoreReadLimitError) {
+                throw new AssetSidecarRecoveryError('backup_conflict');
+            }
+            throw readError;
+        }
+        if (!existing?.equals(current.bytes))
+            throw new AssetSidecarRecoveryError('backup_conflict');
+    }
+    return backupId;
+}
+export function recoverAssetSidecar(opts) {
+    assertAssetStoreDirectory(opts.baseDir);
+    const maxFileBytes = recoveryFileLimit(opts.maxFileBytes);
+    const targetPath = join(opts.baseDir, SIDECAR_FILES[opts.sidecar]);
+    const lockPath = join(opts.baseDir, '.assetstore.lock');
+    let committed;
+    try {
+        return withAssetStoreLock(lockPath, () => {
+            const currentRead = readBounded(targetPath, maxFileBytes, 'sidecar');
+            const replacementRead = readBounded(opts.replacementPath, maxFileBytes, 'replacement');
+            const current = parseCurrent(currentRead.bytes, opts.sidecar);
+            const replacement = parseReplacement(replacementRead.bytes, opts.sidecar);
+            const history = compareHistory(current.parsed.records, replacement.parsed.records);
+            const degraded = current.parsed.corruptRows > 0 || current.parsed.unterminated;
+            const sameBytes = current.bytes.equals(replacement.bytes);
+            if (!degraded && !sameBytes)
+                throw new AssetSidecarRecoveryError('sidecar_not_degraded');
+            if (current.parsed.corruptRows > 0
+                && opts.sidecar !== 'asset-sync'
+                && history.correctiveRecords === 0) {
+                throw new AssetSidecarRecoveryError('corrective_record_required');
+            }
+            if (history.added.some((record) => !isSafeCorrectiveRecord(opts.sidecar, record))) {
+                throw new AssetSidecarRecoveryError('unsafe_corrective_record');
+            }
+            const acknowledgementRequired = degraded && !sameBytes;
+            const mode = opts.write ? 'write' : 'preview';
+            const baseReport = {
+                mode,
+                sidecar: opts.sidecar,
+                current: fileReport(current),
+                replacement: {
+                    ...fileReport(replacement),
+                    preservedValidRows: history.preservedValidRows,
+                    addedRecords: history.addedRecords,
+                    correctiveRecords: history.correctiveRecords,
+                },
+            };
+            if (sameBytes) {
+                return {
+                    ...baseReport,
+                    changed: false,
+                    wouldWrite: false,
+                    acknowledgementRequired: false,
+                };
+            }
+            if (!opts.write) {
+                return {
+                    ...baseReport,
+                    changed: false,
+                    wouldWrite: true,
+                    acknowledgementRequired,
+                };
+            }
+            if (!opts.acknowledgeCorruptHistory) {
+                throw new AssetSidecarRecoveryError('acknowledgement_required');
+            }
+            opts.deps?.beforeBackup?.();
+            const backupId = ensureExactBackup(opts.baseDir, opts.sidecar, current);
+            opts.deps?.beforeReplace?.();
+            if (regularFileFingerprint(targetPath) !== currentRead.fingerprint) {
+                throw new AssetSidecarRecoveryError('sidecar_changed');
+            }
+            if (regularFileFingerprint(opts.replacementPath) !== replacementRead.fingerprint) {
+                throw new AssetSidecarRecoveryError('replacement_changed');
+            }
+            replaceUtf8Durable(targetPath, replacement.text);
+            committed = {
+                ...baseReport,
+                changed: true,
+                wouldWrite: false,
+                acknowledgementRequired: false,
+                backupId,
+            };
+            return committed;
+        }, opts.deps?.lock);
+    }
+    catch (error) {
+        if (committed && error instanceof LockReleaseError) {
+            return { ...committed, lockReleaseWarning: error.reason };
+        }
+        throw error;
+    }
+}

package/dist/assetstore/assetStoreHealth.d.ts

@@ -0,0 +1,81 @@
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { type UnsafeAssetStorePathReason } from './assetStoreStorage.js';
+import type { AssetKind } from './provider.js';
+import { type AssetSidecarKind } from './assetSidecarRecords.js';
+export type AssetStoreHealthStatus = 'healthy' | 'degraded' | 'unsafe' | 'unavailable';
+export type AssetStoreFileStatus = 'missing' | 'ok' | 'degraded' | 'unsafe' | 'unavailable';
+export interface AssetStoreFileHealth {
+    kind: AssetKind;
+    file: string;
+    status: AssetStoreFileStatus;
+    bytes: number;
+    rows: number;
+    validRows: number;
+    uniqueAssets: number;
+    duplicateRows: number;
+    corruptRows: number;
+    hashMismatchRows: number;
+    /**
+     * Rows that fail content-hash verification but carry an active, content-bound unverified provenance waiver.
+     * They remain untrusted and are counted separately instead of being misclassified as store corruption.
+     */
+    unverifiedRows: number;
+    schemaInvalidRows: number;
+    unterminated: boolean;
+    reason?: UnsafeAssetStorePathReason | 'base_directory' | 'lock_unavailable' | 'read_unavailable' | 'scan_limit_exceeded';
+}
+export interface AssetStoreHealthTotals {
+    files: number;
+    missingFiles: number;
+    unsafeFiles: number;
+    unavailableFiles: number;
+    bytes: number;
+    rows: number;
+    validRows: number;
+    uniqueAssets: number;
+    duplicateRows: number;
+    corruptRows: number;
+    hashMismatchRows: number;
+    unverifiedRows: number;
+    schemaInvalidRows: number;
+    unterminatedFiles: number;
+}
+export interface AssetStoreSidecarHealth {
+    kind: AssetSidecarKind;
+    file: string;
+    status: AssetStoreFileStatus;
+    bytes: number;
+    rows: number;
+    validRows: number;
+    corruptRows: number;
+    unterminated: boolean;
+    reason?: AssetStoreFileHealth['reason'];
+}
+export interface AssetStoreSidecarHealthTotals {
+    files: number;
+    missingFiles: number;
+    unsafeFiles: number;
+    unavailableFiles: number;
+    bytes: number;
+    rows: number;
+    validRows: number;
+    corruptRows: number;
+    unterminatedFiles: number;
+}
+export interface AssetStoreHealthReport {
+    ok: boolean;
+    status: AssetStoreHealthStatus;
+    totals: AssetStoreHealthTotals;
+    files: AssetStoreFileHealth[];
+    sidecarTotals: AssetStoreSidecarHealthTotals;
+    sidecars: AssetStoreSidecarHealth[];
+}
+export interface InspectLocalAssetStoreOptions {
+    maxFileBytes?: number;
+}
+export interface InspectLocalAssetStoreDeps {
+    acquireLock?: typeof acquireLock;
+    releaseLock?: typeof releaseLock;
+}
+export declare const DEFAULT_ASSET_HEALTH_MAX_FILE_BYTES: number;
+export declare function inspectLocalAssetStore(baseDir: string, opts?: InspectLocalAssetStoreOptions, deps?: InspectLocalAssetStoreDeps): AssetStoreHealthReport;

package/dist/assetstore/assetStoreHealth.js

@@ -0,0 +1,319 @@
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { computeAssetId, validateWire, verifyAssetId } from '../wire/index.js';
+import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
+import { assertOptionalRegularFile, isReliableAssetStoreLockRelease, readUtf8Regular, UnsafeAssetStorePathError, } from './assetStoreStorage.js';
+import { isActiveUnverifiedProvenance } from './provenance.js';
+import { parseAssetSyncSidecarRecord, 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: parseAssetSyncSidecarRecord },
+];
+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,
+        unverifiedRows: 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),
+        unverifiedRows: files.reduce((sum, file) => sum + file.unverifiedRows, 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, unverifiedContentIds) {
+    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, maxFileBytes);
+        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 unverifiedRows = 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);
+                const hashMatches = verifyAssetId(record);
+                if (!hashMatches) {
+                    // A hash mismatch is corruption UNLESS provenance says this id is an unverified hub reuse: the hub
+                    // rewrote the delivered bytes and reuse froze them untrusted on purpose (#570). That is expected, not
+                    // store rot, so it lands in the benign unverifiedRows bucket and never degrades the store.
+                    if (unverifiedContentIds.get(assetId) === computeAssetId(record))
+                        unverifiedRows += 1;
+                    else
+                        hashMismatchRows += 1;
+                }
+                const schemaValid = kind === 'AntiGene' || validateWire(record).ok;
+                if (!schemaValid) {
+                    schemaInvalidRows += 1;
+                }
+                if (hashMatches && schemaValid)
+                    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,
+            unverifiedRows,
+            schemaInvalidRows,
+            unterminated,
+        };
+    }
+    catch (error) {
+        if (error instanceof UnsafeAssetStorePathError)
+            return emptyFile(kind, file, 'unsafe', error.reason);
+        return emptyFile(kind, file, 'unavailable', 'read_unavailable');
+    }
+}
+/**
+ * Asset ids whose latest provenance decision marks a supported unverified frozen ingest.
+ * Read directly from `<baseDir>/provenance.jsonl` — NOT via ProvenanceStore — because inspectLocalAssetStore
+ * already holds the shared `.assetstore.lock`, and ProvenanceStore would try to re-acquire it. A missing or
+ * unreadable sidecar yields an empty map: without provenance every mismatch stays classified as corruption.
+ */
+function readUnverifiedReuseContentIds(baseDir, maxFileBytes) {
+    let raw;
+    try {
+        raw = readUtf8Regular(join(baseDir, 'provenance.jsonl'), maxFileBytes);
+    }
+    catch {
+        return new Map();
+    }
+    if (raw === null)
+        return new Map();
+    const ids = new Map();
+    for (const record of parseSidecarJsonl(raw, parseProvenanceRecord).records) {
+        const frozenContentId = record.frozenContentId;
+        if (frozenContentId && isActiveUnverifiedProvenance(record, frozenContentId)) {
+            ids.set(record.assetId, frozenContentId);
+        }
+        else
+            ids.delete(record.assetId);
+    }
+    return ids;
+}
+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, maxFileBytes);
+        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'));
+    }
+    let report;
+    try {
+        const maxFileBytes = healthScanLimit(opts.maxFileBytes);
+        // Read the unverified-reuse set once, under the lock we already hold, so every asset file classifies its
+        // hash mismatches consistently against the same bounded provenance snapshot.
+        const unverifiedContentIds = readUnverifiedReuseContentIds(baseDir, maxFileBytes);
+        report = summarize(Object.entries(LOCAL_ASSET_FILES)
+            .map(([kind, file]) => inspectFile(baseDir, kind, file, maxFileBytes, unverifiedContentIds)), 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>>;