let-them-talk 5.2.5 → 5.4.0

package/scripts/check-event-schema.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const schema = require(path.resolve(__dirname, '..', 'events', 'schema.js'));
+
+const EXPECTED_EVENT_ENVELOPE_FIELDS = [
+  'event_id',
+  'stream',
+  'branch_id',
+  'seq',
+  'type',
+  'occurred_at',
+  'schema_version',
+  'actor_agent',
+  'session_id',
+  'command_id',
+  'causation_id',
+  'correlation_id',
+  'payload',
+];
+
+const EXPECTED_RUNTIME_GLOBAL_FAMILIES = [
+  'agent',
+  'profile',
+  'lock',
+  'branch',
+  'migration',
+];
+
+const EXPECTED_BRANCH_LOCAL_FAMILIES = [
+  'session',
+  'conversation',
+  'message',
+  'task',
+  'workflow',
+  'workspace',
+  'decision',
+  'kb',
+  'review',
+  'dependency',
+  'vote',
+  'rule',
+  'progress',
+  'evidence',
+];
+
+const EXPECTED_EVENT_TYPES = [
+  'agent.registered',
+  'agent.unregistered',
+  'agent.status_updated',
+  'agent.heartbeat_recorded',
+  'agent.branch_assigned',
+  'agent.listening_updated',
+  'profile.updated',
+  'lock.acquired',
+  'lock.released',
+  'branch.created',
+  'migration.started',
+  'migration.completed',
+  'migration.failed',
+  'session.started',
+  'session.resumed',
+  'session.interrupted',
+  'session.completed',
+  'session.failed',
+  'session.abandoned',
+  'conversation.mode_updated',
+  'conversation.channel_joined',
+  'conversation.channel_left',
+  'conversation.manager_claimed',
+  'conversation.phase_updated',
+  'conversation.floor_yielded',
+  'message.sent',
+  'message.corrected',
+  'message.redacted',
+  'task.created',
+  'task.updated',
+  'task.claimed',
+  'task.completed',
+  'workflow.created',
+  'workflow.step_started',
+  'workflow.step_completed',
+  'workflow.step_reassigned',
+  'workflow.completed',
+  'workflow.paused',
+  'workflow.resumed',
+  'workflow.stopped',
+  'workspace.written',
+  'decision.logged',
+  'kb.written',
+  'review.requested',
+  'review.submitted',
+  'dependency.declared',
+  'dependency.resolved',
+  'vote.called',
+  'vote.cast',
+  'vote.resolved',
+  'rule.added',
+  'rule.toggled',
+  'rule.removed',
+  'progress.updated',
+  'evidence.recorded',
+];
+
+function fail(lines) {
+  console.error(lines.join('\n'));
+  process.exit(1);
+}
+
+function ensureIncludesAll(problems, actualValues, expectedValues, label) {
+  const actualSet = new Set(actualValues);
+  for (const expected of expectedValues) {
+    if (!actualSet.has(expected)) {
+      problems.push(`${label} is missing: ${expected}`);
+    }
+  }
+}
+
+function buildSampleEvent(type) {
+  const stream = schema.resolveTypeStream(type);
+  let payload = {};
+  if (type === 'message.sent') {
+    payload = {
+      message: {
+        id: 'msg_task3a_sample',
+        from: 'schema-alpha',
+        to: 'schema-beta',
+        content: 'schema sample message',
+        timestamp: '2026-04-15T00:00:00.000Z',
+      },
+    };
+  } else if (type === 'message.corrected') {
+    payload = {
+      message_id: 'msg_task3a_sample',
+      content: 'schema sample edit',
+      edited_at: '2026-04-15T00:01:00.000Z',
+      max_edit_history: 10,
+    };
+  } else if (type === 'message.redacted') {
+    payload = {
+      message_id: 'msg_task3a_sample',
+      redacted_at: '2026-04-15T00:02:00.000Z',
+    };
+  }
+
+  return {
+    event_id: 'evt_task3a_sample',
+    stream,
+    branch_id: stream === schema.EVENT_STREAMS.BRANCH ? 'main' : null,
+    seq: 1,
+    type,
+    occurred_at: '2026-04-15T00:00:00.000Z',
+    schema_version: schema.CANONICAL_EVENT_SCHEMA_VERSION,
+    actor_agent: 'task3a-validator',
+    session_id: stream === schema.EVENT_STREAMS.BRANCH ? 'session_task3a' : null,
+    command_id: 'cmd_task3a',
+    causation_id: null,
+    correlation_id: null,
+    payload,
+    extra_field_kept_for_future_replay: true,
+  };
+}
+
+function main() {
+  const problems = [];
+
+  ensureIncludesAll(
+    problems,
+    schema.REQUIRED_EVENT_ENVELOPE_FIELDS,
+    EXPECTED_EVENT_ENVELOPE_FIELDS,
+    'Required event envelope field'
+  );
+
+  if (schema.DEFAULT_COLLABORATION_STREAM !== schema.EVENT_STREAMS.BRANCH) {
+    problems.push('Collaboration event default stream must be branch.');
+  }
+
+  ensureIncludesAll(
+    problems,
+    schema.EVENT_SCOPE_SPLIT.runtimeGlobalFamilies,
+    EXPECTED_RUNTIME_GLOBAL_FAMILIES,
+    'Runtime-global family'
+  );
+
+  ensureIncludesAll(
+    problems,
+    schema.EVENT_SCOPE_SPLIT.branchLocalFamilies,
+    EXPECTED_BRANCH_LOCAL_FAMILIES,
+    'Branch-local family'
+  );
+
+  for (const family of EXPECTED_RUNTIME_GLOBAL_FAMILIES) {
+    const definition = schema.EVENT_FAMILY_REGISTRY[family];
+    if (!definition) {
+      problems.push(`Missing family registry entry: ${family}`);
+      continue;
+    }
+    if (definition.scope !== schema.EVENT_STREAMS.RUNTIME) {
+      problems.push(`Family ${family} must resolve to runtime scope.`);
+    }
+    if (!Array.isArray(definition.types) || definition.types.length === 0) {
+      problems.push(`Family ${family} must register at least one event type.`);
+    }
+  }
+
+  for (const family of EXPECTED_BRANCH_LOCAL_FAMILIES) {
+    const definition = schema.EVENT_FAMILY_REGISTRY[family];
+    if (!definition) {
+      problems.push(`Missing family registry entry: ${family}`);
+      continue;
+    }
+    if (definition.scope !== schema.EVENT_STREAMS.BRANCH) {
+      problems.push(`Family ${family} must resolve to branch scope.`);
+    }
+    if (!Array.isArray(definition.types) || definition.types.length === 0) {
+      problems.push(`Family ${family} must register at least one event type.`);
+    }
+  }
+
+  ensureIncludesAll(
+    problems,
+    Object.keys(schema.EVENT_TYPE_REGISTRY),
+    EXPECTED_EVENT_TYPES,
+    'Required canonical event type'
+  );
+
+  for (const type of EXPECTED_EVENT_TYPES) {
+    const definition = schema.EVENT_TYPE_REGISTRY[type];
+    if (!definition) continue;
+
+    const familyDefinition = schema.EVENT_FAMILY_REGISTRY[definition.family];
+    if (!familyDefinition) {
+      problems.push(`Event type ${type} points at unknown family ${definition.family}.`);
+      continue;
+    }
+
+    if (definition.scope !== familyDefinition.scope) {
+      problems.push(`Event type ${type} has scope ${definition.scope}, but family ${definition.family} is ${familyDefinition.scope}.`);
+    }
+
+    const validation = schema.validateCanonicalEvent(buildSampleEvent(type));
+    if (!validation.ok) {
+      problems.push(`Sample event for ${type} failed validation: ${validation.problems.join('; ')}`);
+    }
+  }
+
+  const invalidCorrectionValidation = schema.validateCanonicalEvent({
+    ...buildSampleEvent('message.corrected'),
+    payload: {
+      message_id: 'msg_task3a_sample',
+      content: 42,
+    },
+  });
+  if (invalidCorrectionValidation.ok || !invalidCorrectionValidation.problems.some((problem) => problem.includes('payload.content'))) {
+    problems.push('message.corrected payload validation must reject non-string payload.content values.');
+  }
+
+  if (problems.length > 0) {
+    fail([
+      'Canonical event schema validation failed.',
+      ...problems.map((problem) => `- ${problem}`),
+    ]);
+  }
+
+  console.log([
+    'Canonical event schema validation passed.',
+    `Envelope fields checked: ${EXPECTED_EVENT_ENVELOPE_FIELDS.length}`,
+    `Runtime-global families checked: ${EXPECTED_RUNTIME_GLOBAL_FAMILIES.length}`,
+    `Branch-local families checked: ${EXPECTED_BRANCH_LOCAL_FAMILIES.length}`,
+    `Seed event types checked: ${EXPECTED_EVENT_TYPES.length}`,
+    'Branch-local collaboration default: branch',
+  ].join('\n'));
+}
+
+main();

package/scripts/check-evidence-completion.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { createCanonicalEventLog } = require(path.resolve(__dirname, '..', 'events', 'log.js'));
+const { createCanonicalState, createBranchPathResolvers } = require(path.resolve(__dirname, '..', 'state', 'canonical.js'));
+
+const SERVER_FILE = path.resolve(__dirname, '..', 'server.js');
+
+function fail(lines, exitCode = 1) {
+  fs.writeSync(2, lines.join('\n') + '\n');
+  process.exit(exitCode);
+}
+
+function assert(condition, message, problems) {
+  if (!condition) problems.push(message);
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function extractBlock(source, startAnchor, endAnchor) {
+  const startIndex = source.indexOf(startAnchor);
+  if (startIndex === -1) return '';
+  const endIndex = endAnchor ? source.indexOf(endAnchor, startIndex + startAnchor.length) : source.length;
+  if (endIndex === -1) return source.slice(startIndex);
+  return source.slice(startIndex, endIndex);
+}
+
+function buildWorkflow(id, description) {
+  return {
+    id,
+    name: `Workflow ${id}`,
+    status: 'active',
+    created_by: 'alpha',
+    created_at: '2026-04-16T02:15:00.000Z',
+    updated_at: '2026-04-16T02:15:00.000Z',
+    steps: [
+      {
+        id: 1,
+        description,
+        assignee: 'alpha',
+        depends_on: [],
+        status: 'in_progress',
+        started_at: '2026-04-16T02:15:00.000Z',
+        completed_at: null,
+        notes: '',
+      },
+      {
+        id: 2,
+        description: `Follow-up for ${id}`,
+        assignee: 'beta',
+        depends_on: [1],
+        status: 'pending',
+        started_at: null,
+        completed_at: null,
+        notes: '',
+      },
+    ],
+  };
+}
+
+function buildTask(id, title) {
+  return {
+    id,
+    title,
+    description: `${title} description`,
+    status: 'pending',
+    assignee: 'alpha',
+    created_by: 'alpha',
+    created_at: '2026-04-16T02:15:00.000Z',
+    updated_at: '2026-04-16T02:15:00.000Z',
+    notes: [],
+  };
+}
+
+function main() {
+  const problems = [];
+  const serverSource = fs.readFileSync(SERVER_FILE, 'utf8');
+  const updateTaskBlock = extractBlock(serverSource, 'function toolUpdateTask(taskId, status, notes = null, evidence = null) {', 'function toolListTasks(status = null, assignee = null) {');
+  const advanceWorkflowBlock = extractBlock(serverSource, 'function toolAdvanceWorkflow(workflowId, notes, evidence = null) {', 'function toolWorkflowStatus(workflowId) {');
+  const verifyAndAdvanceBlock = extractBlock(serverSource, 'async function toolVerifyAndAdvance(params) {', 'function toolRetryWithImprovement(params) {');
+  const handoffBlock = extractBlock(serverSource, 'function emitWorkflowHandoffMessages(options = {}) {', '// --- Tool implementations ---');
+  const updateTaskSchemaBlock = extractBlock(serverSource, "name: 'update_task',", "name: 'list_tasks',");
+  const advanceWorkflowSchemaBlock = extractBlock(serverSource, "name: 'advance_workflow',", "name: 'workflow_status',");
+
+  assert(updateTaskBlock.includes('canonicalState.updateTaskStatus({'), 'toolUpdateTask() must route terminal completion through canonicalState.updateTaskStatus(...).', problems);
+  assert(advanceWorkflowBlock.includes('canonicalState.advanceWorkflow({'), 'toolAdvanceWorkflow() must route advancement through canonicalState.advanceWorkflow(...).', problems);
+  assert(verifyAndAdvanceBlock.includes('canonicalState.advanceWorkflow({'), 'toolVerifyAndAdvance() must route verified advancement through canonicalState.advanceWorkflow(...).', problems);
+  assert(!verifyAndAdvanceBlock.includes('currentStep.verification = {'), 'toolVerifyAndAdvance() must not write inline verification on the workflow step directly.', problems);
+  assert(handoffBlock.includes('evidence_ref: evidenceRef || null'), 'Workflow handoff messages must carry an evidence_ref field.', problems);
+  assert(handoffBlock.includes('session_id: currentSessionId || null'), 'Workflow handoff messages must carry a session_id field.', problems);
+  assert(handoffBlock.includes('canonicalState.appendMessage(msg, {'), 'Workflow handoff messages must use canonicalState.appendMessage(...) so canonical message metadata is preserved.', problems);
+  assert(updateTaskSchemaBlock.includes('evidence: COMPLETION_EVIDENCE_INPUT_SCHEMA'), 'update_task tool schema must expose the evidence input object for terminal transitions.', problems);
+  assert(advanceWorkflowSchemaBlock.includes('evidence: COMPLETION_EVIDENCE_INPUT_SCHEMA'), 'advance_workflow tool schema must expose the evidence input object.', problems);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'letthemtalk-evidence-completion-'));
+  const dataDir = path.join(tempRoot, '.agent-bridge');
+  const branchName = 'feature_task5b';
+  const branchPaths = createBranchPathResolvers(dataDir);
+  const canonicalState = createCanonicalState({ dataDir, processPid: 5150 });
+  const eventLog = createCanonicalEventLog({ dataDir });
+
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(branchPaths.getWorkflowsFile(branchName), JSON.stringify([
+      buildWorkflow('wf_verify_path', 'Verify and advance path'),
+      buildWorkflow('wf_manual_advance', 'Manual advance path'),
+      buildWorkflow('wf_missing_evidence', 'Evidence-less path should fail'),
+    ], null, 2));
+    fs.writeFileSync(branchPaths.getTasksFile(branchName), JSON.stringify([
+      buildTask('task_missing_evidence', 'Task without evidence'),
+      buildTask('task_evidence_backed', 'Task with evidence'),
+    ], null, 2));
+
+    const missingAdvance = canonicalState.advanceWorkflow({
+      workflowId: 'wf_missing_evidence',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: 'session_alpha',
+      sourceTool: 'advance_workflow',
+    });
+    assert(!!missingAdvance.error, 'advanceWorkflow() must reject evidence-less workflow advancement.', problems);
+
+    const verifyAdvance = canonicalState.advanceWorkflow({
+      workflowId: 'wf_verify_path',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: 'session_alpha',
+      commandId: 'cmd_verify',
+      correlationId: 'wf_verify_path',
+      expectedAssignee: 'alpha',
+      sourceTool: 'verify_and_advance',
+      evidence: {
+        summary: 'Implemented the first evidence-backed verify path',
+        verification: 'Ran the deterministic evidence validation fixture',
+        files_changed: ['agent-bridge/server.js', 'agent-bridge/state/canonical.js'],
+        confidence: 88,
+        learnings: 'Keep evidence authoritative and thin.',
+      },
+    });
+    assert(verifyAdvance.success, 'advanceWorkflow() should succeed for the verify_and_advance evidence path.', problems);
+    assert(verifyAdvance.evidence_ref && verifyAdvance.evidence_ref.branch_id === branchName, 'Verified advancement must return a branch-scoped evidence reference.', problems);
+
+    const manualAdvance = canonicalState.advanceWorkflow({
+      workflowId: 'wf_manual_advance',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: 'session_alpha',
+      commandId: 'cmd_manual',
+      correlationId: 'wf_manual_advance',
+      sourceTool: 'advance_workflow',
+      evidence: {
+        summary: 'Manually advanced the workflow with evidence',
+        verification: 'Checked step state and next-step activation',
+        files_changed: ['agent-bridge/state/evidence.js'],
+        confidence: 91,
+      },
+    });
+    assert(manualAdvance.success, 'advanceWorkflow() should succeed for the manual advance_workflow evidence path.', problems);
+    assert(Array.isArray(manualAdvance.next_steps) && manualAdvance.next_steps.length === 1, 'Manual workflow advancement should activate the next ready step.', problems);
+
+    const missingTaskEvidence = canonicalState.updateTaskStatus({
+      taskId: 'task_missing_evidence',
+      status: 'done',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: 'session_alpha',
+      sourceTool: 'update_task',
+    });
+    assert(!!missingTaskEvidence.error, 'updateTaskStatus() must reject evidence-less terminal task completion.', problems);
+
+    const taskCompletion = canonicalState.updateTaskStatus({
+      taskId: 'task_evidence_backed',
+      status: 'done',
+      actor: 'alpha',
+      branch: branchName,
+      sessionId: 'session_alpha',
+      commandId: 'cmd_task',
+      correlationId: 'task_evidence_backed',
+      sourceTool: 'update_task',
+      evidence: {
+        summary: 'Completed the task with canonical evidence',
+        verification: 'Validated task projection and event references',
+        files_changed: ['docs/architecture/runtime-contract.md'],
+        confidence: 93,
+      },
+    });
+    assert(taskCompletion.success, 'updateTaskStatus() should succeed for evidence-backed task completion.', problems);
+    assert(taskCompletion.evidence_ref && taskCompletion.evidence_ref.evidence_id, 'Task completion must return an evidence reference.', problems);
+
+    const evidenceFile = branchPaths.getEvidenceFile(branchName);
+    const mainEvidenceFile = branchPaths.getEvidenceFile('main');
+    const evidenceStore = readJson(evidenceFile);
+    const workflows = readJson(branchPaths.getWorkflowsFile(branchName));
+    const tasks = readJson(branchPaths.getTasksFile(branchName));
+    const branchEvents = eventLog.readBranchEvents(branchName);
+    const branchEventTypes = branchEvents.map((event) => event.type);
+    const verifyWorkflow = workflows.find((workflow) => workflow.id === 'wf_verify_path');
+    const manualWorkflow = workflows.find((workflow) => workflow.id === 'wf_manual_advance');
+    const completedTask = tasks.find((task) => task.id === 'task_evidence_backed');
+
+    assert(fs.existsSync(evidenceFile), 'Evidence-backed completions must materialize a branch-scoped evidence file.', problems);
+    assert(!fs.existsSync(mainEvidenceFile), 'Evidence recorded on a feature branch must not leak into the main-branch evidence file.', problems);
+    assert(Array.isArray(evidenceStore.records) && evidenceStore.records.length === 3, 'Evidence store should contain one record for verify_and_advance, one for advance_workflow, and one for task completion.', problems);
+    assert(evidenceStore.records.every((record) => record.recorded_by_session === 'session_alpha'), 'Evidence records must retain the originating session id.', problems);
+    assert(evidenceStore.records.some((record) => record.source_tool === 'verify_and_advance'), 'Evidence store must retain verify_and_advance provenance.', problems);
+    assert(evidenceStore.records.some((record) => record.source_tool === 'advance_workflow'), 'Evidence store must retain advance_workflow provenance.', problems);
+    assert(evidenceStore.records.some((record) => record.source_tool === 'update_task'), 'Evidence store must retain update_task provenance.', problems);
+
+    assert(verifyWorkflow.steps[0].status === 'done', 'Verified workflow step should be marked done.', problems);
+    assert(verifyWorkflow.steps[0].evidence_ref && verifyWorkflow.steps[0].evidence_ref.evidence_id === verifyAdvance.evidence_ref.evidence_id, 'Verified workflow step must reference its evidence record.', problems);
+    assert(verifyWorkflow.steps[1].status === 'in_progress', 'Verified workflow advancement should start the next pending step.', problems);
+    assert(manualWorkflow.steps[0].evidence_ref && manualWorkflow.steps[0].evidence_ref.evidence_id === manualAdvance.evidence_ref.evidence_id, 'Manual workflow advancement must reference its evidence record.', problems);
+    assert(completedTask.status === 'done', 'Evidence-backed task completion must mark the task done.', problems);
+    assert(completedTask.evidence_ref && completedTask.evidence_ref.evidence_id === taskCompletion.evidence_ref.evidence_id, 'Completed task must reference its evidence record.', problems);
+
+    assert(branchEventTypes.filter((type) => type === 'evidence.recorded').length === 3, 'Canonical branch events must record three evidence.recorded events for the successful targeted paths.', problems);
+    assert(branchEventTypes.includes('workflow.step_completed'), 'Canonical branch events must include workflow.step_completed for evidence-backed workflow advancement.', problems);
+    assert(branchEventTypes.includes('task.completed'), 'Canonical branch events must include task.completed for evidence-backed task completion.', problems);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+
+  if (problems.length > 0) {
+    fail(['Evidence-backed completion validation failed.', ...problems.map((problem) => `- ${problem}`)], 1);
+  }
+
+  console.log([
+    'Evidence-backed completion validation passed.',
+    'Validated canonical evidence storage by reference for verify_and_advance, advance_workflow, and terminal update_task flows.',
+    'Validated evidence-less terminal transitions fail closed and workflow handoffs keep evidence/session linkage in the server routing layer.',
+  ].join('\n'));
+}
+
+main();