futura-scion 0.2.9 → 0.3.0

package/README.md

@@ -946,6 +946,18 @@ persistent world" doctrine FS already holds, taken further:
   its node; a new problem shape ≥ 0.5 Jaccard-similar to an accepted
   ancestor becomes its descendant. The codebase's evolution is navigable.
 
+- **Swarm auto-decomposition** (`src/kernel/auto-decompose.js`): a task
+  enqueued with `kind: 'decompose', payload: { large: true }` opens a
+  delegation run under a manager template and enqueues its declared
+  `subtasks` (plain objectives or `{ text, file }` targets) as child tasks —
+  chained sequentially by default, independent on request. Every child's
+  gate verdict ROLLS UP to its delegation node: accepted children advance
+  the tree; gate-failed or escalated children reject it. Fire-and-forget
+  parents complete on enqueue; awaiting parents escalate with the run id
+  so the reviewer reads the tree (`scion decompose tree <run>`). Verified
+  end-to-end: two file-targeted children patched two files through real
+  `node --check` oracles and rolled up `accepted, accepted`.
+
 - **Operational hygiene** (`src/kernel/ops.js`, `scion ops`): per-task
   scratch dirs reclaimed EVENT-DRIVEN at terminal status (containment-
   guarded), and peak/off-peak concurrency windows (`ops.peak_windows`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "The fused scion of cortex-os-agent + persona: one zero-LLM-dependent agent stack — Mind proposes, Muscle executes, Gate disposes.",
   "type": "module",
   "main": "src/index.js",

package/src/kernel/auto-decompose.js

@@ -0,0 +1,172 @@
+/**
+ * kernel/auto-decompose.js — SWARM AUTO-DECOMPOSITION (EvoX Genesis
+ * lineage, wired into runSwarm).
+ *
+ * The gap: decompose.js provides the delegation spine, but nothing AUTOMATIC
+ * routed large objectives into it. Here the swarm itself gains the Genesis
+ * behavior: a task flagged `large: true` (explicit, never inferred — the
+ * doctrine demands declared knobs) opens a delegation run under a MANAGER
+ * template; the decomposition plan (declared `subtasks` in the payload —
+ * the plan is data) enqueues CHILD TASKS on the same queue; every child's
+ * gate verdict ROLLS UP to its delegation node; the parent task completes
+ * only when all children are accepted.
+ *
+ * Rollup is the acceptance machinery: a child that gate-fails or escalates
+ * marks its node rejected, and the parent — visible to the reviewer through
+ * the delegation tree — carries the failure upward instead of completing.
+ * Transient agents, persistent world, only accepted results advance.
+ *
+ *   maybeAutoDecompose(task, opts)   → { run, parent, children } | null
+ *   rollupChild(nodeId, childResult) → { run, allAccepted, accepted, total }
+ *   runDecompositionTask(task, opts) → the swarm's handler for kind 'decompose'
+ *
+ * @module kernel/auto-decompose
+ */
+
+'use strict';
+
+import * as queue from './queue.js';
+import * as decompose from './decompose.js';
+import { getDb } from '../brain/db.js';
+import { journal as trailJournal } from './trail.js';
+import { get as getConfig } from '../config.js';
+
+/** The manager template used when a task doesn't name one (shipped default). */
+export function managerTemplateFor(task) {
+  return task?.payload?.manager_template
+    ?? (() => { try { return getConfig()?.decomposition?.manager_template; } catch { return undefined; } })()
+    ?? 'constructor';
+}
+
+function rowOf(nodeId) {
+  return getDb().prepare('SELECT * FROM delegations WHERE node_id = ?').get(nodeId);
+}
+
+function flatten(tree) {
+  const out = [];
+  const walk = (n) => { out.push(n); for (const c of n.children) walk(c); };
+  for (const r of tree.roots) walk(r);
+  return out;
+}
+
+/**
+ * Open a delegation run for a large task and enqueue its children.
+ * The decomposition plan comes from the task payload: `subtasks: [objective,
+ * ...]` (declared by the caller/enqueuer — the plan is data). Children
+ * enqueue onto the SAME queue (the swarm's existing workers drain them)
+ * with `delegation_node` stamped into their payloads for rollup.
+ *
+ * @returns {{ run, parent, children: Array<{ node, task }>} | null}
+ *   null when the task is not flagged large.
+ */
+export function maybeAutoDecompose(task, opts = {}) {
+  if (!task?.payload?.large) return null; // explicit flag only — never inferred
+  const managerTemplate = opts.managerTemplate ?? managerTemplateFor(task);
+  const subtasks = Array.isArray(task.payload.subtasks) && task.payload.subtasks.length > 0
+    ? task.payload.subtasks
+    : [String(task.payload.text ?? task.id)]; // single-leaf fallback: the objective itself
+
+  const root = decompose.decompose({
+    text: String(task.payload.text ?? task.id),
+    rootTemplate: managerTemplate,
+    repo: task.payload.repo ?? process.cwd(),
+  });
+
+  const children = [];
+  let prevTaskId = null;
+  for (const sub of subtasks) {
+    // A subtask is either a plain string objective or a declared object
+    // { text, file? } — a file-targeted child lets the analyzer rung derive
+    // a concrete patch; a text-only child researches and escalates.
+    const objective = typeof sub === 'string' ? { text: sub } : sub;
+    const node = decompose.delegate(root, opts.childTemplate ?? 'verifier', String(objective.text), {
+      repo: task.payload.repo ?? process.cwd(),
+      // Children work the PRIMARY repo — foreign writes stay root-only.
+    });
+    const t = queue.enqueue({
+      kind: task.payload.child_kind ?? 'fix',
+      payload: {
+        text: objective.text,
+        ...(objective.file ? { file: objective.file } : {}),
+        // File-targeted children get the analyzer's fresh-truth path; the
+        // earned-research rung would burn web budget on a subtask the tree
+        // already scopes. Text-only children keep research (opt-out is the
+        // operator's call, declared per task via payload.child_research).
+        ...(objective.file && task.payload.child_research !== true ? { research: false } : {}),
+        delegation_node: node.id,
+        delegation_run: root.id,
+        parent_task: task.id,
+      },
+      // Children chain sequentially by default (Genesis: writes to one repo
+      // are a manager's job, one at a time); `sequential: false` trusts the
+      // caller's declaration of independent subtasks.
+      ...(prevTaskId && task.payload.sequential !== false ? { depends_on: [prevTaskId] } : {}),
+      ...(task.payload.child_capabilities ? { capabilities: task.payload.child_capabilities } : {}),
+    });
+    children.push({ node, task: t });
+    prevTaskId = t.id;
+  }
+  trailJournal('autodecompose.opened', {
+    task: task.id, run: root.id, manager: managerTemplate,
+    children: children.length, sequential: task.payload.sequential !== false,
+  });
+  return { run: root.id, parent: root, children };
+}
+
+/**
+ * Roll a child's terminal verdict up to its delegation node.
+ * @param {string} nodeId — the child's delegation_node
+ * @param {{ ok: boolean, rung?: string, error?: string }} childResult
+ * @returns {{ run, allAccepted: boolean, accepted: number, total: number }}
+ */
+export function rollupChild(nodeId, childResult) {
+  const row = rowOf(nodeId);
+  if (!row) throw new Error(`auto-decompose.rollup: unknown delegation node ${JSON.stringify(nodeId)}`);
+  const accepted = childResult?.ok === true;
+  decompose.completeDelegation(nodeId, {
+    ok: accepted,
+    ...(childResult?.error ? { error: String(childResult.error).slice(0, 300) } : {}),
+    ...(childResult?.rung ? { rung: childResult.rung } : {}),
+  });
+  const tree = decompose.delegationTree(row.task_id);
+  const nodes = flatten(tree);
+  const childNodes = nodes.filter(n => n.status !== 'root');
+  const acceptedCount = childNodes.filter(n => n.status === 'accepted').length;
+  const allAccepted = childNodes.length > 0 && acceptedCount === childNodes.length;
+  trailJournal('autodecompose.rollup', { node: nodeId, ok: accepted, accepted: acceptedCount, total: childNodes.length, allAccepted });
+  return { run: row.task_id, allAccepted, accepted: acceptedCount, total: childNodes.length };
+}
+
+/** Whether every child of a run is terminal (accepted/rejected/closed). */
+export function runComplete(runId) {
+  const nodes = flatten(decompose.delegationTree(runId)).filter(n => n.status !== 'root');
+  return nodes.length > 0 && nodes.every(n => n.status !== 'pending');
+}
+
+/**
+ * The swarm's handler for a `decompose` task: open the run, enqueue
+ * children, and park THIS task on the children's completion — the parent
+ * task's own lifecycle closes when the last child rolls up. Implemented as:
+ * enqueue children with depends_on the parent is released by; the parent
+ * fails-soft as 'awaiting-children' (an escalation-shaped verdict so the
+ * review lane can see the tree) OR, when opts.awaitParent is false, the
+ * parent completes immediately after enqueueing (fire-and-forget mode).
+ */
+export async function runDecompositionTask(task, opts = {}) {
+  const opened = maybeAutoDecompose(task, opts);
+  if (!opened) {
+    // Flagged decompose but not large: loud misconfiguration.
+    throw new Error(`auto-decompose: task ${task.id} has kind 'decompose' but payload.large is not set — the trigger is explicit, never inferred`);
+  }
+  // awaitParent is the TASK's declaration first (payload.awaitParent), with
+  // the caller's opts as the operator override. Fire-and-forget: the parent
+  // completes when the children are enqueued — the delegation tree carries
+  // the outcomes, and the reviewer reads it (scion decompose tree).
+  const awaitParent = task.payload?.awaitParent ?? opts.awaitParent ?? true;
+  if (awaitParent === false) {
+    return { ok: true, rung: 'decompose', decision: { rung: 'decompose', candidate: { description: `delegated ${opened.children.length} subtask(s)`, run: opened.run } } };
+  }
+  // Default: the parent waits — fail-soft with the run visible in the tree.
+  const failResult = queue.fail(task.id, `awaiting children of run ${opened.run} (see: scion decompose tree ${opened.run})`, { escalate: true });
+  return { ok: false, escalated: true, rung: 'decompose', awaitingRun: opened.run, ...failResult };
+}

package/src/swarm.js

@@ -14,13 +14,14 @@ import * as queue from './kernel/queue.js';
 import * as roles from './kernel/roles.js';
 import * as trail from './kernel/trail.js';
 import { runTask } from './worker.js';
+import { runDecompositionTask, rollupChild } from './kernel/auto-decompose.js';
 
 /**
  * Run workers until the queue drains (or bounds stop progress).
  * @param {object} opts — { workers, verifyFn, applyCandidate, ladder }
  * @returns {{ completed, failed, escalated }}
  */
-export async function runSwarm({ workers = 3, verifyFn, applyCandidate, ladder: ladderOpts } = {}) {
+export async function runSwarm({ workers = 3, verifyFn, verifiers, applyCandidate, ladder: ladderOpts, decompose: decomposeOpts } = {}) {
   const results = { completed: 0, failed: 0, escalated: 0 };
 
   // Capability routing: swarm workers claim as a REGISTERED generalist role
@@ -32,11 +33,16 @@ export async function runSwarm({ workers = 3, verifyFn, applyCandidate, ladder:
     roles.registerRole({ id: 'swarm-generalist', capabilities: ['*'] });
   }
 
+  // Forward EVERYTHING the worker path needs — verifiers especially: they
+  // were silently dropped here once, and the Gate then refused every
+  // candidate with 'verifier-required' (a confusing diagnosis for the caller).
+  const workerOpts = { verifyFn, verifiers, applyCandidate, ladder: ladderOpts, decompose: decomposeOpts };
+
   await Promise.all(
     Array.from({ length: workers }, (_, i) => {
       const workerId = `w${i + 1}`;
       roles.bindWorker(workerId, 'swarm-generalist');
-      return workerLoop(workerId, { verifyFn, applyCandidate, ladder: ladderOpts }, results)
+      return workerLoop(workerId, workerOpts, results)
         .finally(() => roles.unbindWorker(workerId));
     }),
   );
@@ -49,9 +55,38 @@ async function workerLoop(workerId, opts, results) {
   for (;;) {
     const task = queue.claim(workerId);
     if (!task) return; // queue drained — survivor exits cleanly
-    const r = await runTask(task, opts);
+    const r = await runOne(task, opts);
     if (r.ok) results.completed += 1;
     else if (r.status === 'escalated') results.escalated += 1;
     else results.failed += 1;
   }
 }
+
+/** One task, routed: decompose tasks open delegation runs; ordinary tasks
+ *  run the ladder, and any child carrying a delegation_node rolls its
+ *  gate verdict up to the tree (Genesis: only accepted results advance). */
+async function runOne(task, opts) {
+  if (task.kind === 'decompose') {
+    const r = await runDecompositionTask(task, opts.decompose ?? {});
+    // Fire-and-forget parents COMPLETE on enqueue (the tree carries the
+    // outcomes); the claimed row must not be left dangling. The awaiting
+    // mode escalates via queue.fail inside the handler — no complete here.
+    if (r.ok) queue.complete(task.id, { rung: 'decompose', run: r.decision?.candidate?.run });
+    return { ...r, status: r.escalated ? 'escalated' : undefined };
+  }
+  const r = await runTask(task, opts);
+  // ROLLUP: a child of a decomposition run reports to its node — the run's
+  // parent then reflects accepted/rejected in the delegation tree.
+  if (task.payload?.delegation_node) {
+    try {
+      r.rollup = rollupChild(task.payload.delegation_node, {
+        ok: r.ok, rung: r.rung,
+        ...(r.error ? { error: r.error } : {}),
+      });
+      trail.journal('swarm.child-rollup', { task: task.id, node: task.payload.delegation_node, ok: r.ok, allAccepted: r.rollup.allAccepted });
+    } catch (err) {
+      trail.journal('swarm.rollup-error', { task: task.id, error: String(err?.message || err).slice(0, 160) });
+    }
+  }
+  return r;
+}