@evomap/evolver-core 2.0.0-beta.8 → 2.0.0

package/dist/assetstore/provenance.d.ts

@@ -1,6 +1,7 @@
-import { type AssetStoreProvider, type AssetRecord, type PutResult } from './provider.js';
+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,15 +12,56 @@ 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 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";
+    constructor(assetId: 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.
+ * 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;
@@ -36,6 +78,21 @@ export declare class ProvenanceStore {
     mark(rec: Omit<ProvenanceRecord, 'at'> & {
         at?: string;
     }): ProvenanceRecord;
+    /** Stage a verified Hub write without replacing an in-flight conservative marker. */
+    stageUntrustedWriteTracked(assetId: string, source: ProvenanceSource): {
+        record: ProvenanceRecord;
+        appended: boolean;
+    };
+    /** Finalize a verified write unless an operator made an explicit decision during I/O. */
+    finalizeUntrustedWrite(assetId: string, source: ProvenanceSource): ProvenanceRecord;
+    /** Stage an unverified write without overwriting an explicit trust decision or another conservative marker. */
+    stageUnverifiedWrite(assetId: string, source: ProvenanceSource, frozenContentId: string): ProvenanceRecord;
+    stageUnverifiedWriteTracked(assetId: string, source: ProvenanceSource, frozenContentId: string): {
+        record: ProvenanceRecord;
+        appended: boolean;
+    };
+    /** Atomically replace only a pending/no decision with the health-waiver reason after verified persistence. */
+    finalizeUnverifiedWrite(assetId: string, source: ProvenanceSource, reason: string, frozenContentId: string): ProvenanceRecord;
     rollbackLast(rec: ProvenanceRecord): void;
     get(assetId: string): ProvenanceRecord | null;
     /** No record → trusted (local default); a record → its trusted flag. */
@@ -54,4 +111,23 @@ export declare class ProvenanceStore {
  * 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>;
+export declare function ingestUntrusted(store: AssetStoreProvider, prov: ProvenanceStore, record: AssetRecord, source?: ProvenanceSource): Promise<PutResult>;
+/**
+ * Hub → local-pool landing for an asset whose content does NOT hash to its declared asset_id. The hub
+ * demonstrably rewrites delivered payloads (injected `validation`, wholesale `payload_backfill_reason`
+ * synthesis — evolver-v2#570), which breaks {@link ingestUntrusted}'s normalizeForPut self-consistency check
+ * even though the loop's own in-run reuse already consumes hub content without re-verifying it (adapter
+ * `hubReuse.ts`). Rather than hard-reject a save the operator explicitly asked for, freeze the asset under its
+ * declared (network) asset_id via `putFrozen` and mark it untrusted in the sidecar with an explicit reason.
+ * Trust-first still holds (#30.1): selection defaults to trusted-only, so an unverified asset never silently
+ * enters the reasoning pool — it lands where the operator put it and stays flagged until an explicit,
+ * audited promotion. `reason` records WHY verification was waived (e.g. hub rewrite vs synthesized payload).
+ */
+export declare function ingestUnverified(store: AssetStoreProvider, prov: ProvenanceStore, record: AssetRecord, reason: string, source?: ProvenanceSource): Promise<PutResult>;
+/** Atomic frozen variant used by reuse so the logical-id check and append share one provider lock. */
+export declare function ingestUnverifiedConditional(store: AssetStoreProvider, prov: ProvenanceStore, record: AssetRecord, reason: string, options?: ConditionalPutOptions, source?: ProvenanceSource): Promise<ConditionalPutResult>;
+/**
+ * Conditional variant used by Hub sync to reject a logical-id collision without ever allowing a Hub record
+ * to become implicitly trusted. Providers that cannot make the condition atomically are rejected here.
+ */
+export declare function ingestUntrustedConditional(store: AssetStoreProvider, prov: ProvenanceStore, record: AssetRecord, options?: ConditionalPutOptions, source?: ProvenanceSource): Promise<ConditionalPutResult>;

package/dist/assetstore/provenance.js

@@ -4,16 +4,118 @@
 // 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 { join, dirname } from 'node:path';
-import { normalizeForPut } from './provider.js';
+import { assertCapsuleGeneBinding, FrozenAssetIdCollisionError, InvalidFrozenPutResultError, frozenAssetRecordsEqual, normalizeForPut, supportsAtomicConditionalPut, supportsAtomicFrozenConditionalPut, validateConditionalPutResult, validateFrozenPutResult, } from './provider.js';
 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';
+    constructor(assetId) {
+        super('asset provenance write is pending');
+        this.assetId = assetId;
+        this.name = 'ProvenanceWritePendingError';
+    }
+}
 function immutableRecord(record) {
     return Object.freeze({ ...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;
@@ -69,6 +171,89 @@ export class ProvenanceStore {
             return this.appendUnderLock(full);
         });
     }
+    /** Stage a verified Hub write without replacing an in-flight conservative marker. */
+    stageUntrustedWriteTracked(assetId, source) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            if (current && (current.trusted === true || current.decision !== undefined)) {
+                return { record: current, appended: false };
+            }
+            if (current?.trusted === false) {
+                return { record: current, appended: false };
+            }
+            return {
+                record: this.appendUnderLock({
+                    assetId,
+                    source,
+                    trusted: false,
+                    at: new Date(this.now()).toISOString(),
+                }),
+                appended: true,
+            };
+        });
+    }
+    /** Finalize a verified write unless an operator made an explicit decision during I/O. */
+    finalizeUntrustedWrite(assetId, source) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            if (current && (current.trusted === true || current.decision !== undefined))
+                return current;
+            return this.appendUnderLock({
+                assetId,
+                source,
+                trusted: false,
+                at: new Date(this.now()).toISOString(),
+            });
+        });
+    }
+    /** Stage an unverified write without overwriting an explicit trust decision or another conservative marker. */
+    stageUnverifiedWrite(assetId, source, frozenContentId) {
+        return this.stageUnverifiedWriteTracked(assetId, source, frozenContentId).record;
+    }
+    stageUnverifiedWriteTracked(assetId, source, frozenContentId) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            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_WRITE_PENDING_REASON,
+                    frozenContentId,
+                    at: new Date(this.now()).toISOString(),
+                }),
+                appended: true,
+            };
+        });
+    }
+    /** Atomically replace only a pending/no decision with the health-waiver reason after verified persistence. */
+    finalizeUnverifiedWrite(assetId, source, reason, frozenContentId) {
+        assertAssetStoreDirectory(dirname(this.path));
+        return withAssetStoreLock(this.lockPath, () => {
+            this.refreshUnderLock();
+            const current = this.index.get(assetId);
+            const action = unverifiedFinalizeAction(current, source, reason, frozenContentId);
+            if (current && action !== 'append')
+                return current;
+            return this.appendUnderLock({
+                assetId,
+                source,
+                trusted: false,
+                reason,
+                frozenContentId,
+                at: new Date(this.now()).toISOString(),
+            });
+        });
+    }
     rollbackLast(rec) {
         const line = `${JSON.stringify(rec)}\n`;
         try {
@@ -103,14 +288,22 @@ export class ProvenanceStore {
         return withAssetStoreLock(this.lockPath, () => {
             this.refreshUnderLock();
             const current = this.index.get(assetId) ?? null;
-            if (current?.trusted === trusted)
+            if (trusted
+                && current?.trusted === false
+                && current.decision === undefined
+                && current.reason === UNVERIFIED_WRITE_PENDING_REASON) {
+                throw new ProvenanceWritePendingError(assetId);
+            }
+            const decision = trusted ? 'promoted' : 'revoked';
+            if (current?.trusted === trusted && current.decision === decision) {
                 return { changed: false, record: current };
+            }
             const full = {
                 assetId,
                 source: current?.source ?? 'local',
                 trusted,
                 at: new Date(this.now()).toISOString(),
-                decision: trusted ? 'promoted' : 'revoked',
+                decision,
                 decidedBy: by,
                 ...(trusted ? { promotedBy: by } : {}),
                 reason,
@@ -142,4 +335,119 @@ export async function ingestUntrusted(store, prov, record, source = 'hub') {
     if (!result.stored)
         prov.rollbackLast(mark);
     return result;
+}
+/**
+ * Hub → local-pool landing for an asset whose content does NOT hash to its declared asset_id. The hub
+ * demonstrably rewrites delivered payloads (injected `validation`, wholesale `payload_backfill_reason`
+ * synthesis — evolver-v2#570), which breaks {@link ingestUntrusted}'s normalizeForPut self-consistency check
+ * even though the loop's own in-run reuse already consumes hub content without re-verifying it (adapter
+ * `hubReuse.ts`). Rather than hard-reject a save the operator explicitly asked for, freeze the asset under its
+ * declared (network) asset_id via `putFrozen` and mark it untrusted in the sidecar with an explicit reason.
+ * Trust-first still holds (#30.1): selection defaults to trusted-only, so an unverified asset never silently
+ * enters the reasoning pool — it lands where the operator put it and stays flagged until an explicit,
+ * audited promotion. `reason` records WHY verification was waived (e.g. hub rewrite vs synthesized payload).
+ */
+export async function ingestUnverified(store, prov, record, reason, source = 'hub') {
+    if (typeof store.putFrozen !== 'function') {
+        // Only a content-addressed local pool receives hub reuse writes; a provider that cannot freeze a
+        // hash-inconsistent record cannot preserve the network id, so fail loudly rather than silently restamp it.
+        throw new Error('ingestUnverified requires a store that implements putFrozen');
+    }
+    // putFrozen bypasses normalizeForPut, so re-assert the M3-4 Capsule↔gene binding here — a hash-mismatched
+    // Capsule with an empty gene must still fail closed on the frozen path, exactly as it does on the verified one.
+    assertCapsuleGeneBinding(record);
+    const frozenContentId = computeAssetId(record);
+    if (!frozenContentId)
+        throw new Error('failed to compute frozen content id');
+    const existing = await store.get(record.asset_id);
+    if (existing) {
+        if (!frozenAssetRecordsEqual(existing, record))
+            throw new FrozenAssetIdCollisionError(record.asset_id);
+        prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        return { asset_id: record.asset_id, stored: false, verified: false };
+    }
+    // Stage a non-waiver record before the body write. If the provider throws or lies about persistence,
+    // 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 (planUnverifiedIngest(record, null, staged, reason, source).status !== 'create') {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    const result = validateFrozenPutResult(await store.putFrozen(record), record.asset_id);
+    const persisted = await store.get(record.asset_id);
+    if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+    return result;
+}
+/** Atomic frozen variant used by reuse so the logical-id check and append share one provider lock. */
+export async function ingestUnverifiedConditional(store, prov, record, reason, options, source = 'hub') {
+    if (!supportsAtomicFrozenConditionalPut(store)) {
+        throw new Error('asset store does not support conditional frozen writes');
+    }
+    assertCapsuleGeneBinding(record);
+    const frozenContentId = computeAssetId(record);
+    if (!frozenContentId)
+        throw new Error('failed to compute frozen content id');
+    const existing = await store.get(record.asset_id);
+    if (existing) {
+        if (!frozenAssetRecordsEqual(existing, record))
+            throw new FrozenAssetIdCollisionError(record.asset_id);
+        prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        return { asset_id: record.asset_id, stored: false, verified: false, status: 'already_exists' };
+    }
+    const stage = prov.stageUnverifiedWriteTracked(record.asset_id, source, 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);
+    if (result.verified !== false)
+        throw new InvalidFrozenPutResultError();
+    if (!result.stored) {
+        // The pending row may be shared with a concurrent writer. Keep it until a persisted body is finalized.
+        if (result.status === 'already_exists') {
+            const persisted = await store.get(record.asset_id);
+            if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+                throw new FrozenAssetIdCollisionError(record.asset_id);
+            }
+            prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+        }
+        return result;
+    }
+    const persisted = await store.get(record.asset_id);
+    if (!persisted || !frozenAssetRecordsEqual(persisted, record)) {
+        throw new FrozenAssetIdCollisionError(record.asset_id);
+    }
+    prov.finalizeUnverifiedWrite(record.asset_id, source, reason, frozenContentId);
+    return result;
+}
+/**
+ * Conditional variant used by Hub sync to reject a logical-id collision without ever allowing a Hub record
+ * to become implicitly trusted. Providers that cannot make the condition atomically are rejected here.
+ */
+export async function ingestUntrustedConditional(store, prov, record, options, source = 'hub') {
+    if (!supportsAtomicConditionalPut(store)) {
+        throw new Error('asset store does not support conditional writes');
+    }
+    const normalized = normalizeForPut(record);
+    const stage = prov.stageUntrustedWriteTracked(normalized.record.asset_id, source);
+    const result = validateConditionalPutResult(await store.putConditional(record, options), normalized.record.asset_id, options);
+    if (result.status === 'logical_collision') {
+        if (stage.appended)
+            prov.rollbackLast(stage.record);
+        return result;
+    }
+    if (!result.stored) {
+        const persisted = await store.get(normalized.record.asset_id);
+        if (!persisted || !frozenAssetRecordsEqual(persisted, normalized.record)) {
+            throw new FrozenAssetIdCollisionError(normalized.record.asset_id);
+        }
+        if (stage.appended)
+            prov.rollbackLast(stage.record);
+    }
+    if (!stage.appended) {
+        prov.finalizeUntrustedWrite(normalized.record.asset_id, source);
+    }
+    return result;
 }

package/dist/assetstore/provider.d.ts

@@ -10,12 +10,43 @@ export interface PutResult {
     stored: boolean;
     verified: boolean;
 }
+export declare class FrozenAssetIdCollisionError extends Error {
+    readonly assetId: string;
+    readonly code = "FROZEN_ASSET_ID_COLLISION";
+    constructor(assetId: string);
+}
+export declare class InvalidFrozenPutResultError extends Error {
+    readonly code = "INVALID_FROZEN_PUT_RESULT";
+    constructor();
+}
+export declare function frozenAssetRecordsEqual(left: AssetRecord, right: AssetRecord): boolean;
+export declare function validateFrozenPutResult(value: unknown, expectedAssetId: string): PutResult;
+export type ConditionalPutStatus = 'stored' | 'already_exists' | 'logical_collision';
+export interface ConditionalPutOptions {
+    /** Only explicit force-like callers may keep multiple content versions for the same type + logical id. */
+    allowLogicalCollision?: boolean;
+}
+export interface ConditionalPutResult extends PutResult {
+    status: ConditionalPutStatus;
+    logicalId?: string;
+    collisionWithAssetId?: string;
+}
+export type InvalidConditionalPutResultReason = 'malformed_result' | 'asset_id_mismatch' | 'inconsistent_status' | 'invalid_collision' | 'collision_bypass';
+export declare class InvalidConditionalPutResultError extends Error {
+    readonly reason: InvalidConditionalPutResultReason;
+    readonly code = "INVALID_CONDITIONAL_PUT_RESULT";
+    constructor(reason: InvalidConditionalPutResultReason);
+}
+/** Validate an injected provider response before callers treat it as an explicit write/no-write decision. */
+export declare function validateConditionalPutResult(value: unknown, expectedAssetId: string, options?: ConditionalPutOptions): ConditionalPutResult;
 export interface SearchQuery {
     kind?: AssetKind;
     signalsAny?: string[];
     category?: string;
     gene?: string;
     text?: string;
+    /** Task-domain scope (hub taxonomy slug, e.g. "software_engineering"). Local providers may ignore it; the hub applies it as a recall fence. */
+    domain?: string;
     limit?: number;
 }
 /**
@@ -24,12 +55,32 @@ export interface SearchQuery {
  */
 export interface AssetStoreProvider {
     put(asset: 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>;
     /** Optional direct lookup for non-content-addressed logical ids. Callers must handle 0, 1, or multiple matches. */
-    findByLogicalId?(id: string, limit?: number): Promise<AssetRecord[]>;
+    findByLogicalId?(id: string, limit?: number, kind?: AssetKind): Promise<AssetRecord[]>;
+    /**
+     * Optional frozen write: store the record under its OWN declared asset_id without recomputing or
+     * normalizing it (bypasses {@link normalizeForPut}'s self-consistency check). Only providers backing a
+     * content-addressed local pool implement it. Callers that must preserve a hash-inconsistent asset —
+     * v1 migration import, and unverified hub reuse of a hub-rewritten payload (see `ingestUnverified`) —
+     * feature-detect it rather than assuming it exists.
+     */
+    putFrozen?(record: AssetRecord): Promise<PutResult>;
+    /** Atomic frozen variant that also enforces the type + logical-id condition under the provider write lock. */
+    putFrozenConditional?(record: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
     search(query: SearchQuery): Promise<AssetRecord[]>;
     list(kind?: AssetKind, limit?: number): Promise<AssetRecord[]>;
 }
+export type AtomicConditionalPutProvider = AssetStoreProvider & {
+    putConditional(asset: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
+};
+export declare function supportsAtomicConditionalPut(provider: AssetStoreProvider): provider is AtomicConditionalPutProvider;
+export type AtomicFrozenConditionalPutProvider = AssetStoreProvider & {
+    putFrozenConditional(record: AssetRecord, options?: ConditionalPutOptions): Promise<ConditionalPutResult>;
+};
+export declare function supportsAtomicFrozenConditionalPut(provider: AssetStoreProvider): provider is AtomicFrozenConditionalPutProvider;
 export declare class AssetIdMismatchError extends Error {
     readonly claimed: string;
     readonly actual: string;
@@ -38,6 +89,12 @@ export declare class AssetIdMismatchError extends Error {
 export declare class CapsuleGeneBindingError extends Error {
     constructor();
 }
+/**
+ * M3-4 强绑定校验: Capsule.gene 必须非空(否则一条无来源基因的经验会污染选择池).
+ * 抽成独立 helper 以便 normalizeForPut(校验落库路径)与 ingestUnverified(冻结落库路径,
+ * 绕过 normalizeForPut)共用同一条不变量,不让降级路径把绑定校验漏掉.
+ */
+export declare function assertCapsuleGeneBinding(asset: AssetRecord): void;
 /**
  * 落库前规范化(共享给各 provider): 计算/校验 asset_id + 强绑定校验.
  * - 缺 asset_id → 计算填入(verified=false 表示非入参自带).