@startsimpli/integrations 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/corpus-extract.test.ts

@@ -198,6 +198,60 @@ describe('idempotence: running it twice changes nothing', () => {
     );
   });
 
+  it('survives the MODEL rewording its own output between runs', () => {
+    // THE PRODUCTION BUG, pinned. On the live tandem tenant a second extraction
+    // over the same four documents created SIXTEEN duplicate rows: the model
+    // reworded its own `subject` ("ketamine regimen" -> "ketamine treatment")
+    // while emitting a byte-identical title, and a disagreeing subject was
+    // vetoing the match. Prose subjects are now weak evidence, not a veto.
+    const first = reconcile([], mergeDrafts([
+      { ...draft('m1', 'Find a sustainable ketamine regimen', '2026-08-01'), subject: 'ketamine regimen', extractor: 'model' as const },
+    ]), { scope: TANDEM, documents: [documentFor('m1', '2026-08-01')] });
+
+    const second = reconcile(first.commitments, mergeDrafts([
+      { ...draft('m1', 'Find a sustainable ketamine regimen', '2026-08-01'), subject: "Quinn's ketamine treatment", extractor: 'model' as const },
+    ]), { scope: TANDEM, documents: [documentFor('m1', '2026-08-01')] });
+
+    expect(second.created).toBe(0);
+    expect(second.commitments).toHaveLength(1);
+  });
+
+  it('still refuses to merge two MATTER NUMBERS that disagree, however alike the words', () => {
+    // The other side of the same rule. An identifier is authoritative: "chase
+    // for comments on 2148" and "...on 2198" have identical action stems and are
+    // two different obligations. Merging them deletes work.
+    const { commitments } = reconcile([], mergeDrafts([
+      draft('m1', 'Chase for comments on 2148', '2026-08-01'),
+      draft('m1', 'Chase for comments on 2198', '2026-08-01'),
+    ]), { scope: TANDEM, documents: [documentFor('m1', '2026-08-01')] });
+    expect(commitments).toHaveLength(2);
+  });
+
+  it('tells the model what is ALREADY TRACKED for a document, not just what the rules found', async () => {
+    // The structural half of idempotency: the fuzzy matcher is a safety net, and
+    // not asking the model to invent the same item twice is the actual fix.
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, documents: FIXTURE_TRACKED_DOCUMENTS });
+    const tracked: Commitment[] = [];
+    (corpus as { listCommitments?: unknown }).listCommitments = async () => ({
+      count: tracked.length, next: null, previous: null, results: tracked,
+    });
+    (corpus as { saveCommitments?: unknown }).saveCommitments = async (items: Commitment[]) => {
+      tracked.splice(0, tracked.length, ...items);
+    };
+
+    const extractor = createFixtureExtractor();
+    const spy = vi.spyOn(extractor, 'extract');
+
+    await extractCommitments({ scope: TANDEM }, { corpus, extractor });
+    const firstAsk = spy.mock.calls[0][0].documents.flatMap((d) => d.alreadyFound).length;
+
+    await extractCommitments({ scope: TANDEM }, { corpus, extractor });
+    const secondAsk = spy.mock.calls[1][0].documents.flatMap((d) => d.alreadyFound).length;
+
+    expect(tracked.length).toBeGreaterThan(0);
+    expect(secondAsk).toBeGreaterThan(firstAsk);
+  });
+
   it('keeps a human’s edit when the extractor runs again over the same source', () => {
     const drafts = rulesExtract(FIXTURE_TRACKED_DOCUMENTS[0]);
     const first = reconcile([], mergeDrafts(drafts), { scope: TANDEM, documents: FIXTURE_TRACKED_DOCUMENTS });

package/src/corpus/commitments.ts

@@ -61,6 +61,23 @@ export const EXTRACTOR_VERSION = 'rules+model@1';
  */
 const MERGE_THRESHOLD = 0.5;
 
+/**
+ * The bar when the two statements do NOT agree on a subject — either because
+ * one of them has none, or because they disagree.
+ *
+ * A DISAGREEING SUBJECT MUST NOT VETO A MATCH, and that was a real production
+ * bug: on the live tandem tenant a second extraction run over the same four
+ * documents created sixteen duplicate rows, because the model had rephrased its
+ * own `subject` between runs ("ketamine regimen" vs "ketamine treatment") and
+ * the veto threw away pairs whose TITLES were byte-identical. Measured across
+ * the resulting 98 rows: five same-document duplicate pairs sat at 0.5 or above
+ * on title overlap, and ZERO cross-document pairs reached even 0.5 — so an
+ * unanchored bar of 0.7 catches the rewording with no measured false merge.
+ *
+ * An agreeing subject still buys the lower bar, because it is real evidence.
+ */
+const UNANCHORED_MERGE_THRESHOLD = 0.7;
+
 /**
  * The bar a resolution has to clear before it CLOSES something, which is higher
  * than the bar for merging because the failure is worse. A wrong merge shows one
@@ -100,6 +117,19 @@ const MATTER_BARE = /\b(?!(?:19|20)\d{2}\b)\d{4}\b/;
 
 export interface CommitmentIdentity {
   subjectKey: string;
+  /**
+   * True when the subject is an IDENTIFIER (a matter number) rather than prose.
+   *
+   * The distinction is load-bearing. Two identifiers that disagree are two
+   * different things and no amount of shared wording changes that — "chase for
+   * comments on 2148" and "chase for comments on 2198" are two obligations whose
+   * action stems are identical. Two PROSE subjects that disagree mean much less:
+   * measured on the live tenant, the model described one commitment as being
+   * about "ketamine regimen" on one run and "ketamine treatment" on the next,
+   * while emitting a byte-identical title. So an identifier vetoes; prose does
+   * not, it only raises the bar.
+   */
+  subjectIsIdentifier: boolean;
   actionKey: string;
   actionTokens: string[];
   dedupeKey: string;
@@ -128,20 +158,43 @@ export function commitmentIdentity(input: {
   const subjectTokens = matter ? [matter] : unique(tokenize(subject));
   const subjectKey = matter ? matter : subjectTokens.slice().sort().join('.');
 
-  const drop = new Set(subjectTokens);
+  // ONLY AN IDENTIFIER IS REMOVED FROM THE ACTION. Removing prose subject words
+  // too would couple the two halves of the key: when the model reworded a
+  // subject from "ketamine regimen" to "Quinn's ketamine treatment", a
+  // byte-identical title produced two different action sets and the row
+  // duplicated. The matter number is noise in the action ("chase 2148" is a
+  // chase); the prose words are part of what the title says.
+  const drop = new Set(matter ? [matter] : []);
   const actionTokens = unique(
     tokenize(title).filter((token) => !drop.has(token) && !ACTION_NOISE.has(token)),
   );
   const actionKey = actionTokens.slice().sort().join('.');
 
-  return { subjectKey, actionKey, actionTokens, dedupeKey: hash(`${subjectKey}|${actionKey}`) };
+  return {
+    subjectKey,
+    subjectIsIdentifier: Boolean(matter),
+    actionKey,
+    actionTokens,
+    dedupeKey: hash(`${subjectKey}|${actionKey}`),
+  };
 }
 
 /** Do two identities describe one commitment? Tier 1, then Tier 2. */
 export function isSameCommitment(a: CommitmentIdentity, b: CommitmentIdentity): boolean {
   if (a.dedupeKey === b.dedupeKey) return true;
-  if (!a.subjectKey || a.subjectKey !== b.subjectKey) return false;
-  return jaccard(a.actionTokens, b.actionTokens) >= MERGE_THRESHOLD;
+  if (subjectsConflict(a, b)) return false;
+  const anchored = Boolean(a.subjectKey) && a.subjectKey === b.subjectKey;
+  const bar = anchored ? MERGE_THRESHOLD : UNANCHORED_MERGE_THRESHOLD;
+  return jaccard(a.actionTokens, b.actionTokens) >= bar;
+}
+
+/** Two IDENTIFIERS that disagree. The one veto worth having. */
+function subjectsConflict(a: CommitmentIdentity, b: CommitmentIdentity): boolean {
+  return (
+    a.subjectIsIdentifier &&
+    b.subjectIsIdentifier &&
+    a.subjectKey !== b.subjectKey
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -295,6 +348,7 @@ function toMention(draft: CommitmentDraft, document: SourceDocument): Commitment
 function identityOf(commitment: Commitment): CommitmentIdentity {
   return {
     subjectKey: commitment.subjectKey,
+    subjectIsIdentifier: MATTER_HYPHENATED.test(commitment.subjectKey) || MATTER_BARE.test(commitment.subjectKey),
     actionKey: commitment.actionKey,
     actionTokens: commitment.actionKey ? commitment.actionKey.split('.') : [],
     dedupeKey: commitment.dedupeKey,
@@ -347,13 +401,15 @@ export function applyResolutions(
     for (const commitment of out) {
       if (commitment.status !== 'open' && commitment.status !== 'blocked') continue;
       if (at && commitment.firstSeenAt && commitment.firstSeenAt > at) continue;
+      const other = identityOf(commitment);
+      // Two IDENTIFIERS that disagree are different things, and no amount of
+      // shared wording makes them the same one. Disagreeing prose is only weak
+      // evidence and raises the bar instead of vetoing — see `subjectsConflict`.
+      if (subjectsConflict(identity, other)) continue;
       const anchored = Boolean(identity.subjectKey) && identity.subjectKey === commitment.subjectKey;
-      // Two subjects that both exist and disagree are different things, and no
-      // amount of shared wording makes them the same one.
-      if (identity.subjectKey && commitment.subjectKey && !anchored) continue;
       const candidate = {
         commitment,
-        score: jaccard(identity.actionTokens, identityOf(commitment).actionTokens),
+        score: jaccard(identity.actionTokens, other.actionTokens),
         bar: anchored ? RESOLVE_THRESHOLD : UNANCHORED_RESOLVE_THRESHOLD,
       };
       if (!best || candidate.score > best.score) best = candidate;

package/src/corpus/extract.ts

@@ -289,11 +289,35 @@ export async function extractCommitments(
     };
   }
 
+  const allowedIds = new Set(documents.map((document) => document.id));
+
   // 3. rules first, so the model can be told what not to repeat.
   const ruleDrafts = documents.flatMap(rulesExtract);
   const foundByDocument = new Map<string, string[]>();
-  for (const draft of ruleDrafts) {
-    foundByDocument.set(draft.documentId, [...(foundByDocument.get(draft.documentId) ?? []), draft.title]);
+  const note = (documentId: string, title: string) => {
+    foundByDocument.set(documentId, [...(foundByDocument.get(documentId) ?? []), title]);
+  };
+  for (const draft of ruleDrafts) note(draft.documentId, draft.title);
+
+  // WHAT IS ALREADY TRACKED IS ALSO "ALREADY FOUND". Read BEFORE the model call,
+  // not after, so a second run over the same document tells the model what it
+  // produced last time.
+  //
+  // This is the STRUCTURAL half of idempotency and it exists because the fuzzy
+  // half was not enough: on the live tandem tenant a re-run over four documents
+  // created sixteen duplicates purely because the model reworded its own output.
+  // Matching after the fact is a safety net; not asking the model to invent the
+  // same item twice is the fix.
+  const existing = corpus.listCommitments
+    ? await corpus
+        .listCommitments({ pageSize: 500 })
+        .then((page) => page.results)
+        .catch(() => [] as Commitment[])
+    : [];
+  for (const commitment of existing) {
+    for (const mention of commitment.mentions) {
+      if (allowedIds.has(mention.documentId)) note(mention.documentId, commitment.title);
+    }
   }
 
   // 4. ONE call, every document, ids echoed.
@@ -315,18 +339,10 @@ export async function extractCommitments(
     draft = { items: [], resolutions: [] };
   }
 
-  const allowed = new Set(documents.map((document) => document.id));
-  const modelDrafts = normaliseItems(draft.items ?? [], allowed);
-  const claims = normaliseResolutions(draft.resolutions ?? [], allowed);
+  const modelDrafts = normaliseItems(draft.items ?? [], allowedIds);
+  const claims = normaliseResolutions(draft.resolutions ?? [], allowedIds);
 
   // 5. identity, dedupe within the run, then against what is stored.
-  const existing = corpus.listCommitments
-    ? await corpus
-        .listCommitments({ pageSize: 500 })
-        .then((page) => page.results)
-        .catch(() => [] as Commitment[])
-    : [];
-
   const groups = mergeDrafts([...ruleDrafts, ...modelDrafts]);
   const reconciled = reconcile(existing, groups, { scope: request.scope, documents });