dsh-zen-remote 2.3.6 → 2.3.8

package/src/log-ring.ts

@@ -0,0 +1,101 @@
+/**
+ * CU-1: the plugin's in-process diagnostic log ring (SPEC §方案 C). A bounded
+ * FIFO of the plugin row's own log lines, kept in memory only — the desktop
+ * app writes no log file, so this is the one artifact the debug report (CU-2)
+ * can read on either role. Deliberately NOT a file, and deliberately only
+ * this plugin's lines: DSH's own log stream stays untouched.
+ *
+ * Pure module: no DSH imports, no I/O, no clocks beyond the timestamp it
+ * stamps entries with. The wiring lives in src/index.ts, which funnels its
+ * `logWarn` / `logInfo` through {@link createPluginLog} so existing call
+ * sites enter the ring unchanged (double write: logger first, ring second),
+ * and pushes the handful of lifecycle events (row apply/reload, gateway
+ * spawn/exit, relay link flips, fetch-route installs) by hand.
+ *
+ * One discipline the debug report leans on: ring lines carry event codes,
+ * id shapes and counters — never payloads. The redactor (debug-redact.ts)
+ * is the second layer, not the license to log secrets here.
+ */
+
+import { format } from 'node:util'
+
+/** Severity of one ring entry. The ring only distinguishes what the report
+ * renders: info lines and warnings. */
+export type LogLevel = 'info' | 'warn'
+
+/** One ring entry: ISO timestamp, level, fully interpolated message. */
+export interface LogRingEntry {
+  t: string
+  level: LogLevel
+  msg: string
+}
+
+/** Longest message kept, in characters (UTF-16 code units). Debug lines are
+ * codes and shapes, not dumps — anything longer was the wrong thing to log. */
+const MAX_MSG_CHARS = 512
+
+/** The ring's face. `push` never throws and never returns anything; callers
+ * log through it exactly like they would through the context logger. */
+export interface LogRing {
+  push(level: LogLevel, formatText: string, ...args: unknown[]): void
+  /** Oldest-last copy of the ring. Mutating the returned array or its
+   * entries never reaches the ring's own state. */
+  snapshot(): LogRingEntry[]
+}
+
+/**
+ * Create one bounded log ring. `cap` defaults to 300 entries — a full debug
+ * session of lifecycle lines plus a healthy share of warnings, while keeping
+ * the report a fixed small size. A cap below 1 is clamped to 1.
+ */
+export function createLogRing(cap = 300): LogRing {
+  const capacity = Number.isFinite(cap) && cap >= 1 ? Math.floor(cap) : 1
+  const entries: LogRingEntry[] = []
+  return {
+    push(level, formatText, ...args) {
+      let msg: string
+      try {
+        msg = args.length === 0 ? String(formatText) : format(formatText, ...args)
+      } catch {
+        // A malformed format string must never break the caller's flow —
+        // keep the raw template as the message.
+        msg = String(formatText)
+      }
+      if (msg.length > MAX_MSG_CHARS) msg = msg.slice(0, MAX_MSG_CHARS)
+      entries.push({ t: new Date().toISOString(), level, msg })
+      if (entries.length > capacity) entries.splice(0, entries.length - capacity)
+    },
+    snapshot() {
+      return entries.map((entry) => ({ ...entry }))
+    },
+  }
+}
+
+/** The logger face this module needs: the cordis context logger's two
+ * methods, each optional (test fakes carry none). */
+export interface PluginLogLike {
+  info?(format: string, ...args: unknown[]): void
+  warn?(format: string, ...args: unknown[]): void
+}
+
+/** The double-writer the apply() wiring funnels its logging through: every
+ * line reaches the context logger (unchanged behavior, unchanged call
+ * sites) AND the ring (the debug report's source). A ring failure is
+ * swallowed; a logger failure propagates exactly as it did before this
+ * module existed. */
+export function createPluginLog(ring: LogRing, logger: PluginLogLike | undefined): { info(format: string, ...args: unknown[]): void, warn(format: string, ...args: unknown[]): void } {
+  return {
+    info(formatText, ...args) {
+      logger?.info?.(formatText, ...args)
+      try {
+        ring.push('info', formatText, ...args)
+      } catch { /* the ring must never break logging */ }
+    },
+    warn(formatText, ...args) {
+      logger?.warn?.(formatText, ...args)
+      try {
+        ring.push('warn', formatText, ...args)
+      } catch { /* the ring must never break logging */ }
+    },
+  }
+}

package/src/merge-streams.ts

@@ -968,6 +968,49 @@ export interface ControlMerger {
   retarget(identity: MergerIdentity): void
 }
 
+/** One `session/control` projection change, independent of the wire shape. */
+export interface ControlProjectionChange {
+  key: string
+  value: unknown
+}
+
+/**
+ * Read the changes of one live `session/control` `projection` frame in either
+ * wire shape. DSH 0.2.2-alpha.3 batched the frame per committed event —
+ * `{type:'projection', sessionId, seq, changes:[{key, val}]}` (its client
+ * face's handleControlFrame iterates `frame.changes`) — where 0.2.1 and
+ * 0.2.2-alpha.2 send one key per frame, `{type:'projection', sessionId, key,
+ * value, seq}` (that client face reads `frame.key` / `frame.value`). A
+ * `changes` array wins when present; `undefined` means neither shape is
+ * usable (a malformed entry spoils the whole frame, like every other
+ * malformed frame here).
+ */
+export function controlProjectionChanges(frame: Record<string, unknown>): ControlProjectionChange[] | undefined {
+  if (Array.isArray(frame.changes)) {
+    const out: ControlProjectionChange[] = []
+    for (const change of frame.changes) {
+      if (!isPlainObject(change) || typeof change.key !== 'string' || !('val' in change)) return undefined
+      out.push({ key: change.key, value: change.val })
+    }
+    return out
+  }
+  if (typeof frame.key === 'string' && 'value' in frame) return [{ key: frame.key, value: frame.value }]
+  return undefined
+}
+
+/**
+ * One single-key `session/control` projection frame that BOTH client
+ * generations apply: the per-key `key` / `value` fields for DSH ≤ 0.2.2-alpha.2
+ * and a one-entry `changes` list for ≥ 0.2.2-alpha.3. Neither client face
+ * validates stream frames (the gateway client only runs a binary `decode`),
+ * and each reads only its own fields, so the extra ones are inert. Splitting a
+ * batched frame into one frame per key at the same seq is lossless: the
+ * projection store applies per key (`seq <= row.seq` per row).
+ */
+export function controlProjectionFrame(sessionId: string, key: string, value: unknown, seq: number): Record<string, unknown> {
+  return { type: 'projection', sessionId, key, value, seq, changes: [{ key, val: value }] }
+}
+
 /**
  * The session/control merger. The control stream is key-value projection
  * traffic with no ordering constraints between sessions, so it needs no
@@ -1016,13 +1059,14 @@ export function createControlMerger(options: ControlMergerOptions): ControlMerge
           // UNCONDITIONALLY (T52-fix3): the host's projection store is
           // first-write-wins per seq, so a catalog-gated original value would
           // occupy the seq and the later virtual rewrite could never land.
-          out.push({
-            type: 'projection',
-            sessionId: virtualize(sessionId),
-            key,
-            value: key === 'modelSelection' ? virtualizeModelSelectionValue(values[key], identity.serverId) : values[key],
-            seq: asOfSeq,
-          })
+          out.push(
+            controlProjectionFrame(
+              virtualize(sessionId),
+              key,
+              key === 'modelSelection' ? virtualizeModelSelectionValue(values[key], identity.serverId) : values[key],
+              asOfSeq,
+            ),
+          )
         }
       }
       return out
@@ -1038,18 +1082,29 @@ export function createControlMerger(options: ControlMergerOptions): ControlMerge
         onDiagnostic?.(`dropped a session/control projection frame with unusable seq ${String(frame.seq)}`)
         return []
       }
-      return [
-        {
-          ...frame,
-          sessionId: virtualize(frame.sessionId),
+      // DSH 0.2.2-alpha.3 batches one event's changes into `changes[]`;
+      // older hosts send one key per frame. Read either, then emit one
+      // dual-shape frame per key so a local UI of EITHER generation applies
+      // it (a mixed local/server pair is only a fingerprint warning, the
+      // stream still flows).
+      const changes = controlProjectionChanges(frame)
+      if (changes === undefined) {
+        onDiagnostic?.('dropped a session/control projection frame with neither key/value nor a changes list')
+        return []
+      }
+      const sessionId = virtualize(frame.sessionId)
+      const seq = frame.seq
+      return changes.map(({ key, value }) =>
+        controlProjectionFrame(
+          sessionId,
+          key,
           // The modelSelection update's providers go virtual with the session
           // id (T52) — same unconditional rewrite as the exploded baseline
           // above (T52-fix3: first-write-wins per seq forbids a catalog gate).
-          ...(frame.key === 'modelSelection'
-            ? { value: virtualizeModelSelectionValue(frame.value, identity.serverId) }
-            : {}),
-        },
-      ]
+          key === 'modelSelection' ? virtualizeModelSelectionValue(value, identity.serverId) : value,
+          seq,
+        ),
+      )
     }
     onDiagnostic?.(`dropped a session/control frame of unknown type ${String(frame.type)}`)
     return []

package/src/relay-filter.ts

@@ -88,9 +88,10 @@ export function filterWorkspaceFrame(frame: unknown, isAccessible: Accessibility
 /**
  * Filter one `session/control` frame. Exactly two frame types exist:
  * `baseline{value:{projections: Record<sessionId, {asOfSeq, values}>}}` — the
- * per-session map keeps only accessible keys — and `projection{sessionId, key,
- * value, seq}` — kept whole or dropped by its session id. Anything else is
- * dropped.
+ * per-session map keeps only accessible keys — and `projection{sessionId, …}`
+ * (per-key `key, value, seq` up to DSH 0.2.2-alpha.2, batched `seq,
+ * changes[]` from alpha.3) — kept whole or dropped by its session id, so either
+ * shape passes untouched. Anything else is dropped.
  *
  * The baseline record is rebuilt with `defineProperty` because a session id of
  * `__proto__` must become an own data property of the new record, not fire the

package/src/relay-server.ts

@@ -27,6 +27,7 @@
  */
 
 import { withPeer } from './owner-peer.js'
+import { controlProjectionFrame } from './merge-streams.js'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { Readable, Transform } from 'node:stream'
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
@@ -2508,8 +2509,9 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
           })
         } else if (decision.filter === 'control') {
           // A newly shared session needs its current projections: fetch
-          // them once and emit one synthesized `projection` frame per key,
-          // shaped exactly like the upstream frames. An unshared session
+          // them once and emit one synthesized `projection` frame per key in
+          // the dual shape both DSH generations read (per-key key/value for
+          // ≤ 0.2.2-alpha.2, a one-entry `changes` list for ≥ alpha.3). An unshared session
           // synthesizes nothing — the client drops it via the workspace
           // stream's re-filtered upserts.
           const syncProjections = async (sessionId: string): Promise<void> => {
@@ -2528,7 +2530,7 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
             const values = isPlainObject(result.values) ? result.values : {}
             const seq = typeof result.asOfSeq === 'number' ? result.asOfSeq : 0
             for (const key of Object.keys(values)) {
-              void writeLine({ type: 'frame', frame: { type: 'projection', sessionId, key, value: values[key], seq } })
+              void writeLine({ type: 'frame', frame: controlProjectionFrame(sessionId, key, values[key], seq) })
             }
           }
           unsubscribe = store.subscribe((event) => {