hippo-memory 1.71.0 → 1.72.0

package/dist/cli.js

@@ -1,39 +1,31 @@
 #!/usr/bin/env node
-// Hippo CLI entry point: parses argv and dispatches each verb through the table below.
+// Hippo CLI entry point: parses argv and dispatches each verb through the table in cli/verbs.ts.
 // `hippo help` prints the verb list from that table, so no list is kept here.
 import { envSkipAutoIntegrations } from './util/env.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import { fileURLToPath } from 'node:url';
 import { repairCodexWrapperIfInstalled } from './hooks/codex-wrapper.js';
-import { getHippoRoot } from './store/open.js';
+import { getHippoRoot } from './core/project-identity.js';
 import { resolveTenantId } from './store/tenant.js';
-import { handleGitHub, printGitHubBackfillUsage } from './cli/github.js';
+import { printGitHubBackfillUsage } from './cli/github.js';
 import { printError } from './cli/output.js';
 import { errorFields, errorMessage, isLevelEnabled, log } from './util/log.js';
-import { isStoreBusy, STORE_BUSY_MESSAGE } from './db/busy.js';
-import { boolFlag, flagIsTrue, isBooleanFlag, isStringFlag } from './cli/flag-values.js';
-import { VERB_USAGE, USAGE_HEADER, USAGE_EXAMPLES, printAuditPruneUsage, printSlackBackfillUsage, printSlackWorkspacesUsage } from './cli/usage.js';
-import { VERB_FLAGS, flagKind, isKnownFlag, undeclaredFlags } from './cli/flags.js';
+import { STORE_BUSY_MESSAGE } from './store/port.js';
+import { isStoreBusy } from './store/sqlite/busy.js';
+import { flagIsTrue, isBooleanFlag, isStringFlag } from './cli/flag-values.js';
+import { USAGE_HEADER, USAGE_EXAMPLES, printAuditPruneUsage, printSlackBackfillUsage, printSlackWorkspacesUsage } from './cli/usage.js';
+import { flagKind, isKnownFlag, undeclaredFlags } from './cli/flags.js';
+import { COMMANDS } from './cli/verbs.js';
 import { CliExit } from './cli/exit.js';
 // Helpers
-// Commands that delete or hide memories: an unknown flag here stops the run instead of being ignored.
-const DESTRUCTIVE_COMMANDS = new Set([
-    'audit', 'dedup', 'forget', 'invalidate', 'projects', 'reject', 'resolve', 'sleep', 'supersede',
-]);
-// Commands that honour --dry-run. Any other command would ignore it and run for real.
-const DRY_RUN_COMMANDS = new Set([
-    'audit', 'capture', 'dedup', 'forget', 'import', 'invalidate', 'refine', 'setup', 'sleep',
-]);
-// share and brief honour --dry-run in one form only; their other forms write for real.
-function dryRunRefusal(command, args, flags) {
-    const isBrief = command === 'brief' || command === 'project-brief';
-    const onlyForm = command === 'share' ? 'share --auto' : isBrief ? `${command} refresh` : null;
-    const honoured = command === 'share' ? args[0] === '--auto' || boolFlag(flags, 'auto')
-        : isBrief ? args[0] === 'refresh' : DRY_RUN_COMMANDS.has(command);
+// A command that does not honour --dry-run would ignore it and run for real.
+function dryRunRefusal(command, spec, args, flags) {
+    const only = spec?.dryRun;
+    const honoured = only === undefined ? spec?.flags.switches?.includes('dry-run') : only !== false && only.honoured(args, flags);
     if (honoured)
         return null;
-    const where = onlyForm ? ` outside \`hippo ${onlyForm}\`` : '';
+    const where = only ? ` outside \`hippo ${command} ${only.form}\`` : '';
     return `hippo ${command} has no --dry-run${where}, so it would run for real. Nothing was changed.`;
 }
 function pushRepeatableFlag(flags, key, value) {
@@ -134,294 +126,10 @@ function maybeRepairCodexWrapper(currentCommand, flags) {
         log.debug(`codex wrapper not repaired: ${errorMessage(err)}`);
     }
 }
-// A verb's entry is handle<Verb>(ctx); cmd<Name> is a typed function below an entry, never called from this table.
-/** Every verb main() dispatches, keyed by name; a verb without a VERB_FLAGS entry, or the reverse, fails to compile. */
-export const VERB_HANDLERS = {
-    init: {
-        run: async (c) => { (await import('./cli/init.js')).handleInit(c); },
-    },
-    remember: {
-        run: async (c) => { await (await import('./cli/remember.js')).handleRemember(c); },
-    },
-    recall: {
-        run: async (c) => { await (await import('./cli/recall.js')).handleRecall(c); },
-        scoped: true,
-    },
-    drill: {
-        run: async (c) => { await (await import('./cli/dag.js')).handleDrill(c); },
-        scoped: true,
-    },
-    assemble: {
-        run: async (c) => { await (await import('./cli/dag.js')).handleAssemble(c); },
-        scoped: true,
-    },
-    supersede: {
-        run: async (c) => { await (await import('./cli/remember.js')).handleSupersede(c); },
-    },
-    explain: {
-        run: async (c) => { await (await import('./cli/explain.js')).handleExplain(c); },
-        scoped: true,
-    },
-    eval: {
-        run: async (c) => { await (await import('./cli/eval.js')).handleEval(c); },
-    },
-    trace: {
-        run: async (c) => { await (await import('./cli/remember.js')).handleTrace(c); },
-    },
-    refine: {
-        run: async (c) => { await (await import('./cli/maintenance.js')).handleRefine(c); },
-    },
-    sleep: {
-        run: async (c) => { await (await import('./cli/sleep.js')).handleSleep(c); },
-        scoped: true,
-    },
-    'last-sleep': {
-        run: async (c) => { (await import('./cli/last-sleep.js')).handleLastSleep(c); },
-    },
-    'session-end': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleSessionEnd(c); },
-    },
-    '__session-end-worker': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleSessionEndWorker(c); },
-    },
-    'pre-compact': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handlePreCompact(c); },
-    },
-    'post-compact': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handlePostCompact(c); },
-    },
-    'capture-error': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleCaptureError(c); },
-    },
-    'compact-resume': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleCompactResume(c); },
-    },
-    'codex-run': {
-        run: async (c) => { (await import('./cli/session-hooks.js')).handleCodexRun(c); },
-    },
-    '__codex-session-end-worker': {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleCodexSessionEndWorker(c); },
-    },
-    dedup: {
-        run: async (c) => { (await import('./cli/maintenance.js')).handleDedup(c); },
-    },
-    dag: {
-        run: async (c) => { (await import('./cli/dag.js')).handleDag(c); },
-    },
-    auth: {
-        run: async (c) => { (await import('./cli/auth.js')).handleAuth(c); },
-        scoped: true,
-    },
-    goal: {
-        run: async (c) => { (await import('./cli/goals.js')).handleGoal(c); },
-        scoped: true,
-    },
-    slack: {
-        run: async (c) => { await (await import('./cli/slack.js')).handleSlack(c); },
-    },
-    github: {
-        run: async (c) => { await handleGitHub(c); },
-    },
-    audit: {
-        run: async (c) => { await (await import('./cli/audit.js')).handleAudit(c); },
-        scoped: true,
-    },
-    'correction-latency': {
-        run: async (c) => { await (await import('./cli/status.js')).handleCorrectionLatency(c); },
-    },
-    provenance: {
-        run: async (c) => { await (await import('./cli/status.js')).handleProvenance(c); },
-    },
-    status: {
-        run: async (c) => { (await import('./cli/status.js')).handleStatus(c); },
-    },
-    outcome: {
-        run: async (c) => { (await import('./cli/curate.js')).handleOutcome(c); },
-        scoped: true,
-    },
-    conflicts: {
-        run: async (c) => { (await import('./cli/curate.js')).handleConflicts(c); },
-    },
-    resolve: {
-        run: async (c) => { await (await import('./cli/curate.js')).handleResolve(c); },
-    },
-    reject: {
-        run: async (c) => { (await import('./cli/curate.js')).handleReject(c); },
-    },
-    rejections: {
-        run: async (c) => { (await import('./cli/curate.js')).handleRejections(c); },
-    },
-    unreject: {
-        run: async (c) => { (await import('./cli/curate.js')).handleUnreject(c); },
-    },
-    dormant: {
-        run: async (c) => { (await import('./cli/curate.js')).handleDormant(c); },
-        scoped: true,
-    },
-    projects: {
-        run: async (c) => { (await import('./cli/projects.js')).handleProjects(c); },
-    },
-    quarantine: {
-        run: async (c) => { await (await import('./cli/curate.js')).handleQuarantine(c); },
-        scoped: true,
-    },
-    tokens: {
-        run: async (c) => { (await import('./cli/status.js')).handleTokens(c); },
-        scoped: true,
-    },
-    failures: {
-        run: async (c) => { (await import('./cli/status.js')).handleFailures(c); },
-        scoped: true,
-    },
-    doctor: {
-        run: async (c) => { await (await import('./cli/status.js')).handleDoctor(c); },
-    },
-    'support-bundle': {
-        run: async (c) => { await (await import('./cli/status.js')).handleSupportBundle(c); },
-    },
-    snapshot: {
-        run: async (c) => { (await import('./cli/continuity.js')).handleSnapshot(c); },
-    },
-    session: {
-        run: async (c) => { (await import('./cli/continuity.js')).handleSession(c); },
-    },
-    handoff: {
-        run: async (c) => { (await import('./cli/continuity.js')).handleHandoff(c); },
-    },
-    card: {
-        run: async (c) => { (await import('./cli/card.js')).handleCard(c); },
-    },
-    predict: {
-        run: async (c) => { (await import('./cli/decisions.js')).handlePredict(c); },
-    },
-    current: {
-        run: async (c) => { (await import('./cli/continuity.js')).handleCurrent(c); },
-    },
-    forget: {
-        run: async (c) => { await (await import('./cli/curate.js')).handleForget(c); },
-        scoped: true,
-    },
-    inspect: {
-        run: async (c) => { await (await import('./cli/status.js')).handleInspect(c); },
-    },
-    context: {
-        run: async (c) => { await (await import('./cli/context.js')).handleContext(c); },
-    },
-    hook: {
-        run: async (c) => { (await import('./cli/setup.js')).handleHook(c); },
-    },
-    setup: {
-        run: async (c) => { (await import('./cli/setup.js')).handleSetup(c); },
-    },
-    'daily-runner': {
-        run: async (c) => { (await import('./cli/setup.js')).handleDailyRunner(c); },
-    },
-    embed: {
-        run: async (c) => { await (await import('./cli/maintenance.js')).handleEmbed(c); },
-    },
-    watch: {
-        run: async (c) => { await (await import('./cli/transfer.js')).handleWatch(c); },
-    },
-    learn: {
-        run: async (c) => { (await import('./cli/transfer.js')).handleLearn(c); },
-        scoped: true,
-    },
-    promote: {
-        run: async (c) => { await (await import('./cli/transfer.js')).handlePromote(c); },
-        scoped: true,
-    },
-    sync: {
-        run: async (c) => { (await import('./cli/transfer.js')).handleSync(c); },
-    },
-    share: {
-        run: async (c) => { await (await import('./cli/transfer.js')).handleShare(c); },
-    },
-    peers: {
-        run: async (c) => { await (await import('./cli/transfer.js')).handlePeers(c); },
-    },
-    import: {
-        run: async (c) => { (await import('./cli/transfer.js')).handleImport(c); },
-    },
-    export: {
-        run: async (c) => { await (await import('./cli/transfer.js')).handleExport(c); },
-    },
-    capture: {
-        run: async (c) => { await (await import('./cli/session-hooks.js')).handleCapture(c); },
-    },
-    dashboard: {
-        run: async (c) => { await (await import('./cli/serve.js')).handleDashboard(c); },
-    },
-    wm: {
-        run: async (c) => { (await import('./cli/continuity.js')).handleWm(c); },
-    },
-    mcp: {
-        run: async () => { await (await import('./cli/serve.js')).handleMcp(); },
-    },
-    serve: {
-        run: async (c) => { await (await import('./cli/serve.js')).handleServe(c); },
-    },
-    invalidate: {
-        run: async (c) => { await (await import('./cli/curate.js')).handleInvalidate(c); },
-    },
-    decide: {
-        run: async (c) => { await (await import('./cli/decisions.js')).handleDecide(c); },
-    },
-    incident: {
-        run: async (c) => { (await import('./cli/decisions.js')).handleIncident(c); },
-    },
-    process: {
-        run: async (c) => { (await import('./cli/playbooks.js')).handleProcess(c); },
-    },
-    policy: {
-        run: async (c) => { (await import('./cli/playbooks.js')).handlePolicy(c); },
-    },
-    skill: {
-        run: async (c) => { (await import('./cli/playbooks.js')).handleSkill(c); },
-    },
-    brief: {
-        run: async (c) => { (await import('./cli/briefs.js')).handleProjectBrief(c); },
-        aliases: ['project-brief'],
-    },
-    note: {
-        run: async (c) => { (await import('./cli/briefs.js')).handleCustomerNote(c); },
-        aliases: ['customer-note'],
-    },
-    graph: {
-        run: async (c) => { (await import('./cli/briefs.js')).handleGraph(c); },
-    },
-};
-const USAGE_BLOCKS = VERB_USAGE;
-const FLAGS_BY_VERB = VERB_FLAGS;
-function buildCommands() {
-    const specs = Object.entries(VERB_HANDLERS).map(([verb, handler]) => {
-        const spec = { ...handler, usage: USAGE_BLOCKS[verb] ?? [], flags: FLAGS_BY_VERB[verb] };
-        return [verb, spec];
-    });
-    // SAFETY: VERB_HANDLERS is checked above to have exactly the VerbName keys, so every key is present.
-    return Object.fromEntries(specs);
-}
-/** Every verb's handler, aliases, help blocks and flags, keyed by name. */
-export const COMMANDS = buildCommands();
+const ROWS = Object.values(COMMANDS);
 const COMMAND_INDEX = new Map(Object.entries(COMMANDS).flatMap(([verb, spec]) => [verb, ...(spec.aliases ?? [])].map((name) => [name, spec])));
-// The full listing order; a verb listed twice prints its next help block.
-const USAGE_ORDER = [
-    'init', 'remember', 'supersede', 'recall', 'explain', 'trace', 'refine', 'eval', 'context', 'sleep',
-    'daily-runner', 'dedup', 'status', 'audit', 'github', 'slack', 'provenance', 'dag', 'drill', 'assemble',
-    'correction-latency', 'outcome', 'conflicts', 'resolve', 'reject', 'rejections', 'unreject', 'dormant',
-    'projects', 'quarantine', 'capture-error', 'doctor', 'support-bundle', 'tokens', 'failures', 'snapshot',
-    'session', 'handoff', 'card', 'current', 'forget', 'inspect', 'embed', 'watch', 'learn', 'promote',
-    'share', 'peers', 'sync', 'import', 'export', 'capture', 'setup', 'last-sleep', 'session-end',
-    'pre-compact', 'compact-resume', 'post-compact', 'codex-run', 'hook', 'predict', 'decide', 'incident',
-    'process', 'policy', 'skill', 'brief', 'note', 'graph', 'invalidate', 'wm', 'dashboard', 'mcp', 'serve',
-    'goal', 'auth', 'audit',
-];
 export function usageText() {
-    const printed = new Map();
-    const blocks = USAGE_ORDER.map((verb) => {
-        const index = printed.get(verb) ?? 0;
-        printed.set(verb, index + 1);
-        return COMMANDS[verb].usage[index];
-    });
+    const blocks = [...ROWS.flatMap((row) => row.usage ?? []), ...ROWS.flatMap((row) => row.listedLast ?? [])];
     return USAGE_HEADER + blocks.join('') + USAGE_EXAMPLES;
 }
 function printUsage() {
@@ -429,7 +137,8 @@ function printUsage() {
 }
 /** One verb's help blocks as `hippo <verb> --help` prints them, or null for a verb with none. */
 export function verbUsage(verb) {
-    const usage = COMMAND_INDEX.get(verb)?.usage ?? [];
+    const spec = COMMAND_INDEX.get(verb);
+    const usage = [...(spec?.usage ?? []), ...(spec?.listedLast ?? [])];
     return usage.length > 0 ? usage.join('').slice(1) : null;
 }
 // These sub-commands have fuller usage text than their lines in usageText().
@@ -486,13 +195,14 @@ function rejectValuedSwitches(flags, declared) {
         }
     }
 }
-function checkUnknownFlags(command, flags, declared) {
+function checkUnknownFlags(command, flags, spec) {
+    const declared = spec?.flags;
     // card checks its flags per subcommand, with a stricter message.
     if (command === 'card')
         return;
     const flagNames = (keys) => keys.map((key) => `--${key}`).join(', ');
     const unknown = Object.keys(flags).filter((key) => !isKnownFlag(key));
-    if (unknown.length > 0 && DESTRUCTIVE_COMMANDS.has(command)) {
+    if (unknown.length > 0 && spec?.destructive) {
         printError(`Unknown flag ${flagNames(unknown)} for hippo ${command}. Nothing was changed.`);
         throw new CliExit(2);
     }
@@ -518,8 +228,8 @@ async function main(command, args, flags, hippoRoot) {
     rejectEmptyScope(flags);
     rejectNonNumericFlags(flags, spec?.flags);
     rejectValuedSwitches(flags, spec?.flags);
-    checkUnknownFlags(command, flags, spec?.flags);
-    const refusal = Object.hasOwn(flags, 'dry-run') ? dryRunRefusal(command, args, flags) : null;
+    checkUnknownFlags(command, flags, spec);
+    const refusal = Object.hasOwn(flags, 'dry-run') ? dryRunRefusal(command, spec, args, flags) : null;
     if (refusal) {
         printError(refusal);
         throw new CliExit(2);

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.js

@@ -82,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) {

package/dist/connectors/github/dlq.js

@@ -1,88 +1,46 @@
-import { bumpGitHubDlqRetryCount, githubDlqEntry, listGitHubDlq, } 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: listGitHubDlq,
+    entry: githubDlqEntry,
+    bump: markGitHubDlqRetried,
 };
 /** 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 = githubDlqEntry(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) {
-        bumpGitHubDlqRetryCount(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 owns routing, idempotency and the memory write; this module only validates 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,
-    });
-    bumpGitHubDlqRetryCount(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) {
-        bumpGitHubDlqRetryCount(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) {
-        bumpGitHubDlqRetryCount(hippoRoot, id);
-        // SAFETY: best-effort error message only; property access on any JS value is safe, even for a non-Error throw.
-        const message = e.message;
-        return replayFailed('parse_error', row.retryCount + 1, `still unparseable: ${message}`);
-    }
-    if (!isGitHubWebhookEnvelope(parsed)) {
-        bumpGitHubDlqRetryCount(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