@startsimpli/integrations 0.1.5 → 0.2.1

package/src/corpus/types.ts

@@ -334,6 +334,262 @@ export interface CorpusLlm {
   describe(): LlmDescription;
 }
 
+// ---------------------------------------------------------------------------
+//  Commitments — the one-way funnel (bd startsim-768w.38.25)
+// ---------------------------------------------------------------------------
+//
+// THE PRODUCT IS THIS, and Ask is a secondary affordance over it. A meeting is
+// conversation; what a person needs out of it is a list of things that are now
+// owed, by whom, by when, and whether they are still owed. Once the material is
+// structured, tracking is trivial — so all of the difficulty is deliberately
+// concentrated on the extraction and the identity, and none of it on the list.
+//
+// ONE GENERIC TYPE, DISCRIMINATED BY SUBTYPE (feedback_brutally_generic, and the
+// same rule that gave `source_document` a `subtype` instead of a `GranolaNote`
+// model). There is no Task model, no Decision model and no Risk model. A tenant
+// that wants a fourth kind adds a subtype string; nothing in this package, in
+// the storage, or on the screen changes.
+
+/**
+ * `action`   — somebody owes somebody else a thing. The default and the bulk.
+ * `decision` — a thing was settled. Not owed, but the reason a later action
+ *              exists, and the record people actually go looking for.
+ * `need`     — a stated requirement with no owner yet. Distinct from `action`
+ *              precisely because it has nobody on it; collapsing the two hides
+ *              the most useful column on the screen.
+ * `risk`     — something that will cost if ignored.
+ * `question` — an open question addressed to someone.
+ *
+ * A string, not a union, for the same reason `SourceKey` is: a sixth kind must
+ * not require an app change.
+ */
+export type CommitmentSubtype = string;
+
+/**
+ * `open`    — still owed.
+ * `done`    — satisfied. Set by a human, or by RESOLUTION DETECTION against a
+ *             later meeting, and in the second case `statusReason` carries the
+ *             sentence that closed it and `resolvedBy` the record it came from.
+ * `blocked` — owed, but waiting on something named in `statusReason`.
+ * `dropped` — explicitly abandoned. Not the same as done and must not read as it.
+ */
+export type CommitmentStatus = 'open' | 'done' | 'blocked' | 'dropped';
+
+/**
+ * One time a commitment was talked about.
+ *
+ * MENTIONS ARE THE UNIT OF IDEMPOTENCY. A commitment is identified across
+ * meetings by what it is ABOUT (see `dedupeKey`), and each meeting that
+ * discusses it contributes one mention keyed by `originKey`. Re-extracting a
+ * document REPLACES that document's mentions rather than appending, which is
+ * what makes a second run over the same corpus a no-op instead of a doubling.
+ */
+export interface CommitmentMention {
+  /** The `source_document` this mention came from. */
+  documentId: string;
+  /** Stable within a document: the vendor's own bullet, or the model's item. */
+  originKey: string;
+  /** When the meeting happened — NOT when the row was written. */
+  occurredAt: string | null;
+  /** Verbatim span from that document, so the claim can be checked. */
+  quote: string;
+  /** `rules` when the vendor's own structure produced it, `model` otherwise. */
+  extractor: 'rules' | 'model';
+}
+
+/** A trackable thing that came out of a conversation. */
+export interface Commitment {
+  id: string;
+  /** `commit:<dedupeKey>` — the row's stable external identity in the tenant. */
+  externalId: string;
+  /** Identity across meetings: what it is about, plus what is being done. */
+  dedupeKey: string;
+  subtype: CommitmentSubtype;
+  /** One line, imperative. What the screen shows. */
+  title: string;
+  /** The fuller statement, when the source had one. */
+  detail: string;
+  status: CommitmentStatus;
+  /** Why it is not `open`, in the words of the record that changed it. */
+  statusReason?: string;
+  /** Which record closed or blocked it. */
+  resolvedBy?: string;
+  resolvedAt?: string | null;
+  /**
+   * Who owes it, as NAMED IN THE MEETING. A string and not a `PartyRef`,
+   * because on a real tenant almost nobody in a transcript is a Party row yet —
+   * the live tandem workspace has one Party for sixteen documents. Dropping
+   * "Megan" because Megan is not in the graph would delete the most useful
+   * column on the screen to satisfy a model that has not been populated.
+   */
+  ownerName?: string;
+  /** Resolved to a real record when one exists. Additive, never a replacement. */
+  owner?: PartyRef;
+  /** What it is about — a matter number, a property, a vendor, a person. */
+  subject?: string;
+  /** Normalised `subject`. Half of `dedupeKey`, and the dedupe's precision. */
+  subjectKey: string;
+  /** Normalised action stems. The other half. */
+  actionKey: string;
+  /** When it is due, only when the source actually said so. Never invented. */
+  dueAt?: string | null;
+  mentions: CommitmentMention[];
+  firstSeenAt: string | null;
+  lastSeenAt: string | null;
+  /** Which extractor produced it, so a later one can re-derive without orphaning. */
+  extractorVersion: string;
+  source: SourceKey;
+  sourceLabel: string;
+  scope: CorpusScope;
+}
+
+/** What the extractor proposes, before identity and merging are applied. */
+export interface CommitmentDraft {
+  documentId: string;
+  originKey: string;
+  subtype: CommitmentSubtype;
+  title: string;
+  detail: string;
+  status: CommitmentStatus;
+  ownerName?: string;
+  subject?: string;
+  dueAt?: string | null;
+  quote: string;
+  extractor: 'rules' | 'model';
+}
+
+/**
+ * A statement in a LATER meeting that something previously outstanding is now
+ * settled. Extracted separately from commitments because closing an item is a
+ * different claim from creating one and must clear a higher bar — a wrong close
+ * makes the list lie in the direction of "you have nothing to do".
+ */
+export interface ResolutionClaim {
+  documentId: string;
+  /** What it is about, matched against `Commitment.subjectKey`. */
+  subject?: string;
+  /** What happened, matched against `Commitment.actionKey`. */
+  statement: string;
+  quote: string;
+  /** `done` or `dropped` — a thing can stop being owed without being satisfied. */
+  outcome: 'done' | 'dropped';
+}
+
+/** Server-side filters for the tracking surface (CLAUDE.md rule 8). */
+export interface CommitmentQuery {
+  status?: CommitmentStatus | CommitmentStatus[];
+  subtype?: CommitmentSubtype;
+  owner?: string;
+  /** ISO instants over `dueAt`. */
+  dueBefore?: string;
+  /** ISO instant over `lastSeenAt` — "what changed since last week". */
+  changedAfter?: string;
+  search?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+/**
+ * The tracking surface's contract. Separate from `CorpusApi` because a
+ * deployment can have a corpus without an extractor — the Library and Ask work
+ * with no commitment rows at all, and a composer that required them would make
+ * the corpus surfaces depend on a pipeline that may not have run.
+ */
+export interface CommitmentApi {
+  listCommitments(query?: CommitmentQuery): Promise<CorpusPage<Commitment>>;
+  /**
+   * Persist the result of a run. ONE call carrying every row, keyed by
+   * `externalId`, so the tenant's own upsert provides the idempotency rather
+   * 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>;
+}
+
+/**
+ * The extraction seam. ONE method taking N documents, so the batching rule is
+ * structural rather than something a caller has to remember — exactly like
+ * `CorpusLlm.answer`.
+ */
+export interface CorpusExtractorLlm {
+  extract(input: ExtractionRequest): Promise<ExtractionDraft>;
+  describe(): LlmDescription;
+}
+
+export interface ExtractionRequest {
+  documents: Array<{
+    id: string;
+    title: string;
+    source: string;
+    occurredAt: string | null;
+    participants: string[];
+    text: string;
+    /**
+     * What the deterministic pre-pass already found in this document. Sent so
+     * the model ADDS to it rather than restating it — the vendor's own action
+     * list is not a thing worth paying a model to rediscover.
+     */
+    alreadyFound: string[];
+  }>;
+}
+
+export interface ExtractionDraft {
+  items: Array<{
+    documentId: string;
+    subtype?: string;
+    title: string;
+    detail?: string;
+    status?: string;
+    owner?: string;
+    subject?: string;
+    dueAt?: string | null;
+    quote?: string;
+  }>;
+  resolutions?: Array<{
+    documentId: string;
+    subject?: string;
+    statement: string;
+    quote?: string;
+    outcome?: string;
+  }>;
+}
+
+/**
+ * What `TrackerPage` is injected with. An app points it at its own route
+ * handler; the handler runs the extraction server-side, where the key lives.
+ */
+export interface CommitmentTrackerApi extends CommitmentApi {
+  /**
+   * Run extraction over documents that have not been processed. Optional: a
+   * read-only deployment omits it and the control does not render.
+   */
+  extract?(input: { scope: CorpusScope; documentIds?: string[] }): Promise<ExtractionResult>;
+}
+
+export interface ExtractionResult {
+  /** Documents read and sent to the extractor. */
+  documentsProcessed: number;
+  /** Items the vendor's own structure produced, with no model involved. */
+  fromRules: number;
+  /** Items only the model found. */
+  fromModel: number;
+  created: number;
+  /** Existing items a new mention was attached to — the dedupe, counted. */
+  merged: number;
+  /** Items a later meeting closed. */
+  resolved: number;
+  /**
+   * Resolution claims that matched an open item too weakly to act on. Surfaced
+   * for review rather than applied: closing the wrong item makes the list lie in
+   * the one direction a to-do list must never lie.
+   */
+  needsReview: Array<{ commitmentId: string; documentId: string; quote: string }>;
+  droppedOutOfScope: number;
+  provider: LlmDescription;
+}
+
 /**
  * What `AskPage` is injected with. An app points it at its own route handler;
  * the handler calls `askCorpus` server-side, where the API key lives.