@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to Messaging. Every package releases together at one version.
+Versions follow [Semantic Versioning](https://semver.org); see
+[docs/distribution.md](docs/distribution.md#versions-and-compatibility) for what a version promises.
+
+## [Unreleased]
+
+## [0.7.1] - 2026-11-09
+
+**No store change.** A 0.7.0 home and a 0.7.0 relay database open unchanged, and a 0.7.0 messagingd or relay still
+opens what 0.7.1 writes. 0.7.0 was the last store reset: from 0.7.0 on, stores only grow (the owner's decision of
+8 November, when the first people other than the owner began to use Messaging).
+
+### Changed
+
+- **A refused store has a code and an exit status of its own** (spec §8.8). messagingd and messaging-relay exit
+  **78** (`EX_CONFIG`; `STORE_REFUSED_EXIT` in `@messaging/core`) for a store they do not read, instead of 1. messagingd
+  prints one line, `messagingd: store_refused: …`; the relay's event is still `relay.store_refused`. A new error code,
+  `store_refused`, is what `messaging daemon start` reports, with its own next step, and what agent clients
+  report (`TOOL_REMEDIES`). Clients match the status or the code, never the wording. The relay's systemd unit does
+  not restart on 78.
+- **A refusal says why** (spec §8.8): `pre-reset` (no store generation, or another: start over by moving the home
+  aside) or `newer` (a `min_reader` above the reader's schema: upgrade and keep the home). messagingd prints
+  `messagingd: store_refused: <reason>: …`; `StoreRefusedError.reason`, `reason` in `messaging --json` errors and in
+  agent tool errors carry it, each reason with its own next step. Moving the home aside is offered only for
+  `pre-reset`. The relay's event is `relay.store_refused {db, reason, message}`: **its `reason` field is now the
+  reason, and the text moved to `message`**.
+- **A home moved aside is named `<home>.pre-reset-<UTC timestamp>`** (spec §8.8), with no version in the name, and
+  messagingd's start-over text says so.
+
+### Fixed
+
+- **A roster sync that succeeds on retry clears the error it reported.** messagingd kept the old `relay.lastError`
+  after a later sync succeeded.
+- **The darwin executables are signed with a fixed 4 KiB page size,** so any Mac rebuilds a release byte for byte.
+  The default page size of `codesign` depends on the macOS version (docs/distribution.md).
+- **publish.yml stages `./<tarball>`.** npm read a bare `dir/name.tgz` as a GitHub shorthand, so 0.7.0's packages
+  were staged by hand; `npm run test:pack` now refuses a stage line without `./`.
+
+### Documentation
+
+- The relay's operator docs give its limits and flags as built: pre-auth limits 1024 and 128, `--max-connections`,
+  `--max-buffered-bytes`, `--preauth-*`, `--metrics` and `--sth-witness`. A test fails when they drift.
+- The README describes both identity modes: the Jelly directory and self-hosted roster teams.
+
+### Tests
+
+- The architecture tests enforce where SQLite, network listeners and raw sockets may be used, as AGENTS.md says.
+- A lying relay that withholds the roster entries a signed head commits to is caught (`heads.ts`).
+- The timing tests wait on events and bound cost in units measured on the same machine, not in wall-clock time, so
+  they pass on loaded and slow runners.
+
+## [0.7.0] - 2026-11-08
+
+### Store reset
+
+- **0.7.0 resets the stores.** Messaging is new and its owner is its only user, so its stores restart instead of
+  carrying the migrations of 0.1.0 to 0.6.0 ("reset now, grow later", spec §8.8). The daemon's store
+  (`messaging.db`, store schemas 3-9) and the relay's database (schemas 1-4) are each squashed into one baseline,
+  schema 1, with the same tables, columns and indexes as before (the new snapshots are byte-identical to the old
+  `9.json` and `4.json`). Every migration and the code that read older stores are gone.
+- **Earlier stores are refused, never opened or changed.** A store records its generation (2); a daemon store or
+  relay database of 0.6.0 or earlier has none. messagingd refuses such a home before it reads or writes anything in
+  it, and messaging-relay exits with one line. Both say how to start over: stop the daemon or relay, move the home
+  (or the database, with its `-wal` and `-shm` files) aside, and set it up again (`messaging login`, or `team
+  create` / `team join`). Inbox, transcripts, grants, tasks and notices stay in the old home, which messagingd
+  0.6.0 still opens; a 0.6.0 snapshot does not restore. Reset the managed relay and every home that uses it on the
+  same day: the relay's directory restarts empty.
+- Until the first release another person uses, a store change edits the baseline, raises the generation and
+  resets the stores again, and its release notes say so. From that release on, stores only grow.
+- Stored inbox peers, task peers and provenance now use the API's `device` and `agent`, not the first shape's
+  `machine` and `session`.
+
+### Security
+
+- **Before `hello`, the directory serves heads, never a person's log** (spec §15.10). `dir.lookup` and `dir.device`
+  from a socket that has not authenticated now answer only what a binding or link-approved device needs: log heads,
+  the tree head, and whose device a key is. Before, they returned a person's whole device log, and every entry's
+  Jelly token carries the account's email and name, so anyone who knew a person id or a device key could read them,
+  even with `discoverable: false`.
+- **A relay-wide budget for slow readers and a cap on connections.** `--max-buffered-bytes` (default 256 MiB) bounds
+  the bytes buffered to slow readers across every socket; past it the relay drops the sockets furthest behind.
+  `--max-connections` caps authenticated connections (close 1013). The pre-auth limits are flags:
+  `--preauth-connections` (default 1024) and `--preauth-per-address` (default 128, sized for every client
+  reconnecting after a restart, and for office NATs).
+
+### Added
+
+- **`@joe-broadhead/messaging` is published on npm**, beside the five `messaging-bin-*` packages, so the plugin and
+  other clients build against it instead of a vendored tarball. Releases are staged on npm by CI and the owner
+  approves each package (docs/distribution.md "Releasing"); `scripts/verify-published.mjs` checks that npm serves the
+  bytes the release run built. The repositories are private, so there is no npm provenance.
+- **Relay `/metrics`** (`--metrics <host>:<port>`, off by default): Prometheus text on a listen address of its own,
+  with no person, device or envelope ids in labels or values (spec §7).
+- **A tree-head witness** (`--sth-witness`, default `<db>.sth-witness`): an append-only file of every tree head the
+  directory published, with each epoch's leaf hash. A directory database behind it does not start, so restoring an
+  old copy over a newer one is caught before clients see a rollback. Keep it where a restore of the database does not
+  reach.
+- **A refused database is one JSON event,** `relay.store_refused`, and the relay exits 1 without touching it.
+- **A process policy for errors that escape every handler,** in the relay and the daemon: log the error (without
+  secrets) and exit non-zero, so the supervisor restarts the process.
+- **`@joe-broadhead/messaging/testing/jelly-id`:** the Jelly ID issuer double, for other repositories' tests of a
+  hosted realm (the plugin's real-host suite). Like the other testing entries, nothing in the package's commands or
+  runtime libraries loads it.
+
+### Removed
+
+- **Direct binding** (spec Appendix A, experimental and off by default). The daemon's LAN links, config
+  `transport.direct`, presence `direct` and the `"direct"` feature, `DOMAIN.directAuth` and `DOMAIN.directLink`, core's
+  direct handshake and record cipher (`DirectCipher`, `directKeys`, `directTranscript`, `directAuthPayload`,
+  `directEphemeral`, `sealDirectBox`, `openDirectBox`, `DirectEndpoint` and the `Direct*` frame schemas), and the vector
+  file `direct.json`. The daemon no longer depends on `ws`. A home whose config still has `transport` fails to start
+  on the unknown key.
+- **The A2A gateway**: `packages/gateway`, the `messaging-gateway` command and its bundle. Spec §10 is a stub so the
+  later section numbers stay. Core drops the A2A HTTP shapes only it used (`AgentCard` and its parts, and the
+  `SendMessage`, `GetTask`, `CancelTask`, `SubscribeToTask` and `ListTasks` request and response shapes).
+- **External principals** (wire): `external` in `MessagePayload`, `Provenance` (§6.6), `DelegationGrant` and
+  `DelegationSummary` (§6.7, "External roots") and `msg.send`, and the rule that refused every message to a session of
+  agent `a2a-gateway` (§8.3). A peer's `external` is dropped as an unknown key; a client's is refused by strict
+  `msg.send`. Agent tools and fences lose `external`, `via` and `principal`. Vectors: `delegation.json` and
+  `negative.json` lose their external cases.
+- **The `service` member role** (wire). A member is `admin` or `member`. Invites (`invite.create`, the ticket,
+  `team.invite`, `InviteSummary`) and `team.add` lose `role`, and `messaging team invite` and `team add` lose
+  `--role`: an invite or an admitted machine is always a `member`, and a redeem that claims any other role is
+  `invite_invalid`. The roster vectors' hashes change with the invite entry.
+- `inbound.refuse` and `inbound.wake` in `config.json`: consent replaced them, and the config refuses them now like
+  any unknown key.
+- The spec's sentences about earlier builds' envelope ends and the 0.1.0 header. The schemas still refuse them; the
+  negative vector `header-0.1.0` is now `header-unknown-fields`.
+
+### Fixed
+
+- **`messaging login` works against Jelly's built device sign-in** (Jelly's resource-token contract v1.2 §12, hey-jelly
+  `9d46d17`). Jelly ID sends no `verification_uri_complete`, by design: a link with the code in it turns a phished
+  code into one click. The daemon required it, so every sign-in through the browser failed with `jelly_unavailable`.
+  Now the person opens Jelly ID's page and types the code. The `messaging login`, `identity replace` and `erase`
+  commands print the page and the code (`--open` opens the page, never a link with the code), and a
+  `verification_uri_complete` in an answer is ignored. The code answer is read as Jelly builds it: `interval` is
+  required, `device_code` is 22-256 characters, and a page with a query or fragment is refused.
+- **No false directory alarm when the tree head moves during a read** (spec §15.7, §15.9 "One tree head per view").
+  A directory home that read a person at tree head n while another read (a push, a watch, a send) stored them at
+  n+1 verified the older view against the newer state. The newer map rightly commits to more, so an honest directory
+  raised `directory_inconsistent` ("the map does not commit to the log and keys served", or a keys rollback), and the
+  older view could replace the newer one. Each view is now verified against what the home held when it asked. When
+  another read stored the person meanwhile, the two states are checked against each other (`checkPersonSuccession`
+  in `@messaging/core`: the later one must extend the earlier one's log and keys) and the newer one is kept. A real
+  fork or rollback between epochs still raises the alarm, with its evidence. The relay was not at fault: it serves
+  each view from one epoch.
+
+- **A failing store never crashes the relay.** Every timer (purge, directory epochs, the deletion feed) catches a
+  store error, logs it and retries with backoff; `/readyz` answers `store_failing` meanwhile, so a full disk no longer
+  crash-loops the relay and drops every socket.
+- **An epoch is stored before the directory changes its memory,** so a failed write can't leave a published tree head
+  the database never held.
+- **Litestream's own tables don't make a new relay database look used** (spec §8.8 "Opening"); any other table still
+  does.
+
+### Changed
+
+- **Group commit in the relay:** the sends and receipt acks of one event-loop turn share one fsync. A connection's
+  replies keep the order of its frames.
+- **CI runs every shipped binary on its own platform:** Linux x64 and arm64, macOS arm64 and x64, and Windows x64, each
+  building its executable and running the end-to-end suite through it.
+- **IPC: `verificationUriComplete` is gone** from `device.login`, `device.login.status`, the `login` event, and the
+  `sign-in` steps of `identity.replace` and `directory.erase` (spec §8.2). A client shows `verificationUri` and
+  `userCode`. The plugin's "Sign in with Jelly" must stop reading it.
+- A poll answered `invalid_request`, which Jelly's token route does not define, is retried like an outage instead of
+  failing the sign-in.
+- The Jelly ID test double answers as Jelly's built routes do: their order of checks, a denial that stays denied, an
+  approval that expires if it is not collected in time, 5 approvals per account and resource a day, routes that
+  answer without device sign-in (`401 invalid_client`), and a consent page that refuses a code from a link or a
+  stale sign-in. `test/doubles/jelly-device-sign-in.md` is a cited excerpt of Jelly's contract, and the conformance
+  test reads it instead of Messaging's proposal.
+
+## [0.6.0] - 2026-11-07
+
+The trust gaps closed before Jelly turns on browser device sign-in (contract v1.2). No store migration (daemon 9,
+relay 4); the device log gains one rule.
+
+### Security
+
+- **A sign-in through the browser vouches for one act** (spec §15.3, rule 7). The token of a sign-in (`src:
+  "device"`) that bound or attested a device is refused in any other log entry and by `dir.erase`, by clients and
+  the directory alike. Before, a device bound with one phished user code could spend the same token, within its ten
+  minutes, on removing the person's other devices or erasing the account. A Jelly host's token is exempt. Vectors:
+  `binding.json` `browserLog.invalid`.
+
+### Added
+
+- **"New device on your account"** (design §2.8; spec §8.2 "Notices"): every other device of the person files an
+  `alert` notice with `device` (label, kind, vouch, how it was bound, its approver, whether it is current, and how
+  this device removes it: `token`, `sign-in` or `team`) for each device added, vouched, removed or replaced in its
+  own verified log, including what it missed while offline. In a roster realm, a machine admitted for the person.
+  `messaging notices` shows them and how to remove one.
+- **A contact's devices changed**: `contacts.list`'s `reach` carries `devicesChangedAt` for 7 days, and `people.get`
+  lists `deviceChanges`; `messaging people <person>` shows them.
+- **Trust that ends within 7 days** is an `alert` notice (design §5.2, §13.11).
+- **`identity.replace {token?, label?}`** and its preview (admin tier; design §13.8): a home restored from a backup
+  or `daemon.snapshot` (`keys_missing`), one that runs `restored`, or one that wants a fresh key gets new keys, binds
+  them, re-signs its predecessor's grants (nothing lapses) and unbinds the predecessor with reason `replaced`; tasks
+  continue under the successor rule. A Jelly host's token does it in one step (the plugin's `device.bind`, while
+  `device.status` says `binding: "replace"`); through the browser it takes two sign-ins. `messaging identity replace`.
+- **`directory.erase {token?}`** and its preview (admin tier; design §3.7): erases the person's account from this
+  device, with a host's token or a fresh sign-in; the preview says exactly what is lost and what stays, and the
+  directory's 10 erasures a day are said plainly. `messaging erase`.
+
+### Fixed
+
+- A device whose account was erased reports `removed`, and acts for no one.
+- A directory home watches every person it holds, from the first fetch, and reads a person again once the
+  directory has a new watch (spec §15.9, "Who it watches"). Before, a person fetched between their bind and their keys
+  statement was not watched (only persons with a sealable device were), so their keys reached this device only after
+  the 24-hour freshness bound. This was the cause of the `lying-directory` "a split view…" flake, which also no longer
+  races a real-time 100 ms heartbeat: it grows the forked directory by explicit epochs.
+
+## 0.1.0 to 0.5.0 - 2026-11-05 to 2026-11-07
+
+Pre-release iterations. Their changes are in the git history (`git log --grep '^release: '`), and the published
+`@joe-broadhead/messaging-bin-*` packages of those versions stay on npm.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Broadhead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Messaging
+Copyright (c) 2026 Joe Broadhead. Licensed under the MIT License (see LICENSE).
+
+The design was informed by concepts in reason-machines/reason-network (MIT OR Apache-2.0):
+a team session directory, delivery tiers, idempotent sends, staged receipts and framed peer input.
+No code, wire format or names were copied from it.
+
+The data model follows the A2A protocol v1 specification (Apache-2.0, Agentic AI Foundation).
+
+The LOOKALIKES and WIDE tables in packages/core/src/peer-text.ts are derived from Unicode 17.0.0 data
+files (confusables.txt from UTS #39 and EastAsianWidth.txt from the Unicode Character Database),
+Copyright Unicode, Inc., used under the Unicode License v3 (https://www.unicode.org/license.txt).

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @joe-broadhead/messaging
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Messaging in one package: the four commands, the client libraries the OpenCode plugin builds against,
+and the protocol spec. It has **no dependencies**: every file in `dist/` carries what it runs, and only
+Node built-ins stay imports. It needs Node >= 22.15 (`node:sqlite`). It is public on npm: CI stages each
+release, and it is published only when the owner approves it on npm; `npm run pack:tarballs` in the
+[messaging](https://github.com/joe-broadhead/messaging) repository builds the same tarball locally.
+
+## Commands
+
+| Command | What |
+|---|---|
+| `messaging` | The command line for people: teams, contacts, messages, tasks, chat, the daemon. |
+| `messagingd` | The per-machine daemon. |
+| `messaging-relay` | The relay a team's machines connect to. |
+| `messaging-mcp` | A stdio MCP server with the eight agent tools, for non-OpenCode agents. |
+
+Each is one self-contained file in `dist/bin/`.
+
+## Libraries
+
+| Export | What |
+|---|---|
+| `@joe-broadhead/messaging/core` | Wire and IPC contracts, protocol logic, the agent tools' schemas and operations. Pure. |
+| `@joe-broadhead/messaging/ipc` | The local daemon API client (JSON-RPC over a Unix socket) and its paths. |
+| `@joe-broadhead/messaging/zod` | The zod these libraries use; compose their schemas with it. |
+| `@joe-broadhead/messaging/core/testing`, `…/ipc/testing` | Test helpers (a recording fake daemon, fixed ids). Never for production code. |
+| `@joe-broadhead/messaging/testing/jelly-id` | A Jelly ID issuer double over HTTP (resource tokens, key history, the deletion feed, device sign-in), for tests of a hosted realm. Never for production code. |
+| `@joe-broadhead/messaging/bin/messagingd.js`, `…/bin/messaging.js` | The daemon and CLI files, for a plugin that ships them. |
+| `@joe-broadhead/messaging/spec/messaging-v1.md` | The protocol spec, for consumers' drift tests. |
+| `@joe-broadhead/messaging/third-party.json` | Per export, the third-party packages inlined in it, with their licences. |
+
+The libraries are modules, not bundles: tsc's output of core and ipc and zod's own ESM files in
+`dist/lib/modules/`, importing each other by relative path. So an error class or a schema has one
+identity across `./core`, `./ipc` and `./zod`, and a consumer that bundles them tree-shakes them as
+it would the sources (the package declares `sideEffects: false`). Their declarations (`dist/types/`) import `zod` for types:
+a consumer that type-checks against them installs `zod` 4 as a dev dependency.