@ccmsg/protocol 1.21.0 → 1.22.1

package/README.md

@@ -2,11 +2,11 @@
 
 > 🇯🇵 [README-ja.md](./README-ja.md)
 
-The **contract of record** shared by the ccmsg daemon and its web UI. It holds the shape of
-every op, event, error code and identifier as a schema, and both sides validate against it.
+The **contract of record** shared by the ccmsg daemon and its web UI. It holds the shape of every op, event, error code and identifier as a schema, and both sides validate against it.
 
-The contract is decided here and the daemon and web UI follow it. Neither side learns the
-other's internals by any route that does not pass through it.
+The contract is decided here and the daemon and web UI follow it. Neither side learns the other's internals by any route that does not pass through it.
+
+It covers 48 ops over four planes (common, messaging, control, mesh), 13 topics that are each a snapshot plus a stream of changes, one closed union of 21 error codes, and the op attribute table that authorization, capability gating and forwarding all read.
 
 ## Install
 
@@ -24,9 +24,11 @@ OP_ATTRIBUTES["message.send"].roles; // authorization reads the table, not a bra
 opErrors("session.rename"); // the codes this op may answer with
 ```
 
+`@ccmsg/protocol/fixtures` is a second entry point holding a representative JSON of the real wire for every request, reply and topic frame. An implementation's tests read them from here rather than keeping a copy that goes stale.
+
 ## Documentation
 
-- [DESIGN.md](./docs/DESIGN.md) — layers, planes, the op attribute table, and the conventions
+- [DESIGN.md](./docs/DESIGN.md) — the layers, the four planes, the op attribute table, how topics are folded, the item types a transcript is read into, instances and mesh, authenticating a person, and the naming conventions
 
 ## License
 

package/package.json

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

package/src/attributes.ts

@@ -19,10 +19,10 @@ export interface OpAttributes {
   readonly roles: readonly Role[];
   /** Whether the op requires an identity settled by a greeting.
    *
-   * On a WebSocket connection the ops that may arrive before one are the three
-   * greetings and `instance.ping` — a reachability check answers about the
-   * instance and not about the caller, so there is no identity for it to want.
-   * The ops carried over HTTP answer before any connection exists, which is
+   * On a WebSocket connection the only ops that may arrive before one are the
+   * three greetings: a caller that will not say who it is has nothing to be
+   * answered, and whether the instance is there is already known once the
+   * connection was made. The ops carried over HTTP answer before any connection exists, which is
    * what `carrier` says; `needs_hello` is false on them because there is no
    * greeting to have sent, not because they are open on a settled one. */
   readonly needs_hello: boolean;
@@ -90,7 +90,7 @@ export const OP_ATTRIBUTES = {
   "instance.ping": {
     plane: "common",
     roles: ALL_ROLES,
-    needs_hello: false,
+    needs_hello: true,
     locality: "cluster",
     errors: [],
   },

package/src/common/hello.ts

@@ -7,7 +7,8 @@ import { SessionMetaFields } from "../session-meta.ts";
  *
  * It is not signed and proves nothing on its own: it names the peer and says
  * where its one-off key can be fetched. The proof that binds this connection to
- * `iss` follows on a separate exchange (mesh-peer-auth §5). */
+ * `iss` follows on a separate exchange (the daemon's mesh peer authentication
+ * decision). */
 export const MeshHello = Type.Object(
   {
     /** Generation of the mesh handshake format, apart from the protocol

package/src/errors.ts

@@ -27,7 +27,7 @@ export const ERROR_CODES = [
    * in their `errors`, since only an op that queues for a reader has a queue to
    * fill. */
   "rate_limited",
-  // --- rule-derived (op attribute table §0) ---
+  // --- rule-derived (op attribute table) ---
   /** The connection's role is outside the op's `roles`. Argument problems stay
    * on `invalid_args` / `bad_request`. */
   "forbidden",

package/src/identifiers.ts

@@ -55,7 +55,7 @@ export type InstanceId = Static<typeof InstanceId>;
  * identifies where an instance lives changing with it, and what lets the HTTP
  * routes be spelled without stripping a suffix off first.
  *
- * Compared as a whole string, path included (mesh-peer-auth §4.2 — one origin
+ * Compared as a whole string, path included (one origin
  * may host several instances, so an origin-level comparison would confuse
  * them). The trailing slash is required so that comparison is exact: `/ccmsg`
  * and `/ccmsg/` would otherwise be two spellings of one instance.