@opencxh/domain 1.161.0 → 1.164.0

package/dist/entities/custom-field-def/types.d.ts

@@ -1,4 +1,17 @@
-export type CustomFieldType = "text" | "select";
+/**
+ * De soorten aangepaste velden.
+ *
+ * Begon als `text | select`, want dat was alles wat een gesprek nodig had. Werkitems vragen
+ * er meer: een dealwaarde moet als bedrag getoond worden, een doorlooptijd als duur, en een
+ * klant als verwijzing naar het bedrijvenregister in plaats van als vrije tekst.
+ *
+ * Bewust **geen** `multi_select`: {@link CustomFieldDef.multiValued} bestaat al, wordt al
+ * opgeslagen en betekent precies dat. Twee manieren om één ding te zeggen levert een
+ * renderer op met een tak die niemand onderhoudt.
+ */
+export type CustomFieldType = "text" | "textarea" | "number" | "currency" | "date" | "duration" | "select" | "user" | "checkbox"
+/** Verwijst naar een resource elders in het platform; zie {@link CustomFieldDef.refKinds}. */
+ | "resource_ref";
 /** A selectable option for a `select` field. `label` falls back to `value` when absent. */
 export interface CustomFieldOption {
     value: string;
@@ -21,10 +34,24 @@ export interface CustomFieldDef {
     options?: CustomFieldOption[];
     /** `select` only: multi-select — the stored value becomes a string[]. */
     multiValued?: boolean;
-    /** Resource kinds this field applies to, e.g. ["interaction"]. */
+    /** Resource kinds this field applies to, e.g. ["interaction"], ["work_item"]. */
     appliesTo: string[];
     /** Empty/absent = all teams; otherwise only shown when the resource belongs to one of these teams. */
     teamIds?: string[];
+    /**
+     * Voor `resource_ref`: welke scope-soorten gekozen mogen worden (`"company"`,
+     * `"contact"`, `"work_item"`). Leeg = alles wat de kiezer aanbiedt.
+     */
+    refKinds?: string[];
+    /**
+     * Welke work-projecten dit veld aanzetten. Leeg/afwezig = elk project, net als bij
+     * {@link CustomFieldDef.teamIds}.
+     *
+     * Bestaat omdat een velddefinitie platformbreed is maar een veldenset dat niet is: twee
+     * projecten mogen allebei een "Bedrag" kennen met een eigen betekenis. Additief, dus
+     * bestaande definities houden een lege lijst en blijven overal gelden.
+     */
+    projectIds?: string[];
     /**
      * When true, this field becomes an analytics dimension `comms.cf.<key>`: every conversation-level
      * metric can be grouped/filtered by its value. Opt-in to avoid turning free-text fields into

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

@@ -1,2 +1,3 @@
 export * from './duration';
 export * from './types';
+export * from './work-type';

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

@@ -78,7 +78,14 @@ export interface TimeEntry {
 export interface WorkType {
     id: string;
     organizationId: string;
-    /** Stabiele sleutel die op de urenregel belandt. */
+    /**
+     * Stabiele sleutel die op de urenregel belandt.
+     *
+     * 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.
+     */
     key: string;
     label: string;
     /** Standaardwaarde voor `TimeEntry.billable`; per regel te overrulen. */
@@ -87,9 +94,37 @@ export interface WorkType {
     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.
+     *
+     * 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.
+     */
+    ownerScope?: Extract<OwnerScope, {
+        kind: "org";
+    } | {
+        kind: "team";
+    }>;
     createdAt?: number;
     updatedAt?: number;
 }
+/**
+ * Wat het beheerscherm naar de server stuurt.
+ *
+ * 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.
+ */
+export interface SaveWorkTypeRequest {
+    id?: string;
+    label: string;
+    defaultBillable?: boolean;
+    reportable?: boolean;
+    order?: number;
+    archived?: boolean;
+    ownerScope?: WorkType["ownerScope"];
+}
 /** Een kandidaat waarop de gebruiker kan klokken, aangeboden in de leegstaat van het paneel. */
 export interface TimeTarget {
     scopeKey?: string;

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

@@ -0,0 +1,44 @@
+import { WorkType } from './types';
+/**
+ * De sleutel die bij een naam hoort: kleine letters, streepjes, geen accenten.
+ *
+ * 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.
+ *
+ * `normalize("NFD")` plus het weghalen van de combineertekens, zodat "Béta" `beta` wordt en niet
+ * `b-ta`: een leesbare sleutel is het halve doel.
+ */
+export declare function workTypeKey(label: string): string;
+/**
+ * Dezelfde sleutel, maar gegarandeerd nog vrij binnen de organisatie.
+ *
+ * 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.
+ *
+ * `taken` bevat óók gearchiveerde sleutels: die staan nog op geboekte uren, dus hergebruiken zou
+ * oud werk stilzwijgend onder een nieuwe soort schuiven.
+ */
+export declare function uniqueWorkTypeKey(label: string, taken: Iterable<string>): string;
+/**
+ * Ziet deze gebruiker deze soort?
+ *
+ * Een soort zonder scope is org-breed: rijen zijn ouder dan het veld, en ze wegfilteren zou een
+ * bestaande organisatie zijn hele lijst kosten.
+ */
+export declare function isWorkTypeVisible(workType: Pick<WorkType, "ownerScope">, teamIds: string[]): boolean;
+/**
+ * Wat het paneel toont: niet-gearchiveerd, in de juiste volgorde.
+ *
+ * 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.
+ */
+export declare function activeWorkTypes(workTypes: WorkType[]): WorkType[];
+/** De volgorde van de chips: `order` eerst, gelijke waarden alfabetisch zodat hij stabiel is. */
+export declare function compareWorkTypes(a: WorkType, b: WorkType): number;

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

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

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

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

package/dist/entities/work/keys.d.ts

@@ -0,0 +1,57 @@
+import { WorkItem, WorkProject } from './types';
+/**
+ * Sleutels: de scopeKeys waarmee andere apps werk aanwijzen, en de menselijke itemsleutel.
+ *
+ * Beide staan in `domain` en niet in de app, omdat het contracten zijn: de client bouwt een
+ * scopeKey om een timer te starten, de server autoriseert hem, en twee plekken die het
+ * voorvoegsel los uitschrijven lopen bij de eerste typefout stil uiteen — met "geen toegang
+ * tot deze scope" als gevolg in plaats van een foutmelding die zegt wat er mis is.
+ */
+/** De scope-soorten die `apps/work` claimt via `/provider/scope/describe`. */
+export declare const WORK_ITEM_SCOPE_KIND = "work_item";
+export declare const WORK_PROJECT_SCOPE_KIND = "work_project";
+export declare function workItemScopeKey(itemId: string): string;
+export declare function workProjectScopeKey(projectId: string): string;
+/**
+ * De menselijke sleutel: `SAL-142`, of `SAL-142-1` voor een subitem.
+ *
+ * Alleen voor items mét project — een los item heeft er geen, en dat is geen omissie maar het
+ * verschil tussen "werk dat een plek in een proces heeft" en "iets wat ik nog moet doen".
+ */
+export declare function formatItemKey(projectKey: string, sequenceNumber: number, subSequence?: number): string;
+/** Wat er in een `SAL-142-1` zit, of `null` als het geen itemsleutel is. */
+export interface ParsedItemKey {
+    projectKey: string;
+    sequenceNumber: number;
+    subSequence?: number;
+}
+/**
+ * Leest een sleutel die iemand heeft ingetypt of geplakt.
+ *
+ * Hoofdletterongevoelig aan de invoerkant en genormaliseerd aan de uitvoerkant, want mensen
+ * typen `sal-142` in een zoekveld en verwachten hun item. Het projectvoorvoegsel is
+ * `[A-Z0-9]{2,8}`, wat een streepje uitsluit — anders zou `SAL-142-1` net zo goed te lezen
+ * zijn als project `SAL-142`, item `1`.
+ */
+export declare function parseItemKey(input: string): ParsedItemKey | null;
+/** De projectsleutel die bij een naam hoort: `"Sales pipeline"` → `"SAL"`. */
+export declare function suggestProjectKey(name: string): string;
+/**
+ * De dossiersleutels van een item: waarmee uren, geheugen en attributen het terugvinden.
+ *
+ * **Klein houden.** Dit is de set van de rij zelf en niet zijn hele omgeving — deze sleutels
+ * rijden mee op elke autorisatie, inclusief elke geheugen-schrijfactie, dus de kinderen van
+ * dit item horen er niet in. Dezelfde afweging die `companyDossierKeys` maakt tegenover
+ * `keySetForCompany` in crm.
+ *
+ * De harde bovengrens is er voor het pathologische geval: een item met tweehonderd partijen
+ * mag geen array van tweehonderd sleutels op elke autorisatie leggen.
+ */
+export declare function itemDossierKeys(item: Pick<WorkItem, "id" | "projectId" | "ancestorKeys" | "partyKeys">, limit?: number): string[];
+/**
+ * De dossiersleutels van een project: alleen zichzelf.
+ *
+ * Een project heeft onbegrensd veel items, dus zijn kinderen meegeven zou een onbegrensd
+ * array op elke autorisatie leggen. Wie de items wil, vraagt ernaar.
+ */
+export declare function projectDossierKeys(project: Pick<WorkProject, "id">): string[];

package/dist/entities/work/keys.test.d.ts

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

package/dist/entities/work/ladder.d.ts

@@ -0,0 +1,97 @@
+import { WorkProject, WorkStatus, WorkStatusCategory } from './types';
+/**
+ * De statusladder — de enige plek die weet of een item een project heeft.
+ *
+ * `WorkItem.projectId` is optioneel, en zonder discipline betekent dat een `if (projectId)`
+ * in elke lijst, elke teller en elke statuskiezer. Alles wat "welke statussen kan dit item
+ * hebben" of "is dit open" vraagt gaat daarom door {@link ladderFor} en {@link categoryOf},
+ * en nergens anders.
+ */
+/**
+ * De vaste ladder voor werk zónder project.
+ *
+ * Deze drie sleutels zijn **gereserveerd**: een project mag ze niet claimen, want dan zou
+ * dezelfde sleutel in twee ladders een andere categorie kunnen hebben en werd de
+ * org-brede "wat staat er open"-query stil onjuist. `validateStatuses` bewaakt dat.
+ *
+ * De labels zijn **i18n-sleutels, geen tekst** — een letterlijke string hier zou de taal op
+ * moduleniveau vastzetten voor elke consument, en dat is precies wat de i18n-regel in
+ * `DESIGN_SYSTEM.md` §11 verbiedt. Ze staan zonder app-voorvoegsel omdat de app-sdk dat er
+ * bij het opzoeken zelf voor zet; een `work:`-voorvoegsel hier zou in de eigen app
+ * verdubbelen tot `work:work:status_open`.
+ *
+ * Een projectstatus heeft géén sleutel maar een naam die een beheerder heeft ingetypt. Alleen
+ * deze drie zijn vertaalbaar, want alleen deze zijn van ons.
+ */
+export declare const LOOSE_STATUSES: readonly WorkStatus[];
+/** De sleutels die {@link LOOSE_STATUSES} bezet houdt. */
+export declare const RESERVED_STATUS_KEYS: readonly string[];
+/**
+ * De ladder die voor dit item geldt.
+ *
+ * Een project zónder statussen valt terug op de vaste ladder in plaats van een lege lijst op
+ * te leveren: een statuskiezer met nul opties is een doodlopende weg, en een half aangemaakt
+ * project hoort niet onbruikbaar te zijn.
+ */
+export declare function ladderFor(project?: WorkProject | null): readonly WorkStatus[];
+/**
+ * De categorie van een statussleutel binnen een ladder.
+ *
+ * Valt terug op `"todo"` bij een onbekende sleutel, en dat is de veilige kant: een item dat
+ * door een verwijderde status wees zou anders als afgerond uit elke telling verdwijnen. Beter
+ * zichtbaar op de verkeerde plek dan onzichtbaar.
+ */
+export declare function categoryOf(statusKey: string, ladder: readonly WorkStatus[]): WorkStatusCategory;
+/** De status zelf, als de ladder hem kent. */
+export declare function statusIn(statusKey: string, ladder: readonly WorkStatus[]): WorkStatus | undefined;
+/** Waar een nieuw item begint: de expliciete keuze van het project, anders de eerste stap. */
+export declare function defaultStatusKey(project?: WorkProject | null): string;
+/** `order` eerst, gelijke waarden op label zodat de volgorde stabiel is. */
+export declare function sortStatuses(ladder: readonly WorkStatus[]): WorkStatus[];
+/**
+ * Is dit item afgerond? De enige juiste manier om die vraag te stellen.
+ *
+ * `isWorkClosed` en niet `isClosed`, want `entities/interaction` exporteert die naam al voor
+ * een gesprek. Twee `isClosed`en in één barrel is precies de verwarring waar dit veld niet
+ * op zit te wachten.
+ */
+export declare function isWorkClosed(statusKey: string, ladder: readonly WorkStatus[]): boolean;
+/**
+ * De statussleutel die bij een naam hoort: kleine letters, streepjes, geen accenten.
+ *
+ * Dezelfde vorm en dezelfde reden als `workTypeKey` bij de werksoorten: het beheerscherm
+ * toont hem al tijdens het typen, dus wat de gebruiker daar ziet moet precies zijn wat de
+ * server wegschrijft. `normalize("NFD")` plus het weghalen van de combineertekens, zodat
+ * "Béta" `beta` wordt en niet `b-ta`.
+ */
+export declare function workStatusKey(label: string): string;
+/**
+ * Dezelfde sleutel, gegarandeerd nog vrij binnen de organisatie.
+ *
+ * Botsingen zijn hier de regel en niet de uitzondering: sleutels zijn org-uniek terwijl
+ * statussen per project beheerd worden, dus twee projecten die allebei een "Review" aanmaken
+ * komen hier uit. De tweede krijgt `review-2` in plaats van een foutmelding — een beheerder
+ * die een naam kiest hoort niet te struikelen over een sleutel die hij nooit heeft gezien.
+ *
+ * `taken` moet óók de sleutels van verwijderde statussen bevatten zolang er items naar
+ * wijzen, en altijd {@link RESERVED_STATUS_KEYS}.
+ */
+export declare function uniqueWorkStatusKey(label: string, taken: Iterable<string>): string;
+/** Wat er mis is met een voorgestelde ladder, als leesbare redenen. */
+export interface StatusLadderProblem {
+    /** Index in de aangeleverde lijst, of `-1` als het de lijst als geheel betreft. */
+    index: number;
+    reason: "empty" | "duplicate_key" | "reserved_key" | "missing_key" | "no_open" | "no_done";
+    key?: string;
+}
+/**
+ * Valideert een ladder vóór hij wordt opgeslagen.
+ *
+ * Bestaat omdat de store hier niets bewaakt: `statuses` is één ingebed array, dus uniciteit
+ * en volledigheid zijn de verantwoordelijkheid van de schrijver. Puur en zonder I/O, zodat
+ * het beheerscherm dezelfde regels kan tonen als de server afdwingt.
+ *
+ * De twee laatste regels zijn geen smaak: een ladder zonder open-categorie maakt elk nieuw
+ * item meteen afgerond, en een ladder zonder `done` maakt afronden onmogelijk.
+ */
+export declare function validateStatuses(statuses: readonly WorkStatus[]): StatusLadderProblem[];

package/dist/entities/work/ladder.test.d.ts

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

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

@@ -0,0 +1,255 @@
+import { OwnerScope } from '../contact/types';
+/**
+ * Work management — één entiteit voor alles wat *werk* is.
+ *
+ * Taak, subtaak, zaak, project, fase, deal en campagne zijn hier rijen in hetzelfde model.
+ * Wat ze onderscheidt is configuratie, geen code: het **project** draagt de workflow, de
+ * veldselectie en de toegang, en `typeKey` is niet meer dan een icoon met een etiket.
+ *
+ * De regel waarmee dit model is afgebakend, in drie vragen:
+ *
+ * 1. *Wie bepaalt de statusovergang?* Onze gebruikers → een `WorkItem`. Een extern systeem
+ *    (Shopify, de boekhouding) → gespiegeld door de bron-app, hier hooguit een `WorkLink`.
+ * 2. *Eigen levensduur, of hangt het ergens aan?* Eigen → een item. Hangt eraan (uren,
+ *    notities, attributen, geheugen) → een annotatie op een `scopeKey`, nooit een rij hier.
+ * 3. *Ander gedrag, of andere woorden?* Alleen andere woorden → een `WorkProject` met andere
+ *    statussen. Pas bij ander gedrag komt er code bij.
+ *
+ * Test 3 is waarom "Dossier", "Project" en "Deal" geen drie entiteiten zijn.
+ */
+/**
+ * De drie categorieën waarin elke status valt.
+ *
+ * Vast, terwijl de statusnaam per project vrij is ("Offerte", "Wacht op cliënt"). Dit is de
+ * vraag die élke consument stelt — de lijst, de teller, de rapportage — en zou die de
+ * projectconfiguratie moeten lezen om hem te beantwoorden, dan kon geen enkele query het
+ * geïndexeerd doen.
+ */
+export type WorkStatusCategory = "todo" | "in_progress" | "done";
+/**
+ * Eén stap in de workflow van een project.
+ *
+ * `key` is **org-uniek en niet project-uniek**, en dat is een bewuste last op het
+ * beheerscherm in ruil voor iets belangrijks: het item draagt alleen `statusKey`, dus
+ * "al mijn open werk over alle projecten heen" is één `{ statusKey: anyOf(openKeys) }`.
+ * Zouden twee projecten allebei een `done` mogen hebben met een andere categorie, dan gaf
+ * diezelfde query stilzwijgend het verkeerde antwoord. De sleutel wordt daarom net als bij
+ * de werksoorten uit het label geslugd en bij botsing opgehoogd.
+ *
+ * `label` is vrij te hernoemen; `key` ligt vast zodra er items op staan.
+ */
+export interface WorkStatus {
+    key: string;
+    label: string;
+    category: WorkStatusCategory;
+    order: number;
+    /** Optionele accentkleur voor de bolletjes in de lijst en het beheerscherm. */
+    color?: string;
+}
+/**
+ * Een afloopreden: hóé iets eindigde, los van wáár het staat.
+ *
+ * Bewust een vrij label zonder vaste betekenis en zonder uitkomst-vlag. Een advocatenkantoor
+ * onderscheidt "geschikt" van "vonnis", een salesteam "gewonnen" van "verloren", en geen van
+ * beide past in een enum die wij bedenken. De prijs staat in het plan: niets kan uitrekenen
+ * hoeveel er goed afliep. Komt die vraag, dan is een `positive?: boolean` hier de plek.
+ */
+export interface WorkResolution {
+    key: string;
+    label: string;
+    order: number;
+}
+/**
+ * Een project: de drager van een werkproces.
+ *
+ * Dit is waar Jira zijn schemes heeft en wij niet. Workflow, veldselectie en toegang hangen
+ * rechtstreeks aan het project in plaats van aan drie koppelbare configuratieobjecten — dat
+ * scheelt de drie schermen die je bij Jira langs moet om één status te veranderen.
+ */
+export interface WorkProject {
+    id: string;
+    organizationId: string;
+    /**
+     * Org-uniek, hoofdletters: `"SAL"`. Vormt het voorvoegsel van elke itemsleutel
+     * (`SAL-142`), en ligt daarom vast zodra er items zijn — hem wijzigen zou elke sleutel
+     * hernoemen, inclusief de exemplaren die mensen in een mail hebben geplakt.
+     */
+    key: string;
+    name: string;
+    description?: string;
+    /** Lucide-icoonnaam. */
+    icon?: string;
+    color?: string;
+    ownerScope: OwnerScope;
+    /** Leden bovenop `ownerScope` — wie er nog meer bij mag. */
+    memberUserIds?: string[];
+    memberTeamIds?: string[];
+    /**
+     * De workflow, ingebed in plaats van een eigen entiteit.
+     *
+     * Drie redenen. Niets bevraagt ooit een losse statusrij: elke itemvraag wordt beantwoord
+     * door de platte `statusKey` op het item. De leesvorm is altijd "de hele ladder tegelijk",
+     * want een lijst rendert alle labels, kleuren en volgordes. En het beheerscherm bewerkt de
+     * ladder als één herordening — deze store kent geen transactie, dus als losse rijen zou
+     * "sleep status 3 boven status 1" N updates worden die half kunnen landen en twee
+     * statussen op dezelfde `order` achterlaten. Als array is het één `$set`.
+     *
+     * Wat het kost: uniciteit van `key` wordt niet door de store bewaakt maar door
+     * `validateStatuses` in de app.
+     */
+    statuses: WorkStatus[];
+    /** Afloopredenen, vrij per project. Leeg = afronden vraagt geen reden. */
+    resolutions?: WorkResolution[];
+    /** Welke itemtypes dit project aanbiedt. Leeg = alle. */
+    typeKeys?: string[];
+    /** Sleutels van de `CustomFieldDef`s die op dit project aan staan, in weergavevolgorde. */
+    fieldKeys?: string[];
+    /** Waar een nieuw item begint. Afwezig = de eerste status in `order`. */
+    defaultStatusKey?: string;
+    /**
+     * Duurzaam ankerpunt voor de sleutelteller.
+     *
+     * De teller zelf leeft in `Bridge.kv`, maar kv is een cache: hij kan koud starten of
+     * geëvicteerd worden. Dit veld en de `(organizationId, projectId, sequenceNumber)`-index
+     * zijn samen de weg terug, zodat een lege kv geen sleutels hergebruikt.
+     */
+    lastSequence?: number;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export type WorkPriority = "low" | "normal" | "high" | "urgent";
+/** Waar een item vandaan komt — een mens of iets automatisch. */
+export interface WorkItemSource {
+    initiator: "user" | "system";
+    /** Vrije reden bij `system` ("missed_call", "stale_interaction"). */
+    systemReason?: string;
+}
+/**
+ * Een werkitem.
+ *
+ * Let op wat hier **niet** staat: geen `interactionId`, geen `contactId`, geen `companyId`.
+ * Verbanden lopen via {@link WorkLink} plus de platgeslagen {@link WorkItem.keys}, zodat "de
+ * items op dit gesprek" één geïndexeerde `$in` blijft die combineerbaar is met een
+ * statusfilter — wat een omweg langs de koppeltabel niet is.
+ *
+ * En geen `value`/`currency`: bedragen zijn aangepaste velden in de generieke
+ * attribuutstore. Dat maakt sorteren erop een geheugenoperatie; zie het plan.
+ */
+export interface WorkItem {
+    id: string;
+    organizationId: string;
+    /**
+     * Afwezig = een **los item**: geen sleutel, geen projectvelden, en de vaste ladder uit
+     * {@link LOOSE_STATUSES}. Dat is wat een losse taak is ("terugbellen", een opvolging op
+     * een gesprek), en het bestaat vanaf dag één zodat werk dat later uit een andere app
+     * hierheen komt geen modelwijziging vraagt.
+     */
+    projectId?: string;
+    /** `SAL-142` / `SAL-142-1`. Afwezig bij een los item. Org-uniek waar aanwezig. */
+    key?: string;
+    sequenceNumber?: number;
+    /** Volgnummer binnen de ouder — het `-1` in `SAL-142-1`. */
+    subSequence?: number;
+    /** Lichte classificatie: icoon en welke velden zinvol zijn. Nooit een workflow. */
+    typeKey: string;
+    ownerScope: OwnerScope;
+    title: string;
+    description?: string;
+    /**
+     * Een {@link WorkStatus.key} — die van het project, of uit de vaste ladder. Omdat de
+     * sleutels org-uniek zijn is de categorie er altijd eenduidig bij te zoeken; daarom
+     * staat die hier níet als tweede kolom.
+     */
+    statusKey: string;
+    /** {@link WorkResolution.key}. Alleen zinvol als de status in categorie `done` valt. */
+    resolution?: string;
+    parentId?: string;
+    /**
+     * De scopeKeys van álle voorouders, platgeslagen op schrijfmoment
+     * (`["work_item:program-1", "work_item:project-7"]`, van boven naar beneden).
+     *
+     * Dít maakt onbeperkte diepte betaalbaar: "alles onder dit project" is één geïndexeerde
+     * `$in` in plaats van een recursieve traversal, en die kan deze store niet. De prijs zit
+     * aan de schrijfkant — een item verslepen betekent de `ancestorKeys` van zijn hele
+     * subtree herschrijven, en dat is een job, geen request.
+     */
+    ancestorKeys?: string[];
+    /** UserIds die dit doen. Leeg = de pool van het team. */
+    assignees?: string[];
+    /** Wie het inbracht, los van wie het doet. */
+    reporterId?: string;
+    watchers?: string[];
+    priority?: WorkPriority;
+    labels?: string[];
+    /**
+     * De partijen, plat en zonder rol: `["company:123", "contact:456"]`.
+     *
+     * Afgeleid uit de {@link WorkLink}s op schrijfmoment. Twee vormen naast elkaar omdat ze
+     * twee vragen beantwoorden: de link weet *in welke hoedanigheid* (cliënt, wederpartij),
+     * deze kolom beantwoordt "alle items waar dit bedrijf in zit" in één indexhit — wat over
+     * een koppeltabel een tweede ronde zou kosten.
+     */
+    partyKeys: string[];
+    /**
+     * Dossiersleutels — de `keys`-conventie uit `platform/scope.ts`. Eigen sleutel,
+     * projectsleutel, voorouders en partijen. Hiermee vinden uren, geheugen en attributen
+     * dit item terug.
+     */
+    keys: string[];
+    /** Verwijzingen naar externe systemen (`shopify_order:8842`). Nooit een kopie. */
+    externalIds?: string[];
+    /** Epoch ms. */
+    startDate?: number;
+    dueDate?: number;
+    /** Gezet zodra de status naar categorie `done` gaat, gewist als hij terugkomt. */
+    closedAt?: number;
+    estimateSeconds?: number;
+    /** Standaard voor uren die hierop geboekt worden; de urenregel mag afwijken. */
+    billable?: boolean;
+    source: WorkItemSource;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Een getypeerde koppeling tussen een werkitem en wat dan ook.
+ *
+ * **Eén hop, nooit getraverseerd.** Dat is de afspraak die deze tabel naast de
+ * `keys`-conventie laat bestaan in plaats van ermee te concurreren: context en lidmaatschap
+ * lopen via `keys` (platgeslagen bij schrijven, één indexhit), en dit is de expliciete,
+ * laag-volume, één-niveau-diepe relatie tussen twee dingen. Een link-tabel die alsnog de
+ * contextvraag beantwoordt is het begin van de grafiek die hier bewust niet gebouwd is —
+ * deze store kan niet recursief traverseren.
+ */
+export interface WorkLink {
+    id: string;
+    organizationId: string;
+    /** Altijd `work_item:<id>` op de heenrij. */
+    fromKey: string;
+    /** Elke scopeKey: een ander item, een gesprek, een contact, een artefact. */
+    toKey: string;
+    /**
+     * De relatie én de partijrol in één vocabulaire: `client` · `opposing` · `context` ·
+     * `blocks` · `blocked_by` · `relates` · `duplicates` · `attachment`.
+     *
+     * Eén veld en geen aparte rol-kolom, want het zijn dezelfde soort uitspraak: "dit bedrijf
+     * is de cliënt" en "dit item blokkeert dat item" zijn allebei een benoemde pijl.
+     */
+    type: string;
+    /**
+     * Gedeeld door de heen- en terugrij.
+     *
+     * Elke koppeling wordt als **twee** rijen geschreven, zodat een lookup één geïndexeerde
+     * query op `fromKey` is in plaats van een `$or` over twee kolommen — en zodat "welk werk
+     * hangt aan `interaction:123`" dezelfde query is als "wat hangt aan dit item". Dit veld
+     * houdt ontkoppelen daarmee één handeling.
+     */
+    pairId: string;
+    /** Waar de terugrij zich mee bekendmaakt, zodat de UI "wordt geblokkeerd door" kan tonen. */
+    inverse?: boolean;
+    createdBy: string;
+    createdAt?: number;
+}