@opencxh/domain 1.127.0 → 1.130.0

package/dist/entities/company/index.d.ts

@@ -0,0 +1 @@
+export * from './types';

package/dist/entities/company/types.d.ts

@@ -0,0 +1,50 @@
+import { OwnerScope } from '../contact/types';
+/** Where a company row came from. `local` is a row somebody created by hand. */
+export interface CompanySource {
+    providerId: string;
+    readOnly?: boolean;
+}
+/**
+ * A company we own a row for.
+ *
+ * The identity fields are deliberately flat string arrays: only that shape is
+ * indexable in this datastore, so `keys`, `domains` and `externalIds` are what makes a
+ * lookup an indexed exact match instead of a scan.
+ */
+export interface Company {
+    id: string;
+    organizationId: string;
+    name: string;
+    /**
+     * Registrable e-mail domains that identify this company (`vandijck.nl`). Matched
+     * after `registrableDomain`, so a subdomain resolves too. Public/consumer domains
+     * are rejected on write — one company with `gmail.com` here would claim every
+     * private customer.
+     */
+    domains: string[];
+    /**
+     * Canonical endpoint keys (`tel:+31882112121`, `mailto:info@vandijck.nl`), produced
+     * by `endpointKey`. Never a raw value: the raw form is kept for display only.
+     */
+    keys: string[];
+    /**
+     * Namespaced references into external systems (`hubspot:5591`, `exact:REL0042`).
+     * A reference, never a copy — live figures (balance, deal value) stay where they
+     * belong and are fetched on demand.
+     */
+    externalIds: string[];
+    ownerScope: OwnerScope;
+    source: CompanySource;
+    /** Raw, human-readable phone/website as entered, for display. */
+    phone?: string;
+    website?: string;
+    notes?: string;
+}
+/** What a resolve returns: which company, and how we got there. */
+export interface CompanyMatch {
+    company: Company;
+    /** Which rung of the local chain matched — useful for debugging a wrong link. */
+    via: "contact" | "key" | "domain";
+    /** The contact row that carried the link, when `via` is `contact`. */
+    contactId?: string;
+}

package/dist/entities/contact/types.d.ts

@@ -20,6 +20,16 @@ export interface ContactSource {
     externalId?: string;
     readOnly?: boolean;
 }
+/**
+ * Where a contact row came from.
+ *
+ * - `own` — somebody created or promoted it here; freely editable.
+ * - `shadow` — a lazily cached hit from a federated source (a directory, a CRM). It
+ *   exists so the second call from that number is an indexed hit instead of another
+ *   fan-out. Hidden from the contact list by default: the Entra directory is full of
+ *   your own colleagues, and writing those in as customers pollutes the list.
+ */
+export type ContactOrigin = "own" | "shadow";
 export interface Contact {
     id: string;
     organizationId: string;
@@ -27,7 +37,26 @@ export interface Contact {
     source: ContactSource;
     firstName: string;
     lastName?: string;
+    /**
+     * Free-text company name. Stays as the display fallback for contacts that have no
+     * `companyId` — a dozen render sites use it as a label.
+     */
     company?: string;
+    /** The company row this contact belongs to, once resolved. */
+    companyId?: string;
     address?: string;
+    /** Display form: the resource exactly as entered or as the provider delivered it. */
     endpoints?: ContactEndpoint[];
+    /**
+     * Canonical, indexable mirror of `endpoints`, produced by `endpointKey` on every
+     * write. `endpoints[]` is an array of objects and therefore not indexable, which is
+     * why the old lookup was an unindexed `$elemMatch` scan. Read and write side must use
+     * the same normaliser or the index is structurally a miss.
+     */
+    keys?: string[];
+    /** Namespaced source references (`ms:AAMk…`, `google:people/c123`, `hubspot:42`). */
+    externalIds?: string[];
+    origin?: ContactOrigin;
+    /** When a shadow row last saw its source. There is no refresh job; touching refreshes. */
+    syncedAt?: number;
 }

package/dist/entities/contact-source/index.d.ts

@@ -0,0 +1 @@
+export * from './types';

package/dist/entities/contact-source/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Which sources this organisation uses to search for and enrich contacts.
+ *
+ * Named `...Config` because `ContactSource` already means something else on a contact: its
+ * provenance (`{ providerId, externalId, readOnly }`). This is the register row.
+ *
+ * The one configuration surface of the contact layer. Deliberately *not* a tool name
+ * inside a playbook step: MCP tool names are `mcp__<server row id>__<tool>` and therefore
+ * per-organisation random, a shipped step could never name one, and playbook steps are
+ * snapshotted onto runs so changing a source would leave parked runs on the old one.
+ *
+ * Note what is NOT configurable here: personal versus organisation-wide. That follows from
+ * *who is asking* — an interactive search runs with the user's delegated tokens and may use
+ * their personal connections, an unattended job has no user and cannot, both because
+ * `SYSTEM_TOOL_POLICY` filters personal tools and because the Graph API refuses `/me/*`
+ * without a user token.
+ */
+export interface ContactSourceConfig {
+    /**
+     * Either a built-in source id (`microsoft-directory`, `google`, `eylo-voip`, `local`)
+     * or an AI tool name (`mcp__<id>__search_companies`).
+     *
+     * A field VALUE, never an object key: the SDK client deep-mangles object keys between
+     * camel and snake case, which would corrupt any namespaced name used as a key.
+     */
+    sourceId: string;
+    kind: "internal" | "mcp";
+    /** Take part in the interactive launcher / composer search. */
+    search: boolean;
+    /** Take part in the background enrichment of interactions. */
+    enrich: boolean;
+    order: number;
+}
+/** A source as the settings page sees it: config merged with what is actually available. */
+export interface ContactSourceEntry extends ContactSourceConfig {
+    label: string;
+    /** `platform` = shipped default, `org` = the organisation added it. */
+    origin: "platform" | "org";
+    /**
+     * True when the source is configured but its tool is gone — an MCP server that was
+     * disconnected. Surfaced rather than silently skipped, because a source that quietly
+     * stops answering looks exactly like a customer who is not in the CRM.
+     */
+    broken?: boolean;
+}
+export interface ContactSourceCatalog {
+    sources: ContactSourceEntry[];
+    /** Master switch for background enrichment. Absent means on. */
+    enrichmentEnabled: boolean;
+    /**
+     * Bumped on every change to the register. Used as the generation token of the negative
+     * cache, so a number that was unknown before gets a fresh chance once the organisation
+     * connects a new source — expiry on time alone would never do that.
+     */
+    generation: string;
+}

package/dist/entities/interaction/types.d.ts

@@ -80,6 +80,21 @@ export interface Interaction {
      * en meetings hier de volledige lijst inclusief rollen (cc/bcc/organizer/…).
      */
     participants?: InteractionParticipant[];
+    /**
+     * Canonieke identiteitssleutels van de tegenpartij — de andere helft van `channelUriKey`,
+     * dat onze eigen kant canonicaliseert. Geïndexeerd, zodat "elk gesprek met dit adres, dit
+     * nummer of dit domein" een indexvraag is en geen scan.
+     *
+     * Bevat `mailto:`/`tel:`-sleutels, een `domain:<registreerbaar>`-pseudosleutel voor
+     * niet-publieke e-maildomeinen, en `company:<id>`/`contact:<id>` wanneer een mens een
+     * koppeling expliciet heeft gelegd.
+     *
+     * **Een sleutel wordt nooit onwaar.** "Dit adres kwam voor in dit gesprek" blijft altijd
+     * gelden, terwijl een afgeleide `companyId` onwaar wordt zodra iemand een bedrijf aanmaakt,
+     * samenvoegt of corrigeert — en dan backfill zou vragen. Los een identiteit bij het lezen op
+     * naar zijn sleutels en het antwoord omvat ook gesprekken van vóór die identiteit bestond.
+     */
+    partyKeys?: string[];
     source?: InteractionSource;
     tags: string[];
     links: InteractionLink[];

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

@@ -0,0 +1,19 @@
+import { MemorySubjectKey } from './item';
+/**
+ * Twee subjects die hetzelfde blijken te zijn (een merge van interacties, later een echte
+ * identiteitslaag). Het geheugen verhuist niet: de alias wordt bij het lezen opgelost.
+ *
+ * **Eén niveau diep by construction**: een alias wiens `canonical` zelf een alias is wordt
+ * geweigerd bij het schrijven. Resolutie is daarmee twee queries en nooit recursief — geen
+ * cyclus-detectie, geen diepte-limiet, geen verrassing op het hete pad.
+ */
+export interface MemorySubjectAlias {
+    id: string;
+    organizationId: string;
+    /** Het subject dat is opgegaan in `canonical`. Unique per org. */
+    subject: MemorySubjectKey;
+    canonical: MemorySubjectKey;
+    /** De app die de samenvoeging meldde. */
+    source: string;
+    createdAt?: number;
+}

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

@@ -0,0 +1,5 @@
+export * from './alias';
+export * from './ingest';
+export * from './item';
+export * from './kind';
+export * from './query';

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

@@ -0,0 +1,61 @@
+import { MemoryKindId, MemoryLink, MemorySubjectKey } from './item';
+/**
+ * Schrijven is een **CAS-upsert**, geen snapshot-replace zoals 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.
+ */
+export interface MemoryUpsertRequest {
+    organizationId: string;
+    /** De schrijvende app; de hub vult dit uit `req.source.app` en vertrouwt de body hier niet. */
+    source: string;
+    subject: MemorySubjectKey;
+    kind: MemoryKindId;
+    /** Default bij `cardinality: "single"`: `"<kind>:<subject>"`. */
+    sourceRef?: string;
+    title: string;
+    body: string;
+    occurredAt?: number;
+    /** Watermerk van het bron-event dat deze schrijfactie veroorzaakte. */
+    throughRef?: string;
+    throughAt?: number;
+    /** Mismatch => `accepted: false` met `reason: "stale-version"`; de caller herplant. */
+    expectedVersion?: number;
+    audienceRef?: string;
+    locale?: string;
+    /** Weglaten: de hub extraheert keywords zelf uit titel + body (één tokenizer, schrijf én lees). */
+    keywords?: string[];
+    tags?: string[];
+    links?: MemoryLink[];
+}
+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. */
+    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.
+ */
+export interface MemoryReplaceRequest {
+    organizationId: string;
+    source: string;
+    subject: MemorySubjectKey;
+    kind: MemoryKindId;
+    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`.
+ */
+export interface MemoryPurgeRequest {
+    organizationId: string;
+    source: string;
+    subjects: MemorySubjectKey[];
+}

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

@@ -0,0 +1,112 @@
+/**
+ * De geheugenlaag (`apps/context`): één durende laag per **subject**, waarbij de
+ * organisatie zelf per event bepaalt wat er onthouden wordt.
+ *
+ * `Memory*` en niet `Context*`: `platform/context.ts` exporteert al `HostContext` en
+ * `context.collect` (vluchtige route-context) uit dezelfde platte barrel.
+ */
+/** Een bestaande scopeKey: `interaction:i_1`, `contact:c_9`. Een latere identiteitslaag is gewoon een ander prefix. */
+export type MemorySubjectKey = string;
+/** `comms.resolution` (app-gedeclareerd) of `sales_besluitvormer` (org-eigen). */
+export type MemoryKindId = string;
+/**
+ * Een verwijzing naar iets anders — intern (`interaction:i_2`) of extern
+ * (`hubspot:5591`, `clickup:86ab2`).
+ *
+ * Een **lijst**, nooit een object met de relatie als key: de app-sdk http-client
+ * mangelt elke object-key camel<->snake, dus `{ "crm.company": "..." }` komt verminkt
+ * aan de andere kant aan.
+ */
+export interface MemoryLink {
+    rel: string;
+    target: string;
+}
+/** Harde grens op de body. Geheugen is een samenvatting; een mailbox-schaduwkopie is het niet. */
+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.
+     *
+     * 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.
+     *
+     * **`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.
+     *
+     * 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.
+     *
+     * `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.
+     */
+    keys?: string[];
+    kind: MemoryKindId;
+    title: string;
+    /** DE inhoud: markdown, begrensd op {@link MAX_MEMORY_CHARS}. Nooit een genest object. */
+    body: string;
+    /** Schrijvende app (== `req.source.app`); playbook-schrijfacties komen binnen als "ai". */
+    source: string;
+    /** Identiteit binnen (subject, kind) voor de bron. Bij `cardinality: "single"` de vouw-sleutel. */
+    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.
+     */
+    throughRef?: string;
+    throughAt?: number;
+    /** Optimistic concurrency; de hub doet compare-and-swap op dit veld. */
+    version: number;
+    /** Overgenomen uit de kind-definitie, niet uit de call — zie `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.
+     */
+    audienceRef?: string;
+    /**
+     * Taal van de inhoud. **Beschrijvend, geen filter** — en dat is een besluit, geen omissie.
+     *
+     * 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.
+     *
+     * Zet je dit ooit echt, houd het dan een *ordenings*-signaal (materiaal in je eigen taal is
+     * makkelijker te gebruiken) en geen zichtbaarheidsfilter.
+     */
+    locale: string;
+    /** Gedenormaliseerde termen: het enige selectieve structurele filter (er is geen substring-operator). */
+    keywords?: string[];
+    /** Snelle alternatieve sleutels, bv. `tel:+31612345678` voor het rinkelmoment. */
+    tags?: string[];
+    links?: MemoryLink[];
+    /** Model waarmee de vector is gemaakt; retrieval vergelijkt alleen binnen hetzelfde model. */
+    embeddingModel?: string;
+    /** Uit een live pull (fase 3); nooit gepersisteerd. */
+    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?").
+ *
+ * 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.
+ */
+export type MemoryVisibility = "audience" | "org";

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

@@ -0,0 +1,66 @@
+import { LocaleBundle } from '../analytics/dashboard';
+import { OwnerScope } from '../contact/types';
+import { MemoryKindId, MemoryVisibility } from './item';
+/**
+ * Wat er onthouden mág worden, en met welke regels.
+ *
+ * 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.
+ *
+ * `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.
+ */
+export interface MemoryKindDefinition {
+    /** Org-eigen: `[a-z0-9_]+` (geen punt — die leest als een genest form-pad). App-eigen: `<app>.<naam>`. */
+    id: MemoryKindId;
+    label: string;
+    description?: string;
+    /** Subject-soorten waarop dit kind mag landen, bv. `["interaction"]` of `["contact"]`. */
+    subjectKinds: string[];
+    visibility: MemoryVisibility;
+    /** `"single"` = één item per (subject, kind), doorvouwen. `"many"` = losse items. */
+    cardinality: "single" | "many";
+    /** Ordening onder het tekenbudget van de bundel. */
+    priority: number;
+    /** Mag dit kind in het cross-subject-pad meedoen? Alleen zinvol bij `visibility: "org"`. */
+    crossSubjectSearchable: boolean;
+    /** Embedden kost geld; per kind aan/uit. */
+    embed: boolean;
+    retentionDays?: number;
+    /** Rang-multiplier: een opgeloste casus verslaat een losse notitie. Default 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.
+     */
+    ownerScope?: OwnerScope;
+    /** Wie hem declareerde. De org kan een app-kind niet oprekken, alleen uitzetten. */
+    origin: "app" | "org";
+    enabled: boolean;
+}
+/**
+ * Bare payload van `GET /provider/memory/describe` — **niet** in `ResponseFactory`
+ * verpakt (mal: `AnalyticsSourceDescription`).
+ */
+export interface MemorySourceDescription {
+    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    source: string;
+    kinds: MemoryKindDefinition[];
+    /** Vlakke LIJST: keys met een punt worden gemangeld. */
+    locales?: LocaleBundle;
+    /** Fase 3: welke subjects/kinds deze bron live kan leveren. */
+    live?: {
+        subjectKinds: string[];
+        kinds: MemoryKindId[];
+    };
+}
+/** De samengestelde catalogus die de hub aan de frontend levert (`GET /kinds`). */
+export interface MemoryKindCatalog {
+    /** App-gedeclareerd + org-eigen, gemengd. */
+    kinds: MemoryKindDefinition[];
+    /** Bronnen die meededen aan de fan-out (voor "wie levert dit?"). */
+    sources: string[];
+    locales: LocaleBundle;
+}

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

@@ -0,0 +1,113 @@
+import { MemoryItem, MemoryKindId, MemorySubjectKey } from './item';
+/** Grenzen van het tekenbudget van een bundel. Buiten bereik wordt geklemd, niet geweigerd. */
+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.
+ */
+export interface MemoryQuery {
+    /** Weglaten = cross-subject zoeken ("vergelijkbare cases"). */
+    subject?: MemorySubjectKey;
+    /** Extra subjects die bij hetzelfde beeld horen, bv. het contact naast de interactie. */
+    alsoSubjects?: MemorySubjectKey[];
+    /**
+     * Ook items die niet ópt subject staan maar er wél bij horen: alles wat dezelfde
+     * dossiersleutel draagt (`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.
+     *
+     * **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.
+     *
+     * Vereist een anker (`subject`); zonder anker is dit het cross-subject-pad.
+     */
+    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. */
+    text?: string;
+    since?: number;
+    limit?: number;
+    /** Zo bedoel je "bij ANDERE klanten". */
+    excludeSubjects?: MemorySubjectKey[];
+    format?: "items" | "bundle" | "both";
+    /** Geklemd op [{@link MIN_MEMORY_BUDGET}, {@link MAX_MEMORY_BUDGET}]. */
+    budget?: number;
+    /** Fase 3: ook live bronnen bevragen, met harde timeout en eigen 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare const RELATED_SUBJECT_KINDS: readonly ["contact", "company"];
+/** Hoort {@link MemoryQuery.related} standaard aan te staan voor dit 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? */
+    matched: {
+        keyword: number;
+        semantic: number;
+        recency: number;
+    };
+}
+export interface MemoryQueryResult {
+    hits: MemoryHit[];
+    bundle?: string;
+    /** Hoeveel rijen het structurele voorfilter opleverde. */
+    scanned: number;
+    /** Scan-cap geraakt OF hits uit de bundel gevallen — nooit stil afkappen. */
+    truncated?: boolean;
+    /** `false` = keyword-only (geen embedding-account, of geen enkele vergelijkbare vector). */
+    semantic: boolean;
+    /** Hits die de her-autorisatie van de top-K niet overleefden. */
+    withheld?: number;
+    /**
+     * Kandidaten die op het cross-subject-pad afvielen op de absolute gelijkenisdrempel.
+     *
+     * 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.
+     */
+    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.
+     */
+    vectorSkipped?: number;
+    /**
+     * Waarom er niets terugkwam, als dat een structurele reden heeft in plaats van "niets
+     * gevonden".
+     *
+     * `"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.
+     */
+    reason?: "no-cross-subject-kinds" | "no-subject-access";
+}

package/dist/entities/organization/types.d.ts

@@ -36,6 +36,13 @@ export interface Organization {
     billing?: OrganizationBilling;
     /** Small company logo stored inline as a base64 data-URI. */
     logo?: string;
+    /**
+     * ISO 3166-1 alpha-2 region used to turn a national phone number into E.164
+     * (`088 211 2121` → `+31882112121`). Absent falls back to `DEFAULT_PHONE_REGION`.
+     * Belongs on the organisation and not in code: hardcoding `+31` is wrong for an
+     * org with Belgian numbers. See `toE164` in `text/endpoint.ts`.
+     */
+    defaultPhoneRegion?: string;
 }
 /**
  * Recursive tenant hierarchy node returned by `system.tenants/tree`.

package/dist/entities/playbook/trigger-vars.d.ts

@@ -40,6 +40,18 @@ export declare const TRIGGER_VARS: readonly [{
 }, {
     readonly name: "textRaw";
     readonly type: "string";
+}, {
+    readonly name: "fromStatus";
+    readonly type: "string";
+}, {
+    readonly name: "toStatus";
+    readonly type: "string";
+}, {
+    readonly name: "contactId";
+    readonly type: "string";
+}, {
+    readonly name: "companyId";
+    readonly type: "string";
 }];
 /** De variabelen die een classify-stap oplevert, per mode. */
 export declare const CLASSIFY_VARS: {

package/dist/entities/playbook/types.d.ts

@@ -14,6 +14,19 @@ export type PlaybookTrigger = {
     /** Specific channel ids (e.g. per mailbox). Matched against activity.channelId. */
     channelIds?: string[];
     filter?: unknown;
+    /**
+     * Wacht dit aantal milliseconden en draai dan **één** run voor de berichten in dat
+     * venster, in plaats van een run per bericht.
+     *
+     * Voor een playbook dat bij elk bericht een modelcall doet is dit het verschil tussen
+     * vier calls en één bij een mailwisseling van vier berichten in tien minuten. De run
+     * draait op het **nieuwste** bericht uit het venster; wat ertussen zat is in de
+     * samenvatting van dat gesprek al meegenomen via de lookup-stap.
+     *
+     * Bewust op de trigger en niet in de geheugenlaag: coalesceren is een eigenschap van
+     * "hoe vaak wil ik hierop reageren", niet van wat je onthoudt.
+     */
+    debounceMs?: number;
 } | {
     kind: "manual";
 };
@@ -59,6 +72,15 @@ export interface ClassifyStep {
     question?: string;
     fields?: unknown;
     instruction?: string;
+    /**
+     * Wélke tekst geclassificeerd wordt, als `$ref` in de run-vars. Default `$trigger.text`.
+     *
+     * Nodig zodra de trigger zelf geen tekst draagt. Een `INTERACTION_STATUS_CHANGED`-activity
+     * heeft alleen `{ fromStatus, toStatus }` in zijn payload, dus `trigger.text` is leeg — en
+     * dan krijgt het model een lege invoer. Met `input: "$thread"` leest de stap wat een
+     * eerdere `lookup` heeft opgehaald, zoals de berichten van het gesprek.
+     */
+    input?: string;
 }
 export interface GenerateStep {
     type: "generate";