hippo-memory 1.70.0 → 1.72.0

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

@@ -9,14 +9,8 @@ export type SlackHistoryFetcher = (args: {
     channelId: string;
     /** Slack's opaque pagination token. Null on first page of a backfill run. */
     cursor: string | null;
-    /**
-     * Incremental-resume bound: skip messages with ts <= oldest. Set from
-     * `slack_cursors.latest_ts` on the FIRST page of a rerun; unused on
-     * subsequent pages within one run (where `cursor` carries us forward).
-     * Distinct from `cursor` because Slack treats `cursor` as opaque token
-     * and `oldest` as a numeric ts — feeding `latest_ts` as `cursor` breaks
-     * against the live API even though it round-trips through test fetchers.
-     */
+    /** Incremental-resume bound: skip messages with ts <= oldest, set from `slack_cursors.latest_ts` on the first page only.
+     *  Kept apart from `cursor` because Slack treats `cursor` as an opaque token, so feeding latest_ts as cursor fails on the live API. */
     oldest?: string;
 }) => Promise<SlackHistoryPage>;
 export interface BackfillOpts {
@@ -26,15 +20,8 @@ export interface BackfillOpts {
     /** Stop after this many messages. Default: unlimited. */
     maxMessages?: number;
 }
-/**
- * Page through `conversations.history` via the injected fetcher and ingest each
- * message. The cursor is persisted to `slack_cursors` after every page so a
- * crash mid-backfill resumes near where it left off.
- *
- * Each ingested message uses a synthesized eventId of the form
- * `backfill:${teamId}:${channelId}:${ts}`. Reruns dedupe via the
- * `slack_event_log` PK so calling `backfillChannel` twice is safe.
- */
+/** Page through `conversations.history` and ingest each message, persisting the cursor to `slack_cursors` after every page.
+ *  The synthesized eventId `backfill:${teamId}:${channelId}:${ts}` makes reruns dedupe via the `slack_event_log` PK. */
 export declare function backfillChannel(ctx: Context, opts: BackfillOpts): Promise<{
     ingested: number;
     pages: number;

package/dist/connectors/slack/backfill.js

@@ -1,19 +1,10 @@
 import { saveSlackCursor, slackCursor } from '../../store/connectors/slack.js';
 import { ingestMessage } from './ingest.js';
-/**
- * Page through `conversations.history` via the injected fetcher and ingest each
- * message. The cursor is persisted to `slack_cursors` after every page so a
- * crash mid-backfill resumes near where it left off.
- *
- * Each ingested message uses a synthesized eventId of the form
- * `backfill:${teamId}:${channelId}:${ts}`. Reruns dedupe via the
- * `slack_event_log` PK so calling `backfillChannel` twice is safe.
- */
+/** Page through `conversations.history` and ingest each message, persisting the cursor to `slack_cursors` after every page.
+ *  The synthesized eventId `backfill:${teamId}:${channelId}:${ts}` makes reruns dedupe via the `slack_event_log` PK. */
 export async function backfillChannel(ctx, opts) {
-    // Resume bound from previous run; passed as `oldest` (numeric ts) on the
-    // first page only. `cursor` starts null — Slack mints the next-page token
-    // and we feed it back. Mixing the two would feed a numeric ts as an opaque
-    // cursor and break against the live API on rerun.
+    // `oldest` (numeric ts) is the resume bound for the first page only; `cursor` starts null and Slack mints the next-page token.
+    // Mixing the two would feed a numeric ts as an opaque cursor and break on rerun.
     const resumeFrom = slackCursor(ctx.hippoRoot, ctx.tenantId, opts.channel.id);
     let cursor = null;
     let ingested = 0;

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

@@ -14,24 +14,7 @@ export interface ReplayDlqOpts {
     /** Skew window override for tests. */
     skewSeconds?: number;
 }
-/**
- * Replay a DLQ row through the normal ingest path. Used by `hippo slack dlq
- * replay <id> [--force]`.
- *
- * Behavior:
- *   1. SELECT the row.
- *   2. If signature + slack_timestamp are present and `signingSecret` is set,
- *      re-verify with the CURRENT secret (not previous). Failure → bail unless
- *      --force. Legacy rows from before v19 may have NULL signature; those
- *      require --force to replay safely.
- *   3. Re-parse the raw_payload and dispatch to ingestMessage / handleMessageDeleted.
- *   4. On success: mark retried_at, increment retry_count.
- *   5. On failure: increment retry_count only, leave the row.
- *
- * The replay always uses the routing the deployment has NOW (current
- * slack_workspaces table + env), not whatever was in effect when the original
- * envelope was DLQed. That is intentional: the DLQ exists to be drained after
- * the operator fixed the routing.
- */
+/** Replay a DLQ row via the normal ingest path (`hippo slack dlq replay <id> [--force]`), re-verifying the signature with the CURRENT secret unless forced.
+ *  Rows with a NULL signature need --force; replays use today's routing, because the DLQ exists to be drained after the operator fixed routing. */
 export declare function replayDlqEntry(ctx: Pick<Context, 'hippoRoot'>, id: number, opts?: ReplayDlqOpts): Promise<ReplayResult>;
 //# sourceMappingURL=dlq.d.ts.map

package/dist/connectors/slack/dlq.js

@@ -1,113 +1,75 @@
 import { adminActor } from '../../api/index.js';
-import { bumpSlackDlqRetryCount, listSlackDlq, markSlackDlqRetried, slackDlqEntry, } from '../../store/connectors/slack.js';
-import { replayFailed } from '../dlq.js';
+import { listSlackDlq, markSlackDlqRetried, slackDlqEntry, } from '../../store/connectors/slack.js';
+import { replayParked } from '../dlq.js';
 import { ingestMessage } from './ingest.js';
 import { resolveTenantForSlackTeam } from './tenant-routing.js';
 import { verifySlackSignature } from './signature.js';
 import { isSlackEventEnvelope, isSlackMessageEvent } from './types.js';
 import { handleMessageDeleted } from './deletion.js';
-import { errorMessage } from '../../util/log.js';
+import { YEAR_S } from '../../util/time.js';
 /** Slack's dead-letter table; `teamId` and `slackTimestamp` are the columns only it has. */
 export const slackDlq = {
     letter: (row) => ({ connector: 'slack', ...row }),
     list: listSlackDlq,
+    entry: slackDlqEntry,
+    bump: markSlackDlqRetried,
 };
-/**
- * Replay a DLQ row through the normal ingest path. Used by `hippo slack dlq
- * replay <id> [--force]`.
- *
- * Behavior:
- *   1. SELECT the row.
- *   2. If signature + slack_timestamp are present and `signingSecret` is set,
- *      re-verify with the CURRENT secret (not previous). Failure → bail unless
- *      --force. Legacy rows from before v19 may have NULL signature; those
- *      require --force to replay safely.
- *   3. Re-parse the raw_payload and dispatch to ingestMessage / handleMessageDeleted.
- *   4. On success: mark retried_at, increment retry_count.
- *   5. On failure: increment retry_count only, leave the row.
- *
- * The replay always uses the routing the deployment has NOW (current
- * slack_workspaces table + env), not whatever was in effect when the original
- * envelope was DLQed. That is intentional: the DLQ exists to be drained after
- * the operator fixed the routing.
- */
+/** Replay a DLQ row via the normal ingest path (`hippo slack dlq replay <id> [--force]`), re-verifying the signature with the CURRENT secret unless forced.
+ *  Rows with a NULL signature need --force; replays use today's routing, because the DLQ exists to be drained after the operator fixed routing. */
 export async function replayDlqEntry(ctx, id, opts = {}) {
-    const row = slackDlqEntry(ctx.hippoRoot, id);
-    if (!row)
-        return replayFailed('not_found', 0, `dlq id ${id} not found`);
-    // Signature verification (current secret, not previous).
-    if (!opts.force) {
-        const sigFailure = checkReplaySignature(row, opts);
-        if (sigFailure)
-            return sigFailure;
-    }
-    // Parse + dispatch.
-    let parsed;
-    try {
-        parsed = JSON.parse(row.rawPayload);
-    }
-    catch (e) {
-        return failAndBump(ctx.hippoRoot, row, 'parse_error', `still unparseable: ${errorMessage(e)}`);
-    }
-    if (!isSlackEventEnvelope(parsed)) {
-        return failAndBump(ctx.hippoRoot, row, 'unhandled', 'not an event_callback envelope');
-    }
-    // Resolve tenant against current state. If still unroutable, bail.
-    const tenant = await resolveTenantForSlackTeam(ctx.hippoRoot, parsed.team_id);
-    if (!tenant) {
-        return failAndBump(ctx.hippoRoot, row, 'unroutable', `team_id ${parsed.team_id} still unroutable`);
-    }
-    const replayCtx = {
-        hippoRoot: ctx.hippoRoot,
-        tenantId: tenant,
-        actor: adminActor('connector:slack:replay'),
-    };
-    return dispatchReplay(replayCtx, row, parsed);
+    return replayParked({
+        dlq: slackDlq,
+        refuseSignature: (row) => refuseSignature(row, opts),
+        isEnvelope: isSlackEventEnvelope,
+        notEnvelope: 'not an event_callback envelope',
+        reingest: (_row, envelope) => reingest(ctx.hippoRoot, envelope),
+    }, ctx.hippoRoot, id, opts.force === true);
 }
-/** The failure result when the row cannot pass the signature gate, else null; never bumps the count. */
-function checkReplaySignature(row, opts) {
+/** A missing signature or timestamp refuses even without a secret; a mismatch needs the current secret to show. */
+function refuseSignature(row, opts) {
     if (!row.signature || !row.slackTimestamp) {
-        return replayFailed('sig_missing', row.retryCount, 'row has no signature/timestamp (legacy, or redacted before storing); pass --force to replay');
+        return {
+            status: 'sig_missing',
+            reason: 'row has no signature/timestamp (legacy, or redacted before storing); pass --force to replay',
+        };
     }
-    if (opts.signingSecret) {
-        const ok = verifySlackSignature({
-            rawBody: row.rawPayload,
-            signature: row.signature,
-            timestamp: row.slackTimestamp,
-            signingSecret: opts.signingSecret,
-            now: opts.now,
-            // Replays happen long after the fact — give them a wider skew unless overridden.
-            skewSeconds: opts.skewSeconds ?? 60 * 60 * 24 * 365,
-        });
-        if (!ok) {
-            return replayFailed('sig_fail', row.retryCount, 'signature did not verify against current SLACK_SIGNING_SECRET; pass --force to replay anyway');
-        }
-    }
-    return null;
-}
-function failAndBump(hippoRoot, row, status, reason) {
-    bumpSlackDlqRetryCount(hippoRoot, row.id);
-    return replayFailed(status, row.retryCount + 1, reason);
+    if (!opts.signingSecret)
+        return null;
+    const ok = verifySlackSignature({
+        rawBody: row.rawPayload,
+        signature: row.signature,
+        timestamp: row.slackTimestamp,
+        signingSecret: opts.signingSecret,
+        now: opts.now,
+        // Replays happen long after the fact, so give them a wider skew unless overridden.
+        skewSeconds: opts.skewSeconds ?? YEAR_S,
+    });
+    if (ok)
+        return null;
+    return {
+        status: 'sig_fail',
+        reason: 'signature did not verify against current SLACK_SIGNING_SECRET; pass --force to replay anyway',
+    };
 }
-async function dispatchReplay(replayCtx, row, parsed) {
-    const { hippoRoot } = replayCtx;
-    const id = row.id;
-    const inner = parsed.event;
-    if (!isSlackMessageEvent(inner)) {
-        return failAndBump(hippoRoot, row, 'unhandled', `unhandled inner event type`);
-    }
+async function reingest(hippoRoot, envelope) {
+    const tenantId = await resolveTenantForSlackTeam(hippoRoot, envelope.team_id);
+    if (!tenantId)
+        return { ok: false, status: 'unroutable', reason: `team_id ${envelope.team_id} still unroutable` };
+    const inner = envelope.event;
+    if (!isSlackMessageEvent(inner))
+        return { ok: false, status: 'unhandled', reason: 'unhandled inner event type' };
+    const replayCtx = { hippoRoot, tenantId, actor: adminActor('connector:slack:replay') };
     if (inner.subtype === 'message_deleted' && inner.deleted_ts) {
         const r = await handleMessageDeleted(replayCtx, {
-            teamId: parsed.team_id,
+            teamId: envelope.team_id,
             channelId: inner.channel,
             deletedTs: inner.deleted_ts,
-            eventId: parsed.event_id,
+            eventId: envelope.event_id,
         });
-        markSlackDlqRetried(hippoRoot, id);
-        return { ok: true, status: r.status, memoryId: r.memoryId, retryCount: row.retryCount + 1 };
+        return { ok: true, status: r.status, memoryId: r.memoryId };
     }
     const result = await ingestMessage(replayCtx, {
-        teamId: parsed.team_id,
+        teamId: envelope.team_id,
         channel: {
             id: inner.channel,
             is_private: inner.channel_type !== 'channel',
@@ -115,9 +77,8 @@ async function dispatchReplay(replayCtx, row, parsed) {
             is_mpim: inner.channel_type === 'mpim',
         },
         message: inner,
-        eventId: parsed.event_id,
+        eventId: envelope.event_id,
     });
-    markSlackDlqRetried(hippoRoot, id);
-    return { ok: true, status: result.status, memoryId: result.memoryId, retryCount: row.retryCount + 1 };
+    return { ok: true, status: result.status, memoryId: result.memoryId };
 }
 //# sourceMappingURL=dlq.js.map

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

@@ -1,4 +1,5 @@
-import { type Context } from '../../api/index.js';
+import type { Context } from '../../api/index.js';
+import { type IngestResult } from '../ingest.js';
 import type { ChannelMeta } from './scope.js';
 import type { SlackMessageEvent } from './types.js';
 export interface IngestInput {
@@ -8,13 +9,7 @@ export interface IngestInput {
     /** Slack event_id for the envelope (or for backfill, a synthesized stable id). */
     eventId: string;
 }
-export type IngestStatus = 'ingested' | 'duplicate' | 'skipped' | 'skipped_duplicate';
-export interface IngestResult {
-    status: IngestStatus;
-    memoryId: string | null;
-}
-/** Ingests a Slack message as a kind='raw' memory, once per event id: Slack redelivers within a minute.
- *  The pre-check is only the fast path; the store logs the event in the memory's own transaction, which is what holds when two workers race.
- *  An empty body is logged with no memory, so its replay skips the transform. */
+/** Ingests a Slack message as a kind='raw' memory once per event id (Slack redelivers within a minute); the pre-check is only the fast path,
+ *  the store logs the event in the memory's own transaction, which holds when two workers race. An empty body is logged with no memory. */
 export declare function ingestMessage(ctx: Context, input: IngestInput): Promise<IngestResult>;
 //# sourceMappingURL=ingest.d.ts.map

package/dist/connectors/slack/ingest.js

@@ -1,10 +1,8 @@
-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 { messageToRememberOpts } from './transform.js';
-/** Ingests a Slack message as a kind='raw' memory, once per event id: Slack redelivers within a minute.
- *  The pre-check is only the fast path; the store logs the event in the memory's own transaction, which is what holds when two workers race.
- *  An empty body is logged with no memory, so its replay skips the transform. */
+/** Ingests a Slack message as a kind='raw' memory once per event id (Slack redelivers within a minute); the pre-check is only the fast path,
+ *  the store logs the event in the memory's own transaction, which holds when two workers race. An empty body is logged with no memory. */
 export async function ingestMessage(ctx, input) {
     const events = requireGroup(storeFor(ctx), 'connectorEvents');
     const event = { connector: 'slack', eventId: input.eventId };
@@ -16,30 +14,6 @@ export async function ingestMessage(ctx, input) {
         // they first returned; a non-NULL memory_id means a memory was ingested, so 'duplicate'.
         return { status: seen.memoryId === null ? 'skipped' : 'duplicate', memoryId: seen.memoryId };
     }
-    const opts = messageToRememberOpts(input);
-    if (!opts) {
-        await events.markEventSeen(event);
-        return { status: 'skipped', memoryId: null };
-    }
-    try {
-        return await rememberWithEventLog(ctx, event, opts);
-    }
-    catch (e) {
-        if (!(e instanceof RejectedValueError))
-            throw e;
-        // A tombstone hit is a PERMANENT skip: a DLQ retry would hit the same refusal forever, so mark the
-        // event seen like the empty-body branch above and let a Slack retry ack as done, not error.
-        await events.markEventSeen(event);
-        return { status: 'skipped', memoryId: null };
-    }
-}
-async function rememberWithEventLog(ctx, event, opts) {
-    // No `|| 'connector:slack'` fallback: the caller always builds ctx with the connector subject, and with
-    // an object-shaped Context.actor an OR-fallback would never fire anyway.
-    const result = await remember(ctx, { ...opts, untrusted: true, event });
-    // Another worker logged this event 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 };
+    return rememberWithEventLog(ctx, event, messageToRememberOpts(input));
 }
 //# sourceMappingURL=ingest.js.map

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

@@ -4,13 +4,7 @@ export interface ChannelMeta {
     is_im?: boolean;
     is_mpim?: boolean;
 }
-/**
- * Map a Slack channel into a hippo scope string.
- *
- * Default to private when privacy is undetermined. The cost of leaking a
- * public channel into private scope (recall returns nothing) is far smaller
- * than the cost of leaking a private channel into public scope (data exposed
- * to a tenant that should not see it).
- */
+/** Map a Slack channel into a hippo scope string, defaulting to private when privacy is undetermined:
+ *  a public channel leaking into private scope returns nothing, but the reverse exposes data. */
 export declare function scopeFromChannel(ch: ChannelMeta): string;
 //# sourceMappingURL=scope.d.ts.map

package/dist/connectors/slack/scope.js

@@ -1,11 +1,5 @@
-/**
- * Map a Slack channel into a hippo scope string.
- *
- * Default to private when privacy is undetermined. The cost of leaking a
- * public channel into private scope (recall returns nothing) is far smaller
- * than the cost of leaking a private channel into public scope (data exposed
- * to a tenant that should not see it).
- */
+/** Map a Slack channel into a hippo scope string, defaulting to private when privacy is undetermined:
+ *  a public channel leaking into private scope returns nothing, but the reverse exposes data. */
 export function scopeFromChannel(ch) {
     const isPublic = ch.is_private === false && !ch.is_im && !ch.is_mpim;
     return isPublic ? `slack:public:${ch.id}` : `slack:private:${ch.id}`;

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

@@ -3,12 +3,7 @@ export interface VerifyOpts {
     timestamp: string;
     signature: string;
     signingSecret: string;
-    /**
-     * Previous signing secret during a rotation. Deploy with
-     * both `SLACK_SIGNING_SECRET` (new) and `SLACK_SIGNING_SECRET_PREVIOUS` (old)
-     * set, verify both work, drop previous after rollover. The verifier tries
-     * `signingSecret` first, then `previousSecret` if that fails.
-     */
+    /** Previous signing secret during rotation (SLACK_SIGNING_SECRET_PREVIOUS); the verifier tries `signingSecret` first, then this. */
     previousSecret?: string;
     /** Current unix seconds. Injectable for tests. */
     now?: number;

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

@@ -1,22 +1,5 @@
-import type { DatabaseSyncLike } from '../../db/index.js';
 import { type HippoStore } from '../../store/index.js';
-/**
- * Look up the tenant_id for a Slack team_id.
- *
- * Returns:
- *   - mapped tenant_id when slack_workspaces has a row for `teamId`
- *   - the deployment's HIPPO_TENANT fallback (or 'default') when slack_workspaces
- *     is empty (single-workspace install — env fallback is safe)
- *   - null when slack_workspaces is non-empty AND `teamId` is unknown
- *     (multi-workspace install — fail closed; an unknown team is not the
- *     deployment's tenant). Escape hatch: SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK=1
- *     restores the env fallback for emergency rollback only.
- *
- * The fail-closed contract lives here so every caller (route handler, CLI
- * replay, future MCP) gets the same protection against routing a foreign
- * workspace's events into the deployment tenant.
- */
-export declare function resolveTenantForTeam(db: DatabaseSyncLike, teamId: string): string | null;
-/** resolveTenantForTeam through `store`, else hippo.db under `hippoRoot`. */
+/** Look up the tenant_id for a Slack team_id; the HIPPO_TENANT fallback applies only when slack_workspaces is empty (single-workspace install).
+ *  An unknown team on a multi-workspace install returns null (fail closed); SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK=1 is the emergency escape. */
 export declare function resolveTenantForSlackTeam(hippoRoot: string, teamId: string, store?: HippoStore): Promise<string | null>;
 //# sourceMappingURL=tenant-routing.d.ts.map

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

@@ -1,26 +1,7 @@
 import { envSlackAllowUnknownTeamFallback, envTenant } from '../../util/env.js';
 import { requireGroup, storeFor } from '../../store/index.js';
-import { slackTeamRouteAt } from '../../store/connectors/slack.js';
-/**
- * Look up the tenant_id for a Slack team_id.
- *
- * Returns:
- *   - mapped tenant_id when slack_workspaces has a row for `teamId`
- *   - the deployment's HIPPO_TENANT fallback (or 'default') when slack_workspaces
- *     is empty (single-workspace install — env fallback is safe)
- *   - null when slack_workspaces is non-empty AND `teamId` is unknown
- *     (multi-workspace install — fail closed; an unknown team is not the
- *     deployment's tenant). Escape hatch: SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK=1
- *     restores the env fallback for emergency rollback only.
- *
- * The fail-closed contract lives here so every caller (route handler, CLI
- * replay, future MCP) gets the same protection against routing a foreign
- * workspace's events into the deployment tenant.
- */
-export function resolveTenantForTeam(db, teamId) {
-    return tenantForRoute(slackTeamRouteAt(db, teamId));
-}
-/** resolveTenantForTeam through `store`, else hippo.db under `hippoRoot`. */
+/** Look up the tenant_id for a Slack team_id; the HIPPO_TENANT fallback applies only when slack_workspaces is empty (single-workspace install).
+ *  An unknown team on a multi-workspace install returns null (fail closed); SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK=1 is the emergency escape. */
 export async function resolveTenantForSlackTeam(hippoRoot, teamId, store) {
     return tenantForRoute(await requireGroup(storeFor({ hippoRoot, store }), 'connectorEvents').slackTeamRoute(teamId));
 }

package/dist/connectors/slack/transform.d.ts

@@ -6,23 +6,7 @@ export interface TransformInput {
     channel: ChannelMeta;
     message: SlackMessageEvent;
 }
-/**
- * Convert a SlackMessageEvent into RememberOpts for api.remember(). Returns
- * null when the message has no usable body (e.g. system events, bot reactions
- * without text). Caller treats null as "skip but mark idempotency seen".
- *
- * Contract:
- * - kind is the literal 'raw' (connector boundary, see src/importers.ts).
- * - artifact_ref format MUST be exactly `slack://${teamId}/${channelId}/${ts}`;
- *   the deletion path looks up by this string.
- * - owner is non-null whenever a row is written. Required by the
- *   provenance gate (`hippo provenance --strict`).
- *   - `user:<slack_user_id>` when the event carries a `user`.
- *   - `bot:<bot_id>` for the `bot_message` subtype (or any userless+text event
- *     that supplies bot_id).
- *   - `bot:unknown` only as a last-resort sentinel so the gate never sees null.
- *     Skipping userless messages instead would silently drop bot ingestion
- *     via the "skipped but seen" path in ingest.ts.
- */
+/** Convert a SlackMessageEvent into RememberOpts; returns null when the message has no usable body so the caller marks it seen and skips it.
+ *  artifact_ref MUST be `slack://${teamId}/${channelId}/${ts}` (deletion looks it up); owner is never null: `user:<id>`, `bot:<bot_id>`, else `bot:unknown`. */
 export declare function messageToRememberOpts(input: TransformInput): RememberOpts | null;
 //# sourceMappingURL=transform.d.ts.map

package/dist/connectors/slack/transform.js

@@ -1,22 +1,6 @@
 import { scopeFromChannel } from './scope.js';
-/**
- * Convert a SlackMessageEvent into RememberOpts for api.remember(). Returns
- * null when the message has no usable body (e.g. system events, bot reactions
- * without text). Caller treats null as "skip but mark idempotency seen".
- *
- * Contract:
- * - kind is the literal 'raw' (connector boundary, see src/importers.ts).
- * - artifact_ref format MUST be exactly `slack://${teamId}/${channelId}/${ts}`;
- *   the deletion path looks up by this string.
- * - owner is non-null whenever a row is written. Required by the
- *   provenance gate (`hippo provenance --strict`).
- *   - `user:<slack_user_id>` when the event carries a `user`.
- *   - `bot:<bot_id>` for the `bot_message` subtype (or any userless+text event
- *     that supplies bot_id).
- *   - `bot:unknown` only as a last-resort sentinel so the gate never sees null.
- *     Skipping userless messages instead would silently drop bot ingestion
- *     via the "skipped but seen" path in ingest.ts.
- */
+/** Convert a SlackMessageEvent into RememberOpts; returns null when the message has no usable body so the caller marks it seen and skips it.
+ *  artifact_ref MUST be `slack://${teamId}/${channelId}/${ts}` (deletion looks it up); owner is never null: `user:<id>`, `bot:<bot_id>`, else `bot:unknown`. */
 export function messageToRememberOpts(input) {
     const text = input.message.text?.trim();
     if (!text)

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

@@ -1,7 +1,5 @@
-/**
- * Slack Events API envelope shapes used by the ingestion connector.
- * Spec: https://api.slack.com/events-api
- */
+/** Slack Events API envelope shapes used by the ingestion connector.
+ *  Spec: https://api.slack.com/events-api */
 import { type JsonValue } from '../../util/json.js';
 export interface SlackUrlVerification {
     type: 'url_verification';
@@ -17,11 +15,7 @@ export interface SlackMessageEvent {
     text?: string;
     ts: string;
     thread_ts?: string;
-    /**
-     * Slack `bot_message` subtype carries `bot_id` instead of `user`. The
-     * provenance gate requires a non-null `owner`, so transform.ts
-     * derives `owner: bot:<bot_id>` when `user` is absent.
-     */
+    /** The `bot_message` subtype carries `bot_id` instead of `user`; transform.ts derives `owner: bot:<bot_id>` from it. */
     bot_id?: string;
     /** Present on subtype='message_deleted'. */
     deleted_ts?: string;

package/dist/connectors/slack/types.js

@@ -1,7 +1,5 @@
-/**
- * Slack Events API envelope shapes used by the ingestion connector.
- * Spec: https://api.slack.com/events-api
- */
+/** Slack Events API envelope shapes used by the ingestion connector.
+ *  Spec: https://api.slack.com/events-api */
 import { isJsonString, isJsonObject, isJsonNumber } from '../../util/json.js';
 export function isSlackEventEnvelope(x) {
     if (!isJsonObject(x))

package/dist/connectors/slack/web-client.js

@@ -1,15 +1,31 @@
 import { fetchWithRetry, isRetryableStatus } from '../../util/http-retry.js';
-import { isJsonString } from '../../util/json.js';
-/**
- * Build a SlackHistoryFetcher that pages `conversations.history` over real
- * HTTP. Wraps `fetchWithRetry` so 429 and 5xx handling is automatic. The returned
- * fetcher is the one `backfillChannel` consumes.
- *
- * Slack omits `channel` from messages in the history response, so we stamp
- * the request channel id onto each parsed message — downstream ingest needs
- * it on every event.
- */
+import { readCappedJson } from '../../util/capped-json.js';
+import { errorMessage } from '../../util/log.js';
+import { isJsonObject, isJsonString } from '../../util/json.js';
+/** Build a SlackHistoryFetcher that pages `conversations.history` over HTTP via `fetchWithRetry` (429 and 5xx handled).
+ *  Slack omits `channel` from history messages, so the request channel id is stamped onto each one for ingest. */
 const SLACK_TIMEOUT_MS = 30_000;
+// A page is at most 200 messages, each up to 40,000 characters at 4 bytes, carried once as text and once as rich-text blocks.
+const SLACK_MAX_REPLY_BYTES = 64 * 1024 * 1024;
+function isSlackMessage(m) {
+    return isJsonObject(m) && m.type === 'message' && isJsonString(m.ts);
+}
+/** The reply as a JSON object. The error names the status and the path only, since the query string carries channel ids and cursors. */
+async function readHistoryReply(r, url) {
+    const where = `slack: HTTP ${r.status} on ${url.pathname}`;
+    let body;
+    try {
+        body = await readCappedJson(r, SLACK_MAX_REPLY_BYTES);
+    }
+    catch (err) {
+        throw new Error(`${where}: ${errorMessage(err)}`, { cause: err });
+    }
+    if (!isJsonObject(body))
+        throw new Error(`${where}: the reply is not a JSON object`);
+    if (body.messages !== undefined && !Array.isArray(body.messages))
+        throw new Error(`${where}: \`messages\` is not an array`);
+    return body;
+}
 export function slackHistoryFetcher(token, fetchImpl) {
     return async ({ channelId, cursor, oldest }) => {
         const url = new URL('https://slack.com/api/conversations.history');
@@ -25,27 +41,17 @@ export function slackHistoryFetcher(token, fetchImpl) {
         });
         if (isRetryableStatus(r.status))
             throw new Error(`slack: still rate-limited or unavailable (HTTP ${r.status})`);
-        // SAFETY: body is the Slack `conversations.history` response; per the
-        // documented shape it's `{ ok, error?, messages?, response_metadata? }`.
-        const body = (await r.json());
-        if (!body.ok)
-            throw new Error(`slack: ${body.error ?? 'unknown error'}`);
-        const messages = (body.messages ?? [])
-            .filter((m) => {
-            if (m === null || Array.isArray(m) || typeof m !== 'object') {
-                return false;
-            }
-            // SAFETY: the check above just confirmed m is a non-null, non-array
-            // plain object, so it's safe to treat as a JSON-shaped record; the
-            // `m is SlackMessageEvent` predicate is what validates the fields.
-            const o = m;
-            return o.type === 'message' && isJsonString(o.ts);
-        })
+        const body = await readHistoryReply(r, url);
+        if (body.ok !== true)
+            throw new Error(`slack: ${isJsonString(body.error) ? body.error : 'unknown error'}`);
+        const messages = (Array.isArray(body.messages) ? body.messages : [])
+            .filter(isSlackMessage)
             // Slack returns messages without `channel`; stamp it from the request.
             .map((m) => ({ ...m, channel: channelId }));
+        const nextCursor = isJsonObject(body.response_metadata) ? body.response_metadata.next_cursor : undefined;
         return {
             messages,
-            next_cursor: body.response_metadata?.next_cursor ?? null,
+            next_cursor: isJsonString(nextCursor) ? nextCursor : null,
         };
     };
 }

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

@@ -1,23 +1,7 @@
 import type { HippoStore } from '../../store/index.js';
 import { type WebhookRequest } from '../../util/http-util.js';
-/**
- * Slack Events API webhook. Auth is signature-based (HMAC over the raw
- * body with SLACK_SIGNING_SECRET); Bearer is NOT required, which is why
- * this route is in PUBLIC_ROUTES. The route is responsible for:
- *   1. Echoing the one-time url_verification challenge.
- *   2. Verifying the HMAC on every other inbound payload.
- *   3. Resolving body.team_id → tenantId via slack_workspaces, falling
- *      back to HIPPO_TENANT then 'default'.
- *   4. Dispatching event_callback envelopes to ingestMessage /
- *      handleMessageDeleted.
- *   5. Parking malformed or unhandled payloads in slack_dlq and STILL
- *      ACKing 200 - Slack retries forever otherwise.
- *
- * When SLACK_SIGNING_SECRET is unset we return 404, not
- * 503, so an external probe cannot distinguish "route gated off by config"
- * from "route does not exist on this build".
- *
- * Bearer auth is skipped on purpose: server.ts checks isPublicRoute before calling this.
- */
+/** Slack Events API webhook: HMAC over the raw body with SLACK_SIGNING_SECRET, no Bearer (its route row declares webhook-signature);
+ *  malformed payloads go to slack_dlq, ACK 200.
+ *  404 (not 503) when the secret is unset, so a probe cannot tell a gated-off route from a missing one. */
 export declare function handleSlackEventsWebhook(request: WebhookRequest, store?: HippoStore): Promise<void>;
 //# sourceMappingURL=webhook.d.ts.map