@quolu/lattice 0.58.0 → 0.58.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.58.0",
+  "version": "0.58.2",
   "description": "Schedulability compiler for multi-agent development: observe real code boundaries, refactor the conflicting seam, recompile the plan for parallel execution",
   "author": {
     "name": "Quo / クオ at kitepon.dev",

package/src/todo-cli.mjs

@@ -77,8 +77,7 @@ import {
   explainTodoStructureRealization,
   explainTodoStructureSet,
 } from './todo-structure-contracts.mjs';
-import { collectTodoStructureSourceEvidence } from './todo-structure-source-adapter.mjs';
-import { collectTodoStructureGitProvenance } from './todo-structure-git-adapter.mjs';
+import { collectTodoStructureAuthoritativeObservation } from './todo-structure-authoritative-observation.mjs';
 import { compileTodoStructureOverlay } from './todo-structure-overlay.mjs';
 import {
   buildTodoStructureCompileArtifact,
@@ -2024,8 +2023,9 @@ async function structureCompile({ repoRoot, env, planKey, inputRef }) {
     });
   }
   const actor = mutationActor(env);
-  const sourceEvidence = await collectTodoStructureSourceEvidence({ cwd: repoRoot, structureSet });
-  const gitProvenance = collectTodoStructureGitProvenance({ repoRoot, structureSet });
+  const observation = await collectTodoStructureAuthoritativeObservation({ repoRoot, structureSet });
+  const sourceEvidence = observation.source_evidence;
+  const gitProvenance = observation.git_provenance;
   const realizations = [];
   for (const task of structureSet.tasks.filter(({ applicability }) => applicability === 'graph')) {
     realizations.push(...await readTodoStructureRealizationChain({
@@ -2035,10 +2035,7 @@ async function structureCompile({ repoRoot, env, planKey, inputRef }) {
   const overlay = compileTodoStructureOverlay({
     structureSet,
     topology: mergedTopology(store),
-    taskStates: structureSet.tasks.map(({ task_id: taskId }) => ({
-      task_id: taskId,
-      status: member.tasks.find(({ task_id: id }) => id === taskId)?.status ?? 'pending',
-    })),
+    taskStates: member.tasks.map(({ task_id: taskId, status }) => ({ task_id: taskId, status })),
     sourceProjection: sourceEvidence.projection,
     gitProvenance,
     realizations,
@@ -2188,14 +2185,15 @@ async function structureFinalize({ repoRoot, env, planKey }) {
     effectiveTransforms.set(task.task_id, latest.realized);
   }
   const actor = mutationActor(env);
-  const sourceEvidence = await collectTodoStructureSourceEvidence({
-    cwd: repoRoot, structureSet: source, effectiveTransforms,
+  const observation = await collectTodoStructureAuthoritativeObservation({
+    repoRoot, structureSet: source, effectiveTransforms,
   });
-  const gitProvenance = collectTodoStructureGitProvenance({ repoRoot, structureSet: source });
+  const sourceEvidence = observation.source_evidence;
+  const gitProvenance = observation.git_provenance;
   const overlay = compileTodoStructureOverlay({
     structureSet: source,
     topology: mergedTopology(store),
-    taskStates: source.tasks.map(({ task_id: taskId }) => ({ task_id: taskId, status: 'done' })),
+    taskStates: member.tasks.map(({ task_id: taskId, status }) => ({ task_id: taskId, status })),
     sourceProjection: sourceEvidence.projection,
     gitProvenance,
     realizations,

package/src/todo-structure-authoritative-observation.mjs

@@ -0,0 +1,162 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { gitSpawnSync } from './git-process.mjs';
+import { runSensorCli } from './sensor-cli.mjs';
+import { collectTodoStructureGitProvenance } from './todo-structure-git-adapter.mjs';
+import { collectTodoStructureSourceEvidence } from './todo-structure-source-adapter.mjs';
+
+const SHA = /^[0-9a-f]{40}$/u;
+
+export class TodoStructureObservationError extends Error {
+  constructor(code, reason, detail = {}) {
+    super(reason);
+    this.name = 'TodoStructureObservationError';
+    this.code = code;
+    this.detail = { reason, ...detail };
+  }
+}
+
+function fail(code, reason, detail = {}) {
+  throw new TodoStructureObservationError(code, reason, detail);
+}
+
+function git({ cwd, args, operation }) {
+  const result = gitSpawnSync(args, {
+    cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error !== undefined || result.status !== 0 || result.signal !== null) {
+    fail('STRUCTURE_OBSERVATION_GIT_FAILED', 'observation_git_command_failed', {
+      operation, status: result.status ?? null, signal: result.signal ?? null,
+      cause: result.error?.message ?? null,
+    });
+  }
+  return result.stdout.trim();
+}
+
+function memoryStream() {
+  let value = '';
+  return {
+    stream: { write: (chunk) => { value += String(chunk); } },
+    read: () => value,
+  };
+}
+
+async function initializeObservationSensor(observationRoot) {
+  const stdout = memoryStream();
+  const stderr = memoryStream();
+  const status = await runSensorCli({
+    argv: ['init', observationRoot, '--json'],
+    stdout: stdout.stream,
+    stderr: stderr.stream,
+  });
+  if (status !== 0) {
+    let diagnostic = null;
+    try {
+      const parsed = JSON.parse(stderr.read().trim());
+      diagnostic = {
+        code: typeof parsed?.code === 'string' ? parsed.code : null,
+        detail: parsed?.detail ?? null,
+      };
+    } catch {
+      diagnostic = { code: null, detail: null };
+    }
+    fail('STRUCTURE_OBSERVATION_SENSOR_INIT_FAILED', 'observation_sensor_init_failed', {
+      sensor_error: diagnostic,
+    });
+  }
+}
+
+function errorSummary(error) {
+  return {
+    code: typeof error?.code === 'string' ? error.code : null,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/**
+ * 管理repoのdirtyなindex／worktreeを一切観測せず、current HEADだけを一時detached worktreeへ
+ * 展開してGit来歴とsource graphを収集する。store／planned source／artifactの読書きは呼出側が
+ * 管理repoで行うため、ここへは持ち込まない。
+ */
+export async function collectTodoStructureAuthoritativeObservation({
+  repoRoot, structureSet, effectiveTransforms = null,
+  initializeSensor = initializeObservationSensor,
+} = {}) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0
+    || structureSet === null || typeof structureSet !== 'object'
+    || typeof initializeSensor !== 'function') {
+    fail('STRUCTURE_OBSERVATION_INPUT_INVALID', 'observation_input_invalid');
+  }
+
+  const headSha = git({
+    cwd: repoRoot, args: ['rev-parse', '--verify', 'HEAD^{commit}'], operation: 'resolve_head',
+  });
+  if (!SHA.test(headSha)) fail('STRUCTURE_OBSERVATION_HEAD_INVALID', 'observation_head_invalid');
+
+  const temporaryRoot = await mkdtemp(path.join(tmpdir(), 'lattice-structure-observation-'));
+  const observationRoot = path.join(temporaryRoot, 'worktree');
+  let registered = false;
+  let operationError = null;
+  let result;
+  try {
+    git({
+      cwd: repoRoot,
+      args: ['worktree', 'add', '--detach', '--quiet', observationRoot, headSha],
+      operation: 'worktree_add',
+    });
+    registered = true;
+    const observedHead = git({
+      cwd: observationRoot, args: ['rev-parse', '--verify', 'HEAD^{commit}'],
+      operation: 'verify_observation_head',
+    });
+    if (observedHead !== headSha) {
+      fail('STRUCTURE_OBSERVATION_HEAD_MISMATCH', 'observation_head_mismatch', {
+        expected_head_sha: headSha, actual_head_sha: observedHead,
+      });
+    }
+
+    // sensor DBを作る前にclean treeをGit provenanceへ束縛する。sensorの一時fileは証拠対象外で、
+    // source projection収集後にworktreeごと破棄する。
+    const gitProvenance = collectTodoStructureGitProvenance({
+      repoRoot: observationRoot, structureSet,
+    });
+    await initializeSensor(observationRoot);
+    const sourceEvidence = await collectTodoStructureSourceEvidence({
+      cwd: observationRoot, structureSet, effectiveTransforms,
+      observationStage: effectiveTransforms === null ? 'planned' : 'final',
+    });
+    result = {
+      head_sha: headSha,
+      git_provenance: gitProvenance,
+      source_evidence: sourceEvidence,
+    };
+  } catch (error) {
+    operationError = error;
+  }
+
+  let cleanupError = null;
+  try {
+    if (registered) {
+      git({
+        cwd: repoRoot,
+        args: ['worktree', 'remove', '--force', observationRoot],
+        operation: 'worktree_remove',
+      });
+    }
+    await rm(temporaryRoot, { recursive: true, force: true });
+  } catch (error) {
+    cleanupError = error;
+  }
+
+  if (cleanupError !== null) {
+    fail('STRUCTURE_OBSERVATION_CLEANUP_FAILED', 'observation_cleanup_failed', {
+      operation_error: operationError === null ? null : errorSummary(operationError),
+      cleanup_error: errorSummary(cleanupError),
+      observation_root: observationRoot,
+    });
+  }
+  if (operationError !== null) throw operationError;
+  return result;
+}

package/src/todo-structure-overlay.mjs

@@ -62,12 +62,14 @@ function normalizeTaskStates(structureSet, taskStates) {
     if (!isPlain(entry) || Object.keys(entry).length !== 2
       || typeof entry.task_id !== 'string'
       || !['pending', 'in-progress', 'blocked', 'done'].includes(entry.status)
-      || !expected.has(entry.task_id) || states.has(entry.task_id)) {
+      || states.has(entry.task_id)) {
       fail('STRUCTURE_OVERLAY_INPUT_INVALID', 'task_state_entry_invalid');
     }
     states.set(entry.task_id, entry.status);
   }
-  if (states.size !== expected.size) fail('STRUCTURE_OVERLAY_INPUT_INVALID', 'task_state_coverage_invalid');
+  if ([...expected].some((taskId) => !states.has(taskId))) {
+    fail('STRUCTURE_OVERLAY_INPUT_INVALID', 'task_state_coverage_invalid');
+  }
   return states;
 }
 
@@ -302,7 +304,7 @@ function buildOverlayGraph(structureSet, states, latestRealizations, sourceProje
   return { nodes: uniqueNodes, edges, effective };
 }
 
-function connectionFindings(structureSet, effective, topologyDag) {
+function connectionFindings(structureSet, effective, topologyDag, states) {
   const findings = [];
   const externalById = new Map(structureSet.external_contracts
     .map((external) => [external.contract_id, external]));
@@ -322,7 +324,8 @@ function connectionFindings(structureSet, effective, topologyDag) {
   const structureTaskIds = new Set(structureSet.tasks.map(({ task_id: id }) => id));
   const extraTopologyTasks = topologyDag.nodes
     .filter(({ ref }) => ref.project_id === structureSet.project_id
-      && ref.plan_key === structureSet.plan_key && !structureTaskIds.has(ref.task_id))
+      && ref.plan_key === structureSet.plan_key && !structureTaskIds.has(ref.task_id)
+      && states.get(ref.task_id) !== 'done')
     .map(({ ref }) => ref.task_id).sort(compareText);
   if (extraTopologyTasks.length > 0) findings.push(finding({
     code: 'STRUCTURE_COVERAGE_MISSING', severity: 'error', taskIds: extraTopologyTasks,
@@ -466,12 +469,6 @@ function realizationFindings(structureSet, states, realizations, gitProvenance,
           observed: null, expected: 'fresh task realization',
           nextAction: 'record_the_task_realization_before_done',
         }));
-      } else if (state === 'in-progress') {
-        findings.push(finding({
-          code: 'STRUCTURE_COMMIT_UNBOUND', severity: 'unknown', taskIds: [task.task_id],
-          observed: { commits: [] }, expected: 'explicit realization commit OIDs when implementation exists',
-          nextAction: 'record_a_realization_when_the_task_has_committed_implementation',
-        }));
       }
       continue;
     }
@@ -563,7 +560,7 @@ export function compileTodoStructureOverlay({
   const rawFindings = [
     ...anchorFindings(structureSet, sourceProjection),
     ...missingEffectiveAnchors,
-    ...connectionFindings(structureSet, graph.effective, topologyDag),
+    ...connectionFindings(structureSet, graph.effective, topologyDag, states),
     ...realizationFindings(
       structureSet, states, normalizedRealizations, gitProvenance, graph.effective,
     ),

package/src/todo-structure-source-adapter.mjs

@@ -234,13 +234,26 @@ function edgeObservation(outcome, expectedNode, direction, expectedPath) {
   };
 }
 
-function effectVerdict(anchor, existence) {
-  if (anchor.expected_at !== 'current') {
+function effectVerdict(anchor, existence, observationStage) {
+  if (anchor.expected_at === 'baseline') {
     return { verdict: 'unknown', reason: 'STRUCTURE_CODE_ANCHOR_TIME_DEFERRED' };
   }
+  if (anchor.expected_at === 'after_task' && observationStage === 'planned') {
+    return { verdict: 'consistent', reason: null, deferred: true };
+  }
   if (existence === 'unknown') {
     return { verdict: 'unknown', reason: 'STRUCTURE_CODE_ANCHOR_UNRESOLVED' };
   }
+  if (anchor.expected_at === 'after_task' && observationStage === 'final') {
+    const expected = anchor.effect === 'delete' ? 'absent' : 'present';
+    return existence === expected
+      ? { verdict: 'consistent', reason: null }
+      : { verdict: 'inconsistent', reason: expected === 'present'
+        ? 'STRUCTURE_CODE_ANCHOR_ABSENT' : 'STRUCTURE_DELETE_STILL_EXISTS' };
+  }
+  if (anchor.expected_at !== 'current') {
+    return { verdict: 'unknown', reason: 'STRUCTURE_CODE_ANCHOR_TIME_DEFERRED' };
+  }
   if (anchor.effect === 'create') {
     return existence === 'absent'
       ? { verdict: 'consistent', reason: null }
@@ -274,7 +287,21 @@ function unknownAnchor(anchor, evidence, reason) {
   };
 }
 
-function projectAnchor({ anchor, querySet, outcomes, statusReady }) {
+function deferredAnchor(anchor, evidence) {
+  return {
+    ...unknownAnchor(anchor, evidence, null),
+    verdict: 'consistent',
+    reason: null,
+    coverage: 'deferred',
+    edges: {
+      state: 'not_applicable',
+      incoming: [], outgoing: [], incoming_omitted: 0, outgoing_omitted: 0,
+      incoming_source_limit_reached: false, outgoing_source_limit_reached: false,
+    },
+  };
+}
+
+function projectAnchor({ anchor, querySet, outcomes, statusReady, observationStage }) {
   const pathQuery = queryFor('affected', anchor.path);
   const pathOutcome = outcomes.get(pathQuery.id);
   const evidence = {
@@ -284,11 +311,14 @@ function projectAnchor({ anchor, querySet, outcomes, statusReady }) {
     callers: null,
     callees: null,
   };
+  if (anchor.expected_at === 'after_task' && observationStage === 'planned') {
+    return deferredAnchor(anchor, evidence);
+  }
   if (!statusReady) return unknownAnchor(anchor, evidence, 'STRUCTURE_SENSOR_NOT_READY');
 
   const pathResult = pathObservation(pathQuery, pathOutcome, anchor.path);
   if (anchor.symbol === null) {
-    const decision = effectVerdict(anchor, pathResult.existence);
+    const decision = effectVerdict(anchor, pathResult.existence, observationStage);
     return {
       ...unknownAnchor(anchor, evidence, decision.reason),
       verdict: decision.verdict,
@@ -321,7 +351,7 @@ function projectAnchor({ anchor, querySet, outcomes, statusReady }) {
     candidates: symbolResult.candidates,
   };
 
-  const decision = effectVerdict(anchor, symbolResult.existence);
+  const decision = effectVerdict(anchor, symbolResult.existence, observationStage);
   if (symbolResult.existence !== 'present') {
     return {
       ...unknownAnchor(anchor, evidence, decision.reason),
@@ -366,15 +396,18 @@ function projectAnchor({ anchor, querySet, outcomes, statusReady }) {
 
 /** 収集済みsensor outcomeから、anchor到達範囲だけのbounded projectionを作る。 */
 export function projectTodoStructureSourceEvidence({
-  structureSet, collected, effectiveTransforms = null,
+  structureSet, collected, effectiveTransforms = null, observationStage = 'current',
 } = {}) {
   assertStructureSet(structureSet);
+  if (!['current', 'planned', 'final'].includes(observationStage)) {
+    throw new TypeError('observationStageが不正');
+  }
   const querySet = buildTodoStructureSensorQuerySet(structureSet, { effectiveTransforms });
   const outcomes = indexOutcomes(querySet, collected);
   const statusQuery = querySet.queries[0];
   const statusOutcome = outcomes.get(statusQuery.id);
   const anchors = graphAnchors(structureSet, effectiveTransforms).map((anchor) => projectAnchor({
-    anchor, querySet, outcomes, statusReady: statusOutcome.outcome === 'ready',
+    anchor, querySet, outcomes, statusReady: statusOutcome.outcome === 'ready', observationStage,
   }));
   const projection = {
     schema: TODO_STRUCTURE_SOURCE_PROJECTION_SCHEMA,
@@ -400,7 +433,7 @@ export function projectTodoStructureSourceEvidence({
 
 /** 実sensor収集とpure projectionを同じ既存adapter経由で行う。 */
 export async function collectTodoStructureSourceEvidence({
-  cwd, structureSet, effectiveTransforms = null,
+  cwd, structureSet, effectiveTransforms = null, observationStage = 'current',
   execute = undefined, inspectAffectedPath = undefined,
 } = {}) {
   const querySet = buildTodoStructureSensorQuerySet(structureSet, { effectiveTransforms });
@@ -412,6 +445,8 @@ export async function collectTodoStructureSourceEvidence({
   });
   return {
     query_set: querySet,
-    projection: projectTodoStructureSourceEvidence({ structureSet, collected, effectiveTransforms }),
+    projection: projectTodoStructureSourceEvidence({
+      structureSet, collected, effectiveTransforms, observationStage,
+    }),
   };
 }