@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/continuation-identity.ts

@@ -1,935 +0,0 @@
-/**
- * Continuation identity is a closed selector string. Omitted `continuation`
- * on a channel constructor stays `/v1` (engine pack minting) so existing
- * agents do not change: `githubChannel()` → `github.pr/v1`, `slackChannel()`
- * → `slack.thread/v1`, `originChannel()` → `origin.pr/v1`,
- * `deploymentsChannel()` → `deployments.none/v1`, `changeMonitorsChannel()`
- * → `none/v1`, `issuesChannel()` → `none/v1`, `httpChannel()` →
- * `none/v1`.
- *
- * Opt the whole agent into the v2 control plane with
- * `defineAgent({ architecture: "v2" })`. That stamps `/v2` defaults from
- * the channel kind and declared events (`github.pr/v2`, `github.issue/v2`,
- * `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
- * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
- * `issues.issue/v2`, …) onto every channel that omitted a
- * selector. An explicit per-channel selector still overrides. JSONPath
- * and per-agent format strings are rejected.
- */
-
-import { randomBytes } from "node:crypto";
-import { isSlackImChannel, slackThreadKey } from "./slack-thread-key.js";
-
-export type ConversationType =
-  | "pr"
-  | "issue"
-  | "thread"
-  | "origin-pr"
-  | "gitlab-mr"
-  | "bitbucket-pr"
-  | "deployment"
-  | "change-monitor-checkpoint"
-  | "factory-issue";
-
-export type ContinuationKind =
-  | "github"
-  | "slack"
-  | "origin"
-  | "gitlab"
-  | "bitbucket"
-  | "deployments"
-  | "change_monitors"
-  | "issues"
-  | "http";
-
-export const CONTINUATION_SELECTORS = [
-  "github.pr/v1",
-  "github.pr/v2",
-  "github.issue/v1",
-  "github.issue/v2",
-  "github.none/v2",
-  "slack.thread/v1",
-  "slack.thread/v2",
-  "slack.none/v2",
-  "origin.pr/v1",
-  "origin.pr/v2",
-  "origin.none/v2",
-  "gitlab.mr/v2",
-  "gitlab.none/v2",
-  "bitbucket.pr/v2",
-  "bitbucket.none/v2",
-  "deployments.none/v1",
-  "deployments.none/v2",
-  "deployments.deployment/v2",
-  "change_monitors.checkpoint/v2",
-  "issues.issue/v2",
-  "none/v1",
-  "none/v2",
-] as const;
-
-export type ContinuationSelector = (typeof CONTINUATION_SELECTORS)[number];
-export type ContinuationIdentity = ContinuationSelector;
-/** Agent-root protocol version. Omit / `"v1"` keeps engine minting. */
-export type ContinuationProtocolVersion = "v1" | "v2";
-
-export type ParsedContinuation = {
-  selector: ContinuationSelector;
-  version: 1 | 2;
-  type: ConversationType | "none";
-  kind: ContinuationKind;
-};
-
-export type ContinuationClaim = {
-  type: ConversationType;
-  resource:
-    | { owner: string; repo: string; number: number }
-    | { channelId: string; threadTs: string }
-    | { fullName: string; number: number }
-    | { deploymentId: string }
-    | { checkpointName: string }
-    | { issueName: string };
-};
-
-export type MailboxContinuation = {
-  key: string;
-};
-
-export type ContinuationBuiltin = {
-  type: ConversationType;
-  kind: Exclude<ContinuationKind, "http">;
-  events: readonly string[];
-  format: string;
-};
-
-export const BUILTINS: readonly ContinuationBuiltin[] = [
-  {
-    type: "pr",
-    kind: "github",
-    events: [
-      "pull_request",
-      "issue_comment",
-      "pull_request_review",
-      "pull_request_review_comment",
-      "check_suite",
-      "check_run",
-    ],
-    format: "github-pr:{fullName}#{number}",
-  },
-  {
-    type: "issue",
-    kind: "github",
-    events: ["issues", "issue_comment"],
-    format: "github-issue:{fullName}#{number}",
-  },
-  {
-    type: "thread",
-    kind: "slack",
-    events: ["message", "app_mention"],
-    format: "{channelId}:{threadTs}",
-  },
-  {
-    type: "origin-pr",
-    kind: "origin",
-    // Public webhook deliveries carry `pullRequest.number` + repository
-    // (`owner.slug` / `name`); keep in lockstep with the control plane's
-    // `conversation/origin.ts`.
-    events: [
-      "pull_request.created",
-      "pull_request.published",
-      "pull_request.head_ref.pushed",
-      "pull_request.base_ref.updated",
-      "pull_request.closed",
-      "pull_request.reopened",
-      "pull_request.merged",
-      "pull_request.comment.created",
-      "pull_request.review.submitted",
-      "pull_request.metadata.updated",
-    ],
-    format: "origin-pr:{fullName}#{number}",
-  },
-  {
-    type: "gitlab-mr",
-    kind: "gitlab",
-    // GitLab `object_kind`s that carry a merge request: `note` only when
-    // `noteable_type` is MergeRequest, `pipeline` only with `merge_request`.
-    events: ["merge_request", "note", "pipeline"],
-    format: "gitlab-mr:{fullName}!{number}",
-  },
-  {
-    type: "bitbucket-pr",
-    kind: "bitbucket",
-    // Cloud vocabulary; Data Center keys are normalized before the stamp.
-    events: [
-      "pullrequest:created",
-      "pullrequest:updated",
-      "pullrequest:approved",
-      "pullrequest:unapproved",
-      "pullrequest:changes_request_created",
-      "pullrequest:fulfilled",
-      "pullrequest:rejected",
-      "pullrequest:comment_created",
-    ],
-    format: "bitbucket-pr:{fullName}#{number}",
-  },
-  {
-    type: "deployment",
-    kind: "deployments",
-    // All three factory stream events carry `deploymentId`; keep in
-    // lockstep with the control plane's `conversation/deployments.ts`.
-    events: ["deployment.created", "deployment.succeeded", "deployment.failed"],
-    format: "deployments:{deploymentId}",
-  },
-  {
-    type: "change-monitor-checkpoint",
-    kind: "change_monitors",
-    events: ["checkpoint.created"],
-    format: "change_monitors:{checkpointName}",
-  },
-  {
-    type: "factory-issue",
-    kind: "issues",
-    events: ["issue.created"],
-    format: "issues:{issueName}",
-  },
-] as const;
-
-export class V2EngineError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "V2EngineError";
-  }
-}
-
-const SELECTOR_FIELDS: {
-  [K in ContinuationSelector]: Omit<ParsedContinuation, "selector">;
-} = {
-  "github.pr/v1": { version: 1, type: "pr", kind: "github" },
-  "github.pr/v2": { version: 2, type: "pr", kind: "github" },
-  "github.issue/v1": { version: 1, type: "issue", kind: "github" },
-  "github.issue/v2": { version: 2, type: "issue", kind: "github" },
-  "github.none/v2": { version: 2, type: "none", kind: "github" },
-  "slack.thread/v1": { version: 1, type: "thread", kind: "slack" },
-  "slack.thread/v2": { version: 2, type: "thread", kind: "slack" },
-  "slack.none/v2": { version: 2, type: "none", kind: "slack" },
-  "origin.pr/v1": { version: 1, type: "origin-pr", kind: "origin" },
-  "origin.pr/v2": { version: 2, type: "origin-pr", kind: "origin" },
-  "origin.none/v2": { version: 2, type: "none", kind: "origin" },
-  "gitlab.mr/v2": { version: 2, type: "gitlab-mr", kind: "gitlab" },
-  "gitlab.none/v2": { version: 2, type: "none", kind: "gitlab" },
-  "bitbucket.pr/v2": { version: 2, type: "bitbucket-pr", kind: "bitbucket" },
-  "bitbucket.none/v2": { version: 2, type: "none", kind: "bitbucket" },
-  "deployments.none/v1": { version: 1, type: "none", kind: "deployments" },
-  "deployments.none/v2": { version: 2, type: "none", kind: "deployments" },
-  "deployments.deployment/v2": {
-    version: 2,
-    type: "deployment",
-    kind: "deployments",
-  },
-  "change_monitors.checkpoint/v2": {
-    version: 2,
-    type: "change-monitor-checkpoint",
-    kind: "change_monitors",
-  },
-  "issues.issue/v2": {
-    version: 2,
-    type: "factory-issue",
-    kind: "issues",
-  },
-  "none/v1": { version: 1, type: "none", kind: "http" },
-  "none/v2": { version: 2, type: "none", kind: "http" },
-};
-
-function isContinuationSelector(value: string): value is ContinuationSelector {
-  return Object.hasOwn(SELECTOR_FIELDS, value);
-}
-
-export function defaultContinuationSelector(
-  kind?: string,
-  version: ContinuationProtocolVersion = "v1",
-  eventTypes?: readonly string[],
-): ContinuationSelector {
-  if (version !== "v2") {
-    switch (kind) {
-      case "github":
-        return "github.pr/v1";
-      case "slack":
-        return "slack.thread/v1";
-      case "origin":
-        return "origin.pr/v1";
-      case "deployments":
-        return "deployments.none/v1";
-      default:
-        return "none/v1";
-    }
-  }
-  switch (kind) {
-    case "github":
-      return githubV2Default(eventTypes);
-    case "slack":
-      return "slack.thread/v2";
-    case "origin":
-      return membershipOrNone(eventTypes, "origin-pr", "origin.pr/v2", "origin.none/v2");
-    case "gitlab":
-      return membershipOrNone(eventTypes, "gitlab-mr", "gitlab.mr/v2", "gitlab.none/v2");
-    case "bitbucket":
-      return membershipOrNone(eventTypes, "bitbucket-pr", "bitbucket.pr/v2", "bitbucket.none/v2");
-    case "deployments":
-      return membershipOrNone(
-        eventTypes,
-        "deployment",
-        "deployments.deployment/v2",
-        "deployments.none/v2",
-      );
-    case "change_monitors":
-      return membershipOrNone(
-        eventTypes,
-        "change-monitor-checkpoint",
-        "change_monitors.checkpoint/v2",
-        "none/v2",
-      );
-    case "issues":
-      return membershipOrNone(eventTypes, "factory-issue", "issues.issue/v2", "none/v2");
-    default:
-      return "none/v2";
-  }
-}
-
-/** Typed selector when every declared event is in the type's membership. */
-function membershipOrNone(
-  eventTypes: readonly string[] | undefined,
-  type: ConversationType,
-  typed: ContinuationSelector,
-  none: ContinuationSelector,
-): ContinuationSelector {
-  const allowed = new Set(builtinForType(type)?.events ?? []);
-  if ((eventTypes ?? []).some(event => !allowed.has(event))) {
-    return none;
-  }
-  return typed;
-}
-
-function githubV2Default(eventTypes?: readonly string[]): ContinuationSelector {
-  const events = eventTypes ?? [];
-  const issueEvents = new Set(builtinForType("issue")?.events ?? []);
-  const prEvents = new Set(builtinForType("pr")?.events ?? []);
-  if (events.length > 0 && events.every(event => issueEvents.has(event))) {
-    return "github.issue/v2";
-  }
-  if (events.some(event => !prEvents.has(event))) {
-    return "github.none/v2";
-  }
-  return "github.pr/v2";
-}
-
-const OMITTED_V2_TYPED_TYPE = {
-  github: "pr",
-  origin: "origin-pr",
-  deployments: "deployment",
-  change_monitors: "change-monitor-checkpoint",
-  issues: "factory-issue",
-} as const satisfies Partial<Record<string, ConversationType>>;
-
-/** Typed membership used when an omitted `/v2` selector becomes type `none`. */
-export function omittedV2TypedType(kind: string): ConversationType | undefined {
-  return OMITTED_V2_TYPED_TYPE[kind as keyof typeof OMITTED_V2_TYPED_TYPE];
-}
-
-/**
- * Omitted `/v2` default became type `none` because a declared event sits
- * outside the kind's typed membership. Validate warns; handshake stays
- * silent on omitted selectors (type `none` is always admitted).
- */
-export function omittedV2MembershipDowngrade(
-  kind: string,
-  eventTypes?: readonly string[],
-): { selector: ContinuationSelector; unexpected: readonly string[] } | undefined {
-  const events = eventTypes ?? [];
-  if (events.length === 0) {
-    return undefined;
-  }
-  const selector = defaultContinuationSelector(kind, "v2", events);
-  const parsed = parseContinuationSelector(selector);
-  if (parsed === undefined || parsed.type !== "none") {
-    return undefined;
-  }
-  const typedType = omittedV2TypedType(kind);
-  const typed = typedType === undefined ? undefined : builtinForType(typedType);
-  if (typed === undefined) {
-    return undefined;
-  }
-  const allowed = new Set(typed.events);
-  const unexpected = events.filter(event => !allowed.has(event));
-  if (unexpected.length === 0) {
-    return undefined;
-  }
-  return { selector, unexpected };
-}
-
-export function parseContinuationSelector(selector: string): ParsedContinuation | undefined {
-  if (!isContinuationSelector(selector)) {
-    return undefined;
-  }
-  return { selector, ...SELECTOR_FIELDS[selector] };
-}
-
-function resolveContinuation(raw?: ContinuationIdentity, kind?: string): ParsedContinuation {
-  const selector = raw ?? defaultContinuationSelector(kind);
-  const parsed = parseContinuationSelector(selector);
-  if (parsed === undefined) {
-    throw new V2EngineError(`v2: invalid continuation selector ${JSON.stringify(selector)}`);
-  }
-  return parsed;
-}
-
-export function normalizeIdentity(raw?: ContinuationIdentity, kind?: string): ContinuationIdentity {
-  return resolveContinuation(raw, kind).selector;
-}
-
-export function continuationSource(
-  identity?: ContinuationIdentity,
-  kind?: string,
-): "engine" | "control-plane" {
-  return resolveContinuation(identity, kind).version === 2 ? "control-plane" : "engine";
-}
-
-export function isV2DurableContinuationKey(key: string): boolean {
-  return key.startsWith("cont:") || key.startsWith("evt:");
-}
-
-function newEvtKey(): string {
-  return `evt:${randomBytes(16).toString("hex")}`;
-}
-
-function builtinForType(type: ConversationType): ContinuationBuiltin | undefined {
-  return BUILTINS.find(builtin => builtin.type === type);
-}
-
-function formatConversationKey(
-  type: ConversationType,
-  fields: {
-    fullName?: string;
-    number?: number;
-    channelId?: string;
-    threadTs?: string;
-    deploymentId?: string;
-    checkpointName?: string;
-    issueName?: string;
-  },
-): string {
-  switch (type) {
-    case "pr":
-      return `github-pr:${fields.fullName}#${fields.number}`;
-    case "issue":
-      return `github-issue:${fields.fullName}#${fields.number}`;
-    case "origin-pr":
-      return `origin-pr:${fields.fullName}#${fields.number}`;
-    case "gitlab-mr":
-      return `gitlab-mr:${fields.fullName}!${fields.number}`;
-    case "bitbucket-pr":
-      return `bitbucket-pr:${fields.fullName}#${fields.number}`;
-    case "thread":
-      return slackThreadKey(fields.channelId ?? "", fields.threadTs ?? "");
-    case "deployment":
-      return `deployments:${fields.deploymentId}`;
-    case "change-monitor-checkpoint":
-      return `change_monitors:${fields.checkpointName}`;
-    case "factory-issue":
-      return `issues:${fields.issueName}`;
-  }
-}
-
-export function mintClaim(claim: ContinuationClaim): string {
-  switch (claim.type) {
-    case "thread": {
-      const resource = claim.resource;
-      if (!("channelId" in resource && "threadTs" in resource)) {
-        throw new V2EngineError("v2: thread claim requires channelId and threadTs");
-      }
-      return `cont:${formatConversationKey("thread", resource)}`;
-    }
-    case "deployment": {
-      const resource = claim.resource;
-      if (!("deploymentId" in resource)) {
-        throw new V2EngineError("v2: deployment claim requires deploymentId");
-      }
-      return `cont:${formatConversationKey("deployment", resource)}`;
-    }
-    case "change-monitor-checkpoint": {
-      const resource = claim.resource;
-      if (!("checkpointName" in resource)) {
-        throw new V2EngineError("v2: change-monitor-checkpoint claim requires checkpointName");
-      }
-      return `cont:${formatConversationKey("change-monitor-checkpoint", resource)}`;
-    }
-    case "factory-issue": {
-      const resource = claim.resource;
-      if (!("issueName" in resource)) {
-        throw new V2EngineError("v2: factory-issue claim requires issueName");
-      }
-      return `cont:${formatConversationKey("factory-issue", resource)}`;
-    }
-    case "pr":
-    case "issue":
-    case "origin-pr":
-    case "gitlab-mr":
-    case "bitbucket-pr": {
-      const resource = claim.resource;
-      const fullName =
-        "fullName" in resource
-          ? resource.fullName
-          : "owner" in resource
-            ? `${resource.owner}/${resource.repo}`
-            : undefined;
-      const number = "number" in resource ? resource.number : undefined;
-      if (fullName === undefined || number === undefined) {
-        throw new V2EngineError(`v2: ${claim.type} claim requires repository and number`);
-      }
-      // GitLab paths and Bitbucket project keys arrive in API-native casing;
-      // the webhook extractors lowercase them, so the claim must too or the
-      // two mint different keys for the same MR / PR.
-      const caseFolded =
-        claim.type === "gitlab-mr" || claim.type === "bitbucket-pr"
-          ? fullName.toLowerCase()
-          : fullName;
-      return `cont:${formatConversationKey(claim.type, {
-        fullName: caseFolded,
-        number,
-      })}`;
-    }
-  }
-}
-
-export function handshakeContinuation(input: {
-  kind?: string;
-  eventTypes?: readonly string[];
-  identity?: ContinuationIdentity;
-}): { ok: true } | { ok: false; error: string } {
-  if (input.identity === undefined) {
-    return { ok: true };
-  }
-  const parsed = parseContinuationSelector(input.identity);
-  if (parsed === undefined) {
-    return {
-      ok: false,
-      error: `v2: invalid continuation selector ${JSON.stringify(input.identity)}`,
-    };
-  }
-  if (parsed.version !== 2 || parsed.type === "none") {
-    return { ok: true };
-  }
-  if (input.kind !== undefined && parsed.kind !== "http" && input.kind !== parsed.kind) {
-    return {
-      ok: false,
-      error: `v2: continuation ${parsed.selector} does not match channel kind ${input.kind}`,
-    };
-  }
-  const builtin = builtinForType(parsed.type);
-  if (builtin === undefined) {
-    return {
-      ok: false,
-      error: `v2: unknown continuation type ${parsed.type}`,
-    };
-  }
-  const eventTypes = input.eventTypes ?? [];
-  const allowed = new Set(builtin.events);
-  const unexpected = eventTypes.filter(event => !allowed.has(event));
-  if (unexpected.length > 0) {
-    return {
-      ok: false,
-      error: `v2: eventTypes ${unexpected.join(", ")} are not in the ${parsed.type} membership`,
-    };
-  }
-  return { ok: true };
-}
-
-/**
- * CP/pack extract. Returns a `cont:` key when the payload binds the
- * identity type; undefined on membership miss or missing number (caller
- * stamps `evt:` and does not join the conversation index).
- */
-export function extractContinuation(
-  type: ConversationType,
-  eventName: string,
-  payload: unknown,
-): string | undefined {
-  const builtin = builtinForType(type);
-  if (builtin === undefined) {
-    return undefined;
-  }
-  if (!builtin.events.includes(eventName)) {
-    return undefined;
-  }
-  switch (type) {
-    case "pr":
-    case "issue":
-      return extractGitHub(type, eventName, payload);
-    case "thread":
-      return extractSlack(payload);
-    case "origin-pr":
-      return extractOrigin(payload);
-    case "gitlab-mr":
-      return extractGitlab(eventName, payload);
-    case "bitbucket-pr":
-      return extractBitbucket(payload);
-    case "deployment":
-      return extractNamedResource("deployment", "deploymentId", payload);
-    case "change-monitor-checkpoint":
-      return extractNamedResource(
-        "change-monitor-checkpoint",
-        "checkpointName",
-        payload,
-        "checkpoint",
-      );
-    case "factory-issue":
-      return extractNamedResource("factory-issue", "issueName", payload, "issue");
-  }
-}
-
-/**
- * CP mailbox stamp. Hosted `routeVerifiedIngressContinuation` and local
- * `routeLocalIngressContinuation` call this; channel adapters must not.
- * Membership miss or missing identity fields stamp `evt:` instead of
- * joining the conversation index.
- */
-export function stampMailboxContinuation(
-  identity: ContinuationIdentity,
-  eventName: string,
-  payload: unknown,
-  kind?: string,
-): MailboxContinuation {
-  const parsed = resolveContinuation(identity, kind);
-  if (parsed.version !== 2) {
-    throw new V2EngineError("v2: refusing to stamp a mailbox key for v1");
-  }
-  if (parsed.type === "none") {
-    return { key: newEvtKey() };
-  }
-  const extracted = extractContinuation(parsed.type, eventName, payload);
-  if (extracted === undefined) {
-    return { key: newEvtKey() };
-  }
-  return { key: extracted };
-}
-
-export function resolveV2Key(
-  identity: ContinuationIdentity,
-  options: {
-    claim?: ContinuationClaim;
-    continuationToken?: string;
-    mailboxContinuation?: MailboxContinuation;
-  },
-  kind?: string,
-): string {
-  const parsed = resolveContinuation(identity, kind);
-  if (parsed.version !== 2) {
-    throw new V2EngineError("v2: resolveV2Key requires a /v2 selector");
-  }
-  if (options.continuationToken !== undefined) {
-    throw new V2EngineError("v2: do not pass continuationToken; use mailboxContinuation or claim");
-  }
-  if (options.claim !== undefined) {
-    if (parsed.type === "none") {
-      throw new V2EngineError("v2: type none cannot take a claim");
-    }
-    if (options.claim.type !== parsed.type) {
-      throw new V2EngineError(
-        `v2: claim type ${options.claim.type} does not match identity type ${parsed.type}`,
-      );
-    }
-    return mintClaim(options.claim);
-  }
-  if (options.mailboxContinuation !== undefined) {
-    return options.mailboxContinuation.key;
-  }
-  if (parsed.type === "none") {
-    return newEvtKey();
-  }
-  throw new V2EngineError("v2: no CP key on mailbox and no claim; refusing to mint in the engine");
-}
-
-export function bindMailboxContinuationSend<
-  TSession,
-  TOptions extends { mailboxContinuation?: MailboxContinuation },
->(
-  send: (message: string, options?: TOptions) => Promise<TSession>,
-  mailbox: MailboxContinuation | undefined,
-): (message: string, options?: TOptions) => Promise<TSession> {
-  if (mailbox === undefined) {
-    return send;
-  }
-  return (message, options) =>
-    send(message, {
-      ...(options as TOptions),
-      mailboxContinuation: options?.mailboxContinuation ?? mailbox,
-    } as TOptions);
-}
-
-function extractGitHub(
-  type: "pr" | "issue",
-  eventName: string,
-  payload: unknown,
-): string | undefined {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  const fullName = githubFullName(record);
-  if (fullName === undefined) {
-    return undefined;
-  }
-  const bound = githubBoundConversation(eventName, record);
-  if (bound === undefined || bound.type !== type) {
-    return undefined;
-  }
-  return `cont:${formatConversationKey(type, {
-    fullName,
-    number: bound.number,
-  })}`;
-}
-
-function githubBoundConversation(
-  eventName: string,
-  payload: Record<string, unknown>,
-): { type: "pr" | "issue"; number: number } | undefined {
-  switch (eventName) {
-    case "pull_request":
-    case "pull_request_review":
-    case "pull_request_review_comment":
-    case "pull_request_review_thread": {
-      const number = positiveInt(asRecord(payload.pull_request)?.number);
-      return number === undefined ? undefined : { type: "pr", number };
-    }
-    case "issues": {
-      const number = positiveInt(asRecord(payload.issue)?.number);
-      return number === undefined ? undefined : { type: "issue", number };
-    }
-    case "issue_comment": {
-      const issue = asRecord(payload.issue);
-      const number = positiveInt(issue?.number);
-      if (number === undefined) {
-        return undefined;
-      }
-      return issue?.pull_request !== undefined && issue.pull_request !== null
-        ? { type: "pr", number }
-        : { type: "issue", number };
-    }
-    case "check_suite": {
-      const number = firstPullRequestNumber(asRecord(payload.check_suite));
-      return number === undefined ? undefined : { type: "pr", number };
-    }
-    case "check_run": {
-      const checkRun = asRecord(payload.check_run);
-      const number =
-        firstPullRequestNumber(checkRun) ?? firstPullRequestNumber(asRecord(checkRun?.check_suite));
-      return number === undefined ? undefined : { type: "pr", number };
-    }
-    default:
-      return undefined;
-  }
-}
-
-function extractSlack(payload: unknown): string | undefined {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  // Events-API deliveries are the full event_callback body, so the
-  // identity fields live under `event`. Top-level fields still win for
-  // pre-flattened payloads (Socket Mode local dev, tests). Keep in
-  // lockstep with the control-plane twin (SlackThreadExtractor).
-  const event = asRecord(record.event);
-  const channelId =
-    nonEmpty(record.channelId) ??
-    nonEmpty(record.channel_id) ??
-    nonEmpty(record.channel) ??
-    nonEmpty(event?.channel);
-  const threadTs =
-    nonEmpty(record.threadTs) ??
-    nonEmpty(record.thread_ts) ??
-    nonEmpty(event?.thread_ts) ??
-    nonEmpty(record.ts) ??
-    nonEmpty(event?.ts);
-  if (channelId === undefined) {
-    return undefined;
-  }
-  if (!isSlackImChannel(channelId) && threadTs === undefined) {
-    return undefined;
-  }
-  return `cont:${slackThreadKey(channelId, threadTs ?? "")}`;
-}
-
-function extractOrigin(payload: unknown): string | undefined {
-  const record = originExtractRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  const inner = asRecord(record.pullRequest) ?? asRecord(record.pull_request);
-  const number = positiveInt(inner?.number);
-  const repository = asRecord(record.repository) ?? asRecord(inner?.repository);
-  const fullName =
-    nonEmpty(asRecord(repository)?.fullName) ??
-    nonEmpty(asRecord(repository)?.full_name) ??
-    originFullName(repository);
-  if (number === undefined || fullName === undefined) {
-    return undefined;
-  }
-  return `cont:${formatConversationKey("origin-pr", { fullName, number })}`;
-}
-
-/**
- * Mailbox stores the Origin delivery envelope; local/hosted CP extract
- * also accepts the compact `{ pullRequest, repository }` shape.
- */
-function originExtractRecord(payload: unknown): Record<string, unknown> | undefined {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  const nested = asRecord(asRecord(record.event)?.payload);
-  if (nested !== undefined && asRecord(record.pullRequest) === undefined) {
-    return nested;
-  }
-  return record;
-}
-
-/**
- * GitLab merge request identity: `project.path_with_namespace` (nested
- * groups keep their slashes; lowercased like the scope key) plus the MR
- * `iid`. `merge_request` reads `object_attributes.iid`; `note` binds only
- * MR notes (`noteable_type: "MergeRequest"`); `pipeline` binds only when
- * the payload carries a `merge_request`.
- */
-function extractGitlab(eventName: string, payload: unknown): string | undefined {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  const fullName = nonEmpty(asRecord(record.project)?.path_with_namespace)?.toLowerCase();
-  if (fullName === undefined) {
-    return undefined;
-  }
-  let number: number | undefined;
-  switch (eventName) {
-    case "merge_request":
-      number = positiveInt(asRecord(record.object_attributes)?.iid);
-      break;
-    case "note":
-      if (asRecord(record.object_attributes)?.noteable_type !== "MergeRequest") {
-        return undefined;
-      }
-      number = positiveInt(asRecord(record.merge_request)?.iid);
-      break;
-    case "pipeline":
-      number = positiveInt(asRecord(record.merge_request)?.iid);
-      break;
-    default:
-      return undefined;
-  }
-  if (number === undefined) {
-    return undefined;
-  }
-  return `cont:${formatConversationKey("gitlab-mr", { fullName, number })}`;
-}
-
-/**
- * Bitbucket pull request identity from either dialect. Cloud payloads carry
- * `repository.full_name` + `pullrequest.id`; Data Center payloads carry
- * `pullRequest.id` and the repo under `pullRequest.toRef.repository`
- * (`project.key/slug`). Lowercased so a Cloud/DC pair for one logical PR
- * shares a key.
- */
-function extractBitbucket(payload: unknown): string | undefined {
-  const record = asRecord(payload);
-  if (record === undefined) {
-    return undefined;
-  }
-  const pullRequest = asRecord(record.pullrequest) ?? asRecord(record.pullRequest);
-  const number = positiveInt(pullRequest?.id);
-  const fullName = bitbucketFullName(
-    asRecord(record.repository) ?? asRecord(asRecord(pullRequest?.toRef)?.repository),
-  );
-  if (number === undefined || fullName === undefined) {
-    return undefined;
-  }
-  return `cont:${formatConversationKey("bitbucket-pr", { fullName, number })}`;
-}
-
-function bitbucketFullName(repository: Record<string, unknown> | undefined): string | undefined {
-  if (repository === undefined) {
-    return undefined;
-  }
-  const cloud = nonEmpty(repository.full_name);
-  if (cloud !== undefined) {
-    return cloud.toLowerCase();
-  }
-  const projectKey = nonEmpty(asRecord(repository.project)?.key);
-  const slug = nonEmpty(repository.slug);
-  if (projectKey === undefined || slug === undefined) {
-    return undefined;
-  }
-  return `${projectKey}/${slug}`.toLowerCase();
-}
-
-function extractNamedResource(
-  type: "deployment" | "change-monitor-checkpoint" | "factory-issue",
-  field: "deploymentId" | "checkpointName" | "issueName",
-  payload: unknown,
-  wrapper?: "checkpoint" | "issue",
-): string | undefined {
-  const record = asRecord(payload);
-  const source = wrapper === undefined ? record : asRecord(record?.[wrapper]);
-  const value = nonEmpty(source?.[wrapper === undefined ? field : "name"]);
-  if (value === undefined) {
-    return undefined;
-  }
-  return `cont:${formatConversationKey(type, { [field]: value })}`;
-}
-
-function githubFullName(payload: Record<string, unknown>): string | undefined {
-  const repository = asRecord(payload.repository);
-  return nonEmpty(repository?.full_name) ?? originFullName(repository);
-}
-
-function originFullName(repository: Record<string, unknown> | undefined): string | undefined {
-  if (repository === undefined) {
-    return undefined;
-  }
-  const owner =
-    nonEmpty(asRecord(repository.owner)?.slug) ??
-    nonEmpty(repository.owner) ??
-    nonEmpty(asRecord(repository.owner)?.login) ??
-    nonEmpty(asRecord(repository.owner)?.name);
-  const name = nonEmpty(repository.name);
-  if (owner === undefined || name === undefined) {
-    return undefined;
-  }
-  return `${owner}/${name}`;
-}
-
-function firstPullRequestNumber(record: Record<string, unknown> | undefined): number | undefined {
-  const pullRequests = record?.pull_requests;
-  if (!Array.isArray(pullRequests) || pullRequests.length === 0) {
-    return undefined;
-  }
-  return positiveInt(asRecord(pullRequests[0])?.number);
-}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-function nonEmpty(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
-}
-
-function positiveInt(value: unknown): number | undefined {
-  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
-    return value;
-  }
-  if (typeof value === "string" && /^[1-9]\d*$/.test(value)) {
-    return Number(value);
-  }
-  return undefined;
-}