@twinsearth/w2m-dsh-plugin 1.2.2 → 1.2.5

package/src/relay/state.mjs

@@ -22,6 +22,8 @@ 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, setMemberRole as applyMemberRole } from './fleet-members.mjs';
 
 export const PROTOCOL_VERSION = 1;
 
@@ -506,6 +508,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 +726,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,
@@ -1517,12 +1530,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 +1612,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 +1719,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 +1735,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 +2214,49 @@ export class RabbitState {
     };
   }
 
+  /** 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 +2422,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);
         }

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/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 };
+}