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

package/dist/assetstore/localJsonl.d.ts

@@ -1,4 +1,6 @@
 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,8 +21,12 @@ 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.
@@ -29,6 +36,7 @@ export declare class LocalJsonlProvider implements AssetStoreProvider {
     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),

package/dist/assetstore/localJsonl.js

@@ -1,6 +1,7 @@
+import { unlinkSync } 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 { appendUtf8Durable, assertAssetStoreDirectory, assertOptionalRegularFile, ensureAssetStoreDirectory, fsyncDirectoryBestEffort, readUtf8Regular, regularFileFingerprint, replaceUtf8Durable, } from './assetStoreStorage.js';
 import { LOCAL_ASSET_FILES } from './assetStoreLayout.js';
 import { FrozenAssetIdCollisionError, frozenAssetRecordsEqual, normalizeForPut, } from './provider.js';
 function resultLogicalId(logicalId) {
@@ -8,7 +9,12 @@ function resultLogicalId(logicalId) {
         ? logicalId
         : undefined;
 }
-function signalsOf(a) {
+const BUNDLE_JOURNAL_FILE = '.assetstore-bundle.json';
+const BUNDLE_JOURNAL_SCHEMA = 'evolver.assetstore-bundle.v1';
+const MAX_BUNDLE_ASSETS = 64;
+const MAX_BUNDLE_JOURNAL_BYTES = 4 * 1024 * 1024;
+/** Signal names a record advertises, across the four key spellings the pool uses. */
+export function signalsOf(a) {
     const out = [];
     for (const key of ['signals_match', 'signals', 'trigger', 'trigger_signals']) {
         const v = a[key];
@@ -29,6 +35,7 @@ export class LocalJsonlProvider {
     baseDir;
     index = new Map();
     lockPath;
+    bundleJournalPath;
     fileState = new Map();
     loaded = false;
     // `baseDir` is public-readonly so callers that inject a store (e.g. the CLI under test) can co-locate sidecars
@@ -37,6 +44,7 @@ export class LocalJsonlProvider {
         this.baseDir = baseDir;
         ensureAssetStoreDirectory(baseDir);
         this.lockPath = join(baseDir, '.assetstore.lock');
+        this.bundleJournalPath = join(baseDir, BUNDLE_JOURNAL_FILE);
     }
     captureFileState() {
         assertAssetStoreDirectory(this.baseDir);
@@ -86,11 +94,12 @@ export class LocalJsonlProvider {
     }
     ensureFresh() {
         const state = this.captureFileState();
-        if (!this.stateChanged(state))
+        if (!this.hasPendingBundle() && !this.stateChanged(state))
             return;
         assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
+            this.recoverPendingBundleUnderLock();
             this.refreshUnderLock();
         }
         finally {
@@ -101,6 +110,63 @@ export class LocalJsonlProvider {
         this.fileState = this.captureFileState();
         this.loaded = true;
     }
+    readPendingBundle() {
+        if (assertOptionalRegularFile(this.bundleJournalPath, 'temp_file') === null)
+            return undefined;
+        const raw = readUtf8Regular(this.bundleJournalPath, MAX_BUNDLE_JOURNAL_BYTES);
+        if (raw === null)
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error('asset store bundle journal is malformed');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('asset store bundle journal is malformed');
+        }
+        const journal = parsed;
+        const assets = journal['assets'];
+        if (journal['schema'] !== BUNDLE_JOURNAL_SCHEMA || !Array.isArray(assets) || assets.length === 0 || assets.length > MAX_BUNDLE_ASSETS) {
+            throw new Error('asset store bundle journal is invalid');
+        }
+        return assets.map((asset) => {
+            if (!asset || typeof asset !== 'object' || Array.isArray(asset))
+                throw new Error('asset store bundle journal is invalid');
+            const record = asset;
+            if (typeof record.type !== 'string' || !Object.prototype.hasOwnProperty.call(LOCAL_ASSET_FILES, record.type)
+                || typeof record.asset_id !== 'string' || record.asset_id.length === 0) {
+                throw new Error('asset store bundle journal is invalid');
+            }
+            return record;
+        });
+    }
+    recoverPendingBundleUnderLock() {
+        const pending = this.readPendingBundle();
+        if (!pending)
+            return;
+        this.refreshUnderLock();
+        for (const pendingRecord of pending) {
+            const { record } = normalizeForPut(pendingRecord);
+            if (record.asset_id !== pendingRecord.asset_id)
+                throw new Error('asset store bundle journal asset_id mismatch');
+            const existing = this.index.get(record.asset_id);
+            if (existing) {
+                if (!frozenAssetRecordsEqual(existing, record))
+                    throw new FrozenAssetIdCollisionError(record.asset_id);
+                continue;
+            }
+            appendUtf8Durable(join(this.baseDir, LOCAL_ASSET_FILES[record.type]), `${JSON.stringify(record)}\n`);
+            this.index.set(record.asset_id, record);
+        }
+        unlinkSync(this.bundleJournalPath);
+        fsyncDirectoryBestEffort(this.baseDir);
+        this.updateFileStateAfterWrite();
+    }
+    hasPendingBundle() {
+        return assertOptionalRegularFile(this.bundleJournalPath, 'temp_file') !== null;
+    }
     async put(asset) {
         return this.putConditional(asset, { allowLogicalCollision: true });
     }
@@ -112,6 +178,7 @@ export class LocalJsonlProvider {
         assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
+            this.recoverPendingBundleUnderLock();
             // Refresh under the shared lock so another process cannot append between reload and dedupe.
             this.refreshUnderLock();
             const existing = this.index.get(record.asset_id);
@@ -159,6 +226,59 @@ export class LocalJsonlProvider {
             } : {}),
         };
     }
+    async putBundle(assets) {
+        if (assets.length === 0)
+            return [];
+        if (assets.length > MAX_BUNDLE_ASSETS)
+            throw new Error('asset store bundle is too large');
+        const normalized = assets.map((asset) => normalizeForPut(asset));
+        const seen = new Map();
+        for (const normalizedRecord of normalized) {
+            const { record } = normalizedRecord;
+            const previous = seen.get(record.asset_id);
+            if (previous && !frozenAssetRecordsEqual(previous.record, record))
+                throw new FrozenAssetIdCollisionError(record.asset_id);
+            if (!previous)
+                seen.set(record.asset_id, normalizedRecord);
+        }
+        const results = [];
+        assertOptionalRegularFile(this.lockPath, 'lock_file');
+        acquireLock(this.lockPath);
+        try {
+            this.recoverPendingBundleUnderLock();
+            this.refreshUnderLock();
+            const pending = [];
+            for (const { record, verified } of seen.values()) {
+                const existing = this.index.get(record.asset_id);
+                if (existing) {
+                    if (!frozenAssetRecordsEqual(existing, record))
+                        throw new FrozenAssetIdCollisionError(record.asset_id);
+                    results.push({ asset_id: record.asset_id, stored: false, verified });
+                    continue;
+                }
+                pending.push(record);
+                results.push({ asset_id: record.asset_id, stored: true, verified });
+            }
+            if (pending.length === 0)
+                return results;
+            const journal = `${JSON.stringify({ schema: BUNDLE_JOURNAL_SCHEMA, assets: pending })}\n`;
+            if (Buffer.byteLength(journal, 'utf8') > MAX_BUNDLE_JOURNAL_BYTES) {
+                throw new Error('asset store bundle is too large');
+            }
+            replaceUtf8Durable(this.bundleJournalPath, journal);
+            for (const record of pending) {
+                appendUtf8Durable(join(this.baseDir, LOCAL_ASSET_FILES[record.type]), `${JSON.stringify(record)}\n`);
+                this.index.set(record.asset_id, record);
+            }
+            unlinkSync(this.bundleJournalPath);
+            fsyncDirectoryBestEffort(this.baseDir);
+            this.updateFileStateAfterWrite();
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+        return results;
+    }
     /**
      * 迁移专用(M8-2): 以**冻结 asset_id** 原样写入, 不经 normalizeForPut 重算/校验.
      * 仅 v1→v2 导入用(硬化 A6 存量冻结); 普通写一律走 put(). record 必须自带 asset_id.
@@ -175,6 +295,7 @@ export class LocalJsonlProvider {
         assertOptionalRegularFile(this.lockPath, 'lock_file');
         acquireLock(this.lockPath);
         try {
+            this.recoverPendingBundleUnderLock();
             this.refreshUnderLock();
             const existing = this.index.get(record.asset_id);
             if (existing) {
@@ -246,6 +367,10 @@ export class LocalJsonlProvider {
         }
         return out;
     }
+    listAll(kind) {
+        this.ensureFresh();
+        return [...this.index.values()].filter((record) => kind === undefined || record.type === kind);
+    }
     async search(q) {
         this.ensureFresh();
         const out = [];

package/dist/assetstore/provenance.d.ts

@@ -1,6 +1,7 @@
 import { type AssetStoreProvider, type AssetRecord, type ConditionalPutOptions, type ConditionalPutResult, type PutResult } from './provider.js';
 export type ProvenanceSource = 'local' | 'migrated' | 'hub';
 export type ProvenanceDecision = 'promoted' | 'revoked';
+export declare const UNVERIFIED_V1_IMPORT_REASON = "unverified_v1_import";
 export interface ProvenanceRecord {
     assetId: string;
     source: ProvenanceSource;
@@ -11,13 +12,47 @@ export interface ProvenanceRecord {
     /** Legacy promotion actor field kept for existing sidecar readers. */
     promotedBy?: string;
     reason?: string;
-    /** Canonical content id of the exact hash-mismatched body accepted by an unverified Hub ingest. */
+    /** Canonical content id of the exact hash-mismatched body accepted by a supported unverified ingest. */
     frozenContentId?: string;
 }
 export interface ProvenanceTrustChange {
     changed: boolean;
     record: ProvenanceRecord;
 }
+export type UnverifiedIngestDisposition = {
+    readonly status: 'create';
+    readonly assetId: string;
+    readonly frozenContentId: string;
+    readonly provenanceAction: 'stage_and_finalize';
+} | {
+    readonly status: 'already_bound';
+    readonly assetId: string;
+    readonly frozenContentId: string;
+    readonly provenanceAction: 'finalize' | 'none';
+} | {
+    readonly status: 'preserve_trust';
+    readonly assetId: string;
+    readonly frozenContentId: string;
+    readonly provenanceAction: 'none';
+} | {
+    readonly status: 'collision';
+    readonly assetId: string;
+    readonly frozenContentId: string;
+    readonly collision: 'asset' | 'provenance';
+    readonly provenanceAction: 'none';
+};
+/**
+ * Resolve the exact no-I/O disposition used by {@link ingestUnverified}. Callers may inspect a read-only
+ * target snapshot during migration planning, then apply through ingestUnverified without duplicating its
+ * trust and collision rules.
+ */
+export declare function planUnverifiedIngest(record: AssetRecord, existing: AssetRecord | null, currentProvenance: ProvenanceRecord | null, reason: string, source?: ProvenanceSource): UnverifiedIngestDisposition;
+/**
+ * A frozen hash mismatch is benign only while its latest provenance record is an undecided, content-bound
+ * waiver created by a supported ingest path. Keep the storage/health classification centralized; downstream
+ * reuse and sync apply their own stricter allowlists before an unverified asset may leave quarantine.
+ */
+export declare function isActiveUnverifiedProvenance(record: ProvenanceRecord | null | undefined, frozenContentId: string | null | undefined): boolean;
 export declare class ProvenanceWritePendingError extends Error {
     readonly assetId: string;
     readonly code = "PROVENANCE_WRITE_PENDING";
@@ -25,8 +60,8 @@ export declare class ProvenanceWritePendingError extends Error {
 }
 /**
  * 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
- * write here; the sole untrusted source — hub ingestion — ALWAYS marks via {@link ingestUntrusted}/mark.
+ * record = trusted: verified local writers (cycleEngine self-produce and self-consistent v1 migration rows)
+ * do not write here. Every untrusted or hash-mismatched ingest path MUST mark before persistence.
  */
 export declare class ProvenanceStore {
     private readonly now;

package/dist/assetstore/provenance.js

@@ -8,6 +8,98 @@ import { assertCapsuleGeneBinding, FrozenAssetIdCollisionError, InvalidFrozenPut
 import { appendUtf8Durable, assertAssetStoreDirectory, ensureAssetStoreDirectory, readUtf8Regular, regularFileFingerprint, truncateUtf8SuffixDurable, withAssetStoreLock, } from './assetStoreStorage.js';
 import { assertTrustSidecarHealthy, parseProvenanceRecord, parseSidecarJsonl, } from './assetSidecarRecords.js';
 import { computeAssetId } from '../wire/index.js';
+export const UNVERIFIED_V1_IMPORT_REASON = 'unverified_v1_import';
+const UNVERIFIED_WRITE_PENDING_REASON = 'unverified_hub_write_pending';
+function unverifiedStageAction(current, source, frozenContentId) {
+    if (!current)
+        return 'append';
+    const isUndecidedUntrusted = current.trusted === false
+        && current.decision === undefined
+        && current.decidedBy === undefined
+        && current.promotedBy === undefined;
+    if (isActiveUnverifiedProvenance(current, frozenContentId))
+        return 'append';
+    if (isUndecidedUntrusted && current.source === source && current.reason === undefined)
+        return 'append';
+    if (isUndecidedUntrusted
+        && current.source === source
+        && current.reason === UNVERIFIED_WRITE_PENDING_REASON
+        && current.frozenContentId === frozenContentId)
+        return 'reuse_pending';
+    return 'blocked';
+}
+function unverifiedFinalizeAction(current, source, reason, frozenContentId) {
+    if (!current)
+        return 'append';
+    if (current.trusted === true
+        || current.decision !== undefined
+        || current.decidedBy !== undefined
+        || current.promotedBy !== undefined)
+        return 'preserve';
+    const sameWaiver = current.source === source && current.trusted === false && current.reason === reason;
+    if (sameWaiver && current.frozenContentId === frozenContentId)
+        return 'already_bound';
+    if (!sameWaiver && (current.reason !== UNVERIFIED_WRITE_PENDING_REASON
+        || (current.frozenContentId !== undefined && current.frozenContentId !== frozenContentId)))
+        return 'preserve';
+    return 'append';
+}
+/**
+ * Resolve the exact no-I/O disposition used by {@link ingestUnverified}. Callers may inspect a read-only
+ * target snapshot during migration planning, then apply through ingestUnverified without duplicating its
+ * trust and collision rules.
+ */
+export function planUnverifiedIngest(record, existing, currentProvenance, reason, source = 'hub') {
+    assertCapsuleGeneBinding(record);
+    const frozenContentId = computeAssetId(record);
+    if (!frozenContentId)
+        throw new Error('failed to compute frozen content id');
+    const base = { assetId: record.asset_id, frozenContentId };
+    if (currentProvenance && currentProvenance.assetId !== record.asset_id) {
+        return { ...base, status: 'collision', collision: 'provenance', provenanceAction: 'none' };
+    }
+    if (existing) {
+        if (!frozenAssetRecordsEqual(existing, record)) {
+            return { ...base, status: 'collision', collision: 'asset', provenanceAction: 'none' };
+        }
+        const finalize = unverifiedFinalizeAction(currentProvenance, source, reason, frozenContentId);
+        if (finalize === 'preserve') {
+            return { ...base, status: 'preserve_trust', provenanceAction: 'none' };
+        }
+        return {
+            ...base,
+            status: 'already_bound',
+            provenanceAction: finalize === 'append' ? 'finalize' : 'none',
+        };
+    }
+    if (unverifiedStageAction(currentProvenance, source, frozenContentId) === 'blocked') {
+        return { ...base, status: 'collision', collision: 'provenance', provenanceAction: 'none' };
+    }
+    return { ...base, status: 'create', provenanceAction: 'stage_and_finalize' };
+}
+/**
+ * A frozen hash mismatch is benign only while its latest provenance record is an undecided, content-bound
+ * waiver created by a supported ingest path. Keep the storage/health classification centralized; downstream
+ * reuse and sync apply their own stricter allowlists before an unverified asset may leave quarantine.
+ */
+export function isActiveUnverifiedProvenance(record, frozenContentId) {
+    if (!record
+        || !frozenContentId
+        || record.trusted !== false
+        || record.decision !== undefined
+        || record.decidedBy !== undefined
+        || record.promotedBy !== undefined
+        || record.frozenContentId !== frozenContentId)
+        return false;
+    // V1 input is local legacy data rather than a network-issued identifier. Never let a malformed declared
+    // identity become healthy merely because the shallow wire gate does not enforce the schema's asset_id regex.
+    if (record.reason === UNVERIFIED_V1_IMPORT_REASON
+        && !/^sha256:[0-9a-f]{64}$/.test(record.assetId))
+        return false;
+    return (record.source === 'hub'
+        && (record.reason === 'unverified_hub_rewrite' || record.reason === 'unverified_hub_synthesized')) || (record.source === 'migrated'
+        && (record.reason === 'unverified_gepx_import' || record.reason === UNVERIFIED_V1_IMPORT_REASON));
+}
 export class ProvenanceWritePendingError extends Error {
     assetId;
     code = 'PROVENANCE_WRITE_PENDING';
@@ -22,8 +114,8 @@ function immutableRecord(record) {
 }
 /**
  * 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
- * write here; the sole untrusted source — hub ingestion — ALWAYS marks via {@link ingestUntrusted}/mark.
+ * record = trusted: verified local writers (cycleEngine self-produce and self-consistent v1 migration rows)
+ * do not write here. Every untrusted or hash-mismatched ingest path MUST mark before persistence.
  */
 export class ProvenanceStore {
     now;
@@ -127,26 +219,15 @@ export class ProvenanceStore {
         return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
             const current = this.index.get(assetId);
-            const isUndecidedUntrusted = current?.trusted === false
-                && current.decision === undefined
-                && current.decidedBy === undefined
-                && current.promotedBy === undefined;
-            const isWaiver = isUndecidedUntrusted
-                && current.frozenContentId === frozenContentId
-                && ((current.source === 'hub'
-                    && (current.reason === 'unverified_hub_rewrite' || current.reason === 'unverified_hub_synthesized'))
-                    || (current.source === 'migrated' && current.reason === 'unverified_gepx_import'));
-            const isStaleIngestMarker = isUndecidedUntrusted
-                && current.source === source
-                && current.reason === undefined;
-            if (current && !isWaiver && !isStaleIngestMarker)
+            const action = unverifiedStageAction(current, source, frozenContentId);
+            if (current && action !== 'append')
                 return { record: current, appended: false };
             return {
                 record: this.appendUnderLock({
                     assetId,
                     source,
                     trusted: false,
-                    reason: 'unverified_hub_write_pending',
+                    reason: UNVERIFIED_WRITE_PENDING_REASON,
                     frozenContentId,
                     at: new Date(this.now()).toISOString(),
                 }),
@@ -160,20 +241,9 @@ export class ProvenanceStore {
         return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
             const current = this.index.get(assetId);
-            if (current) {
-                if (current.trusted === true
-                    || current.decision !== undefined
-                    || current.decidedBy !== undefined
-                    || current.promotedBy !== undefined)
-                    return current;
-                const sameWaiver = current.source === source && current.trusted === false && current.reason === reason;
-                if (sameWaiver && current.frozenContentId === frozenContentId)
-                    return current;
-                if (!sameWaiver && (current.reason !== 'unverified_hub_write_pending'
-                    || (current.frozenContentId !== undefined
-                        && current.frozenContentId !== frozenContentId)))
-                    return current;
-            }
+            const action = unverifiedFinalizeAction(current, source, reason, frozenContentId);
+            if (current && action !== 'append')
+                return current;
             return this.appendUnderLock({
                 assetId,
                 source,
@@ -221,7 +291,7 @@ export class ProvenanceStore {
             if (trusted
                 && current?.trusted === false
                 && current.decision === undefined
-                && current.reason === 'unverified_hub_write_pending') {
+                && current.reason === UNVERIFIED_WRITE_PENDING_REASON) {
                 throw new ProvenanceWritePendingError(assetId);
             }
             const decision = trusted ? 'promoted' : 'revoked';
@@ -300,13 +370,7 @@ export async function ingestUnverified(store, prov, record, reason, source = 'hu
     // the asset stays untrusted and health still reports its hash mismatch instead of treating it as #570.
     const staged = prov.stageUnverifiedWrite(record.asset_id, source, frozenContentId);
     // A missing body with an explicit trust decision cannot be replaced without reopening a promotion race.
-    if (staged.source !== source
-        || staged.trusted
-        || staged.decision !== undefined
-        || staged.decidedBy !== undefined
-        || staged.promotedBy !== undefined
-        || staged.reason !== 'unverified_hub_write_pending'
-        || staged.frozenContentId !== frozenContentId) {
+    if (planUnverifiedIngest(record, null, staged, reason, source).status !== 'create') {
         throw new FrozenAssetIdCollisionError(record.asset_id);
     }
     const result = validateFrozenPutResult(await store.putFrozen(record), record.asset_id);
@@ -334,13 +398,7 @@ export async function ingestUnverifiedConditional(store, prov, record, reason, o
         return { asset_id: record.asset_id, stored: false, verified: false, status: 'already_exists' };
     }
     const stage = prov.stageUnverifiedWriteTracked(record.asset_id, source, frozenContentId);
-    if (stage.record.source !== source
-        || stage.record.trusted
-        || stage.record.decision !== undefined
-        || stage.record.decidedBy !== undefined
-        || stage.record.promotedBy !== undefined
-        || stage.record.reason !== 'unverified_hub_write_pending'
-        || stage.record.frozenContentId !== frozenContentId) {
+    if (planUnverifiedIngest(record, null, stage.record, reason, source).status !== 'create') {
         throw new FrozenAssetIdCollisionError(record.asset_id);
     }
     const result = validateConditionalPutResult(await store.putFrozenConditional(record, options), record.asset_id, options);

package/dist/assetstore/provider.d.ts

@@ -55,6 +55,10 @@ export interface SearchQuery {
  */
 export interface AssetStoreProvider {
     put(asset: AssetRecord): Promise<PutResult>;
+    /** 可选的可崩溃恢复批量写入，用于保持相关资产（例如 Gene/Capsule 对）的一致性。
+     * 需要持久化相关资产组的调用方必须先确认此能力存在，不得退回顺序单条写入。
+     * 返回结果按唯一 asset_id 各一条（同 bundle 内重复条目按幂等去重），调用方必须按 asset_id 键控消费结果，不得按索引与输入条目对齐。 */
+    putBundle?(assets: readonly AssetRecord[]): Promise<PutResult[]>;
     /** Optional atomic capability; use supportsAtomicConditionalPut() before calling through this interface. */
     putConditional?(asset: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
     get(assetId: string): Promise<AssetRecord | null>;

package/dist/assetstore/reviewFilter.d.ts

@@ -1,5 +1,5 @@
 import type { AssetStoreProvider, AssetRecord } from './provider.js';
-import { ReviewLedger } from './reviewLedger.js';
+import { ReviewLedger, type ReviewRecord } from './reviewLedger.js';
 import { ProvenanceStore } from './provenance.js';
 /**
  * The ReviewLedger CO-LOCATED with a store — its quarantine/approve records live in the SAME dir as the genes.
@@ -17,4 +17,22 @@ export declare function provenanceStoreForStore(store: AssetStoreProvider): Prov
  * quarantined or rejected draft is withheld. A gene with NO provenance record is trusted; hub-ingested genes are
  * withheld until promotion. This mirrors candidateAssembly's trust-first + review-first filters.
  */
+/**
+ * Authoritative pending-review queue: quarantined ledger records, oldest first.
+ * Callers that display a human queue MUST start here instead of `store.list`, or a
+ * draft sitting past the newest-N cutoff is invisible even though it is still blocked.
+ */
+export declare function pendingReviewRecords(review: ReviewLedger, excludeAssetIds?: ReadonlySet<string>): ReviewRecord[];
+/**
+ * Pending Gene queue with the asset store as the type/existence authority.
+ *
+ * ReviewLedger is intentionally generic because the same sidecar also records
+ * AntiGene decisions. A quarantined row can also outlive its asset after a
+ * repair or a truncated migration. Human Gene queues must therefore resolve
+ * every row through the provider instead of treating the ledger alone as a
+ * complete inventory. The lookups are deliberately sequential so a malformed
+ * or unexpectedly large ledger cannot fan out an unbounded request burst to a
+ * remote provider.
+ */
+export declare function pendingGeneReviewRecords(store: AssetStoreProvider, review: ReviewLedger): Promise<ReviewRecord[]>;
 export declare function listApprovedGenes(store: AssetStoreProvider, review: ReviewLedger, maxGenes: number, provenance?: ProvenanceStore): Promise<AssetRecord[]>;

package/dist/assetstore/reviewFilter.js

@@ -28,6 +28,42 @@ export function provenanceStoreForStore(store) {
  * quarantined or rejected draft is withheld. A gene with NO provenance record is trusted; hub-ingested genes are
  * withheld until promotion. This mirrors candidateAssembly's trust-first + review-first filters.
  */
+/**
+ * Authoritative pending-review queue: quarantined ledger records, oldest first.
+ * Callers that display a human queue MUST start here instead of `store.list`, or a
+ * draft sitting past the newest-N cutoff is invisible even though it is still blocked.
+ */
+export function pendingReviewRecords(review, excludeAssetIds = new Set()) {
+    return review.records()
+        .filter((record) => record.state === 'quarantined' && !excludeAssetIds.has(record.assetId))
+        .sort((a, b) => a.at.localeCompare(b.at));
+}
+/**
+ * Pending Gene queue with the asset store as the type/existence authority.
+ *
+ * ReviewLedger is intentionally generic because the same sidecar also records
+ * AntiGene decisions. A quarantined row can also outlive its asset after a
+ * repair or a truncated migration. Human Gene queues must therefore resolve
+ * every row through the provider instead of treating the ledger alone as a
+ * complete inventory. The lookups are deliberately sequential so a malformed
+ * or unexpectedly large ledger cannot fan out an unbounded request burst to a
+ * remote provider.
+ */
+export async function pendingGeneReviewRecords(store, review) {
+    const pending = pendingReviewRecords(review);
+    // LocalJsonlProvider 可直接使用内存索引精确回答，避免 sidecar 变大后逐行等待查询。
+    if (store instanceof LocalJsonlProvider) {
+        const geneIds = new Set(store.listAll('Gene').map((asset) => asset.asset_id));
+        return pending.filter((record) => geneIds.has(record.assetId));
+    }
+    const genes = [];
+    for (const record of pending) {
+        const asset = await store.get(record.assetId);
+        if (asset?.type === 'Gene')
+            genes.push(record);
+    }
+    return genes;
+}
 export async function listApprovedGenes(store, review, maxGenes, provenance = provenanceStoreForStore(store)) {
     const all = await store.list('Gene', GENE_SCAN_LIMIT);
     const trust = provenance.snapshot();

package/dist/assetstore/unionReadStore.d.ts

@@ -0,0 +1,25 @@
+import type { AssetKind, AssetRecord, AssetStoreProvider, ConditionalPutOptions, ConditionalPutResult, PutResult, SearchQuery } from './provider.js';
+export declare class UnionReadStore implements AssetStoreProvider {
+    private readonly primary;
+    private readonly readOnly;
+    readonly putConditional?: (asset: AssetRecord, options?: ConditionalPutOptions) => Promise<ConditionalPutResult>;
+    readonly putBundle?: (assets: readonly AssetRecord[]) => Promise<PutResult[]>;
+    readonly putFrozen?: (record: AssetRecord) => Promise<PutResult>;
+    readonly putFrozenConditional?: (record: AssetRecord, options?: ConditionalPutOptions) => Promise<ConditionalPutResult>;
+    readonly findByLogicalId?: (id: string, limit?: number, kind?: AssetKind) => Promise<AssetRecord[]>;
+    /**
+     * @param primary the writable pool this engine owns; every mutation lands here
+     * @param readOnly additional pools to read, in precedence order after `primary`
+     */
+    constructor(primary: AssetStoreProvider, readOnly: readonly AssetStoreProvider[]);
+    private get sources();
+    /**
+     * Merge one read across every source: deduplicate by asset_id with earlier sources winning, then fill
+     * the result by {@link interleave} so every source gets a fair share of the cap.
+     */
+    private merged;
+    put(asset: AssetRecord): Promise<PutResult>;
+    get(assetId: string): Promise<AssetRecord | null>;
+    list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+    search(q: SearchQuery): Promise<AssetRecord[]>;
+}