@opencxh/domain 1.234.0 → 1.236.0

package/dist/entities/artifact/blocks.d.ts

@@ -1,153 +1,12 @@
 /**
- * The blocks an artifact is built from.
+ * The artifact vocabulary, under its original names.
  *
- * This is a **document** vocabulary, not the row vocabulary of the timeline
- * (`../activity/blocks.ts`). Those two look alike and deliberately are not: a timeline row sits
- * among dozens of others and may therefore hold only ten blocks, has no paragraphs or headings,
- * and its text nodes are *paths* into an activity. An artifact is a document — it has headings,
- * paragraphs, a table and a KPI row, and its text is just text.
+ * The blocks moved to `platform/document-blocks.ts` when a second and third writer appeared: a
+ * knowledge base article and a quote are the same list of blocks, and a vocabulary with three
+ * consumers is a platform contract rather than one entity's model. See
+ * `plans/DOCUMENTS-2026-09-14.md`.
  *
- * What is carried over is that file's *discipline*, because it proved itself:
- *
- * - an optional `block_id`, so a block can be pointed at without rewriting the whole document;
- * - {@link normalizeArtifactBlocks} **prunes instead of refusing** — one bad block must not make a
- *   whole document disappear — and reports *every* drop, because silent pruning makes "why is my
- *   table missing?" unanswerable;
- * - unknown block types are skipped, so a newer writer can coexist with an older renderer;
- * - semantic tones only, no free colours, so dark mode keeps working.
- *
- * **The inert boundary.** An artifact is stored data, not a program, and that is a property of the
- * *model* rather than the outcome of a filter afterwards. Block texts are **markdown, never
- * HTML**: the renderer hands them to ui-kit's `RichText` with `as="markdown"`, and that branch
- * (react-markdown + remark-gfm) emits no raw HTML, so a `<script>` in the text reaches the screen
- * as literal characters. Hence no tag stripping here — that would break "a < b" and win nothing.
- * What *is* stripped is the only thing markdown itself makes dangerous: a link to a scheme outside
- * {@link ALLOWED_LINK_SCHEMES}, and inline images. See {@link sanitizeInline}.
- */
-/** Semantic colour. No free colours, so dark mode and the tokens keep working. */
-export type ArtifactTone = "info" | "success" | "warning" | "destructive";
-/**
- * One line in a list.
- *
- * `lead` exists because a findings list puts its point up front in bold ("**Yealink outages
- * dominate.** 14 of the 184 calls..."). Without a field of its own the writer has to invent
- * markdown asterisks in a place where the formatting is supposed to be fixed — and then the text
- * shows whether someone forgot.
- */
-export interface ArtifactListItem {
-    lead?: string;
-    text: string;
-}
-export interface ArtifactTableColumn {
-    label: string;
-    /** Numbers right. Left by default. */
-    align?: "left" | "right";
-}
-export interface ArtifactKpiItem {
-    /** Already formatted by the writer ("1u 12m", "184", "-12%"). */
-    value: string;
-    label: string;
-    /** Only set when this number stands out; a tint on every tile is wallpaper. */
-    tone?: ArtifactTone;
-}
-export type ArtifactBlock = {
-    block_id?: string;
-    type: "heading";
-    level: 1 | 2 | 3;
-    text: string;
-} | {
-    block_id?: string;
-    type: "paragraph";
-    text: string;
-} | {
-    block_id?: string;
-    type: "list";
-    style: "bulleted" | "numbered";
-    items: ArtifactListItem[];
-} | {
-    block_id?: string;
-    type: "quote";
-    text: string;
-} | {
-    block_id?: string;
-    type: "code";
-    lang?: string;
-    text: string;
-} | {
-    block_id?: string;
-    type: "divider";
-} | {
-    block_id?: string;
-    type: "table";
-    columns: ArtifactTableColumn[];
-    rows: string[][];
-    caption?: string;
-} | {
-    block_id?: string;
-    type: "kpi";
-    items: ArtifactKpiItem[];
-} | {
-    block_id?: string;
-    type: "callout";
-    tone: ArtifactTone;
-    title?: string;
-    text: string;
-};
-export type ArtifactBlockType = ArtifactBlock["type"];
-/**
- * Ceilings. Wider than the timeline (which sits at 10 blocks) because this is a document, but not
- * unlimited: the body travels as JSON through the same invoke channel as everything else and ends
- * up in a single column.
- */
-export declare const ARTIFACT_MAX_BLOCKS = 200;
-export declare const ARTIFACT_MAX_LIST_ITEMS = 100;
-export declare const ARTIFACT_MAX_TABLE_ROWS = 200;
-export declare const ARTIFACT_MAX_TABLE_COLUMNS = 12;
-export declare const ARTIFACT_MAX_KPI_ITEMS = 4;
-export declare const ARTIFACT_MAX_TEXT_LEN = 4000;
-export declare const ARTIFACT_MAX_CELL_LEN = 500;
-/** Hard upper bound on the serialized body. */
-export declare const ARTIFACT_MAX_BODY_BYTES: number;
-/**
- * Schemes a link in an artifact may carry.
- *
- * `javascript:` and `data:` are not among them, and that is the entire reason this list exists:
- * those two are the only way markdown gets something executable into the document.
- */
-export declare const ALLOWED_LINK_SCHEMES: readonly ["http:", "https:", "mailto:", "tel:"];
-/**
- * Makes one piece of inline markdown safe while keeping it readable.
- *
- * Three interventions, in this order:
- *
- * 1. **Inline images disappear**, with their alt text as replacement. This version has no `image`
- *    block precisely because the product has no publicly loadable URL (bytes come through the
- *    invoke channel as base64). An inline `![](…)` would open that gap through the back door and
- *    tell an external host who opens the document.
- * 2. **Links to a forbidden scheme become plain text** — the label stays. Dropping the label would
- *    break the sentence over the link.
- * 3. **Reference definitions to a forbidden scheme disappear.** Without this step `[click][x]`
- *    with `[x]: javascript:…` below it escapes step 2.
- */
-export declare function sanitizeInline(text: string): string;
-/**
- * Prunes a written block list down to something a renderer can safely draw.
- *
- * Always returns **new** objects: the input comes from a model or an API client, and the sanitized
- * text must not leak back into the original.
- *
- * `onDrop` should log or report back to the writer — a tool losing its table because it sent zero
- * columns has to be able to hear that.
- */
-export declare function normalizeArtifactBlocks(blocks: unknown, onDrop?: (reason: string) => void): ArtifactBlock[];
-/** How many bytes this body costs on the wire. */
-export declare function artifactBodyBytes(blocks: ArtifactBlock[]): number;
-/**
- * A short summary of what is inside, for the thumbnail on a card and for what the assistant sees
- * when it wants to update an artifact without reading the whole body.
+ * These aliases exist so `apps/storage` and the AI tools keep compiling unchanged. New code reads
+ * the document names.
  */
-export declare function artifactOutline(blocks: ArtifactBlock[]): {
-    blocks: number;
-    types: ArtifactBlockType[];
-    headings: string[];
-};
+export { ALLOWED_LINK_SCHEMES, DOCUMENT_MAX_BLOCKS as ARTIFACT_MAX_BLOCKS, DOCUMENT_MAX_BODY_BYTES as ARTIFACT_MAX_BODY_BYTES, DOCUMENT_MAX_CELL_LEN as ARTIFACT_MAX_CELL_LEN, DOCUMENT_MAX_KPI_ITEMS as ARTIFACT_MAX_KPI_ITEMS, DOCUMENT_MAX_LIST_ITEMS as ARTIFACT_MAX_LIST_ITEMS, DOCUMENT_MAX_TABLE_COLUMNS as ARTIFACT_MAX_TABLE_COLUMNS, DOCUMENT_MAX_TABLE_ROWS as ARTIFACT_MAX_TABLE_ROWS, DOCUMENT_MAX_TEXT_LEN as ARTIFACT_MAX_TEXT_LEN, type DocumentBlock as ArtifactBlock, type DocumentBlockType as ArtifactBlockType, type DocumentKpiItem as ArtifactKpiItem, type DocumentListItem as ArtifactListItem, type DocumentTableColumn as ArtifactTableColumn, type DocumentTone as ArtifactTone, documentBodyBytes as artifactBodyBytes, documentOutline as artifactOutline, normalizeDocumentBlocks as normalizeArtifactBlocks, sanitizeInline, } from '../../platform/document-blocks';

package/dist/entities/artifact/markdown.d.ts

@@ -1,6 +1,2 @@
-import { ArtifactBlock } from './blocks';
-/**
- * The whole document as markdown. `title` goes on top as an H1 when the blocks carry none
- * themselves — an export without a title cannot be found back in a downloads folder.
- */
-export declare function artifactToMarkdown(blocks: ArtifactBlock[], title?: string): string;
+/** See `./blocks`: the serializer moved to `platform/document-markdown.ts` with the vocabulary. */
+export { documentToMarkdown as artifactToMarkdown } from '../../platform/document-markdown';

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

@@ -39,6 +39,8 @@ export interface Company {
     phone?: string;
     website?: string;
     notes?: string;
+    /** The language to write to this company in. The rung under {@link Contact.locale}. */
+    locale?: string;
 }
 /** What a resolve returns: which company, and how we got there. */
 export interface CompanyMatch {

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

@@ -47,6 +47,14 @@ export interface Contact {
     keys?: string[];
     /** Namespaced source references (`ms:AAMk…`, `google:people/c123`, `hubspot:42`). */
     externalIds?: string[];
+    /**
+     * The language to write to this person in (`nl`, `en`).
+     *
+     * On the contact and not only on the company, because a Dutch company has a German buyer often
+     * enough to matter. Absent means "no answer here" and the reader falls to the next rung — see
+     * `recipientLocale`.
+     */
+    locale?: string;
     origin?: ContactOrigin;
     /** When a shadow row last saw its source. There is no refresh job; touching refreshes. */
     syncedAt?: number;

package/dist/entities/document-template/index.d.ts

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

package/dist/entities/document-template/locale.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Which language to write to somebody in, and which template row that means.
+ *
+ * Three rungs, and the figure is the same one this platform uses everywhere: the most specific
+ * answer that exists wins, whole.
+ *
+ * | Rung | Says |
+ * |---|---|
+ * | the contact | this person reads German |
+ * | the company | this customer is Dutch |
+ * | the organisation | what we write by default |
+ *
+ * Without it somebody picks a language by hand on every letter, and sooner or later a Dutch
+ * final notice lands at a German customer.
+ */
+export interface RecipientLocaleSources {
+    /** `Contact.locale` — the person. */
+    contactLocale?: string;
+    /** `Company.locale` — the customer. */
+    companyLocale?: string;
+    /** The organisation's own language. The floor; there is nothing under it. */
+    organizationLocale?: string;
+}
+export declare function recipientLocale(sources: RecipientLocaleSources): string | undefined;
+/** The minimum a template row has to carry to be picked. */
+export interface LocalizedTemplate {
+    key: string;
+    locale?: string;
+    archived?: boolean;
+}
+/**
+ * The template for this key in this language, or the nearest thing that exists.
+ *
+ * A reminder written only in Dutch still has to go out to a German customer — in Dutch. Returning
+ * nothing there would mean no letter at all, which is worse than the wrong language. The order is
+ * therefore: the language asked for, the organisation's own, then whatever is there.
+ */
+export declare function pickTemplate<T extends LocalizedTemplate>(templates: readonly T[], key: string, locale?: string, organizationLocale?: string): T | undefined;

package/dist/entities/document-template/tokens.d.ts

@@ -0,0 +1,27 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+import { TemplateCondition } from './types';
+/** A flat or nested plain object. Arrays resolve by index: `regels.0.naam`. */
+export type TemplateContext = Record<string, unknown>;
+/** Walk a dotted path. Returns `undefined` for anything the path does not reach. */
+export declare function lookup(context: TemplateContext, path: string): unknown;
+export interface FillResult {
+    text: string;
+    /** Paths that resolved to nothing, in the order they appeared. Deduplicated. */
+    unresolved: string[];
+}
+/** One string, filled in. */
+export declare function fillText(text: string, context: TemplateContext): FillResult;
+/** Does this block appear? A block with no condition always does. */
+export declare function conditionHolds(condition: TemplateCondition | undefined, context: TemplateContext): boolean;
+export interface FillDocumentResult {
+    blocks: DocumentBlock[];
+    unresolved: string[];
+}
+/**
+ * A whole template, filled in: conditions applied, tokens replaced everywhere text lives.
+ *
+ * Every text-bearing field is walked, not just `text` — a token in a table cell or a letterhead
+ * value is the ordinary case for an invoice, and missing one would leave `{factuur.nummer}`
+ * printed on a document that went out the door.
+ */
+export declare function fillDocument(blocks: readonly DocumentBlock[], context: TemplateContext, conditions?: Record<string, TemplateCondition>): FillDocumentResult;

package/dist/entities/document-template/types.d.ts

@@ -0,0 +1,87 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+/**
+ * A document template: the blocks a generated document is built from.
+ *
+ * A work order, a quote, a first reminder, a final notice. What it is **not** is the letterhead
+ * and the footer — those are the organisation's house style, drawn around every document, so a
+ * change to the address does not mean editing six templates.
+ *
+ * See `plans/DOCUMENTS-2026-09-14.md` §7.
+ */
+export interface DocumentTemplate {
+    id: string;
+    organizationId: string;
+    /** `quote`, `invoice`, `reminder_1`, `reminder_final`, `work_order`… Unique per language. */
+    key: string;
+    name: string;
+    description?: string;
+    /**
+     * Which document kind may use it. Absent = free-standing (a letter, a work order).
+     *
+     * A string and not a union: the kinds live in `apps/sales` and this app must not need to know
+     * them to store one.
+     */
+    documentKindKey?: string;
+    /** The body. Plain document blocks — the same thing the editor and the renderer already speak. */
+    blocks: DocumentBlock[];
+    /**
+     * Which blocks only appear sometimes, keyed by `block_id`.
+     *
+     * **Beside the blocks, not wrapped around them.** A condition is part of the template, not of
+     * the document: keeping it out of the block means the editor, the renderer and the markdown
+     * export need to know nothing about it, and a template's body stays a thing any of them can
+     * open. A block with no entry here always appears.
+     */
+    conditions?: Record<string, TemplateCondition>;
+    /**
+     * The language this template is written in.
+     *
+     * A Dutch reminder and its English version are **two rows**, tied by
+     * {@link DocumentTemplate.translationGroupId} — exactly how `KbArticle` does it, and for the
+     * same reason: a per-key text map cannot carry a translated table, and a translated list is not
+     * a string. The price is that the structure can drift between languages; the alternative is a
+     * mechanism that cannot express half the documents.
+     */
+    locale?: string;
+    /** Ties the language versions together. Defaults to the template's own id. */
+    translationGroupId?: string;
+    isDefault?: boolean;
+    archived?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * When a block appears.
+ *
+ * Three operators and no expression language. "Show the direct-debit paragraph when the customer
+ * pays by direct debit" is the whole job; anything past that is a rule, and a rule belongs in the
+ * app that decides it.
+ */
+export interface TemplateCondition {
+    /** A path into the same context the tokens read: `klant.incasso`. */
+    key: string;
+    /** Show when the value equals this. */
+    equals?: unknown;
+    /** Show when the value is present (`true`) or absent (`false`). */
+    exists?: boolean;
+}
+/**
+ * The organisation's paper: what is drawn around every document, whichever template made it.
+ *
+ * Three fields, and the shortness is the point. The logo, the address and the VAT/KvK numbers are
+ * **not** here — they are already on the organisation (`logo`, `address`, `billing`), and a second
+ * copy is the one that goes stale. What is left is what a document needs and nothing here had.
+ */
+export interface OrganizationHouseStyle {
+    /** Hex, for the rules and the heading accents. */
+    accentColor?: string;
+    /** The line under every document. */
+    footerText?: string;
+    /**
+     * The account to pay into. The one identifier a letter needs that this platform did not already
+     * have — the VAT and chamber-of-commerce numbers live on `Organization.billing`, and a second
+     * copy is the one that goes stale.
+     */
+    iban?: string;
+}

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

@@ -1,3 +1,4 @@
+import { DocumentBlock } from '../../platform/document-blocks';
 /** A language a knowledge base publishes in, e.g. `nl`, `en`, `de`. */
 export type KbLocale = string;
 export interface KnowledgeBase {
@@ -62,7 +63,15 @@ export interface KbArticle {
     knowledgeBaseId: string;
     categoryId?: string;
     title: string;
+    /**
+     * The article as document blocks — the source of truth. Absent on a row written before the
+     * store moved to blocks; readers fall back to parsing {@link KbArticle.body}.
+     */
+    blocks?: DocumentBlock[];
+    /** The same article as markdown. Derived on write, never parsed back. */
     body: string;
+    /** The same article as plain text: what the embedding and the keyword score read. */
+    text?: string;
     status: "draft" | "published";
     authorId?: string;
     order: number;

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

@@ -1,3 +1,4 @@
+import { OrganizationHouseStyle } from '../document-template/types';
 import { OrganizationProfile } from './profile';
 export interface OrganizationAddress {
     street?: string;
@@ -40,6 +41,13 @@ export interface Organization {
      * which steps apply and what to propose. See `profile.ts`.
      */
     profile?: OrganizationProfile;
+    /**
+     * What is drawn around every generated document — accent, footer, KvK/VAT/IBAN.
+     *
+     * The logo and the address are not in here: they are fields of their own on this record, and a
+     * document reads them from there. See `OrganizationHouseStyle`.
+     */
+    houseStyle?: OrganizationHouseStyle;
     /** Small company logo stored inline as a base64 data-URI. */
     logo?: string;
     /**

package/dist/entities/planning/capacity.d.ts

@@ -48,8 +48,14 @@ export interface CapacitySources {
  */
 export declare function capacityTotal(range: DateRange, sources: CapacitySources): CapacityTotal;
 export interface PersonCoverage {
-    /** `null` is the pot nobody has taken yet — what is still to be divided. */
-    userId: string | null;
+    /**
+     * **Absent** is the pot nobody has taken yet — what is still to be divided.
+     *
+     * Absent and not `null`: a `null` in a response arrives at the client as `[]`, which is
+     * truthy, so `row.userId ? …` took the wrong branch and handed an array to everything that
+     * expected a name. An omitted key survives the wire as an omitted key.
+     */
+    userId?: string;
     requiredSeconds: number;
     capacitySeconds: number;
     /** `capacity − required`. Negative = this person is over-committed. */
@@ -65,5 +71,42 @@ export interface PersonCoverage {
  * Work nobody has taken stays a pot of its own rather than being divided over the team: it is
  * precisely what is still to be assigned, and pretending it is already somebody's would erase the
  * one thing that is actionable.
+ *
+ * > **A source that names nobody gets no answer at all — not a table of zeroes.**
+ * > A queue or a fixed staffing level is demand on a *team*: four hundred conversations are not
+ * > Daan's and not Iris's, and they never will be. Answering anyway produced a row per rostered
+ * > person reading `0 / 8u` and a pot claiming the whole week was "still to be divided", which is
+ * > not an empty answer but a false one. Only a source that attributes *some* work to *somebody*
+ * > — a sprint with assignees, where an unassigned item genuinely is still to be handed out — can
+ * > be asked this question.
  */
 export declare function coverageByPerson(points: readonly DemandPointResponse[], capacity: CapacityTotal): PersonCoverage[];
+export interface PersonAvailability {
+    userId: string;
+    /** Hours this person has in the window, by the ladder, after approved absence. */
+    capacitySeconds: number;
+    /** Of that, already earmarked for this workstream. */
+    onThisSeconds: number;
+    /** Of that, spoken for by something else: another workstream, a meeting, training, travel. */
+    elsewhereSeconds: number;
+    /** `capacity − onThis − elsewhere`, floored at zero. What a planner can still hand out. */
+    freeSeconds: number;
+}
+/**
+ * Who is still free, and for how long.
+ *
+ * The other half of the planner's question, and the one `coverageByPerson` cannot answer. That
+ * one asks *who has too much work* — which needs a source that names people, so a queue or a
+ * fixed staffing level has no answer at all. This one asks *who is left*, and every source can
+ * answer it, because it reads the roster rather than the demand.
+ *
+ * > **A shift makes time; it does not spend it — unless it is earmarked.**
+ * > An unearmarked eight-hour shift is eight hours a planner can still fill. The same shift with
+ * > a workstream on it is eight hours already promised. Everything that is not a shift and not
+ * > absence spends time whatever it is: a meeting, training, travel, a break.
+ *
+ * Absence never appears here as spent time. It has already been taken off the capacity by
+ * `capacityTotal`, and subtracting it twice is the shrinkage mistake this file keeps warning
+ * about — a day of leave would read as minus eight hours of freedom on a day with none.
+ */
+export declare function availabilityByPerson(entries: readonly ScheduleEntry[], workstreamId: string, range: DateRange, capacity: CapacityTotal): PersonAvailability[];