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

package/dist/assetstore/assetSyncLedger.js

@@ -1,86 +1,66 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { appendUtf8Durable, assertAssetStoreDirectory, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, withAssetStoreLock, } from './assetStoreStorage.js';
+import { parseAssetSyncRecord, parseSidecarJsonl } from './assetSidecarRecords.js';
 export class AssetSyncLedger {
     now;
     path;
+    lockPath;
     index = new Map();
+    fileState = null;
     loaded = false;
     constructor(baseDir, now = Date.now) {
         this.now = now;
+        ensureAssetStoreDirectory(baseDir);
         this.path = join(baseDir, 'asset-sync.jsonl');
+        this.lockPath = join(baseDir, '.assetstore.lock');
     }
     append(rec) {
-        this.load();
-        const full = {
-            ...rec,
-            syncedAt: rec.syncedAt ?? new Date(this.now()).toISOString(),
-        };
-        mkdirSync(dirname(this.path), { recursive: true });
-        appendFileSync(this.path, `${JSON.stringify(full)}\n`);
-        this.index.set(full.assetId, full);
-        return full;
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const full = immutableRecord({
+                ...rec,
+                syncedAt: rec.syncedAt ?? new Date(this.now()).toISOString(),
+            });
+            appendUtf8Durable(this.path, `${JSON.stringify(full)}\n`);
+            this.index.set(full.assetId, full);
+            this.fileState = regularFileFingerprint(this.path);
+            return full;
+        });
     }
     get(assetId) {
-        this.load();
-        return this.index.get(assetId) ?? null;
+        return this.withFreshRead((index) => index.get(assetId) ?? null);
     }
     list() {
-        this.load();
-        return [...this.index.values()];
+        return this.withFreshRead((index) => [...index.values()]);
     }
-    load() {
-        if (this.loaded)
-            return;
-        if (existsSync(this.path)) {
-            for (const line of readFileSync(this.path, 'utf8').split('\n')) {
-                if (!line.trim())
-                    continue;
-                try {
-                    const rec = parseRecord(JSON.parse(line));
-                    if (rec)
-                        this.index.set(rec.assetId, rec);
-                }
-                catch {
-                    // Skip corrupt audit lines; the asset store remains the source of content truth.
-                }
-            }
+    rebuildIndex(state) {
+        const next = new Map();
+        const raw = state === 'missing' ? null : readUtf8Regular(this.path);
+        if (raw !== null) {
+            const parsed = parseSidecarJsonl(raw, parseAssetSyncRecord);
+            for (const record of parsed.records)
+                next.set(record.assetId, immutableRecord(record));
         }
+        this.index.clear();
+        for (const [assetId, record] of next)
+            this.index.set(assetId, record);
+        this.fileState = state;
         this.loaded = true;
     }
-}
-function parseRecord(value) {
-    const assetId = stringField(value, 'assetId');
-    const type = stringField(value, 'type');
-    const source = stringField(value, 'source');
-    const scope = stringField(value, 'scope');
-    const syncedAt = stringField(value, 'syncedAt');
-    const remoteAssetId = stringField(value, 'remoteAssetId');
-    if (!assetId ||
-        (type !== 'Gene' && type !== 'Capsule') ||
-        source !== 'hub' ||
-        (scope !== 'purchased' && scope !== 'published') ||
-        !syncedAt ||
-        !remoteAssetId) {
-        return null;
+    refreshUnderLock() {
+        const state = regularFileFingerprint(this.path);
+        if (!this.loaded || state !== this.fileState)
+            this.rebuildIndex(state);
+    }
+    withFreshRead(read) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            return read(this.index);
+        });
     }
-    const logicalId = stringField(value, 'logicalId');
-    const status = stringField(value, 'status');
-    const forced = value['forced'] === true;
-    const collisionWithAssetId = stringField(value, 'collisionWithAssetId');
-    return {
-        assetId,
-        type,
-        source,
-        scope,
-        syncedAt,
-        remoteAssetId,
-        ...(logicalId ? { logicalId } : {}),
-        ...(status ? { status } : {}),
-        ...(forced ? { forced: true } : {}),
-        ...(collisionWithAssetId ? { collisionWithAssetId } : {}),
-    };
 }
-function stringField(value, key) {
-    const raw = value[key];
-    return typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+function immutableRecord(record) {
+    return Object.freeze({ ...record });
 }

package/dist/assetstore/index.d.ts

@@ -1,5 +1,7 @@
 export * from './provider.js';
 export * from './localJsonl.js';
+export * from './assetStoreHealth.js';
+export * from './assetSidecarRecovery.js';
 export * from './remoteStub.js';
 export * from './learningHistory.js';
 export * from './provenance.js';

package/dist/assetstore/index.js

@@ -1,5 +1,7 @@
 export * from './provider.js';
 export * from './localJsonl.js';
+export * from './assetStoreHealth.js';
+export * from './assetSidecarRecovery.js';
 export * from './remoteStub.js';
 export * from './learningHistory.js';
 export * from './provenance.js';

package/dist/assetstore/localJsonl.d.ts

@@ -25,6 +25,7 @@ export declare class LocalJsonlProvider implements AssetStoreProvider {
      */
     putFrozen(record: AssetRecord): Promise<PutResult>;
     get(assetId: string): Promise<AssetRecord | null>;
+    findByLogicalId(id: string, limit?: number): Promise<AssetRecord[]>;
     list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
     search(q: SearchQuery): Promise<AssetRecord[]>;
     /**

package/dist/assetstore/localJsonl.js

@@ -1,22 +1,8 @@
-import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { appendUtf8Durable, assertAssetStoreDirectory, assertOptionalRegularFile, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, replaceUtf8Durable, } from './assetStoreStorage.js';
+import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
 import { normalizeForPut, } from './provider.js';
-const FILES = { Gene: 'genes.jsonl', Capsule: 'capsules.jsonl', EvolutionEvent: 'events.jsonl', AntiGene: 'anti-genes.jsonl' };
-function isErrno(error, code) {
-    return typeof error === 'object' && error !== null && error.code === code;
-}
-function fileFingerprint(path) {
-    try {
-        const stat = statSync(path, { bigint: true });
-        return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
-    }
-    catch (error) {
-        if (isErrno(error, 'ENOENT'))
-            return 'missing';
-        throw error;
-    }
-}
 function signalsOf(a) {
     const out = [];
     for (const key of ['signals_match', 'signals', 'trigger', 'trigger_signals']) {
@@ -44,13 +30,14 @@ export class LocalJsonlProvider {
     // — the ReviewLedger/ProvenanceStore — in the SAME directory, instead of defaulting to the real ~/.evomap.
     constructor(baseDir) {
         this.baseDir = baseDir;
-        mkdirSync(baseDir, { recursive: true });
+        ensureAssetStoreDirectory(baseDir);
         this.lockPath = join(baseDir, '.assetstore.lock');
     }
     captureFileState() {
+        assertAssetStoreDirectory(this.baseDir);
         const state = new Map();
-        for (const [kind, file] of Object.entries(FILES)) {
-            state.set(kind, fileFingerprint(join(this.baseDir, file)));
+        for (const [kind, file] of Object.entries(LOCAL_ASSET_FILES)) {
+            state.set(kind, regularFileFingerprint(join(this.baseDir, file)));
         }
         return state;
     }
@@ -65,11 +52,12 @@ export class LocalJsonlProvider {
     }
     rebuildIndex(state) {
         const next = new Map();
-        for (const file of Object.values(FILES)) {
+        for (const file of Object.values(LOCAL_ASSET_FILES)) {
             const p = join(this.baseDir, file);
-            if (!existsSync(p))
+            const raw = readUtf8Regular(p);
+            if (raw === null)
                 continue;
-            for (const line of readFileSync(p, 'utf8').split('\n')) {
+            for (const line of raw.split('\n')) {
                 if (!line.trim())
                     continue;
                 try {
@@ -95,6 +83,7 @@ export class LocalJsonlProvider {
         const state = this.captureFileState();
         if (!this.stateChanged(state))
             return;
+        assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
             this.refreshUnderLock();
@@ -109,14 +98,15 @@ export class LocalJsonlProvider {
     }
     async put(asset) {
         const { record, verified } = normalizeForPut(asset);
-        const file = join(this.baseDir, FILES[record.type]);
+        const file = join(this.baseDir, LOCAL_ASSET_FILES[record.type]);
+        assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
             // Refresh under the shared lock so another process cannot append between reload and dedupe.
             this.refreshUnderLock();
             if (this.index.has(record.asset_id))
                 return { asset_id: record.asset_id, stored: false, verified };
-            appendFileSync(file, `${JSON.stringify(record)}\n`);
+            appendUtf8Durable(file, `${JSON.stringify(record)}\n`);
             this.index.set(record.asset_id, record);
             this.updateFileStateAfterWrite();
         }
@@ -132,13 +122,14 @@ export class LocalJsonlProvider {
     async putFrozen(record) {
         if (!record.asset_id)
             throw new Error('putFrozen 需 record 自带冻结 asset_id');
-        const file = join(this.baseDir, FILES[record.type]);
+        const file = join(this.baseDir, LOCAL_ASSET_FILES[record.type]);
+        assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
             this.refreshUnderLock();
             if (this.index.has(record.asset_id))
                 return { asset_id: record.asset_id, stored: false, verified: false };
-            appendFileSync(file, `${JSON.stringify(record)}\n`);
+            appendUtf8Durable(file, `${JSON.stringify(record)}\n`);
             this.index.set(record.asset_id, record);
             this.updateFileStateAfterWrite();
         }
@@ -151,6 +142,19 @@ export class LocalJsonlProvider {
         this.ensureFresh();
         return this.index.get(assetId) ?? null;
     }
+    async findByLogicalId(id, limit = 2) {
+        this.ensureFresh();
+        const boundedLimit = Number.isFinite(limit) ? Math.max(1, Math.min(1_000, Math.floor(limit))) : 2;
+        const out = [];
+        for (const record of this.index.values()) {
+            if (record['id'] !== id)
+                continue;
+            out.push(record);
+            if (out.length >= boundedLimit)
+                break;
+        }
+        return out;
+    }
     async list(kind, limit = 1000) {
         this.ensureFresh();
         const out = [];
@@ -199,15 +203,17 @@ export class LocalJsonlProvider {
      * the write lock. Returns kept/removed line counts.
      */
     async compact() {
+        assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
             this.refreshUnderLock();
             let kept = 0, removed = 0;
-            for (const [kind, file] of Object.entries(FILES)) {
+            for (const [kind, file] of Object.entries(LOCAL_ASSET_FILES)) {
                 const p = join(this.baseDir, file);
-                if (!existsSync(p))
+                const raw = readUtf8Regular(p);
+                if (raw === null)
                     continue;
-                const lines = readFileSync(p, 'utf8').split('\n').filter((l) => l.trim());
+                const lines = raw.split('\n').filter((l) => l.trim());
                 const byId = new Map(); // asset_id → raw line (last wins, matching load semantics)
                 for (const line of lines) {
                     try {
@@ -218,9 +224,7 @@ export class LocalJsonlProvider {
                     catch { /* drop corrupt line */ }
                 }
                 const out = byId.size ? `${[...byId.values()].join('\n')}\n` : '';
-                const tmp = `${p}.compact.tmp`;
-                writeFileSync(tmp, out);
-                renameSync(tmp, p); // atomic replace; a crash mid-compact leaves the original intact
+                replaceUtf8Durable(p, out);
                 kept += byId.size;
                 removed += lines.length - byId.size;
             }

package/dist/assetstore/provenance.d.ts

@@ -1,13 +1,21 @@
 import { type AssetStoreProvider, type AssetRecord, type PutResult } from './provider.js';
 export type ProvenanceSource = 'local' | 'migrated' | 'hub';
+export type ProvenanceDecision = 'promoted' | 'revoked';
 export interface ProvenanceRecord {
     assetId: string;
     source: ProvenanceSource;
     trusted: boolean;
     at: string;
+    decision?: ProvenanceDecision;
+    decidedBy?: string;
+    /** Legacy promotion actor field kept for existing sidecar readers. */
     promotedBy?: string;
     reason?: string;
 }
+export interface ProvenanceTrustChange {
+    changed: boolean;
+    record: ProvenanceRecord;
+}
 /**
  * Append-only JSONL sidecar (last-write-wins) at <baseDir>/provenance.jsonl. Default for an asset with NO
  * record = trusted: the only local writers (cycleEngine self-produce, v1 migration) are trusted and never
@@ -23,6 +31,7 @@ export declare class ProvenanceStore {
     private rebuildIndex;
     private refreshUnderLock;
     private withFreshRead;
+    private appendUnderLock;
     /** Record provenance for an asset_id (append-only; the JSONL history is the audit trail). */
     mark(rec: Omit<ProvenanceRecord, 'at'> & {
         at?: string;
@@ -33,8 +42,12 @@ export declare class ProvenanceStore {
     isTrusted(assetId: string): boolean;
     /** One linearizable trust snapshot for bounded batch readers. */
     snapshot(): ReadonlyMap<string, ProvenanceRecord>;
+    /** Compare and append one trust decision under the same cross-process lock. */
+    changeTrust(assetId: string, trusted: boolean, by: string, reason: string): ProvenanceTrustChange;
     /** Explicit, audited untrusted→trusted promotion. Appends a new trusted record carrying who/why. */
     promote(assetId: string, by: string, reason: string): ProvenanceRecord;
+    /** Explicit, audited trusted-to-untrusted revocation. A record-less asset is local by default. */
+    revoke(assetId: string, by: string, reason: string): ProvenanceRecord;
 }
 /**
  * The sanctioned hub→local-pool landing: store the asset (store.put recomputes/normalizes the asset_id, so a

package/dist/assetstore/provenance.js

@@ -3,23 +3,12 @@
 // by asset_id, NOT a field on the asset: asset_id = sha256(canonicalize(asset)), and "how we got it" metadata
 // must not enter the content hash (#30.2), or it would break content-addressing. Trust-first by construction:
 // selection defaults to trusted-only; an untrusted asset is promoted to trusted only by an explicit, logged act.
-import { appendFileSync, closeSync, existsSync, openSync, readFileSync, readSync, mkdirSync, statSync, truncateSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { acquireLock, releaseLock } from '../util/fileLock.js';
 import { normalizeForPut } from './provider.js';
-function isErrno(error, code) {
-    return typeof error === 'object' && error !== null && error.code === code;
-}
-function fileFingerprint(path) {
-    try {
-        const stat = statSync(path, { bigint: true });
-        return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
-    }
-    catch (error) {
-        if (isErrno(error, 'ENOENT'))
-            return 'missing';
-        throw error;
-    }
+import { appendUtf8Durable, assertAssetStoreDirectory, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, truncateUtf8SuffixDurable, withAssetStoreLock, } from './assetStoreStorage.js';
+import { assertTrustSidecarHealthy, parseProvenanceRecord, parseSidecarJsonl, } from './assetSidecarRecords.js';
+function immutableRecord(record) {
+    return Object.freeze({ ...record });
 }
 /**
  * Append-only JSONL sidecar (last-write-wins) at <baseDir>/provenance.jsonl. Default for an asset with NO
@@ -34,22 +23,18 @@ export class ProvenanceStore {
     fileState = null;
     constructor(baseDir, now = Date.now) {
         this.now = now;
+        ensureAssetStoreDirectory(baseDir);
         this.path = join(baseDir, 'provenance.jsonl');
         this.lockPath = join(baseDir, '.assetstore.lock');
     }
     rebuildIndex(state) {
         const next = new Map();
-        if (state !== 'missing') {
-            for (const line of readFileSync(this.path, 'utf8').split('\n')) {
-                if (!line.trim())
-                    continue;
-                try {
-                    const r = JSON.parse(line);
-                    if (r.assetId)
-                        next.set(r.assetId, r);
-                }
-                catch { /* skip corrupt line */ }
-            }
+        const raw = state === 'missing' ? null : readUtf8Regular(this.path);
+        if (raw !== null) {
+            const parsed = parseSidecarJsonl(raw, parseProvenanceRecord);
+            assertTrustSidecarHealthy('provenance', parsed);
+            for (const record of parsed.records)
+                next.set(record.assetId, immutableRecord(record));
         }
         this.index.clear();
         for (const [assetId, record] of next)
@@ -57,82 +42,49 @@ export class ProvenanceStore {
         this.fileState = state;
     }
     refreshUnderLock() {
-        const state = fileFingerprint(this.path);
+        const state = regularFileFingerprint(this.path);
         if (state !== this.fileState)
             this.rebuildIndex(state);
     }
     withFreshRead(read) {
-        mkdirSync(dirname(this.path), { recursive: true });
-        acquireLock(this.lockPath);
-        try {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
             return read(this.index);
-        }
-        finally {
-            releaseLock(this.lockPath);
-        }
+        });
+    }
+    appendUnderLock(full) {
+        const stored = immutableRecord(full);
+        appendUtf8Durable(this.path, `${JSON.stringify(stored)}\n`);
+        this.index.set(stored.assetId, stored);
+        this.fileState = regularFileFingerprint(this.path);
+        return stored;
     }
     /** Record provenance for an asset_id (append-only; the JSONL history is the audit trail). */
     mark(rec) {
         const full = { ...rec, at: rec.at ?? new Date(this.now()).toISOString() };
-        mkdirSync(dirname(this.path), { recursive: true });
-        acquireLock(this.lockPath);
-        try {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
-            appendFileSync(this.path, `${JSON.stringify(full)}\n`);
-            this.index.set(full.assetId, full);
-            this.fileState = fileFingerprint(this.path);
-        }
-        finally {
-            releaseLock(this.lockPath);
-        }
-        return full;
+            return this.appendUnderLock(full);
+        });
     }
     rollbackLast(rec) {
         const line = `${JSON.stringify(rec)}\n`;
-        const lineBytes = Buffer.byteLength(line, 'utf8');
-        let locked = false;
         try {
-            mkdirSync(dirname(this.path), { recursive: true });
-            acquireLock(this.lockPath);
-            locked = true;
-            if (!existsSync(this.path))
-                return;
-            const stat = statSync(this.path);
-            if (!stat.isFile() || stat.size < lineBytes)
-                return;
-            const offset = stat.size - lineBytes;
-            const buf = Buffer.alloc(lineBytes);
-            const fd = openSync(this.path, 'r');
-            try {
-                readSync(fd, buf, 0, lineBytes, offset);
-            }
-            finally {
-                closeSync(fd);
-            }
-            if (buf.toString('utf8') !== line) {
-                this.refreshUnderLock();
-                return;
-            }
-            truncateSync(this.path, offset);
-            this.rebuildIndex(fileFingerprint(this.path));
+            assertAssetStoreDirectory(dirname(this.path));
+            withAssetStoreLock(this.lockPath, () => {
+                if (!truncateUtf8SuffixDurable(this.path, line)) {
+                    this.refreshUnderLock();
+                    return;
+                }
+                this.rebuildIndex(regularFileFingerprint(this.path));
+            });
         }
         catch {
             this.index.clear();
             this.fileState = null;
         }
-        finally {
-            if (locked) {
-                try {
-                    releaseLock(this.lockPath);
-                }
-                catch {
-                    // Rollback is best-effort and must not mask the store failure that triggered it.
-                    this.index.clear();
-                    this.fileState = null;
-                }
-            }
-        }
     }
     get(assetId) {
         return this.withFreshRead((index) => index.get(assetId) ?? null);
@@ -145,10 +97,34 @@ export class ProvenanceStore {
     snapshot() {
         return this.withFreshRead((index) => new Map(index));
     }
+    /** Compare and append one trust decision under the same cross-process lock. */
+    changeTrust(assetId, trusted, by, reason) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId) ?? null;
+            if (current?.trusted === trusted)
+                return { changed: false, record: current };
+            const full = {
+                assetId,
+                source: current?.source ?? 'local',
+                trusted,
+                at: new Date(this.now()).toISOString(),
+                decision: trusted ? 'promoted' : 'revoked',
+                decidedBy: by,
+                ...(trusted ? { promotedBy: by } : {}),
+                reason,
+            };
+            return { changed: true, record: this.appendUnderLock(full) };
+        });
+    }
     /** Explicit, audited untrusted→trusted promotion. Appends a new trusted record carrying who/why. */
     promote(assetId, by, reason) {
-        const cur = this.get(assetId);
-        return this.mark({ assetId, source: cur?.source ?? 'hub', trusted: true, promotedBy: by, reason });
+        return this.changeTrust(assetId, true, by, reason).record;
+    }
+    /** Explicit, audited trusted-to-untrusted revocation. A record-less asset is local by default. */
+    revoke(assetId, by, reason) {
+        return this.changeTrust(assetId, false, by, reason).record;
     }
 }
 /**

package/dist/assetstore/provider.d.ts

@@ -25,6 +25,8 @@ export interface SearchQuery {
 export interface AssetStoreProvider {
     put(asset: AssetRecord): Promise<PutResult>;
     get(assetId: string): Promise<AssetRecord | null>;
+    /** Optional direct lookup for non-content-addressed logical ids. Callers must handle 0, 1, or multiple matches. */
+    findByLogicalId?(id: string, limit?: number): Promise<AssetRecord[]>;
     search(query: SearchQuery): Promise<AssetRecord[]>;
     list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
 }

package/dist/assetstore/reviewFilter.js

@@ -31,11 +31,13 @@ export function provenanceStoreForStore(store) {
 export async function listApprovedGenes(store, review, maxGenes, provenance = provenanceStoreForStore(store)) {
     const all = await store.list('Gene', GENE_SCAN_LIMIT);
     const trust = provenance.snapshot();
+    const reviewed = review.snapshot();
     const approved = [];
     for (const g of all) {
         if (trust.get(String(g.asset_id))?.trusted === false)
             continue; // hub-untrusted → withhold until promoted
-        if (!review.isApproved(String(g.asset_id)))
+        const reviewRecord = reviewed.get(String(g.asset_id));
+        if (reviewRecord !== undefined && reviewRecord.state !== 'approved')
             continue; // quarantined/rejected draft → withhold
         approved.push(g);
         if (approved.length >= maxGenes)

package/dist/assetstore/reviewLedger.d.ts

@@ -18,13 +18,17 @@ export interface ReviewRecord {
 export declare class ReviewLedger {
     private readonly now;
     private readonly path;
+    private readonly lockPath;
     private readonly index;
-    private sig;
+    private fileState;
     constructor(baseDir: string, now?: () => number);
     private static isHuman;
     /** Which record wins for an asset_id: a human decision beats a quarantine; otherwise the later one wins. */
     private static keep;
-    private load;
+    private rebuildIndex;
+    private refreshUnderLock;
+    private withFreshRead;
+    private appendUnderLock;
     /** Record a review-state for an asset_id (append-only; the JSONL history is the audit trail). */
     mark(rec: Omit<ReviewRecord, 'at'> & {
         at?: string;
@@ -50,6 +54,8 @@ export declare class ReviewLedger {
      * asset list, so a draft awaiting approval is never missed behind a store-list cutoff.
      */
     records(): ReviewRecord[];
+    /** One linearizable review snapshot for bounded batch readers. */
+    snapshot(): ReadonlyMap<string, ReviewRecord>;
     /** No record → approved (default eligible); a record → approved only when its state is 'approved'. */
     isApproved(assetId: string): boolean;
     /**