@ghostpaw/affinity 0.4.0 → 0.5.0

package/dist/index.js

@@ -263,6 +263,12 @@ function initLinkEventEffectsTables(db) {
       )
     )
   `);
+  const columns = db.prepare("PRAGMA table_info(link_event_effects)").all();
+  if (!columns.some((column) => column.name === "counts_for_recency")) {
+    db.exec(
+      "ALTER TABLE link_event_effects ADD COLUMN counts_for_recency INTEGER NOT NULL DEFAULT 1"
+    );
+  }
   db.exec(
     "CREATE INDEX IF NOT EXISTS idx_link_event_effects_link_time ON link_event_effects(link_id, occurred_at DESC, event_id DESC)"
   );
@@ -513,6 +519,8 @@ function resolveAffinityListLimit(limit) {
 // src/read.ts
 var read_exports = {};
 __export(read_exports, {
+  exportAffinity: () => exportAffinity,
+  exportContact: () => exportContact,
   getAffinityChart: () => getAffinityChart,
   getContactJournal: () => getContactJournal,
   getContactProfile: () => getContactProfile,
@@ -786,13 +794,20 @@ function createContact(db, input) {
     if (!KINDS.has(input.kind)) {
       throw new AffinityValidationError("invalid contact kind");
     }
+    if (input.isOwner !== void 0) {
+      throw new AffinityValidationError(
+        "isOwner is read-only; pass bootstrapOwner: true to create the owner contact"
+      );
+    }
     const now = resolveNow(input.now);
     if (input.bootstrapOwner) {
       const existing = db.prepare(
-        "SELECT id FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
+        "SELECT id, name FROM contacts WHERE is_owner = 1 AND deleted_at IS NULL"
       ).get();
       if (existing !== void 0) {
-        throw new AffinityConflictError("owner already exists");
+        throw new AffinityConflictError(
+          `owner already exists: contact ${existing.id} (${existing.name}); bootstrapOwner can only be used once`
+        );
       }
     }
     const isOwner = input.bootstrapOwner ? 1 : 0;
@@ -813,6 +828,25 @@ function createContact(db, input) {
   });
 }
 
+// src/lib/read/assert_default_ordering.ts
+function assertDefaultOrdering(_readName, options) {
+  if (options?.sort !== void 0 || options?.descending !== void 0) {
+    throw new AffinityValidationError(
+      "This review does not support custom sort ordering"
+    );
+  }
+}
+
+// src/lib/read/resolve_list_limit_offset.ts
+function resolveListLimitOffset(options) {
+  const limit = resolveAffinityListLimit(options?.limit);
+  const offset = options?.offset ?? 0;
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new AffinityValidationError("offset must be a non-negative integer");
+  }
+  return { limit, offset };
+}
+
 // src/events/validators.ts
 var PARTICIPANT_ROLES = /* @__PURE__ */ new Set([
   "actor",
@@ -846,7 +880,10 @@ function assertParticipantContactsLive(db, contactIds) {
       throw new AffinityNotFoundError("contact not found");
     }
     if (row.lifecycle_state === "merged") {
-      throw new AffinityStateError("merged contact is read-only");
+      const winner = row.merged_into_contact_id === null ? null : getContactRowById(db, row.merged_into_contact_id);
+      throw new AffinityStateError(
+        `Contact #${id} was merged into #${row.merged_into_contact_id} ${winner?.name ?? ""}; use contactId ${row.merged_into_contact_id}`
+      );
     }
   }
 }
@@ -1018,6 +1055,213 @@ function findDuplicateDateAnchor(db, params) {
   return null;
 }
 
+// src/events/loaders.ts
+function loadEventParticipantViews(db, eventId) {
+  const rows = db.prepare(
+    `SELECT contact_id, role, directionality
+       FROM event_participants
+       WHERE event_id = ?`
+  ).all(eventId);
+  return rows.map((row) => ({
+    contactId: row.contact_id,
+    role: row.role,
+    ...row.directionality === null ? {} : { directionality: row.directionality }
+  }));
+}
+function loadEventRecord(db, eventId) {
+  const row = getEventRowById(db, eventId);
+  if (!row) {
+    throw new AffinityInvariantError("event not found");
+  }
+  const participants = loadEventParticipantViews(db, eventId);
+  return mapEventRowToEventRecord(row, participants);
+}
+function batchLoadEventRecords(db, eventIds) {
+  if (eventIds.length === 0) {
+    return [];
+  }
+  const ph = eventIds.map(() => "?").join(", ");
+  const eventRows = db.prepare(
+    `SELECT id, type, occurred_at, summary, significance, moment_kind,
+              recurrence_kind, anchor_month, anchor_day,
+              anchor_contact_id, anchor_link_id,
+              created_at, updated_at, deleted_at
+       FROM events WHERE id IN (${ph}) AND deleted_at IS NULL`
+  ).all(...eventIds);
+  const partRows = db.prepare(
+    `SELECT event_id, contact_id, role, directionality
+       FROM event_participants WHERE event_id IN (${ph})`
+  ).all(...eventIds);
+  const partsByEvent = /* @__PURE__ */ new Map();
+  for (const p of partRows) {
+    let arr = partsByEvent.get(p.event_id);
+    if (!arr) {
+      arr = [];
+      partsByEvent.set(p.event_id, arr);
+    }
+    arr.push({
+      contactId: p.contact_id,
+      role: p.role,
+      ...p.directionality === null ? {} : { directionality: p.directionality }
+    });
+  }
+  const rowById = new Map(eventRows.map((r) => [r.id, r]));
+  const out = [];
+  for (const id of eventIds) {
+    const row = rowById.get(id);
+    if (row) {
+      out.push(mapEventRowToEventRecord(row, partsByEvent.get(id) ?? []));
+    }
+  }
+  return out;
+}
+function batchLoadEventParticipantViews(db, eventIds) {
+  const result = /* @__PURE__ */ new Map();
+  if (eventIds.length === 0) {
+    return result;
+  }
+  const ph = eventIds.map(() => "?").join(", ");
+  const rows = db.prepare(
+    `SELECT event_id, contact_id, role, directionality
+       FROM event_participants WHERE event_id IN (${ph})`
+  ).all(...eventIds);
+  for (const row of rows) {
+    let arr = result.get(row.event_id);
+    if (!arr) {
+      arr = [];
+      result.set(row.event_id, arr);
+    }
+    arr.push({
+      contactId: row.contact_id,
+      role: row.role,
+      ...row.directionality === null ? {} : { directionality: row.directionality }
+    });
+  }
+  return result;
+}
+function requireDateAnchorEvent(db, eventId) {
+  const row = getEventRowById(db, eventId);
+  if (!row) {
+    throw new AffinityNotFoundError("event not found");
+  }
+  if (row.type !== "date_anchor") {
+    throw new AffinityInvariantError("not a date anchor");
+  }
+  return row;
+}
+
+// src/events/get_contact_journal.ts
+function getContactJournal(db, contactId, options) {
+  assertDefaultOrdering("getContactJournal", options);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const clauses = ["e.deleted_at IS NULL", "ep.contact_id = ?"];
+  const params = [contactId];
+  if (options?.since !== void 0) {
+    clauses.push("e.occurred_at >= ?");
+    params.push(options.since);
+  }
+  if (options?.until !== void 0) {
+    clauses.push("e.occurred_at <= ?");
+    params.push(options.until);
+  }
+  if (options?.eventTypes !== void 0 && options.eventTypes.length > 0) {
+    const ph = options.eventTypes.map(() => "?").join(", ");
+    clauses.push(`e.type IN (${ph})`);
+    params.push(...options.eventTypes);
+  }
+  const where = clauses.join(" AND ");
+  const rows = db.prepare(
+    `SELECT e.id FROM events e
+       INNER JOIN event_participants ep ON ep.event_id = e.id
+       WHERE ${where}
+       ORDER BY e.occurred_at DESC, e.id DESC
+       LIMIT ? OFFSET ?`
+  ).all(...params, limit, offset);
+  return batchLoadEventRecords(
+    db,
+    rows.map((r) => r.id)
+  );
+}
+
+// src/events/list_open_commitments.ts
+var DAY_MS = 864e5;
+function mapResolution(resolvedAt, resolution) {
+  if (resolvedAt === null) {
+    return "open";
+  }
+  if (resolution === "cancelled") {
+    return "cancelled";
+  }
+  return "resolved";
+}
+function listOpenCommitments(db, filters, options) {
+  assertDefaultOrdering("listOpenCommitments", options);
+  const now = resolveNow(options?.now);
+  const { limit, offset } = resolveListLimitOffset(options);
+  const clauses = ["e.deleted_at IS NULL", "oc.resolved_at IS NULL"];
+  const params = [];
+  if (options?.since !== void 0) {
+    clauses.push("e.occurred_at >= ?");
+    params.push(options.since);
+  }
+  if (options?.until !== void 0) {
+    clauses.push("e.occurred_at <= ?");
+    params.push(options.until);
+  }
+  if (filters?.commitmentType !== void 0) {
+    if (filters.commitmentType !== "promise" && filters.commitmentType !== "agreement") {
+      throw new AffinityValidationError("invalid commitmentType filter");
+    }
+    clauses.push("oc.commitment_type = ?");
+    params.push(filters.commitmentType);
+  }
+  if (filters?.contactId !== void 0) {
+    clauses.push(
+      "EXISTS (SELECT 1 FROM event_participants ep WHERE ep.event_id = oc.event_id AND ep.contact_id = ?)"
+    );
+    params.push(filters.contactId);
+  }
+  if (filters?.linkId !== void 0) {
+    clauses.push(
+      "EXISTS (SELECT 1 FROM link_event_effects le WHERE le.event_id = oc.event_id AND le.link_id = ?)"
+    );
+    params.push(filters.linkId);
+  }
+  if (filters?.horizonDays !== void 0) {
+    if (!Number.isInteger(filters.horizonDays) || filters.horizonDays < 0) {
+      throw new AffinityValidationError(
+        "horizonDays must be a non-negative integer"
+      );
+    }
+    const anchor = options?.since ?? now;
+    clauses.push("oc.due_at IS NOT NULL");
+    clauses.push("oc.due_at <= ?");
+    params.push(anchor + filters.horizonDays * DAY_MS);
+  }
+  const where = clauses.join(" AND ");
+  const rows = db.prepare(
+    `SELECT oc.event_id, oc.commitment_type, oc.due_at, oc.resolved_at, oc.resolution,
+              e.type, e.summary
+       FROM open_commitments oc
+       INNER JOIN events e ON e.id = oc.event_id
+       WHERE ${where}
+       ORDER BY oc.due_at IS NULL, oc.due_at ASC, oc.created_at ASC
+       LIMIT ? OFFSET ?`
+  ).all(...params, limit, offset);
+  const eventIds = rows.map((r) => r.event_id);
+  const partsByEvent = batchLoadEventParticipantViews(db, eventIds);
+  return rows.map((r) => ({
+    eventId: r.event_id,
+    type: r.type,
+    summary: r.summary,
+    participants: partsByEvent.get(r.event_id) ?? [],
+    dueAt: r.due_at,
+    dueAtIso: r.due_at === null ? null : new Date(r.due_at).toISOString(),
+    overdue: r.due_at !== null && r.due_at < now,
+    resolutionState: mapResolution(r.resolved_at, r.resolution)
+  }));
+}
+
 // src/dates/calendar.ts
 function utcStartOfDayMs(ms) {
   const date = new Date(ms);
@@ -1184,13 +1428,20 @@ function loadContactProfileRecord(db, contactId, topLinksLimit) {
   const topLinks = linkRows.map((l) => mapLinkRowToLinkListItem(l));
   const activeDates = loadActiveDatesForContact(db, contactId);
   const contactRollup = loadContactRollup(db, contactId);
+  const winner = row.merged_into_contact_id === null ? null : getContactRowById(db, row.merged_into_contact_id);
   return {
+    ...winner ? { mergedInto: { id: winner.id, name: winner.name } } : {},
     contact: mapContactRowToContactCore(row),
     identities,
     attributes,
     topLinks,
     activeDates,
-    warnings: contactRollup?.warnings ?? [],
+    warnings: [
+      ...contactRollup?.warnings ?? [],
+      ...winner ? [
+        `Contact #${row.id} was merged into #${winner.id} ${winner.name}; use contactId ${winner.id}`
+      ] : []
+    ],
     rollups: contactRollup?.rollup ?? null
   };
 }
@@ -1198,7 +1449,27 @@ function loadContactProfileRecord(db, contactId, topLinksLimit) {
 // src/contacts/get_contact_profile.ts
 function getContactProfile(db, contactId, options) {
   const t = options?.topLinksLimit ?? 8;
-  return loadContactProfileRecord(db, contactId, t);
+  const profile = loadContactProfileRecord(db, contactId, t);
+  if (!profile) return null;
+  const ties = db.prepare(`SELECT l.id, l.kind, l.role, c.id AS contactId, c.name
+    FROM links l JOIN contacts c ON c.id = CASE WHEN l.from_contact_id = ? THEN l.to_contact_id ELSE l.from_contact_id END
+    WHERE l.is_structural = 1 AND l.removed_at IS NULL AND (l.from_contact_id = ? OR l.to_contact_id = ?)
+    AND c.deleted_at IS NULL ORDER BY l.id`).all(contactId, contactId, contactId);
+  return {
+    ...profile,
+    recentEvents: getContactJournal(db, contactId, {
+      limit: options?.recentEventsLimit ?? 5
+    }).map((event) => ({
+      ...event,
+      occurredAtIso: new Date(event.occurredAt).toISOString()
+    })),
+    openCommitments: listOpenCommitments(
+      db,
+      { contactId },
+      options?.now === void 0 ? void 0 : { now: options.now }
+    ),
+    ties
+  };
 }
 
 // src/contacts/get_owner_profile.ts
@@ -1211,23 +1482,21 @@ function getOwnerProfile(db, options) {
   return loadContactProfileRecord(db, ownerId, t);
 }
 
-// src/lib/read/assert_default_ordering.ts
-function assertDefaultOrdering(readName, options) {
-  if (options?.sort !== void 0 || options?.descending !== void 0) {
-    throw new AffinityValidationError(
-      `${readName} does not support custom sort ordering`
-    );
+// src/contacts/contact_attribute_clauses.ts
+function contactAttributeClauses(filters) {
+  const clauses = [];
+  const params = [];
+  const attributes = filters?.attribute === void 0 ? [] : [filters.attribute].flat();
+  const tags = filters?.tag === void 0 ? [] : [filters.tag].flat();
+  for (const filter of [...attributes, ...tags.map((tag) => `tag:${tag}`)]) {
+    const separator = filter.indexOf("=");
+    const name = separator < 0 ? filter : filter.slice(0, separator);
+    clauses.push(`EXISTS (SELECT 1 FROM attributes a WHERE a.contact_id = contacts.id
+      AND a.deleted_at IS NULL AND lower(a.name) = lower(?)${separator < 0 ? "" : " AND lower(CAST(CASE WHEN json_valid(a.value) THEN json_extract(a.value, '$') ELSE a.value END AS TEXT)) = lower(?)"})`);
+    params.push(name);
+    if (separator >= 0) params.push(filter.slice(separator + 1));
   }
-}
-
-// src/lib/read/resolve_list_limit_offset.ts
-function resolveListLimitOffset(options) {
-  const limit = resolveAffinityListLimit(options?.limit);
-  const offset = options?.offset ?? 0;
-  if (!Number.isInteger(offset) || offset < 0) {
-    throw new AffinityValidationError("offset must be a non-negative integer");
-  }
-  return { limit, offset };
+  return { clauses, params };
 }
 
 // src/contacts/list_contacts.ts
@@ -1253,6 +1522,9 @@ function listContacts(db, filters, options) {
   if (filters?.includeDormant === false || options?.includeDormant === false) {
     clauses.push("lifecycle_state != 'dormant'");
   }
+  const attributeFilters = contactAttributeClauses(filters);
+  clauses.push(...attributeFilters.clauses);
+  params.push(...attributeFilters.params);
   const where = clauses.join(" AND ");
   const rows = db.prepare(
     `SELECT id, name, kind, lifecycle_state, is_owner, merged_into_contact_id,
@@ -1435,89 +1707,97 @@ function reviseContact(db, contactId, patch) {
   });
 }
 
-// src/contacts/search_contacts.ts
-function relevanceScore(name, queryLower, matchedName, matchedNormalizedIdentity) {
-  const nl = name.toLowerCase();
-  if (matchedNormalizedIdentity) return 1.1;
-  if (nl.startsWith(queryLower)) return 1;
-  if (matchedName) return 0.85;
-  return 0.7;
+// src/contacts/fold_search_text.ts
+function foldSearchText(value) {
+  let folded = value.toLowerCase();
+  if (/[^\u0020-\u007e]/.test(folded))
+    folded = folded.replace(/ß/g, "ss").normalize("NFKD").replace(new RegExp("\\p{M}", "gu"), "");
+  return folded.replace(/ae/g, "a").replace(/oe/g, "o").replace(/ue/g, "u");
 }
+
+// src/contacts/search_contacts.ts
 function searchContacts(db, query, filters, options) {
-  const q = query.trim();
-  if (q.length === 0) {
-    return [];
-  }
+  const q = foldSearchText(query.trim());
+  if (!q) return [];
   assertDefaultOrdering("searchContacts", options);
   const { limit, offset } = resolveListLimitOffset(options);
-  const queryLower = q.toLowerCase();
-  const pattern = `%${q.replace(/%/g, "").replace(/_/g, "")}%`;
-  const normalizedPattern = `%${queryLower}%`;
+  const fields = /* @__PURE__ */ new Map();
+  const rows = db.prepare(`
+    SELECT contact_id, value || ' ' || normalized_key AS text, 'identity:' || type AS source FROM identities WHERE removed_at IS NULL
+    UNION ALL SELECT contact_id, name || ' ' || COALESCE(value, ''), 'attribute:' || name FROM attributes WHERE deleted_at IS NULL AND contact_id IS NOT NULL
+    UNION ALL SELECT from_contact_id, COALESCE(role, '') || ' ' || COALESCE(bond, ''), 'link_role' FROM links WHERE removed_at IS NULL
+    UNION ALL SELECT to_contact_id, COALESCE(role, '') || ' ' || COALESCE(bond, ''), 'link_role' FROM links WHERE removed_at IS NULL
+    UNION ALL SELECT ep.contact_id, e.summary, 'event' FROM event_participants ep JOIN events e ON e.id = ep.event_id WHERE e.deleted_at IS NULL
+  `).all();
+  for (const row of rows) {
+    const values = fields.get(row.contact_id) ?? [];
+    values.push({ text: foldSearchText(row.text), source: row.source });
+    fields.set(row.contact_id, values);
+  }
+  const tokens = q.split(/\s+/);
+  const phone = /^[+\d()\-/.\s]+$/.test(q) && q.replace(/\D/g, "").length >= 3;
+  const digits = q.replace(/\D/g, "").replace(/^00/, "");
+  const attributeFilters = contactAttributeClauses(filters);
   const clauses = [
-    "c.deleted_at IS NULL",
-    "c.lifecycle_state != 'merged'"
+    "deleted_at IS NULL",
+    "lifecycle_state != 'merged'",
+    ...attributeFilters.clauses
   ];
-  const params = [];
+  const params = [...attributeFilters.params];
   if (filters?.kind !== void 0) {
-    clauses.push("c.kind = ?");
+    clauses.push("kind = ?");
     params.push(filters.kind);
   }
   if (filters?.lifecycleState !== void 0) {
-    clauses.push("c.lifecycle_state = ?");
+    clauses.push("lifecycle_state = ?");
     params.push(filters.lifecycleState);
   }
-  if (filters?.includeOwner === false) {
-    clauses.push("c.is_owner = 0");
-  }
-  if (filters?.includeDormant === false || options?.includeDormant === false) {
-    clauses.push("c.lifecycle_state != 'dormant'");
-  }
-  const where = clauses.join(" AND ");
-  const sql = `
-    SELECT c.id, c.name, c.kind, c.lifecycle_state, c.is_owner, c.merged_into_contact_id,
-           c.created_at, c.updated_at, c.deleted_at,
-           (
-             SELECT value
-             FROM identities primary_i
-             WHERE primary_i.contact_id = c.id AND primary_i.removed_at IS NULL
-             ORDER BY primary_i.id
-             LIMIT 1
-           ) AS primary_identity,
-           MAX(CASE WHEN i.normalized_key LIKE ? THEN 1 ELSE 0 END) AS matched_normalized_identity
-    FROM contacts c
-    LEFT JOIN identities i ON i.contact_id = c.id AND i.removed_at IS NULL
-    WHERE ${where}
-      AND (c.name LIKE ? OR i.value LIKE ? OR i.normalized_key LIKE ?)
-    GROUP BY c.id
-  `;
-  const rows = db.prepare(sql).all(
-    normalizedPattern,
-    ...params,
-    pattern,
-    pattern,
-    normalizedPattern
-  );
-  const scored = rows.map((r) => {
-    const item = mapContactRowToContactListItem(r);
-    const matchedName = r.name.toLowerCase().includes(queryLower);
-    const score = relevanceScore(
-      r.name,
-      queryLower,
-      matchedName,
-      Number(
-        r.matched_normalized_identity ?? 0
-      ) > 0
+  if (filters?.includeOwner === false) clauses.push("is_owner = 0");
+  const contacts = db.prepare(
+    `SELECT id, name, kind, lifecycle_state, is_owner, (SELECT value FROM identities i WHERE i.contact_id = contacts.id AND i.removed_at IS NULL ORDER BY i.id LIMIT 1) AS primary_identity FROM contacts WHERE ${clauses.join(" AND ")}`
+  ).all(...params).map((row) => ({
+    ...mapContactRowToContactListItem(row),
+    primaryIdentity: row.primary_identity
+  }));
+  const scored = [];
+  for (const contact of contacts) {
+    if (contact.lifecycleState === "dormant" && !(filters?.includeDormant ?? options?.includeDormant))
+      continue;
+    if (contact.lifecycleState === "lost" && !filters?.includeLost) continue;
+    const name = foldSearchText(contact.name);
+    const values = [
+      { text: name, source: "name" },
+      ...(fields.get(contact.id) ?? []).filter(
+        (field) => !contact.isOwner || field.source !== "event" && field.source !== "link_role"
+      )
+    ];
+    const phoneFields = phone ? values.filter(
+      (field) => field.source === "identity:phone" && field.text.split(" ").join("").replace(/[^\d]/g, "").replace(/^00/, "").includes(digits)
+    ) : [];
+    if (!phoneFields.length && !tokens.every(
+      (token) => values.some((field) => field.text.includes(token))
+    ))
+      continue;
+    const matchedOn = [
+      ...new Set(
+        [
+          ...values.filter(
+            (field) => tokens.some((token) => field.text.includes(token))
+          ),
+          ...phoneFields
+        ].map((field) => field.source)
+      )
+    ];
+    const identities = values.filter(
+      (field) => field.source.startsWith("identity:")
     );
-    return {
-      item: {
-        ...item,
-        primaryIdentity: r.primary_identity ?? null
-      },
-      score
-    };
-  });
-  scored.sort((a, b) => b.score - a.score);
-  return scored.slice(offset, offset + limit).map((s) => s.item);
+    const score = name === q ? 5 : name.startsWith(q) || tokens.every((token) => name.includes(token)) ? 4 : phoneFields.length || identities.some((field) => field.text.split(" ").includes(q)) ? 3 : identities.some(
+      (field) => tokens.every((token) => field.text.includes(token))
+    ) ? 2 : 1;
+    scored.push({ item: { ...contact, matchedOn }, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.item.id - b.item.id);
+  return scored.slice(offset, offset + limit).map(({ item }) => item);
 }
 
 // src/contacts/validators.ts
@@ -1526,7 +1806,9 @@ function assertValidLifecycleTransition(from, to) {
     throw new AffinityStateError("merged contact is read-only");
   }
   if (to === "merged") {
-    throw new AffinityInvariantError("use mergeContacts to reach merged state");
+    throw new AffinityInvariantError(
+      "use manage_contact merge (CLI: contact merge) to reach merged state"
+    );
   }
   if (from === to) {
     return;
@@ -1577,101 +1859,6 @@ function setContactLifecycle(db, contactId, lifecycleState, options) {
   });
 }
 
-// src/events/loaders.ts
-function loadEventParticipantViews(db, eventId) {
-  const rows = db.prepare(
-    `SELECT contact_id, role, directionality
-       FROM event_participants
-       WHERE event_id = ?`
-  ).all(eventId);
-  return rows.map((row) => ({
-    contactId: row.contact_id,
-    role: row.role,
-    ...row.directionality === null ? {} : { directionality: row.directionality }
-  }));
-}
-function loadEventRecord(db, eventId) {
-  const row = getEventRowById(db, eventId);
-  if (!row) {
-    throw new AffinityInvariantError("event not found");
-  }
-  const participants = loadEventParticipantViews(db, eventId);
-  return mapEventRowToEventRecord(row, participants);
-}
-function batchLoadEventRecords(db, eventIds) {
-  if (eventIds.length === 0) {
-    return [];
-  }
-  const ph = eventIds.map(() => "?").join(", ");
-  const eventRows = db.prepare(
-    `SELECT id, type, occurred_at, summary, significance, moment_kind,
-              recurrence_kind, anchor_month, anchor_day,
-              anchor_contact_id, anchor_link_id,
-              created_at, updated_at, deleted_at
-       FROM events WHERE id IN (${ph}) AND deleted_at IS NULL`
-  ).all(...eventIds);
-  const partRows = db.prepare(
-    `SELECT event_id, contact_id, role, directionality
-       FROM event_participants WHERE event_id IN (${ph})`
-  ).all(...eventIds);
-  const partsByEvent = /* @__PURE__ */ new Map();
-  for (const p of partRows) {
-    let arr = partsByEvent.get(p.event_id);
-    if (!arr) {
-      arr = [];
-      partsByEvent.set(p.event_id, arr);
-    }
-    arr.push({
-      contactId: p.contact_id,
-      role: p.role,
-      ...p.directionality === null ? {} : { directionality: p.directionality }
-    });
-  }
-  const rowById = new Map(eventRows.map((r) => [r.id, r]));
-  const out = [];
-  for (const id of eventIds) {
-    const row = rowById.get(id);
-    if (row) {
-      out.push(mapEventRowToEventRecord(row, partsByEvent.get(id) ?? []));
-    }
-  }
-  return out;
-}
-function batchLoadEventParticipantViews(db, eventIds) {
-  const result = /* @__PURE__ */ new Map();
-  if (eventIds.length === 0) {
-    return result;
-  }
-  const ph = eventIds.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT event_id, contact_id, role, directionality
-       FROM event_participants WHERE event_id IN (${ph})`
-  ).all(...eventIds);
-  for (const row of rows) {
-    let arr = result.get(row.event_id);
-    if (!arr) {
-      arr = [];
-      result.set(row.event_id, arr);
-    }
-    arr.push({
-      contactId: row.contact_id,
-      role: row.role,
-      ...row.directionality === null ? {} : { directionality: row.directionality }
-    });
-  }
-  return result;
-}
-function requireDateAnchorEvent(db, eventId) {
-  const row = getEventRowById(db, eventId);
-  if (!row) {
-    throw new AffinityNotFoundError("event not found");
-  }
-  if (row.type !== "date_anchor") {
-    throw new AffinityInvariantError("not a date anchor");
-  }
-  return row;
-}
-
 // src/events/persistence.ts
 function insertJournalEvent(db, params) {
   const now = resolveNow(params.now);
@@ -2535,7 +2722,7 @@ function getLinkTimeline(db, linkId, options) {
 }
 
 // src/links/rollups.ts
-var DAY_MS = 864e5;
+var DAY_MS2 = 864e5;
 function parseJsonObject2(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -2593,7 +2780,7 @@ function recencyScore(occurredAt, cadenceDays, now) {
     return 0;
   }
   const cadence = Math.max(cadenceDays ?? 0, 1);
-  const daysSince = Math.max(0, (now - occurredAt) / DAY_MS);
+  const daysSince = Math.max(0, (now - occurredAt) / DAY_MS2);
   return Math.max(0, 1 - daysSince / cadence);
 }
 function refreshLinkRollup(db, linkId, now) {
@@ -2604,15 +2791,15 @@ function refreshLinkRollup(db, linkId, now) {
   const latest = db.prepare(
     `SELECT event_id, occurred_at
        FROM link_event_effects
-       WHERE link_id = ?
+       WHERE link_id = ? AND counts_for_recency = 1
        ORDER BY occurred_at DESC, event_id DESC
        LIMIT 1`
   ).get(linkId);
-  const trailingWindowStart = now - 180 * DAY_MS;
+  const trailingWindowStart = now - 180 * DAY_MS2;
   const counts = db.prepare(
     `SELECT
          COUNT(*) AS total_meaningful_events,
-         SUM(CASE WHEN affinity_delta > 0 OR trust_delta > 0 THEN 1 ELSE 0 END) AS positive_meaningful_events
+         SUM(CASE WHEN counts_for_recency = 1 AND (affinity_delta > 0 OR trust_delta > 0) THEN 1 ELSE 0 END) AS positive_meaningful_events
        FROM link_event_effects
        WHERE link_id = ? AND occurred_at >= ?`
   ).get(linkId, trailingWindowStart);
@@ -2620,7 +2807,7 @@ function refreshLinkRollup(db, linkId, now) {
     `SELECT ep.directionality
        FROM link_event_effects le
        INNER JOIN event_participants ep ON ep.event_id = le.event_id
-       WHERE le.link_id = ? AND ep.contact_id = ?
+       WHERE le.link_id = ? AND le.counts_for_recency = 1 AND ep.contact_id = ?
          AND ep.directionality IS NOT NULL
          AND le.occurred_at >= ?`
   ).all(linkId, link.from_contact_id, trailingWindowStart);
@@ -2646,7 +2833,7 @@ function refreshLinkRollup(db, linkId, now) {
     link.cadence_days,
     now
   );
-  const daysSinceLastMeaningfulEvent = latest === void 0 ? 0 : Math.max(0, (now - latest.occurred_at) / DAY_MS);
+  const daysSinceLastMeaningfulEvent = latest === void 0 ? 0 : Math.max(0, (now - latest.occurred_at) / DAY_MS2);
   const driftPriorityValue = driftPriority({
     daysSinceLastMeaningfulEvent,
     cadenceDays: link.cadence_days ?? 1,
@@ -2963,13 +3150,15 @@ function listRadar(db, filters, options) {
   if (ownerId === null) {
     return [];
   }
+  const now = resolveNow(options?.now);
+  const overdue = `EXISTS (SELECT 1 FROM open_commitments oc JOIN events e ON e.id = oc.event_id JOIN event_participants ep ON ep.event_id = e.id WHERE ep.contact_id = CASE WHEN l.from_contact_id = ${ownerId} THEN l.to_contact_id ELSE l.from_contact_id END AND e.deleted_at IS NULL AND oc.resolved_at IS NULL AND oc.due_at < ${now})`;
   const { limit, offset } = resolveListLimitOffset(options);
   const clauses = [
     "l.removed_at IS NULL",
     "l.is_structural = 0",
-    "l.from_contact_id = ?"
+    "(l.from_contact_id = ? OR l.to_contact_id = ?)"
   ];
-  const params = [ownerId];
+  const params = [ownerId, ownerId];
   if (filters?.kind !== void 0) {
     clauses.push("l.kind = ?");
     params.push(filters.kind);
@@ -2991,6 +3180,7 @@ function listRadar(db, filters, options) {
   const rows = db.prepare(
     `SELECT
          l.id,
+         ${overdue} AS overdue_commitment,
          l.from_contact_id,
          l.to_contact_id,
          l.trust,
@@ -2999,17 +3189,18 @@ function listRadar(db, filters, options) {
          lr.recency_score,
          lr.normalized_rank
        FROM links l
-       INNER JOIN contacts c_to ON c_to.id = l.to_contact_id
+       INNER JOIN contacts c_to ON c_to.id = CASE WHEN l.from_contact_id = ${ownerId} THEN l.to_contact_id ELSE l.from_contact_id END
          AND c_to.deleted_at IS NULL AND c_to.lifecycle_state != 'merged'
        LEFT JOIN link_rollups lr ON lr.link_id = l.id
        WHERE ${where}
-       ORDER BY COALESCE(lr.radar_score, 0) DESC
+       ORDER BY ${overdue} DESC, COALESCE(lr.radar_score, 0) DESC
        LIMIT ? OFFSET ?`
   ).all(...params, limit, offset);
   return rows.map((row) => ({
     linkId: row.id,
     contactId: row.from_contact_id === ownerId ? row.to_contact_id : row.from_contact_id,
-    driftPriority: row.drift_priority ?? 0,
+    reasons: row.overdue_commitment ? ["overdue_commitment"] : [],
+    driftPriority: row.overdue_commitment ? Math.max(1, row.drift_priority ?? 0) : row.drift_priority ?? 0,
     recencyScore: row.recency_score ?? 0,
     normalizedRank: row.normalized_rank ?? 0,
     trust: row.trust ?? 0,
@@ -3620,39 +3811,6 @@ function listDismissedDuplicates(db, options) {
   }));
 }
 
-// src/events/get_contact_journal.ts
-function getContactJournal(db, contactId, options) {
-  assertDefaultOrdering("getContactJournal", options);
-  const { limit, offset } = resolveListLimitOffset(options);
-  const clauses = ["e.deleted_at IS NULL", "ep.contact_id = ?"];
-  const params = [contactId];
-  if (options?.since !== void 0) {
-    clauses.push("e.occurred_at >= ?");
-    params.push(options.since);
-  }
-  if (options?.until !== void 0) {
-    clauses.push("e.occurred_at <= ?");
-    params.push(options.until);
-  }
-  if (options?.eventTypes !== void 0 && options.eventTypes.length > 0) {
-    const ph = options.eventTypes.map(() => "?").join(", ");
-    clauses.push(`e.type IN (${ph})`);
-    params.push(...options.eventTypes);
-  }
-  const where = clauses.join(" AND ");
-  const rows = db.prepare(
-    `SELECT e.id FROM events e
-       INNER JOIN event_participants ep ON ep.event_id = e.id
-       WHERE ${where}
-       ORDER BY e.occurred_at DESC, e.id DESC
-       LIMIT ? OFFSET ?`
-  ).all(...params, limit, offset);
-  return batchLoadEventRecords(
-    db,
-    rows.map((r) => r.id)
-  );
-}
-
 // src/events/mechanics.ts
 function clamp2(value, min, max) {
   return Math.min(max, Math.max(min, value));
@@ -3877,86 +4035,10 @@ function massPenalty(weeklyPositiveBaseWeight2) {
   return 1 / (1 + excessWeeklyMass / 8);
 }
 function dateSalienceBonus(significance) {
-  return 1 + Math.min(0.25, significance / 40);
-}
-function repairBonus(consecutiveRepairEvents) {
-  return Math.min(0.12, consecutiveRepairEvents * 0.02);
-}
-
-// src/events/list_open_commitments.ts
-var DAY_MS2 = 864e5;
-function mapResolution(resolvedAt, resolution) {
-  if (resolvedAt === null) {
-    return "open";
-  }
-  if (resolution === "cancelled") {
-    return "cancelled";
-  }
-  return "resolved";
-}
-function listOpenCommitments(db, filters, options) {
-  assertDefaultOrdering("listOpenCommitments", options);
-  const { limit, offset } = resolveListLimitOffset(options);
-  const clauses = ["e.deleted_at IS NULL", "oc.resolved_at IS NULL"];
-  const params = [];
-  if (options?.since !== void 0) {
-    clauses.push("e.occurred_at >= ?");
-    params.push(options.since);
-  }
-  if (options?.until !== void 0) {
-    clauses.push("e.occurred_at <= ?");
-    params.push(options.until);
-  }
-  if (filters?.commitmentType !== void 0) {
-    if (filters.commitmentType !== "promise" && filters.commitmentType !== "agreement") {
-      throw new AffinityValidationError("invalid commitmentType filter");
-    }
-    clauses.push("oc.commitment_type = ?");
-    params.push(filters.commitmentType);
-  }
-  if (filters?.contactId !== void 0) {
-    clauses.push(
-      "EXISTS (SELECT 1 FROM event_participants ep WHERE ep.event_id = oc.event_id AND ep.contact_id = ?)"
-    );
-    params.push(filters.contactId);
-  }
-  if (filters?.linkId !== void 0) {
-    clauses.push(
-      "EXISTS (SELECT 1 FROM link_event_effects le WHERE le.event_id = oc.event_id AND le.link_id = ?)"
-    );
-    params.push(filters.linkId);
-  }
-  if (filters?.horizonDays !== void 0) {
-    if (!Number.isInteger(filters.horizonDays) || filters.horizonDays < 0) {
-      throw new AffinityValidationError(
-        "horizonDays must be a non-negative integer"
-      );
-    }
-    const anchor = options?.since ?? Date.now();
-    clauses.push("oc.due_at IS NOT NULL");
-    clauses.push("oc.due_at <= ?");
-    params.push(anchor + filters.horizonDays * DAY_MS2);
-  }
-  const where = clauses.join(" AND ");
-  const rows = db.prepare(
-    `SELECT oc.event_id, oc.commitment_type, oc.due_at, oc.resolved_at, oc.resolution,
-              e.type, e.summary
-       FROM open_commitments oc
-       INNER JOIN events e ON e.id = oc.event_id
-       WHERE ${where}
-       ORDER BY oc.due_at IS NULL, oc.due_at ASC, oc.created_at ASC
-       LIMIT ? OFFSET ?`
-  ).all(...params, limit, offset);
-  const eventIds = rows.map((r) => r.event_id);
-  const partsByEvent = batchLoadEventParticipantViews(db, eventIds);
-  return rows.map((r) => ({
-    eventId: r.event_id,
-    type: r.type,
-    summary: r.summary,
-    participants: partsByEvent.get(r.event_id) ?? [],
-    dueAt: r.due_at,
-    resolutionState: mapResolution(r.resolved_at, r.resolution)
-  }));
+  return 1 + Math.min(0.25, significance / 40);
+}
+function repairBonus(consecutiveRepairEvents) {
+  return Math.min(0.12, consecutiveRepairEvents * 0.02);
 }
 
 // src/links/effects.ts
@@ -4236,7 +4318,7 @@ function applyEventEffectToLink(db, params) {
     1,
     Math.round((params.occurredAt - latest.occurred_at) / DAY_MS3)
   );
-  const cadenceAfter = nextCadenceDays({
+  const cadenceAfter = commitmentResolution === "broken" || commitmentResolution === "cancelled" ? cadenceBefore : nextCadenceDays({
     kind: linkKind,
     currentCadenceDays: cadenceBefore,
     gapDays
@@ -4299,6 +4381,11 @@ function applyEventEffectToLink(db, params) {
     params.now,
     params.now
   );
+  if (commitmentResolution === "broken" || commitmentResolution === "cancelled") {
+    db.prepare(
+      "UPDATE link_event_effects SET counts_for_recency = 0 WHERE event_id = ? AND link_id = ?"
+    ).run(params.eventId, params.linkId);
+  }
   refreshLinkRollup(db, params.linkId, params.now);
   return {
     linkId: params.linkId,
@@ -4678,12 +4765,16 @@ function resolveCommitment(db, commitmentEventId, resolution, options) {
     if (row.type !== "promise" && row.type !== "agreement") {
       throw new AffinityInvariantError("not a commitment event");
     }
-    const open = db.prepare("SELECT resolved_at FROM open_commitments WHERE event_id = ?").get(commitmentEventId);
+    const open = db.prepare(
+      "SELECT resolved_at, resolution FROM open_commitments WHERE event_id = ?"
+    ).get(commitmentEventId);
     if (!open) {
       throw new AffinityNotFoundError("open commitment not found");
     }
     if (open.resolved_at !== null) {
-      throw new AffinityStateError("commitment already resolved");
+      throw new AffinityConflictError(
+        `Commitment #${commitmentEventId} is already resolved (${open.resolution})`
+      );
     }
     const now = resolveNow(options?.now);
     const originalParticipants = loadEventParticipantViews(
@@ -4696,7 +4787,9 @@ function resolveCommitment(db, commitmentEventId, resolution, options) {
          WHERE event_id = ? AND resolved_at IS NULL`
     ).run(resolution, now, now, commitmentEventId);
     if (Number(result.changes ?? 0) === 0) {
-      throw new AffinityStateError("commitment already resolved");
+      throw new AffinityConflictError(
+        `Commitment #${commitmentEventId} is already resolved (${open.resolution})`
+      );
     }
     const shouldCreateResolvingEvent = options?.resolvingEvent !== void 0 || resolution === "broken";
     const created = [];
@@ -4759,6 +4852,82 @@ function resolveCommitment(db, commitmentEventId, resolution, options) {
   });
 }
 
+// src/contacts/export_contact.ts
+function exportContact(db, id) {
+  const query = (sql, ...params) => db.prepare(sql).all(...params).map((row) => {
+    const result = {};
+    for (const [key, value] of Object.entries(row)) {
+      const name = key.replace(
+        /_([a-z])/g,
+        (_, letter) => letter.toUpperCase()
+      );
+      result[name] = value;
+      if ((name.endsWith("At") || name === "dueAt") && typeof value === "number")
+        result[`${name}Iso`] = new Date(value).toISOString();
+      if (key.endsWith("_json") && typeof value === "string")
+        result[name] = JSON.parse(value);
+    }
+    return result;
+  });
+  const contact = query("SELECT * FROM contacts WHERE id = ?", id)[0];
+  if (!contact) throw new AffinityNotFoundError("contact not found");
+  const events = query(
+    "SELECT DISTINCT e.* FROM events e JOIN event_participants p ON p.event_id = e.id WHERE p.contact_id = ? ORDER BY e.id",
+    id
+  ).map((event) => ({
+    ...event,
+    participants: query(
+      "SELECT p.*, c.name AS contact_name FROM event_participants p JOIN contacts c ON c.id = p.contact_id WHERE event_id = ? ORDER BY p.contact_id",
+      event.id
+    )
+  }));
+  return {
+    contact,
+    identities: query(
+      "SELECT * FROM identities WHERE contact_id = ? ORDER BY id",
+      id
+    ),
+    attributes: query(
+      "SELECT * FROM attributes WHERE contact_id = ? OR link_id IN (SELECT id FROM links WHERE from_contact_id = ? OR to_contact_id = ?) ORDER BY id",
+      id,
+      id,
+      id
+    ),
+    links: query(
+      "SELECT l.*, f.name AS from_contact_name, t.name AS to_contact_name FROM links l JOIN contacts f ON f.id = l.from_contact_id JOIN contacts t ON t.id = l.to_contact_id WHERE from_contact_id = ? OR to_contact_id = ? ORDER BY l.id",
+      id,
+      id
+    ),
+    events,
+    commitments: query(
+      "SELECT o.* FROM open_commitments o JOIN event_participants p ON p.event_id = o.event_id WHERE p.contact_id = ? ORDER BY o.event_id",
+      id
+    ),
+    dates: query(
+      "SELECT * FROM events WHERE anchor_contact_id = ? OR anchor_link_id IN (SELECT id FROM links WHERE from_contact_id = ? OR to_contact_id = ?) ORDER BY id",
+      id,
+      id,
+      id
+    ),
+    mergeHistory: query(
+      "SELECT * FROM contact_merges WHERE winner_contact_id = ? OR loser_contact_id = ? ORDER BY id",
+      id,
+      id
+    )
+  };
+}
+
+// src/contacts/export_affinity.ts
+function exportAffinity(db) {
+  const now = Date.now();
+  return {
+    version: 1,
+    exportedAt: now,
+    exportedAtIso: new Date(now).toISOString(),
+    contacts: db.prepare("SELECT id FROM contacts ORDER BY id").all().map((row) => exportContact(db, row.id))
+  };
+}
+
 // src/soul.ts
 var soul_exports = {};
 __export(soul_exports, {
@@ -5526,6 +5695,7 @@ __export(tools_exports, {
   numberSchema: () => numberSchema,
   objectSchema: () => objectSchema,
   oneOfSchema: () => oneOfSchema,
+  parseTimeInput: () => parseTimeInput,
   recordEventTool: () => recordEventTool,
   recordEventToolHandler: () => recordEventToolHandler,
   recordEventToolName: () => recordEventToolName,
@@ -5559,8 +5729,55 @@ __export(tools_exports, {
   withToolHandling: () => withToolHandling
 });
 
+// src/tools/parse_time_input.ts
+var timeInputForms = "epoch milliseconds integer, ISO 8601 date-time with Z/offset, YYYY-MM-DD, today, tomorrow, yesterday, +3d or -2d";
+function parseTimeInput(value, field = "time", now = Date.now()) {
+  const fail = () => {
+    throw new AffinityValidationError(`${field}: expected ${timeInputForms}`);
+  };
+  if (typeof value === "number")
+    return Number.isSafeInteger(value) && Number.isFinite(new Date(value).getTime()) ? value : fail();
+  if (typeof value !== "string") return fail();
+  const text = value.trim();
+  const relative = /^(?:today|tomorrow|yesterday|[+-]\d+d)$/.test(text);
+  let day;
+  if (relative) {
+    const offset = text === "today" ? 0 : text === "tomorrow" ? 1 : text === "yesterday" ? -1 : Number(text.slice(0, -1));
+    day = Math.floor(now / 864e5) * 864e5 + offset * 864e5;
+  } else if (/^\d{4}-\d{2}-\d{2}$/.test(text)) {
+    day = Date.parse(`${text}T00:00:00.000Z`);
+    if (!Number.isFinite(day) || new Date(day).toISOString().slice(0, 10) !== text)
+      return fail();
+  } else {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      text
+    ))
+      return fail();
+    const calendar = Date.parse(`${text.slice(0, 10)}T00:00:00Z`);
+    if (!Number.isFinite(calendar) || new Date(calendar).toISOString().slice(0, 10) !== text.slice(0, 10))
+      return fail();
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? parsed : fail();
+  }
+  const result = day + (field.split(".").at(-1) === "dueAt" ? 86399999 : 0);
+  return Number.isSafeInteger(result) && Number.isFinite(new Date(result).getTime()) ? result : fail();
+}
+
 // src/tools/tool_metadata.ts
 function defineAffinityTool(definition) {
+  const visit = (schema) => {
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if ((key.endsWith("At") || ["now", "asOf", "since", "until"].includes(key)) && child.type === "integer") {
+        child.type = void 0;
+        child.oneOf = [{ type: "integer" }, { type: "string" }];
+        child.description = `${child.description ?? "Time."} Accepts ${timeInputForms}. UTC midnight for dates; dueAt uses UTC end of day.`;
+      }
+      visit(child);
+    }
+    if (schema.items) visit(schema.items);
+    for (const child of schema.oneOf ?? schema.anyOf ?? []) visit(child);
+  };
+  visit(definition.inputSchema);
   return definition;
 }
 function stringSchema(description, options = {}) {
@@ -5659,6 +5876,7 @@ function toContactEntityRef(value) {
 function toContactListToolItem(value) {
   return {
     ...toContactEntityRef(value),
+    ..."matchedOn" in value ? { matchedOn: value.matchedOn } : {},
     subtitle: "kind" in value ? value.kind : void 0
   };
 }
@@ -5705,7 +5923,9 @@ function toEventEntityRef(value) {
 }
 function toEventListToolItem(value) {
   return {
+    ...value,
     ...toEventEntityRef(value),
+    occurredAtIso: new Date(value.occurredAt).toISOString(),
     snippet: `${value.participants.length} participant(s)`
   };
 }
@@ -5762,7 +5982,7 @@ function withOptionalFields(result, options) {
   if (options.warnings && options.warnings.length > 0) {
     result.warnings = options.warnings;
   }
-  return result;
+  return roundToolValues(result);
 }
 function toolWarning(code, message) {
   return { code, message };
@@ -5826,9 +6046,31 @@ function toolFailure(kind, code, summary, message, options = {}) {
     options
   );
 }
+function roundToolValues(value) {
+  if (typeof value === "number")
+    return Number.isInteger(value) ? value : Math.round(value * 1e3) / 1e3;
+  if (Array.isArray(value)) return value.map(roundToolValues);
+  if (value !== null && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [
+        key,
+        roundToolValues(child)
+      ])
+    );
+  return value;
+}
 
 // src/tools/tool_resolvers.ts
-function resolveContactLocator(db, locator, field = "contact") {
+function resolveContactLocator(db, locator, field = "contact", allowMerged = false) {
+  if (!locator || typeof locator !== "object")
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field} locator.`,
+        [field]
+      )
+    };
   if ("contactId" in locator) {
     const row2 = getContactRowById(db, locator.contactId);
     if (!row2) {
@@ -5842,8 +6084,25 @@ function resolveContactLocator(db, locator, field = "contact") {
         )
       };
     }
+    if (!allowMerged && row2.merged_into_contact_id !== null) {
+      const winner = getContactRowById(db, row2.merged_into_contact_id);
+      const message = `Contact #${row2.id} was merged into #${row2.merged_into_contact_id} ${winner?.name ?? ""}; use contactId ${row2.merged_into_contact_id}`;
+      return {
+        ok: false,
+        result: toolFailure("domain", "invalid_state", message, message)
+      };
+    }
     return { ok: true, value: row2 };
   }
+  if (!("identity" in locator) || !locator.identity)
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field}.contactId or identity.`,
+        [field]
+      )
+    };
   const normalizedKey = normalizeIdentityKey(
     locator.identity.type,
     locator.identity.value
@@ -5901,6 +6160,15 @@ function resolveContactLocator(db, locator, field = "contact") {
   return { ok: true, value: matchedContact };
 }
 function resolveLinkLocator(db, locator, field = "link") {
+  if (!locator || typeof locator !== "object")
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field} locator.`,
+        [field]
+      )
+    };
   if ("linkId" in locator) {
     const row = getLinkRowById(db, locator.linkId);
     if (!row) {
@@ -5916,6 +6184,15 @@ function resolveLinkLocator(db, locator, field = "link") {
     }
     return { ok: true, value: row };
   }
+  if (!("endpoints" in locator) || !locator.endpoints)
+    return {
+      ok: false,
+      result: toolNeedsClarification(
+        "missing_required_choice",
+        `Provide ${field}.linkId or endpoints.`,
+        [field]
+      )
+    };
   const { endpoints } = locator;
   const clauses = [
     "removed_at IS NULL",
@@ -6034,6 +6311,92 @@ function affinityErrorCodeToToolCode(error) {
   }
 }
 
+// src/tools/validate_tool_input.ts
+function validateToolInput(schema, value, path = "input", injectedNow = Date.now()) {
+  if (schema.anyOf || schema.oneOf) {
+    const choices = schema.anyOf ?? schema.oneOf ?? [];
+    return choices.some(
+      (choice) => validateToolInput(choice, value, path, injectedNow) === null
+    ) ? null : `${path}: invalid value`;
+  }
+  if (schema.type === "object") {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+      return `${path}: missing input or expected object`;
+    const object = value;
+    if (path.endsWith(".patch") && schema.additionalProperties === false) {
+      for (const key of Object.keys(object)) {
+        if (!Object.hasOwn(schema.properties ?? {}, key))
+          return key === "kind" && "name" in (schema.properties ?? {}) ? "kind cannot be changed after creation" : `${path}.${key}: unknown patch key; allowed keys: ${Object.keys(schema.properties ?? {}).join(", ")}`;
+      }
+    }
+    if (object.action === "revise" && schema.properties?.patch && object.patch === void 0)
+      return `${path}.patch: missing required field`;
+    if (object.patch !== void 0 && !schema.properties?.patch)
+      return `${path}.patch: unknown patch key; allowed keys: none (use the action's named fields)`;
+    const referenceNow = object.now === void 0 ? injectedNow : (() => {
+      try {
+        return parseTimeInput(
+          object.now,
+          `${path}.now`,
+          injectedNow
+        );
+      } catch {
+        return Date.now();
+      }
+    })();
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (object[key] !== void 0 && (key.endsWith("At") || ["now", "asOf", "since", "until"].includes(key)) && child.oneOf?.some((choice) => choice.type === "integer")) {
+        try {
+          object[key] = parseTimeInput(
+            object[key],
+            `${path}.${key}`,
+            referenceNow
+          );
+        } catch (error) {
+          return error.message;
+        }
+      }
+    }
+    for (const key of schema.required ?? []) {
+      if (object[key] === void 0)
+        return `${path}.${key}: missing required field`;
+    }
+    for (const [key, child] of Object.entries(schema.properties ?? {})) {
+      if (object[key] === void 0) continue;
+      const error = validateToolInput(
+        child,
+        object[key],
+        `${path}.${key}`,
+        referenceNow
+      );
+      if (error) return error;
+    }
+    return null;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) return `${path}: expected array`;
+    for (const [index, item] of value.entries()) {
+      const error = validateToolInput(
+        schema.items ?? {},
+        item,
+        `${path}[${index}]`,
+        injectedNow
+      );
+      if (error) return error;
+    }
+    return null;
+  }
+  if (schema.enum && !schema.enum.includes(value))
+    return `${path}: expected ${schema.enum.join(", ")}`;
+  if (schema.type === "null")
+    return value === null ? null : `${path}: expected null`;
+  if (schema.type === "integer")
+    return Number.isInteger(value) ? null : `${path}: expected integer`;
+  const valid = schema.type === void 0 || schema.type === "string" && typeof value === "string" || schema.type === "number" && typeof value === "number" && Number.isFinite(value) || schema.type === "boolean" && typeof value === "boolean";
+  if (!valid) return `${path}: expected ${schema.type}`;
+  return null;
+}
+
 // src/tools/inspect_affinity_item_tool.ts
 function contactLocatorSchema(description) {
   return {
@@ -6069,7 +6432,19 @@ function linkLocatorSchema(description) {
     description
   };
 }
-function inspectAffinityItemToolHandler(db, input) {
+function inspectAffinityItemToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    inspectAffinityItemTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     if (input.kind === "owner_profile") {
       const detail2 = getOwnerProfile(
@@ -6087,19 +6462,21 @@ function inspectAffinityItemToolHandler(db, input) {
       return toolSuccess(
         `Loaded owner profile for ${detail2.contact.name}.`,
         { kind: input.kind, detail: detail2 },
-        { entities: [toContactEntityRef(detail2.contact)] }
+        {
+          entities: [toContactEntityRef(detail2.contact)],
+          warnings: detail2.mergedInto ? [{ code: "partial_match", message: detail2.warnings.join("; ") }] : void 0
+        }
       );
     }
     if (input.kind === "contact_profile") {
-      const contact = resolveContactLocator(db, input.contact, "contact");
+      const contact = resolveContactLocator(db, input.contact, "contact", true);
       if (!contact.ok) {
         return contact.result;
       }
-      const detail2 = getContactProfile(
-        db,
-        contact.value.id,
-        input.topLinksLimit === void 0 ? void 0 : { topLinksLimit: input.topLinksLimit }
-      );
+      const detail2 = getContactProfile(db, contact.value.id, {
+        ...input.topLinksLimit === void 0 ? {} : { topLinksLimit: input.topLinksLimit },
+        ...input.recentEventsLimit === void 0 ? {} : { recentEventsLimit: input.recentEventsLimit }
+      });
       if (!detail2) {
         return toolFailure(
           "domain",
@@ -6111,7 +6488,10 @@ function inspectAffinityItemToolHandler(db, input) {
       return toolSuccess(
         `Loaded contact profile for ${detail2.contact.name}.`,
         { kind: input.kind, detail: detail2 },
-        { entities: [toContactEntityRef(detail2.contact)] }
+        {
+          entities: [toContactEntityRef(detail2.contact)],
+          warnings: detail2.mergedInto ? [{ code: "partial_match", message: detail2.warnings.join("; ") }] : void 0
+        }
       );
     }
     const link = resolveLinkLocator(db, input.link, "link");
@@ -6451,21 +6831,18 @@ function unsetAttribute(db, target, name, removedAt) {
   });
 }
 
-// src/tools/tool_summary.ts
-function summarizeCount(count, singular) {
-  if (count === 0) {
-    return `No ${singular}s found.`;
-  }
-  if (count === 1) {
-    return `Found 1 ${singular}.`;
-  }
-  return `Found ${count} ${singular}s.`;
-}
-
 // src/tools/tool_mutation.ts
-function mutationToolResult(action, receipt, entitySummary) {
+function mutationToolResult(action, receipt, entitySummary, fields) {
   const changedCount = receipt.created.length + receipt.updated.length + receipt.archived.length + receipt.removed.length;
   const data = {
+    changes: ["created", "updated", "archived", "removed"].flatMap(
+      (verb) => receipt[verb].map((ref) => ({
+        entity: ref.kind,
+        id: ref.id,
+        action: verb,
+        ...verb === "updated" && fields ? { fields } : {}
+      }))
+    ),
     action,
     primary: receipt.primary,
     created: receipt.created,
@@ -6475,7 +6852,7 @@ function mutationToolResult(action, receipt, entitySummary) {
     affectedLinks: receipt.affectedLinks,
     derivedEffects: receipt.derivedEffects
   };
-  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : summarizeCount(changedCount, `${entitySummary} change`);
+  const summary = changedCount === 0 ? `No ${entitySummary} changes were needed.` : describeChanges(receipt);
   if (changedCount === 0) {
     return toolNoOp(summary, data, {
       entities: toReceiptEntityRefs(receipt)
@@ -6485,6 +6862,23 @@ function mutationToolResult(action, receipt, entitySummary) {
     entities: toReceiptEntityRefs(receipt)
   });
 }
+var PLURALS = { identity: "identities" };
+function describeChanges(receipt) {
+  const parts = [];
+  for (const verb of ["created", "updated", "archived", "removed"]) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const ref of receipt[verb]) {
+      counts.set(ref.kind, (counts.get(ref.kind) ?? 0) + 1);
+    }
+    if (counts.size === 0) continue;
+    const items = [...counts].map(
+      ([kind, n]) => `${n} ${n === 1 ? kind : PLURALS[kind] ?? `${kind}s`}`
+    );
+    parts.push(`${verb} ${items.join(", ")}`);
+  }
+  const text = parts.join("; ");
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
 
 // src/tools/manage_attribute_tool.ts
 function contactLocatorSchema2(description) {
@@ -6535,7 +6929,23 @@ function resolveAttributeTarget(db, target) {
   }
   return { kind: "ok", target: { kind: "link", id: link.value.id } };
 }
-function manageAttributeToolHandler(db, input) {
+function manageAttributeToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageAttributeTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (!input.target)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing target.",
+      "target is required."
+    );
   return withToolHandling(() => {
     const resolved = resolveAttributeTarget(db, input.target);
     if (resolved.kind === "error") {
@@ -6646,9 +7056,25 @@ function ensureOwnerParticipates(db, participants) {
 function prepareParticipants(db, raw) {
   return ensureOwnerParticipates(db, raw.map(normalizeParticipant));
 }
-function manageCommitmentToolHandler(db, input) {
+function manageCommitmentToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageCommitmentTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     if (input.action === "record") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for record."
+        );
       const patched = {
         ...input.input,
         participants: prepareParticipants(
@@ -6715,7 +7141,7 @@ var manageCommitmentTool = defineAffinityTool({
                 role: stringSchema("Participant role."),
                 directionality: stringSchema("Optional directionality.")
               },
-              ["contactId", "role"]
+              ["role"]
             ),
             "Participant list. Must be non-empty and include the owner contact."
           ),
@@ -6739,28 +7165,282 @@ var manageCommitmentTool = defineAffinityTool({
       ),
       options: objectSchema(
         {
-          now: integerSchema("Optional timestamp."),
-          resolvingEvent: objectSchema(
-            {
-              type: stringSchema("Optional resolving event type."),
-              occurredAt: integerSchema("Optional resolving event timestamp."),
-              summary: stringSchema("Optional resolving event summary."),
-              significance: integerSchema(
-                "Optional resolving event significance."
-              )
-            },
-            []
-          )
-        },
-        [],
-        "Optional metadata."
-      )
-    },
-    ["action"],
-    "Record or resolve one commitment."
-  ),
-  handler: manageCommitmentToolHandler
-});
+          now: integerSchema("Optional timestamp."),
+          resolvingEvent: objectSchema(
+            {
+              type: stringSchema("Optional resolving event type."),
+              occurredAt: integerSchema("Optional resolving event timestamp."),
+              summary: stringSchema("Optional resolving event summary."),
+              significance: integerSchema(
+                "Optional resolving event significance."
+              )
+            },
+            []
+          )
+        },
+        [],
+        "Optional metadata."
+      )
+    },
+    ["action"],
+    "Record or resolve one commitment."
+  ),
+  handler: manageCommitmentToolHandler
+});
+
+// src/contacts/delete_contact.ts
+function deleteContact(db, locatorId, options) {
+  if (options?.confirm !== true)
+    throw new AffinityValidationError(
+      "delete is permanent; pass confirm: true"
+    );
+  return withTransaction(db, () => {
+    const contact = db.prepare("SELECT is_owner FROM contacts WHERE id = ?").get(locatorId);
+    if (!contact) throw new AffinityNotFoundError("contact not found");
+    if (contact.is_owner)
+      throw new AffinityStateError("The owner contact cannot be deleted");
+    const tables = [
+      "contacts",
+      "identities",
+      "attributes",
+      "links",
+      "events",
+      "event_participants",
+      "open_commitments",
+      "contact_merges",
+      "dismissed_duplicates",
+      "link_event_effects",
+      "upcoming_occurrences",
+      "link_rollups",
+      "contact_rollups"
+    ];
+    const before = new Map(
+      tables.map((table) => [
+        table,
+        db.prepare(`SELECT rowid AS row_id, * FROM ${table}`).all()
+      ])
+    );
+    db.prepare(
+      "DELETE FROM events WHERE id IN (SELECT p.event_id FROM event_participants p WHERE p.contact_id = ? AND NOT EXISTS (SELECT 1 FROM event_participants q JOIN contacts c ON c.id = q.contact_id WHERE q.event_id = p.event_id AND q.contact_id != ? AND c.is_owner = 0))"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "DELETE FROM contact_merges WHERE winner_contact_id = ? OR loser_contact_id = ?"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "DELETE FROM dismissed_duplicates WHERE left_id = ? OR right_id = ?"
+    ).run(locatorId, locatorId);
+    db.prepare(
+      "UPDATE contacts SET merged_into_contact_id = NULL WHERE merged_into_contact_id = ?"
+    ).run(locatorId);
+    db.prepare("DELETE FROM contacts WHERE id = ?").run(locatorId);
+    const now = Date.now();
+    const affectedLinks = db.prepare(
+      "SELECT id FROM links WHERE removed_at IS NULL AND is_structural = 0"
+    ).all().map((row) => row.id);
+    refreshAllBridgeScores(db, now);
+    for (const id of affectedLinks) refreshLinkRollup(db, id, now);
+    for (const row of db.prepare("SELECT id FROM contacts").all())
+      refreshContactRollup(db, Number(row.id), now);
+    const removed = tables.map((table) => {
+      const remaining = new Set(
+        db.prepare(`SELECT rowid AS row_id FROM ${table}`).all().map((row) => row.row_id)
+      );
+      const ids = (before.get(table) ?? []).filter((row) => !remaining.has(row.row_id)).map((row) => Number(row.id ?? row.event_id ?? row.row_id));
+      return { entity: table, count: ids.length, ids };
+    }).filter((item) => item.count > 0);
+    return { contactId: locatorId, removed, affectedLinks };
+  });
+}
+
+// src/identities/queries.ts
+function getIdentityRowById(db, id) {
+  const row = db.prepare(
+    `SELECT id, contact_id, type, value, label, normalized_key, verified, verified_at,
+              created_at, updated_at, removed_at
+       FROM identities
+       WHERE id = ? AND removed_at IS NULL`
+  ).get(id);
+  if (row === void 0) {
+    return null;
+  }
+  return row;
+}
+
+// src/identities/receipts.ts
+function buildIdentityMutationReceipt(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/identities/validators.ts
+function assertNoIdentityCollision(db, normalizedKey, excludeIdentityId) {
+  const row = excludeIdentityId === void 0 ? db.prepare(
+    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
+  ).get(normalizedKey) : db.prepare(
+    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL AND id != ?"
+  ).get(normalizedKey, excludeIdentityId);
+  if (row !== void 0) {
+    const owner = db.prepare(
+      "SELECT c.id, c.name FROM contacts c JOIN identities i ON i.contact_id = c.id WHERE i.normalized_key = ? AND i.removed_at IS NULL"
+    ).get(normalizedKey);
+    throw new AffinityConflictError(
+      `${normalizedKey.replace(":", " ")} already belongs to #${owner?.id} ${owner?.name}`
+    );
+  }
+}
+
+// src/identities/validate_identity_input.ts
+var identityTypes = [
+  "email",
+  "phone",
+  "url",
+  "website",
+  "handle",
+  "x",
+  "twitter",
+  "linkedin",
+  "github",
+  "mastodon",
+  "bluesky",
+  "telegram",
+  "whatsapp",
+  "signal",
+  "matrix",
+  "discord",
+  "slack",
+  "instagram",
+  "facebook",
+  "youtube",
+  "tiktok",
+  "address",
+  "other",
+  "account_id",
+  "alias"
+];
+function validateIdentityInput(type, value) {
+  const kind = type.toLowerCase();
+  if (!identityTypes.includes(kind) && !/^custom:[a-z0-9_-]+$/.test(type))
+    throw new AffinityValidationError(
+      `identity type must be one of ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen)`
+    );
+  if (!value.trim())
+    throw new AffinityValidationError("identity value must be non-empty");
+  if (kind === "email" && !/^[^\s@]+@[^\s@.]+(?:\.[^\s@.]+)+$/.test(value))
+    throw new AffinityValidationError(
+      "email value must match local@domain.tld"
+    );
+  if (kind === "phone" && value.replace(/\D/g, "").length < 5)
+    throw new AffinityValidationError(
+      "phone value must contain at least 5 digits"
+    );
+  if (kind === "url" || kind === "website") {
+    try {
+      const url = new URL(value.includes("://") ? value : `https://${value}`);
+      if (!["http:", "https:"].includes(url.protocol) || !url.hostname || /\s/.test(value))
+        throw new Error();
+    } catch {
+      throw new AffinityValidationError(
+        "url/website value must be an http/https URL or bare domain"
+      );
+    }
+  }
+}
+
+// src/identities/add_identity.ts
+function addIdentity(db, contactId, input) {
+  return withTransaction(db, () => {
+    const contact = getContactRowById(db, contactId);
+    if (!contact) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    if (contact.lifecycle_state === "merged") {
+      throw new AffinityStateError("merged contact is read-only");
+    }
+    const type = input.type.trim();
+    const value = input.value.trim();
+    if (type.length === 0 || value.length === 0) {
+      throw new AffinityValidationError("type and value must be non-empty");
+    }
+    validateIdentityInput(type, value);
+    const nk = normalizeIdentityKey(type, value);
+    assertNoIdentityCollision(db, nk);
+    const now = resolveNow(input.now);
+    const verified = input.verified ? 1 : 0;
+    const verifiedAt = verified === 1 ? now : null;
+    const result = db.prepare(
+      `INSERT INTO identities (contact_id, type, value, label, normalized_key, verified, verified_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      contactId,
+      type,
+      value,
+      input.label ?? null,
+      nk,
+      verified,
+      verifiedAt,
+      now,
+      now
+    );
+    const id = Number(result.lastInsertRowid);
+    const row = getIdentityRowById(db, id);
+    if (!row) {
+      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 }]
+    });
+  });
+}
+
+// src/tools/create_contact_tool_result.ts
+function createContactToolResult(db, input) {
+  return withTransaction(db, () => {
+    const receipt = createContact(db, input);
+    const identityOwners = /* @__PURE__ */ new Set();
+    for (const identity of input.identities ?? []) {
+      validateIdentityInput(identity.type.trim(), identity.value.trim());
+      const existing = db.prepare(
+        "SELECT contact_id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
+      ).get(normalizeIdentityKey(identity.type, identity.value));
+      if (existing) {
+        if (Number(existing.contact_id) !== receipt.primary.id)
+          identityOwners.add(Number(existing.contact_id));
+        continue;
+      }
+      const added = addIdentity(db, receipt.primary.id, identity);
+      receipt.created.push(...added.created);
+    }
+    const result = mutationToolResult("create", receipt, "contact");
+    const fold = (name) => foldSearchText(name).trim().replace(/\s+/g, " ");
+    const warnings = db.prepare(
+      "SELECT id, name FROM contacts WHERE id != ? AND deleted_at IS NULL AND lifecycle_state IN ('active', 'dormant')"
+    ).all(receipt.primary.id).flatMap((row) => {
+      const score = identityOwners.has(row.id) ? 1 : fold(row.name) === fold(input.name) ? 0.92 : void 0;
+      return score === void 0 ? [] : [
+        {
+          code: "possible_duplicate",
+          message: `Possible duplicate of #${row.id} ${row.name} (score ${score})`,
+          contactId: row.id,
+          score
+        }
+      ];
+    });
+    if (warnings.length) result.warnings = warnings;
+    return result;
+  });
+}
 
 // src/tools/manage_contact_tool.ts
 function contactLocatorSchema3(description) {
@@ -6780,24 +7460,76 @@ function contactLocatorSchema3(description) {
     description
   };
 }
-function manageContactToolHandler(db, input) {
+function manageContactToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageContactTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
-    if (input.action === "create") {
-      return mutationToolResult(
-        "create",
-        createContact(db, input.input),
-        "contact"
+    if (input.action === "export") {
+      if (!input.contact)
+        return toolSuccess("Exported Affinity.", {
+          action: "export",
+          export: exportAffinity(db)
+        });
+      const target = resolveContactLocator(db, input.contact, "contact", true);
+      if (!target.ok) return target.result;
+      return toolSuccess("Exported contact.", {
+        action: "export",
+        export: exportContact(db, target.value.id)
+      });
+    }
+    if (input.action === "delete" && input.confirm !== true)
+      return toolFailure(
+        "protocol",
+        "invalid_input",
+        "Delete requires confirmation.",
+        "delete is permanent; pass confirm: true (CLI: --confirm)"
       );
+    if (input.action === "create") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for create."
+        );
+      return createContactToolResult(db, input.input);
     }
-    const contact = resolveContactLocator(db, input.contact, "contact");
+    const contact = resolveContactLocator(
+      db,
+      input.contact,
+      "contact",
+      input.action === "delete"
+    );
     if (!contact.ok) {
       return contact.result;
     }
+    if (input.action === "delete") {
+      const deletion = deleteContact(db, contact.value.id, { confirm: true });
+      return toolSuccess("Permanently deleted contact.", {
+        action: "delete",
+        deletion,
+        changes: deletion.removed.flatMap(
+          (item) => item.ids.map((id) => ({
+            entity: item.entity,
+            id,
+            action: "removed"
+          }))
+        )
+      });
+    }
     if (input.action === "revise") {
       return mutationToolResult(
         "revise",
         reviseContact(db, contact.value.id, input.patch),
-        "contact"
+        "contact",
+        Object.keys(input.patch)
       );
     }
     return mutationToolResult(
@@ -6814,7 +7546,7 @@ function manageContactToolHandler(db, input) {
 }
 var manageContactTool = defineAffinityTool({
   name: manageContactToolName,
-  description: "Create a contact, revise one contact's core fields, or change lifecycle state. ALWAYS search_affinity first before creating \u2014 duplicates corrupt the graph.",
+  description: "Create, revise, export or permanently delete a contact (confirm: true required; owner cannot be deleted). Export without contact exports the whole database. Lifecycle lost is soft delete. ALWAYS search_affinity first before creating \u2014 duplicates corrupt the graph.",
   whenToUse: "Use this for contact creation and lifecycle-safe contact maintenance.",
   whenNotToUse: "Do not use this for identities, links, attributes, or merges.",
   sideEffects: "writes_state",
@@ -6835,10 +7567,25 @@ var manageContactTool = defineAffinityTool({
       action: enumSchema("Operation to perform.", [
         "create",
         "revise",
-        "set_lifecycle"
+        "set_lifecycle",
+        "export",
+        "delete"
       ]),
       input: objectSchema(
         {
+          identities: arraySchema(
+            objectSchema(
+              {
+                type: stringSchema("Identity type."),
+                value: stringSchema("Identity value."),
+                label: stringSchema("Optional label."),
+                verified: booleanSchema("Verified identity."),
+                now: integerSchema("Optional timestamp.")
+              },
+              ["type", "value"]
+            ),
+            "Optional identities to attach. Identities already owned by another contact are left with that owner and reported as possible duplicates."
+          ),
           name: stringSchema("Contact name."),
           kind: enumSchema("Contact kind.", [
             "human",
@@ -6857,6 +7604,7 @@ var manageContactTool = defineAffinityTool({
         ["name", "kind"],
         "New contact payload. Required when action=create."
       ),
+      confirm: booleanSchema("Required true for permanent deletion."),
       contact: contactLocatorSchema3(
         "Target contact. Required when action=revise or set_lifecycle. Provide contactId or identity."
       ),
@@ -6903,7 +7651,19 @@ function contactLocatorSchema4(description) {
     description
   };
 }
-function manageDuplicateDismissalToolHandler(db, input) {
+function manageDuplicateDismissalToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    manageDuplicateDismissalTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const left = resolveContactLocator(db, input.left, "left");
     if (!left.ok) {
@@ -6913,6 +7673,11 @@ function manageDuplicateDismissalToolHandler(db, input) {
     if (!right.ok) {
       return right.result;
     }
+    const leftContactId = Math.min(left.value.id, right.value.id);
+    const rightContactId = Math.max(left.value.id, right.value.id);
+    const existed = db.prepare(
+      "SELECT 1 FROM dismissed_duplicates WHERE left_id = ? AND right_id = ?"
+    ).get(leftContactId, rightContactId) !== void 0;
     if (input.action === "dismiss") {
       const receipt2 = dismissDuplicate(
         db,
@@ -6922,19 +7687,41 @@ function manageDuplicateDismissalToolHandler(db, input) {
       );
       return toolSuccess(
         `Dismissed pair #${receipt2.primary.leftContactId} / #${receipt2.primary.rightContactId}.`,
-        { action: "dismiss", primary: receipt2.primary }
+        {
+          ...receipt2,
+          action: "dismiss",
+          changes: [
+            {
+              entity: "duplicate_dismissal",
+              leftContactId,
+              rightContactId,
+              action: existed ? "updated" : "created"
+            }
+          ]
+        }
       );
     }
     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 }
+      {
+        ...receipt,
+        action: "undismiss",
+        changes: existed ? [
+          {
+            entity: "duplicate_dismissal",
+            leftContactId,
+            rightContactId,
+            action: "removed"
+          }
+        ] : []
+      }
     );
   }, "Duplicate dismissal failed.");
 }
 var manageDuplicateDismissalTool = defineAffinityTool({
   name: manageDuplicateDismissalToolName,
-  description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in listDuplicateCandidates.",
+  description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in review_affinity contacts.duplicates.",
   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",
@@ -7020,9 +7807,32 @@ function resolveDateAnchorTarget(db, target) {
   }
   return { kind: "ok", target: { kind: "link", linkId: link.value.id } };
 }
-function manageDateAnchorToolHandler(db, input) {
+function manageDateAnchorToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageDateAnchorTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (input.action !== "add" && input.anchorEventId === void 0)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing anchorEventId.",
+      "anchorEventId is required."
+    );
   return withToolHandling(() => {
     if (input.action === "add") {
+      if (!input.input)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Missing input.",
+          "input is required for add."
+        );
       const resolved = resolveDateAnchorTarget(db, input.input.target);
       if (resolved.kind === "error") {
         return resolved.result;
@@ -7037,7 +7847,8 @@ function manageDateAnchorToolHandler(db, input) {
       return mutationToolResult(
         "revise",
         reviseDateAnchor(db, input.anchorEventId, input.patch, input.options),
-        "date anchor"
+        "date anchor",
+        Object.keys(input.patch)
       );
     }
     return mutationToolResult(
@@ -7145,97 +7956,6 @@ var manageDateAnchorTool = defineAffinityTool({
   handler: manageDateAnchorToolHandler
 });
 
-// src/identities/queries.ts
-function getIdentityRowById(db, id) {
-  const row = db.prepare(
-    `SELECT id, contact_id, type, value, label, normalized_key, verified, verified_at,
-              created_at, updated_at, removed_at
-       FROM identities
-       WHERE id = ? AND removed_at IS NULL`
-  ).get(id);
-  if (row === void 0) {
-    return null;
-  }
-  return row;
-}
-
-// src/identities/receipts.ts
-function buildIdentityMutationReceipt(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/identities/validators.ts
-function assertNoIdentityCollision(db, normalizedKey, excludeIdentityId) {
-  const row = excludeIdentityId === void 0 ? db.prepare(
-    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL"
-  ).get(normalizedKey) : db.prepare(
-    "SELECT id FROM identities WHERE normalized_key = ? AND removed_at IS NULL AND id != ?"
-  ).get(normalizedKey, excludeIdentityId);
-  if (row !== void 0) {
-    throw new AffinityConflictError(
-      "another contact already owns this normalized identity"
-    );
-  }
-}
-
-// src/identities/add_identity.ts
-function addIdentity(db, contactId, input) {
-  return withTransaction(db, () => {
-    const contact = getContactRowById(db, contactId);
-    if (!contact) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    if (contact.lifecycle_state === "merged") {
-      throw new AffinityStateError("merged contact is read-only");
-    }
-    const type = input.type.trim();
-    const value = input.value.trim();
-    if (type.length === 0 || value.length === 0) {
-      throw new AffinityValidationError("type and value must be non-empty");
-    }
-    const nk = normalizeIdentityKey(type, value);
-    assertNoIdentityCollision(db, nk);
-    const now = resolveNow(input.now);
-    const verified = input.verified ? 1 : 0;
-    const verifiedAt = verified === 1 ? now : null;
-    const result = db.prepare(
-      `INSERT INTO identities (contact_id, type, value, label, normalized_key, verified, verified_at, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
-    ).run(
-      contactId,
-      type,
-      value,
-      input.label ?? null,
-      nk,
-      verified,
-      verifiedAt,
-      now,
-      now
-    );
-    const id = Number(result.lastInsertRowid);
-    const row = getIdentityRowById(db, id);
-    if (!row) {
-      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 }]
-    });
-  });
-}
-
 // src/identities/remove_identity.ts
 function removeIdentity(db, identityId, removedAt) {
   return withTransaction(db, () => {
@@ -7287,6 +8007,7 @@ function reviseIdentity(db, identityId, patch) {
     if (nextType.length === 0 || nextValue.length === 0) {
       throw new AffinityValidationError("type and value must be non-empty");
     }
+    validateIdentityInput(nextType, nextValue);
     const nextLabel = patch.label !== void 0 ? patch.label : row.label;
     const nkNext = normalizeIdentityKey(nextType, nextValue);
     if (nkNext !== row.normalized_key) {
@@ -7341,7 +8062,9 @@ function contactLocatorSchema6(description) {
       contactId: integerSchema("Exact contact id."),
       identity: objectSchema(
         {
-          type: stringSchema("Identity type."),
+          type: stringSchema(
+            `Identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+          ),
           value: stringSchema("Identity value.")
         },
         ["type", "value"],
@@ -7351,7 +8074,23 @@ function contactLocatorSchema6(description) {
     description
   };
 }
-function manageIdentityToolHandler(db, input) {
+function manageIdentityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(manageIdentityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
+  if (input.action !== "add" && input.identityId === void 0)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Missing identityId.",
+      "identityId is required."
+    );
   return withToolHandling(() => {
     switch (input.action) {
       case "add": {
@@ -7369,7 +8108,8 @@ function manageIdentityToolHandler(db, input) {
         return mutationToolResult(
           "revise",
           reviseIdentity(db, input.identityId, input.patch),
-          "identity"
+          "identity",
+          Object.keys(input.patch)
         );
       case "verify":
         return mutationToolResult(
@@ -7418,7 +8158,9 @@ var manageIdentityTool = defineAffinityTool({
       ),
       input: objectSchema(
         {
-          type: stringSchema("Identity type."),
+          type: stringSchema(
+            `Identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+          ),
           value: stringSchema("Identity value."),
           label: stringSchema("Optional label."),
           verified: booleanSchema("Whether the identity starts verified."),
@@ -7432,7 +8174,9 @@ var manageIdentityTool = defineAffinityTool({
       ),
       patch: objectSchema(
         {
-          type: stringSchema("Optional identity type."),
+          type: stringSchema(
+            `Optional identity type: ${identityTypes.join(", ")}, or custom:<name> (lowercase a-z, 0-9, underscore or hyphen).`
+          ),
           value: stringSchema("Optional identity value."),
           label: stringSchema("Optional label.")
         },
@@ -7490,7 +8234,19 @@ function linkLocatorSchema4(description) {
     description
   };
 }
-function manageRelationshipToolHandler(db, input) {
+function manageRelationshipToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(
+    manageRelationshipTool.inputSchema,
+    input
+  );
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     switch (input.action) {
       case "seed_social_link": {
@@ -7671,7 +8427,16 @@ function contactLocatorSchema8(description) {
     description
   };
 }
-function mergeContactsToolHandler(db, input) {
+function mergeContactsToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(mergeContactsTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const winner = resolveContactLocator(db, input.winner, "winner");
     if (!winner.ok) {
@@ -7752,7 +8517,16 @@ function prepareParticipants2(db, raw, injectOwner) {
   const normalized = raw.map(normalizeParticipant2);
   return injectOwner ? ensureOwnerParticipates2(db, normalized) : normalized;
 }
-function recordEventToolHandler(db, input) {
+function recordEventToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(recordEventTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const patched = {
       ...input.input,
@@ -7850,7 +8624,7 @@ var recordEventTool = defineAffinityTool({
                   "observed"
                 ])
               },
-              ["contactId", "role"]
+              ["role"]
             ),
             "Participant list. Must be non-empty and include the owner contact."
           ),
@@ -7866,9 +8640,71 @@ var recordEventTool = defineAffinityTool({
   handler: recordEventToolHandler
 });
 
+// src/tools/enrich_review_item.ts
+function enrichReviewItem(db, item) {
+  const name = (id) => {
+    if (typeof id !== "number") return "";
+    return db.prepare("SELECT name FROM contacts WHERE id = ?").get(id)?.name ?? `Contact #${id}`;
+  };
+  const result = { ...item };
+  if (item.kind === "link") {
+    const link = db.prepare(`SELECT l.*, a.name AS from_name, b.name AS to_name, a.is_owner AS from_owner, b.is_owner AS to_owner,
+      lr.recency_score, lr.drift_priority, lr.readiness_score, lr.normalized_rank, lr.reciprocity_score, lr.radar_score FROM links l JOIN contacts a ON a.id = l.from_contact_id JOIN contacts b ON b.id = l.to_contact_id LEFT JOIN link_rollups lr ON lr.link_id = l.id WHERE l.id = ?`).get(item.id);
+    if (link) {
+      result.title = link.from_owner ? String(link.to_name) : link.to_owner ? String(link.from_name) : `${link.from_name} \xB7 ${link.to_name}`;
+      result.subtitle = [link.kind, link.role].filter(Boolean).join(" \xB7 ");
+      for (const key of ["affinity", "trust", "rank"])
+        if (typeof link[key] === "number") result[key] = link[key];
+      result.recencyScore ??= link.recency_score;
+      result.driftPriority ??= link.drift_priority;
+      result.readinessScore = link.readiness_score;
+      result.normalizedRank ??= link.normalized_rank;
+      result.reciprocityScore = link.reciprocity_score;
+      result.radarScore = link.radar_score;
+    }
+  }
+  if (item.kind === "event" && typeof item.linkId === "number" && !Array.isArray(item.participants)) {
+    const link = db.prepare("SELECT from_contact_id, to_contact_id FROM links WHERE id = ?").get(item.linkId);
+    if (link)
+      result.subtitle = `${item.subtitle} \xB7 ${name(link.from_contact_id)} \xB7 ${name(link.to_contact_id)}`;
+  }
+  if (Array.isArray(item.participants)) {
+    result.counterpartyNames = item.participants.map(
+      (p) => name(p.contactId)
+    );
+    result.subtitle = [
+      item.subtitle,
+      result.counterpartyNames.join(", ")
+    ].filter(Boolean).join(" \xB7 ");
+  }
+  if (typeof item.leftContactId === "number")
+    result.title = `${name(item.leftContactId)} \xB7 ${name(item.rightContactId)}`;
+  if (typeof item.winnerContactId === "number")
+    result.title = `Merged ${name(item.loserContactId)} into ${name(item.winnerContactId)}`;
+  if (item.occursAt !== void 0 && item.kind === "contact")
+    result.title = `${name(item.id)} \xB7 ${item.title}`;
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value === "number" && /score|priority|affinity|trust|rank/i.test(key))
+      result[key] = Math.round(value * 1e3) / 1e3;
+  }
+  return result;
+}
+
+// src/tools/tool_summary.ts
+function summarizeCount(count, singular) {
+  if (count === 0) {
+    return `No ${singular}s found.`;
+  }
+  if (count === 1) {
+    return `Found 1 ${singular}.`;
+  }
+  return `Found ${count} ${singular}s.`;
+}
+
 // src/tools/review_affinity_tool.ts
 function buildReadOptions(input) {
   return {
+    ...input.now === void 0 ? {} : { now: input.now },
     ...input.limit === void 0 ? {} : { limit: input.limit },
     ...input.offset === void 0 ? {} : { offset: input.offset },
     ...input.includeArchived === void 0 ? {} : { includeArchived: input.includeArchived },
@@ -7988,6 +8824,7 @@ function validateReviewInput(input) {
 }
 function duplicateCandidateItem(candidate) {
   return {
+    ...candidate,
     kind: "contact",
     id: candidate.leftContactId,
     title: `Possible duplicate: #${candidate.leftContactId} and #${candidate.rightContactId}`,
@@ -7997,24 +8834,28 @@ function duplicateCandidateItem(candidate) {
 }
 function momentItem(moment) {
   return {
+    ...moment,
+    occurredAtIso: new Date(moment.occurredAt).toISOString(),
     kind: "event",
     id: moment.eventId,
     title: moment.summary,
     subtitle: moment.momentKind,
-    snippet: `link #${moment.linkId} at ${moment.occurredAt}`
+    snippet: new Date(moment.occurredAt).toISOString().slice(0, 10)
   };
 }
 function commitmentItem(commitment) {
   return {
+    ...commitment,
     kind: "event",
     id: commitment.eventId,
     title: commitment.summary,
     subtitle: commitment.type,
-    snippet: `state ${commitment.resolutionState}; participants ${commitment.participants.length}; due ${commitment.dueAt ?? "none"}`
+    snippet: `state ${commitment.resolutionState}; participants ${commitment.participants.length}; due ${commitment.dueAt == null ? "none" : new Date(commitment.dueAt).toISOString().slice(0, 10)}`
   };
 }
 function radarItem(radar) {
   return {
+    ...radar,
     kind: "link",
     id: radar.linkId,
     title: `Link #${radar.linkId}`,
@@ -8024,29 +8865,34 @@ function radarItem(radar) {
 }
 function upcomingDateItem(date) {
   return {
+    ...date,
+    occursAt: date.occursOn,
+    occursAtIso: new Date(date.occursOn).toISOString(),
     kind: date.targetRef.kind,
     id: date.targetRef.id,
     title: date.summary,
     subtitle: date.recurrenceKind,
-    snippet: `occurs ${date.occursOn}`
+    snippet: `occurs ${new Date(date.occursOn).toISOString().slice(0, 10)}`
   };
 }
 function mergeHistoryItem(record) {
   return {
+    ...record,
     kind: "contact",
     id: record.winnerContactId,
     title: `Merged #${record.loserContactId} into #${record.winnerContactId}`,
-    subtitle: `at ${record.mergedAt}`,
+    subtitle: new Date(record.mergedAt).toISOString().slice(0, 10),
     snippet: record.reasonSummary ?? void 0
   };
 }
 function dismissedPairItem(record) {
   return {
+    ...record,
     kind: "contact",
     id: record.leftContactId,
     title: `Dismissed pair: #${record.leftContactId} and #${record.rightContactId}`,
     subtitle: record.reason ?? "no reason given",
-    snippet: `dismissed at ${record.dismissedAt}`
+    snippet: `dismissed at ${new Date(record.dismissedAt).toISOString().slice(0, 10)}`
   };
 }
 function compactFilters(input) {
@@ -8056,7 +8902,16 @@ function compactFilters(input) {
     )
   );
 }
-function reviewAffinityToolHandler(db, input) {
+function reviewAffinityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(reviewAffinityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const invalid = validateReviewInput(input);
     if (invalid) {
@@ -8070,6 +8925,9 @@ function reviewAffinityToolHandler(db, input) {
         items = listContacts(
           db,
           {
+            ...input.attribute === void 0 ? {} : { attribute: input.attribute },
+            ...input.tag === void 0 ? {} : { tag: input.tag },
+            ...input.includeLost === void 0 ? {} : { includeLost: input.includeLost },
             ...input.kind === void 0 ? {} : { kind: input.kind },
             ...input.lifecycleState === void 0 ? {} : { lifecycleState: input.lifecycleState },
             ...input.includeOwner === void 0 ? {} : { includeOwner: input.includeOwner },
@@ -8100,7 +8958,7 @@ function reviewAffinityToolHandler(db, input) {
             "Provide `contact` when `view` is `events.contact_journal`."
           );
         }
-        const contact = resolveContactLocator(db, locator, "contact");
+        const contact = resolveContactLocator(db, locator, "contact", true);
         if (!contact.ok) {
           return contact.result;
         }
@@ -8135,7 +8993,12 @@ function reviewAffinityToolHandler(db, input) {
           let contactId;
           let linkId;
           if (input.contact !== void 0) {
-            const contact = resolveContactLocator(db, input.contact, "contact");
+            const contact = resolveContactLocator(
+              db,
+              input.contact,
+              "contact",
+              true
+            );
             if (!contact.ok) {
               return contact.result;
             }
@@ -8164,7 +9027,12 @@ function reviewAffinityToolHandler(db, input) {
           let contactId;
           let linkId;
           if (input.contact !== void 0) {
-            const contact = resolveContactLocator(db, input.contact, "contact");
+            const contact = resolveContactLocator(
+              db,
+              input.contact,
+              "contact",
+              true
+            );
             if (!contact.ok) {
               return contact.result;
             }
@@ -8257,7 +9125,7 @@ function reviewAffinityToolHandler(db, input) {
             "Provide `contact` when `view` is `merges.history`."
           );
         }
-        const contact = resolveContactLocator(db, locator, "contact");
+        const contact = resolveContactLocator(db, locator, "contact", true);
         if (!contact.ok) {
           return contact.result;
         }
@@ -8270,6 +9138,7 @@ function reviewAffinityToolHandler(db, input) {
         items = listDismissedDuplicates(db, options).map(dismissedPairItem);
         break;
     }
+    items = items.map((item) => enrichReviewItem(db, item));
     return toolSuccess(
       summarizeCount(items.length, "item"),
       {
@@ -8302,12 +9171,16 @@ var reviewAffinityTool = defineAffinityTool({
   targetKinds: ["contact", "link", "event"],
   inputDescriptions: {
     view: "Which review surface to return.",
+    now: "Optional current timestamp for overdue calculations.",
     contact: "Target contact locator for views that require one.",
     link: "Target link locator for views that require one.",
     contactIds: "Optional contact id subset for duplicate review or graph review.",
     kind: "Optional contact kind or link kind filter, depending on the view.",
     lifecycleState: "Optional contact lifecycle filter for the contact list view.",
     linkState: "Optional link state filter for link review views.",
+    attribute: "Attribute name or name=value; arrays require all filters.",
+    tag: "Tag name; arrays require all tags.",
+    includeLost: "Whether lost contacts are included.",
     includeOwner: "Whether owner contacts should be included in contact review.",
     includeDormant: "Whether dormant links or contacts should be included where supported.",
     includeArchived: "Whether archived links should be included where supported.",
@@ -8344,6 +9217,9 @@ var reviewAffinityTool = defineAffinityTool({
         "merges.history",
         "merges.dismissed"
       ]),
+      now: integerSchema(
+        "Optional current timestamp for overdue calculations."
+      ),
       contact: contactLocatorSchema9("Optional target contact locator."),
       link: linkLocatorSchema5("Optional target link locator."),
       contactIds: arraySchema(
@@ -8366,6 +9242,17 @@ var reviewAffinityTool = defineAffinityTool({
         "broken",
         "archived"
       ]),
+      attribute: oneOfSchema([
+        stringSchema("Attribute filter."),
+        arraySchema(stringSchema("Attribute filter."), "AND filters.")
+      ]),
+      tag: oneOfSchema([
+        stringSchema("Tag filter."),
+        arraySchema(stringSchema("Tag filter."), "AND tags.")
+      ]),
+      includeLost: booleanSchema(
+        "Include lost contacts (search excludes them by default)."
+      ),
       includeOwner: booleanSchema("Whether owner contacts are included."),
       includeDormant: booleanSchema("Whether dormant rows are included."),
       includeArchived: booleanSchema("Whether archived links are included."),
@@ -8410,7 +9297,16 @@ var reviewAffinityTool = defineAffinityTool({
 });
 
 // src/tools/search_affinity_tool.ts
-function searchAffinityToolHandler(db, input) {
+function searchAffinityToolHandler(db, rawInput) {
+  const input = structuredClone(rawInput);
+  const inputError = validateToolInput(searchAffinityTool.inputSchema, input);
+  if (inputError)
+    return toolFailure(
+      "protocol",
+      "invalid_input",
+      "Invalid input.",
+      inputError
+    );
   return withToolHandling(() => {
     const options = {
       ...input.limit === void 0 ? {} : { limit: input.limit },
@@ -8420,6 +9316,9 @@ function searchAffinityToolHandler(db, input) {
       db,
       input.query,
       {
+        ...input.attribute === void 0 ? {} : { attribute: input.attribute },
+        ...input.tag === void 0 ? {} : { tag: input.tag },
+        ...input.includeLost === void 0 ? {} : { includeLost: input.includeLost },
         ...input.kind === void 0 ? {} : { kind: input.kind },
         ...input.lifecycleState === void 0 ? {} : { lifecycleState: input.lifecycleState },
         ...input.includeOwner === void 0 ? {} : { includeOwner: input.includeOwner },
@@ -8443,7 +9342,7 @@ function searchAffinityToolHandler(db, input) {
 }
 var searchAffinityTool = defineAffinityTool({
   name: searchAffinityToolName,
-  description: "Search contacts by name or identity, including exact natural-key lookups like email-style identifiers.",
+  description: "Search contacts by name, identity, attributes, link roles, bonds and event text. All whitespace tokens must match. Dormant and lost contacts are excluded by default; use includeDormant and includeLost to include them.",
   whenToUse: "Use this when you want to find contacts from free text or a known routing identity such as an email or URL-like handle.",
   whenNotToUse: "Do not use this when you already know the exact contact you want to inspect in depth.",
   sideEffects: "none",
@@ -8454,6 +9353,9 @@ var searchAffinityTool = defineAffinityTool({
     query: "Free-text or natural-key search text.",
     kind: "Optional contact kind filter.",
     lifecycleState: "Optional lifecycle state filter.",
+    attribute: "Attribute name or name=value; arrays require all filters.",
+    tag: "Tag name; arrays require all tags.",
+    includeLost: "Whether lost contacts are included in search.",
     includeOwner: "Whether owner contacts are eligible for results.",
     includeDormant: "Whether dormant contacts should be eligible for results.",
     limit: "Optional result limit.",
@@ -8478,6 +9380,17 @@ var searchAffinityTool = defineAffinityTool({
         "merged",
         "lost"
       ]),
+      attribute: oneOfSchema([
+        stringSchema("Attribute filter."),
+        arraySchema(stringSchema("Attribute filter."), "AND filters.")
+      ]),
+      tag: oneOfSchema([
+        stringSchema("Tag filter."),
+        arraySchema(stringSchema("Tag filter."), "AND tags.")
+      ]),
+      includeLost: booleanSchema(
+        "Include lost contacts (search excludes them by default)."
+      ),
       includeOwner: booleanSchema("Whether owner contacts are included."),
       includeDormant: booleanSchema("Whether dormant contacts are included."),
       limit: integerSchema("Optional result limit."),
@@ -8513,6 +9426,9 @@ function getAffinityToolByName(name) {
 
 // src/tools/tool_mapping.ts
 var affinityToolMappings = [
+  { source: "exportContact", tool: manageContactToolName, action: "export" },
+  { source: "exportAffinity", tool: manageContactToolName, action: "export" },
+  { source: "deleteContact", tool: manageContactToolName, action: "delete" },
   { source: "searchContacts", tool: searchAffinityToolName },
   {
     source: "getOwnerProfile",
@@ -8699,6 +9615,7 @@ __export(write_exports, {
   addDateAnchor: () => addDateAnchor,
   addIdentity: () => addIdentity,
   createContact: () => createContact,
+  deleteContact: () => deleteContact,
   dismissDuplicate: () => dismissDuplicate,
   mergeContacts: () => mergeContacts,
   overrideLinkState: () => overrideLinkState,