@ghostpaw/affinity 0.1.6 → 0.2.0

package/dist/index.js

@@ -388,11 +388,32 @@ function initContactMergesTables(db) {
   );
 }
 
+// src/merges/init_dismissed_duplicates_tables.ts
+function initDismissedDuplicatesTables(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS dismissed_duplicates (
+      left_id      INTEGER NOT NULL,
+      right_id     INTEGER NOT NULL,
+      reason       TEXT,
+      dismissed_at INTEGER NOT NULL,
+      PRIMARY KEY (left_id, right_id),
+      CHECK (left_id < right_id)
+    )
+  `);
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_dismissed_duplicates_left ON dismissed_duplicates(left_id)"
+  );
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_dismissed_duplicates_right ON dismissed_duplicates(right_id)"
+  );
+}
+
 // src/init_affinity_tables.ts
 function initAffinityTables(db) {
   initContactsTables(db);
   initContactRollupsTables(db);
   initContactMergesTables(db);
+  initDismissedDuplicatesTables(db);
   initIdentitiesTables(db);
   initLinksTables(db);
   initLinkRollupsTables(db);
@@ -500,6 +521,7 @@ __export(read_exports, {
   getMergeHistory: () => getMergeHistory,
   getOwnerProfile: () => getOwnerProfile,
   listContacts: () => listContacts,
+  listDismissedDuplicates: () => listDismissedDuplicates,
   listDuplicateCandidates: () => listDuplicateCandidates,
   listMoments: () => listMoments,
   listObservedLinks: () => listObservedLinks,
@@ -1352,8 +1374,24 @@ function listDuplicateCandidates(db, filters, options) {
       }
     }
   }
+  const dismissedRows = db.prepare("SELECT left_id, right_id FROM dismissed_duplicates").all();
+  const dismissedSet = new Set(
+    dismissedRows.map((r) => pairKey(r.left_id, r.right_id))
+  );
+  const includeDismissed = filters?.includeDismissed === true;
+  for (const candidate of pairs.values()) {
+    if (dismissedSet.has(
+      pairKey(candidate.leftContactId, candidate.rightContactId)
+    )) {
+      candidate.dismissed = true;
+    }
+  }
   const minScore = filters?.minScore ?? 0;
-  return [...pairs.values()].filter((candidate) => candidate.matchScore >= minScore).sort((left, right) => {
+  return [...pairs.values()].filter((candidate) => {
+    if (candidate.matchScore < minScore) return false;
+    if (candidate.dismissed === true && !includeDismissed) return false;
+    return true;
+  }).sort((left, right) => {
     const leftExact = left.matchScore === 1 ? 1 : 0;
     const rightExact = right.matchScore === 1 ? 1 : 0;
     return rightExact - leftExact || right.matchScore - left.matchScore;
@@ -3416,6 +3454,12 @@ function mergeContacts(db, input) {
       `INSERT INTO contact_merges (winner_contact_id, loser_contact_id, merged_at, reason_summary, manual)
        VALUES (?, ?, ?, ?, 1)`
     ).run(winnerId, loserId, now, reasonSummary);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(loserId, loserId);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(winnerId, winnerId);
     db.prepare(
       "DELETE FROM link_rollups WHERE link_id IN (SELECT id FROM links WHERE removed_at IS NOT NULL)"
     ).run();
@@ -3443,6 +3487,117 @@ function mergeContacts(db, input) {
   });
 }
 
+// src/merges/receipts.ts
+function buildDismissalMutationReceipt(primary, partial) {
+  const normalized = normalizeMutationReceiptPartial(partial);
+  return {
+    primary,
+    created: normalized.created,
+    updated: normalized.updated,
+    archived: normalized.archived,
+    removed: normalized.removed,
+    affectedLinks: normalized.affectedLinks,
+    derivedEffects: normalized.derivedEffects
+  };
+}
+
+// src/merges/dismiss_duplicate.ts
+function canonicalize(a, b) {
+  return {
+    leftContactId: Math.min(a, b),
+    rightContactId: Math.max(a, b)
+  };
+}
+function dismissDuplicate(db, leftContactId, rightContactId, reason, now) {
+  return withTransaction(db, () => {
+    if (leftContactId === rightContactId) {
+      throw new AffinityValidationError(
+        "cannot dismiss a contact as a duplicate of itself"
+      );
+    }
+    const left = getContactRowById(db, leftContactId);
+    if (!left) {
+      throw new AffinityNotFoundError(`contact ${leftContactId} not found`);
+    }
+    if (left.lifecycle_state === "merged") {
+      throw new AffinityStateError(
+        `contact ${leftContactId} is merged and cannot be dismissed`
+      );
+    }
+    const right = getContactRowById(db, rightContactId);
+    if (!right) {
+      throw new AffinityNotFoundError(`contact ${rightContactId} not found`);
+    }
+    if (right.lifecycle_state === "merged") {
+      throw new AffinityStateError(
+        `contact ${rightContactId} is merged and cannot be dismissed`
+      );
+    }
+    const pair = canonicalize(leftContactId, rightContactId);
+    const resolvedNow = resolveNow(now);
+    const resolvedReason = reason === void 0 || reason === null ? null : (() => {
+      const t = reason.trim();
+      return t.length === 0 ? null : t;
+    })();
+    db.prepare(
+      `INSERT INTO dismissed_duplicates (left_id, right_id, reason, dismissed_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(left_id, right_id) DO UPDATE SET
+         reason = excluded.reason,
+         dismissed_at = excluded.dismissed_at`
+    ).run(pair.leftContactId, pair.rightContactId, resolvedReason, resolvedNow);
+    return buildDismissalMutationReceipt(pair);
+  });
+}
+
+// src/merges/undismiss_duplicate.ts
+function canonicalize2(a, b) {
+  return {
+    leftContactId: Math.min(a, b),
+    rightContactId: Math.max(a, b)
+  };
+}
+function undismissDuplicate(db, leftContactId, rightContactId) {
+  return withTransaction(db, () => {
+    if (leftContactId === rightContactId) {
+      throw new AffinityValidationError(
+        "cannot undismiss a contact from itself"
+      );
+    }
+    const left = getContactRowById(db, leftContactId);
+    if (!left) {
+      throw new AffinityNotFoundError(`contact ${leftContactId} not found`);
+    }
+    const right = getContactRowById(db, rightContactId);
+    if (!right) {
+      throw new AffinityNotFoundError(`contact ${rightContactId} not found`);
+    }
+    const pair = canonicalize2(leftContactId, rightContactId);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? AND right_id = ?"
+    ).run(pair.leftContactId, pair.rightContactId);
+    return buildDismissalMutationReceipt(pair);
+  });
+}
+
+// src/merges/list_dismissed_duplicates.ts
+function listDismissedDuplicates(db, options) {
+  assertDefaultOrdering("listDismissedDuplicates", options);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const rows = db.prepare(
+    `SELECT left_id, right_id, reason, dismissed_at
+       FROM dismissed_duplicates
+       ORDER BY dismissed_at DESC
+       LIMIT ? OFFSET ?`
+  ).all(limit, offset);
+  return rows.map((row) => ({
+    leftContactId: row.left_id,
+    rightContactId: row.right_id,
+    reason: row.reason,
+    dismissedAt: row.dismissed_at
+  }));
+}
+
 // src/events/get_contact_journal.ts
 function getContactJournal(db, contactId, options) {
   assertDefaultOrdering("getContactJournal", options);
@@ -5331,6 +5486,9 @@ __export(tools_exports, {
   manageDateAnchorTool: () => manageDateAnchorTool,
   manageDateAnchorToolHandler: () => manageDateAnchorToolHandler,
   manageDateAnchorToolName: () => manageDateAnchorToolName,
+  manageDuplicateDismissalTool: () => manageDuplicateDismissalTool,
+  manageDuplicateDismissalToolHandler: () => manageDuplicateDismissalToolHandler,
+  manageDuplicateDismissalToolName: () => manageDuplicateDismissalToolName,
   manageIdentityTool: () => manageIdentityTool,
   manageIdentityToolHandler: () => manageIdentityToolHandler,
   manageIdentityToolName: () => manageIdentityToolName,
@@ -5453,6 +5611,7 @@ var reviewAffinityToolName = "review_affinity";
 var inspectAffinityItemToolName = "inspect_affinity_item";
 var manageContactToolName = "manage_contact";
 var mergeContactsToolName = "merge_contacts";
+var manageDuplicateDismissalToolName = "manage_duplicate_dismissal";
 var manageIdentityToolName = "manage_identity";
 var manageRelationshipToolName = "manage_relationship";
 var recordEventToolName = "record_event";
@@ -6704,7 +6863,7 @@ var manageContactTool = defineAffinityTool({
   handler: manageContactToolHandler
 });
 
-// src/tools/manage_date_anchor_tool.ts
+// src/tools/manage_duplicate_dismissal_tool.ts
 function contactLocatorSchema4(description) {
   return {
     type: "object",
@@ -6722,6 +6881,86 @@ function contactLocatorSchema4(description) {
     description
   };
 }
+function manageDuplicateDismissalToolHandler(db, input) {
+  return withToolHandling(() => {
+    const left = resolveContactLocator(db, input.left, "left");
+    if (!left.ok) {
+      return left.result;
+    }
+    const right = resolveContactLocator(db, input.right, "right");
+    if (!right.ok) {
+      return right.result;
+    }
+    if (input.action === "dismiss") {
+      const receipt2 = dismissDuplicate(
+        db,
+        left.value.id,
+        right.value.id,
+        input.reason ?? null
+      );
+      return toolSuccess(
+        `Dismissed pair #${receipt2.primary.leftContactId} / #${receipt2.primary.rightContactId}.`,
+        { action: "dismiss", primary: receipt2.primary }
+      );
+    }
+    const receipt = undismissDuplicate(db, left.value.id, right.value.id);
+    return toolSuccess(
+      `Un-dismissed pair #${receipt.primary.leftContactId} / #${receipt.primary.rightContactId}.`,
+      { action: "undismiss", primary: receipt.primary }
+    );
+  }, "Duplicate dismissal failed.");
+}
+var manageDuplicateDismissalTool = defineAffinityTool({
+  name: manageDuplicateDismissalToolName,
+  description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in listDuplicateCandidates.",
+  whenToUse: "Use dismiss after confirming two contacts are different people (not duplicates). Use undismiss to re-surface a pair for re-evaluation.",
+  whenNotToUse: "Do not use this to merge contacts \u2014 use merge_contacts for confirmed duplicates.",
+  sideEffects: "writes_state",
+  readOnly: false,
+  supportsClarification: true,
+  targetKinds: ["contact"],
+  inputDescriptions: {
+    action: "dismiss to suppress the pair; undismiss to re-surface it.",
+    left: "One contact of the pair.",
+    right: "The other contact of the pair.",
+    reason: "Optional reason for the dismissal (audit trail)."
+  },
+  outputDescription: "Returns the dismissal receipt with the canonical pair identifiers.",
+  inputSchema: objectSchema(
+    {
+      action: enumSchema("Action to perform.", ["dismiss", "undismiss"]),
+      left: contactLocatorSchema4(
+        "Left contact. Provide contactId or identity."
+      ),
+      right: contactLocatorSchema4(
+        "Right contact. Provide contactId or identity."
+      ),
+      reason: nullableStringSchema("Optional reason for the dismissal.")
+    },
+    ["action", "left", "right"],
+    "Dismiss or un-dismiss a duplicate candidate pair."
+  ),
+  handler: manageDuplicateDismissalToolHandler
+});
+
+// src/tools/manage_date_anchor_tool.ts
+function contactLocatorSchema5(description) {
+  return {
+    type: "object",
+    properties: {
+      contactId: integerSchema("Exact contact id."),
+      identity: objectSchema(
+        {
+          type: stringSchema("Identity type."),
+          value: stringSchema("Identity value.")
+        },
+        ["type", "value"],
+        "Contact identity locator."
+      )
+    },
+    description
+  };
+}
 function linkLocatorSchema3(description) {
   return {
     type: "object",
@@ -6812,7 +7051,7 @@ var manageDateAnchorTool = defineAffinityTool({
           target: objectSchema(
             {
               kind: enumSchema("Target kind.", ["contact", "link"]),
-              contact: contactLocatorSchema4(
+              contact: contactLocatorSchema5(
                 "Contact locator. Required when kind=contact. Provide contactId or identity."
               ),
               link: linkLocatorSchema3(
@@ -6966,6 +7205,9 @@ function addIdentity(db, contactId, input) {
       throw new AffinityInvariantError("inserted identity not found");
     }
     refreshContactRollup(db, contactId, now);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(contactId, contactId);
     return buildIdentityMutationReceipt(mapIdentityRowToIdentityRecord(row), {
       created: [{ kind: "identity", id }]
     });
@@ -6989,6 +7231,9 @@ function removeIdentity(db, identityId, removedAt) {
       "UPDATE identities SET removed_at = ?, updated_at = ? WHERE id = ?"
     ).run(now, now, identityId);
     refreshContactRollup(db, row.contact_id, now);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(row.contact_id, row.contact_id);
     return buildIdentityMutationReceipt(primary, {
       removed: [{ kind: "identity", id: identityId }]
     });
@@ -7067,7 +7312,7 @@ function verifyIdentity(db, identityId, verifiedAt) {
 }
 
 // src/tools/manage_identity_tool.ts
-function contactLocatorSchema5(description) {
+function contactLocatorSchema6(description) {
   return {
     type: "object",
     properties: {
@@ -7146,7 +7391,7 @@ var manageIdentityTool = defineAffinityTool({
         "verify",
         "remove"
       ]),
-      contact: contactLocatorSchema5(
+      contact: contactLocatorSchema6(
         "Target contact. Required when action=add. Provide contactId or identity."
       ),
       input: objectSchema(
@@ -7186,7 +7431,7 @@ var manageIdentityTool = defineAffinityTool({
 });
 
 // src/tools/manage_relationship_tool.ts
-function contactLocatorSchema6(description) {
+function contactLocatorSchema7(description) {
   return {
     type: "object",
     properties: {
@@ -7342,10 +7587,10 @@ var manageRelationshipTool = defineAffinityTool({
         "set_structural_tie",
         "remove_structural_tie"
       ]),
-      from: contactLocatorSchema6(
+      from: contactLocatorSchema7(
         "Source contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
-      to: contactLocatorSchema6(
+      to: contactLocatorSchema7(
         "Target contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
       kind: stringSchema(
@@ -7387,7 +7632,7 @@ var manageRelationshipTool = defineAffinityTool({
 });
 
 // src/tools/merge_contacts_tool.ts
-function contactLocatorSchema7(description) {
+function contactLocatorSchema8(description) {
   return {
     type: "object",
     properties: {
@@ -7444,10 +7689,10 @@ var mergeContactsTool = defineAffinityTool({
   outputDescription: "Returns the merge receipt with rewired entities and affected-link information.",
   inputSchema: objectSchema(
     {
-      winner: contactLocatorSchema7(
+      winner: contactLocatorSchema8(
         "Winner contact. Provide contactId or identity."
       ),
-      loser: contactLocatorSchema7(
+      loser: contactLocatorSchema8(
         "Loser contact. Provide contactId or identity."
       ),
       reasonSummary: stringSchema("Optional merge reason."),
@@ -7618,7 +7863,7 @@ function buildChartOptions(input) {
     ...input.contactIds === void 0 ? {} : { contactIds: input.contactIds }
   };
 }
-function contactLocatorSchema8(description) {
+function contactLocatorSchema9(description) {
   return {
     type: "object",
     properties: {
@@ -7709,6 +7954,14 @@ function validateReviewInput(input) {
       "Use `contactIds` only with duplicate-candidate or chart review views."
     );
   }
+  if (input.includeDismissed !== void 0 && input.view !== "contacts.duplicates") {
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "The `includeDismissed` filter is not valid for this review view.",
+      "Use `includeDismissed` only with the contacts.duplicates review view."
+    );
+  }
   return null;
 }
 function duplicateCandidateItem(candidate) {
@@ -7765,6 +8018,15 @@ function mergeHistoryItem(record) {
     snippet: record.reasonSummary ?? void 0
   };
 }
+function dismissedPairItem(record) {
+  return {
+    kind: "contact",
+    id: record.leftContactId,
+    title: `Dismissed pair: #${record.leftContactId} and #${record.rightContactId}`,
+    subtitle: record.reason ?? "no reason given",
+    snippet: `dismissed at ${record.dismissedAt}`
+  };
+}
 function compactFilters(input) {
   return Object.fromEntries(
     Object.entries(input).filter(
@@ -7800,7 +8062,8 @@ function reviewAffinityToolHandler(db, input) {
           {
             ...input.contactIds === void 0 ? {} : { contactIds: input.contactIds },
             ...input.exactOnly === void 0 ? {} : { exactOnly: input.exactOnly },
-            ...input.minScore === void 0 ? {} : { minScore: input.minScore }
+            ...input.minScore === void 0 ? {} : { minScore: input.minScore },
+            ...input.includeDismissed === void 0 ? {} : { includeDismissed: input.includeDismissed }
           },
           options
         ).map(duplicateCandidateItem);
@@ -7981,6 +8244,9 @@ function reviewAffinityToolHandler(db, input) {
         );
         break;
       }
+      case "merges.dismissed":
+        items = listDismissedDuplicates(db, options).map(dismissedPairItem);
+        break;
     }
     return toolSuccess(
       summarizeCount(items.length, "item"),
@@ -8031,6 +8297,7 @@ var reviewAffinityTool = defineAffinityTool({
     horizonDays: "Optional horizon filter for commitments or upcoming dates.",
     exactOnly: "Whether duplicate review should only include exact identity matches.",
     minScore: "Optional minimum duplicate score.",
+    includeDismissed: "Whether dismissed pairs should be included in duplicate review (marked with dismissed flag).",
     since: "Optional lower timestamp bound for time-based views.",
     until: "Optional upper timestamp bound for time-based views.",
     limit: "Optional result limit.",
@@ -8052,9 +8319,10 @@ var reviewAffinityTool = defineAffinityTool({
         "links.radar",
         "dates.upcoming",
         "graph.chart",
-        "merges.history"
+        "merges.history",
+        "merges.dismissed"
       ]),
-      contact: contactLocatorSchema8("Optional target contact locator."),
+      contact: contactLocatorSchema9("Optional target contact locator."),
       link: linkLocatorSchema5("Optional target link locator."),
       contactIds: arraySchema(
         integerSchema("Contact id."),
@@ -8105,6 +8373,9 @@ var reviewAffinityTool = defineAffinityTool({
       horizonDays: integerSchema("Optional horizon-days filter."),
       exactOnly: booleanSchema("Whether duplicate review is exact-only."),
       minScore: numberSchema("Optional duplicate minimum score."),
+      includeDismissed: booleanSchema(
+        "Whether dismissed pairs are included in duplicate review (marked with dismissed flag)."
+      ),
       since: integerSchema("Optional lower timestamp bound."),
       until: integerSchema("Optional upper timestamp bound."),
       limit: integerSchema("Optional result limit."),
@@ -8203,6 +8474,7 @@ var affinityTools = [
   inspectAffinityItemTool,
   manageContactTool,
   mergeContactsTool,
+  manageDuplicateDismissalTool,
   manageIdentityTool,
   manageRelationshipTool,
   recordEventTool,
@@ -8304,6 +8576,21 @@ var affinityToolMappings = [
     action: "set_lifecycle"
   },
   { source: "mergeContacts", tool: mergeContactsToolName },
+  {
+    source: "dismissDuplicate",
+    tool: manageDuplicateDismissalToolName,
+    action: "dismiss"
+  },
+  {
+    source: "undismissDuplicate",
+    tool: manageDuplicateDismissalToolName,
+    action: "undismiss"
+  },
+  {
+    source: "listDismissedDuplicates",
+    tool: reviewAffinityToolName,
+    view: "merges.dismissed"
+  },
   { source: "addIdentity", tool: manageIdentityToolName, action: "add" },
   { source: "reviseIdentity", tool: manageIdentityToolName, action: "revise" },
   { source: "verifyIdentity", tool: manageIdentityToolName, action: "verify" },
@@ -8385,6 +8672,7 @@ __export(write_exports, {
   addDateAnchor: () => addDateAnchor,
   addIdentity: () => addIdentity,
   createContact: () => createContact,
+  dismissDuplicate: () => dismissDuplicate,
   mergeContacts: () => mergeContacts,
   overrideLinkState: () => overrideLinkState,
   recordCommitment: () => recordCommitment,
@@ -8405,6 +8693,7 @@ __export(write_exports, {
   setAttribute: () => setAttribute,
   setContactLifecycle: () => setContactLifecycle,
   setStructuralTie: () => setStructuralTie,
+  undismissDuplicate: () => undismissDuplicate,
   unsetAttribute: () => unsetAttribute,
   verifyIdentity: () => verifyIdentity
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostpaw/affinity",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Relationship intelligence and social CRM model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
   "license": "MIT",
   "author": {