hippo-memory 1.69.0 → 1.71.0

package/dist/connectors/dlq.d.ts

@@ -0,0 +1,44 @@
+import { type HippoStore } from '../store/index.js';
+import type { ConnectorDeadLetter } from '../store/port.js';
+declare const DEFAULT_BUCKET = "parse_error";
+/** What a caller hands over to park one payload, whatever the connector. */
+export interface ParkOpts<Bucket extends string> {
+    /** null when no tenant was resolved for the payload. */
+    tenantId: string | null;
+    rawPayload: string;
+    error: string;
+    bucket?: Bucket;
+    signature?: string | null;
+}
+/** The columns every connector's table has, as stored. */
+export interface ParkedRow<Bucket extends string> {
+    tenantId: string;
+    rawPayload: string;
+    error: string;
+    bucket: Bucket | typeof DEFAULT_BUCKET;
+    signature: string | null;
+}
+/** What one connector supplies: the tag that names its table to the store, and its list. `Own` is the columns only its table has. */
+export interface ConnectorDlq<Own, Bucket extends string, Item> {
+    readonly letter: (row: ParkedRow<Bucket> & Own) => ConnectorDeadLetter;
+    readonly list: (hippoRoot: string, tenantId: string, limit: number) => Item[];
+}
+/** Parks on `store`, else on hippo.db under `hippoRoot`. */
+export declare function parkInDlq<Own, Bucket extends string>(dlq: ConnectorDlq<Own, Bucket, unknown>, hippoRoot: string, opts: ParkOpts<Bucket> & NoInfer<Own>, store?: HippoStore): Promise<number>;
+export declare function listDlq<Item>(dlq: ConnectorDlq<never, never, Item>, hippoRoot: string, opts: {
+    tenantId: string;
+    limit?: number;
+}): Item[];
+/** Every outcome a replay reports; a connector that re-ingests inline reports the ingest outcome itself. */
+export type ReplayStatus = 'not_found' | 'sig_missing' | 'sig_fail' | 'parse_error' | 'unhandled' | 'unroutable' | 'replayed' | 'ingested' | 'duplicate' | 'skipped' | 'skipped_duplicate' | 'archived';
+export interface ReplayResult {
+    ok: boolean;
+    status: ReplayStatus;
+    memoryId: string | null;
+    retryCount: number;
+    reason?: string;
+}
+/** A replay that did not go through; `retryCount` is the row's count after any bump the caller made. */
+export declare function replayFailed(status: ReplayStatus, retryCount: number, reason: string): ReplayResult;
+export {};
+//# sourceMappingURL=dlq.d.ts.map

package/dist/connectors/dlq.js

@@ -0,0 +1,30 @@
+// The dead-letter queue every webhook connector parks into: one redaction, one unroutable sentinel, one set of defaults, one replay result.
+import { DLQ_REDACTED_NOTE, redactPayload } from '../util/secret-detect.js';
+import { requireGroup, storeFor } from '../store/index.js';
+/** The tenant stored on a row no tenant was resolved for; the column is NOT NULL. */
+const UNROUTABLE_TENANT = '__unroutable__';
+const DEFAULT_BUCKET = 'parse_error';
+const DEFAULT_LIST_LIMIT = 100;
+/** Parks on `store`, else on hippo.db under `hippoRoot`. */
+export async function parkInDlq(dlq, hippoRoot, opts, store) {
+    const rawPayload = redactPayload(opts.rawPayload);
+    // A redacted body can never match its signature, so the row keeps none and replay needs --force.
+    const redacted = rawPayload !== opts.rawPayload;
+    const letter = dlq.letter({
+        ...opts,
+        tenantId: opts.tenantId ?? UNROUTABLE_TENANT,
+        rawPayload,
+        error: redacted ? `${opts.error}; ${DLQ_REDACTED_NOTE}` : opts.error,
+        bucket: opts.bucket ?? DEFAULT_BUCKET,
+        signature: redacted ? null : opts.signature ?? null,
+    });
+    return requireGroup(storeFor({ hippoRoot, store }), 'connectorEvents').parkDeadLetter(letter);
+}
+export function listDlq(dlq, hippoRoot, opts) {
+    return dlq.list(hippoRoot, opts.tenantId, opts.limit ?? DEFAULT_LIST_LIMIT);
+}
+/** A replay that did not go through; `retryCount` is the row's count after any bump the caller made. */
+export function replayFailed(status, retryCount, reason) {
+    return { ok: false, status, memoryId: null, retryCount, reason };
+}
+//# sourceMappingURL=dlq.js.map

package/dist/connectors/github/backfill.d.ts

@@ -1,29 +1,7 @@
-/**
- * Paginated backfill of three GitHub REST streams with per-stream
- * high-water marks (HWMs):
- *   - /repos/{repo}/issues               -> issues_hwm
- *   - /repos/{repo}/issues/comments      -> issue_comments_hwm
- *   - /repos/{repo}/pulls/comments       -> pr_review_comments_hwm
- *
- * Crash safety: each stream's HWM is persisted ONLY after
- * the stream fully drains. If stream 2 throws mid-flight, stream 1's HWM
- * is committed and stream 2's stays NULL (or its prior value). Rerun
- * picks up from stream 1's saved HWM and re-fetches stream 2 from its
- * last committed point.
- *
- * The /issues endpoint returns BOTH issues and PRs (a PR is
- * an issue with a `pull_request` field). We skip PRs here so they don't
- * get ingested under the issues schema. PRs are handled via webhook in
- * V1 (no /pulls backfill stream — review comments cover the discussion
- * surface).
- *
- * Privacy (V1 limitation): the REST list endpoints don't reliably set
- * `repository.private`, and resolving it requires an extra API call per
- * repo. Backfill leaves the field undefined so scopeFromRepository falls
- * through to private. Callers who know the repo is public can re-tag
- * downstream; the fail-safe default protects private orgs.
- */
-import type { Context } from '../../api.js';
+/** Paginated backfill of the GitHub issues, issue-comments and PR-review-comments streams, each with its own high-water mark (HWM).
+ *  An HWM is persisted only after its stream fully drains, so a crash in stream 2 leaves stream 1 committed and stream 2 resumes from its prior HWM.
+ *  `repository.private` is left undefined (REST lists omit it), so scopeFromRepository falls through to private. */
+import type { Context } from '../../api/index.js';
 import type { GitHubFetcher } from './octokit-client.js';
 export interface BackfillOpts {
     /** e.g. 'acme/repo'. */
@@ -32,6 +10,8 @@ export interface BackfillOpts {
     token: string;
     /** Optional cap on items per stream. Useful for tests. */
     maxPerStream?: number;
+    /** First-run `--since`; seeds all three HWMs, COALESCE keeps any HWM a stream already saved. */
+    sinceIso?: string;
     /** sleep ms — injectable so tests don't actually wait. */
     sleepMs?: (ms: number) => Promise<void>;
 }

package/dist/connectors/github/backfill.js

@@ -1,68 +1,12 @@
-/**
- * Paginated backfill of three GitHub REST streams with per-stream
- * high-water marks (HWMs):
- *   - /repos/{repo}/issues               -> issues_hwm
- *   - /repos/{repo}/issues/comments      -> issue_comments_hwm
- *   - /repos/{repo}/pulls/comments       -> pr_review_comments_hwm
- *
- * Crash safety: each stream's HWM is persisted ONLY after
- * the stream fully drains. If stream 2 throws mid-flight, stream 1's HWM
- * is committed and stream 2's stays NULL (or its prior value). Rerun
- * picks up from stream 1's saved HWM and re-fetches stream 2 from its
- * last committed point.
- *
- * The /issues endpoint returns BOTH issues and PRs (a PR is
- * an issue with a `pull_request` field). We skip PRs here so they don't
- * get ingested under the issues schema. PRs are handled via webhook in
- * V1 (no /pulls backfill stream — review comments cover the discussion
- * surface).
- *
- * Privacy (V1 limitation): the REST list endpoints don't reliably set
- * `repository.private`, and resolving it requires an extra API call per
- * repo. Backfill leaves the field undefined so scopeFromRepository falls
- * through to private. Callers who know the repo is public can re-tag
- * downstream; the fail-safe default protects private orgs.
- */
-import { openHippoDb, closeHippoDb } from '../../db.js';
+/** Paginated backfill of the GitHub issues, issue-comments and PR-review-comments streams, each with its own high-water mark (HWM).
+ *  An HWM is persisted only after its stream fully drains, so a crash in stream 2 leaves stream 1 committed and stream 2 resumes from its prior HWM.
+ *  `repository.private` is left undefined (REST lists omit it), so scopeFromRepository falls through to private. */
+import { readCursors, seedCursors, writeHwm } from '../../store/connectors/github.js';
 import { ingestEvent } from './ingest.js';
+import { isJsonObject } from '../../util/json.js';
 const API = 'https://api.github.com';
-function readCursor(root, tenantId, repo) {
-    const db = openHippoDb(root);
-    try {
-        // SAFETY: row's shape matches the three HWM columns named in the SELECT
-        // above; `better-sqlite3`'s `.get()` return type is untyped by the driver.
-        const row = db
-            .prepare(`SELECT issues_hwm, issue_comments_hwm, pr_review_comments_hwm
-         FROM github_cursors WHERE tenant_id = ? AND repo_full_name = ?`)
-            .get(tenantId, repo);
-        return {
-            issues: row?.issues_hwm ?? null,
-            issueComments: row?.issue_comments_hwm ?? null,
-            prReviewComments: row?.pr_review_comments_hwm ?? null,
-        };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-function writeOneHwm(root, tenantId, repo, column, value) {
-    const db = openHippoDb(root);
-    try {
-        db.prepare(`INSERT INTO github_cursors (tenant_id, repo_full_name, ${column}, updated_at)
-       VALUES (?, ?, ?, ?)
-       ON CONFLICT(tenant_id, repo_full_name)
-       DO UPDATE SET ${column} = excluded.${column}, updated_at = excluded.updated_at`).run(tenantId, repo, value, new Date().toISOString());
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Build a synthetic `repository` object from the known repo full name.
- * REST list endpoints often omit the full repository object on each item;
- * we already know the repo since the caller passed it. `private` left
- * undefined so scopeFromRepository falls through to private.
- */
+/** Build a synthetic `repository` from the known repo full name, because REST list items often omit it.
+ *  `private` stays undefined so scopeFromRepository falls through to private. */
 function syntheticRepository(repoFullName) {
     const [owner, name] = repoFullName.split('/');
     return {
@@ -72,11 +16,7 @@ function syntheticRepository(repoFullName) {
         // private intentionally omitted — fail-safe to private scope.
     };
 }
-/**
- * Parse the trailing issue/PR number from a REST API URL.
- * e.g. https://api.github.com/repos/o/r/issues/42 -> 42
- *      https://api.github.com/repos/o/r/pulls/7   -> 7
- */
+/** Parse the trailing issue/PR number from a REST API URL, e.g. .../issues/42 -> 42. */
 function parseTrailingNumber(url) {
     if (!url)
         return null;
@@ -86,14 +26,11 @@ function parseTrailingNumber(url) {
     const n = Number(m[1]);
     return Number.isFinite(n) ? n : null;
 }
-function isPlainObject(x) {
-    return x !== undefined && x !== null && typeof x === 'object' && !Array.isArray(x);
-}
 function isGitHubUser(x) {
-    return isPlainObject(x) && typeof x.login === 'string' && typeof x.id === 'number';
+    return isJsonObject(x) && typeof x.login === 'string' && typeof x.id === 'number';
 }
 function isIssuesItem(x) {
-    if (!isPlainObject(x))
+    if (!isJsonObject(x))
         return false;
     if (typeof x.number !== 'number')
         return false;
@@ -102,47 +39,25 @@ function isIssuesItem(x) {
     return isGitHubUser(x.user);
 }
 function isCommentItem(x) {
-    if (!isPlainObject(x))
+    if (!isJsonObject(x))
         return false;
     if (typeof x.id !== 'number')
         return false;
     return isGitHubUser(x.user);
 }
-/**
- * Drain one stream end-to-end. Pauses and retries on rate-limit. Throws on
- * any other fetch error so the caller leaves the HWM unchanged.
- *
- *   - Tracks max(updated_at) across ALL fetched items, including ones
- *     `toIngestEvent` rejects (e.g., PRs returned via `/issues`). Otherwise
- *     a page of pure PRs would never advance the HWM and the next run would
- *     re-fetch the same window forever.
- *   - Returns `drained: boolean` — true only when the stream actually ran
- *     to next=null. Callers MUST NOT advance the HWM when drained=false,
- *     or a capped run would persist a partial HWM and skip the unfetched tail.
- */
-async function drainStream(ctx, url0, toIngestEvent, fetcher, token, sleep, maxItems) {
+async function drainStream(ctx, url0, options) {
+    const { toIngestEvent, maxItems } = options;
     let url = url0;
     let ingested = 0;
     let pages = 0;
     let maxUpdatedAt = null;
     while (url) {
-        // Fetch with rate-limit retry loop.
-        let page;
-        while (true) {
-            page = await fetcher({ url, token });
-            if (page.rateLimit.reason !== 'none') {
-                await sleep(page.rateLimit.sleepSeconds * 1000);
-                continue;
-            }
-            break;
-        }
+        const page = await fetchPagePastRateLimit(options, url);
         pages++;
         for (const item of page.items) {
             // Track updated_at on EVERY item, before the toIngestEvent filter, so PR-only pages don't loop forever.
-            // SAFETY: updated_at is GitHub's ISO-timestamp field on every item
-            // shape this stream returns; a non-string value would only fail the
-            // string comparisons below, matching pre-migration passthrough.
-            const updatedAt = isPlainObject(item)
+            // SAFETY: updated_at is GitHub's ISO-timestamp field on every item shape this stream returns.
+            const updatedAt = isJsonObject(item)
                 ? (item.updated_at ?? null)
                 : null;
             if (updatedAt && (!maxUpdatedAt || updatedAt > maxUpdatedAt)) {
@@ -151,7 +66,7 @@ async function drainStream(ctx, url0, toIngestEvent, fetcher, token, sleep, maxI
             const evt = toIngestEvent(item);
             if (!evt)
                 continue;
-            const r = ingestEvent(ctx, {
+            const r = await ingestEvent(ctx, {
                 event: evt,
                 rawBody: JSON.stringify(item),
                 deliveryId: `backfill:${ctx.tenantId}:${updatedAt ?? ''}`,
@@ -167,6 +82,16 @@ async function drainStream(ctx, url0, toIngestEvent, fetcher, token, sleep, maxI
     }
     return { ingested, pages, maxUpdatedAt, drained: true };
 }
+async function fetchPagePastRateLimit(options, url) {
+    const { fetcher, token, sleep } = options;
+    // Fetch with rate-limit retry loop.
+    while (true) {
+        const page = await fetcher({ url, token });
+        if (page.rateLimit.reason === 'none')
+            return page;
+        await sleep(page.rateLimit.sleepSeconds * 1000);
+    }
+}
 function issueItemToEvent(item, repository) {
     if (!isIssuesItem(item))
         return null;
@@ -189,9 +114,8 @@ function issueItemToEvent(item, repository) {
 function issueCommentItemToEvent(item, repository) {
     if (!isCommentItem(item))
         return null;
-    // SAFETY: this closure only runs against the /issues/comments stream,
-    // so every item isCommentItem validates here is genuinely an
-    // IssueCommentItem; a missing issue_url is handled defensively below.
+    // SAFETY: this closure only runs against the /issues/comments stream, so every item isCommentItem
+    // validates is an IssueCommentItem; a missing issue_url is handled below.
     const c = item;
     const issueNumber = parseTrailingNumber(c.issue_url);
     if (issueNumber === null)
@@ -212,9 +136,8 @@ function issueCommentItemToEvent(item, repository) {
 function prReviewCommentItemToEvent(item, repository) {
     if (!isCommentItem(item))
         return null;
-    // SAFETY: this closure only runs against the /pulls/comments stream,
-    // so every item isCommentItem validates here is genuinely a
-    // PrReviewCommentItem; a missing pull_request_url is handled below.
+    // SAFETY: this closure only runs against the /pulls/comments stream, so every item isCommentItem
+    // validates is a PrReviewCommentItem; a missing pull_request_url is handled below.
     const c = item;
     const prNumber = parseTrailingNumber(c.pull_request_url);
     if (prNumber === null)
@@ -234,22 +157,29 @@ function prReviewCommentItemToEvent(item, repository) {
 }
 /** Drains one stream, then persists its HWM only when the stream ran to the end. */
 async function backfillStream(ctx, opts, sleep, stream) {
-    const res = await drainStream(ctx, stream.url, stream.toIngestEvent, opts.fetcher, opts.token, sleep, opts.maxPerStream);
+    const res = await drainStream(ctx, stream.url, {
+        toIngestEvent: stream.toIngestEvent,
+        fetcher: opts.fetcher,
+        token: opts.token,
+        sleep,
+        maxItems: opts.maxPerStream,
+    });
     // A capped run (--max) must leave the HWM at its previous value so the next run re-fetches the unprocessed tail.
     if (res.drained && res.maxUpdatedAt) {
-        writeOneHwm(ctx.hippoRoot, ctx.tenantId, opts.repoFullName, stream.column, res.maxUpdatedAt);
+        writeHwm(ctx.hippoRoot, ctx.tenantId, opts.repoFullName, stream.column, res.maxUpdatedAt);
     }
     return { ingested: res.ingested, pages: res.pages };
 }
 export async function backfillRepo(ctx, opts) {
     const sleep = opts.sleepMs ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const cursors = readCursor(ctx.hippoRoot, ctx.tenantId, opts.repoFullName);
+    if (opts.sinceIso)
+        seedCursors(ctx.hippoRoot, ctx.tenantId, opts.repoFullName, opts.sinceIso);
+    const cursors = readCursors(ctx.hippoRoot, ctx.tenantId, opts.repoFullName);
     const repository = syntheticRepository(opts.repoFullName);
     const result = {
         ingested: { issues: 0, issueComments: 0, prReviewComments: 0 },
         pages: { issues: 0, issueComments: 0, prReviewComments: 0 },
     };
-    // ---------- Stream 1: issues (skip PRs) ----------
     const issuesRes = await backfillStream(ctx, opts, sleep, {
         url: `${API}/repos/${opts.repoFullName}/issues?state=all&per_page=100` +
             (cursors.issues ? `&since=${encodeURIComponent(cursors.issues)}` : ''),
@@ -258,7 +188,6 @@ export async function backfillRepo(ctx, opts) {
     });
     result.ingested.issues = issuesRes.ingested;
     result.pages.issues = issuesRes.pages;
-    // ---------- Stream 2: repo-level issue comments ----------
     const commentsRes = await backfillStream(ctx, opts, sleep, {
         url: `${API}/repos/${opts.repoFullName}/issues/comments?per_page=100` +
             (cursors.issueComments ? `&since=${encodeURIComponent(cursors.issueComments)}` : ''),
@@ -267,7 +196,6 @@ export async function backfillRepo(ctx, opts) {
     });
     result.ingested.issueComments = commentsRes.ingested;
     result.pages.issueComments = commentsRes.pages;
-    // ---------- Stream 3: repo-level PR review comments ----------
     const prCommentsRes = await backfillStream(ctx, opts, sleep, {
         url: `${API}/repos/${opts.repoFullName}/pulls/comments?per_page=100` +
             (cursors.prReviewComments ? `&since=${encodeURIComponent(cursors.prReviewComments)}` : ''),

package/dist/connectors/github/deletion.d.ts

@@ -1,8 +1,7 @@
-import { type Context } from '../../api.js';
+import { type Context } from '../../api/index.js';
 export interface DeletionInput {
-    /** artifact_ref of the comment, e.g.,
-     *  'github://acme/repo/issue/42/comment/123' or
-     *  'github://acme/repo/pull/7/review_comment/456'. */
+    /** artifact_ref of the comment, e.g. 'github://acme/repo/issue/42/comment/123'
+     *  or 'github://acme/repo/pull/7/review_comment/456'. */
     artifactRef: string;
     /** Source idempotency key for this delete event (sha256 of artifact_ref + ':' + updated_at). */
     idempotencyKey: string;
@@ -16,21 +15,7 @@ export interface DeletionResult {
     status: DeletionStatus;
     archivedCount: number;
 }
-/**
- * Handle GitHub `issue_comment.deleted` and `pull_request_review_comment.deleted`.
- *
- * Filter by tenant_id + kind='raw'. Multi-row archive:
- * GitHub edits keep the same artifact_ref, so multiple active raw rows can
- * match a single deletion event. Archive ALL of them.
- *
- * ONE shared DB handle wraps ALL archives + the idempotency mark in a single
- * outer write scope: a per-row failure rolls back the whole batch, idempotency
- * included, so a retry re-attempts cleanly instead of leaving searchable
- * survivors. archiveRawMemory's own inner SAVEPOINT nests safely inside it.
- *
- * Tenant scope and kind='raw' filtering are load-bearing: without them a
- * deletion event from tenant A could archive tenant B's row sharing the same
- * artifact_ref, or accidentally target a distilled row.
- */
-export declare function handleCommentDeleted(ctx: Context, input: DeletionInput): DeletionResult;
+/** Handle `issue_comment.deleted` and `pull_request_review_comment.deleted`: archive ALL active raw rows for the artifact_ref in one write.
+ *  Tenant and kind='raw' filtering are load-bearing: without them a deletion could archive another tenant's row or a distilled row. */
+export declare function handleCommentDeleted(ctx: Context, input: DeletionInput): Promise<DeletionResult>;
 //# sourceMappingURL=deletion.d.ts.map

package/dist/connectors/github/deletion.js

@@ -1,66 +1,19 @@
-import { openHippoDb, closeHippoDb, withWriteScope } from '../../db.js';
-import { archiveRawMemory } from '../../raw-archive.js';
-import { hasSeenKey, markKeySeen } from './idempotency.js';
-/**
- * Handle GitHub `issue_comment.deleted` and `pull_request_review_comment.deleted`.
- *
- * Filter by tenant_id + kind='raw'. Multi-row archive:
- * GitHub edits keep the same artifact_ref, so multiple active raw rows can
- * match a single deletion event. Archive ALL of them.
- *
- * ONE shared DB handle wraps ALL archives + the idempotency mark in a single
- * outer write scope: a per-row failure rolls back the whole batch, idempotency
- * included, so a retry re-attempts cleanly instead of leaving searchable
- * survivors. archiveRawMemory's own inner SAVEPOINT nests safely inside it.
- *
- * Tenant scope and kind='raw' filtering are load-bearing: without them a
- * deletion event from tenant A could archive tenant B's row sharing the same
- * artifact_ref, or accidentally target a distilled row.
- */
-export function handleCommentDeleted(ctx, input) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        if (hasSeenKey(db, input.idempotencyKey)) {
-            return { status: 'duplicate', archivedCount: 0 };
-        }
-        // SAFETY: rows come from the SELECT above, which projects only the
-        // `id` column, so each row is exactly `{ id: string }`.
-        const rows = db
-            .prepare(`SELECT id FROM memories WHERE artifact_ref = ? AND tenant_id = ? AND kind = 'raw'`)
-            .all(input.artifactRef, ctx.tenantId);
-        const memoryIds = rows.map((r) => r.id);
-        if (memoryIds.length === 0) {
-            // Nothing to archive — still mark idempotency so a retry returns 'duplicate'.
-            // Independent INSERT, no rollback needed.
-            markKeySeen(db, {
-                idempotencyKey: input.idempotencyKey,
-                deliveryId: input.deliveryId,
-                eventName: input.eventName,
-                memoryId: null,
-            });
-            return { status: 'archive_skipped_not_found', archivedCount: 0 };
-        }
-        // Outer write scope wrapping all archives + the idempotency mark. Any throw
-        // rolls back the whole batch so retry sees neither archive nor mark — and
-        // re-attempts the full set.
-        withWriteScope(db, 'github_delete_all', () => {
-            for (const id of memoryIds) {
-                archiveRawMemory(db, id, {
-                    reason: `source_deleted:github:${input.eventName}:${input.deliveryId}`,
-                    who: ctx.actor.subject,
-                });
-            }
-            markKeySeen(db, {
-                idempotencyKey: input.idempotencyKey,
-                deliveryId: input.deliveryId,
-                eventName: input.eventName,
-                memoryId: memoryIds[0],
-            });
-        });
-        return { status: 'archived', archivedCount: memoryIds.length };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+import { requireGroup, storeFor } from '../../store/index.js';
+/** Handle `issue_comment.deleted` and `pull_request_review_comment.deleted`: archive ALL active raw rows for the artifact_ref in one write.
+ *  Tenant and kind='raw' filtering are load-bearing: without them a deletion could archive another tenant's row or a distilled row. */
+export async function handleCommentDeleted(ctx, input) {
+    const { artifactRef, idempotencyKey, deliveryId, eventName } = input;
+    const done = await requireGroup(storeFor(ctx), 'connectorEvents').archiveDeletedArtifact({
+        tenantId: ctx.tenantId,
+        actor: ctx.actor.subject,
+        artifactRef,
+        reason: `source_deleted:github:${eventName}:${deliveryId}`,
+        event: { connector: 'github', idempotencyKey, deliveryId, eventName },
+    });
+    if (done.duplicate)
+        return { status: 'duplicate', archivedCount: 0 };
+    if (done.archived === 0)
+        return { status: 'archive_skipped_not_found', archivedCount: 0 };
+    return { status: 'archived', archivedCount: done.archived };
 }
 //# sourceMappingURL=deletion.js.map

package/dist/connectors/github/dlq.d.ts

@@ -1,86 +1,20 @@
-import type { DatabaseSyncLike } from '../../db.js';
-import type { Context } from '../../api.js';
-/**
- * GitHub webhook DLQ. Mirrors the Slack DLQ shape (src/connectors/slack/dlq.ts)
- * but carries GitHub-specific metadata: event_name, delivery_id, signature,
- * installation_id, repo_full_name, so a `hippo gh dlq replay` operator can
- * triage without re-deriving anything from the raw payload.
- *
- * Buckets:
- *   - parse_error     — raw_payload was not valid JSON
- *   - unroutable      — no tenant resolved for installation_id / repo_full_name
- *   - signature_failed — HMAC did not verify against the active webhook secret
- *   - unhandled       — parsed but no handler matched the event
- */
-export type DlqBucket = 'parse_error' | 'unroutable' | 'signature_failed' | 'unhandled';
-export interface DlqItem {
-    id: number;
-    tenantId: string;
-    rawPayload: string;
-    error: string;
-    eventName: string | null;
-    deliveryId: string | null;
-    signature: string | null;
-    installationId: string | null;
-    repoFullName: string | null;
-    retryCount: number;
-    receivedAt: string;
-    retriedAt: string | null;
-    bucket: DlqBucket | string;
-}
-/**
- * `tenantId: null` means the connector could not resolve a tenant for the
- * envelope (unroutable installation/repo). Stored as the sentinel
- * `'__unroutable__'` so the NOT NULL column is honored — same convention as
- * Slack DLQ.
- */
-export interface WriteDlqOpts {
-    tenantId: string | null;
-    rawPayload: string;
-    error: string;
-    bucket?: DlqBucket;
-    eventName?: string | null;
-    deliveryId?: string | null;
-    signature?: string | null;
-    installationId?: string | null;
-    repoFullName?: string | null;
-}
-export declare function writeToDlq(db: DatabaseSyncLike, opts: WriteDlqOpts): number;
-export declare function listDlq(db: DatabaseSyncLike, opts: {
-    tenantId: string;
-    limit?: number;
-}): DlqItem[];
-export declare function getDlqEntry(db: DatabaseSyncLike, id: number): DlqItem | null;
+import type { Context } from '../../api/index.js';
+import { type DlqBucket, type DlqItem, type GitHubDlqInsert } from '../../store/connectors/github.js';
+import { type ConnectorDlq, type ReplayResult } from '../dlq.js';
+export type { DlqBucket, DlqItem };
+type GitHubOwnColumns = Pick<GitHubDlqInsert, 'eventName' | 'deliveryId' | 'installationId' | 'repoFullName'>;
+/** GitHub's dead-letter table; the event, delivery, installation and repo columns let an operator triage a row without re-reading the payload. */
+export declare const githubDlq: ConnectorDlq<GitHubOwnColumns, DlqBucket, DlqItem>;
 export interface ReplayDlqOpts {
     /** Current webhook secret. If omitted, signature check is skipped (force-only path). */
     webhookSecret?: string;
-    /**
-     * Previous webhook secret during rotation.
-     * Operators rotating GITHUB_WEBHOOK_SECRET would otherwise be forced into
-     * --force on DLQ rows written under the old secret. Plumbed through to
-     * verifyGitHubSignature.previousSecret.
-     */
+    /** Previous webhook secret during rotation, passed to verifyGitHubSignature.previousSecret so old-secret DLQ rows need no --force. */
     previousSecret?: string;
     /** When true, skip signature verification (used for legacy entries after secret rotation). */
     force?: boolean;
 }
-export type ReplayStatus = 'replayed' | 'parse_error' | 'sig_fail' | 'sig_missing' | 'unhandled' | 'not_found';
-export interface ReplayResult {
-    ok: boolean;
-    status: ReplayStatus;
-    memoryId: string | null;
-    retryCount: number;
-    reason?: string;
-}
-/**
- * Hook the webhook route injects to actually re-ingest a row. Decoupling
- * the dispatch keeps this module free of every event-type handler — the
- * route already knows how to route an envelope, so it passes that capability
- * back in.
- *
- * No `idempotencyKey` field: ingest re-derives the key from the parsed event,
- * so a hook trusting a passed-in key would dedupe against a stale one.
- */
+/** Hook the webhook route injects to re-ingest a row, which keeps this module free of every event-type handler.
+ *  No `idempotencyKey` field: ingest re-derives it from the parsed event, and a passed-in key could be stale. */
 export type IngestHook = (ctx: Context, args: {
     rawPayload: string;
     eventName: string;
@@ -88,21 +22,8 @@ export type IngestHook = (ctx: Context, args: {
 }) => Promise<{
     memoryId: string | null;
 }>;
-/**
- * Replay a DLQ row through the normal ingest path. Behavior:
- *   1. Fetch row by id. Not found → `not_found`.
- *   2. If !force and webhookSecret provided, verify signature with the
- *      current secret. Fail → bump retry_count, `sig_fail`.
- *      Missing signature on the row → `sig_missing` (no bump; --force required).
- *   3. JSON.parse the raw payload. Fail → bump, `parse_error`.
- *   4. Type-guard the envelope. Fail → bump, `unhandled`.
- *   5. If an `ingestHook` is supplied, call it and return its memoryId.
- *      If not (dry-run path), bump retry_count and return status `replayed`
- *      with memoryId=null. The webhook route wires the real hook.
- *
- * Mirrors Slack's "always use current routing" policy: replays use the
- * deployment state NOW, not at the time of original DLQing.
- */
+/** Replay a DLQ row through the normal ingest path; a failed signature, parse or envelope check bumps retry_count.
+ *  Without an `ingestHook` (dry-run) it bumps retry_count and returns `replayed` with memoryId=null; replays use today's routing, not the original's. */
 export declare function replayDlqEntry(ctx: Context, id: number, opts?: ReplayDlqOpts & {
     ingestHook?: IngestHook;
 }): Promise<ReplayResult>;