@ours.network/notifications 0.1.1

package/mufl_code/core/docs/workflows/introductions.md

@@ -0,0 +1,60 @@
+# Introductions (core.connect)
+
+A control plane bound to **both** parties can connect two nodes without a new out-of-band
+invite: it already holds each managed node's self-signed address document (captured in
+`peer_ads` when the node was established as its contact), so an introduction is simply sending
+each node the *other's* signed document. There is no SAS and no confirmation step — the
+bound-CP channel is the authorization, and the node-side capability gate is the authoritative
+"do I accept introductions".
+
+Traced from [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`introduce`, `introduce_to_group`, `emit_pair`, `handle_ingest_connect_descriptor`,
+`require_cluster_cp_or_abort`).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant H as CP host
+    participant CP as Control-plane packet
+    participant A as Node A packet
+    participant B as Node B packet
+
+    H->>CP: introduce ($peer_a, $peer_b)
+    Note over CP: both must be established contacts<br/>(peer_ads holds their signed address documents)
+    CP->>A: ingest_connect_descriptor ($peer_ad of B, $peer_name) - encrypted channel
+    CP->>B: ingest_connect_descriptor ($peer_ad of A, $peer_name) - encrypted channel
+
+    Note over A: gates (same on both nodes):<br/>1. require_cluster_cp_or_abort - relay came from MY bound CP,<br/>or from the CP my root designated (verified against pinned root keys)<br/>2. my own live manifest advertises core.connect (self_supports)<br/>3. the peer document's self-signature verifies (proof-of-possession)
+    Note over A: new contact registered immediately under the CP-supplied<br/>display name - already-known peer just refreshes its stored document
+    A-->>A: notify $introduced (or $reintroduced) to its host
+    B-->>B: notify $introduced (or $reintroduced) to its host
+
+    Note over A,B: A and B are now direct contacts - messages flow peer-to-peer,<br/>the CP is not on the path
+```
+
+## Variants and entry points
+
+- **`introduce`** — the 1:1 pair, host-fired on the CP.
+- **`introduce_to_group`** — fan-out: one joiner is introduced to every member of a list (the
+  cluster-root case: a new subagent meets all existing ones). Same `emit_pair` relays, once per
+  member, in a single transaction.
+- **`core.connect` / `introduce` verb** — the same composition reached through the
+  [control-envelope dispatch](./control-verbs.md) (`connect_handler`), so a remote controller
+  can trigger it.
+
+## Trust details
+
+- The **CP-supplied display name is unauthenticated by design** — a receiver-chosen label. The
+  document's self-signature is the only identity the receiver trusts; the cid is key-derived,
+  so an existing contact's keys can never be silently overwritten by a different keyset.
+- The gate accepts a relay on **either** of two grounds: the node ran the 6-digit ceremony
+  itself (sender is its own `monitoring_proxy`), or — for cluster children — the sender is the
+  CP the node's *root* designated, re-verified against the pinned root identity on every call
+  (`root_cp_binding` + `root_ad`), with no per-child ceremony.
+- The node-side manifest check makes "supports introductions" **enforced**, not advisory: a
+  node whose manifest does not advertise `core.connect` rejects the relay regardless of who
+  sent it. The CP-side pre-check (don't try to introduce a node that doesn't support it) is a
+  courtesy the daemon performs via `get_manifest`.
+
+For how a cluster child receives its CP contact in the first place (host-injected, not
+network-introduced), see [Cluster lifecycle](./cluster.md).

package/mufl_code/core/docs/workflows/messaging.md

@@ -0,0 +1,75 @@
+# Send & receive messages
+
+The message path is the protocol's chokepoint: every text and file between contacts flows
+through `send_message` / `handle_receive_message` (and their file twins), which is also where
+the forced monitoring copy is generated. Message **storage is app-side**: the core validates,
+resolves the sender, and hands the record to the app-injected hooks (`on_message_sent`,
+`on_message_received`, …) wired at `a2a_messaging::init`.
+
+Traced from [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`send_message`, `handle_receive_message`, `send_file`, `handle_receive_file`,
+`monitor_copy_actions`).
+
+## Text message
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant SH as Sender host
+    participant S as Sender packet
+    participant P as Peer packet
+    participant PH as Peer host
+    participant CP as Bound control plane (optional)
+
+    SH->>S: send_message ($contact, $text, $reply_to?)
+    Note over S: resolve_contact - mint fresh $wire_id
+    alt peer address document present
+        S->>P: receive_message ($text, $wire_id, $reply_to) - encrypted channel
+        Note over S: on_message_sent hook (app storage)
+        S->>CP: receive_monitoring_copy (direction "out") - forced, if bound
+        S-->>SH: $sent_to, $wire_id
+        Note over P: check encrypted - sender from envelope $from -<br/>contact lookup gives $sender_name (NIL if unknown)
+        Note over P: on_message_received hook - the app decides<br/>storage or rejection of an unknown sender
+        P->>CP: receive_monitoring_copy (direction "in") - forced, if the PEER has a CP bound
+        P-->>PH: app-hook actions (store, notify)
+    else degraded contact (no peer address document)
+        Note over S: queue in deferred_msgs (cap 50 per contact)
+        S->>P: request_contact_restore - see the contact-restore flow
+        S-->>SH: $deferred TRUE, $queued
+    end
+```
+
+The inbound name is `::actor::receive_message` (`receive_message_tx`) — kept for compatibility
+with pre-migration clients; consumers keep a one-line `::actor::` shim that delegates to this
+library.
+
+## File transfer
+
+`send_file` mirrors `send_message` exactly — same `wire_id` namespace (a reply can point across
+messages and files), same hook pattern (`on_file_sent` / `on_file_received`), and the inbound
+rides `::a2a_messaging::receive_file` (`receive_file_tx`, a library-routed name — no legacy
+shim). Two deliberate differences:
+
+- **No queueing**: `send_file` to a degraded contact aborts fast with an explicit error instead
+  of queueing bulk binary; a `send_message` to the same contact queues and drives the restore.
+- **Metadata-only monitoring**: the forced copy for a file carries `file_monitor_summary` —
+  name, mime, size — never the bytes.
+
+## Reading, receipts, and reply threading
+
+There is **no mark-read or read-receipt transaction in the core**. The inbox lifecycle (unread /
+processed, receipts, retention) belongs to the consuming app, built on the storage hooks. What
+the core does provide cross-side is:
+
+- `$wire_id` — a stable id stamped on every message and file by the sender; the receiver's own
+  message ids stay local to its inbox.
+- `$reply_to` — an optional pointer (`$wire_id` + optional sentence index) that threads a reply
+  to an earlier message on either side.
+
+## Forced monitoring copies
+
+Both the send and receive paths append `monitor_copy_actions` *after* the app hook, as
+unconditional core code. It self-gates on `monitoring_proxy` — nothing is emitted when no
+control plane is bound; when one is, the copy rides a distinct transaction name
+(`receive_monitoring_copy`), so copy traffic is never itself monitored. See
+[Monitoring bind & copies](./monitoring.md).

package/mufl_code/core/docs/workflows/monitoring.md

@@ -0,0 +1,84 @@
+# Monitoring bind & forced copies
+
+Monitoring is bound by a **6-digit ceremony** and enforced at the message chokepoint: once a
+control plane is bound, every send and receive emits one re-encrypted copy to it as
+unconditional core code. The gate state (`monitoring_proxy`, `proxy_pending`) is `hidden` in
+`a2a_messaging`, so only that library can mutate it — an app cannot switch monitoring off by
+assignment.
+
+Traced from [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`set_proxy_pending`, `do_verify_proxy_code`, `monitor_copy_actions`, `disable_monitoring`),
+[`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm)
+(`monitoring_handler`), and
+[`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm)
+(`handle_receive_monitoring_copy`).
+
+## The bind ceremony
+
+The code is generated host-side (MUFL has no random source), expires after 300 seconds, and
+allows 3 attempts. Both entry paths — the legacy host-relayed `verify_proxy_code` transaction
+and the `core.monitoring` / `bind` capability verb — run the **same** ceremony function,
+`do_verify_proxy_code`.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant H as Node host
+    participant N as Node packet
+    participant CP as Control-plane node
+
+    Note over H: operator initiates - host generates a 6-digit code<br/>and shows it to the user out-of-band
+    H->>N: set_proxy_pending ($code, $proxy)
+    Note over N: proxy_pending = code + proxy cid + created_at + attempts
+
+    CP->>N: control_message carrying core.monitoring / bind ($code)
+    Note over N: dispatch - auth class "bootstrap" (pre-bind, code possession IS the auth)
+    Note over N: monitoring_handler - do_verify_proxy_code:<br/>expiry 300s - sender must be the pending proxy -<br/>wrong code burns one of 3 attempts (returned as data,<br/>not abort, so the counter persists)
+    alt code verifies
+        Note over N: monitoring_proxy = ($proxy_cid, $bound_at) - pending cleared
+        N-->>CP: response: $manifest, $members, $config, $version (one-shot bootstrap)
+    else wrong code / expired / wrong sender
+        N-->>CP: response: bind_failed + reason
+    end
+```
+
+## Forced copies at the chokepoint
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant N as Monitored node
+    participant P as Peer
+    participant CP as Bound control plane
+
+    N->>P: send_message - encrypted channel
+    N->>CP: receive_monitoring_copy (direction "out", $peer_cid, $date, $body)
+    P->>N: receive_message from the peer
+    N->>CP: receive_monitoring_copy (direction "in")
+    Note over CP: gate: sender must be a known contact - copy $version must be 1
+    Note over CP: on_monitoring_copy_received hook - storage is the CP app's
+```
+
+Properties, all visible in `monitor_copy_actions`:
+
+- **Self-gating**: with no `monitoring_proxy` bound the function returns no actions — zero
+  overhead for unmonitored nodes.
+- **No recursion**: copies ride the distinct name `::a2a_monitoring::receive_monitoring_copy`
+  (`receive_monitoring_copy_tx`), never `send_message`, so copy traffic is not itself monitored.
+- **Fire-and-forget**: no local queue, no liveness wait — an offline CP's copies sit with the
+  ADAPT broker.
+- **Files are metadata-only**: name, mime, and size; never the bytes.
+- **App hooks cannot suppress it**: the copy is appended after the app's storage hook, in core
+  code.
+
+## Disable
+
+Disabling is **CP-authenticated**: the request must arrive external and encrypted, and the
+sender must *be* the bound control plane — there is deliberately no user-origin, app-callable
+clear. Both `disable_monitoring` (direct transaction) and the `core.monitoring` / `disable`
+verb clear the binding via `do_disable_monitoring`. For hosted cluster children there is one
+host-mediated exception, `host_clear_child_monitoring` — a child's monitoring was propagated
+from the root's ceremony, so the root operator revokes it; see
+[Cluster lifecycle](./cluster.md).
+
+`get_monitoring_status` is the readonly view: `$monitored`, `$proxy_pending`, `$proxy_cid`.

package/mufl_code/core/docs/workflows/notifications.md

@@ -0,0 +1,109 @@
+# Notifications
+
+The notification path lets a **sender** wake a **recipient's** device without being able to
+read anyone else's traffic. A recipient registers WebPush bindings with a notification
+**service** and asks it to mint one **scoped token** per contact; each contact receives only its
+own handout (`service cid + its scoped token`). A sender posts with that token as a **bare signed
+send** — the service is typically a packet it has never met — and the service validates the token,
+checks the sender binding and the receive-mute flag, then hands the payload to its host, which
+does the WebPush egress. There is **no reply leg**: an aborted post is invisible to the sender, so
+a mute is unprobeable.
+
+Traced from
+[`a2a_notifications.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_notifications.mm)
+(`notify_register`, `notify_issue_tokens`, `export_notify_address`, `send_notification` →
+`post_notification`, `notify_mark_read`, `notify_set_sender_muted`, `notify_rotate_token`,
+`notify_revoke_contact_tokens`).
+
+## Register and issue per-contact tokens
+
+The recipient registers over the encrypted channel (the service is a normal contact of the
+recipient), then asks the service to mint a scoped token for each of its contacts.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant RH as Recipient host
+    participant R as Recipient packet
+    participant NS as Service packet
+    participant NSH as Service host
+
+    RH->>R: notify_register ($service, $bindings)
+    R->>NS: register ($bindings) - encrypted channel
+    Note over NS: store registration + WebPush bindings
+    NS->>R: confirm_registration ($ok) - encrypted channel
+    Note over R: registration confirmed (app state)
+
+    RH->>R: notify_issue_tokens ($service, $contacts)
+    R->>NS: issue_tokens ($contacts) - encrypted channel
+    Note over NS: mint one scoped token per (recipient, sender);<br/>idempotent, re-issue keeps the existing token
+    NS->>R: confirm ($sender_tokens) - the per-contact map
+    Note over R: my_notify_contact_tokens updated
+```
+
+## Hand a contact its notification address
+
+The recipient exports the per-contact handout and delivers it to that contact out-of-band (in the
+reference stack, over the normal messaging channel).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant RH as Recipient host
+    participant R as Recipient packet
+
+    RH->>R: export_notify_address ($service, $contact)
+    R-->>RH: $address (service cid + that contact's scoped token)
+    Note over RH: deliver $address to the contact out-of-band
+```
+
+## Send a notification
+
+The sender holds the recipient's handout and posts a bare signed send. The service validates and
+never replies.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant SH as Sender host
+    participant S as Sender packet
+    participant NS as Service packet
+    participant NSH as Service host
+    participant Dev as Recipient device
+
+    SH->>S: send_notification ($address, $payload)
+    S->>NS: post_notification ($token, $recipient_cid, $payload) - bare signed send
+    Note over NS: validate in order - minted by THIS service, live index entry,<br/>sender binding ($from == $scope), byte-equality, not muted
+    NS-->>NSH: $notify_agent (deliver payload to the recipient's bindings)
+    NSH->>Dev: WebPush (aes128gcm + VAPID) to each stored binding
+    Note over NS: no reply leg - an aborted post is invisible to the sender
+```
+
+## Read, mute, rotate, revoke
+
+Runtime management from the recipient. Muting is a runtime flag only (the token is unchanged
+across a mute/unmute cycle); rotation replaces one sender's slot or all of them (a panic button);
+revocation drops the index entry and the slot with no re-mint, so old handouts abort at the index
+lookup.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant RH as Recipient host
+    participant R as Recipient packet
+    participant NS as Service packet
+
+    RH->>R: notify_mark_read ($service, $notif_ids)
+    R->>NS: mark_read ($notif_ids)
+
+    RH->>R: notify_set_sender_muted ($service, $contact, $muted)
+    R->>NS: set_sender_muted ($sender, $muted)
+    Note over NS: runtime-only; token unchanged
+
+    RH->>R: notify_rotate_token ($service, $contact?)
+    R->>NS: rotate_token ($sender?) - one slot, or all (panic button)
+
+    RH->>R: notify_revoke_contact_tokens ($service, $contacts)
+    R->>NS: revoke_sender_tokens ($senders)
+    Note over NS: delete index entry + slot, no re-mint;<br/>old handouts abort at the index lookup
+```

package/mufl_code/core/release-notes/0.1.md

@@ -0,0 +1,60 @@
+# core 0.1 — MIN (additive): `a2a_notifications` — protocol-level Notifications-as-a-Service
+
+**Version:** 0.1.0 · **Bump:** MIN (additive) · One new library defining the
+notification-service node surface + a `send_notification` transaction parallel
+to `send_message`; no existing wire shape or verification path touched.
+
+## What shipped
+
+- **`a2a_notifications.mm`** — one library, two halves:
+  - *Client half* (every consumer): `notify_register`, `notify_update_bindings`,
+    `notify_rotate_token`, `notify_unregister`, `notify_mark_read`,
+    `send_notification`, `export_notify_address` (readonly), inbound
+    `confirm_registration`.
+  - *Service half* (a notifier packet): `set_vapid_public_key`, inbound
+    `register`, `update_bindings`, `rotate_token`, `unregister`,
+    `post_notification`, `mark_read`; app hooks for storage/egress
+    (`on_notification_posted`, `on_notifications_marked_read`,
+    `on_unregistered`; client-side `on_notify_registration`).
+- `cap_notifications = "core.notifications"` reserved in `a2a_capabilities.mm`
+  (constant only — no control verbs, no dispatch change).
+- `config.mufl` exports the library; `export_notify_state` /
+  `import_notify_state` persistence helpers.
+- Contract doc: [`NOTIFICATIONS_CONTRACT.md`](../NOTIFICATIONS_CONTRACT.md).
+
+## New/changed transactions
+
+All new, library-routed `::a2a_notifications::<name>` (no `::actor::` shims).
+Nothing existing changed. `post_notification` is the first non-invite inbound
+accepted as a **bare signed send** from an unknown packet — the shared token
+is the sole authorization; validation is version → minted-by-me → live index
+entry → `_value_id` byte-equality vs the stored token → payload cap (≤ 4000).
+
+## Integration TODO for consumers
+
+Nothing required — consumers recompile unchanged (new inbound names are never
+sent to packets that don't play a half). To adopt: call
+`a2a_notifications::init` beside `a2a_messaging::init`, compose
+`export_notify_state`/`import_notify_state` into your state wrappers, and (as
+a client) drive register → subscribe → `notify_update_bindings` →
+`export_notify_address`.
+
+## Security notes
+
+- **No E2E to the device:** the service reads every payload.
+  The contract doc carries the loud warning; operators and app authors must
+  not put service-hidden secrets in payloads.
+- **No anti-spam in v1:** any token holder can post without limit; rotation
+  (`notify_rotate_token`) is the recovery path and invalidates the old
+  handout atomically (index delete).
+- Sender `$from` on a post is recorded but never used for authorization (the
+  token is); the recipient surface is encrypted-channel-gated; the VAPID
+  private key never enters packet state.
+
+## Tests
+
+`tests/run.sh` scenarios N1–N8 (register/confirm; bare-send post happy path
+from a non-contact; adversarial token matrix incl. a `$scope` flip that only
+the byte-equality check catches; rotation; unregister; mark_read ids/NIL;
+export/import round-trip incl. secret-absence; oversize payload on both
+sides), alongside the pre-existing T1–T10 — all green.

package/mufl_code/core/release-notes/0.3.md

@@ -0,0 +1,22 @@
+# core 0.3 — PATCH (rebase): `a2a_notifications` rebased onto core 0.2.0
+
+**Version:** 0.3.0 · **Bump:** PATCH (rebase, no wire change) · The
+`a2a_notifications` library (originally introduced in core 0.1.0 on a
+separate branch) is now rebased onto the core 0.2.0 lineage, producing a
+single unified commit on `feat/a2a-notifications` that downstream consumers
+(ours-notifications daemon, ours-control-plane) can build against.
+
+No wire shape was changed: all `$field` names in `notify_token_*`,
+`webpush_binding_t`, `notify_address_t`, `registration_t`,
+`my_registration_t`, and `notification_t` are byte-identical to the core
+0.1.0 form. The library surface (`register`, `update_bindings`,
+`rotate_token`, `unregister`, `mark_read`, `confirm_registration`,
+`post_notification`, `send_notification`, `export_notify_address`,
+`set_vapid_public_key`, `export_notify_state`, `import_notify_state`, all
+`init` hooks) is unchanged.
+
+The conflict resolution merged the core 0.2.0 additions (`qa_strip_peer_ads`,
+`qa_send_restore_request`, `qa_send_fake_restore_response` — contact-survival
+tests) with the notification test helpers (`qa_notify_state`, `qa_post_tampered`,
+`qa_send_fake_confirm`) so the full T1–T11e + N1–N8 suite now runs against
+core 0.3.0 — all green.

package/mufl_code/core/release-notes/0.4.md

@@ -0,0 +1,97 @@
+# core 0.4 — `a2a_notifications` v2: per-contact notification tokens (shared token removed)
+
+**Version:** 0.4.0 · **Bump:** breaking rewrite of the notifications library (no deployed
+v1-notifications clients exist; consumers are (re)built against 0.4). Per-contact scoped
+tokens are the ONLY model — the v1 shared-token feature is deleted, not deprecated.
+
+---
+
+## What changed
+
+**Per-contact scoped tokens only.** Every token names exactly one (recipient, sender) pair:
+`$scope == _str(sender_cid)`. Token `$version` stays `1` and `notify_address_t` stays
+version `1` (the `$scope` field always existed in the shape). Tokens are minted exclusively
+by `issue_tokens`; **registration mints nothing**.
+
+**Shared-token feature removed entirely:**
+
+- `registration_t` and `my_registration_t` no longer carry a `$token` field; the
+  `confirm_registration` targ no longer carries `$token`.
+- `handle_register` stores the registration record only — no mint, no index entry.
+- `retire_shared` / `notify_retire_shared` (a transitional retirement path drafted during
+  development) do not exist.
+- `post_notification` has a single validation path: index lookup → **sender binding**
+  (envelope `$from` must equal the token's `$scope` — abort
+  `"Token is not bound to this sender."`) → byte-equality against
+  `notify_sender_tokens[recipient][sender]` → mute check (abort
+  `"Notifications from this sender are disabled."`) → payload cap.
+- `rotate_token` with `$sender` absent rotates ALL scoped slots (panic button);
+  with `$sender` present rotates exactly one.
+- `unregister` is a full teardown: registration, every scoped token (slot + index entry)
+  and the mute map are purged.
+
+**Service-side inbounds (all encrypted-channel, registered-recipient gate):**
+
+- `issue_tokens ($senders -> global_id[]+)` — mint or keep (idempotent, E8, byte-stable) a
+  scoped token per requested sender cid; capped at `issue_max_senders = 256` per call
+  (the client wrapper pages larger lists). Re-confirms with the full per-sender map.
+- `set_sender_muted ($sender -> global_id, $muted -> bool)` — runtime receive-mute toggle
+  (present entry = muted, absent = enabled). No token change, no redistribution.
+- `revoke_sender_tokens ($senders -> global_id[])` — delete each sender's scoped token from
+  the index and `notify_sender_tokens`, without re-minting (the contact-removal path).
+- `rotate_token` gains optional `$sender -> global_id` (per-sender vs rotate-all).
+
+**Client-side transactions:**
+
+- `notify_issue_tokens ($service, $contacts -> global_id[])` — pages into batches of 256.
+- `notify_set_sender_muted ($service, $contact -> global_id, $muted -> bool)`.
+- `notify_revoke_contact_tokens ($service, $contacts -> global_id[])`.
+- `notify_rotate_token` gains optional `$contact -> str+` (resolved via `resolve_contact`).
+- `export_notify_address ($service, $contact)` — exports the PER-CONTACT handout blob from
+  `my_notify_contact_tokens[service][contact]`; aborts if issuance hasn't confirmed yet.
+
+**Confirm shape.** Every service-side mutator replies the same idempotent confirm:
+`($vapid_pub, $bindings, $sender_tokens, $sender_muted)`. The client replaces
+`my_notify_contact_tokens[service]` wholesale on each confirm (single source of truth;
+re-confirms are idempotent replays). The `on_notify_registration` hook now receives
+`$sender_tokens` and `$sender_muted` beside `$service_cid`/`$registration`, so a consumer
+(the messenger's distribution engine) can diff/mirror per-contact state.
+
+**State maps:**
+
+- Service: `notify_sender_tokens (global_id ->> (global_id ->> notify_token_t))`,
+  `notify_sender_muted (global_id ->> (global_id ->> bool))`.
+- Client: `my_notify_contact_tokens (global_id ->> (global_id ->> notify_token_t))`.
+
+`export_notify_state`/`import_notify_state` carry all fields with the individually-guarded
+optional-read pattern — a pre-0.4 export imports with the new maps empty.
+
+---
+
+## Security model (why per-contact)
+
+| Property | shared token (removed) | per-contact (0.4) |
+|---|---|---|
+| Leak blast radius | any leak ⇒ anyone can spam the recipient | one relationship's channel only |
+| Attribution | none — all contacts hold identical bytes | `$scope` names the relationship |
+| Authorization | possession alone | possession + sender binding (`$from == $scope`) — a stolen handout is useless without the named sender's signing key |
+| Recovery granularity | rotate-all + full redistribution | rotate/revoke one contact; rotate-all retained as panic button |
+| Per-relationship control | none | receive-mute at the service (unprobeable), plus consumer-side send gating |
+
+---
+
+## Deployment
+
+There is no migration path from the 0.3 shared-token PoC — deployments are recreated:
+the service daemon ships first (new inbound names), clients register + `issue_tokens`
+against it. Old handout blobs from any pre-0.4 deployment die at validation (their
+token_ids are not in the new service's index; unscoped tokens additionally fail sender
+binding).
+
+---
+
+## Non-goals (unchanged)
+
+Payload content remains **plaintext to the service** (transport legs are encrypted, but the
+service decrypts and stores the notification). There is **no rate limiting or anti-spam**
+beyond per-contact rotation/revocation.

package/mufl_code/core/tests/README.md

@@ -0,0 +1,83 @@
+# core 3.0 ephemeral-invite — loopback test suite
+
+End-to-end behavioural tests for the slim ephemeral-key invite + two-message boxed
+redeem (legs 1/2/3) shipped in core 3.0 (`release-notes/3.0.md`).
+
+The core repo is pure mufl libraries with no standalone build, so these tests run
+through a small **self-contained test actor** (`test_actor.mu`) that loads the
+shared core and supplies the minimum host wiring (storage hooks, a tiny inbox, the
+identity-hierarchy helpers, export/import wrappers) plus `qa_*` probe transactions
+the driver uses to inject adversarial inputs and read state. **No consumer/daemon
+source is vendored** — the actor is derived locally for this repo.
+
+## Files
+
+- **`test_actor.mu`** — the derived test actor (pure mufl; compiles against this
+  repo's `core/` via the toolkit).
+- **`test.mjs`** — the loopback driver: spins up multiple packets on one broker and
+  runs the scenarios, asserting **receiver-side state** (not just send emission).
+- **`run.sh`** — builds a throwaway harness, compiles, boots a local broker, runs
+  the driver. Exit 0 = all green.
+- **`corpus.mjs` / `run_corpus.sh`** — the **golden-wire corpus gate**
+  (`COMPATIBILITY.md`): replays one fixture per registered wire version per
+  registry through the `a2a_versions` dispatch and asserts the branch taken.
+  Fast (single packet); a release is green only if this passes.
+- **`mufl_semantics/run.sh`** — toolchain-behavior pins the registry rests on
+  (safe-cast extra-field strip, disjunction canonical-order rebuild, 3-version
+  dispatch), run against the vendored `@adapt-toolkit/mufl` package.
+
+## Prerequisites (external to this repo)
+
+1. **ADAPT toolkit** — the `mufl-compile` binary + `mufl_stdlib` / `meta` /
+   `transactions` (default root `…/adapt-toolkit`).
+2. **`@adapt-toolkit` Node SDK** — from any consumer checkout's `node_modules`
+   (e.g. `ours-mcp/node_modules`); used only to drive packets in the loopback.
+3. **`dev-broker.mjs`** — the local relay launcher (ships in `ours-mcp/scripts`).
+
+Node 18+ (tested on v20).
+
+## Run
+
+```sh
+./tests/run.sh
+# or override paths:
+ADAPT_TOOLKIT=/path/to/adapt-toolkit \
+OURS_SDK_NODE_MODULES=/path/to/ours-mcp/node_modules \
+DEV_BROKER=/path/to/ours-mcp/scripts/dev-broker.mjs \
+PORT=9799 ./tests/run.sh
+```
+
+The SDK's leak-tracker prints `###`/`Leak for AdaptValue` lines at exit and inbound
+aborts surface as `EVAL_ERROR` on stderr — both are expected noise (the adversarial
+scenarios deliberately trigger aborts; `run.sh` forwards only the meaningful
+`inbound rejected` lines). The verdict is the final `SCORECARD` + exit code.
+
+## Scenarios asserted (10 scenarios, 36 assertions)
+
+| # | Scenario | What it proves |
+|---|----------|----------------|
+| T1 | happy-flat | leg-2 consumes the invite + registers the responder; **leg-3 receiver-side**: the responder decrypts the boxed leg-3 with its kept eph priv and registers the inviter; both `list_contacts` show the other; `send_message` round-trips **both** directions over `encrypted_channel`. |
+| T2 | happy-role | both sides are delegated roles; the delegation chain verifies and `contact_roots` is pinned on **both** legs. |
+| T3 | single-use | a 2nd leg-1 for the same `invite_id` aborts (`already-redeemed`); inviter state unchanged. |
+| T4 | invalid-then-valid | a bad box aborts at decrypt and does **not** consume the invite; a subsequent valid redeem then consumes it. |
+| T5 | tamper | a tampered box aborts and mutates **no** state. |
+| T6 | cid-bind leg-2 | a boxed AD whose `container_id` ≠ sender aborts; nothing registered/consumed. |
+| T7 | PoP leg-2 | an AD with stripped self-signatures aborts in `process_address_document`. |
+| T8 | leg-3 gates | unexpected-inviter (sender ≠ pinned cid), cid-bind leg-3, and PoP leg-3 each abort and register nothing. |
+| T9 | export-secrecy | `export_core_state` contains **neither** `pending_invite_keys` **nor** `pending_redemption_keys`; `pending_invites` carries only public `{assigned, eph_pub, scheme}` (INV-4). |
+| T10 | import migration | `export_state`→`import_state` preserves contacts/peer_ads and resets `pending_invites` (plan §4.4). |
+
+Hard invariants exercised: **INV-5** (no `contacts`/`peer_ads`/`contact_roots`
+write before lookup → decrypt → cid-bind → PoP → chain) on both legs; **single-use**
+consumes both per-side ephemeral stores; **INV-4** (ephemeral secrets never
+exported).
+
+The R- and N-series (contact restore, notifications v1/v2) and the 0.5.0
+**V-series** follow the same pattern. V-series (versioned type registry,
+`COMPATIBILITY.md`): V1 the exact 0.2.0 leg-1 shape (no `$name` — the incident)
+registers under the sender cid with **no abort**; V2 the 0.3.0 shape honors
+`$name`; V3 the v5 shape learns `contact_pv`/`contact_caps`; V4 a below-floor
+peer (`$pv=1`) produces the **error-as-data** `$protocol_error` notify at the
+inviter, consumes **nothing**, and the same invite redeems after the peer
+"updates"; V5 the CAP-1 capability gate denies as data only on positive
+evidence; V6 stamped `$targ`s deliver normally and are learned passively.