@ghostpaw/affinity 0.4.1 → 0.5.0

package/dist/mcp.cjs

@@ -5,11 +5,16 @@ var node_path = require('node:path');
 var node_os = require('node:os');
 
 // src/version.ts
-var affinityVersion = "0.4.1";
+var affinityVersion = "0.5.0";
 
 // src/surface/affinity_mcp_instructions.ts
 var affinityMcpInstructions = "Affinity is a local relationship model and social CRM. Search before creating contacts. Inspect before revising or merging. Record direct evidence honestly, keep identities and structural ties distinct from social links, and ask for clarification when a target is ambiguous. Review commitments and recurring dates regularly. Derived scores guide attention and do not prove relationship quality.";
 
+// src/surfaces/cli_args.ts
+var CliUsageError = class extends Error {
+  exitCode = 2;
+};
+
 // src/lib/errors/affinity_error.ts
 var AffinityError = class extends Error {
   constructor(message, options) {
@@ -19,11 +24,60 @@ var AffinityError = class extends Error {
   }
 };
 
+// src/lib/errors/affinity_validation_error.ts
+var AffinityValidationError = class extends AffinityError {
+  code = "VALIDATION";
+};
+
+// 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/types/read_list_options.ts
+var AFFINITY_DEFAULT_LIST_LIMIT = 50;
+var AFFINITY_MAX_LIST_LIMIT = 250;
+
+// src/lib/types/resolve_affinity_list_limit.ts
+function resolveAffinityListLimit(limit) {
+  if (limit === void 0) {
+    return AFFINITY_DEFAULT_LIST_LIMIT;
+  }
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new AffinityValidationError("limit must be a positive integer");
+  }
+  if (limit > AFFINITY_MAX_LIST_LIMIT) {
+    throw new AffinityValidationError(
+      `limit must be <= ${String(AFFINITY_MAX_LIST_LIMIT)}`
+    );
+  }
+  return limit;
+}
+
+// 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/lib/errors/affinity_invariant_error.ts
 var AffinityInvariantError = class extends AffinityError {
   code = "INVARIANT";
 };
 
+// src/lib/errors/affinity_not_found_error.ts
+var AffinityNotFoundError = class extends AffinityError {
+  code = "NOT_FOUND";
+};
+
 // src/contacts/queries.ts
 function getContactRowById(db, id) {
   const row = db.prepare(
@@ -55,21 +109,11 @@ function requireOwnerContactId(db) {
   return ownerId;
 }
 
-// src/lib/errors/affinity_not_found_error.ts
-var AffinityNotFoundError = class extends AffinityError {
-  code = "NOT_FOUND";
-};
-
 // src/lib/errors/affinity_state_error.ts
 var AffinityStateError = class extends AffinityError {
   code = "STATE";
 };
 
-// src/lib/errors/affinity_validation_error.ts
-var AffinityValidationError = class extends AffinityError {
-  code = "VALIDATION";
-};
-
 // src/events/validators.ts
 var PARTICIPANT_ROLES = /* @__PURE__ */ new Set([
   "actor",
@@ -103,7 +147,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}`
+      );
     }
   }
 }
@@ -275,6 +322,134 @@ 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/resolve_now.ts
 function resolveNow(now) {
   if (now !== void 0) {
@@ -288,6 +463,85 @@ function resolveNow(now) {
   return Date.now();
 }
 
+// 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/with_transaction.ts
 var transactionDepth = /* @__PURE__ */ new WeakMap();
 function withTransaction(db, fn) {
@@ -559,13 +813,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
   };
 }
@@ -573,7 +834,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
@@ -586,45 +867,6 @@ 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/lib/types/read_list_options.ts
-var AFFINITY_DEFAULT_LIST_LIMIT = 50;
-var AFFINITY_MAX_LIST_LIMIT = 250;
-
-// src/lib/types/resolve_affinity_list_limit.ts
-function resolveAffinityListLimit(limit) {
-  if (limit === void 0) {
-    return AFFINITY_DEFAULT_LIST_LIMIT;
-  }
-  if (!Number.isInteger(limit) || limit < 1) {
-    throw new AffinityValidationError("limit must be a positive integer");
-  }
-  if (limit > AFFINITY_MAX_LIST_LIMIT) {
-    throw new AffinityValidationError(
-      `limit must be <= ${String(AFFINITY_MAX_LIST_LIMIT)}`
-    );
-  }
-  return limit;
-}
-
-// 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/list_moments.ts
 function listMoments(db, filters, options) {
   assertDefaultOrdering("listMoments", options);
@@ -680,101 +922,6 @@ function listMoments(db, filters, 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/links/queries.ts
 function getLinkRowById(db, id) {
   const row = db.prepare(
@@ -972,7 +1119,7 @@ function nextCadenceDays(params) {
 }
 
 // src/links/rollups.ts
-var DAY_MS = 864e5;
+var DAY_MS2 = 864e5;
 function parseJsonObject2(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -1030,7 +1177,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) {
@@ -1041,15 +1188,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);
@@ -1057,7 +1204,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);
@@ -1083,7 +1230,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,
@@ -1210,8 +1357,55 @@ function getLinkDetail(db, linkId, options) {
   };
 }
 
+// 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 = {}) {
@@ -1258,6 +1452,12 @@ function objectSchema(properties, required, description) {
 function nullableStringSchema(description) {
   return { anyOf: [{ type: "string" }, { type: "null" }], description };
 }
+function oneOfSchema(schemas, description) {
+  const schema = {
+    oneOf: schemas
+  };
+  return schema;
+}
 
 // src/tools/tool_names.ts
 var searchAffinityToolName = "search_affinity";
@@ -1291,6 +1491,7 @@ function toContactEntityRef(value) {
 function toContactListToolItem(value) {
   return {
     ...toContactEntityRef(value),
+    ..."matchedOn" in value ? { matchedOn: value.matchedOn } : {},
     subtitle: "kind" in value ? value.kind : void 0
   };
 }
@@ -1322,7 +1523,9 @@ function toEventEntityRef(value) {
 }
 function toEventListToolItem(value) {
   return {
+    ...value,
     ...toEventEntityRef(value),
+    occurredAtIso: new Date(value.occurredAt).toISOString(),
     snippet: `${value.participants.length} participant(s)`
   };
 }
@@ -1370,7 +1573,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 };
@@ -1434,9 +1637,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) {
@@ -1450,8 +1675,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
@@ -1509,6 +1751,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) {
@@ -1524,6 +1775,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",
@@ -1642,6 +1902,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 {
@@ -1677,7 +2023,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(
@@ -1695,19 +2053,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",
@@ -1719,7 +2079,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");
@@ -2161,9 +2524,17 @@ function unsetAttribute(db, target, name, removedAt) {
 }
 
 // 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,
@@ -2250,7 +2621,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") {
@@ -2876,13 +3263,13 @@ function repairBonus(consecutiveRepairEvents) {
 }
 
 // src/links/effects.ts
-var DAY_MS2 = 864e5;
+var DAY_MS3 = 864e5;
 function clamp3(value, min, max) {
   return Math.min(max, Math.max(min, value));
 }
 function countSameDaySimilarEvents(db, linkId, eventType, occurredAt) {
   const dayStart = utcStartOfDayMs(occurredAt);
-  const dayEnd = dayStart + DAY_MS2;
+  const dayEnd = dayStart + DAY_MS3;
   const row = db.prepare(
     `SELECT COUNT(*) AS c
        FROM link_event_effects le
@@ -2895,7 +3282,7 @@ function countSameDaySimilarEvents(db, linkId, eventType, occurredAt) {
   return Number(row.c ?? 0);
 }
 function weeklyPositiveBaseWeight(db, linkId, occurredAt) {
-  const weekStart = occurredAt - 7 * DAY_MS2;
+  const weekStart = occurredAt - 7 * DAY_MS3;
   const row = db.prepare(
     `SELECT SUM(base_weight) AS total
        FROM link_event_effects
@@ -2907,7 +3294,7 @@ function weeklyPositiveBaseWeight(db, linkId, occurredAt) {
   return Number(row.total ?? 0);
 }
 function countRepairContext(db, linkId, occurredAt) {
-  const thirtyDaysAgo = occurredAt - 30 * DAY_MS2;
+  const thirtyDaysAgo = occurredAt - 30 * DAY_MS3;
   const hasPriorDamage = db.prepare(
     `SELECT 1 FROM link_event_effects
        WHERE link_id = ? AND trust_delta < 0
@@ -2982,8 +3369,8 @@ function computePreferenceMatch(db, linkId, contactId, eventType, provenance) {
   return preferenceMatch(liked, disliked);
 }
 function computeDateSalienceMultiplier(db, contactId, occurredAt, significance) {
-  const windowBefore = 7 * DAY_MS2;
-  const windowAfter = 2 * DAY_MS2;
+  const windowBefore = 7 * DAY_MS3;
+  const windowAfter = 2 * DAY_MS3;
   const row = db.prepare(
     `SELECT 1 FROM upcoming_occurrences uo
        JOIN events e ON e.id = uo.event_id
@@ -3150,9 +3537,9 @@ function applyEventEffectToLink(db, params) {
   ).get(params.linkId);
   const gapDays = latest === void 0 ? cadenceBefore : Math.max(
     1,
-    Math.round((params.occurredAt - latest.occurred_at) / DAY_MS2)
+    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
@@ -3215,6 +3602,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,
@@ -3564,12 +3956,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(
@@ -3582,7 +3978,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 = [];
@@ -3670,9 +4068,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(
@@ -3739,7 +4153,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."
           ),
@@ -3786,6 +4200,142 @@ var manageCommitmentTool = defineAffinityTool({
   handler: manageCommitmentToolHandler
 });
 
+// src/contacts/delete_contact.ts
+function deleteContact(db, locatorId, options) {
+  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/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/contacts/receipts.ts
 function buildContactMutationReceipt(primary, partial) {
   const normalized = normalizeMutationReceiptPartial(partial);
@@ -3812,6 +4362,101 @@ function buildMergeMutationReceipt(primary, partial) {
   };
 }
 
+// src/contacts/revise_contact.ts
+function reviseContact(db, contactId, patch) {
+  return withTransaction(db, () => {
+    const row = getContactRowById(db, contactId);
+    if (!row) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    if (row.lifecycle_state === "merged") {
+      throw new AffinityStateError("merged contact is read-only");
+    }
+    if (patch.name === void 0) {
+      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
+        updated: []
+      });
+    }
+    const name = patch.name.trim();
+    if (name.length === 0) {
+      throw new AffinityValidationError("name must be non-empty");
+    }
+    const now = resolveNow();
+    db.prepare("UPDATE contacts SET name = ?, updated_at = ? WHERE id = ?").run(
+      name,
+      now,
+      contactId
+    );
+    refreshContactRollup(db, contactId, now);
+    const next = getContactRowById(db, contactId);
+    if (!next) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
+      updated: [{ kind: "contact", id: contactId }]
+    });
+  });
+}
+
+// src/contacts/validators.ts
+function assertValidLifecycleTransition(from, to) {
+  if (from === "merged") {
+    throw new AffinityStateError("merged contact is read-only");
+  }
+  if (to === "merged") {
+    throw new AffinityInvariantError(
+      "use manage_contact merge (CLI: contact merge) to reach merged state"
+    );
+  }
+  if (from === to) {
+    return;
+  }
+  const allowed = {
+    active: ["dormant", "lost"],
+    dormant: ["active", "lost"],
+    lost: ["active"],
+    merged: []
+  };
+  if (!allowed[from].includes(to)) {
+    throw new AffinityValidationError(
+      `cannot transition from ${from} to ${to}`
+    );
+  }
+}
+
+// src/contacts/set_contact_lifecycle.ts
+var STATES2 = /* @__PURE__ */ new Set(["active", "dormant", "merged", "lost"]);
+function setContactLifecycle(db, contactId, lifecycleState, options) {
+  return withTransaction(db, () => {
+    if (!STATES2.has(lifecycleState)) {
+      throw new AffinityValidationError("invalid lifecycle state");
+    }
+    const row = getContactRowById(db, contactId);
+    if (!row) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    const from = row.lifecycle_state;
+    assertValidLifecycleTransition(from, lifecycleState);
+    const now = resolveNow(options?.now);
+    if (from === lifecycleState) {
+      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
+        updated: []
+      });
+    }
+    db.prepare(
+      "UPDATE contacts SET lifecycle_state = ?, updated_at = ? WHERE id = ?"
+    ).run(lifecycleState, now, contactId);
+    refreshContactRollup(db, contactId, now);
+    const next = getContactRowById(db, contactId);
+    if (!next) {
+      throw new AffinityNotFoundError("contact not found");
+    }
+    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
+      updated: [{ kind: "contact", id: contactId }]
+    });
+  });
+}
+
 // src/contacts/create_contact.ts
 var KINDS = /* @__PURE__ */ new Set([
   "human",
@@ -3865,96 +4510,201 @@ function createContact(db, input) {
   });
 }
 
-// src/contacts/revise_contact.ts
-function reviseContact(db, contactId, patch) {
-  return withTransaction(db, () => {
-    const row = getContactRowById(db, contactId);
-    if (!row) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    if (row.lifecycle_state === "merged") {
-      throw new AffinityStateError("merged contact is read-only");
-    }
-    if (patch.name === void 0) {
-      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
-        updated: []
-      });
-    }
-    const name = patch.name.trim();
-    if (name.length === 0) {
-      throw new AffinityValidationError("name must be non-empty");
-    }
-    const now = resolveNow();
-    db.prepare("UPDATE contacts SET name = ?, updated_at = ? WHERE id = ?").run(
-      name,
-      now,
-      contactId
-    );
-    refreshContactRollup(db, contactId, now);
-    const next = getContactRowById(db, contactId);
-    if (!next) {
-      throw new AffinityNotFoundError("contact not found");
-    }
-    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
-      updated: [{ kind: "contact", id: contactId }]
-    });
-  });
+// 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/validators.ts
-function assertValidLifecycleTransition(from, to) {
-  if (from === "merged") {
-    throw new AffinityStateError("merged contact is read-only");
-  }
-  if (to === "merged") {
-    throw new AffinityInvariantError("use mergeContacts to reach merged state");
-  }
-  if (from === to) {
-    return;
+// 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;
   }
-  const allowed = {
-    active: ["dormant", "lost"],
-    dormant: ["active", "lost"],
-    lost: ["active"],
-    merged: []
+  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
   };
-  if (!allowed[from].includes(to)) {
+}
+
+// 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(
-      `cannot transition from ${from} to ${to}`
+      `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/contacts/set_contact_lifecycle.ts
-var STATES2 = /* @__PURE__ */ new Set(["active", "dormant", "merged", "lost"]);
-function setContactLifecycle(db, contactId, lifecycleState, options) {
+// src/identities/add_identity.ts
+function addIdentity(db, contactId, input) {
   return withTransaction(db, () => {
-    if (!STATES2.has(lifecycleState)) {
-      throw new AffinityValidationError("invalid lifecycle state");
-    }
-    const row = getContactRowById(db, contactId);
-    if (!row) {
+    const contact = getContactRowById(db, contactId);
+    if (!contact) {
       throw new AffinityNotFoundError("contact not found");
     }
-    const from = row.lifecycle_state;
-    assertValidLifecycleTransition(from, lifecycleState);
-    const now = resolveNow(options?.now);
-    if (from === lifecycleState) {
-      return buildContactMutationReceipt(mapContactRowToContactListItem(row), {
-        updated: []
-      });
+    if (contact.lifecycle_state === "merged") {
+      throw new AffinityStateError("merged contact is read-only");
     }
-    db.prepare(
-      "UPDATE contacts SET lifecycle_state = ?, updated_at = ? WHERE id = ?"
-    ).run(lifecycleState, now, contactId);
-    refreshContactRollup(db, contactId, now);
-    const next = getContactRowById(db, contactId);
-    if (!next) {
-      throw new AffinityNotFoundError("contact not found");
+    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");
     }
-    return buildContactMutationReceipt(mapContactRowToContactListItem(next), {
-      updated: [{ kind: "contact", id: contactId }]
+    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;
   });
 }
 
@@ -3976,24 +4726,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(
@@ -4010,7 +4812,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",
@@ -4031,10 +4833,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",
@@ -4053,6 +4870,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."
       ),
@@ -4281,9 +5099,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;
@@ -4298,7 +5139,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(
@@ -4517,7 +5359,19 @@ function contactLocatorSchema5(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) {
@@ -4527,6 +5381,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,
@@ -4536,139 +5395,70 @@ 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 }
-    );
-  }, "Duplicate dismissal failed.");
-}
-var manageDuplicateDismissalTool = defineAffinityTool({
-  name: manageDuplicateDismissalToolName,
-  description: "Dismiss or un-dismiss a duplicate candidate pair so it does not resurface in listDuplicateCandidates.",
-  whenToUse: "Use dismiss after confirming two contacts are different people (not duplicates). Use undismiss to re-surface a pair for re-evaluation.",
-  whenNotToUse: "Do not use this to merge contacts \u2014 use merge_contacts for confirmed duplicates.",
-  sideEffects: "writes_state",
-  readOnly: false,
-  supportsClarification: true,
-  targetKinds: ["contact"],
-  inputDescriptions: {
-    action: "dismiss to suppress the pair; undismiss to re-surface it.",
-    left: "One contact of the pair.",
-    right: "The other contact of the pair.",
-    reason: "Optional reason for the dismissal (audit trail)."
-  },
-  outputDescription: "Returns the dismissal receipt with the canonical pair identifiers.",
-  inputSchema: objectSchema(
-    {
-      action: enumSchema("Action to perform.", ["dismiss", "undismiss"]),
-      left: contactLocatorSchema5(
-        "Left contact. Provide contactId or identity."
-      ),
-      right: contactLocatorSchema5(
-        "Right contact. Provide contactId or identity."
-      ),
-      reason: nullableStringSchema("Optional reason for the dismissal.")
-    },
-    ["action", "left", "right"],
-    "Dismiss or un-dismiss a duplicate candidate pair."
-  ),
-  handler: manageDuplicateDismissalToolHandler
-});
-
-// src/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 }]
-    });
-  });
+      {
+        ...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 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",
+  readOnly: false,
+  supportsClarification: true,
+  targetKinds: ["contact"],
+  inputDescriptions: {
+    action: "dismiss to suppress the pair; undismiss to re-surface it.",
+    left: "One contact of the pair.",
+    right: "The other contact of the pair.",
+    reason: "Optional reason for the dismissal (audit trail)."
+  },
+  outputDescription: "Returns the dismissal receipt with the canonical pair identifiers.",
+  inputSchema: objectSchema(
+    {
+      action: enumSchema("Action to perform.", ["dismiss", "undismiss"]),
+      left: contactLocatorSchema5(
+        "Left contact. Provide contactId or identity."
+      ),
+      right: contactLocatorSchema5(
+        "Right contact. Provide contactId or identity."
+      ),
+      reason: nullableStringSchema("Optional reason for the dismissal.")
+    },
+    ["action", "left", "right"],
+    "Dismiss or un-dismiss a duplicate candidate pair."
+  ),
+  handler: manageDuplicateDismissalToolHandler
+});
 
 // src/identities/remove_identity.ts
 function removeIdentity(db, identityId, removedAt) {
@@ -4721,6 +5511,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) {
@@ -4775,7 +5566,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"],
@@ -4785,7 +5578,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": {
@@ -4803,7 +5612,8 @@ function manageIdentityToolHandler(db, input) {
         return mutationToolResult(
           "revise",
           reviseIdentity(db, input.identityId, input.patch),
-          "identity"
+          "identity",
+          Object.keys(input.patch)
         );
       case "verify":
         return mutationToolResult(
@@ -4852,7 +5662,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."),
@@ -4866,7 +5678,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.")
         },
@@ -5085,7 +5899,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": {
@@ -5455,7 +6281,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) {
@@ -5685,7 +6520,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,
@@ -5783,7 +6627,7 @@ var recordEventTool = defineAffinityTool({
                   "observed"
                 ])
               },
-              ["contactId", "role"]
+              ["role"]
             ),
             "Participant list. Must be non-empty and include the owner contact."
           ),
@@ -5799,6 +6643,23 @@ var recordEventTool = defineAffinityTool({
   handler: recordEventToolHandler
 });
 
+// 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));
+  }
+  return { clauses, params };
+}
+
 // src/contacts/list_contacts.ts
 function listContacts(db, filters, options) {
   assertDefaultOrdering("listContacts", options);
@@ -5822,6 +6683,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,
@@ -6053,115 +6917,6 @@ function listUpcomingDates(db, filters, options) {
   return rows.map((r) => mapUpcomingRowToUpcomingDateRecord(r));
 }
 
-// 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_MS3 = 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_MS3);
-  }
-  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)
-  }));
-}
-
 // src/graph/get_affinity_chart.ts
 function getAffinityChart(db, options) {
   const contactClauses = [
@@ -6368,13 +7123,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);
@@ -6396,6 +7153,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,
@@ -6404,17 +7162,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,
@@ -6464,6 +7223,56 @@ function listDismissedDuplicates(db, options) {
   }));
 }
 
+// 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) {
@@ -6478,6 +7287,7 @@ function summarizeCount(count, singular) {
 // 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 },
@@ -6597,6 +7407,7 @@ function validateReviewInput(input) {
 }
 function duplicateCandidateItem(candidate) {
   return {
+    ...candidate,
     kind: "contact",
     id: candidate.leftContactId,
     title: `Possible duplicate: #${candidate.leftContactId} and #${candidate.rightContactId}`,
@@ -6606,24 +7417,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}`,
@@ -6633,29 +7448,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) {
@@ -6665,7 +7485,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) {
@@ -6679,6 +7508,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 },
@@ -6709,7 +7541,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;
         }
@@ -6744,7 +7576,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;
             }
@@ -6773,7 +7610,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;
             }
@@ -6866,7 +7708,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;
         }
@@ -6879,6 +7721,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"),
       {
@@ -6911,12 +7754,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.",
@@ -6953,6 +7800,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(
@@ -6975,6 +7825,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."),
@@ -7019,92 +7880,101 @@ var reviewAffinityTool = defineAffinityTool({
 });
 
 // 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;
-}
 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/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 },
@@ -7114,6 +7984,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 },
@@ -7137,7 +8010,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",
@@ -7148,6 +8021,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.",
@@ -7172,6 +8048,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."),
@@ -7199,6 +8086,94 @@ var affinityTools = [
   manageAttributeTool
 ];
 
+// src/surface/plain_dates.ts
+function parsePlainDue(raw, now = Date.now(), endOfDay = true) {
+  const invalid = () => new CliUsageError(
+    `Invalid timestamp "${raw}". Use YYYY-MM-DD, DD.MM.YYYY, today, tomorrow, yesterday, +3d, -2d or an ISO date-time.`
+  );
+  if (/^-?\d+$/.test(raw)) {
+    const value = Number(raw);
+    if (Number.isSafeInteger(value) && Number.isFinite(new Date(value).getTime()))
+      return value;
+    throw invalid();
+  }
+  const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+  const european = /^(\d{2})\.(\d{2})\.(\d{4})$/.exec(raw);
+  let date;
+  if (iso || european) {
+    const year = Number(iso?.[1] ?? european?.[3]);
+    const month = Number(iso?.[2] ?? european?.[2]);
+    const day = Number(iso?.[3] ?? european?.[1]);
+    date = /* @__PURE__ */ new Date(0);
+    date.setFullYear(year, month - 1, day);
+    date.setHours(
+      endOfDay ? 23 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 999 : 0
+    );
+    if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day)
+      throw invalid();
+  } else if (raw === "today" || raw === "tomorrow" || raw === "yesterday" || /^[+-]\d+d$/.test(raw)) {
+    date = new Date(now);
+    date.setDate(
+      date.getDate() + (raw === "today" ? 0 : raw === "tomorrow" ? 1 : raw === "yesterday" ? -1 : Number(raw.slice(0, -1)))
+    );
+    date.setHours(
+      endOfDay ? 23 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 59 : 0,
+      endOfDay ? 999 : 0
+    );
+  } else {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      raw
+    ))
+      throw invalid();
+    parsePlainDue(raw.slice(0, 10), now);
+    date = new Date(raw);
+  }
+  if (!Number.isFinite(date.getTime())) throw invalid();
+  return date.getTime();
+}
+function parsePlainStart(raw, now = Date.now()) {
+  return parsePlainDue(raw, now, false);
+}
+function normalizeTimeInputs(value, now = Date.now()) {
+  if (Array.isArray(value))
+    return value.map((item) => normalizeTimeInputs(item, now));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      typeof item === "string" && (key.endsWith("At") || ["asOf", "now"].includes(key)) ? key === "dueAt" ? parsePlainDue(item, now) : parsePlainStart(item, now) : normalizeTimeInputs(item, now)
+    ])
+  );
+}
+
+// src/surface/timestamp_schema.ts
+function acceptsString(schema) {
+  return schema.type === "string" || Array.isArray(schema.type) && schema.type.includes("string") || (schema.oneOf?.some(acceptsString) ?? false);
+}
+function timestampSchema(schema) {
+  return {
+    ...schema,
+    ...schema.properties ? {
+      properties: Object.fromEntries(
+        Object.entries(schema.properties).map(([key, value]) => [
+          key,
+          key.endsWith("At") || ["asOf", "now"].includes(key) ? acceptsString(value) ? value : {
+            description: value.description,
+            oneOf: [value, { type: "string" }]
+          } : timestampSchema(value)
+        ])
+      )
+    } : {},
+    ...schema.items ? { items: timestampSchema(schema.items) } : {},
+    ...schema.oneOf ? { oneOf: schema.oneOf.map(timestampSchema) } : {}
+  };
+}
+
 // src/surface/affinity_surface_tools.ts
 var affinitySurfaceTools = affinityTools.map((tool) => ({
   name: tool.name,
@@ -7207,8 +8182,24 @@ var affinitySurfaceTools = affinityTools.map((tool) => ({
   ...tool.whenNotToUse === void 0 ? {} : { whenNotToUse: tool.whenNotToUse },
   readOnly: tool.readOnly,
   sideEffects: tool.sideEffects,
-  inputSchema: { ...tool.inputSchema, type: "object" },
-  handler: tool.handler
+  inputSchema: {
+    ...timestampSchema({ ...tool.inputSchema, type: "object" }),
+    type: "object"
+  },
+  handler: (db, input) => {
+    try {
+      return tool.handler(db, normalizeTimeInputs(input));
+    } catch (error) {
+      if (error instanceof CliUsageError)
+        return toolFailure(
+          "protocol",
+          "invalid_input",
+          "Invalid input.",
+          error.message
+        );
+      throw error;
+    }
+  }
 }));
 
 // src/surface/affinity_mcp_options.ts
@@ -7490,6 +8481,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)"
   );
@@ -7681,7 +8678,8 @@ async function openAffinityDb(path) {
   }
 }
 function resolveAffinityDbPath(options = {}) {
-  return options.flag ?? ((options.env ?? process.env).GHOSTPAW_AFFINITY_DB || node_path.join(node_os.homedir(), ".ghostpaw", "affinity.db"));
+  const path = options.flag ?? ((options.env ?? process.env).GHOSTPAW_AFFINITY_DB || node_path.join(node_os.homedir(), ".ghostpaw", "affinity.db"));
+  return path === ":memory:" ? path : node_path.resolve(path);
 }
 
 // src/surfaces/surface_types.ts
@@ -7908,10 +8906,10 @@ async function serveMcpStdio(server, options = {}) {
     const response = await server.handleLine(line.replace(/\r$/, ""));
     if (response !== void 0)
       await new Promise(
-        (resolve, reject) => output.write(
+        (resolve2, reject) => output.write(
           `${response}
 `,
-          (error) => error ? reject(error) : resolve()
+          (error) => error ? reject(error) : resolve2()
         )
       );
   };