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

package/dist/algo/orchestrator.d.ts

@@ -3,11 +3,12 @@ import type { ProvenanceStore } from '../assetstore/provenance.js';
 import type { ReviewLedger } from '../assetstore/reviewLedger.js';
 import type { GepCategory } from '../wire/index.js';
 import type { ProblemPattern } from '../schema/problem.js';
-import type { GeneCandidateInput } from './geneSelection.js';
+import type { GeneCandidateInput, SelectionGuardMode } 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';
+import type { SelectionPolicy } from './ucb1.js';
 export interface RunCycleOptions {
     cycleId: string;
     problem: ProblemPattern;
@@ -20,6 +21,12 @@ export interface RunCycleOptions {
     summary: string;
     confidence: number;
     selectionFloor?: number;
+    /** Emergency rollback for semantic IDF. Also skips pre-admission corpus collection. */
+    disableSemanticIdf?: boolean;
+    /** Experimental plateau policy. Omit for current engine-health + random drift behavior. */
+    selectionPolicy?: SelectionPolicy;
+    /** Versioned relevance-guard rollout. Omit for legacy direct-call behavior. */
+    selectionGuard?: SelectionGuardMode;
     /** Optional explicit gene chosen by GEP / an external runtime; forwarded to CycleEngine after assembly. */
     forcedGeneId?: string;
     /** The agent runtime's work: run the mutation, return the outcome. */

package/dist/algo/orchestrator.js

@@ -18,6 +18,12 @@ export async function runEvolutionCycle(engine, store, opts) {
             console.warn(`[ExplicitSignals] Failed to consume pending signals (non-fatal): ${message}`);
         }
     }
+    // Curriculum targets must be present before candidate assembly; injecting them only inside CycleEngine would
+    // be too late to recall a gene whose signals_match is curriculum_target:*. The engine repeats this enrichment
+    // for direct runCycle callers; the operation is deterministic and set-idempotent.
+    const baseSignals = signals;
+    const preparedCurriculum = engine.prepareCurriculumSignals(baseSignals);
+    const selectionSignals = preparedCurriculum.signals;
     // #268 phase 1 + #274 slice 3: fold cross-runtime reuse counts AND observed recall into the pool (soft re-order).
     // Absent both → no map → default-off. Recall is folded at a lower weight (RECALL_WEIGHT). Assembly sums a gene's
     // ids → sentiment; bounded + clamped in geneSelection; the hard trust/review/ban gates in assembly run first.
@@ -31,6 +37,7 @@ export async function runEvolutionCycle(engine, store, opts) {
         }
     }
     const asmOpts = {
+        includeSemanticCorpus: opts.disableSemanticIdf !== true,
         ...(opts.candidateLimit ? { limit: opts.candidateLimit } : {}),
         ...(opts.provenance ? { provenance: opts.provenance } : {}),
         ...(opts.review ? { review: opts.review } : {}),
@@ -38,7 +45,7 @@ export async function runEvolutionCycle(engine, store, opts) {
         ...(opts.hubCandidates && opts.hubCandidates.length > 0 ? { hubCandidates: opts.hubCandidates } : {}),
         ...(reuseCounts.size > 0 ? { reuseCounts } : {}),
     };
-    const { candidates: assembledCandidates, distilledFallback, antiWarnings } = await assembleSelectionPool(store, signals, asmOpts);
+    const { candidates: assembledCandidates, distilledFallback, semanticCorpus, antiWarnings } = await assembleSelectionPool(store, selectionSignals, 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);
@@ -53,10 +60,15 @@ export async function runEvolutionCycle(engine, store, opts) {
     return engine.runCycle({
         cycleId: opts.cycleId,
         problem: opts.problem,
-        signals,
+        signals: baseSignals,
+        curriculumSignals: preparedCurriculum.curriculumSignals,
         category: opts.category,
         ...(opts.strategyName !== undefined ? { strategyName: opts.strategyName } : {}),
         candidates,
+        semanticCorpus,
+        ...(opts.disableSemanticIdf ? { disableSemanticIdf: true } : {}),
+        ...(opts.selectionPolicy ? { selectionPolicy: opts.selectionPolicy } : {}),
+        ...(opts.selectionGuard ? { selectionGuard: opts.selectionGuard } : {}),
         target: opts.target,
         expectedEffect: opts.expectedEffect,
         summary: opts.summary,
@@ -67,7 +79,7 @@ export async function runEvolutionCycle(engine, store, opts) {
         ...(opts.failureContext !== undefined ? { failureContext: opts.failureContext } : {}),
         ...(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.
+        // (instead of a blind innovate) when normal selection has no reusable positive choice.
         ...(memoryDistilledFallback.length > 0 ? { distilledFallback: memoryDistilledFallback } : {}),
         ...(antiWarnings.length > 0 ? { antiWarnings } : {}),
         ...(memoryEvidence.length > 0 ? { memoryEvidence } : {}),

package/dist/algo/publishEligibility.d.ts

@@ -0,0 +1,34 @@
+import { type GeneLearningView } from '../assetstore/learningHistory.js';
+import type { AssetStoreProvider } from '../assetstore/provider.js';
+export type PublishEligibilityReason = 'eligible' | 'no_proven_success';
+export interface GenePublishEvidence {
+    geneId: string;
+    /** Real, value-producing successes (inert zero-work successes excluded upstream). */
+    success: number;
+    failed: number;
+    inert: number;
+    total: number;
+    eligible: boolean;
+    reason: PublishEligibilityReason;
+}
+/**
+ * The single publish/upload eligibility predicate: a gene may be published iff
+ * it has at least one capsule with a `success` outcome.
+ *
+ * We count `success + inert`, NOT just `success`. aggregateLearningHistory
+ * demotes a `success` capsule that carries no `proof_of_work` to `inert`
+ * (#195), but the evox capsule builder (asset_builder.rs) does NOT emit
+ * `proof_of_work` — a genuine successful run surfaces there as `inert`. Gating
+ * publish on the proof-only `success` count would therefore block genes that
+ * actually succeeded in production. "Has a success outcome" is the honest bar
+ * for the publish gate; the proof/inert distinction stays where it belongs
+ * (success-rate, auto-promote), not here. A gene with only failures — or one
+ * never run at all — has `success + inert === 0` and is not publishable.
+ */
+export declare function isGenePublishEligible(view: Pick<GeneLearningView, 'success' | 'inert'>): boolean;
+/**
+ * Read-only: derive a gene's outcome evidence and whether it clears the publish
+ * bar. Returns `no_proven_success` for a gene the store has never seen succeed,
+ * so callers can surface a precise, self-serviceable reason.
+ */
+export declare function assessGenePublishEvidence(store: AssetStoreProvider, geneId: string): Promise<GenePublishEvidence>;

package/dist/algo/publishEligibility.js

@@ -0,0 +1,52 @@
+// Proven-success gate for publishing / uploading a gene (#581).
+//
+// A gene's `confidence` is minted from model self-report (solidify), text
+// completeness (conversationDistiller), or is absent (like) — none of which
+// prove the gene ever WORKED. Publishing such a gene to the market pairs it
+// with a capsule and lets the Hub quality gate reject it after a round-trip
+// ("never truly succeeded"). This predicate is the single, outcome-driven bar
+// every publish/upload surface routes through, so an unproven gene is stopped
+// locally with a clear reason instead of leaking to the Hub.
+//
+// Deliberately DISTINCT from `probationWouldPromote` (genePromotion.ts):
+// auto-promotion runs with NO human in the loop, so it demands a strong, clean
+// record (>= minSuccess successes AND zero failures). Publishing is human-
+// initiated, so the bar is only "has this gene truly succeeded at least once"
+// — a gene with many successes and one stray failure is still worth publishing,
+// and blocking it on `failed === 0` would be wrong.
+import { aggregateLearningHistory } from '../assetstore/learningHistory.js';
+/**
+ * The single publish/upload eligibility predicate: a gene may be published iff
+ * it has at least one capsule with a `success` outcome.
+ *
+ * We count `success + inert`, NOT just `success`. aggregateLearningHistory
+ * demotes a `success` capsule that carries no `proof_of_work` to `inert`
+ * (#195), but the evox capsule builder (asset_builder.rs) does NOT emit
+ * `proof_of_work` — a genuine successful run surfaces there as `inert`. Gating
+ * publish on the proof-only `success` count would therefore block genes that
+ * actually succeeded in production. "Has a success outcome" is the honest bar
+ * for the publish gate; the proof/inert distinction stays where it belongs
+ * (success-rate, auto-promote), not here. A gene with only failures — or one
+ * never run at all — has `success + inert === 0` and is not publishable.
+ */
+export function isGenePublishEligible(view) {
+    return view.success + (view.inert ?? 0) >= 1;
+}
+/**
+ * Read-only: derive a gene's outcome evidence and whether it clears the publish
+ * bar. Returns `no_proven_success` for a gene the store has never seen succeed,
+ * so callers can surface a precise, self-serviceable reason.
+ */
+export async function assessGenePublishEvidence(store, geneId) {
+    const view = await aggregateLearningHistory(store, geneId);
+    const eligible = isGenePublishEligible(view);
+    return {
+        geneId,
+        success: view.success,
+        failed: view.failed,
+        inert: view.inert ?? 0,
+        total: view.total,
+        eligible,
+        reason: eligible ? 'eligible' : 'no_proven_success',
+    };
+}

package/dist/algo/ucb1.d.ts

@@ -0,0 +1,53 @@
+import type { RootEvent } from '../events/eventSchema.js';
+export declare const SELECTION_POLICIES: readonly ["engine-health", "ucb1-shadow", "ucb1"];
+export type SelectionPolicy = (typeof SELECTION_POLICIES)[number];
+export declare const UCB1_SELECTION_POLICY_VERSION = "ucb1-v1";
+export declare const UCB1_REWARD_POLICY_VERSION = "productive-binary-v1";
+export interface Ucb1ArmStats {
+    armId: string;
+    pulls: number;
+    completedPulls: number;
+    rewardSum: number;
+    meanReward: number;
+}
+export interface Ucb1History {
+    arms: ReadonlyMap<string, Ucb1ArmStats>;
+    /** Every non-ad-hoc decision counts immediately, including decisions whose terminal event is still pending. */
+    totalPulls: number;
+}
+export interface Ucb1Arm {
+    armId: string;
+    baseScore: number;
+    explorationEligible: boolean;
+    stats: Ucb1ArmStats;
+}
+export interface Ucb1Choice {
+    armId: string;
+    pulls: number;
+    completedPulls: number;
+    totalPulls: number;
+    meanReward: number;
+    /** Null represents the canonical +Infinity cold-start index without putting Infinity on the event wire. */
+    bonus: number | null;
+    /** Null represents the canonical +Infinity cold-start index without putting Infinity on the event wire. */
+    index: number | null;
+    coldStart: boolean;
+}
+export type Ucb1FallbackReason = 'empty_pool' | 'ineligible_arm' | 'missing_history';
+export interface Ucb1Decision {
+    choice: Ucb1Choice | null;
+    fallbackReason?: Ucb1FallbackReason;
+}
+/**
+ * Rebuild UCB1 state from the append-only root event log. Decisions are pulls immediately, so later readers no
+ * longer treat an in-flight arm as cold. The read-select-append sequence is not an atomic reservation across
+ * workers. A terminal event adds reward exactly once per cycle; duplicate rows collapse to their latest projection.
+ */
+export declare function deriveUcb1History(events: readonly RootEvent[]): Ucb1History;
+/** Combine current asset identity with legacy gene-only history when that bridge is unambiguous. */
+export declare function ucb1StatsForCandidate(history: Ucb1History, geneId: string, assetId?: string, includeLegacyGeneHistory?: boolean): Ucb1ArmStats;
+/**
+ * Canonical UCB1: mean reward + sqrt(2 ln(total pulls) / arm pulls). Cold arms have +Infinity and are ordered
+ * deterministically by base score then arm identity. The caller supplies only the already-gated exploration window.
+ */
+export declare function chooseUcb1Arm(arms: readonly Ucb1Arm[], historyTotalPulls: number): Ucb1Decision;

package/dist/algo/ucb1.js

@@ -0,0 +1,156 @@
+export const SELECTION_POLICIES = ['engine-health', 'ucb1-shadow', 'ucb1'];
+export const UCB1_SELECTION_POLICY_VERSION = 'ucb1-v1';
+export const UCB1_REWARD_POLICY_VERSION = 'productive-binary-v1';
+function nonEmptyString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function decisionProjection(event) {
+    if (event.type !== 'decision.gene_selected')
+        return undefined;
+    const payload = event.payload;
+    const cycleId = nonEmptyString(payload['cycleId']);
+    const geneId = nonEmptyString(payload['selectedGeneId']);
+    if (!cycleId)
+        return undefined;
+    if (!geneId || geneId === 'ad-hoc')
+        return { cycleId, decision: null };
+    return {
+        cycleId,
+        decision: { armId: nonEmptyString(payload['selectedAssetId']) ?? geneId },
+    };
+}
+function terminalReward(event) {
+    if (event.type !== 'cycle.failed' && event.type !== 'cycle.solidified')
+        return null;
+    const payload = event.payload;
+    const cycleId = nonEmptyString(payload['cycleId']);
+    if (!cycleId)
+        return null;
+    if (event.type === 'cycle.failed' || payload['producedValue'] === false)
+        return { cycleId, reward: 0 };
+    // Legacy solidified events predate producedValue. Preserve the existing confidence replay compatibility policy.
+    return { cycleId, reward: 1 };
+}
+/**
+ * Rebuild UCB1 state from the append-only root event log. Decisions are pulls immediately, so later readers no
+ * longer treat an in-flight arm as cold. The read-select-append sequence is not an atomic reservation across
+ * workers. A terminal event adds reward exactly once per cycle; duplicate rows collapse to their latest projection.
+ */
+export function deriveUcb1History(events) {
+    const cycles = new Map();
+    for (const event of events) {
+        const decision = decisionProjection(event);
+        // A restarted/re-emitted decision for the same cycleId begins a new pending lifecycle. Never let a terminal
+        // from the earlier lifecycle leak reward into this newer arm.
+        if (decision) {
+            if (decision.decision)
+                cycles.set(decision.cycleId, { decision: decision.decision });
+            else
+                cycles.delete(decision.cycleId);
+        }
+        const terminal = terminalReward(event);
+        if (terminal) {
+            const cycle = cycles.get(terminal.cycleId);
+            if (cycle)
+                cycle.reward = terminal.reward;
+        }
+    }
+    const mutable = new Map();
+    for (const cycle of cycles.values()) {
+        const current = mutable.get(cycle.decision.armId) ?? { pulls: 0, completedPulls: 0, rewardSum: 0 };
+        current.pulls += 1;
+        if (cycle.reward !== undefined) {
+            current.completedPulls += 1;
+            current.rewardSum += cycle.reward;
+        }
+        mutable.set(cycle.decision.armId, current);
+    }
+    const arms = new Map();
+    for (const [armId, stats] of mutable) {
+        arms.set(armId, {
+            armId,
+            ...stats,
+            meanReward: stats.completedPulls > 0 ? stats.rewardSum / stats.completedPulls : 0,
+        });
+    }
+    return { arms, totalPulls: cycles.size };
+}
+function emptyStats(armId) {
+    return { armId, pulls: 0, completedPulls: 0, rewardSum: 0, meanReward: 0 };
+}
+/** Combine current asset identity with legacy gene-only history when that bridge is unambiguous. */
+export function ucb1StatsForCandidate(history, geneId, assetId, includeLegacyGeneHistory = true) {
+    const armId = assetId ?? geneId;
+    const identities = assetId === undefined
+        ? [geneId]
+        : [...new Set([assetId, ...(includeLegacyGeneHistory ? [geneId] : [])])];
+    const matches = identities.map((identity) => history.arms.get(identity)).filter((stats) => stats !== undefined);
+    if (matches.length === 0)
+        return emptyStats(armId);
+    const pulls = matches.reduce((sum, stats) => sum + stats.pulls, 0);
+    const completedPulls = matches.reduce((sum, stats) => sum + stats.completedPulls, 0);
+    const rewardSum = matches.reduce((sum, stats) => sum + stats.rewardSum, 0);
+    return {
+        armId,
+        pulls,
+        completedPulls,
+        rewardSum,
+        meanReward: completedPulls > 0 ? rewardSum / completedPulls : 0,
+    };
+}
+function finiteBaseScore(value) {
+    return Number.isFinite(value) ? value : Number.NEGATIVE_INFINITY;
+}
+function finiteCount(value) {
+    return Number.isFinite(value) ? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(Math.max(0, value))) : 0;
+}
+function finiteMeanReward(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+}
+function saturatingCountSum(total, value) {
+    const count = finiteCount(value);
+    return total >= Number.MAX_SAFE_INTEGER - count ? Number.MAX_SAFE_INTEGER : total + count;
+}
+/**
+ * Canonical UCB1: mean reward + sqrt(2 ln(total pulls) / arm pulls). Cold arms have +Infinity and are ordered
+ * deterministically by base score then arm identity. The caller supplies only the already-gated exploration window.
+ */
+export function chooseUcb1Arm(arms, historyTotalPulls) {
+    if (arms.length === 0)
+        return { choice: null, fallbackReason: 'empty_pool' };
+    if (arms.some((arm) => !arm.explorationEligible))
+        return { choice: null, fallbackReason: 'ineligible_arm' };
+    const totalPulls = Math.max(1, finiteCount(historyTotalPulls), arms.reduce((sum, arm) => saturatingCountSum(sum, arm.stats.pulls), 0));
+    const ranked = arms.map((arm) => {
+        const pulls = finiteCount(arm.stats.pulls);
+        const meanReward = finiteMeanReward(arm.stats.meanReward);
+        const coldStart = pulls === 0;
+        const bonus = coldStart ? null : Math.sqrt((2 * Math.log(totalPulls)) / pulls);
+        const index = coldStart ? null : meanReward + bonus;
+        return { arm, pulls, meanReward, coldStart, bonus, index };
+    }).sort((left, right) => {
+        if (left.coldStart !== right.coldStart)
+            return left.coldStart ? -1 : 1;
+        if (left.index !== null && right.index !== null && left.index !== right.index)
+            return right.index - left.index;
+        const leftScore = finiteBaseScore(left.arm.baseScore);
+        const rightScore = finiteBaseScore(right.arm.baseScore);
+        return rightScore !== leftScore ? rightScore - leftScore : left.arm.armId.localeCompare(right.arm.armId);
+    });
+    const winner = ranked[0];
+    return {
+        choice: {
+            armId: winner.arm.armId,
+            pulls: winner.pulls,
+            completedPulls: finiteCount(winner.arm.stats.completedPulls),
+            totalPulls,
+            meanReward: winner.meanReward,
+            bonus: winner.bonus,
+            index: winner.index,
+            coldStart: winner.coldStart,
+        },
+    };
+}

package/dist/assetstore/assetSidecarRecords.d.ts

@@ -1,4 +1,4 @@
-import type { AssetSyncRecord } from './assetSyncLedger.js';
+import type { AssetSyncInventorySegmentRecord, AssetSyncRecord, AssetSyncRunRecord } from './assetSyncLedger.js';
 import type { ProvenanceRecord } from './provenance.js';
 import type { ReviewRecord } from './reviewLedger.js';
 export type AssetSidecarKind = 'provenance' | 'review' | 'asset-sync';
@@ -20,4 +20,9 @@ export declare function parseSidecarJsonl<T>(raw: string, parseRecord: (value: u
 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;
+export declare function parseAssetSyncRecord(value: unknown): AssetSyncRecord | null;
+export declare const ASSET_SYNC_INVENTORY_MAX_SEGMENT_BYTES: number;
+export type AssetSyncSidecarRecord = AssetSyncRecord | AssetSyncRunRecord | AssetSyncInventorySegmentRecord;
+export declare function parseAssetSyncRunRecord(value: unknown): AssetSyncRunRecord | null;
+export declare function parseAssetSyncInventorySegmentRecord(value: unknown): AssetSyncInventorySegmentRecord | null;
+export declare function parseAssetSyncSidecarRecord(value: unknown): AssetSyncSidecarRecord | null;

package/dist/assetstore/assetSidecarRecords.js

@@ -62,6 +62,9 @@ export function parseProvenanceRecord(value) {
     const decidedBy = stringField(record, 'decidedBy');
     const promotedBy = stringField(record, 'promotedBy');
     const reason = stringField(record, 'reason');
+    const frozenContentId = stringField(record, 'frozenContentId');
+    if (frozenContentId !== undefined && !/^sha256:[0-9a-f]{64}$/.test(frozenContentId))
+        return null;
     return {
         assetId,
         source,
@@ -71,6 +74,7 @@ export function parseProvenanceRecord(value) {
         ...(decidedBy ? { decidedBy } : {}),
         ...(promotedBy ? { promotedBy } : {}),
         ...(reason ? { reason } : {}),
+        ...(frozenContentId ? { frozenContentId } : {}),
     };
 }
 export function parseReviewRecord(value) {
@@ -116,6 +120,10 @@ export function parseAssetSyncRecord(value) {
     }
     const logicalId = stringField(record, 'logicalId');
     const status = stringField(record, 'status');
+    const runKey = optionalStrictString(record, 'runKey');
+    const inventoryKey = optionalStrictString(record, 'inventoryKey');
+    if (runKey === null || inventoryKey === null)
+        return null;
     const forced = record['forced'] === true;
     const collisionWithAssetId = stringField(record, 'collisionWithAssetId');
     return {
@@ -125,12 +133,223 @@ export function parseAssetSyncRecord(value) {
         scope,
         syncedAt,
         remoteAssetId,
+        ...(runKey ? { runKey } : {}),
+        ...(inventoryKey ? { inventoryKey } : {}),
         ...(logicalId ? { logicalId } : {}),
         ...(status ? { status } : {}),
         ...(forced ? { forced: true } : {}),
         ...(collisionWithAssetId ? { collisionWithAssetId } : {}),
     };
 }
+const MAX_INVENTORY_SEGMENTS = 24;
+const MAX_INVENTORY_ITEMS_PER_SEGMENT = 10_000;
+const MAX_INVENTORY_STRING_LENGTH = 4096;
+export const ASSET_SYNC_INVENTORY_MAX_SEGMENT_BYTES = 2 * 1024 * 1024;
+export function parseAssetSyncRunRecord(value) {
+    const record = objectRecord(value);
+    if (!record || record['recordType'] !== 'run')
+        return null;
+    const runId = optionalStrictString(record, 'runId');
+    const runKey = optionalStrictString(record, 'runKey');
+    const state = optionalStrictString(record, 'state');
+    const currentTimestamp = optionalStrictString(record, 'syncedAt');
+    const legacyTimestamp = optionalStrictString(record, 'at');
+    if (!runId
+        || !runKey
+        || state === null
+        || !isRunState(state)
+        || currentTimestamp === null
+        || legacyTimestamp === null
+        || (currentTimestamp && legacyTimestamp && currentTimestamp !== legacyTimestamp)) {
+        return null;
+    }
+    const syncedAt = currentTimestamp ?? legacyTimestamp;
+    if (!syncedAt || Number.isNaN(Date.parse(syncedAt)))
+        return null;
+    const remoteAssetId = optionalStrictString(record, 'remoteAssetId');
+    const outcomeValue = optionalStrictString(record, 'outcome');
+    const reason = optionalStrictString(record, 'reason');
+    if (remoteAssetId === null || outcomeValue === null || reason === null)
+        return null;
+    const outcome = isRunOutcome(outcomeValue) ? outcomeValue : undefined;
+    if (outcomeValue !== undefined && !outcome)
+        return null;
+    let plan;
+    const rawPlan = record['plan'];
+    if (rawPlan !== undefined) {
+        if (!Array.isArray(rawPlan) || rawPlan.length === 0)
+            return null;
+        const normalized = rawPlan.map((entry) => typeof entry === 'string' ? entry.trim() : '');
+        if (normalized.some((entry, index) => !entry || entry !== rawPlan[index]))
+            return null;
+        if (new Set(normalized).size !== normalized.length)
+            return null;
+        plan = Object.freeze(normalized);
+    }
+    if (state === 'started' && (remoteAssetId || outcome || reason))
+        return null;
+    if (state === 'progress') {
+        if (!remoteAssetId || !outcome || plan)
+            return null;
+        if ((outcome === 'failed') !== Boolean(reason))
+            return null;
+    }
+    if (state === 'completed' && (remoteAssetId || outcome || reason || plan))
+        return null;
+    return immutableRunRecord({
+        recordType: 'run',
+        runId,
+        runKey,
+        state,
+        ...(remoteAssetId ? { remoteAssetId } : {}),
+        ...(outcome ? { outcome } : {}),
+        ...(reason ? { reason } : {}),
+        ...(plan ? { plan } : {}),
+        syncedAt,
+    });
+}
+export function parseAssetSyncInventorySegmentRecord(value) {
+    const record = objectRecord(value);
+    if (!record || record['recordType'] !== 'inventory_scan')
+        return null;
+    try {
+        if (Buffer.byteLength(JSON.stringify(record), 'utf8') > ASSET_SYNC_INVENTORY_MAX_SEGMENT_BYTES)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const scanId = strictBoundedString(record['scanId']);
+    const inventoryKey = strictBoundedString(record['inventoryKey']);
+    const scope = strictBoundedString(record['scope']);
+    const syncedAt = strictBoundedString(record['syncedAt']);
+    const index = record['index'];
+    const inputCursorFingerprints = parseInventoryCursorFingerprints(record['inputCursorFingerprints']);
+    const nextCursorFingerprints = parseInventoryCursorFingerprints(record['nextCursorFingerprints']);
+    const anonymousBlocked = record['anonymousBlocked'];
+    const cursorHeld = record['cursorHeld'];
+    const batchId = record['batchId'];
+    const batchIndex = record['batchIndex'];
+    const batchSize = record['batchSize'];
+    const rawItems = record['items'];
+    const hasBatchMetadata = batchId !== undefined || batchIndex !== undefined || batchSize !== undefined;
+    if (!scanId
+        || !inventoryKey
+        || (scope !== 'purchased' && scope !== 'published' && scope !== 'all')
+        || !syncedAt
+        || Number.isNaN(Date.parse(syncedAt))
+        || !Number.isInteger(index)
+        || index < 0
+        || index >= MAX_INVENTORY_SEGMENTS
+        || !inputCursorFingerprints
+        || !nextCursorFingerprints
+        || !Number.isInteger(anonymousBlocked)
+        || anonymousBlocked < 0
+        || anonymousBlocked > MAX_INVENTORY_ITEMS_PER_SEGMENT
+        || !Array.isArray(rawItems)
+        || rawItems.length > MAX_INVENTORY_ITEMS_PER_SEGMENT
+        || (cursorHeld !== undefined && cursorHeld !== true)
+        || (hasBatchMetadata && (!strictBoundedString(batchId)
+            || !Number.isInteger(batchIndex)
+            || !Number.isInteger(batchSize)
+            || batchSize < 2
+            || batchSize > MAX_INVENTORY_SEGMENTS
+            || batchIndex < 0
+            || batchIndex >= batchSize
+            || index - batchIndex < 0
+            || index + (batchSize - batchIndex) > MAX_INVENTORY_SEGMENTS))) {
+        return null;
+    }
+    if (scope === 'purchased'
+        && (inputCursorFingerprints.published !== null || nextCursorFingerprints.published !== null))
+        return null;
+    if (cursorHeld === true
+        && (inputCursorFingerprints.purchased !== nextCursorFingerprints.purchased
+            || inputCursorFingerprints.published !== nextCursorFingerprints.published))
+        return null;
+    if (scope === 'published'
+        && (inputCursorFingerprints.purchased !== null || nextCursorFingerprints.purchased !== null))
+        return null;
+    if (index === 0
+        && (inputCursorFingerprints.purchased !== null || inputCursorFingerprints.published !== null))
+        return null;
+    const items = [];
+    const seen = new Set();
+    for (const rawItem of rawItems) {
+        const item = objectRecord(rawItem);
+        if (!item)
+            return null;
+        const remoteAssetId = strictBoundedString(item['remoteAssetId']);
+        const outcome = strictBoundedString(item['outcome']);
+        if (!remoteAssetId || !isInventoryOutcome(outcome) || seen.has(remoteAssetId))
+            return null;
+        seen.add(remoteAssetId);
+        items.push(Object.freeze({ remoteAssetId, outcome }));
+    }
+    if (items.length + anonymousBlocked > MAX_INVENTORY_ITEMS_PER_SEGMENT)
+        return null;
+    return Object.freeze({
+        recordType: 'inventory_scan',
+        scanId,
+        inventoryKey,
+        scope,
+        index: index,
+        inputCursorFingerprints,
+        nextCursorFingerprints,
+        items: Object.freeze(items),
+        anonymousBlocked: anonymousBlocked,
+        ...(cursorHeld === true ? { cursorHeld: true } : {}),
+        ...(hasBatchMetadata ? {
+            batchId: batchId,
+            batchIndex: batchIndex,
+            batchSize: batchSize,
+        } : {}),
+        syncedAt,
+    });
+}
+export function parseAssetSyncSidecarRecord(value) {
+    const record = objectRecord(value);
+    if (!record)
+        return null;
+    if (record['recordType'] !== undefined) {
+        if (record['recordType'] === 'run')
+            return parseAssetSyncRunRecord(record);
+        if (record['recordType'] === 'inventory_scan')
+            return parseAssetSyncInventorySegmentRecord(record);
+        return null;
+    }
+    return parseAssetSyncRecord(record);
+}
+function parseInventoryCursorFingerprints(value) {
+    const record = objectRecord(value);
+    if (!record || !Object.hasOwn(record, 'purchased') || !Object.hasOwn(record, 'published'))
+        return null;
+    const purchased = strictNullableCursorFingerprint(record['purchased']);
+    const published = strictNullableCursorFingerprint(record['published']);
+    if (purchased === undefined || published === undefined)
+        return null;
+    return Object.freeze({ purchased, published });
+}
+function strictNullableCursorFingerprint(value) {
+    if (value === null)
+        return null;
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value) ? value : undefined;
+}
+function strictBoundedString(value) {
+    return typeof value === 'string'
+        && value.length <= MAX_INVENTORY_STRING_LENGTH
+        && value.trim()
+        && value === value.trim()
+        ? value
+        : undefined;
+}
+function isInventoryOutcome(value) {
+    return value === 'imported'
+        || value === 'already_local'
+        || value === 'blocked'
+        || value === 'failed'
+        || value === 'pending';
+}
 function objectRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -139,4 +358,23 @@ function objectRecord(value) {
 function stringField(value, key) {
     const raw = value[key];
     return typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+}
+function optionalStrictString(value, key) {
+    const raw = value[key];
+    if (raw === undefined)
+        return undefined;
+    return typeof raw === 'string' && raw.trim() && raw === raw.trim() ? raw : null;
+}
+function immutableRunRecord(record) {
+    const plan = record.plan ? Object.freeze([...record.plan]) : undefined;
+    return Object.freeze({ ...record, ...(plan ? { plan } : {}) });
+}
+function isRunState(value) {
+    return value === 'started' || value === 'progress' || value === 'completed';
+}
+function isRunOutcome(value) {
+    return value === 'imported'
+        || value === 'already_local'
+        || value === 'failed'
+        || value === 'remote_missing';
 }