@dotdrelle/wiki-manager 0.11.10 → 0.12.0

package/src/orchestrator/lockManager.js

@@ -0,0 +1,51 @@
+export function createLockManager({ locks = new Set() } = {}) {
+  return {
+    canAcquire(taskOrLocks) {
+      return locksFor(taskOrLocks).every((lock) => !locks.has(lock));
+    },
+    acquire(taskOrLocks) {
+      const lockNames = locksFor(taskOrLocks);
+      if (lockNames.some((lock) => locks.has(lock))) return null;
+      for (const lock of lockNames) locks.add(lock);
+      let released = false;
+      return {
+        locks: lockNames,
+        release() {
+          if (released) return;
+          released = true;
+          for (const lock of lockNames) locks.delete(lock);
+        },
+      };
+    },
+    release(taskOrLocks) {
+      for (const lock of locksFor(taskOrLocks)) locks.delete(lock);
+    },
+    clear() {
+      locks.clear();
+    },
+    snapshot() {
+      return [...locks].sort();
+    },
+  };
+}
+
+export function locksForTask(task) {
+  const locks = new Set();
+  const explicit = task?.locks ?? task?.writeLocks ?? null;
+  if (Array.isArray(explicit)) {
+    for (const lock of explicit) if (lock) locks.add(String(lock));
+  } else if (explicit && typeof explicit === 'object') {
+    if (explicit.workspaceWrite || explicit.workspace) locks.add('workspace:write');
+    for (const value of explicit.deliverableWrites ?? explicit.deliverables ?? []) locks.add(`deliverable:${value}`);
+    for (const value of explicit.wikiPageWrites ?? explicit.wikiPages ?? []) locks.add(`wiki-page:${value}`);
+  }
+  for (const value of task?.deliverableWrites ?? []) locks.add(`deliverable:${value}`);
+  for (const value of task?.wikiPageWrites ?? []) locks.add(`wiki-page:${value}`);
+  if (task?.workspaceWrite) locks.add('workspace:write');
+  return [...locks].sort();
+}
+
+function locksFor(taskOrLocks) {
+  if (Array.isArray(taskOrLocks)) return [...new Set(taskOrLocks.map(String).filter(Boolean))].sort();
+  return locksForTask(taskOrLocks);
+}

package/src/orchestrator/planIntegrator.js

@@ -0,0 +1,268 @@
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { readyPlanTasks } from '../core/planPatch.js';
+import { applyApprovalCoverage } from './approvalPolicy.js';
+import { isValidatedFragment, validateFragment } from './planValidator.js';
+
+const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'error', 'complete', 'completed', 'success']);
+
+export function integrate(runId, fragment, {
+  registry,
+  budgets = {},
+  session = null,
+  store = null,
+  workspace = null,
+  insertBeforeTasks = [],
+  insertAfterTasks = [],
+  approvals = null,
+  enforceApprovalCoverage = false,
+  now = () => new Date(),
+} = {}) {
+  if (!runId) throw new Error('integrate requires runId.');
+  const received = emitPlanEvent('plan.received', { runId, session, store, workspace, now, payload: { runId, fragment } });
+  const validation = isValidatedFragment(fragment)
+    ? { ok: true, errors: [], normalizedFragment: fragment }
+    : validateFragment(fragment, { registry, run: { plannerAgentInstanceId: fragment?.agentInstanceId }, budgets });
+
+  if (!validation.ok) {
+    emitPlanEvent('plan.rejected', {
+      runId,
+      session,
+      store,
+      workspace,
+      now,
+      payload: { runId, receivedEventId: received.id, errors: validation.errors },
+    });
+    return { ok: false, errors: validation.errors, planRevision: currentRevision(session), readyTasks: [] };
+  }
+
+  const normalizedFragment = validation.normalizedFragment;
+  const currentPlan = clonePlan(session?.headlessPlan ?? session?.agentProjection?.plan ?? []);
+  const current = new Map(currentPlan.map((task) => [String(task.id ?? task.step), task]));
+  const beforeIds = stringifyList(insertBeforeTasks);
+  const afterIds = stringifyList(insertAfterTasks);
+  const terminalViolation = firstTerminalMutation(current, beforeIds, afterIds);
+  if (terminalViolation) {
+    const errors = [{ code: 'terminal_task_mutation', message: `Cannot modify terminal task: ${terminalViolation}`, details: { taskId: terminalViolation } }];
+    emitPlanEvent('plan.rejected', {
+      runId,
+      session,
+      store,
+      workspace,
+      now,
+      payload: { runId, receivedEventId: received.id, errors },
+    });
+    return { ok: false, errors, planRevision: currentRevision(session), readyTasks: [] };
+  }
+
+  const globalized = globalizeFragment(runId, normalizedFragment, current);
+  const integrated = mergePlan(currentPlan, globalized.tasks, { insertBeforeTasks: beforeIds, insertAfterTasks: afterIds });
+  const planRevision = currentRevision(session) + 1;
+  const approvalRequests = applyApprovalCoverage(integrated.plan, {
+    runId,
+    workspaceId: workspace ?? session?.workspace ?? null,
+    planRevision,
+    approvals: approvals ?? approvalList(session),
+  });
+
+  emitPlanEvent('plan.validated', {
+    runId,
+    session,
+    store,
+    workspace,
+    now,
+    payload: { runId, receivedEventId: received.id, fragment: normalizedFragment },
+  });
+  for (const group of globalized.groups) {
+    emitPlanEvent('task_group.created', {
+      runId,
+      session,
+      store,
+      workspace,
+      now,
+      payload: { runId, group },
+    });
+  }
+  for (const task of integrated.createdTasks) {
+    emitPlanEvent('task.created', {
+      runId,
+      taskId: task.id,
+      session,
+      store,
+      workspace,
+      now,
+      payload: { runId, task },
+    });
+  }
+  emitPlanEvent('plan.revision_changed', {
+    runId,
+    session,
+    store,
+    workspace,
+    now,
+    payload: {
+      runId,
+      planRevision,
+      previousRevision: planRevision - 1,
+      taskIds: integrated.plan.map((task) => task.id),
+      tasks: integrated.plan,
+    },
+  });
+  for (const request of approvalRequests) {
+    emitPlanEvent('approval.requested', {
+      runId,
+      taskId: request.taskId,
+      session,
+      store,
+      workspace,
+      now,
+      payload: request,
+    });
+  }
+
+  const readyTasks = readyPlanTasks(integrated.plan);
+  return {
+    ok: true,
+    errors: [],
+    normalizedFragment,
+    planRevision,
+    plan: integrated.plan,
+    createdTasks: integrated.createdTasks,
+    readyTasks,
+  };
+}
+
+function emitPlanEvent(type, { runId, taskId = null, session, store, workspace, now, payload }) {
+  const event = createAgentEvent(type, {
+    origin: 'plan_integrator',
+    runId,
+    taskId,
+    workspace,
+    payload,
+  });
+  event.ts = now().toISOString();
+  const dispatched = session ? dispatchAgentEvent(session, event) : event;
+  store?.persistEvent?.(dispatched);
+  return dispatched;
+}
+
+function globalizeFragment(runId, fragment, current) {
+  const usedIds = new Set([
+    ...current.keys(),
+    ...[...current.values()].map((task) => task.groupId).filter(Boolean),
+  ]);
+  const idMap = new Map();
+  const groups = fragment.groups.map((group) => {
+    const globalId = uniqueGlobalId(runId, group.id, usedIds);
+    idMap.set(group.id, globalId);
+    return { ...group, id: globalId, localId: group.id };
+  });
+  const tasks = fragment.tasks.map((task) => {
+    const globalId = uniqueGlobalId(runId, task.id, usedIds);
+    idMap.set(task.id, globalId);
+    return {
+      ...task,
+      id: globalId,
+      localId: task.id,
+      description: task.description ?? task.label,
+      status: task.status ?? 'pending',
+    };
+  });
+  for (const task of tasks) {
+    task.dependsOn = task.dependsOn.map((dep) => idMap.get(dep) ?? dep);
+    if (task.groupId != null) task.groupId = idMap.get(task.groupId) ?? task.groupId;
+    if (task.dependsOnGroup != null) task.dependsOnGroup = idMap.get(task.dependsOnGroup) ?? task.dependsOnGroup;
+  }
+  return { groups, tasks };
+}
+
+function mergePlan(currentPlan, newTasks, { insertBeforeTasks, insertAfterTasks }) {
+  const plan = clonePlan(currentPlan);
+  const createdTasks = clonePlan(newTasks);
+  const newTaskIds = new Set(createdTasks.map((task) => task.id));
+  const roots = createdTasks.filter((task) => task.dependsOn.length === 0).map((task) => task.id);
+  const leaves = createdTasks
+    .filter((task) => !createdTasks.some((candidate) => candidate.dependsOn.includes(task.id)))
+    .map((task) => task.id);
+
+  if (insertBeforeTasks.length > 0) {
+    const beforeSet = new Set(insertBeforeTasks);
+    for (const target of plan.filter((task) => beforeSet.has(task.id))) {
+      const previousDeps = [...(target.dependsOn ?? [])];
+      for (const task of createdTasks) {
+        if (roots.includes(task.id)) task.dependsOn = uniqueStrings([...task.dependsOn, ...previousDeps]);
+      }
+      target.dependsOn = uniqueStrings([...leaves]);
+    }
+  }
+
+  if (insertAfterTasks.length > 0) {
+    const afterSet = new Set(insertAfterTasks);
+    for (const task of createdTasks) {
+      if (roots.includes(task.id)) task.dependsOn = uniqueStrings([...task.dependsOn, ...afterSet]);
+    }
+    for (const existing of plan) {
+      if (!Array.isArray(existing.dependsOn)) existing.dependsOn = [];
+      const touched = existing.dependsOn.some((dep) => afterSet.has(dep));
+      if (!touched || newTaskIds.has(existing.id)) continue;
+      existing.dependsOn = uniqueStrings(existing.dependsOn.flatMap((dep) => (afterSet.has(dep) ? leaves : [dep])));
+    }
+  }
+
+  const next = [...plan, ...createdTasks].map((task, index) => ({
+    ...task,
+    step: index + 1,
+    dependsOn: uniqueStrings(task.dependsOn ?? []),
+  }));
+  return { plan: next, createdTasks };
+}
+
+function firstTerminalMutation(current, beforeIds, afterIds) {
+  for (const id of beforeIds) {
+    if (isTerminal(current.get(id))) return id;
+  }
+  for (const id of afterIds) {
+    const dependents = [...current.values()].filter((task) => (task.dependsOn ?? []).includes(id));
+    const terminal = dependents.find(isTerminal);
+    if (terminal) return terminal.id;
+  }
+  return null;
+}
+
+function approvalList(session) {
+  const projectionApprovals = session?.agentProjection?.approvals;
+  if (Array.isArray(projectionApprovals) && projectionApprovals.length > 0) return projectionApprovals;
+  return Array.isArray(session?.approvals) ? session.approvals : [];
+}
+
+function uniqueGlobalId(runId, localId, usedIds) {
+  const base = `${runId}:${localId}`;
+  if (!usedIds.has(base)) {
+    usedIds.add(base);
+    return base;
+  }
+  let suffix = 2;
+  while (usedIds.has(`${base}-${suffix}`)) suffix += 1;
+  const id = `${base}-${suffix}`;
+  usedIds.add(id);
+  return id;
+}
+
+function currentRevision(session) {
+  return Number.isInteger(session?.planRevision) && session.planRevision >= 0 ? session.planRevision : 0;
+}
+
+function isTerminal(task) {
+  return TERMINAL_STATUSES.has(String(task?.status ?? '').toLowerCase());
+}
+
+function stringifyList(value) {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.map(String).filter(Boolean))];
+}
+
+function clonePlan(plan) {
+  return Array.isArray(plan) ? plan.map((task) => ({ ...task, dependsOn: [...(task.dependsOn ?? [])] })) : [];
+}

package/src/orchestrator/planIntegrator.test.js

@@ -0,0 +1,213 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { openRuntimeStore } from '../runtime/store.js';
+import { integrate } from './planIntegrator.js';
+
+function registry() {
+  return {
+    providersFor(capability) {
+      if (capability !== 'knowledge.update') return [];
+      return [{
+        agentInstanceId: 'production-main',
+        health: 'available',
+        capability: {
+          id: 'knowledge.update',
+          version: '1',
+          description: 'Knowledge update',
+          inputSchema: {
+            type: 'object',
+            required: ['inputs'],
+            additionalProperties: true,
+            properties: {
+              inputs: { type: 'array', items: { type: 'string' } },
+            },
+          },
+          outputSchema: {},
+          supportedOperations: ['ingest'],
+          mutationClass: 'workspace',
+          defaultRequiresApproval: true,
+        },
+        description: { contractVersion: '1' },
+      }];
+    },
+    isCompatible(contractVersion) {
+      return String(contractVersion) === '1';
+    },
+  };
+}
+
+function fragment(tasks = [task('ingest-a')]) {
+  return {
+    contractVersion: '1',
+    agentInstanceId: 'production-main',
+    capability: 'knowledge.update',
+    summary: {
+      label: 'Update knowledge',
+      initialSynthesis: ['Ingest sources.'],
+      estimatedTasks: tasks.length,
+    },
+    groups: [{
+      id: 'ingest',
+      label: 'Ingest sources',
+      recommendedConcurrency: 2,
+      progressWeight: tasks.length,
+    }],
+    tasks,
+    expectedOutputs: [{ type: 'directory', ref: 'wiki' }],
+  };
+}
+
+function task(id, dependsOn = []) {
+  return {
+    id,
+    label: `Task ${id}`,
+    requiredCapability: 'knowledge.update',
+    operation: 'ingest',
+    arguments: { inputs: [`raw/untracked/${id}.md`] },
+    groupId: 'ingest',
+    dependsOn,
+    parallelizable: true,
+    inputRefs: [{ type: 'file', ref: `raw/untracked/${id}.md` }],
+    expectedOutputRefs: [{ type: 'file', ref: `.wiki/ingest-plans/${id}.json` }],
+    locks: ['workspace-write'],
+    requiresApproval: true,
+    idempotencyKey: `idem-${id}`,
+    progressWeight: 1,
+  };
+}
+
+function storeAndSession() {
+  const store = openRuntimeStore({ stateDir: mkdtempSync(join(tmpdir(), 'wiki-manager-plan-integrator-')) });
+  const session = { activities: {}, headlessPlan: null };
+  return { store, session };
+}
+
+test('planIntegrator integrates an initial fragment, persists DAG tables and emits events', () => {
+  const { store, session } = storeAndSession();
+  const result = integrate('run-1', fragment(), {
+    registry: registry(),
+    session,
+    store,
+    workspace: 'docs',
+    now: () => new Date('2026-07-07T10:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.planRevision, 1);
+  assert.deepEqual(session.headlessPlan.map((item) => item.id), ['run-1:ingest-a']);
+  assert.deepEqual(result.readyTasks.map((item) => item.id), []);
+  assert.deepEqual(session.agentEvents.map((event) => event.type), [
+    'plan.received',
+    'plan.validated',
+    'task_group.created',
+    'task.created',
+    'plan.revision_changed',
+    'approval.requested',
+  ]);
+  assert.equal(store.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'tasks'").get().name, 'tasks');
+  assert.equal(store.listTasks({ runId: 'run-1' })[0].id, 'run-1:ingest-a');
+  assert.equal(store.listTasks({ runId: 'run-1' })[0].status, 'waiting_approval');
+  assert.equal(store.listApprovalGrants({ runId: 'run-1' })[0].status, 'pending_approval');
+  assert.equal(store.listTaskDependencies({ runId: 'run-1' }).length, 0);
+  assert.equal(store.listPlanRevisions({ runId: 'run-1' })[0].revision, 1);
+  store.close();
+});
+
+test('planIntegrator inserts before a task and rewires its dependencies', () => {
+  const { store, session } = storeAndSession();
+  integrate('run-2', fragment([task('a'), task('b', ['a'])]), { registry: registry(), session, store, workspace: 'docs' });
+
+  const result = integrate('run-2', fragment([task('x')]), {
+    registry: registry(),
+    session,
+    store,
+    workspace: 'docs',
+    insertBeforeTasks: ['run-2:b'],
+  });
+
+  assert.equal(result.ok, true);
+  const plan = Object.fromEntries(session.headlessPlan.map((item) => [item.id, item]));
+  assert.deepEqual(plan['run-2:x'].dependsOn, ['run-2:a']);
+  assert.deepEqual(plan['run-2:b'].dependsOn, ['run-2:x']);
+  assert.ok(store.listTaskDependencies({ runId: 'run-2' }).some((dep) => dep.taskId === 'run-2:b' && dep.dependsOnTaskId === 'run-2:x'));
+  assert.equal(session.planRevision, 2);
+  store.close();
+});
+
+test('planIntegrator inserts after a task and rewires existing dependents', () => {
+  const { store, session } = storeAndSession();
+  integrate('run-3', fragment([task('a'), task('b', ['a'])]), { registry: registry(), session, store, workspace: 'docs' });
+
+  const result = integrate('run-3', fragment([task('x')]), {
+    registry: registry(),
+    session,
+    store,
+    workspace: 'docs',
+    insertAfterTasks: ['run-3:a'],
+  });
+
+  assert.equal(result.ok, true);
+  const plan = Object.fromEntries(session.headlessPlan.map((item) => [item.id, item]));
+  assert.deepEqual(plan['run-3:x'].dependsOn, ['run-3:a']);
+  assert.deepEqual(plan['run-3:b'].dependsOn, ['run-3:x']);
+  store.close();
+});
+
+test('planIntegrator resolves global id collisions', () => {
+  const { store, session } = storeAndSession();
+  integrate('run-4', fragment([task('a')]), { registry: registry(), session, store, workspace: 'docs' });
+  const result = integrate('run-4', fragment([task('a')]), { registry: registry(), session, store, workspace: 'docs' });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(session.headlessPlan.map((item) => item.id), ['run-4:a', 'run-4:a-2']);
+  assert.deepEqual(store.listTasks({ runId: 'run-4' }).map((item) => item.id), ['run-4:a', 'run-4:a-2']);
+  store.close();
+});
+
+test('planIntegrator rejects insertions that would modify a terminal task', () => {
+  const { store, session } = storeAndSession();
+  integrate('run-5', fragment([task('a')]), { registry: registry(), session, store, workspace: 'docs' });
+  dispatchAgentEvent(session, createAgentEvent('plan_step_updated', {
+    origin: 'test',
+    runId: 'run-5',
+    workspace: 'docs',
+    taskId: 'run-5:a',
+    payload: { taskId: 'run-5:a', status: 'done' },
+  }));
+
+  const result = integrate('run-5', fragment([task('x')]), {
+    registry: registry(),
+    session,
+    store,
+    workspace: 'docs',
+    insertBeforeTasks: ['run-5:a'],
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.errors[0].code, 'terminal_task_mutation');
+  assert.equal(session.headlessPlan.length, 1);
+  assert.equal(session.agentEvents.at(-1).type, 'plan.rejected');
+  store.close();
+});
+
+test('planIntegrator replay reconstructs the same DAG projection', () => {
+  const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-plan-integrator-'));
+  const store = openRuntimeStore({ stateDir });
+  const session = { activities: {}, headlessPlan: null };
+  integrate('run-6', fragment([task('a'), task('b', ['a'])]), { registry: registry(), session, store, workspace: 'docs' });
+  const originalPlan = session.headlessPlan.map(({ id, dependsOn, status }) => ({ id, dependsOn, status }));
+  store.close();
+
+  const reopened = openRuntimeStore({ stateDir });
+  const replayed = { activities: {}, headlessPlan: null };
+  reopened.hydrateSession(replayed, { workspace: 'docs' });
+  assert.deepEqual(
+    replayed.headlessPlan.map(({ id, dependsOn, status }) => ({ id, dependsOn, status })),
+    originalPlan,
+  );
+  reopened.close();
+});