@uuaid/pillar 0.2.0-alpha.9 → 2.0.2

package/INTERACTION-CONVENTION.md

@@ -1,7 +1,8 @@
 # Pillar Interaction Convention v1
 
 App-layer standard for bidirectional interactive conversations over the
-pillar carrier (v0.2.0-alpha.5). No core protocol changes — this is a
+pillar carrier (written against v0.2.0-alpha.5; still current as of
+2.0.1). No core protocol changes — this is a
 convention any enrolled agent opts into by mutual agreement. LLM-agnostic:
 pure JSON envelopes; any client that can HTTPS + Ed25519-seal can speak it.
 
@@ -14,6 +15,34 @@ pure JSON envelopes; any client that can HTTPS + Ed25519-seal can speak it.
 | `ack`     | receipt for any envelope; echoes the id being acked    |
 | `message` | fire-and-forget (default kind, unchanged)              |
 
+### Reserved prefixes
+
+| prefix   | owner                  | status                                |
+|----------|------------------------|---------------------------------------|
+| `esig:*` | esig-suite (Esig-Lead) | reserved by convention — NOT enforced |
+
+`kind` is unvalidated except against a delegation: `seal()` takes
+`body.kind ?? "message"` with no enum, allowlist or regex, and neither `open()`
+nor the carrier's `_handlePost()` checks it on a plainly signed envelope. The
+one exception is a DELEGATED envelope: `open()` refuses a capability name used
+as a kind (`inbox`, even under `"*"`) and a kind outside the delegation's
+`kinds` (`src/net/envelope.mjs`, `kind-reserved-capability` and
+`kind-not-covered`). That limits what a delegate may *emit*; it never grants a
+recipient anything. A reserved prefix is therefore a naming convention between
+lanes, **not an access control** — any enrolled agent can emit `esig:sealed`.
+
+What `kind` does give you: it sits inside the signed canonical body, and
+`open()` binds the sender key to `sender`, so a kind is unforgeable *as another
+sender* — it is authentic as "this sender asserted this kind." What it does not
+give you: any authorization value. An `esig:*` envelope from an unrelated uuaid
+is a well-formed envelope with a misleading label; every authorization decision
+MUST rest on the sealed payload's own signature, never on `kind`.
+
+Per rule 5 below, `kind` is cleartext to the carrier, so `esig:sign-request`
+discloses "uuaid X asked uuaid Y to sign something, at time T" to every relay.
+Lanes running signature workflows SHOULD use an opaque routing kind (`esig:m`)
+and put the real verb inside the sealed payload.
+
 ## Payload fields (all optional unless stated)
 
 - `text` — human/agent-readable body
@@ -42,3 +71,195 @@ pure JSON envelopes; any client that can HTTPS + Ed25519-seal can speak it.
 sends a `request` and blocks until the `ack`+`reply` arrive (default
 120s timeout), printing: request id → ack latency → reply latency → text.
 Synchronous Q→A over the same carrier as everything else.
+
+## App-level convention: read receipts (`pillar-read-receipt`)
+
+*Status: app-level convention, first implemented by the Pillar mobile app.
+No wire change — it rides the existing `ack` kind inside an ordinary
+E2E-encrypted payload; carriers and non-participating clients are unaffected.*
+
+A client signals "I have seen your messages up to here" by sending a sealed
+`ack` envelope whose decrypted payload is exactly:
+
+```json
+{ "v": 1, "type": "pillar-read-receipt", "upTo": "env-…", "thread": "env-…" }
+```
+
+- `upTo` — id of the most recent inbound envelope the reader has seen.
+- `thread` — the thread root id (rule 1) the receipt applies to.
+- `inReplyTo` is deliberately omitted; `upTo` plays that role, and keeping
+  the payload free of it lets older senders ignore the ack without
+  mis-marking a single message as delivered.
+
+Semantics for the receiving (original sender) side:
+
+- Mark every outbound envelope in `thread` created at or before `upTo` as
+  **read**; read implies delivered, so a missing ack state is backfilled.
+- Only honor receipts whose sender is the thread's counterparty.
+
+Etiquette for the sending (reader) side:
+
+- Send when a thread is opened and when a new inbound envelope arrives while
+  the thread is open — at most one receipt per `upTo` value per view.
+- Only send to known contacts (same gate as auto-acks; sealing needs the
+  peer's pubkey anyway).
+- Read receipts MUST NOT be re-acked (rule 2 covers `request`/`reply` only),
+  SHOULD NOT be rendered as messages, and MUST NOT increment unread
+  counters.
+- Privacy is symmetric (WhatsApp-style): a client configured not to send
+  read receipts also ignores incoming ones.
+
+### What a read receipt does NOT mean
+
+**A receipt proves that the endpoint holding the key acknowledged the
+envelope. It does NOT prove that the human, agent or seat capable of acting
+on the content has read it.** Implementations MUST NOT present it as more
+than that, and MUST NOT let a UI label ("Read", a blue tick) — or a
+machine-readable field name in a ledger or API response (e.g.
+`delivery_verified: true`) — imply comprehension, agreement, or that a task
+has been picked up. The prohibition binds the data model, not just the
+presentation layer: a field name no human ever renders can oversell a
+receipt exactly as effectively as a checkmark can.
+
+This is not hypothetical. In a fleet deployment (2026-09-04) a governance
+halt was delivered, acked in 21 s and replied to in one inbox surface while
+the working session that actually held the capability never saw it: a fully
+green receipt above a structurally ignorant actor. A receipt is evidence
+about a *mailbox*, never about an *understanding*.
+
+Consequences for anyone wiring receipts into an ack/receipt ledger:
+
+- Label the state after the surface that produced it ("acknowledged in
+  inbox"), never after the actor you hope is behind it.
+- A receipt is a lower bound on delivery and says nothing about routing
+  *inside* the recipient. If the recipient fans work out to other sessions,
+  seats or tabs, that hop is invisible here and needs its own evidence —
+  and that evidence has an owner: the RECIPIENT, not the sender and not the
+  courier, owes a second signal originating from the acting seat. An
+  unowned requirement is exactly how a green receipt ended up sitting above
+  a structurally ignorant actor in the incident above.
+- Never close, escalate or exonerate on a receipt alone. It answers "did the
+  bytes arrive and get opened", which is strictly weaker than "was this
+  acted on" — and it is the second question that decisions usually turn on.
+
+The receipt is still worth having: it is signed by the recipient's key, so it
+is stronger evidence of arrival than any sender-side or render-side proxy
+(e.g. reading a UI surface back). Claim exactly that much and no more.
+
+## Handle convention (`...`)
+
+*Status: app-level convention, first implemented by the Pillar mobile app.
+Display/UX-level only — the wire protocol continues to carry full UUAIDs in
+every envelope; nothing in this section changes any protocol behavior.*
+
+The handle prefix in the Pillar ecosystem is **`...` (three dots)** — NOT
+`@` or `#`. The ecosystem already truncates UUAIDs for display as
+`…a2e0d9c6`; `...` formalizes that visual language into a handle syntax.
+
+### Grammar
+
+- `...<name>` — a directory-resolved handle: three dots, then
+  `[a-z0-9-]+` (case-insensitive). Matched case-insensitively against the
+  carrier directory's agent `name` and `role` fields (e.g. `...my-agent`,
+  `...helper`). Resolution prefers an exact name/role match, then a prefix
+  match, then a substring match; the first non-empty tier wins. Multiple
+  matches → the client shows a picker; zero matches → a clear
+  "no agent found" error.
+- `...<hex-suffix>` — three dots, then 6+ hex chars (case-insensitive).
+  Matched against the tail of directory agents' UUAID localIds AND their
+  pubkey-derived localIds (dashes stripped before comparison, e.g.
+  `...7c801eba`). If a suffix matches nobody in the directory it is NOT
+  usable on its own: the user must also supply the full UUAID + public key
+  — a suffix alone is never enough to trust.
+
+Parsing is strict: exactly three leading dots (whitespace-trimmed). `..x`,
+`....x`, a bare `...`, and characters outside the two charsets all fail to
+parse. A value that is both a legal name and 6+ hex chars (`...cafe`,
+`...decade`) is tried as a NAME first; suffix matching applies only when
+name resolution finds nobody (documented decision: name-then-suffix, so a
+directory agent literally named `decade` always beats a localId-tail
+collision).
+
+### Resolution and trust rules
+
+- A handle ALWAYS resolves to a `(uuaid, publicKey)` pair taken from the
+  directory or an existing contact. A pubkey-less resolution MUST NOT be
+  accepted for sending — candidates without a valid 64-hex Ed25519 public
+  key are dropped before matching.
+- When a handle resolves, the client shows the matched name + full UUAID +
+  public-key suffix and lets the user eyeball the binding before adding
+  (trust-on-first-use with visible binding). The resolved fields remain
+  editable.
+
+Reference implementation: `apps/mobile/src/services/handles.ts`
+(`parseHandle` / `resolveHandle`), exercised by
+`scripts/test-handles.mjs`.
+
+## App-level convention: group chats (`pillar-group` v1)
+
+*Status: app-level convention, first implemented by the Pillar mobile app
+(2026-09-03). Superset of the reference `Pillar.sendGroup` shape. No wire
+change: every group message is an ordinary 1:1 envelope; carriers and
+non-participating clients see nothing new.*
+
+There is deliberately **no group key**. A group message is sealed separately
+to every member (per-member fan-out, one envelope each, kind `message`), so
+membership changes never require rekeying and a carrier still cannot read
+anything or even tell that a group exists. The group context rides INSIDE the
+sealed payload under `_group`:
+
+```json
+{
+  "text": "hello crew",
+  "_group": {
+    "v": 1,
+    "id": "grp-0123456789abcdef",
+    "name": "Weekend crew",
+    "members": ["uuaid:…sender", "uuaid:…", "uuaid:…"],
+    "keys": { "uuaid:…": "<ed25519 pubkey hex>" },
+    "msgId": "gm-…",
+    "op": "message"
+  }
+}
+```
+
+- `id` — stable group id, `grp-<16 hex>`. The reference `sendGroup` sends
+  only `{ name, members }`; a client receiving a tag WITHOUT `id` derives a
+  local id from the name plus the sorted roster so the conversation still
+  groups. `id` is a grouping key, not an authority.
+- `members` — the full roster, uuaid strings, including the sender (same as
+  the reference). A recipient that is sealed to but missing from the roster
+  adds itself locally.
+- `keys` — OPTIONAL trust-on-first-use hints so members can seal to each
+  other without a prior contact exchange. A receiver MUST binding-check every
+  hint (the key must derive the uuaid) before storing it, and MUST prefer a
+  key already known from a contact or from a plainly verified envelope's
+  `transportSignature` (first key wins). Delegated envelopes are signed by a
+  device key and therefore teach nothing about the persona key.
+- `msgId` — `gm-…`, identical across the per-member envelopes of one group
+  message; receivers show one bubble per msgId and senders aggregate delivery
+  state across the fan-out (read only when EVERY recipient read).
+- `op` — `message` (default, may be omitted) | `create` | `rename` | `add` |
+  `leave`. Control ops carry an empty or informational `text` (`add` lists the
+  added uuaids comma-separated) and render as system lines, not bubbles.
+
+Roster rules for receivers: an unknown `id` creates the group; only a current
+MEMBER may rename or add; nobody can remove anyone but themselves (`leave`
+drops the sender). A member who left keeps history and stops sending.
+
+Acks and read receipts: group traffic uses kind `message`, so implementations
+SHOULD ack it like `request`/`reply` (rule 2 covers the minimum, not the
+maximum). A read receipt for a group envelope names that envelope's own thread
+(group messages carry no `thread`); the original sender applies it to every
+earlier outbound envelope it sealed to that reader in the same group.
+
+## App-level payload fields: `quote` and `senderName`
+
+Both optional, both inside the sealed payload, both ignorable.
+
+- `quote: { "id": "env-…", "text": "…", "from": "uuaid:…" }` — reply-with-quote.
+  `text` is a ≤300-char excerpt copied at reply time; receivers render it as
+  a quoted block and may scroll to `id` when they hold that envelope.
+- `senderName: "Ada"` — the sender's self-declared display name (≤64 chars).
+  UX-level only: a client uses it as a fallback after its own contact name
+  and MUST NOT treat it as an identity claim (the uuaid + key are).