feat(memory): add the people domain and carve out the inert diff types

Cargo.toml

@@ -79,6 +79,22 @@ wiki-git = ["dep:git2", "dep:hex"]
 # about (its `obsidian.json` registry).
 obsidian = ["dep:dirs"]
 
+# Contact resolution and scoring (`memory::people`): a SQLite store of people,
+# handle aliases and interactions, a deterministic handle → `PersonId` resolver,
+# and a recency × frequency × reciprocity × depth scorer.
+#
+# Implies `tokio` because the store shares its connection as an
+# `Arc<tokio::sync::Mutex<Connection>>` across tasks. It adds no other
+# dependency — `rusqlite`, `chrono`, `uuid` and `serde` are already core.
+people = ["tokio"]
+
+# The macOS system address book (`memory::people::address_book`) as a seed
+# source for the people store. Gated on the target *and* this feature: the four
+# objc2 crates it needs are macOS-only and are not worth compiling for a host
+# that never seeds from Contacts. Off (or non-macOS) leaves a stub that returns
+# an empty contact list, so a refresh seeds nothing rather than failing.
+contacts = ["people", "dep:objc2", "dep:objc2-foundation", "dep:objc2-contacts", "dep:block2"]
+
 [dependencies]
 anyhow = "1"
 log = "0.4"
@@ -144,6 +160,28 @@ tokio = { version = "1", features = [
     "net",
 ], optional = true }
 
+# macOS system address book, read by `memory::people::address_book` behind the
+# `contacts` feature. Declared under a `cfg(target_os = "macos")` target table
+# so these never enter a Linux or Windows dependency graph at all — the feature
+# is a no-op there and the module falls back to its empty-contacts stub.
+[target.'cfg(target_os = "macos")'.dependencies]
+objc2 = { version = "0.6", optional = true }
+objc2-foundation = { version = "0.3", features = [
+    "NSArray",
+    "NSError",
+    "NSObject",
+    "NSString",
+    "NSPredicate",
+], optional = true }
+objc2-contacts = { version = "0.3.2", features = [
+    "CNContact",
+    "CNContactFetchRequest",
+    "CNContactStore",
+    "CNLabeledValue",
+    "CNPhoneNumber",
+], optional = true }
+block2 = { version = "0.6", optional = true }
+
 [dev-dependencies]
 dotenvy = "0.15"
 tempfile = "3"

src/memory/mod.rs

@@ -107,6 +107,19 @@ pub mod providers;
 /// the git-history reader additionally requires `git-diff`.
 #[cfg(feature = "persona")]
 pub mod persona;
+
+/// Contact resolution and scoring: a SQLite store of people, handle aliases and
+/// interactions, a deterministic (handle | email | display name) → `PersonId`
+/// resolver, and a recency × frequency × reciprocity × depth scorer.
+///
+/// Gated behind the default-off `people` feature, which implies `tokio` — the
+/// store shares its connection across tasks. The macOS address-book seed
+/// source additionally requires `contacts`.
+///
+/// This is storage, so it belongs to the engine rather than to the memory
+/// contract: an engine bound in TinyCortex's place brings its own.
+#[cfg(feature = "people")]
+pub mod people;
 // ── Re-exports ──────────────────────────────────────────────────────────────
 pub use config::{MemoryConfig, WeightProfile};
 pub use error::{MemoryEngineResult, MemoryError as MemoryEngineError};

src/memory/people/README.md

@@ -0,0 +1,85 @@
+# people
+
+Contact resolution + relationship scoring (the "A5" module). Maps any of three handle kinds — iMessage handle, email, or display name — to a single stable `PersonId`, and ranks known people by a deterministic composite score (recency × frequency × reciprocity × depth) derived from observed interaction rows. Backed by its own SQLite database (people / handle aliases / interactions). Can seed itself from the macOS system Address Book (`CNContactStore`). Intentionally self-contained — per its module docstring it has no dependency on `life_capture`, `chronicle`, `nudges`, or UI; downstream integration is left to later slices.
+
+## Responsibilities
+
+- Canonicalize handles (lowercase/trim emails + email-style iMessage handles; whitespace-collapse display names) so the same person resolves consistently across case and spacing.
+- Deterministically resolve a `Handle` to an existing `PersonId`, or mint a new `Person` skeleton on first sight (`create_if_missing`).
+- Link handles together (`link`) so an email + phone + display name can be attached to one person — without ever *auto*-merging distinct identities that share only a display name or an unverified handle.
+- Record interactions and aggregate them into a per-person composite score plus an explainable component breakdown.
+- Rank all known people by score for `people.list`.
+- Seed the store from the macOS Address Book, distinguishing "permission denied" from "no contacts".
+- Persist people, handle aliases, and interactions in a dedicated SQLite DB with idempotent migrations.
+
+## Key files
+
+| File | Role |
+| --- | --- |
+| `src/openhuman/memory/people/mod.rs` | Export-focused. Declares submodules and re-exports `all_people_controller_schemas` / `all_people_registered_controllers`. |
+| `src/openhuman/memory/people/types.rs` | Domain types: `PersonId`, `Handle` (with `canonicalize` / `as_key`), `Person`, `Interaction`, `ScoreComponents`, `AddressBookContact`. |
+| `src/openhuman/memory/people/resolver.rs` | `HandleResolver` — `resolve`, `resolve_or_create(_with_status)`, `link`, `seed_from_address_book`. The deterministic handle→PersonId logic + cross-source merge-safety contract. |
+| `src/openhuman/memory/people/scorer.rs` | Pure `score(interactions, now) -> ScoreComponents`. Recency half-life, frequency window/cap, reciprocity balance, depth cap as module constants. |
+| `src/openhuman/memory/people/store.rs` | SQLite-backed `PeopleStore` (`Arc<Mutex<Connection>>`) + rebindable process-global accessor (`init_from_workspace` / `get`). CRUD, lookup, interaction read/write, batched interaction fetch. |
+| `src/openhuman/memory/people/address_book.rs` | `ContactsSource` trait + `SystemContactsSource` (macOS `CNContactStore` FFI via objc2) and non-mac stub; `MockContactsSource` for tests; `AddressBookError`. |
+| `src/openhuman/memory/people/rpc.rs` | Domain RPC handlers (`handle_list`, `handle_resolve`, `handle_score`, `handle_refresh_address_book`) returning `RpcOutcome<Value>`; callable directly in tests with a constructed `PeopleStore`. |
+| `src/openhuman/memory/people/schemas.rs` | Controller schemas + param-parsing adapter handlers that fetch the global store and delegate to `rpc.rs`. |
+| `src/openhuman/memory/people/migrations.rs` | Idempotent migration runner (bookkeeping table `_people_migrations`, per-migration transaction). |
+| `src/openhuman/memory/people/migrations/0001_init.sql` | Schema: `people`, `handle_aliases`, `interactions` + indexes. |
+| `src/openhuman/memory/people/tests.rs` | Cross-file integration tests for the domain. |
+
+## Public surface
+
+- Types: `PersonId`, `Handle` (`IMessage` / `Email` / `DisplayName`), `Person`, `Interaction`, `ScoreComponents`, `AddressBookContact`.
+- `HandleResolver::{resolve, resolve_or_create, resolve_or_create_with_status, link, seed_from_address_book}`.
+- `scorer::score` + tunable constants `RECENCY_HALF_LIFE_DAYS`, `FREQUENCY_WINDOW_DAYS`, `FREQUENCY_CAP`, `DEPTH_CAP_CHARS`.
+- `store::{PeopleStore, init, get}` and `ConnHandle`.
+- `address_book::{ContactsSource, SystemContactsSource, read, read_with, AddressBookError}`.
+- `mod.rs` re-exports `all_people_controller_schemas` / `all_people_registered_controllers` for the controller registry.
+
+## RPC / controllers
+
+Registered via the controller registry (wired in `src/core/all.rs`). Four controllers in the `people` namespace:
+
+| Method | Inputs | Output |
+| --- | --- | --- |
+| `people.list` | `limit?` (default 100, capped at 500) | `people[]` ranked by score desc — each with `person_id`, `display_name?`, `primary_email?`, `primary_phone?`, `handles[]`, `score`, `components`, `interaction_count`. |
+| `people.resolve` | `kind` (`imessage`/`email`/`display_name`), `value`, `create_if_missing?` | `person_id?` (null when unknown and not creating), `created`. |
+| `people.score` | `person_id` (UUID) | `person_id`, `score`, `components`, `interaction_count`. Errors if person not found. |
+| `people.refresh_address_book` | — | `seeded`, `skipped`, `permission_denied`. |
+
+`score` / composite is `recency * frequency * reciprocity * depth`, each clamped to `[0,1]`.
+
+## Persistence
+
+Dedicated SQLite DB managed by `PeopleStore` (open via `open_at(path)` or `open_in_memory()`; migrations run on open). Three tables (see `0001_init.sql`):
+
+- `people` — one row per resolved person (uuid id, display name, primary email/phone, timestamps).
+- `handle_aliases` — `(kind, value)` primary key → `person_id` (FK, `ON DELETE CASCADE`); `value` is the canonicalized form. This table *is* the resolver index.
+- `interactions` — `(person_id, ts, is_outbound, length)` rows the scorer aggregates; indexed by `(person_id, ts DESC)` and `ts DESC`.
+
+Migrations are tracked in `_people_migrations` and applied idempotently in a transaction. The store is exposed process-globally through a workspace-tagged `RwLock<Option<…>>` slot (`get` from controller handlers). `store::init_from_workspace(workspace_dir)` seeds it, opening `<workspace>/people/people.db`; it is called at core boot (`src/core/jsonrpc.rs`, alongside `memory::global` and `whatsapp_data::global`) and again on active-user switch (`credentials::ops`, `app_state::ops`), where a **different** workspace rebinds the store — mirroring `memory::global` so people never keeps writing the pre-login workspace. Same-workspace calls are a no-op. Tests construct stores directly with `open_in_memory`.
+
+## Dependencies
+
+- the host's `core::all::{ControllerFuture, RegisteredController}` — controller registry types, used by the RPC surface that stayed in the host.
+- the host's `core::{ControllerSchema, FieldSchema, TypeSchema}` — controller schema definitions, used by the RPC surface that stayed in the host.
+- `crate::rpc::RpcOutcome` — standard RPC result envelope (`RpcOutcome<T>`).
+- External crates: `rusqlite` (storage), `tokio` (async + `spawn_blocking` for sync SQL, `Mutex`), `chrono` (timestamps/scoring), `uuid` (`PersonId`), `serde`; on macOS, `block2` / `objc2` / `objc2-contacts` / `objc2-foundation` for the `CNContactStore` FFI in `address_book.rs`. The global store slot uses `std::sync::{OnceLock, RwLock}`.
+
+Notably it depends on **no other `openhuman` domain** — consistent with its "self-contained" docstring.
+
+## Used by
+
+- `src/core/all.rs` — registers the people controllers and schemas, and routes the `"people"` namespace.
+- `src/openhuman/memory/store/` — reuses `people::types::{Person, PersonId, Handle}` (e.g. `Person` aliased as `Contact` in `kinds.rs`, and in `traits.rs`).
+
+## Notes / gotchas
+
+- **Cross-source merge safety (issue #1538):** two identities that share only a display name or only an unverified handle from different sources are **never** auto-merged. Merging only happens via explicit `link()`. Resolver tests lock this contract in.
+- **Idempotent seeding:** `seed_from_address_book` re-runs as a no-op for already-known handles; on `PermissionDenied` it writes nothing (no partial state). The "primary" link target is first email, else first phone, else display name.
+- **macOS Address Book FFI must not run on the main thread** — `CNContactStore` access requests deadlock there; `request_access` blocks on a completion-handler channel. Non-mac builds return an empty contact list.
+- **Scoring constants are module-level**, not config-driven yet — kept fixed so tests stay stable; the docstring notes they can move to config later without breaking the API.
+- **Composite is a product:** any zero component (e.g. a one-sided conversation → reciprocity 0) zeroes the whole score.
+- **SQL runs on `spawn_blocking`:** the connection is sync `rusqlite` behind `Arc<Mutex<Connection>>`; `JoinError`s from blocking tasks are mapped into a synthetic `rusqlite` IO error.
+- **Tests bypass the global store:** they construct `PeopleStore::open_in_memory()` and call `rpc::*` / `HandleResolver` directly rather than going through the schema adapters (which require the workspace-seeded global).