@twinsearth/w2m-dsh-plugin 1.2.7 → 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',
@@ -737,6 +738,8 @@ export class RabbitState {
           // 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,
@@ -1723,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,
@@ -1757,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,
@@ -2039,6 +2066,8 @@ export class RabbitState {
             // 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,
       },
@@ -2150,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.
@@ -2306,6 +2337,8 @@ export class RabbitState {
        * 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()];

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