@quolu/lattice 0.50.1 → 0.52.0

package/src/runtime-contracts.mjs

@@ -51,6 +51,7 @@ export const RUN_EVENT_KINDS = Object.freeze([
 // ADR 0044 Decision 5のclosed conflict分類と、Decision 7.5のhold理由kind。
 export const RUNTIME_CONFLICT_KINDS = Object.freeze([
   'observed_write_conflict',
+  'observed_line_change',
   'semantic_conflict_unknown',
   'effect_conflict_unknown',
   'undeclared_write',
@@ -187,6 +188,33 @@ export const MANUAL_WITNESS_FIELDS = Object.freeze([
   'affected_tests',
   'unknowns',
 ]);
+export const MANUAL_WITNESS_OPTIONAL_FIELDS = Object.freeze(['lines']);
+export const LINE_ROLES = Object.freeze(['reads', 'writes']);
+
+function lineAnchor(value) {
+  if (!plainObject(value)) return false;
+  if (value.kind === 'path') {
+    return exactRecord(value, ['kind', 'path']) && repoRelativePath(value.path);
+  }
+  return value.kind === 'symbol'
+    && exactRecord(value, ['kind', 'name', 'path'])
+    && typeof value.name === 'string' && value.name.length > 0
+    && Buffer.byteLength(value.name, 'utf8') <= MAX_PATH_BYTES
+    && repoRelativePath(value.path);
+}
+
+function lineEntry(value) {
+  return plainObject(value)
+    && exactRecord(value, ['line_id', 'role', 'anchors'])
+    && identifier(value.line_id)
+    && LINE_ROLES.includes(value.role)
+    && boundedArray(value.anchors, lineAnchor, { min: 1 });
+}
+
+function lineEntries(value) {
+  return boundedArray(value, lineEntry)
+    && new Set(value.map(({ line_id: lineId }) => lineId)).size === value.length;
+}
 
 // manual witness entryの判定は`explainRunRequest`だけが所有する。
 // 同じ規則をbooleanと診断の二箇所へ持たないための単一正本化（ADR 0123）。
@@ -235,15 +263,17 @@ const WITNESS_PROVENANCE = Object.freeze([
 ]);
 
 /**
- * 現行のrun request契約。v4は計画境界を予測として扱う。v3以前の厳密なcompile契約は、
- * 既存requestの意味を変えないため読み口として残す。
+ * 現行のrun request契約。v5はpathを跨ぐ意味的な線を任意宣言できる。v4は同じ予測契約の
+ * lines無し版として残し、v3以前の厳密なcompile契約も既存requestの意味を変えずに読む。
  *
  * v2はこの系列ではない。ADR 0064のepoch後継request（`predecessor_request_digest`と
  * `task_migration_digest`を持つ別shape）が既に使っている番号なので、飛ばして採番する。
  */
-export const RUN_REQUEST_SCHEMA = 'lattice.run_request.v4';
+export const RUN_REQUEST_SCHEMA = 'lattice.run_request.v5';
+export const RUN_REQUEST_PREDICTION_SCHEMA = 'lattice.run_request.v4';
 export const RUN_REQUEST_DECLARATIVE_SCHEMA = 'lattice.run_request.v3';
 export const RUN_REQUEST_LEGACY_SCHEMAS = Object.freeze([
+  RUN_REQUEST_PREDICTION_SCHEMA,
   RUN_REQUEST_DECLARATIVE_SCHEMA,
   'lattice.run_request.v1',
 ]);
@@ -309,7 +339,10 @@ export function explainRunRequest(value) {
   if (!exactRecord(value, RUN_REQUEST_FIELDS)) return reject('unexpected_or_missing_top_level_keys', '');
   if (!RUN_REQUEST_SCHEMAS.includes(value.schema)) return reject('schema_mismatch', '/schema');
   // 創作宣言はv2から。v1のclosed shapeは余分fieldを拒否するので加算互換が成立しない。
-  const allowCreates = [RUN_REQUEST_SCHEMA, RUN_REQUEST_DECLARATIVE_SCHEMA].includes(value.schema);
+  const allowCreates = [
+    RUN_REQUEST_SCHEMA, RUN_REQUEST_PREDICTION_SCHEMA, RUN_REQUEST_DECLARATIVE_SCHEMA,
+  ].includes(value.schema);
+  const allowLines = value.schema === RUN_REQUEST_SCHEMA;
   if (!identifier(value.request_id)) return reject('invalid_identifier', '/request_id');
   if (!exactRecord(value.repo, ['base_sha', 'root_kind'])) return reject('unexpected_or_missing_keys', '/repo');
   if (!gitSha(value.repo.base_sha)) return reject('invalid_git_sha', '/repo/base_sha');
@@ -333,7 +366,13 @@ export function explainRunRequest(value) {
     const witness = value.manual_witness[todoId];
     const at = `/manual_witness/${todoId}`;
     if (!plainObject(witness)) return reject('not_an_object', at);
-    if (!exactRecord(witness, MANUAL_WITNESS_FIELDS)) return reject('unexpected_or_missing_keys', at);
+    const hasLines = Object.hasOwn(witness, 'lines');
+    const witnessFields = hasLines
+      ? [...MANUAL_WITNESS_FIELDS, ...MANUAL_WITNESS_OPTIONAL_FIELDS]
+      : MANUAL_WITNESS_FIELDS;
+    if (!exactRecord(witness, witnessFields)) return reject('unexpected_or_missing_keys', at);
+    if (hasLines && !allowLines) return reject('lines_require_run_request_v5', `${at}/lines`);
+    if (hasLines && !lineEntries(witness.lines)) return reject('invalid_line_entries', `${at}/lines`);
     if (!boundedArray(witness.owns, (own) => ownEntry(own, { allowCreates }))) {
       return reject('invalid_own_entries', `${at}/owns`);
     }
@@ -407,20 +446,23 @@ export function verifyRuntimePlanBinding(options = {}) {
 }
 
 /**
- * `lattice.boundary_manifest.v3`。witness_provenanceはresourceごとに区別する。
+ * `lattice.boundary_manifest.v4`。v4はpathを跨ぐ意味的な線を任意記録できる。
  *
  * v3は`owns[].creates`だけがv2との差である。宣言が持っていた「このpathはまだ無い」を
  * 記録側でも保つ——落とすと、manifestだけを読む消費者が既存fileと同じ扱いをする。
- * 旧v2 manifestはrun storeに残るので読み口として受理する。
+ * 旧v2/v3 manifestはrun storeに残るので読み口として受理し、linesを要求しない。
  */
-export const BOUNDARY_MANIFEST_SCHEMA = 'lattice.boundary_manifest.v3';
+export const BOUNDARY_MANIFEST_SCHEMA = 'lattice.boundary_manifest.v4';
 export const BOUNDARY_MANIFEST_SCHEMAS = Object.freeze([
   BOUNDARY_MANIFEST_SCHEMA,
+  'lattice.boundary_manifest.v3',
   'lattice.boundary_manifest.v2',
 ]);
 export function validateRuntimeBoundaryManifest(value) {
-  return validateSafely(value, (manifest) => (
-    exactRecord(manifest, [
+  return validateSafely(value, (manifest) => {
+    const hasLines = Object.hasOwn(manifest, 'lines');
+    return (
+      exactRecord(manifest, [
       'schema',
       'todo_id',
       'owns',
@@ -432,12 +474,14 @@ export function validateRuntimeBoundaryManifest(value) {
       'affected_tests',
       'graph_evidence',
       'witness_provenance',
+      ...(hasLines ? ['lines'] : []),
       'manifest_digest',
-    ])
+      ])
     && BOUNDARY_MANIFEST_SCHEMAS.includes(manifest.schema)
+    && (!hasLines || manifest.schema === BOUNDARY_MANIFEST_SCHEMA)
     && identifier(manifest.todo_id)
     && boundedArray(manifest.owns, (own) => ownEntry(own, {
-      allowCreates: manifest.schema === BOUNDARY_MANIFEST_SCHEMA,
+      allowCreates: [BOUNDARY_MANIFEST_SCHEMA, 'lattice.boundary_manifest.v3'].includes(manifest.schema),
     }))
     && repoPathArray(manifest.reads)
     && repoPathArray(manifest.writes, { allowPrefix: true })
@@ -450,8 +494,10 @@ export function validateRuntimeBoundaryManifest(value) {
     && Object.values(manifest.witness_provenance).every((entry) => (
       WITNESS_PROVENANCE.includes(entry)
     ))
+    && (!hasLines || lineEntries(manifest.lines))
     && selfDigestValid(manifest, 'manifest_digest')
-  ));
+    );
+  });
 }
 
 /** `lattice.runtime_plan.v1`。exact_minimum claimは1〜8 nodeだけを受理する（Decision 1）。 */

package/src/runtime-controller-protocol.mjs

@@ -8,6 +8,10 @@ import {
 
 const SHA256 = /^[0-9a-f]{64}$/;
 const ID = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/;
+const CONTROLLER_ERROR_SCHEMAS = new Set([
+  'lattice.scripted_adapter_error.v1',
+  'lattice.work_order_adapter_error.v1',
+]);
 
 export const CONTROLLER_OPERATIONS = Object.freeze([
   'dispatch', 'observe', 'inventory', 'barrier', 'rebind', 'prepare', 'activate', 'release', 'revoke',
@@ -106,6 +110,18 @@ function selfValid(value, field) {
   try { return digest(value[field]) && selfDigest(value, field) === value[field]; } catch { return false; }
 }
 
+/** controller実装が返す既知errorを、request bindingを含めて検証する。 */
+export function validateControllerError(value, expectedRequestId = null) {
+  return exact(value, ['schema', 'code', 'message', 'request_id', 'detail', 'error_digest'])
+    && CONTROLLER_ERROR_SCHEMAS.has(value.schema)
+    && identifier(value.code)
+    && typeof value.message === 'string' && value.message.length > 0
+    && identifier(value.request_id)
+    && (expectedRequestId === null || value.request_id === expectedRequestId)
+    && plain(value.detail)
+    && selfValid(value, 'error_digest');
+}
+
 export function validateRuntimeHeartbeatPolicy(value) {
   return exact(value, ['schema', 'interval_ms', 'ttl_ms', 'disconnect_revokes_immediately', 'policy_digest'])
     && value.schema === 'lattice.runtime_heartbeat_policy.v1'
@@ -125,15 +141,30 @@ export function validateControllerHeartbeat(value) {
 }
 
 export function validateRuntimeAdapterCapabilities(value) {
-  return exact(value, ['schema', 'operations', 'process_observation', 'worktree_fingerprint', 'staged_write_lease', 'durable_dispatch', 'capabilities_digest'])
-    && value.schema === 'lattice.runtime_adapter_capabilities.v1'
+  const fields = ['schema', 'operations', 'process_observation', 'worktree_fingerprint',
+    'staged_write_lease', 'durable_dispatch', 'capabilities_digest'];
+  if (value?.schema === 'lattice.runtime_adapter_capabilities.v2') {
+    fields.push('host_driven_epoch');
+  }
+  return exact(value, fields)
+    && ['lattice.runtime_adapter_capabilities.v1',
+      'lattice.runtime_adapter_capabilities.v2'].includes(value.schema)
     && Array.isArray(value.operations) && value.operations.length === CONTROLLER_OPERATIONS.length
     && value.operations.every((op, i) => op === CONTROLLER_OPERATIONS[i])
     && value.process_observation === true && value.worktree_fingerprint === true
     && value.staged_write_lease === true && value.durable_dispatch === true
+    && (value.schema !== 'lattice.runtime_adapter_capabilities.v2'
+      || typeof value.host_driven_epoch === 'boolean')
     && selfValid(value, 'capabilities_digest');
 }
 
+/** hostがmanaged epochを駆動してよいとcontroller自身が宣言した能力だけを採る。 */
+export function acceptsHostDrivenEpoch(value) {
+  return validateRuntimeAdapterCapabilities(value)
+    && value.schema === 'lattice.runtime_adapter_capabilities.v2'
+    && value.host_driven_epoch === true;
+}
+
 export function validateProcessStartIdentity(value) {
   return exact(value, ['schema', 'platform', 'pid', 'started_identity', 'identity_digest'])
     && value.schema === 'lattice.process_start_identity.v1'
@@ -405,7 +436,7 @@ function validateProtocolRunningBinding(value) {
  * dispatchが名指しするworker process。直接OS観測が期待するchild processと同じ形にする
  * ——照合先の形が分かれると、supervisorとcontrollerが別のものを見ていても気づけない。
  */
-export function validateExpectedWorkerProcess(value) {
+function validateExpectedWorkerProcessLeaf(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')
@@ -415,6 +446,20 @@ export function validateExpectedWorkerProcess(value) {
     && value.process_start_identity.pid === value.pid;
 }
 
+export function validateExpectedWorkerProcess(value) {
+  if (validateExpectedWorkerProcessLeaf(value)) return true;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).sort().join('\0')
+      !== ['pid', 'process_group_id', 'process_start_identity', 'process_membership'].sort().join('\0')
+    || !validateExpectedWorkerProcessLeaf({
+      pid: value.pid,
+      process_group_id: value.process_group_id,
+      process_start_identity: value.process_start_identity,
+    })
+    || value.process_membership !== 'dynamic_group') return false;
+  return true;
+}
+
 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

@@ -1,3 +1,5 @@
+import path from 'node:path';
+
 import { digestArtifact } from './artifact-contracts.mjs';
 import { validateCarryOverWitness } from './runtime-contracts.mjs';
 import { projectRuntimeState } from './runtime-projection.mjs';
@@ -117,6 +119,57 @@ function witnessSet(manifest, kinds) {
   return resources;
 }
 
+const LINE_ID = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/;
+const LINE_PATH_CONTROL = /[\u0000-\u001f\u007f]/;
+
+function runtimeLinePath(value) {
+  return typeof value === 'string' && value.length > 0
+    && Buffer.byteLength(value, 'utf8') <= 1_024
+    && !LINE_PATH_CONTROL.test(value) && !value.includes('\\')
+    && !path.posix.isAbsolute(value) && value === path.posix.normalize(value)
+    && !value.split('/').includes('..');
+}
+
+function runtimeLineGroups(manifests, todoIds) {
+  const groups = new Map();
+  for (const todoId of sorted(new Set(todoIds))) {
+    const manifest = manifests[todoId];
+    if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)
+      || !Array.isArray(manifest.lines ?? [])) {
+      invalidVerification(`boundary manifestのlinesが不正: ${todoId}`);
+    }
+    const seen = new Set();
+    for (const line of manifest.lines ?? []) {
+      if (line === null || typeof line !== 'object' || Array.isArray(line)
+        || Object.keys(line).sort().join(',') !== 'anchors,line_id,role'
+        || !LINE_ID.test(line.line_id ?? '') || !['reads', 'writes'].includes(line.role)
+        || !Array.isArray(line.anchors) || line.anchors.length === 0
+        || seen.has(line.line_id)) {
+        invalidVerification(`line宣言が不正: ${todoId}`);
+      }
+      seen.add(line.line_id);
+      const group = groups.get(line.line_id) ?? {
+        readers: new Set(), writers: new Set(), anchorPaths: new Set(),
+      };
+      group[line.role === 'reads' ? 'readers' : 'writers'].add(todoId);
+      for (const anchor of line.anchors) {
+        const keys = anchor !== null && typeof anchor === 'object' && !Array.isArray(anchor)
+          ? Object.keys(anchor).sort().join(',') : '';
+        const valid = anchor?.kind === 'path'
+          ? keys === 'kind,path' && runtimeLinePath(anchor.path)
+          : anchor?.kind === 'symbol' && keys === 'kind,name,path'
+            && typeof anchor.name === 'string' && anchor.name.length > 0
+            && runtimeLinePath(anchor.path);
+        if (!valid) invalidVerification(`line anchorが不正: ${todoId}/${line.line_id}`);
+        // producerと共有せず、観測pathだけから独立に近似する。
+        group.anchorPaths.add(anchor.path);
+      }
+      groups.set(line.line_id, group);
+    }
+  }
+  return groups;
+}
+
 /**
  * 観測diffをdeclared path／resource witnessへcross-bindし、closed conflict分類の
  * findingを返す（ADR 0044 Decision 5）。宣言外writeと運転中overlapは別findingで
@@ -157,6 +210,23 @@ export function classifyObservedDiff(options = {}) {
     }
   }
 
+  const lineScope = new Set([...relevant, ...observedByTodo.keys()]);
+  const lineGroups = runtimeLineGroups(manifests, lineScope);
+  for (const [todoId, paths] of observedByTodo) {
+    const observedPaths = new Set(paths);
+    for (const [lineId, group] of lineGroups) {
+      if (group.writers.has(todoId)) continue;
+      const readers = [...group.readers].filter((readerId) => readerId !== todoId).sort();
+      if (readers.length === 0
+        || ![...group.anchorPaths].some((anchorPath) => observedPaths.has(anchorPath))) continue;
+      findings.push({
+        kind: 'observed_line_change',
+        todo_ids: [todoId, ...readers].sort(),
+        resource_id: lineId,
+      });
+    }
+  }
+
   const writersByPath = new Map();
   for (const [todoId, paths] of observedByTodo) {
     for (const path of paths) {

package/src/runtime-diff-observer.mjs

@@ -21,6 +21,7 @@ import { digestArtifact } from './artifact-contracts.mjs';
 const MAX_DIFF_ENTRIES = 256;
 const MAX_TRACKED_FILE_BYTES = 4_194_304;
 const GIT_SHA1 = /^[0-9a-f]{40}$/;
+const LINE_ID = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/;
 
 function fail(reason) {
   throw new TypeError(`diff observer契約違反: ${reason}`);
@@ -252,6 +253,45 @@ export function coveredBy(declaredWrites, observedPath) {
   ));
 }
 
+function lineGroupsFor(manifests, todoIds) {
+  if (!plainRecord(manifests)) fail('boundary manifestsが不正');
+  const groups = new Map();
+  for (const todoId of [...new Set(todoIds)].sort()) {
+    const manifest = manifests[todoId];
+    if (!plainRecord(manifest) || !Array.isArray(manifest.lines ?? [])) {
+      fail(`boundary manifestのlinesが不正: ${todoId}`);
+    }
+    const seen = new Set();
+    for (const line of manifest.lines ?? []) {
+      if (!exactRecord(line, ['line_id', 'role', 'anchors'])
+        || !LINE_ID.test(line.line_id ?? '')
+        || !['reads', 'writes'].includes(line.role)
+        || !Array.isArray(line.anchors) || line.anchors.length === 0
+        || seen.has(line.line_id)) {
+        fail(`line宣言が不正: ${todoId}`);
+      }
+      seen.add(line.line_id);
+      const group = groups.get(line.line_id) ?? {
+        readers: new Set(), writers: new Set(), anchorPaths: new Set(),
+      };
+      group[line.role === 'reads' ? 'readers' : 'writers'].add(todoId);
+      for (const anchor of line.anchors) {
+        const valid = anchor?.kind === 'path'
+          ? exactRecord(anchor, ['kind', 'path']) && safeRelativePath(anchor.path)
+          : anchor?.kind === 'symbol'
+            && exactRecord(anchor, ['kind', 'name', 'path'])
+            && typeof anchor.name === 'string' && anchor.name.length > 0
+            && safeRelativePath(anchor.path);
+        if (!valid) fail(`line anchorが不正: ${todoId}/${line.line_id}`);
+        // symbol解決は実行時diffに存在しないので、初期実装では宣言済みpathへ近似する。
+        group.anchorPaths.add(anchor.path);
+      }
+      groups.set(line.line_id, group);
+    }
+  }
+  return groups;
+}
+
 /**
  * checkpoint diffのobserved pathをdeclared scope／他running TODOのdeclared writeへ
  * cross-bindし、closed conflict分類のfindingを返す（producer側の検出。独立再計算は
@@ -261,10 +301,10 @@ export function coveredBy(declaredWrites, observedPath) {
  * - observed_write_conflict: 他のrunning TODOのdeclared writeとのpath overlap。
  */
 export function detectCheckpointFindings(options = {}) {
-  if (!exactRecord(options, ['todoId', 'checkpoint', 'packets', 'runningTodoIds'])) {
+  if (!exactRecord(options, ['todoId', 'checkpoint', 'packets', 'manifests', 'runningTodoIds'])) {
     fail('detectCheckpointFindings optionsがexact shapeでない');
   }
-  const { todoId, checkpoint, packets, runningTodoIds } = options;
+  const { todoId, checkpoint, packets, manifests, runningTodoIds } = options;
   if (!plainRecord(checkpoint) || !plainRecord(checkpoint.diff) || !Array.isArray(checkpoint.diff.entries)) {
     fail('checkpoint diff recordが不正');
   }
@@ -272,10 +312,14 @@ export function detectCheckpointFindings(options = {}) {
   if (!plainRecord(packet) || !plainRecord(packet.scope) || !Array.isArray(packet.scope.writes)) {
     fail(`packetが不正: ${todoId}`);
   }
+  const manifest = manifests[todoId];
+  if (!plainRecord(manifest) || !Array.isArray(manifest.writes)) {
+    fail(`boundary manifestが不正: ${todoId}`);
+  }
   // findingはverifier（classifyObservedDiff）と同じper-path shapeで返す。
   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)) {
+    if (!coveredBy(manifest.writes, entry.path)) {
       findings.push({ kind: 'undeclared_write', todo_ids: [todoId], path: entry.path });
     }
   }
@@ -285,8 +329,12 @@ export function detectCheckpointFindings(options = {}) {
     if (!plainRecord(other) || !plainRecord(other.scope) || !Array.isArray(other.scope.writes)) {
       fail(`packetが不正: ${otherId}`);
     }
+    const otherManifest = manifests[otherId];
+    if (!plainRecord(otherManifest) || !Array.isArray(otherManifest.writes)) {
+      fail(`boundary manifestが不正: ${otherId}`);
+    }
     for (const entry of [...checkpoint.diff.entries].sort((l, r) => (l.path < r.path ? -1 : 1))) {
-      if (coveredBy(other.scope.writes, entry.path)) {
+      if (coveredBy(otherManifest.writes, entry.path)) {
         findings.push({
           kind: 'observed_write_conflict',
           todo_ids: [todoId, otherId].sort(),
@@ -295,5 +343,19 @@ export function detectCheckpointFindings(options = {}) {
       }
     }
   }
+  const observedPaths = new Set(checkpoint.diff.entries.map((entry) => entry.path));
+  for (const [lineId, group] of lineGroupsFor(
+    manifests, [todoId, ...runningTodoIds],
+  )) {
+    if (group.writers.has(todoId)) continue;
+    const readers = [...group.readers].filter((readerId) => readerId !== todoId).sort();
+    if (readers.length === 0
+      || ![...group.anchorPaths].some((anchorPath) => observedPaths.has(anchorPath))) continue;
+    findings.push({
+      kind: 'observed_line_change',
+      todo_ids: [todoId, ...readers].sort(),
+      resource_id: lineId,
+    });
+  }
   return { findings };
 }

package/src/runtime-direct-os-observer.mjs

@@ -56,6 +56,7 @@ function validateResolvedBinding(value) {
     || value.process_start_identity.pid !== value.process_pid
     || !Array.isArray(value.process_children)
     || !value.process_children.every(validExpectedProcess)
+    || !['static', 'dynamic_group'].includes(value.process_membership_policy ?? 'static')
     || typeof value.worktree_path !== 'string' || !path.isAbsolute(value.worktree_path)
     || typeof value.base_sha !== 'string' || !GIT_SHA1.test(value.base_sha)) {
     fail('observation binding不正');
@@ -208,20 +209,36 @@ export function createDirectOsProcessObserver({
     };
     const root = verifyProcess(expectedRoot, records.get(resolved.process_pid), 'root');
     const actualDescendants = descendantPids(records, resolved.process_pid);
-    const expectedDescendants = new Set(resolved.process_children.map((child) => child.pid));
-    for (const pid of expectedDescendants) {
-      if (!actualDescendants.has(pid)) fail(`保存済みchildが見つからない: ${pid}`);
-    }
-    for (const pid of actualDescendants) {
-      if (!expectedDescendants.has(pid)) fail(`未記録childを検出: ${pid}`);
+    const dynamicGroup = resolved.process_membership_policy === 'dynamic_group';
+    const expectedChildren = dynamicGroup
+      ? [...actualDescendants].map((pid) => {
+        const record = records.get(pid);
+        if (record.process_group_id !== resolved.process_group_id) {
+          fail(`dynamic childがrootと別process groupに居る: ${pid}`);
+        }
+        return {
+          pid,
+          process_group_id: record.process_group_id,
+          process_start_identity: identityFor(pid, record.started_identity),
+        };
+      })
+      : resolved.process_children;
+    const expectedDescendants = new Set(expectedChildren.map((child) => child.pid));
+    if (!dynamicGroup) {
+      for (const pid of expectedDescendants) {
+        if (!actualDescendants.has(pid)) fail(`保存済みchildが見つからない: ${pid}`);
+      }
+      for (const pid of actualDescendants) {
+        if (!expectedDescendants.has(pid)) fail(`未記録childを検出: ${pid}`);
+      }
     }
-    const expectedGroup = new Set([resolved.process_pid, ...expectedDescendants]);
+    const expectedGroup = new Set([resolved.process_pid, ...actualDescendants]);
     for (const record of records.values()) {
       if (record.process_group_id === resolved.process_group_id && !expectedGroup.has(record.pid)) {
         fail(`未記録process group memberを検出: ${record.pid}`);
       }
     }
-    const children = resolved.process_children
+    const children = expectedChildren
       .map((expected) => verifyProcess(expected, records.get(expected.pid), 'child'))
       .sort((left, right) => left.pid - right.pid);
 

package/src/runtime-driver-state.mjs

@@ -0,0 +1,162 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { canonicalizeArtifact } from './artifact-contracts.mjs';
+import { selfDigest } from './runtime-contracts.mjs';
+
+const DRIVER_STATE_SCHEMA = 'lattice.runtime_driver_state.v1';
+const DIGEST = /^[0-9a-f]{64}$/u;
+const IDENTIFIER = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/u;
+const DESCRIPTOR_REF = /^supervisor\/(?:descriptor\.json|restart-candidates\/[0-9a-f]{64}\/descriptor\.json)$/u;
+const WAIT_KINDS = new Set(['frontier_dispatch', 'executor_completion']);
+const MAX_STATE_BYTES = 65_536;
+
+export class RuntimeDriverStateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'RuntimeDriverStateError';
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new RuntimeDriverStateError(code, message);
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function exact(value, keys) {
+  return plain(value)
+    && Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+}
+
+function validWaitingOn(value) {
+  return exact(value, ['kind', 'todo_ids'])
+    && WAIT_KINDS.has(value.kind)
+    && Array.isArray(value.todo_ids)
+    && value.todo_ids.length > 0
+    && value.todo_ids.length <= 256
+    && value.todo_ids.every((todoId) => IDENTIFIER.test(todoId))
+    && value.todo_ids.every((todoId, index) => index === 0 || value.todo_ids[index - 1] < todoId);
+}
+
+export function validateRuntimeDriverState(value) {
+  if (!exact(value, [
+    'schema',
+    'run_id',
+    'supervisor_descriptor_ref',
+    'supervisor_descriptor_digest',
+    'supervisor_process_start_identity_digest',
+    'driver_state',
+    'waiting_on',
+    'updated_at',
+    'state_digest',
+  ])
+    || value.schema !== DRIVER_STATE_SCHEMA
+    || !IDENTIFIER.test(value.run_id ?? '')
+    || !DESCRIPTOR_REF.test(value.supervisor_descriptor_ref ?? '')
+    || !DIGEST.test(value.supervisor_descriptor_digest ?? '')
+    || !DIGEST.test(value.supervisor_process_start_identity_digest ?? '')
+    || !['driving', 'stopped'].includes(value.driver_state)
+    || typeof value.updated_at !== 'string'
+    || Number.isNaN(Date.parse(value.updated_at))
+    || !DIGEST.test(value.state_digest ?? '')
+    || value.state_digest !== selfDigest(value, 'state_digest')) return false;
+  return value.driver_state === 'stopped'
+    ? value.waiting_on === null
+    : validWaitingOn(value.waiting_on);
+}
+
+function statePath(runDir) {
+  return path.join(runDir, 'supervisor', 'driver-state.json');
+}
+
+async function fsyncDirectory(directory) {
+  const handle = await open(directory, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function replaceRuntimeDriverState({
+  runDir,
+  runId,
+  supervisorDescriptorRef,
+  supervisorDescriptorDigest,
+  supervisorProcessStartIdentityDigest,
+  driverState,
+  waitingOn,
+  updatedAt,
+} = {}) {
+  if (typeof runDir !== 'string' || runDir.length === 0) {
+    throw new TypeError('runDirが不正');
+  }
+  const state = {
+    schema: DRIVER_STATE_SCHEMA,
+    run_id: runId,
+    supervisor_descriptor_ref: supervisorDescriptorRef,
+    supervisor_descriptor_digest: supervisorDescriptorDigest,
+    supervisor_process_start_identity_digest: supervisorProcessStartIdentityDigest,
+    driver_state: driverState,
+    waiting_on: waitingOn === null ? null : structuredClone(waitingOn),
+    updated_at: updatedAt,
+    state_digest: '',
+  };
+  state.state_digest = selfDigest(state, 'state_digest');
+  if (!validateRuntimeDriverState(state)) throw new TypeError('runtime driver state入力が不正');
+
+  const supervisorDir = path.join(runDir, 'supervisor');
+  await mkdir(supervisorDir, { recursive: true, mode: 0o700 });
+  const target = statePath(runDir);
+  const temporary = path.join(supervisorDir, `.driver-state-${process.pid}-${randomUUID()}.tmp`);
+  try {
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(`${canonicalizeArtifact(state)}\n`);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, target);
+    await fsyncDirectory(supervisorDir);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+  return state;
+}
+
+export async function readRuntimeDriverState({ runDir } = {}) {
+  if (typeof runDir !== 'string' || runDir.length === 0) {
+    throw new TypeError('runDirが不正');
+  }
+  const target = statePath(runDir);
+  let info;
+  try {
+    info = await lstat(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    fail('INVALID_RUN_STORE', 'driver stateを読めない');
+  }
+  if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_STATE_BYTES) {
+    fail('INVALID_RUN_STORE', 'driver stateが安全なbounded regular fileでない');
+  }
+  let bytes;
+  let value;
+  try {
+    bytes = await readFile(target);
+    value = JSON.parse(bytes);
+  } catch {
+    fail('INVALID_RUN_STORE', 'driver stateがJSONとして不正');
+  }
+  if (bytes.toString('utf8') !== `${canonicalizeArtifact(value)}\n`
+    || !validateRuntimeDriverState(value)) {
+    fail('INVALID_RUN_STORE', 'driver stateのschemaまたはcanonical bytesが不正');
+  }
+  return value;
+}