@twinsearth/w2m-dsh-plugin 1.2.3 → 1.2.6

package/src/relay/state.mjs

@@ -11,7 +11,7 @@
  * there is intentionally no snapshot/serialization hook yet.
  */
 
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes , verify as verifyBytes } from 'node:crypto';
 
 // v0.7.7: fleet scoping. Imported rather than inlined so the rule has one home with its own
 // exhaustive tests — three lines inside this object would be untestable without a live relay.
@@ -22,6 +22,9 @@ import { deviceFleetFields } from '../chatops/fleet-wiring.mjs';
 import { scopeFleetId } from '../chatops/fleet-wiring.mjs';
 // v0.8.1: the account-derived fleet key, so a machine can join with no pairing code.
 import { planJoin } from '../chatops/fleet-join.mjs';
+import { validateTaskDependencies } from './task-deps.mjs';
+import { buildMembers, isMemberRole, setMemberRole as applyMemberRole } from './fleet-members.mjs';
+import { canonicalSignedPayload, publicKeyFromBase64 } from '../util/envelope-signature.mjs';
 
 export const PROTOCOL_VERSION = 1;
 
@@ -506,6 +509,14 @@ export class RabbitState {
     /** @type {{seq:number,event:object,target:string|null}[]} ring buffer, last N events */
     this.buffer = [];
     this.devices = new Map();      // machine_id -> device
+    /** v1.2.5: operator-assigned roles, kept apart from device records so a re-pair cannot change authority. */
+    this.roles = new Map();        // machine_id -> 'owner'|'worker'|'observer'
+    /** v1.2.5: read watermarks per session, per machine. */
+    this.readMarks = new Map();    // session_id -> Map<machine_id, {at_ms, message_id}>
+    /** v1.2.5: operator-assigned roles, kept apart from device records so a re-pair cannot change authority. */
+    this.roles = new Map();        // machine_id -> 'owner'|'worker'|'observer'
+    /** v1.2.5: read watermarks per session, per machine. */
+    this.readMarks = new Map();    // session_id -> Map<machine_id, {at_ms, message_id}>
     this.tokens = new Map();       // device_token -> machine_id
     this.tasks = new Map();        // task_id -> task
     this.results = new Map();      // instanceKey -> {envelope, machine_id, received_at_ms, ...}
@@ -716,6 +727,9 @@ export class RabbitState {
           requirements: t.requirements ?? {},
           compare_policy: t.compare_policy ?? {},
           halt: t.halt ?? 'never',
+      ...(t.mode === 'mapreduce' ? { reduce_argv: Array.isArray(t.reduce_argv) ? t.reduce_argv : null, reducer_machine_id: t.reducer_machine_id ?? null } : {}),
+      max_attempts: Number.isInteger(t.max_attempts) ? t.max_attempts : 1,
+      retry_on: Array.isArray(t.retry_on) ? t.retry_on : [],
           created_by: t.created_by ?? null,
           created_at_ms: Number.isFinite(createdAt) ? createdAt : this.nowMs(),
           command_hash: t.command_hash ?? null,
@@ -737,6 +751,16 @@ export class RabbitState {
         this.tasks.set(task.task_id, task);
         return true;
       }
+      case 'member.role': {
+        /**
+         * v1.2.6: a role survives a restart. The ledger entry already existed (setMemberRole writes it); replaying it here is
+         * what stops "the relay restarted" from silently demoting every owner to the default worker.
+         */
+        if (typeof entry.machine_id !== 'string' || entry.machine_id === '') return false;
+        if (isMemberRole(entry.role) !== true) return false;
+        this.roles.set(entry.machine_id, entry.role);
+        return false;
+      }
       case 'lease.changed': {
         const task = this.tasks.get(entry.task_id);
         const lease = task?.leases.get(entry.machine_id);
@@ -1517,12 +1541,20 @@ export class RabbitState {
     // v0.4.0: refused BEFORE the task literal is built and before any offer is emitted, so a bad
     // value cannot leave a half-created task behind. `POST /v1/task` is all-or-nothing.
     const routing = RabbitState.validateTaskRouting(input);
+    // v1.2.4: prerequisites are validated where the task is CREATED. A graph that only fails later puts the
+    // refusal on a machine that did not create the problem.
+    const deps = validateTaskDependencies({
+      task_id: typeof input.task_id === 'string' ? input.task_id : null,
+      depends_on: input.depends_on,
+      tasksById: this.tasks,
+    });
+    if (deps.ok !== true) return { status: 'refused', refusal_reason: deps.code, detail: deps.detail ?? {} };
 
     const mode = input.mode ?? 'replicate';
-    if (mode !== 'replicate' && mode !== 'split' && mode !== 'broadcast' && mode !== 'pipeline' && mode !== 'compose') {
+    if (mode !== 'replicate' && mode !== 'split' && mode !== 'broadcast' && mode !== 'pipeline' && mode !== 'compose' && mode !== 'mapreduce') {
       throw new ProtocolError(
         'BAD_REQUEST',
-        'mode must be replicate|split|broadcast|pipeline|compose',
+        'mode must be replicate|split|broadcast|pipeline|compose|mapreduce',
         { mode },
       );
     }
@@ -1591,9 +1623,48 @@ export class RabbitState {
     }
     const indexTotal = Number.isInteger(input.index_total) ? input.index_total : 1;
     if (indexTotal < 1) throw new ProtocolError('BAD_REQUEST', 'index_total must be >= 1');
+    /**
+     * v1.2.4 mapreduce: the map half is ordinary dispatch; the reduce half is described here so the caller can run it as an
+     * explicit second task once w2m_wait has verified every shard is present. Deliberately NOT a cascade: a relay that
+     * launches the reduce itself would decide on a partial fleet, and the operator would see one task id for two executions.
+     */
+    let reduceArgv = null;
+    let reducerMachineId = null;
+    if (mode === 'mapreduce') {
+      if (indexTotal !== 1) {
+        throw new ProtocolError('BAD_REQUEST', 'mode=mapreduce maps the whole input on every machine, so index_total must be 1', { index_total: indexTotal });
+      }
+      const argv = input.reduce_argv;
+      if (!Array.isArray(argv) || argv.length === 0 || argv.some((part) => typeof part !== 'string' || part === '')) {
+        throw new ProtocolError('BAD_REQUEST', 'mode=mapreduce requires reduce_argv as a non-empty string[]', { reduce_argv: argv ?? null });
+      }
+      reduceArgv = [...argv];
+      if (input.reducer_machine_id !== undefined && input.reducer_machine_id !== null && typeof input.reducer_machine_id !== 'string') {
+        throw new ProtocolError('BAD_REQUEST', 'reducer_machine_id must be a machine id string', { reducer_machine_id: input.reducer_machine_id });
+      }
+      reducerMachineId = typeof input.reducer_machine_id === 'string' && input.reducer_machine_id !== '' ? input.reducer_machine_id : null;
+    } else if (input.reduce_argv !== undefined || input.reducer_machine_id !== undefined) {
+      throw new ProtocolError('BAD_REQUEST', 'reduce_argv and reducer_machine_id are only valid with mode=mapreduce', { mode });
+    }
 
     const halt = input.halt ?? 'never';
     if (halt !== 'never' && halt !== 'now') throw new ProtocolError('BAD_REQUEST', 'halt must be never|now', { halt });
+    /**
+     * v1.2.4 retry policy: how many attempts the task may take in total, and which terminal conditions justify
+     * another. Default one attempt and no retry, so every existing caller keeps at-most-once semantics.
+     */
+    const maxAttempts = Number.isInteger(input.max_attempts) ? input.max_attempts : 1;
+    if (maxAttempts < 1 || maxAttempts > 5) {
+      throw new ProtocolError('BAD_REQUEST', 'max_attempts must be an integer 1..5', { max_attempts: input.max_attempts });
+    }
+    const RETRYABLE = ['expired', 'failed', 'partial', 'timeout'];
+    if (input.retry_on !== undefined && !Array.isArray(input.retry_on)) {
+      throw new ProtocolError('BAD_REQUEST', 'retry_on must be an array of expired|failed|partial|timeout', { retry_on: input.retry_on });
+    }
+    const retryOn = Array.isArray(input.retry_on) ? [...new Set(input.retry_on)] : [];
+    if (retryOn.some((reason) => typeof reason !== 'string' || !RETRYABLE.includes(reason))) {
+      throw new ProtocolError('BAD_REQUEST', 'retry_on must list expired|failed|partial|timeout', { retry_on: input.retry_on, retryable: RETRYABLE });
+    }
 
     const taskId = input.task_id ?? this.nextId();
     if (this.tasks.has(taskId)) {
@@ -1659,6 +1730,8 @@ export class RabbitState {
       // machine. Named explicitly so it travels.
       cwd_outside_project: input.cwd_outside_project === true,
       index_total: indexTotal,
+      // v1.2.4: the reduce half travels with the task so a caller (and a revived relay) can read what was intended.
+      ...(mode === 'mapreduce' ? { reduce_argv: reduceArgv, reducer_machine_id: reducerMachineId } : {}),
       timeout_ms: timeoutMs,
       write: input.write === true,
       write_scope: input.write_scope ?? [],
@@ -1673,6 +1746,14 @@ export class RabbitState {
       created_at_ms: now,
       command_hash: commandHash,
       attempt: 1,
+      // v1.2.4: the policy travels with the task so a revived relay can still decide to retry after a restart.
+      max_attempts: maxAttempts,
+      retry_on: retryOn,
+      // v1.2.4: prerequisites and an assignee travel with the task, because a graph the relay validated but did not
+      // store would have to be re-derived later -- and a re-derivation that disagrees with the validation is exactly
+      // the silent-drop failure this field-by-field literal exists to prevent.
+      depends_on: deps.ok === true ? deps.depends_on : [],
+      assignee: typeof input.assignee === 'string' && input.assignee !== '' ? input.assignee : null,
       leases: new Map(),
       cancelled: false,
       cancel_reason: null,
@@ -2144,6 +2225,54 @@ export class RabbitState {
     };
   }
 
+  /** v1.2.6: the role this machine holds, for the permission matrix. Unknown means worker, never owner. */
+  roleOf(machineId) {
+    return typeof machineId === 'string' ? (this.roles.get(machineId) ?? null) : null;
+  }
+
+  /** v1.2.5: the fleet's members, with the role each holds and when it joined. */
+  listMembers() {
+    return buildMembers({ devices: this.devices, roles: this.roles });
+  }
+
+  /** v1.2.5: an operator decision about one machine. Refused by name, never silently ignored. */
+  setMemberRole(machineId, role) {
+    const result = applyMemberRole({ machineId, role, devices: this.devices, roles: this.roles });
+    if (result.ok === true) {
+      this.emit('notice', { level: 'info', code: 'MEMBER_ROLE_SET', message: `${machineId} is now ${role}`, machine_id: machineId });
+      this._ledger({ type: 'member.role', machine_id: machineId, role });
+    }
+    return result;
+  }
+
+  /**
+   * v1.2.5: record that a machine has read a session up to a marker.
+   *
+   * Only forward: a stale marker arriving after a newer one must not move the watermark backwards, or the unread count would
+   * grow for messages the machine has already seen.
+   */
+  markRead(sessionId, machineId, marker = {}) {
+    if (typeof sessionId !== 'string' || sessionId === '') return { ok: false, code: 'BAD_SESSION' };
+    if (typeof machineId !== 'string' || machineId === '') return { ok: false, code: 'BAD_MACHINE' };
+    const atMs = Number.isFinite(marker.at_ms) ? Math.floor(marker.at_ms) : this.nowMs();
+    const messageId = typeof marker.message_id === 'string' && marker.message_id !== '' ? marker.message_id : null;
+    if (!this.readMarks.has(sessionId)) this.readMarks.set(sessionId, new Map());
+    const perSession = this.readMarks.get(sessionId);
+    const previous = perSession.get(machineId) ?? null;
+    if (previous !== null && previous.at_ms > atMs) return { ok: true, mark: { ...previous }, advanced: false };
+    const mark = { at_ms: atMs, message_id: messageId };
+    perSession.set(machineId, mark);
+    return { ok: true, mark: { ...mark }, advanced: true };
+  }
+
+  /** v1.2.5: this machine's watermark for one session (null when it never read it). */
+  readMark(sessionId, machineId) {
+    const perSession = this.readMarks.get(sessionId) ?? null;
+    if (perSession === null) return null;
+    const mark = perSession.get(machineId) ?? null;
+    return mark === null ? null : { ...mark };
+  }
+
   cancelTask(taskId, reason = 'cancelled_by_operator') {
     const task = this.requireTask(taskId);
     if (task.cancelled) return task;
@@ -2309,7 +2438,12 @@ export class RabbitState {
           task_id: task.task_id,
           machine_id: lease.machine_id,
         });
-        if (task.halt === 'now') {
+        // v1.2.4: a caller that named "expired" in retry_on gets the hand-off halt=now always had, as long as it
+        // has attempts left. Without the policy this stays book-keeping only -- the pre-1.2.4 behaviour.
+        const retryExpired = task.halt === 'now'
+          || (Number.isInteger(task.max_attempts) && task.attempt < task.max_attempts
+            && Array.isArray(task.retry_on) && task.retry_on.includes('expired'));
+        if (retryExpired) {
           task.attempt += 1;
           this._takeover(task, lease, nowMs);
         }
@@ -2513,6 +2647,42 @@ export class RabbitState {
       return { deduped: true, task_id: taskId, dedupe_key: dedupeKey, seq: prior.seq };
     }
 
+    /**
+     * v1.2.6: verify the envelope signature against the key this machine registered WHEN IT PAIRED.
+     *
+     * This is the difference between "the result matches the key it carries" and "the key belongs to this machine". The relay is
+     * the place that can answer the second question, because pairing is the moment the operator (or the account) let the machine
+     * in, and that is the only moment its signing key has a reason to be believed. A signature whose key differs from the
+     * registered one is bad_signature even when it verifies against itself.
+     */
+    let signatureStatus = 'unsigned';
+    const signature = envelope.signature ?? null;
+    if (signature !== null) {
+      signatureStatus = 'bad_signature';
+      if (signature.alg !== 'ed25519') {
+        signatureStatus = 'unsupported_algorithm';
+      } else {
+        const registeredKey = machineId === null ? null : (typeof this.devices.get(machineId)?.public_key === 'string' ? this.devices.get(machineId).public_key : null);
+        if (registeredKey === null) {
+          signatureStatus = 'unbound';
+        } else if (signature.public_key !== registeredKey) {
+          signatureStatus = 'bad_signature';
+        } else {
+          const key = publicKeyFromBase64(registeredKey);
+          const payload = canonicalSignedPayload({
+            task_id: envelope.task_id,
+            argv_hash: envelope.command_hash,
+            machine_id: envelope.machine_id,
+            ts: signature.ts,
+          });
+          try {
+            signatureStatus = key !== null && verifyBytes(null, Buffer.from(payload, 'utf8'), key, Buffer.from(String(signature.value ?? ''), 'base64'))
+              ? 'signed' : 'bad_signature';
+          } catch { signatureStatus = 'bad_signature'; }
+        }
+      }
+    }
+
     const now = this.nowMs();
     let envelopeShaOk = null;
     if (typeof envelope.envelope_sha256 === 'string') {
@@ -2531,6 +2701,7 @@ export class RabbitState {
         missing: [...new Set(missing)],
         problems,
         envelope_sha256_ok: envelopeShaOk,
+        signature_status: signatureStatus,
       },
     };
 

package/src/relay/task-deps.mjs

@@ -0,0 +1,92 @@
+/**
+ * Task dependencies: a task may name prerequisites, and the graph is validated where the task is CREATED.
+ *
+ * ## Why the refusal belongs at enqueue time
+ *
+ * A dependency checked when a worker picks the task up puts the refusal on a machine that did not create the problem, at a
+ * time when the operator has long stopped looking. Everything here is a pure function over the tasks already known, so the
+ * relay can answer "is this graph sound" before it stores anything.
+ *
+ * ## What is refused, and why each one is a refusal rather than a warning
+ *
+ * - a dependency on a task that does not exist: it can never complete, so the task can never be ready;
+ * - a self-dependency and any cycle: no topological order exists, so "ready" would never arrive;
+ * - a duplicate id in the list: the same edge stated twice is not two edges, and accepting it would make the stored list
+ *   disagree with the graph it describes.
+ */
+export const TASK_DEPS_REFUSAL = Object.freeze({
+  DEPENDS_ON_NOT_ARRAY: 'TASK_DEPENDS_ON_NOT_ARRAY',
+  DEPENDENCY_UNKNOWN: 'TASK_DEPENDENCY_UNKNOWN',
+  DEPENDENCY_SELF: 'TASK_DEPENDENCY_SELF',
+  DEPENDENCY_DUPLICATE: 'TASK_DEPENDENCY_DUPLICATE',
+  DEPENDENCY_CYCLE: 'TASK_DEPENDENCY_CYCLE',
+  MAX_DEPENDENCIES: 'TASK_DEPENDENCY_TOO_MANY',
+});
+
+/** A cap exists so a hostile caller cannot make the cycle check quadratic without bound. */
+export const MAX_DEPENDENCIES = 32;
+
+/**
+ * Walk the ancestors of a task id and report whether a new edge would close a cycle.
+ *
+ * @param {string} from the dependency being added
+ * @param {string} target the task being created
+ * @param {Map<string, object>} tasksById
+ * @returns {string[]|null} the cycle path when one exists, null otherwise
+ */
+export function wouldCycle(from, target, tasksById) {
+  const seen = new Set();
+  const stack = [from];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (id === target) return [target, from];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const task = tasksById.get(id) ?? null;
+    const deps = Array.isArray(task?.depends_on) ? task.depends_on : [];
+    for (const dep of deps) stack.push(dep);
+  }
+  return null;
+}
+
+/**
+ * @param {{task_id?: string|null, depends_on?: unknown, tasksById?: Map<string, object>}} input
+ * @returns {{ok: true, depends_on: string[]} | {ok: false, code: string, detail?: object}}
+ */
+export function validateTaskDependencies({ task_id = null, depends_on = null, tasksById = new Map() } = {}) {
+  if (depends_on === undefined || depends_on === null) return { ok: true, depends_on: [] };
+  if (!Array.isArray(depends_on)) return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDS_ON_NOT_ARRAY };
+  if (depends_on.length > MAX_DEPENDENCIES) {
+    return { ok: false, code: TASK_DEPS_REFUSAL.MAX_DEPENDENCIES, detail: { count: depends_on.length, max: MAX_DEPENDENCIES } };
+  }
+  const list = [];
+  for (const dep of depends_on) {
+    if (typeof dep !== 'string' || dep === '') {
+      return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDENCY_UNKNOWN, detail: { dependency: dep } };
+    }
+    if (task_id !== null && dep === task_id) return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDENCY_SELF, detail: { task_id } };
+    if (list.includes(dep)) return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDENCY_DUPLICATE, detail: { dependency: dep } };
+    if (!tasksById.has(dep)) return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDENCY_UNKNOWN, detail: { dependency: dep } };
+    const cycle = task_id === null ? null : wouldCycle(dep, task_id, tasksById);
+    if (cycle !== null) return { ok: false, code: TASK_DEPS_REFUSAL.DEPENDENCY_CYCLE, detail: { path: cycle } };
+    list.push(dep);
+  }
+  return { ok: true, depends_on: list };
+}
+
+/**
+ * What a task may do, given its prerequisites' states.
+ *
+ * @param {{depends_on?: string[], tasksById?: Map<string, object>}} input
+ * @returns {'ready'|'blocked'|'waiting'}
+ */
+export function readinessOf({ depends_on = [], tasksById = new Map() } = {}) {
+  let waiting = false;
+  for (const dep of depends_on) {
+    const task = tasksById.get(dep) ?? null;
+    const status = typeof task?.status === 'string' ? task.status : 'unknown';
+    if (status === 'failed' || status === 'cancelled' || status === 'refused') return 'blocked';
+    if (status !== 'completed' && status !== 'done') waiting = true;
+  }
+  return waiting ? 'waiting' : 'ready';
+}

package/src/util/chat-crypto.mjs

@@ -0,0 +1,98 @@
+/**
+ * The fleet chat's end-to-end encryption.
+ *
+ * ## Why the relay never sees the key
+ *
+ * The group key is HKDF over the fleet key, and the fleet key is derived from the account identity on each machine -- it never
+ * travels to the relay. So the relay stores ciphertext it cannot open, and the honest consequence is written down rather than
+ * discovered later: the relay cannot search message content, and the quota it enforces is measured on ciphertext length.
+ *
+ * ## Why the metadata is next to the ciphertext, not inside it
+ *
+ * `{v, alg, iv, tag}` has to be readable by every client of every version, including one that cannot decrypt. Keeping it in a
+ * plain field means a reader can say "encrypted with aes-256-gcm, version 1" even when it has no key, instead of guessing from
+ * random-looking text.
+ *
+ * ## Backward compatibility, both directions
+ *
+ * A message with no `enc` field is plaintext and stays readable. A reader with no key keeps the ciphertext and marks it
+ * `encrypted: true` rather than throwing: an unreadable message must not break a whole page.
+ */
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+
+export const CHAT_CIPHER = Object.freeze({ version: 1, alg: 'aes-256-gcm' });
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+
+/**
+ * Turn the fleet key into the chat group key. Deterministic: every machine in the fleet derives the same key from the same
+ * fleet key, which is what makes a message encrypted on one machine readable on another.
+ *
+ * @param {string} fleetKey base64 (the usual shape) or a passphrase
+ * @returns {Buffer|null}
+ */
+export function deriveChatKey(fleetKey) {
+  if (typeof fleetKey !== 'string' || fleetKey.trim() === '') return null;
+  try {
+    let material = null;
+    try {
+      const decoded = Buffer.from(fleetKey.trim(), 'base64');
+      material = decoded.length >= 16 ? decoded : Buffer.from(fleetKey.trim(), 'utf8');
+    } catch {
+      material = Buffer.from(fleetKey.trim(), 'utf8');
+    }
+    return Buffer.from(hkdfSync('sha256', material, Buffer.from('w2m-fleet-chat-salt'), Buffer.from('fleet-chat-v1'), KEY_BYTES));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Buffer|null} key
+ * @param {string} text
+ * @returns {{ok: true, text: string, enc: {v: number, alg: string, iv: string, tag: string}} | {ok: false, code: string}}
+ */
+export function encryptChatText(key, text) {
+  if (key === null || !Buffer.isBuffer(key) || key.length !== KEY_BYTES) return { ok: false, code: 'CHAT_NO_KEY' };
+  if (typeof text !== 'string' || text === '') return { ok: false, code: 'CHAT_EMPTY_TEXT' };
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(Buffer.from(text, 'utf8')), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    ok: true,
+    text: ciphertext.toString('base64'),
+    enc: { v: CHAT_CIPHER.version, alg: CHAT_CIPHER.alg, iv: iv.toString('base64'), tag: tag.toString('base64') },
+  };
+}
+
+/**
+ * @param {Buffer|null} key
+ * @param {{text?: string, enc?: object|null}} message
+ * @returns {{ok: true, text: string} | {ok: false, code: string}}
+ */
+export function decryptChatMessage(key, message = {}) {
+  const enc = message?.enc ?? null;
+  if (enc === null || enc === undefined) {
+    // Plaintext: the pre-encryption shape, still readable by everyone.
+    return typeof message?.text === 'string' ? { ok: true, text: message.text } : { ok: false, code: 'CHAT_TEXT_MISSING' };
+  }
+  if (key === null || !Buffer.isBuffer(key) || key.length !== KEY_BYTES) return { ok: false, code: 'CHAT_NO_KEY' };
+  if (enc.alg !== CHAT_CIPHER.alg || enc.v !== CHAT_CIPHER.version) return { ok: false, code: 'CHAT_UNSUPPORTED_CIPHER' };
+  try {
+    const iv = Buffer.from(String(enc.iv ?? ''), 'base64');
+    const tag = Buffer.from(String(enc.tag ?? ''), 'base64');
+    if (iv.length !== IV_BYTES || tag.length !== 16) return { ok: false, code: 'CHAT_BAD_ENCRYPTION' };
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(Buffer.from(String(message.text ?? ''), 'base64')), decipher.final()]);
+    return { ok: true, text: plain.toString('utf8') };
+  } catch {
+    return { ok: false, code: 'CHAT_DECRYPT_FAILED' };
+  }
+}
+
+/** True when a message carries the encryption metadata, whatever its text looks like. */
+export function isEncrypted(message) {
+  return message?.enc !== null && message?.enc !== undefined && typeof message.enc === 'object';
+}

package/src/util/dataflow.mjs

@@ -0,0 +1,72 @@
+/**
+ * Data flow across the fleet: map results that are too big to return inline travel as blobs, and the reduce step names
+ * exactly which blob it read.
+ *
+ * ## Why a plan instead of a pipe
+ *
+ * Machines do not send data to each other directly: the relay is the only channel every machine can reach, and it already
+ * stores content-addressed blobs. So the shape is map -> PUT blob -> reduce by sha256. The decisions worth testing are the
+ * boundaries: when an output is inline, when it becomes a blob, and what happens when a blob a reduce depends on is not
+ * there. A pipeline that silently drops a shard is worse than one that fails.
+ */
+
+/** Stage stdout at or below this travels inline in the result envelope. */
+export const MAX_INLINE_BYTES = 64 * 1024;
+
+/** Past this a stage output is not a result any more: it is a data problem the operator has to see. */
+export const HARD_CAP_BYTES = 16 * 1024 * 1024;
+
+/**
+ * Decide how one machine's stage output travels.
+ *
+ * @param {{machineId?: string, stageIndex?: number, stdoutBytes?: number}} input
+ * @returns {{ok: true, mode: 'inline'|'blob', stdoutBytes: number} | {ok: false, code: string, detail: object}}
+ */
+export function planStageOutput(input = {}) {
+  const machineId = typeof input.machineId === 'string' && input.machineId !== '' ? input.machineId : null;
+  if (machineId === null) return { ok: false, code: 'STAGE_MACHINE_MISSING', detail: {} };
+  const stdoutBytes = Number.isFinite(input.stdoutBytes) ? Math.max(0, Math.floor(input.stdoutBytes)) : 0;
+  if (stdoutBytes > HARD_CAP_BYTES) {
+    return { ok: false, code: 'STAGE_OUTPUT_TOO_LARGE', detail: { machineId, stdoutBytes, hardCapBytes: HARD_CAP_BYTES } };
+  }
+  return { ok: true, mode: stdoutBytes <= MAX_INLINE_BYTES ? 'inline' : 'blob', stdoutBytes };
+}
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+/**
+ * Build the reduce input list from the map results.
+ *
+ * Every map machine must contribute exactly one entry: inline text is carried as-is, a blob result must name a sha256.
+ * A missing or malformed hash is refused by name -- the reduce step must never run on a partial fleet and call the answer
+ * complete.
+ *
+ * @param {{results?: Array<{machine_id?: string, mode?: string, stdout?: string, blob_sha256?: string}>,
+ *          reducerMachineId?: string}} input
+ * @returns {{ok: true, reducerMachineId: string, inputs: Array<{machine_id: string, mode: 'inline'|'blob', stdout?: string, sha256?: string}>} |
+ *           {ok: false, code: string, detail: object}}
+ */
+export function buildReducePlan(input = {}) {
+  const reducer = typeof input.reducerMachineId === 'string' && input.reducerMachineId !== '' ? input.reducerMachineId : null;
+  if (reducer === null) return { ok: false, code: 'REDUCER_MISSING', detail: {} };
+  const results = Array.isArray(input.results) ? input.results : null;
+  if (results === null || results.length === 0) return { ok: false, code: 'NO_MAP_RESULTS', detail: {} };
+
+  const seen = new Set();
+  const inputs = [];
+  for (const result of results) {
+    const machineId = typeof result?.machine_id === 'string' && result.machine_id !== '' ? result.machine_id : null;
+    if (machineId === null) return { ok: false, code: 'MAP_MACHINE_MISSING', detail: {} };
+    if (seen.has(machineId)) return { ok: false, code: 'MAP_MACHINE_DUPLICATE', detail: { machineId } };
+    seen.add(machineId);
+    const mode = result?.mode === 'blob' ? 'blob' : 'inline';
+    if (mode === 'blob') {
+      const sha = typeof result?.blob_sha256 === 'string' ? result.blob_sha256.toLowerCase() : '';
+      if (!SHA256.test(sha)) return { ok: false, code: 'BLOB_MISSING', detail: { machineId, sha256: result?.blob_sha256 ?? null } };
+      inputs.push({ machine_id: machineId, mode, sha256: sha });
+    } else {
+      inputs.push({ machine_id: machineId, mode, stdout: typeof result?.stdout === 'string' ? result.stdout : '' });
+    }
+  }
+  return { ok: true, reducerMachineId: reducer, inputs };
+}

package/src/util/envelope-signature.mjs

@@ -0,0 +1,69 @@
+/**
+ * Envelope signatures: what a machine signed, and how a reader checks it.
+ *
+ * ## Why the payload is exactly four fields
+ *
+ * A signature over "the whole envelope" is impossible to verify reproducibly: the envelope carries hashes, timestamps and
+ * transport facts that change between the signing machine and the reader. So the machine signs the four facts that identify
+ * THE COMMAND: task id, argv hash (the envelope's command_hash), machine id, and when it signed. Everything else in the
+ * envelope is covered indirectly through those, and a reader verifies exactly this tuple.
+ *
+ * ## Why verification returns a status rather than throwing
+ *
+ * "unsigned" is not an error -- a machine running an older build, or one configured without a device key, is a fact to report.
+ * "bad_signature" is the interesting case: the data does not match the signature, which is exactly what tampering looks like.
+ * A caller must see the difference, so both are values.
+ */
+import { createPublicKey, verify } from 'node:crypto';
+
+/** The DER prefix for an Ed25519 SubjectPublicKeyInfo; the 32 raw key bytes follow. */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+/**
+ * The canonical bytes a machine signs. Sorted keys, no whitespace, so the same tuple always produces the same bytes.
+ *
+ * @param {{task_id: string, argv_hash: string, machine_id: string, ts: string}} input
+ * @returns {string}
+ */
+export function canonicalSignedPayload({ task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts }) {
+  return JSON.stringify({
+    argv_hash: String(argvHash ?? ''),
+    machine_id: String(machineId ?? ''),
+    task_id: String(taskId ?? ''),
+    ts: String(ts ?? ''),
+  });
+}
+
+/**
+ * @param {string|null} publicKeyBase64
+ * @returns {import('node:crypto').KeyObject|null}
+ */
+export function publicKeyFromBase64(publicKeyBase64) {
+  if (typeof publicKeyBase64 !== 'string' || publicKeyBase64 === '') return null;
+  try {
+    const raw = Buffer.from(publicKeyBase64, 'base64');
+    if (raw.length !== 32) return null;
+    return createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{signature?: object|null, task_id?: string, argv_hash?: string, machine_id?: string, ts?: string}} input
+ * @returns {'signed'|'unsigned'|'bad_signature'|'unsupported_algorithm'}
+ */
+export function verifyEnvelopeSignature({ signature = null, task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts } = {}) {
+  if (signature === null || signature === undefined || typeof signature !== 'object') return 'unsigned';
+  if (signature.alg !== 'ed25519') return 'unsupported_algorithm';
+  if (typeof signature.value !== 'string' || signature.value === '') return 'bad_signature';
+  const key = publicKeyFromBase64(signature.public_key);
+  if (key === null) return 'bad_signature';
+  const payload = canonicalSignedPayload({ task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts: signature.ts ?? ts });
+  try {
+    const ok = verify(null, Buffer.from(payload, 'utf8'), key, Buffer.from(signature.value, 'base64'));
+    return ok ? 'signed' : 'bad_signature';
+  } catch {
+    return 'bad_signature';
+  }
+}