@opencxh/domain 1.171.0 → 1.172.2

package/dist/platform/account.d.ts

@@ -1,34 +1,30 @@
 /**
- * Laag 1 van de integratielagen: **Account** — het credential.
+ * Layer 1 of the integration layers: **Account** — the credential.
  *
- * Vier lagen, en dit is de onderste:
- * | Laag | Vraag | Woord |
+ * Four layers, and this is the bottom one:
+ * | Layer | Question | Word |
  * |---|---|---|
- * | 1 Credential | mag ik erin? | **Account** (`ManagedAccount`) |
- * | 2 Connector | waar is het, welk protocol? | **Connector** (`McpServerEntity`) |
- * | 3 Capability | wat kan ik ermee? | **Source** (`sync-source`, `memory-source`, …) |
- * | 4 Usage | staat het aan, met welke instellingen? | **Connection** (`SyncConnection`, `Channel`) |
+ * | 1 Credential | may I get in? | **Account** (`ManagedAccount`) |
+ * | 2 Connector | where is it, which protocol? | **Connector** (`McpServerEntity`) |
+ * | 3 Capability | what can I do with it? | **Source** (`sync-source`, `memory-source`, …) |
+ * | 4 Usage | is it on, with which settings? | **Connection** (`SyncConnection`, `Channel`) |
  *
- * `ManagedAccount` is een **platform**-primitive, niet een comms-entiteit — dat het type
- * historisch in `entities/communication/types.ts` stond kwam alleen doordat de *store* daar
- * woont. De store blijft in comms (daar zitten de scope-guard en de OAuth-orchestrator);
- * het type hoort hier, want ai, mail, ftp, s3, google en microsoft hangen er allemaal aan.
+ * `ManagedAccount` is a **platform** primitive, not a comms entity — that the type historically
+ * sat in `entities/communication/types.ts` was only because the *store* lives there. The store
+ * stays in comms (the scope guard and the OAuth orchestrator are there); the type belongs here,
+ * because ai, mail, ftp, s3, google and microsoft all hang off it.
  *
- * ## Niet verwarren met een Registration
+ * **Not to be confused with a Registration.** `google_account`, `microsoft_account`,
+ * `shopify_account`, `slack_account` and `meta_app` are NOT accounts in this sense. Those are
+ * **registrations**: the clientId/clientSecret the organisation identifies itself to the vendor
+ * with. One registration carries N accounts. They only share the word.
  *
- * `google_account`, `microsoft_account`, `shopify_account`, `slack_account` en `meta_app` zijn
- * GEEN accounts in deze zin. Dat zijn **registraties**: de clientId/clientSecret waarmee de
- * organisatie zichzelf bij de vendor aanmeldt. Eén registratie draagt N accounts. Ze delen
- * alleen het woord.
- *
- * ## Scope: `userId` is de enige eigendom-as
- *
- * `userId` afwezig/`null` = org-breed, gedeeld. Gezet = persoonlijk, van die ene gebruiker.
- * Er is bewust **geen** `ownerScope` en **geen** `createdBy` op een credential:
- * - `ownerScope` (`personal`/`team`/`org`) is de as van een *resource* — met wie deel ik dit
- *   contact, werkitem of geheugen. Een token heeft geen teamvariant.
- * - "wat eist de vendor" (één gedeeld token vs. iedereen zijn eigen) is een eigenschap van de
- *   **connector**, niet van de accountrij: zie `credentialScope` in `entities/mcp/types.ts`.
+ * **Scope: `userId` is the only ownership axis.** Absent/`null` = org-wide, shared. Set =
+ * personal, of that one user. There is deliberately **no** `ownerScope` and **no** `createdBy` on
+ * a credential: `ownerScope` (`personal`/`team`/`org`) is the axis of a *resource* — who do I
+ * share this contact, work item or memory with — and a token has no team variant; and "what does
+ * the vendor demand" (one shared token vs. everyone their own) is a property of the **connector**,
+ * not of the account row: see `credentialScope` in `entities/mcp/types.ts`.
  */
 export type AuthState = {
     type: "oauth2";
@@ -41,16 +37,16 @@ export type AuthState = {
 } | {
     type: "password";
     username: string;
-    /** Rauw wachtwoord (geen secret-store in repo). Alleen via internal-path. */
+    /** Raw password (no secret store in the repo). Internal path only. */
     password: string;
-    /** Toekomstige secret-store-referentie i.p.v. raw `password`. */
+    /** Future secret-store reference instead of the raw `password`. */
     passwordRef?: string;
 } | {
     type: "certificate";
     certRef: string;
 } | {
     type: "apikey";
-    /** Rauwe API-key (geen secret-store in repo). Alleen via internal-path. */
+    /** Raw API key (no secret store in the repo). Internal path only. */
     apiKey: string;
 } | {
     type: "static";
@@ -60,29 +56,29 @@ export interface ManagedAccount {
     id: string;
     organizationId: string;
     /**
-     * Afwezig/`null` = org-breed gedeeld account. Gezet = persoonlijk account van die gebruiker.
-     * De enige eigendom-as op dit niveau — zie de moduledoc.
+     * Absent/`null` = org-wide shared account. Set = personal account of that user. The only
+     * ownership axis at this level — see the module doc.
      */
     userId?: string;
     providerId: string;
-    /** "oauth2" | "imap" | "sip" | "webhook" | "apikey" | provider-eigen string */
+    /** "oauth2" | "imap" | "sip" | "webhook" | "apikey" | a provider's own string */
     protocol: string;
     displayName: string;
     status: ManagedAccountStatus;
     auth: AuthState;
-    /** Provider-specifieke metadata (tenantId, externalUserId, scope-flags). */
+    /** Provider-specific metadata (tenantId, externalUserId, scope flags). */
     metadata: Record<string, unknown>;
     createdAt?: number;
     updatedAt?: number;
 }
 /**
- * Public-view zonder tokens — wat `account/list` en `account/get` aan UI/comm-server
- * retourneren. `auth` is gestript tot alleen het type.
+ * Public view without tokens — what `account/list` and `account/get` return to the UI and
+ * comm-server. `auth` is stripped down to its type.
  *
- * **Leesasymmetrie, en dit is de valkuil:** de publieke `account/list` filtert op de
- * *huidige* gebruiker, dus een job of cron (die geen sessie heeft) ziet daar niets — ook
- * geen org-brede rijen. Server-side code die accounts moet zien gebruikt altijd de
- * `account-internal/`-route (`listManagedAccountsInternal` / `getManagedAccountInternal`).
+ * **Read asymmetry, and this is the trap:** the public `account/list` filters on the *current*
+ * user, so a job or cron (which has no session) sees nothing there — not even org-wide rows.
+ * Server-side code that needs to see accounts always uses the `account-internal/` route
+ * (`listManagedAccountsInternal` / `getManagedAccountInternal`).
  */
 export type ManagedAccountPublic = Omit<ManagedAccount, "auth"> & {
     authType: AuthState["type"];

package/dist/platform/ai-tools.d.ts

@@ -105,20 +105,20 @@ export interface AiToolResult {
     sources?: ToolSource[];
 }
 /**
- * Stabiele sleutel voor "dit heb ik al laten zien".
+ * Stable key for "I have already shown this".
  *
- * De volgorde `id` → `url` → `title` is aflopend in betrouwbaarheid: een id is stabiel, een
- * url meestal, een titel alleen bij gebrek aan beide. Dat laatste is bewust geen fout — een
- * geheugen-item heeft geen pagina en soms geen id, en dan is de titel de enige identiteit die
- * het heeft. Een sleutel is nooit leeg, want dan zou hetzelfde item elke ronde terugkomen.
+ * The order `id` → `url` → `title` descends in reliability: an id is stable, a url usually, a title
+ * only for lack of both. That last one is deliberately not an error — a memory item has no page and
+ * sometimes no id, and then the title is the only identity it has. A key is never empty, because
+ * then the same item would come back every round.
  */
 export declare function sourceKey(source: ToolSource): string;
 /**
- * Wat hiervan nieuw is, met de sleutels erbij.
+ * Which of these are new, with their keys.
  *
- * Voor een oppervlak dat zichzelf ongevraagd bijwerkt (live meelezen) is dit het verschil
- * tussen "drie kaarten" en "dezelfde drie kaarten, elke acht seconden opnieuw". Ontdubbelt
- * ook binnen de lading zelf: twee banen kunnen hetzelfde artikel aandragen.
+ * For a surface that updates itself unasked (live assist) this is the difference between "three
+ * cards" and "the same three cards, every eight seconds again". Deduplicates within the payload
+ * itself too: two lanes can surface the same article.
  */
 export declare function freshSources(sources: readonly ToolSource[], alreadyShown?: readonly string[]): {
     sources: ToolSource[];
@@ -127,83 +127,79 @@ export declare function freshSources(sources: readonly ToolSource[], alreadyShow
 /**
  * Returned by an app's `GET /provider/ai-tools/describe`.
  *
- * Beide extra velden zijn optioneel en additief: een tool die ze niet zet gedraagt
- * zich exact als voorheen. Ze bestaan zodat generieke lagen (de suggest-gate, de
- * scope-gate in `registerAiToolProvider`) een tool kunnen beoordelen **zonder hem
- * te kennen** — nu zit die kennis in `AIProfile.toolPolicy` met "onbekend = write".
+ * Both extra fields are optional and additive: a tool that does not set them behaves exactly as
+ * before. They exist so generic layers (the suggest gate, the scope gate in
+ * `registerAiToolProvider`) can judge a tool **without knowing it** — today that knowledge sits in
+ * `AIProfile.toolPolicy` with "unknown = write".
  */
 export interface AiToolDescriptor extends AiTool {
-    /** Muteert deze tool iets? Bepaalt de suggest-gate. Afwezig = onbekend. */
+    /** Does this tool mutate anything? Drives the suggest gate. Absent = unknown. */
     access?: "read" | "write";
     /**
-     * De resource waarop deze tool werkt, zodat een generieke gate hem kan
-     * autoriseren: `{ param: "interactionId", kind: "interaction" }` betekent
-     * "autoriseer `interaction:<args.interactionId>` voor de acting identity".
+     * The resource this tool works on, so a generic gate can authorize it:
+     * `{ param: "interactionId", kind: "interaction" }` means "authorize
+     * `interaction:<args.interactionId>` for the acting identity".
      */
     scope?: {
         param: string;
         kind: string;
     };
     /**
-     * `"interactive"` = deze tool heeft een kijkende gebruiker nodig, omdat hij aflevert
-     * op een client-oppervlak (bijvoorbeeld een SSE naar een geopend venster) in plaats
-     * van iets te persisteren. Onbemande runs krijgen zulke tools niet aangeboden:
-     * anders rapporteert het model succes voor iets dat nergens landt. Afwezig = werkt
-     * overal.
+     * `"interactive"` = this tool needs a watching user, because it delivers to a client surface (an
+     * SSE to an open window, say) instead of persisting something. Unattended runs are not offered
+     * such tools: otherwise the model reports success for something that lands nowhere. Absent =
+     * works everywhere.
      */
     surface?: "interactive";
     /**
-     * Reikt deze tool naar **buiten** de organisatie, of blijft het intern?
+     * Does this tool reach **outside** the organisation, or stay internal?
      *
-     * `"outward"` = er gaat iets de deur uit of er verschijnt iets bij een derde: een mail
-     * versturen, een ticket aanmaken, in Slack posten. Twee autonome playbooks die dat
-     * tegelijk op hetzelfde gesprek doen leveren dubbele berichten aan een klant, en dáár
-     * hoort een mens tussen te staan.
+     * `"outward"` = something leaves the building or appears at a third party: sending a mail,
+     * creating a ticket, posting in Slack. Two autonomous playbooks doing that at once on the same
+     * conversation deliver duplicate messages to a customer, and a human belongs in between.
      *
-     * `"internal"` = het resultaat blijft binnen het platform: een attribuut, een
-     * geheugen-item, een notitie. Twee playbooks die dat tegelijk doen zitten elkaar niet in
-     * de weg — verschillende rijen, en de concurrency wordt al door de store afgehandeld.
+     * `"internal"` = the result stays inside the platform: an attribute, a memory item, a note. Two
+     * playbooks doing that at once do not get in each other's way — different rows, and the store
+     * already handles the concurrency.
      *
-     * **Afwezig betekent `"outward"`.** Bewust de voorzichtige kant: een tool die niets
-     * declareert hoort niet stilzwijgend als onschuldig te gelden. Zie
-     * `shouldDemoteAuto` in de playbook-engine, dat hierop de suggest-degradatie bepaalt.
+     * **Absent means `"outward"`.** Deliberately the careful side: a tool that declares nothing
+     * should not silently count as harmless. See `shouldDemoteAuto` in the playbook engine, which
+     * decides the suggest downgrade on this.
      */
     effect?: "internal" | "outward";
 }
 /**
- * Body van `POST /provider/ai-tools/invoke`. Vervangt vijf inline structurele
- * types (de beller in de ai-app plus de vier ontvangende apps).
+ * Body of `POST /provider/ai-tools/invoke`. Replaces five inline structural types (the caller in
+ * the ai app plus the four receiving apps).
  *
- * De acting identity zit hier **niet** in: die reist als header mee
- * (`ACTING_IDENTITY_HEADER` in `@opencxh/platform-api`). Gemeten in fase 0 dat dat
- * werkt vanuit een request, een job én een subscriber — dus geen tweede kanaal.
+ * The acting identity is **not** in here: it travels as a header (`ACTING_IDENTITY_HEADER` in
+ * `@opencxh/platform-api`). Phase 0 measured that this works from a request, a job and a
+ * subscriber — so no second channel.
  */
 export interface AiToolInvokeRequest {
     tool: string;
     arguments?: Record<string, unknown>;
     /**
-     * Wat er in déze beurt al gebeurd is, voor een tool die niet alleen zijn eigen
-     * argumenten nodig heeft maar ook de context waarin hij wordt aangeroepen.
+     * What already happened in *this* turn, for a tool that needs not only its own arguments but
+     * also the context it is called in.
      *
-     * Optioneel en additief, net als de extra velden op {@link AiToolDescriptor}:
-     * een tool die dit negeert gedraagt zich exact als voorheen.
+     * Optional and additive, like the extra fields on {@link AiToolDescriptor}: a tool ignoring this
+     * behaves exactly as before.
      *
-     * De aanleiding is bronvermelding die klopt. De runner verzamelt al de
-     * {@link ToolSource}s van álle tools in een beurt, maar het invoke-contract
-     * droeg alleen `{tool, arguments}` — dus een tool die iets *bewaart* (een
-     * artefact, een geheugen-item) kon niet vastleggen waar het uit is opgebouwd.
-     * Het model ernaar laten raden levert verzonnen bronvermelding op, precies wat
-     * `ToolSource` moest voorkomen.
+     * The reason is provenance that holds up. The runner already collects the {@link ToolSource}s of
+     * *all* tools in a turn, but the invoke contract carried only `{tool, arguments}` — so a tool
+     * that *stores* something (an artifact, a memory item) could not record what it was built from.
+     * Letting the model guess yields invented provenance, exactly what `ToolSource` had to prevent.
      */
     turn?: AiToolTurnContext;
 }
-/** Zie {@link AiToolInvokeRequest.turn}. */
+/** See {@link AiToolInvokeRequest.turn}. */
 export interface AiToolTurnContext {
-    /** Het gesprek waarin deze beurt loopt, als er een is. */
+    /** The conversation this turn runs in, when there is one. */
     conversationId?: string;
     /**
-     * Wat er tot nu toe in deze beurt is geraadpleegd, ontdubbeld. Bevat **niet**
-     * de resultaten van deze call zelf — die bestaan nog niet.
+     * What has been consulted so far in this turn, deduplicated. Does **not** include the results of
+     * this call itself — those do not exist yet.
      */
     sources?: ToolSource[];
 }

package/dist/platform/api.d.ts

@@ -9,16 +9,17 @@ export interface InvokeOptions {
     headers?: Record<string, string>;
     manifest?: AppManifest;
     /**
-     * Laat de aanroep **afwijzen** wanneer de server een fout teruggeeft, in plaats van te
-     * slagen met een leeg `data`.
+     * Make the call **reject** when the server returns an error, instead of succeeding with an empty
+     * `data`.
      *
-     * Zonder dit lost `invoke` altijd op: `sendViaHttp` keek niet naar `response.ok` en de
-     * ws-kant kende geen reject-pad. Een geweigerde mutatie kwam daardoor binnen als
-     * `data: undefined`, de entity-store liet die stil vallen, en de `next`-tak van de
-     * mutatie liep gewoon door — de composer maakte zichzelf leeg en de gebruiker dacht dat
-     * het bericht verstuurd was. Elke `error:`-handler in de app was daarmee dode code.
+     * Without this, `invoke` always resolved: `sendViaHttp` did not look at `response.ok` and the ws
+     * side had no reject path. A refused mutation therefore arrived as `data: undefined`, the entity
+     * store dropped it silently, and the mutation's `next` branch ran anyway — the composer cleared
+     * itself and the user thought the message had been sent. Every `error:` handler in the app was
+     * dead code.
      *
-     * Voorlopig opt-in zodat apps één voor één om kunnen; comms gaat als eerste.
+     * **On by default.** Set it to `false` to deliberately keep one call quiet — then it is a choice
+     * that stands in the code, not the default state everyone walks into.
      */
     throwOnError?: boolean;
 }

package/dist/platform/author.d.ts

@@ -1,14 +1,12 @@
 /**
- * Wie een mutatie heeft uitgevoerd — voor attributie op de timeline en in
- * analytics. Server-side afgeleid uit de request (zie `resolveAuthor` in
- * `@opencxh/platform-api`). De shape sluit aan op `BaseActivity.author`, zodat
- * een author direct als activity-author kan worden weggeschreven.
+ * Who performed a mutation — for attribution on the timeline and in analytics. Derived server-side
+ * from the request (see `resolveAuthor` in `@opencxh/platform-api`). The shape lines up with
+ * `BaseActivity.author`, so an author can be written straight as an activity author.
  *
- * - `user`   — ingelogde gebruiker; `id` is de user-id (analytics-attributie).
- * - `app`    — een provider/integratie-app (bv. een playbook dat als de `ai`-app
- *              muteert); `id` is de app-naam. De timeline toont dan de app
- *              i.p.v. een anonieme "System".
- * - `system` — geen geïdentificeerde actor (cron, achtergrondjob).
+ * - `user`   — a logged-in user; `id` is the user id (analytics attribution).
+ * - `app`    — a provider/integration app (a playbook mutating as the `ai` app, say); `id` is the
+ *              app name. The timeline then shows the app instead of an anonymous "System".
+ * - `system` — no identified actor (cron, background job).
  */
 export type MutationAuthor = {
     type: "user";

package/dist/platform/capabilities.d.ts

@@ -40,9 +40,9 @@ export declare function resolveChannelIntents(channel: Channel, description: Pro
  */
 export declare function resolveAccountCapabilities(description: ProviderDescription, accountCaps: Record<string, boolean> | undefined): Record<string, boolean>;
 /**
- * Lijst van intent-namen die UIT staan voor dit account. Mapt 1-op-1 naar
- * `Channel.disabledIntents`. Niet-togglable intents komen nooit op de lijst —
- * die kan provider hardcode'n via eigen channel-kind constraint.
+ * List of intent names that are OFF for this account. Maps one-to-one onto
+ * `Channel.disabledIntents`. Non-togglable intents never make the list — a provider can hardcode
+ * those through its own channel-kind constraint.
  */
 export declare function disabledIntentsFromCapabilities(description: ProviderDescription, accountCaps: Record<string, boolean> | undefined): string[];
 /**