@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/runtime/mailbox.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The mailbox — durable intake, schedule, delivery and ack. Nothing else.
+ *
+ * v7 §4.3 gives this store four jobs and names what it must not do: it manages
+ * durable delivery/ack and mechanical concurrency ONLY; it does not classify an
+ * original as work, and it does not pre-emptively create a task row. §4.4 says
+ * the same from the other side — no `acted/no_update/owner_question`
+ * classification may be invented here.
+ *
+ * So the fields are only the ones that hold for any consumer: identity,
+ * principal, source, content notice, time, where a reply goes, what may merge
+ * with what, and delivery state. A stimulus's MEANING belongs to the agent
+ * that reads it, and a consumer's vocabulary for that meaning belongs to the
+ * consumer — a product's trigger-loop intake may add its own display lines and
+ * procedure activations (design W6 correction). A core that exported those words would make "receive
+ * something durably" unusable without importing them.
+ *
+ * What this is NOT, and where that lives instead:
+ *   - It does not run a turn, retry a model, or know a turn's outcome. That is
+ *     the native session (`native-session.ts`), which already
+ *     provides native protocol and turn observations. `ack` says the loop took the
+ *     stimulus; it never says the work is done.
+ *   - It does not deliver anything outward. An effect receipt is the effect
+ *     ledger's (`operations.ts`).
+ */
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { JsonValue } from '../memory/judgment-types.js';
+import { NativeInputJournal, type NativeDeliveryRecord } from './native-input-journal.js';
+/**
+ * What kind of stimulus a row holds — v7 R2 inputs and a native harness event.
+ *
+ * Stated by the producer, never derived from the payload: a host that read a
+ * message body to decide what kind of work it is would be doing the
+ * classification this contract removes.
+ */
+export type StimulusKind = 'owner_message' | 'source_delta' | 'scheduled' | 'native_event';
+export declare function isStimulusKind(value: unknown): value is StimulusKind;
+/** One preserved observation this stimulus points at. Identity, not content. */
+export interface StimulusRef {
+    /** The producer's id for the observation; the dedupe key. */
+    refId: string;
+    /** Where the preserved original is readable, when the producer preserved one. */
+    observationRef: string | null;
+}
+/**
+ * One stimulus as its producer states it.
+ *
+ * `preview` is the bounded change notice of §4.4 — never the whole context and
+ * never a task list. The agent reads the rest through the source actions when
+ * it decides it needs to.
+ */
+export interface Stimulus {
+    /** The producer's identity for this stimulus. Dedupe key when it states no refs. */
+    id: string;
+    kind: StimulusKind;
+    /** Whose stimulus this is. The runtime refuses a principal it does not serve. */
+    principalId: string;
+    /** Where it came from — durable channel identity, canonical at the producer. */
+    channelKey: string;
+    /** Preserved observation identity, when the producer has any. */
+    refs?: readonly StimulusRef[];
+    /** Bounded change notice. Display, not context. */
+    preview?: readonly string[];
+    /** Consumer-owned JSON input, retained verbatim in meaning, never interpreted here. */
+    payload?: JsonValue;
+    /** Where an answer goes back, when the producer can name it. */
+    replyTo?: string | null;
+    /**
+     * What may merge with what.
+     *
+     * Pending stimuli sharing a key, payload, kind and destination can become one
+     * row — the mechanical concurrency §4.3 assigns here. It is the producer's key, and
+     * merging is append-only: refs and preview join, nothing is dropped and
+     * nothing is interpreted. A producer that states none gets no merging.
+     */
+    coalesceKey?: string | null;
+    /** When it happened, as against when it was accepted. */
+    occurredAt: number;
+}
+/** A stimulus as it was stored, with its delivery state. */
+export interface MailboxRow {
+    id: number;
+    stimulusId: string;
+    kind: StimulusKind | null;
+    principalId: string;
+    channelKey: string;
+    refs: StimulusRef[];
+    preview: string[];
+    /** Absent on inputs accepted before payload preservation was supported. */
+    payload?: JsonValue;
+    replyTo: string | null;
+    coalesceKey: string | null;
+    occurredAt: number;
+    createdAt: number;
+    status: 'pending' | 'claimed' | 'acked' | 'dead';
+    attempts: number;
+    nativeDelivery?: NativeDeliveryRecord;
+}
+/** Bounded provenance for inputs sharing one native turn; no payload is projected. */
+export interface NativeTurnInputRef {
+    id: number;
+    stimulusId: string;
+    kind: StimulusKind | null;
+    channelKey: string;
+    occurredAt: number;
+    status: MailboxRow['status'];
+}
+/** A row the mailbox refused to parse. Parked dead, never silently dropped. */
+export declare class MailboxCorruptionError extends Error {
+    readonly rowId: number;
+    readonly code = "MAILBOX_CORRUPT";
+    constructor(rowId: number, cause: unknown);
+}
+export declare class Mailbox {
+    private readonly db;
+    private readonly clock;
+    readonly nativeInputs: NativeInputJournal;
+    private readonly stmtInsertSeen;
+    private readonly stmtInsert;
+    private readonly stmtInsertRef;
+    private readonly stmtRefsFor;
+    private readonly stmtClaimSelect;
+    private readonly stmtClaimSelectKind;
+    private readonly stmtClaimUpdate;
+    private readonly stmtAck;
+    private readonly stmtRetry;
+    private readonly stmtRetryStatus;
+    private readonly stmtPruneAcked;
+    private readonly stmtPrunePending;
+    private readonly stmtPruneSeen;
+    private readonly stmtReplay;
+    private readonly stmtDepth;
+    private readonly stmtPendingCoalesced;
+    private readonly stmtAppendPreview;
+    private readonly stmtIdentityPayload;
+    constructor(db: DatabaseAdapter, clock?: () => number);
+    private now;
+    /**
+     * Make a stimulus durable. Returns the row id, or `null` when every ref it
+     * carries was already accepted.
+     *
+     * Dedupe is PER REF, not per stimulus shape. A boundary key fails on partial
+     * redelivery: [r1] enqueues, the producer's cursor commit fails, the next
+     * tick delivers [r1,r2] under a different boundary — and r1 runs twice.
+     * A stimulus with no unseen ref is dropped; one with any unseen ref is
+     * stored with exactly its unseen refs.
+     */
+    enqueue(stimulus: Stimulus): number | null;
+    /**
+     * Take the next pending row under a lease. A corrupt row parks dead and the
+     * scan continues.
+     *
+     * `prefer` orders kinds ahead of the rest, oldest-first within each. It is
+     * ordering, not meaning: §4.3 forbids a host FIFO in which the person's
+     * current request waits behind a mass replay, and the kind a producer stated
+     * is the only thing that can say which is which without reading content.
+     */
+    claimNext(options?: {
+        prefer?: readonly StimulusKind[];
+    }): MailboxRow | null;
+    private hydrate;
+    /** Renew only a live runtime-owned claim; native ACKs remain independent. */
+    renewClaim(id: number, now?: number): void;
+    /** Inspect one accepted input without claiming it or changing its lease. */
+    readInput(stimulusId: string, principalId: string): MailboxRow | null;
+    /** Reopen claims that never crossed the native dispatch boundary. */
+    recoverOrphanedClaims(now?: number): number;
+    /** Identity lookup for transport recovery; never returns another principal's payload. */
+    principalsForInput(stimulusId: string): string[];
+    /** The exact native turn's accepted input cohort, scoped to its principal. */
+    readNativeTurnInputs(stimulusId: string, principalId: string, options?: {
+        afterId?: number;
+        limit?: number;
+    }): {
+        items: NativeTurnInputRef[];
+        nextCursor: number | null;
+    };
+    /** Inputs needing native/result reconciliation, never a second model execution. */
+    unsettledNative(limit: number, afterId?: number): MailboxRow[];
+    /**
+     * The loop took this stimulus.
+     *
+     * That is all this says. It is not a claim that anything was read, decided
+     * or done — §4.4 is explicit that a delivery ACK is not a work receipt, and
+     * there is deliberately no field here to record one in.
+     */
+    ack(id: number): void;
+    /**
+     * Return a claim to pending, or park it dead after MAX_ATTEMPTS. Returns the
+     * resulting status so the caller can be LOUD about a dead row — a permanent
+     * loss must never be silent.
+     */
+    retry(id: number, error: string): 'pending' | 'dead' | 'noop';
+    /** Park a row dead without spending an attempt. */
+    quarantine(id: number, reason: string): void;
+    replayStale(olderThanMs: number, now?: number): number;
+    replayStaleDetailed(olderThanMs: number, now?: number): {
+        replayed: number;
+        newlyDead: MailboxRow[];
+    };
+    depth(): {
+        pending: number;
+        claimed: number;
+        dead: number;
+    };
+    /**
+     * Schedule a wake. The fourth job: when to come back, and for what channel.
+     *
+     * `mailbox_schedules` is this daemon's own alarm clock, not anyone's
+     * calendar — a consumer's calendar is source data and is read through the
+     * source actions (design §6.3).
+     */
+    scheduleWake(channelKey: string, dueAt: number): number;
+    /** Wakes that are due and have not fired. The caller marks them fired when it acts. */
+    dueWakes(now?: number, limit?: number): Array<{
+        id: number;
+        channelKey: string;
+        dueAt: number;
+    }>;
+    /** Mark a wake fired. Idempotent: a second call changes nothing. */
+    markWakeFired(id: number): boolean;
+}
+//# sourceMappingURL=mailbox.d.ts.map