@sixb/core 0.1.9 → 0.1.10

package/src/testing/lake-changes-contract.ts

@@ -0,0 +1,240 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { col, defineDataset } from "../datasets"
+import type { DatasetChanges, DatasetRow, DatasetRowChange, LakeStorage } from "../lake-storage"
+
+export function runLakeChangesContractSuite<T extends LakeStorage>(
+  name: string,
+  harness: {
+    readonly createStorage: () => T | Promise<T>
+    readonly teardown?: (storage: T) => void | Promise<void>
+  }
+): void {
+  describe(name, () => {
+    let storage: T
+    const dataset = defineDataset("delta.contract", {
+      schema: [
+        col("id", "string"),
+        col("part", "string"),
+        col("value", "string", { nullable: true }),
+        col("ignored", "string"),
+      ],
+    })
+    const row = (id: string, value: string | null, part = "x", ignored = "unused"): DatasetRow => ({
+      id,
+      part,
+      value,
+      ignored,
+    })
+    const columns = ["id", "part", "value"]
+    beforeEach(async () => {
+      storage = await harness.createStorage()
+      await storage.createDataset(dataset)
+    })
+    afterEach(async () => {
+      if (harness.teardown) await harness.teardown(storage)
+      else await storage.close?.()
+    })
+    async function write(rows: readonly DatasetRow[]) {
+      const writer = await storage.beginWrite({ dataset })
+      await writer.writeRows(rows)
+      return (await writer.commit()).versionId
+    }
+    async function read(fromVersionId: string, toVersionId: string, keyColumns = ["id"]) {
+      if (!storage.readChanges) throw new Error("Provider does not implement readChanges")
+      return storage.readChanges({
+        datasetId: dataset.id,
+        fromVersionId,
+        toVersionId,
+        columns,
+        keyColumns,
+      })
+    }
+    async function collect(reader: DatasetChanges | null) {
+      if (!reader) throw new Error("Expected a complete delta")
+      const changes: DatasetRowChange[] = []
+      try {
+        for await (const change of reader.changes) changes.push(change)
+      } finally {
+        await reader.close()
+      }
+      expect(changes).toHaveLength(reader.changeCount)
+      return changes.sort((a, b) =>
+        JSON.stringify(a.after ?? a.before).localeCompare(JSON.stringify(b.after ?? b.before))
+      )
+    }
+
+    // Red proof: remove the provider's readChanges implementation; this suite must fail.
+    test("compares pinned states across skipped versions, including removals and key changes", async () => {
+      const first = await write([row("A", "one"), row("B", "two"), row("C", "three")])
+      await write([row("A", "temporary"), row("B", "two"), row("C", "three")])
+      const last = await write([row("A", "one"), row("B", "new"), row("D", "three")])
+      const reader = await read(first, last)
+      expect(reader?.fromRowCount).toBe(3)
+      expect(reader?.toRowCount).toBe(3)
+      expect(await collect(reader)).toEqual([
+        {
+          before: { id: "B", part: "x", value: "two" },
+          after: { id: "B", part: "x", value: "new" },
+        },
+        { before: { id: "C", part: "x", value: "three" }, after: null },
+        { before: null, after: { id: "D", part: "x", value: "three" } },
+      ])
+    })
+    test("ignores row order and unrequested columns", async () => {
+      const first = await write([row("A", "one"), row("B", "two")])
+      const last = await write([row("B", "two", "x", "changed"), row("A", "one")])
+      expect(await collect(await read(first, last))).toEqual([])
+      expect(await collect(await read(last, last))).toEqual([])
+    })
+    test("distinguishes null from a value and handles an empty target", async () => {
+      const first = await write([row("A", null)])
+      const second = await write([row("A", "value")])
+      expect(await collect(await read(first, second))).toEqual([
+        {
+          before: { id: "A", part: "x", value: null },
+          after: { id: "A", part: "x", value: "value" },
+        },
+      ])
+      const empty = await write([])
+      expect(await collect(await read(second, empty))).toEqual([
+        { before: { id: "A", part: "x", value: "value" }, after: null },
+      ])
+      expect(await collect(await read(empty, second))).toEqual([
+        { before: null, after: { id: "A", part: "x", value: "value" } },
+      ])
+    })
+    test("supports composite keys without concatenation collisions", async () => {
+      const first = await write([row("a:b", "one", "c"), row("a", "two", "b:c")])
+      const last = await write([row("a:b", "new", "c"), row("a", "two", "b:c")])
+      expect(await collect(await read(first, last, ["id", "part"]))).toEqual([
+        {
+          before: { id: "a:b", part: "c", value: "one" },
+          after: { id: "a:b", part: "c", value: "new" },
+        },
+      ])
+    })
+    test("refuses duplicate keys in either snapshot rather than losing rows", async () => {
+      const first = await write([row("A", "one"), row("A", "two")])
+      const last = await write([row("A", "new")])
+      expect(await read(first, last)).toBeNull()
+      expect(await read(last, first)).toBeNull()
+    })
+    test("refuses blank identities and invalid column requests", async () => {
+      const first = await write([row(" ", "one")])
+      expect(await read(first, first)).toBeNull()
+      await expect(read(first, first, [])).rejects.toThrow("distinct columns")
+      await expect(read(first, first, ["missing"])).rejects.toThrow("distinct columns")
+    })
+    test("releases the connection between yielded changes and closes after early exit", async () => {
+      const first = await write([row("A", "one"), row("B", "two")])
+      const last = await write([row("A", "new"), row("B", "new")])
+      const reader = await read(first, last)
+      expect(reader).not.toBeNull()
+      try {
+        for await (const _change of reader!.changes) {
+          expect((await storage.getLatestVersion(dataset.id))?.versionId).toBe(last)
+          break
+        }
+      } finally {
+        await reader!.close()
+      }
+      expect((await storage.getLatestVersion(dataset.id))?.versionId).toBe(last)
+    })
+    test("pages a complete pinned delta while a newer snapshot is published", async () => {
+      const count = 5_007
+      const first = await write(Array.from({ length: count }, (_, i) => row(String(i), "old")))
+      const last = await write(Array.from({ length: count }, (_, i) => row(String(i), "new")))
+      const reader = await read(first, last)
+      expect(reader?.changeCount).toBe(count)
+      await write([row("later", "unrelated")])
+      const changes = await collect(reader)
+      expect(new Set(changes.map((change) => change.after?.id)).size).toBe(count)
+      expect(
+        changes.every((change) => change.before?.value === "old" && change.after?.value === "new")
+      ).toBe(true)
+    })
+    test("returns complete typed images without exposing mutable stored values", async () => {
+      const typed = defineDataset("delta.typed", {
+        schema: [
+          col("id", "string"),
+          col("payload", "json"),
+          col("at", "timestamp"),
+          col("amount", "int64"),
+        ],
+      })
+      await storage.createDataset(typed)
+      const writeTyped = async (value: number) => {
+        const writer = await storage.beginWrite({ dataset: typed })
+        await writer.writeRows([
+          {
+            id: "a",
+            payload: { nested: [value] },
+            at: "2026-01-01T00:00:00.000Z",
+            amount: "9007199254740993",
+          },
+        ])
+        return (await writer.commit()).versionId
+      }
+      const first = await writeTyped(1)
+      const last = await writeTyped(2)
+      const reader = await storage.readChanges!({
+        datasetId: typed.id,
+        fromVersionId: first,
+        toVersionId: last,
+        keyColumns: ["id"],
+        columns: ["id", "payload", "at", "amount"],
+      })
+      const changes = await collect(reader)
+      expect(changes).toEqual([
+        {
+          before: {
+            id: "a",
+            payload: { nested: [1] },
+            at: "2026-01-01T00:00:00.000Z",
+            amount: "9007199254740993",
+          },
+          after: {
+            id: "a",
+            payload: { nested: [2] },
+            at: "2026-01-01T00:00:00.000Z",
+            amount: "9007199254740993",
+          },
+        },
+      ])
+      ;(changes[0]!.after!.payload as { nested: number[] }).nested.push(3)
+      const rows: DatasetRow[] = []
+      for await (const value of storage.readRows({ datasetId: typed.id, versionId: last }))
+        rows.push(value)
+      expect(rows[0]?.payload).toEqual({ nested: [2] })
+    })
+    test("returns unavailable for a version belonging to another dataset", async () => {
+      const first = await write([row("A", "one")])
+      const other = defineDataset("delta.other", { schema: [col("id", "string")] })
+      await storage.createDataset(other)
+      const writer = await storage.beginWrite({ dataset: other })
+      await writer.writeRows([{ id: "other" }])
+      const otherVersion = await writer.commit()
+      expect(await read(otherVersion.versionId, first)).toBeNull()
+      expect(await read(first, otherVersion.versionId)).toBeNull()
+    })
+    test("can close an unread delta and observes cancellation", async () => {
+      const first = await write([row("A", "one")])
+      const last = await write([row("A", "new")])
+      const reader = await read(first, last)
+      await reader!.close()
+      await reader!.close()
+      const controller = new AbortController()
+      controller.abort(new Error("cancelled delta"))
+      await expect(
+        storage.readChanges!({
+          datasetId: dataset.id,
+          fromVersionId: first,
+          toVersionId: last,
+          columns,
+          keyColumns: ["id"],
+          signal: controller.signal,
+        })
+      ).rejects.toThrow("cancelled delta")
+    })
+  })
+}

package/src/testing/materializer-storage-contract.ts

@@ -19,6 +19,8 @@ import {
   createOntologyMaterializer,
   type OntologyEditOperation,
   ProjectionRegistry,
+  type ProjectionSourceBase,
+  type ProjectionSourceDeletion,
   type ProjectionSourceEntry,
 } from "../materializer"
 import type { ActionRunStorage, ProjectionRunStorage } from "../storage"
@@ -125,6 +127,175 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
   name: string,
   provider: MaterializerStorageContractProvider<TStorage>
 ): void {
+  // Regression: replacing previousSourceRows with only the latest manifest loses "a" at v3.
+  // Removing root retirement checks from cleanup deletes "a" when v1 becomes terminal.
+  test(`${name} retains current roots across deltas, cleanup, overrides and full replacement`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let ordinal = 0
+    const projectId = "materializer-storage-contract"
+    const source = { projectionId: devices.id }
+    const materializer = createOntologyMaterializer({
+      projectId,
+      ontology,
+      projections,
+      storage,
+      dependencies: { batching: { sourceStageRows: 1, statePageRows: 1, planChunkRows: 1 } },
+    })
+    const active = async (): Promise<ProjectionSourceBase> => {
+      const current = await materializer.projections.getActive(source)
+      if (!current?.lastCommitId) throw new Error("Missing source head")
+      return { materializationId: current.materializationId, lastCommitId: current.lastCommitId }
+    }
+    const replace = async (
+      values: readonly (ProjectionSourceEntry | ProjectionSourceDeletion)[],
+      base?: ProjectionSourceBase,
+      interleave?: { readonly version: number; readonly beforeSeal?: () => Promise<void> }
+    ) => {
+      const version = interleave?.version ?? ++ordinal
+      const datasetVersion = {
+        datasetId: devices.id,
+        versionId: `delta-v${version}`,
+        createdAt: `2026-01-${String(version).padStart(2, "0")}T00:00:00.000Z`,
+      }
+      const execution = await claim(storage, {
+        runId: `delta-run-${version}`,
+        projectionId: devices.id,
+        protocol: "replacement",
+        datasetVersion,
+      })
+      const bound = await projectionMaterializer(
+        materializer,
+        storage,
+        devices.id,
+        execution.projectionRunId
+      )
+      return bound.projections.replace({
+        source,
+        datasetVersion,
+        execution,
+        entries: (async function* () {
+          yield* entries(values)
+          await interleave?.beforeSeal?.()
+        })(),
+        ...(base ? { base } : {}),
+      })
+    }
+    const ref = (primaryId: string) => ({ objectTypeId: Device.id, primaryId })
+    const object = (id: string) => storage.objects.getByPrimaryId({ projectId, ...ref(id) })
+    const remove = (id: string): ProjectionSourceDeletion => ({
+      root: { kind: "object", ref: ref(id) },
+      deleted: true,
+    })
+    try {
+      await replace([sourceEntry("a", "A"), sourceEntry("b", "B", "a"), sourceEntry("c", "C")])
+      const stale = await active()
+      const initialA = await object("a")
+      const initialB = await object("b")
+      const transact = storage.transaction.bind(storage)
+      // Fail after finalize has moved the source pointers, written the commit and its outbox.
+      // Removing the enclosing transaction rollback must fail these head/value assertions.
+      storage.transaction = (run, options) =>
+        transact(async (tx) => {
+          const materializations = new Proxy(tx.ontology.materializations, {
+            get(target, key) {
+              if (key !== "finalize") return Reflect.get(target, key)
+              return async (input: Parameters<typeof target.finalize>[0]) => {
+                await target.finalize(input)
+                throw new Error("injected after source activation")
+              }
+            },
+          })
+          const ontology = new Proxy(tx.ontology, {
+            get(target, key) {
+              return key === "materializations" ? materializations : Reflect.get(target, key)
+            },
+          })
+          return run(
+            new Proxy(tx, {
+              get(target, key) {
+                return key === "ontology" ? ontology : Reflect.get(target, key)
+              },
+            })
+          )
+        }, options)
+      try {
+        await expect(replace([remove("a"), sourceEntry("b", "Failed B")], stale)).rejects.toThrow(
+          "injected after source activation"
+        )
+      } finally {
+        storage.transaction = transact
+      }
+      expect(await active()).toEqual(stale)
+      expect(await object("a")).toEqual(initialA)
+      expect(await object("b")).toEqual(initialB)
+      await replace([sourceEntry("b", "B2", "c")], await active())
+      await replace([sourceEntry("c", "C2")], await active())
+      expect(await object("a")).toEqual(initialA)
+      expect(await object("b")).toMatchObject({ properties: { name: "B2" } })
+      for (let pass = 0; pass < 20; pass++) {
+        const result = await storage.ontology.sources.cleanupTerminal({
+          projectId,
+          terminalBefore: "2100-01-01T00:00:00.000Z",
+          limit: 2,
+        })
+        if (result.rowsDeleted + result.materializationsDeleted === 0) break
+      }
+      const scoped = materializer.withScope(runtimeScope())
+      const edit = (operations: readonly OntologyEditOperation[]) =>
+        scoped.edits.commit({
+          mode: "atomic",
+          source: { kind: "runtime", requestId: `delta-edit-${++ordinal}` },
+          operations,
+          expectedObjects: [],
+          expectedLinks: [],
+          expectedLinkScopes: [],
+        })
+      await edit([
+        { id: "edit-a", kind: "object.upsert", ref: ref("a"), properties: { name: "Edited A" } },
+      ])
+      await edit([
+        { id: "reset-a", kind: "object.patch", ref: ref("a"), set: {}, unset: [], reset: ["name"] },
+      ])
+      expect(await object("a")).toMatchObject({ properties: { name: "A" } })
+      await replace([], await active())
+      expect(await object("a")).toMatchObject({ properties: { name: "A" } })
+      await expect(replace([remove("a")], stale)).rejects.toMatchObject({
+        kind: "source-materialization",
+      })
+      expect(await object("a")).not.toBeNull()
+      await replace([remove("a")], await active())
+      expect(await object("a")).toBeNull()
+      expect(await object("b")).toMatchObject({ properties: { name: "B2" } })
+      await replace([sourceEntry("b", "B3")])
+      expect(await object("b")).toMatchObject({ properties: { name: "B3" } })
+      expect(await object("c")).toBeNull()
+      await replace([], await active())
+      expect(await object("b")).toMatchObject({ properties: { name: "B3" } })
+      await replace([])
+      expect(await object("b")).toBeNull()
+
+      // A different run commits after base validation but before this candidate is sealed.
+      // Only checking the base before reading the delta would allow a stale publication here.
+      const base = await active()
+      const earlier = ++ordinal
+      const later = ++ordinal
+      await expect(
+        replace([sourceEntry("a", "Stale delta")], base, {
+          version: later,
+          beforeSeal: async () => {
+            await replace([sourceEntry("a", "Concurrent value")], base, { version: earlier })
+          },
+        })
+      ).rejects.toMatchObject({ kind: "source-materialization" })
+      expect(await object("a")).toMatchObject({ properties: { name: "Concurrent value" } })
+      await replace([sourceEntry("a", "Fresh delta")], await active())
+      expect(await object("a")).toMatchObject({ properties: { name: "Fresh delta" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+
   test(`${name} persists replacement, Action, and telemetry commits atomically`, async () => {
     const createdStorage = await provider.createStorage()
     const storage = requireContractStorage(createdStorage)
@@ -811,7 +982,7 @@ function sourceEntry(id: string, name: string, parentId?: string): ProjectionSou
   }
 }
 
-async function* entries(values: readonly ProjectionSourceEntry[]) {
+async function* entries(values: readonly (ProjectionSourceEntry | ProjectionSourceDeletion)[]) {
   for (const value of values) yield value
 }
 

package/src/testing/ontology-storage-contract.ts

@@ -383,6 +383,13 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             limit: 1,
           })
         ).toEqual({ rowsDeleted: 1, materializationsDeleted: 0 })
+        expect(
+          await storage.ontology.sources.cleanupTerminal({
+            projectId: "contract-project",
+            terminalBefore: "2026-02-01T00:00:00.000Z",
+            limit: 1,
+          })
+        ).toEqual({ rowsDeleted: 1, materializationsDeleted: 0 })
         expect(
           await storage.ontology.sources.cleanupTerminal({
             projectId: "contract-project",

package/src/testing/projection-run-storage-contract.ts

@@ -256,6 +256,40 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
       })
     })
 
+    test("persists independent incremental progress across reclaim without a physical-row floor", async () => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        await admitProjectionRun(context, replacementInput("delta-progress"))
+        const first = await storage.startOrReclaim(replacementInput("delta-progress"))
+        const updated = await storage.update({
+          ...executionInput(first),
+          progress: { sourceChangesRead: 12 },
+        })
+        expect(updated.progress).toEqual({
+          sourceRowsRead: 0,
+          sourceRowsSkipped: 0,
+          sourceChangesRead: 12,
+        })
+        const second = await storage.startOrReclaim(replacementInput("delta-progress"))
+        expect(second.run.progress).toEqual(updated.progress)
+        await expect(
+          storage.update({ ...executionInput(first), progress: { sourceChangesRead: 13 } })
+        ).rejects.toThrow()
+        await expect(
+          storage.update({ ...executionInput(second), progress: { sourceChangesRead: 11 } })
+        ).rejects.toThrow("must not decrease")
+        const fallback = await storage.update({
+          ...executionInput(second),
+          progress: { sourceRowsRead: 2 },
+        })
+        expect(fallback.progress).toEqual({
+          sourceRowsRead: 2,
+          sourceRowsSkipped: 0,
+          sourceChangesRead: 12,
+        })
+      })
+    })
+
     test("rejects immutable dataset-version metadata reuse", async () => {
       await withStorage(async (context) => {
         await admitProjectionRun(context, replacementInput("dataset-metadata-first"))

package/src/webhooks/connections.ts

@@ -0,0 +1,56 @@
+import { createConnectorCodedError } from "../connectors/errors"
+import { type ConnectorRuntime, getConnectorExecutionSourceResolver } from "../connectors/execution"
+import { type ConnectorDefinition, isOAuthConnectorDefinition } from "../connectors/types"
+import type { WebhookConnections } from "./types"
+
+/** Lookup stays inside the admitted execution's project and registered connector. */
+export function createWebhookConnections(
+  runtime: ConnectorRuntime,
+  definition: ConnectorDefinition
+): WebhookConnections {
+  return {
+    async forAccount(accountId) {
+      if (!isOAuthConnectorDefinition(definition)) {
+        throw createConnectorCodedError(
+          "connector.configuration_invalid",
+          "Webhook connections.forAccount() requires a managed OAuth connector."
+        )
+      }
+      if (typeof accountId !== "string" || !accountId.trim()) {
+        throw createConnectorCodedError(
+          "connector.configuration_invalid",
+          "Webhook account ID must be a non-empty string."
+        )
+      }
+      const resolver = getConnectorExecutionSourceResolver(runtime)
+      const sources = await resolver.list(definition)
+      return sources.flatMap((source) => {
+        const connection = source.connection
+        if (!connection || connection.account.id !== accountId) return []
+        const connectionId = connection.id
+        let clientPromise: Promise<unknown> | undefined
+        return [
+          {
+            connection,
+            client() {
+              clientPromise ??= (async () => {
+                const current = (await resolver.list(definition)).find(
+                  (candidate) =>
+                    candidate.connection?.id === connectionId &&
+                    candidate.connection.account.id === accountId
+                )
+                if (!current)
+                  throw createConnectorCodedError(
+                    "connector.not_found",
+                    "Webhook connection is no longer active for this account."
+                  )
+                return current.connect(new AbortController().signal)
+              })()
+              return clientPromise
+            },
+          },
+        ]
+      })
+    },
+  }
+}

package/src/webhooks/index.ts

@@ -9,6 +9,8 @@ export type {
   WebhookBodyFormat,
   WebhookBodyParser,
   WebhookBodySchema,
+  WebhookConnection,
+  WebhookConnections,
   WebhookDefinition,
   WebhookHandlerContext,
   WebhookHandlerResult,

package/src/webhooks/internal.ts

@@ -1,3 +1,5 @@
+export { isStaticConnectorDefinition } from "../connectors/types"
+export { createWebhookConnections } from "./connections"
 export {
   type AdmitWebhookRunInput,
   type AdmitWebhookRunResult,

package/src/webhooks/registry.ts

@@ -1,6 +1,6 @@
-import { type ConnectorDefinition, isStaticConnectorDefinition } from "../connectors/types"
+import type { ConnectorDefinition } from "../connectors/types"
 import { WebhookValidationError } from "./errors"
-import type { RegisteredWebhook, WebhookDefinition } from "./types"
+import type { RegisteredWebhook } from "./types"
 
 /** Read-only access to connector webhooks registered by a host. */
 export interface WebhookCatalog {
@@ -21,7 +21,6 @@ export class WebhookRegistry implements WebhookCatalog {
     const registered: RegisteredWebhook[] = []
 
     for (const connector of options.connectors) {
-      if (!isStaticConnectorDefinition(connector)) continue
       const webhooks = connector.adapter.webhooks ?? []
       if (!Array.isArray(webhooks)) {
         throw new WebhookValidationError(
@@ -82,7 +81,7 @@ export function webhookRoute(connectorId: string, webhookId: string): string {
 function assertValidWebhook(
   connectorId: string,
   webhook: unknown
-): asserts webhook is WebhookDefinition {
+): asserts webhook is RegisteredWebhook["webhook"] {
   if (!isRecord(webhook)) {
     throw new WebhookValidationError(`[Sixb] Connector '${connectorId}' has an invalid webhook.`)
   }

package/src/webhooks/types.ts

@@ -1,4 +1,4 @@
-import type { StaticConnectorDefinition } from "../connectors/types"
+import type { ConnectorConnectionMetadata, ConnectorDefinition } from "../connectors/types"
 import type { Logger } from "../logging"
 import type { OntologySource, Sixb } from "../runtime"
 
@@ -49,7 +49,7 @@ export interface WebhookMetadata {
 
 /** Pre-admission input. It intentionally has no execution SDK or run-scoped logger. */
 export interface WebhookVerifyContext {
-  readonly connector: StaticConnectorDefinition
+  readonly connector: ConnectorDefinition
   readonly webhook: WebhookMetadata
   readonly request: Request
   readonly rawBody: Uint8Array
@@ -60,7 +60,9 @@ export interface WebhookHandlerContext<TBody, TClient> extends WebhookVerifyCont
   readonly sixb: Sixb<readonly OntologySource[]>
   readonly logger: Logger
   readonly body: TBody
-  /** Lazily resolve the connector client only when the handler needs it. */
+  /** Resolve selected managed connections for an external account in this connector. */
+  readonly connections: WebhookConnections<TClient>
+  /** Resolve a static connector's client. For OAuth, use connections.forAccount(). */
   client(): Promise<TClient>
 }
 
@@ -93,9 +95,20 @@ export type WebhookHandlerResult = WebhookResponse | void
 export interface RegisteredWebhook<
   TBody = unknown,
   TClient = unknown,
-  TConnector extends StaticConnectorDefinition = StaticConnectorDefinition,
+  TConnector extends ConnectorDefinition = ConnectorDefinition,
 > {
   readonly connector: TConnector
   readonly webhook: WebhookDefinition<TBody, TClient>
   readonly route: string
 }
+
+export interface WebhookConnection<TClient = unknown> {
+  readonly connection: ConnectorConnectionMetadata
+  /** First call rechecks the connection and creates its client; later calls reuse that client. */
+  client(): Promise<TClient>
+}
+
+export interface WebhookConnections<TClient = unknown> {
+  /** Returns all matching selected connections; an unknown account returns an empty array. */
+  forAccount(accountId: string): Promise<readonly WebhookConnection<TClient>[]>
+}