@opencxh/domain 1.171.0 → 1.172.2

package/dist/entities/resource-reminder/types.d.ts

@@ -1,10 +1,9 @@
 /**
- * Persoonlijke "kom hier later op terug"-markering op een resource, per
- * (resourceType, resourceId, userId) - dezelfde ResourceRef-vorm die read-state
- * gebruikt.
+ * A personal "come back to this later" marker on a resource, per (resourceType, resourceId,
+ * userId) - the same ResourceRef shape read-state uses.
  *
- * Anders dan een snooze raakt dit de resource zelf niet: het team blijft het
- * gesprek gewoon in zijn lijst zien, alleen jouw aandachtsstapel slaat het over.
+ * Unlike a snooze this does not touch the resource itself: the team keeps seeing the conversation
+ * in its list, only your attention stack skips it.
  */
 export interface ResourceReminder {
     id: string;
@@ -12,12 +11,12 @@ export interface ResourceReminder {
     resourceId: string;
     userId: string;
     organizationId: string;
-    /** Epoch-ms waarop het item weer in beeld mag komen. */
+    /** Epoch ms at which the item may come back into view. */
     remindAt: number;
     /**
-     * Epoch-ms waarop geparkeerd werd. Bepaalt of latere activiteit de
-     * herinnering opheft - expliciet veld, niet het framework-`updatedAt`, zodat
-     * de vervalregel deterministisch en testbaar is.
+     * Epoch ms at which it was parked. Decides whether later activity lifts the reminder - an
+     * explicit field and not the framework `updatedAt`, so the expiry rule stays deterministic and
+     * testable.
      */
     parkedAt: number;
     createdAt?: number;

package/dist/entities/scope/actor.d.ts

@@ -0,0 +1,16 @@
+import { ActingIdentity } from '../../platform/identity';
+import { OwnerScope } from './types';
+/**
+ * An owner scope as the identity that acts for it.
+ *
+ * Storage calls the personal rung `personal`, execution calls it `user`, and `org`
+ * carries an id on one side and not on the other. This is that translation, and it is
+ * meant to be the only one: a hand-rolled `kind === "personal" ? "user" : …` at a call
+ * site is how two vocabularies for the same three rungs drift apart.
+ *
+ * It arrived as `playbookActor` in `entities/playbook/`, whose own docstring already
+ * claimed to be "the only place this belongs" — correct, but it read as
+ * playbook-specific while every scoped entity needs the same conversion. `playbookActor`
+ * stays as a name so the playbook call sites and their tests keep working.
+ */
+export declare function toActingIdentity(scope: OwnerScope): ActingIdentity;

package/dist/entities/{note → scope}/index.d.ts

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

package/dist/entities/scope/scope.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,53 @@
+/**
+ * One vocabulary for "whose is this".
+ *
+ * ## Why this is its own module
+ *
+ * `OwnerScope` lived in `entities/contact/types.ts`, and nineteen other entities —
+ * work, task, topic, playbook, artifact, calendar-event, time-entry, memory, … —
+ * imported the platform's scoping primitive *from the contact entity*. Nothing was
+ * broken by that; it just meant the answer to "which type do I use to say who owns
+ * this" was somewhere nobody would look, and a new entity picked whatever it found
+ * first. The audit counted six different spellings in use.
+ *
+ * ## The field-name convention
+ *
+ * **The field is always called `ownerScope`.** `scope` is reserved for OAuth scopes,
+ * which are an unrelated concept that happens to share the word — `AiBudget.scope` is
+ * the one place that still deviates.
+ *
+ * ## The three rungs, and the fourth spelling
+ *
+ * Storage says `personal` / `team` / `org`. The execution side —
+ * {@link ActingIdentity} in `platform/identity.ts` — says `user` / `team` / `org`, and
+ * its `org` carries no id because the tenant is already in context there. Those are
+ * genuinely two vocabularies for two layers, not an accident, and the bridge between
+ * them is `toActingIdentity` next door. That function is the **only** place the
+ * translation belongs; a hand-rolled `kind === "personal" ? "user" : …` at a call site
+ * is how the two drift apart.
+ */
+export type OwnerScope = {
+    kind: "personal";
+    userId: string;
+} | {
+    kind: "team";
+    teamId: string;
+} | {
+    kind: "org";
+    organizationId: string;
+};
+/**
+ * A scope that cannot be personal.
+ *
+ * For records that are shared by definition: a topic one person can see cannot be read
+ * by the colleague who takes over the conversation, and the same goes for an AI profile
+ * or a work type. Those rules exist today as prose in the entity's docstring, with the
+ * type still permitting `personal` — which means nothing enforces them.
+ *
+ * Applying this to an existing entity is a type *tightening*, so it can surface rows
+ * that already violate the rule. Query for personal-scoped rows first; that is why it
+ * is offered here rather than applied everywhere at once.
+ */
+export type OrgTeamScope = Exclude<OwnerScope, {
+    kind: "personal";
+}>;

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

@@ -1,4 +1,4 @@
-import { OwnerScope } from '../contact/types';
+import { OwnerScope } from '../scope/types';
 export type TaskStatus = "open" | "in_progress" | "done" | "cancelled";
 export type TaskPriority = "low" | "normal" | "high" | "urgent";
 export type TaskInitiator = "user" | "system";

package/dist/entities/time-entry/duration.d.ts

@@ -1,22 +1,22 @@
 import { TimeEntry, TimeRounding } from './types';
 /**
- * De verstreken tijd van een regel, in seconden.
+ * The elapsed time of an entry, in seconds.
  *
- * In `domain` en niet in de app-server, omdat client én server hetzelfde antwoord moeten geven:
- * de server stempelt de duur bij het stoppen, het paneel laat 'm ondertussen elke seconde
- * oplopen. Zou het paneel zelf tellen vanaf een eigen nulpunt, dan loopt de zichtbare klok weg
- * van wat er uiteindelijk geboekt wordt zodra een tabblad even slaapt.
+ * In `domain` and not in the app server, because client and server have to give the same answer:
+ * the server stamps the duration on stop, the panel counts it up every second in the meantime. If
+ * the panel counted from a zero point of its own, the visible clock would drift from what is
+ * eventually booked as soon as a tab sleeps.
  */
 export declare function elapsedSeconds(entry: Pick<TimeEntry, "accumulatedSeconds" | "runningSince">, now: number): number;
 /**
- * De geboekte duur die bij een gemeten duur hoort.
+ * The booked duration belonging to a measured one.
  *
- * Naar boven en met een minimum van één eenheid: wie "per 15 minuten" kiest, wil dat een klus
- * van drie minuten een kwartier wordt en niet nul. Bij `exact` is de bodem één minuut, om
- * dezelfde reden — een regel van nul seconden is geen regel.
+ * Rounded up and with a minimum of one unit: whoever picks "per 15 minutes" wants a three-minute
+ * job to become a quarter of an hour and not zero. With `exact` the floor is one minute, for the
+ * same reason — an entry of zero seconds is not an entry.
  */
 export declare function applyRounding(rawSeconds: number, rounding: TimeRounding | undefined): number;
-/** `0:45` / `2:05` — uren en minuten, zoals de dagtotalen in het paneel. */
+/** `0:45` / `2:05` — hours and minutes, like the day totals in the panel. */
 export declare function formatHm(totalSeconds: number): string;
-/** `12:34` onder het uur, `1:02:03` erboven — de lopende klok. */
+/** `12:34` under the hour, `1:02:03` above it — the running clock. */
 export declare function formatClock(totalSeconds: number): string;

package/dist/entities/time-entry/types.d.ts

@@ -1,70 +1,71 @@
-import { OwnerScope } from '../contact/types';
+import { OwnerScope } from '../scope/types';
 /**
- * Waar een urenregel in zijn leven staat.
+ * Where a time entry stands in its life.
  *
- * `review` is met opzet een **server**-staat en niet iets wat alleen in het paneel leeft: het
- * ontwerp laat je na het stoppen nog afronden, een werksoort kiezen en een notitie bijwerken
- * voordat de regel telt. Zat die tussenstap alleen in de client, dan was een dichtgeslagen
- * tabblad precies het moment waarop het gewerkte uur verdampt. Nu vindt het paneel de regel bij
- * het volgende bezoek gewoon terug en staat de review-kaart er weer.
+ * `review` is deliberately a **server** state and not something living only in the panel: the
+ * design lets you round off, pick a work type and update a note after stopping, before the entry
+ * counts. If that intermediate step lived only in the client, a closed tab would be exactly the
+ * moment the worked hour evaporates. Now the panel simply finds the entry again on the next visit,
+ * review card and all.
  *
- * `logged` is de enige staat die meetelt in totalen en in de rapportage.
+ * `logged` is the only state counting towards totals and reporting.
  */
 export type TimeEntryStatus = "running" | "paused" | "review" | "logged";
-/** Hoe de gemeten tijd naar een boekbare duur wordt vertaald. */
+/** How measured time is translated into a bookable duration. */
 export type TimeRounding = "exact" | "15" | "30";
-/** Handmatig ingevoerd of daadwerkelijk geklokt — zichtbaar in de rapportage. */
+/** Entered by hand or actually clocked — visible in the reporting. */
 export type TimeEntrySource = "timer" | "manual";
 export interface TimeEntry {
     id: string;
     organizationId: string;
-    /** Wie de tijd schreef. Een regel hoort altijd bij precies één mens. */
+    /** Who wrote the time. An entry always belongs to exactly one person. */
     userId: string;
     /**
-     * Waarop geboekt wordt: `"interaction:abc"`, `"task:42"`, `"company:xyz"`. Afwezig =
-     * algemeen werk zonder object.
+     * What the time is booked on: `"interaction:abc"`, `"task:42"`, `"company:xyz"`. Absent =
+     * general work without an object.
      *
-     * Bewust een opake sleutel en geen `interactionId`: de app die de soort bezit beantwoordt
-     * de toegangsvraag (`assertScopeAccess`), dus urenregistratie hoeft geen enkele andere app
-     * te kennen om er tijd op te kunnen schrijven.
+     * Deliberately an opaque key and not an `interactionId`: the app owning the kind answers the
+     * access question (`assertScopeAccess`), so time tracking needs to know no other app at all to
+     * be able to write time against it.
      */
     scopeKey?: string;
-    /** Menselijk etiket op schrijfmoment ("Gesprek · RE: EYLO"), zodat een lijst leesbaar blijft
-     *  zonder per regel de bron-app te bevragen. */
+    /** Human label at write time ("Gesprek · RE: EYLO"), so a list stays readable without
+     *  querying the source app per row. */
     scopeLabel?: string;
-    /** Dossiersleutels van de resource, platgeslagen bij schrijven — zie de `keys`-conventie. */
+    /** File keys of the resource, flattened at write time — see the `keys` convention. */
     keys?: string[];
-    /** Eigenaarschap zoals de bron-app het ziet; bepaalt wie de regel in een teamweergave ziet. */
+    /** Ownership as the source app sees it; decides who sees the entry in a team view. */
     ownerScope?: OwnerScope;
     status: TimeEntryStatus;
-    /** Epoch ms, gezet door de server. De client rekent alleen af hoe laat het nu is. */
+    /** Epoch ms, set by the server. The client only works out what time it is now. */
     startedAt: number;
-    /** Epoch ms; gezet zodra de timer stopt. Afwezig zolang hij loopt of gepauzeerd staat. */
+    /** Epoch ms; set as soon as the timer stops. Absent while it runs or is paused. */
     endedAt?: number;
     /**
-     * Seconden die vóór het huidige segment al gebankt zijn.
+     * Seconds already banked before the current segment.
      *
-     * Pauzeren mag geen tweede rij opleveren — het ontwerp belooft één regel per klus, met een
-     * pauzeknop erin. Daarom telt de server bij elke pauze het gelopen segment hierbij op en
-     * laat `runningSince` los; hervatten zet alleen `runningSince` opnieuw. De verstreken tijd
-     * is dus altijd `accumulatedSeconds + (runningSince ? now - runningSince : 0)`, en dat
-     * antwoord is hetzelfde op elk apparaat.
+     * Pausing must not produce a second row — the design promises one entry per job, with a pause
+     * button in it. So on every pause the server adds the elapsed segment here and releases
+     * `runningSince`; resuming only sets `runningSince` again. Elapsed time is therefore always
+     * `accumulatedSeconds + (runningSince ? now - runningSince : 0)`, and that answer is the same on
+     * every device.
      */
     accumulatedSeconds: number;
-    /** Epoch ms waarop het lopende segment begon. Afwezig = gepauzeerd of gestopt. */
+    /** Epoch ms the running segment started at. Absent = paused or stopped. */
     runningSince?: number;
-    /** Wat de klok werkelijk mat. Blijft staan als afronding de geboekte duur optrekt. */
+    /** What the clock actually measured. Stays when rounding pulls the booked duration up. */
     rawSeconds?: number;
     /**
-     * De geboekte duur in seconden — dít telt in totalen en facturatie.
+     * The booked duration in seconds — *this* is what counts in totals and invoicing.
      *
-     * Los van `rawSeconds` omdat afronding een keuze van de gebruiker is en geen meting: wie
-     * later vraagt "waar komt dat kwartier vandaan" moet de gemeten twee minuten nog kunnen zien.
+     * Separate from `rawSeconds` because rounding is a user's choice and not a measurement: whoever
+     * asks later "where does that quarter of an hour come from" must still be able to see the two
+     * minutes that were measured.
      */
     durationSeconds?: number;
     rounding?: TimeRounding;
     billable: boolean;
-    /** Verwijst naar `WorkType.key`. */
+    /** Refers to `WorkType.key`. */
     workType?: string;
     note?: string;
     source: TimeEntrySource;
@@ -72,35 +73,34 @@ export interface TimeEntry {
     updatedAt?: number;
 }
 /**
- * Een beheerbare werksoort in plaats van een rijtje in code: welke soorten een organisatie
- * kent verschilt per bedrijf, en de soort bepaalt of iets standaard declarabel is.
+ * A manageable work type instead of a list in code: which types an organisation knows differs per
+ * company, and the type decides whether something is billable by default.
  */
 export interface WorkType {
     id: string;
     organizationId: string;
     /**
-     * Stabiele sleutel die op de urenregel belandt.
+     * Stable key that lands on the time entry.
      *
-     * Uniek binnen de organisatie en niet binnen de scope, hoewel de soort een team kan
-     * toebehoren: `TimeEntry.workType` bewaart alléén deze sleutel en de rapportage groepeert
-     * erop. Twee teams met elk een eigen `installatie` zouden daar als één regel uitkomen, met
-     * twee betekenissen erin.
+     * Unique within the organisation and not within the scope, even though a type can belong to a
+     * team: `TimeEntry.workType` stores only this key and the reporting groups on it. Two teams each
+     * with their own `installatie` would come out as one row there, carrying two meanings.
      */
     key: string;
     label: string;
-    /** Standaardwaarde voor `TimeEntry.billable`; per regel te overrulen. */
+    /** Default for `TimeEntry.billable`; overridable per entry. */
     defaultBillable: boolean;
-    /** Meegenomen als dimensie in de rapportage. */
+    /** Included as a dimension in the reporting. */
     reportable?: boolean;
     order?: number;
     archived?: boolean;
     /**
-     * Van wie deze soort is: de hele organisatie of één team. Bepaalt wie hem in zijn
-     * urenpaneel ziet en wie hem mag beheren.
+     * Whose type this is: the whole organisation or one team. Decides who sees it in their time
+     * panel and who may manage it.
      *
-     * Geen `personal`, om dezelfde reden als bij `Topic`: een soort die maar één mens kent,
-     * maakt het geboekte uur onleesbaar voor de collega die de week overneemt. Afwezig telt als
-     * org-breed — dat is wat elke soort vóór dit veld feitelijk was.
+     * No `personal`, for the same reason as with `Topic`: a type only one person knows makes the
+     * booked hour unreadable for the colleague taking over the week. Absent counts as org-wide —
+     * which is what every type effectively was before this field.
      */
     ownerScope?: Extract<OwnerScope, {
         kind: "org";
@@ -111,10 +111,10 @@ export interface WorkType {
     updatedAt?: number;
 }
 /**
- * Wat het beheerscherm naar de server stuurt.
+ * What the admin screen sends to the server.
  *
- * Zonder `id` is het een nieuwe soort. `key` staat er met opzet niet in: die leidt de server af
- * uit de naam en ligt daarna vast, omdat geboekte uren ernaar verwijzen.
+ * Without an `id` it is a new type. `key` is deliberately absent: the server derives it from the
+ * name and it is fixed afterwards, because booked hours refer to it.
  */
 export interface SaveWorkTypeRequest {
     id?: string;
@@ -125,13 +125,13 @@ export interface SaveWorkTypeRequest {
     archived?: boolean;
     ownerScope?: WorkType["ownerScope"];
 }
-/** Een kandidaat waarop de gebruiker kan klokken, aangeboden in de leegstaat van het paneel. */
+/** A candidate the user can clock on, offered in the panel's empty state. */
 export interface TimeTarget {
     scopeKey?: string;
-    /** Soortlabel boven de titel ("GESPREK OP JE SCHERM", "TAAK"). */
+    /** Kind label above the title ("GESPREK OP JE SCHERM", "TAAK"). */
     kindLabel: string;
     title: string;
-    /** Lucide-icoonnaam. */
+    /** Lucide icon name. */
     icon: string;
     keys?: string[];
 }
@@ -142,14 +142,14 @@ export interface StartTimerRequest {
     workType?: string;
     note?: string;
 }
-/** Wat er bij het opslaan van een regel nog aan te passen valt. */
+/** What can still be adjusted when saving an entry. */
 export interface SaveTimeEntryRequest {
     id: string;
     rounding?: TimeRounding;
     workType?: string;
     billable?: boolean;
     note?: string;
-    /** Naar een ander object boeken dan waar de timer op startte. */
+    /** Book against a different object than the timer started on. */
     scopeKey?: string;
     scopeLabel?: string;
     keys?: string[];
@@ -158,18 +158,18 @@ export interface ManualTimeEntryRequest {
     scopeKey?: string;
     scopeLabel?: string;
     keys?: string[];
-    /** Epoch ms; de dag waarop de regel valt. */
+    /** Epoch ms; the day the entry falls on. */
     startedAt: number;
     durationSeconds: number;
     workType?: string;
     billable?: boolean;
     note?: string;
 }
-/** Wat het paneel in één keer ophaalt: de lopende timer plus de dag eromheen. */
+/** What the panel fetches in one go: the running timer plus the day around it. */
 export interface TimeDaySummary {
-    /** De regel die nu loopt, gepauzeerd staat of op afronding wacht — er is er hooguit één. */
+    /** The entry running, paused or awaiting review right now — there is at most one. */
     active?: TimeEntry;
-    /** Afgeronde regels van de opgevraagde dag, oplopend op starttijd. */
+    /** Finished entries of the requested day, ascending on start time. */
     entries: TimeEntry[];
     totalSeconds: number;
     billableSeconds: number;

package/dist/entities/time-entry/work-type.d.ts

@@ -1,44 +1,41 @@
 import { WorkType } from './types';
 /**
- * De sleutel die bij een naam hoort: kleine letters, streepjes, geen accenten.
+ * The key belonging to a name: lowercase, hyphens, no accents.
  *
- * In `domain` en niet in de app-server omdat het beheerscherm hem al tijdens het typen laat
- * zien — wat de gebruiker daar ziet moet exact zijn wat de server straks wegschrijft, anders
- * belooft het formulier `installatie-op-locatie` en staat er `installatieoplocatie` in de
- * rapportage.
+ * In `domain` and not in the app server because the admin screen shows it while you type — what
+ * the user sees there has to be exactly what the server writes later, or the form promises
+ * `installatie-op-locatie` and the reporting says `installatieoplocatie`.
  *
- * `normalize("NFD")` plus het weghalen van de combineertekens, zodat "Béta" `beta` wordt en niet
- * `b-ta`: een leesbare sleutel is het halve doel.
+ * `normalize("NFD")` plus stripping the combining marks, so "Béta" becomes `beta` and not `b-ta`:
+ * a readable key is half the point.
  */
 export declare function workTypeKey(label: string): string;
 /**
- * Dezelfde sleutel, maar gegarandeerd nog vrij binnen de organisatie.
+ * The same key, but guaranteed still free within the organisation.
  *
- * Botsingen zijn echt: de sleutel is org-uniek terwijl soorten per team beheerd worden, dus twee
- * teams die allebei "Installatie" aanmaken komen hier uit. De tweede krijgt `installatie-2` in
- * plaats van een foutmelding — een beheerder die een naam kiest, hoort niet te struikelen over
- * een sleutel die hij nooit heeft gezien.
+ * Collisions are real: the key is org-unique while types are managed per team, so two teams both
+ * creating "Installatie" end up here. The second gets `installatie-2` instead of an error — an
+ * admin picking a name should not trip over a key they never saw.
  *
- * `taken` bevat óók gearchiveerde sleutels: die staan nog op geboekte uren, dus hergebruiken zou
- * oud werk stilzwijgend onder een nieuwe soort schuiven.
+ * `taken` also holds archived keys: those still sit on booked hours, so reusing one would silently
+ * shift old work under a new type.
  */
 export declare function uniqueWorkTypeKey(label: string, taken: Iterable<string>): string;
 /**
- * Ziet deze gebruiker deze soort?
+ * Does this user see this type?
  *
- * Een soort zonder scope is org-breed: rijen zijn ouder dan het veld, en ze wegfilteren zou een
- * bestaande organisatie zijn hele lijst kosten.
+ * A type without a scope is org-wide: rows are older than the field, and filtering them out would
+ * cost an existing organisation its whole list.
  */
 export declare function isWorkTypeVisible(workType: Pick<WorkType, "ownerScope">, teamIds: string[]): boolean;
 /**
- * Wat het paneel toont: niet-gearchiveerd, in de juiste volgorde.
+ * What the panel shows: not archived, in the right order.
  *
- * Zonder team-argument, en dat is met opzet: de server heeft de teamzichtbaarheid al afgekapt
- * voordat de lijst de client bereikt (dat is een rechtenvraag). Zou de client hier nóg eens op
- * `teamIds` filteren, dan moest hij het lidmaatschap van de gebruiker kennen — en met een lege
- * lijst, zoals hij hem nu heeft, zou hij precies de teamsoorten wegfilteren die de server net
- * heeft goedgekeurd.
+ * Without a team argument, deliberately: the server already cut team visibility off before the
+ * list reaches the client (that is a permission question). If the client filtered on `teamIds`
+ * again here it would have to know the user's memberships — and with an empty list, as it has one
+ * now, it would filter out precisely the team types the server just approved.
  */
 export declare function activeWorkTypes(workTypes: WorkType[]): WorkType[];
-/** De volgorde van de chips: `order` eerst, gelijke waarden alfabetisch zodat hij stabiel is. */
+/** The order of the chips: `order` first, ties alphabetical so it stays stable. */
 export declare function compareWorkTypes(a: WorkType, b: WorkType): number;

package/dist/entities/topic/examples.d.ts

@@ -1,46 +1,45 @@
 import { Topic, TopicExampleCandidate } from './types';
 /**
- * De vorm waarop twee voorbeelden "hetzelfde" zijn.
+ * The shape in which two examples are "the same".
  *
- * Alleen voor vergelijken, nooit voor opslaan: wat de beheerder ziet is de originele tekst.
- * Tien keer "Ik wil mijn factuur" leert de classifier niets en verdringt wel een voorbeeld dat het
- * wél zou doen, dus hoofdletters, leestekens en dubbele spaties mogen dat niet verhullen.
+ * For comparing only, never for storing: what the admin sees is the original text. Ten copies of
+ * "Ik wil mijn factuur" teach the classifier nothing while crowding out an example that would, so
+ * capitals, punctuation and double spaces must not hide that.
  */
 export declare function normalizeExample(text: string): string;
-/** Afkappen op een hele zin waar dat kan, anders hard op de grens. */
+/** Truncate on a whole sentence where possible, otherwise hard at the limit. */
 export declare function truncateExample(text: string): string;
 /**
- * Een voorstel toevoegen. Geeft de nieuwe kandidatenlijst terug, of `null` als er niets te
- * veranderen viel — de caller slaat dan geen schrijfactie op.
+ * Add a suggestion. Returns the new candidate list, or `null` when there was nothing to change —
+ * the caller then stores no write.
  *
- * Drie redenen om `null` te geven, en ze zijn alle drie gewoon:
- * 1. Lege tekst. Een gesprek zonder inkomend bericht levert geen voorbeeld.
- * 2. Het staat al bij `examples`. De beheerder heeft dit al beoordeeld; het opnieuw voorstellen is
- *    ruis, en na één afwijzing zou het bij elke volgende toekenning terugkomen.
- * 3. Het staat al bij de kandidaten. Wel wordt hij dan **bijgewerkt** als de nieuwe melding een
- *    correctie is: dat is het sterkere signaal en het hoort bovenaan.
+ * Three reasons to return `null`, all three ordinary:
+ * 1. Empty text. A conversation without an inbound message yields no example.
+ * 2. It is already in `examples`. The admin already judged this; suggesting it again is noise, and
+ *    after one rejection it would come back on every next assignment.
+ * 3. It is already among the candidates. It *is* **updated** when the new report is a correction:
+ *    that is the stronger signal and belongs at the top.
  */
 export declare function addExampleCandidate(topic: Pick<Topic, "examples" | "exampleCandidates">, candidate: TopicExampleCandidate): TopicExampleCandidate[] | null;
 /**
- * Een voorstel overnemen: van de kandidatenlijst naar `examples`.
+ * Accept a suggestion: from the candidate list into `examples`.
  *
- * Draait in de **editor**, niet op de server — accepteren is een bewerking van het onderwerp en
- * gaat mee met de gewone opslag. Dat scheelt een endpoint en houdt "wat de beheerder ziet" en "wat
- * er opgeslagen wordt" één ding.
+ * Runs in the **editor**, not on the server — accepting is an edit of the topic and travels with
+ * the normal save. That saves an endpoint and keeps "what the admin sees" and "what gets stored"
+ * one thing.
  *
- * Bij een volle `examples` valt de **oudste** eruit (voorop in de lijst). Dat is niet
- * onvermijdelijk goed — de eerste voorbeelden zijn vaak met zorg getypt — maar het alternatief is
- * de beheerder een keuze voorleggen op het moment dat hij iets anders aan het doen is. De cap staat
- * in de UI vermeld.
+ * On a full `examples` the **oldest** falls out (first in the list). Not unavoidably right — the
+ * first examples are often typed with care — but the alternative is putting a choice to the admin
+ * while they are doing something else. The cap is stated in the UI.
  */
 export declare function acceptExampleCandidate(topic: Pick<Topic, "examples" | "exampleCandidates">, text: string): Pick<Topic, "examples" | "exampleCandidates">;
 /**
- * Een voorstel weggooien.
+ * Throw a suggestion away.
  *
- * Er wordt **niet** onthouden dat je hem hebt afgewezen. Verschijnt exact dezelfde zin nog eens bij
- * een handmatige toekenning, dan staat hij er weer. Bewust geen derde lijst met afgewezen teksten:
- * dat is dubbel zoveel state voor een geval dat alleen optreedt bij een generieke openingszin
- * ("Hallo, ik heb een vraag") — en dán is terugkomen ook niet gek. Hindert het toch, dan is de
- * echte oplossing hem accepteren, want daarna wordt hij nooit meer voorgesteld.
+ * Rejecting is **not** remembered. If the exact same sentence shows up again on a manual
+ * assignment, it is back. Deliberately no third list of rejected texts: that is twice the state
+ * for a case that only occurs with a generic opening line ("Hallo, ik heb een vraag") — and then
+ * coming back is not strange either. If it still bothers you, the real fix is to accept it, after
+ * which it is never suggested again.
  */
 export declare function rejectExampleCandidate(topic: Pick<Topic, "exampleCandidates">, text: string): TopicExampleCandidate[];

package/dist/entities/topic/scope.d.ts

@@ -1,20 +1,19 @@
 import { Topic } from './types';
 /**
- * Mag dit onderwerp aangeboden worden op een gesprek in een inbox van dit team?
+ * May this topic be offered on a conversation in an inbox of this team?
  *
- * Let op het woord *aangeboden*. Dit is een **keuzelijst-filter**, geen autorisatie: het
- * leesrecht is al afgehandeld door de server (`buildScopeQuery` in
- * `apps/communication/server/src/utils/scope.ts`), en wat hier binnenkomt mag de gebruiker dus
- * sowieso zien. Wat dit filter toevoegt is relevantie — Sales hoeft de onderwerpen van Support
- * niet door te scrollen.
+ * Mind the word *offered*. This is a **picker filter**, not authorization: the read right is
+ * already handled by the server (`buildScopeQuery` in
+ * `apps/communication/server/src/utils/scope.ts`), so whatever arrives here the user may see
+ * anyway. What this filter adds is relevance — Sales need not scroll past Support's topics.
  *
- * Daarom mag je hem **nooit** gebruiken om een reeds toegekend onderwerp op te zoeken. Een gesprek
- * dat van team wisselt houdt zijn etiket; dat opzoeken in de gefilterde lijst zou het label leeg
- * laten terwijl er wel degelijk een onderwerp op staat.
+ * So it must **never** be used to look up an already assigned topic. A conversation that changes
+ * team keeps its label; looking that up in the filtered list would leave the label empty while a
+ * topic is very much set.
  *
- * `personal` valt altijd af: die scope wordt bij het schrijven geweigerd, en komt er ooit toch een
- * rij zo binnen, dan hoort hij niet in een gedeelde keuzelijst.
+ * `personal` always drops out: that scope is refused at write time, and if a row ever does arrive
+ * that way, it does not belong in a shared picker.
  */
 export declare function topicOfferedForTeam(topic: Topic, teamId: string | undefined): boolean;
-/** {@link topicOfferedForTeam} over een lijst. */
+/** {@link topicOfferedForTeam} over a list. */
 export declare function topicsForTeam(topics: Topic[], teamId: string | undefined): Topic[];