@hraness/kb 0.17.2 → 0.18.0

package/README.md

@@ -3,31 +3,55 @@
 
 [![skills.sh](https://skills.sh/b/hraness/kb)](https://skills.sh/hraness/kb)
 
-a knowledge base for coding agents, built from Markdown, backlinks, semantic
+A knowledge base for coding agents, built from Markdown, backlinks, semantic
 search, and Git context.
+It turns sources, plans, and decisions into inspectable context that agents can
+recover across sessions without coupling application code to the knowledge
+system.
 
-## install
+## Install
+
+Bun 1.3.14 or newer is required.
 
 ```sh
-bun add --global @hraness/kb@0.17.2
+bun add --global @hraness/kb@0.18.0
 ```
 
-## about
+## 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.
+
+## Create one durable note
+
+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
+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
+```
 
-Turn research, plans, and decisions into reusable context for coding agents.
-Keep sources and repository context beside your code in Markdown and Git. Your
-application stays independent.
+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.
 
-Search identifiers and metadata. Find meaning locally with QMD. Follow
-backlinks and typed relations. Inspect Git provenance. Search an explicitly
-authorized portfolio of vaults without merging their Markdown or comparing
-their local QMD scores.
+<!-- hraness:kb-landing:end -->
 
-Capture signed-in pages and PDFs. Use the TypeScript SDK and bounded workflows.
+## Links
 
-Markdown and Git stay authoritative. Indexes and graph views are replaceable.
+[Install `@hraness/kb` from npm](https://www.npmjs.com/package/@hraness/kb) ·
+[KB source on GitHub](https://github.com/hraness/kb) ·
+[KB overview](https://hraness.com/kb)
 
-## use
+## Use
 
 ```sh
 kb init kb
@@ -43,13 +67,6 @@ kb portfolio search "parser-v2" --registry kb-portfolio.json \
 kb history search packages/parser --root . --repo .. --json
 ```
 
-## links
-
-[npm](https://www.npmjs.com/package/@hraness/kb) ·
-[github](https://github.com/hraness/kb) ·
-[overview](https://hraness.com/kb)
-<!-- hraness:kb-landing:end -->
-
 ## 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.
@@ -113,7 +130,15 @@ kb history search packages/parser/src/index.ts --root kb --repo . --json
 
 ### Preserve evidence and plans as working records
 
-Durable reasoning needs inspectable evidence. `kb clip` can read a public URL, saved HTML, rendered page, a page already open in an authenticated browser, or an existing exact Archive.today snapshot after the direct routes fail. Archive fallback is read-only and always partial. The [capture documentation](<https://github.com/hraness/kb/blob/main/docs/capture.md>) defines the supported routes. A capture writes readable Markdown beside localized assets and `capture.json`, whose manifest records where the material came from, how it was extracted, what was saved, and any warnings. “Complete” describes the selected page surface, not every hidden branch or future version of the site.
+Durable reasoning needs inspectable evidence. `kb clip` can read a public URL,
+saved HTML, rendered page, a page already open in an authenticated browser, or
+an existing exact Archive.today snapshot after the direct routes fail. Archive
+fallback is read-only and always partial. The
+[capture documentation](docs/capture.md) defines the supported routes. A capture
+writes readable Markdown beside localized assets and `capture.json`, whose
+manifest records where the material came from, how it was extracted, what was
+saved, and any warnings. “Complete” describes the selected page surface, not
+every hidden branch or future version of the site.
 
 **Capture a web source or local PDF**
 
@@ -168,6 +193,24 @@ 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.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
@@ -207,7 +250,7 @@ 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.
 
-## Install
+## Installation reference
 
 [Bun](https://bun.sh/docs/installation) is the required runtime.
 
@@ -216,34 +259,35 @@ audit projection disposable.
 Copy this prompt into Codex, Claude Code, or another coding agent:
 
 ```text
-Install the `kb` Agent Skill from hraness/kb with the standard skills CLI. Use
-the skill's runtime instructions to install the exact `@hraness/kb@0.17.2`
-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.
+Install the `kb` Agent Skill from `hraness/kb#v0.18.0` with the standard skills
+CLI. Use the skill's runtime instructions to install the exact
+`@hraness/kb@0.18.0` 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.
 ```
 
 Install the single public skill with either runner:
 
 ```sh
-npx skills add hraness/kb
-bunx skills add hraness/kb
+npx skills add hraness/kb#v0.18.0
+bunx skills add hraness/kb#v0.18.0
 ```
 
 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.2` npm version.
+CLI from the immutable `@hraness/kb@0.18.0` npm version.
 
 The public skills CLI reads `skills/kb/` from the repository. The immutable
-`0.17.2` npm package includes the same tree under
+`0.18.0` 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.2
+bun add --global @hraness/kb@0.18.0
 kb --help
 kb-evaluation-builder --help
 ```
@@ -251,7 +295,7 @@ kb-evaluation-builder --help
 The same registry package can be installed with npm:
 
 ```sh
-npm install --global --ignore-scripts @hraness/kb@0.17.2
+npm install --global --ignore-scripts @hraness/kb@0.18.0
 kb --help
 ```
 
@@ -264,7 +308,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.2
+bun add --exact @hraness/kb@0.18.0
 ```
 
 The resulting dependency should remain exact:
@@ -272,12 +316,13 @@ The resulting dependency should remain exact:
 ```json
 {
   "dependencies": {
-    "@hraness/kb": "0.17.2"
+    "@hraness/kb": "0.18.0"
   }
 }
 ```
 
-Version 0.17.2 retains two public GitHub dependencies:
+Version 0.18.0 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
@@ -540,9 +585,9 @@ a vault. The package smoke test keeps future tagged packages byte-identical to
 that source tree.
 
 ```sh
-npx skills add hraness/kb
+npx skills add hraness/kb#v0.18.0
 # or
-bunx skills add hraness/kb
+bunx skills add hraness/kb#v0.18.0
 ```
 
 The skill invokes the installed `kb` command without depending on a repository

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.2",
+  "version": "0.18.0",
   "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

@@ -31,7 +31,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.2
+  bun add --global @hraness/kb@0.18.0
 }
 kb --help
 ```

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) });
+}