akari-video 0.1.2 → 0.1.4

package/README.md

@@ -21,13 +21,40 @@ akari
   │     .akari/connections.json の doctor ブロックを更新・表示する
   │     （キーの値は一切表示しない）
   │
-  └─ 4. 最後に opencode を exec する
+  ├─ 4. 公式音源ライブラリ（AKARI Sounds）の初回セットアップ（src/sounds-setup.mjs）:
+  │     未導入かつ TTY のとき生涯 1 回だけ [Y/n]（既定 Yes）を聞き、Yes なら
+  │     packages/audio-library-setup/bin/fetch-akari-sounds.mjs で一括ダウンロード。
+  │     n は marker（~/.akari/assets/audio/.akari-sounds-declined.json）を書いて以後
+  │     聞かない。再入口は `akari sounds`。失敗しても起動は止めない
+  │
+  └─ 5. 最後に opencode を exec する
         （PATH に opencode が無ければ、インストール案内を出して終了する）
 ```
 
+サブコマンド: `akari update`（更新確認）/ `akari init`（作業場の作成・確認のみ）/
+`akari sounds [--variant wav] [--force]`（公式音源の一括ダウンロード。プロンプトなし・headless 可）/
+`akari store <connect|status|download|disconnect>`（AKARI Store 連携。マイページで発行した
+接続トークンを `~/.akari/store-credentials.json`（0600）に保存し、購入済み一覧の確認と
+配布物の取得ができる。`src/store-command.mjs`）。
+
 `akari` に渡した引数はそのまま `opencode` に転送する（例: `akari --continue` は
 `opencode --continue` を起動する）。
 
+## 状態・受理・能力検索
+
+```sh
+akari status [project-path] --json
+akari status [project-path] --full --json
+akari accept [project-path]                         # 実 TTY でのみ対話記録
+akari capability <query> --json
+akari capability <query> --record-miss --json      # 0 hit のときだけ absence receipt
+```
+
+fast status は現在工程を決定的に返すが、最終受理を true にしない。full status だけが immutable
+render receipt の全 input / output と人間受理 event を再検証し、`release.accepted:true` を返せる。
+`accept` が作るのは協調的ローカル運用の人間操作記録であり、暗号学的な本人署名ではない。
+capability の 0 hit receipt は `approved_to_build:false` 固定で、新設許可を意味しない。
+
 ## 3 入口の対応表
 
 AKARI Video は「同じファイル契約（`.akari/` 配下の JSON）に収束する 3 つの入口」を
@@ -62,18 +89,11 @@ npm i -g akari-video && akari
 npx akari-video
 ```
 
-`package.json` は `"private": true` のままにしてある（誤って publish されることを防ぐ
-セーフティネット）。実際に npm へ配信する契約が別途 approve されたときに、まず
-この 1 行を外すところから始める。
-
 ## 既知の制約
 
-- **配布パッケージとしての自己完結性は未整備**: `akari` はスキル正本・
-  `templates/project-default`・`packages/schemas` を、自分の checkout 位置からの
-  相対パスで解決する（`skills/create-project/bin/create-project.mjs` と同じ方式）。
-  これはこのリポジトリの checkout 内で実行される前提であり、npm レジストリ経由で
-  単体インストールされた場合にこれらのアセットを同梱する build/vendor 手順はまだ
-  実装していない（マーケットプレイス配布・審査は上位契約 §7 でスコープ外）。
+- npm tarball は追跡済み skills・雛形・schemas と capability source set を `vendor/` に同梱する。
+  Claude plugin の status は単体コピーでも動くが、skill symlink と CLI capability は checkout / CLI
+  の有無に依存し、利用不能なら明示的に unsupported とする。
 - Windows での動作は未検証（`claude.exe` / `claude.cmd` の探索ロジックはあるが
   実機確認していない）。
 

package/bin/akari.mjs

@@ -1,10 +1,26 @@
 #!/usr/bin/env node
 import { run, runUpdateCommand } from '../src/cli.mjs';
+import { runInitCommand } from '../src/init-command.mjs';
+import { runSoundsCommand } from '../src/sounds-setup.mjs';
+import { runStatusCommand } from '../src/status-command.mjs';
+import { runAcceptCommand } from '../src/accept-command.mjs';
+import { runCapabilityCommand } from '../src/capability-command.mjs';
+import { runStoreCommand } from '../src/store-command.mjs';
 
 const argv = process.argv.slice(2);
-// `akari update` は claude へ転送せず、更新の案内だけを行う専用サブコマンド
-// （契約 §4-1）。それ以外の引数はすべて従来どおり claude へ転送する。
-const invoke = argv[0] === 'update' ? runUpdateCommand(argv.slice(1)) : run(argv);
+// `akari update` / `akari init` / `akari sounds` / `akari status` / `akari accept` /
+// `akari capability` / `akari store` は claude へ転送せず、
+// 専用のサブコマンドとして扱う（契約 §4-1 / タスク契約 launcher-init（内部リポ）/
+// 音源カタログ既定化のオーナー裁定 2026-08-03 / AKARI Store 連携）。
+// それ以外の引数はすべて従来どおり claude へ転送する。
+const invoke = argv[0] === 'update' ? runUpdateCommand(argv.slice(1))
+  : argv[0] === 'init' ? runInitCommand(argv.slice(1))
+  : argv[0] === 'sounds' ? runSoundsCommand(argv.slice(1))
+  : argv[0] === 'status' ? runStatusCommand(argv.slice(1))
+  : argv[0] === 'accept' ? runAcceptCommand(argv.slice(1))
+  : argv[0] === 'capability' ? runCapabilityCommand(argv.slice(1))
+  : argv[0] === 'store' ? runStoreCommand(argv.slice(1))
+  : run(argv);
 
 const result = await invoke.catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/src/accept-command.mjs

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { inspectFullIntegrity } from "./status-core/integrity.mjs";
+import { resolveFullProjectStatus } from "./status-core/status.mjs";
+
+export async function runAcceptCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => process.stdout.write(line));
+  const error = options.error ?? ((line) => process.stderr.write(`${line}\n`));
+  let parsed;
+  try {
+    parsed = parseAcceptArguments(argv, options.cwd ?? process.cwd());
+  } catch (cause) {
+    error(messageOf(cause));
+    return { exitCode: 2 };
+  }
+
+  const isTTY = options.isTTY ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+  if (!isTTY) {
+    error("akari accept requires an interactive input and output TTY; pipes, flags, and environment confirmation are not accepted");
+    return { exitCode: 2 };
+  }
+
+  const status = await resolveFullProjectStatus(parsed.projectRoot);
+  if (status.release.accepted) {
+    error("the current verified artifact already has an active human acceptance record");
+    return { exitCode: 1, status };
+  }
+  if (status.workflow_stage !== "acceptance_pending" || status.state_health !== "valid") {
+    error(`the project is not ready for human acceptance: ${status.workflow_stage} (${status.state_health})`);
+    return { exitCode: 1, status };
+  }
+
+  const before = await inspectFullIntegrity(parsed.projectRoot);
+  if (!before.ok || !before.candidate || before.activeAcceptance) {
+    error(`the verified artifact cannot be accepted: ${before.problems.join("; ") || "no current acceptance candidate"}`);
+    return { exitCode: 1, status };
+  }
+  const candidate = before.candidate;
+  const phrase = `ACCEPT ${candidate.artifact_sha256}`;
+  log(`Artifact: ${candidate.artifact}\nArtifact SHA-256: ${candidate.artifact_sha256}\nReceipt: ${candidate.receipt}\nReceipt SHA-256: ${candidate.receipt_sha256}\n`);
+  if (candidate.audio_qc?.verdict === "INCONCLUSIVE") {
+    log(`WARNING: audio_qc is INCONCLUSIVE; this is not an audio conformance PASS.\nConfigured: ${JSON.stringify(candidate.audio_qc.configured)}\nFilter report: ${JSON.stringify(candidate.audio_qc.filter_report)}\nDecoded artifact measurement: ${JSON.stringify(candidate.audio_qc.decoded_measurement)}\n`);
+  }
+
+  const prompt = options.prompt ?? promptFromTTY;
+  let actorId;
+  let acceptanceStatement;
+  let checksumConfirmation;
+  try {
+    actorId = (await prompt("Human identity for this cooperative local record: ")).trim();
+    if (actorId === "") throw new Error("human identity must not be empty");
+    acceptanceStatement = await prompt("Your final acceptance statement for this artifact: ");
+    if (acceptanceStatement.trim() === "") throw new Error("final acceptance statement must not be empty");
+    checksumConfirmation = await prompt(`Type exactly “${phrase}” to confirm this artifact checksum: `);
+  } catch (cause) {
+    error(`acceptance was not recorded: ${messageOf(cause)}`);
+    return { exitCode: 1, status };
+  }
+  if (checksumConfirmation !== phrase) {
+    error("artifact checksum confirmation did not match exactly; nothing was recorded");
+    return { exitCode: 1, status };
+  }
+
+  const after = await inspectFullIntegrity(parsed.projectRoot);
+  if (!after.ok || !after.candidate || after.activeAcceptance || !sameCandidate(candidate, after.candidate)) {
+    error("project integrity or acceptance state changed during confirmation; nothing was recorded");
+    return { exitCode: 1, status };
+  }
+
+  try {
+    const written = await writeAcceptanceEvent({
+      projectRoot: parsed.projectRoot,
+      actorId,
+      verbatim: acceptanceStatement,
+      candidate,
+      now: options.now,
+      id: options.id,
+    });
+    log(`Recorded cooperative local acceptance event ${written.event.id} at ${written.path}. This record is not a cryptographic human-identity proof.\n`);
+    return { exitCode: 0, event: written.event, path: written.path };
+  } catch (cause) {
+    error(`acceptance was not recorded: ${messageOf(cause)}`);
+    return { exitCode: 1, status };
+  }
+}
+
+export function parseAcceptArguments(argv, cwd = process.cwd()) {
+  let projectRoot = cwd;
+  let pathSeen = false;
+  for (const argument of argv) {
+    if (argument.startsWith("-")) throw new Error(`Unknown accept option: ${argument}`);
+    if (pathSeen) throw new Error("accept accepts only one project path");
+    projectRoot = argument;
+    pathSeen = true;
+  }
+  return { projectRoot };
+}
+
+export async function writeAcceptanceEvent({ projectRoot, actorId, verbatim, candidate, now, id }) {
+  const root = realpathSync(resolve(projectRoot));
+  if (typeof actorId !== "string" || actorId.trim() === "") throw new Error("human actor identity is required");
+  if (typeof verbatim !== "string" || verbatim.trim() === "") throw new Error("verbatim confirmation is required");
+  assertCandidate(candidate);
+  const eventId = id ?? randomUUID();
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u.test(eventId)) throw new Error("event id contains unsafe characters");
+  const occurredAt = now instanceof Date ? now.toISOString() : typeof now === "string" ? now : new Date().toISOString();
+  if (!/(?:Z|[+-]\d{2}:?\d{2})$/u.test(occurredAt) || !Number.isFinite(Date.parse(occurredAt))) {
+    throw new Error("acceptance timestamp must include an explicit UTC offset");
+  }
+  const event = {
+    version: 1,
+    id: eventId,
+    type: "final-acceptance",
+    occurredAt,
+    actor: { kind: "human", id: actorId.trim() },
+    issuer: { kind: "akari-cli-tty", version: 1 },
+    artifact: candidate.artifact,
+    artifact_sha256: candidate.artifact_sha256,
+    render_receipt: candidate.receipt,
+    render_receipt_sha256: candidate.receipt_sha256,
+    review_sha256: candidate.review_sha256,
+    verbatim,
+  };
+  const eventsDirectory = await prepareEventsDirectory(root);
+  const compactTime = occurredAt.replace(/[-:.]/gu, "");
+  const eventPath = join(eventsDirectory, `${compactTime}-${eventId}-final-acceptance.json`);
+  await writeFile(eventPath, `${JSON.stringify(event, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  return { event, path: relative(root, eventPath) };
+}
+
+async function prepareEventsDirectory(root) {
+  const akariDirectory = join(root, ".akari");
+  const actualAkari = realpathSync(akariDirectory);
+  if (!isWithin(root, actualAkari) || !lstatSync(akariDirectory).isDirectory()) {
+    throw new Error(".akari is not a regular project directory");
+  }
+  const eventsDirectory = join(akariDirectory, "events");
+  await mkdir(eventsDirectory, { recursive: true });
+  const actualEvents = realpathSync(eventsDirectory);
+  if (!isWithin(root, actualEvents) || !lstatSync(eventsDirectory).isDirectory()) {
+    throw new Error(".akari/events is not a regular project directory");
+  }
+  return actualEvents;
+}
+
+async function promptFromTTY(question) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await readline.question(question);
+  } finally {
+    readline.close();
+  }
+}
+
+function sameCandidate(left, right) {
+  return left.receipt === right.receipt
+    && left.receipt_sha256 === right.receipt_sha256
+    && left.artifact === right.artifact
+    && left.artifact_sha256 === right.artifact_sha256
+    && left.review_sha256 === right.review_sha256;
+}
+
+function assertCandidate(value) {
+  if (!isSafeRelativePath(value?.artifact) || !isSafeRelativePath(value?.receipt)) throw new Error("acceptance candidate paths are invalid");
+  for (const key of ["artifact_sha256", "receipt_sha256", "review_sha256"]) {
+    if (!/^[a-f0-9]{64}$/u.test(value?.[key] ?? "")) throw new Error(`acceptance candidate ${key} is invalid`);
+  }
+}
+
+function isSafeRelativePath(value) {
+  return typeof value === "string" && value !== "" && !isAbsolute(value) && !value.split(/[\\/]/u).includes("..");
+}
+
+function isWithin(root, target) {
+  const value = relative(root, target);
+  return value === "" || (!value.startsWith("..") && !isAbsolute(value));
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/capability-command.mjs

@@ -0,0 +1,47 @@
+import { buildCapabilityCatalog, queryCapability, recordCapabilityMiss } from "./capability.mjs";
+
+export async function runCapabilityCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => process.stdout.write(line));
+  const error = options.error ?? ((line) => process.stderr.write(`${line}\n`));
+  let parsed;
+  try {
+    parsed = parseCapabilityArguments(argv, options.cwd ?? process.cwd());
+    const catalog = buildCapabilityCatalog(options.catalogOptions);
+    const result = queryCapability(catalog, parsed.query);
+    if (parsed.recordMiss && result.matches.length === 0) {
+      const recorded = await recordCapabilityMiss(parsed.projectRoot, catalog, result);
+      log(parsed.json ? `${JSON.stringify(recorded.receipt, null, 2)}\n` : `No text match; review required. Receipt: ${recorded.path}\n`);
+      return { exitCode: 0, result, receipt: recorded };
+    }
+    if (parsed.json) log(`${JSON.stringify(result, null, 2)}\n`);
+    else if (result.matches.length === 0) log("No text match. Review the source set before proposing a new capability.\n");
+    else {
+      for (const match of result.matches) log(`${match.path} — ${match.heading} (score ${match.score})\n${match.snippet}\n`);
+    }
+    return { exitCode: 0, result };
+  } catch (cause) {
+    error(cause instanceof Error ? cause.message : String(cause));
+    return { exitCode: 1 };
+  }
+}
+
+export function parseCapabilityArguments(argv, cwd = process.cwd()) {
+  const queryParts = [];
+  let json = false;
+  let recordMiss = false;
+  let projectRoot = cwd;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--json") json = true;
+    else if (argument === "--record-miss") recordMiss = true;
+    else if (argument === "--project") {
+      const value = argv[++index];
+      if (!value || value.startsWith("-")) throw new Error("--project requires a path");
+      projectRoot = value;
+    } else if (argument.startsWith("-")) throw new Error(`Unknown capability option: ${argument}`);
+    else queryParts.push(argument);
+  }
+  const query = queryParts.join(" ").trim();
+  if (query === "") throw new Error("capability requires a query");
+  return { query, json, recordMiss, projectRoot };
+}

package/src/capability-sources.mjs

@@ -0,0 +1,122 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export function discoverCheckoutCapabilitySources(repoRoot, { trackedFiles = null } = {}) {
+  const root = realpathSync(resolve(repoRoot));
+  const tracked = trackedFiles ?? execFileSync("git", ["-C", root, "ls-files", "-z"], {
+    maxBuffer: 64 * 1024 * 1024,
+  }).toString("utf8").split("\0").filter(Boolean);
+  const trackedSet = new Set(tracked);
+  const selected = new Set(tracked.filter(isBaseCapabilitySource));
+  const manifests = [...selected].filter((path) => /^packages\/[^/]+\/package\.json$/u.test(path)).sort(compare);
+  for (const manifestPath of manifests) {
+    const manifest = parseManifest(join(root, manifestPath), manifestPath);
+    const packageRoot = dirname(manifestPath);
+    for (const target of manifestBinTargets(manifest)) {
+      if (typeof target !== "string" || target.trim() === "") {
+        throw new Error(`${manifestPath} has an invalid package.json#bin target`);
+      }
+      const canonical = normalizeRelative(join(packageRoot, target));
+      if (!isWithinRelative(packageRoot, canonical)) {
+        throw new Error(`${manifestPath} package.json#bin escapes its package root: ${target}`);
+      }
+      if (!trackedSet.has(canonical)) {
+        throw new Error(`${manifestPath} package.json#bin target is not tracked: ${canonical}`);
+      }
+      assertRegularContainedFile(root, canonical, `${manifestPath} package.json#bin`);
+      selected.add(canonical);
+    }
+  }
+  const paths = [...selected].sort(compare);
+  for (const path of paths) assertRegularContainedFile(root, path, "capability source");
+  return paths;
+}
+
+export function loadVendoredCapabilitySources(packageRoot) {
+  const root = realpathSync(resolve(packageRoot));
+  const manifestPath = join(root, "vendor", ".akari-capability-sources.json");
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`vendored capability manifest is unavailable: ${messageOf(error)}`);
+  }
+  if (manifest?.version !== 1 || !Array.isArray(manifest.sources)) {
+    throw new Error("vendored capability manifest has an unsupported shape");
+  }
+  const paths = [...manifest.sources];
+  if (paths.some((path) => typeof path !== "string") || JSON.stringify(paths) !== JSON.stringify([...paths].sort(compare))) {
+    throw new Error("vendored capability manifest source list is not sorted strings");
+  }
+  if (new Set(paths).size !== paths.length) throw new Error("vendored capability manifest contains duplicate sources");
+  for (const path of paths) assertRegularContainedFile(join(root, "vendor"), path, "vendored capability source");
+  return paths;
+}
+
+export function isCheckoutRepoRoot(root) {
+  try {
+    return execFileSync("git", ["-C", root, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim() === realpathSync(root);
+  } catch {
+    return false;
+  }
+}
+
+export function isBaseCapabilitySource(path) {
+  return /^skills\/.+\.md$/u.test(path)
+    || /^docs\/contract-[^/]+\.md$/u.test(path)
+    || /^packages\/[^/]+\/README[^/]*\.md$/u.test(path)
+    || /^packages\/[^/]+\/package\.json$/u.test(path);
+}
+
+export function manifestBinTargets(manifest) {
+  if (typeof manifest?.bin === "string") return [manifest.bin];
+  if (manifest?.bin && typeof manifest.bin === "object" && !Array.isArray(manifest.bin)) {
+    return Object.keys(manifest.bin).sort(compare).map((key) => manifest.bin[key]);
+  }
+  return [];
+}
+
+function parseManifest(path, label) {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("root must be an object");
+    return value;
+  } catch (error) {
+    throw new Error(`${label} is not a valid package manifest: ${messageOf(error)}`);
+  }
+}
+
+function assertRegularContainedFile(root, canonical, label) {
+  if (typeof canonical !== "string" || canonical === "" || isAbsolute(canonical) || canonical.split(/[\\/]/u).includes("..")) {
+    throw new Error(`${label} path is unsafe: ${String(canonical)}`);
+  }
+  const lexical = resolve(root, canonical);
+  if (!existsSync(lexical)) throw new Error(`${label} does not exist: ${canonical}`);
+  const actual = realpathSync(lexical);
+  if (!isWithin(root, actual) || !lstatSync(lexical).isFile()) {
+    throw new Error(`${label} is not a regular contained file: ${canonical}`);
+  }
+}
+
+function normalizeRelative(path) {
+  return path.replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+
+function isWithinRelative(root, target) {
+  const value = relative(root, target);
+  return value === "" || (!value.startsWith("..") && !isAbsolute(value));
+}
+
+function isWithin(root, target) {
+  const value = relative(root, target);
+  return value === "" || (!value.startsWith("..") && !isAbsolute(value));
+}
+
+function compare(left, right) {
+  return left.localeCompare(right, "en");
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/capability.mjs

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { discoverCheckoutCapabilitySources, isCheckoutRepoRoot, loadVendoredCapabilitySources } from "./capability-sources.mjs";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CHECKOUT_ROOT = resolve(PACKAGE_ROOT, "..", "..");
+const MISS_VERDICT = "NO_TEXT_MATCH_REQUIRES_REVIEW";
+
+export function buildCapabilityCatalog(options = {}) {
+  const topology = resolveCapabilityTopology(options);
+  const sources = topology.paths.map((path) => {
+    const absolutePath = join(topology.contentRoot, path);
+    const bytes = readFileSync(absolutePath);
+    return {
+      path,
+      bytes: bytes.byteLength,
+      sha256: sha256(bytes),
+      text: bytes.toString("utf8"),
+    };
+  });
+  const sourceManifest = sources.map(({ path, bytes, sha256: digest }) => ({ path, bytes, sha256: digest }));
+  return {
+    version: 1,
+    topology: topology.kind,
+    sources,
+    source_set_sha256: sha256(canonicalJson(sourceManifest)),
+  };
+}
+
+export function queryCapability(catalog, query, { maximum = 20 } = {}) {
+  if (typeof query !== "string" || query.trim() === "") throw new Error("capability query must not be empty");
+  const tokens = tokenize(query);
+  const candidates = [];
+  for (const source of catalog.sources) {
+    for (const section of sectionsForSource(source)) {
+      const pathText = normalize(source.path);
+      const headingText = normalize(section.heading);
+      const bodyText = normalize(section.body);
+      if (!tokens.every((token) => pathText.includes(token) || headingText.includes(token) || bodyText.includes(token))) continue;
+      const score = tokens.reduce((total, token) => total
+        + (pathText.includes(token) ? 12 : 0)
+        + (headingText.includes(token) ? 8 : 0)
+        + (bodyText.includes(token) ? 3 : 0), 0);
+      candidates.push({
+        path: source.path,
+        heading: section.heading,
+        score,
+        snippet: snippet(section.body || section.heading),
+      });
+    }
+  }
+  candidates.sort((left, right) => right.score - left.score
+    || left.path.localeCompare(right.path, "en")
+    || left.heading.localeCompare(right.heading, "en")
+    || left.snippet.localeCompare(right.snippet, "en"));
+  return {
+    version: 1,
+    query,
+    source_set_sha256: catalog.source_set_sha256,
+    source_count: catalog.sources.length,
+    matches: candidates.slice(0, maximum),
+  };
+}
+
+export async function recordCapabilityMiss(projectInput, catalog, result) {
+  if (result.matches.length !== 0) throw new Error("absence receipt may be recorded only for a zero-hit query");
+  const projectRoot = realpathSync(resolve(projectInput));
+  const connections = join(projectRoot, ".akari", "connections.json");
+  if (!lstatSync(connections).isFile()) throw new Error("absence receipt requires an AKARI project");
+  const akariDirectory = realpathSync(join(projectRoot, ".akari"));
+  if (!isWithin(projectRoot, akariDirectory) || !lstatSync(join(projectRoot, ".akari")).isDirectory()) {
+    throw new Error(".akari is not a contained project directory");
+  }
+  const reportsDirectory = await ensureContainedDirectory(projectRoot, join(akariDirectory, "reports"));
+  const absenceDirectory = await ensureContainedDirectory(projectRoot, join(reportsDirectory, "absence"));
+  const receipt = {
+    version: 1,
+    query: result.query,
+    source_set_sha256: catalog.source_set_sha256,
+    sources: catalog.sources.map(({ path, sha256: digest }) => ({ path, sha256: digest })),
+    matches: [],
+    verdict: MISS_VERDICT,
+    approved_to_build: false,
+  };
+  const bytes = `${JSON.stringify(receipt, null, 2)}\n`;
+  const digest = sha256(bytes);
+  const path = join(absenceDirectory, `${digest}.json`);
+  try {
+    await writeFile(path, bytes, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    if (await readFile(path, "utf8") !== bytes) throw new Error("absence receipt digest collision");
+  }
+  return { receipt, path: relative(projectRoot, path), sha256: digest };
+}
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${Object.keys(value).sort((left, right) => left.localeCompare(right, "en"))
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function resolveCapabilityTopology(options) {
+  if (options.sourceRoot) {
+    const root = realpathSync(resolve(options.sourceRoot));
+    return {
+      kind: "checkout",
+      contentRoot: root,
+      paths: discoverCheckoutCapabilitySources(root, { trackedFiles: options.trackedFiles }),
+    };
+  }
+  if (isCheckoutRepoRoot(CHECKOUT_ROOT)) {
+    return { kind: "checkout", contentRoot: CHECKOUT_ROOT, paths: discoverCheckoutCapabilitySources(CHECKOUT_ROOT) };
+  }
+  return { kind: "vendor", contentRoot: join(PACKAGE_ROOT, "vendor"), paths: loadVendoredCapabilitySources(PACKAGE_ROOT) };
+}
+
+function sectionsForSource(source) {
+  if (source.path.endsWith("package.json")) {
+    try {
+      const manifest = JSON.parse(source.text);
+      const body = JSON.stringify({ name: manifest.name, description: manifest.description, bin: manifest.bin });
+      return [{ heading: manifest.name ?? source.path, body }];
+    } catch {
+      return [{ heading: source.path, body: source.text }];
+    }
+  }
+  if (!source.path.endsWith(".md")) return [{ heading: source.path, body: source.text }];
+  const sections = [];
+  let heading = source.path;
+  let lines = [];
+  for (const line of source.text.split(/\r?\n/u)) {
+    const match = line.match(/^#{1,6}\s+(.+)$/u);
+    if (match) {
+      if (lines.some((value) => value.trim() !== "")) sections.push({ heading, body: lines.join("\n") });
+      heading = match[1].trim();
+      lines = [];
+    } else {
+      lines.push(line);
+    }
+  }
+  if (lines.some((value) => value.trim() !== "") || sections.length === 0) sections.push({ heading, body: lines.join("\n") });
+  return sections;
+}
+
+function tokenize(value) {
+  const tokens = normalize(value).split(/\s+/u).filter(Boolean);
+  return [...new Set(tokens)];
+}
+
+function normalize(value) {
+  return String(value ?? "").normalize("NFKC").toLocaleLowerCase("en").replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+function snippet(value) {
+  return String(value ?? "").replace(/\s+/gu, " ").trim().slice(0, 240);
+}
+
+async function ensureContainedDirectory(root, path) {
+  await mkdir(path, { recursive: true });
+  const actual = realpathSync(path);
+  if (!isWithin(root, actual) || !lstatSync(path).isDirectory()) throw new Error("absence receipt directory escapes the project");
+  return actual;
+}
+
+function isWithin(root, target) {
+  const value = relative(root, target);
+  return value === "" || (!value.startsWith("..") && !isAbsolute(value));
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}