@hraness/message-like-me 0.8.0

package/docs/local-message-bundle-v1.md

@@ -0,0 +1,245 @@
+# Local message bundle version 1
+
+`message-like-me.local-message-bundle` is a private directory interchange for
+moving a bounded local provider observation into Message Like Me. It separates
+provider capture from analysis: a producer handles provider access and writes
+the bundle, while `messagelikeme ingest bundle` verifies and normalizes it. The
+importer never receives provider credentials, starts Wrench, invokes a Beeper
+operation, or sends a message.
+
+The currently verified producer is the local Beeper export in the
+[`@hraness/wrench@0.16.1`](https://www.npmjs.com/package/@hraness/wrench/v/0.16.1)
+npm package:
+
+```sh
+bun add --global @hraness/wrench@0.16.1
+wrench beeper export-message-like-me \
+  --auth <beeper-auth-id> \
+  --output <normalized-absolute-new-directory> \
+  [--limit-chats <n>] \
+  [--limit-messages <n>] \
+  [--max-participants <n>] \
+  [--json]
+```
+
+The JSON shape is published as
+[`schema/local-message-bundle-v1.schema.json`](../schema/local-message-bundle-v1.schema.json).
+Runtime validation also enforces UTF-8 byte bounds, canonical encoding,
+filesystem identity, graph joins, and digest laws that JSON Schema cannot
+express.
+
+## Compatibility coordinates
+
+Message Like Me accepts schema version `1` with source ID `beeper-local` and
+source-transform version `1.1.0`. Wrench v0.16.1 emits those coordinates with
+the pinned Beeper CLI version `0.6.2`. A later Wrench package release remains
+compatible only while its manifest still declares that schema, source ID, and
+`source.version: "1.1.0"`; package age or a permissive version range never
+overrides the manifest coordinates. The provider version records the pinned
+Beeper CLI used for capture and may change without changing the bundle
+contract.
+
+The dependency-free package subpath is the executable contract authority for
+producers and consumers:
+
+```ts
+import {
+  LOCAL_MESSAGE_BUNDLE_V1_SOURCE_TRANSFORM_VERSION,
+  parseLocalMessageBundleV1Manifest,
+  parseLocalMessageBundleV1Record,
+} from "@hraness/message-like-me/message-bundle-v1"
+```
+
+It exports the exact readonly record and manifest types, fixed artifact
+inventory, safety bounds, compatibility constants, canonical bundle-digest
+helpers, and strict pure parsers. Those parsers operate on already decoded
+unknown values and perform no filesystem, credential, provider, network, AI,
+analytics, or message-sending work. The CLI adds private filesystem and graph
+validation around the same parsers.
+
+## Directory inventory
+
+The input is a normalized absolute path to a current-user-owned physical
+directory with mode `0700`. It contains exactly these mode-`0600`, singly
+linked physical files:
+
+```text
+manifest.json
+accounts.ndjson
+participants.ndjson
+conversations.ndjson
+messages.ndjson
+reactions.ndjson
+tombstones.ndjson
+```
+
+The six artifacts always exist, including when they are empty. Every artifact
+uses canonical JSON, one object per line, and one final newline per record.
+Empty artifacts contain zero bytes. `manifest.json` is canonical JSON followed
+by one newline and is written last by the producer.
+
+The importer rejects symbolic links, extra files, ownership or mode changes,
+files that change while read, invalid UTF-8, noncanonical JSON, blank records,
+missing final newlines, count or byte mismatches, and digest mismatches.
+
+## Bounds
+
+Version one has these hard importer and producer ceilings:
+
+- 128 connected accounts;
+- 500,000 records across all six artifacts;
+- 512 MiB across all six artifacts;
+- 2 MiB for one encoded NDJSON record, including its final newline;
+- 1 MiB of UTF-8 for one message body;
+- 1,024 UTF-8 bytes for an identifier, sort key, or provider revision;
+- 8 KiB of UTF-8 for a display name, handle, title, reaction body, or
+  attachment filename;
+- 256 UTF-8 bytes for an attachment MIME type;
+- 10,000 known participants in one conversation;
+- 256 attachment metadata items in one message; and
+- 128 unique categorical warning codes.
+
+Custom producer limits may only lower the total record, byte, and line bounds.
+All timestamps are canonical millisecond UTC strings equal to
+`Date#toISOString()` output. Identifiers are nonempty and contain no ASCII
+control characters. Network and warning values are bounded lowercase tokens.
+
+## Manifest integrity
+
+The manifest declares source and provider versions, collection timestamps,
+completeness, privacy guarantees, per-kind counts, and each artifact's exact
+record count, byte length, and lowercase SHA-256.
+
+Artifact SHA-256 covers the file's exact bytes, including every final newline.
+Artifacts appear in the fixed directory order shown above. The bundle digest
+is:
+
+```text
+SHA256(UTF8(canonicalJson(manifest with the entire integrity property omitted)))
+```
+
+The manifest file's own SHA-256 covers its exact canonical bytes plus final
+newline. It is returned by the producer and recorded by Message Like Me, but is
+not embedded in the manifest.
+
+The privacy declaration is fixed to `private-local`, `metadata-only`
+attachments, excluded provider URLs, and excluded credentials. This is an
+interchange constraint, not anonymization. Bodies, timestamps, handles,
+account coordinates, and relationship graphs remain private.
+
+## Account realms and provenance
+
+Every line has `schemaVersion`, `kind`, a bundle-local `id`, `accountId`,
+`network`, and provenance:
+
+- `providerId` is the stable provider coordinate for that entity;
+- `providerRevision` preserves a provider revision when one exists;
+- `observedAt` records when the producer observed this record; and
+- `connectedAccountProviderId` is the stable connected-account coordinate.
+
+An account line has `id === accountId` and
+`provenance.providerId === provenance.connectedAccountProviderId`. Every other
+record must match one account line on `accountId`, `network`, and connected
+account coordinate. Bundle-local IDs exist only for joins inside this one
+bundle. Message Like Me derives its stored source and entity IDs from stable
+provider, connected-account, and self-participant coordinates with a private
+per-install HMAC key. The mutable network label is source metadata and never
+part of that identity namespace.
+
+Provider IDs must be unique within one entity kind and account. Validation
+errors name the record kind and ordinal, never the foreign coordinate. Message
+and reaction provider IDs are independent domains and may contain the same
+value. Message Like Me assigns a separate internal timeline coordinate when a
+dated reaction is represented in the normalized messages table; the raw
+reaction coordinate remains in the reaction fact and private provenance.
+
+## Identity and conversation rosters
+
+Each account names one self participant. Participants carry optional display
+names and handles plus `isSelf`. Conversations carry their known participant
+IDs and `participantsComplete`:
+
+- `true` is the only positive assertion that the roster is complete;
+- `false` or `null` means the producer cannot assert completeness; and
+- a complete direct roster must contain exactly the account's one self
+  participant and one non-self participant.
+
+Message senders and reaction actors must agree with direction and any complete
+roster. Message Like Me may expose an exact email or E.164 handle from the one
+non-self participant of a complete direct conversation to local Contacts
+matching. It never uses an incomplete roster for that join.
+
+## Messages, replies, and attachments
+
+`sentAt` is the message's actual temporal coordinate. `sortKey` is an opaque
+provider ordering key. Within one account and conversation, Message Like Me
+orders lexical `sortKey`, then `sentAt` and stable provider ID as deterministic
+tie-breakers.
+
+`bodyTruncated: true` means the body cannot be prose evidence. The record still
+becomes a text bubble for tempo, reply, and response-shape analysis. A message
+with deletion state must have a null body. Attachment entries contain metadata
+only; they never contain paths, URLs, or media bytes.
+
+A reply target has a required provider ID and an optional bundle-local ID. When
+the local ID is present, it must resolve to the same provider coordinate in the
+same account and conversation. A null local ID preserves a reply to a message
+outside the bounded artifact.
+
+## Edits and deletion
+
+Edits are discriminated:
+
+- `in-place` records a terminal mutation under the same provider message ID and
+  never suppresses that message; and
+- `replacement` identifies a different provider message in the same account
+  and conversation.
+
+Replacement targets may be outside the bounded artifact. In-bundle targets
+must agree on local and provider coordinates. Replacement graphs must be
+non-self, single-terminal, and acyclic. A validated replacement suppresses the
+older version as evidence.
+
+Message deletion state is explicit and carries the observation time and
+provider revision. Deleted bodies are null.
+
+## Reactions and tombstones
+
+A reaction has a required target provider message ID and an optional
+bundle-local target. When present, the local target must resolve to the same
+provider coordinate. `reactedAt` is nullable because the provider may not
+expose a reaction time. Producers never synthesize one. Active undated
+reactions contribute to fixed aggregate reaction counts, direction counts, and
+timestamp-coverage counts but never enter the message timeline, sessions,
+bursts, response episodes, or latency metrics.
+
+Tombstones identify a conversation, message, or reaction kind, required
+provider coordinate, optional bundle-local coordinate, deletion time, scope,
+and provider revision. Account and participant tombstones are outside the
+version-one contract. A nonnull local coordinate must resolve inside the same
+account and agree with
+the provider coordinate. A null coordinate preserves deletion knowledge for
+an entity outside the bounded artifact.
+
+## Reimport semantics
+
+Version-one bundle completeness is `bounded-local`, `truncated`, or `unknown`.
+None is authoritative for deletion by absence. Reimport therefore upserts
+present records and retains prior records omitted by a later bundle. Explicit
+message deletion, removed reaction state, replacement edges, and tombstones
+are applied separately. A valid later reappearance clears the matching
+suppression. Present and retained messages are reranked together by the provider
+ordering coordinates, so a bounded backfill converges with a fresh import of
+the same final records.
+
+The manifest completeness kind and reason apply conservatively to every
+account. Stored `observedFrom` and `observedTo` bounds are derived from the
+dated message and reaction records for that account, so one account never
+inherits another account's time range. An account with no dated timeline
+records has null bounds.
+
+`timestamps.createdAt` is monotonic within one stable connected-account source.
+An older bundle is rejected. An equal-time replay is accepted only when its
+manifest and input revision match exactly; an equal-time conflict is rejected.
+Native iMessage replacement remains scoped to its own source and cannot remove
+bundle history.

package/docs/local-message-bundle-v2.md

@@ -0,0 +1,167 @@
+# Local message bundle v2
+
+Local message bundle v2 is the native WhatsApp evidence boundary between a
+Wrench-owned Wacli adapter and Message Like Me. Wrench owns Wacli discovery,
+authentication, local synchronization, provider interpretation, and export.
+Message Like Me reads only the finished caller-owned directory. It never starts
+Wrench or Wacli, receives a WhatsApp credential or session database, accesses a
+network, or sends a message.
+
+The intended producer flow is:
+
+```sh
+bun add --global @hraness/wrench@0.16.3
+wrench whatsapp export-message-like-me \
+  --auth <whatsapp-auth-id> \
+  --output /absolute/private/path/whatsapp-bundle
+
+messagelikeme ingest bundle \
+  --input /absolute/private/path/whatsapp-bundle \
+  --json
+```
+
+The checked compatibility coordinates are Wrench v0.16.3 and official Wacli
+v0.15.0. Wrench owns that executable dependency and its authentication state;
+neither enters Message Like Me.
+
+The normative object schema is
+[`schema/local-message-bundle-v2.schema.json`](../schema/local-message-bundle-v2.schema.json).
+The runtime parser is stricter than JSON Schema where byte length, canonical
+timestamps, filesystem identity, exact JID semantics, account joins, digests,
+and graph laws require executable checks.
+
+## Immutable identity
+
+Message Like Me accepts exactly:
+
+- schema version `2`;
+- format `message-like-me.local-message-bundle`;
+- source ID `wacli-local`;
+- source-transform version `1.0.0`;
+- provider `whatsapp@0.15.0` (ID `whatsapp`, version `0.15.0`);
+- network `whatsapp` on every record; and
+- exactly one connected WhatsApp account.
+
+The manifest's provider coordinate is the exact official Wacli v0.15.0 used by
+the producer, not a compatibility wildcard. A semantic producer change
+requires a new supported source-transform version or bundle schema.
+
+Producers and consumers can import the dependency-free contract directly:
+
+```ts
+import {
+  LOCAL_MESSAGE_BUNDLE_V2_ARTIFACTS,
+  LOCAL_MESSAGE_BUNDLE_V2_SOURCE_TRANSFORM_VERSION,
+  parseLocalMessageBundleV2Manifest,
+  parseLocalMessageBundleV2Record,
+  parseLocalMessageBundleV2WhatsAppJid,
+} from "@hraness/message-like-me/message-bundle-v2"
+```
+
+Importing this module performs no filesystem, process, authentication, network,
+or messaging work.
+
+## Fixed private directory
+
+The bundle directory must be a normalized absolute, current-user-owned,
+physical mode-`0700` directory. It contains exactly:
+
+```text
+manifest.json
+accounts.ndjson
+participants.ndjson
+conversations.ndjson
+messages.ndjson
+reactions.ndjson
+tombstones.ndjson
+```
+
+Every file is a singly linked, current-user-owned, physical mode-`0600` file.
+The importer rejects symbolic links, hard links, inventory drift, concurrent
+changes, invalid UTF-8, blank or oversized records, noncanonical JSON, count or
+byte disagreement, and SHA-256 disagreement. The same public bounds as v1
+apply, except v2 admits exactly one account.
+
+`manifest.json` is canonical JSON followed by one newline. Every NDJSON record
+is one canonical JSON object followed by one newline. The manifest integrity
+digest covers its canonical projection without the `integrity` member;
+individual artifact digests cover their exact bytes.
+
+## WhatsApp coordinates
+
+The contract admits only canonical JIDs that establish a supported WhatsApp
+realm:
+
+- an E.164-backed user JID ending in `@s.whatsapp.net`;
+- a numeric privacy-preserving LID ending in `@lid`; or
+- a numeric group JID ending in `@g.us`.
+
+Status, broadcast, newsletter, mixed-case, plus-prefixed JID local parts, and
+unknown server forms are rejected. Accounts and participants use a user JID or
+LID. Direct conversations use the exact non-self participant JID;
+group conversations use a group JID. Complete direct rosters contain exactly
+one self and one non-self participant.
+
+A connected account or participant `handle` is the exact `+`-prefixed E.164
+projection only when its JID is an E.164-backed user JID. LIDs and group
+coordinates never mint a phone handle. This is the only v2 bridge to optional
+macOS Contacts enrichment. Names,
+titles, phone suffixes, timestamps, and LIDs are never used as fuzzy contact
+matches.
+
+Every message has a proven incoming or outgoing direction. Direct-message
+senders are proven. A group or system row may retain a null sender when the
+bounded local observation cannot prove one, and it cannot establish overlap.
+Reply, edit, deletion, reaction, attachment, and tombstone fields retain the
+same strict meanings as v1. Attachment bytes, provider URLs, credentials, Wacli
+session state, database paths, and unmodeled provider payloads are excluded.
+Unsupported status, broadcast, and newsletter records are not represented as
+ordinary conversations.
+
+## Coverage and replay
+
+A linked-device export is a bounded local observation. It does not prove that
+all remote WhatsApp history exists locally. `bounded-local`, `truncated`, and
+`unknown` completeness remain non-authoritative: omission in a later bundle
+does not delete retained evidence. Only explicit deletion, replacement, or
+tombstone records suppress evidence. A later explicit record reappearance
+clears that suppression. Creation timestamps remain monotonic per source.
+
+## Beeper WhatsApp overlap
+
+A native Wacli source and an older Beeper WhatsApp source have separate stable
+namespaces. If the same exact account is already present, the importer stops and
+requires the caller to name that source:
+
+```sh
+messagelikeme ingest bundle \
+  --input /absolute/private/path/whatsapp-bundle \
+  --overlap-source <beeper-whatsapp-source-id> \
+  --json
+```
+
+`--overlap-source` is not a fuzzy merge switch. Reconciliation requires the
+same exact self E.164 account, complete one-to-one direct-peer E.164 identity,
+and at least one unambiguous shared message with the same sender role,
+timestamp, direction, text body, message kind, and attachment count. Bodyless
+messages, groups, names, phone suffixes, approximate timestamps, and ambiguous
+duplicates cannot prove equivalence.
+
+Both source provenances and all source-unique history remain stored. Proven
+message and reaction duplicates contribute once. The native Wacli conversation
+is the preferred action route and carries the exact private `whatsappJid`
+coordinate. Its proven Beeper duplicate remains evidence with reason
+`superseded-route`. Reimport rechecks the named proof atomically and fails
+closed on disagreement.
+
+## Privacy and action boundary
+
+Ordinary source, contact, metrics, and CLI receipts expose only pseudonymous
+IDs, counts, digests, coverage, and categorical health. Exact JIDs, E.164
+handles, account coordinates, message bodies, and source metadata stay in the
+private store or explicit owner-only artifacts.
+
+Message Like Me may write an exact `whatsappJid` route into an explicit
+mode-`0600` route inventory. That coordinate is evidence for a separate Wrench
+binding and preview. Message Like Me does not authenticate, synchronize,
+preview, submit, or send through WhatsApp.