@jungjaehoon/mama-os 0.32.2 → 0.33.0

package/dist/gateways/telegram-report-context-store.d.ts

@@ -0,0 +1,193 @@
+/**
+ * TG-05/TG-06: Telegram owner-report context inbox store.
+ *
+ * The messenger SQLite database is the single report-context authority for
+ * owner-report delivery events and turn-consumption receipts
+ * (docs/development/telegram-outbound-context-inbox-design.md, Decision 4).
+ */
+import type { SQLiteDatabase } from '../sqlite.js';
+export type ReportContextEventState = 'prepared_retryable' | 'prepared_definite_rejection' | 'delivered' | 'cancelled';
+export interface ReportContextTarget {
+    source: 'telegram';
+    channelId: string;
+}
+export interface ReportContextReservationInput {
+    deliveryId: string;
+    target: ReportContextTarget;
+    mode: 'digest' | 'full';
+    occurrence: Record<string, unknown>;
+    provenance?: Record<string, unknown>;
+    text: string;
+    payloadIdentity: string;
+}
+export interface ReportContextEvent {
+    seq: number;
+    deliveryId: string;
+    state: ReportContextEventState;
+}
+export interface ReportContextEventDetail extends ReportContextEvent {
+    attemptCount: number;
+    nextAttemptAt: string | null;
+    leaseUntil: string | null;
+    rejectionReason: string | null;
+    cancelReason: string | null;
+}
+export interface TelegramReportContextStoreOptions {
+    nowIso?: () => string;
+    /**
+     * TG-05 Slice K (design Decision 8): when set, the constructor solely
+     * migrates the legacy V2 carry file (last-full-report.json) into the
+     * event/legacy-restoration tables and renames the source `.migrated`.
+     * No component reads or writes V2 afterward.
+     */
+    legacyCarryPath?: string;
+    /** Design Decision 5 live capacity (prepared-or-unconsumed) per target. */
+    liveRowCapPerTarget?: number;
+    liveByteCapPerTarget?: number;
+    /** Retained exact-text capacity per target before consumed rows compact. */
+    retainedRowCapPerTarget?: number;
+    retainedByteCapPerTarget?: number;
+}
+export declare class TelegramReportContextStore {
+    private readonly db;
+    private readonly nowIso;
+    private readonly liveRowCap;
+    private readonly liveByteCap;
+    private readonly retainedRowCap;
+    private readonly retainedByteCap;
+    constructor(db: SQLiteDatabase, options?: TelegramReportContextStoreOptions);
+    /**
+     * TG-05 Slice K: migrate the legacy V2 carry file. Unconsumed -> a
+     * delivered-pending event (even past the old 24h TTL); consumed -> a
+     * target-scoped legacy restoration record carrying the EXACT old prefix
+     * bytes. Transactionally insert/verify, commit, then atomically rename the
+     * source `.migrated`. Invalid files are quarantined and never injected.
+     */
+    private migrateLegacyCarry;
+    /**
+     * Idempotently insert the exact prepared report before any external send.
+     * A replay of the same delivery ID must carry the identical payload; any
+     * divergence is an identity conflict and never silently overwrites.
+     */
+    reserve(input: ReportContextReservationInput): ReportContextEvent;
+    /**
+     * Atomically transition a confirmed send to `delivered`. Idempotent: an
+     * already-delivered row keeps its original delivery time so crash-recovery
+     * replays converge instead of rewriting history.
+     */
+    markDelivered(deliveryId: string, deliveredAtIso: string): void;
+    /**
+     * Compare-and-swap attempt lease: exactly one holder may execute a Telegram
+     * send at a time. A live lease excludes every new claim - another worker,
+     * another tick, or the same owner - and an expired lease is recoverable
+     * after restart. Returns null when no claim is possible.
+     */
+    claimAttempt(deliveryId: string, owner: string, nowIso: string, leaseUntilIso: string): {
+        deliveryId: string;
+        owner: string;
+        leaseUntilIso: string;
+    } | null;
+    /**
+     * Safe cancellation (design Decision 3): permitted only from
+     * prepared_definite_rejection - the one state where the Telegram ledger
+     * proves definite non-acceptance and no attempt lease is live. Ambiguous or
+     * confirmed acceptance can never be cancelled. Replay on an already
+     * cancelled row is a converging no-op that keeps the first audit record.
+     */
+    cancel(deliveryId: string, reason: string, operatorTimeIso: string): void;
+    /**
+     * Explicit operator reactivation of a definite rejection after conditions
+     * are corrected (for example the bot was unblocked). Same delivery ID, same
+     * immutable target; the row becomes immediately recoverable.
+     */
+    reactivate(deliveryId: string): void;
+    /**
+     * Delivered reports not yet consumed by an owner turn, for one exact
+     * target, oldest first. This is the pending-projection source; one chat can
+     * never read another target's reports.
+     */
+    listDeliveredPending(target: ReportContextTarget): Array<{
+        seq: number;
+        deliveryId: string;
+        mode: 'digest' | 'full';
+        deliveredAtIso: string;
+        text: string;
+    }>;
+    /**
+     * Committed receipts for the given source-message references, in the input
+     * order. Only text-bearing receipts are returned; a compacted receipt no
+     * longer restores.
+     */
+    listReceiptsByRefs(refs: string[]): Array<{
+        sourceMessageRef: string;
+        deliveryIds: string[];
+        projectionText: string;
+        committedAtIso: string;
+    }>;
+    /**
+     * Legacy V2 restorations for one target, eligible for fresh-session history
+     * (30 days after consumption, design Decision 8). Restoration text is
+     * JSON-decoded back to the exact legacy prefix string.
+     */
+    listLegacyRestorations(target: ReportContextTarget, nowIso: string): Array<{
+        deliveryId: string;
+        consumedAtIso: string;
+        deliveredAtIso: string;
+        restorationText: string;
+    }>;
+    private compactRetained;
+    private enforceLiveCapacity;
+    /**
+     * Design Decision 5: explicit two-step operator action (token flow lives at
+     * the API layer). Archives ONLY already-delivered pending rows up to and
+     * including `throughSeq`, records the audit fields, and removes them from
+     * pending projection and live capacity. Never Telegram cancellation.
+     */
+    archiveDelivered(target: ReportContextTarget, throughSeq: number, actor: string, reason: string, nowIso: string): string[];
+    /** Live usage for the status surface; warn at 80% of either bound. */
+    liveUsage(target: ReportContextTarget): {
+        rows: number;
+        bytes: number;
+        rowCap: number;
+        byteCap: number;
+        warn: boolean;
+    };
+    /**
+     * Tombstone GC (design Decision 4): identity tombstones are retained up to
+     * 365 days with a global count cap. No tombstone younger than Telegram's
+     * seven-day replay window is ever pruned; beyond that floor the oldest
+     * terminal tombstones go first. Returns the number of removed rows.
+     */
+    pruneTombstones(nowIso: string, options?: {
+        maxTombstones?: number;
+    }): number;
+    /** Read one event's attempt/terminal detail; null when unknown. */
+    getEvent(deliveryId: string): ReportContextEventDetail | null;
+    /**
+     * Record a retryable send failure: keep the row nonterminal, stamp the next
+     * attempt time, and release the lease. Only the current lease holder may
+     * reshape backoff - a stale worker's outcome must not race a live one.
+     */
+    scheduleRetry(deliveryId: string, owner: string, nextAttemptAtIso: string): void;
+    /**
+     * Record a definite Telegram non-acceptance. The row stays pinned in the
+     * ledger (nonterminal) and is never automatically retried; only an explicit
+     * operator action may reactivate it (design Decision 3).
+     */
+    markDefiniteRejection(deliveryId: string, owner: string, reason: string): void;
+    /**
+     * Startup/tick recovery: prepared_retryable rows that are due (no future
+     * retry scheduled) and not held by a live attempt lease, oldest first.
+     */
+    listRecoverable(nowIso: string): ReportContextEvent[];
+    /**
+     * Startup ledger reconciliation input: every nonterminal row must hold a
+     * Telegram-ledger pin, every terminal row must not (design Decision 2).
+     */
+    listPinReconciliation(): {
+        nonterminal: string[];
+        terminal: string[];
+    };
+    private runMigration;
+}
+//# sourceMappingURL=telegram-report-context-store.d.ts.map

package/dist/gateways/telegram-report-context-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-report-context-store.d.ts","sourceRoot":"","sources":["../../src/gateways/telegram-report-context-store.ts"],"names":[],"mappings":"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"}