@lovelaces-io/storyteller 0.3.0 → 0.4.0

package/dist/stories-BgN4BSoZ.d.cts

@@ -0,0 +1,744 @@
+/**
+ * Which default audience a storyteller registers.
+ *
+ * - `text` — colorized console output for a person watching
+ * - `ndjson` — one JSON object per line for a program reading
+ */
+type OutputFormat = "text" | "ndjson";
+/**
+ * A level written any of the ways people and agents actually write it.
+ * `report("...", { level: "warn" })` should not be a type error.
+ */
+type LevelInput = StoryLevel | "info" | "information" | "warn" | "warning" | "oops" | "error";
+/**
+ * Resolve any accepted level spelling to a stored level label.
+ *
+ * @param input - A level in any accepted spelling
+ * @returns The canonical StoryLevel, defaulting to Information
+ */
+declare function toStoryLevel(input?: LevelInput): StoryLevel;
+/**
+ * Read an environment variable, tolerating runtimes that have no environment at all.
+ *
+ * @param name - Variable name
+ * @returns The trimmed value, or undefined when unset or unavailable
+ */
+declare function readEnvironmentValue(name: string): string | undefined;
+/**
+ * Resolve the minimum level to deliver, from an explicit option then `STORYTELLER_LEVEL`.
+ *
+ * @param requested - Explicit level, if the caller set one
+ * @returns The threshold level, defaulting to Information (deliver everything)
+ */
+declare function resolveMinimumLevel(requested?: StoryLevel | string): StoryLevel;
+/**
+ * Check whether a level clears the configured minimum.
+ *
+ * @param level - The emission's level
+ * @param minimum - The configured threshold
+ */
+declare function meetsLevel(level: StoryLevel, minimum: StoryLevel): boolean;
+/**
+ * Resolve which default audience to register, from an explicit option then
+ * `STORYTELLER_FORMAT`.
+ *
+ * Deliberately not inferred from whether stdout is a TTY: output that silently
+ * changes shape when a process is piped is a debugging afternoon nobody asked for.
+ *
+ * @param requested - Explicit format, if the caller set one
+ * @returns The format, defaulting to text
+ */
+declare function resolveOutputFormat(requested?: OutputFormat): OutputFormat;
+/**
+ * Resolve whether to colorize, from an explicit option then `STORYTELLER_COLOR`.
+ *
+ * @param requested - Explicit choice, if the caller set one
+ * @returns Whether colors should be used, defaulting to true
+ */
+declare function resolveColors(requested?: boolean): boolean;
+
+/**
+ * Redaction by value, not only by key.
+ *
+ * Key-name matching catches `password: "hunter2"`. It does not catch a Stripe
+ * key inside an error message, a bearer token in a URL, or a private key
+ * pasted into a note. Once stories are persisted and read back by agents, a
+ * leaked secret is durable and retrievable, so the value itself has to be
+ * recognised too.
+ *
+ * Defense in depth, not a guarantee: these are recognisable formats and
+ * suspicious positions. A secret that looks like an ordinary word passes.
+ * The balance leans toward keeping records readable — a viewer full of
+ * `[redacted]` is no viewer — with a strict mode for the other trade.
+ */
+
+/** Marker written in place of a redacted value or span */
+declare const REDACTED = "[redacted]";
+/** How hard to look inside values. `off` leaves key matching only. */
+type RedactionStrictness = "off" | "balanced" | "strict";
+
+/** A value that survives JSON.stringify with no loss and no throwing */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type NormalizeOptions = {
+    /** How many levels deep to descend before replacing the value with a truncation marker */
+    maxDepth?: number;
+    /** How many array entries to keep before truncating */
+    maxArrayLength?: number;
+    /** How many object properties to keep before truncating */
+    maxProperties?: number;
+    /** How many characters of a string to keep before truncating */
+    maxStringLength?: number;
+    /** Property names whose values are replaced with the redaction marker */
+    redactKeys?: string[];
+    /** Set false to keep secret-shaped values as-is */
+    redact?: boolean;
+    /**
+     * How hard to look inside values for secrets: `balanced` (default) redacts
+     * recognisable token formats and random-looking strings under secret-shaped
+     * keys; `strict` also redacts any long random-looking run; `off` matches key
+     * names only.
+     */
+    redactValues?: RedactionStrictness;
+};
+
+/**
+ * Property names whose values are replaced with {@link REDACTED}.
+ * Matching ignores case and separators, so `apiKey`, `api_key` and `API-KEY` all match.
+ */
+declare const DEFAULT_REDACT_KEYS: string[];
+/**
+ * Convert any value into a JSON-safe structure suitable for a story record.
+ *
+ * Handles the shapes real code actually holds — errors, dates, maps, sets, class
+ * instances, binary buffers, circular references, throwing getters — and never throws,
+ * so a hostile object logged by a caller cannot break the delivery pipeline.
+ *
+ * Data dropped for size is replaced with an explicit `@truncated` marker rather than
+ * disappearing silently, so a consumer can tell the difference between "this was empty"
+ * and "this was too big".
+ *
+ * @param input - Any value
+ * @param options - Depth, size and redaction limits
+ * @returns A value that JSON.stringify can always serialize
+ *
+ * @example
+ * ```ts
+ * normalizeValue({ user: new Map([["id", 1]]), apiKey: "sk-live-abc" });
+ * // { user: { "@type": "Map", entries: { id: 1 } }, apiKey: "[redacted]" }
+ * ```
+ */
+declare function normalizeValue(input: unknown, options?: NormalizeOptions): JsonValue;
+/**
+ * Convert an unknown thrown value into a serializable StoryError,
+ * following the `cause` chain and collecting AggregateError members.
+ *
+ * @param rawError - Any thrown or rejected value
+ * @param options - Depth, size and redaction limits applied to attached data
+ * @returns A StoryError safe to store and serialize
+ */
+declare function normalizeError(rawError: unknown, options?: NormalizeOptions): StoryError;
+
+/** Human-readable level labels stored in story records */
+type StoryLevel = "Information" | "Warning" | "Error";
+/**
+ * A stored context value. Always JSON-safe — whatever the caller passed in has
+ * already been through the normalizer by the time it reaches a record.
+ */
+type StoryContextValue = JsonValue;
+/** Context accepted from callers. Anything goes; the normalizer makes it storable. */
+type StoryContextInput = unknown;
+type StoryError = {
+    name?: string;
+    message?: string;
+    stack?: string;
+    cause?: JsonValue;
+    /** Members of an AggregateError */
+    errors?: StoryError[];
+};
+/** Origin as stored on a record */
+type StoryOrigin = {
+    who?: StoryContextValue;
+    what?: StoryContextValue;
+    where?: StoryContextValue;
+};
+/** Origin as accepted from callers */
+type StoryOriginInput = {
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
+};
+type StoryNote = {
+    timestamp: string;
+    /**
+     * Position within the story, assigned when the note is taken. Gap-free from 0.
+     * Optional so records written before sequencing existed still typecheck.
+     */
+    sequence?: number;
+    note: string;
+    /** Omitted when the note carries the story's default Information level */
+    level?: StoryLevel;
+    who?: StoryContextValue;
+    what?: StoryContextValue;
+    where?: StoryContextValue;
+    error?: StoryError;
+};
+type StoryEventBase = {
+    timestamp: string;
+    level: StoryLevel;
+    title: string;
+    /**
+     * Correlates every note emission with the story it belongs to. Always set on
+     * events this library builds; optional so older stored records still typecheck.
+     */
+    storyId?: string;
+    /**
+     * The story this one is a chapter of. Absent on a top-level story.
+     * Following this field reconstructs the tree of a nested run.
+     */
+    parentStoryId?: string;
+    origin?: StoryOrigin;
+    notes: StoryNote[];
+    durationMs?: number;
+    /**
+     * How many emissions were dropped for back-pressure while this story was being
+     * collected. Present only when something was actually lost, so the loss shows up
+     * in the record instead of vanishing.
+     */
+    droppedEmissions?: number;
+    error?: StoryError;
+};
+type ReportOptions = {
+    timezone?: string;
+    locale?: string;
+    detail?: "brief" | "normal" | "full";
+    noteLimit?: number;
+    showData?: boolean;
+    colors?: boolean;
+};
+/** @deprecated Use ReportOptions instead */
+type StorySummaryOptions = ReportOptions;
+type PreviewOptions = ReportOptions & {
+    title?: string;
+    level?: StoryLevel;
+    error?: unknown;
+};
+/** @deprecated Use PreviewOptions instead */
+type StoryPreviewOptions = PreviewOptions;
+type ReportNote = {
+    timestamp: string;
+    when: string;
+    note: string;
+    text: string;
+    who?: StoryContextValue;
+    what?: StoryContextValue;
+    where?: StoryContextValue;
+    error?: StoryError;
+};
+/** @deprecated Use ReportNote instead */
+type StorySummaryNote = ReportNote;
+type StoryReport = {
+    title: string;
+    level: StoryLevel;
+    when: string;
+    durationMs?: number;
+    duration?: string;
+    origin?: StoryEventBase["origin"];
+    notes: ReportNote[];
+    error?: StoryError;
+};
+/** @deprecated Use StoryReport instead */
+type StorySummaryData = StoryReport;
+type FormattedReport = {
+    text: string;
+    data: StoryReport;
+};
+/** @deprecated Use FormattedReport instead */
+type StorySummary = FormattedReport;
+type StoryEvent = StoryEventBase & {
+    kind: "story";
+    summarize: (options?: ReportOptions) => FormattedReport;
+};
+/** @deprecated Use StoryEvent — the story-shaped emission */
+type StoryEmission = StoryEvent;
+/** The two things an audience can hear */
+type EmissionKind = "note" | "story";
+/**
+ * A single beat, delivered the moment it happens when narration is live.
+ *
+ * `storyId` and `sequence` are what make streaming lossless: a consumer holding
+ * the beats of a story can order and group them back into the record that
+ * collected narration would have produced.
+ */
+type NoteEmission = StoryNote & {
+    kind: "note";
+    storyId: string;
+    parentStoryId?: string;
+    sequence: number;
+    level: StoryLevel;
+    origin?: StoryOrigin;
+};
+type Emission = NoteEmission | StoryEvent;
+/** The emission type an audience receives, given the kinds it hears */
+type EmissionOf<Kind extends EmissionKind> = Kind extends "note" ? NoteEmission : StoryEvent;
+/**
+ * An audience, typed by what it hears.
+ *
+ * With no `hears`, it hears stories only and `accepts`/`hear` receive a
+ * `StoryEvent` — so an audience written before live narration existed compiles
+ * unchanged, including one that hands the event to a helper typed for
+ * `StoryEvent`. `hears: ["note"]` gives `NoteEmission`; `["note", "story"]`
+ * gives the union, and the code narrows on `kind`.
+ */
+type AudienceMember<Kind extends EmissionKind = "story"> = {
+    name: string;
+    /** Which emission kinds this audience wants. Defaults to `["story"]`. */
+    hears?: Kind[];
+    accepts?(emission: EmissionOf<Kind>): boolean;
+    hear(emission: EmissionOf<Kind>): void | Promise<void>;
+};
+/** Any audience, whatever it hears — the shape the registry stores */
+type AnyAudienceMember = AudienceMember<EmissionKind>;
+/**
+ * How a storyteller narrates.
+ *
+ * - `collected` — beats are buffered and leave as one story record (the default)
+ * - `live` — each beat is emitted as it happens, and the story still lands at the end
+ *
+ * Live narration adds emissions, it never removes them: a consumer that only wants
+ * beats says so with `hears: ["note"]` rather than by silencing the record.
+ */
+type Narration = "collected" | "live";
+/** @deprecated `both` is now the behavior of `live` — beats stream and the story still lands */
+type NarrationInput = Narration | "both";
+type NoteData = {
+    who?: StoryContextInput;
+    what?: StoryContextInput;
+    where?: StoryContextInput;
+    error?: unknown;
+    /** Level for this beat alone. Defaults to Information. */
+    level?: LevelInput;
+    /** Emit this beat immediately even when narration is collected */
+    live?: boolean;
+    /** Deliver this beat only to the named audiences */
+    to?: string[];
+};
+type FinishOptions = {
+    /** Defaults to Information */
+    level?: LevelInput;
+    /** The error that ended the story, normalized onto the record */
+    error?: unknown;
+};
+type ChapterOptions = {
+    /** Merged over the parent's origin */
+    origin?: StoryOriginInput;
+    /** Defaults to the parent's setting */
+    narration?: NarrationInput;
+    /** Defaults to the parent's setting */
+    level?: LevelInput;
+    /** Defaults to the parent's handler */
+    onAudienceError?: AudienceErrorHandler;
+    /** Defaults to the parent's bound */
+    maxInFlight?: number;
+};
+type StorytellerOptions = {
+    origin?: StoryOriginInput;
+    audiences?: AnyAudienceMember[];
+    /** Defaults to `STORYTELLER_NARRATION`, then `collected` */
+    narration?: NarrationInput;
+    /**
+     * Which default audience to register: colorized text for a person, NDJSON for a
+     * program. Defaults to `STORYTELLER_FORMAT`, then `text`.
+     */
+    format?: OutputFormat;
+    /**
+     * Share another storyteller's audience registry instead of creating one.
+     * Audiences added to it later reach this storyteller too. When given, no
+     * default audience is registered — the registry already has whatever it has.
+     */
+    audience?: AudienceRegistry;
+    /** The story this one is a chapter of. Set by `chapter()`. */
+    parentStoryId?: string;
+    /**
+     * Drop emissions below this level before they reach any audience.
+     * Defaults to `STORYTELLER_LEVEL`, then Information (deliver everything).
+     */
+    level?: LevelInput;
+    /**
+     * Called when an audience throws or rejects. Without one, a single throttled
+     * warning per audience goes to the console — a logging library that loses
+     * records in silence is worse than one that complains.
+     */
+    onAudienceError?: AudienceErrorHandler;
+    /**
+     * Cap on deliveries in flight to a single audience at once. Live narration is
+     * fire-and-forget, so a slow audience would otherwise grow an unbounded queue.
+     * Past the cap, emissions are dropped and counted on the closing story.
+     */
+    maxInFlight?: number;
+};
+/** Called when an audience member throws or rejects while hearing an emission */
+type AudienceErrorHandler = (error: unknown, member: AnyAudienceMember, emission: Emission) => void;
+/** Manages the set of audience members that receive story events */
+declare class AudienceRegistry {
+    private members;
+    /** Register an audience member, replacing any existing member with the same name */
+    add<Kind extends EmissionKind = "story">(member: AudienceMember<Kind>): this;
+    /** Remove an audience member by name */
+    remove(name: string): this;
+    /** Return all registered audience members */
+    getAll(): AnyAudienceMember[];
+    /** Return only the audience members matching the given names */
+    getOnly(names: string[]): AnyAudienceMember[];
+    /** Check if an audience member is registered by name */
+    has(name: string): boolean;
+    /** List the names of all registered audience members */
+    names(): string[];
+}
+/**
+ * Collects timestamped notes and emits them as one structured story — and, when
+ * narration is live, emits each note the moment it is taken.
+ *
+ * @example
+ * ```ts
+ * const story = new Storyteller({ origin: { who: "api-server" }, narration: "live" });
+ * story.report("Request received", { what: { path: "/checkout" } });
+ * story.report("Validated cart");
+ * story.finish("Checkout started");
+ * ```
+ */
+declare class Storyteller {
+    readonly audience: AudienceRegistry;
+    private readonly origin?;
+    private readonly parentStoryId?;
+    private notes;
+    private narration;
+    private readonly minimumLevel;
+    private readonly onAudienceError;
+    private readonly maxInFlight;
+    /** Deliveries currently awaiting each audience, keyed by audience name */
+    private readonly inFlight;
+    /** Emissions dropped for back-pressure since the current story began */
+    private droppedEmissions;
+    /** Identifies the story currently being collected; regenerated after each telling */
+    private storyId;
+    /** Position of the next note within the current story */
+    private nextSequence;
+    constructor(options?: StorytellerOptions);
+    /**
+     * Switch between collected and live narration at runtime.
+     * Takes effect on the next note; already-buffered notes are not replayed.
+     *
+     * @param narration - `collected` to buffer, `live` to emit each note as it happens
+     * @returns `this` for chaining
+     */
+    narrate(narration: NarrationInput): this;
+    /** The id of the story currently being collected */
+    get currentStoryId(): string;
+    /**
+     * Start a chapter: a child storyteller whose stories are linked back to this
+     * one by `parentStoryId`.
+     *
+     * Real work nests — an agent spawns subtasks, a batch runs per-item operations.
+     * A chapter keeps each of those a complete story in its own right while leaving
+     * the run reconstructable as a tree.
+     *
+     * The child shares this storyteller's audience registry, so audiences added
+     * later reach it too, and inherits narration, level and delivery settings.
+     * Its stories are separate records — a chapter is not folded into the parent's
+     * notes.
+     *
+     * @param options - Origin to merge over the parent's, and any setting to override
+     * @returns A child Storyteller
+     *
+     * @example
+     * ```ts
+     * for (const account of accounts) {
+     *   const chapter = story.chapter({ origin: { what: account.id } });
+     *   chapter.report("Fetching invoices");
+     *   chapter.finish(`Synced ${account.id}`);
+     * }
+     * ```
+     */
+    chapter(options?: ChapterOptions): Storyteller;
+    /**
+     * Report a beat of the current story.
+     *
+     * In collected narration the beat is buffered and leaves with the story. In live
+     * narration it is emitted the moment you call this, so whoever is tuned in sees
+     * the work as it happens.
+     *
+     * Accepts anything, not just a string — pass an error, an API response, a Map, a
+     * class instance — and the value is normalized into a storable shape with the note
+     * text derived from it.
+     *
+     * @param input - What happened: a message, or any value to describe
+     * @param data - Optional context: who did it, what was involved, where it happened, any error
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```ts
+     * story.report("Card charged", { what: { amount: "$42" }, where: "stripe" });
+     * story.report(await response.json());
+     * ```
+     */
+    report(input: unknown, data?: NoteData): this;
+    /** Clear all accumulated notes without emitting a story, and start a new story id */
+    reset(): this;
+    /** Preview the current notes as a formatted report without emitting or clearing them */
+    summarize(options?: PreviewOptions): FormattedReport;
+    /**
+     * Finish the story: emit everything collected so far as one record, and start fresh.
+     *
+     * @param title - What the story was about
+     * @param options - Level, and the error that ended it
+     * @returns A one-shot handle whose `.to()` overrides the audience list — call it
+     *   synchronously, delivery happens on the next microtask
+     *
+     * @example
+     * ```ts
+     * story.finish("Sync complete");
+     * story.finish("Sync failed", { level: "oops", error }).to("db");
+     * ```
+     */
+    finish(title: string, options?: FinishOptions): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `finish(title)`. Removed at 1.0. */
+    tell(title: string): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `finish(title, { level: "warn" })`. Removed at 1.0. */
+    warn(title: string): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `finish(title, { level: "oops", error })`. Removed at 1.0. */
+    oops(title: string, error?: unknown): {
+        to: (...names: string[]) => void;
+    };
+    /** @deprecated Use `report()`. Removed at 1.0. */
+    note(input: unknown, data?: NoteData): this;
+    /** Emit a single note to the audiences listening for notes */
+    private emitNote;
+    /** Build a story event and schedule delivery, returning a handle to override the audience list */
+    private createDelivery;
+    /** Assemble the story event from current notes and start a fresh story */
+    private buildEvent;
+    /** Begin a new story: fresh id, sequence back to zero */
+    private startNewStory;
+    /** Deliver an emission to the audience members listening for its kind */
+    private deliver;
+    /** Run an audience's accepts() without letting a throw from it lose the emission */
+    private acceptsSafely;
+    /**
+     * Hand an emission to one audience, keeping its failures and its slowness
+     * contained: a throw is reported rather than swallowed, and a backlog is dropped
+     * rather than grown without limit.
+     */
+    private hearSafely;
+    /** Report an audience failure without ever letting it reach caller code */
+    private handleAudienceError;
+}
+
+/**
+ * The StoryStore contract: where stories go, and how they come back.
+ *
+ * A story is the unit of retrieval — self-contained, ordered, small enough to
+ * fit in a context window. The contract is deliberately small: append, get by
+ * id, query by structured criteria, walk chapters, and forget. Every adapter
+ * (in memory, a file, SQLite, Postgres) answers the same questions, so the
+ * questions — not each adapter's query language — are the contract.
+ */
+
+/** A story as kept: the record without the `summarize` method, with an id it can be fetched by */
+type StoredStory = StoryEventBase & {
+    storyId: string;
+};
+/**
+ * Structured criteria. Every field narrows; an empty query matches everything.
+ * Built by hand or by the query vocabulary; adapters receive this object,
+ * never a string to parse.
+ */
+type StoryQuery = {
+    /** Stories whose timestamp is at or after this instant */
+    since?: Date;
+    /** Stories whose timestamp is before this instant */
+    until?: Date;
+    /** Exactly this level, or any of these */
+    level?: StoryLevel | StoryLevel[];
+    /** At least this level: Warning matches Warning and Error */
+    minimumLevel?: StoryLevel;
+    /** Case-insensitive match over the title, note text, scalar context and error messages */
+    about?: string;
+    /** Case-insensitive match over the origin's who / what / where */
+    from?: string;
+    /** Chapters of this story */
+    parentStoryId?: string;
+    /** Stories that took longer than this */
+    slowerThanMs?: number;
+    /** Stories that carry an error or closed at Error level */
+    failed?: boolean;
+    limit?: number;
+    offset?: number;
+    /** Newest first unless told otherwise */
+    order?: "newest" | "oldest";
+};
+type StoryStore = {
+    /** Keep a story. Replaces an earlier record with the same id. Never throws synchronously. */
+    append(event: StoryEvent | StoredStory): Promise<void>;
+    /** One story, complete, by id */
+    get(storyId: string): Promise<StoredStory | undefined>;
+    /** Stories matching the criteria, newest first by default */
+    query(criteria?: StoryQuery): Promise<StoredStory[]>;
+    /** The chapters of a story, in the order they were told */
+    children(parentStoryId: string): Promise<StoredStory[]>;
+    /** Forget stories that began before the boundary; returns how many were removed */
+    prune(before: Date): Promise<number>;
+};
+type ToStoredStoryOptions = {
+    /**
+     * Redaction at the storage boundary. The normalizer already redacted at
+     * capture; this pass covers a record fed to a store by hand, or one
+     * normalized with redaction off, before it becomes durable. Default
+     * `balanced`; `off` trusts the record as given.
+     */
+    redactValues?: RedactionStrictness;
+};
+/**
+ * The record as a store keeps it: a deep copy of the JSON-safe fields, so a
+ * caller holding the event cannot change what was stored, and no method rides
+ * along. A record without an id — one written before ids existed — is given
+ * one. Secrets are redacted once more on the way in: persisted is the moment
+ * a leaked value stops being a line that scrolled past.
+ */
+declare function toStoredStory(event: StoryEvent | StoredStory, options?: ToStoredStoryOptions): StoredStory;
+/**
+ * Everything a full-text search over a story should see: the title, each
+ * note's text, scalar context values, and error messages. Adapters store this
+ * as the canonical `search_text` column; the in-memory matcher searches it.
+ */
+declare function storySearchText(story: StoredStory): string;
+/** The origin as three text columns: scalars as-is, objects as JSON */
+declare function flattenOrigin(origin?: StoryOrigin): {
+    who?: string;
+    what?: string;
+    where?: string;
+};
+/**
+ * The canonical schema. An adapter that stores these columns can answer every
+ * StoryQuery; `record` carries the whole story so `get` returns it unchanged.
+ * Deliberately not a normalized notes table — nothing yet demands one.
+ */
+type CanonicalRow = {
+    story_id: string;
+    parent_story_id: string | null;
+    timestamp: string;
+    level: StoryLevel;
+    title: string;
+    origin_who: string | null;
+    origin_what: string | null;
+    origin_where: string | null;
+    duration_ms: number | null;
+    error_message: string | null;
+    /** The notes, as JSON */
+    notes: string;
+    /** Derived: what `about` searches */
+    search_text: string;
+    /** The whole story, as JSON */
+    record: string;
+};
+declare function canonicalRow(event: StoryEvent | StoredStory): CanonicalRow;
+/** Does one story satisfy the criteria? The reference matcher every adapter is measured against. */
+declare function matchesQuery(story: StoredStory, query?: StoryQuery): boolean;
+/** Filter, order and page a set of stories in memory — what a store without an index does */
+declare function applyQuery(stories: Iterable<StoredStory>, query?: StoryQuery): StoredStory[];
+
+/**
+ * The query vocabulary: ask a store a question in the library's own words.
+ *
+ *   await stories(store).about("checkout").from("payment-service").failing().since("24h");
+ *
+ * The same words have to read well aloud and be easy for a model to write.
+ * Every clause returns a new builder; a builder compiles to a StoryQuery, so
+ * an adapter receives structured criteria and never a string to parse.
+ */
+
+/** `"30s"`, `"5m"`, `"24h"`, `"7d"`, `"2w"`, or milliseconds */
+type DurationInput = string | number;
+/** A duration as milliseconds. Throws on something that is not a duration, so a typo cannot become "since forever". */
+declare function parseDuration(input: DurationInput): number;
+type StoriesOptions = {
+    /** The clock `since("24h")` counts back from. Injectable for tests. */
+    now?: () => Date;
+};
+/**
+ * A question in progress. Immutable: every clause returns a new one.
+ * Awaiting it runs `.all()`.
+ *
+ * Being thenable has one consequence: returning a builder from an `async`
+ * function resolves it into its results. Return the store, or the
+ * `toQuery()` object, when a caller should get the question rather than
+ * the answer.
+ */
+declare class StoryQueryBuilder implements PromiseLike<StoredStory[]> {
+    private readonly store;
+    private readonly query;
+    private readonly now;
+    constructor(store: StoryStore, query: StoryQuery, now: () => Date);
+    private with;
+    private instant;
+    /** Title, note text, scalar context or error message mentions this */
+    about(text: string): StoryQueryBuilder;
+    /** The origin — who, what or where — mentions this */
+    from(origin: string): StoryQueryBuilder;
+    /** Exactly this level. Accepts the aliases: `"info"`, `"warn"`, `"oops"`. */
+    level(level: LevelInput): StoryQueryBuilder;
+    /** This level or worse */
+    atLeast(level: LevelInput): StoryQueryBuilder;
+    /** Carried an error, or closed at Error level */
+    failing(): StoryQueryBuilder;
+    /** Neither an error nor closed at Error level */
+    succeeding(): StoryQueryBuilder;
+    /** Took longer than this: `"5s"`, `"2m"`, or milliseconds */
+    slowerThan(duration: DurationInput): StoryQueryBuilder;
+    /** Began within this long ago (`"24h"`), or at or after this date */
+    since(when: DurationInput | Date): StoryQueryBuilder;
+    /** Began before this long ago, or before this date */
+    until(when: DurationInput | Date): StoryQueryBuilder;
+    /** The chapters of this story */
+    under(parentStoryId: string): StoryQueryBuilder;
+    /** Most recent first — the default */
+    newest(): StoryQueryBuilder;
+    /** Earliest first */
+    oldest(): StoryQueryBuilder;
+    /** At most this many */
+    limit(count: number): StoryQueryBuilder;
+    /** Skip this many first */
+    skip(count: number): StoryQueryBuilder;
+    /** The structured criteria this question compiles to — what an adapter receives */
+    toQuery(): StoryQuery;
+    /** Every matching story */
+    all(): Promise<StoredStory[]>;
+    /** The first match, or nothing */
+    first(): Promise<StoredStory | undefined>;
+    /** How many match, ignoring paging */
+    count(): Promise<number>;
+    /** An awaited builder resolves to `.all()` */
+    then<Result = StoredStory[], Failure = never>(onFulfilled?: ((stories: StoredStory[]) => Result | PromiseLike<Result>) | null, onRejected?: ((reason: unknown) => Failure | PromiseLike<Failure>) | null): Promise<Result | Failure>;
+}
+/**
+ * Start a question against a store.
+ *
+ * @example
+ * ```ts
+ * const recent = stories(store);
+ * await recent.failing().since("1h");
+ * await recent.about("checkout").from("payment-service").level("oops").since("24h");
+ * await recent.slowerThan("5s").since("7d").oldest().limit(10);
+ * await recent.under(parentStoryId).count();
+ * ```
+ */
+declare function stories(store: StoryStore, options?: StoriesOptions): StoryQueryBuilder;
+
+export { type DurationInput as $, type AudienceMember as A, type AudienceErrorHandler as B, type ChapterOptions as C, AudienceRegistry as D, type EmissionKind as E, type FormattedReport as F, type NormalizeOptions as G, DEFAULT_REDACT_KEYS as H, normalizeValue as I, type JsonValue as J, normalizeError as K, type LevelInput as L, REDACTED as M, type NarrationInput as N, type CanonicalRow as O, type PreviewOptions as P, type StoredStory as Q, type ReportOptions as R, type StoryEventBase as S, type StoryQuery as T, type ToStoredStoryOptions as U, applyQuery as V, canonicalRow as W, flattenOrigin as X, matchesQuery as Y, storySearchText as Z, toStoredStory as _, type StoryOriginInput as a, type StoriesOptions as a0, parseDuration as a1, stories as a2, StoryQueryBuilder as a3, type OutputFormat as a4, toStoryLevel as a5, readEnvironmentValue as a6, resolveMinimumLevel as a7, meetsLevel as a8, resolveOutputFormat as a9, resolveColors as aa, Storyteller as b, type StoryEvent as c, type StoryLevel as d, type StoryStore as e, type StoryOrigin as f, type StoryError as g, type StoryContextValue as h, type StoryContextInput as i, type StoryNote as j, type StorySummaryOptions as k, type StoryPreviewOptions as l, type ReportNote as m, type StorySummaryNote as n, type StoryReport as o, type StorySummaryData as p, type StorySummary as q, type StoryEmission as r, type NoteEmission as s, type Emission as t, type EmissionOf as u, type AnyAudienceMember as v, type Narration as w, type NoteData as x, type FinishOptions as y, type StorytellerOptions as z };