sneakoscope 7.3.0 → 7.6.0

package/dist/core/telegram/ingress-spool.js

@@ -0,0 +1,419 @@
+import { redactString } from '../secret-redaction.js';
+import { nowIso, readJson, writeTextAtomic } from '../fsx.js';
+import { withFileLock } from '../locks/file-lock.js';
+export class TelegramIngressSpool {
+    file;
+    options;
+    maxPending;
+    maxCompleted;
+    maxDeadLetters;
+    maxAttempts;
+    identityFingerprint;
+    constructor(file, options) {
+        this.file = file;
+        this.options = options;
+        this.identityFingerprint = options.identityFingerprint ?? options.tokenFingerprint ?? '';
+        if (!/^sha256:[A-Za-z0-9._-]{3,128}$/.test(this.identityFingerprint)) {
+            throw new Error('telegram_ingress_identity_fingerprint_invalid');
+        }
+        this.maxPending = Math.max(16, options.maxPending ?? 512);
+        this.maxCompleted = Math.max(128, options.maxCompleted ?? 4096);
+        this.maxDeadLetters = Math.max(16, options.maxDeadLetters ?? 128);
+        this.maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    }
+    async admit(update) {
+        if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+            throw new Error('telegram_update_id_invalid');
+        }
+        return this.mutate((spool) => {
+            if (spool.completed.some((entry) => entry.update_id === update.update_id))
+                return 'completed';
+            if (spool.dead_letters.some((entry) => entry.update_id === update.update_id))
+                return 'dead_letter';
+            if (spool.pending.some((entry) => entry.update_id === update.update_id))
+                return 'pending';
+            if (spool.pending.length >= this.maxPending) {
+                throw new Error('telegram_ingress_spool_capacity_exceeded');
+            }
+            const at = nowIso();
+            spool.pending.push({
+                update_id: update.update_id,
+                update,
+                routed: null,
+                execution: emptyIngressExecution(),
+                attempts: 0,
+                admitted_at: at,
+                updated_at: at
+            });
+            spool.pending.sort((left, right) => left.update_id - right.update_id);
+            return 'admitted';
+        });
+    }
+    async pending() {
+        const spool = await this.read();
+        return spool.pending.map((entry) => structuredClone(normalizeIngressEntry(entry)));
+    }
+    async execution(updateId) {
+        assertIngressUpdateId(updateId);
+        const spool = await this.read();
+        const entry = spool.pending.find((candidate) => candidate.update_id === updateId);
+        return entry ? structuredClone(normalizeIngressEntry(entry).execution) : null;
+    }
+    async markRouted(updateId, routed) {
+        await this.mutate((spool) => {
+            const index = spool.pending.findIndex((entry) => entry.update_id === updateId);
+            if (index < 0)
+                throw new Error('telegram_ingress_entry_missing');
+            const current = spool.pending[index];
+            spool.pending[index] = {
+                ...normalizeIngressEntry(current),
+                routed,
+                updated_at: nowIso()
+            };
+        });
+    }
+    async markEffectDispatching(updateId) {
+        await this.updateExecution(updateId, (execution) => {
+            if (execution.effect_state === 'dispatching' || execution.effect_state === 'unknown') {
+                throw new Error('telegram_ingress_effect_delivery_ambiguous');
+            }
+            if (execution.effect_state === 'applied' || execution.effect_state === 'rejected')
+                return;
+            execution.effect_state = 'dispatching';
+        });
+    }
+    async markEffectOutcome(updateId, input) {
+        await this.updateExecution(updateId, (execution) => {
+            execution.effect_state = input.effectState;
+            execution.effect_receipt = boundedCheckpointText(input.effectReceipt, 240);
+            execution.final_text = boundedCheckpointText(input.finalText, 16_000);
+            execution.decision = input.decision;
+            execution.policy_reason = boundedCheckpointText(input.policyReason, 240);
+            execution.action_completion = input.actionCompletion;
+        });
+    }
+    async markTelegramDispatching(updateId) {
+        await this.updateExecution(updateId, (execution) => {
+            if (execution.telegram_delivery === 'delivered')
+                return;
+            if (execution.telegram_delivery === 'dispatching' || execution.telegram_delivery === 'unknown') {
+                throw new Error('telegram_ingress_telegram_delivery_ambiguous');
+            }
+            execution.telegram_delivery = 'dispatching';
+            execution.telegram_message_receipt = null;
+        });
+    }
+    async markTelegramDelivered(updateId, receipt) {
+        if (!Number.isInteger(receipt.message_id) || receipt.message_id < 1) {
+            throw new Error('telegram_ingress_message_receipt_invalid');
+        }
+        await this.updateExecution(updateId, (execution) => {
+            execution.telegram_delivery = 'delivered';
+            execution.telegram_message_receipt = {
+                method: boundedCheckpointText(receipt.method, 64) ?? 'sendMessage',
+                message_id: receipt.message_id
+            };
+        });
+    }
+    async markTelegramDeliveryFailure(updateId, delivery) {
+        await this.updateExecution(updateId, (execution) => {
+            execution.telegram_delivery = delivery;
+            execution.telegram_message_receipt = null;
+        });
+    }
+    async markAuditCompleted(updateId) {
+        await this.updateExecution(updateId, (execution) => {
+            execution.audit_state = 'completed';
+        });
+    }
+    async assertIdentityRotationSafe() {
+        const spool = await this.readRaw();
+        if (spool.pending.length > 0 || spool.dead_letters.length > 0) {
+            throw new Error('telegram_ingress_recovery_required_before_identity_change');
+        }
+    }
+    async resetForIdentity() {
+        await withFileLock({
+            lockPath: `${this.file}.lock`,
+            timeoutMs: 5_000,
+            staleMs: 30_000
+        }, async () => {
+            const raw = await this.readRaw();
+            if (raw.pending.length > 0 || raw.dead_letters.length > 0) {
+                throw new Error('telegram_ingress_recovery_required_before_identity_change');
+            }
+            await this.write(this.empty());
+        });
+    }
+    async markCompleted(updateId) {
+        await this.mutate((spool) => {
+            spool.pending = spool.pending.filter((entry) => entry.update_id !== updateId);
+            if (!spool.completed.some((entry) => entry.update_id === updateId)) {
+                spool.completed.push({ update_id: updateId, completed_at: nowIso() });
+            }
+            spool.completed = spool.completed
+                .sort((left, right) => right.update_id - left.update_id)
+                .slice(0, this.maxCompleted);
+        });
+    }
+    async markFailed(updateId, error) {
+        return this.mutate((spool) => {
+            const index = spool.pending.findIndex((entry) => entry.update_id === updateId);
+            if (index < 0)
+                return 'dead_letter';
+            const current = normalizeIngressEntry(spool.pending[index]);
+            const executionAmbiguous = current.execution.effect_state === 'dispatching'
+                || current.execution.effect_state === 'unknown'
+                || current.execution.telegram_delivery === 'dispatching'
+                || current.execution.telegram_delivery === 'unknown';
+            const attempts = current.attempts + 1;
+            if (!executionAmbiguous && attempts < this.maxAttempts) {
+                spool.pending[index] = {
+                    ...current,
+                    attempts,
+                    updated_at: nowIso()
+                };
+                return 'pending';
+            }
+            spool.pending.splice(index, 1);
+            if (spool.dead_letters.length >= this.maxDeadLetters) {
+                throw new Error('telegram_ingress_dead_letter_capacity_exceeded');
+            }
+            const requeueSafe = current.execution.effect_state === 'not_started'
+                && ['not_started', 'not_dispatched'].includes(current.execution.telegram_delivery);
+            spool.dead_letters.push({
+                update_id: updateId,
+                failed_at: nowIso(),
+                error_code: boundedIngressError(error),
+                recovery: requeueSafe ? 'requeue_safe' : 'acknowledge_only',
+                effect_state: requeueSafe ? 'not_started' : 'ambiguous',
+                admitted_at: current.admitted_at,
+                routed_status: current.routed?.status ?? null,
+                update: requeueSafe ? current.update : null
+            });
+            spool.dead_letters = spool.dead_letters
+                .sort((left, right) => right.update_id - left.update_id);
+            return 'dead_letter';
+        });
+    }
+    async nextOffset() {
+        const spool = await this.read();
+        const ids = [
+            ...spool.pending.map((entry) => entry.update_id),
+            ...spool.completed.map((entry) => entry.update_id),
+            ...spool.dead_letters.map((entry) => entry.update_id)
+        ];
+        return ids.length ? Math.max(...ids) + 1 : 0;
+    }
+    async counts() {
+        const spool = await this.read();
+        return {
+            pending: spool.pending.length,
+            completed: spool.completed.length,
+            dead_letters: spool.dead_letters.length
+        };
+    }
+    async deadLetters(updateId) {
+        if (updateId !== undefined)
+            assertIngressUpdateId(updateId);
+        const spool = await this.read();
+        return spool.dead_letters
+            .filter((entry) => updateId === undefined || entry.update_id === updateId)
+            .map((entry) => summarizeDeadLetter(entry));
+    }
+    async requeueDeadLetter(updateId) {
+        assertIngressUpdateId(updateId);
+        return this.mutate((spool) => {
+            const index = spool.dead_letters.findIndex((entry) => entry.update_id === updateId);
+            if (index < 0)
+                throw new Error('telegram_ingress_dead_letter_not_found');
+            const deadLetter = spool.dead_letters[index];
+            if (!deadLetterRequeueAllowed(deadLetter) || !deadLetter.update) {
+                throw new Error('telegram_ingress_dead_letter_requeue_refused_effect_ambiguous');
+            }
+            if (spool.pending.some((entry) => entry.update_id === updateId)
+                || spool.completed.some((entry) => entry.update_id === updateId)) {
+                throw new Error('telegram_ingress_dead_letter_requeue_conflict');
+            }
+            if (spool.pending.length >= this.maxPending) {
+                throw new Error('telegram_ingress_spool_capacity_exceeded');
+            }
+            const at = nowIso();
+            spool.pending.push({
+                update_id: updateId,
+                update: structuredClone(deadLetter.update),
+                routed: null,
+                execution: emptyIngressExecution(),
+                attempts: 0,
+                admitted_at: deadLetter.admitted_at ?? at,
+                updated_at: at
+            });
+            spool.pending.sort((left, right) => left.update_id - right.update_id);
+            spool.dead_letters.splice(index, 1);
+            return summarizeDeadLetter(deadLetter);
+        });
+    }
+    async acknowledgeDeadLetters(updateIds) {
+        const selected = updateIds === undefined ? null : new Set(updateIds);
+        for (const updateId of selected ?? [])
+            assertIngressUpdateId(updateId);
+        return this.mutate((spool) => {
+            if (selected && selected.size > 0) {
+                const existingIds = new Set(spool.dead_letters.map((entry) => entry.update_id));
+                if ([...selected].some((updateId) => !existingIds.has(updateId))) {
+                    throw new Error('telegram_ingress_dead_letter_not_found');
+                }
+            }
+            const acknowledgedEntries = selected === null
+                ? spool.dead_letters
+                : spool.dead_letters.filter((entry) => selected.has(entry.update_id));
+            const acknowledged = acknowledgedEntries.length;
+            if (acknowledged === 0)
+                return 0;
+            const completedAt = nowIso();
+            const completedIds = new Set(spool.completed.map((entry) => entry.update_id));
+            for (const deadLetter of acknowledgedEntries) {
+                if (!completedIds.has(deadLetter.update_id)) {
+                    spool.completed.push({
+                        update_id: deadLetter.update_id,
+                        completed_at: completedAt
+                    });
+                    completedIds.add(deadLetter.update_id);
+                }
+            }
+            spool.completed = spool.completed
+                .sort((left, right) => right.update_id - left.update_id)
+                .slice(0, this.maxCompleted);
+            const acknowledgedIds = new Set(acknowledgedEntries.map((entry) => entry.update_id));
+            spool.dead_letters = spool.dead_letters.filter((entry) => !acknowledgedIds.has(entry.update_id));
+            return acknowledged;
+        });
+    }
+    async read() {
+        const spool = await this.readRaw();
+        const persistedIdentity = spool.identity_fingerprint ?? spool.token_fingerprint ?? null;
+        const legacyIdentityMatches = !spool.identity_fingerprint
+            && Boolean(this.options.legacyTokenFingerprint)
+            && spool.token_fingerprint === this.options.legacyTokenFingerprint;
+        if (persistedIdentity !== this.identityFingerprint && !legacyIdentityMatches) {
+            throw new Error('telegram_ingress_identity_mismatch:run_setup_before_starting_hub');
+        }
+        const { token_fingerprint: _legacyTokenFingerprint, ...current } = spool;
+        return {
+            ...current,
+            identity_fingerprint: this.identityFingerprint,
+            pending: spool.pending.map(normalizeIngressEntry)
+        };
+    }
+    async readRaw() {
+        const spool = await readJson(this.file, this.empty());
+        if (spool.schema !== 'sks.telegram-ingress-spool.v1'
+            || !Array.isArray(spool.pending)
+            || !Array.isArray(spool.completed)
+            || !Array.isArray(spool.dead_letters)) {
+            throw new Error('telegram_ingress_spool_schema_invalid');
+        }
+        return spool;
+    }
+    async mutate(fn) {
+        return withFileLock({
+            lockPath: `${this.file}.lock`,
+            timeoutMs: 5_000,
+            staleMs: 30_000
+        }, async () => {
+            const spool = await this.read();
+            const result = fn(spool);
+            await this.write(spool);
+            return result;
+        });
+    }
+    empty() {
+        return {
+            schema: 'sks.telegram-ingress-spool.v1',
+            identity_fingerprint: this.identityFingerprint,
+            pending: [],
+            completed: [],
+            dead_letters: []
+        };
+    }
+    async updateExecution(updateId, mutateExecution) {
+        assertIngressUpdateId(updateId);
+        await this.mutate((spool) => {
+            const index = spool.pending.findIndex((entry) => entry.update_id === updateId);
+            if (index < 0)
+                throw new Error('telegram_ingress_entry_missing');
+            const current = normalizeIngressEntry(spool.pending[index]);
+            const execution = structuredClone(current.execution);
+            mutateExecution(execution);
+            spool.pending[index] = {
+                ...current,
+                execution,
+                updated_at: nowIso()
+            };
+        });
+    }
+    async write(spool) {
+        await writeTextAtomic(this.file, `${JSON.stringify(spool, null, 2)}\n`, { mode: 0o600 });
+    }
+}
+function boundedIngressError(error) {
+    const message = error instanceof Error ? error.message : String(error || 'telegram_ingress_failed');
+    return redactString(message)
+        .replace(/(?:\/Users|\/home|\/private|\/Volumes|\/etc|\/root|[A-Za-z]:\\)[^\s]+/g, '[path-redacted]')
+        .replace(/[\r\n\t]/g, ' ')
+        .slice(0, 240);
+}
+function summarizeDeadLetter(entry) {
+    const requeueSafe = deadLetterRequeueAllowed(entry);
+    return {
+        schema: 'sks.telegram-ingress-dead-letter.v1',
+        update_id: entry.update_id,
+        failed_at: entry.failed_at,
+        error_code: boundedIngressError(entry.error_code),
+        recovery: requeueSafe ? 'requeue_safe' : 'acknowledge_only',
+        effect_state: requeueSafe ? 'not_started' : 'ambiguous',
+        routed_status: typeof entry.routed_status === 'string' ? entry.routed_status : null
+    };
+}
+function deadLetterRequeueAllowed(entry) {
+    return entry.recovery === 'requeue_safe'
+        && entry.effect_state === 'not_started'
+        && entry.update?.update_id === entry.update_id;
+}
+function assertIngressUpdateId(updateId) {
+    if (!Number.isSafeInteger(updateId) || updateId < 0) {
+        throw new Error('telegram_update_id_invalid');
+    }
+}
+function emptyIngressExecution() {
+    return {
+        effect_state: 'not_started',
+        effect_receipt: null,
+        final_text: null,
+        decision: null,
+        policy_reason: null,
+        action_completion: 'none',
+        telegram_delivery: 'not_started',
+        telegram_message_receipt: null,
+        audit_state: 'pending'
+    };
+}
+function normalizeIngressEntry(entry) {
+    return {
+        ...entry,
+        execution: entry.execution && typeof entry.execution === 'object'
+            ? {
+                ...emptyIngressExecution(),
+                ...entry.execution
+            }
+            : emptyIngressExecution()
+    };
+}
+function boundedCheckpointText(value, maxLength) {
+    if (value === null)
+        return null;
+    return redactString(value)
+        .replace(/(?:\/Users|\/home|\/private|\/Volumes|\/etc|\/root|[A-Za-z]:\\)[^\s]+/g, '[path-redacted]')
+        .replace(/[\r\n\t]/g, ' ')
+        .slice(0, maxLength);
+}