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

package/dist/algo/geneSelection.d.ts

@@ -4,6 +4,8 @@ import { type GeneHealth } from './geneHealth.js';
 import type { GeneLearningView } from '../assetstore/learningHistory.js';
 import type { AssetRecord } from '../assetstore/provider.js';
 import { type ExplorationInput } from './exploration.js';
+import type { GenerationSource } from '../wire/index.js';
+import type { MemoryGraphGeneEvidence } from './memoryGraph.js';
 /** 一个候选 gene 的选择期素材. */
 export interface GeneCandidateInput {
     geneId: string;
@@ -34,6 +36,8 @@ export interface GeneCandidateInput {
      * set the hard gates already produced, so a high confidence can never resurrect a gene that was excluded.
      */
     confidence?: number;
+    /** Scoped local MemoryGraph outcome signal in [-1,1]. Data-only and never executable prompt content. */
+    memoryBoost?: number;
     /**
      * Cross-runtime reuse sentiment in [-1, 1] for this gene (#268 phase 1): the net of self-reported reuse
      * SUCCESSes vs negatives (failed/mismatched/stale/unsafe), computed upstream from reuse-outcome events
@@ -43,6 +47,11 @@ export interface GeneCandidateInput {
      * effect, so the factor is dormant until a caller injects the signal (default-off).
      */
     reuseAdjust?: number;
+    /**
+     * Authoritative provenance tag from Gene.generation_meta.source. The legacy `gene_distilled_` prefix remains a
+     * fallback only for old candidates that do not carry this field.
+     */
+    generationSource?: GenerationSource;
 }
 export interface SelectionInput {
     signals: readonly string[];
@@ -72,6 +81,8 @@ export interface SelectionInput {
      * for prompt rendering only; they never enter scoring, fallback, or forced selection.
      */
     antiWarnings?: readonly AntiWarning[];
+    /** Structured, scoped outcome evidence selected upstream. Contains no raw memory text or instructions. */
+    memoryEvidence?: readonly MemoryGraphGeneEvidence[];
 }
 export interface ScoredCandidate {
     geneId: string;
@@ -99,6 +110,10 @@ export interface GeneDecision {
     antiWarnings?: AntiWarning[];
     weightsVersion: string;
     strategyName: string;
+    /** Human-readable explanation for the winning candidate. */
+    selectedReason?: string;
+    /** Bounded structured outcome evidence for prompt enrichment. */
+    memoryEvidence?: MemoryGraphGeneEvidence[];
 }
 /**
  * Weight of the preferred-gene confidence factor (fourth factor, positive cross-cycle learning). Kept small so
@@ -112,12 +127,14 @@ export declare const CONFIDENCE_WEIGHT = 0.15;
  * ±REUSE_WEIGHT and can never dominate health/signal-match.
  */
 export declare const REUSE_WEIGHT = 0.1;
+/** Weight of scoped local MemoryGraph outcome evidence. */
+export declare const MEMORY_GRAPH_WEIGHT = 0.12;
 /**
  * Version of the full engine-health weight vector (health 0.6 + signal-match 0.4 − epigenetic penalty
  * + CONFIDENCE_WEIGHT × confidence + REUSE_WEIGHT × reuse-sentiment). Bumped whenever a factor is added so golden
  * weight snapshots track the change. Composed from the health-weights version so a change to either layer shows.
  */
-export declare const SELECTION_WEIGHTS_VERSION = "sel-3(gh-1,conf=0.15,reuse=0.1)";
+export declare const SELECTION_WEIGHTS_VERSION = "sel-4(gh-1,conf=0.15,memory=0.12,reuse=0.1)";
 /** 实现1: engine 健康分主导(health 0.6 + 信号匹配 0.4). */
 export declare const engineHealthSelection: Strategy<SelectionInput, GeneDecision>;
 /** 实现2: 纯信号匹配采样(忽略 health, 对照基线 — 经验主义要可对比). */

package/dist/algo/geneSelection.js

@@ -4,9 +4,17 @@ import { tagOverlapScore, bagCosine } from '../signals/expand.js';
 import { driftSelect } from './exploration.js';
 import { isDistilledGeneId } from './geneIntake.js';
 function decisionWithWarnings(input, decision) {
+    const selected = decision.selectedGeneId
+        ? decision.candidates.find((candidate) => candidate.geneId === decision.selectedGeneId || candidate.assetId === decision.selectedAssetId)
+        : undefined;
+    const enriched = {
+        ...decision,
+        ...(selected ? { selectedReason: selected.reasons.join('; ') } : {}),
+        ...(input.memoryEvidence && input.memoryEvidence.length > 0 ? { memoryEvidence: [...input.memoryEvidence] } : {}),
+    };
     return input.antiWarnings && input.antiWarnings.length > 0
-        ? { ...decision, antiWarnings: [...input.antiWarnings] }
-        : decision;
+        ? { ...enriched, antiWarnings: [...input.antiWarnings] }
+        : enriched;
 }
 function signalMatchScore(signals, match) {
     if (signals.length === 0 || match.length === 0)
@@ -29,12 +37,14 @@ export const CONFIDENCE_WEIGHT = 0.15;
  * ±REUSE_WEIGHT and can never dominate health/signal-match.
  */
 export const REUSE_WEIGHT = 0.1;
+/** Weight of scoped local MemoryGraph outcome evidence. */
+export const MEMORY_GRAPH_WEIGHT = 0.12;
 /**
  * Version of the full engine-health weight vector (health 0.6 + signal-match 0.4 − epigenetic penalty
  * + CONFIDENCE_WEIGHT × confidence + REUSE_WEIGHT × reuse-sentiment). Bumped whenever a factor is added so golden
  * weight snapshots track the change. Composed from the health-weights version so a change to either layer shows.
  */
-export const SELECTION_WEIGHTS_VERSION = `sel-3(${HEALTH_WEIGHTS_VERSION},conf=${CONFIDENCE_WEIGHT},reuse=${REUSE_WEIGHT})`;
+export const SELECTION_WEIGHTS_VERSION = `sel-4(${HEALTH_WEIGHTS_VERSION},conf=${CONFIDENCE_WEIGHT},memory=${MEMORY_GRAPH_WEIGHT},reuse=${REUSE_WEIGHT})`;
 /**
  * Match score with semantic signal expansion (ported from v1): literal coverage first, then fill the
  * recall gap with semantic tag overlap, then with bag-of-words cosine similarity. A perfect literal match
@@ -65,13 +75,16 @@ function scoreCandidate(signals, c) {
     // Cross-runtime reuse sentiment (#268 phase 1): clamped to [-1,1] so an upstream bug cannot turn the soft nudge
     // into a dominant (or unbounded) term. Absent → 0 → no effect (default-off until a caller injects it).
     const reuse = Math.max(-1, Math.min(1, c.reuseAdjust ?? 0));
-    const score = 0.6 * health.score + 0.4 * m.score - epi + CONFIDENCE_WEIGHT * conf + REUSE_WEIGHT * reuse;
+    const memory = Math.max(-1, Math.min(1, c.memoryBoost ?? 0));
+    const score = 0.6 * health.score + 0.4 * m.score - epi + CONFIDENCE_WEIGHT * conf + MEMORY_GRAPH_WEIGHT * memory + REUSE_WEIGHT * reuse;
     const breakdown = m.tag > 0 || m.cos > 0 ? `(literal=${m.literal.toFixed(2)}+tag=${m.tag.toFixed(2)}+cos=${m.cos.toFixed(2)})` : '';
     const reasons = [`health=${health.score.toFixed(3)}(succ=${health.successRate.toFixed(2)},reuse=${health.reuseCount})`, `信号匹配=${m.score.toFixed(2)}${breakdown}`];
     if (epi > 0)
         reasons.push(`epigenetic 环境抑制 -${epi.toFixed(2)}`);
     if (conf > 0)
         reasons.push(`preferred-gene confidence +${(CONFIDENCE_WEIGHT * conf).toFixed(3)} (conf=${conf.toFixed(2)})`);
+    if (memory !== 0)
+        reasons.push(`scoped memory-graph outcome ${memory >= 0 ? '+' : ''}${(MEMORY_GRAPH_WEIGHT * memory).toFixed(3)} (boost=${memory.toFixed(2)})`);
     if (reuse !== 0)
         reasons.push(`cross-runtime reuse ${reuse >= 0 ? '+' : ''}${(REUSE_WEIGHT * reuse).toFixed(3)} (sentiment=${reuse.toFixed(2)})`);
     return { geneId: c.geneId, ...(c.assetId ? { assetId: c.assetId } : {}), score, health, reasons };
@@ -88,6 +101,14 @@ function matchesScoredIdentity(a, b) {
 function withoutCandidateIdentity(scored, c) {
     return scored.filter((s) => !matchesCandidateIdentity(s, c));
 }
+function isReusableGenerationSource(source) {
+    return source === 'distilled' || source === 'evolved';
+}
+function isReusableFallbackCandidate(c) {
+    if (c.generationSource !== undefined)
+        return isReusableGenerationSource(c.generationSource);
+    return isDistilledGeneId(c.geneId);
+}
 function forcedSelection(input, scored, scoreForcedFallback, floor) {
     const forcedGeneId = input.forcedGeneId?.trim();
     if (!forcedGeneId)
@@ -116,7 +137,7 @@ function forcedSelection(input, scored, scoreForcedFallback, floor) {
         forcedFallback.reasons.push('forced gene rejected: epigenetic suppression');
         return { scoredForChoice: scoredCandidatesOnly, forceRejected: true };
     }
-    if (!isDistilledGeneId(fallback.geneId)) {
+    if (!isReusableFallbackCandidate(fallback)) {
         forcedFallback.reasons.push('forced gene rejected: suppressed fallback');
         return { scoredForChoice: scoredCandidatesOnly, forceRejected: true };
     }
@@ -141,26 +162,29 @@ export const engineHealthSelection = {
         let selectedAssetId = forced.selectedAssetId ?? chosen?.assetId;
         if (!selectedGeneId) {
             // Issue #97 (ported from v1 selector.js): no candidate matched any live signal (every gene scored <= 0). Rather
-            // than fall straight through to a blind innovate, reuse a *distilled* gene if one is available. NB the prefix
-            // does NOT mean "skill-derived" in v2 the way it did in v1: v1 tagged only skill genes gene_distilled_ (auto-
-            // evolved genes were gene_auto_), but v2's intakeGene tags EVERY intaken gene gene_distilled_ (autoExec even
-            // intakes task strategies that way) and has no gene_auto_. So this pool is "any trusted/approved/non-suppressed
-            // pooled gene that does not match", not specifically skill-derived — the safety rests on the upstream gates
-            // (trust #30 / review #89-91 / signal-ban / inert-ban #195) plus the epigenetic skip below, not on a skill-
-            // provenance low-blast-radius assumption. We skip any distilled fallback epigenetically suppressed in this env;
-            // v2's event-log-derived epigeneticPenalty is the analog of v1's asset-mark hard suppression (related band, not
-            // the identical predicate). No usable distilled fallback → stay null so the caller still innovates (the contract).
+            // than fall straight through to a blind innovate, reuse a *distilled* (or evolved) gene if one is available.
+            // The fallback pool is built by candidateAssembly, which now filters by generation_meta.source ∈ {distilled,
+            // evolved} (V1 #302), falling back to the `gene_distilled_` id namespace for legacy genes. The id-prefix check
+            // below is a defense-in-depth filter for callers that bypass candidateAssembly; the authoritative provenance
+            // lives on generation_meta (see geneGenerationSource). The safety rests on the upstream gates (trust #30 /
+            // review #89-91 / signal-ban / inert-ban #195) plus the epigenetic skip below, not on a skill-provenance
+            // low-blast-radius assumption. We skip any distilled fallback epigenetically suppressed in this env; v2's
+            // event-log-derived epigeneticPenalty is the analog of v1's asset-mark hard suppression (related band, not the
+            // identical predicate). No usable distilled fallback → stay null so the caller still innovates (the contract).
             //
             // v1 #97 parity: the distilled fallback is a *no-signal-match* last resort — it must fire only when NOTHING
             // scored above zero, NOT merely when nothing cleared a positive `floor`. Otherwise a real but weak signal match
             // (0 < score <= floor) would be preempted by an unrelated zero-evidence distilled gene; V1 (which has no floor)
             // keeps such a match. When candidates scored > 0 but below floor, defer to V2's floor policy (innovate).
             const noSignalMatch = !forced.forceRejected && forced.scoredForChoice.every((s) => s.score <= 0);
-            const fb = noSignalMatch
-                ? (input.distilledFallback ?? []).find((c) => isDistilledGeneId(c.geneId) && (c.epigeneticPenalty ?? 0) === 0)
+            const fallback = noSignalMatch
+                ? (input.distilledFallback ?? [])
+                    .filter((candidate) => isReusableFallbackCandidate(candidate) && (candidate.epigeneticPenalty ?? 0) === 0)
+                    .map((candidate) => ({ candidate, scored: scoreCandidate(input.signals, candidate) }))
+                    .sort((left, right) => right.scored.score - left.scored.score || left.candidate.geneId.localeCompare(right.candidate.geneId))[0]
                 : undefined;
-            if (fb) {
-                const fbScored = scoreCandidate(input.signals, fb);
+            if (fallback) {
+                const { candidate: fb, scored: fbScored } = fallback;
                 fbScored.reasons.push('distilled_fallback(#97): 无信号匹配, 低置信度复用蒸馏 gene');
                 scored.push(fbScored);
                 selectedGeneId = fb.geneId;

package/dist/algo/index.d.ts

@@ -2,7 +2,9 @@ export * from './geneHealth.js';
 export * from './exploration.js';
 export * from './epigenetics.js';
 export * from './confidence.js';
+export * from './memoryGraph.js';
 export * from './capabilityCandidates.js';
+export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';

package/dist/algo/index.js

@@ -2,7 +2,9 @@ export * from './geneHealth.js';
 export * from './exploration.js';
 export * from './epigenetics.js';
 export * from './confidence.js';
+export * from './memoryGraph.js';
 export * from './capabilityCandidates.js';
+export * from './conversationSniffer.js';
 export * from './geneIntake.js';
 export * from './candidateAssembly.js';
 export * from './genePromotion.js';

package/dist/algo/memoryGraph.d.ts

@@ -0,0 +1,62 @@
+export type MemoryGraphOutcomeStatus = 'success' | 'failed';
+export interface MemoryGraphOutcomeRecord {
+    version: 2;
+    kind: 'outcome';
+    provenance: 'v2_local' | 'v1_import';
+    workspaceScope: string;
+    userScope: string;
+    signalFingerprint: string;
+    signals: readonly string[];
+    geneId: string;
+    status: MemoryGraphOutcomeStatus;
+    score: number;
+    at: string;
+    /** Stable local-source identity used to make one-time imports crash-retry safe. */
+    sourceFingerprint?: string;
+    successCount?: number;
+    failCount?: number;
+}
+export interface MemoryGraphGeneEvidence {
+    geneId: string;
+    boost: number;
+    expectedSuccess: number;
+    successCount: number;
+    failCount: number;
+    attempts: number;
+    similarity: number;
+    lastAt: string;
+}
+export interface MemoryGraphDiagnostics {
+    bytesRead: number;
+    recordsRead: number;
+    corruptLines: number;
+    oversizedLines: number;
+    scopeRejected: number;
+    provenanceRejected: number;
+    truncated: boolean;
+    recovery: 'healthy' | 'degraded' | 'recovered' | 'empty';
+    /** The graph was healthy enough to address, but another process held its maintenance lock. */
+    busy?: boolean;
+}
+export interface MemoryGraphAdvice {
+    genes: readonly MemoryGraphGeneEvidence[];
+    diagnostics: MemoryGraphDiagnostics;
+}
+export interface MemoryGraphQueryInput {
+    workspace: string;
+    signals: readonly string[];
+}
+export interface MemoryGraphRecordInput extends MemoryGraphQueryInput {
+    geneId: string;
+    status: MemoryGraphOutcomeStatus;
+    score: number;
+    at: string;
+}
+export interface MemoryGraphProvider {
+    query(input: MemoryGraphQueryInput): Promise<MemoryGraphAdvice> | MemoryGraphAdvice;
+    recordOutcome(input: MemoryGraphRecordInput): Promise<void> | void;
+}
+export declare function normalizeMemorySignals(signals: readonly string[]): string[];
+export declare function memorySignalFingerprint(signals: readonly string[]): string;
+export declare function safeMemoryGeneId(value: string): string;
+export declare function deriveMemoryGraphAdvice(records: readonly MemoryGraphOutcomeRecord[], signals: readonly string[], nowMs: number, diagnostics: MemoryGraphDiagnostics): MemoryGraphAdvice;

package/dist/algo/memoryGraph.js

@@ -0,0 +1,86 @@
+const MAX_SIGNALS = 32;
+const MAX_SIGNAL_CHARS = 120;
+const MAX_GENE_CHARS = 240;
+const MIN_SIMILARITY = 0.34;
+const HALF_LIFE_DAYS = 30;
+export function normalizeMemorySignals(signals) {
+    return [...new Set(signals
+            .filter((signal) => typeof signal === 'string')
+            .map((signal) => signal.trim().toLowerCase().slice(0, MAX_SIGNAL_CHARS))
+            .filter(Boolean))]
+        .sort()
+        .slice(0, MAX_SIGNALS);
+}
+export function memorySignalFingerprint(signals) {
+    return normalizeMemorySignals(signals).join('|') || '(none)';
+}
+export function safeMemoryGeneId(value) {
+    return value.trim().slice(0, MAX_GENE_CHARS);
+}
+export function deriveMemoryGraphAdvice(records, signals, nowMs, diagnostics) {
+    const currentSignals = normalizeMemorySignals(signals);
+    const aggregates = new Map();
+    for (const record of records) {
+        const similarity = jaccard(currentSignals, record.signals);
+        if (similarity < MIN_SIMILARITY)
+            continue;
+        const successCount = boundedCount(record.successCount ?? (record.status === 'success' ? 1 : 0));
+        const failCount = boundedCount(record.failCount ?? (record.status === 'failed' ? 1 : 0));
+        const total = successCount + failCount;
+        if (total === 0)
+            continue;
+        const decay = decayWeight(record.at, nowMs);
+        const weight = similarity * decay;
+        const current = aggregates.get(record.geneId) ?? { success: 0, fail: 0, weightedSimilarity: 0, weight: 0, lastAt: record.at };
+        current.success += successCount * weight;
+        current.fail += failCount * weight;
+        current.weightedSimilarity += similarity * total;
+        current.weight += total;
+        if (Date.parse(record.at) > Date.parse(current.lastAt))
+            current.lastAt = record.at;
+        aggregates.set(record.geneId, current);
+    }
+    const genes = [];
+    for (const [geneId, aggregate] of aggregates) {
+        const successCount = Math.round(aggregate.success);
+        const failCount = Math.round(aggregate.fail);
+        const attempts = successCount + failCount;
+        if (attempts === 0)
+            continue;
+        const expectedSuccess = (aggregate.success + 1) / (aggregate.success + aggregate.fail + 2);
+        const similarity = aggregate.weight > 0 ? Math.min(1, aggregate.weightedSimilarity / aggregate.weight) : 0;
+        const confidence = Math.min(1, Math.log2(attempts + 1) / 3);
+        const boost = clamp((expectedSuccess - 0.5) * 2 * similarity * confidence, -1, 1);
+        genes.push({ geneId, boost, expectedSuccess, successCount, failCount, attempts, similarity, lastAt: aggregate.lastAt });
+    }
+    genes.sort((left, right) => Math.abs(right.boost) - Math.abs(left.boost) || right.attempts - left.attempts || left.geneId.localeCompare(right.geneId));
+    return { genes: genes.slice(0, 64), diagnostics };
+}
+function boundedCount(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.min(1_000_000, Math.floor(value));
+}
+function jaccard(left, right) {
+    const a = new Set(normalizeMemorySignals(left));
+    const b = new Set(normalizeMemorySignals(right));
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const value of a)
+        if (b.has(value))
+            intersection += 1;
+    return intersection / (a.size + b.size - intersection);
+}
+function decayWeight(at, nowMs) {
+    const timestamp = Date.parse(at);
+    if (!Number.isFinite(timestamp))
+        return 0;
+    const ageDays = Math.max(0, nowMs - timestamp) / 86_400_000;
+    return Math.pow(0.5, ageDays / HALF_LIFE_DAYS);
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}

package/dist/algo/orchestrator.d.ts

@@ -7,6 +7,7 @@ import type { GeneCandidateInput } from './geneSelection.js';
 import { CycleEngine, type CycleInput, type CycleResult, type SolidifyPermitGate } from './cycleEngine.js';
 import { type PendingSignalsContext } from '../assetstore/pendingSignals.js';
 import { type ReuseOutcomeSummary, type ReuseOutcomeEvent } from '../ops/reuseOutcomes.js';
+import type { MemoryGraphAdvice } from './memoryGraph.js';
 export interface RunCycleOptions {
     cycleId: string;
     problem: ProblemPattern;
@@ -60,6 +61,8 @@ export interface RunCycleOptions {
      * agent self-report) gains teeth on selection. Omit → no recall contribution. Never feeds quarantine.
      */
     recallEvents?: readonly ReuseOutcomeEvent[];
+    /** Scoped local MemoryGraph query result. Omit to keep selection unchanged. */
+    memoryGraphAdvice?: MemoryGraphAdvice;
 }
 /** Drive one full evolution cycle end-to-end: assemble candidates from the store, then run the cycle. */
 export declare function runEvolutionCycle(engine: CycleEngine, store: AssetStoreProvider, opts: RunCycleOptions): Promise<CycleResult>;

package/dist/algo/orchestrator.js

@@ -38,7 +38,18 @@ export async function runEvolutionCycle(engine, store, opts) {
         ...(opts.hubCandidates && opts.hubCandidates.length > 0 ? { hubCandidates: opts.hubCandidates } : {}),
         ...(reuseCounts.size > 0 ? { reuseCounts } : {}),
     };
-    const { candidates, distilledFallback, antiWarnings } = await assembleSelectionPool(store, signals, asmOpts);
+    const { candidates: assembledCandidates, distilledFallback, antiWarnings } = await assembleSelectionPool(store, signals, asmOpts);
+    const memoryByGene = new Map((opts.memoryGraphAdvice?.genes ?? []).map((evidence) => [evidence.geneId, evidence]));
+    const candidates = assembledCandidates.map((candidate) => {
+        const evidence = memoryByGene.get(candidate.geneId) ?? (candidate.assetId ? memoryByGene.get(candidate.assetId) : undefined);
+        return evidence ? { ...candidate, memoryBoost: evidence.boost } : candidate;
+    });
+    const memoryDistilledFallback = distilledFallback.map((candidate) => {
+        const evidence = memoryByGene.get(candidate.geneId) ?? (candidate.assetId ? memoryByGene.get(candidate.assetId) : undefined);
+        return evidence ? { ...candidate, memoryBoost: evidence.boost } : candidate;
+    });
+    const memoryEligible = [...candidates, ...memoryDistilledFallback];
+    const memoryEvidence = opts.memoryGraphAdvice?.genes.filter((evidence) => memoryEligible.some((candidate) => candidate.geneId === evidence.geneId || candidate.assetId === evidence.geneId)).slice(0, 3) ?? [];
     return engine.runCycle({
         cycleId: opts.cycleId,
         problem: opts.problem,
@@ -57,7 +68,8 @@ export async function runEvolutionCycle(engine, store, opts) {
         ...(opts.solidifyPermit ? { solidifyPermit: opts.solidifyPermit } : {}),
         // #97: forward the distilled-gene fallback pool so a no-signal-match cycle reuses a distilled strategy
         // (instead of a blind innovate) when nothing clears the floor.
-        ...(distilledFallback.length > 0 ? { distilledFallback } : {}),
+        ...(memoryDistilledFallback.length > 0 ? { distilledFallback: memoryDistilledFallback } : {}),
         ...(antiWarnings.length > 0 ? { antiWarnings } : {}),
+        ...(memoryEvidence.length > 0 ? { memoryEvidence } : {}),
     });
 }

package/dist/assetstore/assetSidecarRecords.d.ts

@@ -0,0 +1,23 @@
+import type { AssetSyncRecord } from './assetSyncLedger.js';
+import type { ProvenanceRecord } from './provenance.js';
+import type { ReviewRecord } from './reviewLedger.js';
+export type AssetSidecarKind = 'provenance' | 'review' | 'asset-sync';
+export type AssetSidecarCorruptionReason = 'invalid_row' | 'unterminated';
+export interface ParsedSidecarJsonl<T> {
+    records: T[];
+    rows: number;
+    validRows: number;
+    corruptRows: number;
+    unterminated: boolean;
+}
+export declare class CorruptAssetSidecarError extends Error {
+    readonly sidecar: AssetSidecarKind;
+    readonly reason: AssetSidecarCorruptionReason;
+    readonly code = "CORRUPT_ASSET_SIDECAR";
+    constructor(sidecar: AssetSidecarKind, reason: AssetSidecarCorruptionReason);
+}
+export declare function parseSidecarJsonl<T>(raw: string, parseRecord: (value: unknown) => T | null): ParsedSidecarJsonl<T>;
+export declare function assertTrustSidecarHealthy<T>(sidecar: Extract<AssetSidecarKind, 'provenance' | 'review'>, parsed: ParsedSidecarJsonl<T>): void;
+export declare function parseProvenanceRecord(value: unknown): ProvenanceRecord | null;
+export declare function parseReviewRecord(value: unknown): ReviewRecord | null;
+export declare function parseAssetSyncRecord(value: unknown): AssetSyncRecord | null;

package/dist/assetstore/assetSidecarRecords.js

@@ -0,0 +1,142 @@
+export class CorruptAssetSidecarError extends Error {
+    sidecar;
+    reason;
+    code = 'CORRUPT_ASSET_SIDECAR';
+    constructor(sidecar, reason) {
+        super(`corrupt asset sidecar: ${sidecar}/${reason}`);
+        this.sidecar = sidecar;
+        this.reason = reason;
+        this.name = 'CorruptAssetSidecarError';
+    }
+}
+export function parseSidecarJsonl(raw, parseRecord) {
+    const records = [];
+    let rows = 0;
+    let corruptRows = 0;
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        rows += 1;
+        try {
+            const record = parseRecord(JSON.parse(line));
+            if (record)
+                records.push(record);
+            else
+                corruptRows += 1;
+        }
+        catch {
+            corruptRows += 1;
+        }
+    }
+    return {
+        records,
+        rows,
+        validRows: records.length,
+        corruptRows,
+        unterminated: raw.length > 0 && !raw.endsWith('\n'),
+    };
+}
+export function assertTrustSidecarHealthy(sidecar, parsed) {
+    if (parsed.unterminated)
+        throw new CorruptAssetSidecarError(sidecar, 'unterminated');
+    if (parsed.corruptRows > 0)
+        throw new CorruptAssetSidecarError(sidecar, 'invalid_row');
+}
+export function parseProvenanceRecord(value) {
+    const record = objectRecord(value);
+    if (!record)
+        return null;
+    const assetId = stringField(record, 'assetId');
+    const source = stringField(record, 'source');
+    const at = stringField(record, 'at');
+    if (!assetId
+        || (source !== 'local' && source !== 'migrated' && source !== 'hub')
+        || typeof record['trusted'] !== 'boolean'
+        || !at
+        || Number.isNaN(Date.parse(at))) {
+        return null;
+    }
+    const decision = record['decision'] === 'promoted' || record['decision'] === 'revoked'
+        ? record['decision']
+        : undefined;
+    const decidedBy = stringField(record, 'decidedBy');
+    const promotedBy = stringField(record, 'promotedBy');
+    const reason = stringField(record, 'reason');
+    return {
+        assetId,
+        source,
+        trusted: record['trusted'],
+        at,
+        ...(decision ? { decision } : {}),
+        ...(decidedBy ? { decidedBy } : {}),
+        ...(promotedBy ? { promotedBy } : {}),
+        ...(reason ? { reason } : {}),
+    };
+}
+export function parseReviewRecord(value) {
+    const record = objectRecord(value);
+    if (!record)
+        return null;
+    const assetId = stringField(record, 'assetId');
+    const state = stringField(record, 'state');
+    const at = stringField(record, 'at');
+    if (!assetId
+        || (state !== 'quarantined' && state !== 'approved' && state !== 'rejected')
+        || !at
+        || Number.isNaN(Date.parse(at))) {
+        return null;
+    }
+    const by = stringField(record, 'by');
+    const reason = stringField(record, 'reason');
+    return {
+        assetId,
+        state,
+        at,
+        ...(by ? { by } : {}),
+        ...(reason ? { reason } : {}),
+    };
+}
+export function parseAssetSyncRecord(value) {
+    const record = objectRecord(value);
+    if (!record)
+        return null;
+    const assetId = stringField(record, 'assetId');
+    const type = stringField(record, 'type');
+    const source = stringField(record, 'source');
+    const scope = stringField(record, 'scope');
+    const syncedAt = stringField(record, 'syncedAt');
+    const remoteAssetId = stringField(record, 'remoteAssetId');
+    if (!assetId
+        || (type !== 'Gene' && type !== 'Capsule')
+        || source !== 'hub'
+        || (scope !== 'purchased' && scope !== 'published')
+        || !syncedAt
+        || !remoteAssetId) {
+        return null;
+    }
+    const logicalId = stringField(record, 'logicalId');
+    const status = stringField(record, 'status');
+    const forced = record['forced'] === true;
+    const collisionWithAssetId = stringField(record, 'collisionWithAssetId');
+    return {
+        assetId,
+        type,
+        source,
+        scope,
+        syncedAt,
+        remoteAssetId,
+        ...(logicalId ? { logicalId } : {}),
+        ...(status ? { status } : {}),
+        ...(forced ? { forced: true } : {}),
+        ...(collisionWithAssetId ? { collisionWithAssetId } : {}),
+    };
+}
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringField(value, key) {
+    const raw = value[key];
+    return typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+}

package/dist/assetstore/assetSidecarRecovery.d.ts

@@ -0,0 +1,48 @@
+import { type ReleaseLockReason } from '../util/fileLock.js';
+import { type AssetStoreLockDeps } from './assetStoreStorage.js';
+import { type AssetSidecarKind } from './assetSidecarRecords.js';
+export type { AssetSidecarKind } from './assetSidecarRecords.js';
+export type AssetSidecarRecoveryFailureReason = 'sidecar_missing' | 'sidecar_not_degraded' | 'replacement_missing' | 'replacement_too_large' | 'replacement_invalid_utf8' | 'replacement_invalid' | 'replacement_unterminated' | 'valid_history_missing' | 'corrective_record_required' | 'unsafe_corrective_record' | 'acknowledgement_required' | 'sidecar_too_large' | 'sidecar_changed' | 'replacement_changed' | 'backup_conflict';
+export declare class AssetSidecarRecoveryError extends Error {
+    readonly reason: AssetSidecarRecoveryFailureReason;
+    readonly code = "ASSET_SIDECAR_RECOVERY_FAILED";
+    constructor(reason: AssetSidecarRecoveryFailureReason);
+}
+export interface AssetSidecarRecoveryFileReport {
+    rows: number;
+    validRows: number;
+    corruptRows: number;
+    unterminated: boolean;
+    digest: string;
+}
+export interface AssetSidecarReplacementReport extends AssetSidecarRecoveryFileReport {
+    preservedValidRows: number;
+    addedRecords: number;
+    correctiveRecords: number;
+}
+export interface AssetSidecarRecoveryReport {
+    mode: 'preview' | 'write';
+    sidecar: AssetSidecarKind;
+    changed: boolean;
+    wouldWrite: boolean;
+    acknowledgementRequired: boolean;
+    current: AssetSidecarRecoveryFileReport;
+    replacement: AssetSidecarReplacementReport;
+    backupId?: string;
+    lockReleaseWarning?: ReleaseLockReason;
+}
+export interface RecoverAssetSidecarOptions {
+    baseDir: string;
+    sidecar: AssetSidecarKind;
+    replacementPath: string;
+    write?: boolean;
+    acknowledgeCorruptHistory?: boolean;
+    maxFileBytes?: number;
+    deps?: {
+        beforeBackup?: () => void;
+        beforeReplace?: () => void;
+        lock?: AssetStoreLockDeps;
+    };
+}
+export declare const DEFAULT_SIDECAR_RECOVERY_MAX_FILE_BYTES: number;
+export declare function recoverAssetSidecar(opts: RecoverAssetSidecarOptions): AssetSidecarRecoveryReport;