@appinternalleads/ui 0.2.0

package/src/components/checklist/contract.ts

@@ -0,0 +1,599 @@
+import { FILTER_OPS, VALUELESS_FILTER_OPS, type FilterAuthor, type FilterOp } from '../../runtime/query';
+
+/**
+ * **Checklist — the contract.** A piece of shared, durable work: a named set of tasks that people
+ * complete over time, and that the component keeps honest.
+ *
+ * Source of truth: `docs/components/checklist/CHECKLIST-DESIGN.md`, approved 2026-09-19. Section
+ * numbers below refer to it.
+ *
+ * The load-bearing rule, and the reason this file exists at all — Directory's sentence over a
+ * different vocabulary:
+ *
+ * > **Nothing in a rule may name a task, section or field the document does not contain.** The
+ * > document is the vocabulary: for the builder UI, for the configuration, for a person's rule and
+ * > for an agent's rule alike.
+ *
+ * The second load-bearing rule, §15:
+ *
+ * > **`done` and `skipped` are the only completion facts that are ever stored.** Progress, section
+ * > completion and checklist completion are pure functions of them (`derive.ts`), computed at
+ * > render, held nowhere. There is no field below in which a derived value *could* be stored, and
+ * > `tests/checklistContract.test.ts` asserts that.
+ */
+
+/* ── The data — §4 ───────────────────────────────────────────────────────── */
+
+/**
+ * The authoritative content. Everything a reader sees that is not derived is in here, and nothing
+ * else is: no React callbacks, no component instances, no DOM references, no CSS, no colour, no
+ * pixel value, no processing state.
+ */
+export type Checklist = {
+  id: string;
+  title: string;
+  description?: string;
+  /**
+   * Ordered, and the only ordering — containment *is* the index. A flat `tasks[]` with a
+   * `sectionId` would need a second structure to hold order, and two structures can disagree: a
+   * task in no section, a task in two, an order array naming an id that is gone. This makes all
+   * three unrepresentable. An ungrouped checklist is one section with no title (§4, decision 2),
+   * never a second container shape.
+   */
+  sections: ChecklistSection[];
+};
+
+export type ChecklistSection = {
+  id: string;
+  /** Absent on the implicit single section of an ungrouped checklist. */
+  title?: string;
+  tasks: ChecklistTask[];
+};
+
+export type ChecklistTask = {
+  id: string;
+  title: string;
+  description?: string;
+  /** One of the two stored completion facts. §15. */
+  done: boolean;
+  /**
+   * The other. Only meaningful when `config.can.skip` is on. "Not applicable to me" is a real and
+   * distinct answer from "not done yet" — and skipped **never** counts as done.
+   */
+  skipped?: boolean;
+  /** An opaque id resolved through the people boundary (§9). Never a denormalised name. */
+  assigneeId?: string;
+  /** Must this task be done for the CHECKLIST to be complete? Absent means yes. */
+  required?: boolean;
+};
+
+/* ── The configuration — §5 ──────────────────────────────────────────────── */
+
+export type ChecklistProgressMode = 'bar' | 'count' | 'both' | 'none';
+export type ChecklistSectionMode = 'grouped' | 'flat';
+export type ChecklistAssigneeMode = 'hidden' | 'shown' | 'editable';
+
+/**
+ * What people may **see** and **do**. Behaviour, never arbitrary visual redesign: there is no
+ * colour, radius, spacing, type scale, row height or icon here, and there never will be — those
+ * come from `src/tokens`/`src/core` and are the same in every Checklist ever placed
+ * (`docs/architecture/RULE-DRIVEN-COMPONENTS.md`: "The component implementation remains
+ * consistent").
+ *
+ * **There is deliberately no `mode: 'use' | 'build'`.** A mode is a bundle of capability flags,
+ * and a bundle hides which flag is load-bearing for a given placement. Every capability is named
+ * individually below, so "why can I not delete this task?" always has a single-field answer.
+ */
+export type ChecklistConfig = {
+  showDescription: boolean;
+  taskDescriptions: 'shown' | 'hidden';
+  assignees: ChecklistAssigneeMode;
+  progress: ChecklistProgressMode;
+  /** `flat` draws no section chrome; the document's shape is unchanged either way (§4). */
+  sections: ChecklistSectionMode;
+  collapsibleSections: boolean;
+
+  /** One flag per verb, and one `ChecklistChange` kind per flag. */
+  can: {
+    /** Rename the checklist or change its description. Creation needs it; a handed-off copy may not. */
+    editChecklist: boolean;
+    /** Tick a task. `false` ⇒ a read-only checklist, which is a legitimate configuration. */
+    complete: boolean;
+    /** Enables `task.skipped` at all. */
+    skip: boolean;
+    addTask: boolean;
+    editTask: boolean;
+    deleteTask: boolean;
+    addSection: boolean;
+    editSection: boolean;
+    deleteSection: boolean;
+    reorder: boolean;
+    /** Requires `assignees !== 'hidden'` — validated, not merely documented. */
+    assign: boolean;
+  };
+
+  /** The boundaries, off by default. §10, §11. */
+  sharing: { enabled: boolean };
+  /** `channels` holds host-declared channel **ids**. The component ships zero concrete channels. */
+  notifications: { enabled: boolean; channels: string[] };
+
+  /** The nouns. Separate strings because they are different facts. */
+  copy: {
+    /** No tasks at all. */
+    emptyLabel: string;
+    /** Every required task done. */
+    allDoneLabel: string;
+    addTaskLabel: string;
+    addSectionLabel: string;
+  };
+};
+
+/**
+ * A constant, not a derivation — and not dressed up as more. Directory's `defaultConfigFor(schema)`
+ * derives a starting point from what was *discovered*; a Checklist has nothing to discover, so its
+ * default is simply everything visible and everything permitted except `skip`, with both external
+ * boundaries off. A builder edits from here.
+ */
+export function defaultChecklistConfig(): ChecklistConfig {
+  return {
+    showDescription: true,
+    taskDescriptions: 'shown',
+    assignees: 'shown',
+    progress: 'both',
+    sections: 'grouped',
+    collapsibleSections: true,
+    can: {
+      editChecklist: true,
+      complete: true, skip: false,
+      addTask: true, editTask: true, deleteTask: true,
+      addSection: true, editSection: true, deleteSection: true,
+      reorder: true, assign: true,
+    },
+    sharing: { enabled: false },
+    notifications: { enabled: false, channels: [] },
+    copy: {
+      emptyLabel: 'Nothing on this checklist yet',
+      allDoneLabel: 'All done',
+      addTaskLabel: 'Add task',
+      addSectionLabel: 'Add section',
+    },
+  };
+}
+
+/* ── The rules — §6 ──────────────────────────────────────────────────────── */
+
+/**
+ * The events a rule may fire on. Deliberately four: each is something the *document* observably
+ * became, not something the runtime did.
+ */
+export const CHECKLIST_EVENTS = ['task.completed', 'task.uncompleted', 'task.assigned', 'checklist.completed'] as const;
+export type ChecklistEvent = (typeof CHECKLIST_EVENTS)[number];
+
+export type ChecklistTaskField = 'done' | 'skipped' | 'assigneeId';
+export type ChecklistSectionField = 'complete';
+
+/**
+ * A condition names a subject in **this** document and asks one question of it.
+ *
+ * `op` is the repo's existing closed operator set (`FilterOp`, `src/runtime/query`) — reused rather
+ * than re-invented, because it is already validated and already executed by one `applyFilter`.
+ */
+export type ChecklistCondition =
+  | { subject: 'task'; ref: string; field: ChecklistTaskField; op: FilterOp; value: string }
+  | { subject: 'section'; ref: string; field: ChecklistSectionField; op: FilterOp; value: string };
+
+/** "This task cannot be completed until …". Pure, local, deterministic, no side effect. */
+export type ChecklistGateRule = {
+  kind: 'gate';
+  /** The task being gated. Must be a task id of this document. */
+  target: string;
+  /** Every one of these must hold before `target` may be completed. */
+  requires: ChecklistCondition[];
+};
+
+/** "When this happens, a notification is due." The component decides due-ness; the host sends. */
+export type ChecklistNotifyRule = {
+  kind: 'notify';
+  when: ChecklistEvent;
+  /** Optional narrowing, over the same closed vocabulary a gate uses. */
+  if?: ChecklistCondition[];
+  to: 'assignee' | 'sharedWith';
+  /** A channel id the host declared. The component never enumerates channels — §11. */
+  channel: string;
+};
+
+/**
+ * **One primitive, two authors** — `docs/architecture/FILTER-CONTRACT.md` N1, inherited verbatim.
+ * A rule a person builds and a rule an agent adds mid-run are the same object; `author` is
+ * provenance, not a permission level. Both validate through `validateChecklistRule`, both are
+ * bounded by the same document, both execute identically, and a rejection is reported rather than
+ * swallowed. There is no agent-only rule path and no second rule system.
+ */
+export type ChecklistRule = {
+  id: string;
+  author: FilterAuthor;
+  /** Plain words, shown to the user verbatim when a gate blocks them. Not a code comment. */
+  label?: string;
+} & (ChecklistGateRule | ChecklistNotifyRule);
+
+/**
+ * What each field may be asked. A boolean fact takes equality and nothing else — `gt` on `done`
+ * would be an operator the builder offers and the engine cannot mean. An assignee reference adds
+ * presence, because "is anyone on this?" is a real question.
+ */
+export const OPERATORS_BY_FIELD: Record<ChecklistTaskField | ChecklistSectionField, FilterOp[]> = {
+  done: ['eq', 'neq'],
+  skipped: ['eq', 'neq'],
+  complete: ['eq', 'neq'],
+  assigneeId: ['eq', 'neq', 'isEmpty', 'isNotEmpty'],
+};
+
+export const TASK_FIELDS: ChecklistTaskField[] = ['done', 'skipped', 'assigneeId'];
+export const SECTION_FIELDS: ChecklistSectionField[] = ['complete'];
+
+/* ── The change — §7 ─────────────────────────────────────────────────────── */
+
+/**
+ * **Every mutation is one serializable value.** This is the contract's centre of gravity and the
+ * write-side analogue of the query runtime's `QueryDescriptor`.
+ *
+ * It buys three things a `setState` callback would not: a change is **inspectable** (the
+ * Playground's runtime tab shows the real objects), **portable** (a backend and a future agent
+ * receive exactly this, with no translation layer where a user's edit and an agent's edit
+ * diverge), and **reversible** (`applyChange` returns the exact inverse, which is what makes
+ * rollback a fact rather than a best effort).
+ */
+export type ChecklistChangeBody =
+  /**
+   * The checklist's own identity. Added in Phase 2 because creation needs it: a new checklist is
+   * invalid until named (the schema requires `title`, `minLength: 1`), and every other content
+   * edit already flows through `applyChange` while this one had no path at all.
+   *
+   * There is deliberately no `checklist.add`/`checklist.delete` (a document's existence is the
+   * host's concern) and no id mutation (`checklist.id` is identity — changing it makes a
+   * different document).
+   */
+  | { kind: 'checklist.edit'; title?: string; description?: string }
+  | { kind: 'task.complete'; taskId: string; done: boolean }
+  | { kind: 'task.skip'; taskId: string; skipped: boolean }
+  | { kind: 'task.edit'; taskId: string; title?: string; description?: string; required?: boolean }
+  | { kind: 'task.assign'; taskId: string; assigneeId: string | null }
+  | { kind: 'task.add'; sectionId: string; index: number; task: ChecklistTask }
+  | { kind: 'task.delete'; taskId: string }
+  | { kind: 'task.move'; taskId: string; toSectionId: string; toIndex: number }
+  | { kind: 'section.add'; index: number; section: ChecklistSection }
+  | { kind: 'section.edit'; sectionId: string; title: string }
+  | { kind: 'section.delete'; sectionId: string }
+  | { kind: 'section.move'; sectionId: string; toIndex: number };
+
+export type ChecklistChangeKind = ChecklistChangeBody['kind'];
+
+export type ChecklistChange = { id: string; author: FilterAuthor } & ChecklistChangeBody;
+
+export const CHECKLIST_CHANGE_KINDS: ChecklistChangeKind[] = [
+  'checklist.edit',
+  'task.complete', 'task.skip', 'task.edit', 'task.assign', 'task.add', 'task.delete', 'task.move',
+  'section.add', 'section.edit', 'section.delete', 'section.move',
+];
+
+/** Which capability flag governs each change kind. One verb, one flag — §5. */
+export const CAPABILITY_FOR_CHANGE: Record<ChecklistChangeKind, keyof ChecklistConfig['can']> = {
+  'checklist.edit': 'editChecklist',
+  'task.complete': 'complete',
+  'task.skip': 'skip',
+  'task.edit': 'editTask',
+  'task.assign': 'assign',
+  'task.add': 'addTask',
+  'task.delete': 'deleteTask',
+  'task.move': 'reorder',
+  'section.add': 'addSection',
+  'section.edit': 'editSection',
+  'section.delete': 'deleteSection',
+  'section.move': 'reorder',
+};
+
+/* ── The effects — §11 ───────────────────────────────────────────────────── */
+
+/**
+ * What a `notify` rule produced. The pure engine resolves what the **document** knows (an
+ * assignee); the runtime completes what the **session** knows (who it is shared with) before the
+ * host is called. Delivery state is never part of the document.
+ */
+export type ChecklistEffect = {
+  /** Deterministic: `<changeId>:<ruleId>`. Pure, because `applyChange` is. */
+  id: string;
+  kind: 'notify';
+  ruleId: string;
+  channel: string;
+  audience: 'assignee' | 'sharedWith';
+  /** Resolved for `assignee`; empty for `sharedWith` until the runtime fills it in. */
+  recipients: string[];
+  event: ChecklistEvent;
+  checklist: { id: string; title: string };
+  task?: { id: string; title: string };
+};
+
+/* ── The boundaries — §9, §10, §11 ───────────────────────────────────────── */
+
+/** What a task stores. That is the entire identity model. */
+export type AssigneeId = string;
+
+/** What the people boundary returns, for rendering only. No roles, no permissions, no auth. */
+export type Person = { id: string; name: string; initials?: string; email?: string };
+
+/**
+ * The host's half of assignment. Mirrors `DataAdapter`'s split exactly: the component owns the
+ * lifecycle, the host owns the lookup. The library has no user/identity system and does not gain
+ * one here.
+ */
+export type PeopleAdapter = {
+  /** Resolve ids the document already names — for drawing rows. */
+  resolve: (ids: string[], ctx: { signal: AbortSignal }) => Promise<Person[]>;
+  /** Offer candidates for the assign control. `q` is what the person typed. */
+  search: (q: string, ctx: { signal: AbortSignal }) => Promise<Person[]>;
+};
+
+export type ShareRequest = {
+  /** The whole checklist, or specific tasks of it. Both are one request shape. */
+  scope: { kind: 'checklist' } | { kind: 'tasks'; taskIds: string[] };
+  /** Ids from the same vocabulary as an assignee. Not email addresses. */
+  recipients: AssigneeId[];
+  message?: string;
+};
+
+/** `url` is optional **because** what a share *is* — a link, an ACL, a copy — is the host's call. */
+export type ShareResult = { sharedWith: AssigneeId[]; url?: string };
+
+/** Fully resolved, so the host needs no knowledge of the rule model. */
+export type NotificationRequest = {
+  channel: string;
+  to: AssigneeId[];
+  event: ChecklistEvent;
+  checklist: { id: string; title: string };
+  task?: { id: string; title: string };
+};
+
+/** What a `notify` rule is. It is a rule, not a second configuration surface. */
+export type NotificationTrigger = ChecklistNotifyRule;
+
+/** Which channels exist — declared by the host, never by the component. */
+export type ChecklistCapabilities = {
+  channels: { id: string; label: string }[];
+};
+
+/**
+ * The replaceable boundary, the same shape `UploadOperations` established: everything above this
+ * line is the component's, everything inside a function body is the host's.
+ *
+ * **Omit it entirely ⇒ local-only mode**: changes apply, nothing is persisted, nothing ever fails.
+ * That is a legitimate configuration of the component rather than a stub — exactly as
+ * `DirectoryView` without an `adapter` queries in-memory records through the real runtime.
+ */
+export type ChecklistOperations = {
+  /** Persist one change. Resolve = it stuck. Reject = it did not, and the component rolls back. */
+  commit: (change: ChecklistChange, ctx: { doc: Checklist; signal: AbortSignal }) => Promise<void>;
+  /** Only called when `config.sharing.enabled`. */
+  share?: (req: ShareRequest, ctx: { signal: AbortSignal }) => Promise<ShareResult>;
+  /** Only called when a notify rule fires and `config.notifications.enabled`. */
+  notify?: (req: NotificationRequest, ctx: { signal: AbortSignal }) => Promise<void>;
+};
+
+/* ── The document — §14 ──────────────────────────────────────────────────── */
+
+/**
+ * The portable envelope. Three separable contracts, one artefact — the same shape
+ * `DirectoryDocument` uses, with `checklist` where Directory has `source`: Directory's content is
+ * *external* so its document stores a pointer; a Checklist's content *is* the thing, so its
+ * document stores it.
+ *
+ * The content key is `checklist`, not `data`, deliberately: `data` already means a record's cell
+ * map in this repo (`QueryRecord.data`, `DirectoryRecord.data`), and one word with two meanings is
+ * how a contract starts drifting.
+ *
+ * **This is the boundary a builder, a backend and a future agent all produce.** The component
+ * receives only this plus `operations`/`people`/`capabilities`, and has no other input — which is
+ * what makes "same document, same behaviour, whoever wrote it" a testable claim rather than a
+ * promise (`tests/checklistPortability.test.tsx`).
+ */
+export type ChecklistDocument = {
+  schema: 'checklist/1';
+  checklist: Checklist;
+  config: ChecklistConfig;
+  rules: ChecklistRule[];
+};
+
+/* ── Lookup helpers — the vocabulary, as functions ───────────────────────── */
+
+export function findTask(checklist: Checklist, taskId: string): { task: ChecklistTask; section: ChecklistSection; taskIndex: number; sectionIndex: number } | undefined {
+  for (let s = 0; s < checklist.sections.length; s += 1) {
+    const section = checklist.sections[s]!;
+    const t = section.tasks.findIndex(x => x.id === taskId);
+    if (t >= 0) return { task: section.tasks[t]!, section, taskIndex: t, sectionIndex: s };
+  }
+  return undefined;
+}
+
+export function findSection(checklist: Checklist, sectionId: string): ChecklistSection | undefined {
+  return checklist.sections.find(s => s.id === sectionId);
+}
+
+export function allTasks(checklist: Checklist): ChecklistTask[] {
+  return checklist.sections.flatMap(s => s.tasks);
+}
+
+/* ── Validation — an invented id must be impossible, not merely unlikely ─── */
+
+export type ChecklistRuleRejection =
+  | 'unknown-task' | 'unknown-section' | 'unsupported-field'
+  | 'unsupported-operator' | 'empty-value' | 'cycle'
+  | 'unknown-channel' | 'unknown-event';
+
+export type ChecklistRuleCheck = { ok: true } | { ok: false; reason: ChecklistRuleRejection; message: string };
+
+function checkCondition(c: ChecklistCondition, checklist: Checklist): ChecklistRuleCheck {
+  if (c.subject === 'task') {
+    if (!findTask(checklist, c.ref)) {
+      return { ok: false, reason: 'unknown-task', message: `"${c.ref}" is not a task of this checklist` };
+    }
+    if (!TASK_FIELDS.includes(c.field)) {
+      return { ok: false, reason: 'unsupported-field', message: `A task has no "${c.field}"` };
+    }
+  } else {
+    if (!findSection(checklist, c.ref)) {
+      return { ok: false, reason: 'unknown-section', message: `"${c.ref}" is not a section of this checklist` };
+    }
+    if (!SECTION_FIELDS.includes(c.field)) {
+      return { ok: false, reason: 'unsupported-field', message: `A section has no "${c.field}"` };
+    }
+  }
+  const allowed = OPERATORS_BY_FIELD[c.field];
+  if (!allowed || !allowed.includes(c.op)) {
+    return { ok: false, reason: 'unsupported-operator', message: `"${c.op}" does not apply to ${c.field}` };
+  }
+  if (!(FILTER_OPS as readonly string[]).includes(c.op)) {
+    return { ok: false, reason: 'unsupported-operator', message: `"${c.op}" is not an operator` };
+  }
+  if (c.value === '' && !(VALUELESS_FILTER_OPS as readonly string[]).includes(c.op)) {
+    return { ok: false, reason: 'empty-value', message: 'This condition needs a value' };
+  }
+  return { ok: true };
+}
+
+/**
+ * **The same rule for a person's rule and an agent's.** Optionally given the rest of the rule set,
+ * it additionally answers the one question a single rule cannot: would this gate close a cycle?
+ * A-requires-B while B-requires-A is a checklist nobody can finish, and it is rejected at authoring
+ * time rather than discovered at completion time — the one rejection Checklist needs that Directory
+ * does not.
+ */
+export function validateChecklistRule(
+  rule: ChecklistRule,
+  checklist: Checklist,
+  rules: ChecklistRule[] = [],
+  capabilities?: ChecklistCapabilities,
+): ChecklistRuleCheck {
+  if (rule.kind === 'gate') {
+    if (!findTask(checklist, rule.target)) {
+      return { ok: false, reason: 'unknown-task', message: `"${rule.target}" is not a task of this checklist` };
+    }
+    for (const c of rule.requires) {
+      const check = checkCondition(c, checklist);
+      if (!check.ok) return check;
+    }
+    const others = rules.filter(r => r.id !== rule.id);
+    if (hasGateCycle([...others, rule], checklist)) {
+      return { ok: false, reason: 'cycle', message: 'These rules block each other — nothing could ever be completed' };
+    }
+    return { ok: true };
+  }
+
+  if (!(CHECKLIST_EVENTS as readonly string[]).includes(rule.when)) {
+    return { ok: false, reason: 'unknown-event', message: `"${rule.when}" is not a checklist event` };
+  }
+  for (const c of rule.if ?? []) {
+    const check = checkCondition(c, checklist);
+    if (!check.ok) return check;
+  }
+  if (rule.channel === '') {
+    return { ok: false, reason: 'empty-value', message: 'A notification rule needs a channel' };
+  }
+  if (capabilities && !capabilities.channels.some(ch => ch.id === rule.channel)) {
+    return { ok: false, reason: 'unknown-channel', message: `"${rule.channel}" is not a channel this host offers` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Gate dependencies form a graph: `target` depends on every task named by a `done`/`skipped`
+ * condition, and on every task of a section named by a `complete` condition. A cycle in it is a
+ * checklist that can never be finished.
+ */
+export function hasGateCycle(rules: ChecklistRule[], checklist: Checklist): boolean {
+  const deps = new Map<string, string[]>();
+  for (const rule of rules) {
+    if (rule.kind !== 'gate') continue;
+    const on: string[] = [];
+    for (const c of rule.requires) {
+      if (c.subject === 'task') on.push(c.ref);
+      else on.push(...(findSection(checklist, c.ref)?.tasks.map(t => t.id) ?? []));
+    }
+    deps.set(rule.target, [...(deps.get(rule.target) ?? []), ...on]);
+  }
+
+  const WHITE = 0; const GREY = 1; const BLACK = 2;
+  const mark = new Map<string, number>();
+  const visit = (id: string): boolean => {
+    const state = mark.get(id) ?? WHITE;
+    if (state === GREY) return true;
+    if (state === BLACK) return false;
+    mark.set(id, GREY);
+    for (const next of deps.get(id) ?? []) if (visit(next)) return true;
+    mark.set(id, BLACK);
+    return false;
+  };
+  for (const id of deps.keys()) if (visit(id)) return true;
+  return false;
+}
+
+/** Every rule the set contains, split into the ones that hold and the ones that do not. */
+export function validateChecklistRules(
+  rules: ChecklistRule[],
+  checklist: Checklist,
+  capabilities?: ChecklistCapabilities,
+): { accepted: ChecklistRule[]; rejected: { rule: ChecklistRule; author: FilterAuthor; reason: ChecklistRuleRejection; message: string }[] } {
+  const accepted: ChecklistRule[] = [];
+  const rejected: { rule: ChecklistRule; author: FilterAuthor; reason: ChecklistRuleRejection; message: string }[] = [];
+  for (const rule of rules) {
+    /* Validated against the rules ALREADY accepted, so the first rule of a mutually-blocking pair
+       survives and the one that closes the cycle is the one reported. */
+    const check = validateChecklistRule(rule, checklist, accepted, capabilities);
+    if (check.ok) accepted.push(rule);
+    else rejected.push({ rule, author: rule.author, reason: check.reason, message: check.message });
+  }
+  return { accepted, rejected };
+}
+
+/**
+ * Configuration errors, as messages. `[]` means valid — `validateDirectoryConfig`'s shape exactly.
+ *
+ * It checks the internal consistency the *type* cannot. Like Directory's, it matters chiefly for a
+ * **saved** configuration meeting content that has since changed, and like Directory's, the result
+ * is shown as a configuration problem rather than as a blank card that reads like "nothing here".
+ */
+export function validateChecklistConfig(
+  config: ChecklistConfig,
+  opts: { checklist?: Checklist; rules?: ChecklistRule[]; capabilities?: ChecklistCapabilities } = {},
+): string[] {
+  const errors: string[] = [];
+
+  if (config.can.assign && config.assignees === 'hidden') {
+    errors.push('Assign: tasks can be assigned but assignees are hidden');
+  }
+  if (config.notifications.enabled && config.notifications.channels.length === 0) {
+    errors.push('Notifications: enabled with no channel selected');
+  }
+  if (opts.capabilities) {
+    for (const id of config.notifications.channels) {
+      if (!opts.capabilities.channels.some(c => c.id === id)) {
+        errors.push(`Notifications: "${id}" is not a channel this host offers`);
+      }
+    }
+  }
+  if (!config.can.skip && opts.checklist && allTasks(opts.checklist).some(t => t.skipped)) {
+    errors.push('Skip: tasks are marked skipped but skipping is turned off');
+  }
+  for (const rule of opts.rules ?? []) {
+    if (rule.kind !== 'notify') continue;
+    if (!config.notifications.enabled) {
+      errors.push(`Notifications: rule "${rule.id}" would notify, but notifications are turned off`);
+    } else if (!config.notifications.channels.includes(rule.channel)) {
+      errors.push(`Notifications: rule "${rule.id}" uses "${rule.channel}", which this checklist does not send on`);
+    }
+    if (!config.can.complete && (rule.when === 'task.completed' || rule.when === 'checklist.completed')) {
+      errors.push(`Notifications: rule "${rule.id}" fires on completion, but tasks cannot be completed`);
+    }
+  }
+  return errors;
+}
+
+export { type FilterOp, type FilterAuthor };