instar 1.3.1661 → 1.3.1663

package/dist/threadline/requiredAckService.d.ts

@@ -0,0 +1,223 @@
+/**
+ * RequiredAckService — the production behaviour of
+ * docs/specs/a2a-required-acknowledgment.md, kept out of server.ts and routes.ts
+ * so the tests run the same code the server runs.
+ *
+ * Enforcement is detection and telling the sender. Nothing here blocks a session or
+ * a message, nothing is typed into the SENDER's session, and no kinded ack starts or
+ * wakes a session. The only input ever typed into a session is one fixed reminder,
+ * on the receiving side, carrying server handles only.
+ */
+import type { A2ADeliveryTracker } from './A2ADeliveryTracker.js';
+import { type KindedAckWire } from './requiredAck.js';
+export declare const DEFAULT_REMINDER_MS: number;
+export declare const DEFAULT_ATTENTION_MS: number;
+export declare const DEFAULT_REMINDER_DAILY_CAP = 20;
+export declare const PENDING_TICK_MS: number;
+export declare const PENDING_MAX_BACKOFF_MS: number;
+export declare const PENDING_TTL_MS: number;
+export declare const KINDED_ACK_PER_MINUTE = 20;
+export interface RequiredAckConfigShape {
+    threadline?: {
+        requiredAck?: {
+            enabled?: boolean;
+            reminderMs?: number;
+            attentionMs?: number;
+            reminderDailyCap?: number;
+        };
+    };
+}
+/** On unless explicitly false: omitted means on. */
+export declare function resolveRequiredAckEnabled(liveEnabled: boolean | undefined, config: RequiredAckConfigShape): boolean;
+export interface RequiredAckThresholds {
+    reminderMs: number;
+    attentionMs: number;
+    reminderDailyCap: number;
+}
+export declare function resolveRequiredAckThresholds(config: RequiredAckConfigShape): RequiredAckThresholds;
+/** Where a kinded ack goes out: this machine's relay client, or the holder over the mesh. */
+export type KindedAckRoute = {
+    kind: 'relay';
+    send: (peerFp: string, ack: KindedAckWire, text: string, opts: {
+        threadId: string | null;
+        triggerEncrypted: boolean;
+    }) => void;
+} | {
+    kind: 'forward';
+    send: (payload: ForwardAckPayload) => Promise<'sent' | 'refused'>;
+} | {
+    kind: 'none';
+};
+export interface ForwardAckPayload {
+    peerFp: string;
+    ack: KindedAckWire;
+    text: string;
+    threadId: string | null;
+    triggerEncrypted: boolean;
+    /** The capability this machine has for the peer, for a new holder without a row. */
+    ackKinds: number | null;
+}
+export interface RequiredAckDeps {
+    tracker: A2ADeliveryTracker;
+    enabled: () => boolean;
+    thresholds: () => RequiredAckThresholds;
+    route: () => KindedAckRoute;
+    /** A relay standby: a missing caps row means unknown, and the holder decides. */
+    isStandby: () => boolean;
+    hasTrustProfile: (peerFp: string) => boolean;
+    /** Peer paired by invite: its `read` must arrive encrypted and signed. */
+    isPinned: (peerFp: string) => boolean;
+    isSessionAlive: (sessionName: string) => boolean;
+    /** Type fixed text into a session as queued input. Never peer text. */
+    injectReminder: (sessionName: string, text: string) => boolean;
+    /** The launch lane of a live session, when known. */
+    laneOf?: (sessionName: string) => 'interactive' | 'headless' | null;
+    /** The peer of a thread, when no watch row names it. */
+    threadPeer?: (threadId: string) => string | null;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/** What the relay handler carries through the router for one watched message. */
+export interface RequiredAckHandle {
+    watchId: number;
+    ackRef: string;
+    instruction: string;
+    receipt: QueuedReceipt;
+}
+/** Travels with a spawn-queue entry so the queue can report its fate. No content. */
+export interface QueuedReceipt {
+    watchId: number;
+    peerFp: string;
+    messageId: string;
+    threadId: string | null;
+}
+export type QueueDropCause = 'expired' | 'evicted';
+export interface RouterResultShape {
+    delivered?: boolean;
+    queued?: boolean;
+    spawnQueued?: boolean;
+    error?: string;
+    threadId?: string;
+    sessionName?: string;
+    path?: string;
+    remoteTopic?: boolean;
+    deliveryPending?: Promise<{
+        delivered: boolean;
+        reason: string;
+    }>;
+}
+export interface AckToolResult {
+    status: number;
+    body: Record<string, unknown>;
+}
+export declare class RequiredAckService {
+    private readonly d;
+    private readonly outboundLimited;
+    private readonly inboundLimited;
+    private timer;
+    private ticking;
+    private flushChain;
+    /** Kinded acks consumed with no effect, by why. Log-only evidence on the authed read. */
+    readonly counters: {
+        honoured: number;
+        ignoredRow: number;
+        ignoredUnverified: number;
+        ignoredUnknownKind: number;
+        inboundLimited: number;
+        heldSent: number;
+        heldSkippedLimit: number;
+        reminders: number;
+        unacknowledged: number;
+        pendingSent: number;
+        pendingExpired: number;
+    };
+    constructor(deps: RequiredAckDeps);
+    private nowMs;
+    private iso;
+    private get store();
+    private log;
+    /**
+     * Boot: journal rows still open were interrupted by a restart, and become pending
+     * `unknown`. The wording does not assert loss, because a crash between hand-off
+     * and the callback looks the same.
+     */
+    recoverAfterRestart(): number;
+    /** The new 30-second timer (the tracker's only other one is a 15-minute sweep). */
+    start(intervalMs?: number): void;
+    stop(): void;
+    /** Called after the trust check for every non-ack, non-status message. */
+    notePeerMessage(peerFp: string, content: unknown): void;
+    /**
+     * The ack-stage branch. Honoured only when EVERY referenced id is a row we sent to
+     * this same fingerprint; otherwise consumed and logged with no effect, which covers
+     * strangers and the relay. `held` calls nothing on the delivery state; `read` flips
+     * exactly its rows. Never acks, never routes, never starts or wakes a session.
+     */
+    consumeInboundAck(input: {
+        from: string;
+        ack: KindedAckWire;
+        arrivedEncrypted: boolean;
+    }): 'honoured' | 'ignored' | 'limited';
+    /**
+     * The handle for one inbound message about to go through the router, or null when
+     * the feature is off, the peer has not advertised support, or the message has no id
+     * to refer to.
+     */
+    prepare(input: {
+        peerFp: string;
+        messageId: string | undefined;
+        threadId: string | null | undefined;
+        triggerEncrypted: boolean;
+    }): RequiredAckHandle | null;
+    /** Settle one router result. Never throws into routing. */
+    settleRouterResult(handle: RequiredAckHandle | null, result: RouterResultShape): void;
+    /**
+     * A session received the message: the router's report, or the spawn manager's
+     * delivered callback from its queue commit. A later expiry of an earlier queued
+     * copy then sends nothing, because the row records the hand-off.
+     */
+    onDelivered(receipt: QueuedReceipt, session: {
+        sessionName: string | null;
+        interactive?: boolean;
+        threadId?: string | null;
+    }): void;
+    /** D3: a queue entry died at one of the spawn manager's drop sites. */
+    onQueueDropped(receipt: QueuedReceipt, cause: QueueDropCause): void;
+    /** D5 close: a session-authored send was accepted. The caller guarantees "session-authored + accepted". */
+    onSessionSendAccepted(peerFp: string | null | undefined, threadId: string | null | undefined): void;
+    /** POST /threadline/ack. Success means the `read` is durably accepted as a pending row. */
+    acceptSessionAck(input: {
+        threadId?: unknown;
+        ackRefs?: unknown;
+        summary?: unknown;
+    }): Promise<AckToolResult>;
+    /** One pass: reminders, unacknowledged, pending sends. Single-flight, bounded. */
+    tick(): Promise<void>;
+    private runWatchPass;
+    /** Send every due pending row, coalesced per peer and outcome. One pass at a time. */
+    flushPending(): Promise<number>;
+    private runFlush;
+    private sendBatch;
+    /**
+     * `a2a-relay-forward-ack`: the machine holding the relay sends a standby's kinded
+     * ack. Decides from its own caps row, else the capability the standby has, for a
+     * new holder without a row.
+     */
+    handleForwardedAck(payload: Partial<ForwardAckPayload>, deps: {
+        relay: Extract<KindedAckRoute, {
+            kind: 'relay';
+        }> | null;
+    }): {
+        outcome: 'sent';
+    } | {
+        outcome: 'refused';
+        reason: string;
+    };
+    private queuePending;
+    /** Immediate `held` receipts are best-effort: over the limit or on a failed send, nothing more happens. */
+    private sendHeldBestEffort;
+    private reasonFor;
+    private safeHasProfile;
+    private safeAlive;
+}
+//# sourceMappingURL=requiredAckService.d.ts.map

package/dist/threadline/requiredAckService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requiredAckService.d.ts","sourceRoot":"","sources":["../../src/threadline/requiredAckService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE,OAAO,EAYL,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AACjD,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AACnD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,eAAe,QAAY,CAAC;AACzC,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AACrD,eAAO,MAAM,cAAc,QAAiB,CAAC;AAC7C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAGxC,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,OAAO,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CAC5H;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,EAAE,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAEnH;AAED,MAAM,WAAW,qBAAqB;IAAG,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE;AAE5G,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,sBAAsB,GAAG,qBAAqB,CAOlG;AAED,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;CAAE,GACjJ;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,aAAa,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,qBAAqB,CAAC;IACxC,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,iFAAiF;IACjF,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7C,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,uEAAuE;IACvE,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC/D,qDAAqD;IACrD,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,aAAa,GAAG,UAAU,GAAG,IAAI,CAAC;IACpE,wDAAwD;IACxD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAkB;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAuC;IACzD,yFAAyF;IACzF,QAAQ,CAAC,QAAQ;QAAK,QAAQ;QAAK,UAAU;QAAK,iBAAiB;QAAK,kBAAkB;QAAK,cAAc;QAAK,QAAQ;QAAK,gBAAgB;QAAK,SAAS;QAAK,cAAc;QAAK,WAAW;QAAK,cAAc;MAAM;IAEzN,YAAY,IAAI,EAAE,eAAe,EAKhC;IAED,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,GAAG;IACX,OAAO,KAAK,KAAK,GAAsC;IACvD,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACH,mBAAmB,IAAI,MAAM,CAU5B;IAED,mFAAmF;IACnF,KAAK,CAAC,UAAU,GAAE,MAAwB,GAAG,IAAI,CAIhD;IAED,IAAI,IAAI,IAAI,CAGX;IAID,0EAA0E;IAC1E,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAKtD;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,aAAa,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAA;KAAE,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAwC5H;IAID;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;QAAC,gBAAgB,EAAE,OAAO,CAAA;KAAE,GAAG,iBAAiB,GAAG,IAAI,CAkB1J;IAID,2DAA2D;IAC3D,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAuCpF;IAED;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAUlI;IAED,uEAAuE;IACvE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAclE;IAED,2GAA2G;IAC3G,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAKlG;IAID,2FAA2F;IACrF,gBAAgB,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAwClH;IAID,kFAAkF;IAC5E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAW1B;IAED,OAAO,CAAC,YAAY;IA2CpB,sFAAsF;IACtF,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAI9B;YAEa,QAAQ;YA4BR,SAAS;IA+CvB;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC,cAAc,EAAE;YAAE,IAAI,EAAE,OAAO,CAAA;SAAE,CAAC,GAAG,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAiBxL;IAID,OAAO,CAAC,YAAY;IAWpB,2GAA2G;IAC3G,OAAO,CAAC,kBAAkB;IAoB1B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,SAAS;CAGlB"}