@quolu/lattice 0.12.34 → 0.13.0

package/src/todo-independence-contracts.mjs

@@ -0,0 +1,380 @@
+import {
+  exactRecord,
+  isNonNegativeSafeInteger,
+  isStrictTodoTimestamp,
+  isTodoDigest,
+  isTodoIdentifier,
+  todoSelfDigest,
+} from './todo-contracts.mjs';
+import {
+  RUN_REQUEST_CLAIM_MODE,
+  explainRunRequest,
+  selfDigest as runtimeSelfDigest,
+} from './runtime-contracts.mjs';
+import { TODO_INDEPENDENCE_GUIDANCE_CODES } from './todo-independence-guidance.mjs';
+
+export const TODO_WITNESS_SET_SCHEMA = 'lattice.todo_witness_set.v1';
+export const TODO_INDEPENDENCE_SCHEMA = 'lattice.todo_independence.v2';
+export const TODO_INDEPENDENCE_PROJECTION_SCHEMA = 'lattice.todo_independence_projection.v2';
+
+/** boundary compileが一度に扱えるToDo数（runtime front-endのMAX_COLLECTIONと同じ閉じ方）。 */
+export const TODO_INDEPENDENCE_TASK_LIMIT = 256;
+export const TODO_INDEPENDENCE_LIST_LIMIT = 4_096;
+export const TODO_INDEPENDENCE_COVERAGE = Object.freeze([
+  'verified', 'stale', 'superseded', 'missing',
+]);
+
+/** conflictを生んだresourceの種別。切断可能性の導出はこの種別だけを根拠にする。 */
+export const TODO_INDEPENDENCE_CONFLICT_KINDS = Object.freeze([
+  'symbol', 'path', 'state', 'effect',
+]);
+
+/** 切断可能性。code seamで切れるのはsymbol/path起因のconflictだけ（ADR 0128 Decision 2）。 */
+export const TODO_INDEPENDENCE_SEVERABILITY = Object.freeze(['code_seam', 'serial']);
+
+/**
+ * conflict kindから切断可能性を導く。
+ *
+ * 共有state／effectはcode seamでは切断できない（RC1 boundary compilerの分類規則と同一）。
+ * read×write交差から実体化される`rw-*`はkind=stateなのでserialへ倒れる。seam候補を
+ * 見逃す方向にしか外れない保守的な誤りであり、既知の限界として受け入れる。
+ */
+export function severabilityOfConflictKind(kind) {
+  return ['symbol', 'path'].includes(kind) ? 'code_seam' : 'serial';
+}
+
+const GIT_SHA = /^[0-9a-f]{40}$/u;
+const PROBE_BASE_SHA = '0'.repeat(40);
+
+export const isGitSha = (value) => typeof value === 'string' && GIT_SHA.test(value);
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function boundedList(value, validator, limit = TODO_INDEPENDENCE_LIST_LIMIT) {
+  return Array.isArray(value) && value.length <= limit && value.every(validator);
+}
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+
+function strictlySorted(values, key = (value) => value) {
+  return values.every((value, index) => index === 0 || compareText(key(values[index - 1]), key(value)) < 0);
+}
+
+function sorted(values, key = (value) => value) {
+  return values.every((value, index) => index === 0 || compareText(key(values[index - 1]), key(value)) <= 0);
+}
+
+function boundedText(value, maximumBytes = 4_096) {
+  return typeof value === 'string' && value.length > 0
+    && Buffer.byteLength(value) <= maximumBytes
+    && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+
+/**
+ * witness setを、同じ宣言を持つ`lattice.run_request.v1`へ写す。
+ *
+ * manual witnessとsensor query setの判定正本は`explainRunRequest`だけが持つ（ADR 0123）。
+ * ここで同じ規則を書き直すと契約が二箇所へ分裂するため、検証もcompileもこの合成を通す。
+ * `requestId`はplan identityとwitness digestから導出され、run lifecycleへは登録されない。
+ */
+export function synthesizeWitnessRunRequest(witnessSet, { baseSha, requestId }) {
+  const taskIds = Object.keys(witnessSet.manual_witness).sort(compareText);
+  const request = {
+    schema: 'lattice.run_request.v1',
+    request_id: requestId,
+    repo: { base_sha: baseSha, root_kind: 'git' },
+    capacity: witnessSet.capacity,
+    todos: taskIds.map((taskId) => ({ todo_id: taskId })),
+    manual_witness: witnessSet.manual_witness,
+    sensor_query_set: witnessSet.sensor_query_set,
+    executor_capability: { adapters: ['todo-independence'] },
+    claim_mode: RUN_REQUEST_CLAIM_MODE,
+    request_digest: '',
+  };
+  request.request_digest = runtimeSelfDigest(request, 'request_digest');
+  return request;
+}
+
+/**
+ * `lattice.todo_witness_set.v1`を検証し、拒否理由とpathを返す。
+ *
+ * 自分のshapeだけをここで見て、witness本体はprobe requestへ合成して
+ * `explainRunRequest`へ委譲する。probeのbase_shaは検証専用の定数であり永続化しない。
+ */
+export function explainTodoWitnessSet(value) {
+  const reject = (reason, at = '') => ({ valid: false, reason, path: at });
+  try {
+    if (!exactRecord(value, [
+      'schema', 'project_id', 'plan_key', 'capacity', 'sensor_query_set',
+      'manual_witness', 'witness_set_digest',
+    ])) return reject('unexpected_or_missing_top_level_keys');
+    if (value.schema !== TODO_WITNESS_SET_SCHEMA) return reject('schema_mismatch', '/schema');
+    if (!isTodoIdentifier(value.project_id)) return reject('invalid_identifier', '/project_id');
+    if (!isTodoIdentifier(value.plan_key)) return reject('invalid_identifier', '/plan_key');
+    if (!plain(value.manual_witness)) return reject('not_an_object', '/manual_witness');
+    const taskIds = Object.keys(value.manual_witness);
+    if (taskIds.length < 1 || taskIds.length > TODO_INDEPENDENCE_TASK_LIMIT) {
+      return reject('bounded_collection_violation', '/manual_witness');
+    }
+    if (!taskIds.every(isTodoIdentifier)) return reject('invalid_identifier', '/manual_witness');
+    if (value.witness_set_digest !== todoSelfDigest(value, 'witness_set_digest')) {
+      return reject('witness_set_digest_mismatch', '/witness_set_digest');
+    }
+    const probe = synthesizeWitnessRunRequest(value, {
+      baseSha: PROBE_BASE_SHA, requestId: 'witness-set-probe',
+    });
+    const explained = explainRunRequest(probe);
+    if (!explained.valid) return reject(explained.reason, explained.path);
+    return { valid: true };
+  } catch {
+    return reject('non_canonical_witness_set_bytes');
+  }
+}
+
+export function validateTodoWitnessSet(value) {
+  return explainTodoWitnessSet(value).valid;
+}
+
+function conflictEntry(value) {
+  return exactRecord(value, ['task_ids', 'resource_id', 'kind'])
+    && Array.isArray(value.task_ids) && value.task_ids.length === 2
+    && value.task_ids.every(isTodoIdentifier)
+    && compareText(value.task_ids[0], value.task_ids[1]) < 0
+    && boundedText(value.resource_id)
+    && TODO_INDEPENDENCE_CONFLICT_KINDS.includes(value.kind);
+}
+
+/**
+ * task別の宣言境界。鮮度判定をartifactとgit diffだけで閉じるために持つ（ADR 0128 Decision 4）。
+ * witness setを読み直さないので、参照コストは定数のまま保たれる。
+ */
+function taskBoundaryEntry(value) {
+  return exactRecord(value, ['task_id', 'paths'])
+    && isTodoIdentifier(value.task_id)
+    && Array.isArray(value.paths) && value.paths.length <= TODO_INDEPENDENCE_LIST_LIMIT
+    && value.paths.every((path) => boundedText(path)) && strictlySorted(value.paths);
+}
+
+function precedenceEntry(value) {
+  return exactRecord(value, ['from_task_id', 'to_task_id', 'reason'])
+    && isTodoIdentifier(value.from_task_id) && isTodoIdentifier(value.to_task_id)
+    && value.from_task_id !== value.to_task_id && boundedText(value.reason);
+}
+
+function unknownEntry(value) {
+  return exactRecord(value, ['task_id', 'kind', 'ref'])
+    && isTodoIdentifier(value.task_id) && isTodoIdentifier(value.kind) && boundedText(value.ref);
+}
+
+function waveEntry(value) {
+  return exactRecord(value, ['task_ids'])
+    && Array.isArray(value.task_ids) && value.task_ids.length >= 1
+    && value.task_ids.length <= TODO_INDEPENDENCE_TASK_LIMIT
+    && value.task_ids.every(isTodoIdentifier) && strictlySorted(value.task_ids);
+}
+
+function wavePlan(value, taskIds) {
+  if (value === null) return true;
+  if (!exactRecord(value, ['waves', 'minimum_feasible_waves'])
+    || !boundedList(value.waves, waveEntry, TODO_INDEPENDENCE_TASK_LIMIT)
+    || !isNonNegativeSafeInteger(value.minimum_feasible_waves)
+    || value.waves.length !== value.minimum_feasible_waves) return false;
+  const scheduled = value.waves.flatMap((wave) => wave.task_ids).sort(compareText);
+  return scheduled.length === taskIds.length
+    && scheduled.every((taskId, index) => taskId === taskIds[index]);
+}
+
+/**
+ * `lattice.todo_independence.v2`。
+ *
+ * conflict／precedence／unknownはnormalized boundary graphから採る（ADR 0127 Decision 4）。
+ * conflictはresource kindを併せて持ち、切断可能性の導出を投影側に許す（ADR 0128 Decision 1）。
+ * `task_boundaries`はtask別の宣言境界で、鮮度のdiff交差判定をartifactだけで閉じるために持つ。
+ * `wave_plan`はschedulability compileが`compiled`を返した時だけ持ち、unknownが残る間はnullになる。
+ * verdictに現れないペアをverified独立と読めるのは、両taskにunknownが無いときだけである。
+ */
+export function validateTodoIndependence(value) {
+  try {
+    if (!exactRecord(value, [
+      'schema', 'project_id', 'plan_key', 'plan_version', 'topology_digest', 'base_sha',
+      'witness_set_digest', 'compiled_at', 'task_ids', 'task_boundaries', 'conflicts',
+      'precedences', 'unknowns', 'wave_plan', 'outcome', 'result_digest',
+    ])) return false;
+    if (value.schema !== TODO_INDEPENDENCE_SCHEMA) return false;
+    if (!isTodoIdentifier(value.project_id) || !isTodoIdentifier(value.plan_key)
+      || !isTodoIdentifier(value.plan_version)) return false;
+    if (!isTodoDigest(value.topology_digest) || !isGitSha(value.base_sha)
+      || !isTodoDigest(value.witness_set_digest)
+      || !isStrictTodoTimestamp(value.compiled_at)) return false;
+    if (!Array.isArray(value.task_ids) || value.task_ids.length < 1
+      || value.task_ids.length > TODO_INDEPENDENCE_TASK_LIMIT
+      || !value.task_ids.every(isTodoIdentifier) || !strictlySorted(value.task_ids)) return false;
+    const known = new Set(value.task_ids);
+    // 宣言境界はcompile対象taskとちょうど一対一で対応する。欠けたtaskがあると、
+    // そのtaskだけ交差判定ができないのに全体はverifiedを名乗れてしまう。
+    if (!boundedList(value.task_boundaries, taskBoundaryEntry, TODO_INDEPENDENCE_TASK_LIMIT)
+      || value.task_boundaries.length !== value.task_ids.length
+      || !strictlySorted(value.task_boundaries, (entry) => entry.task_id)
+      || !value.task_boundaries.every((entry, index) => entry.task_id === value.task_ids[index])) {
+      return false;
+    }
+    if (!boundedList(value.conflicts, conflictEntry)
+      || !value.conflicts.every((entry) => entry.task_ids.every((taskId) => known.has(taskId)))
+      || !strictlySorted(value.conflicts, (entry) => (
+        `${entry.task_ids[0]}\0${entry.task_ids[1]}\0${entry.resource_id}`))) return false;
+    if (!boundedList(value.precedences, precedenceEntry)
+      || !value.precedences.every((entry) => known.has(entry.from_task_id) && known.has(entry.to_task_id))
+      || !strictlySorted(value.precedences, (entry) => (
+        `${entry.from_task_id}\0${entry.to_task_id}\0${entry.reason}`))) return false;
+    if (!boundedList(value.unknowns, unknownEntry)
+      || !value.unknowns.every((entry) => known.has(entry.task_id))
+      || !sorted(value.unknowns, (entry) => (
+        `${entry.task_id}\0${entry.kind}\0${entry.ref}`))) return false;
+    if (!['compiled', 'unknown'].includes(value.outcome)) return false;
+    // unknownが残る限りwave planは主張しない。compiledならunknownは空でなければならない。
+    if (value.outcome === 'compiled' && value.unknowns.length > 0) return false;
+    if (value.outcome === 'unknown' && value.wave_plan !== null) return false;
+    if (!wavePlan(value.wave_plan, value.task_ids)) return false;
+    return isTodoDigest(value.result_digest)
+      && value.result_digest === todoSelfDigest(value, 'result_digest');
+  } catch {
+    return false;
+  }
+}
+
+function groupEntry(value) {
+  return exactRecord(value, ['task_ids'])
+    && Array.isArray(value.task_ids) && value.task_ids.length >= 1
+    && value.task_ids.length <= TODO_INDEPENDENCE_TASK_LIMIT
+    && value.task_ids.every(isTodoIdentifier) && strictlySorted(value.task_ids);
+}
+
+function pairKindAndSeverability(value) {
+  // conflictはkindを持ちseverabilityがそこから導かれる。precedenceは順序制約であって
+  // resource起因ではないためkindを持たず、常にserialになる。
+  if (value.type === 'conflict') {
+    return TODO_INDEPENDENCE_CONFLICT_KINDS.includes(value.kind)
+      && value.severability === severabilityOfConflictKind(value.kind);
+  }
+  return value.kind === null && value.severability === 'serial';
+}
+
+function serializeEntry(value) {
+  return exactRecord(value, ['task_ids', 'type', 'detail', 'kind', 'severability'])
+    && Array.isArray(value.task_ids) && value.task_ids.length === 2
+    && value.task_ids.every(isTodoIdentifier)
+    && compareText(value.task_ids[0], value.task_ids[1]) < 0
+    && ['conflict', 'precedence'].includes(value.type) && boundedText(value.detail)
+    && pairKindAndSeverability(value);
+}
+
+/**
+ * 着手候補と進行中ToDoの競合。
+ *
+ * v1は両端がready集合のペアだけを採っており、片端がactiveのペアを黙って捨てていた。
+ * 着手する瞬間に最も危ないのはこの組み合わせなので、独立した面として持つ（ADR 0128 Decision 3）。
+ */
+function activeConflictEntry(value) {
+  return exactRecord(value, [
+    'ready_task_id', 'active_task_id', 'type', 'detail', 'kind', 'severability',
+  ]) && isTodoIdentifier(value.ready_task_id) && isTodoIdentifier(value.active_task_id)
+    && value.ready_task_id !== value.active_task_id
+    && ['conflict', 'precedence'].includes(value.type) && boundedText(value.detail)
+    && pairKindAndSeverability(value);
+}
+
+/**
+ * 案内。単一正本のcatalogが返した形をそのまま載せる（ADR 0130 Decision 1・2）。
+ * 面ごとに文言を組み立て直さないため、ここではshapeだけを検査する。
+ */
+function guidanceEntry(value) {
+  return exactRecord(value, ['code', 'message', 'next_action'])
+    && TODO_INDEPENDENCE_GUIDANCE_CODES.includes(value.code)
+    && boundedText(value.message) && isTodoIdentifier(value.next_action);
+}
+
+/**
+ * 鮮度の内訳。`coverage`がsha水準の事実を述べるのに対し、こちらは
+ * 「そのdiffが宣言境界に触れたか」というtask単位の事実を述べる（ADR 0128 Decision 4）。
+ */
+function driftEntry(value) {
+  if (value === null) return true;
+  return exactRecord(value, ['base_reachable', 'changed_path_count', 'intersecting_task_ids'])
+    && typeof value.base_reachable === 'boolean'
+    && isNonNegativeSafeInteger(value.changed_path_count)
+    && Array.isArray(value.intersecting_task_ids)
+    && value.intersecting_task_ids.length <= TODO_INDEPENDENCE_TASK_LIMIT
+    && value.intersecting_task_ids.every(isTodoIdentifier)
+    && strictlySorted(value.intersecting_task_ids);
+}
+
+function unknownTaskEntry(value) {
+  return exactRecord(value, ['task_id', 'unknowns'])
+    && isTodoIdentifier(value.task_id)
+    && Array.isArray(value.unknowns) && value.unknowns.length >= 1
+    && value.unknowns.length <= TODO_INDEPENDENCE_LIST_LIMIT
+    && value.unknowns.every((entry) => exactRecord(entry, ['kind', 'ref'])
+      && isTodoIdentifier(entry.kind) && boundedText(entry.ref));
+}
+
+/**
+ * `lattice.todo_independence_projection.v2`。
+ *
+ * ready frontierを「検証済み並列グループ」「直列化すべき組」「未検査」へ分けた読み出し面。
+ * v2は進行中ToDoとの競合（`conflicts_with_active`）と鮮度の内訳（`drift`）を加える。
+ * `todo_status_result.v4`と`dispatch_frontier`は変更せず、加算の別面として持つ（ADR 0124の規律）。
+ */
+export function validateTodoIndependenceProjection(value) {
+  try {
+    if (!exactRecord(value, [
+      'schema', 'project_id', 'plan_key', 'coverage', 'compiled_base_sha', 'current_base_sha',
+      'plan_version', 'topology_digest', 'active_task_ids', 'uncovered_active_task_ids',
+      'drift', 'guidance', 'frontier', 'result_digest',
+    ])) return false;
+    if (value.schema !== TODO_INDEPENDENCE_PROJECTION_SCHEMA) return false;
+    if (!isTodoIdentifier(value.project_id)) return false;
+    if (value.plan_key !== null && !isTodoIdentifier(value.plan_key)) return false;
+    if (!TODO_INDEPENDENCE_COVERAGE.includes(value.coverage)) return false;
+    if (value.compiled_base_sha !== null && !isGitSha(value.compiled_base_sha)) return false;
+    if (!isGitSha(value.current_base_sha)) return false;
+    if (value.plan_version !== null && !isTodoIdentifier(value.plan_version)) return false;
+    if (value.topology_digest !== null && !isTodoDigest(value.topology_digest)) return false;
+    // 記録が無い状態でcompile済みidentityを名乗らない。
+    if (value.coverage === 'missing'
+      && (value.compiled_base_sha !== null || value.topology_digest !== null)) return false;
+    if (value.coverage !== 'missing' && value.compiled_base_sha === null) return false;
+    for (const key of ['active_task_ids', 'uncovered_active_task_ids']) {
+      if (!Array.isArray(value[key]) || value[key].length > TODO_INDEPENDENCE_TASK_LIMIT
+        || !value[key].every(isTodoIdentifier) || !strictlySorted(value[key])) return false;
+    }
+    // 宣言のないactiveは考慮済みactiveの部分集合でなければならない。
+    const activeSet = new Set(value.active_task_ids);
+    if (!value.uncovered_active_task_ids.every((taskId) => activeSet.has(taskId))) return false;
+    if (!driftEntry(value.drift)) return false;
+    if (!guidanceEntry(value.guidance)) return false;
+    // driftはstale時の内訳。それ以外で語ると鮮度の事実を二重に主張することになる。
+    if (value.coverage !== 'stale' && value.drift !== null) return false;
+    if (!exactRecord(value.frontier, [
+      'parallel_groups', 'serialize_pairs', 'conflicts_with_active', 'unknown',
+    ])) return false;
+    if (!boundedList(value.frontier.parallel_groups, groupEntry, TODO_INDEPENDENCE_TASK_LIMIT)
+      || !strictlySorted(value.frontier.parallel_groups, (entry) => entry.task_ids[0])) return false;
+    if (!boundedList(value.frontier.serialize_pairs, serializeEntry)
+      || !strictlySorted(value.frontier.serialize_pairs, (entry) => (
+        `${entry.task_ids[0]}\0${entry.task_ids[1]}\0${entry.type}\0${entry.detail}`))) return false;
+    if (!boundedList(value.frontier.conflicts_with_active, activeConflictEntry)
+      || !strictlySorted(value.frontier.conflicts_with_active, (entry) => (
+        `${entry.ready_task_id}\0${entry.active_task_id}\0${entry.type}\0${entry.detail}`))) {
+      return false;
+    }
+    if (!boundedList(value.frontier.unknown, unknownTaskEntry, TODO_INDEPENDENCE_TASK_LIMIT)
+      || !strictlySorted(value.frontier.unknown, (entry) => entry.task_id)) return false;
+    return isTodoDigest(value.result_digest)
+      && value.result_digest === todoSelfDigest(value, 'result_digest');
+  } catch {
+    return false;
+  }
+}

package/src/todo-independence-guidance.mjs

@@ -0,0 +1,107 @@
+/**
+ * 並列可否の案内（ADR 0130）。
+ *
+ * 状況から`{code, message, next_action}`を引く単一正本。advisory・投影・typed error・helpは
+ * すべてここから引く。面ごとに文言を書けば必ずずれ、同じ状況に別の説明が付く。
+ *
+ * 文は事実と次の一歩だけを述べ、指示しない。dispatchの意思決定はhostが所有する
+ * （ADR 0063 Decision 5）。命令形にするとLatticeがagentを統制する面へ滑る。
+ */
+
+export const TODO_INDEPENDENCE_GUIDANCE_CODES = Object.freeze([
+  'independence_unrecorded',
+  'independence_task_undeclared',
+  'independence_superseded',
+  'independence_stale_for_task',
+  'independence_conflict_with_active',
+  'independence_conflict_between_ready',
+  'independence_verified',
+]);
+
+const CATALOG = Object.freeze({
+  independence_unrecorded: Object.freeze({
+    message: 'このplanの並列可否はまだ判定していない。競合が無いのではなく、記録が存在しない。',
+    next_action: 'declare_witness_set_then_compile',
+  }),
+  independence_task_undeclared: Object.freeze({
+    message: 'この工程はwitness setで宣言されていないため、記録には含まれていない。',
+    next_action: 'add_task_to_witness_set_then_compile',
+  }),
+  independence_superseded: Object.freeze({
+    message: 'planが改訂され、記録は別のtopologyについての判定になっている。',
+    next_action: 'migrate_witness_set_then_compile',
+  }),
+  independence_stale_for_task: Object.freeze({
+    message: '記録後にこの工程の宣言境界が変更されたため、記録時点の判定は現在のcodeを指していない。',
+    next_action: 'recompile_independence',
+  }),
+  independence_conflict_with_active: Object.freeze({
+    message: '作業中の工程と同じ資源を書く記録がある。並行すると衝突する。',
+    next_action: 'serialize_or_split_boundary',
+  }),
+  independence_conflict_between_ready: Object.freeze({
+    message: '他のready工程と同じ資源を書く記録がある。同時に着手すると衝突する。',
+    next_action: 'serialize_or_split_boundary',
+  }),
+  independence_verified: Object.freeze({
+    message: '記録時点の宣言境界では、他のready工程と干渉しない。',
+    next_action: 'none',
+  }),
+});
+
+/** 切断可能性の言い換え。conflictの案内へ添える。 */
+const SEVERABILITY_HINT = Object.freeze({
+  code_seam: 'symbol／pathの衝突なので、境界を分けるrefactorで並列化しうる。',
+  serial: '共有stateまたはeffectの衝突なので、分割では切り離せない。',
+});
+
+export function todoIndependenceGuidance(code, { severability = null } = {}) {
+  const entry = CATALOG[code];
+  if (entry === undefined) {
+    throw new TypeError(`unknown independence guidance code: ${code}`);
+  }
+  const hint = severability === null ? null : SEVERABILITY_HINT[severability] ?? null;
+  return {
+    code,
+    message: hint === null ? entry.message : `${entry.message}${hint}`,
+    next_action: entry.next_action,
+  };
+}
+
+/**
+ * advisoryや投影の状態から、最も行動を要する案内を1つ選ぶ。
+ *
+ * 複数の状況が重なることはあるが、案内を並べると読み手はどれから手を付けるか決められない。
+ * 「記録が無い」より「記録が古い」より「衝突している」を上に置く——後者ほど
+ * 次の一歩が具体的だからである。
+ */
+export function selectIndependenceGuidance({
+  coverage, taskDeclared, taskStale, conflictWithActive = null, conflictBetweenReady = null,
+}) {
+  if (conflictWithActive !== null) {
+    return todoIndependenceGuidance('independence_conflict_with_active', {
+      severability: conflictWithActive,
+    });
+  }
+  if (conflictBetweenReady !== null) {
+    return todoIndependenceGuidance('independence_conflict_between_ready', {
+      severability: conflictBetweenReady,
+    });
+  }
+  if (coverage === 'missing') return todoIndependenceGuidance('independence_unrecorded');
+  if (coverage === 'superseded') return todoIndependenceGuidance('independence_superseded');
+  if (!taskDeclared) return todoIndependenceGuidance('independence_task_undeclared');
+  if (taskStale) return todoIndependenceGuidance('independence_stale_for_task');
+  return todoIndependenceGuidance('independence_verified');
+}
+
+/**
+ * 宣言からcompileを経て読むまでの順序。helpとMCP instructionsが同じ手順を語るための正本。
+ * 面ごとに手順を書き直すと、片方だけが古くなる。
+ */
+export const TODO_INDEPENDENCE_WORKFLOW = Object.freeze([
+  '1. 宣言する: .lattice/todo/witness/<plan_key>.json へ、ToDoごとのowns／reads／writes／affected_testsを書く',
+  '2. 判定する: lattice todo independence compile --plan <key> --input <ref>（実sensorを引き、clean worktreeが要る）',
+  '3. 読む: lattice todo independence --plan <key> --json（sensorを引かず、記録とHEAD照合だけで返る）',
+  '4. 追従する: plan改訂後は lattice todo independence witness migrate --plan <key> で宣言を写してから再compileする',
+]);