@quolu/lattice 0.75.0 → 0.77.0

package/bin/lattice.mjs

@@ -185,8 +185,9 @@ await scheduleRuntimeErrorReport();
  * 送信を有効にしていない端末では、設定fileの有無を1回見るだけで終わる。hookは打鍵ごとに走るので見ない。
  */
 async function scheduleRuntimeErrorReport() {
+  // `reporting verify`の直後は送らない。受け口は1分に1回まで受けるので、続けて送ると断られる。
   if (help !== null || args[0] === '--version' || args[0] === 'hooks'
-    || (args[0] === 'runtime-errors' && args[1] === 'report')) return;
+    || (args[0] === 'runtime-errors' && (args[1] === 'report' || (args[1] === 'reporting' && args[2] === 'verify')))) return;
   try {
     const { runtimeErrorReportingEnabled } = await import('../src/runtime-errors.mjs');
     if (!runtimeErrorReportingEnabled()) return;
@@ -202,11 +203,10 @@ async function scheduleRuntimeErrorReport() {
 
 // typed契約の外へ漏れた例外を、opt-inのruntime error記録へ残す。どの面で・どの種類の例外で
 // 落ちたかを固定語彙の分類（safe_context）で添える——error_codeだけでは原因を追えなかった。
+// 取消は記録せず、通信の失敗が漏れたものは内部故障と別の記録になる（ADR 0196）。
 function observeInternalFailure(error, commandKind) {
-  pendingObservation = import('../src/runtime-errors.mjs').then(({ observeRuntimeError, runtimeErrorSafeContext }) => {
-    observeRuntimeError('LATTICE.CLI_INTERNAL_FAILED', {
-      version: packageJson.version, safeContext: runtimeErrorSafeContext({ commandKind, error }),
-    });
+  pendingObservation = import('../src/runtime-errors.mjs').then(({ observeEscapedCliFailure }) => {
+    observeEscapedCliFailure({ error, commandKind, version: packageJson.version });
   }).catch(() => {});
 }
 
@@ -222,7 +222,7 @@ function workingDirectory() {
 async function runRuntimeErrorsCli(rest) {
   const runtimeErrors = await import('../src/runtime-errors.mjs');
   const usage = () => {
-    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code: 'USAGE', message: 'usage: lattice runtime-errors <snapshot [--after-cursor N] [--limit N]|ack <cursor>|diagnostics|resolve <fingerprint>|reopen <fingerprint>|compact|report|reporting <status|enable|disable>> --json' })}\n`);
+    process.stderr.write(`${JSON.stringify({ schema: 'lattice.cli_error.v2', code: 'USAGE', message: 'usage: lattice runtime-errors <snapshot [--after-cursor N] [--limit N]|ack <cursor>|diagnostics|resolve <fingerprint>|reopen <fingerprint>|compact|report|reporting <status|enable|disable|verify>> --json' })}\n`);
     return 2;
   };
   const options = { version: packageJson.version };
@@ -251,6 +251,12 @@ async function runRuntimeErrorsCli(rest) {
       result = runtimeErrors.setRuntimeErrorStatus(words[1], words[0] === 'resolve' ? 'resolved' : 'open', options);
     } else if (words[0] === 'compact' && words.length === 1) {
       result = runtimeErrors.compactRuntimeErrors(options);
+    } else if (words[0] === 'reporting' && words.length === 2 && words[1] === 'verify') {
+      // 空の報告を1通送って経路を確かめる。受領まで確かめられた時だけexit 0。
+      const reporting = await import('../src/runtime-error-reporting.mjs');
+      result = await reporting.verifyRuntimeErrorReporting(options);
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+      return result.outcome === 'verified' ? 0 : 1;
     } else if (words[0] === 'reporting' && words.length === 2 && ['status', 'enable', 'disable'].includes(words[1])) {
       const reporting = await import('../src/runtime-error-reporting.mjs');
       result = words[1] === 'status' ? reporting.runtimeErrorReportingStatus(options)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "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/cli-command-kind.mjs

@@ -12,6 +12,12 @@ const RUNTIME_SURFACES = Object.freeze({
   event: Object.freeze(['verify']),
 });
 
+/**
+ * storeも端末の状態も書き換えないと確かめた面（ADR 0196）。通信の失敗が漏れた記録の重大度を決める時に使う
+ * ——ここに在る面は、落ちても失うものが無く、打ち直せば戻る。確かめていない面は載せない。
+ */
+export const READ_ONLY_COMMAND_KINDS = new Set(['run.list', 'todo.status', 'todo.verify']);
+
 export function cliCommandKind(argv, surfaces = RUNTIME_SURFACES) {
   if (!Array.isArray(argv)) return 'other';
   const [surface, subcommand] = argv;

package/src/cli-failure-class.mjs

@@ -0,0 +1,34 @@
+/**
+ * typed契約の外へ漏れた例外を、取消・通信の失敗・それ以外に分ける（ADR 0196）。
+ *
+ * runtime error記録の入口が使う。取消は故障として記録しない。通信の失敗が漏れたものは、内部故障とは
+ * 別の記録にする——原因が通信でも、型つきの答えにできず落ちたのは製品の対処不良で、直すのは回線ではなく
+ * その面の通信失敗の受け方である。
+ */
+
+// Nodeとundiciが通信の失敗に付けるcode。端末内のportの取り合い（EADDRINUSE）と、子processとのpipeでも
+// 起きるEPIPEは、通信の失敗に数えない。
+const TRANSPORT_CODES = new Set([
+  'ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'EHOSTUNREACH', 'EHOSTDOWN', 'ENETUNREACH',
+  'ENETDOWN', 'ENOTFOUND', 'EAI_AGAIN', 'ENOTCONN',
+  'ERR_SOCKET_CONNECTION_TIMEOUT', 'ERR_SOCKET_CLOSED',
+  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET', 'UND_ERR_CLOSED',
+]);
+const CAUSE_DEPTH = 4;
+
+/** 例外と、その`cause`の連なり。`fetch failed`（TypeError）は、通信のcodeを`cause`の側に持つ。 */
+export function failureCauseChain(error) {
+  const chain = [];
+  for (let current = error; current !== null && typeof current === 'object' && chain.length < CAUSE_DEPTH;
+    current = current.cause) chain.push(current);
+  return chain;
+}
+
+/** `cancelled`（利用者や呼び出し元の取消）・`transport`（通信の失敗）・`internal`（それ以外）。 */
+export function cliFailureClass(error) {
+  const chain = failureCauseChain(error);
+  if (chain.some((entry) => entry.name === 'AbortError' || entry.code === 'ABORT_ERR')) return 'cancelled';
+  // `AbortSignal.timeout`の時間切れは`TimeoutError`で届く。
+  if (chain.some((entry) => entry.name === 'TimeoutError' || TRANSPORT_CODES.has(entry.code))) return 'transport';
+  return 'internal';
+}

package/src/cli-help.mjs

@@ -198,6 +198,7 @@ Commands:
   compact
   report                        未受領の記録をBugHubの受け口へ送る（送信を有効にした端末だけ）
   reporting <status|enable|disable>
+  reporting verify              空の報告を1通送り、合鍵と受け口までの経路を確かめる（記録には触れない）
 `,
   bridge: `Usage: lattice bridge <command> [options] --json
 
@@ -315,7 +316,7 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'runtime-errors reopen': 'runtime-errors reopen <fingerprint> --json',
   'runtime-errors compact': 'runtime-errors compact --json',
   'runtime-errors report': 'runtime-errors report --json',
-  'runtime-errors reporting': 'runtime-errors reporting <status|enable|disable> --json',
+  'runtime-errors reporting': 'runtime-errors reporting <status|enable|disable|verify> --json',
   'bridge setup': 'bridge setup --listen <IP> [--port <49152..65535|auto>] [--dashboard|--upstream <URL>] [--hub <URL>|none] [--allow-host <host>...] --json',
   'bridge reconfigure': 'bridge reconfigure [--listen <IP>] [--port <49152..65535|auto>] [--dashboard|--upstream <URL>] [--hub <URL>|none] [--allow-host <host>...] --json',
   'bridge status': 'bridge status --json',

package/src/runtime-error-reporting.mjs

@@ -31,6 +31,8 @@ import {
  * - 受領済みにするのは、200・`accepted: true`・`report_id`一致・応答の署名一致がそろった時だけ。
  *   そろわなければ「届いたか不明」として記録を未受領のまま残し、後から今の累計を送り直す。
  * - 送るのは`runtime-errors snapshot`が出す項目だけ。message本文・path・引数・stackは記録に無い。
+ * - `reporting verify`は、記録を載せない空の報告を1通送って、合鍵・署名・受け口までの経路を確かめる。
+ *   受け口は受領を記録するだけで、issueも通知も動かない。storeの記録と受領の印には触れない。
  */
 
 const REPORT_SCHEMA_VERSION = '1.0';
@@ -275,6 +277,41 @@ function parseJson(text) {
   }
 }
 
+/**
+ * 報告を1通、署名して送り、受領を確かめる。`accepted`を返すのは、200・`accepted: true`・`report_id`一致・
+ * 応答の署名一致がそろった時だけ。戻り値に秘密・key_id・宛先は入れない。
+ */
+async function sendReport({ url, keyId, secret }, snapshot, options) {
+  const now = nowMs(options);
+  const ts = Math.floor(now / 1000);
+  // `observed_at`は、載せる記録のどの時刻よりも前にしない（BugHubは観測より後の記録を断る）。秒へ切り捨てると、
+  // 記録と同じ1秒の中で送った時に記録より前へずれる。`ts`とは同じ時刻から作り、差はBugHubの許す幅（10分）に収まる。
+  const observed = Math.max(now, ...snapshot.runtime_errors.map((record) => Date.parse(record.last_seen)),
+    ...snapshot.resolutions.map((resolution) => Date.parse(resolution.resolved_at)));
+  const report = buildRuntimeErrorReport({ snapshot, version: options.version ?? 'unknown',
+    reportId: options.reportId ?? randomUUID(), observedAt: new Date(observed).toISOString() });
+  const bodyBytes = Buffer.from(JSON.stringify(report), 'utf8');
+  if (bodyBytes.length > REPORT_MAX_BYTES) return { outcome: 'too_large', reason: 'report_too_large', http_status: null };
+
+  const response = await post(url, {
+    'Content-Type': 'application/json',
+    'Content-Length': String(bodyBytes.length),
+    Authorization: `BugHub-HMAC-SHA256 key_id=${keyId}, ts=${ts}, sig=${signReport(secret, String(ts), bodyBytes)}`,
+  }, bodyBytes, options.timeoutMs ?? REQUEST_TIMEOUT_MS);
+
+  if (response.status === null) return { outcome: 'unconfirmed', reason: response.reason, http_status: null };
+  const body = parseJson(response.body);
+  if (response.status === 200) {
+    if (body === null || body.accepted !== true || body.report_id !== report.report_id
+      || !receiptSignatureMatches(secret, report.report_id, body.received_at, body.sig)) {
+      return { outcome: 'unconfirmed', reason: 'receipt_not_verified', http_status: 200 };
+    }
+    return { outcome: 'accepted', reason: null, http_status: 200 };
+  }
+  const code = typeof body?.error === 'string' && REJECTION_CODE.test(body.error) ? body.error : 'unrecognized_response';
+  return { outcome: response.status >= 500 ? 'unconfirmed' : 'rejected', reason: code, http_status: response.status };
+}
+
 /**
  * 未受領の記録を1回送る。`options.auto`の時だけ送る時機の制限を見る（手で打った`report`は見ない
  * ——多すぎればBugHubが429で断る）。戻り値に秘密・key_id・宛先は入れない。
@@ -305,13 +342,6 @@ export async function reportRuntimeErrors(options = {}) {
     if (reason !== null) return result('throttled', { reason });
   }
 
-  // `ts`と`observed_at`は同じ時刻から作る（BugHubは10分より離れた組を断る）。
-  const ts = Math.floor(nowMs(options) / 1000);
-  const report = buildRuntimeErrorReport({ snapshot: pending, version: options.version ?? 'unknown',
-    reportId: options.reportId ?? randomUUID(), observedAt: new Date(ts * 1000).toISOString() });
-  const bodyBytes = Buffer.from(JSON.stringify(report), 'utf8');
-  if (bodyBytes.length > REPORT_MAX_BYTES) return result('rejected', { reason: 'report_too_large', sent });
-
   const finish = (outcome, extra = {}) => {
     try {
       writeDelivery(options, { schema: DELIVERY_SCHEMA, last_attempt_at: new Date(nowMs(options)).toISOString(),
@@ -320,31 +350,33 @@ export async function reportRuntimeErrors(options = {}) {
     return result(outcome, { sent, acknowledged_through: pending.cursor.acknowledged_through, ...extra });
   };
 
-  const { credential: { url, keyId, secret } } = credential;
-  const response = await post(url, {
-    'Content-Type': 'application/json',
-    'Content-Length': String(bodyBytes.length),
-    Authorization: `BugHub-HMAC-SHA256 key_id=${keyId}, ts=${ts}, sig=${signReport(secret, String(ts), bodyBytes)}`,
-  }, bodyBytes, options.timeoutMs ?? REQUEST_TIMEOUT_MS);
-
-  if (response.status === null) return finish('unconfirmed', { reason: response.reason });
-  const body = parseJson(response.body);
-  if (response.status === 200) {
-    if (body === null || body.accepted !== true || body.report_id !== report.report_id
-      || !receiptSignatureMatches(secret, report.report_id, body.received_at, body.sig)) {
-      return finish('unconfirmed', { reason: 'receipt_not_verified', http_status: 200 });
-    }
-    try {
-      const acknowledged = acknowledgeRuntimeErrors(pending.cursor.next, options);
-      return finish('delivered', { http_status: 200, acknowledged_through: acknowledged.cursor.acknowledged_through });
-    } catch {
-      // 届いているが受領済みを残せなかった。次の送信が同じ累計を送り直す（BugHubは二重に数えない）。
-      return finish('unconfirmed', { reason: 'ack_not_recorded', http_status: 200 });
-    }
+  const answer = await sendReport(credential.credential, pending, options);
+  if (answer.outcome === 'too_large') return result('rejected', { reason: 'report_too_large', sent });
+  if (answer.outcome !== 'accepted') return finish(answer.outcome, { reason: answer.reason, http_status: answer.http_status });
+  try {
+    const acknowledged = acknowledgeRuntimeErrors(pending.cursor.next, options);
+    return finish('delivered', { http_status: 200, acknowledged_through: acknowledged.cursor.acknowledged_through });
+  } catch {
+    // 届いているが受領済みを残せなかった。次の送信が同じ累計を送り直す（BugHubは二重に数えない）。
+    return finish('unconfirmed', { reason: 'ack_not_recorded', http_status: 200 });
   }
-  const code = typeof body?.error === 'string' && REJECTION_CODE.test(body.error) ? body.error : 'unrecognized_response';
-  if (response.status >= 500) return finish('unconfirmed', { reason: code, http_status: response.status });
-  return finish('rejected', { reason: code, http_status: response.status });
+}
+
+/**
+ * 記録を載せない空の報告を1通送り、合鍵・署名・受け口までの経路を確かめる（`reporting verify`）。
+ * 送る条件は`report`と同じで、送信を有効にしていない端末と合鍵の無い端末はnetworkへ触れない。
+ * storeの記録・受領の印・送る時機の記録には触れない。受け口は端末×製品ごとに1分に1回まで受けるので、
+ * 直前に送っていれば429で断られる。
+ */
+export async function verifyRuntimeErrorReporting(options = {}) {
+  if (!runtimeErrorCollectionSupported(options)) return result('unsupported');
+  if (!runtimeErrorReportingEnabled(options)) return result('disabled');
+  const credential = readProductCredential(options);
+  if (credential.status === 'missing') return result('credential_missing');
+  if (credential.status !== 'ok') return result('credential_unsafe', { reason: credential.reason });
+  const answer = await sendReport(credential.credential, { runtime_errors: [], resolutions: [] }, options);
+  if (answer.outcome === 'accepted') return result('verified', { http_status: 200 });
+  return result(answer.outcome, { reason: answer.reason, http_status: answer.http_status });
 }
 
 /**

package/src/runtime-errors.mjs

@@ -5,6 +5,8 @@ import {
 import { homedir, platform as hostPlatform, arch as hostArch } from 'node:os';
 import { dirname, join } from 'node:path';
 
+import { READ_ONLY_COMMAND_KINDS } from './cli-command-kind.mjs';
+import { cliFailureClass, failureCauseChain } from './cli-failure-class.mjs';
 import {
   daclIsOwnerOnly, daclIsProtected, isAclScratchName, readWindowsDacl, restrictWindowsDirToOwner, windowsSelfSid,
 } from './windows-owner-only.mjs';
@@ -40,6 +42,9 @@ const definitions = Object.freeze({
   'LATTICE.RUN_STORE_IO_FAILED': { component: 'run_store', severity: 'high', template: 'Lattice run store IO failed' },
   'LATTICE.EVENT_CHAIN_INTEGRITY_FAILED': { component: 'event_store', severity: 'high', template: 'Lattice run event chain integrity check failed' },
   'LATTICE.CLI_INTERNAL_FAILED': { component: 'cli', severity: 'high', template: 'Lattice CLI crashed outside the typed error contract' },
+  // 通信の失敗が型つき契約の外へ漏れた記録（ADR 0196）。直すのは回線ではなく、その面の通信失敗の受け方。
+  // 重大度は下の`severityOf`が、落ちた面で失うものがあるかで決める。
+  'LATTICE.CLI_TRANSPORT_UNHANDLED': { component: 'cli', severity: 'high', template: 'Lattice CLI let a communication failure escape the typed error contract' },
   'LATTICE.MCP_SERVER_FAILED': { component: 'mcp', severity: 'high', template: 'Lattice MCP server failed' },
 });
 
@@ -169,13 +174,28 @@ const validSafeContext = (value) => plain(value) && exact(value, SAFE_CONTEXT_KE
  */
 export function runtimeErrorSafeContext({ commandKind, error } = {}) {
   const errorKind = error?.constructor?.name;
+  // `fetch failed`のように、codeを`cause`の側に持つ例外がある。連なりの中で最初に語彙へ合うcodeを載せる。
+  const causeCode = failureCauseChain(error).map((entry) => entry.code)
+    .find((code) => typeof code === 'string' && CAUSE_CODE.test(code));
   return {
     command_kind: validCommandKind(commandKind) ? commandKind : 'other',
     error_kind: ERROR_KINDS.has(errorKind) ? errorKind : 'other',
-    cause_code: typeof error?.code === 'string' && CAUSE_CODE.test(error.code) ? error.code : 'none',
+    cause_code: causeCode ?? 'none',
   };
 }
 
+/**
+ * 記録の重大度。error_codeだけでは決めない記録がある（ADR 0196）: 通信の失敗が漏れた記録は、落ちた面が
+ * 何も書き換えないと確かめてある時だけ`warn`——その1回が止まっただけで、失うものが無く、打ち直せば戻る。
+ * 書き換える面と、確かめていない面は`high`のまま（結果が分からず、不整合や重複を否定できない）。
+ * 分類と面から決まる値なので、同じfingerprintの記録は必ず同じ重大度になる。
+ */
+function severityOf(code, safeContext = null) {
+  if (code === 'LATTICE.CLI_TRANSPORT_UNHANDLED' && safeContext !== null
+    && READ_ONLY_COMMAND_KINDS.has(safeContext.command_kind)) return 'warn';
+  return definitions[code].severity;
+}
+
 /**
  * 旧記録（safe_context無し）はerror_codeだけで決まる式のまま。新しい記録は3つの分類も含める
  * ——原因が違えば別の記録になる。式はdotagentsのadapterが再計算して照合する契約で、
@@ -269,7 +289,7 @@ function validate(store) {
     const definition = definitions[record.error_code];
     if (!definition || record.product !== PRODUCT || !validVersion(record.product_version)
       || record.component !== definition.component || record.message_template !== definition.template
-      || record.severity !== definition.severity || record.fingerprint !== fingerprintOf(record.error_code, safeContext)
+      || record.severity !== severityOf(record.error_code, safeContext) || record.fingerprint !== fingerprintOf(record.error_code, safeContext)
       || seen.has(record.fingerprint) || !Number.isSafeInteger(record.count) || record.count < 1
       || !validTime(record.first_seen) || !validTime(record.last_seen)
       || Date.parse(record.first_seen) > Date.parse(record.last_seen)
@@ -442,7 +462,7 @@ export function recordRuntimeError(code, options = {}) {
       if (store.records.length >= MAX_RECORDS) throw Error('store_overflow');
       store.records.push({
         product: PRODUCT, product_version: version, component: definition.component, error_code: code,
-        message_template: definition.template, severity: definition.severity, fingerprint: key,
+        message_template: definition.template, severity: severityOf(code, safeContext), fingerprint: key,
         count: 1, first_seen: time, last_seen: time, state_schema_version: STATE_VERSION,
         os, arch, status: 'open', resolved_at: null, reason_code: null, sequence,
         safe_context: { ...safeContext },
@@ -462,6 +482,17 @@ export function observeRuntimeError(code, options = {}) {
   }
 }
 
+/**
+ * CLIのtyped契約の外へ漏れた例外を記録する（process境界のbinが呼ぶ）。取消は故障ではないので記録しない。
+ * 通信の失敗が漏れたものは内部故障と別の記録にし、重大度を面で決める（ADR 0196）。
+ */
+export function observeEscapedCliFailure({ error, commandKind, ...options }) {
+  const failureClass = cliFailureClass(error);
+  if (failureClass === 'cancelled') return;
+  observeRuntimeError(failureClass === 'transport' ? 'LATTICE.CLI_TRANSPORT_UNHANDLED' : 'LATTICE.CLI_INTERNAL_FAILED',
+    { ...options, safeContext: runtimeErrorSafeContext({ commandKind, error }) });
+}
+
 export function acknowledgeRuntimeErrors(cursor, options = {}) {
   requireCursor(cursor);
   if (!collectionEnabled(options)) return snapshot({ ...options, afterCursor: cursor });

package/src/todo-cli.mjs

@@ -1,4 +1,5 @@
 import { cliCommandKind } from './cli-command-kind.mjs';
+import { cliFailureClass } from './cli-failure-class.mjs';
 import { gitSync } from './git-process.mjs';
 import { createHash } from 'node:crypto';
 import {
@@ -4253,7 +4254,8 @@ export async function runTodoCli({ argv, cwd, stdout, stderr, env = process.env,
   } catch (error) {
     if (error instanceof TodoStoreError || (typeof error?.code === 'string'
       && error.detail !== null && typeof error.detail === 'object')) return typedFailure(stderr, error);
-    if (error instanceof TypeError) {
+    // 漏れた`fetch failed`もTypeErrorで届く。呼び出し側の契約違反と答えず、内部故障として観測口へ渡す。
+    if (error instanceof TypeError && cliFailureClass(error) !== 'transport') {
       return typedFailure(stderr, {
         code: 'CONTRACT_VIOLATION',
         message: error.message,