@hraness/peopleblade 0.1.2 → 0.2.2

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.2
 peopleblade --version
 peopleblade init
 peopleblade stats --json
@@ -37,44 +37,95 @@ authorized devices, `peopleblade cloud revoke DEVICE_ID` for a lost device, and
 token. The signed-in dashboard provides the lost-device recovery path when no CLI
 token remains available.
 
-### Optional Wrench-backed sources
+### Optional Ghostget-backed sources
 
-The package does not install Wrench, browser automation, KB, native model runtimes,
+The package does not install Ghostget, browser automation, KB, native model runtimes,
 or provider credentials. Beeper, Google, and WhatsApp live sync commands delegate
-through a separately reviewed `wrench` executable on `PATH` (or the absolute
-`PEOPLEBLADE_WRENCH_EXECUTABLE` path). PeopleBlade bundles only the pinned Wrench
-0.16.8 client validators needed to fence requests and receipts; it does not bundle
-or silently download Wrench's execution runtime.
+through a separately reviewed `ghostget` executable on `PATH` (or the absolute
+`PEOPLEBLADE_GHOSTGET_EXECUTABLE` path). PeopleBlade bundles only the pinned Ghostget
+0.17.1 client validators needed to fence requests and receipts; it does not bundle
+or silently download Ghostget's execution runtime.
 
-PeopleBlade 0.1.2 contains the reviewed Wrench-backed Beeper, Google, and WhatsApp
+`PEOPLEBLADE_WRENCH_EXECUTABLE` remains a compatibility alias for the explicit
+path. When both variables are set, they must name the same executable. The
+bridge still requires exact Ghostget 0.17.1 before invoking a provider operation.
+
+PeopleBlade 0.2.2 contains the reviewed Ghostget-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
+`@hraness/ghostget` 0.17.1 package. Beeper support is bounded to account-aware
 `contacts.list@3` reads, `contacts.search@1`, `messaging.search@2`, and the separate
 body-free interaction exporter. `contacts.search@1` executes the official Beeper
-CLI 0.6.2 executable pinned by Wrench; `contacts.list@3` and `messaging.search@2`
-use Wrench's bounded Desktop-loopback read paths. The exporter is macOS arm64 only
+CLI 0.6.2 executable pinned by Ghostget; `contacts.list@3` and `messaging.search@2`
+use Ghostget's bounded Desktop-loopback read paths. The exporter is macOS arm64 only
 and reports lower-bound interaction counts from complete one-to-one conversations
 only. See
 [peopleblade.com/sources](https://peopleblade.com/sources) for the complete provider
 guide. A database previously synced by PeopleBlade 0.1.1 through Wrench 0.16.7
 must run `peopleblade beeper rebind --auth beeper-main --confirm --json` once after
-installing Wrench 0.16.8. The command appends reviewed metadata for the same source
+installing Ghostget 0.17.1. The command appends reviewed metadata for the same source
 identity only after both complete account inventories match. Do not force-bind
-Wrench unless its authenticated Desktop target changed. PeopleBlade calls no
-Beeper interface directly and exposes none of Wrench's Beeper send or action
+Ghostget unless its authenticated Desktop target changed. PeopleBlade calls no
+Beeper interface directly and exposes none of Ghostget's Beeper send or action
 operations. Archive imports, Apple Contacts, iMessage, notes, identity review,
-backups, and optional PeopleBlade cloud commands do not require Wrench.
+backups, and optional PeopleBlade cloud commands do not require Ghostget.
+
+## 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
+This npm artifact contains only the bundled local CLI, its pinned Ghostget 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 Ghostget execution
+runtime, hosted PeopleBlade web server, billing
 implementation, operational tooling, tests, or private product documentation.
 
 ## Update or remove

package/THIRD_PARTY_NOTICES.md

@@ -1,8 +1,8 @@
 # Third-party notices
 
 The PeopleBlade CLI bundle includes reviewed client-boundary code from
-`@hraness/wrench` 0.16.8 (commit
-`b0cf2ecbc1113fcc8ef673a824be475c3d7bbb46`) and message-bundle contract code
+`@hraness/ghostget` 0.17.1 (commit
+`b74ae2ac594bcf07c3def71dc4bb2e5a98c826dd`) and message-bundle contract code
 from `@hraness/message-like-me` 0.7.0. Those portions are provided under the
 following license. The PeopleBlade CLI package has its own MIT grant in
 `LICENSE`; this notice preserves the attribution for the bundled portions.

package/dist/cli.ts

@@ -3,10 +3,20 @@
 import { accessSync, constants, realpathSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 
-const reviewedWrenchVersion = "0.16.8";
-const configured = process.env.PEOPLEBLADE_WRENCH_EXECUTABLE;
+const reviewedGhostgetVersion = "0.17.1";
+const canonicalConfigured = process.env.PEOPLEBLADE_GHOSTGET_EXECUTABLE;
+const legacyConfigured = process.env.PEOPLEBLADE_WRENCH_EXECUTABLE;
+if (
+  canonicalConfigured !== undefined
+  && legacyConfigured !== undefined
+  && canonicalConfigured !== legacyConfigured
+) {
+  console.error("PEOPLEBLADE_GHOSTGET_EXECUTABLE and PEOPLEBLADE_WRENCH_EXECUTABLE must name the same executable when both are set.");
+  process.exit(127);
+}
+const configured = canonicalConfigured ?? legacyConfigured;
 const executable = configured === undefined
-  ? Bun.which("wrench")
+  ? Bun.which("ghostget")
   : isAbsolute(configured)
     ? resolve(configured)
     : null;
@@ -14,8 +24,8 @@ const executable = configured === undefined
 if (executable === null) {
   console.error(
     configured === undefined
-      ? "PeopleBlade Wrench-backed sources require a separately reviewed `wrench` executable on PATH."
-      : "PEOPLEBLADE_WRENCH_EXECUTABLE must be an absolute executable path.",
+      ? "PeopleBlade Ghostget-backed sources require a separately reviewed `ghostget` executable on PATH."
+      : "PEOPLEBLADE_GHOSTGET_EXECUTABLE must be an absolute executable path.",
   );
   process.exit(127);
 }
@@ -25,11 +35,11 @@ try {
   accessSync(executable, constants.X_OK);
   canonicalExecutable = realpathSync(executable);
 } catch {
-  console.error("The configured PeopleBlade Wrench executable is unavailable or not executable.");
+  console.error("The configured PeopleBlade Ghostget executable is unavailable or not executable.");
   process.exit(127);
 }
 if (process.argv[1] !== undefined && canonicalExecutable === realpathSync(process.argv[1])) {
-  console.error("The PeopleBlade Wrench executable bridge cannot delegate to itself.");
+  console.error("The PeopleBlade Ghostget executable bridge cannot delegate to itself.");
   process.exit(127);
 }
 
@@ -54,11 +64,11 @@ if (
   || versionProbe.signalCode !== undefined
   || versionProbe.exitedDueToTimeout === true
   || versionProbe.exitedDueToMaxBuffer === true
-  || versionProbe.stdout?.toString() !== `${reviewedWrenchVersion}\n`
+  || versionProbe.stdout?.toString() !== `${reviewedGhostgetVersion}\n`
   || versionProbe.stderr?.byteLength !== 0
 ) {
   console.error(
-    `PeopleBlade Wrench-backed sources require the exact reviewed Wrench ${reviewedWrenchVersion} executable.`,
+    `PeopleBlade Ghostget-backed sources require the exact reviewed Ghostget ${reviewedGhostgetVersion} executable.`,
   );
   process.exit(126);
 }

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;