@songsid/agend 2.1.7-beta.3 → 2.1.7-beta.5

package/dist/delivery-outbox.d.ts

@@ -0,0 +1,174 @@
+import { EventEmitter } from "node:events";
+import type { QueueResumePolicy } from "./delivery-queue-evidence.js";
+export declare const DURABLE_DELIVERY_MAX_ATTEMPTS = 8;
+export declare const DURABLE_DELIVERY_MAX_AGE_MS: number;
+export declare const DURABLE_DELIVERY_ABORT_BACKOFF_MS = 5000;
+export interface DaemonDeliveryPort {
+    begin(deliveryId: string, targetBootId: string, attemptNo: number, evidence?: DeliveryAttemptEvidence): "begun" | "duplicate" | "stale";
+    markEnterStarted(deliveryId: string, targetBootId: string, attemptNo: number): boolean;
+    abort(deliveryId: string, targetBootId: string, attemptNo: number, reason: string): boolean;
+    complete(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "failed" | "uncertain", evidence?: string): boolean;
+    retryBeforeBegin(deliveryId: string, targetBootId: string, attemptNo: number, reason: string, delayMs?: number): boolean;
+}
+export type OutboxState = "queued" | "delivering" | "submission_started" | "reconciliation_pending" | "retry_wait" | "delivered" | "failed" | "uncertain" | "cancelled";
+export interface NewOutboxDelivery {
+    operationId: string;
+    sourceKey: string;
+    sourceInstance: string;
+    sourceDaemonBootId: string;
+    targetInstance: string;
+    targetSession?: string;
+    kind: string;
+    correlationId?: string;
+    payload: Record<string, unknown>;
+}
+export interface OutboxDelivery {
+    deliveryId: string;
+    operationId: string;
+    sourceKey: string;
+    sourceInstance: string;
+    sourceDaemonBootId: string;
+    targetInstance: string;
+    targetSession: string | null;
+    targetDaemonBootId: string | null;
+    kind: string;
+    correlationId: string | null;
+    payload: Record<string, unknown>;
+    state: OutboxState;
+    attemptNo: number;
+    createdSeq: number;
+    managerBootId: string | null;
+    responseDeliveredAt: string | null;
+    nextAttemptAt: string | null;
+    lastError: string | null;
+    reconciliationPending: boolean;
+}
+export type DeliveryStatusSelector = {
+    deliveryId: string;
+    operationId?: never;
+    correlationId?: never;
+    limit?: never;
+    cursor?: never;
+} | {
+    operationId: string;
+    deliveryId?: never;
+    correlationId?: never;
+    limit?: number;
+    cursor?: string;
+} | {
+    correlationId: string;
+    deliveryId?: never;
+    operationId?: never;
+    limit?: number;
+    cursor?: string;
+};
+export interface DeliveryStatusItem {
+    delivery_id: string;
+    operation_id: string;
+    correlation_id: string | null;
+    source_instance: string;
+    target_instance: string;
+    kind: string;
+    state: OutboxState;
+    attempt_no: number;
+    created_at: string;
+    updated_at: string;
+    status_summary: string;
+    error_summary: string | null;
+    safe_to_retry: boolean;
+}
+export interface DeliveryStatusPage {
+    items: DeliveryStatusItem[];
+    next_cursor: string | null;
+}
+export type DurableSubmissionMode = "idle_submit" | "native_queue_handoff" | "steer" | "raw_paste";
+/** Checkpoint committed with begin, before any pane paste can occur. */
+export interface DeliveryAttemptEvidence {
+    backend: string;
+    backendVersion?: string | null;
+    windowId: string | null;
+    transcriptPath: string | null;
+    transcriptOffset: number | null;
+    transcriptSessionId: string | null;
+    submissionMode: DurableSubmissionMode;
+    queueResumePolicy?: QueueResumePolicy;
+}
+export interface DeliveryReconciliationCandidate extends OutboxDelivery {
+    attempt: {
+        targetDaemonBootId: string;
+        attemptNo: number;
+        backend: string | null;
+        backendVersion: string | null;
+        windowId: string | null;
+        transcriptPath: string | null;
+        transcriptOffset: number | null;
+        transcriptSessionId: string | null;
+        submissionMode: DurableSubmissionMode | null;
+        queueResumePolicy: QueueResumePolicy | null;
+        enterStartedAt: string | null;
+    };
+}
+export interface ClaimedOutboxDelivery extends OutboxDelivery {
+    targetDaemonBootId: string;
+}
+/** Durable admission and fenced state transitions for the fleet delivery queue. */
+export declare class DeliveryOutbox extends EventEmitter {
+    private readonly db;
+    readonly managerBootId: string;
+    constructor(dbPath: string, managerBootId?: string);
+    private ensureColumn;
+    /** Commit admission before returning success. Duplicate source keys return their original row. */
+    admit(input: NewOutboxDelivery): {
+        delivery: OutboxDelivery;
+        inserted: boolean;
+    };
+    get(deliveryId: string): OutboxDelivery | undefined;
+    getByOperation(sourceInstance: string, operationId: string): OutboxDelivery[];
+    /**
+     * Query only rows owned by the authenticated instance as source or target.
+     * This method accepts caller identity separately from user arguments so a
+     * caller cannot widen its own visibility with a forged source name.
+     */
+    queryStatusForInstance(callerInstance: string, selector: DeliveryStatusSelector): DeliveryStatusPage;
+    /** Open the existing outbox without migrations or writes for the operator CLI. */
+    static queryStatusReadOnly(dbPath: string, selector: DeliveryStatusSelector): DeliveryStatusPage;
+    listPending(): OutboxDelivery[];
+    nextRetryAt(): string | null;
+    /** Claim the earliest eligible target row; one caller owns each target lane. */
+    claimNext(managerBootId: string, targetBootIdFor: (target: string) => string | null, blockedTargets: ReadonlySet<string>): ClaimedOutboxDelivery | undefined;
+    /** Idempotent begin permit, committed immediately before the pane side effect. */
+    begin(deliveryId: string, targetBootId: string, attemptNo: number, evidence?: DeliveryAttemptEvidence): "begun" | "duplicate" | "stale";
+    /** Write-ahead fence: commit before tmux is allowed to receive Enter. */
+    markEnterStarted(deliveryId: string, targetBootId: string, attemptNo: number): boolean;
+    /** Safe only when the caller can prove no pane write occurred for this attempt. */
+    abort(deliveryId: string, targetBootId: string, attemptNo: number, reason: string): boolean;
+    complete(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "failed" | "uncertain", evidence?: string): boolean;
+    /** Transient pre-submit failure: state is retryable and the same row keeps its FIFO position. */
+    retryBeforeBegin(deliveryId: string, targetBootId: string, attemptNo: number, reason: string, delayMs?: number): boolean;
+    failBeforeBegin(deliveryId: string, reason: string): boolean;
+    /** Bound both unavailable rows and unresolved reconciliation without stealing a live lease. */
+    expireStale(nowMs?: number, maxAgeMs?: number): number;
+    /** Next queued/retry expiry for bounded maintenance scheduling. */
+    nextExpiryAt(): string | null;
+    markResponseDelivered(sourceInstance: string, operationId: string): number;
+    /** Old process leases are recoverable; an old submission attempt needs evidence reconciliation. */
+    recoverForBoot(managerBootId: string): {
+        queued: number;
+        reconciliationPending: number;
+    };
+    /** Atomically create a post-restart notice for an accepted operation whose response was not recorded. */
+    admitPostRestartOutcomeNotice(parent: OutboxDelivery, currentSourceBootId: string): OutboxDelivery | undefined;
+    recoverTargetGeneration(targetInstance: string, currentTargetBootId: string): {
+        queued: number;
+        reconciliationPending: number;
+    };
+    /** Fence in-flight writes before an in-process target stop begins. */
+    markTargetReconciliationPending(targetInstance: string, targetBootId: string): number;
+    getReconciliationCandidates(targetInstance: string): DeliveryReconciliationCandidate[];
+    /** Atomically settle one old attempt using only its boot/attempt fence. */
+    reconcileAttempt(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "retry_wait" | "uncertain", evidence: string): boolean;
+    getUnansweredAccepted(sourceInstance: string, currentBootId: string): OutboxDelivery[];
+    close(): void;
+    /** Must be called inside the same SQLite transaction as the terminal transition. */
+    private insertFailureNotice;
+}