import { MemoryFrontmatter } from './types.js';
import './index-1qIcnbG1.js';

/**
 * Temporal validity helpers (issue #680).
 *
 * `valid_at` / `invalid_at` are explicit ISO 8601 timestamps that mark when a
 * fact begins and ends being authoritative.  These helpers centralize the
 * read-time defaulting rules so every call site (recall filter, supersession
 * write, tests) agrees on the canonical semantics:
 *
 *   - `effectiveValidAt(fm)` — the moment this fact starts being true.
 *     Falls back to `created` when `valid_at` is absent so legacy memories
 *     written before #680 still participate in `as_of` filtering without
 *     a backfill migration.
 *   - `effectiveInvalidAt(fm)` — the moment this fact stops being true.
 *     Returns `undefined` when no `invalid_at` is set; supersession logic
 *     populates it on the older fact when a newer one replaces it.
 *   - `isValidAsOf(fm, asOfMs)` — true when the fact was authoritative at
 *     `asOfMs` (a numeric timestamp in ms).  Half-open interval semantics:
 *     `valid_at <= asOf < invalid_at`.  Strings are parsed via
 *     `Date.parse()` so timezone-suffixed ISO strings compare correctly
 *     (CLAUDE.md gotcha — never compare ISO strings lexicographically).
 *
 * Boundary case: when `invalid_at === asOf`, the fact is treated as NOT
 * valid (the upper bound is exclusive), which matches the supersession
 * model — at the instant a successor's `valid_at` fires, the predecessor
 * is no longer authoritative.
 */

declare function effectiveValidAt(fm: Pick<MemoryFrontmatter, "valid_at" | "created">): string;
declare function effectiveInvalidAt(fm: Pick<MemoryFrontmatter, "invalid_at" | "supersededAt" | "status">): string | undefined;
/**
 * Returns true when the fact was authoritative at `asOfMs` (parsed
 * milliseconds since epoch).  Half-open semantics: a fact is valid in
 * `[valid_at, invalid_at)`.
 *
 * If `valid_at` cannot be parsed, the fact is conservatively treated as
 * NOT valid at the requested point — we never silently default a corrupt
 * timestamp to "always true" because that would let bad data leak past
 * the historical filter (CLAUDE.md gotcha #34: distinguish empty from
 * malformed).
 */
declare function isValidAsOf(fm: Pick<MemoryFrontmatter, "valid_at" | "invalid_at" | "created" | "supersededAt" | "status">, asOfMs: number): boolean;
/**
 * Parse and validate an `as_of` value supplied at an input boundary
 * (CLI flag, HTTP query param, MCP field).  Returns parsed milliseconds
 * on success; throws a `RangeError` with a helpful message on malformed
 * input.  CLAUDE.md rule 51 — never silently default invalid input.
 */
declare function parseAsOfTimestamp(raw: unknown): number;

export { effectiveInvalidAt, effectiveValidAt, isValidAsOf, parseAsOfTimestamp };
