@opencxh/domain 1.233.1 → 1.235.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/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[];

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

@@ -42,10 +42,14 @@ export interface WorkPattern {
     updatedAt?: number;
 }
 /**
- * Whole calendar days between two instants.
+ * Whole days between two instants, rounded.
  *
- * Counted through `Date`, not by dividing milliseconds: two days a year are 23 or 25 hours long,
- * and a rotation that slips a day every March is a rota nobody trusts again.
+ * **Deliberately timezone-free.** An earlier version normalised both sides to local noon, which
+ * reads the *evaluating* machine's clock — and the two timestamps come from the browser. On a
+ * UTC server a CEST Monday midnight floors to the previous Sunday, the week walks eight days
+ * instead of seven, and the eighth wraps onto cycle day zero: five eight-hour days silently
+ * became six. Rounding the raw difference needs no shared timezone and absorbs the 23- and
+ * 25-hour days of a daylight-saving change on its own.
  */
 export declare function calendarDaysBetween(from: number, to: number): number;
 /** Which day of the cycle a date falls on. Negative offsets wrap the right way round. */