/**
 * Timeline event derivation from entity snapshots.
 * Creates timeline_events rows from date fields in entity snapshots (structured store and interpretation paths).
 */
import type { SchemaDefinition } from "./schema_registry.js";
/**
 * Normalize a value to an ISO date string for event_timestamp, or null if not a valid date.
 *
 * Strict: strings must match a known date-shape regex before being parsed with
 * `new Date(...)`. This prevents arbitrary strings like "1.0", "usd", "unknown",
 * or free-text descriptions from producing spurious timeline events.
 */
export declare function toISODate(value: unknown): string | null;
export interface TimelineEventRow {
    id: string;
    event_type: string;
    event_timestamp: string;
    source_id: string;
    source_field: string;
    entity_id: string | null;
    created_at: string;
    user_id: string;
}
/**
 * Generate a deterministic timeline event id from (source_id, entity_id, source_field, event_timestamp).
 * Returns a UUID-format string (8-4-4-4-12) for compatibility with timeline_events.id (UUID).
 */
export declare function generateTimelineEventId(sourceId: string, entityId: string, sourceField: string, eventTimestamp: string): string;
/**
 * From a record of unknown (e.g. non-schema) fields, return only those that are date-like:
 * key is a known date field name, or value parses as a date (see toISODate).
 * Used for timeline derivation and for merging unknown date-like keys into observations.
 */
export declare function getDateLikeFields(fields: Record<string, unknown>): Record<string, unknown>;
/**
 * Derive timeline events from an entity snapshot.
 *
 * Precedence:
 * - When `schema.temporal_fields` is declared, only those fields emit timeline
 *   events, and their declared `event_type` (if any) is used.
 * - Otherwise, fall back to the heuristic: DATE_FIELD_NAMES or any top-level
 *   value that parses as a date (excluding TIMELINE_SNAPSHOT_FIELD_DENYLIST).
 */
export declare function deriveTimelineEventsFromSnapshot(entityType: string, entityId: string, sourceId: string, userId: string, snapshot: Record<string, unknown>, schema?: Pick<SchemaDefinition, "temporal_fields"> | null): TimelineEventRow[];
/**
 * Derive additional timeline events from raw_fragments (date-like keys not already in snapshot).
 *
 * When `schema.temporal_fields` is declared, only those fields are considered;
 * otherwise the legacy heuristic (DATE_FIELD_NAMES / parses-as-date) applies.
 * Use when there is exactly one entity of this type in the source so fragments
 * can be attributed.
 */
export declare function deriveTimelineEventsFromRawFragments(rawFragments: Array<{
    fragment_key: string;
    fragment_value: unknown;
}>, entityType: string, entityId: string, sourceId: string, userId: string, snapshotFieldKeys: Set<string>, schema?: Pick<SchemaDefinition, "temporal_fields"> | null): TimelineEventRow[];
export interface UpsertTimelineEventsForSnapshotParams {
    entityType: string;
    entityId: string;
    sourceId: string;
    userId: string;
    snapshot: Record<string, unknown>;
    /**
     * When exactly 1, also derive from raw_fragments for this source_id + entity_type (matches structured store).
     * Use &gt;1 when multiple entities of the same type share one source in the same batch (avoids mis-attribution).
     */
    sameTypeInSourceBatch: number;
    /**
     * Optional schema definition. When `temporal_fields` is declared, timeline
     * emission is restricted to those fields (schema-driven). When absent, falls
     * back to the legacy date-like-field heuristic.
     */
    schema?: Pick<SchemaDefinition, "temporal_fields"> | null;
}
/**
 * Derive timeline rows from snapshot (and optionally raw_fragments) and upsert into timeline_events.
 * Shared by structured store, interpretation, and snapshot recomputation.
 */
export declare function upsertTimelineEventsForEntitySnapshot(params: UpsertTimelineEventsForSnapshotParams): Promise<void>;
//# sourceMappingURL=timeline_events.d.ts.map