@jinn-network/core 0.1.0

package/dist/evidence-index.d.ts

@@ -0,0 +1,117 @@
+import { type EpisodeV1 } from '@jinn-network/plugin';
+export type EvidenceSourceKind = 'canonical-episode' | 'misnamed-episode' | 'legacy-capture';
+export type EvidenceOriginKind = 'stamped' | 'legacy-unstamped';
+export interface IndexedEpisode {
+    episodeId: string;
+    sessionId: string;
+    capturedAt: string;
+    sourcePath: string;
+    sourceKind: EvidenceSourceKind;
+    originKind: EvidenceOriginKind;
+    originWriter?: string;
+    originBuild?: string;
+    outcomeStatus: EpisodeV1['outcome']['status'];
+    verificationStrength: EpisodeV1['outcome']['verificationStrength'];
+    durationMs: number;
+    activity: EpisodeV1['activity'] | null;
+    episode: EpisodeV1;
+    contentSha256: string;
+}
+export interface UnreadableEvidence {
+    sourcePath: string;
+    reason: string;
+}
+export interface ExcludedEvidence {
+    sourcePath: string;
+    episodeId: string;
+    rule: 'legacy-short-session-placeholder-model-v1' | 'legacy-known-smoke-payload-v1';
+    reason: string;
+    contentSha256: string;
+}
+export type ReindexMutation = {
+    kind: 'normalized-json';
+    sourcePath: string;
+    nullFieldsRemoved: number;
+} | {
+    kind: 'normalization-recovery-retained';
+    sourcePath: string;
+    journalPath: string;
+} | {
+    kind: 'rescued-misnamed-episode';
+    sourcePath: string;
+    targetPath: string;
+} | {
+    kind: 'rescue-target-published';
+    sourcePath: string;
+    targetPath: string;
+};
+export interface ReindexReport {
+    scannedFiles: number;
+    indexedEpisodes: number;
+    unreadableFiles: number;
+    unreadable: Array<{
+        path: string;
+        reason: string;
+    }>;
+    nullToleratedFiles: number;
+    nullFieldsRemoved: number;
+    misnamedEpisodes: number;
+    renamedFiles: number;
+    legacyUnstampedFiles: number;
+    syntheticExcludedFiles: number;
+    syntheticExcluded: Array<{
+        path: string;
+        episodeId: string;
+        rule: ExcludedEvidence['rule'];
+        reason: string;
+    }>;
+    mutations: ReindexMutation[];
+    /** False for inspection and for a failed derived-index publication. */
+    indexUpdated: boolean;
+    /** Present only when source scanning/repair completed but publication failed. */
+    indexError?: string;
+}
+export interface ReindexEvidenceStoreOptions {
+    episodesDir: string;
+    indexPath: string;
+    repair?: boolean;
+    /** @internal Deterministic concurrency-test seam; called while the store lock is held. */
+    onScanComplete?: () => void;
+    /** @internal Race-regression seam; called after a source descriptor is pinned. */
+    onBeforeSourceMutation?: (kind: 'normalize' | 'rescue-remove', sourcePath: string) => void;
+}
+export interface InspectEvidenceStoreOptions {
+    episodesDir: string;
+}
+export declare function defaultEvidenceIndexPath(episodesDir: string): string;
+/**
+ * The affected operator files carry null in exactly these four optional
+ * fields (#1811). Keep required nullable fields (notably parentSpanId) intact.
+ */
+export declare function tolerateNullQuartet(value: unknown): {
+    value: unknown;
+    removed: number;
+};
+export interface EvidenceIndexOptions {
+    dbPath: string;
+    /** Only the default dedicated state parent is safe to normalize to 0700. */
+    secureParent?: boolean;
+}
+export declare class EvidenceIndex {
+    private readonly db;
+    private readonly dbPath;
+    private readonly dbIdentity;
+    constructor(options: EvidenceIndexOptions);
+    journalMode(): string;
+    replace(rows: IndexedEpisode[], unreadable: UnreadableEvidence[], excluded: ExcludedEvidence[]): void;
+    listEpisodes(): IndexedEpisode[];
+    listUnreadable(): UnreadableEvidence[];
+    listExcluded(): ExcludedEvidence[];
+    close(): void;
+}
+/**
+ * Read-only store inspection for doctor/status surfaces. It deliberately
+ * shares the reindex scanner while neither opening SQLite nor repairing files.
+ */
+export declare function inspectEvidenceStore(options: InspectEvidenceStoreOptions): ReindexReport;
+export declare function reindexEvidenceStore(options: ReindexEvidenceStoreOptions): ReindexReport;