@twinsearth/w2m-dsh-plugin 1.2.0 → 1.2.2

package/src/relay/fleet-memory.mjs

@@ -0,0 +1,85 @@
+/**
+ * Shared fleet memory: an append-only record log with compare-and-swap.
+ *
+ * ## What this is for
+ *
+ * The fleet memory was read/publish only. Two machines writing meant last-writer-wins over a whole document, so a record
+ * added by one could vanish because the other had an older copy. Here the unit of change is a RECORD and the guard is a
+ * revision number: a writer says which revision it saw, and a stale one is refused with the current revision and a diff
+ * summary instead of being applied on top of something it never read.
+ *
+ * ## Refusals are values
+ *
+ * `REVISION_CONFLICT` is a normal answer, not an error: the caller re-reads, decides, and retries. Automatic retry is
+ * deliberately NOT implemented here -- retrying in the transport would turn a visible conflict into a silent overwrite.
+ */
+export class FleetMemoryConflict extends Error {}
+
+/**
+ * @param {{now?: () => number, maxRecords?: number}} [options]
+ */
+export function createFleetMemory(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const maxRecords = Number.isInteger(options.maxRecords) && options.maxRecords > 0 ? options.maxRecords : 10_000;
+  /** doc -> { revision, records: [{ at_ms, author_machine_id, text }] } */
+  const docs = new Map();
+
+  const stateOf = (doc) => docs.get(doc) ?? { revision: 0, records: [] };
+
+  /**
+   * @param {string} doc
+   * @returns {{ok: true, revision: number, records: object[], count: number}}
+   */
+  function get(doc) {
+    const state = stateOf(doc);
+    return { ok: true, revision: state.revision, records: state.records.map((r) => ({ ...r })), count: state.records.length };
+  }
+
+  /**
+   * Append records, guarded by the revision the caller saw.
+   *
+   * @param {{doc: string, if_revision?: number|null, author_machine_id: string, records: string[]}} input
+   * @returns {{ok: true, revision: number, appended: number} |
+   *           {ok: false, code: string, detail?: object}}
+   */
+  function append(input) {
+    const doc = typeof input?.doc === 'string' && input.doc.trim() !== '' ? input.doc.trim() : null;
+    if (doc === null) return { ok: false, code: 'BAD_DOC' };
+    const author = typeof input?.author_machine_id === 'string' && input.author_machine_id !== '' ? input.author_machine_id : null;
+    if (author === null) return { ok: false, code: 'BAD_AUTHOR' };
+    const incoming = Array.isArray(input?.records) ? input.records : null;
+    if (incoming === null) return { ok: false, code: 'NO_RECORDS' };
+    const texts = incoming.filter((r) => typeof r === 'string' && r.trim() !== '');
+    if (texts.length === 0) return { ok: false, code: 'NO_RECORDS' };
+    if (texts.length !== incoming.length) return { ok: false, code: 'BAD_RECORD' };
+
+    const state = stateOf(doc);
+    const seen = Number.isInteger(input?.if_revision) ? input.if_revision : null;
+    if (seen !== null && seen !== state.revision) {
+      // The diff is what the caller needs to decide: how far ahead the document is, and what it has not read yet.
+      const missing = state.records.slice(Math.max(0, seen < 0 ? 0 : seen));
+      return {
+        ok: false,
+        code: 'REVISION_CONFLICT',
+        detail: {
+          if_revision: seen,
+          revision: state.revision,
+          behind_by: state.revision - seen,
+          unread_records: missing.length,
+          sample: missing.slice(0, 3).map((r) => ({ author: r.author_machine_id, text: r.text.slice(0, 80) })),
+        },
+      };
+    }
+    if (state.records.length + texts.length > maxRecords) {
+      return { ok: false, code: 'MEMORY_FULL', detail: { count: state.records.length, maxRecords } };
+    }
+
+    const at = now();
+    const added = texts.map((text) => ({ at_ms: at, author_machine_id: author, text }));
+    const next = { revision: state.revision + 1, records: [...state.records, ...added] };
+    docs.set(doc, next);
+    return { ok: true, revision: next.revision, appended: added.length };
+  }
+
+  return { get, append, _docs: docs };
+}

package/src/relay/fleet-messages.mjs

@@ -88,25 +88,46 @@ export function createFleetMessages(options = {}) {
     const text = input.text;
     if (text.trim() === '') return { ok: false, code: 'EMPTY_TEXT' };
     // Reject control characters (except tab/newline): "plain text" is a contract, not a preference.
-    // Control characters are the thing being rejected here, so the rule that forbids them in a pattern
-    // does not apply -- the escape IS the contract.
-    // eslint-disable-next-line no-control-regex
+    // eslint-disable-next-line no-control-regex
     if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) return { ok: false, code: 'NOT_TEXT' };
     const bytes = Buffer.byteLength(text, 'utf8');
     if (bytes > maxMessageBytes) return { ok: false, code: 'MESSAGE_TOO_LARGE', detail: { bytes, maxBytes: maxMessageBytes } };
 
+    // Addressing: 'all' is the group, a machine id is one recipient. ONE row either way -- N copies for N recipients
+    // would multiply the byte budget by the fleet size for no extra meaning; visibility is a filter at read time.
+    const to = typeof input?.to === 'string' && input.to.trim() !== '' ? input.to.trim() : 'all';
+    if (to !== 'all' && (to.length > 64 || /\s/.test(to))) return { ok: false, code: 'BAD_ADDRESS' };
+    // Correlation: a thread groups a conversation, reply_to points at the message being answered, turn orders the
+    // exchange inside one thread. Plain fields, validated rather than trusted.
+    const threadId = typeof input?.thread_id === 'string' && input.thread_id.trim() !== ''
+      ? input.thread_id.trim().slice(0, 64)
+      : null;
+    const replyTo = typeof input?.reply_to === 'string' && input.reply_to.trim() !== '' ? input.reply_to.trim() : null;
+
     const before = usage();
     const limit = limitBytes();
     if (before.used_24h_bytes + bytes > limit) {
       return { ok: false, code: 'FLEET_QUOTA_EXCEEDED', detail: { used_24h_bytes: before.used_24h_bytes, limit_bytes: limit, bytes } };
     }
 
+    // A reply must point at something that exists in the SAME session: a dangling reply_to makes a thread unreadable.
+    const existing = sessions.get(sessionId) ?? [];
+    if (replyTo !== null && !existing.some((m) => m.message_id === replyTo)) {
+      return { ok: false, code: 'REPLY_TARGET_MISSING', detail: { reply_to: replyTo } };
+    }
+    const threadOf = threadId ?? (replyTo !== null ? (existing.find((m) => m.message_id === replyTo)?.thread_id ?? null) : null);
+    const turn = existing.filter((m) => (threadOf === null ? m.thread_id === null : m.thread_id === threadOf)).length + 1;
+
     seq += 1;
     const message = {
       message_id: 'msg-' + String(seq).padStart(6, '0'),
       session_id: sessionId,
       fleet_id: typeof input?.fleet_id === 'string' ? input.fleet_id : null,
       machine_id: machineId,
+      to,
+      thread_id: threadOf,
+      reply_to: replyTo,
+      turn,
       text,
       at_ms: now(),
       bytes,
@@ -122,9 +143,16 @@ export function createFleetMessages(options = {}) {
   }
 
   /** Read one session's flow. \`since_ms\` is exclusive; the order is the order it was said. */
-  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50 } = {}) {
+  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50, for_machine_id: forMachine = null,
+    thread_id: threadId = null, to: toFilter = null } = {}) {
     const rows = sessions.get(sessionId) ?? [];
-    const filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    let filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    // A reader sees the group and what was addressed to it, never another machine's private message.
+    if (typeof forMachine === 'string' && forMachine !== '') {
+      filtered = filtered.filter((m) => (m.to ?? 'all') === 'all' || m.to === forMachine || m.machine_id === forMachine);
+    }
+    if (typeof threadId === 'string' && threadId !== '') filtered = filtered.filter((m) => m.thread_id === threadId);
+    if (typeof toFilter === 'string' && toFilter !== '') filtered = filtered.filter((m) => (m.to ?? 'all') === toFilter);
     const capped = filtered.slice(-Math.max(1, Math.min(limit, 200)));
     return { ok: true, messages: capped.map((m) => ({ ...m })), count: capped.length };
   }

package/src/relay/server.mjs

@@ -22,7 +22,8 @@ import {
   RabbitState,
   rfc3339,
 } from './state.mjs';
-import { createFleetMessages } from './fleet-messages.mjs';
+import { createFleetMessages } from './fleet-messages.mjs';
+import { createFleetMemory } from './fleet-memory.mjs';
 import { createJoinChallenges } from './join-challenge.mjs';
 import { createAdmission } from './admission.mjs';
 import { Persistence } from './persistence.mjs';
@@ -1045,6 +1046,7 @@ export class RelayServer {
     // speak as another. The refusal codes from the store are passed through unchanged (FLEET_QUOTA_EXCEEDED included)
     // because a caller that cannot tell "too big" from "over quota" from "not text" cannot tell the operator what to do.
     this.fleetMessages ??= createFleetMessages({ now: () => this.state.nowMs() });
+    this.fleetMemory ??= createFleetMemory({ now: () => this.state.nowMs() });
 
     if (method === 'POST' && path === '/v1/fleet/messages') {
       const body = takeJson();
@@ -1052,6 +1054,9 @@ export class RelayServer {
         session_id: body.session_id,
         fleet_id: typeof body.fleet_id === 'string' ? body.fleet_id : null,
         machine_id: device.machine_id,
+        to: body.to,
+        thread_id: body.thread_id,
+        reply_to: body.reply_to,
         text: body.text,
       });
       if (posted.ok !== true) {
@@ -1098,6 +1103,11 @@ export class RelayServer {
         session_id: url.searchParams.get('session_id') ?? '',
         since_ms: sinceRaw === null ? null : Number(sinceRaw),
         limit: limitRaw === null ? 50 : Number(limitRaw),
+        // Addressing/correlation filters. `for_me=1` is answered from the authenticated device identity, never from a
+        // caller-supplied machine id: a reader must not be able to ask for another machine's private messages.
+        for_machine_id: url.searchParams.get('for_me') === '1' ? device.machine_id : null,
+        thread_id: url.searchParams.get('thread_id'),
+        to: url.searchParams.get('to'),
       });
       return sendJson(res, 200, {
         protocol_version: PROTOCOL_VERSION,
@@ -1107,6 +1117,37 @@ export class RelayServer {
       });
     }
 
+    // v1.2.2: shared memory writes. Compare-and-swap on a revision, because two machines appending to one document is
+    // otherwise last-writer-wins over the whole thing -- a record one machine added would vanish because the other had an
+    // older copy. A stale writer gets 409 and the records it has not read; it is NOT retried here, because retrying in
+    // the transport turns a visible conflict into a silent overwrite.
+    if (path.startsWith('/v1/fleet/memory/')) {
+      const doc = decodeURIComponent(path.slice('/v1/fleet/memory/'.length));
+      if (doc === '') throw new ProtocolError('BAD_REQUEST', 'memory doc is required', { method, path });
+      this.fleetMemory ??= createFleetMemory({ now: () => this.state.nowMs() });
+      if (method === 'GET') {
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...this.fleetMemory.get(doc) });
+      }
+      if (method === 'PUT') {
+        const body = takeJson();
+        const appended = this.fleetMemory.append({
+          doc,
+          if_revision: Number.isInteger(body.if_revision) ? body.if_revision : null,
+          author_machine_id: device.machine_id,
+          records: Array.isArray(body.records) ? body.records : (typeof body.text === 'string' ? [body.text] : []),
+        });
+        if (appended.ok !== true) {
+          const status = appended.code === 'REVISION_CONFLICT' ? 409 : 400;
+          return sendJson(res, status, {
+            protocol_version: PROTOCOL_VERSION, ok: false,
+            error: { code: appended.code }, detail: appended.detail ?? null,
+          });
+        }
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...appended });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'memory accepts GET or PUT', { method, path });
+    }
+
     throw new ProtocolError('NOT_FOUND', `no route for ${method} ${path}`, { method, path });
   }