@ghostpaw/affinity 0.5.0 → 0.6.0

package/README.md

@@ -45,9 +45,19 @@ cd "$(mktemp -d)" && T=darwin-x64 && V=$(curl -fsSLI -o /dev/null -w '%{url_effe
 $r='GhostPawJS/affinity'; $v=(irm "https://api.github.com/repos/$r/releases/latest").tag_name; $f="ghostpaw-affinity-$($v.TrimStart('v'))-windows-x64.zip"; $u="https://github.com/$r/releases/download/$v"; $t=(New-Item -ItemType Directory (Join-Path $env:TEMP ([guid]::NewGuid()))).FullName; iwr "$u/$f" -OutFile "$t\$f" -UseBasicParsing; iwr "$u/SHA256SUMS" -OutFile "$t\SHA256SUMS" -UseBasicParsing; $want=((Get-Content "$t\SHA256SUMS" | Where-Object { $_ -like "* $f" }) -split '\s+')[0]; if (-not $want -or (Get-FileHash "$t\$f" -Algorithm SHA256).Hash -ne $want) { throw "checksum mismatch for $f" }; $d=Join-Path $env:LOCALAPPDATA 'Programs\ghostpaw\bin'; Expand-Archive "$t\$f" $t -Force; New-Item -ItemType Directory -Force $d | Out-Null; Copy-Item "$t\ghostpaw-affinity.exe" $d -Force; $p=[Environment]::GetEnvironmentVariable('Path','User'); if (";$p;" -notlike "*;$d;*") { [Environment]::SetEnvironmentVariable('Path',"$p;$d",'User') }; $env:Path="$d;$env:Path"; ghostpaw-affinity --version
 ```
 
-Linux installs to `~/.local/bin` (added to `~/.profile` if missing), macOS to
-`/usr/local/bin` (asks for sudo), Windows to `%LOCALAPPDATA%\Programs\ghostpaw\bin`
-(added to the user `PATH`; open a new terminal afterwards).
+These commands install the latest release in `~/.local/bin` on Linux, `/usr/local/bin` on macOS (asks for sudo), or `%LOCALAPPDATA%\Programs\ghostpaw\bin` on Windows; Linux adds it to PATH via `~/.profile` only if missing, and Windows adds it to the user PATH (open a new terminal afterwards). To pin a version, set `V=0.6.0` instead of resolving latest (`$v='v0.6.0'` in PowerShell).
+
+For a pinned Linux/macOS download to the current directory with no profile or PATH edits, choose the matching `T` (`linux-x64`, `linux-arm64`, `darwin-arm64`, or `darwin-x64`):
+
+```sh
+V=0.6.0
+T=linux-x64
+F=ghostpaw-affinity-$V-$T.tar.gz
+U=https://github.com/GhostPawJS/affinity/releases/download/v$V
+curl -fsSL -O "$U/$F" -O "$U/SHA256SUMS" &&
+  { case "$T" in darwin-*) grep " $F\$" SHA256SUMS | shasum -a 256 -c - ;; *) grep " $F\$" SHA256SUMS | sha256sum -c - ;; esac; } &&
+  tar -xzf "$F" ghostpaw-affinity && ./ghostpaw-affinity --version
+```
 
 Then:
 
@@ -63,7 +73,7 @@ resolve against the current directory.
 
 A session with the linux-x64 binary against a fresh database:
 
-![ghostpaw-affinity session: version, contact create, identity add, event and commitment record, search, review commitments.open and show contact_profile](https://raw.githubusercontent.com/GhostPawJS/affinity/main/docs/assets/cli.png)
+![ghostpaw-affinity session: version, contact create, a tag, an event and a promise with relative dates, search, an overdue promise in review commitments.open, and the radar](https://raw.githubusercontent.com/GhostPawJS/affinity/main/docs/assets/cli.png)
 
 The same session as an [animated GIF](https://raw.githubusercontent.com/GhostPawJS/affinity/main/docs/assets/cli.gif).
 
@@ -218,6 +228,43 @@ ghostpaw-affinity skill --list       # workflow guides
 ghostpaw-affinity skill bootstrap-and-cold-start
 ```
 
+## Events
+
+Record events and commitments with an optional `externalRef: {source, id}`.
+Both values are trimmed and non-empty; source is lowercased. The pair is unique
+across the database. Repeated intake returns the original event and `no_op`,
+without creating rows or relationship effects.
+
+`content` preserves text exactly, including whitespace, empty strings and NUL,
+up to 1 MB (1,048,576 UTF-8 bytes). Supply a short `summary`, or omit it to derive
+one from the first non-empty content line (at most 140 characters; empty text
+becomes `(no text)`). Unknown event fields and moment kinds are validation errors.
+Journal/timeline rows omit content by default; use `{includeContent: true}` in
+library/tool options or CLI `--with-content`. Content appears once in review JSON.
+
+Events support a free-text `channel` (trimmed, lowercased, at most 40 characters),
+`parentRef`, `parentEventId`, and a root `threadRef`. Journal, timeline, moments,
+and open commitment reviews accept a channel filter. Set event attributes with
+`write.setAttribute(db, {kind: "event", eventId}, name, value)`; unset and replace
+use the same target and validation as contact/link attributes.
+
+Read exact events with `read.getEventById(db, eventId)` or
+`read.getEventByExternalRef(db, source, id)`. `read.searchEvents` searches folded
+summary, content, reference and channel text. The search tool's `scope` is
+`contacts` by default, with additive `events` and `all` modes.
+`read.getEventThread(db, source, id)` returns a root and its descendants in time
+order, including parents imported after their children.
+
+`write.reviseEvent(db, eventIdOrTarget, patch)` accepts summary, content,
+occurredAt, significance, channel, type within the same event family, and an
+externalRef only when absent. `write.deleteEvent(db, eventIdOrTarget,
+{confirm: true})` removes evidence, participants, attributes and link effects,
+then replays surviving effects and refreshes rollups. Targets can also be
+`{ref: {source, id}}`. Existing 0.5.x databases migrate through
+`initAffinityTables`. Historical affinity/trust/rank baselines are recovered
+from saved deltas; historical cadence and state before evidence were not stored
+and use the default cadence and active state during replay.
+
 ## CLI
 
 ```sh
@@ -252,6 +299,13 @@ ghostpaw-affinity commitment record|resolve [flags]
 ghostpaw-affinity attribute set|unset|replace [flags]
 ghostpaw-affinity date add|revise|remove [flags]
 ghostpaw-affinity event record [flags]
+ghostpaw-affinity show event --event-id 12
+ghostpaw-affinity show event --ref-source bluesky --ref-id at://record
+ghostpaw-affinity search --scope events "text or record id"
+ghostpaw-affinity review events.contact_journal --contact '{"contactId":2}' --with-content --channel bluesky
+ghostpaw-affinity review events.thread --ref-source bluesky --ref-id at://root
+ghostpaw-affinity event revise --event-id 12 --patch '{"summary":"Corrected"}'
+ghostpaw-affinity event delete --event-id 12 --confirm
 ghostpaw-affinity duplicate dismiss|undismiss [flags]
 ghostpaw-affinity mcp|skill|tools|describe|call|completions|version|help
 ```
@@ -265,15 +319,30 @@ to read a file; repeated array flags accept JSON objects
 (`--entries '{"name":"a","value":"x"}'`) or one JSON array.
 
 Every time field accepts epoch milliseconds, ISO 8601 with `Z` or an offset,
-`YYYY-MM-DD`, `DD.MM.YYYY` (CLI), `today`, `tomorrow`, `yesterday` and signed day offsets
-such as `+3d` or `-2d`. On the CLI, date-only values use local time (midnight,
-or end of day for `dueAt`); through MCP and the tool facade they use UTC.
+`YYYY-MM-DD`, `DD.MM.YYYY`, `today`, `tomorrow`, `yesterday` and signed day offsets
+such as `+3d` or `-2d`, with the same grammar in CLI, MCP and direct tool calls.
+Date-only values preserve their calendar day: timestamps use UTC midnight, or
+23:59:59.999Z for `dueAt`. Keywords first resolve against the process local
+calendar date; this is the only time-zone-dependent parsing step. `occurredOn`
+and `dueOn` retain the input day (the written offset day for ISO inputs; UTC day
+for epoch inputs). Existing rows derive these fields from their UTC timestamps.
+Review rows for dates include `occursOn`, the anchor occurrence day; the library
+keeps its numeric `occursOn` sorting key and adds `occursOnDate`.
+The existing `*Iso` fields remain UTC. Overdue commitments compare the local
+date to `dueOn`. Future events carry a `future_event` warning and do not count
+as contact until their timestamp and day arrive. Commitments and their
+resolutions do not reset recency or cadence. Radar marks `drift` after a gap
+exceeds 1.5 times the expected cadence and explains its reasons in the snippet.
 
 Global flags: `--db <path>`, `--json`, `--quiet`, `--compact`,
 `--help`/`-h`, `--version`/`-V`/`-v`, `--no-color`.
 `NO_COLOR` is accepted. In a terminal, commands print a readable summary with
 names and dates. With `--json` or piped stdout they print the tool result as
-JSON with ISO date siblings and floats rounded to three decimals; `--compact`
+JSON with ISO date siblings and floats rounded to three decimals. Journal review rows
+keep one summary and compact `{id,name,role}` participants. Radar rows keep one link
+id, counterparty name, reasons and rounded scores; upcoming link dates omit radar
+scores. Default piped writes and `--compact` keep primary and changed ids plus
+warnings; explicit `--json` retains full mutation detail. `--compact`
 removes indentation and empty receipt arrays. `--quiet` suppresses stdout.
 Writes list what changed in `data.changes`, and creates warn about likely
 duplicates. Kebab-case flags map to schema properties. `--` ends flags.
@@ -296,7 +365,24 @@ stderr. These commands work offline.
 
 Errors go to stderr. With `--json`, errors also print to stdout.
 `--version` names the variant: `affinity 0.5.0 (binary, linux-x64)`,
-`(npm)` or `(library)`. Legacy `tools [--json]`, `describe <tool>`,
+`(npm)` or `(library)`. Use `--version --short` in scripts for exact semver
+matching. `--version --json` returns `name`, `version`, `variant` and `target`
+(the target is null outside a binary). `version --short` and `version --json`
+are equivalent.
+
+Read commands (search, show, review and contact export, including direct tool
+calls) exit 3 on a missing database without creating files:
+`Database not found: <path> (it is created by the first write)`.
+The first write creates the database and reports `created <path>` on stderr.
+The MCP server continues to create its database on startup.
+
+String-valued flags such as `--value Hamburg`, `--bond 'Warm lead'` and
+`--reason 'Different people'` accept plain strings or JSON strings/null.
+Object and array flags still require JSON. Tag filters accept both
+`--tag gastro-radar` and `--tag tag:gastro-radar`.
+Per-command `--help` lists the fields used by that action.
+
+Legacy `tools [--json]`, `describe <tool>`,
 `call <tool> [JSON|-]` and `<tool_name> --parameter value` remain available.
 `completions bash|zsh|fish` prints shell scripts.
 
@@ -536,3 +622,92 @@ If this package helps your project, consider sponsoring its maintenance:
 ---
 
 **[Anonyfox](https://anonyfox.com) • [MIT License](LICENSE)**
+
+### Social imports and batch writes
+
+Contact creation accepts `identities` and `ifExists: "error" | "return"` in the
+library and tools. Identity ownership conflicts fail atomically (CLI exit 4),
+including `data.existingContactId` and `error.details.existingContactId` in tool
+results. `contact create '<JSON>' --if-exists return` returns the existing contact
+with `outcome: "no_op"` and `matchedIdentities`; it attaches nothing, including
+other free identities. Name-only duplicates still receive a possible-duplicate
+warning. Links can opt into `input.ifExists: "return"` when seeding repeatedly. Identity
+addition supports the same opt-in policy for an identity already on that contact;
+another contact still conflicts. Importers add changed handles separately after
+contact creation.
+
+Handle identities strip a leading `@` and lowercase on add, revise and lookup.
+Bluesky handles must be domain-like, X/Twitter handles have 1–15 letters, digits
+or underscores, and Mastodon handles use `user@host.tld`. Use native `did` (alias
+`atproto_did`) for stable AT Protocol identities. Locators also find legacy
+`custom:atproto-did` rows. Keep former handles as additional identities.
+`search @handle` works because CLI values are literal.
+
+Only the JSON payload arguments (`--input`, the positional `<input>`, `--patch`
+and the `call` argument) read files. Their help line ends with
+`(@file, @- stdin, @@ literal @)`: `@path` reads the file as UTF-8 relative to
+the current directory, `@-` reads stdin, and `@@text` passes the literal
+`@text`. An empty path (`@`) or an unreadable file exits 2. Every other value,
+including names, notes, attribute values and search queries, is taken byte for
+byte, even with a leading `@` or `@@`.
+
+For large payloads use stdin or `@file` to avoid the operating system's argv
+size limit (`E2BIG`). JSON flag values support `-` too:
+
+```sh
+ghostpaw-affinity event record --kind interaction --input - < event.json
+ghostpaw-affinity event record --kind interaction --input @event.json
+ghostpaw-affinity review events.contact_journal --contact '{"contactId":2}' --event-types '["conversation","observation"]'
+```
+
+Array flags accept JSON arrays, comma lists, or repeated flags. Unknown event
+types fail with exit 2 and allowed values. SQLite timestamps such as
+`2026-10-27 17:51:33` use UTC; explicit offsets are honored. Sub-millisecond
+fractions are rounded silently to milliseconds, including carry into the next
+second. Keep the original timestamp in the source archive if finer precision
+matters. Null `occurredAt` is invalid.
+
+Record likes, reposts and follows as observations with `affectsBond: false`.
+Observations with significance <= 2 default to false; other events default to
+true. These ambient records stay in the journal without changing affinity or
+recency. `provenance.ambient: true` also suppresses bond effects. Explicitly
+outbound-only evidence contributes much less and does not reset radar recency;
+without reciprocal contact it generates no routine check-in or drift prompt.
+Include the owner explicitly with the correct actor/recipient role and use
+`owner_initiated`, `other_initiated`, or `mutual` directionality. Observations and
+follow-like milestones never derive breakthroughs; low-significance milestones
+do not derive moments. An explicit `momentKind` is honored.
+
+List reviews default to 50 rows, accept `--limit` (up to 250) and `--offset`,
+and include `total` and `hasMore`. Follow `hasMore` rather than assuming the
+first page is complete.
+
+`batch` reads one tool invocation per JSONL line, with one transaction for the
+whole input by default, or one per `--chunk N` lines. Each line has its own
+savepoint: failed lines roll back and later lines continue. `--stop-on-error`
+stops at the first failure. Results are JSONL `{line, ok, outcome, id, error?}`
+plus `{done, created, noOp, failed}`; created counts successful non-no-op lines.
+Exit status is 0 for success, 1 for failures, or 2 if a line is invalid JSON.
+Committed chunks remain committed if a later chunk fails.
+
+```jsonl
+{"tool":"manage_contact","args":{"action":"create","input":{"name":"Owner","kind":"human","bootstrapOwner":true,"ifExists":"return","identities":[{"type":"did","value":"did:plc:owner"}]}}}
+{"op":"event","kind":"observation","input":{"occurredAt":"2026-10-27","content":"","significance":1,"affectsBond":false,"externalRef":{"source":"bluesky","id":"at://example/like/1"},"participants":[{"contactId":1,"role":"actor"}]}}
+```
+
+```sh
+ghostpaw-affinity batch --chunk 500 < import.jsonl
+node scripts/examples/import_social_jsonl.mjs scripts/examples/fixtures/social_sample.json | ghostpaw-affinity --db /tmp/social-demo.db batch
+node scripts/examples/import_dry_run.mjs
+```
+
+The dependency-free example consumes a JSON export shaped as accounts, posts,
+interactions and follows; it never opens the source database. It resolves handle
+aliases to DIDs, deduplicates record URIs, keeps content verbatim, sets channel,
+parent references and directionality, and uses first_seen for undated follows
+or counts a skipped timestamp. The dry run checks two imports, DID uniqueness
+and byte-identical content, and reports journal JSON bytes versus raw text bytes.
+Examples and synthetic fixtures are development files, outside the npm package.
+
+`ghostpaw-affinity skill --short` prints the compact command reference without
+frontmatter or an appendix. `skill --list` lists guides; `skill <guide>` reads one.