@twinsearth/w2m-dsh-plugin 1.2.6 → 1.3.0

package/src/relay/state.mjs

@@ -711,6 +711,7 @@ export class RabbitState {
         const t = entry.task;
         if (!t || typeof t.task_id !== 'string') return false;
         const createdAt = Number.isFinite(t.created_at_ms) ? t.created_at_ms : Date.parse(entry.ts ?? '');
+
         const task = {
           task_id: t.task_id,
           mode: t.mode ?? 'replicate',
@@ -734,6 +735,11 @@ export class RabbitState {
           created_at_ms: Number.isFinite(createdAt) ? createdAt : this.nowMs(),
           command_hash: t.command_hash ?? null,
           attempt: t.attempt ?? 1,
+          // v1.2.7: a revived task keeps its graph edges and assignment, or the scheduler silently becomes a different scheduler.
+          depends_on: Array.isArray(t.depends_on) ? t.depends_on : [],
+          assignee: typeof t.assignee === 'string' && t.assignee !== '' ? t.assignee : null,
+          reduce_of: typeof t.reduce_of === 'string' ? t.reduce_of : null,
+          reduce_inputs: Array.isArray(t.reduce_inputs) ? t.reduce_inputs : [],
           leases: new Map(),
           cancelled: false,
           cancel_reason: null,
@@ -1720,6 +1726,24 @@ export class RabbitState {
         : targetIds[0] ?? null)
       : null;
 
+    /**
+     * v1.2.10: validate the reduce artifact list up front. A malformed list would otherwise become an offer the machine
+     * cannot execute, and the failure would surface as a generic refusal on the executor instead of at dispatch.
+     */
+    const rawReduceInputs = input.reduce_inputs === undefined || input.reduce_inputs === null ? [] : input.reduce_inputs;
+    if (!Array.isArray(rawReduceInputs) || rawReduceInputs.length > 16) {
+      throw new ProtocolError('BAD_REQUEST', 'reduce_inputs must be an array of at most 16 artifacts', { count: Array.isArray(rawReduceInputs) ? rawReduceInputs.length : null });
+    }
+    const normalizedReduceInputs = [];
+    for (const artifact of rawReduceInputs) {
+      const machineId = typeof artifact?.machine_id === 'string' && artifact.machine_id !== '' ? artifact.machine_id : null;
+      const sha256 = typeof artifact?.sha256 === 'string' ? artifact.sha256.toLowerCase() : '';
+      if (machineId === null || !/^[0-9a-f]{64}$/.test(sha256)) {
+        throw new ProtocolError('BAD_REQUEST', 'each reduce input must be {machine_id, sha256}', { machine_id: machineId, sha256 });
+      }
+      normalizedReduceInputs.push({ machine_id: machineId, sha256 });
+    }
+
     const task = {
       task_id: taskId,
       mode,
@@ -1754,6 +1778,12 @@ export class RabbitState {
       // 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,
+      /**
+       * v1.2.10: a reduce task names the map task it reduces and the artifacts it consumes. The artifact LIST travels with
+       * the task (never inferred by the reducer), because "which shards this reduce covers" is the completeness contract.
+       */
+      reduce_of: typeof input.reduce_of === 'string' && input.reduce_of !== '' ? input.reduce_of : null,
+      reduce_inputs: normalizedReduceInputs,
       leases: new Map(),
       cancelled: false,
       cancel_reason: null,
@@ -1917,6 +1947,31 @@ export class RabbitState {
     if (typeof dedupeKeyBase !== 'string' || dedupeKeyBase.length !== 64) {
       throw new ProtocolError('INTERNAL', 'failed to compute dedupe_key');
     }
+    /**
+     * v1.2.7: a dependency that is not settled means this task is NOT dispatched yet. Its leases are recorded as `waiting`,
+     * which the sweeper ignores and redelivery skips, and `_releaseDependents` moves them to offers when the graph allows it.
+     */
+    const dependencyStates = (task.depends_on ?? []).map((depId) => {
+      const dep = this.tasks.get(depId);
+      if (dep === undefined) return 'unknown';
+      if (dep.cancelled === true) return 'cancelled';
+      return this._taskSettled(dep) === true ? 'completed' : 'waiting';
+    });
+    const graphBlocked = dependencyStates.some((state) => state === 'cancelled' || state === 'unknown');
+    const graphReady = graphBlocked !== true && dependencyStates.every((state) => state === 'completed');
+    const waitingOn = graphReady === true ? [] : (task.depends_on ?? []);
+    /**
+     * v1.2.7: an assignee is a restriction, not a label. Only that machine gets a lease; another machine cannot accidentally
+     * take work that was meant for one host. An unknown assignee is refused by name rather than producing a task nobody holds.
+     */
+    if (task.assignee !== null && !this.devices.has(task.assignee)) {
+      throw new ProtocolError('BAD_REQUEST', 'assignee is not a known device on this relay', { assignee: task.assignee });
+    }
+    if (task.assignee !== null) {
+      const narrowed = targets.filter((device) => device.machine_id === task.assignee);
+      targets.length = 0;
+      targets.push(...narrowed);
+    }
     let lastSeq = this.seq;
     targets.forEach((device, i) => {
       const index = mode === 'replicate' ? 0 : i % indexTotal;
@@ -1950,6 +2005,12 @@ export class RabbitState {
         task.leases.set(device.machine_id, lease);
         return;
       }
+      if (graphReady !== true) {
+        lease.state = 'waiting';
+        lease.waiting_on = waitingOn;
+        task.leases.set(device.machine_id, lease);
+        return;
+      }
       const gate = gateMachine(task, device);
       if (gate) {
         lease.state = 'refused';
@@ -2002,6 +2063,11 @@ export class RabbitState {
         attempt: task.attempt,
         deadline_ms: task.deadline_ms,
         // v0.4.0: routing metadata, so a restarted relay re-offers with the same facts.
+            // v1.2.7: the dependency graph and assignment belong to the task record, not to a reader's memory of it.
+            depends_on: Array.isArray(task.depends_on) ? task.depends_on : [],
+            assignee: task.assignee ?? null,
+            reduce_of: task.reduce_of ?? null,
+            reduce_inputs: Array.isArray(task.reduce_inputs) ? task.reduce_inputs : [],
         origin_machine_id: task.origin_machine_id ?? null,
         p2p: task.p2p ?? null,
       },
@@ -2113,6 +2179,8 @@ export class RabbitState {
        */
       origin_machine_id: task.origin_machine_id ?? null,
       p2p: task.p2p ?? null,
+      // v1.2.10: present only on a reduce task, so a normal offer stays byte-identical.
+      ...(task.reduce_of !== null ? { reduce_of: task.reduce_of, reduce_inputs: task.reduce_inputs } : {}),
       cwd_rel: task.cwd_rel,
       // Omitted when false, so a single-command offer for every existing caller stays byte-identical -- the
       // same reason `stages` above is conditional.
@@ -2211,6 +2279,47 @@ export class RabbitState {
       .map((t) => this.taskSummary(t));
   }
 
+  /** v1.2.7: a task is settled when no lease can still produce a result. Dependencies wait for that, not for a wording. */
+  _taskSettled(task) {
+    for (const lease of task.leases.values()) if (ACTIVE_LEASE_STATES.includes(lease.state)) return false;
+    return true;
+  }
+
+  /**
+   * v1.2.7: release tasks whose prerequisites are all settled.
+   *
+   * Called after a result is stored: a dependency that finished must actually move its dependents from `waiting` to an offer.
+   * Without this the graph would be validated, stored, and then never scheduled -- the exact "validated but not enforced" gap.
+   */
+  _releaseDependents(completedTaskId = null) {
+    const released = [];
+    for (const candidate of this.tasks.values()) {
+      if (!Array.isArray(candidate.depends_on) || candidate.depends_on.length === 0) continue;
+      if (completedTaskId !== null && !candidate.depends_on.includes(completedTaskId)) continue;
+      const waiting = [...candidate.leases.values()].filter((lease) => lease.state === 'waiting');
+      if (waiting.length === 0) continue;
+      let ready = true;
+      for (const depId of candidate.depends_on) {
+        const dep = this.tasks.get(depId);
+        if (dep === undefined) { ready = false; break; }
+        if (dep.cancelled === true) { ready = false; break; }
+        if (this._taskSettled(dep) !== true) { ready = false; break; }
+      }
+      if (ready !== true) continue;
+      for (const lease of waiting) {
+        lease.state = 'queued';
+        lease.claimed_at_ms = this.nowMs();
+        lease.lease_until_ms = this.nowMs() + this.leaseWindowMs();
+        const device = this.devices.get(lease.machine_id);
+        if (device === undefined) continue;
+        this.emitOffer(candidate, lease);
+      }
+      this.emit('notice', { level: 'info', code: 'TASK_READY', message: candidate.task_id + ' is ready: dependencies settled', task_id: candidate.task_id });
+      released.push(candidate.task_id);
+    }
+    return released;
+  }
+
   taskSummary(task) {
     return {
       task_id: task.task_id,
@@ -2222,6 +2331,26 @@ export class RabbitState {
       degraded: task.degraded,
       leases: [...task.leases.values()].map((l) => l.machine_id),
       lease_states: Object.fromEntries([...task.leases.values()].map((l) => [l.machine_id, l.state])),
+      /**
+       * v1.2.7: the state the scheduler is actually in, derived here rather than by each reader.
+       *
+       * Before this, GET /v1/tasks carried no status at all, so a board classified a waiting task as "ready" (its dependencies
+       * map empty) and a released task as "waiting" forever. The board must read the scheduler's own words or it is decoration.
+       */
+      reduce_of: task.reduce_of ?? null,
+      reduce_inputs: Array.isArray(task.reduce_inputs) ? task.reduce_inputs : [],
+      status: (() => {
+        if (task.cancelled === true) return 'cancelled';
+        const leases = [...task.leases.values()];
+        if (leases.some((lease) => lease.state === 'waiting')) return 'waiting';
+        if (leases.some((lease) => ACTIVE_LEASE_STATES.includes(lease.state))) return 'active';
+        const results = [...this.results.values()].filter((record) => record?.envelope?.task_id === task.task_id);
+        if (results.length > 0 && results.every((record) => ['failed', 'crashed', 'refused', 'timeout'].includes(record?.envelope?.status))) return 'failed';
+        return this._taskSettled(task) === true ? 'done' : 'unknown';
+      })(),
+      depends_on: Array.isArray(task.depends_on) ? task.depends_on : [],
+      assignee: task.assignee ?? null,
+      waiting_on: [...task.leases.values()].some((l) => l.state === 'waiting') ? (Array.isArray(task.depends_on) ? task.depends_on : []) : [],
     };
   }
 
@@ -2450,6 +2579,9 @@ export class RabbitState {
       }
       if (changed) task.degraded = 'partial';
     }
+    // v1.2.7: a lease that expires (or a machine that refuses) is a settlement too -- the dependent graph must move.
+    this._releaseDependents();
+
     return expired;
   }
 
@@ -2738,6 +2870,9 @@ export class RabbitState {
     });
 
     // §7: results go into the ledger so the dedupe index survives a restart.
+    // v1.2.7: a settled task may be the prerequisite that frees its dependents.
+    this._releaseDependents(taskId);
+
     this._ledger({ type: 'result.stored', task_id: taskId, machine_id: machineId, result: record });
     if (machineId) {
       const changed = task.leases.get(machineId);

package/src/util/dataflow.mjs

@@ -41,7 +41,8 @@ const SHA256 = /^[0-9a-f]{64}$/;
  * 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}>,
+ * @param {{results?: Array<{machine_id?: string, mode?: string, stdout?: string, blob_sha256?: string, index?: number}>,
+ *          expectedIndexTotal?: number|null,
  *          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}}
@@ -51,6 +52,15 @@ export function buildReducePlan(input = {}) {
   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: {} };
+  /**
+   * v1.2.7: what the task SAID would be produced, not just what arrived.
+   *
+   * Without an expected count the plan can only describe the reports it was handed, so a split run where one shard never
+   * reported produced a plan that looked complete. The count comes from the task (index_total); a missing index is refused
+   * by name before the reduce step can run on a partial fleet.
+   */
+  const expectedTotal = Number.isInteger(input.expectedIndexTotal) && input.expectedIndexTotal > 0 ? input.expectedIndexTotal : null;
+  const seenIndexes = new Set();
 
   const seen = new Set();
   const inputs = [];
@@ -59,6 +69,14 @@ export function buildReducePlan(input = {}) {
     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);
+    if (expectedTotal !== null) {
+      const index = Number.isInteger(result?.index) ? result.index : null;
+      if (index === null) return { ok: false, code: 'MAP_INDEX_MISSING', detail: { machineId } };
+      if (index < 0 || index >= expectedTotal) {
+        return { ok: false, code: 'MAP_INDEX_OUT_OF_RANGE', detail: { machineId, index, expectedIndexTotal: expectedTotal } };
+      }
+      seenIndexes.add(index);
+    }
     const mode = result?.mode === 'blob' ? 'blob' : 'inline';
     if (mode === 'blob') {
       const sha = typeof result?.blob_sha256 === 'string' ? result.blob_sha256.toLowerCase() : '';
@@ -68,5 +86,10 @@ export function buildReducePlan(input = {}) {
       inputs.push({ machine_id: machineId, mode, stdout: typeof result?.stdout === 'string' ? result.stdout : '' });
     }
   }
+  if (expectedTotal !== null) {
+    const missing = [];
+    for (let index = 0; index < expectedTotal; index += 1) if (!seenIndexes.has(index)) missing.push(index);
+    if (missing.length > 0) return { ok: false, code: 'MISSING_SHARD', detail: { missing, expectedIndexTotal: expectedTotal } };
+  }
   return { ok: true, reducerMachineId: reducer, inputs };
 }

package/src/util/reduce-suggestion.mjs

@@ -0,0 +1,107 @@
+/**
+ * The reduce suggestion: what a reader can do about a finished map phase, without deciding it for them.
+ *
+ * ## Why a suggestion instead of a dispatch
+ *
+ * A reduce is a command run on a machine. Every other part of this fleet keeps "who decides to run a command" in the caller: the
+ * relay offers, the agent executes, the plugin dispatches when asked. A tool that dispatched the reduce itself would make a read
+ * into a write, and the caller would lose the ability to say "not on that machine" or "not with those inputs". So this function
+ * answers three questions and stops: is the data complete, who could reduce it, and what is the caller expected to do next.
+ *
+ * ## Why it is derived, not stored
+ *
+ * Two readers of the same aggregate must get the same suggestion, and reading must not change relay state. Everything here comes
+ * from the machine facts the aggregate already publishes (`blob_sha256`, `output_mode`, `stdout_head`, `stdout_bytes`) and the
+ * task's own `index_total`; nothing is written anywhere.
+ */
+import { buildReducePlan } from './dataflow.mjs';
+
+/** The literal next step, kept in the payload so a caller cannot mistake the suggestion for an action. */
+export const REDUCE_NEXT_STEP = 'dispatch the reduce yourself; this tool does not run it';
+
+/**
+ * @param {object} machine a machine entry from the aggregate (full or compact shape)
+ * @returns {boolean} true when this machine actually reported a result
+ */
+export function machineReported(machine) {
+  if (machine === null || typeof machine !== 'object') return false;
+  if ((machine.envelope ?? machine.result ?? null) !== null) return true;
+  return typeof machine.blob_sha256 === 'string'
+    || typeof machine.stdout_head === 'string'
+    || Number.isFinite(machine.stdout_bytes)
+    || (typeof machine.status === 'string' && machine.status !== '' && Number.isFinite(machine.exit_code));
+}
+
+/**
+ * @param {object} machine
+ * @returns {{machine_id: string, index: number|null, mode: 'inline'|'blob', stdout?: string, blob_sha256?: string}}
+ */
+export function reduceInputOf(machine) {
+  const envelope = machine?.envelope ?? machine?.result ?? null;
+  const blobSha256 = typeof envelope?.blob_sha256 === 'string' ? envelope.blob_sha256
+    : (typeof machine?.blob_sha256 === 'string' ? machine.blob_sha256 : null);
+  const head = typeof envelope?.stdout_head === 'string' && envelope.stdout_head !== '' ? envelope.stdout_head
+    : (typeof machine?.stdout_head === 'string' && machine.stdout_head !== '' ? machine.stdout_head : null);
+  const index = Number.isInteger(machine?.index) ? machine.index
+    : (Number.isInteger(envelope?.index) ? envelope.index : null);
+  return {
+    machine_id: typeof machine?.machine_id === 'string' ? machine.machine_id : '',
+    index,
+    mode: blobSha256 === null ? 'inline' : 'blob',
+    ...(head === null ? {} : { stdout: head }),
+    ...(blobSha256 === null ? {} : { blob_sha256: blobSha256 }),
+  };
+}
+
+/**
+ * @param {{machines?: object[], reducerMachineId?: string|null, expectedIndexTotal?: number|null}} input
+ * @returns {{
+ *   ready: boolean,
+ *   plan: object,
+ *   candidates: Array<{machine_id: string, reason: string}>,
+ *   missing: number[],
+ *   next: string,
+ * }}
+ */
+export function suggestReduce(input = {}) {
+  const machines = Array.isArray(input.machines) ? input.machines : [];
+  const reducerMachineId = typeof input.reducerMachineId === 'string' && input.reducerMachineId !== ''
+    ? input.reducerMachineId
+    : null;
+  const expectedIndexTotal = Number.isInteger(input.expectedIndexTotal) && input.expectedIndexTotal > 0
+    ? input.expectedIndexTotal
+    : null;
+
+  const reported = machines.filter(machineReported);
+  const results = reported.map(reduceInputOf);
+  const candidates = reported.map((machine) => ({
+    machine_id: typeof machine?.machine_id === 'string' ? machine.machine_id : '',
+    reason: 'reported-shard',
+  }));
+
+  /**
+   * The reducer is a caller decision. A named reducer that never reported is a refusal with a name, not a suggestion to pick
+   * somebody else: changing the machine changes what the reduce runs against.
+   */
+  let plan;
+  if (reducerMachineId !== null && !candidates.some((candidate) => candidate.machine_id === reducerMachineId)) {
+    plan = { ok: false, code: 'REDUCER_UNREPORTED', detail: { reducerMachineId } };
+  } else {
+    plan = buildReducePlan({
+      results,
+      reducerMachineId,
+      expectedIndexTotal,
+    });
+  }
+
+  const missing = plan.ok === false && plan.code === 'MISSING_SHARD' && Array.isArray(plan.detail?.missing)
+    ? [...plan.detail.missing]
+    : [];
+  return {
+    ready: plan.ok === true,
+    plan,
+    candidates,
+    missing,
+    next: REDUCE_NEXT_STEP,
+  };
+}