@quolu/lattice 0.31.0 → 0.33.0

package/src/runtime-contracts.mjs

@@ -53,7 +53,7 @@ export const RUNTIME_CONFLICT_KINDS = Object.freeze([
   'observed_write_conflict',
   'semantic_conflict_unknown',
   'effect_conflict_unknown',
-  'scope_violation',
+  'undeclared_write',
   'stale_context',
 ]);
 export const HOLD_REASON_KINDS = Object.freeze([

package/src/runtime-control-store.mjs

@@ -161,7 +161,7 @@ export function validateRuntimeControlEventPayload(kind, value) {
   // 機械が何かに気づいたのに黙っている状態を残さない。
   if (kind === 'io_warning_observed') {
     return exact(value, ['warning_kind', 'todo_ids', 'path', 'probe_outcome', 'warning_digest'])
-      && ['io_overlap_warning', 'io_scope_warning'].includes(value.warning_kind)
+      && ['io_overlap_warning', 'io_undeclared_write_warning'].includes(value.warning_kind)
       && Array.isArray(value.todo_ids) && value.todo_ids.length >= 1 && value.todo_ids.length <= 256
       && value.todo_ids.every(identifier)
       && value.todo_ids.every((id, index) => index === 0 || value.todo_ids[index - 1] < id)
@@ -171,6 +171,29 @@ export function validateRuntimeControlEventPayload(kind, value) {
         warning_kind: value.warning_kind, todo_ids: value.todo_ids, path: value.path,
       });
   }
+  // hold裁定のcontinue_setをprocessへ反映した記録（請求項7・8の再開側）。
+  // barrierは全workerを止めるので、続けてよいと判定した作業を再開しなければ、
+  // 判定と実行が食い違ったままになる。
+  if (kind === 'workers_resumed') {
+    return exact(value, ['resumed_todo_ids', 'skipped_count'])
+      && Array.isArray(value.resumed_todo_ids) && value.resumed_todo_ids.length <= 4096
+      && value.resumed_todo_ids.every(identifier)
+      && value.resumed_todo_ids.every((id, index) => index === 0
+        || value.resumed_todo_ids[index - 1] < id)
+      && Number.isSafeInteger(value.skipped_count) && value.skipped_count >= 0;
+  }
+  // 破棄の決定としてworker processを終了した記録。**cleanupではない。**
+  // 停止したworkerの行き先は「再開」か「破棄」の二択であり、破棄を選んだなら
+  // 誰を止めたかが残っていなければ、後から何が捨てられたか説明できない。
+  if (kind === 'worker_processes_terminated') {
+    return exact(value, ['reason', 'terminated_pids', 'skipped_count'])
+      && typeof value.reason === 'string' && value.reason.length > 0
+      && Array.isArray(value.terminated_pids) && value.terminated_pids.length <= 4096
+      && value.terminated_pids.every((pid) => Number.isSafeInteger(pid) && pid > 0)
+      && value.terminated_pids.every((pid, index) => index === 0
+        || value.terminated_pids[index - 1] < pid)
+      && Number.isSafeInteger(value.skipped_count) && value.skipped_count >= 0;
+  }
   // probeを通った警報を既存hold経路へ入れた顛末（ADR 0143の三段目）。
   // 成否どちらも残す。自動escalationが黙って失敗する状態を作らない——失敗の理由は
   // `detail`が持ち、これが無いと「警報は出たのにholdが掛かっていない」を後から説明できない。

package/src/runtime-controller-protocol.mjs

@@ -31,8 +31,8 @@ const WIRES = Object.freeze({
   dispatch: {
     request: ['schema', 'request_id', 'registration_digest', 'packet', 'write_lease', 'request_digest'],
     requestSchema: 'lattice.adapter_dispatch_request.v1',
-    response: ['schema', 'request_id', 'executor_handle', 'worktree_id', 'packet_digest', 'lease_digest', 'response_digest'],
-    responseSchema: 'lattice.adapter_dispatch_response.v1',
+    response: ['schema', 'request_id', 'executor_handle', 'worktree_id', 'packet_digest', 'lease_digest', 'worker_process', 'response_digest'],
+    responseSchema: 'lattice.adapter_dispatch_response.v2',
   },
   observe: {
     request: ['schema', 'request_id', 'registration_digest', 'executor_handle', 'expected_epoch', 'expected_lease_digest', 'request_digest'],
@@ -338,8 +338,12 @@ export function validateControllerResponse(operation, value, expectedRequestId =
   if (!(Boolean(wire) && exact(value, wire.response) && value.schema === wire.responseSchema
     && identifier(value.request_id) && (expectedRequestId === null || value.request_id === expectedRequestId)
     && selfValid(value, 'response_digest'))) return false;
+  // v2で`worker_process`を必須にした。executorがcontroller自身のprocessだと、holdが
+  // 要求する静止を証明できない（止めれば応答できず、止めなければ証明できない）。
+  // 誰を止めればよいかをdispatchの時点で名指しさせる。
   if (operation === 'dispatch') return identifier(value.executor_handle) && identifier(value.worktree_id)
-    && digest(value.packet_digest) && digest(value.lease_digest);
+    && digest(value.packet_digest) && digest(value.lease_digest)
+    && validateExpectedWorkerProcess(value.worker_process);
   if (operation === 'observe') return exact(value.observation, ['schema', 'state', 'executor_handle', 'plan_epoch', 'lease_digest', 'payload_digest', 'observation_digest'])
     && value.observation.schema === 'lattice.adapter_observation.v1'
     && ['running', 'checkpoint_ready', 'terminal', 'held'].includes(value.observation.state)
@@ -397,6 +401,20 @@ function validateProtocolRunningBinding(value) {
     && identifier(value.write_lease_id) && digest(value.controller_registration_digest);
 }
 
+/**
+ * dispatchが名指しするworker process。直接OS観測が期待するchild processと同じ形にする
+ * ——照合先の形が分かれると、supervisorとcontrollerが別のものを見ていても気づけない。
+ */
+export function validateExpectedWorkerProcess(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join('\0')
+      === ['pid', 'process_group_id', 'process_start_identity'].sort().join('\0')
+    && Number.isSafeInteger(value.pid) && value.pid > 0
+    && Number.isSafeInteger(value.process_group_id) && value.process_group_id > 0
+    && validateProcessStartIdentity(value.process_start_identity)
+    && value.process_start_identity.pid === value.pid;
+}
+
 export function validateQuiescenceAck(value) {
   return exact(value, ['schema', 'ack_id', 'run_id', 'todo_id', 'executor_handle', 'worktree_id', 'plan_epoch', 'packet_digest', 'write_lease_id', 'barrier_control_digest', 'final_checkpoint_digest', 'process_observation_digest', 'worktree_fingerprint_digest', 'supervisor_session_nonce_digest', 'ack_digest'])
     && value.schema === 'lattice.executor_quiescence_ack.v1'

package/src/runtime-decision-verifier.mjs

@@ -150,7 +150,7 @@ export function classifyObservedDiff(options = {}) {
     const declaredWrites = manifests[todoId].writes ?? [];
     for (const path of paths) {
       if (!declaredWriteCovers(declaredWrites, path)) {
-        findings.push({ kind: 'scope_violation', todo_ids: [todoId], path });
+        findings.push({ kind: 'undeclared_write', todo_ids: [todoId], path });
       }
     }
   }

package/src/runtime-diff-observer.mjs

@@ -257,7 +257,7 @@ export function coveredBy(declaredWrites, observedPath) {
  * cross-bindし、closed conflict分類のfindingを返す（producer側の検出。独立再計算は
  * runtime-decision-verifierの`classifyObservedDiff`が行う）。
  *
- * - scope_violation: 宣言write scope外へのwrite（offender=当該TODO）。
+ * - undeclared_write: 宣言write scope外へのwrite（offender=当該TODO）。
  * - observed_write_conflict: 他のrunning TODOのdeclared writeとのpath overlap。
  */
 export function detectCheckpointFindings(options = {}) {
@@ -276,7 +276,7 @@ export function detectCheckpointFindings(options = {}) {
   const findings = [];
   for (const entry of [...checkpoint.diff.entries].sort((l, r) => (l.path < r.path ? -1 : 1))) {
     if (!coveredBy(packet.scope.writes, entry.path)) {
-      findings.push({ kind: 'scope_violation', todo_ids: [todoId], path: entry.path });
+      findings.push({ kind: 'undeclared_write', todo_ids: [todoId], path: entry.path });
     }
   }
   for (const otherId of [...runningTodoIds].sort()) {

package/src/runtime-front-end.mjs

@@ -247,6 +247,25 @@ function affectedPayload(raw, expectPath) {
   return plainRecord(payload) ? payload : null;
 }
 
+/**
+ * 収集済みsensor evidenceから、あるpathのaffected testを読む。
+ *
+ * 実行時の翻訳段（宣言を観測へ合わせる）が同じ観測を必要とする。payloadの形の解釈をあちらへ
+ * 書き直すと、driftを判定する規則と、driftを起こさない宣言を作る規則が別々に育つ。
+ *
+ * @returns {string[]|null} 観測できなければnull（空配列と区別する）
+ */
+export function affectedTestsFromEvidence({ sensorEvidence, querySet, path: target } = {}) {
+  const queries = (querySet?.queries ?? [])
+    .filter((query) => query.operation === 'affected' && query.target === target);
+  if (queries.length !== 1) return null;
+  const outcome = (sensorEvidence?.outcomes ?? [])
+    .find((entry) => entry.query_id === queries[0].id);
+  if (!plainRecord(outcome) || outcome.status !== 'ready') return null;
+  const payload = affectedPayload(outcome.raw, target);
+  return Array.isArray(payload?.affectedTests) ? [...payload.affectedTests].sort(compareText) : null;
+}
+
 function affectedTarget(raw, expectPath) {
   if (!plainRecord(raw) || !Array.isArray(raw.targets)) return null;
   const entry = raw.targets.find((candidate) => (
@@ -486,28 +505,43 @@ export function compileRuntimePlanV1(options = {}) {
   }
 
   // affected test drift検査（witness宣言とfresh affected観測のexact比較）。
+  //
+  // 比較はTODO単位で、そのTODOが持つ**全affected束縛の観測の和**に対して行う。1面しか持たない
+  // TODOでは束縛ごとの比較と同じ結果になり、複数面を所有するTODOでも表現できる——束縛ごとに
+  // 宣言全体とexact比較すると、affectedの異なる2 pathを所有するTODOは原理的に成立せず、
+  // 実行時に所有が広がった宣言を受け取れなくなる。和なので緩みは入らない（余分な宣言も
+  // 足りない宣言もdriftのまま）。
   const affectedDrift = [];
   for (const todoId of todoIds) {
     const witness = request.manual_witness[todoId];
+    const declared = [...witness.affected_tests].sort(compareText);
+    const queryIds = [];
+    const observedUnion = new Set();
+    let unreadable = false;
     for (const binding of bindingsByTodo.get(todoId)) {
       if (binding.expect.kind !== 'affected') continue;
       const outcome = outcomeByQueryId.get(binding.query_id);
       if (resolveBindingStatus(binding, outcome) !== 'ready') continue;
+      queryIds.push(binding.query_id);
       const payload = affectedPayload(outcome.raw, binding.expect.path);
-      const observed = Array.isArray(payload?.affectedTests)
-        ? [...payload.affectedTests].sort(compareText)
-        : null;
-      const declared = [...witness.affected_tests].sort(compareText);
-      if (observed === null
-        || observed.length !== declared.length
-        || observed.some((test, index) => test !== declared[index])) {
-        affectedDrift.push({
-          todo_id: todoId,
-          query_id: binding.query_id,
-          declared,
-          observed,
-        });
+      if (!Array.isArray(payload?.affectedTests)) {
+        // 観測が読めないのは「一致しない」とは別の事象である。丸めずそのまま残す。
+        affectedDrift.push({ todo_id: todoId, query_id: binding.query_id, declared, observed: null });
+        unreadable = true;
+        continue;
       }
+      for (const test of payload.affectedTests) observedUnion.add(test);
+    }
+    if (unreadable || queryIds.length === 0) continue;
+    const observed = [...observedUnion].sort(compareText);
+    if (observed.length !== declared.length
+      || observed.some((test, index) => test !== declared[index])) {
+      affectedDrift.push({
+        todo_id: todoId,
+        query_id: queryIds.sort(compareText).join(','),
+        declared,
+        observed,
+      });
     }
   }
   if (affectedDrift.length > 0) {

package/src/runtime-hold-recompile.mjs

@@ -1,4 +1,7 @@
 import { canonicalizeArtifact, digestArtifact } from './artifact-contracts.mjs';
+// 切断可能性の写像はtodo側と同じ正本を使う。計画時と実行時で「切れる種類」の定義が
+// 分かれると、同じ資源が段によって別の答えを持つ。
+import { severabilityOfConflictKind } from './todo-independence-contracts.mjs';
 import { buildNextRunEvent, buildExecutorPackets } from './runtime-engine.mjs';
 import { projectRuntimeState } from './runtime-projection.mjs';
 import {
@@ -594,20 +597,46 @@ export function detectNonConvergentConflicts(options = {}) {
   ));
 }
 
+/**
+ * 係争資源が構造的に切れる種類かを返す（ADR 0144の続き、請求項8の入口判定）。
+ *
+ * pathやsymbolは面を分ければ別々に所有できる。共有stateや外部effectは分けられない——
+ * 変換をどれだけ工夫しても同じ資源に触り続ける。**これは「切れる」ではなく「切れる種類だ」で
+ * あって、実際に切れるかは試して初めて分かる。**
+ */
+export function severabilityOfRuntimeFinding(finding) {
+  return severabilityOfConflictKind(typeof finding?.path === 'string' ? 'path' : 'state');
+}
+
+/**
+ * 競合をどちらの処置へ運ぶか（請求項7＝直列化／請求項8＝変換）。
+ *
+ * `seam_transform`を返すのは事前宣言済みtreatmentが係争pathを覆っている時だけである。
+ * それ以外の既定は直列化だが、**それは「変換が不可能」という意味ではない**。実行時に初めて
+ * 見つかった競合には事前宣言が無いので、既定だけを見ると請求項8へ行く道が無いように見える。
+ *
+ * そこで`severability`と`transform_attemptable`を併せて返す。装置が言えるのは「切れる種類の
+ * 資源か」までで、**実際の難しさは変換を試して五条件で測る**（`run seam resolve`）。試すかどうかは
+ * 費用のかかる判断なので装置が決めない——隔離worktreeでの変換、focused test、再indexを毎回
+ * 走らせるかは、操作するAIが持つ文脈で決める（AGENTS.md「装置の境界にAIを含める」）。
+ */
 export function routeConflictTreatment(options = {}) {
   if (!exactRecord(options, ['finding', 'predeclaredTreatments'])) {
     fail('routeConflictTreatment optionsがexact shapeでない');
   }
   const { finding, predeclaredTreatments } = options;
   if (!plainRecord(finding) || typeof finding.kind !== 'string') fail('findingが不正');
+  const severability = severabilityOfRuntimeFinding(finding);
   if (finding.kind === 'observed_write_conflict' && typeof finding.path === 'string') {
     for (const treatment of predeclaredTreatments) {
       if (Array.isArray(treatment.covered_paths) && treatment.covered_paths.includes(finding.path)) {
-        return { lane: 'seam_transform', treatment: structuredClone(treatment) };
+        return { lane: 'seam_transform', treatment: structuredClone(treatment),
+          severability, transform_attemptable: true };
       }
     }
   }
-  return { lane: 'intentional_serial', treatment: null };
+  return { lane: 'intentional_serial', treatment: null,
+    severability, transform_attemptable: severability === 'code_seam' };
 }
 
 /**

package/src/runtime-io-sentinel.mjs

@@ -28,7 +28,7 @@ import { selfDigest } from './runtime-contracts.mjs';
 import { coveredBy } from './runtime-diff-observer.mjs';
 
 /** 警報の種別。findingのkindとは別空間にする——findingへ昇格するのはprobeを通った後だけである。 */
-export const IO_WARNING_KINDS = Object.freeze(['io_overlap_warning', 'io_scope_warning']);
+export const IO_WARNING_KINDS = Object.freeze(['io_overlap_warning', 'io_undeclared_write_warning']);
 
 /**
  * 監視から外すrepo相対prefix。
@@ -65,7 +65,7 @@ export function isExcludedPath(relativePath, excludes = DEFAULT_IO_EXCLUDES) {
  *
  * checkpoint findingの2述語をそのまま1 pathへ適用する:
  * - 他のrunning TODOの宣言scopeに入るpathへ書いた → `io_overlap_warning`
- * - 自分の宣言scopeの外へ書いた → `io_scope_warning`
+ * - 自分の宣言scopeの外へ書いた → `io_undeclared_write_warning`
  *
  * @returns {{warnings: Array<{kind: string, todo_ids: string[], path: string}>}}
  */
@@ -84,7 +84,7 @@ export function classifyIoObservation(options = {}) {
 
   const warnings = [];
   if (!coveredBy(packet.scope.writes, relativePath)) {
-    warnings.push({ kind: 'io_scope_warning', todo_ids: [todoId], path: relativePath });
+    warnings.push({ kind: 'io_undeclared_write_warning', todo_ids: [todoId], path: relativePath });
   }
   for (const otherId of [...runningTodoIds].sort(compareText)) {
     if (otherId === todoId) continue;
@@ -298,15 +298,22 @@ export function probeIoWarning({ warning, checkpointsByTodo } = {}) {
 }
 
 /**
- * 警報kind → finding kind。probeを通った警報だけがこの写像に乗る。
+ * 警報kind → finding kind。**重なりだけがhold経路へ乗る。**
  *
- * 述語が同一（`coveredBy`）なので、写像は1対1に決まる。ここで新しい種類を発明しない——
- * 発明すると、警報経由のfindingだけ既存の処置（請求項7の直列化、請求項8のseam変換）が
- * 効かない種類になってしまう。
+ * 宣言境界は計画時の**予測**であって、workerを閉じ込める制約ではない。範囲内へ無理に
+ * 押し込めるとworkerの自由度が落ち、成果の品質が下がる。だから自由に書かせ、**実際の足跡が
+ * 他の走行中TODOとぶつかった時にだけ**止めて処置する——請求項7（片方を停止し他方を確定して
+ * 再開する）と請求項8（限定的な変換を施して双方再開する）はそのための構成である。
+ *
+ * よって単独のscope警報——誰の領分とも重なっていない宣言外の書き込み——はhold経路へ運ばない。
+ * それは競合ではなく、**予測が実態より狭かったという情報**であり、止める理由が無い。記録は
+ * 残る（`io_warning_observed`）ので、再計画の材料としては失われない。
+ *
+ * 止めるべきでないものを止めると、処置の当てようが無い停止が生まれる。scope違反に処置が
+ * 無いのは欠落ではなく、処置すべき事象ではないことの現れである。
  */
 const WARNING_FINDING_KIND = Object.freeze({
   io_overlap_warning: 'observed_write_conflict',
-  io_scope_warning: 'scope_violation',
 });
 
 /**
@@ -320,7 +327,7 @@ function selectEscalationAnchor({ warning, writers, packets }) {
   const wrote = new Set(writers);
   const qualified = [...warning.todo_ids].sort(compareText).filter((todoId) => {
     if (!wrote.has(todoId)) return false;
-    if (warning.kind === 'io_scope_warning') return true;
+    if (warning.kind === 'io_undeclared_write_warning') return true;
     return warning.todo_ids.some((otherId) => {
       if (otherId === todoId) return false;
       const other = packets[otherId];

package/src/runtime-managed-supervisor.mjs

@@ -1340,7 +1340,15 @@ if (isDirectDaemon) {
         commitPhaseRevision: (revision) => applyPhaseTodoRevision({
           repoRoot: path.resolve(runDir, '..', '..', '..'),
           writer: createTodoStoreWriter({ caller: 'g5-authoring' }), revision,
-          actor: 'lattice-runtime-supervisor', recordedAt: new Date().toISOString(),
+          // actorは`{host, session, agent}`のexact recordである（`lattice.todo_event.v4`）。
+          // 文字列を渡していた間、seam_splitの再計画はphase revisionをcommitできなかった
+          // ——工程storeへ書く直前で必ず落ちるので、請求項8の再開まで一度も届いていない。
+          actor: {
+            host: 'lattice-runtime',
+            session: sessionNonce.slice(0, 32),
+            agent: 'lattice-runtime-supervisor',
+          },
+          recordedAt: new Date().toISOString(),
         }),
       });
     })

package/src/runtime-multi-epoch-store.mjs

@@ -83,7 +83,7 @@ export function validateRuntimeFindingRecord(value) {
     || new Set(finding.evidence_digests).size !== finding.evidence_digests.length
     || finding.evidence_digests.some((entry, index) => index > 0 && finding.evidence_digests[index - 1] >= entry)
     || !selfDigestValid(finding, 'finding_digest')) return false;
-  const pathKind = ['observed_write_conflict', 'scope_violation', 'stale_context'].includes(finding.kind);
+  const pathKind = ['observed_write_conflict', 'undeclared_write', 'stale_context'].includes(finding.kind);
   if (pathKind !== (finding.path !== null) || pathKind === (finding.resource_id !== null)) return false;
   const observer = value.recorded_by;
   return exactRecord(observer, ['schema', 'kind', 'controller_registration_digest',
@@ -109,7 +109,7 @@ export function validateRuntimeFindingCandidate(value) {
     || value.evidence_digests.some((digest, index) => index > 0
       && value.evidence_digests[index - 1] >= digest)
     || !selfDigestValid(value, 'candidate_digest')) return false;
-  const pathKind = ['observed_write_conflict', 'scope_violation', 'stale_context']
+  const pathKind = ['observed_write_conflict', 'undeclared_write', 'stale_context']
     .includes(value.proposed_kind);
   return pathKind
     ? typeof value.path === 'string' && value.path.length > 0 && value.resource_id === null

package/src/runtime-projection.mjs

@@ -238,5 +238,32 @@ export function projectRuntimeStatusOverlays(options = {}) {
     carry_over: members('carry_over'),
     redispatch: members('redispatch'),
     intake_frozen: runtimeState.freeze !== null,
+    treatment_advice: treatmentAdvice(events),
+  };
+}
+
+/**
+ * 止まっているrunに対して、請求項8（変換）を試せるかを助言する。
+ *
+ * 拒否ではなく助言である（ADR 0128と同じ規律）。既定の再計画modeが`intentional_serial`だから
+ * といって「変換が不可能」ではない——事前宣言が無いだけである。実行時に初めて見つかった競合には
+ * 事前宣言が無いので、既定だけを見ると請求項8へ行く道が無いように見える。
+ *
+ * 装置が言えるのは**係争資源が切れる種類か**までとする。共有stateや外部effectは面を分けても
+ * 同じ資源に触り続けるので切れない。pathは分けられる**かもしれない**——実際に切れるかと、
+ * それが割に合うかは、隔離worktreeで変換して五条件で測って初めて分かる（`run seam resolve`）。
+ * 試すかどうかは費用のかかる判断なので、装置は決めずに材料だけ渡す。
+ */
+function treatmentAdvice(events) {
+  const conflict = [...events].reverse()
+    .find((event) => event.kind === 'conflict_found'
+      && event.payload !== null && typeof event.payload === 'object');
+  if (conflict === undefined) return null;
+  const severability = typeof conflict.payload.path === 'string' ? 'code_seam' : 'serial';
+  return {
+    finding_digest: typeof conflict.payload.finding_digest === 'string'
+      ? conflict.payload.finding_digest : null,
+    severability,
+    transform_attemptable: severability === 'code_seam',
   };
 }