hippo-memory 1.70.0 → 1.72.0

package/dist/connectors/dlq.d.ts

@@ -1,5 +1,6 @@
 import { type HippoStore } from '../store/index.js';
 import type { ConnectorDeadLetter } from '../store/port.js';
+import type { JsonValue } from '../util/json.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> {
@@ -18,10 +19,14 @@ export interface ParkedRow<Bucket extends 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. */
+/** What one connector supplies: the tag that names its table to the store, its list, its one-row read and its retry bump.
+ * `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[];
+    readonly entry: (hippoRoot: string, id: number) => Item | null;
+    /** Adds one to `retry_count` and stamps `retried_at`. */
+    readonly bump: (hippoRoot: string, id: number) => void;
 }
 /** 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>;
@@ -38,7 +43,38 @@ export interface ReplayResult {
     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;
+/** The columns a replay reads from any connector's row. */
+interface ParkedEntry {
+    readonly id: number;
+    readonly retryCount: number;
+    readonly rawPayload: string;
+}
+/** A row that cannot pass the signature gate: 'sig_missing' is not counted, since only --force can get it through. */
+export interface SignatureRefusal {
+    readonly status: 'sig_missing' | 'sig_fail';
+    readonly reason: string;
+}
+/** What a connector's re-ingest of a parsed envelope reports. */
+export type Reingest = {
+    readonly ok: true;
+    readonly status: ReplayStatus;
+    readonly memoryId: string | null;
+    readonly reason?: string;
+} | {
+    readonly ok: false;
+    readonly status: ReplayStatus;
+    readonly reason: string;
+};
+/** The parts of a replay only the connector knows. */
+export interface ReplaySteps<Item, Envelope extends JsonValue> {
+    readonly dlq: ConnectorDlq<never, never, Item>;
+    /** Skipped under --force. */
+    readonly refuseSignature: (row: Item) => SignatureRefusal | null;
+    readonly isEnvelope: (parsed: JsonValue) => parsed is Envelope;
+    readonly notEnvelope: string;
+    readonly reingest: (row: Item, envelope: Envelope) => Promise<Reingest>;
+}
+/** Re-runs a parked row under today's secret and routing; every attempt past the read is counted once, except a missing signature. */
+export declare function replayParked<Item extends ParkedEntry, Envelope extends JsonValue>(steps: ReplaySteps<Item, Envelope>, hippoRoot: string, id: number, force: boolean): Promise<ReplayResult>;
 export {};
 //# sourceMappingURL=dlq.d.ts.map

package/dist/connectors/dlq.js

@@ -1,10 +1,11 @@
 // The dead-letter queue every webhook connector parks into: one redaction, one unroutable sentinel, one set of defaults, one replay result.
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { DLQ_REDACTED_NOTE, redactPayload } from '../util/secret-detect.js';
 import { requireGroup, storeFor } from '../store/index.js';
+import { errorMessage } from '../util/log.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);
@@ -23,8 +24,41 @@ export async function parkInDlq(dlq, hippoRoot, opts, store) {
 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) {
+/** A replay that did not go through; `retryCount` is the row's count after any bump made. */
+function replayFailed(status, retryCount, reason) {
     return { ok: false, status, memoryId: null, retryCount, reason };
 }
+/** A replay that failed after the row was read: counts it exactly once, then reports the new count. */
+function failAndBump(dlq, hippoRoot, row, status, reason) {
+    dlq.bump(hippoRoot, row.id);
+    return replayFailed(status, row.retryCount + 1, reason);
+}
+/** Re-runs a parked row under today's secret and routing; every attempt past the read is counted once, except a missing signature. */
+export async function replayParked(steps, hippoRoot, id, force) {
+    const row = steps.dlq.entry(hippoRoot, id);
+    if (!row)
+        return replayFailed('not_found', 0, `dlq id ${id} not found`);
+    const refusal = force ? null : steps.refuseSignature(row);
+    if (refusal?.status === 'sig_missing')
+        return replayFailed(refusal.status, row.retryCount, refusal.reason);
+    if (refusal)
+        return failAndBump(steps.dlq, hippoRoot, row, refusal.status, refusal.reason);
+    let parsed;
+    try {
+        parsed = JSON.parse(row.rawPayload);
+    }
+    catch (e) {
+        return failAndBump(steps.dlq, hippoRoot, row, 'parse_error', `still unparseable: ${errorMessage(e)}`);
+    }
+    if (!steps.isEnvelope(parsed))
+        return failAndBump(steps.dlq, hippoRoot, row, 'unhandled', steps.notEnvelope);
+    const outcome = await steps.reingest(row, parsed);
+    if (!outcome.ok)
+        return failAndBump(steps.dlq, hippoRoot, row, outcome.status, outcome.reason);
+    steps.dlq.bump(hippoRoot, row.id);
+    const result = { ok: true, status: outcome.status, memoryId: outcome.memoryId, retryCount: row.retryCount + 1 };
+    if (outcome.reason !== undefined)
+        result.reason = outcome.reason;
+    return result;
+}
 //# sourceMappingURL=dlq.js.map

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

@@ -1,28 +1,6 @@
-/**
- * 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.
- */
+/** 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 {
@@ -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,38 +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 { readCursors, writeHwm } from '../../store/connectors/github.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';
-/**
- * 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 {
@@ -42,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,9 +56,7 @@ async function drainStream(ctx, url0, options) {
         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.
+            // 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;
@@ -114,14 +82,23 @@ async function drainStream(ctx, url0, options) {
     }
     return { ingested, pages, maxUpdatedAt, drained: true };
 }
+// A reset hours away must fail the run for a later rerun; sleeping through it would hold the process for the whole window.
+const MAX_RATE_LIMIT_ATTEMPTS = 5;
+const MAX_RATE_LIMIT_WAIT_MS = 10 * 60 * 1000;
 async function fetchPagePastRateLimit(options, url) {
     const { fetcher, token, sleep } = options;
-    // Fetch with rate-limit retry loop.
-    while (true) {
+    let waitedMs = 0;
+    for (let attempt = 1;; attempt++) {
         const page = await fetcher({ url, token });
         if (page.rateLimit.reason === 'none')
             return page;
-        await sleep(page.rateLimit.sleepSeconds * 1000);
+        const waitMs = page.rateLimit.sleepSeconds * 1000;
+        if (attempt >= MAX_RATE_LIMIT_ATTEMPTS || waitedMs + waitMs > MAX_RATE_LIMIT_WAIT_MS) {
+            const resetAt = new Date(Date.now() + waitMs).toISOString();
+            throw new Error(`GitHub rate limit still active after ${attempt} attempts and ${Math.round(waitedMs / 1000)}s waited; resets at ${resetAt}`);
+        }
+        await sleep(waitMs);
+        waitedMs += waitMs;
     }
 }
 function issueItemToEvent(item, repository) {
@@ -146,9 +123,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)
@@ -169,9 +145,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)
@@ -206,13 +181,14 @@ async function backfillStream(ctx, opts, sleep, stream) {
 }
 export async function backfillRepo(ctx, opts) {
     const sleep = opts.sleepMs ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    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)}` : ''),
@@ -221,7 +197,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)}` : ''),
@@ -230,7 +205,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/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,20 +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.
- *
- * The store runs ALL archives + the idempotency mark as one write: a per-row
- * failure rolls back the whole batch, idempotency included, so a retry
- * re-attempts cleanly instead of leaving searchable survivors.
- *
- * 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.
- */
+/** 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,19 +1,6 @@
 import { requireGroup, storeFor } from '../../store/index.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.
- *
- * The store runs ALL archives + the idempotency mark as one write: a per-row
- * failure rolls back the whole batch, idempotency included, so a retry
- * re-attempts cleanly instead of leaving searchable survivors.
- *
- * 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.
- */
+/** 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({

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

@@ -1,32 +1,20 @@
 import type { Context } from '../../api/index.js';
-import { type DlqBucket, type DlqItem, type GithubDlqWrite } from '../../store/connectors/github.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<GithubDlqWrite, 'eventName' | 'deliveryId' | 'installationId' | 'repoFullName'>;
+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 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;
 }
-/**
- * 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;
@@ -34,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>;

package/dist/connectors/github/dlq.js

@@ -1,105 +1,46 @@
-import { bumpDlqRetry, dlqEntry, listDlqRows, } from '../../store/connectors/github.js';
-import { replayFailed } from '../dlq.js';
+import { githubDlqEntry, markGitHubDlqRetried, listGitHubDlq, } from '../../store/connectors/github.js';
+import { replayParked } from '../dlq.js';
 import { verifyGitHubSignature } from './signature.js';
 import { isGitHubWebhookEnvelope } from './types.js';
 /** GitHub's dead-letter table; the event, delivery, installation and repo columns let an operator triage a row without re-reading the payload. */
 export const githubDlq = {
     letter: (row) => ({ connector: 'github', ...row }),
-    list: listDlqRows,
+    list: listGitHubDlq,
+    entry: githubDlqEntry,
+    bump: markGitHubDlqRetried,
 };
-/**
- * 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 async function replayDlqEntry(ctx, id, opts = {}) {
-    const row = dlqEntry(ctx.hippoRoot, id);
-    if (!row)
-        return replayFailed('not_found', 0, `dlq id ${id} not found`);
-    // Signature verification (current secret, not the one in effect when DLQed).
-    if (!opts.force && opts.webhookSecret) {
-        const sigFailure = checkReplaySignature(ctx.hippoRoot, id, row, opts.webhookSecret, opts.previousSecret);
-        if (sigFailure)
-            return sigFailure;
-    }
-    const envelopeFailure = checkReplayEnvelope(ctx.hippoRoot, id, row);
-    if (envelopeFailure)
-        return envelopeFailure;
-    // Without an ingest hook this is a dry-run validation. Bump and report.
-    if (!opts.ingestHook) {
-        bumpDlqRetry(ctx.hippoRoot, id);
-        return {
-            ok: true,
-            status: 'replayed',
-            memoryId: null,
-            retryCount: row.retryCount + 1,
-            reason: 'dry-run: no ingest hook supplied',
-        };
-    }
-    // Real replay path. The route's IngestHook is responsible for routing,
-    // idempotency, and writing the memory. The DLQ module only validates the
-    // surface and bumps the retry counter.
-    // No idempotencyKey arg: the hook re-derives it from the parsed event (artifact_ref + updated_at).
-    const eventName = row.eventName ?? '';
-    const deliveryId = row.deliveryId ?? '';
-    const { memoryId } = await opts.ingestHook(ctx, {
-        rawPayload: row.rawPayload,
-        eventName,
-        deliveryId,
-    });
-    bumpDlqRetry(ctx.hippoRoot, id);
-    return {
-        ok: true,
-        status: 'replayed',
-        memoryId,
-        retryCount: row.retryCount + 1,
-    };
+    const { webhookSecret, previousSecret, ingestHook } = opts;
+    return replayParked({
+        dlq: githubDlq,
+        // The secret in effect now, not the one in effect when the row was parked.
+        refuseSignature: (row) => (webhookSecret ? refuseSignature(row, webhookSecret, previousSecret) : null),
+        isEnvelope: isGitHubWebhookEnvelope,
+        notEnvelope: 'not a GitHub webhook envelope',
+        reingest: async (row) => {
+            if (!ingestHook)
+                return { ok: true, status: 'replayed', memoryId: null, reason: 'dry-run: no ingest hook supplied' };
+            // The hook owns routing, idempotency and the memory write, and re-derives the key from the parsed event.
+            const { memoryId } = await ingestHook(ctx, {
+                rawPayload: row.rawPayload,
+                eventName: row.eventName ?? '',
+                deliveryId: row.deliveryId ?? '',
+            });
+            return { ok: true, status: 'replayed', memoryId };
+        },
+    }, ctx.hippoRoot, id, opts.force === true);
 }
-/** The failure result when the row cannot pass the signature gate, else null. */
-function checkReplaySignature(hippoRoot, id, row, webhookSecret, previousSecret) {
+function refuseSignature(row, webhookSecret, previousSecret) {
     if (!row.signature) {
-        return replayFailed('sig_missing', row.retryCount, 'row has no signature (legacy, or redacted before storing); pass --force to replay');
-    }
-    const sigOk = verifyGitHubSignature({
-        rawBody: row.rawPayload,
-        signature: row.signature,
-        webhookSecret,
-        previousSecret,
-    });
-    if (!sigOk) {
-        bumpDlqRetry(hippoRoot, id);
-        return replayFailed('sig_fail', row.retryCount + 1, 'signature did not verify against current GITHUB_WEBHOOK_SECRET; pass --force to replay anyway');
+        return { status: 'sig_missing', reason: 'row has no signature (legacy, or redacted before storing); pass --force to replay' };
     }
-    return null;
-}
-/** Parse + envelope guard; the failure result after bumping the count, else null. */
-function checkReplayEnvelope(hippoRoot, id, row) {
-    let parsed;
-    try {
-        parsed = JSON.parse(row.rawPayload);
-    }
-    catch (e) {
-        bumpDlqRetry(hippoRoot, id);
-        // SAFETY: this is a best-effort error message only; property access on
-        // any JS value is safe (undefined if absent), preserving the existing
-        // lenient formatting even when something non-Error was thrown.
-        const message = e.message;
-        return replayFailed('parse_error', row.retryCount + 1, `still unparseable: ${message}`);
-    }
-    if (!isGitHubWebhookEnvelope(parsed)) {
-        bumpDlqRetry(hippoRoot, id);
-        return replayFailed('unhandled', row.retryCount + 1, 'not a GitHub webhook envelope');
-    }
-    return null;
+    if (verifyGitHubSignature({ rawBody: row.rawPayload, signature: row.signature, webhookSecret, previousSecret }))
+        return null;
+    return {
+        status: 'sig_fail',
+        reason: 'signature did not verify against current GITHUB_WEBHOOK_SECRET; pass --force to replay anyway',
+    };
 }
 //# sourceMappingURL=dlq.js.map

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

@@ -1,16 +1,8 @@
-import { type Context } from '../../api/index.js';
+import type { Context } from '../../api/index.js';
+import { type IngestResult } from '../ingest.js';
 import type { GitHubIssueEvent, GitHubIssueCommentEvent, GitHubPullRequestEvent, GitHubPullRequestReviewCommentEvent } from './types.js';
-export type IngestStatus = 'ingested' | 'duplicate' | 'skipped' | 'skipped_duplicate';
-export interface IngestResult {
-    status: IngestStatus;
-    memoryId: string | null;
-}
-/**
- * Discriminated union of the four event shapes V1 ingests. The eventName
- * field MUST equal the X-GitHub-Event header value; computeIdempotencyKey
- * folds it into the dedupe key so the same body posted under two different
- * X-GitHub-Event headers produces two distinct keys (test 7).
- */
+/** Discriminated union of the four event shapes V1 ingests; eventName MUST equal the X-GitHub-Event header,
+ *  since computeIdempotencyKey folds it into the dedupe key. */
 export type IngestEvent = {
     eventName: 'issues';
     payload: GitHubIssueEvent;