@evomap/evolver-core 2.0.0-beta.0

package/dist/assetstore/index.js

@@ -0,0 +1,8 @@
+export * from './provider.js';
+export * from './localJsonl.js';
+export * from './remoteStub.js';
+export * from './learningHistory.js';
+export * from './provenance.js';
+export * from './reviewLedger.js';
+export * from './reviewFilter.js';
+export * from './pendingSignals.js';

package/dist/assetstore/learningHistory.d.ts

@@ -0,0 +1,25 @@
+import { type ProofOfWork } from '../schema/proofOfWork.js';
+import type { AssetStoreProvider } from './provider.js';
+/**
+ * Gene 侧 learning_history 聚合视图(M3-4 后半 / M3-6). 批注#28: 不再把 learning_history 内联进 Gene 资产
+ * (会改 asset_id 不稳), 而是按需从 Capsule 集合聚合派生.
+ */
+export interface GeneLearningView {
+    geneId: string;
+    total: number;
+    success: number;
+    failed: number;
+    /**
+     * Inert (zero-work) capsules: `success` outcome with no measurable produced value (#195). Tallied apart from
+     * real `success` so a do-nothing gene's successRate is not inflated. Optional for back-compat with hand-built
+     * views (absent ⇒ 0). When derived here, success + failed + inert === total.
+     */
+    inert?: number;
+    successRate: number;
+    avgScore: number;
+    recentCapsuleIds: string[];
+}
+/** 扫该 gene 关联的 Capsule, 派生学习视图(只读, 不落库). */
+export declare function aggregateLearningHistory(provider: AssetStoreProvider, geneId: string, recentN?: number): Promise<GeneLearningView>;
+/** M3-5: 校验 agent 提交的 proof_of_work(zod). 返回规范化值或抛. */
+export declare function validateProofOfWork(input: unknown): ProofOfWork;

package/dist/assetstore/learningHistory.js

@@ -0,0 +1,38 @@
+import { proofOfWork } from '../schema/proofOfWork.js';
+import { proofIndicatesOutput } from '../algo/solidify.js';
+/** 扫该 gene 关联的 Capsule, 派生学习视图(只读, 不落库). */
+export async function aggregateLearningHistory(provider, geneId, recentN = 10) {
+    const caps = await provider.search({ kind: 'Capsule', gene: geneId, limit: 10_000 });
+    let success = 0, failed = 0, inert = 0, scoreSum = 0;
+    for (const c of caps) {
+        const outcome = c.outcome;
+        if (outcome?.status === 'failed') {
+            failed += 1;
+        }
+        else if (outcome?.status === 'success') {
+            // #195: a success that produced no measurable value (no ProofOfWork output — the same `producedValue`
+            // 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;
+            if (proofIndicatesOutput(proof))
+                success += 1;
+            else
+                inert += 1;
+        }
+        if (typeof outcome?.score === 'number')
+            scoreSum += outcome.score;
+    }
+    const total = caps.length;
+    const decisive = success + failed; // inert excluded from the success-rate denominator (neutral)
+    return {
+        geneId, total, success, failed, inert,
+        successRate: decisive > 0 ? success / decisive : 0,
+        avgScore: total > 0 ? scoreSum / total : 0,
+        recentCapsuleIds: caps.slice(-recentN).map((c) => c.asset_id),
+    };
+}
+/** M3-5: 校验 agent 提交的 proof_of_work(zod). 返回规范化值或抛. */
+export function validateProofOfWork(input) {
+    return proofOfWork.parse(input);
+}

package/dist/assetstore/localJsonl.d.ts

@@ -0,0 +1,34 @@
+import { type AssetKind, type AssetRecord, type AssetStoreProvider, type PutResult, type SearchQuery } from './provider.js';
+/**
+ * 本地 jsonl 资产库(M3-2, 移植 v1 src/gep/assetStore.js 单写锁).
+ * 每 kind 一文件(genes/capsules/events.jsonl); append-only; O_EXCL 文件锁防并发写撕裂;
+ * 内存索引(asset_id→record)供 get/search; 同 asset_id 去重(内容寻址天然幂等).
+ */
+export declare class LocalJsonlProvider implements AssetStoreProvider {
+    readonly baseDir: string;
+    private readonly index;
+    private readonly lockPath;
+    private loaded;
+    constructor(baseDir: string);
+    private ensureLoaded;
+    put(asset: AssetRecord): Promise<PutResult>;
+    /**
+     * 迁移专用(M8-2): 以**冻结 asset_id** 原样写入, 不经 normalizeForPut 重算/校验.
+     * 仅 v1→v2 导入用(硬化 A6 存量冻结); 普通写一律走 put(). record 必须自带 asset_id.
+     */
+    putFrozen(record: AssetRecord): Promise<PutResult>;
+    get(assetId: string): Promise<AssetRecord | null>;
+    list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+    search(q: SearchQuery): Promise<AssetRecord[]>;
+    /**
+     * Opt-in log compaction: rewrite each kind's jsonl keeping ONE line per asset_id (last wins),
+     * dropping duplicate/corrupt lines that accumulate across processes/restarts/migration. Lossless
+     * because the store is content-addressed (one record per asset_id is all there ever was). This does
+     * NOT evict assets — every unique asset is knowledge that stays. Atomic per file (temp + rename) under
+     * the write lock. Returns kept/removed line counts.
+     */
+    compact(): Promise<{
+        kept: number;
+        removed: number;
+    }>;
+}

package/dist/assetstore/localJsonl.js

@@ -0,0 +1,182 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { normalizeForPut, } from './provider.js';
+const FILES = { Gene: 'genes.jsonl', Capsule: 'capsules.jsonl', EvolutionEvent: 'events.jsonl', AntiGene: 'anti-genes.jsonl' };
+function signalsOf(a) {
+    const out = [];
+    for (const key of ['signals_match', 'signals', 'trigger', 'trigger_signals']) {
+        const v = a[key];
+        if (Array.isArray(v))
+            for (const s of v)
+                if (typeof s === 'string')
+                    out.push(s);
+    }
+    return out;
+}
+/**
+ * 本地 jsonl 资产库(M3-2, 移植 v1 src/gep/assetStore.js 单写锁).
+ * 每 kind 一文件(genes/capsules/events.jsonl); append-only; O_EXCL 文件锁防并发写撕裂;
+ * 内存索引(asset_id→record)供 get/search; 同 asset_id 去重(内容寻址天然幂等).
+ */
+export class LocalJsonlProvider {
+    baseDir;
+    index = new Map();
+    lockPath;
+    loaded = false;
+    // `baseDir` is public-readonly so callers that inject a store (e.g. the CLI under test) can co-locate sidecars
+    // — the ReviewLedger/ProvenanceStore — in the SAME directory, instead of defaulting to the real ~/.evomap.
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+        mkdirSync(baseDir, { recursive: true });
+        this.lockPath = join(baseDir, '.assetstore.lock');
+    }
+    ensureLoaded() {
+        if (this.loaded)
+            return;
+        for (const file of Object.values(FILES)) {
+            const p = join(this.baseDir, file);
+            if (!existsSync(p))
+                continue;
+            for (const line of readFileSync(p, 'utf8').split('\n')) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const r = JSON.parse(line);
+                    if (r.asset_id)
+                        this.index.set(r.asset_id, r);
+                }
+                catch { /* skip 坏行 */ }
+            }
+        }
+        this.loaded = true;
+    }
+    async put(asset) {
+        this.ensureLoaded();
+        const { record, verified } = normalizeForPut(asset);
+        if (this.index.has(record.asset_id))
+            return { asset_id: record.asset_id, stored: false, verified };
+        const file = join(this.baseDir, FILES[record.type]);
+        acquireLock(this.lockPath);
+        try {
+            // 锁内复检(另一进程可能刚写)
+            if (!this.index.has(record.asset_id)) {
+                appendFileSync(file, `${JSON.stringify(record)}\n`);
+                this.index.set(record.asset_id, record);
+            }
+            else {
+                return { asset_id: record.asset_id, stored: false, verified };
+            }
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+        return { asset_id: record.asset_id, stored: true, verified };
+    }
+    /**
+     * 迁移专用(M8-2): 以**冻结 asset_id** 原样写入, 不经 normalizeForPut 重算/校验.
+     * 仅 v1→v2 导入用(硬化 A6 存量冻结); 普通写一律走 put(). record 必须自带 asset_id.
+     */
+    async putFrozen(record) {
+        this.ensureLoaded();
+        if (!record.asset_id)
+            throw new Error('putFrozen 需 record 自带冻结 asset_id');
+        if (this.index.has(record.asset_id))
+            return { asset_id: record.asset_id, stored: false, verified: false };
+        const file = join(this.baseDir, FILES[record.type]);
+        acquireLock(this.lockPath);
+        try {
+            if (this.index.has(record.asset_id))
+                return { asset_id: record.asset_id, stored: false, verified: false };
+            appendFileSync(file, `${JSON.stringify(record)}\n`);
+            this.index.set(record.asset_id, record);
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+        return { asset_id: record.asset_id, stored: true, verified: false };
+    }
+    async get(assetId) {
+        this.ensureLoaded();
+        return this.index.get(assetId) ?? null;
+    }
+    async list(kind, limit = 1000) {
+        this.ensureLoaded();
+        const out = [];
+        for (const r of this.index.values()) {
+            if (!kind || r.type === kind)
+                out.push(r);
+            if (out.length >= limit)
+                break;
+        }
+        return out;
+    }
+    async search(q) {
+        this.ensureLoaded();
+        const out = [];
+        for (const r of this.index.values()) {
+            if (q.kind && r.type !== q.kind)
+                continue;
+            if (q.category) {
+                const cat = r.category ?? r.intent;
+                if (cat !== q.category)
+                    continue;
+            }
+            if (q.gene && r.gene !== q.gene)
+                continue;
+            if (q.signalsAny && q.signalsAny.length > 0) {
+                const sig = new Set(signalsOf(r));
+                if (!q.signalsAny.some((s) => sig.has(s)))
+                    continue;
+            }
+            if (q.text) {
+                const summary = String(r.summary ?? '');
+                if (!summary.includes(q.text))
+                    continue;
+            }
+            out.push(r);
+            if (out.length >= (q.limit ?? 1000))
+                break;
+        }
+        return out;
+    }
+    /**
+     * Opt-in log compaction: rewrite each kind's jsonl keeping ONE line per asset_id (last wins),
+     * dropping duplicate/corrupt lines that accumulate across processes/restarts/migration. Lossless
+     * because the store is content-addressed (one record per asset_id is all there ever was). This does
+     * NOT evict assets — every unique asset is knowledge that stays. Atomic per file (temp + rename) under
+     * the write lock. Returns kept/removed line counts.
+     */
+    async compact() {
+        this.ensureLoaded();
+        acquireLock(this.lockPath);
+        try {
+            let kept = 0, removed = 0;
+            for (const [kind, file] of Object.entries(FILES)) {
+                const p = join(this.baseDir, file);
+                if (!existsSync(p))
+                    continue;
+                const lines = readFileSync(p, 'utf8').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 {
+                        const r = JSON.parse(line);
+                        if (r.asset_id && r.type === kind)
+                            byId.set(r.asset_id, line);
+                    }
+                    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
+                kept += byId.size;
+                removed += lines.length - byId.size;
+            }
+            return { kept, removed };
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+    }
+}

package/dist/assetstore/pendingSignals.d.ts

@@ -0,0 +1,22 @@
+import type { AssetStoreProvider } from './provider.js';
+export interface PendingSignalsFile {
+    signals?: unknown;
+    note?: unknown;
+}
+export interface PendingSignalsConsumeResult {
+    signals: string[];
+    path?: string;
+}
+export interface PendingSignalsMergeResult {
+    signals: string[];
+    injected: number;
+    path?: string;
+}
+export interface PendingSignalsContext {
+    repoRoot?: string;
+    cwd?: string;
+}
+export declare function pendingSignalsPath(baseDir: string): string;
+export declare function consumePendingSignals(baseDir: string): PendingSignalsConsumeResult;
+export declare function consumePendingSignalsForStore(store: AssetStoreProvider, context?: PendingSignalsContext): PendingSignalsConsumeResult;
+export declare function mergePendingSignalsForStore(store: AssetStoreProvider, baseSignals: readonly string[], context?: PendingSignalsContext): PendingSignalsMergeResult;

package/dist/assetstore/pendingSignals.js

@@ -0,0 +1,171 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { LocalJsonlProvider } from './localJsonl.js';
+const MAX_SIGNAL_LENGTH = 200;
+export function pendingSignalsPath(baseDir) {
+    return join(baseDir, 'pending_signals.json');
+}
+function envPath(name) {
+    const raw = process.env[name]?.trim();
+    return raw ? raw : null;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function nearestExistingDir(start) {
+    let current = resolve(start);
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return isDirectory(current) ? current : dirname(current);
+}
+function findRepoRoot(start) {
+    let current = nearestExistingDir(start);
+    while (current) {
+        if (existsSync(join(current, '.git')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return null;
+}
+function workspaceRootForRepo(repoRoot) {
+    const workspace = join(repoRoot, 'workspace');
+    return isDirectory(workspace) ? workspace : repoRoot;
+}
+function workspaceRootFromRepoHint(repoRoot) {
+    return workspaceRootForRepo(findRepoRoot(repoRoot) ?? resolve(repoRoot));
+}
+function workspaceRoot(context = {}) {
+    if (context.repoRoot)
+        return workspaceRootFromRepoHint(context.repoRoot);
+    const openclawWorkspace = envPath('OPENCLAW_WORKSPACE');
+    if (openclawWorkspace)
+        return resolve(openclawWorkspace);
+    const explicitRepoRoot = envPath('EVOLVER_REPO_ROOT');
+    if (explicitRepoRoot)
+        return workspaceRootFromRepoHint(explicitRepoRoot);
+    const cwd = context.cwd ?? process.cwd();
+    const repoRoot = findRepoRoot(cwd);
+    return repoRoot ? workspaceRootForRepo(repoRoot) : resolve(cwd);
+}
+function sessionScope() {
+    const raw = String(process.env['EVOLVER_SESSION_SCOPE'] ?? '').trim();
+    if (!raw)
+        return null;
+    const safe = raw.replace(/[^a-zA-Z0-9_\-.]/g, '_').slice(0, 128);
+    if (!safe || /^\.{1,2}$/.test(safe) || /\.\./.test(safe))
+        return null;
+    return safe;
+}
+function legacyV1BaseDir(context = {}, allowEnvOverride = true) {
+    const override = allowEnvOverride ? envPath('GEP_ASSETS_DIR') : null;
+    const baseDir = override ? resolve(override) : join(workspaceRoot(context), '.evolver', 'gep');
+    const scope = sessionScope();
+    return scope ? join(baseDir, 'scopes', scope) : baseDir;
+}
+function pendingSignalBaseDirsForStore(store, context = {}) {
+    const repoScoped = Boolean(context.repoRoot);
+    const baseDirs = repoScoped
+        // Autoexec tasks are repo-scoped; global pending files would be drained by whichever task runs first.
+        ? [{ baseDir: legacyV1BaseDir(context, false), createIfMissing: false }]
+        : [
+            { baseDir: store.baseDir, createIfMissing: true },
+            { baseDir: legacyV1BaseDir(context), createIfMissing: false },
+        ];
+    const seen = new Set();
+    const out = [];
+    for (const candidate of baseDirs) {
+        const key = resolve(candidate.baseDir);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(candidate);
+    }
+    return out;
+}
+function parsePendingSignals(raw) {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+}
+function normalizeSignals(rawSignals) {
+    const raw = Array.isArray(rawSignals) ? rawSignals : [];
+    const signals = raw
+        .map((signal) => (typeof signal === 'string' ? signal.trim() : ''))
+        .filter((signal) => signal.length > 0 && signal.length <= MAX_SIGNAL_LENGTH);
+    return { rawCount: raw.length, signals };
+}
+function writeConsumedFile(path) {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ signals: [], note: '' })}\n`);
+    renameSync(tmp, path);
+}
+function consumePendingSignalsFromBaseDir(baseDir, createIfMissing) {
+    if (createIfMissing)
+        mkdirSync(baseDir, { recursive: true });
+    const path = pendingSignalsPath(baseDir);
+    if (!existsSync(path))
+        return { signals: [] };
+    const lockPath = `${path}.lock`;
+    acquireLock(lockPath);
+    try {
+        if (!existsSync(path))
+            return { signals: [], path };
+        const parsed = parsePendingSignals(readFileSync(path, 'utf8'));
+        const { rawCount, signals } = normalizeSignals(parsed.signals);
+        if (rawCount > 0)
+            writeConsumedFile(path);
+        return { signals, path };
+    }
+    finally {
+        releaseLock(lockPath);
+    }
+}
+export function consumePendingSignals(baseDir) {
+    return consumePendingSignalsFromBaseDir(baseDir, true);
+}
+function tryConsumePendingSignals(baseDir) {
+    try {
+        return consumePendingSignalsFromBaseDir(baseDir.baseDir, baseDir.createIfMissing);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[PendingSignals] Failed to consume ${pendingSignalsPath(baseDir.baseDir)}: ${message}`);
+        return { signals: [] };
+    }
+}
+export function consumePendingSignalsForStore(store, context = {}) {
+    if (!(store instanceof LocalJsonlProvider))
+        return { signals: [] };
+    const pending = { signals: [] };
+    for (const baseDir of pendingSignalBaseDirsForStore(store, context)) {
+        const result = tryConsumePendingSignals(baseDir);
+        pending.signals.push(...result.signals);
+        if (!pending.path && result.path)
+            pending.path = result.path;
+    }
+    return pending;
+}
+export function mergePendingSignalsForStore(store, baseSignals, context = {}) {
+    const merged = [...baseSignals];
+    const pending = consumePendingSignalsForStore(store, context);
+    let injected = 0;
+    for (const signal of pending.signals) {
+        if (!merged.includes(signal)) {
+            merged.push(signal);
+            injected++;
+        }
+    }
+    return { signals: merged, injected, ...(pending.path ? { path: pending.path } : {}) };
+}

package/dist/assetstore/provenance.d.ts

@@ -0,0 +1,39 @@
+import { type AssetStoreProvider, type AssetRecord, type PutResult } from './provider.js';
+export type ProvenanceSource = 'local' | 'migrated' | 'hub';
+export interface ProvenanceRecord {
+    assetId: string;
+    source: ProvenanceSource;
+    trusted: boolean;
+    at: string;
+    promotedBy?: string;
+    reason?: string;
+}
+/**
+ * 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.
+ */
+export declare class ProvenanceStore {
+    private readonly now;
+    private readonly path;
+    private readonly index;
+    private loaded;
+    constructor(baseDir: string, now?: () => number);
+    private load;
+    /** Record provenance for an asset_id (append-only; the JSONL history is the audit trail). */
+    mark(rec: Omit<ProvenanceRecord, 'at'> & {
+        at?: string;
+    }): ProvenanceRecord;
+    rollbackLast(rec: ProvenanceRecord): void;
+    get(assetId: string): ProvenanceRecord | null;
+    /** No record → trusted (local default); a record → its trusted flag. */
+    isTrusted(assetId: string): boolean;
+    /** Explicit, audited untrusted→trusted promotion. Appends a new trusted record carrying who/why. */
+    promote(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
+ * remote-supplied asset_id is never trusted) and mark it untrusted in the sidecar. This is the ONLY path that
+ * should bring hub-fetched assets into the local pool — trust-first from the first byte (#30.1).
+ */
+export declare function ingestUntrusted(store: AssetStoreProvider, prov: ProvenanceStore, record: AssetRecord, source?: ProvenanceSource): Promise<PutResult>;

package/dist/assetstore/provenance.js

@@ -0,0 +1,109 @@
+// Provenance trust ledger (#30): genes/capsules fetched from the hub are untrusted — a poisoned asset that
+// reaches the selection pool could be reused and spread (experience poisoning). Provenance is a SIDECAR keyed
+// 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 { normalizeForPut } from './provider.js';
+/**
+ * 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.
+ */
+export class ProvenanceStore {
+    now;
+    path;
+    index = new Map();
+    loaded = false;
+    constructor(baseDir, now = Date.now) {
+        this.now = now;
+        this.path = join(baseDir, 'provenance.jsonl');
+    }
+    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 r = JSON.parse(line);
+                    if (r.assetId)
+                        this.index.set(r.assetId, r);
+                }
+                catch { /* skip corrupt line */ }
+            }
+        }
+        this.loaded = true;
+    }
+    /** Record provenance for an asset_id (append-only; the JSONL history is the audit trail). */
+    mark(rec) {
+        this.load();
+        const full = { ...rec, at: rec.at ?? 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;
+    }
+    rollbackLast(rec) {
+        const line = `${JSON.stringify(rec)}\n`;
+        const lineBytes = Buffer.byteLength(line, 'utf8');
+        try {
+            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)
+                return;
+            truncateSync(this.path, offset);
+            this.index.clear();
+            this.loaded = false;
+        }
+        catch {
+            this.index.clear();
+            this.loaded = false;
+        }
+    }
+    get(assetId) {
+        this.load();
+        return this.index.get(assetId) ?? null;
+    }
+    /** No record → trusted (local default); a record → its trusted flag. */
+    isTrusted(assetId) {
+        this.load();
+        const r = this.index.get(assetId);
+        return r ? r.trusted : true;
+    }
+    /** 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 });
+    }
+}
+/**
+ * The sanctioned hub→local-pool landing: store the asset (store.put recomputes/normalizes the asset_id, so a
+ * remote-supplied asset_id is never trusted) and mark it untrusted in the sidecar. This is the ONLY path that
+ * should bring hub-fetched assets into the local pool — trust-first from the first byte (#30.1).
+ */
+export async function ingestUntrusted(store, prov, record, source = 'hub') {
+    const normalized = normalizeForPut(record);
+    const mark = prov.mark({ assetId: normalized.record.asset_id, source, trusted: false });
+    try {
+        return await store.put(record);
+    }
+    catch (err) {
+        prov.rollbackLast(mark);
+        throw err;
+    }
+}

package/dist/assetstore/provider.d.ts

@@ -0,0 +1,48 @@
+export type AssetKind = 'Gene' | 'Capsule' | 'EvolutionEvent' | 'AntiGene';
+/** 任意带 type/asset_id 的 wire 资产(schema SSOT=gep-sdk, 此处不重定义字段). */
+export interface AssetRecord {
+    type: AssetKind;
+    asset_id: string;
+    [k: string]: unknown;
+}
+export interface PutResult {
+    asset_id: string;
+    stored: boolean;
+    verified: boolean;
+}
+export interface SearchQuery {
+    kind?: AssetKind;
+    signalsAny?: string[];
+    category?: string;
+    gene?: string;
+    text?: string;
+    limit?: number;
+}
+/**
+ * 可插拔资产库接口(D19/M3-1). 一份接口, 多实现: LocalJsonlProvider(本地) + Remote(hub).
+ * core 可同时连多个 provider(本地 + 远程), 不造第四套契约.
+ */
+export interface AssetStoreProvider {
+    put(asset: AssetRecord): Promise<PutResult>;
+    get(assetId: string): Promise<AssetRecord | null>;
+    search(query: SearchQuery): Promise<AssetRecord[]>;
+    list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
+}
+export declare class AssetIdMismatchError extends Error {
+    readonly claimed: string;
+    readonly actual: string;
+    constructor(claimed: string, actual: string);
+}
+export declare class CapsuleGeneBindingError extends Error {
+    constructor();
+}
+/**
+ * 落库前规范化(共享给各 provider): 计算/校验 asset_id + 强绑定校验.
+ * - 缺 asset_id → 计算填入(verified=false 表示非入参自带).
+ * - 带 asset_id → 必须自洽, 否则抛 AssetIdMismatchError.
+ * - Capsule.gene 必须非空(M3-4 强绑定).
+ */
+export declare function normalizeForPut(asset: AssetRecord): {
+    record: AssetRecord;
+    verified: boolean;
+};