zara-contacts: person and recipient identity resolution #17

New issue

Closed

opened 2026-08-31 18:44:34 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-31 18:44:34 +00:00

(Migrated from github.com)

Plugin

zara-contacts

Goal

Provide Zara with a normalized contact/person domain so other plugins can resolve names to emails, phone numbers and provider identities without duplicating identity logic.

Domain model

Represent:

person/contact stable ID;
display/preferred names and aliases;
email addresses;
phone numbers;
organizations/roles;
provider-specific handles/account IDs;
source/provenance and confidence for inferred matches.

Tool surface

search contacts by name/alias/address/org;
get contact details;
resolve a recipient for a requested channel;
list ambiguous candidates rather than guessing;
create/update local contact records where an adapter allows explicit writes.

Integrations

zara-comms and zara-calendar should consume this plugin for recipient/attendee resolution. zara-memory may retain relationship/context facts, but this plugin owns addressable identity records.

Safety / privacy

no automatic merge of ambiguous identities;
provider writes are explicit;
normalize and validate addresses/numbers;
sensitive contact data is not dumped into logs;
source/provenance survives merges/imports.

Acceptance criteria

normalized person/contact schema exists
aliases and multiple addresses/handles are representable
ambiguous resolution returns candidates instead of guessing
provider adapter boundary is documented
provenance is preserved
tests use fixtures only and require no live accounts/network
README documents identity/merge semantics
registry validation, plugin tests and nix flake check pass

## Plugin `zara-contacts` ## Goal Provide Zara with a normalized contact/person domain so other plugins can resolve names to emails, phone numbers and provider identities without duplicating identity logic. ## Domain model Represent: - person/contact stable ID; - display/preferred names and aliases; - email addresses; - phone numbers; - organizations/roles; - provider-specific handles/account IDs; - source/provenance and confidence for inferred matches. ## Tool surface - search contacts by name/alias/address/org; - get contact details; - resolve a recipient for a requested channel; - list ambiguous candidates rather than guessing; - create/update local contact records where an adapter allows explicit writes. ## Integrations `zara-comms` and `zara-calendar` should consume this plugin for recipient/attendee resolution. `zara-memory` may retain relationship/context facts, but this plugin owns addressable identity records. ## Safety / privacy - no automatic merge of ambiguous identities; - provider writes are explicit; - normalize and validate addresses/numbers; - sensitive contact data is not dumped into logs; - source/provenance survives merges/imports. ## Acceptance criteria - [ ] normalized person/contact schema exists - [ ] aliases and multiple addresses/handles are representable - [ ] ambiguous resolution returns candidates instead of guessing - [ ] provider adapter boundary is documented - [ ] provenance is preserved - [ ] tests use fixtures only and require no live accounts/network - [ ] README documents identity/merge semantics - [ ] registry validation, plugin tests and `nix flake check` pass