@startsimpli/integrations 0.2.24 → 0.2.26

package/src/corpus/planning.ts

@@ -0,0 +1,323 @@
+/**
+ * FOCUSES AND AUTHORED ITEMS — the mapping layer for the planning toolset
+ * (bd startsim-8l6ef).
+ *
+ * The sibling of `entities.ts`, and split from it for the same reason
+ * `CommitmentApi` is split from `CorpusApi`: a deployment can have a corpus with
+ * no planning surface at all, and the Library and Ask screens must not start
+ * depending on a schema that may never have been declared.
+ *
+ * WHAT THIS FILE IS RESPONSIBLE FOR, and it is a short list on purpose:
+ *
+ *   IDENTITY   an authored row needs one, and it must not be able to collide
+ *              with an extracted row's `commit:<dedupeKey>`.
+ *   TIMESTAMPS an authored item has no meeting to date it, so the authoring
+ *              path stamps its own — see `authoredItemToEntity`, where getting
+ *              this wrong hides authored items from three of four tabs.
+ *   PROGRESS   arithmetic over counts, and NOTHING that writes.
+ *
+ * WHAT IT IS DELIBERATELY NOT RESPONSIBLE FOR: filing. An item belongs to a
+ * focus by way of an `in_focus` RELATIONSHIP, which is a second write with no
+ * transaction around it, so it lives in the client next to the other edge
+ * writes rather than being smuggled into an entity payload here.
+ */
+import { ORIGIN, ORIGIN_KEY, type TenantEntity } from './entities';
+import type {
+  Commitment,
+  CorpusScope,
+  Focus,
+  FocusCategory,
+  FocusDraft,
+  FocusStanding,
+  FocusStatus,
+  FocusTimeFrame,
+} from './types';
+
+/** The entity type key a focus lands under, matching `scripts/schemas/planning.json`. */
+export const FOCUS_TYPE = 'focus';
+
+/** The edge types, matching the same payload and the tenant's `capabilities()`. */
+export const IN_FOCUS = 'in_focus';
+export const SUB_FOCUS = 'sub_focus';
+
+const FOCUS_STATUSES: readonly FocusStatus[] = [
+  'draft', 'active', 'on_track', 'at_risk', 'off_track', 'completed', 'cancelled',
+];
+const FOCUS_CATEGORIES: readonly FocusCategory[] = [
+  'milestone', 'financial', 'product', 'team', 'market', 'other',
+];
+const FOCUS_TIME_FRAMES: readonly FocusTimeFrame[] = [
+  'Q1', 'Q2', 'Q3', 'Q4', 'H1', 'H2', 'annual', 'custom',
+];
+
+// ---------------------------------------------------------------------------
+//  identity
+// ---------------------------------------------------------------------------
+
+/**
+ * `focus:<slug>` from a title.
+ *
+ * STABLE ACROSS RENAMES is the property that matters, and it is why the slug is
+ * taken once at creation and never recomputed: `external_id` is what the
+ * tenant's upsert keys on, so deriving it from the CURRENT title would make
+ * renaming a focus fork it into a second row with the first one's items still
+ * attached to the original.
+ */
+export function focusSlug(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return slug || 'untitled';
+}
+
+/**
+ * A fresh id for an authored item.
+ *
+ * INJECTABLE, so a test asserts a payload rather than a regex. Falls back to a
+ * timestamp-plus-counter when `crypto.randomUUID` is unavailable (older Safari,
+ * a non-secure context) — uniqueness within one workspace is all the key needs,
+ * because `external_id` is unique per (org, type, owner) and not globally.
+ */
+let authoredCounter = 0;
+export function authoredId(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  authoredCounter += 1;
+  return `${Date.now().toString(36)}-${authoredCounter.toString(36)}`;
+}
+
+// ---------------------------------------------------------------------------
+//  focus <-> entity
+// ---------------------------------------------------------------------------
+
+function bag(entity: TenantEntity): Record<string, unknown> {
+  const data = entity.data;
+  return data && typeof data === 'object' ? (data as Record<string, unknown>) : {};
+}
+
+function pick(data: Record<string, unknown>, ...keys: string[]): unknown {
+  for (const key of keys) {
+    const value = data[key];
+    if (value !== undefined && value !== null && value !== '') return value;
+  }
+  return undefined;
+}
+
+function text(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return '';
+}
+
+function num(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (typeof value === 'string' && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): T | undefined {
+  const raw = text(value);
+  return (allowed as readonly string[]).includes(raw) ? (raw as T) : undefined;
+}
+
+export function toFocus(entity: TenantEntity, fallbackScope: CorpusScope): Focus {
+  const data = bag(entity);
+  const externalId = text(entity.external_id ?? entity.externalId);
+  const orgId = text(entity.org_id ?? entity.orgId) || fallbackScope.orgId;
+  const ownerSub = text(entity.owner_sub ?? entity.ownerSub) || fallbackScope.ownerSub || '';
+
+  const target = num(pick(data, 'target_value', 'targetValue'));
+  const current = num(pick(data, 'current_value', 'currentValue'));
+  const progress = num(pick(data, 'progress'));
+  const year = num(pick(data, 'year'));
+  const sortOrder = num(pick(data, 'sort_order', 'sortOrder'));
+
+  return {
+    id: String(entity.id),
+    externalId: externalId || `${FOCUS_TYPE}:${entity.id}`,
+    title: text(pick(data, 'title')) || entity.name || 'Untitled focus',
+    detail: text(pick(data, 'detail', 'description')),
+    // `draft` is the floor rather than `active`: a row whose status did not
+    // survive a round trip must not present as work somebody committed to.
+    status: oneOf(pick(data, 'status'), FOCUS_STATUSES) ?? 'draft',
+    ...(oneOf(pick(data, 'category'), FOCUS_CATEGORIES)
+      ? { category: oneOf(pick(data, 'category'), FOCUS_CATEGORIES) } : {}),
+    ...(oneOf(pick(data, 'time_frame', 'timeFrame'), FOCUS_TIME_FRAMES)
+      ? { timeFrame: oneOf(pick(data, 'time_frame', 'timeFrame'), FOCUS_TIME_FRAMES) } : {}),
+    ...(year !== undefined ? { year } : {}),
+    ...(pick(data, 'start_date', 'startDate')
+      ? { startDate: text(pick(data, 'start_date', 'startDate')) } : {}),
+    ...(pick(data, 'end_date', 'endDate')
+      ? { endDate: text(pick(data, 'end_date', 'endDate')) } : {}),
+    // Spread-if-defined rather than `?? null`, so "no target" stays absent and
+    // never becomes a 0 that reads as a fully-achieved measurable focus.
+    ...(target !== undefined ? { targetValue: target } : {}),
+    ...(current !== undefined ? { currentValue: current } : {}),
+    ...(pick(data, 'unit') ? { unit: text(pick(data, 'unit')) } : {}),
+    ...(progress !== undefined ? { progress } : {}),
+    ...(sortOrder !== undefined ? { sortOrder } : {}),
+    ...(pick(data, 'owner_sub', 'ownerSub')
+      ? { ownerSub: text(pick(data, 'owner_sub', 'ownerSub')) } : {}),
+    ...(pick(data, 'owner_name', 'ownerName')
+      ? { ownerName: text(pick(data, 'owner_name', 'ownerName')) } : {}),
+    scope: ownerSub ? { orgId, ownerSub } : { orgId },
+  };
+}
+
+/** The write side: a focus draft as the tenant's upsert payload. */
+export function focusToEntity(draft: FocusDraft, externalId?: string): {
+  entity_type: string;
+  external_id: string;
+  name: string;
+  data: Record<string, unknown>;
+} {
+  const title = draft.title.trim() || 'Untitled focus';
+  return {
+    entity_type: FOCUS_TYPE,
+    external_id: externalId || `${FOCUS_TYPE}:${focusSlug(title)}`,
+    name: title.slice(0, 200),
+    data: {
+      title,
+      ...(draft.detail ? { detail: draft.detail } : {}),
+      status: draft.status ?? 'active',
+      ...(draft.category ? { category: draft.category } : {}),
+      ...(draft.timeFrame ? { time_frame: draft.timeFrame } : {}),
+      ...(draft.year !== undefined && draft.year !== null ? { year: draft.year } : {}),
+      ...(draft.startDate ? { start_date: draft.startDate } : {}),
+      ...(draft.endDate ? { end_date: draft.endDate } : {}),
+      ...(draft.targetValue !== undefined && draft.targetValue !== null
+        ? { target_value: draft.targetValue } : {}),
+      ...(draft.currentValue !== undefined && draft.currentValue !== null
+        ? { current_value: draft.currentValue } : {}),
+      ...(draft.unit ? { unit: draft.unit } : {}),
+      ...(draft.ownerSub ? { owner_sub: draft.ownerSub } : {}),
+      ...(draft.ownerName ? { owner_name: draft.ownerName } : {}),
+      [ORIGIN_KEY]: ORIGIN.authored,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  authored items
+// ---------------------------------------------------------------------------
+
+/**
+ * A person's own item as the tenant's upsert payload.
+ *
+ * THE TIMESTAMPS ARE THE POINT OF THIS FUNCTION, not the identity.
+ *
+ * An extracted item gets `first_seen_at` and `last_seen_at` from the meeting
+ * that raised it. An authored one has no meeting — and if those two fields are
+ * left empty, the item is not merely undated: it silently disappears from three
+ * of the tracker's four tabs. "Changed this week" filters on `last_seen_at`, the
+ * age line ("open for 6 days") reads `first_seen_at`, and the server-side
+ * `changedAfter` filter is a `attr.last_seen_at__gte` that a null never matches.
+ *
+ * The whole argument for putting these rows tenant-side is that an extracted
+ * item and a hand-authored one appear in ONE list. Three tabs quietly excluding
+ * half of it would make that claim false on screen while it stayed true in the
+ * database, which is the worst of both.
+ *
+ * `now` is injectable for the same reason `TrackerPageProps.now` is: a clock
+ * read inside a render is a new value every render.
+ */
+export function authoredItemToEntity(
+  draft: {
+    title: string;
+    detail?: string;
+    subtype?: string;
+    status?: string;
+    ownerName?: string;
+    ownerSub?: string;
+    subject?: string;
+    dueAt?: string | null;
+    priority?: number;
+  },
+  options: { id?: string; now?: number; itemType?: string } = {},
+): { entity_type: string; external_id: string; name: string; data: Record<string, unknown> } {
+  const title = draft.title.trim();
+  const stamp = new Date(options.now ?? Date.now()).toISOString();
+  return {
+    // The item type key is the historical `commitment`, so an authored row and
+    // an extracted one land in the same list — see the payload's own note.
+    entity_type: options.itemType ?? 'commitment',
+    // `item:` and not `commit:`, so an authored row can never collide with an
+    // extracted row's `commit:<dedupeKey>` — and so a re-derivation can tell at
+    // a glance which rows it is allowed to rewrite.
+    external_id: `item:${options.id ?? authoredId()}`,
+    name: title.slice(0, 200),
+    data: {
+      title,
+      detail: draft.detail ?? '',
+      subtype: draft.subtype || 'action',
+      status: draft.status || 'open',
+      ...(draft.ownerName ? { owner_name: draft.ownerName } : {}),
+      ...(draft.ownerSub ? { owner_sub: draft.ownerSub } : {}),
+      ...(draft.subject ? { subject: draft.subject } : {}),
+      ...(draft.dueAt ? { due_at: draft.dueAt } : {}),
+      ...(draft.priority !== undefined ? { priority: draft.priority } : {}),
+      first_seen_at: stamp,
+      last_seen_at: stamp,
+      // No mentions, and the array is written EMPTY rather than omitted: a
+      // reader that has to distinguish "authored, so no meeting" from "the key
+      // is missing" should not have to guess, and the row renderer branches on
+      // exactly this.
+      mentions: [],
+      mention_count: 0,
+      [ORIGIN_KEY]: ORIGIN.authored,
+    },
+  };
+}
+
+/** True when this row was typed by a person rather than read out of a meeting. */
+export function isAuthored(item: Commitment): boolean {
+  return item.origin === ORIGIN.authored || item.externalId.startsWith('item:');
+}
+
+// ---------------------------------------------------------------------------
+//  standing — arithmetic only, and nothing that writes
+// ---------------------------------------------------------------------------
+
+/**
+ * How far along a focus is, as a fraction, or `null` when there is nothing to
+ * say.
+ *
+ * TWO WAYS, mirroring `Goal`'s: a MEASURABLE focus (one with a target) is
+ * current/target; a qualitative one is done/total over its items. `null` when
+ * neither applies, because a focus with no target and no items has no progress —
+ * rendering that as 0% says "started and got nowhere" about work nobody has
+ * filed anything under yet.
+ *
+ * PURE, AND IT NEVER WRITES. `Focus.progress` is a STORED field, set by a person
+ * or by an explicit recalculation the user asks for. Wiring this into a render
+ * effect that PATCHes the result back is the 917-requests-in-ten-minutes loop
+ * recorded on `TrackerPageProps.now`, with a write on every pass.
+ */
+export function focusProgress(focus: Focus, standing?: FocusStanding | null): number | null {
+  if (focus.targetValue !== undefined && focus.targetValue !== null && focus.targetValue > 0) {
+    const current = focus.currentValue ?? 0;
+    return Math.max(0, Math.min(current / focus.targetValue, 1));
+  }
+  if (standing && standing.total > 0) {
+    return Math.max(0, Math.min(standing.done / standing.total, 1));
+  }
+  return null;
+}
+
+/**
+ * What to SHOW for a focus: the stored value when there is one, the derived one
+ * otherwise.
+ *
+ * The stored field wins because it is what the server ORDERS by
+ * (`?order=-attr.progress`), and a card that displayed a number the list was not
+ * sorted by would make the sort look broken.
+ */
+export function displayProgress(focus: Focus, standing?: FocusStanding | null): number | null {
+  if (focus.progress !== undefined && focus.progress !== null) return focus.progress;
+  return focusProgress(focus, standing);
+}

package/src/corpus/types.ts

@@ -511,6 +511,40 @@ export interface Commitment {
   actionKey: string;
   /** When it is due, only when the source actually said so. Never invented. */
   dueAt?: string | null;
+  /**
+   * 0 critical .. 4 backlog — `WorkItem.Priority` verbatim, so ascending is
+   * urgent and a triage list needs no per-client mapping table.
+   *
+   * OPTIONAL AND UNSET IS NOT 2. An extracted item has no priority because
+   * nobody assigned one, and defaulting it to "medium" would put a hundred
+   * unreviewed rows in the middle of a list somebody is trying to triage.
+   */
+  priority?: number;
+  /**
+   * Which focus this item is filed under, when it is filed at all.
+   *
+   * Extraction writes items UNFILED, which is what keeps `saveCommitments` a
+   * single bulk upsert — filing is a second write (an `in_focus` edge) and an
+   * explicitly human act. So `undefined` here is a real and common state, not a
+   * loading artefact.
+   */
+  focusId?: string;
+  /**
+   * Who owes it, as a MEMBER — the central user_id behind the subtree roster.
+   *
+   * ADDITIVE TO `ownerName`, never a replacement (bd startsim-768w.38.29). The
+   * name is what the meeting said; this is the join to a person, and it is what
+   * makes "assigned to me" a server filter instead of a scan over free text.
+   */
+  ownerSub?: string;
+  /**
+   * Where the row came from: `tenant-extraction`, `human`, `central-pipeline`.
+   *
+   * Reads and writes the `_origin` key that three writers have used for months,
+   * NOT a field called `origin` — see `ORIGIN` in `./entities` for why the
+   * underscore is load-bearing and why this arrives from a browser as `Origin`.
+   */
+  origin?: string;
   mentions: CommitmentMention[];
   firstSeenAt: string | null;
   lastSeenAt: string | null;
@@ -536,6 +570,30 @@ export interface CommitmentDraft {
   extractor: 'rules' | 'model';
 }
 
+/**
+ * A trackable thing a PERSON typed, rather than one read out of a meeting.
+ *
+ * Deliberately not a `Partial<Commitment>`: an authored item has no dedupe key,
+ * no mentions and no extractor, and a type that pretended otherwise would let a
+ * caller hand the authoring path a half-built extracted row. Everything the
+ * mapper needs to invent (identity, timestamps, origin) it invents in one place.
+ */
+export interface AuthoredItem {
+  title: string;
+  detail?: string;
+  /** `action` when the caller does not say — including `requirement`, which is
+   *  a subtype rather than a model precisely so it costs nothing to add. */
+  subtype?: CommitmentSubtype;
+  status?: CommitmentStatus;
+  ownerName?: string;
+  ownerSub?: string;
+  subject?: string;
+  dueAt?: string | null;
+  priority?: number;
+  /** File it on creation. Omit to create it unfiled, like an extracted row. */
+  focusId?: string;
+}
+
 /**
  * A statement in a LATER meeting that something previously outstanding is now
  * settled. Extracted separately from commitments because closing an item is a
@@ -562,6 +620,18 @@ export interface CommitmentQuery {
   dueBefore?: string;
   /** ISO instant over `lastSeenAt` — "what changed since last week". */
   changedAfter?: string;
+  /**
+   * Only the items filed under this focus (its tenant row id, not its slug).
+   *
+   * THE SERVER ANSWERS THIS AS AN EDGE WALK, so it reports the filter back as
+   * `related_to` rather than `focus`. The client's applied-filter
+   * reconciliation has to know that, or the honesty banner announces that the
+   * workspace "did not filter by focus" while the server verifiably did — the
+   * same class of bug as reading only one spelling of `applied_filters`.
+   */
+  focus?: string;
+  /** `tenant-extraction` | `human` | ... — filters on the `_origin` attribute. */
+  origin?: string;
   search?: string;
   page?: number;
   pageSize?: number;
@@ -581,9 +651,35 @@ export interface CommitmentApi {
    * than a read-modify-write race in this package.
    */
   saveCommitments?(commitments: Commitment[]): Promise<void>;
-  /** A human overriding the extractor. The extractor must never overwrite this. */
-  updateCommitment?(id: string, patch: Partial<Pick<Commitment,
-    'status' | 'statusReason' | 'ownerName' | 'dueAt' | 'subtype'>>): Promise<Commitment>;
+  /**
+   * A human overriding the extractor. The extractor must never overwrite this.
+   *
+   * TAKES THE ROW, NOT ITS ID, because the write is a shallow-merging upsert
+   * keyed on `external_id` — the only tenant verb that preserves keys the caller
+   * did not send. A signature of `(id, patch)` would force every caller into a
+   * read-modify-write, which is the race the upsert exists to remove.
+   */
+  updateCommitment?(item: Commitment, patch: Partial<Pick<Commitment,
+    'status' | 'statusReason' | 'ownerName' | 'ownerSub' | 'dueAt' | 'subtype'
+    | 'priority' | 'title' | 'detail'>>): Promise<Commitment>;
+  /**
+   * A person adding an item nobody said in a meeting.
+   *
+   * SEPARATE FROM `saveCommitments` ON PURPOSE. That one is the extractor's bulk
+   * upsert keyed by `externalId`, and its documented property — one call
+   * carrying every row, so the tenant's upsert provides idempotency rather than
+   * a read-modify-write race — is exactly what a per-item authoring call would
+   * break if it were folded in.
+   */
+  createCommitment?(draft: AuthoredItem): Promise<Commitment>;
+  /**
+   * File an item under a focus, or unfile it with `null`.
+   *
+   * Its own verb because it writes an EDGE, not a field: there is no transaction
+   * around an entity write and a relationship write, so the two stay separately
+   * observable rather than pretending to be atomic.
+   */
+  fileCommitment?(item: Commitment, focusId: string | null): Promise<void>;
 }
 
 /**
@@ -938,3 +1034,145 @@ export interface CorpusAskApi {
     scope: CorpusScope;
   }): Promise<SourceDocument>;
 }
+
+// ---------------------------------------------------------------------------
+//  focuses — the planning layer above items (bd startsim-8l6ef)
+// ---------------------------------------------------------------------------
+
+/**
+ * `Goal.Status` verbatim, and the whole seven rather than a convenient subset.
+ *
+ * `on_track` / `at_risk` / `off_track` are a HEALTH judgement a person makes and
+ * are NOT derivable from progress — a focus at 40% can be on track in March and
+ * off track in June. Dropping them would push that judgement into prose, where
+ * nothing can filter on it. `cancelled` is not `completed` and must never render
+ * as it, the same distinction `CommitmentStatus` draws between `dropped` and
+ * `done`.
+ */
+export type FocusStatus =
+  | 'draft' | 'active' | 'on_track' | 'at_risk' | 'off_track' | 'completed' | 'cancelled';
+
+/** `Goal.Category` verbatim. */
+export type FocusCategory =
+  | 'milestone' | 'financial' | 'product' | 'team' | 'market' | 'other';
+
+/** `Goal.TimeFrame` verbatim. `custom` makes the dates the authority. */
+export type FocusTimeFrame =
+  | 'Q1' | 'Q2' | 'Q3' | 'Q4' | 'H1' | 'H2' | 'annual' | 'custom';
+
+/**
+ * Something a team is trying to achieve, that items roll up into.
+ *
+ * The `Goal` analogue, field for field, and that is the whole reuse contract:
+ * the rows live tenant-side under RLS because a central `Goal` cannot FK a
+ * tenant document, but the VOCABULARY is central's, so "at risk" means the same
+ * thing in both planes and a later rollup needs no translation table.
+ */
+export interface Focus {
+  id: string;
+  /** `focus:<slug>` — stable across renames, so a re-import converges. */
+  externalId: string;
+  title: string;
+  detail: string;
+  status: FocusStatus;
+  category?: FocusCategory;
+  timeFrame?: FocusTimeFrame;
+  year?: number | null;
+  startDate?: string | null;
+  endDate?: string | null;
+  /**
+   * The numeric target, when there is one. Its ABSENCE is meaningful and is the
+   * switch `Goal.is_measurable` reads: with no target, a focus is qualitative
+   * and its standing comes from its items. Never coerce this to 0 — that turns
+   * every qualitative focus into a fully-achieved measurable one.
+   */
+  targetValue?: number | null;
+  currentValue?: number | null;
+  unit?: string;
+  /**
+   * 0.0-1.0, STORED rather than aggregated live, exactly as `Goal.progress` is.
+   *
+   * Storing it is what lets the SERVER answer "worst-off focuses first"
+   * (`?order=-attr.progress`). It is set by a person or by an explicit
+   * recalculation — NEVER from a render effect. A component that recomputed and
+   * PATCHed progress while loading is the write-loop that already cost 917
+   * requests in ten minutes on a live tenant; see `TrackerPageProps.now`.
+   */
+  progress?: number | null;
+  sortOrder?: number;
+  ownerSub?: string;
+  ownerName?: string;
+  /** The parent focus, when this one nests. Mirrors `Goal.parent`. */
+  parentId?: string;
+  scope: CorpusScope;
+}
+
+/** What a person types to create a focus. */
+export interface FocusDraft {
+  title: string;
+  detail?: string;
+  status?: FocusStatus;
+  category?: FocusCategory;
+  timeFrame?: FocusTimeFrame;
+  year?: number | null;
+  startDate?: string | null;
+  endDate?: string | null;
+  targetValue?: number | null;
+  currentValue?: number | null;
+  unit?: string;
+  ownerSub?: string;
+  ownerName?: string;
+  parentId?: string;
+}
+
+/** Server-side filters for the focus list (CLAUDE.md rule 8). */
+export interface FocusQuery {
+  status?: FocusStatus | FocusStatus[];
+  category?: FocusCategory;
+  timeFrame?: FocusTimeFrame;
+  year?: number;
+  owner?: string;
+  search?: string;
+  /** `progress` ascending is worst-off first, which is the useful default. */
+  orderBy?: 'progress' | '-progress' | 'sortOrder' | 'title';
+  page?: number;
+  pageSize?: number;
+}
+
+/**
+ * How a focus is doing, counted rather than aggregated.
+ *
+ * TWO `page_size=1` READS off the paginator's own `count`, which is why there is
+ * no group_by endpoint on the tenant plane: the number is already available, and
+ * a group_by that skipped the readable-attribute gate would leak the
+ * distribution of a redacted field.
+ */
+export interface FocusStanding {
+  focusId: string;
+  total: number;
+  done: number;
+  /** Open items whose stated due date has passed. */
+  overdue: number;
+}
+
+/**
+ * The planning surface's contract.
+ *
+ * Extends `CommitmentApi` rather than sitting beside it because focuses and
+ * items are ONE surface over one list — a screen that could read focuses without
+ * reading their items would be a folder tree with nothing in it.
+ */
+export interface PlanningApi extends CommitmentApi {
+  listFocuses(query?: FocusQuery): Promise<CorpusPage<Focus>>;
+  createFocus?(draft: FocusDraft): Promise<Focus>;
+  /** Takes the row for the same reason `updateCommitment` does. */
+  updateFocus?(focus: Focus, patch: Partial<FocusDraft>): Promise<Focus>;
+  /** Children of a focus, one level. The tree is walked a level at a time
+   *  because the query layer caps a traversal at `related_depth=2`. */
+  listChildFocuses?(focusId: string): Promise<CorpusPage<Focus>>;
+  /** Counts for one focus, from `count` alone — no row bodies cross the wire. */
+  focusStanding?(focusId: string, now?: number): Promise<FocusStanding>;
+  /** The tenant's real members, for the owner picker. Absent when the fork is
+   *  not wired to central, in which case owners stay free text. */
+  listMembers?(): Promise<Array<{ sub: string; email: string; name?: string }>>;
+}