@devosurf/tesser-server 0.1.0-alpha.0

package/src/triggers/poll.ts

@@ -0,0 +1,167 @@
+// Poll-strategy connector triggers (ADR-0013): the runtime owns the loop — windowed
+// seen-set dedup by the author's dedupeKey, seed-without-firing on first activation,
+// one independent durable run per new item (oldest-first), opt-in cursor mode,
+// self-rescheduling with the author's `every` clamped to the connector floor + stagger.
+
+import { encodeJournal, parseDuration, validateSchema, type JsonValue } from "@devosurf/tesser-sdk/internal";
+import type { Db, DbClient } from "../db/db.js";
+import { createRun } from "../engine/runs.js";
+import { enqueue } from "../queue/queue.js";
+import { authDeclFor, makeActionCtx, providerFactsOf } from "../broker/connections.js";
+import {
+  isPollDecl,
+  loadTriggerState,
+  pruneSeen,
+  resolveLiveTrigger,
+  saveTriggerState,
+  type TriggerLayerDeps,
+} from "./shared.js";
+
+export interface PollJobPayload {
+  projectId: string;
+  automationId: string;
+  env: string;
+}
+
+export function pollDedupeKey(p: PollJobPayload): string {
+  return `trigger-poll:${p.projectId}:${p.automationId}:${p.env}`;
+}
+
+export function pollIntervalMs(decl: { interval?: { default: string; floor?: string } }, every?: string): number {
+  const defaultMs = parseDuration(decl.interval?.default ?? "2m", "trigger interval");
+  const floorMs = parseDuration(decl.interval?.floor ?? "30s", "trigger interval floor");
+  if (every === undefined) return Math.max(defaultMs, floorMs);
+  return Math.max(parseDuration(every, "trigger `every`"), floorMs);
+}
+
+export async function schedulePoll(
+  client: DbClient,
+  payload: PollJobPayload,
+  delayMs: number,
+  stagger = true,
+): Promise<void> {
+  // Stagger ±10% so many triggers on one cadence don't thundering-herd a provider.
+  const jitter = stagger ? delayMs * (Math.random() * 0.2 - 0.1) : 0;
+  await enqueue(client, {
+    kind: "trigger-poll",
+    payload: payload as never,
+    runAtMs: Date.now() + Math.max(1000, delayMs + jitter),
+    dedupeKey: pollDedupeKey(payload),
+    maxAttempts: 5,
+  });
+}
+
+/** Execute one poll for one (automation, trigger, connection); reschedules itself. */
+export async function runPoll(deps: TriggerLayerDeps, payload: PollJobPayload): Promise<{ fired: number } | null> {
+  const resolved = await resolveLiveTrigger(deps, payload.projectId, payload.automationId, payload.env);
+  if (!resolved) return null; // undeployed / connection missing → stop rescheduling
+  const { decl, manifest } = resolved;
+  if (!isPollDecl(decl)) return null;
+
+  const reschedule = async (db: Db) => {
+    await db.tx((c) => schedulePoll(c, payload, pollIntervalMs(decl, manifest.every)));
+  };
+
+  const stateKey = {
+    projectId: payload.projectId,
+    automationId: payload.automationId,
+    triggerId: manifest.trigger,
+    connectionId: resolved.connection.id,
+  };
+
+  try {
+    const bundle = await deps.broker.freshCredential(
+      resolved.connection.id,
+      providerFactsOf(resolved.connector.__connector)?.oauth2,
+    );
+    const actx = makeActionCtx({
+      spec: resolved.connector.__connector,
+      decl: authDeclFor(resolved.connector.__connector, resolved.connection.auth_mode),
+      conn: resolved.connection,
+      facts: providerFactsOf(resolved.connector.__connector),
+      fields: bundle.fields,
+      broker: deps.broker,
+      fetchImpl: deps.fetchImpl,
+    });
+
+    const state = await loadTriggerState(deps.db, stateKey, "poll");
+    const polled = await decl.poll(actx, resolved.params, state.cursor ?? undefined);
+    const items: unknown[] = Array.isArray(polled) ? polled : polled.items;
+    const nextCursor = Array.isArray(polled) ? undefined : polled.nextCursor;
+
+    const now = Date.now();
+    const seen = new Map(pruneSeen(state.seen, now));
+    let fired = 0;
+
+    if (!state.seeded) {
+      // First activation: seed without firing — turning a trigger on never floods (ADR-0013).
+      for (const item of items) seen.set(decl.dedupeKey(item), now);
+    } else {
+      const fresh = items.filter((item) => !seen.has(decl.dedupeKey(item)));
+      // Fire oldest-first regardless of the provider's natural order.
+      const ordered = (decl.order ?? "newest-first") === "newest-first" ? [...fresh].reverse() : fresh;
+      for (const item of ordered) {
+        const key = decl.dedupeKey(item);
+        const mapped = decl.map ? await decl.map(item, resolved.params) : item;
+        const validated = await validateSchema(
+          decl.output,
+          mapped,
+          `${manifest.connector}.triggers.${manifest.trigger} payload`,
+        );
+        await createRun(deps.db, {
+          projectId: payload.projectId,
+          automationId: payload.automationId,
+          versionId: resolved.versionId,
+          env: payload.env,
+          trigger: {
+            kind: "connector",
+            connector: manifest.connector,
+            trigger: manifest.trigger,
+            strategy: "poll",
+            itemKey: key,
+            connectionId: resolved.connection.id,
+            ...(resolved.connection.end_user_id !== null ? { endUserId: resolved.connection.end_user_id } : {}),
+          },
+          input: validated,
+        });
+        seen.set(key, now);
+        fired++;
+      }
+    }
+
+    await saveTriggerState(deps.db, stateKey, {
+      seen: [...seen.entries()],
+      ...(nextCursor !== undefined ? { cursor: encodeJournal(nextCursor) as JsonValue } : {}),
+      seeded: true,
+      touch: "poll",
+    });
+    return { fired };
+  } finally {
+    await reschedule(deps.db);
+  }
+}
+
+/** Activate polling for every live connector-poll trigger of a project+env (on promote). */
+export async function activatePolls(
+  deps: TriggerLayerDeps,
+  projectId: string,
+  env: string,
+): Promise<number> {
+  if (env !== "production") return 0; // preview is trigger-inert (ADR-0013)
+  const { rows } = await deps.db.query<{ automation_id: string; manifest: { trigger?: { kind?: string } } }>(
+    `SELECT a.automation_id, v.manifest FROM aliases a JOIN automation_versions v ON v.id=a.version_id
+     WHERE a.project_id=$1 AND a.env=$2`,
+    [projectId, env],
+  );
+  let activated = 0;
+  for (const row of rows) {
+    if (row.manifest.trigger?.kind !== "connector") continue;
+    const resolved = await resolveLiveTrigger(deps, projectId, row.automation_id, env).catch(() => null);
+    if (!resolved || !isPollDecl(resolved.decl)) continue;
+    await deps.db.tx((c) =>
+      schedulePoll(c, { projectId, automationId: row.automation_id, env }, 1500, false),
+    );
+    activated++;
+  }
+  return activated;
+}

package/src/triggers/registrar.ts

@@ -0,0 +1,274 @@
+// Webhook-strategy registration lifecycle (ADR-0013): auto mode rides the brokered token
+// to create/destroy provider hooks pointing at our stable ingress URL; manual mode
+// surfaces a connect-page step. Config-hash decides re-registration; undeploy
+// unregisters (no orphaned hooks).
+
+import { createHash, randomBytes } from "node:crypto";
+import { decodeJournal, stableStringify } from "@devosurf/tesser-sdk/internal";
+import type { Db } from "../db/db.js";
+import { authDeclFor, makeActionCtx, providerFactsOf } from "../broker/connections.js";
+import type { ManualWebhookRequirement } from "../broker/connect.js";
+import {
+  isWebhookDecl,
+  resolveLiveTrigger,
+  type TriggerLayerDeps,
+} from "./shared.js";
+
+function configHash(manifest: { connector: string; trigger: string; params: unknown }, connectionId: string): string {
+  return createHash("sha256")
+    .update(stableStringify({
+      connector: manifest.connector,
+      trigger: manifest.trigger,
+      params: manifest.params,
+      connection: connectionId,
+    } as never))
+    .digest("hex")
+    .slice(0, 24);
+}
+
+export interface RegistrationOutcome {
+  automationId: string;
+  trigger: string;
+  status: "registered" | "manual-pending" | "failed" | "unchanged";
+  manualRequirement?: ManualWebhookRequirement;
+  error?: string;
+}
+
+/** Bring one automation's webhook trigger to its registered state. */
+export async function ensureRegistration(
+  deps: TriggerLayerDeps,
+  projectId: string,
+  automationId: string,
+  env: string,
+): Promise<RegistrationOutcome | null> {
+  if (env !== "production") return null; // preview is trigger-inert (ADR-0013)
+  const resolved = await resolveLiveTrigger(deps, projectId, automationId, env);
+  if (!resolved || !isWebhookDecl(resolved.decl)) return null;
+  const { decl, manifest, connection } = resolved;
+  const hash = configHash(manifest, connection.id);
+
+  const { rows } = await deps.db.query<{
+    id: string;
+    config_hash: string;
+    status: string;
+    ingress_token: string;
+    external_id: string | null;
+    state: unknown;
+    signing_secret_cipher: string | null;
+  }>(
+    `SELECT id, config_hash, status, ingress_token, external_id, state, signing_secret_cipher
+     FROM webhook_registrations
+     WHERE project_id=$1 AND automation_id=$2 AND trigger_id=$3 AND connection_id=$4 AND env=$5`,
+    [projectId, automationId, manifest.trigger, connection.id, env],
+  );
+  const existing = rows[0];
+
+  if (existing && existing.config_hash === hash && ["registered", "manual-pending"].includes(existing.status)) {
+    if (existing.status === "registered") {
+      return { automationId, trigger: manifest.trigger, status: "unchanged" };
+    }
+    // still waiting on the human — re-surface the same requirement
+    return {
+      automationId,
+      trigger: manifest.trigger,
+      status: "manual-pending",
+      manualRequirement: manualRequirementFor(deps, existing.id, existing.ingress_token, resolved, decl),
+    };
+  }
+
+  // Config changed → tear down the old provider hook first (auto mode only).
+  if (existing && existing.config_hash !== hash) {
+    await destroyRegistration(deps, projectId, automationId, env, existing.id).catch(() => {});
+  }
+
+  const ingressToken = existing?.config_hash === hash ? existing.ingress_token : `wt_${randomBytes(16).toString("hex")}`;
+  const url = `${deps.baseUrl}/ingress/c/${ingressToken}`;
+
+  if (decl.register.mode === "manual") {
+    const { rows: created } = await deps.db.query<{ id: string }>(
+      `INSERT INTO webhook_registrations
+         (project_id, automation_id, trigger_id, connector_id, connection_id, env, config_hash, ingress_token, status)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'manual-pending')
+       ON CONFLICT (project_id, automation_id, trigger_id, connection_id, env)
+       DO UPDATE SET config_hash=EXCLUDED.config_hash, status='manual-pending', updated_at=now()
+       RETURNING id`,
+      [projectId, automationId, manifest.trigger, manifest.connector, connection.id, env, hash, ingressToken],
+    );
+    return {
+      automationId,
+      trigger: manifest.trigger,
+      status: "manual-pending",
+      manualRequirement: manualRequirementFor(deps, created[0]!.id, ingressToken, resolved, decl),
+    };
+  }
+
+  // auto mode: we generate the signing secret and call the provider's hook API.
+  const secret = randomBytes(24).toString("hex");
+  try {
+    const bundle = await deps.broker.freshCredential(
+      connection.id,
+      providerFactsOf(resolved.connector.__connector)?.oauth2,
+    );
+    const actx = makeActionCtx({
+      spec: resolved.connector.__connector,
+      decl: authDeclFor(resolved.connector.__connector, connection.auth_mode),
+      conn: connection,
+      facts: providerFactsOf(resolved.connector.__connector),
+      fields: bundle.fields,
+      broker: deps.broker,
+      fetchImpl: deps.fetchImpl,
+    });
+    const result = await decl.register.create(actx, { url, secret }, resolved.params);
+    const cipher = await deps.broker.encryptValue(resolved.workspaceId, secret, "webhook.signing");
+    await deps.db.query(
+      `INSERT INTO webhook_registrations
+         (project_id, automation_id, trigger_id, connector_id, connection_id, env, config_hash, ingress_token,
+          signing_secret_cipher, external_id, state, status)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::jsonb,'registered')
+       ON CONFLICT (project_id, automation_id, trigger_id, connection_id, env)
+       DO UPDATE SET config_hash=EXCLUDED.config_hash, ingress_token=EXCLUDED.ingress_token,
+         signing_secret_cipher=EXCLUDED.signing_secret_cipher, external_id=EXCLUDED.external_id,
+         state=EXCLUDED.state, status='registered', error=NULL, updated_at=now()`,
+      [
+        projectId,
+        automationId,
+        manifest.trigger,
+        manifest.connector,
+        connection.id,
+        env,
+        hash,
+        ingressToken,
+        cipher,
+        result && typeof result === "object" && "externalId" in result ? ((result as { externalId?: string }).externalId ?? null) : null,
+        result && typeof result === "object" && "state" in result ? JSON.stringify((result as { state?: unknown }).state ?? null) : null,
+      ],
+    );
+    return { automationId, trigger: manifest.trigger, status: "registered" };
+  } catch (err) {
+    await deps.db.query(
+      `INSERT INTO webhook_registrations
+         (project_id, automation_id, trigger_id, connector_id, connection_id, env, config_hash, ingress_token, status, error)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'failed',$9)
+       ON CONFLICT (project_id, automation_id, trigger_id, connection_id, env)
+       DO UPDATE SET status='failed', error=EXCLUDED.error, updated_at=now()`,
+      [projectId, automationId, manifest.trigger, manifest.connector, connection.id, env, hash, ingressToken, String(err).slice(0, 1000)],
+    );
+    return { automationId, trigger: manifest.trigger, status: "failed", error: String(err) };
+  }
+}
+
+function manualRequirementFor(
+  deps: TriggerLayerDeps,
+  registrationId: string,
+  ingressToken: string,
+  resolved: NonNullable<Awaited<ReturnType<typeof resolveLiveTrigger>>>,
+  decl: import("@devosurf/tesser-sdk/connector").WebhookTriggerDecl<any, any>,
+): ManualWebhookRequirement {
+  const url = `${deps.baseUrl}/ingress/c/${ingressToken}`;
+  const instructions =
+    decl.register.mode === "manual"
+      ? decl.register.instructions({ url, secret: "(paste your provider's signing secret below)" }, resolved.params)
+      : "";
+  return {
+    type: "webhook-manual",
+    registrationId,
+    connector: resolved.manifest.connector,
+    trigger: resolved.manifest.trigger,
+    automation: resolved.automationId,
+    instructions,
+    url,
+  };
+}
+
+/** Undeploy / config-change teardown: destroy the provider hook, mark removed, GC state. */
+export async function destroyRegistration(
+  deps: TriggerLayerDeps,
+  projectId: string,
+  automationId: string,
+  env: string,
+  registrationId: string,
+): Promise<void> {
+  const { rows } = await deps.db.query<{
+    id: string;
+    trigger_id: string;
+    connector_id: string;
+    connection_id: string | null;
+    external_id: string | null;
+    state: unknown;
+    status: string;
+  }>(`SELECT id, trigger_id, connector_id, connection_id, external_id, state, status FROM webhook_registrations WHERE id=$1`, [
+    registrationId,
+  ]);
+  const reg = rows[0];
+  if (!reg) return;
+
+  if (reg.status === "registered" && reg.connection_id) {
+    const resolved = await resolveLiveTrigger(deps, projectId, automationId, env).catch(() => null);
+    if (resolved && isWebhookDecl(resolved.decl) && resolved.decl.register.mode === "auto" && resolved.decl.register.destroy) {
+      try {
+        const bundle = await deps.broker.freshCredential(
+          resolved.connection.id,
+          providerFactsOf(resolved.connector.__connector)?.oauth2,
+        );
+        const actx = makeActionCtx({
+          spec: resolved.connector.__connector,
+          decl: authDeclFor(resolved.connector.__connector, resolved.connection.auth_mode),
+          conn: resolved.connection,
+          facts: providerFactsOf(resolved.connector.__connector),
+          fields: bundle.fields,
+          broker: deps.broker,
+          fetchImpl: deps.fetchImpl,
+        });
+        await resolved.decl.register.destroy(
+          actx,
+          { ...(reg.external_id !== null ? { externalId: reg.external_id } : {}), state: decodeJournal(reg.state as never) },
+          resolved.params,
+        );
+      } catch {
+        // best-effort: the provider hook may already be gone
+      }
+    }
+  }
+  await deps.db.query(`UPDATE webhook_registrations SET status='removed', updated_at=now() WHERE id=$1`, [reg.id]);
+  if (reg.connection_id) {
+    await deps.db.query(
+      `DELETE FROM trigger_state WHERE project_id=$1 AND automation_id=$2 AND trigger_id=$3 AND connection_id=$4`,
+      [projectId, automationId, reg.trigger_id, reg.connection_id],
+    );
+  }
+}
+
+/** Reconcile all webhook registrations for a project+env after promote. Returns the
+ *  manual steps that still need a human (they join the connect link). */
+export async function ensureRegistrations(
+  deps: TriggerLayerDeps,
+  projectId: string,
+  env: string,
+): Promise<RegistrationOutcome[]> {
+  if (env !== "production") return [];
+  const { rows } = await deps.db.query<{ automation_id: string; manifest: { trigger?: { kind?: string } } }>(
+    `SELECT a.automation_id, v.manifest FROM aliases a JOIN automation_versions v ON v.id=a.version_id
+     WHERE a.project_id=$1 AND a.env=$2`,
+    [projectId, env],
+  );
+  const outcomes: RegistrationOutcome[] = [];
+  const liveAutomationIds = new Set<string>();
+  for (const row of rows) {
+    liveAutomationIds.add(row.automation_id);
+    if (row.manifest.trigger?.kind !== "connector") continue;
+    const outcome = await ensureRegistration(deps, projectId, row.automation_id, env);
+    if (outcome) outcomes.push(outcome);
+  }
+  // Undeployed automations: tear down their registrations.
+  const stale = await deps.db.query<{ id: string; automation_id: string }>(
+    `SELECT id, automation_id FROM webhook_registrations
+     WHERE project_id=$1 AND env=$2 AND status IN ('registered','manual-pending','failed')`,
+    [projectId, env],
+  );
+  for (const reg of stale.rows) {
+    if (!liveAutomationIds.has(reg.automation_id)) {
+      await destroyRegistration(deps, projectId, reg.automation_id, env, reg.id);
+    }
+  }
+  return outcomes;
+}

package/src/triggers/shared.ts

@@ -0,0 +1,188 @@
+// Shared plumbing for the connector-trigger layer (ADR-0013): resolve a live automation
+// version to its def + connector instance + trigger declaration, and manage the
+// version-independent trigger state (windowed seen-set keyed by automation+trigger+connection).
+
+import { TerminalError, type AutomationDef } from "@devosurf/tesser-sdk";
+import type {
+  AnyTriggerDecl,
+  ConnectorInstance,
+  PollTriggerDecl,
+  WebhookTriggerDecl,
+} from "@devosurf/tesser-sdk/connector";
+import { decodeJournal, validateSchema, type JsonValue } from "@devosurf/tesser-sdk/internal";
+import type { Db } from "../db/db.js";
+import type { Broker, ConnectionRow } from "../broker/broker.js";
+
+export interface TriggerLayerDeps {
+  db: Db;
+  broker: Broker;
+  baseUrl: string;
+  loadAutomation(versionId: string): Promise<AutomationDef<any, any, any, any, any, any, any>>;
+  fetchImpl?: typeof fetch | undefined;
+}
+
+export interface ConnectorTriggerManifest {
+  kind: "connector";
+  connector: string;
+  trigger: string;
+  params: JsonValue;
+  connection: string;
+  every?: string;
+}
+
+export interface ResolvedTrigger {
+  projectId: string;
+  workspaceId: string;
+  automationId: string;
+  env: string;
+  versionId: string;
+  def: AutomationDef<any, any, any, any, any, any, any>;
+  manifest: ConnectorTriggerManifest;
+  connector: ConnectorInstance<any, any>;
+  decl: AnyTriggerDecl;
+  /** Validated trigger params (decl.input). */
+  params: unknown;
+  connection: ConnectionRow;
+}
+
+export function isPollDecl(d: AnyTriggerDecl): d is PollTriggerDecl<any, any, any> {
+  return d.__trigger === "poll";
+}
+export function isWebhookDecl(d: AnyTriggerDecl): d is WebhookTriggerDecl<any, any> {
+  return d.__trigger === "webhook";
+}
+
+/** Resolve everything a poll/delivery needs from the CURRENT live alias — the stable
+ *  registration outlives versions; the version is resolved at fire time (ADR-0013). */
+export async function resolveLiveTrigger(
+  deps: TriggerLayerDeps,
+  projectId: string,
+  automationId: string,
+  env: string,
+): Promise<ResolvedTrigger | null> {
+  const { rows } = await deps.db.query<{
+    version_id: string;
+    manifest: { trigger?: ConnectorTriggerManifest };
+    workspace_id: string;
+  }>(
+    `SELECT a.version_id, v.manifest, p.workspace_id
+     FROM aliases a
+     JOIN automation_versions v ON v.id = a.version_id
+     JOIN projects p ON p.id = a.project_id
+     WHERE a.project_id=$1 AND a.automation_id=$2 AND a.env=$3`,
+    [projectId, automationId, env],
+  );
+  const row = rows[0];
+  if (!row || row.manifest.trigger?.kind !== "connector") return null;
+  const manifest = row.manifest.trigger;
+
+  const def = await deps.loadAutomation(row.version_id);
+  const connector = (def.connections as Record<string, ConnectorInstance<any, any>> | undefined)?.[
+    manifest.connection
+  ];
+  if (!connector || connector.id !== manifest.connector) {
+    throw new TerminalError(
+      `automation ${automationId}: trigger connection "${manifest.connection}" missing from the loaded bundle`,
+    );
+  }
+  const decl = connector.__connector.triggers?.[manifest.trigger];
+  if (!decl) {
+    throw new TerminalError(`connector ${manifest.connector} has no trigger "${manifest.trigger}"`);
+  }
+
+  const conn = await deps.broker.resolveBinding({
+    workspaceId: row.workspace_id,
+    projectId,
+    automationId,
+    env,
+    reqKey: manifest.connection,
+    connectorId: manifest.connector,
+    scope: connector.scope ?? "workspace",
+  });
+  if (!conn) return null; // connection went away → trigger dormant until reconnected
+
+  const params = await validateSchema(
+    decl.input,
+    decodeJournal(manifest.params),
+    `${manifest.connector}.triggers.${manifest.trigger} params`,
+  );
+
+  return {
+    projectId,
+    workspaceId: row.workspace_id,
+    automationId,
+    env,
+    versionId: row.version_id,
+    def,
+    manifest,
+    connector,
+    decl,
+    params,
+    connection: conn,
+  };
+}
+
+// ---- windowed seen-set (version-independent dedup, ADR-0013) ----
+
+const SEEN_WINDOW_MS = 14 * 24 * 3600 * 1000;
+const SEEN_MAX = 2000;
+
+export interface TriggerState {
+  seen: Array<[string, number]>;
+  cursor: JsonValue | null;
+  seeded: boolean;
+}
+
+export async function loadTriggerState(
+  db: Db,
+  key: { projectId: string; automationId: string; triggerId: string; connectionId: string },
+  kind: "poll" | "webhook",
+): Promise<TriggerState> {
+  const { rows } = await db.query<{ seen: Array<[string, number]>; cursor: JsonValue | null; seeded: boolean }>(
+    `SELECT seen, cursor, seeded FROM trigger_state
+     WHERE project_id=$1 AND automation_id=$2 AND trigger_id=$3 AND connection_id=$4`,
+    [key.projectId, key.automationId, key.triggerId, key.connectionId],
+  );
+  if (rows[0]) return rows[0];
+  await db.query(
+    `INSERT INTO trigger_state (project_id, automation_id, trigger_id, connection_id, kind)
+     VALUES ($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING`,
+    [key.projectId, key.automationId, key.triggerId, key.connectionId, kind],
+  );
+  return { seen: [], cursor: null, seeded: false };
+}
+
+export function pruneSeen(seen: Array<[string, number]>, nowMs: number): Array<[string, number]> {
+  const cutoff = nowMs - SEEN_WINDOW_MS;
+  const pruned = seen.filter(([, ts]) => ts >= cutoff);
+  return pruned.length > SEEN_MAX ? pruned.slice(pruned.length - SEEN_MAX) : pruned;
+}
+
+export async function saveTriggerState(
+  db: Db,
+  key: { projectId: string; automationId: string; triggerId: string; connectionId: string },
+  state: { seen?: Array<[string, number]>; cursor?: JsonValue | null; seeded?: boolean; touch?: "poll" | "delivery" },
+): Promise<void> {
+  const sets: string[] = [];
+  const params: unknown[] = [key.projectId, key.automationId, key.triggerId, key.connectionId];
+  if (state.seen !== undefined) {
+    params.push(JSON.stringify(state.seen));
+    sets.push(`seen = $${params.length}::jsonb`);
+  }
+  if (state.cursor !== undefined) {
+    params.push(state.cursor === null ? null : JSON.stringify(state.cursor));
+    sets.push(`cursor = $${params.length}::jsonb`);
+  }
+  if (state.seeded !== undefined) {
+    params.push(state.seeded);
+    sets.push(`seeded = $${params.length}`);
+  }
+  if (state.touch === "poll") sets.push(`last_poll_at = now()`);
+  if (state.touch === "delivery") sets.push(`last_delivery_at = now()`);
+  if (sets.length === 0) return;
+  await db.query(
+    `UPDATE trigger_state SET ${sets.join(", ")}
+     WHERE project_id=$1 AND automation_id=$2 AND trigger_id=$3 AND connection_id=$4`,
+    params,
+  );
+}