@hraness/kb 0.17.3 → 0.18.1

package/README.md

@@ -14,34 +14,67 @@ system.
 Bun 1.3.14 or newer is required.
 
 ```sh
-bun add --global @hraness/kb@0.17.3
+bun add --global @hraness/kb@0.18.1
+kb --help
 ```
 
-## Why kb
-
-- **Inspect what agents recover.** Markdown and Git stay authoritative,
-  retrieval signals stay distinct, and indexes, embeddings, and graph views
-  remain replaceable.
-- **Keep the application independent.** Application code imports neither the
-  vault nor a hosted knowledge service. Capture and semantic adapters declare
-  their network, browser, native-tool, and model-download effects.
+## Keep one decision available to the next session
 
-## Create one durable note
+Suppose a parser must stop retrying after three attempts. Record that constraint
+in a note, then link the plan that will implement it:
 
-From a directory without an existing `kb/` path, this local task creates a
-vault, writes one typed note, and finds it without a network request or
-embedding model:
-
-```sh
+```shell
 kb init kb
 kb note create notes/parser-contract \
-  --title "Parser contract" --type concept --tag architecture --root kb
-kb search "parser contract" --root kb --mode exact
+  --title "Parser contract" --type concept --tag architecture \
+  --body "Parser retries stop after three attempts." --root kb
+kb note create plans/parser-v2 \
+  --title "Parser v2" --type plan \
+  --body "The plan implements [[notes/parser-contract|the parser contract]]." \
+  --root kb
 ```
 
-The note is stored at `kb/notes/parser-contract.md`. Exact search reads the
-current Markdown and returns that record. Commit the vault when it should
-travel with the repository.
+The first `kb note create` command stores ordinary Markdown at
+`kb/notes/parser-contract.md` and assigns its stable `document_id`. Add the
+exact code boundary to that note's frontmatter so path lookup can recover it:
+
+```yaml
+repository_scopes:
+  - packages/parser
+```
+
+Commit the vault with the repository. The Markdown and its Git history are the
+durable record.
+
+## Recover the stopped session
+
+In a later session, start from the code path and inspect each independent
+signal:
+
+```shell
+kb context packages/parser/src/index.ts --root kb --repo .
+kb search "why parser retries stop" --root kb --mode exact \
+  --history --repo .
+kb backlinks notes/parser-contract --root kb
+kb history notes/parser-contract --root kb --repo .
+```
+
+| Signal | What it recovers |
+| --- | --- |
+| Markdown | The current parser constraint in the file you can review and edit. |
+| Backlinks | The plan that explicitly links to the constraint. |
+| Exact search | The current note matched from its words, without a network request or embedding model. |
+| Repository context | Inherited `AGENTS.md` guides and records scoped to `packages/parser`. |
+| Git history | The commits and bounded co-change evidence associated with the note. |
+
+Together, those views recover the persisted decision, related plan, applicable
+rules, and provenance needed to resume the work. They do not reconstruct
+private chat or prove that the note is still correct. Open the returned
+Markdown and guides before acting on them.
+
+The boundaries stay visible: Markdown and Git are authoritative, backlinks and
+indexes are replaceable views, and Git work is opt-in. Application code imports
+neither the vault nor a hosted knowledge service.
 
 <!-- hraness:kb-landing:end -->
 
@@ -51,22 +84,6 @@ travel with the repository.
 [KB source on GitHub](https://github.com/hraness/kb) ·
 [KB overview](https://hraness.com/kb)
 
-## Use
-
-```sh
-kb init kb
-kb clip https://example.com/article --output articles
-kb pdf ./report.pdf --output articles
-kb percolate notes/topic --root .
-kb context packages/parser/src/index.ts --root kb --repo .
-kb list --where type=plan --scope packages/parser --root .
-kb links notes/topic --root . --direction both
-kb search "parser-v2" --root . --mode exact
-kb portfolio search "parser-v2" --registry kb-portfolio.json \
-  --workspace .. --shared
-kb history search packages/parser --root . --repo .. --json
-```
-
 ## A knowledge base for your coding agents
 
 > Give coding agents durable, searchable memory beside the repository with plain Markdown, Git history, and replaceable local search.
@@ -193,51 +210,6 @@ Start with a short inherited `AGENTS.md` path for rules whose omission would mak
 
 Treat the knowledge base as repository-adjacent durable memory. Authored Markdown and Git are the record; catalogs, indexes, embeddings, and graph views are replaceable ways to find and inspect it. Checks can validate structure, captures can preserve a selected surface, and similarity can suggest candidates. None of those mechanisms proves that a source is trustworthy or an explanation is still true. People and agents must revise the knowledge as the repository changes.
 
-## Upgrade to v0.17.3
-
-Version 0.17.3 restructures the README around an inspectable first task,
-explicit operating boundaries, and a shorter path from installation to useful
-output. Runtime APIs and package behavior are unchanged.
-
-## Upgrade to v0.17.2
-
-Version 0.17.2 improves package discovery through focused npm keywords, a more
-specific README opening, and direct links between npm, GitHub, and the project
-overview. Runtime APIs and package behavior are unchanged.
-
-## Upgrade to v0.17.1
-
-Version 0.17.1 adds the public `@hraness/kb` npm installation path without
-changing the runtime API introduced in 0.17.0. Bun `1.3.14` or newer is now an
-explicit package requirement. Consumers should review the package's declared
-dual-use capture boundary and the lifecycle scripts used by optional browser
-and native search adapters before enabling those scripts.
-
-## Upgrade to v0.17.0
-
-Version 0.17 adds selected portfolio federation, stable note identities,
-qualified external relations, search rules, capture inspection, and untrusted
-context packing. Consumers with typed fixtures or custom capture writers should
-make these migrations before upgrading:
-
-- Capture writers now emit manifest schema v4 and must provide the stored
-  document `path`, exact UTF-8 `bytes`, and lowercase SHA-256 digest. The reader
-  can inspect schema v1-v3, but verification reports their document integrity as
-  unavailable instead of success.
-- `DecisionContextOutput.search` has been removed. Consume the bounded untrusted
-  `context` projection and its `truncated` flag instead of transporting the raw
-  search result into an agent prompt.
-- `VaultAnalysis` fixtures must include `externalAuthoredRelations`, even when
-  the value is an empty array. This keeps qualified authored edges distinct
-  from locally resolved graph edges.
-- `createNote` and `kb note create` now assign `document_id` to new ordinary
-  notes. Preserve that ID across renames and update snapshots that intentionally
-  assert the generated frontmatter.
-
-Existing Markdown is not rewritten automatically. Add IDs to maintained legacy
-notes only through reviewed edits, and keep every QMD, graph, portfolio, and
-audit projection disposable.
-
 ## Installation reference
 
 [Bun](https://bun.sh/docs/installation) is the required runtime.
@@ -247,9 +219,9 @@ audit projection disposable.
 Copy this prompt into Codex, Claude Code, or another coding agent:
 
 ```text
-Install the `kb` Agent Skill from `hraness/kb#v0.17.3` with the standard skills
+Install the `kb` Agent Skill from `hraness/kb#v0.18.1` with the standard skills
 CLI. Use the skill's runtime instructions to install the exact
-`@hraness/kb@0.17.3` registry release only when the command is missing. Verify it
+`@hraness/kb@0.18.1` registry release only when the command is missing. Verify it
 with `kb doctor` and `kb --help`, but do not initialize or modify a vault until
 I ask.
 ```
@@ -257,25 +229,25 @@ I ask.
 Install the single public skill with either runner:
 
 ```sh
-npx skills add hraness/kb#v0.17.3
-bunx skills add hraness/kb#v0.17.3
+npx skills add hraness/kb#v0.18.1
+bunx skills add hraness/kb#v0.18.1
 ```
 
 Both commands discover the same `kb` skill and install it into the selected
 agent runner. Skill installation is inert: it does not initialize a vault,
 refresh a catalog, or edit Markdown. When invoked, the skill uses an existing
 `kb` command or, when the command is missing, checks for Bun and installs the
-CLI from the immutable `@hraness/kb@0.17.3` npm version.
+CLI from the immutable `@hraness/kb@0.18.1` npm version.
 
 The public skills CLI reads `skills/kb/` from the repository. The immutable
-`0.17.3` npm package includes the same tree under
+`0.18.1` npm package includes the same tree under
 `node_modules/@hraness/kb/skills/kb/`, and the package check verifies that the
 installed skill is byte-identical to the repository source.
 
 Install the two global commands with Bun:
 
 ```sh
-bun add --global @hraness/kb@0.17.3
+bun add --global @hraness/kb@0.18.1
 kb --help
 kb-evaluation-builder --help
 ```
@@ -283,7 +255,7 @@ kb-evaluation-builder --help
 The same registry package can be installed with npm:
 
 ```sh
-npm install --global --ignore-scripts @hraness/kb@0.17.3
+npm install --global --ignore-scripts @hraness/kb@0.18.1
 kb --help
 ```
 
@@ -296,7 +268,7 @@ reviewed and enabled; run `kb doctor` to inspect the resulting capabilities.
 For programmatic use, add the exact npm version to a Bun project:
 
 ```sh
-bun add --exact @hraness/kb@0.17.3
+bun add --exact @hraness/kb@0.18.1
 ```
 
 The resulting dependency should remain exact:
@@ -304,12 +276,13 @@ The resulting dependency should remain exact:
 ```json
 {
   "dependencies": {
-    "@hraness/kb": "0.17.3"
+    "@hraness/kb": "0.18.1"
   }
 }
 ```
 
-Version 0.17.3 retains two public GitHub dependencies:
+Version 0.18.1 retains three public GitHub dependencies: `@hraness/oh` at
+immutable release `v0.2.0` for closure verification,
 `@steipete/sweet-cookie` at Hraness release `v0.4.2` for the cookie-scope safety
 fork, and `@tobilu/qmd` at commit
 `aa993dceb3ef8cfb71d470554ca437570f5a2b3c` for store-local model behavior. A
@@ -572,9 +545,9 @@ a vault. The package smoke test keeps future tagged packages byte-identical to
 that source tree.
 
 ```sh
-npx skills add hraness/kb#v0.17.3
+npx skills add hraness/kb#v0.18.1
 # or
-bunx skills add hraness/kb#v0.17.3
+bunx skills add hraness/kb#v0.18.1
 ```
 
 The skill invokes the installed `kb` command without depending on a repository
@@ -584,3 +557,69 @@ effect. The repository's phase-orchestration skill remains available to local
 repository agents but is marked internal, so public skill discovery omits it.
 
 See [Design](docs/design.md), [Portfolio federation](docs/portfolio.md), [Agent workflow](docs/agent-workflow.md), [PDF capture](docs/pdf.md), and [Contributing](CONTRIBUTING.md) for the durable contracts and development gate. hraness/kb is available under the [MIT License](LICENSE).
+
+## Release notes
+
+### Upgrade to v0.18.1
+
+Version 0.18.1 restructures the public README and hosted projection around one
+durable note, the exact recovery workflow, inspectable retrieval signals, and
+explicit authority boundaries. Runtime APIs and package behavior are
+unchanged.
+
+### Upgrade to v0.18.0
+
+Version 0.18.0 adds a review-only adoption seam for exact dependency closures
+from an Oh working authority. Trusted host code creates a
+`createOhAdoptionPreparerV1` facade with the expected binding and head,
+destination, rights clearance, review route, and conflict policy. The narrow
+`prepare` call accepts only a capsule plus transformation and redaction
+disclosures, returns deeply immutable deterministic Markdown and manifest
+bytes with status `prepared`, and has no vault, Git, Oh-store, or promotion
+capability. KB pins `@hraness/oh` v0.2.0 and delegates closure integrity to its
+official store verifier.
+
+### Upgrade to v0.17.3
+
+Version 0.17.3 restructures the README around an inspectable first task,
+explicit operating boundaries, and a shorter path from installation to useful
+output. Runtime APIs and package behavior are unchanged.
+
+### Upgrade to v0.17.2
+
+Version 0.17.2 improves package discovery through focused npm keywords, a more
+specific README opening, and direct links between npm, GitHub, and the project
+overview. Runtime APIs and package behavior are unchanged.
+
+### Upgrade to v0.17.1
+
+Version 0.17.1 adds the public `@hraness/kb` npm installation path without
+changing the runtime API introduced in 0.17.0. Bun `1.3.14` or newer is now an
+explicit package requirement. Consumers should review the package's declared
+dual-use capture boundary and the lifecycle scripts used by optional browser
+and native search adapters before enabling those scripts.
+
+### Upgrade to v0.17.0
+
+Version 0.17 adds selected portfolio federation, stable note identities,
+qualified external relations, search rules, capture inspection, and untrusted
+context packing. Consumers with typed fixtures or custom capture writers should
+make these migrations before upgrading:
+
+- Capture writers now emit manifest schema v4 and must provide the stored
+  document `path`, exact UTF-8 `bytes`, and lowercase SHA-256 digest. The reader
+  can inspect schema v1-v3, but verification reports their document integrity as
+  unavailable instead of success.
+- `DecisionContextOutput.search` has been removed. Consume the bounded untrusted
+  `context` projection and its `truncated` flag instead of transporting the raw
+  search result into an agent prompt.
+- `VaultAnalysis` fixtures must include `externalAuthoredRelations`, even when
+  the value is an empty array. This keeps qualified authored edges distinct
+  from locally resolved graph edges.
+- `createNote` and `kb note create` now assign `document_id` to new ordinary
+  notes. Preserve that ID across renames and update snapshots that intentionally
+  assert the generated frontmatter.
+
+Existing Markdown is not rewritten automatically. Add IDs to maintained legacy
+notes only through reviewed edits, and keep every QMD, graph, portfolio, and
+audit projection disposable.

package/dist/index.js

@@ -245,6 +245,314 @@ import {
   wikiLinks
 } from "./index-cxfrakt7.js";
 import"./index-1xxnjn0d.js";
+// src/oh-adoption.ts
+import { createHash } from "crypto";
+import { posix } from "path";
+import { canonicalJson, canonicalSha256 } from "@hraness/oh";
+import {
+  parseOhHeadV1,
+  parseOhStoreBindingV1,
+  verifyOhDependencyClosureAgainstV1
+} from "@hraness/oh/store";
+var CODE_PATTERN = /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u;
+var RECORD_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u;
+var MAX_CAPSULE_BYTES = 16 * 1024 * 1024;
+var MAX_RECORDS = 1024;
+var MAX_ROOTS = 256;
+var MAX_TEXT_BYTES = 4096;
+var MAX_STRUCTURAL_NODES = 262144;
+var MAX_STRUCTURAL_DEPTH = 128;
+function isRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function exactKeys(value, keys) {
+  const actual = Reflect.ownKeys(value);
+  return actual.length === keys.length && actual.every((key) => {
+    if (typeof key !== "string" || !keys.includes(key))
+      return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && descriptor.enumerable && "value" in descriptor;
+  });
+}
+function validUnicode(value) {
+  for (let index = 0;index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 55296 && code <= 56319) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 56320 || next > 57343)
+        return false;
+      index += 1;
+    } else if (code >= 56320 && code <= 57343)
+      return false;
+  }
+  return true;
+}
+function structurallyBounded(value) {
+  const pending = [[value, 0]];
+  const seen = new Set;
+  let nodes = 0;
+  let scalarBytes = 0;
+  while (pending.length > 0) {
+    const [candidate, depth] = pending.pop();
+    nodes += 1;
+    scalarBytes += 4;
+    if (nodes > MAX_STRUCTURAL_NODES || depth > MAX_STRUCTURAL_DEPTH || scalarBytes > MAX_CAPSULE_BYTES)
+      return false;
+    if (typeof candidate === "string") {
+      if (!validUnicode(candidate))
+        return false;
+      scalarBytes += Buffer.byteLength(candidate, "utf8");
+      if (scalarBytes > MAX_CAPSULE_BYTES)
+        return false;
+    }
+    if (typeof candidate !== "object" || candidate === null)
+      continue;
+    if (seen.has(candidate))
+      return false;
+    seen.add(candidate);
+    if (Array.isArray(candidate)) {
+      if (candidate.length > MAX_STRUCTURAL_NODES)
+        return false;
+      const keys = Reflect.ownKeys(candidate);
+      if (keys.some((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= candidate.length)))
+        return false;
+      for (let index = 0;index < candidate.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index));
+        if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor))
+          return false;
+        pending.push([descriptor.value, depth + 1]);
+      }
+    } else if (isRecord(candidate)) {
+      const keys = Reflect.ownKeys(candidate);
+      if (keys.length > MAX_STRUCTURAL_NODES || keys.some((key) => typeof key !== "string"))
+        return false;
+      for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+        if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor) || !validUnicode(key))
+          return false;
+        scalarBytes += Buffer.byteLength(key, "utf8");
+        if (scalarBytes > MAX_CAPSULE_BYTES)
+          return false;
+        pending.push([descriptor.value, depth + 1]);
+      }
+    } else
+      return false;
+  }
+  return true;
+}
+function immutableClone(value) {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((item) => immutableClone(item)));
+  }
+  if (isRecord(value)) {
+    const clone = {};
+    for (const key of Object.keys(value))
+      clone[key] = immutableClone(value[key]);
+    return Object.freeze(clone);
+  }
+  return value;
+}
+function code(value, maximum = 256) {
+  return typeof value === "string" && value.length <= maximum && CODE_PATTERN.test(value) ? value : null;
+}
+function recordKey(value) {
+  return typeof value === "string" && value.length <= 512 && RECORD_KEY_PATTERN.test(value) ? value : null;
+}
+function orderedUnique(values) {
+  return values.every((value, index) => index === 0 || values[index - 1] < value);
+}
+function unsafeReviewCodePoint(codePoint) {
+  return codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint === 1564 || codePoint === 8206 || codePoint === 8207 || codePoint >= 8232 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297 || codePoint === 65279;
+}
+function singleLine(value) {
+  if (typeof value !== "string" || value.length < 1 || value.normalize("NFC") !== value || !validUnicode(value) || [...value].some((character) => unsafeReviewCodePoint(character.codePointAt(0) ?? 0)) || Buffer.byteLength(value, "utf8") > MAX_TEXT_BYTES)
+    return null;
+  return value;
+}
+function parseExpectedSource(value) {
+  if (!isRecord(value) || !exactKeys(value, ["authorityId", "binding", "head", "v"]) || value.v !== 1)
+    return null;
+  const authorityId = code(value.authorityId);
+  const binding = parseOhStoreBindingV1(value.binding);
+  const head = parseOhHeadV1(value.head);
+  return authorityId !== null && binding !== null && binding.profile.profileKind === "working" && head !== null ? immutableClone({ authorityId, binding, head, v: 1 }) : null;
+}
+function parseDestination(value) {
+  if (!isRecord(value) || !exactKeys(value, ["purpose", "targetPath", "v"]) || value.v !== 1)
+    return null;
+  const purpose = code(value.purpose);
+  if (purpose === null || typeof value.targetPath !== "string" || value.targetPath.length > 512 || value.targetPath.includes("\\") || value.targetPath.startsWith("/") || posix.normalize(value.targetPath) !== value.targetPath || !/^notes\/[a-z0-9][a-z0-9._/-]*\.md$/u.test(value.targetPath) || value.targetPath.split("/").some((segment) => segment === "." || segment === ".." || segment.startsWith("."))) {
+    return null;
+  }
+  return { purpose, targetPath: value.targetPath, v: 1 };
+}
+function parseRights(value, purpose) {
+  if (!isRecord(value) || !exactKeys(value, ["decisionId", "disposition", "purpose", "v"]) || value.v !== 1 || value.disposition !== "cleared-for-purpose" || value.purpose !== purpose)
+    return null;
+  const decisionId = code(value.decisionId);
+  return decisionId === null ? null : { decisionId, disposition: "cleared-for-purpose", purpose, v: 1 };
+}
+function parseReview(value) {
+  if (!isRecord(value) || !exactKeys(value, ["route", "status", "v"]) || value.v !== 1 || value.status !== "required")
+    return null;
+  const route = code(value.route);
+  return route === null ? null : { route, status: "required", v: 1 };
+}
+function parseConflicts(value) {
+  if (!isRecord(value) || !exactKeys(value, ["notes", "status", "v"]) || value.v !== 1 || value.status !== "none-observed" && value.status !== "requires-resolution" || !Array.isArray(value.notes) || value.notes.length < 1 || value.notes.length > 64)
+    return null;
+  const notes = value.notes.map(singleLine);
+  if (notes.some((note) => note === null))
+    return null;
+  const sorted = [...notes].sort();
+  return orderedUnique(sorted) ? { notes: sorted, status: value.status, v: 1 } : null;
+}
+function parseHostPolicy(value) {
+  if (!structurallyBounded(value) || !isRecord(value) || !exactKeys(value, ["conflicts", "destination", "expectedSource", "review", "rights", "v"]) || value.v !== 1)
+    return null;
+  const destination = parseDestination(value.destination);
+  const expectedSource = parseExpectedSource(value.expectedSource);
+  const conflicts = parseConflicts(value.conflicts);
+  const review = parseReview(value.review);
+  const rights = destination === null ? null : parseRights(value.rights, destination.purpose);
+  return destination !== null && expectedSource !== null && conflicts !== null && review !== null && rights !== null ? immutableClone({ conflicts, destination, expectedSource, review, rights, v: 1 }) : null;
+}
+function verifyCapsule(value, expectedSource) {
+  try {
+    if (!structurallyBounded(value) || !isRecord(value) || !exactKeys(value, ["binding", "closureSha256", "head", "records", "roots", "v"]) || value.v !== 1 || !Array.isArray(value.records) || !Array.isArray(value.roots) || value.records.length < 1 || value.records.length > MAX_RECORDS || value.roots.length < 1 || value.roots.length > MAX_ROOTS || Buffer.byteLength(canonicalJson(value), "utf8") > MAX_CAPSULE_BYTES)
+      return null;
+    const verified = verifyOhDependencyClosureAgainstV1(value, {
+      binding: expectedSource.binding,
+      head: expectedSource.head
+    });
+    return verified.ok && verified.closure.binding.profile.profileKind === "working" ? verified.closure : null;
+  } catch {
+    return null;
+  }
+}
+function parseDisclosures(value, keys) {
+  if (!Array.isArray(value) || value.length > 256)
+    return null;
+  const parsed = [];
+  for (const item of value) {
+    if (!isRecord(item) || !exactKeys(item, ["id", "recordKey", "summary", "v"]) || item.v !== 1)
+      return null;
+    const id = code(item.id);
+    const key = recordKey(item.recordKey);
+    const summary = singleLine(item.summary);
+    if (id === null || key === null || summary === null || !keys.has(key))
+      return null;
+    parsed.push({ id, recordKey: key, summary, v: 1 });
+  }
+  parsed.sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+  return orderedUnique(parsed.map((item) => item.id)) ? parsed : null;
+}
+function markdownEscape(value) {
+  return value.replace(/[\\`*_{}\[\]<>()#+.!|>-]/gu, "\\$&");
+}
+function renderMarkdown(manifest, candidateSha256) {
+  const lines = [
+    "# Oh adoption candidate",
+    "",
+    `- Status: \`${manifest.status}\``,
+    `- Candidate: \`sha256:${candidateSha256}\``,
+    `- Destination: \`${manifest.destination.targetPath}\``,
+    `- Purpose: \`${manifest.destination.purpose}\``,
+    `- Source authority: \`${manifest.source.authorityId}\``,
+    `- Source binding: \`${manifest.source.binding.bindingSha256}\``,
+    `- Source head sequence: \`${manifest.source.head.sequence}\``,
+    `- Source head operation: \`${manifest.source.head.operationSha256 ?? "empty"}\``,
+    `- Source graph revision: \`${manifest.source.head.graphRevisionSha256 ?? "empty"}\``,
+    `- Source records digest: \`${manifest.source.head.recordsSha256}\``,
+    `- Closure: \`${manifest.source.closureSha256}\``,
+    "",
+    "This is a review candidate, not reviewed knowledge. It does not mutate a vault or adopt the source operation chain, database, projection, or derived tuples.",
+    "",
+    "## Required decisions",
+    "",
+    `- Rights: \`${manifest.rights.disposition}\` via \`${manifest.rights.decisionId}\` for \`${manifest.rights.purpose}\``,
+    `- Review: \`${manifest.review.status}\` via \`${manifest.review.route}\``,
+    `- Conflicts: \`${manifest.conflicts.status}\``,
+    ...manifest.conflicts.notes.map((note) => `  - ${markdownEscape(note)}`),
+    "",
+    "## Selected roots",
+    "",
+    ...manifest.source.roots.map((root) => `- \`${root}\``),
+    "",
+    "## Exact source records",
+    ""
+  ];
+  for (const record of manifest.source.records) {
+    lines.push(`### \`${record.key}\``, "", `- Kind: \`${record.kind}\``, `- Digest: \`${record.recordSha256}\``, `- Dependencies: ${record.dependencies.length === 0 ? "none" : record.dependencies.map((key) => `\`${key}\``).join(", ")}`, "");
+  }
+  lines.push("## Transformations", "", ...manifest.transformations.length === 0 ? ["- None declared."] : manifest.transformations.map((item) => `- \`${item.id}\` on \`${item.recordKey}\`: ${markdownEscape(item.summary)}`), "", "## Redactions", "", ...manifest.redactions.length === 0 ? ["- None declared."] : manifest.redactions.map((item) => `- \`${item.id}\` on \`${item.recordKey}\`: ${markdownEscape(item.summary)}`), "");
+  return `${lines.join(`
+`)}
+`;
+}
+function prepareWithPolicy(value, policy) {
+  if (!structurallyBounded(value) || !isRecord(value) || !exactKeys(value, ["capsule", "redactions", "transformations", "v"]) || value.v !== 1) {
+    throw new TypeError("Invalid Oh adoption preparation input.");
+  }
+  const capsule = verifyCapsule(value.capsule, policy.expectedSource);
+  if (capsule === null)
+    throw new TypeError("The source capsule is invalid for the bound authority and head.");
+  const recordKeys = new Set(capsule.records.map((record) => record.key));
+  const transformations = parseDisclosures(value.transformations, recordKeys);
+  const redactions = parseDisclosures(value.redactions, recordKeys);
+  const roots = new Set(capsule.roots);
+  if (transformations === null || redactions === null || capsule.records.filter((record) => roots.has(record.key)).every((record) => record.kind === "view")) {
+    throw new TypeError("Adoption requires valid disclosures and an authoritative root.");
+  }
+  const source = {
+    authorityId: policy.expectedSource.authorityId,
+    binding: { bindingSha256: capsule.binding.bindingSha256, v: 1 },
+    closureSha256: capsule.closureSha256,
+    head: capsule.head,
+    records: capsule.records.map((record) => ({
+      dependencies: record.dependencies,
+      key: record.key,
+      kind: record.kind,
+      recordSha256: record.recordSha256,
+      v: 1
+    })),
+    roots: capsule.roots,
+    v: 1
+  };
+  const manifest = {
+    conflicts: policy.conflicts,
+    destination: policy.destination,
+    format: "hraness.kb.oh-adoption-candidate.v1",
+    redactions,
+    review: policy.review,
+    rights: policy.rights,
+    source,
+    status: "prepared",
+    transformations,
+    v: 1
+  };
+  const candidateSha256 = canonicalSha256(manifest);
+  const markdown = renderMarkdown(manifest, candidateSha256);
+  if (Buffer.byteLength(markdown, "utf8") > MAX_CAPSULE_BYTES) {
+    throw new RangeError("The adoption candidate exceeds its Markdown byte limit.");
+  }
+  return immutableClone({
+    artifactSha256: createHash("sha256").update(markdown).digest("hex"),
+    candidateSha256,
+    manifest,
+    markdown,
+    v: 1
+  });
+}
+function createOhAdoptionPreparerV1(value) {
+  const policy = parseHostPolicy(value);
+  if (policy === null)
+    throw new TypeError("Invalid Oh adoption host policy.");
+  return Object.freeze({ prepare: (input) => prepareWithPolicy(input, policy) });
+}
 export {
   workflowFromUnknown,
   wikiLinks,
@@ -330,6 +638,7 @@ export {
   createVerifiedEmbeddingModelLease,
   createSyntheticRankFusionFixture,
   createRepresentativeRetrievalFixture,
+  createOhAdoptionPreparerV1,
   createNote,
   createConceptNote,
   compareAgentGuideAudits,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/kb",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "A knowledge base for coding agents, built from Markdown, backlinks, semantic search, and Git context.",
   "license": "MIT",
   "contentPolicy": {
@@ -335,6 +335,7 @@
     "src/init.ts",
     "src/navigation.ts",
     "src/note-lock.ts",
+    "src/oh-adoption.ts",
     "src/percolate.ts",
     "src/portfolio.ts",
     "src/portfolio-audit.ts",
@@ -391,6 +392,7 @@
     "prepack": "bun run check"
   },
   "dependencies": {
+    "@hraness/oh": "github:hraness/oh#v0.2.0",
     "@steipete/sweet-cookie": "github:hraness/sweet-cookie#v0.4.2",
     "@tobilu/qmd": "git+https://github.com/hraness/qmd.git#aa993dceb3ef8cfb71d470554ca437570f5a2b3c",
     "agent-browser": "0.32.3",

package/skills/kb/SKILL.md

@@ -3,12 +3,13 @@ name: kb
 description: >-
   Operate a hraness/kb local-first Markdown knowledge base for coding-agent
   memory. Use when a user asks to search or query a KB or Obsidian vault; load
-  repository context, plans, decisions, concepts, backlinks, semantic search,
-  or Git provenance; save, clip, scrape, or archive a URL, article, social
-  thread, signed-in browser page, or PDF as auditable Markdown; create or
-  update a durable plan in the vault; or refresh, check, percolate, and
-  maintain its knowledge graph. Do not use for generic web research, generic
-  PDF reading, or ordinary planning that will not use a hraness/kb vault.
+  or recover repository context, plans, decisions, concepts, backlinks,
+  semantic search, or Git provenance from an earlier coding session; save,
+  clip, scrape, or archive a URL, article, social thread, signed-in browser
+  page, or PDF as auditable Markdown; create or update a durable plan in the
+  vault; or refresh, check, percolate, and maintain its knowledge graph. Do not
+  use for generic web research, generic PDF reading, or ordinary planning that
+  will not use a hraness/kb vault.
 ---
 
 # Work with KB
@@ -31,7 +32,7 @@ missing:
 ```sh
 command -v kb >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global @hraness/kb@0.17.3
+  bun add --global @hraness/kb@0.18.1
 }
 kb --help
 ```
@@ -50,7 +51,7 @@ Initialize or mutate a vault only when the user's request requires that change.
 
 | User intent | Read |
 | --- | --- |
-| Find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
+| Recover work from an earlier session, find notes, search one vault or an authorized portfolio, load repository-path context, inspect plans or decisions, follow backlinks or relationships, audit vault organization, or retrieve Git provenance | [Query the knowledge base](references/query.md) |
 | Save, clip, scrape, or archive a URL, article, social post or thread, GitHub or Discourse discussion, signed-in page, feed, inbox, private document, WhatsApp conversation, or YouTube page | [Capture web content](references/save-url.md); add [browser authentication](references/url-authentication.md) for signed-in sources and [platform routing](references/url-platforms.md) when route choice or completeness matters |
 | Import, extract, archive, OCR, or convert a local or public PDF into Markdown | [Save a PDF](references/save-pdf.md); add [PDF image review](references/pdf-review.md) for scans, screenshots, conversations, charts, or mixed media |
 | Create or update an implementation plan, proposal, RFC, migration plan, execution audit, or phased checklist in the vault | [Write a durable plan](references/plan.md) and [use its structure](references/plan-structure.md) |

package/skills/kb/references/query.md

@@ -14,6 +14,27 @@ authority; search scores, metadata rows, and graph results are derived views.
 - Pass the resolved path to every `--root`; do not scan a repository root merely
   because that is where the agent session started.
 
+## Recover a stopped session
+
+When the user asks to resume earlier work, begin with the path being changed.
+Keep each retrieval signal separate so the agent can inspect why a record was
+returned:
+
+```sh
+kb context packages/parser/src/index.ts --root "$KB_ROOT" --repo "$KB_REPO"
+kb search "why parser retries stop" --root "$KB_ROOT" --mode exact \
+  --history --repo "$KB_REPO" --json
+kb backlinks notes/parser-contract --root "$KB_ROOT" --json
+kb history notes/parser-contract --root "$KB_ROOT" \
+  --repo "$KB_REPO" --json
+```
+
+Replace the example path, query, and note ID with values from the current task.
+Read the inherited guides and authoritative Markdown returned by these views.
+Use the backlink to inspect related plans and use Git history as provenance,
+not as proof that the note remains correct. This workflow recovers only context
+that was persisted in files or Git; it does not reconstruct private chat.
+
 ## Choose the retrieval lane
 
 - Repository file or directory: run `kb context` first. Read its inherited

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./git.js";
 export * from "./graph.js";
 export * from "./init.js";
 export * from "./navigation.js";
+export * from "./oh-adoption.js";
 export * from "./percolate.js";
 export * from "./query.js";
 export * from "./repository-memory.js";

package/src/oh-adoption.ts

@@ -0,0 +1,444 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+
+import { canonicalJson, canonicalSha256 } from "@hraness/oh";
+import {
+  parseOhHeadV1,
+  parseOhStoreBindingV1,
+  verifyOhDependencyClosureAgainstV1,
+  type OhDependencyClosureV1,
+  type OhHeadV1,
+  type OhStoreBindingV1,
+} from "@hraness/oh/store";
+
+const CODE_PATTERN = /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u;
+const RECORD_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u;
+const MAX_CAPSULE_BYTES = 16 * 1024 * 1024;
+const MAX_RECORDS = 1_024;
+const MAX_ROOTS = 256;
+const MAX_TEXT_BYTES = 4_096;
+const MAX_STRUCTURAL_NODES = 262_144;
+const MAX_STRUCTURAL_DEPTH = 128;
+
+export interface OhAdoptionExpectedSourceV1 {
+  readonly authorityId: string;
+  readonly binding: OhStoreBindingV1;
+  readonly head: OhHeadV1;
+  readonly v: 1;
+}
+
+export interface OhAdoptionDestinationV1 {
+  readonly purpose: string;
+  readonly targetPath: string;
+  readonly v: 1;
+}
+
+export interface OhAdoptionRightsClearanceV1 {
+  readonly decisionId: string;
+  readonly disposition: "cleared-for-purpose";
+  readonly purpose: string;
+  readonly v: 1;
+}
+
+export interface OhAdoptionReviewRequirementV1 {
+  readonly route: string;
+  readonly status: "required";
+  readonly v: 1;
+}
+
+export interface OhAdoptionConflictReviewV1 {
+  readonly notes: readonly string[];
+  readonly status: "none-observed" | "requires-resolution";
+  readonly v: 1;
+}
+
+export interface OhAdoptionChangeDisclosureV1 {
+  readonly id: string;
+  readonly recordKey: string;
+  readonly summary: string;
+  readonly v: 1;
+}
+
+export interface OhAdoptionHostPolicyV1 {
+  readonly conflicts: OhAdoptionConflictReviewV1;
+  readonly destination: OhAdoptionDestinationV1;
+  readonly expectedSource: OhAdoptionExpectedSourceV1;
+  readonly review: OhAdoptionReviewRequirementV1;
+  readonly rights: OhAdoptionRightsClearanceV1;
+  readonly v: 1;
+}
+
+export interface OhAdoptionPrepareInputV1 {
+  readonly capsule: OhDependencyClosureV1;
+  readonly redactions: readonly OhAdoptionChangeDisclosureV1[];
+  readonly transformations: readonly OhAdoptionChangeDisclosureV1[];
+  readonly v: 1;
+}
+
+export interface OhAdoptionCandidateV1 {
+  readonly artifactSha256: string;
+  readonly candidateSha256: string;
+  readonly manifest: Readonly<{
+    readonly conflicts: OhAdoptionConflictReviewV1;
+    readonly destination: OhAdoptionDestinationV1;
+    readonly format: "hraness.kb.oh-adoption-candidate.v1";
+    readonly redactions: readonly OhAdoptionChangeDisclosureV1[];
+    readonly review: OhAdoptionReviewRequirementV1;
+    readonly rights: OhAdoptionRightsClearanceV1;
+    readonly source: Readonly<{
+      readonly authorityId: string;
+      readonly binding: Readonly<{
+        readonly bindingSha256: string;
+        readonly v: 1;
+      }>;
+      readonly closureSha256: string;
+      readonly head: OhHeadV1;
+      readonly records: readonly Readonly<{
+        readonly dependencies: readonly string[];
+        readonly key: string;
+        readonly kind: string;
+        readonly recordSha256: string;
+        readonly v: 1;
+      }>[];
+      readonly roots: readonly string[];
+      readonly v: 1;
+    }>;
+    readonly status: "prepared";
+    readonly transformations: readonly OhAdoptionChangeDisclosureV1[];
+    readonly v: 1;
+  }>;
+  readonly markdown: string;
+  readonly v: 1;
+}
+
+export interface OhAdoptionPreparerV1 {
+  /** Accepts capsule bytes and disclosures only; all authority and policy are host-bound. */
+  prepare(value: unknown): OhAdoptionCandidateV1;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Reflect.ownKeys(value);
+  return actual.length === keys.length && actual.every((key) => {
+    if (typeof key !== "string" || !keys.includes(key)) return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined && descriptor.enumerable && "value" in descriptor;
+  });
+}
+
+function validUnicode(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next < 0xdc00 || next > 0xdfff) return false;
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) return false;
+  }
+  return true;
+}
+
+function structurallyBounded(value: unknown): boolean {
+  const pending: Array<readonly [unknown, number]> = [[value, 0]];
+  const seen = new Set<object>();
+  let nodes = 0;
+  let scalarBytes = 0;
+  while (pending.length > 0) {
+    const [candidate, depth] = pending.pop() as readonly [unknown, number];
+    nodes += 1;
+    scalarBytes += 4;
+    if (nodes > MAX_STRUCTURAL_NODES || depth > MAX_STRUCTURAL_DEPTH
+      || scalarBytes > MAX_CAPSULE_BYTES) return false;
+    if (typeof candidate === "string") {
+      if (!validUnicode(candidate)) return false;
+      scalarBytes += Buffer.byteLength(candidate, "utf8");
+      if (scalarBytes > MAX_CAPSULE_BYTES) return false;
+    }
+    if (typeof candidate !== "object" || candidate === null) continue;
+    if (seen.has(candidate)) return false;
+    seen.add(candidate);
+    if (Array.isArray(candidate)) {
+      if (candidate.length > MAX_STRUCTURAL_NODES) return false;
+      const keys = Reflect.ownKeys(candidate);
+      if (keys.some((key) => key !== "length" && (typeof key !== "string"
+        || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= candidate.length))) return false;
+      for (let index = 0; index < candidate.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index));
+        if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor)) return false;
+        pending.push([descriptor.value, depth + 1]);
+      }
+    } else if (isRecord(candidate)) {
+      const keys = Reflect.ownKeys(candidate);
+      if (keys.length > MAX_STRUCTURAL_NODES || keys.some((key) => typeof key !== "string")) return false;
+      for (const key of keys as string[]) {
+        const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+        if (descriptor === undefined || !descriptor.enumerable || !("value" in descriptor)
+          || !validUnicode(key)) return false;
+        scalarBytes += Buffer.byteLength(key, "utf8");
+        if (scalarBytes > MAX_CAPSULE_BYTES) return false;
+        pending.push([descriptor.value, depth + 1]);
+      }
+    } else return false;
+  }
+  return true;
+}
+
+function immutableClone<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((item) => immutableClone(item))) as T;
+  }
+  if (isRecord(value)) {
+    const clone: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) clone[key] = immutableClone(value[key]);
+    return Object.freeze(clone) as T;
+  }
+  return value;
+}
+
+function code(value: unknown, maximum = 256): string | null {
+  return typeof value === "string" && value.length <= maximum && CODE_PATTERN.test(value) ? value : null;
+}
+
+function recordKey(value: unknown): string | null {
+  return typeof value === "string" && value.length <= 512 && RECORD_KEY_PATTERN.test(value) ? value : null;
+}
+
+function orderedUnique(values: readonly string[]): boolean {
+  return values.every((value, index) => index === 0 || (values[index - 1] as string) < value);
+}
+
+function unsafeReviewCodePoint(codePoint: number): boolean {
+  return codePoint <= 0x1f
+    || (codePoint >= 0x7f && codePoint <= 0x9f)
+    || codePoint === 0x061c
+    || codePoint === 0x200e
+    || codePoint === 0x200f
+    || (codePoint >= 0x2028 && codePoint <= 0x202e)
+    || (codePoint >= 0x2066 && codePoint <= 0x2069)
+    || codePoint === 0xfeff;
+}
+
+function singleLine(value: unknown): string | null {
+  if (typeof value !== "string" || value.length < 1 || value.normalize("NFC") !== value
+    || !validUnicode(value) || [...value].some((character) =>
+      unsafeReviewCodePoint(character.codePointAt(0) ?? 0))
+    || Buffer.byteLength(value, "utf8") > MAX_TEXT_BYTES) return null;
+  return value;
+}
+
+function parseExpectedSource(value: unknown): OhAdoptionExpectedSourceV1 | null {
+  if (!isRecord(value) || !exactKeys(value, ["authorityId", "binding", "head", "v"])
+    || value.v !== 1) return null;
+  const authorityId = code(value.authorityId);
+  const binding = parseOhStoreBindingV1(value.binding);
+  const head = parseOhHeadV1(value.head);
+  return authorityId !== null && binding !== null && binding.profile.profileKind === "working" && head !== null
+    ? immutableClone({ authorityId, binding, head, v: 1 }) : null;
+}
+
+function parseDestination(value: unknown): OhAdoptionDestinationV1 | null {
+  if (!isRecord(value) || !exactKeys(value, ["purpose", "targetPath", "v"]) || value.v !== 1) return null;
+  const purpose = code(value.purpose);
+  if (purpose === null || typeof value.targetPath !== "string" || value.targetPath.length > 512
+    || value.targetPath.includes("\\") || value.targetPath.startsWith("/")
+    || posix.normalize(value.targetPath) !== value.targetPath
+    || !/^notes\/[a-z0-9][a-z0-9._/-]*\.md$/u.test(value.targetPath)
+    || value.targetPath.split("/").some((segment) => segment === "." || segment === ".." || segment.startsWith("."))) {
+    return null;
+  }
+  return { purpose, targetPath: value.targetPath, v: 1 };
+}
+
+function parseRights(value: unknown, purpose: string): OhAdoptionRightsClearanceV1 | null {
+  if (!isRecord(value) || !exactKeys(value, ["decisionId", "disposition", "purpose", "v"])
+    || value.v !== 1 || value.disposition !== "cleared-for-purpose" || value.purpose !== purpose) return null;
+  const decisionId = code(value.decisionId);
+  return decisionId === null ? null
+    : { decisionId, disposition: "cleared-for-purpose", purpose, v: 1 };
+}
+
+function parseReview(value: unknown): OhAdoptionReviewRequirementV1 | null {
+  if (!isRecord(value) || !exactKeys(value, ["route", "status", "v"])
+    || value.v !== 1 || value.status !== "required") return null;
+  const route = code(value.route);
+  return route === null ? null : { route, status: "required", v: 1 };
+}
+
+function parseConflicts(value: unknown): OhAdoptionConflictReviewV1 | null {
+  if (!isRecord(value) || !exactKeys(value, ["notes", "status", "v"]) || value.v !== 1
+    || (value.status !== "none-observed" && value.status !== "requires-resolution")
+    || !Array.isArray(value.notes) || value.notes.length < 1 || value.notes.length > 64) return null;
+  const notes = value.notes.map(singleLine);
+  if (notes.some((note) => note === null)) return null;
+  const sorted = [...notes as string[]].sort();
+  return orderedUnique(sorted) ? { notes: sorted, status: value.status, v: 1 } : null;
+}
+
+function parseHostPolicy(value: unknown): OhAdoptionHostPolicyV1 | null {
+  if (!structurallyBounded(value) || !isRecord(value)
+    || !exactKeys(value, ["conflicts", "destination", "expectedSource", "review", "rights", "v"])
+    || value.v !== 1) return null;
+  const destination = parseDestination(value.destination);
+  const expectedSource = parseExpectedSource(value.expectedSource);
+  const conflicts = parseConflicts(value.conflicts);
+  const review = parseReview(value.review);
+  const rights = destination === null ? null : parseRights(value.rights, destination.purpose);
+  return destination !== null && expectedSource !== null && conflicts !== null && review !== null && rights !== null
+    ? immutableClone({ conflicts, destination, expectedSource, review, rights, v: 1 }) : null;
+}
+
+function verifyCapsule(
+  value: unknown,
+  expectedSource: OhAdoptionExpectedSourceV1,
+): OhDependencyClosureV1 | null {
+  try {
+    if (!structurallyBounded(value) || !isRecord(value)
+      || !exactKeys(value, ["binding", "closureSha256", "head", "records", "roots", "v"])
+      || value.v !== 1 || !Array.isArray(value.records) || !Array.isArray(value.roots)
+      || value.records.length < 1 || value.records.length > MAX_RECORDS
+      || value.roots.length < 1 || value.roots.length > MAX_ROOTS
+      || Buffer.byteLength(canonicalJson(value), "utf8") > MAX_CAPSULE_BYTES) return null;
+    const verified = verifyOhDependencyClosureAgainstV1(value, {
+      binding: expectedSource.binding,
+      head: expectedSource.head,
+    });
+    return verified.ok && verified.closure.binding.profile.profileKind === "working"
+      ? verified.closure : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseDisclosures(value: unknown, keys: ReadonlySet<string>): readonly OhAdoptionChangeDisclosureV1[] | null {
+  if (!Array.isArray(value) || value.length > 256) return null;
+  const parsed: OhAdoptionChangeDisclosureV1[] = [];
+  for (const item of value) {
+    if (!isRecord(item) || !exactKeys(item, ["id", "recordKey", "summary", "v"]) || item.v !== 1) return null;
+    const id = code(item.id);
+    const key = recordKey(item.recordKey);
+    const summary = singleLine(item.summary);
+    if (id === null || key === null || summary === null || !keys.has(key)) return null;
+    parsed.push({ id, recordKey: key, summary, v: 1 });
+  }
+  parsed.sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+  return orderedUnique(parsed.map((item) => item.id)) ? parsed : null;
+}
+
+function markdownEscape(value: string): string {
+  return value.replace(/[\\`*_{}\[\]<>()#+.!|>-]/gu, "\\$&");
+}
+
+function renderMarkdown(manifest: OhAdoptionCandidateV1["manifest"], candidateSha256: string): string {
+  const lines = [
+    "# Oh adoption candidate",
+    "",
+    `- Status: \`${manifest.status}\``,
+    `- Candidate: \`sha256:${candidateSha256}\``,
+    `- Destination: \`${manifest.destination.targetPath}\``,
+    `- Purpose: \`${manifest.destination.purpose}\``,
+    `- Source authority: \`${manifest.source.authorityId}\``,
+    `- Source binding: \`${manifest.source.binding.bindingSha256}\``,
+    `- Source head sequence: \`${manifest.source.head.sequence}\``,
+    `- Source head operation: \`${manifest.source.head.operationSha256 ?? "empty"}\``,
+    `- Source graph revision: \`${manifest.source.head.graphRevisionSha256 ?? "empty"}\``,
+    `- Source records digest: \`${manifest.source.head.recordsSha256}\``,
+    `- Closure: \`${manifest.source.closureSha256}\``,
+    "",
+    "This is a review candidate, not reviewed knowledge. It does not mutate a vault or adopt the source operation chain, database, projection, or derived tuples.",
+    "",
+    "## Required decisions",
+    "",
+    `- Rights: \`${manifest.rights.disposition}\` via \`${manifest.rights.decisionId}\` for \`${manifest.rights.purpose}\``,
+    `- Review: \`${manifest.review.status}\` via \`${manifest.review.route}\``,
+    `- Conflicts: \`${manifest.conflicts.status}\``,
+    ...manifest.conflicts.notes.map((note) => `  - ${markdownEscape(note)}`),
+    "",
+    "## Selected roots",
+    "",
+    ...manifest.source.roots.map((root) => `- \`${root}\``),
+    "",
+    "## Exact source records",
+    "",
+  ];
+  for (const record of manifest.source.records) {
+    lines.push(`### \`${record.key}\``, "", `- Kind: \`${record.kind}\``,
+      `- Digest: \`${record.recordSha256}\``,
+      `- Dependencies: ${record.dependencies.length === 0 ? "none" : record.dependencies.map((key) => `\`${key}\``).join(", ")}`, "");
+  }
+  lines.push("## Transformations", "",
+    ...(manifest.transformations.length === 0 ? ["- None declared."] : manifest.transformations.map((item) =>
+      `- \`${item.id}\` on \`${item.recordKey}\`: ${markdownEscape(item.summary)}`)), "",
+    "## Redactions", "",
+    ...(manifest.redactions.length === 0 ? ["- None declared."] : manifest.redactions.map((item) =>
+      `- \`${item.id}\` on \`${item.recordKey}\`: ${markdownEscape(item.summary)}`)), "");
+  return `${lines.join("\n")}\n`;
+}
+
+function prepareWithPolicy(
+  value: unknown,
+  policy: OhAdoptionHostPolicyV1,
+): OhAdoptionCandidateV1 {
+  if (!structurallyBounded(value) || !isRecord(value)
+    || !exactKeys(value, ["capsule", "redactions", "transformations", "v"]) || value.v !== 1) {
+    throw new TypeError("Invalid Oh adoption preparation input.");
+  }
+  const capsule = verifyCapsule(value.capsule, policy.expectedSource);
+  if (capsule === null) throw new TypeError("The source capsule is invalid for the bound authority and head.");
+  const recordKeys = new Set(capsule.records.map((record) => record.key));
+  const transformations = parseDisclosures(value.transformations, recordKeys);
+  const redactions = parseDisclosures(value.redactions, recordKeys);
+  const roots = new Set(capsule.roots);
+  if (transformations === null || redactions === null
+    || capsule.records.filter((record) => roots.has(record.key)).every((record) => record.kind === "view")) {
+    throw new TypeError("Adoption requires valid disclosures and an authoritative root.");
+  }
+  const source = {
+    authorityId: policy.expectedSource.authorityId,
+    binding: { bindingSha256: capsule.binding.bindingSha256, v: 1 as const },
+    closureSha256: capsule.closureSha256,
+    head: capsule.head,
+    records: capsule.records.map((record) => ({ dependencies: record.dependencies, key: record.key,
+      kind: record.kind, recordSha256: record.recordSha256, v: 1 as const })),
+    roots: capsule.roots,
+    v: 1 as const,
+  };
+  const manifest = {
+    conflicts: policy.conflicts,
+    destination: policy.destination,
+    format: "hraness.kb.oh-adoption-candidate.v1" as const,
+    redactions,
+    review: policy.review,
+    rights: policy.rights,
+    source,
+    status: "prepared" as const,
+    transformations,
+    v: 1 as const,
+  };
+  const candidateSha256 = canonicalSha256(manifest);
+  const markdown = renderMarkdown(manifest, candidateSha256);
+  if (Buffer.byteLength(markdown, "utf8") > MAX_CAPSULE_BYTES) {
+    throw new RangeError("The adoption candidate exceeds its Markdown byte limit.");
+  }
+  return immutableClone({
+    artifactSha256: createHash("sha256").update(markdown).digest("hex"),
+    candidateSha256,
+    manifest,
+    markdown,
+    v: 1,
+  });
+}
+
+/**
+ * Captures all authority, destination, rights, review, and conflict policy in
+ * trusted host code. The returned facade can only prepare inert review bytes.
+ */
+export function createOhAdoptionPreparerV1(value: unknown): OhAdoptionPreparerV1 {
+  const policy = parseHostPolicy(value);
+  if (policy === null) throw new TypeError("Invalid Oh adoption host policy.");
+  return Object.freeze({ prepare: (input: unknown) => prepareWithPolicy(input, policy) });
+}