hippo-memory 1.70.0 → 1.72.0

package/dist/connectors/github/ingest.js

@@ -1,9 +1,8 @@
 // GitHub event ingest, once per idempotency key. The key comes from the event's own content, never from the unsigned
 // X-GitHub-Delivery header, so a replay cannot get past it by rotating the delivery id. The pre-check is only the fast path:
 // the store logs the key in the memory's own transaction, which is what holds when two workers race.
-import { remember } from '../../api/index.js';
 import { requireGroup, storeFor } from '../../store/index.js';
-import { RejectedValueError } from '../../store/rejection.js';
+import { rememberWithEventLog } from '../ingest.js';
 import { computeIdempotencyKey } from './signature.js';
 import { issueEventToRememberOpts, issueCommentEventToRememberOpts, pullRequestEventToRememberOpts, prReviewCommentEventToRememberOpts, } from './transform.js';
 function transformEvent(event) {
@@ -18,12 +17,8 @@ function transformEvent(event) {
             return prReviewCommentEventToRememberOpts(event.payload);
     }
 }
-/**
- * Extract the source-normalized identifier the idempotency key needs.
- * Backfill and webhook both produce IngestEvent objects describing the same
- * source revision, so deriving the key from these fields collapses both paths
- * onto the same dedupe row. Mirrors the artifactRef strings in transform.ts.
- */
+/** Extract the source-normalized identifier the idempotency key needs, so backfill and webhook deliveries of the same
+ *  source revision collapse onto one dedupe row. Mirrors the artifactRef strings in transform.ts. */
 function eventArtifactRef(event) {
     const repo = event.payload.repository?.full_name ?? 'unknown/unknown';
     switch (event.eventName) {
@@ -58,33 +53,7 @@ export async function ingestEvent(ctx, input) {
     const seen = await events.eventRecord(event);
     if (seen.seen)
         return { status: 'duplicate', memoryId: seen.memoryId };
-    const opts = transformEvent(input.event);
-    if (!opts) {
-        // Empty body: no memory to write, but mark seen so a retry of the same
-        // empty event returns 'duplicate' (not 'skipped' again — that would
-        // re-run the transform on every retry).
-        await events.markEventSeen(event);
-        return { status: 'skipped', memoryId: null };
-    }
-    try {
-        return await rememberWithEventLog(ctx, event, opts);
-    }
-    catch (e) {
-        if (e instanceof RejectedValueError) {
-            // A tombstone hit is a PERMANENT skip, never DLQ-retried: mark the key seen like the empty-body
-            // branch above so a GitHub retry of the same delivery acks as done, not error.
-            await events.markEventSeen(event);
-            return { status: 'skipped', memoryId: null };
-        }
-        throw e;
-    }
-}
-async function rememberWithEventLog(ctx, event, opts) {
-    // No `|| 'connector:github'` fallback (see rememberWithEventLog in slack/ingest.ts for rationale).
-    const result = await remember(ctx, { ...opts, untrusted: true, event });
-    // Another worker logged this key between the pre-check and the write: its memory stands and ours was not stored.
-    if (result.duplicate)
-        return { status: 'skipped_duplicate', memoryId: result.duplicate.memoryId };
-    return { status: 'ingested', memoryId: result.id };
+    // An empty body is logged too, so a retry returns 'duplicate' instead of re-running the transform.
+    return rememberWithEventLog(ctx, event, transformEvent(input.event));
 }
 //# sourceMappingURL=ingest.js.map

package/dist/connectors/github/octokit-client.d.ts

@@ -1,19 +1,12 @@
-/**
- * Octokit-shaped HTTP fetcher for the GitHub connector backfill.
- *
- * Production uses `realGitHubFetcher` against `https://api.github.com`.
- * Tests inject a fake `GitHubFetcher` so they never hit the network.
- *
- * Any non-200 response that is NOT a recognized rate-limit pause MUST throw
- * `GitHubFetchError`: an empty page would be an empty backfill with no operator signal.
- */
+/** Octokit-shaped HTTP fetcher for the GitHub backfill; tests inject a fake `GitHubFetcher`.
+ *  Any non-200 that is not a recognised rate-limit pause MUST throw `GitHubFetchError`, since an empty page would be a silent empty backfill. */
 import { type RateLimitInfo } from './ratelimit.js';
 import type { JsonValue } from '../../util/json.js';
 export declare class GitHubFetchError extends Error {
     readonly status: number;
     readonly bodyExcerpt: string;
     readonly url: string;
-    constructor(status: number, bodyExcerpt: string, url: string);
+    constructor(status: number, bodyExcerpt: string, url: string, options?: ErrorOptions);
 }
 export interface GitHubBackfillPage {
     readonly items: ReadonlyArray<JsonValue>;
@@ -24,12 +17,7 @@ export type GitHubFetcher = (args: {
     url: string;
     token: string;
 }) => Promise<GitHubBackfillPage>;
-/**
- * Parse the rel="next" URL from an RFC 5988 `Link` header.
- *
- * Header format: `<url1>; rel="next", <url2>; rel="last"`.
- * Returns the URL whose rel parameter is exactly `"next"`, or null.
- */
+/** Parse the rel="next" URL from an RFC 5988 `Link` header, or null. */
 export declare function parseNextLink(linkHeader: string): string | null;
 export declare const realGitHubFetcher: GitHubFetcher;
 //# sourceMappingURL=octokit-client.d.ts.map

package/dist/connectors/github/octokit-client.js

@@ -1,32 +1,22 @@
-/**
- * Octokit-shaped HTTP fetcher for the GitHub connector backfill.
- *
- * Production uses `realGitHubFetcher` against `https://api.github.com`.
- * Tests inject a fake `GitHubFetcher` so they never hit the network.
- *
- * Any non-200 response that is NOT a recognized rate-limit pause MUST throw
- * `GitHubFetchError`: an empty page would be an empty backfill with no operator signal.
- */
+/** Octokit-shaped HTTP fetcher for the GitHub backfill; tests inject a fake `GitHubFetcher`.
+ *  Any non-200 that is not a recognised rate-limit pause MUST throw `GitHubFetchError`, since an empty page would be a silent empty backfill. */
 import { parseRateLimit } from './ratelimit.js';
 import { fetchWithRetry } from '../../util/http-retry.js';
+import { readCappedJson, readCappedText } from '../../util/capped-json.js';
+import { errorMessage } from '../../util/log.js';
 export class GitHubFetchError extends Error {
     status;
     bodyExcerpt;
     url;
-    constructor(status, bodyExcerpt, url) {
-        super(`GitHub ${status} on ${url}: ${bodyExcerpt}`);
+    constructor(status, bodyExcerpt, url, options) {
+        super(`GitHub ${status} on ${url}: ${bodyExcerpt}`, options);
         this.status = status;
         this.bodyExcerpt = bodyExcerpt;
         this.url = url;
         this.name = 'GitHubFetchError';
     }
 }
-/**
- * Parse the rel="next" URL from an RFC 5988 `Link` header.
- *
- * Header format: `<url1>; rel="next", <url2>; rel="last"`.
- * Returns the URL whose rel parameter is exactly `"next"`, or null.
- */
+/** Parse the rel="next" URL from an RFC 5988 `Link` header, or null. */
 export function parseNextLink(linkHeader) {
     if (!linkHeader)
         return null;
@@ -43,6 +33,24 @@ function headersToRecord(h) {
 }
 const GITHUB_TIMEOUT_MS = 30_000;
 const ERROR_BODY_SNIPPET_CHARS = 256;
+const UTF8_MAX_BYTES_PER_CHAR = 4;
+// A page is at most 100 items (per_page=100), each with a body of up to 65,536 characters at 4 bytes, plus its fields.
+const GITHUB_MAX_REPLY_BYTES = 32 * 1024 * 1024;
+/** The items of a 200 list reply. A body that is not JSON, is over the cap or is not an array throws, so it never reaches ingest as items. */
+async function readItems(res, url) {
+    // The path only: a `next` link comes from the server, so its query string is not ours to print.
+    const path = new URL(url).pathname;
+    let body;
+    try {
+        body = await readCappedJson(res, GITHUB_MAX_REPLY_BYTES);
+    }
+    catch (err) {
+        throw new GitHubFetchError(res.status, errorMessage(err), path, { cause: err });
+    }
+    if (!Array.isArray(body))
+        throw new GitHubFetchError(res.status, 'the reply is not a JSON array', path);
+    return body;
+}
 export const realGitHubFetcher = async ({ url, token }) => {
     const res = await fetchWithRetry(url, {
         headers: {
@@ -56,15 +64,10 @@ export const realGitHubFetcher = async ({ url, token }) => {
     // Don't silently turn 401/403/404/500 into empty pages.
     if (res.status !== 200 && rateLimit.reason === 'none') {
         // The status is the error reported; a body that cannot be read only costs its snippet.
-        const body = await res.text().catch(() => '');
+        const body = await readCappedText(res, ERROR_BODY_SNIPPET_CHARS * UTF8_MAX_BYTES_PER_CHAR).catch(() => '');
         throw new GitHubFetchError(res.status, body.slice(0, ERROR_BODY_SNIPPET_CHARS), url);
     }
-    // SAFETY: GitHub's list/paginated endpoints (issues, comments, etc. — the
-    // only endpoints this backfill fetcher targets) return a JSON array body
-    // on 200; per-item shape is intentionally left as `unknown` here since
-    // GitHubBackfillPage.items is opaque to this seam (callers parse the
-    // shape they expect downstream).
-    const items = res.status === 200 ? (await res.json()) : [];
+    const items = res.status === 200 ? await readItems(res, url) : [];
     const link = res.headers.get('link') ?? '';
     const next = parseNextLink(link);
     return { items, next, rateLimit };

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

@@ -1,20 +1,9 @@
-/**
- * GitHub rate-limit header parser.
- *
- * GitHub returns 403 for primary rate-limit (with `X-RateLimit-Remaining: 0`
- * and `X-RateLimit-Reset: <epoch>`) and 429 + `Retry-After: <seconds>` for
- * secondary rate-limit. Backfill must pause and resume rather than error.
- */
+/** GitHub rate-limit header parser: 403 with `X-RateLimit-Remaining: 0` is primary, 429 with `Retry-After` is secondary.
+ *  Backfill must pause and resume rather than error. */
 export interface RateLimitInfo {
     readonly sleepSeconds: number;
     readonly reason: 'primary' | 'secondary' | 'none';
 }
-/**
- * Parse rate-limit signal from a GitHub HTTP response.
- *
- * @param headers Lower-cased HTTP response headers.
- * @param status  HTTP status code.
- * @param now     Optional current epoch seconds (for deterministic tests).
- */
+/** Parse the rate-limit signal from a GitHub response; `headers` are lower-cased and `now` (epoch seconds) is for deterministic tests. */
 export declare function parseRateLimit(headers: Record<string, string | undefined>, status: number, now?: number): RateLimitInfo;
 //# sourceMappingURL=ratelimit.d.ts.map

package/dist/connectors/github/ratelimit.js

@@ -1,17 +1,6 @@
-/**
- * GitHub rate-limit header parser.
- *
- * GitHub returns 403 for primary rate-limit (with `X-RateLimit-Remaining: 0`
- * and `X-RateLimit-Reset: <epoch>`) and 429 + `Retry-After: <seconds>` for
- * secondary rate-limit. Backfill must pause and resume rather than error.
- */
-/**
- * Parse rate-limit signal from a GitHub HTTP response.
- *
- * @param headers Lower-cased HTTP response headers.
- * @param status  HTTP status code.
- * @param now     Optional current epoch seconds (for deterministic tests).
- */
+/** GitHub rate-limit header parser: 403 with `X-RateLimit-Remaining: 0` is primary, 429 with `Retry-After` is secondary.
+ *  Backfill must pause and resume rather than error. */
+/** Parse the rate-limit signal from a GitHub response; `headers` are lower-cased and `now` (epoch seconds) is for deterministic tests. */
 export function parseRateLimit(headers, status, now) {
     const _now = now ?? Math.floor(Date.now() / 1000);
     if (status === 429) {

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

@@ -1,8 +1,6 @@
 import type { GitHubRepository } from './types.js';
-/**
- * Map a GitHub repository to a hippo scope string. Default-private when
- * privacy is undetermined: cost of leaking public into private (recall returns
- * nothing) << cost of leaking private into public (data exposure).
- */
+/** Map a GitHub repository to a hippo scope string. Default-private when
+ *  privacy is undetermined: cost of leaking public into private (recall returns
+ *  nothing) << cost of leaking private into public (data exposure). */
 export declare function scopeFromRepository(repo: GitHubRepository | undefined): string;
 //# sourceMappingURL=scope.d.ts.map

package/dist/connectors/github/scope.js

@@ -1,8 +1,6 @@
-/**
- * Map a GitHub repository to a hippo scope string. Default-private when
- * privacy is undetermined: cost of leaking public into private (recall returns
- * nothing) << cost of leaking private into public (data exposure).
- */
+/** Map a GitHub repository to a hippo scope string. Default-private when
+ *  privacy is undetermined: cost of leaking public into private (recall returns
+ *  nothing) << cost of leaking private into public (data exposure). */
 export function scopeFromRepository(repo) {
     if (!repo)
         return 'github:private:unknown';

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

@@ -7,32 +7,10 @@ export interface VerifyOpts {
     previousSecret?: string;
 }
 export declare function verifyGitHubSignature(opts: VerifyOpts): boolean;
-/**
- * Source-aware idempotency key: artifact_ref plus the source-side updated_at.
- * A raw-body key would hash a webhook envelope and a REST backfill item of the
- * SAME source event differently and ingest it twice. Same artifact + same
- * revision = same key, whichever path delivered it; an edit gets a new key,
- * which is correct because each edit IS a new memory revision.
- *
- * Both inputs are upstream-derived from the parsed event, not from the
- * unsigned delivery header — replay attacks still cannot bypass dedupe.
- *
- * Inputs:
- *   - artifactRef: e.g. 'github://acme/repo/issue/42' or
- *     'github://acme/repo/issue/42/comment/123'.
- *   - updatedAt: source-side ISO timestamp (issue.updated_at,
- *     comment.updated_at, pull_request.updated_at). Empty string when the
- *     payload omits it (rare; older REST shapes).
- */
+/** Source-aware idempotency key: artifact_ref plus the source-side updated_at, so a webhook and a REST backfill of the SAME event dedupe.
+ *  An edit gets a new key (a new revision); both inputs come from the parsed event, not the unsigned delivery header, so replays cannot bypass dedupe. */
 export declare function computeIdempotencyKey(artifactRef: string, updatedAt: string | null | undefined): string;
-/**
- * Deletion-specific idempotency key: sha256('deleted:' + artifactRef + ':' +
- * updatedAt). Distinct namespace from computeIdempotencyKey so an ingest's row
- * in github_event_log doesn't make a deletion return 'duplicate' before it
- * gets a chance to archive; retries of the SAME deletion still dedupe.
- *
- * Kept as a separate exported function so the namespace prefix is explicit
- * at every call site (server.ts deletion branches, deletion.ts, DLQ replay).
- */
+/** Deletion idempotency key: sha256('deleted:' + artifactRef + ':' + updatedAt).
+ *  A separate namespace so an ingest's event-log row cannot make a deletion return 'duplicate'; retries of the same deletion still dedupe. */
 export declare function computeDeletionKey(artifactRef: string, updatedAt: string | null | undefined): string;
 //# sourceMappingURL=signature.d.ts.map

package/dist/connectors/github/signature.js

@@ -16,35 +16,13 @@ export function verifyGitHubSignature(opts) {
         return true;
     return false;
 }
-/**
- * Source-aware idempotency key: artifact_ref plus the source-side updated_at.
- * A raw-body key would hash a webhook envelope and a REST backfill item of the
- * SAME source event differently and ingest it twice. Same artifact + same
- * revision = same key, whichever path delivered it; an edit gets a new key,
- * which is correct because each edit IS a new memory revision.
- *
- * Both inputs are upstream-derived from the parsed event, not from the
- * unsigned delivery header — replay attacks still cannot bypass dedupe.
- *
- * Inputs:
- *   - artifactRef: e.g. 'github://acme/repo/issue/42' or
- *     'github://acme/repo/issue/42/comment/123'.
- *   - updatedAt: source-side ISO timestamp (issue.updated_at,
- *     comment.updated_at, pull_request.updated_at). Empty string when the
- *     payload omits it (rare; older REST shapes).
- */
+/** Source-aware idempotency key: artifact_ref plus the source-side updated_at, so a webhook and a REST backfill of the SAME event dedupe.
+ *  An edit gets a new key (a new revision); both inputs come from the parsed event, not the unsigned delivery header, so replays cannot bypass dedupe. */
 export function computeIdempotencyKey(artifactRef, updatedAt) {
     return createHash('sha256').update(`${artifactRef}:${updatedAt ?? ''}`).digest('hex');
 }
-/**
- * Deletion-specific idempotency key: sha256('deleted:' + artifactRef + ':' +
- * updatedAt). Distinct namespace from computeIdempotencyKey so an ingest's row
- * in github_event_log doesn't make a deletion return 'duplicate' before it
- * gets a chance to archive; retries of the SAME deletion still dedupe.
- *
- * Kept as a separate exported function so the namespace prefix is explicit
- * at every call site (server.ts deletion branches, deletion.ts, DLQ replay).
- */
+/** Deletion idempotency key: sha256('deleted:' + artifactRef + ':' + updatedAt).
+ *  A separate namespace so an ingest's event-log row cannot make a deletion return 'duplicate'; retries of the same deletion still dedupe. */
 export function computeDeletionKey(artifactRef, updatedAt) {
     return createHash('sha256').update(`deleted:${artifactRef}:${updatedAt ?? ''}`).digest('hex');
 }

package/dist/connectors/github/tenant-routing.d.ts

@@ -5,29 +5,7 @@ export interface ResolveArgs {
     /** `repository.full_name` from the webhook envelope, used for PAT-mode multi-tenant routing. */
     repoFullName?: string | null;
 }
-/**
- * Resolve the tenant_id for a GitHub webhook envelope.
- *
- * Returns:
- *   - mapped tenant_id when `github_installations` has a row for `installationId`
- *     (App-mode multi-tenant — primary path)
- *   - mapped tenant_id when `installation` is absent, `repository.full_name`
- *     matches a `github_repositories` row (PAT-mode multi-tenant)
- *   - the deployment's HIPPO_TENANT fallback (or 'default') when BOTH routing
- *     tables are empty (single-tenant deployment — env fallback is safe)
- *   - null when:
- *       - `installationId` is present but unknown AND `github_installations`
- *         is non-empty (multi-tenant install with foreign installation)
- *       - `installationId` is missing AND either routing table is non-empty
- *         AND no `repository.full_name` match (PAT-mode webhook from a foreign
- *         account)
- *
- * Escape hatch: `GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK=1` restores the
- * env fallback for emergency rollback only. Mirrors the Slack equivalent
- * (`SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK`).
- *
- * The fail-closed contract lives here so every caller (route handler, CLI
- * replay, future MCP) gets identical protection.
- */
+/** Resolve a GitHub envelope's tenant_id by installation id, then repository.full_name; the HIPPO_TENANT fallback applies only if both tables are empty.
+ *  An unknown installation or repo on a multi-tenant deployment returns null (fail closed); GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK=1 escapes. */
 export declare function resolveTenantForGitHub(hippoRoot: string, args: ResolveArgs, store?: HippoStore): Promise<string | null>;
 //# sourceMappingURL=tenant-routing.d.ts.map

package/dist/connectors/github/tenant-routing.js

@@ -1,32 +1,10 @@
-import { envGithubAllowUnknownInstallationFallback, envTenant } from '../../util/env.js';
+import { envGitHubAllowUnknownInstallationFallback, envTenant } from '../../util/env.js';
 import { requireGroup, storeFor } from '../../store/index.js';
-/**
- * Resolve the tenant_id for a GitHub webhook envelope.
- *
- * Returns:
- *   - mapped tenant_id when `github_installations` has a row for `installationId`
- *     (App-mode multi-tenant — primary path)
- *   - mapped tenant_id when `installation` is absent, `repository.full_name`
- *     matches a `github_repositories` row (PAT-mode multi-tenant)
- *   - the deployment's HIPPO_TENANT fallback (or 'default') when BOTH routing
- *     tables are empty (single-tenant deployment — env fallback is safe)
- *   - null when:
- *       - `installationId` is present but unknown AND `github_installations`
- *         is non-empty (multi-tenant install with foreign installation)
- *       - `installationId` is missing AND either routing table is non-empty
- *         AND no `repository.full_name` match (PAT-mode webhook from a foreign
- *         account)
- *
- * Escape hatch: `GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK=1` restores the
- * env fallback for emergency rollback only. Mirrors the Slack equivalent
- * (`SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK`).
- *
- * The fail-closed contract lives here so every caller (route handler, CLI
- * replay, future MCP) gets identical protection.
- */
+/** Resolve a GitHub envelope's tenant_id by installation id, then repository.full_name; the HIPPO_TENANT fallback applies only if both tables are empty.
+ *  An unknown installation or repo on a multi-tenant deployment returns null (fail closed); GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK=1 escapes. */
 export async function resolveTenantForGitHub(hippoRoot, args, store) {
     const envFallback = () => envTenant();
-    const escapeHatch = envGithubAllowUnknownInstallationFallback();
+    const escapeHatch = envGitHubAllowUnknownInstallationFallback();
     const routing = await requireGroup(storeFor({ hippoRoot, store }), 'connectorEvents').githubRouting(args);
     if (routing.tenant)
         return routing.tenant;

package/dist/connectors/github/transform.js

@@ -1,20 +1,6 @@
 import { scopeFromRepository } from './scope.js';
-/**
- * Convert GitHub webhook events into RememberOpts for api.remember(). Each
- * function returns null when the event has no usable body so the webhook
- * caller can mark the delivery seen for idempotency and skip the insert.
- *
- * Contract (mirrors src/connectors/slack/transform.ts):
- * - kind is the literal 'raw' (connector boundary, see src/importers.ts).
- * - artifact_ref formats are stable; deletion paths look up by these strings.
- *   - issue:               github://<owner/repo>/issue/<number>
- *   - issue_comment:       github://<owner/repo>/issue/<number>/comment/<id>
- *   - pull_request:        github://<owner/repo>/pull/<number>
- *   - pr_review_comment:   github://<owner/repo>/pull/<number>/review_comment/<id>
- * - owner is `user:github:<login>`. Required by the provenance gate.
- * - scope is derived from repository.private via scopeFromRepository (default
- *   private when undetermined).
- */
+/** Convert GitHub webhook events into RememberOpts; each returns null when the event has no usable body so the caller marks it seen and skips the insert.
+ *  artifact_ref formats (github://<owner/repo>/issue|pull/<n>[/comment|review_comment/<id>]) are stable because deletion looks rows up by them. */
 const UNKNOWN_REPO = 'unknown/unknown';
 export function issueEventToRememberOpts(evt) {
     const body = evt.issue.body?.trim();

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

@@ -1,19 +1,7 @@
-/**
- * GitHub webhook event shapes used by the ingestion connector.
- * Spec: https://docs.github.com/en/webhooks/webhook-events-and-payloads
- *
- * V1 cares about four event types: issues, issue_comment, pull_request,
- * pull_request_review_comment. Each guard is gated on the X-GitHub-Event
- * header value so a malicious or misrouted payload cannot satisfy a guard
- * for the wrong event type.
- */
+/** GitHub webhook event shapes for the ingestion connector (https://docs.github.com/en/webhooks/webhook-events-and-payloads).
+ *  Each guard is gated on the X-GitHub-Event header so a misrouted payload cannot satisfy a guard for the wrong event type. */
 import { type JsonValue } from '../../util/json.js';
-/**
- * `private` MUST be optional, not required. The Slack-style
- * fail-safe in scope.ts requires an envelope with `private: undefined` to
- * map to private; a strict boolean type would reject the payload before
- * scope can fail closed.
- */
+/** `private` MUST stay optional: scope.ts maps `private: undefined` to private, and a strict boolean would reject the payload before scope can fail closed. */
 export interface GitHubRepository {
     full_name: string;
     private?: boolean;

package/dist/connectors/github/types.js

@@ -1,12 +1,5 @@
-/**
- * GitHub webhook event shapes used by the ingestion connector.
- * Spec: https://docs.github.com/en/webhooks/webhook-events-and-payloads
- *
- * V1 cares about four event types: issues, issue_comment, pull_request,
- * pull_request_review_comment. Each guard is gated on the X-GitHub-Event
- * header value so a malicious or misrouted payload cannot satisfy a guard
- * for the wrong event type.
- */
+/** GitHub webhook event shapes for the ingestion connector (https://docs.github.com/en/webhooks/webhook-events-and-payloads).
+ *  Each guard is gated on the X-GitHub-Event header so a misrouted payload cannot satisfy a guard for the wrong event type. */
 import { isJsonString, isJsonNumber } from '../../util/json.js';
 function isObjectOrArray(x) {
     return x !== null && typeof x === 'object';

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

@@ -1,20 +1,7 @@
 import type { HippoStore } from '../../store/index.js';
 import { type WebhookRequest } from '../../util/http-util.js';
-/**
- * GitHub webhook receiver. Mirrors the Slack route shape but with
- * GitHub-specific idioms:
- *   1. HMAC SHA-256 over the raw body (X-Hub-Signature-256), no timestamp.
- *   2. Event type discriminated by the X-GitHub-Event header (not body.type).
- *   3. X-GitHub-Delivery is required audit metadata (NOT the dedupe seam - see
- *      computeIdempotencyKey, which folds the signed body into the key so a
- *      replayed body with a fresh delivery UUID still dedupes).
- *   4. Tenant resolved by installation.id → github_installations, then by
- *      repository.full_name → github_repositories (PAT-mode multi-tenant).
- *   5. ALWAYS ACK 200 on signed envelopes (DLQ included). 401 only on bad
- *      signature; 404 only when GITHUB_WEBHOOK_SECRET is unset (don't expose
- *      the route's existence on builds where it's gated off).
- *
- * Bearer auth is skipped on purpose: server.ts checks isPublicRoute before calling this.
- */
+/** GitHub webhook receiver: HMAC SHA-256 over the raw body, event type from the X-GitHub-Event header, tenant by installation.id then repository.full_name.
+ *  ACKs 200 on signed envelopes (DLQ too); 401 only on a bad signature; 409 on a delivery id seen in the replay window;
+ *  404 when GITHUB_WEBHOOK_SECRET is unset. No Bearer: its route row declares webhook-signature. */
 export declare function handleGitHubEventsWebhook(request: WebhookRequest, store?: HippoStore): Promise<void>;
 //# sourceMappingURL=webhook.d.ts.map

package/dist/connectors/github/webhook.js

@@ -1,4 +1,4 @@
-import { envGithubWebhookSecret, envGithubWebhookSecretPrevious } from '../../util/env.js';
+import { envGitHubWebhookSecret, envGitHubWebhookSecretPrevious } from '../../util/env.js';
 import { verifyGitHubSignature } from './signature.js';
 import { isGitHubWebhookEnvelope, isGitHubIssueEvent, isGitHubIssueCommentEvent, isGitHubPullRequestEvent, isGitHubPullRequestReviewCommentEvent, } from './types.js';
 import { ingestEvent as ingestGitHubEvent } from './ingest.js';
@@ -9,33 +9,20 @@ import { resolveTenantForGitHub } from './tenant-routing.js';
 import { computeDeletionKey as computeGitHubDeletionKey } from './signature.js';
 import { resolveTenantId } from '../../store/tenant.js';
 import { HttpError, JSON_HEADERS, isHeaderString, closeIfBodyUnread, readWebhookBody, sendJson, } from '../../util/http-util.js';
-/**
- * GitHub webhook receiver. Mirrors the Slack route shape but with
- * GitHub-specific idioms:
- *   1. HMAC SHA-256 over the raw body (X-Hub-Signature-256), no timestamp.
- *   2. Event type discriminated by the X-GitHub-Event header (not body.type).
- *   3. X-GitHub-Delivery is required audit metadata (NOT the dedupe seam - see
- *      computeIdempotencyKey, which folds the signed body into the key so a
- *      replayed body with a fresh delivery UUID still dedupes).
- *   4. Tenant resolved by installation.id → github_installations, then by
- *      repository.full_name → github_repositories (PAT-mode multi-tenant).
- *   5. ALWAYS ACK 200 on signed envelopes (DLQ included). 401 only on bad
- *      signature; 404 only when GITHUB_WEBHOOK_SECRET is unset (don't expose
- *      the route's existence on builds where it's gated off).
- *
- * Bearer auth is skipped on purpose: server.ts checks isPublicRoute before calling this.
- */
+/** GitHub webhook receiver: HMAC SHA-256 over the raw body, event type from the X-GitHub-Event header, tenant by installation.id then repository.full_name.
+ *  ACKs 200 on signed envelopes (DLQ too); 401 only on a bad signature; 409 on a delivery id seen in the replay window;
+ *  404 when GITHUB_WEBHOOK_SECRET is unset. No Bearer: its route row declares webhook-signature. */
 export async function handleGitHubEventsWebhook(request, store) {
     const { req, res, opts } = request;
     // Secret and signature header before the body, so a caller with neither cannot make the server buffer one.
-    const secret = envGithubWebhookSecret();
+    const secret = envGitHubWebhookSecret();
     if (!secret) {
         closeIfBodyUnread(request);
         res.writeHead(404, JSON_HEADERS);
         res.end(JSON.stringify({ error: 'not found' }));
         return;
     }
-    const previousSecret = envGithubWebhookSecretPrevious();
+    const previousSecret = envGitHubWebhookSecretPrevious();
     const sigHdr = req.headers['x-hub-signature-256'];
     const eventHdr = req.headers['x-github-event'];
     const deliveryHdr = req.headers['x-github-delivery'];
@@ -57,7 +44,37 @@ export async function handleGitHubEventsWebhook(request, store) {
     }
     // Signature OK from here on. Everything else is ACK-200; bad envelopes go
     // to the DLQ and a human can replay later.
-    await routeSignedDelivery({ hippoRoot: opts.hippoRoot, store, res, rawBody, eventName, deliveryId, signature: sigStr });
+    const replayKey = deliveryId === null ? null : `${opts.hippoRoot}\n${deliveryId}`;
+    if (replayKey !== null && !claimDelivery(replayKey, Date.now()))
+        throw new HttpError(409, 'duplicate X-GitHub-Delivery');
+    try {
+        await routeSignedDelivery({ hippoRoot: opts.hippoRoot, store, res, rawBody, eventName, deliveryId, signature: sigStr });
+    }
+    catch (err) {
+        // A delivery that failed left nothing stored, so GitHub's redelivery of the same id must get through.
+        if (replayKey !== null)
+            seenDeliveries.delete(replayKey);
+        throw err;
+    }
+}
+// GitHub signs no timestamp, so a captured delivery verifies forever; this window is what refuses its replay.
+const DELIVERY_REPLAY_TTL_MS = 24 * 60 * 60 * 1000;
+const DELIVERY_REPLAY_MAX_IDS = 10_000;
+// SHORTCUT: seen ids live in this process and reset on restart or eviction; move them to the store if serve ever runs as several processes.
+const seenDeliveries = new Map();
+/** Claims a delivery id for the window; false when it was claimed within the window already. The oldest claim goes first at the cap. */
+function claimDelivery(key, now) {
+    const seenAt = seenDeliveries.get(key);
+    if (seenAt !== undefined && now - seenAt < DELIVERY_REPLAY_TTL_MS)
+        return false;
+    seenDeliveries.delete(key);
+    if (seenDeliveries.size >= DELIVERY_REPLAY_MAX_IDS) {
+        const oldest = seenDeliveries.keys().next();
+        if (!oldest.done)
+            seenDeliveries.delete(oldest.value);
+    }
+    seenDeliveries.set(key, now);
+    return true;
 }
 const ALLOWED_EVENTS = new Set([
     'issues',
@@ -167,9 +184,7 @@ async function dispatchGitHubEvent(d, ctx, body, deliveryId, routing) {
     if (action === null)
         return false;
     if (action.kind === 'manual-review') {
-        // GitHub does fire issues.deleted (admin-initiated). Don't archive - V1
-        // policy is to log and let an operator decide. Archive could lose the
-        // memory if the issue is being moved between accounts.
+        // issues.deleted (admin-initiated) is logged, not archived: archiving could lose the memory if the issue moves between accounts.
         await parkAndAck(d, {
             ...routing,
             tenantId: ctx.tenantId,

package/dist/connectors/ingest.d.ts

@@ -0,0 +1,10 @@
+import { type Context, type RememberOpts } from '../api/index.js';
+import type { ConnectorEvent } from '../store/port.js';
+export type IngestStatus = 'ingested' | 'duplicate' | 'skipped' | 'skipped_duplicate';
+export interface IngestResult {
+    status: IngestStatus;
+    memoryId: string | null;
+}
+/** Stores `opts` once per event key; null `opts` (an empty body) and a tombstoned value are logged with no memory, so a redelivery acks instead of retrying. */
+export declare function rememberWithEventLog(ctx: Context, event: ConnectorEvent, opts: RememberOpts | null): Promise<IngestResult>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/connectors/ingest.js

@@ -0,0 +1,28 @@
+// The write half every connector's ingest shares, after its own pre-check of the event log.
+import { remember } from '../api/index.js';
+import { requireGroup, storeFor } from '../store/index.js';
+import { RejectedValueError } from '../core/api-errors.js';
+/** Stores `opts` once per event key; null `opts` (an empty body) and a tombstoned value are logged with no memory, so a redelivery acks instead of retrying. */
+export async function rememberWithEventLog(ctx, event, opts) {
+    if (!opts)
+        return markSkipped(ctx, event);
+    try {
+        // No actor fallback: every caller builds ctx with its connector subject.
+        const result = await remember(ctx, { ...opts, untrusted: true, event });
+        // Another worker logged this key between the pre-check and the write: its memory stands and ours was not stored.
+        if (result.duplicate)
+            return { status: 'skipped_duplicate', memoryId: result.duplicate.memoryId };
+        return { status: 'ingested', memoryId: result.id };
+    }
+    catch (e) {
+        // A tombstone refusal is permanent, so a DLQ retry would hit it forever.
+        if (e instanceof RejectedValueError)
+            return markSkipped(ctx, event);
+        throw e;
+    }
+}
+async function markSkipped(ctx, event) {
+    await requireGroup(storeFor(ctx), 'connectorEvents').markEventSeen(event);
+    return { status: 'skipped', memoryId: null };
+}
+//# sourceMappingURL=ingest.js.map