@opencxh/domain 1.172.1 → 1.173.0

package/dist/platform/sync-source.d.ts

@@ -1,415 +1,395 @@
 /**
- * Data van buiten naar binnen halen, één keer geregeld.
+ * Pulling outside data in, settled once.
  *
- * Het platform ingest vandaag op vier onafhankelijke manieren — een cron-sync per provider-app,
- * webhooks, een event-driven verrijkingsjob en losse backfills — en elk van die vier herbouwt
- * zelfstandig dezelfde zes dingen: cursor, batching, locking, idempotentie, foutafhandeling en
- * observability. Dat is te zien: `cursorKey()` staat drie keer los in de repo,
- * `microsoft_sync_state` groeit per sub-sync een kolom, en een sync die stilvalt is een
- * `console.error` die niemand ziet.
+ * The platform ingests in four independent ways today — a cron sync per provider app, webhooks, an
+ * event-driven enrichment job and loose backfills — and each of the four rebuilds the same six
+ * things: cursor, batching, locking, idempotency, error handling and observability. It shows:
+ * `cursorKey()` sits in the repo three times, `microsoft_sync_state` grows a column per sub-sync,
+ * and a sync that stalls is a `console.error` nobody sees.
  *
- * De splitsing die dat oplost is de industriestandaard (Singer/Airbyte, Nango, Fivetran): **een
- * smal bron-contract met een dikke generieke runtime.** De bron weet hoe je één pagina uit
- * Microsoft Graph of Asana haalt; de runtime weet hoe je cursors checkpoint, batches
- * doorschakelt, backoff doet en er een run-log van bijhoudt. Dit bestand is dat smalle contract.
+ * The split that fixes that is the industry standard (Singer/Airbyte, Nango, Fivetran): **a narrow
+ * source contract with a thick generic runtime.** The source knows how to fetch one page from
+ * Microsoft Graph or Asana; the runtime knows how to checkpoint cursors, chain batches, back off
+ * and keep a run log. This file is that narrow contract.
  *
- * Drie endpoints, in de vorm van `memory-source` en `analytics-source` — dus een providerrol en
- * geen servicebus-sleutel, want dit draait server-side zonder gebruiker erbij:
+ * Three endpoints, shaped like `memory-source` and `analytics-source` — so a provider role and not
+ * a service-bus key, because this runs server-side with no user present:
  *
- * | Rol | Endpoint | Antwoord |
+ * | Role | Endpoint | Answer |
  * |---|---|---|
  * | `sync-source` | `GET /provider/sync/describe` | {@link SyncSourceDescribe} |
  * | `sync-source` | `POST /provider/sync/pull` | {@link SyncPullResponse} |
  * | `sync-target` | `POST /provider/sync/land` | {@link SyncLandResponse} |
  *
- * Bron en doel zijn **losse rollen**: `apps/microsoft` levert records en landt niets,
- * `apps/work` landt records en levert niets. Een app mag beide zijn, maar hoeft dat niet.
+ * Source and target are **separate roles**: `apps/microsoft` delivers records and lands none,
+ * `apps/work` lands records and delivers none. An app may be both, but need not be.
  */
-/** De providerrol-groepen, als constante zodat een typefout niet stil een lege lijst oplevert. */
+/** The provider role groups, as constants so a typo does not silently yield an empty list. */
 export declare const SYNC_SOURCE_PROVIDER_GROUP = "sync-source";
 export declare const SYNC_TARGET_PROVIDER_GROUP = "sync-target";
 /**
- * Continu of eenmalig — en dat is een echt verschil, geen label.
+ * Continuous or one-off — a real difference, not a label.
  *
- * `continuous` draait op een tik en moet dus goedkoop kunnen niksdoen (een cursor die zegt
- * "niets nieuws"). `once` wordt door een mens gestart, mag duur zijn, en moet **uitputtend**
- * zijn: een migratie die 95% ophaalt is geen migratie. Die eis is precies waarom niet elke bron
- * beide kan — zie {@link SyncSourceDefinition.transport}.
+ * `continuous` runs on a tick and so has to be able to do nothing cheaply (a cursor saying
+ * "nothing new"). `once` is started by a person, may be expensive, and has to be **exhaustive**: a
+ * migration that fetches 95% is not a migration. That requirement is exactly why not every source
+ * can do both — see {@link SyncSourceDefinition.transport}.
  */
 export type SyncMode = "continuous" | "once";
 /**
- * Hoe de records feitelijk binnenkomen.
+ * How the records actually arrive.
  *
- * Dit staat in het contract omdat het de verwachtingen bepaalt die de runtime en de UI mogen
- * hebben, niet als documentatie:
+ * This sits in the contract because it sets the expectations the runtime and the UI may have, not
+ * as documentation:
  *
- * - **`native`** — de app praat zelf met de API van de leverancier. Kent delta-tokens en
- *   pagination, dus geschikt voor `continuous` én `once`.
- * - **`tool`** — de app gaat via de AI-tool/MCP-laag. Prima voor de lange staart aan systemen
- *   waarvoor een eigen connector niet loont, maar een MCP-zoektool antwoordt "top-N relevant"
- *   en niet "alles sinds X", en het protocol kent geen change-token. Een `tool`-bron die
- *   `once` claimt belooft volledigheid die hij niet kan leveren.
- * - **`file`** — een geüpload bestand (CSV). Per definitie `once`, en per definitie volledig.
+ * - **`native`** — the app talks to the vendor's API itself. Knows delta tokens and pagination,
+ *   so suitable for `continuous` as well as `once`.
+ * - **`tool`** — the app goes through the AI tool/MCP layer. Fine for the long tail of systems
+ *   where a dedicated connector does not pay off, but an MCP search tool answers "top-N relevant"
+ *   and not "everything since X", and the protocol has no change token. A `tool` source claiming
+ *   `once` promises completeness it cannot deliver.
+ * - **`file`** — an uploaded file (CSV). `once` by definition, and complete by definition.
  */
 export type SyncTransport = "native" | "tool" | "file";
-/** Eén ding dat een app van buiten kan halen. */
 /**
- * Eén instelling van een koppeling, zoals de bron hem declareert.
+ * One setting of a connection, as the source declares it.
  *
- * Bewust geen ui-kit-types hier: `packages/domain` heeft geen UI-afhankelijkheden, en het
- * formulier mapt deze declaratie zelf op zijn eigen velden.
+ * Deliberately no ui-kit types here: `packages/domain` has no UI dependencies, and the form maps
+ * this declaration onto its own fields itself.
  */
 export interface SyncSettingsField {
-    /** Sleutel in het settings-object dat de bron bij `pull` terugkrijgt. */
+    /** Key in the settings object the source gets back on `pull`. */
     key: string;
     label: string;
     type: "text" | "number" | "boolean" | "select";
     required?: boolean;
-    /** Alleen bij `type: "select"`. */
+    /** Only with `type: "select"`. */
     options?: {
         value: string;
         label: string;
     }[];
-    /** Uitleg onder het veld. Voor "leeg = ..."-gevallen, die anders raadwerk zijn. */
+    /** Explanation under the field. For "empty = ..." cases, which are guesswork otherwise. */
     help?: string;
     /**
-     * Hint dat deze waarde een resource in een andere app aanwijst (`"work_project"`).
+     * Hint that this value points at a resource in another app (`"work_project"`).
      *
-     * Vandaag rendert het formulier hem als tekstveld; de hint staat er zodat een picker later
-     * toegevoegd kan worden zonder dat de bron verandert. Een hint en geen belofte.
+     * Today the form renders it as a text field; the hint is here so a picker can be added later
+     * without the source changing. A hint, not a promise.
      */
     resource?: string;
 }
 export interface SyncSourceDefinition {
     /**
-     * Stabiel en app-genamespaced: `microsoft.todo`, `asana.tasks`, `csv.contacts`.
+     * Stable and app-namespaced: `microsoft.todo`, `asana.tasks`, `csv.contacts`.
      *
-     * Dit is een **opgeslagen verwijzing** — `SyncConnection.sourceId` bewaart hem — dus
-     * hernoemen breekt bestaande koppelingen. Punt als scheidingsteken, zoals `MemoryKindId`
-     * voor app-eigen kinds.
+     * A **stored reference** — `SyncConnection.sourceId` keeps it — so renaming breaks existing
+     * connections. Dot as separator, like `MemoryKindId` for app-owned kinds.
      */
     id: string;
     label: string;
     description?: string;
     /**
-     * De scope-soorten die deze bron landt: `work_item`, `interaction`, `company`, `contact`.
+     * The scope kinds this source lands: `work_item`, `interaction`, `company`, `contact`.
      *
-     * Hetzelfde vocabulaire als `ScopeDescribe.kinds`, en dat is geen cosmetische keuze — de
-     * runtime routeert een record naar de bezittende app met `findScopeOwner(kind)`. Een soort
-     * die geen scope-eigenaar heeft, kan dus niet geland worden, en dat merk je bij het
-     * registreren in plaats van halverwege een run.
+     * The same vocabulary as `ScopeDescribe.kinds`, and not a cosmetic choice — the runtime routes a
+     * record to the owning app with `findScopeOwner(kind)`. A kind without a scope owner cannot be
+     * landed, and you notice that while registering instead of halfway a run.
      */
     kinds: string[];
-    /** Welke modi deze bron ondersteunt. Leeg is zinloos; minstens één. */
+    /** Which modes this source supports. Empty is pointless; at least one. */
     modes: SyncMode[];
     transport: SyncTransport;
     /**
-     * De `providerId` van de {@link ManagedAccount} die deze bron nodig heeft.
+     * The `providerId` of the {@link ManagedAccount} this source needs.
      *
-     * Afwezig = geen credential nodig (een bestand-upload). Aanwezig betekent dat een koppeling
-     * niet werkt zonder gekozen account, en dat de UI dat vóór de eerste run kan zeggen in
-     * plaats van een mislukte run te laten zien.
+     * Absent = no credential needed (a file upload). Present means a connection does not work
+     * without a chosen account, and the UI can say so before the first run instead of showing a
+     * failed one.
      */
     accountProviderId?: string;
     /**
-     * Instellingen die per koppeling verschillen en dus niet in code horen.
+     * Settings that differ per connection and therefore do not belong in code.
      *
-     * Declaratief, zodat een connector-app **geen frontend nodig heeft** om configureerbaar te
-     * zijn: het Koppelingen-formulier rendert deze velden. Dat is wat `apps/asana` (nul
-     * frontend-bestanden) mogelijk houdt.
+     * Declarative, so a connector app needs **no frontend** to be configurable: the Connections form
+     * renders these fields. That is what keeps `apps/asana` (zero frontend files) possible.
      *
-     * Plat gehouden met opzet. Een genest schema zou een mapping-DSL worden, en die is eerder
-     * afgewezen: datumformaten en enums verschillen per bron, en fouten verschuiven dan van `tsc`
-     * naar runtime.
+     * Kept flat on purpose. A nested schema would turn into a mapping DSL, which was rejected
+     * earlier: date formats and enums differ per source, and errors then move from `tsc` to runtime.
      */
     settingsSchema?: SyncSettingsField[];
     /**
-     * Alleen bij `transport: "tool"`: de catalogus-sleutel waarop de connector-picker
-     * voorfiltert (`"asana"`, `"linear"`).
+     * Only with `transport: "tool"`: the catalog key the connector picker pre-filters on
+     * (`"asana"`, `"linear"`).
      *
-     * Een **hint**, geen resolutie: hij bepaalt welke van de MCP-verbindingen van de
-     * organisatie als kandidaat worden voorgesteld. Wat de koppeling daarna bewaart is het
-     * connector-**id** ({@link SyncConnection.connectorId}). Zonder hint krijgt de gebruiker
-     * simpelweg de volledige lijst.
+     * A **hint**, not a resolution: it decides which of the organisation's MCP connections are
+     * offered as candidates. What the connection stores afterwards is the connector **id**
+     * ({@link SyncConnection.connectorId}). Without a hint the user simply gets the full list.
      */
     connectorHint?: string;
     /**
-     * Alleen bij `transport: "tool"`: deze bron kan alleen draaien op een gedeeld
-     * organisatie-credential.
+     * Only with `transport: "tool"`: this source can only run on a shared organisation credential.
      *
-     * Waarom dit bestaat: een onbemande ronde (cron, sync) heeft geen handelende gebruiker, dus
-     * een connector met `credentialScope: "per-user"` levert daar per definitie nul tools — en dat
-     * zag je vroeger alleen als "de sync doet niets". Met deze vlag weigert het opslaan van een
-     * `continuous`-koppeling meteen, met een uitleg.
+     * Why this exists: an unattended round (cron, sync) has no acting user, so a connector with
+     * `credentialScope: "per-user"` yields zero tools there by definition — which used to show up
+     * only as "the sync does nothing". With this flag, saving a `continuous` connection is refused
+     * right away, with an explanation.
      *
-     * Alleen voor `continuous`: een `once`-koppeling start een mens, en dan is er wél een
-     * handelende gebruiker wiens token gebruikt kan worden.
+     * Only for `continuous`: a `once` connection is started by a person, and then there *is* an
+     * acting user whose token can be used.
      */
     requiresCredentialScope?: "shared";
     /**
-     * Aanbevolen minimale tijd tussen twee rondes, in ms. De organisatie mag hem overschrijven.
+     * Recommended minimum time between two rounds, in ms. The organisation may override it.
      *
-     * Een **interval** en geen cron-expressie, omdat dat is wat er daadwerkelijk uitvoerbaar is:
-     * `JobOptions.schedule` staat vast bij registratie, dus een cron-string per koppeling zou
-     * nooit geëvalueerd worden — een veld dat belooft wat het niet doet. De runtime tikt op een
-     * grof raster en poort daarop.
+     * An **interval** and not a cron expression, because that is what is actually executable:
+     * `JobOptions.schedule` is fixed at registration, so a per-connection cron string would never be
+     * evaluated — a field promising what it does not do. The runtime ticks on a coarse grid and
+     * gates on this.
      *
-     * Bij de bron en niet in de runtime, omdat alleen de bron weet wat zijn API verdraagt: een
-     * delta-feed mag elke minuut, een lijst-endpoint dat elke keer alles teruggeeft niet.
+     * On the source and not in the runtime, because only the source knows what its API tolerates: a
+     * delta feed may run every minute, a list endpoint returning everything every time may not.
      */
     defaultIntervalMs?: number;
     /**
-     * Hoe vaak de bron zijn cursor moet negeren en alles opnieuw lezen (ms).
+     * How often the source should ignore its cursor and read everything again (ms).
      *
-     * De reconcile-sweep uit het Stripe/Shopify-patroon, en in deze codebase al bewezen als
-     * `CHAT_FULL_SWEEP_INTERVAL_MS`: cursors rusten op de aanname dat de leverancier een
-     * `updatedAt` bumpt voor alles wat telt, en dat houdt voor nieuwe records maar is
-     * onbetrouwbaar voor edits en verwijderingen. Afwezig = nooit vegen (juist voor een
-     * delta-feed die verwijderingen zelf meldt).
+     * The reconcile sweep from the Stripe/Shopify pattern, already proven in this codebase as
+     * `CHAT_FULL_SWEEP_INTERVAL_MS`: cursors rest on the assumption that the vendor bumps an
+     * `updatedAt` for everything that counts, which holds for new records but is unreliable for
+     * edits and deletions. Absent = never sweep (right for a delta feed that reports deletions).
      */
     fullSweepIntervalMs?: number;
 }
 /**
- * Bare payload van `GET /provider/sync/describe` — **niet** in `ResponseFactory` verpakt
- * (mal: {@link MemorySourceDescription} en `AnalyticsSourceDescription`).
+ * Bare payload of `GET /provider/sync/describe` — **not** wrapped in `ResponseFactory` (template:
+ * {@link MemorySourceDescription} and `AnalyticsSourceDescription`).
  */
 export interface SyncSourceDescribe {
-    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    /** The declaring app (== `manifest.name` == `req.source.app`). */
     source: string;
     sources: SyncSourceDefinition[];
 }
 /**
- * Eén record uit een bronsysteem, klaar om geland te worden.
+ * One record from a source system, ready to be landed.
  *
- * De bron doet de mapping naar de vorm die de doel-app verwacht. Dat is bewust: de runtime kent
- * geen enkel veld van geen enkele leverancier, en zodra hij dat wél zou doen is hij niet meer
- * generiek. Zie {@link SyncRecord.data}.
+ * The source does the mapping into the shape the target app expects. Deliberately so: the runtime
+ * knows no field of any vendor, and the moment it did it would stop being generic. See
+ * {@link SyncRecord.data}.
  */
 export interface SyncRecord {
     /**
-     * Het stabiele id in het bronsysteem, genamespaced door de bron zelf
-     * (`asana_task:12345`, `graph-todo:AAMk…`).
+     * The stable id in the source system, namespaced by the source itself (`asana_task:12345`,
+     * `graph-todo:AAMk…`).
      *
-     * Dit is de dedupe-as: de doel-app upsert hierop via zijn
-     * `upsert_by_external_provider_id`-route, dus dezelfde run twee keer draaien schrijft één
-     * rij. "Stabiel" is de hele eis — een id dat per pagina verandert maakt van elke sync een
-     * duplicaat-fabriek.
+     * This is the dedupe axis: the target app upserts on it through its
+     * `upsert_by_external_provider_id` route, so running the same run twice writes one row.
+     * "Stable" is the whole requirement — an id that changes per page turns every sync into a
+     * duplicate factory.
      */
     externalId: string;
     /**
-     * Ids die de **container** aanwijzen en niet deze rij: de lijst, het project, het board.
+     * Ids pointing at the **container** and not at this row: the list, the project, the board.
      *
-     * Ze worden wél bewaard (uitgaande dispatch heeft ze nodig) maar mogen nooit meedoen in de
-     * dedupe. Dit veld bestaat omdat het al één keer fout is gegaan: Microsoft Graph stuurt
-     * naast het taak-id ook `graph-todolist:<id>`, dat voor élke taak in die lijst hetzelfde is,
-     * en zoeken daarop klapte de hele lijst op één rij (`task/external-ids.ts`). Daar is het
-     * met een prefix-lijst gerepareerd; hier zegt de bron het zelf, zodat die lijst niet hoeft
-     * te groeien.
+     * They are stored (outgoing dispatch needs them) but must never take part in the dedupe. This
+     * field exists because it went wrong once: next to the task id Microsoft Graph also sends
+     * `graph-todolist:<id>`, identical for every task in that list, and searching on it collapsed
+     * the whole list onto one row (`task/external-ids.ts`). Repaired there with a prefix list; here
+     * the source says it itself, so that list does not have to grow.
      */
     containerExternalIds?: string[];
-    /** De scope-soort, uit {@link SyncSourceDefinition.kinds}. Bepaalt naar welke app dit gaat. */
+    /** The scope kind, from {@link SyncSourceDefinition.kinds}. Decides which app this goes to. */
     kind: string;
     /**
-     * De velden voor de doel-app.
+     * The fields for the target app.
      *
-     * **Vaste veldnamen, nooit een map met een extern id als sleutel.**
-     *
-     * Hier stond de sleutel-mangeling van de SDK-client als reden. Die gold voor dit veld
-     * **nooit**: een `SyncRecord` reist van bron-app naar doel-app over `Bridge.rpc` en komt nooit
-     * bij een browser langs. (En sinds 17-08-2026 mangelt de client helemaal niets meer.)
-     *
-     * De regel blijft, om de reden die er werkelijk is: de doel-app moet de velden kunnen *typen*.
-     * `{ "asana_gid_123": {...} }` is voor `upsertWorkItemFromExternal` niet te lezen zonder eerst
-     * te weten wat de bron erin stopte, en dan verschuift elke fout van `tsc` naar runtime.
+     * **Fixed field names, never a map keyed by an external id.** The target app has to be able to
+     * *type* the fields: `{ "asana_gid_123": {...} }` cannot be read by `upsertWorkItemFromExternal`
+     * without first knowing what the source put in there, and then every error moves from `tsc` to
+     * runtime.
      */
     data: Record<string, unknown>;
     /**
-     * Dit record is bij de bron verwijderd.
+     * This record was deleted at the source.
      *
-     * Alleen zinvol als de bron dat kán weten: een delta-feed meldt verwijderingen, een
-     * lijst-endpoint laat ze simpelweg weg. Afwezigheid uit een lijst is géén verwijdering —
-     * dat verschil niet respecteren betekent dat een gefilterde of gepagineerde respons je
-     * halve administratie opruimt.
+     * Only meaningful when the source *can* know: a delta feed reports deletions, a list endpoint
+     * simply leaves them out. Absence from a list is **not** a deletion — not respecting that
+     * difference means a filtered or paginated response clears out half your administration.
      */
     deleted?: boolean;
 }
-/** `POST /provider/sync/pull` — haal één pagina op. */
+/** `POST /provider/sync/pull` — fetch one page. */
 export interface SyncPullRequest {
     sourceId: string;
-    /** Zodat de bron kan loggen en zijn eigen per-koppeling state kan vinden als hij die heeft. */
+    /** So the source can log and find its own per-connection state, if it has any. */
     connectionId: string;
-    /** De {@link ManagedAccount} om mee te praten. Afwezig bij `transport: "file"`. */
+    /** The {@link ManagedAccount} to talk with. Absent with `transport: "file"`. */
     accountId?: string;
     /**
-     * Bij `transport: "tool"`: het id van de MCP-connector die deze koppeling mag gebruiken,
-     * gekozen tóen de koppeling werd geconfigureerd.
+     * With `transport: "tool"`: the id of the MCP connector this connection may use, chosen when the
+     * connection was configured.
      *
-     * Hiermee is de toolnaam een pure string — `mcpToolPrefix(connectorId) + toolnaam` — en is
-     * er per pagina géén resolutie-RPC nodig. Eerder zocht een bron zijn connector op
-     * catalogus-sleutel op, en dat kon bij twee kandidaten (een org-rij naast een persoonlijke,
-     * of twee gebruikers met elk hun eigen) geen winnaar kiezen; een app kon zelfs het prefix
-     * van iemands persoonlijke connector krijgen.
+     * This makes the tool name a pure string — `mcpToolPrefix(connectorId) + tool name` — with no
+     * resolution RPC per page. A source used to look its connector up by catalog key, which could
+     * not pick a winner with two candidates (an org row next to a personal one, or two users each
+     * with their own); an app could even end up with the prefix of somebody's personal connector.
      */
     connectorId?: string;
     /**
-     * De instellingen van deze koppeling, volgens {@link SyncSourceDefinition.settingsSchema}.
+     * The settings of this connection, per {@link SyncSourceDefinition.settingsSchema}.
      *
-     * Een **object** hier en een JSON-string in de opslag. Let op: dat is NIET omdat de
-     * SDK-client uitgaande sleutels zou mangelen — dat doet hij niet, de verzendkant is
-     * `removeUndefined` + `JSON.stringify`. Alleen *antwoorden* worden gecamelCase't. De string in
-     * de opslag is er om dezelfde reden als de cursor: één schemaveld dat elke vorm moet kunnen
-     * dragen.
+     * An **object** here and a JSON string in storage — for the same reason as the cursor: one
+     * schema field that has to be able to carry any shape. Not because of key mangling; the client
+     * does not transform outgoing keys.
      */
     settings?: Record<string, unknown>;
     /**
-     * Opaak, exact zoals de bron hem vorige keer teruggaf. `undefined` = vanaf het begin.
+     * Opaque, exactly as the source returned it last time. `undefined` = from the start.
      *
-     * **De runtime kijkt er nooit in.** Een Graph `deltaLink`, een tijdstempel, een
-     * pagina-token — het maakt niet uit, en juist daarom hoeft er geen kolom per sub-sync te
-     * bestaan. Dat `microsoft_sync_state` vandaag `todoDeltaLink` náást `chatCursors` náást
-     * `chatFullSweepAt` heeft, is precies wat een opaak veld voorkomt.
+     * **The runtime never looks inside.** A Graph `deltaLink`, a timestamp, a page token — it does
+     * not matter, and that is precisely why no column per sub-sync has to exist. That
+     * `microsoft_sync_state` today carries `todoDeltaLink` next to `chatCursors` next to
+     * `chatFullSweepAt` is exactly what an opaque field prevents.
      */
     cursor?: unknown;
-    /** Negeer de cursor en lees alles opnieuw — de reconcile-sweep. */
+    /** Ignore the cursor and read everything again — the reconcile sweep. */
     fullSweep?: boolean;
-    /** Maximum aantal records in dit antwoord. De bron mag minder geven, nooit meer. */
+    /** Maximum number of records in this answer. The source may give fewer, never more. */
     limit: number;
 }
-/** Antwoord op `POST /provider/sync/pull`. Wél in `ResponseFactory` verpakt. */
+/** Answer to `POST /provider/sync/pull`. This one *is* wrapped in `ResponseFactory`. */
 export interface SyncPullResponse {
     records: SyncRecord[];
     /**
-     * De cursor ná deze pagina. De runtime bewaart hem **pas nadat de records geland zijn**.
+     * The cursor after this page. The runtime stores it **only once the records have landed**.
      *
-     * Dat is de Singer/Airbyte-regel en de reden dat crash-herstel werkt: valt de boel om
-     * tussen pull en land, dan wordt de batch herhaald (idempotent, want upsert op
-     * `externalId`) in plaats van overgeslagen. Andersom — cursor eerst — verlies je records
-     * stil, en stil is hier het probleem.
+     * That is the Singer/Airbyte rule and the reason crash recovery works: if things fall over
+     * between pull and land, the batch is repeated (idempotent, because upsert on `externalId`)
+     * instead of skipped. The other way round — cursor first — loses records silently, and silent is
+     * the problem here.
      */
     cursor?: unknown;
-    /** Geen data meer na deze pagina. De runtime schakelt dan niet door. */
+    /** No more data after this page. The runtime then does not chain on. */
     done: boolean;
     /**
-     * De bron is gerate-limit; wacht minstens zo lang voor de volgende poging.
+     * The source is rate-limited; wait at least this long before the next attempt.
      *
-     * In milliseconden, zoals elke andere duur in dit platform. Een bron die dit vult in
-     * plaats van te gooien, houdt de run `partial` in plaats van `failed` — het is uitstel,
-     * geen fout.
+     * In milliseconds, like every other duration in this platform. A source that fills this in
+     * instead of throwing keeps the run `partial` rather than `failed` — it is a delay, not an
+     * error.
      */
     retryAfterMs?: number;
 }
-/** `POST /provider/sync/land` — schrijf deze records weg. Alleen app-callers. */
+/** `POST /provider/sync/land` — write these records. App callers only. */
 export interface SyncLandRequest {
-    /** Waar ze vandaan komen, voor `source`/attributie op de gelande rij. */
+    /** Where they came from, for `source`/attribution on the landed row. */
     sourceId: string;
     records: SyncRecord[];
 }
-/** Wat er met één record gebeurde. */
+/** What happened to one record. */
 export interface SyncLandOutcome {
     externalId: string;
     /**
-     * `created` en `updated` zijn beide "geschreven"; `unchanged` bestaat apart omdat een
-     * idempotente resync die niets veranderde géén SSE-ruis mag maken en niet als werk mag
-     * tellen (het patroon uit `lib/upsert-dedup.ts`). `failed` is één rij, niet de batch.
+     * `created` and `updated` are both "written"; `unchanged` exists separately because an
+     * idempotent resync that changed nothing must not make SSE noise and must not count as work
+     * (the pattern from `lib/upsert-dedup.ts`). `failed` is one row, not the batch.
      */
     result: "created" | "updated" | "unchanged" | "deleted" | "failed";
-    /** De scopeKey van de gelande rij, zodat de run-log naar het resultaat kan linken. */
+    /** The scopeKey of the landed row, so the run log can link to the result. */
     scopeKey?: string;
-    /** Alleen bij `failed`. Kort genoeg voor een tabelregel. */
+    /** Only on `failed`. Short enough for a table row. */
     error?: string;
 }
-/** Antwoord op `POST /provider/sync/land`. Wél in `ResponseFactory` verpakt. */
+/** Answer to `POST /provider/sync/land`. This one *is* wrapped in `ResponseFactory`. */
 export interface SyncLandResponse {
     outcomes: SyncLandOutcome[];
 }
 /**
- * Bare payload van `GET /provider/sync/land-describe`: welke soorten deze app kan landen.
+ * Bare payload of `GET /provider/sync/land-describe`: which kinds this app can land.
  *
- * Apart van `ScopeDescribe`, ook al overlappen de soorten meestal: een app kan een soort
- * autoriseren zonder er een ingest-route voor te hebben. Dat verschil zichtbaar maken is
- * goedkoper dan een run die halverwege een 404 vindt.
+ * Separate from `ScopeDescribe`, even though the kinds usually overlap: an app can authorize a
+ * kind without having an ingest route for it. Making that difference visible is cheaper than a run
+ * that finds a 404 halfway.
  */
 export interface SyncTargetDescribe {
     source: string;
     kinds: string[];
 }
-/** Hoe gezond een koppeling is. Wat de lijst als badge toont. */
+/** How healthy a connection is. What the list shows as a badge. */
 export type SyncHealth = 
-/** Laatste run geslaagd. */
+/** Last run succeeded. */
 "ok"
-/** Laatste run deels geslaagd, of gerate-limit. Loopt nog, maar niet schoon. */
+/** Last run partly succeeded, or was rate-limited. Still running, but not cleanly. */
  | "degraded"
-/** Laatste run gefaald — meestal een verlopen credential. Vraagt een mens. */
+/** Last run failed — usually an expired credential. Needs a person. */
  | "broken"
-/** Nooit gedraaid, of een verplicht account ontbreekt. Nog geen fout. */
+/** Never ran, or a required account is missing. Not an error yet. */
  | "unconfigured";
 /**
- * Eén geconfigureerde koppeling: deze bron, met dit account, in deze organisatie.
+ * One configured connection: this source, with this account, in this organisation.
  *
- * De credential zit hier **niet** in — `accountId` verwijst naar de canonieke
- * {@link ManagedAccount}-store. Een tweede plek waar tokens leven is een tweede plek waar ze
- * verlopen zonder dat iemand het weet.
+ * The credential is **not** in here — `accountId` points at the canonical
+ * {@link ManagedAccount} store. A second place where tokens live is a second place where they
+ * expire without anyone knowing.
  */
 export interface SyncConnection {
     id: string;
     organizationId: string;
     /** → {@link SyncSourceDefinition.id} */
     sourceId: string;
-    /** → {@link ManagedAccount.id}. Afwezig bij een bron zonder credential. */
+    /** → {@link ManagedAccount.id}. Absent for a source without a credential. */
     accountId?: string;
     /**
-     * Bij `transport: "tool"`: de gekozen MCP-connector. Expliciet, niet run-time geraden —
-     * zo is in de UI te zien welke verbinding deze koppeling gebruikt, en verandert het antwoord
-     * niet doordat iemand anders dezelfde catalogus-entry toevoegt.
+     * With `transport: "tool"`: the chosen MCP connector. Explicit, not guessed at run time — so the
+     * UI shows which connection this one uses, and the answer does not change because somebody else
+     * adds the same catalog entry.
      *
-     * Is de rij weg of uitgezet, dan gaat de koppeling naar `health: "unconfigured"` en faalt de
-     * run luid — nooit een stille lege pagina waarop de cursor doorschuift.
+     * If the row is gone or disabled, the connection goes to `health: "unconfigured"` and the run
+     * fails loudly — never a silent empty page the cursor advances over.
      */
     connectorId?: string;
     /**
-     * De ingevulde instellingen, geparsed. In de opslag staat hij als JSON-string, om dezelfde
-     * reden als de cursor: één schemaveld dat elke vorm moet kunnen dragen. **Niet** vanwege
-     * sleutel-mangeling — de client transformeert uitgaande sleutels niet.
+     * The filled-in settings, parsed. In storage it is a JSON string, for the same reason as the
+     * cursor: one schema field that has to be able to carry any shape.
      */
     settings?: Record<string, unknown>;
-    /** Vrije naam; afwezig = het label van de bron. */
+    /** Free-form name; absent = the source's label. */
     label?: string;
     mode: SyncMode;
     enabled: boolean;
     /**
-     * Minimale tijd tussen twee rondes, in ms.
+     * Minimum time between two rounds, in ms.
      *
-     * Bij het aanmaken gekopieerd uit {@link SyncSourceDefinition.defaultIntervalMs}, zodat de
-     * tik hem kan lezen zonder per koppeling de bron-catalogus te bevragen — en zodat het
-     * effectieve interval te zien en te wijzigen is in plaats van ergens in code te zitten.
+     * Copied from {@link SyncSourceDefinition.defaultIntervalMs} on creation, so the tick can read
+     * it without querying the source catalog per connection — and so the effective interval is
+     * visible and changeable instead of buried in code.
      */
     intervalMs?: number;
-    /** Opaak, van de bron. Zie {@link SyncPullRequest.cursor}. */
+    /** Opaque, from the source. See {@link SyncPullRequest.cursor}. */
     cursor?: unknown;
-    /** Epoch ms van de laatste volledige veegronde. */
+    /** Epoch ms of the last full sweep. */
     lastFullSweepAt?: number;
     health: SyncHealth;
     lastRunAt?: number;
-    /** De fout van de laatste gefaalde run, zodat de lijst hem kan tonen zonder een run te lezen. */
+    /** The error of the last failed run, so the list can show it without reading a run. */
     lastError?: string;
     createdBy?: string;
     createdAt?: number;
     updatedAt?: number;
 }
-/** Waardoor een run begon. */
+/** What started a run. */
 export type SyncRunTrigger = "cron" | "manual" | "webhook";
 /**
- * `partial` bestaat naast `done` en `failed` omdat "12 van de 500 rijen deden het niet" geen
- * van beide is: de koppeling werkt, de cursor mag opschuiven, en er is toch iets om te melden.
- * Zonder die derde staat wordt het óf een fout die de sync stilzet óf een succes dat de fouten
- * verzwijgt.
+ * `partial` exists next to `done` and `failed` because "12 of the 500 rows did not make it" is
+ * neither: the connection works, the cursor may advance, and there is still something to report.
+ * Without that third state it becomes either an error that halts the sync or a success that hides
+ * the failures.
  */
 export type SyncRunStatus = "running" | "done" | "partial" | "failed";
 /**
- * Wat er tijdens één ronde gebeurde.
+ * What happened during one round.
  *
- * Bewust dezelfde vorm als `PlaybookRun`: het is dezelfde vraag ("wat deed het systeem
- * ongevraagd, en ging het goed?"), dus dezelfde velden en dezelfde schermen.
+ * Deliberately the same shape as `PlaybookRun`: it is the same question ("what did the system do
+ * unasked, and did it go well?"), so the same fields and the same screens.
  */
 export interface SyncRun {
     id: string;
@@ -420,28 +400,28 @@ export interface SyncRun {
     status: SyncRunStatus;
     startedAt: number;
     finishedAt?: number;
-    /** Hoeveel pagina's deze run gelezen heeft. Verraadt een bron die niet opschiet. */
+    /** How many pages this run read. Gives away a source that is not making progress. */
     pages: number;
     scanned: number;
-    /** `created` + `updated`. Expliciet niet `unchanged`, anders lijkt een lege resync werk. */
+    /** `created` + `updated`. Explicitly not `unchanged`, or an empty resync looks like work. */
     written: number;
-    /** `unchanged` — de gezonde uitkomst van een idempotente resync. */
+    /** `unchanged` — the healthy outcome of an idempotent resync. */
     skipped: number;
     failed: number;
-    /** Was dit een veegronde? Verklaart waarom `scanned` ineens veel hoger is. */
+    /** Was this a sweep? Explains why `scanned` is suddenly much higher. */
     fullSweep?: boolean;
-    /** De fout die de hele run stopte. Bij `partial` leeg — die staan in {@link SyncRun.errors}. */
+    /** The error that stopped the whole run. Empty on `partial` — see {@link SyncRun.errors}. */
     error?: string;
     /**
-     * De eerste N mislukte rijen, met hun `externalId`.
+     * The first N failed rows, with their `externalId`.
      *
-     * Begrensd en niet volledig: een bron waarvan élke rij faalt zou anders een run-rij van
-     * megabytes opleveren. Het doel is debuggen ("welke rij, en waarom"), niet boekhouden.
+     * Bounded and not complete: a source where every row fails would otherwise produce a run row of
+     * megabytes. The goal is debugging ("which row, and why"), not bookkeeping.
      */
     errors?: {
         externalId: string;
         message: string;
     }[];
 }
-/** Hoeveel mislukte rijen een {@link SyncRun} onthoudt. */
+/** How many failed rows a {@link SyncRun} remembers. */
 export declare const SYNC_RUN_MAX_ERRORS = 20;