@ccmsg/cli 0.11.3 → 0.11.5

package/src/transport/conn.ts

@@ -8,7 +8,7 @@ import {
 /** One accepted connection, as the layers above transport see it.
  *
  * UDS and WS produce this same type, so nothing above transport can tell them
- * apart (daemon-v2 §3.1). Everything that differs between the two — how a line
+ * apart (DESIGN §2.1). Everything that differs between the two — how a line
  * reaches the peer, how a blocked write is retried — is settled behind `send`. */
 export interface Conn extends Requester {
   /** Distinguishes connections within one process run. It is not an identity:
@@ -34,7 +34,7 @@ export interface Conn extends Requester {
    * (mesh-peer-auth §8.1). Transports that carry no such code ignore it. */
   close(code?: number, reason?: string): void;
   /** Run when the connection is gone. Anything held per connection — the
-   * subscriptions of §6.3 once they exist — is released here, because a closed
+   * subscriptions of DESIGN §6.3 once they exist — is released here, because a closed
    * connection is the only end a subscription has. */
   onClose(listener: () => void): void;
 }
@@ -101,7 +101,7 @@ export class BaseConn implements Conn {
 
 /** The connections one instance currently holds.
  *
- * It exists so shutdown (§8.5 step 3) can reach every connection before any
+ * It exists so shutdown (DESIGN §8.5 step 3) can reach every connection before any
  * listener is closed, and so tests can see that a closed connection is gone. */
 export class ConnRegistry {
   readonly #conns = new Set<Conn>();

package/src/transport/dial.ts

@@ -16,7 +16,7 @@ export interface DialOptions {
 
 /** A connection this instance opened, as the same `Conn` an accepted one is.
  *
- * daemon-v2 §3.1 has one connection type above transport, and a mesh link is a
+ * DESIGN §2.1 has one connection type above transport, and a mesh link is a
  * connection of that layer whichever end dialled it: the two differ in who
  * opened the socket and in nothing the layers above can see. */
 export async function dialWs(options: DialOptions): Promise<Conn> {

package/src/transport/driver.ts

@@ -9,7 +9,7 @@ export interface FrameHandler {
 }
 
 /** The ops whose reply settles the connection's identity. Transport knows these
- * three op names because binding the identity is its job (daemon-v2 §3.1);
+ * three op names because binding the identity is its job (DESIGN §2.1);
  * every other op is opaque to it. */
 
 /** Drive one connection: a line in, a frame answered on the same connection.
@@ -36,7 +36,7 @@ export function createDriver(conn: Conn, handle: FrameHandler) {
           settleIfHello(conn, frame, result);
           conn.send(responseOf(result));
           // Whatever the implementation queued for after its reply — the
-          // snapshot of a fresh subscription (§6.1) — goes out here.
+          // snapshot of a fresh subscription (DESIGN §6.1) — goes out here.
           conn.flushDeferred();
         },
         (cause: unknown) => {

package/src/transport/entry.ts

@@ -1,4 +1,4 @@
-/** Who is allowed to reach this instance at all (daemon-v2 §3.1, "入口の許可").
+/** Who is allowed to reach this instance at all (DESIGN §2.1, "入口の許可").
  *
  * Two questions, because they are asked of different things. `allowRequest`
  * runs for every HTTP request the listener takes, the routed ones included, and

package/src/transport/framing.ts

@@ -1,4 +1,4 @@
-/** Newline-delimited JSON, in one place for both transports (daemon-v2 §3.1).
+/** Newline-delimited JSON, in one place for both transports (DESIGN §2.1).
  *
  * The limit and the backpressure handling live here rather than in the UDS and
  * WS listeners, so the two cannot drift into two framings. */

package/src/transport/listener.ts

@@ -1,6 +1,6 @@
 /** One bound address, and the way to give it up.
  *
- * `kind` exists for the stop order of daemon-v2 §8.5: the UDS is released after
+ * `kind` exists for the stop order of DESIGN §8.5: the UDS is released after
  * everything else, because a client reads "the unix socket refuses" as the
  * instance having finished leaving, and a successor may take the resources it
  * sees freed before that. */
@@ -15,7 +15,7 @@ export interface Listener {
   close(): Promise<void>;
 }
 
-/** The listeners one instance holds, closed in the order §8.5 requires. */
+/** The listeners one instance holds, closed in the order DESIGN §8.5 requires. */
 export class Transport {
   readonly #listeners: Listener[] = [];
 
@@ -29,7 +29,7 @@ export class Transport {
   }
 
   /** Release every address, the unix socket last. Callers do the steps that
-   * come before this one (§8.5 1-4: refuse new work, stop upstream watches,
+   * come before this one (DESIGN §8.5 1-4: refuse new work, stop upstream watches,
    * tell the connections, settle what is persisted). */
   async close(): Promise<void> {
     const held = [...this.#listeners];

package/src/transport/uds.ts

@@ -13,7 +13,7 @@ interface UdsState {
 export interface UdsOptions {
   /** The socket path.
    *
-   * §8.5 asks that closing leave the path alone, because a successor's socket
+   * DESIGN §8.5 asks that closing leave the path alone, because a successor's socket
    * may already stand there. Bun's listener unlinks it in `stop()` regardless
    * (measured against Bun 1.3.13: the path is gone the moment `stop` returns),
    * so this layer cannot honour that on its own — what it can do is not add a
@@ -29,7 +29,7 @@ export interface UdsOptions {
  *
  * `socket.write` hands the bytes to sendto(2) and returns a short count when
  * the socket buffer is full, so the unsent tail is kept by the queue and
- * written again on `drain` — the difference from WS that §3.1 puts in this
+ * written again on `drain` — the difference from WS that DESIGN §2.1 puts in this
  * layer. */
 export function listenUds(options: UdsOptions): Listener {
   const server = Bun.listen<UdsState>({

package/src/transport/ws.ts

@@ -37,7 +37,7 @@ export interface WsOptions {
    *
    * It shares this listener rather than opening a second one: a producer that
    * posts to this instance reaches it at the address it already has, and the
-   * entry check of §3.1 runs before this is asked, so a route cannot be
+   * entry check of DESIGN §2.1 runs before this is asked, so a route cannot be
    * reached by anyone the WebSocket could not be. Answering `undefined` leaves
    * the request to the upgrade, which refuses it.
    *
@@ -54,7 +54,7 @@ export interface WsOptions {
  * newline-delimited framing as the unix socket: one line is one frame, whether
  * a message holds one line or several. Backpressure differs from UDS — a send
  * is either buffered whole by Bun or dropped whole — and the queue absorbs
- * that difference here (§3.1). */
+ * that difference here (DESIGN §2.1). */
 export function serveWs(options: WsOptions): Listener {
   const path = options.path ?? ENTRY_PATH;
   const entry = options.entry ?? OPEN;

package/src/upstream/events.ts

@@ -4,7 +4,7 @@ import type { LlmRequestInfo, Sid, Timestamp } from "@ccmsg/protocol";
  * instance decides whether its series is the session's main one.
  *
  * `main` is a verdict about a session's several series, so it needs the other
- * series to be made and cannot be read off one event (§3.5 renames, it does not
+ * series to be made and cannot be read off one event (DESIGN §2.4 renames, it does not
  * derive). `instance` is stamped by whoever publishes, since an event says
  * nothing about which instance received it. */
 export type LlmRequestObservation = Omit<LlmRequestInfo, "main" | "instance">;
@@ -68,7 +68,7 @@ export type GatewayItem =
       /** The name of the lifetime this request promised, when it promised one.
        * Kept beside the observation rather than inside it: it is how two
        * notices of the gateway's are matched to each other, and nothing a
-       * client reads (§3.5). */
+       * client reads (DESIGN §2.4). */
       readonly notice?: string;
     }
   | { readonly kind: "response"; readonly info: LlmResponseObservation }
@@ -95,7 +95,7 @@ const SAME_NAME_NUMBERS = [
 
 /** The instants the gateway names without the suffix this contract requires of
  * every field that is a point in time. Renamed here, at the boundary, so
- * nothing downstream sees the gateway's spelling (§3.5). */
+ * nothing downstream sees the gateway's spelling (DESIGN §2.4). */
 const RENAMED_INSTANTS = [
   ["cache_since", "cache_since_at"],
   ["cache_until", "cache_until_at"],

package/src/upstream/gateway.ts

@@ -45,14 +45,14 @@ export interface GatewaySetup {
   readonly statsUrl?: string;
 }
 
-/** Read the upstream section (§8.2).
+/** Read the upstream section (DESIGN §8.2).
  *
  * A setting that is there and cannot be honoured ends the start rather than
- * leaving the feature it asked for silently off (DV-Q9): an operator who named
+ * leaving the feature it asked for silently off (DR-0004): an operator who named
  * a webhook source wants the route, and an instance that came up without it
  * looks identical to one nobody is posting to. A section that is absent is not
  * broken — it states that this instance has no gateway, which costs the rows
- * one attribute and nothing else (§5.2). */
+ * one attribute and nothing else (DESIGN §4.3). */
 export function gatewaySetup(config: UpstreamConfig, file: string, env: Env): GatewaySetup {
   const name = config.gateway_webhook_source;
   const url = config.gateway_url;
@@ -112,7 +112,7 @@ export interface GatewayDeps {
   readonly setup: GatewaySetup;
   readonly publish: (topic: string, data: unknown) => void;
   /** The gateway saw something happen for a session, which is an input of the
-   * sessions domain (§5.1) rather than of either topic. */
+   * sessions domain (DESIGN §4.2) rather than of either topic. */
   readonly onActivity?: () => void;
   /** A session already known to be running was seen again: its clock moved,
    * and the row that carries it is what says so. */
@@ -173,7 +173,7 @@ export class Gateway {
     return this.status ?? SILENT;
   }
 
-  /** When the gateway last saw inference for a session (§5.1). */
+  /** When the gateway last saw inference for a session (DESIGN §4.2). */
   activeAt(sid: Sid, now?: Timestamp): Timestamp | undefined {
     return this.requests.activeAt(sid, now);
   }
@@ -184,7 +184,7 @@ export class Gateway {
     return handleWebhook(request, this.#source, this.deps.log);
   }
 
-  /** Stop what is pending. Called from the stop order (§8.5). */
+  /** Stop what is pending. Called from the stop order (DESIGN §8.5). */
   close(): void {
     this.status?.stop();
   }

package/src/upstream/json.ts

@@ -1,6 +1,6 @@
 import type { Timestamp } from "@ccmsg/protocol";
 
-/** What every read of an upstream document is built from (§3.5).
+/** What every read of an upstream document is built from (DESIGN §2.4).
  *
  * The gateway's three documents are read the same way — a field is taken only
  * at the type this contract states for it, and anything else is absent — so the

package/src/upstream/requests.ts

@@ -17,10 +17,10 @@ import type {
 
 export interface LlmRequestsDeps {
   readonly self: InstanceId;
-  /** The one way a value reaches subscribers (§6.1). */
+  /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
   /** An event moved when a session was last seen running inference, which is
-   * an input of the sessions domain (§5.1) and not of this topic. Told when
+   * an input of the sessions domain (DESIGN §4.2) and not of this topic. Told when
    * the window opened, which is the moment the classification can change. */
   readonly onActivity?: () => void;
   /** The same session seen again inside a window already open: one attribute
@@ -32,7 +32,7 @@ export interface LlmRequestsDeps {
 
 /** Which of a session's gateway facts moved.
  *
- * `live` is the moment the classification of §5.1 can change, because the
+ * `live` is the moment the classification of DESIGN §4.2 can change, because the
  * window either opened or closed, and the sessions domain recomputes for it.
  * `clock` is the same session seen again inside a window that was already open
  * — the value of an attribute, not a section anything is in — so what it asks
@@ -209,7 +209,7 @@ export class LlmRequests implements UpstreamResource {
     else if (move === "clock") this.deps.onMoved?.(sid);
   }
 
-  /** When the gateway last saw inference for a session (§5.1). Undefined once
+  /** When the gateway last saw inference for a session (DESIGN §4.2). Undefined once
    * that is old enough to say nothing about whether the session is alive. */
   activeAt(sid: Sid, now: Timestamp = Date.now()): Timestamp | undefined {
     const at = this.#activeAt.get(sid);
@@ -237,7 +237,7 @@ export class LlmRequests implements UpstreamResource {
     }));
   }
 
-  // --- UpstreamResource (§6.3). There is nothing to start: the events are
+  // --- UpstreamResource (DESIGN §6.3). There is nothing to start: the events are
   // pushed to this instance whether or not anyone is listening, because the
   // sessions domain reads the same arrivals for a value of its own.
 
@@ -258,7 +258,7 @@ export class LlmRequests implements UpstreamResource {
    * A session already inside its window moves its clock and nothing else, so
    * the row it lands on is restated on its own: inference is observed several
    * times a second, and recomputing the domain for each would spend the whole
-   * of that work on one attribute of one row (§5.2). */
+   * of that work on one attribute of one row (DESIGN §4.3). */
   private active(sid: Sid, at: Timestamp): GatewayMove {
     const held = this.#activeAt.get(sid);
     if (held !== undefined && held >= at) return "none";

package/src/upstream/stats.ts

@@ -47,7 +47,7 @@ export async function readStats(
   return stats;
 }
 
-/** Read the gateway's document as this contract's answer (§3.5). The dates are
+/** Read the gateway's document as this contract's answer (DESIGN §2.4). The dates are
  * the gateway's own keys and are not reinterpreted: a day here means whatever
  * it means there. */
 export function statsOf(value: unknown): LlmStatsReadResult | undefined {

package/src/upstream/status.ts

@@ -59,7 +59,7 @@ export interface LlmStatusDeps {
 
 /** The gateway's report on the services behind it.
  *
- * `per_instance_whole` (§6.2): a frame replaces what this instance last said
+ * `per_instance_whole` (DESIGN §6.2): a frame replaces what this instance last said
  * and leaves other instances' reports alone, because the report is one document
  * the gateway behind this instance assembles and half of it means nothing on
  * its own.
@@ -85,7 +85,7 @@ export class LlmStatus implements UpstreamResource {
       this.#settling = undefined;
       void this.read();
     }, this.deps.settleMs ?? TROUBLE_SETTLE_MS);
-    // The instance must be able to leave while this is pending (§8.5).
+    // The instance must be able to leave while this is pending (DESIGN §8.5).
     this.#settling.unref?.();
   }
 
@@ -99,7 +99,7 @@ export class LlmStatus implements UpstreamResource {
     await this.#reading;
   }
 
-  // --- UpstreamResource (§6.3)
+  // --- UpstreamResource (DESIGN §6.3)
 
   start(): void {
     this.#listening = true;
@@ -156,7 +156,7 @@ const OFFICIAL_STATES: readonly LlmStatusOfficialState[] = [
 ];
 const OBSERVED_STATES: readonly LlmStatusObservedState[] = ["reachable", "failing", "unknown"];
 
-/** Read the gateway's document as this contract's report (§3.5).
+/** Read the gateway's document as this contract's report (DESIGN §2.4).
  *
  * The gateway already answers in Unix ms under these names, so nothing is
  * converted — but nothing is passed through unread either: every field is

package/src/upstream/usage.ts

@@ -64,7 +64,7 @@ export async function readUsage(
   return usage;
 }
 
-/** Read the gateway's document as this contract's answer (§3.5).
+/** Read the gateway's document as this contract's answer (DESIGN §2.4).
  *
  * The names that differ are the two the gateway spells its own way — `reset`
  * and `window_seconds` — and both are already Unix ms and seconds, so the

package/src/upstream/webhook.ts

@@ -94,7 +94,7 @@ export async function handleWebhook(
 /** Whether the request presents exactly this source's token.
  *
  * Compared in constant time. The route is reachable only by whoever the entry
- * check of §3.1 already let through, but a comparison that leaks its prefix
+ * check of DESIGN §2.1 already let through, but a comparison that leaks its prefix
  * through timing is the kind of thing that quietly stops being enough once an
  * instance is bound past loopback. */
 function authorized(header: string | null, token: string): boolean {