instar 1.3.18 → 1.3.19

package/dist/core/wireRegistrySync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireRegistrySync.js","sourceRoot":"","sources":["../../src/core/wireRegistrySync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAmC,EACnC,IAAuB;IAEvB,MAAM,MAAM,GAAG,CAAC,IAAa,EAAE,EAAW,EAAE,EAAE,CAC5C,IAAI,CAAC,iBAAiB,CAAC,cAAc,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,cAAc,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE1F,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IAE5C,OAAO;QACL,WAAW,EAAE,CAAC,YAAY,EAAE,kBAAkB,CAAC;QAC/C,MAAM;YACJ,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;YACtC,WAAW,CAAC,GAAG,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/feedback-factory/dispatch/dispatch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * dispatch.ts — framework-agnostic port of the dispatch (guidance-out) logic.
+ *
+ * Ports the pure logic of `the-portal/pages/api/instar/dispatches/index.ts` out of
+ * the Next.js handler: the dispatch type/priority vocab, the semver comparison used
+ * for version-compat filtering (an agent only receives a dispatch whose
+ * [minVersion, maxVersion] window includes the agent's version), the list query
+ * filter (since/type/version), and the create-dedup title normalization. The HTTP
+ * wiring + storage are excluded (the app-placement decision); this is the reusable
+ * core. Reference is TypeScript, so equivalence is by faithful transcription +
+ * exhaustive both-sides-of-boundary tests (not a cross-runtime parity harness).
+ */
+export declare const DISPATCH_TYPES: readonly ["strategy", "behavioral", "lesson", "configuration", "security", "action"];
+export type DispatchType = typeof DISPATCH_TYPES[number];
+export declare const DISPATCH_PRIORITIES: readonly ["low", "normal", "high", "critical"];
+export type DispatchPriority = typeof DISPATCH_PRIORITIES[number];
+export declare const SEMVER_RE: RegExp;
+export declare function isValidDispatchType(type: unknown): type is DispatchType;
+export declare function isValidDispatchPriority(p: unknown): p is DispatchPriority;
+/** Port of parseVersion: leading major.minor.patch → [n,n,n]; [0,0,0] if unparseable. */
+export declare function parseVersion(v: string): [number, number, number];
+/** Port of isVersionGte: version >= min (major.minor.patch, equal counts as gte). */
+export declare function isVersionGte(version: string, min: string): boolean;
+/** Port of isVersionLte: version <= max (equal counts as lte). */
+export declare function isVersionLte(version: string, max: string): boolean;
+export interface DispatchRecord {
+    dispatchId: string;
+    type: string;
+    title: string;
+    content?: string;
+    priority?: string;
+    minVersion?: string | null;
+    maxVersion?: string | null;
+    active?: boolean;
+    createdAt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Port of handleList's version-compat filter: a dispatch is included only if the
+ * agent's version is within its [minVersion, maxVersion] window. Mirrors the
+ * reference — applied only when the agent sent a valid-semver version; otherwise
+ * all candidates pass (the caller gates on SEMVER_RE before calling).
+ */
+export declare function filterDispatchesForVersion(dispatches: DispatchRecord[], version: string): DispatchRecord[];
+/** Port of the create-path title normalization used for dedup: trim + cap at 500 chars. */
+export declare function normalizeDispatchTitle(title: string): string;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/feedback-factory/dispatch/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/dispatch/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,cAAc,sFAAuF,CAAC;AACnH,MAAM,MAAM,YAAY,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AACzD,eAAO,MAAM,mBAAmB,gDAAiD,CAAC;AAClF,MAAM,MAAM,gBAAgB,GAAG,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,SAAS,QAA8B,CAAC;AAErD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,YAAY,CAEvE;AACD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAEzE;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAIhE;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlE;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlE;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAM1G;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/feedback-factory/dispatch/dispatch.js

@@ -0,0 +1,72 @@
+/**
+ * dispatch.ts — framework-agnostic port of the dispatch (guidance-out) logic.
+ *
+ * Ports the pure logic of `the-portal/pages/api/instar/dispatches/index.ts` out of
+ * the Next.js handler: the dispatch type/priority vocab, the semver comparison used
+ * for version-compat filtering (an agent only receives a dispatch whose
+ * [minVersion, maxVersion] window includes the agent's version), the list query
+ * filter (since/type/version), and the create-dedup title normalization. The HTTP
+ * wiring + storage are excluded (the app-placement decision); this is the reusable
+ * core. Reference is TypeScript, so equivalence is by faithful transcription +
+ * exhaustive both-sides-of-boundary tests (not a cross-runtime parity harness).
+ */
+export const DISPATCH_TYPES = ['strategy', 'behavioral', 'lesson', 'configuration', 'security', 'action'];
+export const DISPATCH_PRIORITIES = ['low', 'normal', 'high', 'critical'];
+export const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+export function isValidDispatchType(type) {
+    return typeof type === 'string' && DISPATCH_TYPES.includes(type);
+}
+export function isValidDispatchPriority(p) {
+    return typeof p === 'string' && DISPATCH_PRIORITIES.includes(p);
+}
+/** Port of parseVersion: leading major.minor.patch → [n,n,n]; [0,0,0] if unparseable. */
+export function parseVersion(v) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!match)
+        return [0, 0, 0];
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** Port of isVersionGte: version >= min (major.minor.patch, equal counts as gte). */
+export function isVersionGte(version, min) {
+    const v = parseVersion(version);
+    const m = parseVersion(min);
+    for (let i = 0; i < 3; i++) {
+        if (v[i] > m[i])
+            return true;
+        if (v[i] < m[i])
+            return false;
+    }
+    return true; // equal
+}
+/** Port of isVersionLte: version <= max (equal counts as lte). */
+export function isVersionLte(version, max) {
+    const v = parseVersion(version);
+    const m = parseVersion(max);
+    for (let i = 0; i < 3; i++) {
+        if (v[i] < m[i])
+            return true;
+        if (v[i] > m[i])
+            return false;
+    }
+    return true; // equal
+}
+/**
+ * Port of handleList's version-compat filter: a dispatch is included only if the
+ * agent's version is within its [minVersion, maxVersion] window. Mirrors the
+ * reference — applied only when the agent sent a valid-semver version; otherwise
+ * all candidates pass (the caller gates on SEMVER_RE before calling).
+ */
+export function filterDispatchesForVersion(dispatches, version) {
+    return dispatches.filter((d) => {
+        if (d.minVersion && !isVersionGte(version, d.minVersion))
+            return false;
+        if (d.maxVersion && !isVersionLte(version, d.maxVersion))
+            return false;
+        return true;
+    });
+}
+/** Port of the create-path title normalization used for dedup: trim + cap at 500 chars. */
+export function normalizeDispatchTitle(title) {
+    return title.trim().slice(0, 500);
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/feedback-factory/dispatch/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../../src/feedback-factory/dispatch/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/messaging/FencedOutbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * FencedOutbox — fencing-token-gated outbound reply path (spec §8 G3a).
+ *
+ * "No duplicate replies" is enforced here STRUCTURALLY, not by assuming a single
+ * consumer. A reply is sent only while this machine holds the lease at the epoch
+ * the reply was stamped under; a fenced (stale-epoch) machine's in-flight reply
+ * is SUPPRESSED at the send path. The reply is committed to the message ledger
+ * with a deterministic idempotency key (hash(dedupeKey + replyIndex)) so any
+ * machine re-running the same event reproduces it identically — and the ledger
+ * recognizes an already-committed reply and refuses to re-send.
+ *
+ * On a channel with native outbound dedup the idempotency key makes a re-send a
+ * no-op; on a channel without it (Telegram), the dual-medium reply_committed
+ * marker (propagated by the sync layer) is what prevents a failover re-send.
+ */
+import { MessageProcessingLedger } from './MessageProcessingLedger.js';
+export interface FencedOutboxDeps {
+    ledger: MessageProcessingLedger;
+    /** The current effective fencing epoch. */
+    currentEpoch: () => number;
+    /** Whether this machine structurally holds the lease right now. */
+    holdsLease: () => boolean;
+    logger?: (msg: string) => void;
+}
+export interface SendOutcome {
+    sent: boolean;
+    suppressed: boolean;
+    reason: 'sent' | 'already-replied' | 'fenced-no-lease' | 'fenced-stale-epoch' | 'send-failed';
+    idempotencyKey: string;
+}
+export declare class FencedOutbox {
+    private readonly d;
+    constructor(deps: FencedOutboxDeps);
+    private log;
+    /**
+     * Send a reply for `dedupeKey`, stamped under `stampedEpoch` (the epoch the
+     * turn began processing under). Returns the outcome. The actual platform send
+     * is `sendFn`; it is invoked ONLY after the fencing checks pass.
+     */
+    send(dedupeKey: string, replyIndex: number, stampedEpoch: number, sendFn: () => Promise<void>): Promise<SendOutcome>;
+}
+//# sourceMappingURL=FencedOutbox.d.ts.map

package/dist/messaging/FencedOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FencedOutbox.d.ts","sourceRoot":"","sources":["../../src/messaging/FencedOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uBAAuB,EAA8B,MAAM,8BAA8B,CAAC;AAEnG,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,uBAAuB,CAAC;IAChC,2CAA2C;IAC3C,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,mEAAmE;IACnE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,oBAAoB,GAAG,aAAa,CAAC;IAC9F,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAmB;gBAEzB,IAAI,EAAE,gBAAgB;IAIlC,OAAO,CAAC,GAAG;IAIX;;;;OAIG;IACG,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAC1B,OAAO,CAAC,WAAW,CAAC;CAgCxB"}

package/dist/messaging/FencedOutbox.js

@@ -0,0 +1,60 @@
+/**
+ * FencedOutbox — fencing-token-gated outbound reply path (spec §8 G3a).
+ *
+ * "No duplicate replies" is enforced here STRUCTURALLY, not by assuming a single
+ * consumer. A reply is sent only while this machine holds the lease at the epoch
+ * the reply was stamped under; a fenced (stale-epoch) machine's in-flight reply
+ * is SUPPRESSED at the send path. The reply is committed to the message ledger
+ * with a deterministic idempotency key (hash(dedupeKey + replyIndex)) so any
+ * machine re-running the same event reproduces it identically — and the ledger
+ * recognizes an already-committed reply and refuses to re-send.
+ *
+ * On a channel with native outbound dedup the idempotency key makes a re-send a
+ * no-op; on a channel without it (Telegram), the dual-medium reply_committed
+ * marker (propagated by the sync layer) is what prevents a failover re-send.
+ */
+import { computeReplyIdempotencyKey } from './MessageProcessingLedger.js';
+export class FencedOutbox {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    log(m) {
+        this.d.logger?.(`[outbox] ${m}`);
+    }
+    /**
+     * Send a reply for `dedupeKey`, stamped under `stampedEpoch` (the epoch the
+     * turn began processing under). Returns the outcome. The actual platform send
+     * is `sendFn`; it is invoked ONLY after the fencing checks pass.
+     */
+    async send(dedupeKey, replyIndex, stampedEpoch, sendFn) {
+        const idempotencyKey = computeReplyIdempotencyKey(dedupeKey, replyIndex);
+        // Idempotency: if a reply was already committed (locally or via a remote
+        // dual-medium marker), do not send again.
+        if (this.d.ledger.isActedOn(dedupeKey)) {
+            this.log(`already replied to ${dedupeKey} — suppressing`);
+            return { sent: false, suppressed: true, reason: 'already-replied', idempotencyKey };
+        }
+        // Fencing: only the current lease holder, at the stamped epoch, may send.
+        if (!this.d.holdsLease()) {
+            this.log(`fenced (no lease) — suppressing reply to ${dedupeKey}`);
+            return { sent: false, suppressed: true, reason: 'fenced-no-lease', idempotencyKey };
+        }
+        const epoch = this.d.currentEpoch();
+        if (epoch !== stampedEpoch) {
+            this.log(`fenced (stale epoch ${stampedEpoch} != current ${epoch}) — suppressing reply to ${dedupeKey}`);
+            return { sent: false, suppressed: true, reason: 'fenced-stale-epoch', idempotencyKey };
+        }
+        try {
+            await sendFn();
+        }
+        catch (err) {
+            this.log(`send failed for ${dedupeKey}: ${err instanceof Error ? err.message : String(err)}`);
+            return { sent: false, suppressed: false, reason: 'send-failed', idempotencyKey };
+        }
+        // Commit the reply marker (durable, synchronous) BEFORE advancing the cursor.
+        this.d.ledger.commitReply(dedupeKey, idempotencyKey, stampedEpoch);
+        return { sent: true, suppressed: false, reason: 'sent', idempotencyKey };
+    }
+}
+//# sourceMappingURL=FencedOutbox.js.map

package/dist/messaging/FencedOutbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FencedOutbox.js","sourceRoot":"","sources":["../../src/messaging/FencedOutbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA2B,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAkBnG,MAAM,OAAO,YAAY;IACN,CAAC,CAAmB;IAErC,YAAY,IAAsB;QAChC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IAChB,CAAC;IAEO,GAAG,CAAC,CAAS;QACnB,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,UAAkB,EAClB,YAAoB,EACpB,MAA2B;QAE3B,MAAM,cAAc,GAAG,0BAA0B,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QAEzE,yEAAyE;QACzE,0CAA0C;QAC1C,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,sBAAsB,SAAS,gBAAgB,CAAC,CAAC;YAC1D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;QACtF,CAAC;QAED,0EAA0E;QAC1E,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,4CAA4C,SAAS,EAAE,CAAC,CAAC;YAClE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;QACtF,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;QACpC,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,uBAAuB,YAAY,eAAe,KAAK,4BAA4B,SAAS,EAAE,CAAC,CAAC;YACzG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,cAAc,EAAE,CAAC;QACzF,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,EAAE,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,mBAAmB,SAAS,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;QACnF,CAAC;QAED,8EAA8E;QAC9E,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAC3E,CAAC;CACF"}

package/dist/messaging/MessageProcessingLedger.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MessageProcessingLedger — the no-loss / no-duplicate-reply guarantee (spec §8 G3a).
+ *
+ * A durable, SQLite-backed record of each inbound message's lifecycle:
+ *   received → processing → reply_committed → cursor_advanced
+ * keyed by the adapter's `dedupeKey(rawEvent)` (Telegram update_id, Slack
+ * event_id/client_msg_id). Rules:
+ *
+ *  - An event whose dedupeKey is already reply_committed/cursor_advanced is
+ *    NEVER acted on again — a redelivery (Telegram retry, Slack reconnect, or a
+ *    transfer-window overlap during a handoff) is recognized and dropped. This
+ *    is what makes "no duplicate replies" structural, not merely "only one
+ *    consumer".
+ *  - The ingress cursor advances ONLY on durable completion (cursor_advanced),
+ *    so a crash before completion replays the event (at-least-once) and the
+ *    ledger makes the replay a no-op-or-resume (exactly-once effect).
+ *  - Each transition is flushed to local SQLite synchronously on commit (WAL +
+ *    NORMAL), so a same-machine crash-restart never double-acts.
+ *  - A stuck `processing` entry past maxProcessingMs (old holder fenced
+ *    mid-turn) is re-runnable by the current holder from its stored input.
+ *
+ * Substrate is SQLite (the proven PendingRelayStore/CommitmentTracker path) —
+ * NOT a new ad-hoc JSON file and NOT a git-synced blob. Schema self-initializes
+ * on first access (no PostUpdateMigrator step needed). Per-agent-id isolation.
+ */
+export type LedgerState = 'received' | 'processing' | 'reply_committed' | 'cursor_advanced';
+export interface LedgerEntry {
+    dedupeKey: string;
+    platform: string;
+    topic: string | null;
+    state: LedgerState;
+    receivedAt: string;
+    processingStartedAt: string | null;
+    replyCommittedAt: string | null;
+    cursorAdvancedAt: string | null;
+    replyIdempotencyKey: string | null;
+    replyEpoch: number | null;
+    inputSnapshot: string | null;
+    attempts: number;
+}
+export declare function resolveMessageLedgerPath(stateDir: string, agentId: string): string;
+/**
+ * Deterministic outbound idempotency key — any machine re-running the same
+ * inbound event reproduces it identically (spec §8 G3a). Used so a failover
+ * re-send is recognized as the same reply.
+ */
+export declare function computeReplyIdempotencyKey(dedupeKey: string, replyIndex: number): string;
+export declare class MessageProcessingLedger {
+    private readonly db;
+    readonly path: string;
+    private constructor();
+    static open(agentId: string, stateDir: string): MessageProcessingLedger;
+    /** Open an in-memory ledger (tests). */
+    static openMemory(): MessageProcessingLedger;
+    /**
+     * Record an inbound event. Idempotent on dedupeKey (INSERT OR IGNORE).
+     * Returns whether this is the first time we've seen it + the current state.
+     * A caller seeing firstSeen:false with an acted-on state must DROP the event.
+     */
+    record(dedupeKey: string, opts: {
+        platform: string;
+        topic?: string | null;
+        input?: string;
+    }): {
+        firstSeen: boolean;
+        state: LedgerState;
+    };
+    /** Has this event already been acted on (reply committed or cursor advanced)? */
+    isActedOn(dedupeKey: string): boolean;
+    /**
+     * Claim an event for processing under the given fencing epoch. Returns false
+     * if it has already been acted on (drop). A stuck 'processing' entry can be
+     * re-claimed (the old holder was fenced); attempts is incremented.
+     */
+    beginProcessing(dedupeKey: string, epoch: number): boolean;
+    /**
+     * Commit that a reply was sent. Records the deterministic idempotency key and
+     * the fencing epoch it was committed under. Idempotent — committing twice is
+     * a no-op (the marker already exists).
+     */
+    commitReply(dedupeKey: string, replyIdempotencyKey: string, epoch: number): void;
+    /** Advance the ingress cursor — only call after durable reply commit. */
+    advanceCursor(dedupeKey: string): void;
+    /**
+     * Apply a reply_committed marker propagated from another machine (dual-medium
+     * marker, spec §8 G3a): if we have the entry and it's not yet acted on, mark
+     * it committed so a failover does not re-send. Creates the entry if unknown
+     * (the other machine saw it first).
+     */
+    applyRemoteReplyMarker(dedupeKey: string, opts: {
+        platform: string;
+        replyIdempotencyKey: string;
+        epoch: number;
+        topic?: string | null;
+    }): void;
+    /**
+     * Entries stuck in 'processing' past maxProcessingMs — eligible for re-run by
+     * the current lease holder from their stored input (spec §8 G3a). The old
+     * holder's abandoned output is discarded (the new holder re-executes).
+     */
+    reclaimStuck(maxProcessingMs: number, nowMs?: number): LedgerEntry[];
+    get(dedupeKey: string): LedgerEntry | null;
+    close(): void;
+}
+//# sourceMappingURL=MessageProcessingLedger.d.ts.map

package/dist/messaging/MessageProcessingLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageProcessingLedger.d.ts","sourceRoot":"","sources":["../../src/messaging/MessageProcessingLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAE5F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoBD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExF;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAuB;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO;IAKP,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB;IAYvE,wCAAwC;IACxC,MAAM,CAAC,UAAU,IAAI,uBAAuB;IAO5C;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG;QAC5F,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,WAAW,CAAC;KACpB;IAYD,iFAAiF;IACjF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAKrC;;;;OAIG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAc1D;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAUhF,yEAAyE;IACzE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAStC;;;;;OAKG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAe9I;;;;OAIG;IACH,YAAY,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,WAAW,EAAE;IAahF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAK1C,KAAK,IAAI,IAAI;CAGd"}

package/dist/messaging/MessageProcessingLedger.js

@@ -0,0 +1,206 @@
+/**
+ * MessageProcessingLedger — the no-loss / no-duplicate-reply guarantee (spec §8 G3a).
+ *
+ * A durable, SQLite-backed record of each inbound message's lifecycle:
+ *   received → processing → reply_committed → cursor_advanced
+ * keyed by the adapter's `dedupeKey(rawEvent)` (Telegram update_id, Slack
+ * event_id/client_msg_id). Rules:
+ *
+ *  - An event whose dedupeKey is already reply_committed/cursor_advanced is
+ *    NEVER acted on again — a redelivery (Telegram retry, Slack reconnect, or a
+ *    transfer-window overlap during a handoff) is recognized and dropped. This
+ *    is what makes "no duplicate replies" structural, not merely "only one
+ *    consumer".
+ *  - The ingress cursor advances ONLY on durable completion (cursor_advanced),
+ *    so a crash before completion replays the event (at-least-once) and the
+ *    ledger makes the replay a no-op-or-resume (exactly-once effect).
+ *  - Each transition is flushed to local SQLite synchronously on commit (WAL +
+ *    NORMAL), so a same-machine crash-restart never double-acts.
+ *  - A stuck `processing` entry past maxProcessingMs (old holder fenced
+ *    mid-turn) is re-runnable by the current holder from its stored input.
+ *
+ * Substrate is SQLite (the proven PendingRelayStore/CommitmentTracker path) —
+ * NOT a new ad-hoc JSON file and NOT a git-synced blob. Schema self-initializes
+ * on first access (no PostUpdateMigrator step needed). Per-agent-id isolation.
+ */
+import Database from 'better-sqlite3';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS message_ledger (
+  dedupe_key TEXT PRIMARY KEY,
+  platform TEXT NOT NULL,
+  topic TEXT,
+  state TEXT NOT NULL,
+  received_at TEXT NOT NULL,
+  processing_started_at TEXT,
+  reply_committed_at TEXT,
+  cursor_advanced_at TEXT,
+  reply_idempotency_key TEXT,
+  reply_epoch INTEGER,
+  input_snapshot TEXT,
+  attempts INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_message_ledger_state ON message_ledger(state);
+`;
+export function resolveMessageLedgerPath(stateDir, agentId) {
+    const safe = agentId.replace(/[^A-Za-z0-9._-]/g, '_') || 'default';
+    return path.join(stateDir, 'state', `message-ledger.${safe}.sqlite`);
+}
+/**
+ * Deterministic outbound idempotency key — any machine re-running the same
+ * inbound event reproduces it identically (spec §8 G3a). Used so a failover
+ * re-send is recognized as the same reply.
+ */
+export function computeReplyIdempotencyKey(dedupeKey, replyIndex) {
+    return crypto.createHash('sha256').update(`${dedupeKey}::${replyIndex}`).digest('hex').slice(0, 32);
+}
+export class MessageProcessingLedger {
+    db;
+    path;
+    constructor(db, dbPath) {
+        this.db = db;
+        this.path = dbPath;
+    }
+    static open(agentId, stateDir) {
+        const dbPath = resolveMessageLedgerPath(stateDir, agentId);
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        const db = new Database(dbPath);
+        try {
+            fs.chmodSync(dbPath, 0o600);
+        }
+        catch { /* best-effort */ }
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = NORMAL');
+        db.pragma('busy_timeout = 5000');
+        db.exec(SCHEMA);
+        return new MessageProcessingLedger(db, dbPath);
+    }
+    /** Open an in-memory ledger (tests). */
+    static openMemory() {
+        const db = new Database(':memory:');
+        db.pragma('busy_timeout = 5000');
+        db.exec(SCHEMA);
+        return new MessageProcessingLedger(db, ':memory:');
+    }
+    /**
+     * Record an inbound event. Idempotent on dedupeKey (INSERT OR IGNORE).
+     * Returns whether this is the first time we've seen it + the current state.
+     * A caller seeing firstSeen:false with an acted-on state must DROP the event.
+     */
+    record(dedupeKey, opts) {
+        const now = new Date().toISOString();
+        const info = this.db
+            .prepare(`INSERT OR IGNORE INTO message_ledger (dedupe_key, platform, topic, state, received_at, input_snapshot)
+         VALUES (?, ?, ?, 'received', ?, ?)`)
+            .run(dedupeKey, opts.platform, opts.topic ?? null, now, opts.input ?? null);
+        const row = this.get(dedupeKey);
+        return { firstSeen: info.changes === 1, state: row.state };
+    }
+    /** Has this event already been acted on (reply committed or cursor advanced)? */
+    isActedOn(dedupeKey) {
+        const row = this.get(dedupeKey);
+        return !!row && (row.state === 'reply_committed' || row.state === 'cursor_advanced');
+    }
+    /**
+     * Claim an event for processing under the given fencing epoch. Returns false
+     * if it has already been acted on (drop). A stuck 'processing' entry can be
+     * re-claimed (the old holder was fenced); attempts is incremented.
+     */
+    beginProcessing(dedupeKey, epoch) {
+        const row = this.get(dedupeKey);
+        if (!row)
+            return false;
+        if (row.state === 'reply_committed' || row.state === 'cursor_advanced')
+            return false;
+        this.db
+            .prepare(`UPDATE message_ledger
+         SET state = 'processing', processing_started_at = ?, reply_epoch = ?, attempts = attempts + 1
+         WHERE dedupe_key = ?`)
+            .run(new Date().toISOString(), epoch, dedupeKey);
+        return true;
+    }
+    /**
+     * Commit that a reply was sent. Records the deterministic idempotency key and
+     * the fencing epoch it was committed under. Idempotent — committing twice is
+     * a no-op (the marker already exists).
+     */
+    commitReply(dedupeKey, replyIdempotencyKey, epoch) {
+        this.db
+            .prepare(`UPDATE message_ledger
+         SET state = 'reply_committed', reply_committed_at = ?, reply_idempotency_key = ?, reply_epoch = ?
+         WHERE dedupe_key = ? AND state NOT IN ('reply_committed','cursor_advanced')`)
+            .run(new Date().toISOString(), replyIdempotencyKey, epoch, dedupeKey);
+    }
+    /** Advance the ingress cursor — only call after durable reply commit. */
+    advanceCursor(dedupeKey) {
+        this.db
+            .prepare(`UPDATE message_ledger SET state = 'cursor_advanced', cursor_advanced_at = ?
+         WHERE dedupe_key = ? AND state = 'reply_committed'`)
+            .run(new Date().toISOString(), dedupeKey);
+    }
+    /**
+     * Apply a reply_committed marker propagated from another machine (dual-medium
+     * marker, spec §8 G3a): if we have the entry and it's not yet acted on, mark
+     * it committed so a failover does not re-send. Creates the entry if unknown
+     * (the other machine saw it first).
+     */
+    applyRemoteReplyMarker(dedupeKey, opts) {
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO message_ledger (dedupe_key, platform, topic, state, received_at, reply_committed_at, reply_idempotency_key, reply_epoch)
+         VALUES (?, ?, ?, 'reply_committed', ?, ?, ?, ?)
+         ON CONFLICT(dedupe_key) DO UPDATE SET
+           state = CASE WHEN message_ledger.state IN ('reply_committed','cursor_advanced') THEN message_ledger.state ELSE 'reply_committed' END,
+           reply_committed_at = COALESCE(message_ledger.reply_committed_at, excluded.reply_committed_at),
+           reply_idempotency_key = COALESCE(message_ledger.reply_idempotency_key, excluded.reply_idempotency_key),
+           reply_epoch = COALESCE(message_ledger.reply_epoch, excluded.reply_epoch)`)
+            .run(dedupeKey, opts.platform, opts.topic ?? null, now, now, opts.replyIdempotencyKey, opts.epoch);
+    }
+    /**
+     * Entries stuck in 'processing' past maxProcessingMs — eligible for re-run by
+     * the current lease holder from their stored input (spec §8 G3a). The old
+     * holder's abandoned output is discarded (the new holder re-executes).
+     */
+    reclaimStuck(maxProcessingMs, nowMs = Date.now()) {
+        const rows = this.db
+            .prepare(`SELECT * FROM message_ledger WHERE state = 'processing'`)
+            .all();
+        return rows
+            .map(rowToEntry)
+            .filter((e) => {
+            if (!e.processingStartedAt)
+                return false;
+            const startedMs = Date.parse(e.processingStartedAt);
+            return !Number.isNaN(startedMs) && nowMs - startedMs > maxProcessingMs;
+        });
+    }
+    get(dedupeKey) {
+        const row = this.db.prepare(`SELECT * FROM message_ledger WHERE dedupe_key = ?`).get(dedupeKey);
+        return row ? rowToEntry(row) : null;
+    }
+    close() {
+        try {
+            this.db.close();
+        }
+        catch { /* best-effort */ }
+    }
+}
+function rowToEntry(row) {
+    return {
+        dedupeKey: row.dedupe_key,
+        platform: row.platform,
+        topic: row.topic ?? null,
+        state: row.state,
+        receivedAt: row.received_at,
+        processingStartedAt: row.processing_started_at ?? null,
+        replyCommittedAt: row.reply_committed_at ?? null,
+        cursorAdvancedAt: row.cursor_advanced_at ?? null,
+        replyIdempotencyKey: row.reply_idempotency_key ?? null,
+        replyEpoch: row.reply_epoch ?? null,
+        inputSnapshot: row.input_snapshot ?? null,
+        attempts: row.attempts ?? 0,
+    };
+}
+//# sourceMappingURL=MessageProcessingLedger.js.map

package/dist/messaging/MessageProcessingLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageProcessingLedger.js","sourceRoot":"","sources":["../../src/messaging/MessageProcessingLedger.ts"],"names":[],"mappings":"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"}

package/dist/messaging/TelegramAdapter.d.ts

@@ -8,7 +8,7 @@
  *
  * No external dependencies — uses native fetch for Telegram API calls.
  */
-import type { MessagingAdapter, Message, OutgoingMessage, IntelligenceProvider } from '../core/types.js';
+import type { MessagingAdapter, Message, OutgoingMessage, IntelligenceProvider, IngressPosition } from '../core/types.js';
 import { NotificationBatcher, NotificationTier } from './NotificationBatcher.js';
 import type { ContentValidationConfig } from './TopicContentValidator.js';
 import { MessagingEventBus } from './shared/MessagingEventBus.js';
@@ -320,6 +320,23 @@ export declare class TelegramAdapter implements MessagingAdapter {
     private registerSharedCommands;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Stable provider-level identity for an inbound update — the Telegram
+     * update_id. Used by the message-processing ledger so a redelivered update
+     * (retry / reconnect / transfer-window overlap) is recognized and not
+     * re-acted-on.
+     */
+    dedupeKey(rawEvent: unknown): string;
+    /** The durable resumable position — the long-poll update_id offset. */
+    getIngressPosition(): IngressPosition;
+    /**
+     * Stop the inbound loop deterministically and return the durable position
+     * AFTER the stop (the persisted offset), so a handoff resumes from exactly
+     * where this machine left off — never replaying or skipping.
+     */
+    stopConsuming(): Promise<IngressPosition>;
+    /** Resume the inbound loop from exactly the given position. */
+    resumeConsuming(position: IngressPosition): Promise<void>;
     send(message: OutgoingMessage): Promise<SendResult>;
     /**
      * Log an inbound user message that arrived via an external path (e.g. Lifeline