import type { OperationId } from '../events/types.js';
export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
export type InboxEntryId = string & {
    readonly __inboxEntryId: unique symbol;
};
/** A single inbox entry: a push pointer (`ref` as a canonical
 *  `<node-id>:reports/<basename>` history handle, no inline body), or a direct
 *  message/system notice (short bodies inline via `data.body`; bodies too long
 *  to inline spill to `messages/` and carry an absolute filesystem `ref` plus
 *  a bounded inline preview). */
export interface InboxEntry {
    /** Unique physical-entry identity. It is opaque and never sortable. */
    entry_id: InboxEntryId;
    /** Correlation identity inherited from the producing operation. */
    operation_id: OperationId;
    /** ISO 8601 timestamp of delivery (display only). */
    ts: string;
    /** Node id of the sender, or null for system-generated entries. */
    from: string | null;
    /** Priority band for the receiver's attention. */
    tier: InboxTier;
    /** Semantic kind of the push event. */
    kind: InboxKind;
    /** Canonical `<node-id>:reports/<basename>` history ref for a push, or an
     *  absolute path to the spilled body file under `messages/` for an oversized
     *  direct message/system notice. */
    ref?: string;
    /** First ~80 chars of the body's first line — enough to decide if it matters. */
    label: string;
    /** Arbitrary structured payload for non-push message entries. */
    data?: Record<string, unknown>;
}
export type InboxEntryInput = Omit<InboxEntry, 'entry_id' | 'ts' | 'operation_id'> & {
    operation_id?: string;
};
/** Complete an entry exactly once before any spill or append work. */
export declare function finalizeInboxEntry(input: InboxEntryInput): InboxEntry;
/** Atomically append one finalized inbox entry to `nodes/<nodeId>/inbox.jsonl`. */
export declare function appendInbox(nodeId: string, entry: InboxEntryInput): InboxEntry;
/** Deliver the one system notice for a controller that can no longer satisfy a
 * wait. Returns null when another durable operation already settled or re-armed
 * that wait. */
export declare function appendControllerDeathNotice(nodeId: string, controller: string): InboxEntry | null;
/** Return the physical suffix strictly after the exact cursor identity. */
export declare function readInboxSince(nodeId: string, cursorEntryId?: string): InboxEntry[];
/** Read one exact contiguous physical range after an exclusive boundary through an inclusive boundary. */
export declare function readInboxRange(nodeId: string, afterEntryId: string | undefined, throughEntryId: string): InboxEntry[];
/** Entry ids a human interrupt canceled before delivery. Append-only sidecar
 *  (the inbox itself is append-only — never mutated in place): one entry_id
 *  per line. The watcher skips canceled entries at plan time; a missing file
 *  is an empty set. */
export declare function readCanceledEntryIds(nodeId: string): Set<InboxEntryId>;
/** Mark every not-yet-settled HUMAN message entry canceled — the boot-window
 *  half of a first-class interrupt (`POST /v1/nodes/{id}/interrupt`): a send
 *  that rode the durable inbox (dormant target, or the mid-revive fallback)
 *  must not be injected after the human pressed Esc. Scope: `from === 'human'`
 *  `kind: 'message'` entries ONLY — a human Esc never cancels spine/agent
 *  messages or system notices. Entries past the durable cursor that a live
 *  watcher already handed to the engine may be over-canceled; that is safe —
 *  the interrupt's abort lands right behind, and covered handoffs are never
 *  re-delivered anyway. Returns the newly canceled entry ids. */
export declare function cancelPendingHumanMessages(nodeId: string): InboxEntryId[];
/** Read and validate the persisted exact cursor identity. */
export declare function readCursor(nodeId: string): InboxEntryId | undefined;
/** Persist one validated exact cursor identity (atomic tmp+rename). */
export declare function writeCursor(nodeId: string, entryId: string): void;
/** Clip a body to a bounded preview, reporting whether anything was dropped. */
export declare function clipBody(body: string): {
    text: string;
    clipped: boolean;
};
/**
 * Render many unread inbox pointers into one compact digest string.
 *
 * Format (per sender group):
 *   From <sender> — <N> update(s):
 *     [<kind>] <label> at <absolute report path>:
 *
 *   <short report body>
 *
 * Large reports remain canonical pointers and add one shared dereference hint.
 */
export declare function coalesce(entries: InboxEntry[]): string;