@opencxh/domain 1.172.1 → 1.173.0

package/dist/entities/memory/ingest.d.ts

@@ -1,31 +1,31 @@
 import { MemoryKindId, MemoryLink, MemorySubjectKey } from './item';
 /**
- * Schrijven is een **CAS-upsert**, geen snapshot-replace zoals analytics.
+ * Writing is a **CAS upsert**, not a snapshot replace like analytics.
  *
- * Analytics mag een hele periode weggooien en opnieuw wegschrijven omdat een fact
- * herberekenbaar is uit de bronstore. Een delta-gevouwen verhaal is de opgetelde uitkomst
- * van N modelcalls en is dat niet. Bovendien is remove+insert niet atomair: een lezer kan
- * "geen item" observeren op een subject dat wél een verhaal heeft.
+ * Analytics may throw a whole period away and write it again because a fact is recomputable from
+ * the source store. A delta-folded story is the accumulated outcome of N model calls and is not.
+ * On top of that, remove+insert is not atomic: a reader can observe "no item" on a subject that
+ * does have a story.
  */
 export interface MemoryUpsertRequest {
     organizationId: string;
-    /** De schrijvende app; de hub vult dit uit `req.source.app` en vertrouwt de body hier niet. */
+    /** The writing app; the hub fills this from `req.source.app` and does not trust the body. */
     source: string;
     subject: MemorySubjectKey;
     kind: MemoryKindId;
-    /** Default bij `cardinality: "single"`: `"<kind>:<subject>"`. */
+    /** Default with `cardinality: "single"`: `"<kind>:<subject>"`. */
     sourceRef?: string;
     title: string;
     body: string;
     occurredAt?: number;
-    /** Watermerk van het bron-event dat deze schrijfactie veroorzaakte. */
+    /** Watermark of the source event that caused this write. */
     throughRef?: string;
     throughAt?: number;
-    /** Mismatch => `accepted: false` met `reason: "stale-version"`; de caller herplant. */
+    /** A mismatch => `accepted: false` with `reason: "stale-version"`; the caller reschedules. */
     expectedVersion?: number;
     audienceRef?: string;
     locale?: string;
-    /** Weglaten: de hub extraheert keywords zelf uit titel + body (één tokenizer, schrijf én lees). */
+    /** Omit it: the hub extracts keywords from title + body itself (one tokenizer, write and read). */
     keywords?: string[];
     tags?: string[];
     links?: MemoryLink[];
@@ -33,14 +33,14 @@ export interface MemoryUpsertRequest {
 export type MemoryUpsertRejection = "stale-version" | "stale-watermark" | "unknown-kind" | "kind-disabled" | "subject-kind-mismatch" | "not-owner";
 export interface MemoryUpsertResult {
     accepted: boolean;
-    /** De versie zoals die nu in de store staat — ook bij een afwijzing, zodat de caller kan herplannen. */
+    /** The version as it stands in the store now — also on a rejection, so the caller can reschedule. */
     version: number;
     itemId?: string;
     reason?: MemoryUpsertRejection;
 }
 /**
- * Expliciet destructief: gooit alle items van (subject, kind) van deze bron weg en zet
- * `items` ervoor terug. Alleen voor **herberekenbare** kinds, bv. een nachtelijke re-fold.
+ * Explicitly destructive: throws away all items of (subject, kind) from this source and puts
+ * `items` back in their place. Only for **recomputable** kinds, e.g. a nightly re-fold.
  */
 export interface MemoryReplaceRequest {
     organizationId: string;
@@ -50,23 +50,19 @@ export interface MemoryReplaceRequest {
     items: MemoryUpsertRequest[];
 }
 /**
- * Bron-gestuurd wissen. De **bron** pusht dit; de hub interpreteert geen deletes: de
- * mapping van een verwijderd contact naar zijn interacties leeft in comms, en
- * `contacts:deleted` publiceert alleen `{ id }` — zonder `organizationId`.
+ * Source-driven wiping. The **source** pushes this; the hub interprets no deletes: the mapping
+ * from a deleted contact to its interactions lives in comms, and `contacts:deleted` publishes only
+ * `{ id }` — without an `organizationId`.
  *
- * ## Er staat geen `source` in, en dat was de bug
+ * **There is no `source` field, and that was the bug.** It used to exist and the purge filtered on
+ * it, so only memory carrying that source was wiped. The server derived it from the *calling* app,
+ * but memory is written by the app that *records* it — `"context"` for a note, `ctx.app` for the
+ * `memory_remember` tool — never by the app deleting the subject. Net effect: the purge matched
+ * nothing, a deleted contact or conversation kept its memory. A retention leak, and invisible,
+ * because `{ removed: 0 }` is a valid answer.
  *
- * Dit veld bestond en de purge filterde erop: alleen geheugen mét die bron werd gewist. De
- * serverkant leidde hem af uit de *aanroepende* app (`requireApp`), dus comms wiste met
- * `source: "communication"` en crm zou met `"crm"` wissen. Maar geheugen wordt geschreven door
- * de app die het *vastlegt* — `"context"` voor een notitie, `ctx.app` voor de
- * `memory_remember`-tool. Nooit door de app die het subject verwijdert.
- *
- * Netto matchte de purge dus niets: een verwijderd contact of gesprek liet zijn geheugen
- * staan. Een retentie-lek, en niet zichtbaar, want `{ removed: 0 }` is een geldig antwoord.
- *
- * Een purge is subject-gescopeerd en niet bron-gescopeerd: "dit subject bestaat niet meer, haal
- * alles erover weg". Dat de aanroeper een app moet zijn blijft de poort; het is geen filter.
+ * A purge is subject-scoped and not source-scoped: "this subject no longer exists, remove
+ * everything about it". That the caller has to be an app stays the gate; it is not a filter.
  */
 export interface MemoryPurgeRequest {
     organizationId: string;

package/dist/entities/memory/item.d.ts

@@ -1,114 +1,109 @@
 /**
- * De geheugenlaag (`apps/context`): één durende laag per **subject**, waarbij de
- * organisatie zelf per event bepaalt wat er onthouden wordt.
+ * The memory layer (`apps/context`): one durable layer per **subject**, where the organisation
+ * itself decides per event what gets remembered.
  *
- * `Memory*` en niet `Context*`: `platform/context.ts` exporteert al `HostContext` en
- * `context.collect` (vluchtige route-context) uit dezelfde platte barrel.
+ * `Memory*` and not `Context*`: `platform/context.ts` already exports `HostContext` and
+ * `context.collect` (ephemeral route context) from the same flat barrel.
  */
-/** Een bestaande scopeKey: `interaction:i_1`, `contact:c_9`. Een latere identiteitslaag is gewoon een ander prefix. */
+/** An existing scopeKey: `interaction:i_1`, `contact:c_9`. A later identity layer is just another prefix. */
 export type MemorySubjectKey = string;
-/** `comms.resolution` (app-gedeclareerd) of `sales_besluitvormer` (org-eigen). */
+/** `comms.resolution` (app-declared) or `sales_besluitvormer` (org-owned). */
 export type MemoryKindId = string;
 /**
- * Een verwijzing naar iets anders — intern (`interaction:i_2`) of extern
- * (`hubspot:5591`, `clickup:86ab2`).
+ * A reference to something else — internal (`interaction:i_2`) or external (`hubspot:5591`,
+ * `clickup:86ab2`).
  *
- * Een **lijst**, nooit een object met de relatie als key.
- *
- * De oorspronkelijke reden (de http-client mangelde object-keys) geldt niet meer sinds 17-08-2026.
- * De lijst blijft om een reden die altijd al sterker was: **dezelfde `rel` mag twee keer voorkomen**
- * — twee gekoppelde bedrijven, drie betrokken interacties — en een map gooit er dan één weg.
+ * A **list**, never an object keyed by the relation: **the same `rel` may occur twice** — two
+ * linked companies, three involved interactions — and a map would throw one away.
  */
 export interface MemoryLink {
     rel: string;
     target: string;
 }
-/** Harde grens op de body. Geheugen is een samenvatting; een mailbox-schaduwkopie is het niet. */
+/** Hard limit on the body. Memory is a summary; it is not a shadow copy of a mailbox. */
 export declare const MAX_MEMORY_CHARS = 2000;
 export interface MemoryItem {
     id: string;
     organizationId: string;
     subject: MemorySubjectKey;
     /**
-     * De dossiersleutels waaronder dit item vindbaar is: het subject zelf, plus de sleutels die
-     * de eigenaar-app van dat subject teruggaf (`ScopeAuth.keys`). Gestempeld bij het schrijven.
+     * The file keys this item is findable under: the subject itself, plus the keys the owning app of
+     * that subject returned (`ScopeAuth.keys`). Stamped at write time.
      *
-     * Dit is wat "vertel me wat er speelde bij deze klant" één geïndexeerde query maakt in
-     * plaats van een traversal. Een casus die op een gesprek is onthouden draagt via
-     * `Interaction.partyKeys` ook `domain:vandijck.nl` en `company:co_1`; het bedrijfsdossier
-     * matcht daarop met zijn eigen handvol sleutels, hoeveel medewerkers dat bedrijf ook heeft.
+     * This is what makes "tell me what was going on at this customer" one indexed query instead of a
+     * traversal. A case remembered on a conversation also carries `domain:vandijck.nl` and
+     * `company:co_1` through `Interaction.partyKeys`; the company file matches on those with its own
+     * handful of keys, however many employees that company has.
      *
-     * **`keys` en niet `subjects`**, want dat zijn ze niet: `domain:vandijck.nl` is geen subject
-     * — geen app bezit die soort, dus `authorizeIdentity` erop geeft `allowed: false`. Een naam
-     * die belooft dat dit subjects zijn, nodigt precies die fout uit. Zelfde woord als
-     * `Interaction.partyKeys`, `Contact.keys` en `ScopeAuth.keys`: één begrip, één term.
+     * **`keys` and not `subjects`**, because they are not: `domain:vandijck.nl` is no subject — no
+     * app owns that kind, so `authorizeIdentity` on it returns `allowed: false`. A name promising
+     * these are subjects invites exactly that mistake. Same word as `Interaction.partyKeys`,
+     * `Contact.keys` and `ScopeAuth.keys`: one concept, one term.
      *
-     * Bewust een momentopname en niet op leesmoment opgelost: opgelost bij elke query zou
-     * betekenen dat elke hit een autorisatie-fan-out kost — precies wat de engine zich niet kan
-     * veroorloven. De prijs is dat een sleutel die *later* wordt vastgelegd dit item niet meer
-     * bereikt; in de praktijk dekken `mailto:`/`domain:` dat vrijwel altijd al.
+     * Deliberately a snapshot and not resolved at read time: resolving on every query would mean
+     * every hit costs an authorization fan-out, which the engine cannot afford. The price is that a
+     * key recorded *later* no longer reaches this item; in practice `mailto:`/`domain:` already
+     * cover that almost always.
      *
-     * `subject` blijft het anker, en is dus géén element-onder-de-andere: de unieke index, het
-     * vouwen, het wissen bij een verwijderd contact en de autorisatie lopen alle vier dáárover,
-     * en die hebben er exact één nodig.
+     * `subject` stays the anchor and is therefore not one element among the others: the unique
+     * index, the folding, the wipe on a deleted contact and the authorization all four run over it,
+     * and those need exactly one.
      */
     keys?: string[];
     kind: MemoryKindId;
     title: string;
-    /** DE inhoud: markdown, begrensd op {@link MAX_MEMORY_CHARS}. Nooit een genest object. */
+    /** THE content: markdown, capped at {@link MAX_MEMORY_CHARS}. Never a nested object. */
     body: string;
-    /** Schrijvende app (== `req.source.app`); playbook-schrijfacties komen binnen als "ai". */
+    /** Writing app (== `req.source.app`); playbook writes arrive as "ai". */
     source: string;
-    /** Identiteit binnen (subject, kind) voor de bron. Bij `cardinality: "single"` de vouw-sleutel. */
+    /** Identity within (subject, kind) for the source. With `cardinality: "single"` the fold key. */
     sourceRef: string;
     occurredAt: number;
     /**
-     * Watermerk: tot en met welk bron-event dit item gevouwen is. Maakt dubbele events en
-     * retries gratis — een oudere `throughAt` wordt afgewezen in plaats van overschreven.
+     * Watermark: up to and including which source event this item is folded. Makes duplicate events
+     * and retries free — an older `throughAt` is refused instead of overwriting.
      */
     throughRef?: string;
     throughAt?: number;
-    /** Optimistic concurrency; de hub doet compare-and-swap op dit veld. */
+    /** Optimistic concurrency; the hub does compare-and-swap on this field. */
     version: number;
-    /** Overgenomen uit de kind-definitie, niet uit de call — zie `MemoryKindDefinition.visibility`. */
+    /** Taken from the kind definition, not from the call — see `MemoryKindDefinition.visibility`. */
     visibility: MemoryVisibility;
     /**
-     * Zichtbaarheids-ANKER (inbox-id / OwnerScope-sleutel), **geen ledenlijst**: een
-     * gesnapshotte ledenlijst veroudert bij elke inbox-join en reassignment, en
-     * stale-permissive is een lek.
+     * Visibility ANCHOR (inbox id / OwnerScope key), **not a member list**: a snapshotted member list
+     * goes stale on every inbox join and reassignment, and stale-permissive is a leak.
      */
     audienceRef?: string;
     /**
-     * Taal van de inhoud. **Beschrijvend, geen filter** — en dat is een besluit, geen omissie.
+     * Language of the content. **Descriptive, not a filter** — a decision, not an omission.
      *
-     * Retrieval vergelijkt bewust óók over taalgrenzen: de embeddingmodellen hier zijn meertalig,
-     * dus een Nederlandse vraag hoort een Engelse casus over hetzelfde probleem te vinden. Er
-     * stond eerder een harde taalcheck in `rank.ts`; die was nooit aangesloten en zou, als je hem
-     * wél had aangesloten, bij een anderstalige zoekvraag élk item hebben overgeslagen — want
-     * niets zet dit veld, dus alles staat op de default.
+     * Retrieval deliberately compares across language boundaries too: the embedding models here are
+     * multilingual, so a Dutch question should find an English case about the same problem. A hard
+     * language check once sat in `rank.ts`; it was never wired up and, had it been, would have
+     * skipped *every* item on a foreign-language query — because nothing sets this field, so
+     * everything sits on the default.
      *
-     * Zet je dit ooit echt, houd het dan een *ordenings*-signaal (materiaal in je eigen taal is
-     * makkelijker te gebruiken) en geen zichtbaarheidsfilter.
+     * If this is ever really set, keep it an *ordering* signal (material in your own language is
+     * easier to use) and not a visibility filter.
      */
     locale: string;
-    /** Gedenormaliseerde termen: het enige selectieve structurele filter (er is geen substring-operator). */
+    /** Denormalized terms: the only selective structural filter (there is no substring operator). */
     keywords?: string[];
-    /** Snelle alternatieve sleutels, bv. `tel:+31612345678` voor het rinkelmoment. */
+    /** Fast alternative keys, e.g. `tel:+31612345678` for the moment the phone rings. */
     tags?: string[];
     links?: MemoryLink[];
-    /** Model waarmee de vector is gemaakt; retrieval vergelijkt alleen binnen hetzelfde model. */
+    /** Model the vector was made with; retrieval only compares within the same model. */
     embeddingModel?: string;
-    /** Uit een live pull (fase 3); nooit gepersisteerd. */
+    /** From a live pull (phase 3); never persisted. */
     live?: boolean;
     createdAt?: number;
     updatedAt?: number;
 }
 /**
- * `"audience"` = alleen voor wie het subject mag zien. `"org"` = org-breed leesbaar en
- * daarmee vindbaar in het cross-subject-pad ("is dit eerder bij een andere klant
- * voorgekomen?").
+ * `"audience"` = only for whoever may see the subject. `"org"` = readable org-wide and therefore
+ * findable in the cross-subject path ("has this happened at another customer before?").
  *
- * Per **kind** gedeclareerd en niet per item: het cross-subject-pad kan zich geen
- * autorisatie-round-trip per hit veroorloven, dus het filtert structureel op deze kolom.
+ * Declared per **kind** and not per item: the cross-subject path cannot afford an authorization
+ * round trip per hit, so it filters structurally on this column.
  */
 export type MemoryVisibility = "audience" | "org";

package/dist/entities/memory/kind.d.ts

@@ -2,65 +2,65 @@ import { LocaleBundle } from '../analytics/dashboard';
 import { OwnerScope } from '../scope/types';
 import { MemoryKindId, MemoryVisibility } from './item';
 /**
- * Wat er onthouden mág worden, en met welke regels.
+ * What may be remembered, and under which rules.
  *
- * Twee bronnen, één type:
- *  - **app-gedeclareerd** via `GET /provider/memory/describe` (de ingebouwde defaults);
- *  - **org-eigen** als rij in `memory_kind`. Mal: `CustomFieldDef` — de organisatie
- *    definieert de sleutel, een generieke store bewaart de waarde.
+ * Two sources, one type:
+ *  - **app-declared** through `GET /provider/memory/describe` (the built-in defaults);
+ *  - **org-owned** as a row in `memory_kind`. Template: `CustomFieldDef` — the organisation
+ *    defines the key, a generic store keeps the value.
  *
- * `ownerScope` is wat "iedereen wil zijn eigen relevante data" mogelijk maakt: sales legt
- * andere dingen vast dan support, en een persoonlijk kind is alleen van die gebruiker.
+ * `ownerScope` is what makes "everyone wants their own relevant data" possible: sales records
+ * different things from support, and a personal kind belongs to that user only.
  */
 export interface MemoryKindDefinition {
-    /** Org-eigen: `[a-z0-9_]+` (geen punt — die leest als een genest form-pad). App-eigen: `<app>.<naam>`. */
+    /** Org-owned: `[a-z0-9_]+` (no dot — that reads as a nested form path). App-owned: `<app>.<name>`. */
     id: MemoryKindId;
     label: string;
     description?: string;
-    /** Subject-soorten waarop dit kind mag landen, bv. `["interaction"]` of `["contact"]`. */
+    /** Subject kinds this kind may land on, e.g. `["interaction"]` or `["contact"]`. */
     subjectKinds: string[];
     visibility: MemoryVisibility;
-    /** `"single"` = één item per (subject, kind), doorvouwen. `"many"` = losse items. */
+    /** `"single"` = one item per (subject, kind), folded onward. `"many"` = separate items. */
     cardinality: "single" | "many";
-    /** Ordening onder het tekenbudget van de bundel. */
+    /** Ordering under the bundle's character budget. */
     priority: number;
-    /** Mag dit kind in het cross-subject-pad meedoen? Alleen zinvol bij `visibility: "org"`. */
+    /** May this kind take part in the cross-subject path? Only meaningful with `visibility: "org"`. */
     crossSubjectSearchable: boolean;
-    /** Embedden kost geld; per kind aan/uit. */
+    /** Embedding costs money; on or off per kind. */
     embed: boolean;
     retentionDays?: number;
-    /** Rang-multiplier: een opgeloste casus verslaat een losse notitie. Default 1. */
+    /** Rank multiplier: a resolved case beats a loose note. Defaults to 1. */
     weight?: number;
     /**
-     * Wie dit kind bezit. Bepaalt zowel wie mag schrijven als de **ordening** voor een
-     * lezer (eigen team eerst). Afwezig = de hele organisatie.
+     * Who owns this kind. Decides both who may write and the **ordering** for a reader (own team
+     * first). Absent = the whole organisation.
      */
     ownerScope?: OwnerScope;
-    /** Wie hem declareerde. De org kan een app-kind niet oprekken, alleen uitzetten. */
+    /** Who declared it. The org cannot widen an app kind, only switch it off. */
     origin: "app" | "org";
     enabled: boolean;
 }
 /**
- * Bare payload van `GET /provider/memory/describe` — **niet** in `ResponseFactory`
- * verpakt (mal: `AnalyticsSourceDescription`).
+ * Bare payload of `GET /provider/memory/describe` — **not** wrapped in `ResponseFactory`
+ * (template: `AnalyticsSourceDescription`).
  */
 export interface MemorySourceDescription {
-    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    /** The declaring app (== `manifest.name` == `req.source.app`). */
     source: string;
     kinds: MemoryKindDefinition[];
-    /** Vlakke LIJST, zoals {@link LocaleBundle}; zie daar waarom die vorm blijft. */
+    /** Flat LIST, like {@link LocaleBundle}; see there why that shape stays. */
     locales?: LocaleBundle;
-    /** Fase 3: welke subjects/kinds deze bron live kan leveren. */
+    /** Phase 3: which subjects/kinds this source can deliver live. */
     live?: {
         subjectKinds: string[];
         kinds: MemoryKindId[];
     };
 }
-/** De samengestelde catalogus die de hub aan de frontend levert (`GET /kinds`). */
+/** The composed catalog the hub delivers to the frontend (`GET /kinds`). */
 export interface MemoryKindCatalog {
-    /** App-gedeclareerd + org-eigen, gemengd. */
+    /** App-declared plus org-owned, mixed. */
     kinds: MemoryKindDefinition[];
-    /** Bronnen die meededen aan de fan-out (voor "wie levert dit?"). */
+    /** Sources that took part in the fan-out (for "who provides this?"). */
     sources: string[];
     locales: LocaleBundle;
 }

package/dist/entities/memory/query.d.ts

@@ -1,71 +1,71 @@
 import { MemoryItem, MemoryKindId, MemorySubjectKey } from './item';
-/** Grenzen van het tekenbudget van een bundel. Buiten bereik wordt geklemd, niet geweigerd. */
+/** Bounds of a bundle's character budget. Out of range is clamped, not refused. */
 export declare const MIN_MEMORY_BUDGET = 500;
 export declare const MAX_MEMORY_BUDGET = 12000;
 export declare const DEFAULT_MEMORY_BUDGET = 4000;
 /**
- * Één query-contract voor het dossier-paneel, de brief tijdens het rinkelen en elke
- * AI-tool. Geen tweede codepad: het verschil tussen die drie is `budget`, niet code.
+ * One query contract for the file panel, the briefing while the phone rings, and every AI tool. No
+ * second code path: the difference between those three is `budget`, not code.
  */
 export interface MemoryQuery {
-    /** Weglaten = cross-subject zoeken ("vergelijkbare cases"). */
+    /** Omit = cross-subject search ("similar cases"). */
     subject?: MemorySubjectKey;
-    /** Extra subjects die bij hetzelfde beeld horen, bv. het contact naast de interactie. */
+    /** Extra subjects belonging to the same picture, e.g. the contact next to the interaction. */
     alsoSubjects?: MemorySubjectKey[];
     /**
-     * Ook items die niet ópt subject staan maar er wél bij horen: alles wat dezelfde
-     * dossiersleutel draagt (`MemoryItem.keys`).
+     * Also items not *on* the subject but belonging to it: everything carrying the same file key
+     * (`MemoryItem.keys`).
      *
-     * Dit is het antwoord op "wat speelde er bij dit bedrijf": een casus staat op het gesprek,
-     * en het bedrijfsdossier vindt hem via `domain:`/`company:` in plaats van via een lijst van
-     * vijftig medewerker-subjects. Eén extra `$or`-tak op een geïndexeerde array-kolom, geen
-     * tweede query en geen extra autorisatie-fan-out.
+     * This is the answer to "what was going on at this company": a case sits on the conversation, and
+     * the company file finds it through `domain:`/`company:` instead of through a list of fifty
+     * employee subjects. One extra `$or` branch on an indexed array column, no second query and no
+     * extra authorization fan-out.
      *
-     * **Alleen `visibility: "org"` erft mee.** De autorisatie van dit pad is de ene check op het
-     * anker; een geërfd item is per definitie niet op dat anker geautoriseerd. Een casus uit
-     * iemands persoonlijke mailbox is bij het schrijven al versmald naar `audience`
-     * (`effectiveVisibility`) en blijft dus buiten het klantdossier van een collega.
+     * **Only `visibility: "org"` is inherited.** The authorization of this path is the single check
+     * on the anchor; an inherited item is by definition not authorized on that anchor. A case from
+     * someone's personal mailbox is already narrowed to `audience` at write time
+     * (`effectiveVisibility`) and therefore stays out of a colleague's customer file.
      *
-     * Vereist een anker (`subject`); zonder anker is dit het cross-subject-pad.
+     * Requires an anchor (`subject`); without one this is the cross-subject path.
      */
     related?: boolean;
     /** Default true. */
     resolveAliases?: boolean;
     kinds?: MemoryKindId[];
     tags?: string[];
-    /** Vrije tekst. Afwezig = puur structurele ordening (priority x recency x weight) en dus geen embedding-call. */
+    /** Free text. Absent = purely structural ordering (priority x recency x weight), so no embedding call. */
     text?: string;
     since?: number;
     limit?: number;
-    /** Zo bedoel je "bij ANDERE klanten". */
+    /** This is how you say "at OTHER customers". */
     excludeSubjects?: MemorySubjectKey[];
     format?: "items" | "bundle" | "both";
-    /** Geklemd op [{@link MIN_MEMORY_BUDGET}, {@link MAX_MEMORY_BUDGET}]. */
+    /** Clamped to [{@link MIN_MEMORY_BUDGET}, {@link MAX_MEMORY_BUDGET}]. */
     budget?: number;
-    /** Fase 3: ook live bronnen bevragen, met harde timeout en eigen sub-budget. */
+    /** Phase 3: query live sources too, with a hard timeout and their own sub-budget. */
     live?: boolean;
 }
 /**
- * Subject-soorten waarvoor "het dossier" de **verbanden** insluit: alles wat dezelfde
- * dossiersleutel draagt, ook als het op een ander subject is onthouden.
+ * Subject kinds for which "the file" includes the **relations**: everything carrying the same file
+ * key, even when it was remembered on another subject.
  *
- * Bij een klant of een persoon ís de partij de vraag — "wat speelde er bij Van Dijck" gaat over
- * het bedrijf, terwijl de casussen op de gesprekken staan. Bij een gesprek niet: dan wil je de
- * draad zelf, want het hele klantverleden verdringt in een begrensde bundel precies wat er nú
- * aan de hand is.
+ * With a customer or a person the party *is* the question — "what was going on at Van Dijck" is
+ * about the company, while the cases sit on the conversations. With a conversation it is not: there
+ * you want the thread itself, because in a bounded bundle the whole customer history crowds out
+ * exactly what is going on right now.
  *
- * Staat hier en niet in de tool of in het paneel, omdat het er twee zijn: de assistent en het
- * dossierpaneel horen hetzelfde te bedoelen met "het dossier van deze klant". Twee kopieën van
- * die regel is precies de soort regel die uit elkaar loopt.
+ * Here and not in the tool or the panel, because there are two of them: the assistant and the file
+ * panel should mean the same thing by "this customer's file". Two copies of that rule is exactly
+ * the kind of rule that drifts apart.
  */
 export declare const RELATED_SUBJECT_KINDS: readonly ["contact", "company"];
-/** Hoort {@link MemoryQuery.related} standaard aan te staan voor dit subject? */
+/** Should {@link MemoryQuery.related} default to on for this subject? */
 export declare function relatedByDefault(subject: MemorySubjectKey | undefined): boolean;
 export interface MemoryHit {
     item: MemoryItem;
     score: number;
     snippet: string;
-    /** Ruw materiaal voor een confidence-gate (fase 4): waar kwam de score vandaan? */
+    /** Raw material for a confidence gate (phase 4): where did the score come from? */
     matched: {
         keyword: number;
         semantic: number;
@@ -75,39 +75,37 @@ export interface MemoryHit {
 export interface MemoryQueryResult {
     hits: MemoryHit[];
     bundle?: string;
-    /** Hoeveel rijen het structurele voorfilter opleverde. */
+    /** How many rows the structural pre-filter yielded. */
     scanned: number;
-    /** Scan-cap geraakt OF hits uit de bundel gevallen — nooit stil afkappen. */
+    /** Scan cap hit OR hits dropped from the bundle — never truncate silently. */
     truncated?: boolean;
-    /** `false` = keyword-only (geen embedding-account, of geen enkele vergelijkbare vector). */
+    /** `false` = keyword-only (no embedding account, or not a single comparable vector). */
     semantic: boolean;
-    /** Hits die de her-autorisatie van de top-K niet overleefden. */
+    /** Hits that did not survive the re-authorization of the top-K. */
     withheld?: number;
     /**
-     * Kandidaten die op het cross-subject-pad afvielen op de absolute gelijkenisdrempel.
+     * Candidates dropped on the cross-subject path by the absolute similarity threshold.
      *
-     * Het verschil met een leeg resultaat: `belowThreshold: 7` betekent "er was materiaal, maar
-     * niets leek er echt op" en `undefined` betekent "er was niets". Zonder deze teller is de
-     * drempel niet te kalibreren — je ziet dan alleen dat er niets terugkomt, niet of hij te hoog
-     * staat.
+     * The difference with an empty result: `belowThreshold: 7` means "there was material, but nothing
+     * really resembled it" and `undefined` means "there was nothing". Without this counter the
+     * threshold cannot be calibrated — you only see that nothing comes back, not whether it sits too
+     * high.
      */
     belowThreshold?: number;
     /**
-     * Kandidaten overgeslagen door model- of taal-mismatch. Zonder deze teller degradeert
-     * een modelwissel volkomen stil: `cosineSimilarity` geeft bij dimensie-mismatch 0, dus
-     * na het omzetten van `isDefaultEmbedding` scoort élk bestaand item 0 en valt retrieval
-     * geruisloos terug op keyword.
+     * Candidates skipped by a model or language mismatch. Without this counter a model switch
+     * degrades completely silently: `cosineSimilarity` returns 0 on a dimension mismatch, so after
+     * flipping `isDefaultEmbedding` *every* existing item scores 0 and retrieval quietly falls back
+     * to keyword.
      */
     vectorSkipped?: number;
     /**
-     * Waarom er niets terugkwam, als dat een structurele reden heeft in plaats van "niets
-     * gevonden".
+     * Why nothing came back, when that has a structural reason instead of "nothing found".
      *
-     * `"no-cross-subject-kinds"` is de belangrijkste: zoeken bij ándere klanten leest alleen
-     * geheugensoorten die als `visibility: "org"` én `crossSubjectSearchable` zijn
-     * gedeclareerd. Is er geen enkele, dan is een leeg resultaat geen zoekuitkomst maar een
-     * configuratiefeit — en dat hoort de caller te weten in plaats van te concluderen dat er
-     * niets vergelijkbaars bestaat.
+     * `"no-cross-subject-kinds"` is the important one: searching at *other* customers reads only
+     * memory kinds declared both `visibility: "org"` and `crossSubjectSearchable`. If there is not a
+     * single one, an empty result is not a search outcome but a configuration fact — and the caller
+     * should know that instead of concluding nothing comparable exists.
      */
     reason?: "no-cross-subject-kinds" | "no-subject-access";
 }