@quolu/lattice 0.28.0 → 0.30.0

package/src/runtime-socket-owner.mjs

@@ -0,0 +1,125 @@
+/**
+ * unix domain socketの所有関係をOS非依存に観測する。
+ *
+ * 管理runtimeは「そのPIDが本当にそのcontrol socketを持っているか」を確かめてから接続する。
+ * この検査は成りすましたsocketへ繋がないための要であり、緩めない。
+ *
+ * 実装は`/usr/sbin/lsof`をhard-codeしていた。**これはmacOS専用のpathで、Linuxでは管理runtime
+ * が丸ごと動かなかった**（CIで実測：実daemonを起動するtestが軒並み`socket owner観測失敗`で
+ * 落ちていた）。移植性の欠陥であってtestの都合ではない。
+ *
+ * Linuxには`/proc`という一次情報があるので、外部commandを介さずに同じことが分かる。
+ * `/proc/<pid>/fd/*`のsymlinkが`socket:[inode]`を指し、`/proc/net/unix`がinodeとpathを結ぶ。
+ * lsofを持たない最小構成のcontainerでも動くので、Linuxでは`/proc`を優先する。
+ *
+ * どちらの手段でも観測できない環境では、**観測できたことにしない**。呼び出し側がfail closed
+ * するために、例外を投げるか空を返す（「所有していない」ではなく「分からない」を返さない設計に
+ * するため、判定は必ず呼び出し側の`some(...)`で行う）。
+ */
+
+import { execFile } from 'node:child_process';
+import { readdir, readFile, readlink } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/** lsofの絶対path候補。PATHは引かない——探索経路を広げるとsocket検査の前提が緩む。 */
+const LSOF_PATHS = Object.freeze(['/usr/sbin/lsof', '/usr/bin/lsof', '/bin/lsof']);
+
+const SOCKET_INODE = /^socket:\[(\d+)\]$/u;
+
+async function runLsof(args) {
+  let lastError = new Error('lsof not found');
+  for (const binary of LSOF_PATHS) {
+    try {
+      const { stdout } = await execFileAsync(binary, args, { encoding: 'utf8' });
+      return stdout;
+    } catch (error) {
+      // ENOENTは「その場所に無い」だけなので次の候補へ。
+      if (error?.code === 'ENOENT') { lastError = error; continue; }
+      // lsofは該当が無いとexit 1を返す。これは観測の失敗ではなく「所有者なし」である。
+      // ここを潰すと、誰も掴んでいないstale socketが観測失敗として扱われ、正常な後片付けが
+      // 止まる（元の呼び出し側も同じ区別をしていた）。
+      if (error?.code === 1 && String(error?.stdout ?? '').trim() === '') return '';
+      throw error;
+    }
+  }
+  throw lastError;
+}
+
+/** `/proc/<pid>/fd`からunix socketのinodeを集める。Linux専用。 */
+async function procSocketInodes(pid) {
+  const entries = await readdir(`/proc/${pid}/fd`);
+  const inodes = new Set();
+  for (const entry of entries) {
+    let target;
+    try { target = await readlink(`/proc/${pid}/fd/${entry}`); } catch { continue; }
+    const matched = SOCKET_INODE.exec(target);
+    if (matched !== null) inodes.add(matched[1]);
+  }
+  return inodes;
+}
+
+/** `/proc/net/unix`を読み、inode -> pathの対応を返す。 */
+async function procUnixSocketPaths() {
+  const text = await readFile('/proc/net/unix', 'utf8');
+  const byInode = new Map();
+  for (const line of text.split('\n').slice(1)) {
+    // Num RefCount Protocol Flags Type St Inode Path
+    const fields = line.trim().split(/\s+/u);
+    if (fields.length < 8) continue;
+    const inode = fields[6];
+    const socketPath = fields.slice(7).join(' ');
+    if (socketPath.length === 0) continue;
+    if (!byInode.has(inode)) byInode.set(inode, []);
+    byInode.get(inode).push(socketPath);
+  }
+  return byInode;
+}
+
+/**
+ * 指定PIDが開いているunix socketのpath一覧を返す。
+ *
+ * @returns {Promise<string[]>} 観測できたpath。観測手段が無ければthrowする。
+ */
+export async function socketPathsOwnedByPid(pid) {
+  if (process.platform === 'linux') {
+    const inodes = await procSocketInodes(pid);
+    if (inodes.size === 0) return [];
+    const byInode = await procUnixSocketPaths();
+    return [...inodes].flatMap((inode) => byInode.get(inode) ?? []);
+  }
+  const stdout = await runLsof(['-a', '-p', String(pid), '-U', '-F', 'fn']);
+  return stdout.split('\n')
+    .filter((line) => line.startsWith('n'))
+    .map((line) => line.slice(1));
+}
+
+/**
+ * 指定socket pathを開いているPID一覧を返す。
+ *
+ * @returns {Promise<number[]>} 観測できたPID。観測手段が無ければthrowする。
+ */
+export async function pidsOwningSocketPath(socketPath) {
+  if (process.platform === 'linux') {
+    const byInode = await procUnixSocketPaths();
+    const wanted = new Set();
+    for (const [inode, paths] of byInode) {
+      if (paths.includes(socketPath)) wanted.add(inode);
+    }
+    if (wanted.size === 0) return [];
+    const pids = new Set();
+    for (const entry of await readdir('/proc')) {
+      if (!/^\d+$/u.test(entry)) continue;
+      let inodes;
+      // 他ユーザーのprocessは読めない。読めないものを「所有していない」へ丸めるが、
+      // これはlsofが権限不足で黙るのと同じ性質であり、判定は所有を**肯定**する側でのみ使う。
+      try { inodes = await procSocketInodes(entry); } catch { continue; }
+      if ([...wanted].some((inode) => inodes.has(inode))) pids.add(Number(entry));
+    }
+    return [...pids];
+  }
+  const stdout = await runLsof(['-t', socketPath]);
+  return stdout.split('\n').map((line) => line.trim())
+    .filter((line) => /^\d+$/u.test(line)).map(Number);
+}

package/src/todo-cli.mjs

@@ -74,6 +74,7 @@ import {
 } from './todo-independence.mjs';
 import {
   selectIndependenceGuidance,
+  selectWitnessScaffoldGuidance,
   selectSeamProposalGuidance,
 } from './todo-independence-guidance.mjs';
 import {
@@ -964,18 +965,26 @@ async function witnessScaffold({ repoRoot, planKey, inputRef }) {
   }
   const { queries, paths } = buildWitnessObservationQuerySet(draft);
   const collected = await collectSensorEvidence({ cwd: repoRoot, querySet: { queries } });
-  const affectedTestsByPath = {};
+  const observationByPath = {};
   queries.forEach((query, index) => {
     if (query.operation !== 'affected') return;
     const entry = collected.outcomes[index]?.targets?.[0];
     // 観測できていないものを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
-    if (entry?.path_state === 'absent' || !Array.isArray(entry?.data?.affectedTests)) return;
-    affectedTestsByPath[query.target] = [...entry.data.affectedTests];
+    // 不存在（absent）は観測**できている**——fsのlstat結果である。未観測と混ぜると、
+    // 創作境界を宣言したToDoが「まだ確かめていない」側へ落ちる（ADR 0136）。
+    if (!Array.isArray(entry?.data?.affectedTests) || !Array.isArray(entry?.data?.changedFiles)) return;
+    observationByPath[query.target] = {
+      state: entry.path_state === 'absent' ? 'absent' : 'present',
+      affectedTests: [...entry.data.affectedTests],
+      changedFiles: [...entry.data.changedFiles],
+    };
   });
-  const { witnessSet, reasons } = buildWitnessSet({ draft, affectedTestsByPath });
+  const { witnessSet, reasons } = buildWitnessSet({ draft, observationByPath });
   if (witnessSet === null) {
+    // 理由コードは具体的なのに次の一手が汎用だと、何をどう直すのかが伝わらない。
+    const guidance = selectWitnessScaffoldGuidance(reasons);
     throw new TodoStoreError('WITNESS_SCAFFOLD_INCOMPLETE', 'witness_scaffold_incomplete', undefined, {
-      reasons, next_action: 'resolve_declaration_then_retry',
+      reasons, guidance, next_action: guidance.next_action,
     });
   }
   const ref = todoWitnessRef(planKey);

package/src/todo-independence-guidance.mjs

@@ -232,3 +232,65 @@ export const TODO_INDEPENDENCE_WORKFLOW = Object.freeze([
   '3. 読む: lattice todo independence --plan <key> --json（sensorを引かず、記録とHEAD照合だけで返る）',
   '4. 追従する: plan改訂後は lattice todo independence witness migrate --plan <key> で宣言を写してから再compileする',
 ]);
+
+/**
+ * 宣言の下書きが受理されなかった時の案内（`witness scaffold`）。
+ *
+ * 理由コードは具体的なのに次の一手が「宣言を直して再実行」のままだと、何をどう直すのかが
+ * 伝わらない。一番必要な瞬間——機械が「作れませんでした」と言った瞬間——に解決法を知らせない
+ * のは、ADR 0130が禁じたものそのものである。
+ */
+const SCAFFOLD_CATALOG = Object.freeze({
+  path_absent_declare_creates: {
+    message: '宣言したpathは不在と観測できている。そのToDoが作るなら、owns entryを{ path, creates: true }（下書きv2）にして再実行する。作らないなら、宣言しているpathが正しいか確かめる。',
+    next_action: 'declare_creates_then_retry',
+  },
+  creates_path_present: {
+    message: '創作を宣言したpathは既に存在する。作るのでなく変更するなら、creates宣言を外してpath名だけにする。',
+    next_action: 'drop_creates_then_retry',
+  },
+  creates_unverified: {
+    message: '創作宣言の裏付けが取れない。sensorの観測が「対象1件・依存test無し」の形になっていない。sensor syncで索引を取り直してから再実行する。',
+    next_action: 'sync_sensor_then_retry',
+  },
+  affected_tests_unobserved: {
+    message: '所有pathのaffected観測が取れていない。sensor syncで索引へ収載してから再実行する。',
+    next_action: 'sync_sensor_then_retry',
+  },
+  multiple_owned_paths_unsupported: {
+    message: 'affected_testsは宣言とfresh観測をbinding単位でexact比較するため、1 ToDoが複数pathを所有する宣言は今の契約で表現できない。ToDoを分けるか、所有を1 pathに絞る。',
+    next_action: 'split_todo_or_narrow_owns',
+  },
+  anchor_outside_owned: {
+    message: 'concern_anchorのwithinが、自分の所有pathを指していない。所有していない資源の内側に担当を主張できない。',
+    next_action: 'align_anchor_with_owns',
+  },
+  owns_empty: {
+    message: 'ownsが空のToDoがある。何を所有するかは判定の起点なので、道具が補わない。',
+    next_action: 'declare_owns_then_retry',
+  },
+  draft_invalid: {
+    message: '下書きがlattice.todo_witness_draft契約を満たしていない。creates宣言を使うならschemaをv2にする。',
+    next_action: 'fix_draft_schema_then_retry',
+  },
+});
+
+/**
+ * 理由の集合から、最も行動を要する案内を1つ選ぶ。
+ *
+ * 並べると読み手はどれから手を付けるか決められない。「形が壊れている」を最優先にし、
+ * 以下、宣言の直し方が具体的なものほど上へ置く。
+ */
+export function selectWitnessScaffoldGuidance(reasons = []) {
+  const codes = reasons.map((reason) => String(reason).split(':')[0]);
+  const order = [
+    'draft_invalid', 'owns_empty', 'multiple_owned_paths_unsupported', 'anchor_outside_owned',
+    'path_absent_declare_creates', 'creates_path_present', 'creates_unverified',
+    'affected_tests_unobserved',
+  ];
+  const code = order.find((candidate) => codes.includes(candidate));
+  if (code === undefined) {
+    return { code: 'witness_scaffold_incomplete', message: '下書きから宣言を組めなかった。', next_action: 'resolve_declaration_then_retry' };
+  }
+  return { code, ...SCAFFOLD_CATALOG[code] };
+}

package/src/todo-store.mjs

@@ -696,6 +696,34 @@ function validateMergedTransition(store, member, event) {
   }
 }
 
+/**
+ * refsから辿れるobject idの集合。repositoryごとに1度だけ数え、以後は使い回す。
+ *
+ * 到達可能性を見ないと、手元にだけ在るdangling blobを「検証済み」と読んでしまう。
+ */
+const reachableObjectCache = new Map();
+function reachableObjects(absoluteRepo) {
+  const cached = reachableObjectCache.get(absoluteRepo);
+  if (cached !== undefined) return cached;
+  let set;
+  try {
+    const stdout = execFileSync('git', ['rev-list', '--objects', '--all'],
+      { cwd: absoluteRepo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 256 * 1024 * 1024 });
+    set = new Set();
+    for (const line of stdout.split('\n')) {
+      const oid = line.slice(0, 40);
+      if (oid.length === 40) set.add(oid);
+    }
+  } catch {
+    // 数えられない環境では到達可能性で落とさない。判定できないことを「到達不能」へ丸めると、
+    // 既存recordが一斉に読めなくなる。ここは厳しさより「誤って否定しない」を採る。
+    set = { has: () => true };
+  }
+  reachableObjectCache.set(absoluteRepo, set);
+  return set;
+}
+
 function evidenceVerifier(manifest, repoRoot, hard) {
   const repositories = new Map(manifest.repositories.map((repo) => [repo.repo_id, repo.path]));
   return (descriptor) => {
@@ -706,6 +734,17 @@ function evidenceVerifier(manifest, repoRoot, hard) {
     try {
       const type = execFileSync('git', ['cat-file', '-t', descriptor.git_blob_oid], { cwd: absoluteRepo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
       if (type !== 'blob') throw new Error('not blob');
+      // **objectが在ることと、cloneした人が読めることは別である。** commitやtagから辿れない
+      // dangling blobでも`cat-file`は通るので、手元では検証済みに見えるのに、fresh cloneでは
+      // 誰も確かめられない証拠が残る。実際に16件そうなっており、公開CIで初めて露見した。
+      // 手元とCIで判定が食い違う状態を残さない。
+      //
+      // ただし**書き込み時には要求しない**。証拠文書は同じ変更でcommitするのが普通の流れで、
+      // `todo done`の時点ではindexに在るだけである。そこで拒むと正常な運用が止まる。
+      // 「記録はできるが、commitするまでverifyは通らない」が正しい強さである。
+      if (!hard && !reachableObjects(absoluteRepo).has(descriptor.git_blob_oid)) {
+        throw new Error('blob unreachable from refs');
+      }
       const bytes = execFileSync('git', ['cat-file', 'blob', descriptor.git_blob_oid], { cwd: absoluteRepo, encoding: 'buffer', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: TODO_LIMITS.narrativeSectionBytes + 1 });
       if (sha256Bytes(bytes) !== descriptor.content_digest) throw new Error('digest mismatch');
       return true;

package/src/witness-scaffold.mjs

@@ -18,6 +18,34 @@ const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const sortedUnique = (values) => [...new Set(values)].sort(compareText);
 
 export const WITNESS_DRAFT_SCHEMA = 'lattice.todo_witness_draft.v1';
+/** 創作宣言を書ける版。v1はstringのownsだけを受け、`creates`を表現できない。 */
+export const WITNESS_DRAFT_SCHEMA_V2 = 'lattice.todo_witness_draft.v2';
+const DRAFT_SCHEMAS = Object.freeze([WITNESS_DRAFT_SCHEMA, WITNESS_DRAFT_SCHEMA_V2]);
+
+/**
+ * ownsの1件を正規化する。
+ *
+ * v2では`{ path, creates: true }`を書ける。まだ存在しないpathを所有するToDo——新module・
+ * 新doc・新testの追加——は、これが無いと道具で宣言を作れない（ADR 0136）。
+ */
+function ownEntry(value, { allowCreates }) {
+  if (typeof value === 'string') return isTodoRef(value) ? { target: value, creates: false } : null;
+  if (!allowCreates || value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value).sort();
+  if (keys.length !== 2 || keys[0] !== 'creates' || keys[1] !== 'path') return null;
+  if (!isTodoRef(value.path) || value.creates !== true) return null;
+  // prefix形（末尾/）はaffectedがunresolvedを返すので、file単位に限る（ADR 0136）。
+  if (value.path.endsWith('/')) return null;
+  return { target: value.path, creates: true };
+}
+
+/** 下書きの1 taskが宣言する所有を正規化する。1件でも形が壊れていればnull。 */
+export function draftOwnEntries(task, schema) {
+  const allowCreates = schema === WITNESS_DRAFT_SCHEMA_V2;
+  if (!Array.isArray(task?.owns)) return null;
+  const entries = task.owns.map((own) => ownEntry(own, { allowCreates }));
+  return entries.some((entry) => entry === null) ? null : entries;
+}
 
 function reject(reasons) {
   return { witnessSet: null, queries: [], reasons: sortedUnique(reasons) };
@@ -26,7 +54,7 @@ function reject(reasons) {
 /** 下書きの形。AIが書く欄だけを持ち、観測で埋まる欄は持たない。 */
 export function validateWitnessDraft(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
-  if (value.schema !== WITNESS_DRAFT_SCHEMA) return false;
+  if (!DRAFT_SCHEMAS.includes(value.schema)) return false;
   if (!isTodoIdentifier(value.project_id) || !isTodoIdentifier(value.plan_key)) return false;
   if (value.capacity === null || typeof value.capacity !== 'object'
     || !Number.isSafeInteger(value.capacity.executors) || value.capacity.executors < 1) return false;
@@ -35,7 +63,7 @@ export function validateWitnessDraft(value) {
   if (entries.length === 0) return false;
   return entries.every(([taskId, task]) => isTodoIdentifier(taskId)
     && task !== null && typeof task === 'object' && !Array.isArray(task)
-    && Array.isArray(task.owns) && task.owns.every(isTodoRef)
+    && draftOwnEntries(task, value.schema) !== null
     && (task.reads === undefined || (Array.isArray(task.reads) && task.reads.every(isTodoRef)))
     && (task.unknowns === undefined || (Array.isArray(task.unknowns)
       && task.unknowns.every((entry) => entry !== null && typeof entry === 'object'
@@ -52,7 +80,8 @@ function queryIdFor(index) {
 
 /** 下書きから、観測に要るquery setを組む。所有pathごとに1つのaffected queryを引く。 */
 export function buildWitnessObservationQuerySet(draft) {
-  const paths = sortedUnique(Object.values(draft.tasks).flatMap(({ owns }) => owns));
+  const paths = sortedUnique(Object.values(draft.tasks)
+    .flatMap((task) => (draftOwnEntries(task, draft.schema) ?? []).map(({ target }) => target)));
   return {
     queries: [
       { id: 'witness-status', operation: 'status' },
@@ -69,9 +98,11 @@ export function buildWitnessObservationQuerySet(draft) {
  *
  * @param {object} options
  * @param {object} options.draft `lattice.todo_witness_draft.v1`
- * @param {object} options.affectedTestsByPath 所有pathごとのfresh観測
+ * @param {object} options.observationByPath 所有pathごとのfresh観測
+ *   `{ state: 'absent'|'present', affectedTests: string[], changedFiles: string[] }`。
+ *   観測できていないpathは**欄そのものを置かない**——空で置くと不在と区別できない。
  */
-export function buildWitnessSet({ draft, affectedTestsByPath } = {}) {
+export function buildWitnessSet({ draft, observationByPath } = {}) {
   if (!validateWitnessDraft(draft)) return reject(['draft_invalid']);
   const { paths } = buildWitnessObservationQuerySet(draft);
   const queryIdByPath = new Map(paths.map((target, index) => [target, queryIdFor(index)]));
@@ -79,21 +110,39 @@ export function buildWitnessSet({ draft, affectedTestsByPath } = {}) {
   const reasons = [];
   const manualWitness = {};
   for (const [taskId, task] of Object.entries(draft.tasks).sort(([left], [right]) => compareText(left, right))) {
-    const owns = sortedUnique(task.owns);
+    const entries = draftOwnEntries(task, draft.schema) ?? [];
+    const owns = [...new Map(entries.map((entry) => [entry.target, entry])).values()]
+      .sort((left, right) => compareText(left.target, right.target));
     if (owns.length === 0) { reasons.push(`owns_empty:${taskId}`); continue; }
     // affected_testsは宣言とfresh観測をbinding単位でexact比較する。複数pathを所有すると
     // 観測集合が一致しない限り必ず落ちるので、今の契約では表現できない（2026-07-27の実測）。
     if (owns.length > 1) { reasons.push(`multiple_owned_paths_unsupported:${taskId}`); continue; }
-    const [target] = owns;
-    const affected = affectedTestsByPath?.[target];
+    const [own] = owns;
+    const target = own.target;
+    const observed = observationByPath?.[target];
     // 観測できていないことを空配列へ丸めない。丸めるとdriftでcompileが落ちる。
-    if (!Array.isArray(affected)) { reasons.push(`affected_tests_unobserved:${target}`); continue; }
+    if (observed === undefined) { reasons.push(`affected_tests_unobserved:${target}`); continue; }
+    if (own.creates) {
+      // 宣言が実態と合っているかを確かめるのが道具の役目である。front endが要求する形
+      // （fresh absent・blast radiusが空・changedFilesが対象1件）をここで満たしておかないと、
+      // 通る宣言を作ったつもりでcompileで落ちる（ADR 0136）。
+      if (observed.state !== 'absent') { reasons.push(`creates_path_present:${target}`); continue; }
+      if (observed.affectedTests.length !== 0
+        || observed.changedFiles.length !== 1
+        || observed.changedFiles[0] !== target) {
+        reasons.push(`creates_unverified:${target}`); continue;
+      }
+    } else if (observed.state === 'absent') {
+      // 不存在のpathを黙って通さない。作るつもりならそう宣言する、が次の一手である。
+      reasons.push(`path_absent_declare_creates:${target}`); continue;
+    }
+    const affected = own.creates ? [] : observed.affectedTests;
     for (const anchor of task.concern_anchors ?? []) {
       // `within`は自分が所有している資源に限る。所有していない資源の内側に担当を主張させない。
-      if (!owns.includes(anchor.within)) reasons.push(`anchor_outside_owned:${taskId}:${anchor.within}`);
+      if (anchor.within !== target) reasons.push(`anchor_outside_owned:${taskId}:${anchor.within}`);
     }
     manualWitness[taskId] = {
-      owns: [{ kind: 'path', target }],
+      owns: [own.creates ? { kind: 'path', target, creates: true } : { kind: 'path', target }],
       reads: sortedUnique(task.reads ?? []),
       writes: [target],
       resources: [],