@real-life/trust-protocol 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## 0.5.0
+
+Takes up Message Tasks 0.1, Delivery Contract 0.82 and Membership Tasks
+0.20.
+
+- **Messages** (Message Tasks 0.1): `sendMessage(contactId, text,
+  {when, actId, replyTo?})` sends a `message@1` on a ready, unblocked
+  relationship (refused as `not-ready`, `blocked` or `message-invalid`;
+  event `message.sent` with the mid and the document digest). Reception
+  runs the stages of Delivery 6.2: the MAC under `k_msg`, the age bound
+  (`failed(stale-issuance)`) and the future bound on the holder's time
+  mark, the completion record per tuple (no new effect for a known body,
+  equivocation refused), the inbox entry committed with the cache entry
+  and the acknowledgement. `inbox()` lists the messages not yet taken
+  over, in display order; `takeMessages(ids, {when})` takes them over.
+  `ContactView.canMessage`. The pure forms (`messageKeyOf`,
+  `messageMac`, `messageProblem`, `MESSAGE_TYPE`, …) are exported from the
+  root.
+- **The block** (Message Tasks 6): `block(contactId)` and
+  `unblock(contactId)`, chain-level state of every relationship of the
+  entry, kept through chaining, merge and split; event `contact.blocked`,
+  `ContactView.blocked`. Under a block messages are discarded and
+  invitations declined into the register of declined invitations,
+  silently and acknowledged; the holder's own messages, invitations and
+  introduction acts toward a blocked relationship are refused. The
+  treatment of the Trust Layer's types waits for that layer's next
+  casting.
+- **Invitations** (Membership Tasks 0.20 §3.1): attributed to the
+  relationship of their prelude binding, or to none; at most 20 new
+  credential digests per relationship and day; one surfacing per
+  credential digest, decided with the register and the permanent record
+  of surfaced invitations.
+- **The prelude** (Membership §3.5): the registered types
+  `membership-prelude-request/0.1` and `membership-prelude-reply/0.1` with
+  the binding `membership-inviter@1`, kept per relationship for its life;
+  genesis digests compared by their bytes. **Breaking:** a holder of 0.4.0
+  sends `x-membership-prelude-*`, which 0.5.0 refuses as `unknown-type`.
+- The inviter admits without a human act only before
+  `validUntil + membership-skew + P90D` (Membership 3282).
+- **Delivery 0.82**: the transient disposition `failed(rate-limited)`
+  (nothing committed, no ack, no cache entry, evaluated afresh when
+  delivered again); an outbound may carry its type's sender lifetime,
+  after which resume moves it to `failed(task-expired)` and never hands it
+  out again — for a message `sentAt + P179D`, after any retry horizon
+  (at most P90D), so an undelivered message fails as
+  `failed(expired-by-adapter-policy)` first.
+- `./adapters/vti-mediator`: `conclude(collection, now, {keep})` leaves
+  transient items unconcluded and offers them again; `concludable(result)`.
+- **State codec 2**, with a pure migration from codec 1 (no block, no
+  rate, no record, no inbox; the ready tuples read from the state; every
+  received invitation counted as surfaced), its non-normative schema
+  `schemas/holder-state-v2.schema.json` and the type `HolderStateV2`, and
+  golden fixtures reproduced in `npm test`. The codec 1 fixtures are
+  frozen as 0.4.0 wrote them and migrated in the tests.
+- Closed unions grown: `ActError` (`blocked`, `not-ready`,
+  `message-invalid`), `ReceiveFailure` (`rate-limited`), `HolderEvent`
+  (`contact.blocked`, `message.sent`, `message.received`), the outbox's
+  failure reasons (`task-expired`), the entropy purposes (`message.mid`).
+- Engine (for modules): `keepKeys(state, when)` gets the tick's time; the
+  module hook `accepted` runs in the stage-9 transaction of every unique
+  document.
+- Tests: the scenario set of Message Tasks §10.2, the race of #103 on two
+  engines over one store, and a seeded interleaving generator over
+  messages, the block, take-over and the record's retention.
+
+## 0.4.0
+
+- `createHolder`: one person's device state behind typed human acts
+  (`{when, actId}`, journaled), `receive`, `report`, `resume` and `tick`,
+  with the views `contacts`, `contact`, `groups`, `profile`, `prompts`,
+  `deliveryStatus` and `subscribe`. Results are a closed union with rule
+  references; events are a closed union, issued after the commit.
+- Ports: `Store` (compare-and-swap), `KeyProvider` (`seedKeys` by default),
+  `Entropy` by closed purpose, `Log`, `Access`, `RetryPolicy`,
+  `DeliveryReport`, pure-JSON `Outbound`. `storeContract` is the suite a
+  Store adapter passes.
+- Modules on the holder: identity (the register, device names, the
+  community anchor's rotation over the Log port), trust (the trust act and
+  the classes, the anchor mapping, the star and the group star, merge,
+  split and departure, continuity, `profile@1`, the duties), encounter
+  (`encounter-scan@0.25` with both paths), membership (founding, prelude,
+  invite, admission, welcome, `vouch@2`) and introduction (Trust §8, three
+  roles).
+- Delivery: stages 1–9 once per envelope through a task register, the
+  completed-effect cache with stored acks, the outbox with the status
+  trias, retry by backoff, give-up at the horizon.
+- State codec 1 with golden fixtures (`test/fixtures/`) and a
+  non-normative JSON Schema (`schemas/holder-state-v1.schema.json`) with
+  the generated type `HolderStateV1`; a newer codec is `codec-newer`, a
+  codec without a validator `codec-unknown`.
+- Entry points: the root, `./testing`, `./internal`,
+  `./adapters/vti-mediator`. `visibility` and `ceremony` carry pure wire
+  builders and verifiers only. There is no `./probe` entry point.
+- Invariant predicates over every commit (`invariants: true`) and a
+  generator over random sequences of acts on two and three holders.

package/README.md

@@ -5,14 +5,18 @@ encounters between people: two humans meet, recognize each other, and record
 that recognition as verifiable credentials. Cryptography proves freshness and
 authorship; only a human can witness a human.
 
-This package is the **executable form of the specification** — it lives beside
-the schemas and the test vectors it must reproduce byte-for-byte. Published by
-the [Real Life Organisation](https://real-life.org) under CC BY 4.0.
-
-- Specification, schemas and vectors: <https://rltp.real-life.org>
-- Zero dependencies. WebCrypto only (Ed25519, X25519, HKDF, AES-256-GCM).
-- Works in browsers, Node ≥ 20, Deno, Bun. No DOM, no storage, no network:
-  the library computes and verifies, the host decides where bytes live.
+This package is the reference library of the specification. It lives beside
+the schemas and the test vectors it reproduces byte for byte. Published by the
+[Real Life Organisation](https://real-life.org) under CC BY 4.0.
+
+- Specification, schemas and vectors: <https://trust-protocol.real-life.org>
+- Zero runtime dependencies. WebCrypto only (Ed25519, X25519, HKDF,
+  AES-256-GCM, SHA-256), with one scoped exception: a synchronous SHA-256
+  (`sha256.ts`) digests local reconciliation views inside synchronous state
+  transitions (the star and the group star). It never touches wire bytes,
+  keys or MACs.
+- No DOM, no storage, no network: the holder computes and verifies, the app
+  stores its state and carries its envelopes.
 
 ## Install
 
@@ -20,92 +24,219 @@ the [Real Life Organisation](https://real-life.org) under CC BY 4.0.
 npm i @real-life/trust-protocol
 ```
 
-## The modules mirror the specification
-
-Each module answers to one document, so a reader of the spec knows where to
-look in the code:
+## The holder
 
-| Module | Specification | What it carries |
-|---|---|---|
-| `core` | across all layers | The canonical form: JCS serialization, multibase encodings, digest equality over *decoded* bytes, whole-second timestamps, calendar validity — and the JSON-Schema subset validator the conformance runner uses. |
-| `crypto` | — (primitives) | Hashes, HKDF, key pairs, did:key and multikey renderings, ECDH, and the eddsa-jcs-2022 Data Integrity proof every layer signs with. Answers *how*, never *what*. |
-| `identity` | Identity Layer | One root seed, every context derived — community anchor, pair anchor per relationship, member anchor per group. Contexts never link without their holder's deliberate act. |
-| `encounter` | Encounter Layer | The ceremony under fresh-always pair anchors: challenges, contact cards, the enactment binding both sides compute independently, encounter credentials. |
-| `delivery` | Delivery Contract | The sealed envelope, and the receive chain in its declared order — size bound *before* decryption, envelope form, decryption, parse and digest over the canonical form, completed-effect cache. |
-| `carrier-identity` | Identity §7a | The carrier-relationship principal: one Ed25519 control key per (relationship × carrier), derived so that no computable relation to the relationship's other principals or its `rkid` exists — which is why registration must *prove* the binding instead of computing it. |
-| `carrier` | Delivery §4.4 + §5a | The carrier side of the port as one transport-agnostic state machine: the five guarantees, the proof rule, the total binding lifecycle (unbound → live → closing → released), the verdict sets in their normative evaluation orders, wind-up and binding tombstones. The clock is injected. |
-| `holder` | Delivery §5a + Identity §9.3 | The holder's half: proof construction for all four purposes, the closed verdict set, and the two-exchange recovery flow for a lost carrier entry. |
-| `visibility` | Network Visibility 0.29 on Delivery 0.79 | The trust act (`anchor-mapping@2` + `grade-declaration@1`), the blinded star (`star@1`, 5.2a chunks), the admission layer and the 5.4 reconciliation automaton, §6a continuity (probe + mapping — chains instead of duplicates), and the deniable `delivery-ack/0.1`. Namespaced: `visibility.trust`, `.continuity`, `.acks`. Graduated from `/probe` on 04.09.2026 after a 39-round conformance loop. |
-| `ceremony` | Encounter 0.29 (`encounter-scan@0.25`) on Delivery 0.79 | The ceremony's transmission: `encounter-bundle/0.1`, `encounter-credential-delivery/0.1` (counter-step in the bundle's thread), the signed `delivery-ack/0.1`; the own-challenge state model with its aging latch, the enactment record as the serialization point, the eight-step acceptance, connected and offline path with free switching; one commit discipline (prepare → verify → commit) under the §6.2 lock set; resumable issuance. Graduated from `/probe` on 05.09.2026 after a 25-round conformance loop. |
-
-Everything is re-exported from the package root; the table is a map, not an
-import instruction.
+`createHolder` is one person's device: its state behind the human acts, the
+delivery channel's three calls and the views an app reads.
 
 ```ts
-import { labeledContext, signCard, seal, sameDigest } from '@real-life/trust-protocol'
+import { createHolder, seedKeys } from '@real-life/trust-protocol'
+import { InMemoryStore } from '@real-life/trust-protocol/testing'
+
+const holder = await createHolder({ store: new InMemoryStore(), keys: seedKeys(rootSeed) })
+
+// a human act: its time and an actId the app mints when the human acts
+const shown = await holder.show({ when: Date.now(), actId: crypto.randomUUID() })
+// shown.events carries the card to display; shown.outbound the envelopes to send
+
+// the channel: one receive per arriving envelope, the adapter's reports,
+// and resume on a timer (retries and due duties)
+const got = await holder.receive(envelope, Date.now())
+await holder.report({ digest, status: 'accepted' }, Date.now())
+const { outbound, nextDueAt } = await holder.resume(Date.now())
+
+// the views, read after each commit (subscribe announces them)
+holder.subscribe(async () => render(await holder.contacts(), await holder.prompts()))
 ```
 
-## Two entry points
+**The timer.** Every act, receive and resume may name `nextDueAt`: the
+earliest time something is due, delivery work (retries, duties, acks)
+and expiry work (a prompt's expiry, an act's timeout or lifetime, an aging
+challenge, the retention of the effect cache, the journal, the outbox and
+the address keys) alike. The app keeps one timer at the earliest
+`nextDueAt` it was given; when it fires, it calls `tick(now)` and then
+`resume(now)`, sends the outbound and sets the timer anew.
+
+Every act returns `{ok: true, outbound, events} | {ok: false, code, ref?}`;
+`code` is a closed union, `ref` names the rule where one applies. Every
+`outbound` item is pure JSON (`digest`, `envelope`, `type`, `threadId`,
+`recipient`, `attempt`); the app delivers it to the device holding
+`envelope.rkid` and reports what its transport saw by `digest`.
+
+The human acts: `show`, `scan`, `captureSentCard`, `counter` (the encounter),
+`decide` (a prompt: confirm an encounter, accept an invitation, take up or
+consent to an introduction), `trust`, `untrust`, `pauseTrust`, `setClass`,
+`setGroupClass`, `merge`, `depart`, `setProfile`, `foundGroup`, `invite`,
+`vouchFor`, `introduce`, `sendMessage`, `block`, `unblock`, `rotateAnchor`,
+`addDevice`, `revokeDevice`. Not
+human: `receive`, `report`, `resume`, `tick`, `recover`, `takeMessages`.
+Reads: `contacts`, `contact`, `groups`, `profile`, `prompts`, `inbox`,
+`deliveryStatus`, `deviceKey`, `snapshot`, `subscribe`.
+
+## What the root exports
+
+- `createHolder` and its types (`Holder`, `HolderOptions`, `HumanActOptions`,
+  `HolderSnapshot`).
+- The ports: `Store`, `KeyProvider`, `Entropy`, `Log`, `Access`,
+  `RetryPolicy`, `DeliveryReport`, `Outbound`; `seedKeys(seed)` is the
+  default KeyProvider, `randomEntropy` the default Entropy.
+- The views: `ContactView`, `GroupView`, `PromptView`, `ProfileView`,
+  `InboxMessageView`, `DeliveryStatusView` and their parts.
+- The results and events: `ActResult`, `ReceiveResult`, `ResumeResult`,
+  `InfraError`, `CryptoUnavailableError`, `HolderEvent`.
+- The state as an opaque type (`HolderState`), `decodeState`, `CODEC`,
+  `StateCodecError`, and `storeContract`, the suite a Store adapter passes.
+- The pure wire builders and verifiers of every layer (`core`, `crypto`,
+  `identity`, `profile`, `encounter`, `membership`, `message` —
+  `MESSAGE_TYPE`, `messageKeyOf`, `messageMac`, `messageProblem`,
+  `messageShapeOk` and the constants of Message Tasks 0.1 —,
+  `introduction`, `delivery`, `carrier-identity`, `carrier`,
+  `carrier-holder`), and two
+  namespaces of pure forms: `visibility` (anchor, star, group star,
+  continuity, acks) and `ceremony` (the encounter's, the group's and the
+  introduction's forms).
+
+Other entry points:
+
+| Entry point | What it holds |
+|---|---|
+| `./testing` | `InMemoryStore`, `memoryLog`, `scriptedEntropy`, `storeContract`, `emptyState`, `stateBuilder`, `freezeDeep`, `sampleState`, `openPromptModule`, the invariant checks, `forgeMapping` (deniability, Trust 6.1), `SCHEMAS` and the generated `wire` types. For tests, vectors and adapter authors; not for production holders. |
+| `./internal` | The structural `HolderState`, `encodeState` and the codec chain, the engine's module types, the pure view functions, the modules' factories and pure reads. For the library's own modules and tests; not an app contract. |
+| `./adapters/vti-mediator` | The VTI mediator as a carrier adapter: its submission states as `DeliveryReport`, collection and ack handling, the selective conclusion of a collection (`conclude(c, now, {keep})`, `concludable(result)`: a `failed(rate-limited)` item stays with the carrier). |
+
+## The modules and the rules they implement
+
+Bare four-digit numbers are RLTP-TRU rules; the other layers name theirs.
+
+| Module | Specification | Rules |
+|---|---|---|
+| `core` | all layers | the canonical form: JCS (RFC 8785), multibase, digest equality over decoded bytes, whole-second timestamps, calendar validity, the JSON-Schema subset validator |
+| `crypto` | primitives | HKDF, key pairs, did:key and multikey, X25519, the `eddsa-jcs-2022` Data Integrity proof |
+| `identity` | Identity 0.54 §6.1, §6.2, §5.4, §5.5 | context derivation under the closed label registry: `group/<digest>` and its generations, `pair/…`, `persona/…`, `device/<n>/<c>`; the name pipeline pinned to Unicode 15.0 |
+| `identity-state` | Identity §2, §5.4, §5.5 | the label register with monotone sets, device names and revocation marks, the community anchor's rotation as a procedure over the Log port (register before log before duties) |
+| `encounter`, `encounter/ceremony` | Encounter 0.31 §4–§7 | `encounter-scan@0.25`: challenges and their aging latch (5.3), the enactment record (5.5), the 5.6 acceptance in its order, both paths of 5.8, `encounter-bundle/0.1` and `encounter-credential-delivery/0.1` with signed acks, the confirm prompt |
+| `trust/mapping` | Trust Section 2, 2a, §6.1–§6.5 | the trust act and the class settings (2720–2850), `anchor-mapping@4` issuance (6300/6310, 6420) and verification (6.3, conditions 4a, 4b, 8), the entry commit and the admission bound |
+| `trust/star`, `trust/group-star` | Trust §5.1–§5.4, §5.2b | `star@2` and `group-star@1` reconciled per recipient (5.4: salt scope, baseline automaton, completion by the ack), reception with assemblies and lower bounds |
+| `trust/entries` | Trust Section 2, §6a.1 | merge (net and manual, 6640), split (2080–2115), departure (2260), the head rule and the binding rule (6605) |
+| `trust/continuity` | Trust §6a | `continuity-probe@1` and `continuity-mapping@1`, chaining a re-encounter into the existing relationship (6a.4) |
+| `trust/profile`, `profile` | Trust §6b | `profile@1`: the one revision counter (6450), delivery on the class gates (6455), reception and the image bounds (6475) |
+| `trust/duties` | Trust 2850, 6370, 6455, 6595, 6596 | the duties a commit leaves: class on, re-issue after a rotation, the lag rule |
+| `membership`, `membership/holder` | Membership Tasks 0.20 on Access 0.57 | founding (Access 3.4.1), the prelude (3.5: `membership-prelude-request/0.1`, `membership-prelude-reply/0.1`, the binding per relationship), invite, accept, admission within the bound of 3282 and welcome, evidence relay and `vouch@2` (Access 5.3), an in-library Access over the holder's groups |
+| `message`, `message/holder` | Message Tasks 0.1 | `message@1`, `k_msg` and its MAC (3); sending on a ready, unblocked relationship with the sender lifetime (5); reception through the stages with the age and future bounds on the time mark, the completion record, the inbox taken over by the app, the rates and the inbox bound as `failed(rate-limited)` (4); the block of a relationship (6010–6030, 6510), its discard of messages and its treatment of invitations and prelude replies (Membership 3115, 3975), the holder's own offers refused (6410) |
+| `introduction`, `introduction/holder` | Trust §8 on Delivery §4.4 | the Introduction Act in its three roles: request, forward, reply, the mediator's one ack at its declared delay, the vouchers; the requester's timeout at the act's expiry (8340; A20, spec follow-up 18: no ack timeout of 8690) |
+| `receive`, `engine` | Delivery 0.82 §5, §6.1, §6.2 | the sealed envelope and the two key classes, stages 1–9 once per envelope with the dispositions `discarded` and the transient `failed(rate-limited)`, the task register by full task URI, the completed-effect cache with stored acks, the outbox with the status trias, retry by backoff, give-up at the horizon, the act journal |
+| `carrier-identity`, `carrier`, `carrier-holder` | Identity §7a, Delivery §4.4, §5a, Identity §9.3 | the carrier-relationship principal, the carrier port's state machine, proofs, verdicts and recovery |
+| `views`, `prompts` | — | the read model: contacts by entry (2120, 2140), groups, prompts, the delivery status |
+
+## Runtime
+
+| Runtime | Status |
+|---|---|
+| Node 22 | tested in CI (the library job) |
+| Node 24 | tested locally |
+| Node 20 | the declared minimum (`engines`); Ed25519 and X25519 are in its WebCrypto |
+| Chromium 145 | tested by the workbench's end-to-end run (`apps/gesamtsimulator/tests/local-perspective.mjs`) |
+| Chromium ≥ 137, Firefox ≥ 129, Safari ≥ 17 | expected: they carry Ed25519 and X25519 in WebCrypto; not tested here |
+
+The WebCrypto handle is resolved when a holder is built, not at import: an
+app may pass its own (`createHolder({crypto})`, `seedKeys(seed, crypto)`),
+and a runtime without Ed25519 or X25519 is reported then as
+`CryptoUnavailableError`.
+
+## State, codec and storage
+
+A holder's state is pure JSON under a codec version. The Store port takes
+the state as opaque JSON and gives it back; the library decodes it
+(`decodeState`), the adapter never migrates.
+
+- **Codec 1** is the format of 0.4.0, the first stable one. Its golden
+  fixtures (`test/fixtures/state-v1*.json`, written by lib 0.4.0 with
+  `test/fixtures/gen-state-v1.mjs` and frozen since) cover a settled
+  holder, one with work open (prompts, a joining invite, duties, a
+  rotation at step 2) and one with a tombstone, a revoked device and
+  carrier entries. They validate under codec 1 and migrate to codec 2.
+- **Codec 2** is the format of 0.5.0: codec 1 with the state of Message
+  Tasks 0.1 (`messages`: the block, the rates, the ready tuples, the
+  completion record, the inbox), an outbox item's sender lifetime
+  (`expiresAt`) and `failed(task-expired)`, and the record of surfaced
+  and the register of declined invitations (`joining.surfaced`,
+  `joining.declined`); an invitation may be attributed to no
+  relationship. The migration from codec 1 is pure: no block, no rate, no
+  record, no inbox, the ready tuples read from what the counterparts'
+  documents left, every invitation received counted as surfaced. Its
+  fixtures (`test/fixtures/state-v2*.json`, deterministic runs of
+  `test/fixtures/gen-state-v2.mjs`, reproduced in `npm test`) add
+  messages to the settled holder and a block and a declined invitation to
+  the open one; each decodes and re-encodes byte for byte. A later codec brings its validator, a pure
+  migration from the one before, and its own fixture with a migration
+  test.
+- A newer codec is refused as `codec-newer`, a codec without a validator
+  as `codec-unknown`; nothing is read best-effort.
+- `schemas/holder-state-v1.schema.json` and
+  `schemas/holder-state-v2.schema.json` describe the codecs as
+  non-normative JSON Schemas (published with the package). The types
+  `HolderStateV1` and `HolderStateV2` (`./internal`) are generated from
+  them (`scripts/build-holder-state-types.mjs`); the build holds the
+  current one against the library's `HolderState`, and the tests hold each
+  schema against its codec's validator on the fixtures and on mutations
+  of them. Rules only the codec states: a record's id equals its key, an
+  envelope's `rkid` equals its recipient's `keyAgreement`, and (codec 2) a
+  set of strings is sorted.
+
+**Writing a Store adapter.** Implement `read(): Promise<{state, version}>`
+(a deep, independent copy; `null` state and version for an empty store) and
+`commit(version, next): Promise<{ok: true, version} | {ok: false, reason:
+'conflict'}>` as compare-and-swap: atomic, storing a copy, a version token
+never reused in the store's lifetime. One writer per holder; the adapter
+guarantees it. Then run the contract against it:
 
 ```ts
-import { …, visibility } from '@real-life/trust-protocol'   // wire-normative core
-const { trust, continuity, acks } = visibility                // Network Visibility, graduated
-import { introduce, membership }
-  from '@real-life/trust-protocol/probe'                     // draft — will change
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { storeContract } from '@real-life/trust-protocol'
+
+storeContract(() => new MyStore(), { test, assert })   // a fresh, empty store per call
 ```
 
-The **`/probe` subpath is deliberate.** Its modules exercise the converged
-*semantics* of their layers, but their transport shapes carry `@probe` and
-are **not wire-normative**: mediated introductions over a rendezvous drop
-and group membership (founding, VIC invite, admission, vouching). The
-trust act, the blinded star, §6a continuity and the deniable ack **left
-this subpath on 04.09.2026** — they are wire-normative now and live under
-`visibility` at the package root; the Encounter ceremony's transmission
-**left on 05.09.2026** and lives under `ceremony`. Experiment with the rest; do not treat its wire forms
-as an interoperability target. A subpath import is a decision someone has
-to make — nothing behind it can be reached by accident.
-
-**The redelivery contract of probe receivers:** a receiver's inbound
-effect is complete the moment it returns `handled: true` without `error` —
-that delivery is cached and answers `duplicate-known` forever after.
-Outbound work a receiver triggers (star refreshes, continuity mappings)
-is built per recipient and never discards partial results; what failed is
-named in `outboundError` / `outbound.failures`, and **redelivering the
-inbound document is not the retry path** — re-invoking the producing call
-(e.g. `trust.starRefreshAll`) is, and it is the host application's job.
+It checks snapshot isolation, CAS, atomicity, a lost result, the codec
+boundary and reopening. Durability across process loss is the persistent
+adapter's own test.
+
+## Invariants and the generator
+
+`invariants.ts` states predicates over a commit (`state → state'`): the
+register and revocation marks only grow, tombstones never shrink, a salt is
+issued at most once per tuple, the effect cache holds only completed
+digests, `accepted` arises only from a report, a duty leaves only by its
+specified fulfilment. `createHolder(ports, {invariants: true})` checks them
+on every commit. `test/invariants-generator.test.mjs` runs random sequences
+of acts, receives, reports and ticks over two and three holders and checks
+every predicate after every step.
 
 ## Versions
 
-This package uses its own semver; the specification uses castings. Each
-release states, per module, whose **wire forms** it implements — and what
-it deliberately does not:
-
-| Module (0.3.x) | Casting | Implemented | Not in this package |
-|---|---|---|---|
-| `identity` | Identity 0.50 | context derivation under the closed label registry (§6.1, unchanged since 0.13) with the ordered persona pipeline (§6.2, Unicode 15.0 pinned) | recovery derivation (§5.3), service identities (§7), the label register and its state |
-| `carrier-identity` | Identity 0.51 (§7a) | the carrier-relationship principal derivation, identifier validation | the register's generation state (held by the holder's store) |
-| `carrier` + `holder` | Delivery 0.79 (§4.4, §5a) + Identity 0.51 (§9.3) | the port state machine, proofs for all four purposes, verdicts, recovery | transport adapters and their policies (a carrier's budgets enter through hooks) |
-| `encounter` | Encounter 0.29 — wire `0.25` (`rltp-card/0.25`, `encounter-scan@0.25`) | challenges, both card profiles, the enactment binding, encounter credentials (the primitives) | — (the ceremony machine lives in `ceremony`) |
-| `ceremony` | Encounter 0.29 §5.3–5.8 + Delivery 0.79 (§3, §4.1–4.3, §6) | `encounter-bundle/0.1`, `encounter-credential-delivery/0.1`, signed `delivery-ack/0.1`; own-challenge state model (aging latch, whole seconds), enactment record + record-key lock set, 5.6 acceptance in order, both 5.8 paths, thread freshness incl. re-issue, resumable issuance, chain-head carry | storage, transport adapters, the host's UI correlation (duties listed in the handoff) |
-| `delivery` | Delivery 0.64 | the sealed envelope (§5) and the generic receive stages 1–4 | the type-specific stages, residual bookkeeping, transport adapters |
-| `core`, `crypto` | cross-layer | canonical form, digest equality, timestamps, validator; primitives + `eddsa-jcs-2022` proof | — |
-| `visibility` | Network Visibility 0.29 + Delivery 0.79 (§3, §4.2, §4.4) | the trust act (`anchor-mapping@2`, `grade-declaration@1`), `star@1` with 5.2a chunk assembly, the admission layer (Section 2), the 5.4 reconciliation automaton with completion via deniable acks, §6a continuity (`continuity-probe@1`, `continuity-mapping@1`, chaining), the registered task documents and `delivery-ack/0.1` with the 4.2 class rule; full §6.2 stage order on every receive path, peek→build→commit issuance on every producer | storage, transport adapters and their policies (the Encounter ceremony's flows live in `ceremony`) |
-| `/probe` | Network Visibility (introductions) · Membership Tasks + Access | mediated introductions, group membership — semantics of the running castings, transport shapes `@probe` | any wire-form stability whatsoever |
-
-Persona-name validation is **pinned to Unicode 15.0** as Identity §6.2
-requires: the repertoire ships with the package (`unicode15.ts`, ~5 kB of
-ranges) and no platform Unicode data is consulted — the same name derives
-the same anchor on every runtime, whatever ICU it carries.
+This package uses its own semver; the specification uses castings.
+
+| Area | Casting | Not in this package |
+|---|---|---|
+| identity | Identity 0.54 | recovery derivation (§5.3), service identities (§7) |
+| encounter | Encounter 0.31, cards 0.25, credentials 0.26 | — |
+| trust | Trust Layer 0.31 | — |
+| membership | Membership Tasks 0.20, Access 0.57 | the Access envelope (Membership 3.3: `access-operation/0.1` with `member.add` and the sealed welcome; this library sends its own `x-membership-welcome/0.1`); an admission prompt after the bound of RLTP-MT-3282; roster replication: a holder knows the members it admitted and the roster its welcome carried |
+| introduction | Trust 0.31 §8 | how a requester learns the mediator's designator (8.3): this library's mediator sends `x-introduction-offer/0.1` |
+| delivery | Delivery 0.82 | transport adapters beyond `./adapters/vti-mediator`; the block of the Trust Layer's types (Message Tasks 6240: their treatments wait for the next casting of the Trust Layer) |
+| message | Message Tasks 0.1 | holding a message unsent until its tuple is ready (5020): `sendMessage` answers `not-ready` and the app keeps the message; checking `replyTo` against the relationship's history (5120), which is the app's; multi-device (§9); `failed(task-expired)` for a message: reachable only with a retry horizon beyond P179D, which the engine does not admit (at most P90D), so an undelivered message ends as `failed(expired-by-adapter-policy)` |
+| devices | Identity §5.5 | multi-device production: one writer per holder |
 
 ## The contract: the vectors
 
-A version that does not reproduce `vectors/` byte-for-byte is not a valid
-version — the conformance runner checks every cryptographic claim, and every
-negative case must fail at its declared stage. If you implement RLTP in
-another language, those same vectors are how you check yourself; you do not
-need this package to do it.
+A version that does not reproduce `vectors/` byte for byte is not a valid
+version. The conformance runner checks every cryptographic claim, and every
+negative case fails at its declared stage. An implementation in another
+language checks itself against the same vectors; it does not need this
+package.
 
 ## License
 
-[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — specification and
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), specification and
 reference implementation alike.

package/dist/ack.d.ts

@@ -0,0 +1,84 @@
+/** The registered type of the acknowledgement (Delivery §4.2). */
+export declare const ACK_TYPE = "https://real-life.org/trust-tasks/delivery-ack/0.1";
+/** The ack document without its proof: the MAC preimage (4.2). */
+export interface AckDocument {
+    id: string;
+    type: typeof ACK_TYPE;
+    issuer: string;
+    recipient: string;
+    threadId: string;
+    issuedAt: string;
+    payload: {
+        ref: string;
+        meaning: 'received';
+    };
+}
+/** The HKDF info of the channel ack key, issuer first (4.2). */
+export declare const ackInfo: (issuerPairAnchor: string, recipientPairAnchor: string) => string;
+/** The channel ack key from the tuple's X25519 shared secret (4.2). */
+export declare function ackKeyOf(shared: Uint8Array, issuerPairAnchor: string, recipientPairAnchor: string, subtle?: SubtleCrypto): Promise<Uint8Array>;
+/** "u" + base64url HMAC-SHA-256 over the JCS of `doc` under `key`. */
+export declare function ackMac(key: Uint8Array, doc: unknown, subtle?: SubtleCrypto): Promise<string>;
+/** The proof-less ack of `ref` on the acked document's thread (4.2):
+ *  issuer = the acked document's recipient, recipient = its issuer. */
+export declare const ackDocument: (f: {
+    id: string;
+    issuer: string;
+    recipient: string;
+    threadId: string;
+    issuedAt: string;
+    ref: string;
+}) => AckDocument;
+/** The deniable ack: `doc` with its MAC-form proof under the channel ack key. */
+export declare function macAck(doc: AckDocument, key: Uint8Array, subtle?: SubtleCrypto): Promise<AckDocument & {
+    proof: {
+        mac: string;
+    };
+}>;
+/** Where a received ack's form fails, by the stage of Delivery §6.2 that names it. */
+export type AckFormFailure = {
+    stage: 5 | 7;
+    reason: 'malformed';
+} | {
+    stage: 8;
+    reason: 'validation-failed';
+};
+/**
+ * The context-free checks of a received MAC-form ack, in stage order
+ * (Delivery §6.2): 5 document profile (schema, closed form, calendar), 7
+ * payload schema, 8 the class rule's proof form (exactly `{mac}`), no
+ * enactment, `meaning`. What needs the arrival context stays the
+ * caller's: recipient = own anchor (5), issuer = the tuple's counterpart,
+ * `ref` = a document sent on that thread, and the MAC itself (8).
+ */
+export declare function macAckForm(doc: unknown): {
+    ok: true;
+    ref: string;
+    threadId: string;
+} | ({
+    ok: false;
+} & AckFormFailure);
+/**
+ * The context-free checks of a received SIGNED ack (the class rule's
+ * form for a signature-class payload, 4.2/4.4), in stage order: 5 the
+ * document profile, 7 the payload schema, 8 the proof form (an
+ * eddsa-jcs-2022 DataIntegrityProof, no `mac`, calendar-valid), no
+ * enactment, `meaning`. The signature itself (under `issuer`) and the
+ * consistency against what the holder sent stay the caller's.
+ */
+export declare function signedAckForm(doc: unknown): {
+    ok: true;
+    ref: string;
+    threadId: string;
+} | ({
+    ok: false;
+} & AckFormFailure);
+/** The proof form a received ack carries: the MAC object, a signature, or neither. */
+export declare const ackProofForm: (doc: unknown) => "mac" | "signed" | null;
+/** Does the ack's MAC verify under `key`? (4.2; over JCS of the document without proof) */
+export declare function macAckValid(doc: {
+    proof?: {
+        mac?: unknown;
+    };
+} & Record<string, unknown>, key: Uint8Array, subtle?: SubtleCrypto): Promise<boolean>;
+//# sourceMappingURL=ack.d.ts.map

package/dist/ack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ack.d.ts","sourceRoot":"","sources":["../src/ack.ts"],"names":[],"mappings":"AAwBA,kEAAkE;AAClE,eAAO,MAAM,QAAQ,uDAAuD,CAAA;AAE5E,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,OAAO,QAAQ,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAA;CAC9C;AAED,gEAAgE;AAChE,eAAO,MAAM,OAAO,GAAI,kBAAkB,MAAM,EAAE,qBAAqB,MAAM,KAAG,MACJ,CAAA;AAE5E,uEAAuE;AACvE,wBAAsB,QAAQ,CAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAGrJ;AAED,sEAAsE;AACtE,wBAAsB,MAAM,CAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAInG;AAED;uEACuE;AACvE,eAAO,MAAM,WAAW,GAAI,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KAAG,WAGlI,CAAA;AAEF,iFAAiF;AACjF,wBAAsB,MAAM,CAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,GAAG;IAAE,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAEzI;AAMD,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG;IAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAA;AAE9G;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAE,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GAAG,cAAc,CAAC,CAUxH;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAE,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GAAG,cAAc,CAAC,CAY3H;AAED,sFAAsF;AACtF,eAAO,MAAM,YAAY,GAAI,KAAK,OAAO,KAAG,KAAK,GAAG,QAAQ,GAAG,IAI9D,CAAA;AAED,2FAA2F;AAC3F,wBAAsB,WAAW,CAAE,GAAG,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAGzJ"}

package/dist/ack.js

@@ -0,0 +1,114 @@
+// ack — the delivery acknowledgement's pure parts (Delivery §4.2, the
+// acknowledgement class rule of §4.4): the type, the deniable MAC form's
+// channel-keyed derivation, the MAC, and the context-free form checks of
+// a received ack. Used by the holder's receive core (engine.ts);
+// byte-compatible with vectors/delivery-ack.json
+// (lib/test/vectors4.test.mjs).
+//
+//   k     = HKDF-SHA-256(ikm = X25519(pairX_issuer, pairX_recipient),
+//                        salt = empty, info = "rltp/v1/delivery/mac/ack/"
+//                        || issuerPairAnchor || "/" || recipientPairAnchor,
+//                        32 bytes; an all-zero shared secret is rejected)
+//   proof = { mac: "u" + base64url(HMAC-SHA-256(k, JCS(document without proof))) }
+//
+// Deniable by construction: either party of the tuple derives k, so for a
+// designated-verifier payload the ack is evidence to its sender alone,
+// never an attestation (4.2). The key agreement itself is the caller's:
+// the holder asks its KeyProvider.
+import { jcs, b64uOf, calOK, makeValidator } from './core.js';
+import { hkdf, platformSubtle } from './crypto.js';
+import { SCHEMAS } from './schemas.js';
+const te = new TextEncoder();
+/** The registered type of the acknowledgement (Delivery §4.2). */
+export const ACK_TYPE = 'https://real-life.org/trust-tasks/delivery-ack/0.1';
+/** The HKDF info of the channel ack key, issuer first (4.2). */
+export const ackInfo = (issuerPairAnchor, recipientPairAnchor) => 'rltp/v1/delivery/mac/ack/' + issuerPairAnchor + '/' + recipientPairAnchor;
+/** The channel ack key from the tuple's X25519 shared secret (4.2). */
+export async function ackKeyOf(shared, issuerPairAnchor, recipientPairAnchor, subtle) {
+    if (shared.every((b) => b === 0))
+        throw new Error('all-zero X25519 output');
+    return hkdf(shared, ackInfo(issuerPairAnchor, recipientPairAnchor), 32, subtle);
+}
+/** "u" + base64url HMAC-SHA-256 over the JCS of `doc` under `key`. */
+export async function ackMac(key, doc, subtle) {
+    const S = subtle ?? platformSubtle();
+    const k = await S.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return 'u' + b64uOf(new Uint8Array(await S.sign('HMAC', k, te.encode(jcs(doc)))));
+}
+/** The proof-less ack of `ref` on the acked document's thread (4.2):
+ *  issuer = the acked document's recipient, recipient = its issuer. */
+export const ackDocument = (f) => ({
+    id: f.id, type: ACK_TYPE, issuer: f.issuer, recipient: f.recipient, threadId: f.threadId, issuedAt: f.issuedAt,
+    payload: { ref: f.ref, meaning: 'received' },
+});
+/** The deniable ack: `doc` with its MAC-form proof under the channel ack key. */
+export async function macAck(doc, key, subtle) {
+    return { ...doc, proof: { mac: await ackMac(key, doc, subtle) } };
+}
+const V = makeValidator(SCHEMAS);
+const schemaOk = (file, data) => V.validate(data, SCHEMAS[file], SCHEMAS[file]).length === 0;
+const ACK_FIELDS = new Set(['id', 'type', 'issuer', 'recipient', 'threadId', 'issuedAt', 'payload', 'proof', 'ceremony']);
+/**
+ * The context-free checks of a received MAC-form ack, in stage order
+ * (Delivery §6.2): 5 document profile (schema, closed form, calendar), 7
+ * payload schema, 8 the class rule's proof form (exactly `{mac}`), no
+ * enactment, `meaning`. What needs the arrival context stays the
+ * caller's: recipient = own anchor (5), issuer = the tuple's counterpart,
+ * `ref` = a document sent on that thread, and the MAC itself (8).
+ */
+export function macAckForm(doc) {
+    const d = doc;
+    if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE)
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt))
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (!schemaOk('payload-delivery-ack.schema.json', d.payload))
+        return { ok: false, stage: 7, reason: 'malformed' };
+    const p = d.proof;
+    if (p === null || typeof p !== 'object' || Object.keys(p).length !== 1 || typeof p.mac !== 'string')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.ceremony?.enactment !== undefined)
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.payload.meaning !== 'received')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    return { ok: true, ref: d.payload.ref, threadId: d.threadId };
+}
+/**
+ * The context-free checks of a received SIGNED ack (the class rule's
+ * form for a signature-class payload, 4.2/4.4), in stage order: 5 the
+ * document profile, 7 the payload schema, 8 the proof form (an
+ * eddsa-jcs-2022 DataIntegrityProof, no `mac`, calendar-valid), no
+ * enactment, `meaning`. The signature itself (under `issuer`) and the
+ * consistency against what the holder sent stay the caller's.
+ */
+export function signedAckForm(doc) {
+    const d = doc;
+    if (!schemaOk('rltp-delivery-document.schema.json', d) || d?.type !== ACK_TYPE)
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (Object.keys(d).some((k) => !ACK_FIELDS.has(k)) || !calOK(d.issuedAt))
+        return { ok: false, stage: 5, reason: 'malformed' };
+    if (!schemaOk('payload-delivery-ack.schema.json', d.payload))
+        return { ok: false, stage: 7, reason: 'malformed' };
+    const p = d.proof;
+    if (p === null || typeof p !== 'object' || p.mac !== undefined || p.type !== 'DataIntegrityProof' || p.cryptosuite !== 'eddsa-jcs-2022' || !calOK(p.created)) {
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    }
+    if (d.ceremony?.enactment !== undefined)
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    if (d.payload.meaning !== 'received')
+        return { ok: false, stage: 8, reason: 'validation-failed' };
+    return { ok: true, ref: d.payload.ref, threadId: d.threadId };
+}
+/** The proof form a received ack carries: the MAC object, a signature, or neither. */
+export const ackProofForm = (doc) => {
+    const p = doc?.proof;
+    if (p === null || typeof p !== 'object')
+        return null;
+    return typeof p.mac === 'string' ? 'mac' : typeof p.proofValue === 'string' ? 'signed' : null;
+};
+/** Does the ack's MAC verify under `key`? (4.2; over JCS of the document without proof) */
+export async function macAckValid(doc, key, subtle) {
+    const { proof, ...rest } = doc;
+    return typeof proof?.mac === 'string' && (await ackMac(key, rest, subtle)) === proof.mac;
+}
+//# sourceMappingURL=ack.js.map