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

package/dist/assetrepair/repair.d.ts

@@ -0,0 +1,33 @@
+import type { AssetRecord } from '../assetstore/index.js';
+export type RepairStatus = 'already_valid' | 'repaired' | 'unrepairable';
+export interface RepairIssue {
+    path: string;
+    keyword: string;
+    message: string;
+    /** `schema` = found by the local gep-sdk gate; `hub` = reported by the network in its rejection body. */
+    source: 'schema' | 'hub';
+}
+export interface RepairChange {
+    path: string;
+    action: 'added' | 'removed' | 'replaced';
+    note: string;
+}
+export interface RepairReport {
+    status: RepairStatus;
+    /** The accepted-by-schema record. Absent only when blockers remain (`status: 'unrepairable'`). */
+    asset?: AssetRecord;
+    changes: RepairChange[];
+    blockers: RepairIssue[];
+}
+export interface RepairOptions {
+    /** Field-level issues the network itself reported — see `hubRejectionIssues`. Stricter than the GEP schema
+     *  (the Hub adds envelope rules of its own), so they are folded in rather than re-derived locally. */
+    hubIssues?: readonly RepairIssue[];
+}
+type JsonRecord = Record<string, unknown>;
+/**
+ * Repair `input` into a record the GEP schema (and, when supplied, the Hub's own rules) accepts.
+ * Pure: `input` is never mutated, and nothing is written anywhere — the caller decides what to do with the result.
+ */
+export declare function repairAssetRecord(input: JsonRecord, options?: RepairOptions): RepairReport;
+export {};

package/dist/assetrepair/repair.js

@@ -0,0 +1,155 @@
+// Asset repair — turn a GEP record the network refuses into one it accepts, WITHOUT inventing content.
+//
+// Two producers of refused records exist and both were wasting assets outright:
+//   * publish: the Hub rejects a bundle field-by-field (`details[]`), the operator gets a flat error, and the
+//     distilled asset is dropped on the floor.
+//   * reuse/fetch: the Hub delivers a lossy projection of a published record (dropped `schema_version`, dropped
+//     logical `id`, emptied `constraints.forbidden_paths`, extra non-schema keys such as `model_name`), which
+//     then fails the local wire gate and is discarded — reported to the operator as "not found".
+//
+// The line this module refuses to cross: a repair may only restore fields whose value is DERIVABLE (recomputed
+// `asset_id`), CONSTANT (`schema_version`), or a strictly-narrowing default (`constraints`). Anything carrying
+// an evidence or meaning claim — a Capsule's `outcome`/`confidence`/`blast_radius`, a Gene's `strategy`, a
+// human summary — is never fabricated: it is reported as a blocker so the operator (or a re-distill) supplies it.
+import { computeAssetId, wireSchemaIssues } from '../wire/index.js';
+import { SCHEMA_VERSION } from '@evomap/gep-sdk';
+const DEFAULT_MAX_FILES = 12;
+const DEFAULT_FORBIDDEN_PATHS = ['.git', 'node_modules'];
+const CONTENT_ASSET_ID = /^sha256:[0-9a-f]{64}$/;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+/**
+ * Repair `input` into a record the GEP schema (and, when supplied, the Hub's own rules) accepts.
+ * Pure: `input` is never mutated, and nothing is written anywhere — the caller decides what to do with the result.
+ */
+export function repairAssetRecord(input, options = {}) {
+    const hubIssues = options.hubIssues ?? [];
+    const before = wireSchemaIssues(input);
+    if (before.length === 0 && hubIssues.length === 0 && assetIdIsCurrent(input)) {
+        return { status: 'already_valid', asset: input, changes: [], blockers: [] };
+    }
+    const changes = [];
+    const draft = { ...input };
+    restoreSchemaVersion(draft, changes);
+    dropUnknownProperties(draft, before, changes);
+    restoreGeneConstraints(draft, changes);
+    restoreLogicalId(draft, changes);
+    restoreAssetId(draft, changes);
+    const remaining = wireSchemaIssues(draft);
+    const blockers = [...remaining.map(schemaBlocker), ...unresolvedHubIssues(hubIssues, changes)];
+    if (blockers.length > 0)
+        return { status: 'unrepairable', changes, blockers };
+    return { status: 'repaired', asset: draft, changes, blockers: [] };
+}
+/**
+ * Hub rules the local schema cannot see (a minimum summary length, a bundle arity) stay blockers — but a hub
+ * complaint about a field this pass just mended is answered, and keeping it would report every repairable
+ * asset as unrepairable.
+ */
+function unresolvedHubIssues(issues, changes) {
+    return issues.filter((issue) => !changes.some((change) => pathsOverlap(change.path, issue.path)));
+}
+function pathsOverlap(repaired, reported) {
+    return repaired === reported
+        || reported.startsWith(`${repaired}.`)
+        || repaired.startsWith(`${reported}.`);
+}
+/** True when the record already declares the id its own content hashes to — the invariant `restoreAssetId` holds. */
+function assetIdIsCurrent(record) {
+    const declared = record['asset_id'];
+    return typeof declared === 'string' && declared === safeComputeAssetId(record);
+}
+function restoreSchemaVersion(draft, changes) {
+    const current = draft['schema_version'];
+    if (typeof current === 'string' && SEMVER.test(current))
+        return;
+    draft['schema_version'] = SCHEMA_VERSION;
+    changes.push({
+        path: 'schema_version',
+        action: current === undefined ? 'added' : 'replaced',
+        note: `set to the SDK schema version ${SCHEMA_VERSION}`,
+    });
+}
+// `additionalProperties: false` means an unknown key is fatal, so a delivery that adds `model_name` is
+// unusable as-is. Dropping is the only content-preserving move: the key is not part of the GEP contract, so
+// nothing that reads the record by contract can miss it. Every dropped key is named in the report.
+function dropUnknownProperties(draft, issues, changes) {
+    for (const issue of issues) {
+        if (issue.keyword !== 'additionalProperties' || !issue.property)
+            continue;
+        if (!(issue.property in draft))
+            continue;
+        delete draft[issue.property];
+        changes.push({ path: issue.path, action: 'removed', note: 'not declared by the GEP schema' });
+    }
+}
+// A Gene's constraints are a CEILING on what an executing agent may touch. Restoring the default is therefore
+// safe in one direction only: the default must be at least as restrictive as a missing/empty value, which
+// (no ceiling at all) it always is.
+function restoreGeneConstraints(draft, changes) {
+    if (draft['type'] !== 'Gene')
+        return;
+    const current = asRecord(draft['constraints']);
+    if (!current) {
+        draft['constraints'] = { max_files: DEFAULT_MAX_FILES, forbidden_paths: [...DEFAULT_FORBIDDEN_PATHS] };
+        changes.push({ path: 'constraints', action: 'added', note: 'restored the default execution ceiling' });
+        return;
+    }
+    const repaired = { ...current };
+    const maxFiles = repaired['max_files'];
+    if (typeof maxFiles !== 'number' || !Number.isInteger(maxFiles) || maxFiles < 1) {
+        repaired['max_files'] = DEFAULT_MAX_FILES;
+        changes.push({ path: 'constraints.max_files', action: maxFiles === undefined ? 'added' : 'replaced', note: `restored the default ceiling ${DEFAULT_MAX_FILES}` });
+    }
+    const forbidden = repaired['forbidden_paths'];
+    const usable = Array.isArray(forbidden) && forbidden.length > 0 && forbidden.every((entry) => typeof entry === 'string');
+    if (!usable) {
+        repaired['forbidden_paths'] = [...DEFAULT_FORBIDDEN_PATHS];
+        changes.push({ path: 'constraints.forbidden_paths', action: forbidden === undefined ? 'added' : 'replaced', note: 'restored the default forbidden paths' });
+    }
+    draft['constraints'] = repaired;
+}
+// A logical id names the asset for humans and for Capsule→Gene binding; it carries no claim about the content.
+// A delivery that dropped it cannot be re-bound to its original name (that name is not recoverable from the
+// bytes), so the derived one is marked `repaired_` — visibly synthetic, and stable for the same content.
+function restoreLogicalId(draft, changes) {
+    const current = draft['id'];
+    if (typeof current === 'string' && current.length > 0)
+        return;
+    const type = typeof draft['type'] === 'string' ? draft['type'].toLowerCase() : 'asset';
+    const digest = safeComputeAssetId(draft)?.slice('sha256:'.length, 'sha256:'.length + 12);
+    if (!digest)
+        return;
+    draft['id'] = `${type}_repaired_${digest}`;
+    changes.push({ path: 'id', action: 'added', note: 'derived a stable placeholder id from the content digest' });
+}
+// Content-addressing means `asset_id` is a FUNCTION of the rest of the record, so it is the one field that must
+// be recomputed last — every repair above changes what the content hashes to.
+function restoreAssetId(draft, changes) {
+    const declared = draft['asset_id'];
+    const computed = safeComputeAssetId(draft);
+    if (!computed || !CONTENT_ASSET_ID.test(computed))
+        return;
+    if (declared === computed)
+        return;
+    draft['asset_id'] = computed;
+    changes.push({
+        path: 'asset_id',
+        action: typeof declared === 'string' ? 'replaced' : 'added',
+        note: 'recomputed the content id over the repaired record',
+    });
+}
+function safeComputeAssetId(record) {
+    try {
+        const id = computeAssetId(record);
+        return typeof id === 'string' && id.length > 0 ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function schemaBlocker(issue) {
+    return { path: issue.path, keyword: issue.keyword, message: issue.message, source: 'schema' };
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}

package/dist/assetstore/assetSidecarRecords.d.ts

@@ -0,0 +1,28 @@
+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';
+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;
+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

@@ -0,0 +1,384 @@
+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');
+    const frozenContentId = stringField(record, 'frozenContentId');
+    if (frozenContentId !== undefined && !/^sha256:[0-9a-f]{64}$/.test(frozenContentId))
+        return null;
+    return {
+        assetId,
+        source,
+        trusted: record['trusted'],
+        at,
+        ...(decision ? { decision } : {}),
+        ...(decidedBy ? { decidedBy } : {}),
+        ...(promotedBy ? { promotedBy } : {}),
+        ...(reason ? { reason } : {}),
+        ...(frozenContentId ? { frozenContentId } : {}),
+    };
+}
+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 = rawStringField(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 {
+        assetId,
+        type,
+        source,
+        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
+        : null;
+}
+function stringField(value, key) {
+    const raw = value[key];
+    return typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+}
+function rawStringField(value, key) {
+    const raw = value[key];
+    return typeof raw === 'string' && raw.length > 0 ? raw : 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';
+}

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;