@appinternalleads/ui 0.2.0

package/src/components/checklist/derive.ts

@@ -0,0 +1,147 @@
+import { applyFilter } from '../../runtime/query';
+import {
+  findSection, findTask,
+  type Checklist, type ChecklistCondition, type ChecklistRule, type ChecklistSection, type ChecklistTask,
+} from './contract';
+
+/**
+ * **The derivations — §15, the single source of truth.**
+ *
+ * > `ChecklistTask.done` and `ChecklistTask.skipped` are the only completion facts that are ever
+ * > stored. Every other completion-shaped number or flag in the system is a pure function of them,
+ * > computed at render, held nowhere.
+ *
+ * Pure. No React, no state, no memoisation. The cost is disclosed rather than optimised away: the
+ * header's count, the bar and every section count recompute on every change. For a checklist of a
+ * few hundred tasks that is nothing — and a memoised cache is exactly how a second source of truth
+ * gets introduced by accident.
+ */
+
+/** Never stored. Computed from the one stored fact plus the rules. */
+export type TaskView = 'done' | 'skipped' | 'blocked' | 'open';
+
+export type ChecklistProgress = {
+  total: number;
+  done: number;
+  skipped: number;
+  /** Tasks that must be done for the checklist to be complete (`required !== false`). */
+  required: number;
+  requiredDone: number;
+  /** 0–1. `required` is the denominator, because that is what "complete" is measured against. */
+  fraction: number;
+  complete: boolean;
+};
+
+/** `required` is opt-out: a task with no opinion is required. */
+export const isRequired = (task: ChecklistTask) => task.required !== false;
+
+/** Skipped is **not** done. It is an answer, not a completion. */
+export const isDone = (task: ChecklistTask) => task.done === true;
+
+/**
+ * A required task is satisfied when it is done. A *skipped* required task is deliberately still
+ * unsatisfied — skipping is "not applicable to me", and letting it complete a checklist would make
+ * the bar lie in exactly the way §15 exists to prevent.
+ */
+export function progressOf(checklist: Checklist): ChecklistProgress {
+  const tasks = checklist.sections.flatMap(s => s.tasks);
+  const total = tasks.length;
+  const done = tasks.filter(isDone).length;
+  const skipped = tasks.filter(t => t.skipped === true).length;
+  const requiredTasks = tasks.filter(isRequired);
+  const required = requiredTasks.length;
+  const requiredDone = requiredTasks.filter(isDone).length;
+  /* No required task at all ⇒ nothing is outstanding ⇒ the checklist is complete and the bar is
+     full. A 0/0 fraction has to be *decided*; NaN would propagate into aria-valuenow. */
+  const fraction = required === 0 ? 1 : requiredDone / required;
+  return { total, done, skipped, required, requiredDone, fraction, complete: required === 0 ? total > 0 : requiredDone === required };
+}
+
+/**
+ * A section's own count. Every task of the section, not only the required ones — a reader counting
+ * rows on screen must get the same number the section header shows.
+ */
+export function sectionProgressOf(section: ChecklistSection): { total: number; done: number; complete: boolean } {
+  const total = section.tasks.length;
+  const done = section.tasks.filter(isDone).length;
+  return { total, done, complete: total > 0 && done === total };
+}
+
+/** The string a condition compares against — the field's value, in the operator set's own domain. */
+function cellFor(condition: ChecklistCondition, checklist: Checklist): string | undefined {
+  if (condition.subject === 'task') {
+    const found = findTask(checklist, condition.ref);
+    if (!found) return undefined;
+    if (condition.field === 'done') return String(found.task.done === true);
+    if (condition.field === 'skipped') return String(found.task.skipped === true);
+    return found.task.assigneeId ?? '';
+  }
+  const section = findSection(checklist, condition.ref);
+  if (!section) return undefined;
+  return String(sectionProgressOf(section).complete);
+}
+
+/**
+ * One condition, evaluated. The comparison itself is `applyFilter` from `src/runtime/query` — the
+ * one place an operator's meaning is defined, shared rather than re-implemented.
+ *
+ * A condition naming something the document does not have is **false**, never a throw: a stale
+ * rule must not break a render, and `validateChecklistRule` is where it is *reported*.
+ */
+export function evaluateCondition(condition: ChecklistCondition, checklist: Checklist): boolean {
+  const cell = cellFor(condition, checklist);
+  if (cell === undefined) return false;
+  return applyFilter(cell, { op: condition.op, value: condition.value });
+}
+
+/** Gates that apply to a task and are not yet satisfied. Empty ⇒ the task may be completed. */
+export function unsatisfiedGates(
+  taskId: string,
+  checklist: Checklist,
+  rules: ChecklistRule[],
+): { rule: ChecklistRule; unmet: ChecklistCondition[] }[] {
+  const out: { rule: ChecklistRule; unmet: ChecklistCondition[] }[] = [];
+  for (const rule of rules) {
+    if (rule.kind !== 'gate' || rule.target !== taskId) continue;
+    const unmet = rule.requires.filter(c => !evaluateCondition(c, checklist));
+    if (unmet.length) out.push({ rule, unmet });
+  }
+  return out;
+}
+
+/**
+ * The sentence a blocked task says when pressed. A rule's own `label` wins — it is the author's
+ * words and they are always better than generated prose. Otherwise the most common gate by far
+ * ("that task must be done first") is named in full, and anything else degrades to a truthful
+ * general statement rather than an invented specific one.
+ */
+export function gateMessage(
+  entry: { rule: ChecklistRule; unmet: ChecklistCondition[] },
+  checklist: Checklist,
+): string {
+  if (entry.rule.label) return entry.rule.label;
+  const first = entry.unmet[0];
+  if (first?.subject === 'task' && first.field === 'done' && first.op === 'eq' && first.value === 'true') {
+    const other = findTask(checklist, first.ref);
+    if (other) return `Finish “${other.task.title}” first`;
+  }
+  if (first?.subject === 'section' && first.field === 'complete' && first.op === 'eq' && first.value === 'true') {
+    const section = findSection(checklist, first.ref);
+    if (section?.title) return `Finish “${section.title}” first`;
+  }
+  return 'Something else has to happen first';
+}
+
+/**
+ * **`blocked` is derived, never stored.** Storing it would make it a second copy of a truth the
+ * rules already hold, and the copy would go stale the moment another task is ticked.
+ *
+ * Order matters: a task that is done is `done` even if a gate would now block it — the gate governs
+ * *becoming* done, and re-labelling an already-finished task would be a lie about the past.
+ */
+export function taskViewOf(task: ChecklistTask, checklist: Checklist, rules: ChecklistRule[] = []): TaskView {
+  if (task.done) return 'done';
+  if (task.skipped) return 'skipped';
+  if (unsatisfiedGates(task.id, checklist, rules).length) return 'blocked';
+  return 'open';
+}

package/src/components/checklist/engine.ts

@@ -0,0 +1,342 @@
+import {
+  CAPABILITY_FOR_CHANGE, findSection, findTask,
+  type Checklist, type ChecklistChange, type ChecklistChangeBody, type ChecklistConfig, type ChecklistEffect,
+  type ChecklistDocument,
+  type ChecklistRule, type ChecklistSection, type ChecklistTask,
+} from './contract';
+import { evaluateCondition, gateMessage, progressOf, unsatisfiedGates } from './derive';
+
+/**
+ * **The change engine — §7 and §11 of the design. The one place a Checklist document mutates.**
+ *
+ * Pure: no React, no async, no side effect, no clock, no randomness. Given the same document,
+ * change and rules it returns the same result forever, which is what makes the runtime above it
+ * testable without a renderer and what makes a backend able to replay the same change and land on
+ * the same document.
+ *
+ * It returns three things, and each earns its place:
+ *
+ * - `next` — the document after the change.
+ * - `inverse` — the change that undoes it **exactly**. Rollback after a failed commit is therefore
+ *   a fact rather than a best effort, and never a reload.
+ * - `effects` — the notifications the rules decided were *due*. Deciding is the component's job;
+ *   sending is the host's (§11).
+ */
+
+export type ChangeRejection =
+  | { reason: 'blocked'; message: string }
+  | { reason: 'unknown-task'; message: string }
+  | { reason: 'unknown-section'; message: string }
+  | { reason: 'not-permitted'; message: string }
+  /**
+   * A value the document cannot hold — today only an empty checklist title, which
+   * `checklist/1` forbids (`minLength: 1`). Named `empty-value` to match the vocabulary
+   * `validateChecklistRule` already uses rather than inventing a second word for the same idea.
+   */
+  | { reason: 'empty-value'; message: string };
+
+export type ChangeResult =
+  | { ok: true; next: Checklist; inverse: ChecklistChange; effects: ChecklistEffect[] }
+  | ({ ok: false } & ChangeRejection);
+
+export type ApplyChangeOptions = {
+  /** When given, a change whose capability flag is off is refused as `not-permitted`. */
+  config?: ChecklistConfig;
+};
+
+const fail = (reason: ChangeRejection['reason'], message: string): ChangeResult => ({ ok: false, reason, message });
+
+/**
+ * **One spelling per fact.** `skipped: false`, `description: ''` and `required: true` are each a
+ * second way of writing what the absent key already says, and a document with two spellings cannot
+ * have exact inverses: apply-then-undo would leave a key behind that was never there.
+ *
+ * So the optional fields are canonicalised on every write, and the round-trip test in
+ * `tests/checklistEngine.test.ts` is what holds the rule — it is the test that found this.
+ */
+export function normalizeTask(task: ChecklistTask): ChecklistTask {
+  const out: ChecklistTask = { ...task };
+  if (out.skipped !== true) delete out.skipped;
+  if (out.description === undefined || out.description === '') delete out.description;
+  if (out.required !== false) delete out.required;
+  return out;
+}
+
+/**
+ * The same canonicalisation, one level up. A section with `title: ''` is the *ungrouped* section,
+ * which the document spells by **omitting** the key; a checklist with `description: ''` has no
+ * description. Exported because generation must canonicalise a document that was seeded or
+ * hand-authored rather than built up through `applyChange`.
+ */
+export function normalizeSection(section: ChecklistSection): ChecklistSection {
+  const out: ChecklistSection = { ...section, tasks: section.tasks.map(normalizeTask) };
+  if (out.title === undefined || out.title.trim() === '') delete out.title;
+  return out;
+}
+
+export function normalizeChecklist(checklist: Checklist): Checklist {
+  const out: Checklist = { ...checklist, sections: checklist.sections.map(normalizeSection) };
+  if (out.description === undefined || out.description.trim() === '') delete out.description;
+  return out;
+}
+
+/** The whole portable artefact, canonical. Rules lose an empty `label`/`if` for the same reason. */
+export function normalizeChecklistDocument(doc: ChecklistDocument): ChecklistDocument {
+  return {
+    ...doc,
+    checklist: normalizeChecklist(doc.checklist),
+    rules: doc.rules.map(r => {
+      const out = { ...r };
+      if (out.label === undefined || out.label.trim() === '') delete out.label;
+      if (out.kind === 'notify' && Array.isArray(out.if) && out.if.length === 0) delete out.if;
+      return out;
+    }),
+  };
+}
+
+/** Structural clone of the containment tree. Small, and it keeps `next` free of shared references. */
+const cloneSections = (sections: ChecklistSection[]): ChecklistSection[] =>
+  sections.map(s => ({ ...s, tasks: s.tasks.map(t => ({ ...t })) }));
+
+function withTask(doc: Checklist, taskId: string, edit: (task: ChecklistTask) => ChecklistTask): Checklist {
+  return {
+    ...doc,
+    sections: doc.sections.map(s => ({
+      ...s,
+      tasks: s.tasks.map(t => (t.id === taskId ? normalizeTask(edit({ ...t })) : t)),
+    })),
+  };
+}
+
+/**
+ * Which notify rules the transition from `before` to `after` fired, as resolved effects.
+ *
+ * The event set is deliberately four (`CHECKLIST_EVENTS`): each is something the *document*
+ * observably became, never something the runtime did. `sharedWith` recipients are left empty here
+ * on purpose — the pure engine resolves what the **document** knows, and the runtime completes
+ * what the **session** knows before the host is called.
+ */
+function effectsFor(
+  before: Checklist,
+  after: Checklist,
+  change: ChecklistChange,
+  rules: ChecklistRule[],
+): ChecklistEffect[] {
+  const fired: { event: ChecklistEffect['event']; task?: ChecklistTask }[] = [];
+
+  if (change.kind === 'task.complete') {
+    const was = findTask(before, change.taskId)?.task;
+    const now = findTask(after, change.taskId)?.task;
+    if (now && was && was.done !== now.done) {
+      fired.push({ event: now.done ? 'task.completed' : 'task.uncompleted', task: now });
+    }
+  }
+  if (change.kind === 'task.assign') {
+    const now = findTask(after, change.taskId)?.task;
+    const was = findTask(before, change.taskId)?.task;
+    if (now && now.assigneeId && now.assigneeId !== was?.assigneeId) {
+      fired.push({ event: 'task.assigned', task: now });
+    }
+  }
+  /* Checklist completion is a DERIVATION crossing a threshold, not a stored flag being written —
+     which is why it is computed from both documents rather than read off either. */
+  if (!progressOf(before).complete && progressOf(after).complete) {
+    fired.push({ event: 'checklist.completed' });
+  }
+
+  const effects: ChecklistEffect[] = [];
+  for (const rule of rules) {
+    if (rule.kind !== 'notify') continue;
+    for (const f of fired) {
+      if (rule.when !== f.event) continue;
+      if ((rule.if ?? []).some(c => !evaluateCondition(c, after))) continue;
+      const recipients = rule.to === 'assignee'
+        ? [f.task?.assigneeId].filter((x): x is string => !!x)
+        : [];
+      effects.push({
+        id: `${change.id}:${rule.id}`,
+        kind: 'notify',
+        ruleId: rule.id,
+        channel: rule.channel,
+        audience: rule.to,
+        recipients,
+        event: f.event,
+        checklist: { id: after.id, title: after.title },
+        task: f.task ? { id: f.task.id, title: f.task.title } : undefined,
+      });
+    }
+  }
+  return effects;
+}
+
+/** The inverse's id: a distinct, derived, deterministic id so a rollback is visible as its own row. */
+const inverseId = (change: ChecklistChange) => `${change.id}~undo`;
+
+export function applyChange(
+  doc: Checklist,
+  change: ChecklistChange,
+  rules: ChecklistRule[] = [],
+  opts: ApplyChangeOptions = {},
+): ChangeResult {
+  const can = opts.config?.can;
+  if (can && can[CAPABILITY_FOR_CHANGE[change.kind]] === false) {
+    return fail('not-permitted', 'That is not something this checklist allows');
+  }
+
+  const ok = (next: Checklist, inverseBody: ChecklistChangeBody): ChangeResult => {
+    const inverse: ChecklistChange = { ...inverseBody, id: inverseId(change), author: change.author };
+    return { ok: true, next, inverse, effects: effectsFor(doc, next, change, rules) };
+  };
+
+  switch (change.kind) {
+    case 'checklist.edit': {
+      /* `checklist/1` requires a title (`minLength: 1`), so emptying it is refused rather than
+         written and caught later at generation — the document should never hold a value it is
+         not allowed to hold. */
+      if (change.title !== undefined && change.title.trim() === '') {
+        return fail('empty-value', 'A checklist needs a title');
+      }
+      const before = doc;
+      const next = normalizeChecklist({
+        ...doc,
+        title: change.title ?? doc.title,
+        description: change.description ?? doc.description,
+      });
+      /* Same rule as `task.edit`: the inverse names exactly the fields the change named. */
+      return ok(next, {
+        kind: 'checklist.edit',
+        ...(change.title !== undefined ? { title: before.title } : {}),
+        ...(change.description !== undefined ? { description: before.description ?? '' } : {}),
+      });
+    }
+
+    case 'task.complete': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      /* **Gates evaluate here, synchronously, before anything is attempted.** They are pure
+         functions of the document, so they need no round trip — and blocking a tick *after* an
+         operation had been sent would be a worse experience for no gain (§6). Only becoming done
+         is gated; un-ticking is always allowed, because a gate governs the transition INTO done. */
+      if (change.done) {
+        const blocked = unsatisfiedGates(change.taskId, doc, rules);
+        if (blocked.length) return fail('blocked', gateMessage(blocked[0]!, doc));
+      }
+      if (found.task.done === change.done) {
+        return ok(doc, { kind: 'task.complete', taskId: change.taskId, done: change.done });
+      }
+      /* Completing clears `skipped`: "done" and "not applicable" cannot both be true. The inverse
+         restores the prior skipped value, so a rollback is exact rather than approximately right. */
+      const next = withTask(doc, change.taskId, t => ({ ...t, done: change.done, skipped: change.done ? false : t.skipped }));
+      /* Disclosed rather than silently lost: un-ticking returns a task to OPEN, not to skipped.
+         One inverse restores one fact, and `done` is the fact this change asserted. */
+      return ok(next, { kind: 'task.complete', taskId: change.taskId, done: found.task.done });
+    }
+
+    case 'task.skip': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      const next = withTask(doc, change.taskId, t => ({ ...t, skipped: change.skipped, done: change.skipped ? false : t.done }));
+      return ok(next, { kind: 'task.skip', taskId: change.taskId, skipped: found.task.skipped === true });
+    }
+
+    case 'task.edit': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      const before = found.task;
+      const next = withTask(doc, change.taskId, t => ({
+        ...t,
+        title: change.title ?? t.title,
+        description: change.description ?? t.description,
+        required: change.required ?? t.required,
+      }));
+      /* The inverse names exactly the fields the change named — an inverse that rewrote every
+         field would clobber a concurrent edit to a field this change never touched. */
+      return ok(next, {
+        kind: 'task.edit',
+        taskId: change.taskId,
+        ...(change.title !== undefined ? { title: before.title } : {}),
+        ...(change.description !== undefined ? { description: before.description ?? '' } : {}),
+        ...(change.required !== undefined ? { required: before.required !== false } : {}),
+      });
+    }
+
+    case 'task.assign': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      const before = found.task.assigneeId ?? null;
+      const next = withTask(doc, change.taskId, t => {
+        const copy = { ...t };
+        if (change.assigneeId === null) delete copy.assigneeId;
+        else copy.assigneeId = change.assigneeId;
+        return copy;
+      });
+      return ok(next, { kind: 'task.assign', taskId: change.taskId, assigneeId: before });
+    }
+
+    case 'task.add': {
+      if (!findSection(doc, change.sectionId)) return fail('unknown-section', 'That section is no longer on this checklist');
+      const sections = cloneSections(doc.sections);
+      const section = sections.find(s => s.id === change.sectionId)!;
+      const index = Math.max(0, Math.min(change.index, section.tasks.length));
+      section.tasks.splice(index, 0, normalizeTask(change.task));
+      return ok({ ...doc, sections }, { kind: 'task.delete', taskId: change.task.id });
+    }
+
+    case 'task.delete': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      const sections = cloneSections(doc.sections);
+      const section = sections.find(s => s.id === found.section.id)!;
+      section.tasks.splice(found.taskIndex, 1);
+      /* The inverse carries the whole task back, at the same index — which is why `task.add`
+         takes a task and an index rather than a title. */
+      return ok({ ...doc, sections }, { kind: 'task.add', sectionId: found.section.id, index: found.taskIndex, task: { ...found.task } });
+    }
+
+    case 'task.move': {
+      const found = findTask(doc, change.taskId);
+      if (!found) return fail('unknown-task', 'That task is no longer on this checklist');
+      if (!findSection(doc, change.toSectionId)) return fail('unknown-section', 'That section is no longer on this checklist');
+      const sections = cloneSections(doc.sections);
+      const from = sections.find(s => s.id === found.section.id)!;
+      const [moved] = from.tasks.splice(found.taskIndex, 1);
+      const to = sections.find(s => s.id === change.toSectionId)!;
+      const index = Math.max(0, Math.min(change.toIndex, to.tasks.length));
+      to.tasks.splice(index, 0, moved!);
+      return ok({ ...doc, sections }, { kind: 'task.move', taskId: change.taskId, toSectionId: found.section.id, toIndex: found.taskIndex });
+    }
+
+    case 'section.add': {
+      const sections = cloneSections(doc.sections);
+      const index = Math.max(0, Math.min(change.index, sections.length));
+      sections.splice(index, 0, { ...change.section, tasks: change.section.tasks.map(normalizeTask) });
+      return ok({ ...doc, sections }, { kind: 'section.delete', sectionId: change.section.id });
+    }
+
+    case 'section.edit': {
+      const section = findSection(doc, change.sectionId);
+      if (!section) return fail('unknown-section', 'That section is no longer on this checklist');
+      const next = { ...doc, sections: doc.sections.map(s => (s.id === change.sectionId ? { ...s, title: change.title } : s)) };
+      return ok(next, { kind: 'section.edit', sectionId: change.sectionId, title: section.title ?? '' });
+    }
+
+    case 'section.delete': {
+      const index = doc.sections.findIndex(s => s.id === change.sectionId);
+      if (index < 0) return fail('unknown-section', 'That section is no longer on this checklist');
+      const removed = doc.sections[index]!;
+      const sections = cloneSections(doc.sections);
+      sections.splice(index, 1);
+      return ok({ ...doc, sections }, { kind: 'section.add', index, section: { ...removed, tasks: removed.tasks.map(normalizeTask) } });
+    }
+
+    case 'section.move': {
+      const index = doc.sections.findIndex(s => s.id === change.sectionId);
+      if (index < 0) return fail('unknown-section', 'That section is no longer on this checklist');
+      const sections = cloneSections(doc.sections);
+      const [moved] = sections.splice(index, 1);
+      const to = Math.max(0, Math.min(change.toIndex, sections.length));
+      sections.splice(to, 0, moved!);
+      return ok({ ...doc, sections }, { kind: 'section.move', sectionId: change.sectionId, toIndex: index });
+    }
+  }
+}

package/src/components/checklist/index.ts

@@ -0,0 +1,64 @@
+/**
+ * **Checklist — the second component family.** A piece of shared, durable work.
+ *
+ * ```
+ * ChecklistDocument  =  checklist  +  config  +  rules      the portable contract (§14)
+ *          ↓
+ * useChecklistRuntime                                        optimistic, concurrent, reversible (§7)
+ *          ↓
+ * ChecklistView                                              renders it and nothing else (§3)
+ *          ↓
+ * ChecklistChange  →  applyChange  →  next + inverse + effects    the one place a document mutates
+ *          ↓
+ * ChecklistOperations                                        the host's half: commit / share / notify
+ * ```
+ *
+ * The design is `docs/components/checklist/CHECKLIST-DESIGN.md`; every section reference in this
+ * package points into it. The write-side runtime it stands on is `src/runtime/operations`.
+ */
+export { ChecklistView, type ChecklistViewProps } from './ChecklistView';
+
+export {
+  defaultChecklistConfig, validateChecklistConfig,
+  validateChecklistRule, validateChecklistRules, hasGateCycle,
+  findTask, findSection, allTasks,
+  CHECKLIST_EVENTS, CHECKLIST_CHANGE_KINDS, CAPABILITY_FOR_CHANGE, OPERATORS_BY_FIELD,
+  TASK_FIELDS, SECTION_FIELDS,
+  type Checklist, type ChecklistSection, type ChecklistTask, type ChecklistDocument,
+  type ChecklistConfig, type ChecklistProgressMode, type ChecklistSectionMode, type ChecklistAssigneeMode,
+  type ChecklistRule, type ChecklistGateRule, type ChecklistNotifyRule, type ChecklistCondition,
+  type ChecklistEvent, type ChecklistTaskField, type ChecklistSectionField,
+  type ChecklistChange, type ChecklistChangeBody, type ChecklistChangeKind, type ChecklistEffect,
+  type ChecklistOperations, type ChecklistCapabilities,
+  type AssigneeId, type Person, type PeopleAdapter,
+  type ShareRequest, type ShareResult, type NotificationRequest, type NotificationTrigger,
+  type ChecklistRuleRejection, type ChecklistRuleCheck,
+} from './contract';
+
+export {
+  progressOf, sectionProgressOf, taskViewOf, evaluateCondition, unsatisfiedGates, gateMessage,
+  isRequired, isDone,
+  type TaskView, type ChecklistProgress,
+} from './derive';
+
+export {
+  applyChange, normalizeTask, normalizeSection, normalizeChecklist, normalizeChecklistDocument,
+  type ChangeResult, type ChangeRejection, type ApplyChangeOptions,
+} from './engine';
+
+export {
+  processChecklistDocument, blankChecklist,
+  type ProcessResult, type ProcessIssue, type ProcessIssueStage,
+} from './process';
+
+export {
+  useChecklistRuntime, SLOW_THRESHOLD_MS,
+  type ChecklistRuntime, type ChecklistRuntimeState, type ChecklistRuntimeOptions,
+  type PendingChange, type EffectRecord, type RejectedRule, type ShareState,
+} from './runtime';
+
+export {
+  createMockChecklistOperations, createMockPeopleAdapter, CHECKLIST_LATENCY, MOCK_PEOPLE,
+  type MockChecklistOperationsOptions, type ChecklistLatencyPreset,
+} from './mock';
+export { CHECKLIST_CASE_STUDIES, type ChecklistCaseStudy } from './cases';

package/src/components/checklist/mock.ts

@@ -0,0 +1,126 @@
+import { abortableDelay, resolveLatency } from '../../runtime/operations';
+import type {
+  ChecklistChange, ChecklistOperations, NotificationRequest, Person, PeopleAdapter,
+  ShareRequest, ShareResult,
+} from './contract';
+
+/**
+ * **The deterministic mock runtime — §12.**
+ *
+ * The constraint is inherited, not invented: `createMockAdapter` (`src/runtime/query`) and
+ * `createMockUploadOperations` (`src/widgets/fileUploadEngine.ts`) both take latency as a
+ * value-or-function-of-call-index and failure as a predicate, and both explicitly avoid
+ * `Math.random` and `Date.now`. A test that can make call 1 slower than call 2 can *prove* race
+ * safety; a random one can only prove it usually.
+ *
+ * **Every timer in the Checklist family lives in this file.** There is no `setTimeout` in
+ * `ChecklistView`, no `await` in an event handler and no failure branch in a row component. A UI
+ * component's only relationship with latency is reading a status off the runtime.
+ *
+ * Nothing here sends anything. `notify` records what *would* have been sent and resolves.
+ */
+
+/**
+ * The three presets, chosen for what each one lets a reviewer *see* rather than for realism:
+ *
+ * - `fast` lands inside the no-spinner window (§16's 500 ms), so a quick tick shows no machinery.
+ * - `normal` crosses it, so the quiet activity indicator appears.
+ * - `slow` is long enough to tick a second task while the first is still in flight — the
+ *   concurrency property that distinguishes this runtime from a query machine.
+ */
+export const CHECKLIST_LATENCY = { fast: 120, normal: 450, slow: 1600 } as const;
+export type ChecklistLatencyPreset = keyof typeof CHECKLIST_LATENCY;
+
+export type MockChecklistOperationsOptions = {
+  /** Fixed, or a function of the change and the 0-based call index. Default 0. */
+  latencyMs?: number | ((change: ChecklistChange, callIndex: number) => number);
+  /** Deterministic failure injection — by change kind, by call index, by any predicate. */
+  failWhen?: (change: ChecklistChange, callIndex: number) => boolean;
+  failShare?: (req: ShareRequest, callIndex: number) => boolean;
+  failNotify?: (req: NotificationRequest, callIndex: number) => boolean;
+  /** Latency for the two boundary operations, when they should differ from `latencyMs`. */
+  shareLatencyMs?: number | ((req: ShareRequest, callIndex: number) => number);
+  notifyLatencyMs?: number | ((req: NotificationRequest, callIndex: number) => number);
+  /** Everything the mock "sent", for the Playground inspector and for assertions. */
+  onCall?: (op: 'commit' | 'share' | 'notify', payload: unknown, callIndex: number) => void;
+};
+
+const COMMIT_FAILED = 'The change was not saved';
+const SHARE_FAILED = 'The checklist was not shared';
+const NOTIFY_FAILED = 'The notification was not sent';
+
+export function createMockChecklistOperations(opts: MockChecklistOperationsOptions = {}): ChecklistOperations {
+  let commits = 0;
+  let shares = 0;
+  let notifies = 0;
+
+  return {
+    commit: async (change, { signal }) => {
+      const callIndex = commits++;
+      opts.onCall?.('commit', change, callIndex);
+      await abortableDelay(resolveLatency(opts.latencyMs, change, callIndex), signal);
+      if (opts.failWhen?.(change, callIndex)) throw new Error(COMMIT_FAILED);
+    },
+    share: async (req, { signal }): Promise<ShareResult> => {
+      const callIndex = shares++;
+      opts.onCall?.('share', req, callIndex);
+      await abortableDelay(resolveLatency(opts.shareLatencyMs ?? 0, req, callIndex), signal);
+      if (opts.failShare?.(req, callIndex)) throw new Error(SHARE_FAILED);
+      /* No `url`: this mock writes no link, and inventing one would suggest the component had
+         decided what a share *is*. A host that mints links returns one; this one does not. */
+      return { sharedWith: req.recipients };
+    },
+    notify: async (req, { signal }) => {
+      const callIndex = notifies++;
+      opts.onCall?.('notify', req, callIndex);
+      await abortableDelay(resolveLatency(opts.notifyLatencyMs ?? 0, req, callIndex), signal);
+      if (opts.failNotify?.(req, callIndex)) throw new Error(NOTIFY_FAILED);
+    },
+  };
+}
+
+/**
+ * Deterministic mock people. Generic names on purpose — there is not one real team member here,
+ * for the same reason there is not one column name in `src/components/directory/`.
+ */
+export const MOCK_PEOPLE: Person[] = [
+  { id: 'p-ana', name: 'Ana', initials: 'A', email: 'ana@example.test' },
+  { id: 'p-ben', name: 'Ben', initials: 'B', email: 'ben@example.test' },
+  { id: 'p-chi', name: 'Chi', initials: 'C', email: 'chi@example.test' },
+  { id: 'p-dev', name: 'Dev', initials: 'D', email: 'dev@example.test' },
+  { id: 'p-eli', name: 'Eli', initials: 'E', email: 'eli@example.test' },
+  { id: 'p-fay', name: 'Fay', initials: 'F', email: 'fay@example.test' },
+  { id: 'p-gus', name: 'Gus', initials: 'G', email: 'gus@example.test' },
+  { id: 'p-hana', name: 'Hana', initials: 'H', email: 'hana@example.test' },
+];
+
+export type MockPeopleAdapterOptions = {
+  latencyMs?: number | ((q: string, callIndex: number) => number);
+};
+
+/**
+ * The host's half of assignment, mocked. `resolve` returns only the ids it actually has — an id it
+ * does not know is **absent from the result**, not invented, which is what lets the component draw
+ * the difference between "nobody is on this" and "somebody is, and we do not know who" (§9).
+ */
+export function createMockPeopleAdapter(
+  people: Person[] = MOCK_PEOPLE,
+  opts: MockPeopleAdapterOptions = {},
+): PeopleAdapter {
+  let calls = 0;
+  const wait = (q: string, signal: AbortSignal) =>
+    abortableDelay(resolveLatency(opts.latencyMs, q, calls++), signal);
+
+  return {
+    resolve: async (ids, { signal }) => {
+      await wait(ids.join(','), signal);
+      return people.filter(p => ids.includes(p.id));
+    },
+    search: async (q, { signal }) => {
+      await wait(q, signal);
+      const needle = q.trim().toLowerCase();
+      if (!needle) return people;
+      return people.filter(p => p.name.toLowerCase().includes(needle) || p.id.toLowerCase().includes(needle));
+    },
+  };
+}