@ccmsg/protocol 1.22.1 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.22.1",
+  "version": "1.23.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/attributes.ts

@@ -8,10 +8,10 @@ import type { Capability, Role } from "./identifiers.ts";
  * different op. */
 export type Plane = "common" | "messaging" | "control" | "mesh";
 
-/** `instance-local` ops answer for one instance's processes, paths and
+/** `owner_instance` ops answer for one instance's processes, paths and
  * handles, so they are forwarded to the instance that owns the subject.
- * `cluster` ops are answerable by whichever instance is asked. */
-export type Locality = "instance-local" | "cluster";
+ * `any_instance` ops are answerable by whichever instance is asked. */
+export type Locality = "owner_instance" | "any_instance";
 
 export interface OpAttributes {
   readonly plane: Plane;
@@ -65,47 +65,47 @@ export const OP_ATTRIBUTES = {
   //
   // The greetings and `instance.ping` address the instance the caller reached, so
   // there is nothing to forward and no unreachable instance to report — which
-  // is why they are `cluster` despite answering about one instance.
+  // is why they are `any_instance` despite answering about one instance.
   "hello.session": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "hello.user": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "hello.instance": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "instance.ping": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "instance.shutdown": {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "session.stopping": {
     plane: "common",
     roles: SESSION_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   // Open to every role, with which role may have which topic left to the topic
@@ -115,20 +115,20 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["topic_unknown"],
   },
   "topic.unsubscribe": {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["topic_unknown"],
   },
 
   // The four ops that authenticate a person are open to every role for the
   // same reason the greetings are: they run before there is an identity to
-  // check, and what they answer is what settles one. They are `cluster` because whichever
+  // check, and what they answer is what settles one. They are `any_instance` because whichever
   // instance is reached answers — behind a load balancer that is not a choice
   // the caller makes — and each asks the issuing instance itself for the parts
   // only it holds.
@@ -136,7 +136,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: [],
   },
@@ -144,7 +144,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -152,7 +152,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -160,7 +160,7 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: ALL_ROLES,
     needs_hello: false,
-    locality: "cluster",
+    locality: "any_instance",
     carrier: "http",
     errors: ["auth_invalid", "auth_expired", "auth_unknown_issuer"],
   },
@@ -170,24 +170,24 @@ export const OP_ATTRIBUTES = {
     plane: "common",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
-  // Between instances: what an issuer alone can answer. Instance-local by the
+  // Between instances: what an issuer alone can answer. `owner_instance` by the
   // usual rule — the subject belongs to one instance, and it is reached by
   // `to_instance` being that instance's id.
   "auth.resolve": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
   "auth.rotate": {
     plane: "common",
     roles: INSTANCE_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["auth_invalid", "auth_expired"],
   },
 
@@ -196,28 +196,28 @@ export const OP_ATTRIBUTES = {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["session_not_found"],
   },
   "say.post": {
     plane: "messaging",
     roles: SESSION_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["rate_limited"],
   },
   "say.unread.clear": {
     plane: "messaging",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "notify.send": {
     plane: "messaging",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["rate_limited"],
   },
 
@@ -226,7 +226,7 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["session_not_found"],
   },
   "session.rename": {
@@ -234,42 +234,42 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "terminal",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["session_not_found"],
   },
   "session.env.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["session_not_found"],
   },
   "session.search": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "session.dump.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["not_found"],
   },
   "dump.presets.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "transcript.read": {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["not_found"],
   },
@@ -277,7 +277,7 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["not_found"],
   },
@@ -286,14 +286,14 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "fork",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["not_found"],
   },
   "session.forget": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
@@ -302,7 +302,7 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["path_forbidden", "not_found"],
   },
@@ -310,7 +310,7 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: AGENT_AND_USER,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     scope: "role",
     errors: ["path_forbidden", "not_found"],
   },
@@ -318,42 +318,42 @@ export const OP_ATTRIBUTES = {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["path_not_writable", "file_exists"],
   },
   "file.create": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["file_exists", "path_forbidden"],
   },
   "file.edit": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["file_conflict", "not_a_text_file"],
   },
   "file.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["path_forbidden", "not_found"],
   },
   "file.find": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["path_forbidden"],
   },
   "file.stat": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "dir.tree": {
@@ -361,7 +361,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
@@ -371,7 +371,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "launcher.run": {
@@ -379,7 +379,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "launcher",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "sandbox.grant": {
@@ -387,7 +387,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "sandbox",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["path_forbidden"],
   },
   "sandbox.revoke": {
@@ -395,7 +395,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "sandbox",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "translate.run": {
@@ -403,7 +403,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "translate",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: ["translate_helper_failed"],
   },
   "llm.usage.read": {
@@ -411,7 +411,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "llm_usage",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
   "llm.stats.read": {
@@ -419,32 +419,32 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     capability: "llm_stats",
-    locality: "instance-local",
+    locality: "owner_instance",
     errors: [],
   },
 
   // --- control: the shared key-value store (3) ---
-  // The only control ops that are not instance-local: a value is held by every
+  // The only control ops not answered by an owning instance: a value is held by every
   // instance rather than by one, so whichever is asked can answer.
   "kv.read": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: ["not_found"],
   },
   "kv.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
   "kv.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
-    locality: "cluster",
+    locality: "any_instance",
     errors: [],
   },
 } as const satisfies Record<string, OpAttributes>;
@@ -466,7 +466,7 @@ export function opErrors(op: OpName): ErrorCode[] {
   if (attrs.needs_hello) codes.add("hello_required");
   if (attrs.roles.length < ALL_ROLES.length) codes.add("forbidden");
   if (attrs.capability !== undefined) codes.add("capability_unavailable");
-  if (attrs.locality === "instance-local") codes.add("instance_unreachable");
+  if (attrs.locality === "owner_instance") codes.add("instance_unreachable");
   return [...codes];
 }
 

package/src/common/auth.ts

@@ -30,7 +30,7 @@ export const REGISTER_TTL_MS = 10 * 60 * 1000;
  * retention would otherwise carry the removed credential back as news. */
 export const FAMILY_TOMBSTONE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
-/** Who a person is to this cluster. Issued when the registration URL is made
+/** Who a person is to this mesh. Issued when the registration URL is made
  * (`<unit>-<counter>` by default) and carried by every record they own. */
 export const Subject = Type.String({ $id: "Subject", minLength: 1, maxLength: 128 });
 export type Subject = Static<typeof Subject>;
@@ -337,11 +337,11 @@ export const AuthRotateResponse = response("auth.rotate", AuthRotateResult);
 
 // --- the replicated records ------------------------------------------------
 
-/** A registered passkey, as every instance in the cluster holds it.
+/** A registered passkey, as every instance in the mesh holds it.
  *
  * Complete once it is written: the instance that registered it is not asked
  * about it again, which is what lets a person authenticate anywhere in the
- * cluster while the instance they registered at is down. */
+ * mesh while the instance they registered at is down. */
 export const CredentialRecord = Type.Object(
   {
     kind: Type.Literal("credential"),
@@ -503,7 +503,7 @@ export type AuthTombstone = Static<typeof AuthTombstone>;
 /** One entry of the replicated set, under the key it is matched by. */
 export const AuthRecord = Type.Object(
   {
-    /** What this entry is, cluster-wide. Two instances writing one key hold the
+    /** What this entry is, mesh-wide. Two instances writing one key hold the
      * same thing, and the later `updated_at` is what stands. */
     key: Type.String({ minLength: 1, maxLength: 256 }),
     updated_at: Timestamp,

package/src/common/ping.ts

@@ -7,8 +7,8 @@ export type InstancePingArgs = Static<typeof InstancePingArgs>;
 
 /** How the answering daemon process is running.
  *
- * This is about one process, which is why the op is instance-local: the health
- * of the cluster is `hello`'s `instances[]`, not a ping fanned out. */
+ * This is about one process, which is why the op is `owner_instance`: the health
+ * of the mesh is `hello`'s `instances[]`, not a ping fanned out. */
 export const InstancePingResult = Type.Object({
   instance: InstanceId,
   version: Type.String(),

package/src/common/topics.ts

@@ -93,6 +93,12 @@ export interface TopicAttributes {
  * `forbidden`, and one naming a capability the instance lacks answers
  * `capability_unavailable`. */
 export const TOPIC_ATTRIBUTES = {
+  // The one topic where the same subscription means two things: a session is
+  // handed what was addressed to it, so what it reads leaves its inbox, while a
+  // person is looking at somebody else's mail and reading it moves nothing.
+  // Stated on the frame rather than as an attribute here — it is not a fold and
+  // not an authorization, and a subscriber does the same thing with the frames
+  // whichever it is.
   inbox: { roles: ["session", "user"], granularity: "element" },
   notify: { roles: ["session", "user"], granularity: "event" },
   // A row here changes on its own — one session becomes busy while the rest

package/src/control/dump.ts

@@ -576,7 +576,28 @@ export type DumpIdEntry = Static<typeof DumpIdEntry>;
 export const DumpIds = Type.Array(DumpIdEntry, { $id: "DumpIds" });
 export type DumpIds = Static<typeof DumpIds>;
 
-/** The file a dump is written to.
+/** How the selected items are written out.
+ *
+ * The selection is one thing and its rendering another: which items a dump is
+ * of follows from the range and the `types`, and a format decides only what the
+ * file then says about them. So all three are dumps of the same items, and the
+ * reply describes that selection whichever was asked for.
+ *
+ * `items` is this contract's own vocabulary, the typed items as
+ * `SessionDumpFile`. `records` writes the transcript records those items were
+ * read from, unchanged, one JSON document per line — for a tool that already
+ * reads the harness's file and wants the classifying alone, which is why
+ * nothing of ours is added around them. An item names its record, so several
+ * items out of one record are one record here and the line count is not the
+ * item count. `text` renders the items for a person to read. */
+export const SessionDumpFormat = Type.Union(
+  [Type.Literal("items"), Type.Literal("records"), Type.Literal("text")],
+  { $id: "SessionDumpFormat" },
+);
+export type SessionDumpFormat = Static<typeof SessionDumpFormat>;
+
+/** The file an `items` dump is written to. The other two formats are not this
+ * shape: `records` is the harness's own lines and `text` is prose.
  *
  * The reply to a dump names a path rather than carrying the items, so the file
  * is where they actually travel — which makes its shape as much a part of the

package/src/control/session.ts

@@ -1,7 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
 import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
-import { DumpIds, TranscriptItemSelector, TranscriptItemType } from "./dump.ts";
+import { DumpIds, SessionDumpFormat, TranscriptItemSelector, TranscriptItemType } from "./dump.ts";
 
 /** Ends the OS process behind a session.
  *
@@ -203,6 +203,8 @@ export const SessionDumpWriteArgs = Type.Object({
   /** Leave out the machinery of in-process agents, which
    * `["-message.sub", "-tool.Agent"]` also says. */
   no_agent: Type.Optional(Type.Boolean()),
+  /** What the file says about the items selected. Absent is `items`. */
+  format: Type.Optional(SessionDumpFormat),
 });
 export type SessionDumpWriteArgs = Static<typeof SessionDumpWriteArgs>;
 
@@ -210,12 +212,18 @@ export const SessionDumpWriteResult = Type.Object({
   /** Absolute path on the writing instance's host. */
   path: Type.String(),
   instance: InstanceId,
-  /** How many items of each type were written, keyed by type name. A single
+  /** How many items of each type were selected, keyed by type name. A single
    * total leaves the caller unable to tell a dump that kept what it asked for
-   * from one whose selection matched almost nothing. */
+   * from one whose selection matched almost nothing.
+   *
+   * It counts items and not what the file holds, whatever the `format`: the
+   * selection is what a caller asked for and what it reads this against, and a
+   * count that moved with the rendering would answer a different question each
+   * time. */
   entries: Type.Record(TranscriptItemType, Type.Integer({ minimum: 0 })),
   /** The ids those items carried, so the next dump — of an agent named here —
-   * can be asked for without opening the file. */
+   * can be asked for without opening the file. Read off the selection like
+   * `entries`, whatever the `format`. */
   ids: DumpIds,
   bytes: Type.Integer({ minimum: 0 }),
 });

package/src/envelope.ts

@@ -62,7 +62,7 @@ export const RequestEnvelope = Type.Object(
      *
      * A forwarded request that names none is dispatched as the `instance` role
      * it arrived on, which the attribute table already answers: an
-     * instance-local op called by an instance is `forbidden`. */
+     * an `owner_instance` op called by an instance is `forbidden`. */
     caller: Type.Optional(CallerIdentity),
   },
   { $id: "RequestEnvelope" },

package/src/errors.ts

@@ -35,14 +35,14 @@ export const ERROR_CODES = [
   "invalid_args",
   /** The op declares a `capability` this instance does not have. */
   "capability_unavailable",
-  /** An `instance-local` op could not be forwarded to the instance that owns
+  /** An `owner_instance` op could not be forwarded to the instance that owns
    * the subject. */
   "instance_unreachable",
   // --- subscription ---
   /** The topic name is not one this protocol generation defines. */
   "topic_unknown",
   // --- subject lookup ---
-  /** The `sid` names no session anywhere in the cluster. */
+  /** The `sid` names no session anywhere in the mesh. */
   "session_not_found",
   /** The path, transcript, or record named by the arguments does not exist. */
   "not_found",
@@ -66,7 +66,7 @@ export const ERROR_CODES = [
    * and `msg` says no more than the instance's own log would want. */
   "auth_invalid",
   /** The instance that issued the challenge or registration, and alone can
-   * spend it, is not one this cluster knows or could reach just now. The client
+   * spend it, is not one this mesh knows or could reach just now. The client
    * asks for a fresh one, which the instance it is talking to can issue. */
   "auth_unknown_issuer",
   // --- translate ---

package/src/fixtures/messaging.ts

@@ -75,6 +75,7 @@ export const NOTIFY_SEND_REQUEST: Static<typeof NotifySendRequest> = {
   op: "notify.send",
   sid,
   text: "確認して",
+  reply_to: mid,
 };
 
 export const NOTIFY_SEND_RESPONSE: Static<typeof NotifySendResponse> = {

package/src/fixtures/topics.ts

@@ -29,6 +29,7 @@ export const INBOX_FRAME: Static<typeof InboxFrame> = {
       from_label: "contract-fixtures",
       text: "fixture を export した",
       sent_at: FIXTURE_NOW,
+      to: sid,
     },
     {
       mid: `${instance}/1842`,
@@ -37,15 +38,34 @@ export const INBOX_FRAME: Static<typeof InboxFrame> = {
       text: "確認する",
       reply_to: mid,
       sent_at: FIXTURE_NOW + 1_000,
+      to: sid,
     },
   ],
 };
 
+/** A later frame, where one message has been handed over and another was never
+ * taken. */
+export const INBOX_REMOVED_FRAME: Static<typeof InboxFrame> = {
+  ev: "topic",
+  topic: "inbox",
+  instance,
+  data: [
+    { mid, removed: true, reason: "delivered" },
+    { mid: `${instance}/1842`, removed: true, reason: "expired" },
+  ],
+};
+
 export const NOTIFY_FRAME: Static<typeof NotifyFrame> = {
   ev: "topic",
   topic: "notify",
   instance,
-  data: { sid, sid_label: "contract-fixtures", text: "確認して", sent_at: FIXTURE_NOW },
+  data: {
+    sid,
+    sid_label: "contract-fixtures",
+    text: "確認して",
+    reply_to: mid,
+    sent_at: FIXTURE_NOW,
+  },
 };
 
 const PEER = {

package/src/identifiers.ts

@@ -1,7 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 
 /** A session id: the uuid Claude Code gives its own session. Globally unique,
- * so it names a session across the whole cluster without an instance prefix. */
+ * so it names a session across the whole mesh without an instance prefix. */
 export const Sid = Type.String({
   $id: "Sid",
   pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",

package/src/messaging/message.ts

@@ -7,7 +7,7 @@ import { InstanceId, Mid, Sender, Sid, Timestamp } from "../identifiers.ts";
  * These are not errors: the op succeeded and the message is held in the
  * recipient's inbox. They tell the sender what to do next — wait, resend to
  * another session, or give up. The op itself fails only when `to` names no
- * session anywhere in the cluster (`session_not_found`). */
+ * session anywhere in the mesh (`session_not_found`). */
 export const UndeliveredReason = Type.Union(
   [
     /** Alive, but not yet listening. The daemon delivers when it starts. */
@@ -89,11 +89,57 @@ export const InboxMessage = Type.Object(
     text: Type.String(),
     reply_to: Type.Optional(Mid),
     sent_at: Timestamp,
+    /** Who it is addressed to. A session's own subscription is already the
+     * recipient, so a row reaching one says nothing by repeating it; a person
+     * holds the inbox of every session in one subscription, and a row that
+     * does not name its recipient cannot be placed against any of them. So the
+     * instance states it on the rows it answers a person with. */
+    to: Type.Optional(Sid),
   },
   { $id: "InboxMessage" },
 );
 export type InboxMessage = Static<typeof InboxMessage>;
 
+/** Why a message is no longer in the inbox.
+ *
+ * The three are apart because they are three different things to have happened
+ * to a message, and a reader watching for one it sent draws each differently:
+ * `delivered` means the recipient has it and its own account of it follows,
+ * while the other two mean it never arrived and never will. A removal with no
+ * reason would leave a waiting message and an abandoned one looking alike. */
+export const InboxRemovedReason = Type.Union(
+  [
+    /** Handed to the recipient. */
+    Type.Literal("delivered"),
+    /** `INBOX_RETENTION_MS` ran out with the recipient never taking it. */
+    Type.Literal("expired"),
+    /** Dropped, oldest first, to take a newer message into a full inbox —
+     * the same event the newer message's sender was told as `inbox_full`. */
+    Type.Literal("dropped"),
+  ],
+  { $id: "InboxRemovedReason" },
+);
+export type InboxRemovedReason = Static<typeof InboxRemovedReason>;
+
+/** A message that has left the inbox.
+ *
+ * A removal has to be a marked element rather than an absence, since a frame
+ * carries only what changed and an absence in it says nothing. It names the
+ * `mid` every row is matched by, and why — there is no message left to
+ * describe, and the reason is the one thing the reader cannot derive. */
+export const InboxRemoved = Type.Object(
+  {
+    mid: Mid,
+    removed: Type.Literal(true),
+    reason: InboxRemovedReason,
+  },
+  { $id: "InboxRemoved" },
+);
+export type InboxRemoved = Static<typeof InboxRemoved>;
+
+export const InboxElement = Type.Union([InboxMessage, InboxRemoved], { $id: "InboxElement" });
+export type InboxElement = Static<typeof InboxElement>;
+
 /** How long an undelivered message is kept for its recipient. The same window
  * a lost session stays listed for: a message outliving the session it was
  * addressed to would be offered to no one, and a session outliving what was
@@ -106,6 +152,21 @@ export const INBOX_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
  * accepts is one the recipient can still be handed. */
 export const INBOX_MAX_PER_SID = 256;
 
-/** The `inbox` topic. Its snapshot is whatever is still undelivered for this
- * session; each later frame is one newly arrived message. */
-export const InboxFrame = topicFrame("inbox", Type.Array(InboxMessage));
+/** The `inbox` topic: what is waiting, for whoever may see it.
+ *
+ * Elements, matched by `mid`. The snapshot is what is still undelivered and
+ * each later frame is what changed — a message arriving, or one leaving as an
+ * `InboxRemoved`.
+ *
+ * **A session's subscription is the delivery and a person's is a view.** What
+ * the session is handed it has been given, and the message leaves its inbox;
+ * what a person reads leaves the inbox exactly as it was, because a person is
+ * not who any of it was addressed to. The asymmetry is the point rather than an
+ * exception: without the view there is no way to see that something sent is
+ * still waiting, and a view that consumed what it looked at would deliver
+ * messages to no one by being opened.
+ *
+ * A person therefore sees a message twice over: waiting here, and afterwards in
+ * the recipient's own transcript. `mid` is what joins the two, and the removal
+ * marked `delivered` is what says the second is coming. */
+export const InboxFrame = topicFrame("inbox", Type.Array(InboxElement));

package/src/messaging/notify.ts

@@ -1,6 +1,6 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response, topicFrame } from "../envelope.ts";
-import { Sid, Timestamp } from "../identifiers.ts";
+import { Mid, Sid, Timestamp } from "../identifiers.ts";
 
 /** A short line meant to reach a person watching, not the session's own turn.
  * Delivery is best effort and unacknowledged; unlike `message.send`, nothing is
@@ -9,6 +9,8 @@ export const NotifySendArgs = Type.Object({
   /** The session the notification is about. Omit to mean the caller. */
   sid: Type.Optional(Sid),
   text: Type.String({ minLength: 1 }),
+  /** The `mid` this line answers, when it answers one. */
+  reply_to: Type.Optional(Mid),
 });
 export type NotifySendArgs = Static<typeof NotifySendArgs>;
 
@@ -24,6 +26,15 @@ export const Notification = Type.Object(
     /** How the session should be shown, resolved by the issuing instance. */
     sid_label: Type.String(),
     text: Type.String(),
+    /** What this line answers, when it answers something. A notification is
+     * shown while the session's own account of the same answer is still being
+     * written, so a reader holding both needs to know they are one thing: the
+     * `mid` is the key it matches on, and without it the two stand as two.
+     *
+     * It says what is answered and never what kind of line this is. A
+     * notification is one thing whoever it came from, and a kind would be read
+     * as a reason to draw it differently. */
+    reply_to: Type.Optional(Mid),
     sent_at: Timestamp,
   },
   { $id: "Notification" },