Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Open Knowledge Format (OKF) export / import round-trip
* (Brain Portability & Interop suite, Unit C).
*
* `buildOkfBundle` projects the vault into a portable markdown bundle
* (concepts / queries / references + date-grouped log + okf.json
* manifest); `readOkfBundle` + `importOkfBundle` reconstruct it, staging
* pages as review candidates by default and writing directly under
* `--trusted`. Foreign provenance (raw type + producer-specific
* frontmatter) survives a re-export.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
OKF_PRODUCER,
OKF_REVIEW_REL,
OKF_SCHEMA_VERSION,
OkfError,
buildOkfBundle,
buildOkfSubsetBundle,
collectOkfPages,
importOkfBundle,
readOkfBundle,
writeOkfBundle,
type OkfPage,
} from "../../../../src/core/brain/portability/okf.ts";
import { parseFrontmatter } from "../../../../src/core/vault.ts";
import type { FrontmatterValue } from "../../../../src/core/types.ts";
import {
installKnowledgePack,
readKnowledgePack,
sealKnowledgePack,
} from "../../../../src/core/brain/portability/knowledge-pack.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-okf-"));
// An unswitched vault: its Brain/ tree is the legacy layout under test.
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));
/** A fresh unswitched vault (its legacy `Brain/` tree in place) under the temp dir. */
function legacyVaultDir(prefix: string): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
mkdirSync(join(dir, "Brain"), { recursive: true });
return dir;
}
function note(rel: string, content: string): void {
const p = join(vault, rel);
mkdirSync(join(p, ".."), { recursive: true });
writeFileSync(p, content, "utf8");
}
function fileOf(files: ReadonlyArray<{ path: string; contents: string }>, path: string): string {
const f = files.find((x) => x.path === path);
if (!f) throw new Error(`bundle has no file ${path}`);
return f.contents;
}
describe("buildOkfBundle", () => {
test("classifies pages into concepts / queries / references by kind", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nlinks to [[Beta]].\n");
note("Brain/sources/src-paper.md", "---\ntitle: Paper\nkind: brain-source\n---\ncited.\n");
note("Brain/reports/2026-06-01-q.md", "---\ntitle: Q\nkind: brain-report\n---\nfindings.\n");
const bundle = buildOkfBundle(vault);
expect(bundle.manifest.schema).toBe(OKF_SCHEMA_VERSION);
expect(bundle.manifest.producer).toBe(OKF_PRODUCER);
const byPath = new Map(bundle.manifest.pages.map((p) => [p.path, p]));
expect(byPath.get("Notes/Alpha.md")?.class).toBe("concept");
expect(byPath.get("Brain/sources/src-paper.md")?.class).toBe("reference");
expect(byPath.get("Brain/reports/2026-06-01-q.md")?.class).toBe("query");
// Concept citation derived structurally from the body wikilink.
expect(byPath.get("Notes/Alpha.md")?.citations).toEqual(["Beta"]);
});
test("emits okf.json, index.md, log.md, and one file per page", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nbody.\n");
note("Brain/log/2026-06-01.md", "- did a thing\n");
note("Brain/log/2026-06-02.md", "- did another\n");
const bundle = buildOkfBundle(vault);
const paths = bundle.files.map((f) => f.path);
expect(paths).toContain("okf.json");
expect(paths).toContain("index.md");
expect(paths).toContain("log.md");
expect(paths).toContain("concepts/Alpha.md");
// Log is date-grouped under H2 headings, sorted ascending.
const log = fileOf(bundle.files, "log.md");
expect(log.indexOf("## 2026-06-01")).toBeGreaterThanOrEqual(0);
expect(log.indexOf("## 2026-06-01")).toBeLessThan(log.indexOf("## 2026-06-02"));
expect(bundle.manifest.log_days).toBe(2);
// Page file carries frontmatter + body verbatim.
const page = fileOf(bundle.files, "concepts/Alpha.md");
expect(page).toContain("title: Alpha");
expect(page).toContain("body.");
});
test("a per-device log shard is a log day, not an invisible file", () => {
// `Brain/log/` writes `<date>.<deviceId>.md` on every default install
// since the per-device shard layout landed, so a pattern that matched
// only the legacy un-sharded name reported `0 log day(s)` and an empty
// `log.md` for a vault with a full change log.
note("Brain/log/2026-06-01.bb4363ed.md", "- sharded entry\n");
note("Brain/log/2026-06-02.md", "- legacy entry\n");
const bundle = buildOkfBundle(vault);
const log = fileOf(bundle.files, "log.md");
expect(log).toContain("## 2026-06-01");
expect(log).toContain("sharded entry");
expect(bundle.manifest.log_days).toBe(2);
});
test("two shards of one day fold into one dated section", () => {
note("Brain/log/2026-06-01.aaaaaaaa.md", "- from device a\n");
note("Brain/log/2026-06-01.bbbbbbbb.md", "- from device b\n");
const bundle = buildOkfBundle(vault);
const log = fileOf(bundle.files, "log.md");
expect(log.match(/## 2026-06-01/g)?.length).toBe(1);
expect(log).toContain("from device a");
expect(log).toContain("from device b");
expect(bundle.manifest.log_days).toBe(1);
});
test("a `private: true` page exports in full - the key is not a boundary", () => {
// Retraction, asserted rather than assumed. Nothing under
// `portability/` reads this frontmatter key, the export composers are
// content composers rather than visibility filters, and the
// `<private>` REGION marker is the product's only content-derived
// privacy primitive. The test exists so the label cannot be re-read as
// a boundary by a later reader.
note(
"Notes/Labelled.md",
"---\ntitle: Labelled\nprivate: true\ntags: [private, confidential]\n---\nsalary discussion.\n",
);
const bundle = buildOkfBundle(vault);
const page = fileOf(bundle.files, "concepts/Labelled.md");
expect(page).toContain("private: true");
expect(page).toContain("salary discussion.");
expect(bundle.manifest.pages.map((p) => p.path)).toContain("Notes/Labelled.md");
});
test("excludes Brain machinery (preferences, inbox) from pages", () => {
note("Notes/Real.md", "---\ntitle: Real\n---\nx\n");
note("Brain/preferences/pref-foo.md", "---\nid: pref-foo\n---\nrule\n");
note("Brain/inbox/sig-2026-06-01-foo.md", "---\ntopic: foo\n---\nsig\n");
const bundle = buildOkfBundle(vault);
const paths = bundle.manifest.pages.map((p) => p.path);
expect(paths).toContain("Notes/Real.md");
expect(paths.some((p) => p.startsWith("Brain/preferences"))).toBe(false);
expect(paths.some((p) => p.startsWith("Brain/inbox"))).toBe(false);
});
test("content is deterministic across two builds (one shared generated instant)", () => {
note("Notes/B.md", "---\ntitle: B\n---\nsee [[A]].\n");
note("Notes/A.md", "---\ntitle: A\n---\nleaf.\n");
const first = buildOkfBundle(vault);
const second = buildOkfBundle(vault);
// Every nondeterministic byte in the bundle flows from ONE generated
// instant: the manifest's `generated_at` and every page's
// `generated.at` (the two normalized fields) share the single bundle
// value. Substituting the first build's instant into the second must
// therefore make the two builds byte-identical - a timestamp that did
// not share would survive the substitution and fail the comparison.
const instant = second.manifest.generated_at;
const normalized = second.files.map((f) => ({
path: f.path,
contents: f.contents.split(instant).join(first.manifest.generated_at),
}));
expect(JSON.stringify(normalized)).toBe(JSON.stringify(first.files));
expect(JSON.stringify(first.manifest.pages)).toBe(JSON.stringify(second.manifest.pages));
});
test("de-duplicates colliding basenames within a class subdir", () => {
note("A/Dup.md", "---\ntitle: one\n---\nx\n");
note("B/Dup.md", "---\ntitle: two\n---\ny\n");
const bundle = buildOkfBundle(vault);
const bundlePaths = bundle.manifest.pages.map((p) => p.bundle_path).toSorted();
expect(bundlePaths).toEqual(["concepts/Dup-2.md", "concepts/Dup.md"]);
});
});
/**
* OKF v0.2 emission (t_ffdb4fac): the bundle-root index declares
* `okf_version: "0.2"` (the only frontmatter an index file may carry),
* every page frontmatter carries the spec's per-concept keys -
* `sources:` translated from citations with a REQUIRED `resource`, and
* `generated: {by, at}` sharing the one bundle instant - and the open
* status vocabulary lands on the spec's closed draft|stable|deprecated
* enum conservatively.
*/
describe("v0.2 emission", () => {
test("the bundle-root index declares okf_version and the manifest keeps the dialect schema", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nbody.\n");
const bundle = buildOkfBundle(vault);
const index = fileOf(bundle.files, "index.md");
expect(index.startsWith('---\nokf_version: "0.2"\n---\n')).toBe(true);
// The dialect manifest field is untouched: `schema` stays "1".
expect(bundle.manifest.schema).toBe(OKF_SCHEMA_VERSION);
});
test("every page carries a generated block sharing the bundle instant", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nsee [[Beta]].\n");
note("Notes/Beta.md", "---\ntitle: Beta\n---\nleaf.\n");
const bundle = buildOkfBundle(vault);
const ats = bundle.manifest.pages.map((p) => {
const page = fileOf(bundle.files, p.bundle_path);
const m = page.match(/generated: \{by: "open-second-brain\/[^"]+", at: "([^"]+)"\}/);
expect(m).not.toBeNull();
return m![1]!;
});
expect(ats.length).toBe(bundle.manifest.pages.length);
expect(new Set(ats).size).toBe(1);
expect(ats[0]).toBe(bundle.manifest.generated_at);
});
test("flow scalars render as JSON double-quoted YAML, safe for ids like 2024", () => {
// A bare `id: 2024` is an integer to a strict YAML reader, and bare
// true/null/~ are booleans or null: every emitted scalar is a
// double-quoted JSON string, which is valid YAML of type string.
note("Notes/2024.md", "---\ntitle: Year\n---\nleaf.\n");
note("Notes/Citer.md", "---\ntitle: Citer\n---\nsee [[2024]].\n");
const bundle = buildOkfBundle(vault);
const citer = fileOf(bundle.files, "concepts/Citer.md");
expect(citer).toContain('- {resource: "concepts/2024.md", id: "2024"}');
expect(citer).not.toContain("id: 2024");
});
test("citations translate into sources with a required resource", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nsee [[Beta]], [[Deep/Gamma]].\n");
note("Notes/Beta.md", "---\ntitle: Beta\n---\nleaf.\n");
note("Deep/Gamma.md", "---\ntitle: Gamma\n---\nleaf.\n");
note("Notes/Url.md", "---\ntitle: Url\n---\ncited [[https://example.com/paper]].\n");
const bundle = buildOkfBundle(vault);
const alpha = fileOf(bundle.files, "concepts/Alpha.md");
expect(alpha).toContain("sources:");
expect(alpha).toContain('- {resource: "concepts/Beta.md", id: "Beta"}');
expect(alpha).toContain('- {resource: "concepts/Gamma.md", id: "Gamma"}');
// A URL target is carried as-is; the manifest mirrors the entries.
const url = fileOf(bundle.files, "concepts/Url.md");
expect(url).toContain('- {resource: "https://example.com/paper"}');
const alphaEntry = bundle.manifest.pages.find((p) => p.path === "Notes/Alpha.md");
expect(alphaEntry?.sources).toEqual([
{ resource: "concepts/Beta.md", id: "Beta" },
{ resource: "concepts/Gamma.md", id: "Gamma" },
]);
});
test("a dangling citation is dropped, not guessed", () => {
note(
"Notes/Lonely.md",
"---\ntitle: Lonely\n---\nsee [[Ghost]] and [[https://example.com/real]].\n",
);
const bundle = buildOkfBundle(vault);
const page = fileOf(bundle.files, "concepts/Lonely.md");
// The URL source survives; the unresolvable wikilink never becomes a
// source entry (the body keeps its verbatim link either way).
expect(page).toContain('- {resource: "https://example.com/real"}');
expect(page).not.toContain("{resource: Ghost");
expect(page).not.toContain("id: Ghost");
});
test("an ambiguous basename citation is dropped rather than guessed", () => {
note("A/Dup.md", "---\ntitle: one\n---\nx\n");
note("B/Dup.md", "---\ntitle: two\n---\ny\n");
note("Notes/Citer.md", "---\ntitle: Citer\n---\nsee [[Dup]].\n");
const bundle = buildOkfBundle(vault);
const citer = fileOf(bundle.files, "concepts/Citer.md");
expect(citer).not.toContain("sources:");
expect(citer).not.toContain("resource:");
});
test("a path citation into colliding stems emits the resource without an id", () => {
// The path resolves the page (bundle_path names exactly one file), but
// the stem does not name an id: A/Dup.md and B/Dup.md are both id
// "Dup". The id field is documented as a stable key, so the entry
// carries the resource only - same refuse-to-guess rule as the
// basename branch.
note("A/Dup.md", "---\ntitle: one\n---\nx\n");
note("B/Dup.md", "---\ntitle: two\n---\ny\n");
note("Notes/Citer.md", "---\ntitle: Citer\n---\nsee [[B/Dup]].\n");
const bundle = buildOkfBundle(vault);
const citer = fileOf(bundle.files, "concepts/Citer.md");
expect(citer).toContain('- {resource: "concepts/Dup-2.md"}');
expect(citer).not.toContain("id:");
const entry = bundle.manifest.pages.find((p) => p.path === "Notes/Citer.md");
expect(entry?.sources).toEqual([{ resource: "concepts/Dup-2.md" }]);
});
test("an extension-bearing basename citation resolves through the stem map", () => {
// `[[Dup.md]]` names the same page `[[Dup]]` does: the citation keeps
// its extension while the stem map keys on stems, so the resolver
// falls back to stem(citation) instead of dropping a resolvable page.
note("Notes/Dup.md", "---\ntitle: Dup\n---\nleaf.\n");
note("Notes/Citer.md", "---\ntitle: Citer\n---\nsee [[Dup.md]].\n");
const bundle = buildOkfBundle(vault);
const citer = fileOf(bundle.files, "concepts/Citer.md");
expect(citer).toContain('- {resource: "concepts/Dup.md", id: "Dup"}');
const entry = bundle.manifest.pages.find((p) => p.path === "Notes/Citer.md");
expect(entry?.sources).toEqual([{ resource: "concepts/Dup.md", id: "Dup" }]);
});
test("an extension-bearing ambiguous basename citation is still dropped", () => {
note("A/Dup.md", "---\ntitle: one\n---\nx\n");
note("B/Dup.md", "---\ntitle: two\n---\ny\n");
note("Notes/Citer.md", "---\ntitle: Citer\n---\nsee [[Dup.md]].\n");
const bundle = buildOkfBundle(vault);
const citer = fileOf(bundle.files, "concepts/Citer.md");
expect(citer).not.toContain("sources:");
expect(citer).not.toContain("resource:");
});
test("lifecycle maps conservatively onto draft | stable | deprecated", () => {
note("Notes/Done.md", "---\ntitle: Done\nstatus: done\n---\nx\n");
note("Notes/Archived.md", "---\ntitle: Archived\nstatus: archived\n---\nx\n");
note("Notes/Draft.md", "---\ntitle: Draft\nstatus: draft\n---\nx\n");
note("Notes/Plain.md", "---\ntitle: Plain\n---\nx\n");
const bundle = buildOkfBundle(vault);
const pageOf = (rel: string): string => fileOf(bundle.files, `concepts/${rel}.md`);
// Completion is never mapped to deprecation.
expect(pageOf("Done")).toContain("status: stable");
expect(pageOf("Done")).not.toContain("status: done");
expect(pageOf("Archived")).toContain("status: deprecated");
expect(pageOf("Draft")).toContain("status: draft");
expect(pageOf("Plain")).toContain("status: stable");
const byPath = new Map(bundle.manifest.pages.map((p) => [p.path, p]));
expect(byPath.get("Notes/Done.md")?.status).toBe("stable");
expect(byPath.get("Notes/Archived.md")?.status).toBe("deprecated");
expect(byPath.get("Notes/Draft.md")?.status).toBe("draft");
expect(byPath.get("Notes/Plain.md")?.status).toBe("stable");
});
});
/**
* The OKF v0.2 spec's only ALWAYS-REQUIRED per-concept key is `type`
* (non-empty). The export therefore emits a derived `type` on every page
* - the preserved foreign type when the page came from a foreign
* producer, else the page's own structural kind - and carries a native
* frontmatter `type` through the producer namespace (`okf_type_raw`,
* beside `okf_status_raw`) so an own-producer trusted import restores it
* exactly instead of keeping the derived projection.
*/
describe("v0.2 type emission", () => {
test("every exported page carries a non-empty derived type", () => {
note("Notes/Plain.md", "---\ntitle: Plain\n---\nbody.\n");
note("Notes/Typed.md", "---\ntitle: Typed\nkind: book\n---\nbody.\n");
note("Brain/sources/src-paper.md", "---\ntitle: Paper\nkind: brain-source\n---\ncited.\n");
const bundle = buildOkfBundle(vault);
expect(bundle.manifest.pages.length).toBe(3);
for (const p of bundle.manifest.pages) {
const page = fileOf(bundle.files, p.bundle_path);
const m = /^type: "(.+)"$/m.exec(page);
expect(m).not.toBeNull();
expect(m![1]!.length).toBeGreaterThan(0);
}
// The derived type is the page's own kind, not its structural lane:
// the sources-lane page keeps the kind its frontmatter declares.
expect(fileOf(bundle.files, "concepts/Plain.md")).toContain('type: "note"');
expect(fileOf(bundle.files, "concepts/Typed.md")).toContain('type: "book"');
expect(fileOf(bundle.files, "references/src-paper.md")).toContain('type: "brain-source"');
});
test("a foreign page's preserved raw type is the derived type on re-export", () => {
note("Imported/Foo.md", "---\ntitle: Foo\nokf_type: encyclopedia-entry\n---\nbody\n");
const bundle = buildOkfBundle(vault);
expect(fileOf(bundle.files, "concepts/Foo.md")).toContain('type: "encyclopedia-entry"');
});
test("a native type is carried raw and restored byte-exact through a trusted import", () => {
// The derived emission is a projection (foreign type, else the
// structural kind); a native `type` the operator wrote must not be
// shadowed by it. The native value rides `okf_type_raw` beside the
// derived block, and an own-producer trusted import restores it
// exactly - the same contract as `okf_status_raw`.
note("Notes/Beta.md", "---\ntitle: Beta\ntype: glossary-entry\n---\nbody.\n");
const bundle = buildOkfBundle(vault);
const beta = fileOf(bundle.files, "concepts/Beta.md");
expect(beta).toContain("okf_type_raw: glossary-entry");
// The derived emission names the kind; the native value rides raw.
expect(beta).toContain('type: "note"');
expect(beta).not.toContain("type: glossary-entry");
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-type-rt-"));
const dest = legacyVaultDir("o2b-okf-type-rt-dest-");
try {
writeOkfBundle(dir, bundle);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Beta.md"), "utf8");
expect(landed).toContain("type: glossary-entry");
expect(landed).not.toContain('type: "note"');
expect(landed).not.toContain("okf_type_raw");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a plain page round-trips without the derived block, from the first export", () => {
// A fresh export declares its full coverage - the derived type
// included - so the trusted import strips the WHOLE derived block
// from a page that never carried one natively. Under the bare-true
// marker the type pair went undeclared, and the derived type
// survived the import as a real native field: one step of drift,
// locked in by every export after it. Absent okf_type_raw beside a
// marker naming `type` means "the export derived this type" - never
// "delete a native type": a page whose export rode a REAL native
// type verbatim keeps it (the legacy marker below).
note("Notes/Plain.md", "---\ntitle: Plain\n---\nbody.\n");
const bundle = buildOkfBundle(vault);
const plain = fileOf(bundle.files, "concepts/Plain.md");
expect(plain).toContain('type: "note"');
// The marker names exactly the natives the exporter manages, inline.
expect(plain).toContain("okf_raw: [status, sources, generated, type]");
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-type-plain-"));
const dest = legacyVaultDir("o2b-okf-type-plain-dest-");
const dir2 = mkdtempSync(join(tmpdir(), "o2b-okf-type-plain-rt-"));
const dest2 = mkdtempSync(join(tmpdir(), "o2b-okf-type-plain-rt-dest-"));
try {
writeOkfBundle(dir, bundle);
const result = importOkfBundle(dest, readOkfBundle(dir), { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Plain.md"), "utf8");
expect(landed).not.toContain("type:");
expect(landed).not.toContain("okf_type_raw");
expect(landed).not.toContain("status:");
expect(landed).not.toContain("sources:");
expect(landed).not.toContain("generated:");
expect(landed).not.toContain("okf_raw");
expect(landed).toContain("title: Plain");
// The round-trip converges from the first export: the imported
// page re-exports with the derived block beside a fresh full
// marker, and the next import strips it again - the derived type
// never accumulates into a native.
const second = buildOkfBundle(dest);
expect(fileOf(second.files, "concepts/Plain.md")).toContain(
"okf_raw: [status, sources, generated, type]",
);
writeOkfBundle(dir2, second);
const result2 = importOkfBundle(dest2, readOkfBundle(dir2), { trusted: true });
expect(result2.errors).toEqual([]);
const relanded = readFileSync(join(dest2, "Notes/Plain.md"), "utf8");
expect(relanded).not.toContain("type:");
expect(relanded).toContain("title: Plain");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
rmSync(dir2, { recursive: true, force: true });
rmSync(dest2, { recursive: true, force: true });
}
});
});
/**
* The `okf_raw` marker declares which native fields the export managed:
* `true` (the shape every exporter stamped before the marker could
* declare coverage) covers the old status/sources/generated set, a list
* of native names covers exactly what it names, and the restore drops a
* native ONLY when its pair was declared. Reading a bare `true` as
* covering `type` too deleted real native types: exports produced before
* the type pair existed carried a page's `type` verbatim beside the
* marker with no `okf_type_raw`, and the restore read that absence as
* "never had a value".
*/
describe("the raw-carry marker declares what it covers", () => {
const entry = {
id: "Topic",
path: "Notes/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "stable",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
} as const;
/** Hand-build an own-producer bundle whose single page is caller-written. */
function ownBundle(dir: string, pageContents: string): void {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Declared",
log_days: 0,
pages: [entry],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(join(dir, "concepts/Topic.md"), pageContents, "utf8");
}
test("a legacy marker-bearing page keeps its native type through import", () => {
// The pre-type-pair export shape: a native `type` rode the page
// verbatim beside the bare `okf_raw: true` marker, and no
// okf_type_raw existed. The restore covers only what the marker
// declares (status / sources / generated), so the real type survives
// - trusted round-trip and review staging alike.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-mark-type-"));
const trustedDest = mkdtempSync(join(tmpdir(), "o2b-okf-mark-type-tr-"));
const reviewDest = mkdtempSync(join(tmpdir(), "o2b-okf-mark-type-rv-"));
try {
ownBundle(
dir,
"---\ntitle: Topic\ntype: glossary-entry\nokf_status_raw: quarantine\nstatus: stable\nokf_raw: true\n---\nBody.\n",
);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const trusted = importOkfBundle(trustedDest, parsed, { trusted: true });
expect(trusted.errors).toEqual([]);
const landed = readFileSync(join(trustedDest, "Notes/Topic.md"), "utf8");
expect(landed).toContain("type: glossary-entry");
expect(landed).toContain("status: quarantine");
expect(landed).not.toContain("status: stable");
expect(landed).not.toContain("okf_type_raw");
expect(landed).not.toContain("okf_status_raw");
expect(landed).not.toContain("okf_raw");
expect(landed).toContain("Body.");
const review = importOkfBundle(reviewDest, parsed, { now: new Date(0) });
expect(review.errors).toEqual([]);
const staged = readFileSync(join(reviewDest, OKF_REVIEW_REL, "Notes", "Topic.md"), "utf8");
expect(staged).toContain("type: glossary-entry");
expect(staged).toContain("okf_review: pending");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(trustedDest, { recursive: true, force: true });
rmSync(reviewDest, { recursive: true, force: true });
}
});
test("a declared-but-absent native still strips, and an undeclared one survives", () => {
// A list marker covers exactly what it names: status and type are
// declared and absent, so their derived values drop; generated was
// never declared, so its derived value lands instead of being
// dropped by a guess.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-mark-list-"));
const dest = legacyVaultDir("o2b-okf-mark-list-dest-");
try {
ownBundle(
dir,
'---\ntitle: Declared\nokf_raw: [status, type]\nstatus: stable\ntype: "note"\ngenerated: {by: "someone/1.0", at: "2026-06-01T00:00:00Z"}\n---\nBody.\n',
);
const parsed = readOkfBundle(dir);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Topic.md"), "utf8");
expect(landed).not.toContain("status:");
expect(landed).not.toContain("type:");
expect(landed).toContain("generated:");
expect(landed).not.toContain("okf_raw");
expect(landed).toContain("Body.");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
});
/**
* Manifest-less, spec-shaped OKF v0.2 bundles: the spec defines a bundle
* as a plain directory tree of markdown (reserving index.md and log.md)
* and requires NO manifest, so a tree whose bundle-root index declares
* `okf_version: "0.2"` must import even without okf.json. The page list
* is built by walking the tree; every walked page routes through the
* EXISTING foreign-producer path - staged for review, provenance
* stamped, machinery keys stripped - never a silent restore. A bundle
* WITH okf.json keeps the manifest path and its schema gate entirely,
* and every refusal but the absent-manifest one is unchanged.
*/
describe("manifest-less spec-shaped v0.2 bundles", () => {
/** Hand-built spec-shaped bundle: index.md + pages, no okf.json. */
function specBundle(dir: string): void {
mkdirSync(join(dir, "concepts"), { recursive: true });
mkdirSync(join(dir, "queries"), { recursive: true });
mkdirSync(join(dir, "references"), { recursive: true });
mkdirSync(join(dir, "notes"), { recursive: true });
writeFileSync(join(dir, "index.md"), '---\nokf_version: "0.2"\n---\n# Foreign\n', "utf8");
writeFileSync(join(dir, "log.md"), "## 2026-06-01\n\n- old news\n", "utf8");
writeFileSync(
join(dir, "concepts/foo.md"),
"---\ntitle: Foo\ntype: wiki-article\n_status: confirmed\nowner: someone\n---\nFoo body.\n",
"utf8",
);
writeFileSync(join(dir, "queries/q.md"), "---\ntitle: Q\ntype: report\n---\nQ body.\n", "utf8");
writeFileSync(
join(dir, "references/r.md"),
"---\ntitle: R\ntype: paper\n---\nR body.\n",
"utf8",
);
writeFileSync(join(dir, "notes/n.md"), "---\ntitle: N\ntype: zettel\n---\nN body.\n", "utf8");
writeFileSync(
join(dir, "loose.md"),
"---\ntitle: Loose\ntype: note\n---\nLoose body.\n",
"utf8",
);
}
test("a bundle with no okf.json and a v0.2 index is read by walking the tree", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-spec-"));
try {
specBundle(dir);
const parsed = readOkfBundle(dir);
// Reserved files are never pages; everything else is.
expect(parsed.pages.map((p) => p.entry.bundle_path).toSorted()).toEqual([
"concepts/foo.md",
"loose.md",
"notes/n.md",
"queries/q.md",
"references/r.md",
]);
// Class comes from the directory name when it names a class lane,
// and defaults to concept everywhere else (foreign dirs, root).
const byPath = new Map(parsed.pages.map((p) => [p.entry.bundle_path, p.entry]));
expect(byPath.get("concepts/foo.md")?.class).toBe("concept");
expect(byPath.get("queries/q.md")?.class).toBe("query");
expect(byPath.get("references/r.md")?.class).toBe("reference");
expect(byPath.get("notes/n.md")?.class).toBe("concept");
expect(byPath.get("loose.md")?.class).toBe("concept");
// Native frontmatter and body are intact.
const foo = parsed.pages.find((p) => p.entry.bundle_path === "concepts/foo.md")!;
expect(foo.frontmatter["title"]).toBe("Foo");
expect(foo.frontmatter["type"]).toBe("wiki-article");
expect(foo.body).toContain("Foo body.");
// No manifest declared anything: the parsed manifest shows it.
expect(parsed.manifest.schema).toBe("");
expect(parsed.foreign).toBe(true);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("imported spec pages stage for review through the foreign-producer path", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-spec-imp-"));
const dest = legacyVaultDir("o2b-okf-spec-imp-dest-");
try {
specBundle(dir);
const result = importOkfBundle(dest, readOkfBundle(dir), { now: new Date(0) });
expect(result.mode).toBe("review");
expect(result.errors).toEqual([]);
const staged = readFileSync(join(dest, OKF_REVIEW_REL, "concepts/foo.md"), "utf8");
// Native frontmatter intact.
expect(staged).toContain("title: Foo");
expect(staged).toContain("type: wiki-article");
// Provenance stamped: the spec page's own type is the raw foreign
// type the stamp preserves.
expect(staged).toContain("okf_producer: unknown");
expect(staged).toContain("okf_type: wiki-article");
expect(staged).toContain('okf_imported_at: "1970-01-01T00:00:00Z"');
expect(staged).toContain("okf_review: pending");
// Machinery keys are stripped, never silently restored, and this
// system's raw namespace cannot be planted through the walk either.
expect(staged).not.toContain("_status:");
expect(staged).not.toContain("owner:");
expect(staged).not.toContain("okf_raw");
expect(staged).toContain("Foo body.");
// The reserved change log is not staged as a page.
expect(existsSync(join(dest, OKF_REVIEW_REL, "log.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a nested index.md is a page; only the bundle-root index and log are reserved", () => {
// The reserved-name check compared the BASENAME at any depth, so a
// foreign bundle's real nested pages - a concepts/index.md, a
// per-project log page - were silently dropped from the walk. The
// spec's reservation is a bundle-ROOT one: index.md at the top is
// the version declaration and log.md the change log; the same names
// below the root are nobody's machinery.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-spec-nested-"));
const dest = legacyVaultDir("o2b-okf-spec-nested-dest-");
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
writeFileSync(join(dir, "index.md"), '---\nokf_version: "0.2"\n---\n# Root\n', "utf8");
writeFileSync(join(dir, "log.md"), "## 2026-06-01\n\n- old news\n", "utf8");
mkdirSync(join(dir, "notes"), { recursive: true });
writeFileSync(
join(dir, "concepts", "index.md"),
"---\ntitle: Index Page\ntype: zettel\n---\nNested body.\n",
"utf8",
);
writeFileSync(
join(dir, "notes", "log.md"),
"---\ntitle: Project Log\ntype: zettel\n---\nLog body.\n",
"utf8",
);
const parsed = readOkfBundle(dir);
expect(parsed.pages.map((p) => p.entry.bundle_path).toSorted()).toEqual([
"concepts/index.md",
"notes/log.md",
]);
const result = importOkfBundle(dest, parsed, { now: new Date(0) });
expect(result.errors).toEqual([]);
expect(result.written).toEqual([
`${OKF_REVIEW_REL}/concepts/index.md`,
`${OKF_REVIEW_REL}/notes/log.md`,
]);
const staged = readFileSync(join(dest, OKF_REVIEW_REL, "concepts", "index.md"), "utf8");
expect(staged).toContain("title: Index Page");
expect(staged).toContain("Nested body.");
// The root files stay reserved: never staged as pages.
expect(existsSync(join(dest, OKF_REVIEW_REL, "index.md"))).toBe(false);
expect(existsSync(join(dest, OKF_REVIEW_REL, "log.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a manifest-less tree without a v0.2 index declaration is still refused by name", () => {
const noIndex = mkdtempSync(join(tmpdir(), "o2b-okf-spec-noindex-"));
const unversioned = mkdtempSync(join(tmpdir(), "o2b-okf-spec-unvers-"));
const wrongVersion = mkdtempSync(join(tmpdir(), "o2b-okf-spec-wrongvers-"));
try {
specBundle(noIndex);
rmSync(join(noIndex, "index.md"));
expect(() => readOkfBundle(noIndex)).toThrow("not an OKF bundle");
specBundle(unversioned);
writeFileSync(join(unversioned, "index.md"), "# No version declared\n", "utf8");
expect(() => readOkfBundle(unversioned)).toThrow("not an OKF bundle");
specBundle(wrongVersion);
writeFileSync(
join(wrongVersion, "index.md"),
'---\nokf_version: "9.9"\n---\n# Future\n',
"utf8",
);
expect(() => readOkfBundle(wrongVersion)).toThrow("not an OKF bundle");
} finally {
rmSync(noIndex, { recursive: true, force: true });
rmSync(unversioned, { recursive: true, force: true });
rmSync(wrongVersion, { recursive: true, force: true });
}
});
test("a present okf.json with a wrong schema is still refused beside a v0.2 index", () => {
// The manifest path and its schema gate are untouched by the
// manifest-less acceptance: a PRESENT wrong schema never falls back
// to the version declaration.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-spec-manifest-"));
try {
specBundle(dir);
const manifest = {
schema: "999",
producer: "some-other-wiki",
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Foreign",
log_days: 0,
pages: [],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
expect(() => readOkfBundle(dir)).toThrow("unsupported OKF schema: expected 1, got 999");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
/**
* OKF v0.2 import acceptance (t_ffdb4fac): the reader admits a bundle
* whose manifest carries the Open Second Brain dialect `schema: "1"` OR
* one that declares NO manifest schema while its bundle-root index
* declares `okf_version: "0.2"`, preserves the on-disk schema value
* instead of stamping its own constant, and still refuses everything
* else by name. The index path is version-level only: the gate never
* reads the producer. A PRESENT non-dialect schema is refused even
* beside a v0.2 index - otherwise every future dialect bump would slip
* through under v1 assumptions, because this export's own index always
* declares okf_version.
*/
describe("v0.2 import acceptance", () => {
/**
* Hand-build a bundle in `dir` in the singlePageBundle pattern, with
* caller-chosen manifest `schema` and index `okf_version` markers
* (either may be null to omit the marker entirely). The producer is a
* foreign one throughout: the gate is version-level, not producer-
* keyed, so every acceptance test doubles as the wrong-producer pin.
*/
function bundleWithMarkers(
dir: string,
schema: string | null,
indexVersion: string | null,
): void {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest: Record<string, unknown> = {
producer: "some-other-wiki",
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Foreign",
log_days: 0,
pages: [
{
id: "Topic",
path: "Concepts/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "stable",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
if (schema !== null) manifest["schema"] = schema;
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
const index =
indexVersion === null
? "# Foreign\n"
: `---\nokf_version: "${indexVersion}"\n---\n# Foreign\n`;
writeFileSync(join(dir, "index.md"), index, "utf8");
writeFileSync(join(dir, "concepts/Topic.md"), "---\ntitle: Topic\n---\nBody.\n", "utf8");
}
test("a schema-less bundle whose index declares okf_version 0.2 is accepted at the gate", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-v02-"));
try {
bundleWithMarkers(dir, null, "0.2");
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(true);
expect(parsed.pages.length).toBe(1);
// The parsed manifest reports the ON-DISK declaration, not a
// hardcoded constant: no schema was declared, so the reader shows "".
expect(parsed.manifest.schema).toBe("");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a present non-dialect schema is refused even beside a v0.2 index", () => {
// The index always declares okf_version on this export's own bundles,
// so an OR that treats the declaration as sufficient would accept a
// future dialect schema "2" under v1 assumptions.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-v02-refuse-"));
try {
bundleWithMarkers(dir, "2", "0.2");
expect(() => readOkfBundle(dir)).toThrow("unsupported OKF schema: expected 1, got 2");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a schema-less bundle whose index declares no version is refused by name", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-v02-none-"));
try {
bundleWithMarkers(dir, null, null);
expect(() => readOkfBundle(dir)).toThrow("unsupported OKF schema");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a bundle with neither marker is refused by name", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-v02-refuse-"));
try {
bundleWithMarkers(dir, "999", "9.9");
expect(() => readOkfBundle(dir)).toThrow("unsupported OKF schema: expected 1, got 999");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
/**
* Rewrite the bundle's manifest so `schema` is an EXPLICIT JSON null -
* a writer that nulls the field declares no schema just as surely as
* one that omits it, and the gate must not read null as a PRESENT
* wrong schema.
*/
function withExplicitNullSchema(dir: string): void {
const manifestPath = join(dir, "okf.json");
const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
manifest["schema"] = null;
writeFileSync(manifestPath, JSON.stringify(manifest), "utf8");
}
test("a null manifest schema beside a v0.2 index is treated as absent", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-nullschema-"));
try {
bundleWithMarkers(dir, null, "0.2");
withExplicitNullSchema(dir);
const parsed = readOkfBundle(dir);
expect(parsed.pages.length).toBe(1);
// The on-disk declaration is still what the parsed manifest shows:
// null is no string schema, so the reader reports "".
expect(parsed.manifest.schema).toBe("");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a null schema with no index declaration is refused naming the expectation", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-nullschema-none-"));
try {
bundleWithMarkers(dir, null, null);
withExplicitNullSchema(dir);
expect(() => readOkfBundle(dir)).toThrow(
"unsupported OKF schema: no schema 1 in okf.json and no okf_version 0.2 declaration in index.md",
);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a trusted own-producer round-trip restores native frontmatter, not the derived block", () => {
// The v0.2 derived keys are recomputed on every export, and the
// closed status enum cannot name this system's own statuses. The
// export therefore carries the native values under the producer
// namespace (okf_status_raw / okf_sources_raw / okf_generated_raw)
// beside the derived block, and a trusted own-producer import
// restores them and drops the derived block: a page quarantined
// before export is quarantined again instead of being silently
// promoted to the enum's `stable` by its own round-trip.
note("Notes/Q.md", "---\ntitle: Q\nstatus: quarantine\n---\nbody.\n");
note("Notes/Done.md", "---\ntitle: Done\nstatus: done\n---\nbody.\n");
note("Notes/G.md", "---\ntitle: G\ngenerated: hand-written\n---\nbody.\n");
note("Notes/Plain.md", "---\ntitle: Plain\n---\nsee [[Q]].\n");
note("Notes/S.md", "---\ntitle: S\nsources: [https://example.com/orig]\n---\nsee [[Q]].\n");
const bundle = buildOkfBundle(vault);
// The export carries the raw values beside the derived block.
const qPage = fileOf(bundle.files, "concepts/Q.md");
expect(qPage).toContain("status: stable");
expect(qPage).toContain("okf_status_raw: quarantine");
// Every page of a fresh export declares raw-carrying, raw keys or
// not, and names the natives the exporter manages.
expect(qPage).toContain("okf_raw: [status, sources, generated, type]");
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-rt-bundle-"));
const dest = legacyVaultDir("o2b-okf-rt-dest-");
try {
writeOkfBundle(dir, bundle);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
expect(result.written).toContain("Notes/Q.md");
// Quarantine survives: the derived `stable` is dropped, the raw
// status is restored, and no namespaced key is left behind.
const landedQ = readFileSync(join(dest, "Notes/Q.md"), "utf8");
expect(landedQ).toContain("status: quarantine");
expect(landedQ).not.toContain("status: stable");
expect(landedQ).not.toContain("okf_status_raw");
expect(landedQ).not.toContain("generated:");
expect(landedQ).toContain("body.");
// Completion states come back too: `done` is `done`, not `stable`.
const landedDone = readFileSync(join(dest, "Notes/Done.md"), "utf8");
expect(landedDone).toContain("status: done");
expect(landedDone).not.toContain("status: stable");
// A native generated value is restored, not the derived block.
const landedG = readFileSync(join(dest, "Notes/G.md"), "utf8");
expect(landedG).toContain("generated: hand-written");
expect(landedG).not.toContain("open-second-brain/");
// A page whose source carried none of the three fields exports no
// raw keys - but its bundle file carries the okf_raw marker, so
// the import reads the absent raw keys as "the field never had a
// value" and strips the derived block: the plain page comes back
// plain, with no `status: stable` materialized out of nothing
// that the next export would carry as a raw native.
const landedPlain = readFileSync(join(dest, "Notes/Plain.md"), "utf8");
expect(landedPlain).not.toContain("status:");
expect(landedPlain).not.toContain("sources:");
expect(landedPlain).not.toContain("generated:");
expect(landedPlain).not.toContain("okf_raw");
expect(landedPlain).toContain("see [[Q]].");
// User-written sources come back; the derived flow map does not.
// The writer quotes array items on re-render - the DATA is what is
// pinned, in its deterministic written form.
const landedS = readFileSync(join(dest, "Notes/S.md"), "utf8");
expect(landedS).toContain('sources: ["https://example.com/orig"]');
expect(landedS).not.toContain("{resource:");
// Re-export is deterministic: the restored state re-exports as the
// same raw + derived shape, byte-identical modulo the shared
// generated instant. The marker declared the type pair, so the
// first import stripped the derived type along with the rest of
// the block - nothing materialized, nothing to carry raw, and the
// round-trip converges from the first export instead of drifting
// one step into a native type.
const re = buildOkfBundle(dest);
const reQ = fileOf(re.files, "concepts/Q.md");
expect(reQ.split(re.manifest.generated_at).join(bundle.manifest.generated_at)).toBe(qPage);
// From there the shape is stable: importing the re-export strips
// the derived block again, and a third export is byte-identical to
// the second.
const dir2 = mkdtempSync(join(tmpdir(), "o2b-okf-rt-bundle2-"));
const dest2 = mkdtempSync(join(tmpdir(), "o2b-okf-rt-dest2-"));
try {
writeOkfBundle(dir2, re);
const result2 = importOkfBundle(dest2, readOkfBundle(dir2), { trusted: true });
expect(result2.errors).toEqual([]);
const landedQ2 = readFileSync(join(dest2, "Notes/Q.md"), "utf8");
expect(landedQ2).toContain("status: quarantine");
expect(landedQ2).not.toContain("type:");
const re2 = buildOkfBundle(dest2);
expect(
fileOf(re2.files, "concepts/Q.md")
.split(re2.manifest.generated_at)
.join(re.manifest.generated_at),
).toBe(reQ);
} finally {
rmSync(dir2, { recursive: true, force: true });
rmSync(dest2, { recursive: true, force: true });
}
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a legacy own-producer page (no raw-carry marker) keeps its natives on a trusted import", () => {
// Bundles exported before the raw-carrying declaration existed
// carried the page's native status / sources / generated in place,
// with no okf_raw marker to say otherwise. The restore branch runs
// only on a marked page, so a marker-less page imports untouched:
// its frontmatter already IS the native state, and reading absent
// raw keys as "the field never had a value" would delete exactly
// those natives - a legacy bundle's trusted round-trip once lost
// every page's status, quarantine included.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-legacy-"));
const dest = legacyVaultDir("o2b-okf-legacy-dest-");
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Legacy",
log_days: 0,
pages: [
{
id: "Topic",
path: "Notes/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "deprecated",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(
join(dir, "concepts/Topic.md"),
"---\ntitle: Topic\nstatus: quarantine\nsources: [https://example.com/orig]\ngenerated: by-hand\n---\nBody.\n",
"utf8",
);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Topic.md"), "utf8");
expect(landed).toContain("status: quarantine");
expect(landed).toContain('sources: ["https://example.com/orig"]');
expect(landed).toContain("generated: by-hand");
expect(landed).not.toContain("okf_status_raw");
expect(landed).toContain("Body.");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a marker-less page carrying raw keys still restores its natives", () => {
// The raw keys and the okf_raw marker ship together, so no released
// bundle can carry one without the other - but a page that keeps the
// keys and loses the marker must not fall back to the legacy path:
// the raw keys are themselves the declaration that this page's
// natives ride beside the derived block. The legacy early-return
// stranded them - the derived `stable` landed, the carrier rode
// along beside it, and the next export carried the materialized
// status as a raw native, permanent.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-rawnomark-"));
const dest = legacyVaultDir("o2b-okf-rawnomark-dest-");
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Markerless",
log_days: 0,
pages: [
{
id: "Topic",
path: "Notes/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "stable",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(
join(dir, "concepts/Topic.md"),
"---\ntitle: Topic\nokf_status_raw: quarantine\nstatus: stable\n---\nBody.\n",
"utf8",
);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Topic.md"), "utf8");
// The raw status is restored and the derived block shed, exactly
// as if the marker had been present beside the keys.
expect(landed).toContain("status: quarantine");
expect(landed).not.toContain("status: stable");
expect(landed).not.toContain("okf_status_raw");
expect(landed).not.toContain("sources:");
expect(landed).not.toContain("generated:");
expect(landed).toContain("Body.");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a fresh-export plain page round-trips without gaining the derived block", () => {
// A page whose source carried no status / sources / generated exports
// no raw keys - but it is still a raw-carrying exporter's page, and
// its bundle file says so with the okf_raw marker beside the derived
// block. The import must read the absent raw keys as "the field
// never had a value" and strip the derived block, so the plain page
// comes back plain. Reading the zero-raw-key shape as a legacy page
// instead materialized `status: stable` where none existed - and the
// next export then carried the materialized status as a raw native,
// permanent.
note("Notes/Plain.md", "---\ntitle: Plain\n---\nsee [[Q]].\n");
const bundle = buildOkfBundle(vault);
// The marker declares raw-carrying on every page of a fresh export,
// raw keys or not, naming the full coverage the exporter manages.
const plainPage = fileOf(bundle.files, "concepts/Plain.md");
expect(plainPage).toContain("okf_raw: [status, sources, generated, type]");
expect(plainPage).toContain("status: stable");
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-plain-rt-"));
const dest = legacyVaultDir("o2b-okf-plain-rt-dest-");
try {
writeOkfBundle(dir, bundle);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Notes/Plain.md"), "utf8");
// The derived block is stripped, not landed: no status the closed
// enum materialized out of nothing, no generated stamp - and no
// marker machinery left behind either.
expect(landed).not.toContain("status:");
expect(landed).not.toContain("generated:");
expect(landed).not.toContain("okf_raw");
expect(landed).toContain("title: Plain");
expect(landed).toContain("see [[Q]].");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a non-string native status round-trips through the raw key", () => {
// The raw status was carried through the string-only field reader: a
// numeric or whitespace-only status was exported with no raw key at
// all, and the trusted restore then deleted the field wholesale. The
// raw key now carries whatever the frontmatter holds, and the
// restore keys on presence, not shape - the same rule sources and
// generated already follow. (A frontmatter map built in memory, as
// the knowledge-pack subset path does, can hold non-string scalars
// the file scanner would parse into strings.)
const page = (id: string, status: FrontmatterValue): OkfPage => ({
id,
path: `Notes/${id}.md`,
cls: "concept",
bundle_path: `concepts/${id}.md`,
kind: "note",
citations: [],
status: "stable",
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
frontmatter: { title: id, status },
body: "body.",
});
const bundle = buildOkfSubsetBundle(vault, [page("Num", 42), page("Ws", " ")]);
// The export carries both under the raw key, beside the derived block.
expect(fileOf(bundle.files, "concepts/Num.md")).toContain("okf_status_raw: 42");
expect(fileOf(bundle.files, "concepts/Ws.md")).toContain('okf_status_raw: " "');
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-rawshape-"));
const dest = legacyVaultDir("o2b-okf-rawshape-dest-");
try {
writeOkfBundle(dir, bundle);
const result = importOkfBundle(dest, readOkfBundle(dir), { trusted: true });
expect(result.errors).toEqual([]);
const landedNum = readFileSync(join(dest, "Notes/Num.md"), "utf8");
expect(landedNum).toContain("status: 42");
expect(landedNum).not.toContain("status: stable");
expect(landedNum).not.toContain("okf_status_raw");
const [landedWsMeta] = parseFrontmatter(join(dest, "Notes/Ws.md"));
expect(landedWsMeta["status"]).toBe(" ");
expect(landedWsMeta["okf_status_raw"]).toBeUndefined();
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a foreign bundle's derived keys ride a trusted import verbatim", () => {
// Foreign bundles import as-is: the derived block is the bundle's
// own data, never restored away and never re-stamped, and no raw
// keys are read on a foreign producer's word.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-foreign-v02-"));
const dest = legacyVaultDir("o2b-okf-foreign-v02-dest-");
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: "some-other-wiki",
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Foreign",
log_days: 0,
pages: [
{
id: "Topic",
path: "Concepts/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "stable",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(
join(dir, "concepts/Topic.md"),
'---\ntitle: Topic\nstatus: stable\nsources:\n - {resource: "concepts/Other.md", id: "Other"}\ngenerated: {by: "some-other-wiki/9", at: "2026-06-01T00:00:00Z"}\n---\nBody.\n',
"utf8",
);
const result = importOkfBundle(dest, readOkfBundle(dir), {
trusted: true,
now: new Date(0),
});
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Concepts/Topic.md"), "utf8");
expect(landed).toContain("status: stable");
expect(landed).toContain("concepts/Other.md");
expect(landed).toContain("some-other-wiki/9");
expect(landed).not.toContain("okf_status_raw");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("an own-producer bundle staged untrusted keeps its real status and sheds the raw keys", () => {
// The restore keys on the PRODUCER, not on the operator's vouch: a
// staged page is already marked okf_review: pending, so restoring the
// native status there cannot promote anything into the live vault -
// while skipping the restore is the exact regression the raw keys
// exist to fix (a quarantined page lands `stable` on review).
note("Notes/Q.md", "---\ntitle: Q\nstatus: quarantine\n---\nbody.\n");
const bundle = buildOkfBundle(vault);
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-review-rt-"));
const dest = legacyVaultDir("o2b-okf-review-rt-dest-");
try {
writeOkfBundle(dir, bundle);
const result = importOkfBundle(dest, readOkfBundle(dir));
expect(result.mode).toBe("review");
expect(result.errors).toEqual([]);
const staged = readFileSync(join(dest, OKF_REVIEW_REL, "Notes/Q.md"), "utf8");
expect(staged).toContain("status: quarantine");
expect(staged).not.toContain("status: stable");
expect(staged).toContain("okf_review: pending");
expect(staged).not.toContain("okf_status_raw");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a foreign bundle cannot plant the raw machinery keys", () => {
// okf_status_raw / okf_sources_raw / okf_generated_raw are this
// system's restore machinery: a foreign producer's word neither
// triggers the restore nor leaves the keys behind as stray machinery
// in the vault - the page imports verbatim minus the namespace.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-foreign-raw-"));
const dest = legacyVaultDir("o2b-okf-foreign-raw-dest-");
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: "some-other-wiki",
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Foreign",
log_days: 0,
pages: [
{
id: "Topic",
path: "Concepts/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
status: "stable",
sources: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(
join(dir, "concepts/Topic.md"),
"---\ntitle: Topic\nstatus: stable\nokf_status_raw: quarantine\nokf_sources_raw: [planted]\nokf_generated_raw: forged\n---\nBody.\n",
"utf8",
);
const result = importOkfBundle(dest, readOkfBundle(dir), {
trusted: true,
now: new Date(0),
});
expect(result.errors).toEqual([]);
const landed = readFileSync(join(dest, "Concepts/Topic.md"), "utf8");
expect(landed).toContain("status: stable");
expect(landed).not.toContain("okf_status_raw");
expect(landed).not.toContain("okf_sources_raw");
expect(landed).not.toContain("okf_generated_raw");
expect(landed).not.toContain("planted");
expect(landed).not.toContain("forged");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("a sealed knowledge-pack half carrying a v0.2 okf.json installs", () => {
const packDir = mkdtempSync(join(tmpdir(), "o2b-okf-pack-"));
const dest = legacyVaultDir("o2b-okf-pack-dest-");
try {
const okfManifest = {
schema: "",
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Packed",
log_days: 0,
log_private_omitted: 0,
pages: [
{
id: "runbook",
path: "Notes/runbook.md",
class: "concept" as const,
bundle_path: "concepts/runbook.md",
kind: "note",
citations: [],
status: "stable" as const,
sources: [],
aliases: [] as string[],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
const sealed = sealKnowledgePack({
name: "v02-pack",
version: "1.0.0",
selection: ["tag:ops"],
okfManifest,
// The index carries the v0.2 declaration the manifest schema
// does not; the seal hashes exactly these bytes.
pageFiles: [
{ path: "index.md", contents: '---\nokf_version: "0.2"\n---\n# Packed\n' },
{ path: "concepts/runbook.md", contents: "---\ntitle: Runbook\n---\nRestart.\n" },
],
preferences: [],
});
writeOkfBundle(packDir, { manifest: okfManifest, files: sealed.files });
const pack = readKnowledgePack(packDir);
expect(pack.integrity.verified).toBe(true);
const result = installKnowledgePack(dest, pack);
expect(result.pages.written).toEqual([`${OKF_REVIEW_REL}/Notes/runbook.md`]);
expect(existsSync(join(dest, OKF_REVIEW_REL, "Notes", "runbook.md"))).toBe(true);
} finally {
rmSync(packDir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
});
describe("collectOkfPages", () => {
test("surfaces a preserved foreign type from okf_type frontmatter", () => {
note(
"Imported/Foo.md",
"---\ntitle: Foo\nkind: note\nokf_type: encyclopedia-entry\nx-source-db: wikidata\n---\nbody\n",
);
const pages = collectOkfPages(vault);
const foo = pages.find((p) => p.path === "Imported/Foo.md");
expect(foo?.foreign_type).toBe("encyclopedia-entry");
expect(foo?.producer_meta).toEqual({ "x-source-db": "wikidata" });
});
});
describe("round-trip", () => {
test("trusted import restores pages at their recorded paths", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nlinks [[Beta]].\n");
note("Brain/sources/src-paper.md", "---\ntitle: Paper\nkind: brain-source\n---\ncited.\n");
const bundle = buildOkfBundle(vault);
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-bundle-"));
const dest = legacyVaultDir("o2b-okf-dest-");
try {
writeOkfBundle(dir, bundle);
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(false);
const result = importOkfBundle(dest, parsed, { trusted: true });
expect(result.mode).toBe("trusted");
expect(result.written).toContain("Notes/Alpha.md");
expect(result.written).toContain("Brain/sources/src-paper.md");
expect(existsSync(join(dest, "Notes/Alpha.md"))).toBe(true);
expect(readFileSync(join(dest, "Notes/Alpha.md"), "utf8")).toContain("links [[Beta]].");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("default import stages pages under OKF Review/ as candidates", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nx\n");
const bundle = buildOkfBundle(vault);
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-bundle-"));
const dest = legacyVaultDir("o2b-okf-dest-");
try {
writeOkfBundle(dir, bundle);
const result = importOkfBundle(dest, readOkfBundle(dir));
expect(result.mode).toBe("review");
const staged = join(dest, OKF_REVIEW_REL, "Notes/Alpha.md");
expect(existsSync(staged)).toBe(true);
expect(readFileSync(staged, "utf8")).toContain("okf_review: pending");
// The live target was never created.
expect(existsSync(join(dest, "Notes/Alpha.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
test("review mode skips an existing staged target rather than clobbering", () => {
note("Notes/Alpha.md", "---\ntitle: Alpha\n---\nx\n");
const bundle = buildOkfBundle(vault);
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-bundle-"));
const dest = legacyVaultDir("o2b-okf-dest-");
try {
writeOkfBundle(dir, bundle);
const staged = join(dest, OKF_REVIEW_REL, "Notes/Alpha.md");
mkdirSync(join(staged, ".."), { recursive: true });
writeFileSync(staged, "PREEXISTING\n", "utf8");
const result = importOkfBundle(dest, readOkfBundle(dir));
expect(result.skipped).toContain(`${OKF_REVIEW_REL}/Notes/Alpha.md`);
expect(readFileSync(staged, "utf8")).toBe("PREEXISTING\n");
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(dest, { recursive: true, force: true });
}
});
});
describe("foreign provenance", () => {
function foreignBundleDir(): string {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-foreign-"));
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: "some-other-wiki",
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Foreign",
log_days: 0,
pages: [
{
id: "Topic",
path: "Concepts/Topic.md",
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
aliases: [],
freshness: null,
foreign_type: "wiki-article",
producer_meta: { "x-wiki-id": "42" },
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(
join(dir, "concepts/Topic.md"),
"---\ntitle: Topic\nkind: note\nokf_type: wiki-article\nx-wiki-id: 42\n---\nForeign body.\n",
"utf8",
);
return dir;
}
test("import stamps producer + raw foreign type, preserves x-* keys", () => {
const dir = foreignBundleDir();
try {
const parsed = readOkfBundle(dir);
expect(parsed.foreign).toBe(true);
const result = importOkfBundle(vault, parsed, { trusted: true, now: new Date(0) });
expect(result.foreign).toBe(true);
const written = readFileSync(join(vault, "Concepts/Topic.md"), "utf8");
expect(written).toContain("okf_producer: some-other-wiki");
expect(written).toContain("okf_type: wiki-article");
expect(written).toContain("x-wiki-id: 42");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("re-export preserves raw foreign type while deriving standard fields", () => {
const dir = foreignBundleDir();
try {
importOkfBundle(vault, readOkfBundle(dir), { trusted: true, now: new Date(0) });
// The page now lives in OUR vault; re-export must keep foreign type
// but derive standard kind from current state.
const re = buildOkfBundle(vault);
const page = re.manifest.pages.find((p) => p.path === "Concepts/Topic.md");
expect(page?.foreign_type).toBe("wiki-article");
expect(page?.producer_meta).toEqual({ "x-wiki-id": "42" });
expect(page?.kind).toBe("note"); // standard field derived from current frontmatter
// The re-exported page file still carries the foreign frontmatter.
const body = fileOf(re.files, page!.bundle_path);
expect(body).toContain("okf_type: wiki-article");
expect(body).toContain("x-wiki-id: 42");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
/**
* Hand-built single-page bundles for the recorded-path trust walls
* (t_sec_okf_lane): `..` can never escape the review lane, Brain
* machinery is writable only by this producer's own trusted round-trip,
* and foreign pages do not arrive speaking in this system's voice.
*/
describe("import path lanes (t_sec_okf_lane)", () => {
function singlePageBundle(
dir: string,
producer: string,
pagePath: string,
pageFrontmatter: string,
): void {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Lane",
log_days: 0,
pages: [
{
id: "Topic",
path: pagePath,
class: "concept",
bundle_path: "concepts/Topic.md",
kind: "note",
citations: [],
aliases: [],
freshness: null,
foreign_type: null,
producer_meta: {},
},
],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
writeFileSync(join(dir, "concepts/Topic.md"), `---\n${pageFrontmatter}---\nBody.\n`, "utf8");
}
test("review mode refuses a '..' recorded path instead of staging into Brain", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(dir, OKF_PRODUCER, "../Brain/standing-rules.md", "title: S\n");
const result = importOkfBundle(vault, readOkfBundle(dir));
expect(result.written).toEqual([]);
expect(result.errors).toHaveLength(1);
expect(result.errors[0]?.message).toContain("'..'");
// Neither the live machinery file nor a staging-prefixed copy exists.
expect(existsSync(join(vault, "Brain/standing-rules.md"))).toBe(false);
expect(existsSync(join(vault, OKF_REVIEW_REL, "Brain/standing-rules.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("trusted import of a foreign bundle refuses Brain machinery paths", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(dir, "some-other-wiki", "Brain/standing-rules.md", "title: S\n");
const result = importOkfBundle(vault, readOkfBundle(dir), { trusted: true });
expect(result.written).toEqual([]);
expect(result.errors[0]?.message).toContain("Brain machinery");
expect(existsSync(join(vault, "Brain/standing-rules.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("trusted own-producer round-trip still writes the Brain sources lane", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(dir, OKF_PRODUCER, "Brain/sources/src-paper.md", "title: Paper\n");
const result = importOkfBundle(vault, readOkfBundle(dir), { trusted: true });
expect(result.errors).toEqual([]);
expect(result.written).toEqual(["Brain/sources/src-paper.md"]);
expect(existsSync(join(vault, "Brain/sources/src-paper.md"))).toBe(true);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("trusted own-producer round-trip refuses Brain machinery outside the page lanes", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(dir, OKF_PRODUCER, "Brain/standing-rules.md", "title: S\n");
const result = importOkfBundle(vault, readOkfBundle(dir), { trusted: true });
expect(result.written).toEqual([]);
expect(result.errors[0]?.message).toContain("Brain machinery");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a foreign staged page arrives without machinery frontmatter keys", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(
dir,
"some-other-wiki",
"Concepts/Topic.md",
"title: Topic\n_status: confirmed\n_confidence: high\nowner: someone\norigin_channel: cli\n_revision: 99\n",
);
const result = importOkfBundle(vault, readOkfBundle(dir), {
trusted: true,
now: new Date(0),
});
expect(result.errors).toEqual([]);
const written = readFileSync(join(vault, "Concepts/Topic.md"), "utf8");
expect(written).not.toContain("_status:");
expect(written).not.toContain("_confidence:");
expect(written).not.toContain("owner:");
expect(written).not.toContain("origin_channel:");
expect(written).not.toContain("_revision:");
expect(written).toContain("okf_producer: some-other-wiki");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("this producer's own round-trip stays lossless (machinery keys survive)", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(
dir,
OKF_PRODUCER,
"Notes/Topic.md",
"title: Topic\n_status: confirmed\nowner: someone\n",
);
const result = importOkfBundle(vault, readOkfBundle(dir), { trusted: true });
expect(result.errors).toEqual([]);
const written = readFileSync(join(vault, "Notes/Topic.md"), "utf8");
expect(written).toContain("_status: confirmed");
expect(written).toContain("owner: someone");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a forged own-producer claim does not carry machinery keys into review", () => {
// `producer` is bundle-supplied: any bundle can claim to be this
// system. Without the operator's --trusted the claim buys nothing.
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(
dir,
OKF_PRODUCER,
"Notes/Topic.md",
"title: Topic\n_status: confirmed\n_force_confirmed_via: cli\nowner: someone\norigin_channel: cli\n",
);
const result = importOkfBundle(vault, readOkfBundle(dir));
expect(result.errors).toEqual([]);
const written = readFileSync(join(vault, OKF_REVIEW_REL, "Notes/Topic.md"), "utf8");
expect(written).not.toContain("_status:");
expect(written).not.toContain("_force_confirmed_via:");
expect(written).not.toContain("owner:");
expect(written).not.toContain("origin_channel:");
expect(written).toContain("okf_review: pending");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a staged page keeps its visibility: stripping it could only widen reach", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(
dir,
OKF_PRODUCER,
"Notes/Secret.md",
"title: Secret\nvisibility: private\n",
);
importOkfBundle(vault, readOkfBundle(dir));
const written = readFileSync(join(vault, OKF_REVIEW_REL, "Notes/Secret.md"), "utf8");
expect(written).toContain("visibility: private");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("trusted import compares the Brain segment case-insensitively", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
singlePageBundle(dir, OKF_PRODUCER, "brain/_brain.yaml", "title: S\n");
const result = importOkfBundle(vault, readOkfBundle(dir), { trusted: true });
expect(result.written).toEqual([]);
expect(result.errors[0]?.message).toContain("Brain machinery");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("the Brain page lanes open on the operator's --trusted, not on the producer claim", () => {
const own = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
const other = mkdtempSync(join(tmpdir(), "o2b-okf-lane-"));
try {
// Claiming this producer without --trusted: staged, lane untouched.
singlePageBundle(own, OKF_PRODUCER, "Brain/sources/src-paper.md", "title: Paper\n");
const review = importOkfBundle(vault, readOkfBundle(own));
expect(review.written).toEqual([`${OKF_REVIEW_REL}/Brain/sources/src-paper.md`]);
expect(existsSync(join(vault, "Brain/sources/src-paper.md"))).toBe(false);
// Declaring a foreign producer with --trusted: the operator vouched,
// so the lane opens - with machinery keys still stripped.
singlePageBundle(
other,
"some-other-wiki",
"Brain/reports/2026-06-01-r.md",
"title: R\n_status: confirmed\n",
);
const trusted = importOkfBundle(vault, readOkfBundle(other), { trusted: true });
expect(trusted.written).toEqual(["Brain/reports/2026-06-01-r.md"]);
const written = readFileSync(join(vault, "Brain/reports/2026-06-01-r.md"), "utf8");
expect(written).not.toContain("_status:");
} finally {
rmSync(own, { recursive: true, force: true });
rmSync(other, { recursive: true, force: true });
}
});
});
describe("readOkfBundle validation", () => {
test("rejects a missing manifest", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-empty-"));
try {
expect(() => readOkfBundle(dir)).toThrow(OkfError);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("rejects an unsupported schema loudly", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-badschema-"));
try {
writeFileSync(join(dir, "okf.json"), JSON.stringify({ schema: "999", pages: [] }), "utf8");
expect(() => readOkfBundle(dir)).toThrow(OkfError);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("a page whose recorded bundle_path escapes the bundle is dropped", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-escape-"));
try {
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: "x",
pages: [{ id: "evil", path: "a.md", class: "concept", bundle_path: "../../etc/passwd" }],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
const parsed = readOkfBundle(dir);
expect(parsed.pages.length).toBe(0);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe("writeOkfBundle", () => {
test("refuses a non-empty directory without force", () => {
note("Notes/A.md", "---\ntitle: A\n---\nx\n");
const bundle = buildOkfBundle(vault);
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-nonempty-"));
try {
writeFileSync(join(dir, "stuff.txt"), "x", "utf8");
expect(() => writeOkfBundle(dir, bundle)).toThrow(OkfError);
// force overwrites.
writeOkfBundle(dir, bundle, { force: true });
expect(existsSync(join(dir, "okf.json"))).toBe(true);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test("rejects bundle file paths that escape the output directory", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-escape-write-"));
const outside = mkdtempSync(join(tmpdir(), "o2b-okf-outside-"));
try {
const outsideName = outside.split("/").pop()!;
const bundle = {
manifest: {
schema: OKF_SCHEMA_VERSION,
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Vault",
pages: [],
log_days: 0,
log_private_omitted: 0,
},
files: [{ path: `../${outsideName}/pwned.md`, contents: "nope\n" }],
};
expect(() => writeOkfBundle(dir, bundle)).toThrow(/path escapes vault/);
expect(existsSync(join(outside, "pwned.md"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
rmSync(outside, { recursive: true, force: true });
}
});
});
describe("log_private_omitted on the legacy layout", () => {
test("an unswitched vault with log day files counts zero", () => {
note("Brain/log/2026-06-01.md", "- a plain day entry\n");
const bundle = buildOkfBundle(vault);
const log = fileOf(bundle.files, "log.md");
expect(log).toContain("a plain day entry");
expect(bundle.manifest.log_private_omitted).toBe(0);
});
test("a manifest without log_private_omitted parses with zero", () => {
const dir = mkdtempSync(join(tmpdir(), "o2b-okf-omit-"));
try {
mkdirSync(join(dir, "concepts"), { recursive: true });
const manifest = {
schema: OKF_SCHEMA_VERSION,
producer: OKF_PRODUCER,
generated_at: "2026-06-01T00:00:00Z",
vault_basename: "Parse",
log_days: 2,
pages: [],
};
writeFileSync(join(dir, "okf.json"), JSON.stringify(manifest), "utf8");
const parsed = readOkfBundle(dir);
expect(parsed.manifest.log_days).toBe(2);
expect(parsed.manifest.log_private_omitted).toBe(0);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});