@hraness/peopleblade 0.1.2 → 0.2.1

package/README.md

@@ -15,7 +15,7 @@ Installation includes the pinned runtime dependencies Zod 4.4.3 and Effect 3.22.
 ## Install
 
 ```bash
-bun add --global @hraness/peopleblade@0.1.2
+bun add --global @hraness/peopleblade@0.2.1
 peopleblade --version
 peopleblade init
 peopleblade stats --json
@@ -46,7 +46,7 @@ through a separately reviewed `wrench` executable on `PATH` (or the absolute
 0.16.8 client validators needed to fence requests and receipts; it does not bundle
 or silently download Wrench's execution runtime.
 
-PeopleBlade 0.1.2 contains the reviewed Wrench-backed Beeper, Google, and WhatsApp
+PeopleBlade 0.2.1 contains the reviewed Wrench-backed Beeper, Google, and WhatsApp
 live sync commands. Running them requires the separately installed public
 `@hraness/wrench` 0.16.8 package. Beeper support is bounded to account-aware
 `contacts.list@3` reads, `contacts.search@1`, `messaging.search@2`, and the separate
@@ -65,16 +65,63 @@ Beeper interface directly and exposes none of Wrench's Beeper send or action
 operations. Archive imports, Apple Contacts, iMessage, notes, identity review,
 backups, and optional PeopleBlade cloud commands do not require Wrench.
 
+## Browse and edit locally
+
+```bash
+peopleblade capabilities --json
+peopleblade query --search "Ada" --sort name --direction asc --json
+peopleblade people show 12 --json
+peopleblade ui
+```
+
+`capabilities` is offline discovery, not proof that a provider is configured.
+`query` supports source, email, phone and do-not-contact filters, up to 100 rows
+per page, source facets, and `nextOffset` continuation. Pages are a live view;
+imports and identity reviews can move rows between requests. `list` retains its
+legacy shape for existing clients.
+
+`ui` starts a local workspace on a random `127.0.0.1` port. Open the printed URL
+and select its owner-only access file. The capability stays in tab memory; the
+page loads no remote assets and performs no provider or cloud calls. Ctrl+C
+stops the workspace and invalidates access. A process running as your OS user
+can access your local files; this is not a sandbox against that process.
+
+The workspace supports contact details, note search, Markdown creation/editing,
+safe preview, history and draft recovery. Note edits append immutable user
+revisions; original source content and attribution remain intact. No raw HTML
+or remote images are rendered. Notes never enter cloud sync or agent packets.
+
+```bash
+peopleblade notes show 42 --json
+peopleblade notes update 42 --expected-revision 0 \
+  --expected-context CONTEXT_SHA256 --request-id REQUEST_UUID \
+  --body-file /private/path/note.md --json
+peopleblade notes history 42 --json
+```
+
+Read the revision and context digest from `notes show`. Use a fresh UUID for a
+new edit; retry an uncertain edit with the same UUID and exact input. Stale
+content or identity context fails without overwriting a newer edit. `--body-file -`
+reads bounded UTF-8 stdin. `--title` changes the title, `--clear-title` clears it,
+and omission retains the title from the expected revision.
+
+The versioned `research prepare` envelope can be filled and passed directly to
+`research apply`. Keep its subject and instructions unchanged; fill only `result`.
+The envelope binds this database and its current identity evidence. The strict
+legacy three-field input remains supported. JSON-mode errors are one structured
+`peopleblade.error.v1` object on stderr; successful results stay on stdout.
+
 ## Privacy boundary
 
 PeopleBlade's provider import paths never retain, search, enrich from, or upload
 message text. The optional cloud projection excludes source records, raw archives,
-local paths, provider credentials, and message bodies. Ambiguous identity links
+local paths, provider credentials, note bodies and revisions, and message bodies. Ambiguous identity links
 remain reviewable instead of being silently merged.
 
 This npm artifact contains only the bundled local CLI, its pinned Wrench client
 validators and executable bridge, SQLite migrations, and package documentation.
-It does not contain the Wrench execution runtime, PeopleBlade web server, billing
+It includes the self-contained loopback workspace, but not the Wrench execution
+runtime, hosted PeopleBlade web server, billing
 implementation, operational tooling, tests, or private product documentation.
 
 ## Update or remove

package/dist/cloud-sync-client.js

@@ -354,6 +354,7 @@ var serverCliEnrichmentStartSchema = z.object({
 var cliEnrichmentStatusSchema = z.object({
   jobId: z.uuid()
 }).strict();
+var cliEnrichmentPublicEmailsRequestSchema = z.object({}).strict();
 var cliEnrichmentRevalidationSchema = z.object({
   limit: z.number().int().min(1).max(100)
 }).strict();
@@ -1460,7 +1461,14 @@ function localSchemaVersion(database) {
     throw new Error("PeopleBlade schema is not initialized.");
   return row.count;
 }
-function projectCloudContacts(database) {
+function projectCloudContacts(database, options = {}) {
+  const selected = options.personIds === undefined ? undefined : [...new Set(options.personIds)];
+  if (selected !== undefined && (selected.length > 100 || selected.some((id) => !Number.isSafeInteger(id) || id < 1))) {
+    throw new Error("Projection selection requires at most 100 positive canonical person IDs.");
+  }
+  if (selected?.length === 0)
+    return [];
+  const selectionSql = selected === undefined ? "" : `AND p.id IN (${selected.map(() => "?").join(",")})`;
   const rows = database.query(`
     WITH
     ${canonicalInteractionRollupCtesSql},
@@ -1627,11 +1635,12 @@ function projectCloudContacts(database) {
     LEFT JOIN source_rollup ON source_rollup.person_id = p.id
     LEFT JOIN handle_rollup ON handle_rollup.person_id = p.id
     LEFT JOIN resource_eligibility ON resource_eligibility.person_id = p.id
-    WHERE resource_eligibility.person_id IS NULL
+    WHERE (resource_eligibility.person_id IS NULL
       OR resource_eligibility.has_active_resource = 1
-      OR canonical_interaction_rollup.person_id IS NOT NULL
+      OR canonical_interaction_rollup.person_id IS NOT NULL)
+      ${selectionSql}
     ORDER BY p.id
-  `).all();
+  `).all(...selected ?? []);
   const instance = localDatabaseFingerprint(database);
   return rows.map((row) => {
     const sources = sourceLabelSchema.array().parse(parseStringArray(row.sources_json).filter((source) => sourceLabelSchema.safeParse(source).success));

package/dist/migrations/017_person_note_content_revisions.sql

@@ -0,0 +1,151 @@
+PRAGMA foreign_keys = ON;
+
+-- User edits are overlays; original provider content and attribution stay immutable.
+CREATE TABLE person_note_content_revisions (
+    note_id INTEGER NOT NULL REFERENCES person_notes(id) ON DELETE RESTRICT,
+    revision INTEGER NOT NULL CHECK(revision BETWEEN 1 AND 9007199254740991),
+    expected_revision INTEGER NOT NULL CHECK(expected_revision BETWEEN 0 AND 9007199254740990),
+    request_id TEXT NOT NULL UNIQUE CHECK(length(request_id) = 36),
+    expected_context_sha256 TEXT NOT NULL CHECK(
+      length(expected_context_sha256) = 64
+      AND expected_context_sha256 NOT GLOB '*[^0-9a-f]*'
+    ),
+    context_json TEXT NOT NULL CHECK(json_valid(context_json)),
+    title TEXT CHECK(title IS NULL OR (length(title) BETWEEN 1 AND 1024 AND instr(title, char(0)) = 0)),
+    body TEXT NOT NULL CHECK(length(CAST(body AS BLOB)) BETWEEN 1 AND 65536 AND instr(body, char(0)) = 0),
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    PRIMARY KEY(note_id, revision),
+    CHECK(revision = expected_revision + 1)
+) STRICT;
+
+CREATE TRIGGER person_note_content_revision_valid
+BEFORE INSERT ON person_note_content_revisions FOR EACH ROW
+BEGIN
+  SELECT CASE WHEN
+    EXISTS (SELECT 1 FROM person_note_content_revisions prior
+      WHERE prior.request_id = NEW.request_id
+        OR (prior.note_id = NEW.note_id AND prior.revision = NEW.revision))
+    OR NEW.expected_revision IS NOT coalesce(
+      (SELECT max(prior.revision) FROM person_note_content_revisions prior WHERE prior.note_id = NEW.note_id), 0)
+    OR NOT EXISTS (SELECT 1 FROM person_notes WHERE id = NEW.note_id)
+    OR json_extract(NEW.context_json, '$.schemaVersion') IS NOT 1
+    OR json_extract(NEW.context_json, '$.databaseInstanceId') IS NOT
+      (SELECT instance_id FROM local_state WHERE singleton = 1)
+    OR json_extract(NEW.context_json, '$.noteId') IS NOT NEW.note_id
+    OR json_extract(NEW.context_json, '$.revision') IS NOT NEW.expected_revision
+    OR json_extract(NEW.context_json, '$.originalPersonId') IS NOT
+      (SELECT person_id FROM person_notes WHERE id = NEW.note_id)
+    OR json_extract(NEW.context_json, '$.attributedPersonId') IS NOT
+      (SELECT person_id FROM person_notes_current WHERE id = NEW.note_id)
+    OR json_extract(NEW.context_json, '$.attributionRevisionId') IS NOT coalesce(
+      (SELECT max(id) FROM person_note_attribution_revisions WHERE note_id = NEW.note_id), 0)
+    OR json_extract(NEW.context_json, '$.identityRevision') IS NOT
+      (SELECT identity_revision FROM local_revisions WHERE singleton = 1)
+    OR json_extract(NEW.context_json, '$.canonicalPersonId') IS NOT
+      (SELECT component.canonical_person_id FROM person_identity_components component
+       JOIN person_notes_current note ON note.person_id = component.person_id WHERE note.id = NEW.note_id)
+    OR json_extract(NEW.context_json, '$.componentPersonIds') IS NOT (
+      SELECT json_group_array(person_id) FROM (
+        SELECT member.person_id FROM person_identity_components member
+        WHERE member.canonical_person_id = (
+          SELECT component.canonical_person_id FROM person_identity_components component
+          JOIN person_notes_current note ON note.person_id = component.person_id WHERE note.id = NEW.note_id
+        ) ORDER BY member.person_id
+      )
+    )
+  THEN RAISE(ABORT, 'person note revision context is not current') END;
+END;
+
+CREATE TABLE person_note_creation_requests (
+    request_id TEXT PRIMARY KEY CHECK(length(request_id) = 36),
+    note_id INTEGER NOT NULL UNIQUE REFERENCES person_notes(id) ON DELETE RESTRICT,
+    requested_person_id INTEGER NOT NULL REFERENCES people(id) ON DELETE RESTRICT,
+    expected_context_sha256 TEXT NOT NULL CHECK(
+      length(expected_context_sha256) = 64 AND expected_context_sha256 NOT GLOB '*[^0-9a-f]*'
+    ),
+    context_json TEXT NOT NULL CHECK(json_valid(context_json)),
+    occurred_at_input TEXT NOT NULL CHECK(length(occurred_at_input) BETWEEN 1 AND 80)
+) STRICT;
+
+CREATE TRIGGER person_note_creation_request_valid
+BEFORE INSERT ON person_note_creation_requests FOR EACH ROW
+BEGIN
+  SELECT CASE WHEN
+    EXISTS (SELECT 1 FROM person_note_creation_requests prior
+      WHERE prior.request_id = NEW.request_id OR prior.note_id = NEW.note_id)
+    OR json_extract(NEW.context_json, '$.schemaVersion') IS NOT 1
+    OR json_extract(NEW.context_json, '$.databaseInstanceId') IS NOT
+      (SELECT instance_id FROM local_state WHERE singleton = 1)
+    OR json_extract(NEW.context_json, '$.personId') IS NOT NEW.requested_person_id
+    OR json_extract(NEW.context_json, '$.identityRevision') IS NOT
+      (SELECT identity_revision FROM local_revisions WHERE singleton = 1)
+    OR json_extract(NEW.context_json, '$.canonicalPersonId') IS NOT
+      (SELECT canonical_person_id FROM person_identity_components WHERE person_id = NEW.requested_person_id)
+    OR json_extract(NEW.context_json, '$.componentPersonIds') IS NOT (
+      SELECT json_group_array(person_id) FROM (
+        SELECT member.person_id FROM person_identity_components member
+        WHERE member.canonical_person_id = (
+          SELECT canonical_person_id FROM person_identity_components WHERE person_id = NEW.requested_person_id
+        ) ORDER BY member.person_id
+      )
+    )
+    OR NOT EXISTS (SELECT 1 FROM person_notes note
+      WHERE note.id = NEW.note_id AND note.source = 'manual' AND note.source_id = NEW.request_id
+        AND note.person_id = json_extract(NEW.context_json, '$.canonicalPersonId'))
+  THEN RAISE(ABORT, 'person note creation context is not current') END;
+END;
+
+CREATE TRIGGER person_note_creation_requests_immutable_update
+BEFORE UPDATE ON person_note_creation_requests FOR EACH ROW
+BEGIN SELECT RAISE(ABORT, 'person note creation requests are immutable'); END;
+CREATE TRIGGER person_note_creation_requests_immutable_delete
+BEFORE DELETE ON person_note_creation_requests FOR EACH ROW
+BEGIN SELECT RAISE(ABORT, 'person note creation requests are immutable'); END;
+
+CREATE TRIGGER person_note_content_revisions_immutable_update
+BEFORE UPDATE ON person_note_content_revisions FOR EACH ROW
+BEGIN SELECT RAISE(ABORT, 'person note content revisions are immutable'); END;
+CREATE TRIGGER person_note_content_revisions_immutable_delete
+BEFORE DELETE ON person_note_content_revisions FOR EACH ROW
+BEGIN SELECT RAISE(ABORT, 'person note content revisions are immutable'); END;
+
+CREATE VIEW person_notes_effective AS
+SELECT note.id, note.person_id, note.occurred_at, note.source, note.source_id,
+  CASE WHEN revision.revision IS NULL THEN note.title ELSE revision.title END AS title,
+  coalesce(revision.body, note.body) AS body,
+  note.metadata_json, note.created_at,
+  coalesce(revision.revision, 0) AS revision,
+  revision.created_at AS revised_at
+FROM person_notes_current note
+LEFT JOIN person_note_content_revisions revision ON revision.note_id = note.id
+  AND revision.revision = (
+    SELECT max(latest.revision) FROM person_note_content_revisions latest WHERE latest.note_id = note.id
+  );
+
+CREATE VIRTUAL TABLE person_notes_effective_fts USING fts5(
+  title, body, content='person_notes_effective', content_rowid='id',
+  tokenize='unicode61 remove_diacritics 2'
+);
+INSERT INTO person_notes_effective_fts(rowid, title, body)
+SELECT id, coalesce(title, ''), body FROM person_notes_effective;
+
+CREATE TRIGGER person_notes_effective_fts_original_insert
+AFTER INSERT ON person_notes FOR EACH ROW
+BEGIN
+  INSERT INTO person_notes_effective_fts(rowid, title, body)
+  VALUES (NEW.id, coalesce(NEW.title, ''), NEW.body);
+END;
+
+CREATE TRIGGER person_notes_effective_fts_revision_insert
+AFTER INSERT ON person_note_content_revisions FOR EACH ROW
+BEGIN
+  INSERT INTO person_notes_effective_fts(person_notes_effective_fts, rowid, title, body)
+  SELECT 'delete', NEW.note_id, coalesce(note.title, ''), note.body
+  FROM person_notes note WHERE note.id = NEW.note_id AND NEW.expected_revision = 0;
+  INSERT INTO person_notes_effective_fts(person_notes_effective_fts, rowid, title, body)
+  SELECT 'delete', NEW.note_id, coalesce(prior.title, ''), prior.body
+  FROM person_note_content_revisions prior
+  WHERE prior.note_id = NEW.note_id AND prior.revision = NEW.expected_revision;
+  INSERT INTO person_notes_effective_fts(rowid, title, body)
+  VALUES (NEW.note_id, coalesce(NEW.title, ''), NEW.body);
+END;