@quolu/lattice 0.12.22 → 0.12.24

package/docs/schemas/lattice.runtime_adapter_registration_input.v1.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kitepon-rgb/Lattice/blob/main/docs/schemas/lattice.runtime_adapter_registration_input.v1.schema.json",
+  "title": "lattice.runtime_adapter_registration_input.v1",
+  "description": "lattice run adapter register の入力契約。digestと固定capabilitiesはCLIが導出する。",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "adapter_kind",
+        "launch_kind",
+        "binary_path",
+        "argv",
+        "config_ref"
+      ],
+      "properties": {
+        "schema": {
+          "const": "lattice.runtime_adapter_registration_input.v1"
+        },
+        "adapter_kind": {
+          "$ref": "#/$defs/identifier"
+        },
+        "launch_kind": {
+          "const": "host_binary"
+        },
+        "binary_path": {
+          "type": "string",
+          "pattern": "^/"
+        },
+        "argv": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "type": "string",
+            "pattern": "^[^\\u0000]*$"
+          }
+        },
+        "config_ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "adapter_kind",
+        "launch_kind",
+        "endpoint"
+      ],
+      "properties": {
+        "schema": {
+          "const": "lattice.runtime_adapter_registration_input.v1"
+        },
+        "adapter_kind": {
+          "$ref": "#/$defs/identifier"
+        },
+        "launch_kind": {
+          "const": "existing_endpoint"
+        },
+        "endpoint": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/lattice",
-  "version": "0.12.22",
+  "version": "0.12.24",
   "description": "Lattice — phase-aware TODO graph compiler and conflict-aware orchestration runtime",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "docs/schemas/lattice.run_request.v1.schema.json",
     "docs/schemas/lattice.executor_packet.v1.schema.json",
     "docs/schemas/lattice.executor_receipt.v1.schema.json",
+    "docs/schemas/lattice.runtime_adapter_registration_input.v1.schema.json",
     "docs/bridge-setup.md",
     "sensor/dist",
     "!sensor/dist/bin/lattice-sensor.*",
@@ -57,7 +58,7 @@
     "test": "node scripts/run-product-tests.mjs",
     "test:sensor": "npm --prefix sensor test",
     "precheck": "node --check src/bridge-launch-agent.mjs",
-    "check": "node --check bin/lattice.mjs && node --check bin/lattice-mcp.mjs && node --check bin/lattice-dashboard.mjs && node --check bin/lattice-bridge.mjs && node --check src/cli-stdio.mjs && node --check src/bridge-address.mjs && node --check src/bridge-registrar.mjs && node --check src/todo-gantt-layout.mjs && node --check src/todo-gantt-scope.mjs && node --check src/bridge-config.mjs && node --check src/bridge-server.mjs && node --check src/bridge-daemon.mjs && node --check src/bridge-cli.mjs && node --check src/project-cli.mjs && node --check src/sensor-cli.mjs && node --check src/sensor-runtime.mjs && node --check src/sensor-adapter.mjs && node --check src/factory-diagnostics.mjs && node --check src/runtime-errors.mjs && node --check src/runtime-contracts.mjs && node --check src/runtime-event-store.mjs && node --check src/hash-chain.mjs && node --check src/dag-chain.mjs && node --check src/todo-contracts.mjs && node --check src/todo-chain.mjs && node --check src/todo-store.mjs && node --check src/todo-migration.mjs && node --check src/todo-revision.mjs && node --check src/todo-status.mjs && node --check src/todo-cli.mjs && node --check src/todo-dashboard-registry.mjs && node --check src/todo-gantt-presentation.mjs && node --check src/todo-gantt-live.mjs && node --check src/bounded-seam.mjs && node --check src/todo-narrative-anchor.mjs && node --check src/todo-markdown-renderer.mjs && node --check src/todo-gantt-svg.mjs && node --check src/todo-gantt-html.mjs && node --check src/runtime-projection.mjs && node --check src/runtime-decision-verifier.mjs && node --check src/runtime-front-end.mjs && node --check src/runtime-cli.mjs && node --check src/rc3-dogfood-scaffold.mjs && node --check src/runtime-engine.mjs && node --check src/runtime-scripted-executor.mjs && node --check src/runtime-diff-observer.mjs && node --check src/runtime-worktree-executor.mjs && node --check src/runtime-hold-recompile.mjs && node --check src/rc3-scripted-campaign.mjs && node --check src/rc3-actual-dogfood.mjs && node --check src/rc4-stage1-dogfood.mjs && node --check research/fixtures/dispatch-record/src/dispatch-record.mjs && node --check test/research-dispatch-record.test.mjs",
+    "check": "node --check bin/lattice.mjs && node --check bin/lattice-mcp.mjs && node --check bin/lattice-dashboard.mjs && node --check bin/lattice-bridge.mjs && node --check src/cli-stdio.mjs && node --check src/bridge-address.mjs && node --check src/bridge-registrar.mjs && node --check src/todo-gantt-layout.mjs && node --check src/todo-gantt-scope.mjs && node --check src/bridge-config.mjs && node --check src/bridge-server.mjs && node --check src/bridge-daemon.mjs && node --check src/bridge-cli.mjs && node --check src/project-cli.mjs && node --check src/sensor-cli.mjs && node --check src/sensor-runtime.mjs && node --check src/sensor-adapter.mjs && node --check src/factory-diagnostics.mjs && node --check src/runtime-errors.mjs && node --check src/runtime-contracts.mjs && node --check src/runtime-event-store.mjs && node --check src/runtime-adapter-registry.mjs && node --check src/hash-chain.mjs && node --check src/dag-chain.mjs && node --check src/todo-contracts.mjs && node --check src/todo-chain.mjs && node --check src/todo-store.mjs && node --check src/todo-migration.mjs && node --check src/todo-revision.mjs && node --check src/todo-status.mjs && node --check src/todo-cli.mjs && node --check src/todo-dashboard-registry.mjs && node --check src/todo-gantt-presentation.mjs && node --check src/todo-gantt-live.mjs && node --check src/bounded-seam.mjs && node --check src/todo-narrative-anchor.mjs && node --check src/todo-markdown-renderer.mjs && node --check src/todo-gantt-svg.mjs && node --check src/todo-gantt-html.mjs && node --check src/runtime-projection.mjs && node --check src/runtime-decision-verifier.mjs && node --check src/runtime-front-end.mjs && node --check src/runtime-cli.mjs && node --check src/rc3-dogfood-scaffold.mjs && node --check src/runtime-engine.mjs && node --check src/runtime-scripted-executor.mjs && node --check src/runtime-diff-observer.mjs && node --check src/runtime-worktree-executor.mjs && node --check src/runtime-hold-recompile.mjs && node --check src/rc3-scripted-campaign.mjs && node --check src/rc3-actual-dogfood.mjs && node --check src/rc4-stage1-dogfood.mjs && node --check research/fixtures/dispatch-record/src/dispatch-record.mjs && node --check test/research-dispatch-record.test.mjs",
     "check:project-identity": "node --check src/project-identity.mjs",
     "ci": "npm run test && npm run test:sensor && npm run check && npm run check:project-identity"
   }

package/src/cli-help.mjs

@@ -32,6 +32,9 @@ Commands:
 Commands:
   start --request <request.json> --executor <adapter>
   start --schema --json              # lattice.run_request.v1 の JSON Schema を出す
+  adapter register --input <descriptor.json>
+  adapter register --schema --json   # 登録入力の JSON Schema を出す
+  adapter list --json
   observe --run .lattice/runs/<id>
   status --run .lattice/runs/<id>
   resume --run .lattice/runs/<id>
@@ -103,6 +106,8 @@ const SUBCOMMAND_USAGE = Object.freeze({
   'plan compile': 'plan compile --request <request.json> | --schema --json',
   'plan verify': 'plan verify --request <request.json> --plan <plan.json>',
   'run start': 'run start --request <request.json> --executor <adapter> | --schema --json',
+  'run adapter register': 'run adapter register --input <descriptor.json> | --schema --json',
+  'run adapter list': 'run adapter list --json',
   'run observe': 'run observe --run .lattice/runs/<id>',
   'run status': 'run status --run .lattice/runs/<id>',
   'run resume': 'run resume --run .lattice/runs/<id>',

package/src/runtime-adapter-registry.mjs

@@ -0,0 +1,506 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+import { canonicalizeArtifact } from './artifact-contracts.mjs';
+import {
+  CONTROLLER_OPERATIONS,
+  validateAdapterLaunchDescriptor,
+  validateAdapterRegistry,
+  validateRuntimeAdapterCapabilities,
+} from './runtime-controller-protocol.mjs';
+import { selfDigest } from './runtime-contracts.mjs';
+import { observeMacosBinaryIdentity } from './runtime-managed-supervisor.mjs';
+
+const INPUT_SCHEMA = 'lattice.runtime_adapter_registration_input.v1';
+const REGISTRY_SCHEMA = 'lattice.runtime_adapter_registry.v1';
+const DESCRIPTOR_SCHEMA = 'lattice.runtime_adapter_launch_descriptor.v1';
+const REGISTRY_REF = '.lattice/runtime/adapter-registry/registry.json';
+const DESCRIPTOR_ROOT_REF = '.lattice/runtime/adapter-registry/descriptors';
+const ID = /^[0-9A-Za-z](?:[0-9A-Za-z._-]{0,127})$/u;
+
+export class AdapterRegistryError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'AdapterRegistryError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+function fail(code, message, detail) {
+  throw new AdapterRegistryError(code, message, detail);
+}
+
+function sha256Bytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function exact(value, fields) {
+  if (!plain(value)) return false;
+  const actual = Object.keys(value).sort();
+  const expected = [...fields].sort();
+  return actual.length === expected.length
+    && actual.every((field, index) => field === expected[index]);
+}
+
+function inputFailure(reason, inputPath = '') {
+  fail(
+    'INVALID_ADAPTER_REGISTRATION_INPUT',
+    'adapter registration inputが公開契約を満たさない',
+    { reason, path: inputPath },
+  );
+}
+
+function validateRegistrationInput(value) {
+  if (!plain(value)) inputFailure('input_must_be_object');
+  if (value.schema !== INPUT_SCHEMA) inputFailure('unsupported_schema', '/schema');
+  if (!ID.test(value.adapter_kind ?? '')) inputFailure('invalid_adapter_kind', '/adapter_kind');
+  if (value.launch_kind === 'host_binary') {
+    if (!exact(value, ['schema', 'adapter_kind', 'launch_kind', 'binary_path', 'argv', 'config_ref'])) {
+      inputFailure('unexpected_or_missing_keys');
+    }
+    if (typeof value.binary_path !== 'string' || !path.isAbsolute(value.binary_path)) {
+      inputFailure('binary_path_must_be_absolute', '/binary_path');
+    }
+    if (!Array.isArray(value.argv) || value.argv.length > 64
+      || !value.argv.every((arg) => typeof arg === 'string' && !arg.includes('\0'))) {
+      inputFailure('invalid_argv', '/argv');
+    }
+    if (typeof value.config_ref !== 'string' || value.config_ref.length === 0) {
+      inputFailure('invalid_config_ref', '/config_ref');
+    }
+    return;
+  }
+  if (value.launch_kind === 'existing_endpoint') {
+    if (!exact(value, ['schema', 'adapter_kind', 'launch_kind', 'endpoint'])) {
+      inputFailure('unexpected_or_missing_keys');
+    }
+    if (typeof value.endpoint !== 'string' || value.endpoint.length === 0) {
+      inputFailure('invalid_endpoint', '/endpoint');
+    }
+    // activateはendpointへ絶対pathを要求する（ADAPTER_LAUNCH_INVALID）。登録時点で
+    // 確定する条件をここで揃え、「登録できたのにactivateできない」descriptorを作らせない。
+    // 親directoryがcanonicalかはactivate時にしか判定できないため、そこは動的検査へ残す。
+    if (!path.isAbsolute(value.endpoint)) {
+      inputFailure('endpoint_must_be_absolute', '/endpoint');
+    }
+    return;
+  }
+  inputFailure('unsupported_launch_kind', '/launch_kind');
+}
+
+function createCapabilities() {
+  const capabilities = {
+    schema: 'lattice.runtime_adapter_capabilities.v1',
+    operations: [...CONTROLLER_OPERATIONS],
+    process_observation: true,
+    worktree_fingerprint: true,
+    staged_write_lease: true,
+    durable_dispatch: true,
+    capabilities_digest: '',
+  };
+  capabilities.capabilities_digest = selfDigest(capabilities, 'capabilities_digest');
+  if (!validateRuntimeAdapterCapabilities(capabilities)) {
+    throw new TypeError('runtime adapter capabilities生成不正');
+  }
+  return capabilities;
+}
+
+async function readCanonicalRegular(filePath, label) {
+  let info;
+  try {
+    info = await lstat(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw error;
+    fail('ADAPTER_REGISTRY_INVALID', `${label}を読めない`, { path: filePath, reason: 'unreadable' });
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail('ADAPTER_REGISTRY_INVALID', `${label}がregular fileではない`, {
+      path: filePath,
+      reason: 'not_regular_file',
+    });
+  }
+  let bytes;
+  try {
+    bytes = await readFile(filePath);
+  } catch {
+    fail('ADAPTER_REGISTRY_INVALID', `${label}を読めない`, { path: filePath, reason: 'unreadable' });
+  }
+  let value;
+  try {
+    value = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    fail('ADAPTER_REGISTRY_INVALID', `${label}がJSONとして不正`, {
+      path: filePath,
+      reason: 'invalid_json',
+    });
+  }
+  if (bytes.toString('utf8') !== `${canonicalizeArtifact(value)}\n`) {
+    fail('ADAPTER_REGISTRY_INVALID', `${label}がcanonical bytesではない`, {
+      path: filePath,
+      reason: 'noncanonical_bytes',
+    });
+  }
+  return { value, bytes };
+}
+
+async function durableReplaceBytes(directory, name, bytes) {
+  const temporaryPath = path.join(directory, `.${name}-${process.pid}-${randomUUID()}.tmp`);
+  let handle;
+  try {
+    handle = await open(
+      temporaryPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      0o600,
+    );
+    await handle.writeFile(bytes);
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(temporaryPath, path.join(directory, name));
+    const directoryHandle = await open(directory, fsConstants.O_RDONLY);
+    try {
+      await directoryHandle.sync();
+    } finally {
+      await directoryHandle.close();
+    }
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+    await rm(temporaryPath, { force: true }).catch(() => {});
+  }
+}
+
+async function ensureRegistryDirectories(repoRoot) {
+  const registryDir = path.join(repoRoot, '.lattice/runtime/adapter-registry');
+  const descriptorDir = path.join(registryDir, 'descriptors');
+  await mkdir(descriptorDir, { recursive: true, mode: 0o700 });
+  for (const directory of [registryDir, descriptorDir]) {
+    let observed;
+    try {
+      observed = await realpath(directory);
+    } catch {
+      fail('ADAPTER_REGISTRY_INVALID', 'adapter registry directoryを解決できない', {
+        path: directory,
+        reason: 'directory_unresolved',
+      });
+    }
+    if (observed !== directory) {
+      fail('ADAPTER_REGISTRY_INVALID', 'adapter registry directoryにsymlinkを使えない', {
+        path: directory,
+        reason: 'directory_not_canonical',
+      });
+    }
+  }
+  return { registryDir, descriptorDir };
+}
+
+async function acquireRegistryLock(registryDir) {
+  const lockPath = path.join(registryDir, '.registry.lock');
+  let handle;
+  try {
+    handle = await open(
+      lockPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      0o600,
+    );
+    await handle.writeFile(`${process.pid}\n`);
+    await handle.sync();
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    if (error?.code === 'EEXIST') {
+      fail('ADAPTER_REGISTRY_BUSY', 'adapter registryを別processが更新中', {
+        path: lockPath,
+        reason: 'lock_exists',
+      });
+    }
+    throw error;
+  }
+  return async () => {
+    await handle.close().catch(() => {});
+    await rm(lockPath, { force: true });
+  };
+}
+
+async function readRegistry(repoRoot, { missingIsEmpty }) {
+  const registryPath = path.join(repoRoot, REGISTRY_REF);
+  let artifact;
+  try {
+    artifact = await readCanonicalRegular(registryPath, 'adapter registry');
+  } catch (error) {
+    if (error?.code === 'ENOENT' && missingIsEmpty) return null;
+    if (error?.code === 'ENOENT') {
+      fail('ADAPTER_REGISTRY_INVALID', 'adapter registryが存在しない', {
+        path: registryPath,
+        reason: 'missing',
+      });
+    }
+    throw error;
+  }
+  if (!validateAdapterRegistry(artifact.value)) {
+    fail('ADAPTER_REGISTRY_INVALID', 'adapter registry contract不正', {
+      path: registryPath,
+      reason: 'contract_violation',
+    });
+  }
+  return artifact;
+}
+
+async function resolveHostBinary(repoRoot, input, binaryIdentityObserver) {
+  let binaryInfo;
+  try {
+    binaryInfo = await lstat(input.binary_path);
+  } catch {
+    inputFailure('binary_unreadable', '/binary_path');
+  }
+  if (!binaryInfo.isFile() || binaryInfo.isSymbolicLink() || (binaryInfo.mode & 0o111) === 0) {
+    inputFailure('binary_must_be_executable_regular_file', '/binary_path');
+  }
+  let binaryReal;
+  try {
+    binaryReal = await realpath(input.binary_path);
+  } catch {
+    inputFailure('binary_unreadable', '/binary_path');
+  }
+  if (binaryReal !== input.binary_path) {
+    inputFailure('binary_path_must_be_canonical', '/binary_path');
+  }
+
+  const configPath = path.resolve(repoRoot, input.config_ref);
+  if (!configPath.startsWith(`${repoRoot}${path.sep}`)) {
+    inputFailure('config_ref_outside_repo', '/config_ref');
+  }
+  let configInfo;
+  let configReal;
+  try {
+    [configInfo, configReal] = await Promise.all([lstat(configPath), realpath(configPath)]);
+  } catch {
+    inputFailure('config_unreadable', '/config_ref');
+  }
+  if (!configInfo.isFile() || configInfo.isSymbolicLink() || configReal !== configPath) {
+    inputFailure('config_must_be_canonical_regular_file', '/config_ref');
+  }
+
+  let binaryIdentity = null;
+  let observation;
+  if (process.platform !== 'darwin') {
+    observation = {
+      status: 'not_observed',
+      reason: 'platform_not_darwin',
+      message: 'macOS binary identity観測はdarwin以外では利用できない',
+    };
+  } else {
+    try {
+      binaryIdentity = await binaryIdentityObserver(binaryReal);
+      observation = { status: 'observed', reason: null, message: null };
+    } catch (error) {
+      observation = {
+        status: 'not_observed',
+        reason: 'identity_observation_failed',
+        message: error?.message ?? 'macOS binary identity観測に失敗した',
+      };
+    }
+  }
+
+  return {
+    binaryPath: binaryReal,
+    binaryDigest: sha256Bytes(await readFile(binaryReal)),
+    binaryIdentity,
+    configDigest: sha256Bytes(await readFile(configReal)),
+    observation,
+  };
+}
+
+async function buildLaunchDescriptor(repoRoot, input, binaryIdentityObserver) {
+  const capabilities = createCapabilities();
+  let observation = { status: 'not_applicable', reason: null, message: null };
+  let descriptor;
+  if (input.launch_kind === 'host_binary') {
+    const host = await resolveHostBinary(repoRoot, input, binaryIdentityObserver);
+    observation = host.observation;
+    descriptor = {
+      schema: DESCRIPTOR_SCHEMA,
+      adapter_kind: input.adapter_kind,
+      launch_kind: input.launch_kind,
+      binary_path: host.binaryPath,
+      binary_digest: host.binaryDigest,
+      binary_identity: host.binaryIdentity,
+      argv: [...input.argv],
+      config_ref: input.config_ref,
+      config_digest: host.configDigest,
+      endpoint: null,
+      capabilities_digest: capabilities.capabilities_digest,
+      descriptor_digest: '',
+    };
+  } else {
+    descriptor = {
+      schema: DESCRIPTOR_SCHEMA,
+      adapter_kind: input.adapter_kind,
+      launch_kind: input.launch_kind,
+      binary_path: null,
+      binary_digest: null,
+      binary_identity: null,
+      argv: [],
+      config_ref: null,
+      config_digest: null,
+      endpoint: input.endpoint,
+      capabilities_digest: capabilities.capabilities_digest,
+      descriptor_digest: '',
+    };
+  }
+  descriptor.descriptor_digest = selfDigest(descriptor, 'descriptor_digest');
+  // 公開入力から導出した成果物も、activationと同じ正本validatorを通過した時だけ永続化する。
+  if (!validateAdapterLaunchDescriptor(descriptor)) {
+    throw new TypeError('adapter launch descriptor生成不正');
+  }
+  return { descriptor, observation };
+}
+
+export async function registerRuntimeAdapter({
+  repoRoot,
+  input,
+  binaryIdentityObserver = observeMacosBinaryIdentity,
+}) {
+  const canonicalRepo = await realpath(repoRoot);
+  validateRegistrationInput(input);
+  const { descriptor, observation } = await buildLaunchDescriptor(
+    canonicalRepo,
+    input,
+    binaryIdentityObserver,
+  );
+  const { registryDir, descriptorDir } = await ensureRegistryDirectories(canonicalRepo);
+  const releaseLock = await acquireRegistryLock(registryDir);
+  try {
+    const current = await readRegistry(canonicalRepo, { missingIsEmpty: true });
+    const existing = current?.value.entries.find(
+      (entry) => entry.adapter_kind === input.adapter_kind,
+    );
+    const descriptorRef = `${DESCRIPTOR_ROOT_REF}/${input.adapter_kind}.json`;
+    const entry = {
+      adapter_kind: input.adapter_kind,
+      launch_descriptor_ref: descriptorRef,
+      launch_descriptor_digest: descriptor.descriptor_digest,
+    };
+    const entries = [
+      ...(current?.value.entries ?? []).filter(
+        (candidate) => candidate.adapter_kind !== input.adapter_kind,
+      ),
+      entry,
+    ].sort((left, right) => (
+      left.adapter_kind < right.adapter_kind ? -1 : left.adapter_kind > right.adapter_kind ? 1 : 0
+    ));
+    if (entries.length > 256) {
+      fail('ADAPTER_REGISTRY_LIMIT_EXCEEDED', 'adapter registryは256件を超えられない', {
+        limit: 256,
+      });
+    }
+    const registry = { schema: REGISTRY_SCHEMA, entries, registry_digest: '' };
+    registry.registry_digest = selfDigest(registry, 'registry_digest');
+    if (!validateAdapterRegistry(registry)) throw new TypeError('adapter registry生成不正');
+
+    await durableReplaceBytes(
+      descriptorDir,
+      `${input.adapter_kind}.json`,
+      Buffer.from(`${canonicalizeArtifact(descriptor)}\n`),
+    );
+    await durableReplaceBytes(
+      registryDir,
+      'registry.json',
+      Buffer.from(`${canonicalizeArtifact(registry)}\n`),
+    );
+
+    const result = {
+      schema: 'lattice.runtime_adapter_register_result.v1',
+      outcome: existing === undefined ? 'created' : 'replaced',
+      adapter_kind: input.adapter_kind,
+      launch_descriptor_ref: descriptorRef,
+      launch_descriptor_digest: descriptor.descriptor_digest,
+      registry_ref: REGISTRY_REF,
+      registry_digest: registry.registry_digest,
+      binary_identity_observation: observation,
+      result_digest: '',
+    };
+    result.result_digest = selfDigest(result, 'result_digest');
+    return result;
+  } finally {
+    await releaseLock();
+  }
+}
+
+export async function listRuntimeAdapters({ repoRoot }) {
+  const canonicalRepo = await realpath(repoRoot);
+  const registryArtifact = await readRegistry(canonicalRepo, { missingIsEmpty: true });
+  const adapters = [];
+  for (const entry of registryArtifact?.value.entries ?? []) {
+    const descriptorPath = path.join(canonicalRepo, entry.launch_descriptor_ref);
+    if (!descriptorPath.startsWith(`${canonicalRepo}${path.sep}`)) {
+      fail('ADAPTER_REGISTRY_INVALID', 'launch descriptorがrepo外を指す', {
+        path: descriptorPath,
+        reason: 'descriptor_outside_repo',
+      });
+    }
+    let artifact;
+    try {
+      artifact = await readCanonicalRegular(descriptorPath, 'adapter launch descriptor');
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        fail('ADAPTER_REGISTRY_INVALID', 'adapter launch descriptorが存在しない', {
+          path: descriptorPath,
+          reason: 'descriptor_missing',
+        });
+      }
+      throw error;
+    }
+    const descriptor = artifact.value;
+    if (!validateAdapterLaunchDescriptor(descriptor)
+      || descriptor.adapter_kind !== entry.adapter_kind
+      || descriptor.descriptor_digest !== entry.launch_descriptor_digest) {
+      fail('ADAPTER_REGISTRY_INVALID', 'adapter launch descriptor binding不正', {
+        path: descriptorPath,
+        reason: 'descriptor_binding_invalid',
+      });
+    }
+    adapters.push({
+      adapter_kind: descriptor.adapter_kind,
+      launch_kind: descriptor.launch_kind,
+      launch_descriptor_ref: entry.launch_descriptor_ref,
+      launch_descriptor_digest: descriptor.descriptor_digest,
+      binary_path: descriptor.binary_path,
+      binary_identity_observed: descriptor.binary_identity !== null,
+      argv: [...descriptor.argv],
+      config_ref: descriptor.config_ref,
+      endpoint: descriptor.endpoint,
+      capabilities_digest: descriptor.capabilities_digest,
+    });
+  }
+  const result = {
+    schema: 'lattice.runtime_adapter_list_result.v1',
+    registry_ref: REGISTRY_REF,
+    registry_digest: registryArtifact?.value.registry_digest ?? null,
+    adapters,
+    result_digest: '',
+  };
+  result.result_digest = selfDigest(result, 'result_digest');
+  return result;
+}
+
+export const runtimeAdapterRegistryInternal = Object.freeze({
+  INPUT_SCHEMA,
+  REGISTRY_REF,
+  validateRegistrationInput,
+  createCapabilities,
+});

package/src/runtime-cli.mjs

@@ -68,6 +68,11 @@ import { createRuntimeControlRequest, validateRuntimeControlResponse } from './r
 import { createRuntimeControlStore } from './runtime-control-store.mjs';
 import { createRuntimeGateStore } from './runtime-gate-store.mjs';
 import { acquireRuntimeLifecycleLock } from './runtime-lifecycle-lock.mjs';
+import {
+  AdapterRegistryError,
+  listRuntimeAdapters,
+  registerRuntimeAdapter,
+} from './runtime-adapter-registry.mjs';
 import {
   ManagedRuntimeError,
   launchDurableSupervisor,
@@ -84,6 +89,8 @@ import {
  *   lattice plan compile --request <run-request.json>
  *   lattice plan verify  --request <run-request.json> --plan <plan.json>
  *   lattice run start    --request <run-request.json> --executor <adapter>
+ *   lattice run adapter register --input <descriptor.json>
+ *   lattice run adapter list --json
  *   lattice run observe  --run .lattice/runs/<run-id>
  *   lattice run status   --run .lattice/runs/<run-id>
  *   lattice run resume   --run .lattice/runs/<run-id>
@@ -262,6 +269,58 @@ async function runRequestSchema({ stdout }) {
   return 0;
 }
 
+/** 公開登録入力を推測させないため、配布物に同梱したJSON Schemaをそのまま返す（ADR 0125）。 */
+async function runAdapterRegisterSchema({ stdout }) {
+  const schemaUrl = new URL(
+    '../docs/schemas/lattice.runtime_adapter_registration_input.v1.schema.json',
+    import.meta.url,
+  );
+  const schema = JSON.parse(await readFile(schemaUrl, 'utf8'));
+  if (schema?.title !== 'lattice.runtime_adapter_registration_input.v1') {
+    throw new CliContractError('CONTRACT_VIOLATION', '同梱adapter registration input schemaが不正');
+  }
+  stdout.write(`${JSON.stringify(schema)}\n`);
+  return 0;
+}
+
+async function runAdapterRegister({ cwd, inputPath, stdout }) {
+  try {
+    const repoRoot = await resolveRepoRoot(cwd);
+    const input = await readBoundedJson(inputPath, 'adapter registration input');
+    const result = await registerRuntimeAdapter({ repoRoot, input });
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof AdapterRegistryError) throw error;
+    if (error instanceof CliContractError) {
+      if (error.detail !== undefined) throw error;
+      throw new CliContractError(error.code, error.message, {
+        path: inputPath,
+        reason: error.code.toLowerCase(),
+      });
+    }
+    throw new CliContractError('ADAPTER_REGISTRY_WRITE_FAILED', 'adapter registryを書けない', {
+      path: '.lattice/runtime/adapter-registry/registry.json',
+      reason: typeof error?.code === 'string' ? error.code : 'unexpected_write_failure',
+    });
+  }
+}
+
+async function runAdapterList({ cwd, stdout }) {
+  try {
+    const repoRoot = await resolveRepoRoot(cwd);
+    const result = await listRuntimeAdapters({ repoRoot });
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof AdapterRegistryError || error instanceof CliContractError) throw error;
+    throw new CliContractError('ADAPTER_REGISTRY_READ_FAILED', 'adapter registryを読めない', {
+      path: '.lattice/runtime/adapter-registry/registry.json',
+      reason: typeof error?.code === 'string' ? error.code : 'unexpected_read_failure',
+    });
+  }
+}
+
 async function loadRequest(requestPath) {
   const request = await readBoundedJson(requestPath, 'run request');
   const verdict = explainRunRequest(request);
@@ -1230,6 +1289,20 @@ export function reconstructHoldResultFromJournal({ journal, runId, requestId, in
   return result;
 }
 
+/** 現在registryが持つadapter kindを返す。registryが無ければ空配列（推測で埋めない）。 */
+async function registeredAdapterKinds(repoRoot) {
+  try {
+    const registry = JSON.parse(await readFile(
+      path.join(repoRoot, '.lattice/runtime/adapter-registry/registry.json'), 'utf8',
+    ));
+    if (!Array.isArray(registry?.entries)) return [];
+    return registry.entries
+      .map((entry) => entry?.adapter_kind)
+      .filter((kind) => typeof kind === 'string')
+      .sort();
+  } catch { return []; }
+}
+
 async function runActivate({ runDir, runRef, repoRoot, stdout, requestId = null }) {
   return withLifecycleLock(runDir, async () => {
   const { events, meta, managed } = await readRunStore(runDir);
@@ -1280,6 +1353,17 @@ async function runActivate({ runDir, runRef, repoRoot, stdout, requestId = null
       }
       await new Promise((resolve) => setTimeout(resolve, 20));
     }
+    // ADAPTER_NOT_REGISTEREDは「registryが無い／そのadapterのentryが無い」だけを意味し、
+    // 何をどこへ置けば解決するかをそれ自体は伝えない。行き止まりにしないため、
+    // 必要な成果物と現在registryが持つadapterを返す（ADR 0123と同じdiagnosability規律）。
+    if (code === 'ADAPTER_NOT_REGISTERED') {
+      throw new CliContractError(code, `managed activateが${response.outcome}で終了した: ${response.result?.unmet?.[1] ?? code}`, {
+        adapter_kind: meta?.executor_adapter ?? null,
+        required_artifact: '.lattice/runtime/adapter-registry/registry.json',
+        registered_adapters: await registeredAdapterKinds(repoRoot),
+        reason: 'run activateは登録済みexecutor adapterを要求する。run adapter registerで登録する',
+      });
+    }
     throw new CliContractError(code, `managed activateが${response.outcome}で終了した: ${response.result?.unmet?.[1] ?? code}`);
   }
   // daemonがpointerまでcommitしたことを再読してから成功を返す。
@@ -2778,6 +2862,22 @@ export async function runRuntimeCli({ argv, cwd, stdout, stderr }) {
     && argv[0] === 'plan' && argv[1] === 'compile'
     && argv[2] === '--schema' && argv[3] === '--json') {
     action = () => runRequestSchema({ stdout });
+  } else if (argv.length === 5
+    && argv[0] === 'run' && argv[1] === 'adapter' && argv[2] === 'register'
+    && argv[3] === '--schema' && argv[4] === '--json') {
+    action = () => runAdapterRegisterSchema({ stdout });
+  } else if (argv.length === 5
+    && argv[0] === 'run' && argv[1] === 'adapter' && argv[2] === 'register'
+    && argv[3] === '--input' && typeof argv[4] === 'string' && argv[4].length > 0) {
+    action = () => runAdapterRegister({
+      cwd,
+      inputPath: path.resolve(cwd, argv[4]),
+      stdout,
+    });
+  } else if (argv.length === 4
+    && argv[0] === 'run' && argv[1] === 'adapter' && argv[2] === 'list'
+    && argv[3] === '--json') {
+    action = () => runAdapterList({ cwd, stdout });
   } else if (argv.length === 4
     && argv[0] === 'run' && argv[1] === 'start'
     && argv[2] === '--schema' && argv[3] === '--json') {
@@ -2912,6 +3012,9 @@ export async function runRuntimeCli({ argv, cwd, stdout, stderr }) {
     if (error instanceof RuntimeEpochStoreError) {
       return typedFailure(stderr, error.code, error.message);
     }
+    if (error instanceof AdapterRegistryError) {
+      return typedFailure(stderr, error.code, error.message, error.detail);
+    }
     if (error instanceof ManagedRuntimeError) {
       return typedFailure(stderr, error.code, error.message);
     }