ei-tui 1.6.9 → 1.7.1

package/src/cli.ts

@@ -17,6 +17,9 @@ import type { StorageState } from "./core/types";
 import { resolvePersonaId, filterByPersona, filterTypeSpecificByPersona, filterBySource, filterTypeSpecificBySource } from "./cli/persona-filter.js";
 import { installMcpClients } from "./cli/install.js";
 import { getRecentSessionMessages } from "./cli/session-context.js";
+import { createEntity, updateEntity, removeEntity, CorrectionValidationError, CORRECTABLE_TYPES, UPDATABLE_TYPES } from "./cli/corrections-endpoints.js";
+import { createPersonaEntity, updatePersonaEntity, removePersonaEntity } from "./cli/persona-corrections.js";
+import type { CorrectableType } from "./core/corrections.js";
 import pkg from "../package.json" assert { type: "json" };
 
 const rawArgs = process.argv.slice(2);
@@ -38,6 +41,39 @@ const TYPE_ALIASES: Record<string, string> = {
   personas: "personas",
 };
 
+// Wider set accepted by `ei create/update/remove persona` — corrections-endpoints.ts's
+// CORRECTABLE_TYPES/UPDATABLE_TYPES intentionally stay persona-free (personas bypass
+// that module's shared SCHEMAS dispatch entirely, see persona-corrections.ts), so this
+// CLI-only layer is what actually widens the accepted type set.
+const CLI_CORRECTABLE_TYPES = [...CORRECTABLE_TYPES, "persona"] as const;
+const CLI_UPDATABLE_TYPES = [...UPDATABLE_TYPES, "persona"] as const;
+
+// Singular CorrectableType resolution for `ei create/update/remove` — derived
+// from TYPE_ALIASES + CLI_CORRECTABLE_TYPES so the two alias systems can never
+// silently diverge on which strings are accepted (e.g. "person"/"people"
+// stay synonymous here too, since both funnel through TYPE_ALIASES first).
+const PLURAL_TO_CORRECTABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_CORRECTABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+
+function resolveCorrectableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_CORRECTABLE[plural] ?? null : null;
+}
+
+// Plural CorrectableType resolution for `ei update` — same TYPE_ALIASES
+// lookup as resolveCorrectableType above, but sourced from CLI_UPDATABLE_TYPES
+// instead of CLI_CORRECTABLE_TYPES since quotes are correctable via update
+// (repointing data_item_ids after a split/merge, fixing mistranscribed
+// text) but never created or removed.
+const PLURAL_TO_UPDATABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_UPDATABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+function resolveUpdatableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_UPDATABLE[plural] ?? null : null;
+}
+
 function printHelp(): void {
   console.log(`
 Ei
@@ -55,6 +91,9 @@ Usage:
   ei --id <id>                  Look up a specific entity by ID
   echo <id> | ei --id           Look up entity by ID from stdin
   ei mcp                        Start the Ei MCP stdio server (for Claude Code/Cursor/Codex)
+  ei create <type> --json '<json>'  Create a new entity (fact/topic/person/persona)
+  ei update <type> <id> --json '<json>'  Replace an entity by ID (full record, not a patch; fact/topic/person/quote/persona)
+  ei remove <type> <id>         Remove an entity by ID (fact/topic/person/persona; not quotes)
 
 Types:
   quote / quotes      Quotes from conversation history
@@ -69,12 +108,13 @@ Options:
   --persona, -p       Filter to entities a specific persona has learned about
   --source, -s        Filter to entities from a specific source (prefix match, e.g. "cursor", "codex:my-machine", "opencode:my-machine:ses_abc123")
   --id                Look up entity by ID (accepts value or stdin)
-  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks where supported)
+  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks + skills where supported)
   --sync              Pull latest state from remote sync server into state.backup.json (no TUI required)
   --session <id>      Session ID to enrich the query with recent context (use with --hook-source)
   --hook-source <src> Source of the hook: "opencode-plugin" (OpenCode SQLite), "cursor", or "codex"
   --transcript <path> Path to a Claude Code JSONL transcript file for context enrichment
   --help, -h          Show this help message
+  --json <json>       JSON body for create/update (full record for update, not a patch)
 
 Examples:
   ei "debugging"                         # Search everything
@@ -86,6 +126,13 @@ Examples:
   ei topics --source cursor "X"          # Topics learned from Cursor sessions
   ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
+  ei create fact --json '{"name":"Field of Study","description":"CS","sentiment":0,"validated_date":""}'
+  ei update fact abc-123 --json '{"name":"Field of Study","description":"Updated","sentiment":0,"validated_date":""}'
+  ei update quote <id> --json '{"data_item_ids":["person-b-id"], ...}'  # Repoint a quote after splitting a bad merge (fetch the full record via 'ei --id <id>' first)
+  ei create persona --json '{"display_name":"Yoda","long_description":"Speaks in inverted syntax, wise and patient.","traits":[{"name":"Inverted speech","description":"Talks like Yoda","sentiment":0.7}],"topics":[]}'
+  ei update persona <id> --json '<full persona record from ei --id <id>, edited>'
+  ei remove persona abc-123              # Remove a persona (reserved personas like "ei"/"emmet" must be archived instead)
+  ei remove fact abc-123                 # Remove a fact by ID
 `);
 }
 
@@ -146,6 +193,89 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  if (args[0] === "create") {
+    const rawType = args[1];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType) {
+      console.error(`ei create requires a valid type (${CLI_CORRECTABLE_TYPES.join(", ")}). Got: ${rawType ?? "(none)"}`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei create requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const result = entityType === "persona" ? await createPersonaEntity(body) : await createEntity(entityType, body);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "update") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveUpdatableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei update <type> <id> --json '<json>' (types: ${CLI_UPDATABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei update requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const record = entityType === "persona" ? await updatePersonaEntity(id, body) : await updateEntity(entityType, id, body);
+      console.log(JSON.stringify(record, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "remove") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei remove <type> <id> (types: ${CLI_CORRECTABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    try {
+      if (entityType === "persona") {
+        await removePersonaEntity(id);
+      } else {
+        await removeEntity(entityType, id);
+      }
+      console.log(JSON.stringify({ removed: true, id }, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
+  }
+
   if (args[0] === "--sync") {
     const { getDataPath } = await import("./cli/retrieval.js");
     const { RemoteSync } = await import("./storage/remote.js");

package/src/core/corrections.ts

@@ -0,0 +1,233 @@
+/**
+ * Corrections Queue — external write path for CLI/MCP tools.
+ *
+ * Ei's CLI and MCP server are read-only against a snapshot of state.json —
+ * they never hold the live StateManager the running TUI/daemon owns, so
+ * they can't safely mutate state.json directly (the running instance's
+ * next debounced save would silently clobber the write with its stale
+ * in-memory copy).
+ *
+ * corrections.json is the queue that closes this gap. External writers
+ * (ei_update / ei_create / ei_remove) append fully-formed CorrectionRecords
+ * here under an advisory lock. Two consumers drain it:
+ *   - The running Processor, once per runLoop tick (near-instant, ~100ms).
+ *   - The CLI itself, self-draining directly into state.json when it
+ *     detects no live instance is running (see src/cli/corrections-io.ts).
+ *
+ * Every CorrectionRecord is a complete, ready-to-apply entity — including
+ * a pre-computed embedding and (for creates) a pre-assigned id — so
+ * draining is a pure apply, never a fetch-then-merge.
+ */
+
+import type { HumanEntity, Fact, Topic, Person, Quote, PersonaEntity, StorageState } from "./types.js";
+import { isReservedPersonaId } from "./types.js";
+import { withLock, atomicWrite } from "../storage/file-lock.js";
+
+export type CorrectableType = "fact" | "topic" | "person" | "quote" | "persona";
+export type CorrectableEntity = Fact | Topic | Person | Quote | PersonaEntity;
+export const CORRECTABLE_TYPES: CorrectableType[] = ["fact", "topic", "person", "quote", "persona"];
+
+export interface CorrectionUpsert {
+  op: "upsert";
+  entity_type: CorrectableType;
+  id: string;
+  record: CorrectableEntity;
+  timestamp: string;
+}
+
+export interface CorrectionRemove {
+  op: "remove";
+  entity_type: CorrectableType;
+  id: string;
+  timestamp: string;
+}
+
+export type CorrectionRecord = CorrectionUpsert | CorrectionRemove;
+
+/**
+ * Runtime shape validation for a CorrectionRecord read back from
+ * corrections.json. The TypeScript union is compile-time only — every
+ * record actually enters the system via `JSON.parse(...) as CorrectionRecord`
+ * in readCorrections(), so a malformed-but-valid-JSON record (bad `op`,
+ * mismatched `record.id`, missing `record` on an upsert) is otherwise
+ * silently trusted. Both consumers (CLI read-merge/self-drain via
+ * applyCorrectionToHuman, and Processor.applyCorrectionRecord) call this
+ * before mutating anything — it throws, never coerces, so a malformed `op`
+ * can never be silently treated as its sibling operation.
+ */
+export function assertValidCorrection(value: unknown): asserts value is CorrectionRecord {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Malformed correction record: expected an object, got ${JSON.stringify(value)}`);
+  }
+  if (!("op" in value) || (value.op !== "upsert" && value.op !== "remove")) {
+    throw new Error(`Malformed correction record: op must be "upsert" or "remove", got ${JSON.stringify("op" in value ? value.op : undefined)}`);
+  }
+  if (!("entity_type" in value) || !CORRECTABLE_TYPES.includes(value.entity_type as CorrectableType)) {
+    throw new Error(`Malformed correction record: entity_type must be one of ${CORRECTABLE_TYPES.join(", ")}, got ${JSON.stringify("entity_type" in value ? value.entity_type : undefined)}`);
+  }
+  if (!("id" in value) || typeof value.id !== "string" || value.id.length === 0) {
+    throw new Error(`Malformed correction record: id must be a non-empty string, got ${JSON.stringify("id" in value ? value.id : undefined)}`);
+  }
+  if (value.op === "upsert") {
+    if (!("record" in value) || !value.record || typeof value.record !== "object") {
+      throw new Error(`Malformed correction record: upsert requires a record object`);
+    }
+    if (!("id" in value.record) || value.record.id !== value.id) {
+      throw new Error(`Malformed correction record: record.id (${JSON.stringify("id" in value.record ? value.record.id : undefined)}) must equal wrapper id (${JSON.stringify(value.id)})`);
+    }
+  }
+}
+
+/**
+ * Read pending corrections without a lock. Returns [] if the file doesn't
+ * exist or is empty. fs/promises is imported dynamically, not statically —
+ * this module is transitively bundled into Web's browser build via
+ * src/core/processor.ts, and a static `import { readFile } from "fs/promises"`
+ * fails Vite's rollup build (no named exports on the browser-externalized
+ * stub), not just at runtime.
+ */
+export async function readCorrections(correctionsPath: string): Promise<CorrectionRecord[]> {
+  const { readFile } = await import(/* @vite-ignore */ "fs/promises");
+  let text: string;
+  try {
+    text = await readFile(correctionsPath, "utf-8");
+  } catch {
+    return [];
+  }
+  if (!text) return [];
+  return JSON.parse(text) as CorrectionRecord[];
+}
+
+/**
+ * Append one correction under lock (read-modify-write — corrections.json
+ * is a JSON array, not an append-only log, so concurrent writers must
+ * serialize through the same lock rather than racing on a blind append).
+ */
+export async function appendCorrection(
+  correctionsPath: string,
+  record: CorrectionRecord
+): Promise<void> {
+  await withLock(correctionsPath, async () => {
+    const existing = await readCorrections(correctionsPath);
+    existing.push(record);
+    await atomicWrite(correctionsPath, JSON.stringify(existing, null, 2));
+  });
+}
+
+/**
+ * Merge a person's `name` from its primary identifier, replicating the
+ * invariant HumanState.person_upsert enforces on the live-write path
+ * (CONTRACTS.md "Person Identifiers — name Sync Rule"). Both consumers of
+ * this module (Live's StateManager and the CLI's self-drain) must produce
+ * an identical HumanEntity for a given corrections.json, so the formula
+ * is centralized here rather than re-derived at each call site.
+ */
+function syncPersonName(person: Person): Person {
+  const identifiers = person.identifiers ?? [];
+  const primary = identifiers.find((i) => i.is_primary) ?? identifiers[0];
+  return primary ? { ...person, name: primary.value } : person;
+}
+
+/**
+ * Resolve the target array for a CorrectableType. Throws on anything
+ * other than the 4 known types — corrections.json is external input from
+ * CLI/MCP tools (potentially LLM-driven), and a malformed entity_type must
+ * never silently fall through to the people array. Live's Processor
+ * already enforces this (applyCorrectionRecord); this is the equivalent
+ * guard for the CLI read-merge and self-drain paths.
+ */
+function getCorrectableArray(human: HumanEntity, entityType: string): Array<{ id: string }> {
+  if (entityType === "fact") return human.facts;
+  if (entityType === "topic") return human.topics;
+  if (entityType === "person") return human.people;
+  if (entityType === "quote") return human.quotes;
+  throw new Error(`Unrecognized correction entity_type: ${entityType}`);
+}
+
+/**
+ * Apply one correction to a HumanEntity in place, mirroring the exact
+ * upsert/remove semantics of HumanState (src/core/state/human.ts) —
+ * replace-by-id for upsert, splice + orphaned quote-reference cleanup for
+ * remove (for all 3 types, matching fact_remove/topic_remove/person_remove
+ * in HumanState — not just person). Used by both the CLI's read-merge
+ * (materializing a corrected view without a StateManager) and its
+ * self-drain (writing corrections straight into state.json when no live
+ * instance is running).
+ */
+export function applyCorrectionToHuman(human: HumanEntity, correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  const array = getCorrectableArray(human, correction.entity_type);
+
+  if (correction.op === "remove") {
+    const idx = array.findIndex((item) => item.id === correction.id);
+    if (idx < 0) return;
+    array.splice(idx, 1);
+    human.quotes.forEach((q) => {
+      q.data_item_ids = q.data_item_ids.filter((itemId) => itemId !== correction.id);
+    });
+    human.last_updated = new Date().toISOString();
+    return;
+  }
+
+  const record = correction.entity_type === "person"
+    ? syncPersonName(correction.record as Person)
+    : correction.record;
+  const idx = array.findIndex((item) => item.id === correction.id);
+  if (idx >= 0) {
+    array[idx] = record;
+  } else {
+    array.push(record);
+  }
+  human.last_updated = new Date().toISOString();
+}
+
+/** Apply every pending correction to a HumanEntity, in file order (later records for the same id win). */
+export function applyCorrectionsToHuman(human: HumanEntity, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToHuman(human, correction);
+  }
+}
+
+/**
+ * Apply one correction to a StorageState's personas map in place. Personas
+ * live outside HumanEntity — src/core/types/integrations.ts's StorageState.personas
+ * is a top-level `Record<id, {entity, messages}>` — so they need their own
+ * apply function rather than routing through getCorrectableArray/
+ * applyCorrectionToHuman, which only ever resolve arrays on HumanEntity.
+ *
+ * The reserved-persona delete guard here is defense-in-depth for a
+ * hand-edited corrections.json: the primary guard is the SYNCHRONOUS check
+ * in src/cli/persona-corrections.ts's removePersonaEntity, which runs
+ * before a correction is ever queued (so a live-drained rejection here can
+ * never surface as a silent no-op after an apparent CLI success).
+ */
+export function applyCorrectionToPersonas(personas: StorageState["personas"], correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  if (correction.op === "remove") {
+    if (isReservedPersonaId(correction.id)) {
+      throw new Error(`Cannot delete reserved persona "${correction.id}". Use archive instead.`);
+    }
+    delete personas[correction.id];
+    return;
+  }
+  personas[correction.id] = {
+    entity: correction.record as PersonaEntity,
+    messages: personas[correction.id]?.messages ?? [],
+  };
+}
+
+/** Route one correction to its target: the personas map for entity_type "persona", the HumanEntity for everything else. */
+export function applyCorrectionToState(state: StorageState, correction: CorrectionRecord): void {
+  if (correction.entity_type === "persona") {
+    applyCorrectionToPersonas(state.personas, correction);
+  } else {
+    applyCorrectionToHuman(state.human, correction);
+  }
+}
+
+/** Apply every pending correction to a StorageState, in file order (later records for the same id win). */
+export function applyCorrectionsToState(state: StorageState, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToState(state, correction);
+  }
+}

package/src/core/handlers/human-extraction.ts

@@ -14,6 +14,9 @@ import { BUILT_IN_FACT_NAMES } from "../constants/built-in-facts.js";
 import { getEmbeddingService, getItemEmbeddingText, cosineSimilarity, getPersonEmbeddingText } from "../embedding-service.js";
 import { levenshtein, normalizeForMatch } from "../utils/levenshtein.js";
 
+export type PersonMatchStrength = 'strong' | 'weak';
+export interface PersonMatch { person: Person; strength: PersonMatchStrength; }
+
 const MULTI_MATCH_SIMILARITY_THRESHOLD = 0.75;
 const ZERO_MATCH_COSINE_THRESHOLD = 0.80;
 
@@ -27,13 +30,25 @@ const SINGLETON_RELATIONSHIPS = new Set([
   'father', 'mother',
 ]);
 
+function sharesNameToken(normalizedCandidateName: string, person: Person): boolean {
+  const candidateTokens = new Set(normalizedCandidateName.split(/\s+/).filter(t => t.length >= 3));
+  if (candidateTokens.size === 0) return false;
+  const personStrings = [normalizeForMatch(person.name), ...(person.identifiers ?? []).map(i => normalizeForMatch(i.value))];
+  for (const s of personStrings) {
+    for (const tok of s.split(/\s+/)) {
+      if (tok.length >= 3 && candidateTokens.has(tok)) return true;
+    }
+  }
+  return false;
+}
+
 function matchPersonCandidate(
   candidateName: string,
   candidateIdentifiers: PersonIdentifier[],
   people: Person[]
-): Person[] {
+): PersonMatch[] {
   const normName = normalizeForMatch(candidateName);
-  const matched = new Set<Person>();
+  const matched = new Map<Person, PersonMatchStrength>();
 
   // Step 1: Exact match on any identifier value (type-agnostic)
   for (const person of people) {
@@ -41,19 +56,24 @@ function matchPersonCandidate(
       ...(person.identifiers ?? []).map(i => normalizeForMatch(i.value)),
       normalizeForMatch(person.name),
     ];
-    if (allValues.includes(normName)) matched.add(person);
+    if (allValues.includes(normName)) matched.set(person, 'strong');
   }
   // Also check scan-extracted identifiers against existing identifier values
   for (const scanId of candidateIdentifiers) {
     const normVal = normalizeForMatch(scanId.value);
     for (const person of people) {
       if ((person.identifiers ?? []).some(i => normalizeForMatch(i.value) === normVal)) {
-        matched.add(person);
+        // Corroboration gate (#78 C1): a scan-extracted identifier only STRONG-binds when the
+        // candidate's name shares a token with the match. A bare identifier hit with zero name
+        // overlap is the cross-attribution signature (one person's handle on another's record),
+        // so it drops to WEAK and must clear the cosine gate — or become a new record.
+        const strength: PersonMatchStrength = sharesNameToken(normName, person) ? 'strong' : 'weak';
+        if (matched.get(person) !== 'strong') matched.set(person, strength);
       }
     }
   }
 
-  if (matched.size > 0) return [...matched];
+  if (matched.size > 0) return [...matched].map(([person, strength]) => ({ person, strength }));
 
   // Step 2: Fuzzy match — skip for short names (< 6 chars): "mike"↔"jake" = 2 edits, false positive.
   if (normName.length >= 6) {
@@ -63,11 +83,11 @@ function matchPersonCandidate(
         ...(person.identifiers ?? []).map(i => normalizeForMatch(i.value)),
         normalizeForMatch(person.name),
       ];
-      if (allValues.some(v => levenshtein(normName, v) <= threshold)) matched.add(person);
+      if (allValues.some(v => levenshtein(normName, v) <= threshold)) matched.set(person, 'weak');
     }
   }
 
-  if (matched.size > 0) return [...matched];
+  if (matched.size > 0) return [...matched].map(([person, strength]) => ({ person, strength }));
 
   // Step 2.5: First-name match — "Lucas Jeremy Scherer" should find "Lucas".
   // Only fires when first word is >= 4 chars to avoid short-name collisions.
@@ -78,11 +98,11 @@ function matchPersonCandidate(
         normalizeForMatch(person.name),
         ...(person.identifiers ?? []).map(i => normalizeForMatch(i.value)),
       ];
-      if (allNames.some(n => n.split(/\s+/)[0] === candidateFirstWord)) matched.add(person);
+      if (allNames.some(n => n.split(/\s+/)[0] === candidateFirstWord)) matched.set(person, 'weak');
     }
   }
 
-  return [...matched];
+  return [...matched].map(([person, strength]) => ({ person, strength }));
 }
 
 export async function handleFactFind(response: LLMResponse, state: StateManager): Promise<void> {
@@ -182,6 +202,27 @@ export async function handleHumanTopicScan(response: LLMResponse, state: StateMa
   console.log(`[handleHumanTopicScan] Queued ${result.topics.length} topic(s) for matching`);
 }
 
+async function confirmMatchByCosine(
+  person: Person,
+  candidate: { name: string; relationship?: string; description?: string },
+  threshold: number
+): Promise<Person | null> {
+  if (!person.embedding || person.embedding.length === 0) return null;
+  try {
+    const embeddingService = getEmbeddingService();
+    const candidateVector = await embeddingService.embed(getPersonEmbeddingText({
+      name: candidate.name, relationship: candidate.relationship, description: candidate.description,
+    }));
+    const sim = cosineSimilarity(person.embedding, candidateVector);
+    if (sim >= threshold) return person;
+    console.debug(`[handleHumanPersonScan] Weak single-match "${candidate.name}" → "${person.name}" rejected (cosine ${sim.toFixed(3)} < ${threshold}) — new record`);
+    return null;
+  } catch (err) {
+    console.warn(`[handleHumanPersonScan] Weak-match cosine failed for "${candidate.name}":`, err);
+    return null;
+  }
+}
+
 export async function handleHumanPersonScan(response: LLMResponse, state: StateManager): Promise<void> {
   const result = response.parsed as PersonScanResult | undefined;
   
@@ -213,7 +254,12 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
     let matchedPerson: Person | null = null;
 
     if (matches.length === 1) {
-      matchedPerson = matches[0];
+      const { person, strength } = matches[0];
+      if (strength === 'strong') {
+        matchedPerson = person;
+      } else {
+        matchedPerson = await confirmMatchByCosine(person, candidate, MULTI_MATCH_SIMILARITY_THRESHOLD);
+      }
     } else if (matches.length > 1) {
       try {
         const embeddingService = getEmbeddingService();
@@ -224,7 +270,7 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
         });
         const candidateVector = await embeddingService.embed(candidateText);
         let bestSimilarity = MULTI_MATCH_SIMILARITY_THRESHOLD;
-        for (const person of matches) {
+        for (const { person } of matches) {
           if (person.embedding) {
             const sim = cosineSimilarity(person.embedding, candidateVector);
             if (sim > bestSimilarity) {
@@ -238,7 +284,7 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
         }
       } catch (err) {
         console.warn(`[handleHumanPersonScan] Multi-match embedding failed for "${candidate.name}", using first match:`, err);
-        matchedPerson = matches[0];
+        matchedPerson = matches[0].person;
       }
     } else {
       // Step 3: relationship filter → uniqueness match or cosine on the relevant subset.
@@ -253,10 +299,13 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
         const normExistingName = normalizeForMatch(existing.name);
         const isUnknownPlaceholder = normExistingName === 'unknown' || normExistingName === normRel;
         const isSingleton = SINGLETON_RELATIONSHIPS.has(normRel!);
-        if (isUnknownPlaceholder || isSingleton) {
+        if (isSingleton) {
           matchedPerson = existing;
-          const reason = isUnknownPlaceholder ? 'unnamed placeholder' : 'singleton relationship';
-          console.debug(`[handleHumanPersonScan] Relationship unique match: "${candidate.name}" → "${existing.name}" (sole ${candidate.relationship}, ${reason})`);
+          console.debug(`[handleHumanPersonScan] Relationship unique match: "${candidate.name}" → "${existing.name}" (sole ${candidate.relationship}, singleton relationship)`);
+        } else if (isUnknownPlaceholder) {
+          // M1 (deferred, #78): a placeholder with no embedding cannot be confirmed here and will fork a new record instead of promoting. Acceptable under the dupe-tolerant policy; revisit with embedding backfill.
+          matchedPerson = await confirmMatchByCosine(existing, candidate, ZERO_MATCH_COSINE_THRESHOLD);
+          console.debug(`[handleHumanPersonScan] Relationship unique match gated by cosine: "${candidate.name}" → "${existing.name}" (sole ${candidate.relationship}, unnamed placeholder) — ${matchedPerson ? 'confirmed' : 'rejected, new record'}`);
         }
       } else {
         // N>1 same relationship → cosine within that subset.

package/src/core/handlers/human-matching.ts

@@ -282,7 +282,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         value: i.value,
         ...(i.is_primary ? { is_primary: i.is_primary } : {}),
       })),
-      state
+      state.persona_getAll()
     );
     const allCandidateIds = [...llmIdentifiers, ...candidateIdentifiers];
     if (allCandidateIds.length === 0) {
@@ -303,7 +303,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         ...i,
         type: normalizeIdentifierType(i.type, state),
       })),
-      state
+      state.persona_getAll()
     );
     for (const id of sanitizedToAdd) {
       if (!base.some(e => e.value === id.value)) {

package/src/core/orchestrators/human-extraction.ts

@@ -607,17 +607,6 @@ export function queuePersonUpdate(
 
   const candidateIdentifiers = context.candidateIdentifiers ?? [];
 
-  if (!isNewItem && existingItem && candidateIdentifiers.length > 0) {
-    const merged = [...(existingItem.identifiers ?? [])];
-    for (const ci of candidateIdentifiers) {
-      if (!merged.some(ei => ei.value === ci.value)) {
-        merged.push(ci);
-      }
-    }
-    existingItem = { ...existingItem, identifiers: merged };
-    state.human_person_upsert(existingItem);
-  }
-
   const userIdentifierTypes = [...new Set(
     state.getHuman().people
       .flatMap(p => (p.identifiers ?? []).map(i => i.type))
@@ -642,6 +631,7 @@ export function queuePersonUpdate(
       persona_name: chunk.channelDisplayName,
       participant_context: buildParticipantContext(primaryPersonaIdForUpdate, state),
       known_identifier_types: userIdentifierTypes,
+      suggested_identifiers: !isNewItem ? candidateIdentifiers : undefined,
     });
 
     state.queue_enqueue({

package/src/core/persona-manager.ts

@@ -128,15 +128,26 @@ export async function updatePersona(
   const persona = sm.persona_getById(personaId);
   if (!persona) return false;
 
-  if ('long_description' in updates) {
-    const merged = { ...persona, ...updates };
-    const embedding = await computePersonaDescriptionEmbedding(merged);
-    if (embedding) {
-      updates = { ...updates, description_embedding: embedding };
-    }
-  }
+  const shouldRefreshDescriptionEmbedding = 'long_description' in updates;
+  const mergedForEmbedding = shouldRefreshDescriptionEmbedding
+    ? { ...persona, ...updates }
+    : null;
 
   sm.persona_update(personaId, updates);
+
+  if (shouldRefreshDescriptionEmbedding && mergedForEmbedding) {
+    void computePersonaDescriptionEmbedding(mergedForEmbedding).then((embedding) => {
+      if (!embedding) return;
+      const current = sm.persona_getById(personaId);
+      if (!current) return;
+      if (
+        current.long_description !== mergedForEmbedding.long_description ||
+        current.short_description !== mergedForEmbedding.short_description
+      ) return;
+      sm.persona_update(personaId, { description_embedding: embedding });
+    });
+  }
+
   return true;
 }