/**
 * Drift comparison service — fleet-general write integrity layer
 * (item-3-snapshot-export).
 *
 * Compares a canonical Neotoma snapshot export against any external
 * state source via a pluggable `ExternalParser` interface. v0.1 ships
 * with the identity JSON parser; fleet-specific parsers (AIBTC
 * MEMORY.md ASMR, LangGraph state dumps, internal SQLite mirrors)
 * register via {@link registerExternalParser} without touching core.
 *
 * Output contract:
 *   * `missing_in_neotoma` — entities the external source knows about
 *     but Neotoma does not (by `entity_id`).
 *   * `missing_in_external` — entities Neotoma has but the external
 *     source does not.
 *   * `field_diffs` — per-field value disagreements for entities
 *     present in both.
 *   * `provenance_gaps` — entities with concerning provenance posture
 *     (unclassified observation_source, anonymous/unverified
 *     attribution) even when values agree.
 *
 * Design notes:
 *   * Deliberately does NOT care which side is "right" — the report is
 *     symmetric and the caller decides how to reconcile.
 *   * Parsers are pure functions (raw string → normalised shape) so
 *     they're easy to unit test and swap. Core does not import any
 *     fleet-specific code.
 */
import type { ExportedEntitySnapshot, SnapshotExportDocument } from "./snapshot_export.js";
/** Normalised shape every parser must return. */
export interface NormalizedExternalSnapshot {
    source_label: string;
    exported_at?: string;
    entities: NormalizedExternalEntity[];
}
export interface NormalizedExternalEntity {
    entity_id: string;
    entity_type?: string;
    canonical_name?: string | null;
    snapshot: Record<string, unknown>;
}
export interface ExternalParser {
    /** Short identifier used by the CLI flag and the registry. */
    name: string;
    /** Human-readable description for docs / help output. */
    description: string;
    /** Pure transform from raw payload string to normalised shape. */
    parse(raw: string): NormalizedExternalSnapshot;
}
export interface DriftReport {
    schema_version: "0.1.0";
    generated_at: string;
    neotoma_source: string;
    external_source: string;
    summary: {
        total_neotoma: number;
        total_external: number;
        in_common: number;
        missing_in_neotoma: number;
        missing_in_external: number;
        field_diffs: number;
        provenance_gaps: number;
    };
    missing_in_neotoma: NormalizedExternalEntity[];
    missing_in_external: ExportedEntitySnapshot[];
    field_diffs: FieldDiff[];
    provenance_gaps: ProvenanceGap[];
}
export interface FieldDiff {
    entity_id: string;
    entity_type?: string;
    field: string;
    neotoma_value: unknown;
    external_value: unknown;
    neotoma_source_observation_id?: string;
}
export interface ProvenanceGap {
    entity_id: string;
    entity_type: string;
    reasons: ProvenanceGapReason[];
}
export type ProvenanceGapReason = "unclassified_observation_source" | "anonymous_attribution" | "unverified_client_attribution";
export declare function registerExternalParser(parser: ExternalParser): void;
export declare function getExternalParser(name: string): ExternalParser | undefined;
export declare function listExternalParsers(): ExternalParser[];
/**
 * Built-in identity JSON parser. Accepts either a bare array of
 * {@link NormalizedExternalEntity} or an object `{ entities: [...] }`.
 * Keeps the exporter round-trip-safe: calling `diff(export, export)`
 * with this parser produces an empty report.
 */
export declare const identityJsonParser: ExternalParser;
export declare function compareSnapshots(neotomaExport: SnapshotExportDocument, externalSnapshot: NormalizedExternalSnapshot): DriftReport;
//# sourceMappingURL=drift_comparison.d.ts.map