@ghostpaw/affinity 0.1.5 → 0.2.0

package/dist/index.cjs

@@ -390,11 +390,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);
@@ -502,6 +523,7 @@ __export(read_exports, {
   getMergeHistory: () => getMergeHistory,
   getOwnerProfile: () => getOwnerProfile,
   listContacts: () => listContacts,
+  listDismissedDuplicates: () => listDismissedDuplicates,
   listDuplicateCandidates: () => listDuplicateCandidates,
   listMoments: () => listMoments,
   listObservedLinks: () => listObservedLinks,
@@ -1354,8 +1376,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;
@@ -3418,6 +3456,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();
@@ -3445,6 +3489,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);
@@ -5333,6 +5488,9 @@ __export(tools_exports, {
   manageDateAnchorTool: () => manageDateAnchorTool,
   manageDateAnchorToolHandler: () => manageDateAnchorToolHandler,
   manageDateAnchorToolName: () => manageDateAnchorToolName,
+  manageDuplicateDismissalTool: () => manageDuplicateDismissalTool,
+  manageDuplicateDismissalToolHandler: () => manageDuplicateDismissalToolHandler,
+  manageDuplicateDismissalToolName: () => manageDuplicateDismissalToolName,
   manageIdentityTool: () => manageIdentityTool,
   manageIdentityToolHandler: () => manageIdentityToolHandler,
   manageIdentityToolName: () => manageIdentityToolName,
@@ -5455,6 +5613,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";
@@ -6443,12 +6602,43 @@ var manageAttributeTool = defineAffinityTool({
 });
 
 // src/tools/manage_commitment_tool.ts
+function normalizeParticipant(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants(db, raw) {
+  return ensureOwnerParticipates(db, raw.map(normalizeParticipant));
+}
 function manageCommitmentToolHandler(db, input) {
   return withToolHandling(() => {
     if (input.action === "record") {
+      const patched = {
+        ...input.input,
+        participants: prepareParticipants(
+          db,
+          input.input.participants
+        )
+      };
       return mutationToolResult(
         "record",
-        recordCommitment(db, input.input),
+        recordCommitment(db, patched),
         "commitment"
       );
     }
@@ -6466,7 +6656,7 @@ function manageCommitmentToolHandler(db, input) {
 }
 var manageCommitmentTool = defineAffinityTool({
   name: manageCommitmentToolName,
-  description: "Record or resolve one commitment such as a promise or agreement.",
+  description: "Record or resolve one commitment such as a promise or agreement. The owner contact is auto-injected into participants if missing.",
   whenToUse: "Use this when the work is specifically about a commitment lifecycle rather than a general event.",
   whenNotToUse: "Do not use this for ordinary interactions or direct relationship state changes.",
   sideEffects: "writes_state",
@@ -6484,10 +6674,42 @@ var manageCommitmentTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["record", "resolve"]),
-      input: {
-        type: "object",
-        description: "Commitment payload. Required when action=record."
-      },
+      input: objectSchema(
+        {
+          commitmentType: enumSchema("Promise or agreement.", [
+            "promise",
+            "agreement"
+          ]),
+          occurredAt: integerSchema(
+            "When the commitment was made, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Commitment summary. Must be non-empty."),
+          significance: integerSchema("Commitment significance from 1 to 10."),
+          dueAt: integerSchema("Optional due timestamp."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: stringSchema("Participant role."),
+                directionality: stringSchema("Optional directionality.")
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        [
+          "commitmentType",
+          "occurredAt",
+          "summary",
+          "significance",
+          "participants"
+        ],
+        "Commitment payload. Required when action=record."
+      ),
       commitmentEventId: integerSchema(
         "Commitment event id. Required when action=resolve."
       ),
@@ -6643,7 +6865,124 @@ var manageContactTool = defineAffinityTool({
   handler: manageContactToolHandler
 });
 
+// src/tools/manage_duplicate_dismissal_tool.ts
+function contactLocatorSchema4(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 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",
+    properties: {
+      linkId: integerSchema("Exact link id."),
+      endpoints: objectSchema(
+        {
+          fromContactId: integerSchema("From contact id."),
+          toContactId: integerSchema("To contact id."),
+          kind: stringSchema("Optional link kind."),
+          role: stringSchema("Optional link role."),
+          isStructural: booleanSchema("Optional structural discriminator.")
+        },
+        ["fromContactId", "toContactId"],
+        "Endpoint-based link locator."
+      )
+    },
+    description
+  };
+}
 function resolveDateAnchorTarget(db, target) {
   if (target.kind === "contact") {
     const contact = resolveContactLocator(db, target.contact, "target.contact");
@@ -6709,17 +7048,65 @@ var manageDateAnchorTool = defineAffinityTool({
   inputSchema: objectSchema(
     {
       action: enumSchema("Operation to perform.", ["add", "revise", "remove"]),
-      input: {
-        type: "object",
-        description: "Date anchor payload. Required when action=add."
-      },
+      input: objectSchema(
+        {
+          target: objectSchema(
+            {
+              kind: enumSchema("Target kind.", ["contact", "link"]),
+              contact: contactLocatorSchema5(
+                "Contact locator. Required when kind=contact. Provide contactId or identity."
+              ),
+              link: linkLocatorSchema3(
+                "Link locator. Required when kind=link. Provide linkId or endpoints."
+              )
+            },
+            ["kind"],
+            "Date-anchor target."
+          ),
+          recurrenceKind: enumSchema("Recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Anchor month, 1\u201312."),
+          anchorDay: integerSchema("Anchor day, 1\u201331 (validated per month)."),
+          summary: stringSchema("Summary. Must be non-empty."),
+          significance: integerSchema("Significance from 1 to 10."),
+          now: integerSchema("Optional timestamp override."),
+          force: booleanSchema("Whether to bypass duplicate checks.")
+        },
+        [
+          "target",
+          "recurrenceKind",
+          "anchorMonth",
+          "anchorDay",
+          "summary",
+          "significance"
+        ],
+        "Date anchor payload. Required when action=add."
+      ),
       anchorEventId: integerSchema(
         "Anchor event id. Required when action=revise or remove."
       ),
-      patch: {
-        type: "object",
-        description: "Anchor patch. Required when action=revise."
-      },
+      patch: objectSchema(
+        {
+          recurrenceKind: enumSchema("Optional recurrence kind.", [
+            "birthday",
+            "anniversary",
+            "renewal",
+            "memorial",
+            "custom_yearly"
+          ]),
+          anchorMonth: integerSchema("Optional month, 1\u201312."),
+          anchorDay: integerSchema("Optional day, 1\u201331."),
+          summary: stringSchema("Optional summary."),
+          significance: integerSchema("Optional significance, 1\u201310.")
+        },
+        [],
+        "Anchor patch. Required when action=revise."
+      ),
       options: objectSchema(
         {
           now: integerSchema("Optional timestamp."),
@@ -6820,6 +7207,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 }]
     });
@@ -6843,6 +7233,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 }]
     });
@@ -6921,7 +7314,7 @@ function verifyIdentity(db, identityId, verifiedAt) {
 }
 
 // src/tools/manage_identity_tool.ts
-function contactLocatorSchema4(description) {
+function contactLocatorSchema6(description) {
   return {
     type: "object",
     properties: {
@@ -7000,7 +7393,7 @@ var manageIdentityTool = defineAffinityTool({
         "verify",
         "remove"
       ]),
-      contact: contactLocatorSchema4(
+      contact: contactLocatorSchema6(
         "Target contact. Required when action=add. Provide contactId or identity."
       ),
       input: objectSchema(
@@ -7040,7 +7433,7 @@ var manageIdentityTool = defineAffinityTool({
 });
 
 // src/tools/manage_relationship_tool.ts
-function contactLocatorSchema5(description) {
+function contactLocatorSchema7(description) {
   return {
     type: "object",
     properties: {
@@ -7057,7 +7450,7 @@ function contactLocatorSchema5(description) {
     description
   };
 }
-function linkLocatorSchema3(description) {
+function linkLocatorSchema4(description) {
   return {
     type: "object",
     properties: {
@@ -7196,14 +7589,14 @@ var manageRelationshipTool = defineAffinityTool({
         "set_structural_tie",
         "remove_structural_tie"
       ]),
-      from: contactLocatorSchema5(
+      from: contactLocatorSchema7(
         "Source contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
-      to: contactLocatorSchema5(
+      to: contactLocatorSchema7(
         "Target contact. Required when action=seed_social_link or set_structural_tie. Provide contactId or identity."
       ),
       kind: stringSchema(
-        "Link kind. Required for seed_social_link and set_structural_tie. Can be passed here or inside input."
+        "Link kind. Required for seed_social_link and set_structural_tie. Can be passed here or inside input. For seed_social_link: personal, family, professional, romantic, care, service, observed, other_relational. For set_structural_tie: works_at, manages, member_of, married_to, partner_of, parent_of, child_of, sibling_of, friend_of, client_of, vendor_of, reports_to, belongs_to, other_structural."
       ),
       role: stringSchema(
         "Optional role for seed_social_link or set_structural_tie. Can be passed here or inside input."
@@ -7212,7 +7605,7 @@ var manageRelationshipTool = defineAffinityTool({
         type: "object",
         description: "Full payload for seed_social_link or set_structural_tie. Alternative to top-level kind/role."
       },
-      link: linkLocatorSchema3(
+      link: linkLocatorSchema4(
         "Target link. Required when action=revise_bond, override_state, or remove_structural_tie. Provide linkId or endpoints."
       ),
       bond: nullableStringSchema(
@@ -7241,7 +7634,7 @@ var manageRelationshipTool = defineAffinityTool({
 });
 
 // src/tools/merge_contacts_tool.ts
-function contactLocatorSchema6(description) {
+function contactLocatorSchema8(description) {
   return {
     type: "object",
     properties: {
@@ -7298,10 +7691,10 @@ var mergeContactsTool = defineAffinityTool({
   outputDescription: "Returns the merge receipt with rewired entities and affected-link information.",
   inputSchema: objectSchema(
     {
-      winner: contactLocatorSchema6(
+      winner: contactLocatorSchema8(
         "Winner contact. Provide contactId or identity."
       ),
-      loser: contactLocatorSchema6(
+      loser: contactLocatorSchema8(
         "Loser contact. Provide contactId or identity."
       ),
       reasonSummary: stringSchema("Optional merge reason."),
@@ -7314,31 +7707,64 @@ var mergeContactsTool = defineAffinityTool({
 });
 
 // src/tools/record_event_tool.ts
+function normalizeParticipant2(p) {
+  let contactId = p.contactId;
+  if (contactId === void 0 && p.contact != null) {
+    const loc = p.contact;
+    contactId = loc.contactId;
+  }
+  const result = {
+    contactId,
+    role: p.role
+  };
+  if (p.directionality !== void 0) {
+    result.directionality = p.directionality;
+  }
+  return result;
+}
+function ensureOwnerParticipates2(db, participants) {
+  const ownerId = findOwnerContactId(db);
+  if (ownerId === null) return participants;
+  if (participants.some((p) => p.contactId === ownerId)) return participants;
+  return [{ contactId: ownerId, role: "actor" }, ...participants];
+}
+function prepareParticipants2(db, raw, injectOwner) {
+  const normalized = raw.map(normalizeParticipant2);
+  return injectOwner ? ensureOwnerParticipates2(db, normalized) : normalized;
+}
 function recordEventToolHandler(db, input) {
   return withToolHandling(() => {
+    const patched = {
+      ...input.input,
+      participants: prepareParticipants2(
+        db,
+        input.input.participants,
+        input.kind !== "observation"
+      )
+    };
     switch (input.kind) {
       case "interaction":
         return mutationToolResult(
           "interaction",
-          recordInteraction(db, input.input),
+          recordInteraction(db, patched),
           "event"
         );
       case "observation":
         return mutationToolResult(
           "observation",
-          recordObservation(db, input.input),
+          recordObservation(db, patched),
           "event"
         );
       case "milestone":
         return mutationToolResult(
           "milestone",
-          recordMilestone(db, input.input),
+          recordMilestone(db, patched),
           "event"
         );
       case "transaction":
         return mutationToolResult(
           "transaction",
-          recordTransaction(db, input.input),
+          recordTransaction(db, patched),
           "event"
         );
     }
@@ -7346,7 +7772,7 @@ function recordEventToolHandler(db, input) {
 }
 var recordEventTool = defineAffinityTool({
   name: recordEventToolName,
-  description: "Record one social event such as an interaction, observation, milestone, or transaction.",
+  description: "Record one social event such as an interaction, observation, milestone, or transaction. For interactions, milestones, and transactions the owner contact is auto-injected into participants if missing. Observations may omit the owner when recording third-party evidence.",
   whenToUse: "Use this when you are capturing something that happened in the relationship graph.",
   whenNotToUse: "Do not use this for commitments, date anchors, or direct relationship state overrides.",
   sideEffects: "writes_state",
@@ -7366,10 +7792,53 @@ var recordEventTool = defineAffinityTool({
         "milestone",
         "transaction"
       ]),
-      input: {
-        type: "object",
-        description: "Event payload. Shape depends on kind. Interaction events require a `type` subtype; others do not. Always required."
-      }
+      input: objectSchema(
+        {
+          type: enumSchema(
+            "Interaction subtype. Required when kind=interaction, omit otherwise.",
+            [
+              "conversation",
+              "activity",
+              "gift",
+              "support",
+              "conflict",
+              "correction"
+            ]
+          ),
+          occurredAt: integerSchema(
+            "When the event occurred, Unix timestamp in milliseconds."
+          ),
+          summary: stringSchema("Event summary. Must be non-empty."),
+          significance: integerSchema("Event significance from 1 to 10."),
+          participants: arraySchema(
+            objectSchema(
+              {
+                contactId: integerSchema(
+                  "Participant contact id. The owner contact MUST be included."
+                ),
+                role: enumSchema("Participant role.", [
+                  "actor",
+                  "recipient",
+                  "subject",
+                  "observer",
+                  "mentioned"
+                ]),
+                directionality: enumSchema("Optional directionality.", [
+                  "owner_initiated",
+                  "other_initiated",
+                  "mutual",
+                  "observed"
+                ])
+              },
+              ["contactId", "role"]
+            ),
+            "Participant list. Must be non-empty and include the owner contact."
+          ),
+          now: integerSchema("Optional timestamp override.")
+        },
+        ["occurredAt", "summary", "significance", "participants"],
+        "Event payload. Always required. Interaction events also require `type`."
+      )
     },
     ["kind", "input"],
     "Record one social event."
@@ -7396,7 +7865,7 @@ function buildChartOptions(input) {
     ...input.contactIds === void 0 ? {} : { contactIds: input.contactIds }
   };
 }
-function contactLocatorSchema7(description) {
+function contactLocatorSchema9(description) {
   return {
     type: "object",
     properties: {
@@ -7413,7 +7882,7 @@ function contactLocatorSchema7(description) {
     description
   };
 }
-function linkLocatorSchema4(description) {
+function linkLocatorSchema5(description) {
   return {
     type: "object",
     properties: {
@@ -7487,6 +7956,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) {
@@ -7543,6 +8020,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(
@@ -7578,7 +8064,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);
@@ -7759,6 +8246,9 @@ function reviewAffinityToolHandler(db, input) {
         );
         break;
       }
+      case "merges.dismissed":
+        items = listDismissedDuplicates(db, options).map(dismissedPairItem);
+        break;
     }
     return toolSuccess(
       summarizeCount(items.length, "item"),
@@ -7809,6 +8299,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.",
@@ -7830,10 +8321,11 @@ var reviewAffinityTool = defineAffinityTool({
         "links.radar",
         "dates.upcoming",
         "graph.chart",
-        "merges.history"
+        "merges.history",
+        "merges.dismissed"
       ]),
-      contact: contactLocatorSchema7("Optional target contact locator."),
-      link: linkLocatorSchema4("Optional target link locator."),
+      contact: contactLocatorSchema9("Optional target contact locator."),
+      link: linkLocatorSchema5("Optional target link locator."),
       contactIds: arraySchema(
         integerSchema("Contact id."),
         "Optional contact-id subset."
@@ -7883,6 +8375,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."),
@@ -7981,6 +8476,7 @@ var affinityTools = [
   inspectAffinityItemTool,
   manageContactTool,
   mergeContactsTool,
+  manageDuplicateDismissalTool,
   manageIdentityTool,
   manageRelationshipTool,
   recordEventTool,
@@ -8082,6 +8578,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" },
@@ -8163,6 +8674,7 @@ __export(write_exports, {
   addDateAnchor: () => addDateAnchor,
   addIdentity: () => addIdentity,
   createContact: () => createContact,
+  dismissDuplicate: () => dismissDuplicate,
   mergeContacts: () => mergeContacts,
   overrideLinkState: () => overrideLinkState,
   recordCommitment: () => recordCommitment,
@@ -8183,6 +8695,7 @@ __export(write_exports, {
   setAttribute: () => setAttribute,
   setContactLifecycle: () => setContactLifecycle,
   setStructuralTie: () => setStructuralTie,
+  undismissDuplicate: () => undismissDuplicate,
   unsetAttribute: () => unsetAttribute,
   verifyIdentity: () => verifyIdentity
 });