@startsimpli/integrations 0.2.25 → 0.2.27

package/src/corpus/client.ts

@@ -39,6 +39,14 @@ import {
   toSourceDocument,
 } from './entities';
 import type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
+import {
+  FOCUS_TYPE,
+  IN_FOCUS,
+  SUB_FOCUS,
+  authoredItemToEntity,
+  focusToEntity,
+  toFocus,
+} from './planning';
 import type {
   Commitment,
   CommitmentApi,
@@ -49,9 +57,15 @@ import type {
   DocumentQuery,
   ExtractionRun,
   ExtractionRunStore,
+  AuthoredItem,
+  Focus,
+  FocusDraft,
+  FocusQuery,
+  FocusStanding,
   MoneyEvent,
   Party,
   PartyRef,
+  PlanningApi,
   SourceFreshness,
 } from './types';
 
@@ -66,6 +80,18 @@ import type {
 export interface CorpusHttp {
   get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T>;
   post?<T>(path: string, body?: unknown, options?: { params?: Record<string, unknown> }): Promise<T>;
+  /**
+   * OPTIONAL, and needed by exactly one operation: UNFILING an item.
+   *
+   * Every other write in this file is a shallow-merging upsert, which is the
+   * only tenant verb that preserves keys the caller did not send. Removing an
+   * `in_focus` edge cannot be expressed that way — an edge is a row, not a
+   * field — and marking it dead instead would leave a tombstone every other
+   * reader has to know to ignore. A client without this can file and re-file;
+   * `fileCommitment(item, null)` reports that it cannot unfile rather than
+   * appearing to succeed.
+   */
+  delete?<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T>;
 }
 
 export interface CreateCorpusApiOptions {
@@ -82,7 +108,21 @@ export interface CreateCorpusApiOptions {
    */
   supportedFilters?: Array<keyof DocumentQuery | keyof CommitmentQuery>;
   /** Endpoint bases, without leading/trailing slashes (the client convention). */
-  paths?: { entities?: string; connections?: string; relationships?: string };
+  paths?: {
+    entities?: string;
+    connections?: string;
+    relationships?: string;
+    /**
+     * The fork's own same-origin roster, for the owner picker.
+     *
+     * Threaded through here rather than hardcoded because `listMembers` fails
+     * SOFT: a fork whose roster lives elsewhere would swallow the 404 into "no
+     * members", the picker would quietly disappear, and owners would fall back
+     * to free text — which is precisely the gap (bd startsim-768w.38.29) the
+     * picker exists to close, reappearing as an empty dropdown with no error.
+     */
+    members?: string;
+  };
   /** How old a source's last sync may be before the Library calls it stale. */
   staleAfterHours?: number;
   /**
@@ -181,7 +221,18 @@ function commitmentParams(query: CommitmentQuery, type: string): Record<string,
   if (query.owner) out['attr.owner_name__icontains'] = query.owner.slice(0, TEXT_FILTER_MAX);
   if (query.dueBefore) out['attr.due_at__lte'] = query.dueBefore;
   if (query.changedAfter) out['attr.last_seen_at__gte'] = query.changedAfter;
+  if (query.origin) out['attr._origin'] = query.origin;
   if (query.search) out.search = query.search.slice(0, TEXT_FILTER_MAX);
+  if (query.focus) {
+    // FILING IS AN EDGE, so "the items in this focus" is an edge walk and not an
+    // attribute match. `related_direction` describes the RETURNED ROW's end of
+    // the edge (apps/api/filters.py::_one_hop) and an item is the SOURCE of its
+    // own `in_focus` edge — so `out` is correct here, and `in` would silently
+    // return an empty page rather than an error.
+    out.related_to = query.focus;
+    out.related_via = IN_FOCUS;
+    out.related_direction = 'out';
+  }
   return out;
 }
 
@@ -192,6 +243,14 @@ const FILTER_PARAMS: Array<[keyof CommitmentQuery, string[]]> = [
   ['owner', ['attr.owner_name__icontains']],
   ['dueBefore', ['attr.due_at__lte']],
   ['changedAfter', ['attr.last_seen_at__gte']],
+  ['origin', ['attr._origin']],
+  // THE CLIENT ASKS FOR `focus`; THE SERVER CONFIRMS `related_to`. Without this
+  // row the reconciliation below never matches, and the screen announces that
+  // this workspace's data API "did not filter by focus" while the server
+  // verifiably did — the same lie, from the same cause, as reading only one
+  // spelling of `applied_filters`. `partyId -> related_to` on the document side
+  // is the same shape, and the precedent for it.
+  ['focus', ['related_to']],
   ['search', ['search']],
 ];
 
@@ -261,6 +320,38 @@ function appliedFilters(
   return requested.filter((key) => supported.includes(key));
 }
 
+/**
+ * Is this response the ROW that was asked for, or something else wearing a 200?
+ *
+ * Three things are refused, and each of them has been seen answering a
+ * single-record request somewhere: a DRF page (what an ignored `?id=` returns —
+ * verified on the live tenant, 200 with count 180), a body with no id at all,
+ * and a row whose id is somebody else's.
+ */
+function isRecord(value: unknown, id: string): value is TenantEntity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  // A page is the shape a LIST answers with. It is never one record, whatever
+  // its count happens to be.
+  if (Array.isArray((value as { results?: unknown }).results)) return false;
+  const own = (value as TenantEntity).id;
+  if (own === undefined || own === null || String(own).trim() === '') return false;
+  // Case-insensitively, because a UUID has two legal spellings and the server
+  // answers in its own. Anything else different is a DIFFERENT RECORD, which is
+  // the entire reason this function exists.
+  return String(own).trim().toLowerCase() === String(id).trim().toLowerCase();
+}
+
+/**
+ * The tenant's own word for a row that is not there.
+ *
+ * 404 and not a bespoke error, because the tenant's read gate makes a row this
+ * principal may not see ABSENT rather than refused — so callers get one status
+ * to branch on, and "not found" is already the honest word for both.
+ */
+function notFound(id: string): Error & { status: number } {
+  return Object.assign(new Error(`No record ${id} in this workspace.`), { status: 404 });
+}
+
 export function createCorpusApi(
   options: CreateCorpusApiOptions,
 ): CorpusApi & CommitmentApi & ExtractionRunStore {
@@ -364,11 +455,34 @@ export function createCorpusApi(
       };
     },
 
+    /**
+     * ONE record, by the DETAIL ROUTE — never by a filter (bd startsim-2lt8y).
+     *
+     * `/api/v1/entities/<id>/` is a real route on the tenant and it answers the
+     * one row. The entity LIST has no `id` filter: `EntityQuery._note_unknown`
+     * sweeps every unrecognised parameter into `ignored_filters` and returns the
+     * page exactly as wide as it was, so `?id=<uuid>` comes back 200 with the
+     * whole corpus. A lookup spelled that way cannot fail — it just answers with
+     * somebody else's record.
+     *
+     * WHICH IS WHY THE RESPONSE IS CHECKED. Asking the right route is not the
+     * same as being answered by it: a proxy that drops the path segment, a
+     * deployment whose detail route lists, an `?id=` that got ignored upstream —
+     * all hand back a DRF page where a row was expected, and `toSourceDocument`
+     * will map it without complaint into a document with the id `undefined` and
+     * the title "Untitled unknown record". That renders as a blank panel that
+     * claims to be the record, which is worse than an error because nobody
+     * downstream can tell it is wrong. So a response that is not the row that
+     * was asked for is a 404, reported the same way the tenant reports an absent
+     * row — the read gate makes a forbidden row ABSENT rather than refused, so
+     * "not found" is already the honest word for both.
+     */
     async getDocument(id) {
       const [entity, byRecord] = await Promise.all([
         http.get<TenantEntity>(`${entities}/${encodeURIComponent(id)}`),
         participantGraph(),
       ]);
+      if (!isRecord(entity, id)) throw notFound(id);
       return toSourceDocument(entity, scope, sourceLabels, byRecord.get(String(entity.id)) ?? []);
     },
 
@@ -581,3 +695,311 @@ export function createCorpusApi(
     },
   };
 }
+
+/**
+ * `data` key -> the `FocusDraft` key that carries it.
+ *
+ * THE POINT IS PARTIAL UPDATES. `focusToEntity` is a CREATE mapper: it always
+ * emits a `status` (defaulting to `active`) and always stamps `_origin`, because
+ * a new row needs both. Merging that whole object on every edit would mean
+ * renaming a focus silently resurrected a `cancelled` one — the upsert
+ * shallow-merges, so every key present in the body is a write.
+ *
+ * So an update sends a key only when the DRAFT field behind it was actually in
+ * the patch. The two names differ (`time_frame` vs `timeFrame`), which is the
+ * whole reason this is a map rather than a list, and `_origin` is deliberately
+ * absent from it so an edit can never relabel where a row came from.
+ */
+const FOCUS_PATCH_KEYS: Record<string, keyof FocusDraft> = {
+  detail: 'detail',
+  status: 'status',
+  category: 'category',
+  time_frame: 'timeFrame',
+  year: 'year',
+  start_date: 'startDate',
+  end_date: 'endDate',
+  target_value: 'targetValue',
+  current_value: 'currentValue',
+  unit: 'unit',
+  owner_sub: 'ownerSub',
+  owner_name: 'ownerName',
+};
+
+// ---------------------------------------------------------------------------
+//  the planning surface (bd startsim-8l6ef)
+// ---------------------------------------------------------------------------
+
+/**
+ * The tenant client for focuses and items.
+ *
+ * COMPOSED FROM `createCorpusApi`, not written beside it: an item IS a
+ * commitment, so `listCommitments` and — more importantly — its applied-filter
+ * reconciliation are reused wholesale rather than reimplemented against the same
+ * endpoint. What is added here is the focus type, the two edge writes, the
+ * authoring path and counting.
+ *
+ * EVERY WRITE IS THE SHALLOW-MERGING UPSERT, keyed on `external_id`. That is the
+ * only tenant verb that preserves keys the caller did not send, which matters
+ * more here than anywhere else in the package: the extractor and a person write
+ * the SAME rows, and a full-object PUT from an edit dialog would silently drop
+ * whatever the last extraction pass had just added.
+ *
+ * NOTHING AGGREGATES SERVER-SIDE, because the tenant plane deliberately offers
+ * no group_by. `focusStanding` asks for `page_size=1` three times and reads the
+ * paginator's own `count`, so a focus card costs three empty pages rather than
+ * three pages of bodies.
+ */
+export function createPlanningApi(options: CreateCorpusApiOptions): PlanningApi {
+  const base = createCorpusApi(options);
+  const { http, scope } = options;
+  const sourceLabels = options.sourceLabels ?? {};
+  const types: CorpusTypeKeys = { ...DEFAULT_TYPE_KEYS, ...options.typeKeys };
+  const entities = options.paths?.entities ?? 'api/v1/entities';
+  const relationships = options.paths?.relationships ?? 'api/v1/relationships';
+  // tenant-starter/config/urls.py: path("api/v1/org/members/", OrgMembersView…)
+  const membersPath = options.paths?.members ?? 'api/v1/org/members';
+
+  function writer(): NonNullable<CorpusHttp['post']> {
+    if (!http.post) {
+      throw new Error('This planning client is read-only — no write method was supplied.');
+    }
+    return http.post.bind(http);
+  }
+
+  function focusParams(query: FocusQuery): Record<string, unknown> {
+    const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
+    const out: Record<string, unknown> = {
+      type: FOCUS_TYPE,
+      page: query.page ?? 1,
+      ...(query.pageSize ? { page_size: Math.min(query.pageSize, 200) } : {}),
+      // Worst-off first by default. A STORED `progress` is what makes this a
+      // server order at all — see the field's note for why nothing recomputes
+      // it on the way past.
+      order: ({
+        progress: 'attr.progress',
+        '-progress': '-attr.progress',
+        sortOrder: 'attr.sort_order',
+        title: 'attr.title',
+      } as const)[query.orderBy ?? 'progress'],
+    };
+    if (statuses.length === 1) out['attr.status'] = statuses[0];
+    else if (statuses.length > 1) out['attr.status__in'] = statuses.join(',');
+    if (query.category) out['attr.category'] = query.category;
+    if (query.timeFrame) out['attr.time_frame'] = query.timeFrame;
+    if (query.year !== undefined) out['attr.year'] = query.year;
+    if (query.owner) out['attr.owner_sub'] = query.owner;
+    if (query.search) out.search = query.search.slice(0, TEXT_FILTER_MAX);
+    return out;
+  }
+
+  async function focusPage(params: Record<string, unknown>): Promise<CorpusPage<Focus>> {
+    const response = await http.get<DrfPage<TenantEntity> & ServerFilterReport>(
+      entities, { params });
+    return {
+      count: response.count ?? response.results?.length ?? 0,
+      next: response.next ?? null,
+      previous: response.previous ?? null,
+      results: (response.results ?? []).map((entity) => toFocus(entity, scope)),
+      appliedFilters: response.applied_filters ?? response.appliedFilters ?? [],
+    };
+  }
+
+  /** A count with no rows: ask for one, read `count`, throw the row away. */
+  async function countOnly(params: Record<string, unknown>): Promise<number> {
+    const response = await http.get<DrfPage<TenantEntity>>(entities, {
+      params: { ...params, page_size: 1 },
+    });
+    return response.count ?? response.results?.length ?? 0;
+  }
+
+  /** The `in_focus` scope for one focus, as query params. */
+  function inFocus(focusId: string): Record<string, unknown> {
+    return {
+      type: types.commitment,
+      related_to: focusId,
+      related_via: IN_FOCUS,
+      // The direction names the RETURNED ROW's end of the edge, and an item is
+      // the SOURCE of its own `in_focus` edge. `in` here returns an empty page
+      // rather than an error, which is why it is spelled out.
+      related_direction: 'out',
+    };
+  }
+
+  return {
+    ...base,
+
+    listFocuses: (query: FocusQuery = {}) => focusPage(focusParams(query)),
+
+    /**
+     * The children of a focus, one level.
+     *
+     * A level at a time because the query layer caps a traversal at
+     * `related_depth=2`; a deep tree is several cheap reads rather than one
+     * request that cannot be expressed.
+     */
+    listChildFocuses: (focusId: string) => focusPage({
+      type: FOCUS_TYPE,
+      related_to: focusId,
+      related_via: SUB_FOCUS,
+      related_direction: 'out',
+      order: 'attr.sort_order',
+    }),
+
+    async createFocus(draft: FocusDraft): Promise<Focus> {
+      const post = writer();
+      const created = await post<TenantEntity>(`${entities}/upsert`, focusToEntity(draft));
+      const focus = toFocus(created, scope);
+      // Nesting is an EDGE, so it is a second write with no transaction around
+      // it. Done after the row exists rather than smuggled into its payload: a
+      // failure here leaves a real, visible, unparented focus instead of half a
+      // record and no way to tell which half.
+      if (draft.parentId) {
+        await post(relationships, {
+          rel_type: SUB_FOCUS, source: focus.id, target: draft.parentId,
+        });
+        return { ...focus, parentId: draft.parentId };
+      }
+      return focus;
+    },
+
+    async updateFocus(focus: Focus, patch: Partial<FocusDraft>): Promise<Focus> {
+      const post = writer();
+      // Only the keys the caller actually sent. `focusToEntity` would helpfully
+      // default `status` to 'active', and merging that in would resurrect a
+      // cancelled focus every time somebody edited its title.
+      const { data } = focusToEntity({ ...patch, title: patch.title ?? focus.title });
+      const sent: Record<string, unknown> = { title: patch.title ?? focus.title };
+      for (const [key, value] of Object.entries(data)) {
+        if (key === 'title') continue;
+        if (key in FOCUS_PATCH_KEYS && FOCUS_PATCH_KEYS[key] in patch) sent[key] = value;
+      }
+      const updated = await post<TenantEntity>(`${entities}/upsert`, {
+        entity_type: FOCUS_TYPE,
+        external_id: focus.externalId,
+        ...(patch.title ? { name: patch.title.slice(0, 200) } : {}),
+        data: sent,
+      });
+      return toFocus(updated, scope);
+    },
+
+    async createCommitment(draft: AuthoredItem): Promise<Commitment> {
+      const post = writer();
+      const created = await post<TenantEntity>(
+        `${entities}/upsert`,
+        authoredItemToEntity(draft, { itemType: types.commitment }),
+      );
+      const item = toCommitment(created, scope, sourceLabels);
+      if (draft.focusId) {
+        await post(relationships, {
+          rel_type: IN_FOCUS, source: item.id, target: draft.focusId,
+        });
+        return { ...item, focusId: draft.focusId };
+      }
+      return item;
+    },
+
+    /**
+     * A person's edit, merged over whatever the extractor last wrote.
+     *
+     * Sends ONLY the keys in `patch`. The upsert shallow-merges, so an edit to
+     * an owner cannot drop a due date the last extraction pass added — and
+     * `last_seen_at` is deliberately NOT touched, because a person editing a row
+     * is not a meeting mentioning it, and pretending otherwise would move the
+     * item into "changed this week" for the wrong reason.
+     */
+    async updateCommitment(
+      item: Commitment,
+      patch: Parameters<NonNullable<CommitmentApi['updateCommitment']>>[1],
+    ): Promise<Commitment> {
+      const post = writer();
+      const wire: Record<string, unknown> = {};
+      if (patch.title !== undefined) wire.title = patch.title;
+      if (patch.detail !== undefined) wire.detail = patch.detail;
+      if (patch.status !== undefined) wire.status = patch.status;
+      if (patch.statusReason !== undefined) wire.status_reason = patch.statusReason;
+      if (patch.ownerName !== undefined) wire.owner_name = patch.ownerName;
+      if (patch.ownerSub !== undefined) wire.owner_sub = patch.ownerSub;
+      if (patch.dueAt !== undefined) wire.due_at = patch.dueAt;
+      if (patch.subtype !== undefined) wire.subtype = patch.subtype;
+      if (patch.priority !== undefined) wire.priority = patch.priority;
+      const updated = await post<TenantEntity>(`${entities}/upsert`, {
+        entity_type: types.commitment,
+        external_id: item.externalId,
+        ...(patch.title !== undefined ? { name: patch.title.slice(0, 200) } : {}),
+        data: wire,
+      });
+      return toCommitment(updated, scope, sourceLabels);
+    },
+
+    async fileCommitment(item: Commitment, focusId: string | null): Promise<void> {
+      const post = writer();
+      if (focusId !== null) {
+        await post(relationships, { rel_type: IN_FOCUS, source: item.id, target: focusId });
+        return;
+      }
+      if (!http.delete) {
+        // Said out loud rather than resolving. A control that appears to unfile
+        // and does not is worse than one that is disabled.
+        throw new Error('This planning client cannot unfile — no delete method was supplied.');
+      }
+      const del = http.delete.bind(http);
+      const page = await http.get<DrfPage<TenantRelationship>>(relationships, {
+        params: { rel_type: IN_FOCUS, source: item.id },
+      });
+      for (const edge of page.results ?? []) {
+        await del(`${relationships}/${edge.id}`);
+      }
+    },
+
+    /**
+     * "12 of 40 done, 3 overdue" for one focus — three counts, no row bodies.
+     *
+     * `now` is a PARAMETER and not a `Date.now()` read inside, for the reason
+     * `TrackerPageProps.now` records: a clock read on the way past is a new
+     * value every call, which makes it a new memo dependency, which is how a
+     * screen ends up issuing 917 requests in ten minutes on a live tenant.
+     */
+    async focusStanding(focusId: string, now?: number): Promise<FocusStanding> {
+      const scopeParams = inFocus(focusId);
+      const asOf = new Date(now ?? Date.now()).toISOString();
+      const [total, done, overdue] = await Promise.all([
+        countOnly(scopeParams),
+        countOnly({ ...scopeParams, 'attr.status': 'done' }),
+        countOnly({ ...scopeParams, 'attr.status': 'open', 'attr.due_at__lte': asOf }),
+      ]);
+      return { focusId, total, done, overdue };
+    },
+
+    /**
+     * The tenant's real members, for the owner picker — what closes the
+     * free-text-owner gap (bd startsim-768w.38.29).
+     *
+     * Read through the fork's OWN same-origin roster, never central directly:
+     * pointing a browser at api.startsimpli.com with a bearer from a foreign
+     * apex is the cross-origin/refresh-cookie trap the proxy convention exists
+     * to avoid.
+     *
+     * FAILS SOFT TO AN EMPTY ROSTER. A fork with no central wiring has no
+     * members to offer, and the picker degrades to the free-text owner name
+     * rather than the screen erroring — which is exactly why `ownerName` survives
+     * alongside `ownerSub` instead of being replaced by it.
+     */
+    async listMembers(): Promise<Array<{ sub: string; email: string; name?: string }>> {
+      try {
+        const page = await http.get<DrfPage<Record<string, unknown>>>(membersPath, {});
+        return (page.results ?? [])
+          .map((row) => {
+            const user = (row.user ?? {}) as Record<string, unknown>;
+            return {
+              sub: String(user.sub ?? row.sub ?? ''),
+              email: String(user.email ?? row.email ?? ''),
+              ...(user.name ? { name: String(user.name) } : {}),
+            };
+          })
+          .filter((member) => member.sub);
+      } catch {
+        return [];
+      }
+    },
+  };
+}

package/src/corpus/entities.ts

@@ -189,6 +189,25 @@ function asIso(value: unknown): string | null {
   return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
 }
 
+/**
+ * A finite number, or `undefined`.
+ *
+ * `undefined` RATHER THAN 0, and that distinction is the whole reason this is
+ * not a one-liner: an unset `target_value` means "this focus is qualitative"
+ * (`Goal.is_measurable`) and an unset `priority` means "nobody has triaged this
+ * yet". Coercing either to 0 turns a missing judgement into a confident one —
+ * every qualitative focus becomes fully achieved, and every untriaged item
+ * becomes critical.
+ */
+function asNumber(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 asList(value: unknown): unknown[] {
   if (Array.isArray(value)) return value;
   if (value === undefined || value === null || value === '') return [];
@@ -593,6 +612,33 @@ export function moneyEventAsDocument(event: MoneyEvent): SourceDocument {
  *  interesting; the thirty-first quote is not, and the row has to stay small. */
 const MAX_MENTIONS = 20;
 
+/**
+ * WHERE A ROW CAME FROM, under the key the platform already uses.
+ *
+ * THE LEADING UNDERSCORE IS LOAD-BEARING. `_origin` is written as a flat `data`
+ * key by three writers — the central corpus delivery, the foundry-tenant
+ * destination handler and the extractor below — and the tenant declares an
+ * `AttributeDef` of exactly that name, so it is the only spelling with an index
+ * behind it. A field called `origin` would snake_case to `origin`, a DIFFERENT
+ * key that nothing has ever written and nothing indexes: every filter over it
+ * would return an empty page, with no error to explain why.
+ *
+ * READS ARRIVE UNDER `Origin`. `@startsimpli/api`'s `transformKeys` camelCases
+ * response keys recursively into `data`, and `snakeToCamelKey('_origin')` is
+ * `Origin` — while a plain server-side `fetch` sees `_origin` untouched. So the
+ * write side emits the literal key and the read side accepts both, the same
+ * tolerance `toCommitment` already applies to `status_reason`/`statusReason`.
+ */
+export const ORIGIN_KEY = '_origin';
+export const ORIGIN = {
+  /** Read out of a meeting by the tenant-side extractor. */
+  extracted: 'tenant-extraction',
+  /** Typed by a person on the planning surface. */
+  authored: 'human',
+  /** Delivered by the central corpus pipeline. */
+  central: 'central-pipeline',
+} as const;
+
 export function toCommitment(
   entity: TenantEntity,
   fallbackScope: CorpusScope,
@@ -624,6 +670,15 @@ export function toCommitment(
     subjectKey: asText(pick(data, 'subject_key', 'subjectKey')),
     actionKey: asText(pick(data, 'action_key', 'actionKey')),
     dueAt: asIso(pick(data, 'due_at', 'dueAt')),
+    ...(asNumber(pick(data, 'priority')) !== undefined
+      ? { priority: asNumber(pick(data, 'priority')) } : {}),
+    ...(pick(data, 'owner_sub', 'ownerSub')
+      ? { ownerSub: asText(pick(data, 'owner_sub', 'ownerSub')) } : {}),
+    // Both spellings, for the reason spelled out on ORIGIN_KEY above: the
+    // browser client camelCases `_origin` into `Origin` on the way in, and a
+    // server-side fetch does not.
+    ...(pick(data, ORIGIN_KEY, 'Origin')
+      ? { origin: asText(pick(data, ORIGIN_KEY, 'Origin')) } : {}),
     mentions,
     firstSeenAt: asIso(pick(data, 'first_seen_at', 'firstSeenAt')),
     lastSeenAt: asIso(pick(data, 'last_seen_at', 'lastSeenAt')),
@@ -675,6 +730,8 @@ export function commitmentToEntity(commitment: Commitment): {
       action_key: commitment.actionKey,
       dedupe_key: commitment.dedupeKey,
       ...(commitment.dueAt ? { due_at: commitment.dueAt } : {}),
+      ...(commitment.priority !== undefined ? { priority: commitment.priority } : {}),
+      ...(commitment.ownerSub ? { owner_sub: commitment.ownerSub } : {}),
       first_seen_at: commitment.firstSeenAt,
       last_seen_at: commitment.lastSeenAt,
       mention_count: commitment.mentions.length,
@@ -690,7 +747,12 @@ export function commitmentToEntity(commitment: Commitment): {
       // Marks the row as pipeline-written, the same way the corpus delivery
       // marks its own — so a human-created item is distinguishable from a
       // derived one, and a re-derivation knows what it is allowed to rewrite.
-      _origin: 'tenant-extraction',
+      //
+      // PRESERVED WHEN THE ROW ALREADY HAS ONE. A human-authored item that
+      // passes back through the extractor's bulk upsert must not be relabelled
+      // as extracted — that would quietly claim a meeting said something nobody
+      // said, and the row has no mention to contradict it.
+      [ORIGIN_KEY]: commitment.origin || ORIGIN.extracted,
     },
   };
 }

package/src/corpus/index.ts

@@ -9,6 +9,7 @@ export type {
   AnswerDraft,
   AnswerRequest,
   AskMode,
+  AuthoredItem,
   Commitment,
   CommitmentApi,
   CommitmentDraft,
@@ -39,10 +40,18 @@ export type {
   CorpusScope,
   DocumentQuery,
   DocumentSection,
+  Focus,
+  FocusCategory,
+  FocusDraft,
+  FocusQuery,
+  FocusStanding,
+  FocusStatus,
+  FocusTimeFrame,
   LlmDescription,
   MoneyEvent,
   Party,
   PartyRef,
+  PlanningApi,
   PromptDocument,
   RetrievedDocument,
   SourceDocument,
@@ -136,10 +145,26 @@ export type {
   ResolutionResult,
 } from './commitments';
 
+// Focuses and authored items — the planning toolset (bd startsim-8l6ef).
+export {
+  FOCUS_TYPE,
+  IN_FOCUS,
+  SUB_FOCUS,
+  authoredId,
+  authoredItemToEntity,
+  displayProgress,
+  focusProgress,
+  focusSlug,
+  focusToEntity,
+  isAuthored,
+  toFocus,
+} from './planning';
+export { ORIGIN, ORIGIN_KEY } from './entities';
+
 export { jaccard, outcomeSections, splitSections, stem, words } from './text';
 export type { TextSection } from './text';
 
-export { createCorpusApi } from './client';
+export { createCorpusApi, createPlanningApi } from './client';
 export type { CorpusHttp, CreateCorpusApiOptions } from './client';
 
 export {