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

package/dist/assetstore/foreignJsonlSource.d.ts

@@ -0,0 +1,48 @@
+import type { AssetKind, AssetRecord, AssetStoreProvider, PutResult, SearchQuery } from './provider.js';
+/** Thrown by every mutating method: a foreign pool is readable, never writable. */
+export declare class ForeignStoreReadOnlyError extends Error {
+    readonly baseDir: string;
+    readonly kind?: AssetKind | undefined;
+    readonly code = "FOREIGN_STORE_READ_ONLY";
+    constructor(baseDir: string, kind?: AssetKind | undefined);
+}
+/**
+ * EvoX's asset directory: `EVOX_ASSETS_DIR`, else `~/.evox/agent/evolver/assets`. Returns the path
+ * whether or not it exists; {@link ForeignJsonlSource} treats a missing directory as an empty pool.
+ *
+ * The name is engine-scoped on purpose, matching the EVOLVER_HOME / EVOMAP_HOME split. It deliberately
+ * does NOT honour `GEP_ASSETS_DIR`: in THIS repo that variable relocates evolver's OWN pool
+ * (`pendingSignals.legacyV1BaseDir`, README.npm.md), so a user who moved their own store per our own
+ * documentation would silently get a union of the primary with itself and never read EvoX at all.
+ */
+export declare function evoxAssetDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Read-only provider over a foreign asset directory. Re-reads on every call rather than caching: the
+ * owning engine appends to these files behind our back, and a stale cache would silently freeze a gene's
+ * evidence at whatever it was when this process started.
+ */
+export declare class ForeignJsonlSource implements AssetStoreProvider {
+    readonly baseDir: string;
+    private readonly reportedUnreadable;
+    constructor(baseDir: string);
+    /**
+     * Read one foreign file, degrading it to "empty" on ANY failure.
+     *
+     * `readUtf8Regular` returns null only for a missing file and THROWS for a symlink, a non-regular file,
+     * EACCES, ELOOP or ENOTDIR. This read runs inside gene selection (aggregateLearningHistory →
+     * candidateAssembly), where an exception would abort the host's whole cycle — a pool we do not own, and
+     * whose contents are optional extra evidence, must never have that power. Degrading is per file so one
+     * unreadable capsules.jsonl does not also hide genes.jsonl.
+     *
+     * Warned once per path per instance: reads are re-run on every call by design, and a per-call warning
+     * would bury the cycle's real output.
+     */
+    private readOrDegrade;
+    private read;
+    put(asset: AssetRecord): Promise<PutResult>;
+    get(assetId: string): Promise<AssetRecord | null>;
+    /** Filters by logical id BEFORE the cap, so `limit` bounds matches returned, never records scanned. */
+    findByLogicalId(id: string, limit?: number, kind?: AssetKind): Promise<AssetRecord[]>;
+    list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+    search(q: SearchQuery): Promise<AssetRecord[]>;
+}

package/dist/assetstore/foreignJsonlSource.js

@@ -0,0 +1,150 @@
+// Read-only view over ANOTHER evolution engine's local asset pool (#195 follow-up).
+//
+// Why this exists: gene health (algo/geneHealth.ts) is derived from capsule outcomes via
+// aggregateLearningHistory, which can only see what the injected provider sees. EvoX runs write their
+// capsules to EvoX's own pool (`~/.evox/agent/evolver/assets`), not to `~/.evomap`, so every EvoX-produced
+// gene aggregates to an empty view here and scores 0 no matter how its runs actually went. Pointing a
+// LocalJsonlProvider at that directory is NOT an option: its constructor creates the directory and its
+// reads take a lock file inside it, i.e. it would WRITE into a store this engine does not own.
+//
+// The boundary is symmetric and deliberate. EvoX blocks its own agent from writing into `~/.evomap`
+// (`evox-agent-core::foreign_store_guard`) while explicitly leaving reads unguarded — "inspecting a
+// foreign store is legitimate diagnosis; mutating it is not". This module is the mirror of that rule:
+// every write path throws, nothing is created, no lock is taken, and the foreign directory is left
+// byte-identical.
+//
+// The on-disk layout is shared (one jsonl per kind, content-addressed records), so reading is just
+// parsing — no format adapter and no second wire contract.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { readUtf8Regular } from './assetStoreStorage.js';
+import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
+import { signalsOf } from './localJsonl.js';
+/** Thrown by every mutating method: a foreign pool is readable, never writable. */
+export class ForeignStoreReadOnlyError extends Error {
+    baseDir;
+    kind;
+    code = 'FOREIGN_STORE_READ_ONLY';
+    constructor(baseDir, kind) {
+        super(`refusing to write ${kind ?? 'an asset'} into a foreign evolution store: ${baseDir}`);
+        this.baseDir = baseDir;
+        this.kind = kind;
+        this.name = 'ForeignStoreReadOnlyError';
+    }
+}
+/**
+ * EvoX's asset directory: `EVOX_ASSETS_DIR`, else `~/.evox/agent/evolver/assets`. Returns the path
+ * whether or not it exists; {@link ForeignJsonlSource} treats a missing directory as an empty pool.
+ *
+ * The name is engine-scoped on purpose, matching the EVOLVER_HOME / EVOMAP_HOME split. It deliberately
+ * does NOT honour `GEP_ASSETS_DIR`: in THIS repo that variable relocates evolver's OWN pool
+ * (`pendingSignals.legacyV1BaseDir`, README.npm.md), so a user who moved their own store per our own
+ * documentation would silently get a union of the primary with itself and never read EvoX at all.
+ */
+export function evoxAssetDir(env = process.env) {
+    const override = env['EVOX_ASSETS_DIR']?.trim();
+    if (override)
+        return resolve(override);
+    return join(homedir(), '.evox', 'agent', 'evolver', 'assets');
+}
+function parseJsonlRecords(raw) {
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const record = JSON.parse(line);
+            if (record.asset_id)
+                out.push(record);
+        }
+        catch { /* skip corrupt line, same tolerance LocalJsonlProvider applies */ }
+    }
+    return out;
+}
+function matchesQuery(record, q) {
+    if (q.kind && record.type !== q.kind)
+        return false;
+    if (q.gene && record.gene !== q.gene)
+        return false;
+    if (q.category) {
+        const category = record.category
+            ?? record.intent;
+        if (category !== q.category)
+            return false;
+    }
+    if (q.text && !String(record.summary ?? '').includes(q.text))
+        return false;
+    if (q.signalsAny && q.signalsAny.length > 0) {
+        const advertised = new Set(signalsOf(record).map((signal) => signal.trim().toLowerCase()));
+        if (!q.signalsAny.some((signal) => advertised.has(signal.trim().toLowerCase())))
+            return false;
+    }
+    return true;
+}
+/**
+ * Read-only provider over a foreign asset directory. Re-reads on every call rather than caching: the
+ * owning engine appends to these files behind our back, and a stale cache would silently freeze a gene's
+ * evidence at whatever it was when this process started.
+ */
+export class ForeignJsonlSource {
+    baseDir;
+    reportedUnreadable = new Set();
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    /**
+     * Read one foreign file, degrading it to "empty" on ANY failure.
+     *
+     * `readUtf8Regular` returns null only for a missing file and THROWS for a symlink, a non-regular file,
+     * EACCES, ELOOP or ENOTDIR. This read runs inside gene selection (aggregateLearningHistory →
+     * candidateAssembly), where an exception would abort the host's whole cycle — a pool we do not own, and
+     * whose contents are optional extra evidence, must never have that power. Degrading is per file so one
+     * unreadable capsules.jsonl does not also hide genes.jsonl.
+     *
+     * Warned once per path per instance: reads are re-run on every call by design, and a per-call warning
+     * would bury the cycle's real output.
+     */
+    readOrDegrade(path) {
+        try {
+            return readUtf8Regular(path);
+        }
+        catch (error) {
+            if (!this.reportedUnreadable.has(path)) {
+                this.reportedUnreadable.add(path);
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[ForeignAssetPool] Failed to read ${path} (non-fatal, treated as empty): ${message}`);
+            }
+            return null;
+        }
+    }
+    read(kind) {
+        const files = kind ? [LOCAL_ASSET_FILES[kind]] : Object.values(LOCAL_ASSET_FILES);
+        const byAssetId = new Map();
+        for (const file of files) {
+            const raw = this.readOrDegrade(join(this.baseDir, file));
+            if (raw === null)
+                continue;
+            for (const record of parseJsonlRecords(raw))
+                byAssetId.set(record.asset_id, record);
+        }
+        return [...byAssetId.values()];
+    }
+    async put(asset) {
+        throw new ForeignStoreReadOnlyError(this.baseDir, asset.type);
+    }
+    async get(assetId) {
+        return this.read().find((record) => record.asset_id === assetId) ?? null;
+    }
+    /** Filters by logical id BEFORE the cap, so `limit` bounds matches returned, never records scanned. */
+    async findByLogicalId(id, limit = 1000, kind) {
+        return this.read(kind)
+            .filter((record) => record['id'] === id && (kind === undefined || record.type === kind))
+            .slice(0, Math.max(1, limit));
+    }
+    async list(kind, limit = 1000) {
+        return this.read(kind).slice(0, limit);
+    }
+    async search(q) {
+        return this.read(q.kind).filter((record) => matchesQuery(record, q)).slice(0, q.limit ?? 1000);
+    }
+}

package/dist/assetstore/index.d.ts

@@ -1,5 +1,10 @@
 export * from './provider.js';
 export * from './localJsonl.js';
+export * from './foreignJsonlSource.js';
+export * from './unionReadStore.js';
+export * from './localAssetStoreSnapshot.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,10 @@
 export * from './provider.js';
 export * from './localJsonl.js';
+export * from './foreignJsonlSource.js';
+export * from './unionReadStore.js';
+export * from './localAssetStoreSnapshot.js';
+export * from './assetStoreHealth.js';
+export * from './assetSidecarRecovery.js';
 export * from './remoteStub.js';
 export * from './learningHistory.js';
 export * from './provenance.js';

package/dist/assetstore/learningHistory.js

@@ -1,4 +1,4 @@
-import { proofOfWork } from '../schema/proofOfWork.js';
+import { normalizeProofOfWork, proofOfWork } from '../schema/proofOfWork.js';
 import { proofIndicatesOutput } from '../algo/solidify.js';
 /** 扫该 gene 关联的 Capsule, 派生学习视图(只读, 不落库). */
 export async function aggregateLearningHistory(provider, geneId, recentN = 10) {
@@ -14,7 +14,7 @@ export async function aggregateLearningHistory(provider, geneId, recentN = 10) {
             // signal solidify uses to mark it `suppressed_observationally`) is INERT, not a real success. Counting it
             // would inflate successRate for a gene that only ever does nothing. Inert is neutral, not a failure: it is
             // excluded from BOTH sides of successRate, so it neither builds nor erodes confidence.
-            const proof = c.proof_of_work;
+            const proof = normalizeProofOfWork(c.proof_of_work);
             if (proofIndicatesOutput(proof))
                 success += 1;
             else
@@ -34,5 +34,5 @@ export async function aggregateLearningHistory(provider, geneId, recentN = 10) {
 }
 /** M3-5: 校验 agent 提交的 proof_of_work(zod). 返回规范化值或抛. */
 export function validateProofOfWork(input) {
-    return proofOfWork.parse(input);
+    return proofOfWork.parse(normalizeProofOfWork(input) ?? input);
 }

package/dist/assetstore/localAssetStoreSnapshot.d.ts

@@ -0,0 +1,51 @@
+import { type AssetRecord } from './provider.js';
+import type { ProvenanceRecord } from './provenance.js';
+export type CorruptLocalAssetStoreReason = 'invalid_utf8' | 'unterminated' | 'invalid_json' | 'invalid_record';
+export declare class CorruptLocalAssetStoreError extends Error {
+    readonly reason: CorruptLocalAssetStoreReason;
+    readonly file?: string | undefined;
+    readonly row?: number | undefined;
+    readonly code = "CORRUPT_LOCAL_ASSET_STORE";
+    constructor(reason: CorruptLocalAssetStoreReason, file?: string | undefined, row?: number | undefined);
+}
+export type LocalAssetStoreSnapshotLimitReason = 'file_bytes' | 'total_bytes' | 'records';
+export declare class LocalAssetStoreSnapshotLimitError extends Error {
+    readonly reason: LocalAssetStoreSnapshotLimitReason;
+    readonly file?: string | undefined;
+    readonly code = "LOCAL_ASSET_STORE_SNAPSHOT_LIMIT";
+    constructor(reason: LocalAssetStoreSnapshotLimitReason, file?: string | undefined);
+}
+export type LocalAssetStoreSnapshotChangeReason = 'changed' | 'lock_present' | 'invalid_snapshot';
+export declare class LocalAssetStoreSnapshotChangedError extends Error {
+    readonly reason: LocalAssetStoreSnapshotChangeReason;
+    readonly code = "LOCAL_ASSET_STORE_SNAPSHOT_CHANGED";
+    constructor(reason: LocalAssetStoreSnapshotChangeReason);
+}
+export interface ReadLocalAssetStoreSnapshotOptions {
+    maxFileBytes?: number;
+    maxTotalBytes?: number;
+    maxRecords?: number;
+}
+export interface ReadLocalAssetStoreSnapshotDeps {
+    /** Test seam invoked after every tracked file has been read but before the stable-read verification. */
+    beforeVerify?: () => void;
+}
+export interface LocalAssetStoreSnapshot {
+    readonly exists: boolean;
+    readonly fingerprint: string;
+    readonly assets: ReadonlyMap<string, AssetRecord>;
+    readonly provenance: ReadonlyMap<string, ProvenanceRecord>;
+    readonly stats: {
+        readonly bytes: number;
+        readonly assetRows: number;
+        readonly provenanceRows: number;
+        readonly uniqueAssets: number;
+    };
+}
+/**
+ * Read a bounded, strict target-store snapshot without creating the directory, a lock, or any other file.
+ * Writers are detected through the lock/root/file fingerprints; callers must revalidate before apply.
+ */
+export declare function readLocalAssetStoreSnapshot(baseDir: string, options?: ReadLocalAssetStoreSnapshotOptions, deps?: ReadLocalAssetStoreSnapshotDeps): LocalAssetStoreSnapshot;
+/** Fail closed when the target store changed between planning and apply. Performs reads only. */
+export declare function assertLocalAssetStoreSnapshotCurrent(snapshot: LocalAssetStoreSnapshot): void;

package/dist/assetstore/localAssetStoreSnapshot.js

@@ -0,0 +1,329 @@
+import { createHash } from 'node:crypto';
+import { lstatSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
+import { AssetStoreReadLimitError, readRegularBuffer, UnsafeAssetStorePathError, } from './assetStoreStorage.js';
+import { parseProvenanceRecord, CorruptAssetSidecarError, } from './assetSidecarRecords.js';
+import { frozenAssetRecordsEqual, FrozenAssetIdCollisionError } from './provider.js';
+const PROVENANCE_FILE = 'provenance.jsonl';
+const LOCK_FILE = '.assetstore.lock';
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+const DEFAULT_MAX_RECORDS = 100_000;
+export class CorruptLocalAssetStoreError extends Error {
+    reason;
+    file;
+    row;
+    code = 'CORRUPT_LOCAL_ASSET_STORE';
+    constructor(reason, file, row) {
+        super(`corrupt local asset store: ${reason}${file ? `/${file}` : ''}${row ? `/${row}` : ''}`);
+        this.reason = reason;
+        this.file = file;
+        this.row = row;
+        this.name = 'CorruptLocalAssetStoreError';
+    }
+}
+export class LocalAssetStoreSnapshotLimitError extends Error {
+    reason;
+    file;
+    code = 'LOCAL_ASSET_STORE_SNAPSHOT_LIMIT';
+    constructor(reason, file) {
+        super(`local asset store snapshot limit exceeded: ${reason}${file ? `/${file}` : ''}`);
+        this.reason = reason;
+        this.file = file;
+        this.name = 'LocalAssetStoreSnapshotLimitError';
+    }
+}
+export class LocalAssetStoreSnapshotChangedError extends Error {
+    reason;
+    code = 'LOCAL_ASSET_STORE_SNAPSHOT_CHANGED';
+    constructor(reason) {
+        super(`local asset store snapshot changed: ${reason}`);
+        this.reason = reason;
+        this.name = 'LocalAssetStoreSnapshotChangedError';
+    }
+}
+class SnapshotMap {
+    #values;
+    constructor(entries) {
+        this.#values = new Map(entries);
+        Object.freeze(this);
+    }
+    get size() { return this.#values.size; }
+    get(key) { return this.#values.get(key); }
+    has(key) { return this.#values.has(key); }
+    entries() { return this.#values.entries(); }
+    keys() { return this.#values.keys(); }
+    values() { return this.#values.values(); }
+    [Symbol.iterator]() { return this.#values[Symbol.iterator](); }
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.#values)
+            callbackfn.call(thisArg, value, key, this);
+    }
+}
+const metadataBySnapshot = new WeakMap();
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+function boundedPositiveInt(value, fallback) {
+    return value === undefined || !Number.isFinite(value)
+        ? fallback
+        : Math.max(1, Math.floor(value));
+}
+function statFingerprint(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+function directoryFingerprint(path) {
+    try {
+        const stat = lstatSync(path, { bigint: true });
+        if (stat.isSymbolicLink())
+            throw new UnsafeAssetStorePathError('base_directory', 'symlink');
+        if (!stat.isDirectory())
+            throw new UnsafeAssetStorePathError('base_directory', 'not_directory');
+        return statFingerprint(stat);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 'missing';
+        throw error;
+    }
+}
+function optionalFileFingerprint(path, role) {
+    try {
+        const stat = lstatSync(path, { bigint: true });
+        if (stat.isSymbolicLink())
+            throw new UnsafeAssetStorePathError(role, 'symlink');
+        if (!stat.isFile())
+            throw new UnsafeAssetStorePathError(role, 'not_regular_file');
+        return statFingerprint(stat);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return 'missing';
+        throw error;
+    }
+}
+function captureState(baseDir) {
+    const root = directoryFingerprint(baseDir);
+    const files = new Map();
+    if (root === 'missing') {
+        for (const kind of Object.keys(LOCAL_ASSET_FILES))
+            files.set(kind, 'missing');
+        files.set('provenance', 'missing');
+        return { root, lock: 'missing', files };
+    }
+    for (const [kind, file] of Object.entries(LOCAL_ASSET_FILES)) {
+        files.set(kind, optionalFileFingerprint(join(baseDir, file), 'asset_file'));
+    }
+    files.set('provenance', optionalFileFingerprint(join(baseDir, PROVENANCE_FILE), 'asset_file'));
+    return {
+        root,
+        lock: optionalFileFingerprint(join(baseDir, LOCK_FILE), 'lock_file'),
+        files,
+    };
+}
+function recaptureState(baseDir) {
+    try {
+        return captureState(baseDir);
+    }
+    catch (error) {
+        if (error instanceof UnsafeAssetStorePathError) {
+            throw new LocalAssetStoreSnapshotChangedError('changed');
+        }
+        throw error;
+    }
+}
+function statesEqual(left, right) {
+    if (left.root !== right.root || left.lock !== right.lock || left.files.size !== right.files.size)
+        return false;
+    for (const [file, fingerprint] of left.files) {
+        if (right.files.get(file) !== fingerprint)
+            return false;
+    }
+    return true;
+}
+function snapshotFingerprint(baseDir, state) {
+    const fileState = [...state.files.entries()];
+    const digest = createHash('sha256')
+        .update(JSON.stringify([baseDir, state.root, state.lock, fileState]))
+        .digest('hex');
+    return `sha256:${digest}`;
+}
+function decodeStrict(bytes, file) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new CorruptLocalAssetStoreError('invalid_utf8', file);
+    }
+}
+function assertTerminated(raw, file) {
+    if (raw.length > 0 && !raw.endsWith('\n'))
+        throw new CorruptLocalAssetStoreError('unterminated', file);
+}
+function immutableJson(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const item of Object.values(current)) {
+            if (item && typeof item === 'object')
+                pending.push(item);
+        }
+        Object.freeze(current);
+    }
+    return value;
+}
+function parseAssetFile(bytes, kind, file, assets, consumeRecord) {
+    const raw = decodeStrict(bytes, file);
+    assertTerminated(raw, file);
+    let row = 0;
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        row += 1;
+        consumeRecord();
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new CorruptLocalAssetStoreError('invalid_json', file, row);
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new CorruptLocalAssetStoreError('invalid_record', file, row);
+        }
+        const candidate = value;
+        if (candidate['type'] !== kind
+            || typeof candidate['asset_id'] !== 'string'
+            || !candidate['asset_id']
+            || candidate['asset_id'] !== candidate['asset_id'].trim()) {
+            throw new CorruptLocalAssetStoreError('invalid_record', file, row);
+        }
+        const record = candidate;
+        const existing = assets.get(record.asset_id);
+        if (existing && !frozenAssetRecordsEqual(existing, record)) {
+            throw new FrozenAssetIdCollisionError(record.asset_id);
+        }
+        if (!existing)
+            assets.set(record.asset_id, immutableJson(record));
+    }
+    return row;
+}
+function parseProvenanceFile(bytes, consumeRecord) {
+    const raw = decodeStrict(bytes, PROVENANCE_FILE);
+    const records = new Map();
+    let rows = 0;
+    if (raw.length > 0 && !raw.endsWith('\n')) {
+        throw new CorruptAssetSidecarError('provenance', 'unterminated');
+    }
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        rows += 1;
+        consumeRecord();
+        let record;
+        try {
+            record = parseProvenanceRecord(JSON.parse(line));
+        }
+        catch {
+            record = null;
+        }
+        if (!record)
+            throw new CorruptAssetSidecarError('provenance', 'invalid_row');
+        records.set(record.assetId, immutableJson(record));
+    }
+    return { records: new SnapshotMap(records), rows };
+}
+function readTrackedFile(path, file, maxFileBytes) {
+    try {
+        return readRegularBuffer(path, maxFileBytes) ?? Buffer.alloc(0);
+    }
+    catch (error) {
+        if (error instanceof AssetStoreReadLimitError) {
+            throw new LocalAssetStoreSnapshotLimitError('file_bytes', file);
+        }
+        if (isErrno(error, 'ENOENT') || isErrno(error, 'ELOOP') || isErrno(error, 'EISDIR')) {
+            throw new LocalAssetStoreSnapshotChangedError('changed');
+        }
+        if (error instanceof UnsafeAssetStorePathError && error.reason === 'path_changed') {
+            throw new LocalAssetStoreSnapshotChangedError('changed');
+        }
+        throw error;
+    }
+}
+/**
+ * Read a bounded, strict target-store snapshot without creating the directory, a lock, or any other file.
+ * Writers are detected through the lock/root/file fingerprints; callers must revalidate before apply.
+ */
+export function readLocalAssetStoreSnapshot(baseDir, options = {}, deps = {}) {
+    const resolvedBaseDir = resolve(baseDir);
+    const maxFileBytes = boundedPositiveInt(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES);
+    const maxTotalBytes = boundedPositiveInt(options.maxTotalBytes, DEFAULT_MAX_TOTAL_BYTES);
+    const maxRecords = boundedPositiveInt(options.maxRecords, DEFAULT_MAX_RECORDS);
+    const before = captureState(resolvedBaseDir);
+    if (before.lock !== 'missing')
+        throw new LocalAssetStoreSnapshotChangedError('lock_present');
+    const buffers = new Map();
+    let totalBytes = 0;
+    if (before.root !== 'missing') {
+        for (const [kind, file] of Object.entries(LOCAL_ASSET_FILES)) {
+            const bytes = readTrackedFile(join(resolvedBaseDir, file), file, maxFileBytes);
+            totalBytes += bytes.length;
+            if (totalBytes > maxTotalBytes)
+                throw new LocalAssetStoreSnapshotLimitError('total_bytes');
+            buffers.set(kind, bytes);
+        }
+        const provenanceBytes = readTrackedFile(join(resolvedBaseDir, PROVENANCE_FILE), PROVENANCE_FILE, maxFileBytes);
+        totalBytes += provenanceBytes.length;
+        if (totalBytes > maxTotalBytes)
+            throw new LocalAssetStoreSnapshotLimitError('total_bytes');
+        buffers.set('provenance', provenanceBytes);
+    }
+    deps.beforeVerify?.();
+    const after = recaptureState(resolvedBaseDir);
+    if (after.lock !== 'missing' || !statesEqual(before, after)) {
+        throw new LocalAssetStoreSnapshotChangedError(after.lock !== 'missing' ? 'lock_present' : 'changed');
+    }
+    let records = 0;
+    const consumeRecords = (count) => {
+        records += count;
+        if (records > maxRecords)
+            throw new LocalAssetStoreSnapshotLimitError('records');
+    };
+    const assets = new Map();
+    let assetRows = 0;
+    for (const [kind, file] of Object.entries(LOCAL_ASSET_FILES)) {
+        assetRows += parseAssetFile(buffers.get(kind) ?? Buffer.alloc(0), kind, file, assets, () => consumeRecords(1));
+    }
+    const parsedProvenance = parseProvenanceFile(buffers.get('provenance') ?? Buffer.alloc(0), () => consumeRecords(1));
+    const snapshot = Object.freeze({
+        exists: before.root !== 'missing',
+        fingerprint: snapshotFingerprint(resolvedBaseDir, before),
+        assets: new SnapshotMap(assets),
+        provenance: parsedProvenance.records,
+        stats: Object.freeze({
+            bytes: totalBytes,
+            assetRows,
+            provenanceRows: parsedProvenance.rows,
+            uniqueAssets: assets.size,
+        }),
+    });
+    metadataBySnapshot.set(snapshot, { baseDir: resolvedBaseDir, state: before });
+    return snapshot;
+}
+/** Fail closed when the target store changed between planning and apply. Performs reads only. */
+export function assertLocalAssetStoreSnapshotCurrent(snapshot) {
+    const metadata = metadataBySnapshot.get(snapshot);
+    if (!metadata)
+        throw new LocalAssetStoreSnapshotChangedError('invalid_snapshot');
+    const current = recaptureState(metadata.baseDir);
+    if (current.lock !== 'missing' || !statesEqual(metadata.state, current)) {
+        throw new LocalAssetStoreSnapshotChangedError(current.lock !== 'missing' ? 'lock_present' : 'changed');
+    }
+}

package/dist/assetstore/localJsonl.d.ts

@@ -1,4 +1,6 @@
-import { type AssetKind, type AssetRecord, type AssetStoreProvider, type PutResult, type SearchQuery } from './provider.js';
+import { type AssetKind, type AssetRecord, type AssetStoreProvider, type ConditionalPutOptions, type ConditionalPutResult, type PutResult, type SearchQuery } from './provider.js';
+/** Signal names a record advertises, across the four key spellings the pool uses. */
+export declare function signalsOf(a: AssetRecord): string[];
 /**
  * 本地 jsonl 资产库(M3-2, 移植 v1 src/gep/assetStore.js 单写锁).
  * 每 kind 一文件(genes/capsules/events.jsonl); append-only; O_EXCL 文件锁防并发写撕裂;
@@ -9,6 +11,7 @@ export declare class LocalJsonlProvider implements AssetStoreProvider {
     readonly baseDir: string;
     private readonly index;
     private readonly lockPath;
+    private readonly bundleJournalPath;
     private fileState;
     private loaded;
     constructor(baseDir: string);
@@ -18,14 +21,22 @@ export declare class LocalJsonlProvider implements AssetStoreProvider {
     private refreshUnderLock;
     private ensureFresh;
     private updateFileStateAfterWrite;
+    private readPendingBundle;
+    private recoverPendingBundleUnderLock;
+    private hasPendingBundle;
     put(asset: AssetRecord): Promise<PutResult>;
+    putConditional(asset: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
+    putBundle(assets: readonly AssetRecord[]): Promise<PutResult[]>;
     /**
      * 迁移专用(M8-2): 以**冻结 asset_id** 原样写入, 不经 normalizeForPut 重算/校验.
      * 仅 v1→v2 导入用(硬化 A6 存量冻结); 普通写一律走 put(). record 必须自带 asset_id.
      */
     putFrozen(record: AssetRecord): Promise<PutResult>;
+    putFrozenConditional(record: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
     get(assetId: string): Promise<AssetRecord | null>;
+    findByLogicalId(id: string, limit?: number, kind?: AssetKind): Promise<AssetRecord[]>;
     list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+    listAll(kind?: AssetKind): AssetRecord[];
     search(q: SearchQuery): Promise<AssetRecord[]>;
     /**
      * Opt-in log compaction: rewrite each kind's jsonl keeping ONE line per asset_id (last wins),