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
/**
* Knowledge packs (Brain Portability & Interop suite; upstream task
* t_d037251c): a SELECTED subset of Brain knowledge - rules, and the
* pages that hold runbooks and conventions - exported as a portable,
* privacy-scanned, integrity-sealed bundle; previewed before install;
* installed as untrusted candidates stamped with their pack; removed as a
* unit.
*
* ## Not a third import path
*
* A pack is an OKF bundle directory plus two files, and each half of its
* content travels the path that already owns it:
*
* - PAGES are an OKF subset ({@link buildOkfSubsetBundle}) and install
* through {@link importOkfBundle} in its untrusted review mode: staged
* under `OKF Review/` with `okf_review: pending`, machinery stripped,
* recorded paths walled. OKF is the carrier because it is the format
* that holds page bodies verbatim; the bank bundle carries only a page
* graph and contracts.
* - PREFERENCES are bank-bundle rows (`preferences.json`, the
* `collectExportRows` projection) and install through
* {@link restorePreferences} and so through the audited preference
* transaction. OKF deliberately excludes `Brain/preferences/`, and the
* bank rows are the one projection the restore already validates row
* by row. The restore's `knowledgePack` mode lands every row
* `unconfirmed` on a fresh trial window - never confirmed - with the
* source vault's evidence, counters, revision, pin and aliases cleared.
*
* `knowledge-pack.json` is the pack's own manifest: name, version,
* selection, and a sha256 per file plus a digest over all of them. The
* digest is what the provenance stamp (`knowledge_pack: <name>@<digest12>`,
* see `pack-stamp.ts`) names, and what install refuses to proceed without.
*
* ## Not a schema pack
*
* `_brain.yaml`'s `schema:` block (and `schema_inspect view=packs`) is a
* vocabulary pack - token definitions, not knowledge. Nothing here reads or
* writes it; the CLI verb is `knowledge-pack` so the two never share a name.
*/
import { createHash } from "node:crypto";
import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, type Dirent } from "node:fs";
import { join, posix, relative } from "node:path";
import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { EXCLUDED_DIRS, parseFrontmatterText } from "../../vault.ts";
import type { FrontmatterMap } from "../../types.ts";
import { pageVisibility } from "../../graph/visibility.ts";
import { hasPrivacyDenyMarker } from "../../graph/privacy-markers.ts";
import { omittedPageReferenceMatcher, readContentClass } from "../provenance/content-class.ts";
import {
PRIVATE_REGION_PLACEHOLDER,
REDACTION_PLACEHOLDER,
scanRawOutput,
stripPrivateRegions,
} from "../../redactor.ts";
import { appendContinuitySourceInvalidation } from "../continuity/store.ts";
import { topicKey } from "../dream-plan.ts";
import {
collectExportRowsWithDenials,
collectPreferenceRows,
PREFERENCE_DENY_REASON,
type ExportedPreferenceRow,
} from "../export.ts";
import type { RecoverabilityVerdict } from "../gates/recoverability.ts";
import { classifyRecoverability } from "../gates/recoverability.ts";
import {
BRAIN_PREFERENCES_REL,
BRAIN_ROOT_REL,
ensureInsideVault,
preferencePath,
retiredPath,
} from "../paths.ts";
import { guardBrainContextSnippet } from "../safety/context-guard.ts";
import { withDestructiveSnapshot } from "../snapshot-gate.ts";
import { isoSecond } from "../time.ts";
import { BRAIN_SNAPSHOT_REASON } from "../types.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";
import {
buildOkfSubsetBundle,
collectOkfPages,
importOkfBundle,
OKF_MANIFEST_FILENAME,
OKF_PRODUCER,
OKF_REVIEW_REL,
readOkfBundle,
renderOkfManifest,
stripOkfMachinery,
type OkfBundleFile,
type OkfImportResult,
type OkfManifest,
type OkfPage,
type ParsedOkfBundle,
} from "./okf.ts";
import {
formatKnowledgePackStamp,
isKnowledgePackName,
KNOWLEDGE_PACK_FIELD,
KNOWLEDGE_PACK_SHA_FIELD,
parseKnowledgePackStamp,
} from "./pack-stamp.ts";
import {
restorePreferences,
type PreferenceRestoreFailureRecord,
type RestoredTopicKeyCollision,
} from "./preference-restore.ts";
export const KNOWLEDGE_PACK_SCHEMA = "1";
export const KNOWLEDGE_PACK_KIND = "osb-knowledge-pack";
/** Bundle-relative filename of the pack manifest. Not itself hashed: it holds the hashes. */
export const KNOWLEDGE_PACK_MANIFEST_FILENAME = "knowledge-pack.json";
/** Bundle-relative filename of the carried preference rows. */
export const KNOWLEDGE_PACK_PREFERENCES_FILENAME = "preferences.json";
/** Agent recorded on the audit line when the caller supplies none. */
export const KNOWLEDGE_PACK_DEFAULT_AGENT = "knowledge-pack";
const VERSION_RE = /^[0-9A-Za-z][0-9A-Za-z._+-]{0,31}$/;
const HEX64_RE = /^[0-9a-f]{64}$/;
/** Characters of each entry's text shown in a preview sample. */
const SAMPLE_CHARS = 240;
/** Raised for an invalid request or a bundle that is not a readable pack. */
export class KnowledgePackError extends Error {
constructor(message: string) {
super(message);
this.name = "KnowledgePackError";
}
}
export type KnowledgePackEntryKind = "preference" | "page";
export interface KnowledgePackIntegrity {
readonly algorithm: "sha256";
/** sha256 of every bundle file except the pack manifest, by bundle path. */
readonly files: Readonly<Record<string, string>>;
/** sha256 over the name, the version and the sorted file table. */
readonly digest: string;
}
export interface KnowledgePackManifest {
readonly schema: string;
readonly kind: typeof KNOWLEDGE_PACK_KIND;
readonly name: string;
readonly version: string;
readonly producer: string;
readonly generated_at: string;
/** The selectors the pack was exported with, as the operator typed them. */
readonly selection: ReadonlyArray<string>;
readonly integrity: KnowledgePackIntegrity;
}
// ----- Selection ------------------------------------------------------------
type Selector =
| { readonly kind: "id"; readonly value: string; readonly raw: string }
| { readonly kind: "topic"; readonly value: string; readonly raw: string }
| { readonly kind: "tag"; readonly value: string; readonly raw: string };
/**
* Parse `--select` values. Each value may hold several comma-separated
* selectors: `topic:<topic>`, `tag:<tag>`, or a bare id / vault path
* (`pref-<slug>`, a page's basename stem, or its vault-relative path).
*/
export function parseKnowledgePackSelectors(values: ReadonlyArray<string>): ReadonlyArray<string> {
const out: string[] = [];
for (const value of values) {
for (const part of value.split(",")) {
const trimmed = part.trim();
if (trimmed !== "" && !out.includes(trimmed)) out.push(trimmed);
}
}
return out;
}
function toSelector(raw: string): Selector {
if (raw.startsWith("topic:")) return { kind: "topic", value: raw.slice(6).trim(), raw };
if (raw.startsWith("tag:")) {
return { kind: "tag", value: raw.slice(4).trim().replace(/^#/, ""), raw };
}
return { kind: "id", value: raw, raw };
}
function stringList(value: unknown): string[] {
if (Array.isArray(value)) return value.filter((v): v is string => typeof v === "string");
if (typeof value === "string" && value.trim() !== "") return [value];
return [];
}
function tagSet(tags: ReadonlyArray<string>): Set<string> {
return new Set(tags.map((t) => t.trim().replace(/^#/, "")));
}
function prefMatches(sel: Selector, row: ExportedPreferenceRow): boolean {
if (sel.kind === "id") return row.id === sel.value;
if (sel.kind === "topic") return topicKey(row.topic) === topicKey(sel.value);
return tagSet(row.tags).has(sel.value);
}
function pageMatches(sel: Selector, page: OkfPage): boolean {
if (sel.kind === "id") {
return page.id === sel.value || page.path === sel.value || page.path === `${sel.value}.md`;
}
if (sel.kind === "topic") {
const topic = page.frontmatter["topic"];
return typeof topic === "string" && topicKey(topic) === topicKey(sel.value);
}
return tagSet(stringList(page.frontmatter["tags"])).has(sel.value);
}
/** Why a selected entry was left out of the pack. */
export type KnowledgePackBlockReason =
/** The page declares `visibility:` - it is scoped, and a pack is handed to others. */
| "visibility"
/** The entry carries an `owner:` claim - owner-private knowledge. */
| "owner"
/** The page is a staged import candidate nobody has reviewed. */
| "unreviewed"
/**
* The page carries the reserved `content_class: prompt-derived` stamp -
* material an agent produced from a prompt, which the shared exports
* leave out by default (the guard seam in `src/core/egress/guard.ts`).
* A pack is handed to someone else, so it joins the block list beside
* `visibility` and `owner` rather than composing the page and redacting
* it after the fact; each block names the reason, so the omission is
* never a silently smaller pack.
*/
| "prompt-derived";
export interface KnowledgePackBlocked {
readonly kind: KnowledgePackEntryKind;
readonly id: string;
readonly reason: KnowledgePackBlockReason;
}
/** One entry's privacy / injection findings, as closed codes. */
export interface KnowledgePackWarning {
readonly kind: KnowledgePackEntryKind;
readonly id: string;
readonly reasons: ReadonlyArray<string>;
}
/** A `<private>` region was present and is replaced by the redactor's placeholder. */
export const PRIVATE_REGION_WARNING = "privacy.private_region_stripped";
/** The text still carries a redaction placeholder. */
export const REDACTED_CONTENT_WARNING = "privacy.redacted_content";
/** The text carries secret-shaped content the export scan would redact. */
export const SECRET_SHAPED_WARNING = "privacy.secret_shaped_content";
/**
* The entry's structured citations named a blocked page and were dropped
* from the manifest metadata; the entry's own prose is untouched.
*/
export const BLOCKED_PAGE_CITATION_WARNING = "scope.blocked_page_citation_dropped";
export interface KnowledgePackSelection {
readonly selection: ReadonlyArray<string>;
/** The OKF manifest of the selected pages (no change log). */
readonly okfManifest: OkfManifest;
/** The selected page files, without `okf.json` (rendered at seal time). */
readonly pageFiles: ReadonlyArray<OkfBundleFile>;
readonly preferences: ReadonlyArray<ExportedPreferenceRow>;
/** Entries a selector matched but the privacy rules kept out. Never written. */
readonly blocked: ReadonlyArray<KnowledgePackBlocked>;
/**
* One carried entry's findings, as closed codes: the privacy scan's
* codes, and {@link BLOCKED_PAGE_CITATION_WARNING} once per entry whose
* manifest citations named a blocked page and were dropped.
*/
readonly warnings: ReadonlyArray<KnowledgePackWarning>;
}
function injectionCodes(text: string, id: string): string[] {
const guarded = guardBrainContextSnippet(text, { source: { id } });
return guarded.filtered ? guarded.reasons.map((reason) => reason.code) : [];
}
function exportWarnings(text: string, id: string): string[] {
const codes = injectionCodes(text, id);
if (stripPrivateRegions(text) !== text) codes.push(PRIVATE_REGION_WARNING);
return [...new Set(codes)].toSorted();
}
/**
* Resolve the selectors against the vault and gather what a pack would
* carry. Read-only. Throws {@link KnowledgePackError} for an empty
* selection or for any selector that matched nothing - a pack is a
* deliberate subset, and a selector that silently selects nothing is an
* operator error the export must not paper over.
*
* Private content is blocked, not redacted: a page with `visibility:`,
* an entry with `owner:`, and an unreviewed `OKF Review/` candidate are
* left out and named in `blocked`. `<private>` regions inside a carried
* entry are left for the egress scan (which replaces them) and named in
* `warnings`. Carried preference rows drop the source vault's evidence
* links and rendered body; carried pages drop this vault's machinery
* frontmatter.
*
* A carried page's structured citations are not prose: a citation naming
* a BLOCKED page is the blocked page's name leaving through the carried
* page's manifest metadata, so such citations are dropped - the same
* shared matcher the okf, graph and bank exports apply to their own
* structured references - and the drop is named per carried entry in
* `warnings`. The page body that carries the link stays exactly as
* written, and the manifest's `sources` need no second pass: they are
* re-translated from the citations here, so a dropped citation resolves
* to nothing there either.
*/
export interface SelectKnowledgePackOptions {
/**
* The pack's `--include-prompt-derived` override: a page the selection
* would block ONLY for the reserved `prompt-derived` class is carried.
* The operator-set scopes (`visibility`, `owner`) and the unreviewed
* lane are blocks in their own right, not class decisions, and stay
* blocks under the override - so a citation naming such a page is
* dropped under both paths.
*/
readonly includePromptDerived?: boolean;
}
export function selectKnowledgePack(
vault: string,
selectors: ReadonlyArray<string>,
opts: SelectKnowledgePackOptions = {},
): KnowledgePackSelection {
const selection = parseKnowledgePackSelectors(selectors);
if (selection.length === 0) {
throw new KnowledgePackError(
"a knowledge pack needs at least one selector (--select <id|topic:T|tag:T>)",
);
}
const parsed = selection.map(toSelector);
for (const sel of parsed) {
if (sel.value === "") throw new KnowledgePackError(`empty selector: ${sel.raw}`);
}
const matched = new Set<string>();
const blocked: KnowledgePackBlocked[] = [];
const warnings: KnowledgePackWarning[] = [];
// The complete rows, so a selector naming a reserved rule is MATCHED
// and reported as a named block - never "matched nothing".
const { rows: exportRows, denied } = collectExportRowsWithDenials(vault);
const deniedById = new Map(denied.map((d) => [d.id, d] as const));
const preferences: ExportedPreferenceRow[] = [];
for (const row of exportRows) {
const hits = parsed.filter((sel) => prefMatches(sel, row));
if (hits.length === 0) continue;
for (const sel of hits) matched.add(sel.raw);
// A reserved preference cannot ride redacted - the pack carries
// preference rows with the body dropped but the principle line
// verbatim - so this is drop-and-name, under the same reason
// `pageBlockReason` records for pages, and ahead of the owner check
// with the page reason precedence (visibility > owner).
if (deniedById.has(row.id)) {
blocked.push({ kind: "preference", id: row.id, reason: PREFERENCE_DENY_REASON });
continue;
}
if (preferenceOwner(vault, row.id) !== null) {
blocked.push({ kind: "preference", id: row.id, reason: "owner" });
continue;
}
const codes = exportWarnings(row.principle, row.id);
if (codes.length > 0) warnings.push({ kind: "preference", id: row.id, reasons: codes });
preferences.push({ ...row, evidenced_by: [], body: "" });
}
const pages: OkfPage[] = [];
for (const page of collectOkfPages(vault)) {
const hits = parsed.filter((sel) => pageMatches(sel, page));
if (hits.length === 0) continue;
for (const sel of hits) matched.add(sel.raw);
const reason = pageBlockReason(page);
// The override carries back ONLY the class block: the check itself
// stays in `pageBlockReason`, and the decision to keep a page the
// block scan marked `prompt-derived` is made here, the same way the
// guard's split turns into the identity when the policy includes.
if (reason !== null && !(reason === "prompt-derived" && opts.includePromptDerived === true)) {
blocked.push({ kind: "page", id: page.path, reason });
continue;
}
const codes = exportWarnings(page.body, page.path);
if (codes.length > 0) warnings.push({ kind: "page", id: page.path, reasons: codes });
pages.push({ ...page, frontmatter: stripOkfMachinery(page.frontmatter) });
}
const unmatched = selection.filter((raw) => !matched.has(raw));
if (unmatched.length > 0) {
throw new KnowledgePackError(`selector(s) matched nothing: ${unmatched.join(", ")}`);
}
if (preferences.length === 0 && pages.length === 0) {
throw new KnowledgePackError(
"every selected entry was blocked as private; nothing is left to pack",
);
}
// The block scan is complete, so the blocked page paths are the omitted
// list the shared matcher judges citation targets against. A target
// that names a blocked page leaves the carried page's citations - the
// manifest is where the pack names its references - and each carried
// page that lost one is named in `warnings`.
const namesBlocked = omittedPageReferenceMatcher(
blocked.filter((entry) => entry.kind === "page").map((entry) => entry.id),
);
const packed: OkfPage[] = [];
for (const page of pages) {
const citations = page.citations.filter((target) => !namesBlocked(target));
if (citations.length !== page.citations.length) {
warnings.push({
kind: "page",
id: page.path,
reasons: [BLOCKED_PAGE_CITATION_WARNING],
});
}
packed.push({ ...page, citations });
}
const okf = buildOkfSubsetBundle(vault, packed);
return {
selection,
okfManifest: okf.manifest,
pageFiles: okf.files.filter((file) => file.path !== OKF_MANIFEST_FILENAME),
preferences,
blocked,
warnings,
};
}
function preferenceOwner(vault: string, id: string): string | null {
let text: string;
try {
text = readFileSync(join(vault, BRAIN_PREFERENCES_REL, `${id}.md`), "utf8");
} catch {
return null;
}
const owner = parseFrontmatterText(text)[0]["owner"];
return typeof owner === "string" && owner.trim() !== "" ? owner : null;
}
function pageBlockReason(page: OkfPage): KnowledgePackBlockReason | null {
if (pageVisibility(page.frontmatter).length > 0) return "visibility";
// An informal privacy marker (`access: private` and its siblings) denies
// a remote read just as the reserved token does
// (graph/privacy-markers.ts), so a marker-only page - which declares no
// `visibility:` at all - is blocked under the same reason rather than
// shipped with its body.
if (hasPrivacyDenyMarker(page.frontmatter)) return "visibility";
const owner = page.frontmatter["owner"];
if (typeof owner === "string" && owner.trim() !== "") return "owner";
// The reserved class joins the operator-set scopes: a page stamped
// `prompt-derived` is default-excluded from a shared export, and the
// exclusion is named. First match wins, so an operator's own scoping
// keeps its reason; a value this build does not know reads as unmarked
// (the read side of `readContentClass` never throws), so a hand-edited
// spelling cannot silently hide pages from every pack.
if (readContentClass(page.frontmatter) !== null) return "prompt-derived";
if (page.frontmatter["okf_review"] !== undefined) return "unreviewed";
if (page.path === OKF_REVIEW_REL || page.path.startsWith(`${OKF_REVIEW_REL}/`)) {
return "unreviewed";
}
return null;
}
// ----- Seal -----------------------------------------------------------------
function sha256(text: string): string {
return createHash("sha256").update(text, "utf8").digest("hex");
}
/**
* The pack digest: one sha256 over a canonical text naming the schema, the
* pack name and version, and every file's own hash in path order. Binding
* the name and version in means a pack cannot be renamed into another
* pack's uninstall key without its stamp changing too.
*/
function packDigest(
name: string,
version: string,
files: Readonly<Record<string, string>>,
): string {
const lines = [
`${KNOWLEDGE_PACK_KIND}/${KNOWLEDGE_PACK_SCHEMA}`,
`name=${name}`,
`version=${version}`,
];
for (const path of Object.keys(files).toSorted()) lines.push(`${path}\t${files[path]}`);
return sha256(`${lines.join("\n")}\n`);
}
function validateNameAndVersion(name: string, version: string): void {
if (!isKnowledgePackName(name)) {
throw new KnowledgePackError(
`invalid pack name ${JSON.stringify(name)}: use 1-64 of [a-z0-9._-], starting with a letter or digit`,
);
}
if (!VERSION_RE.test(version)) {
throw new KnowledgePackError(
`invalid pack version ${JSON.stringify(version)}: use 1-32 of [0-9A-Za-z._+-]`,
);
}
}
export interface SealKnowledgePackInput {
readonly name: string;
readonly version: string;
readonly selection: ReadonlyArray<string>;
readonly okfManifest: OkfManifest;
readonly pageFiles: ReadonlyArray<OkfBundleFile>;
readonly preferences: ReadonlyArray<ExportedPreferenceRow>;
readonly now?: Date;
}
export interface SealedKnowledgePack {
readonly manifest: KnowledgePackManifest;
/** Every file to write, including both manifests, sorted by path. */
readonly files: ReadonlyArray<OkfBundleFile>;
}
/**
* Render the final bundle from ALREADY-REDACTED content and seal it: the
* hashes are taken over the exact bytes written, so what the recipient
* verifies is what left the vault.
*/
export function sealKnowledgePack(input: SealKnowledgePackInput): SealedKnowledgePack {
validateNameAndVersion(input.name, input.version);
const content: OkfBundleFile[] = [
{ path: OKF_MANIFEST_FILENAME, contents: renderOkfManifest(input.okfManifest) },
...input.pageFiles,
];
if (input.preferences.length > 0) {
content.push({
path: KNOWLEDGE_PACK_PREFERENCES_FILENAME,
contents:
JSON.stringify({ schema: KNOWLEDGE_PACK_SCHEMA, preferences: input.preferences }, null, 2) +
"\n",
});
}
const hashes: Record<string, string> = {};
for (const file of content) hashes[file.path] = sha256(file.contents);
const sortedHashes: Record<string, string> = {};
for (const path of Object.keys(hashes).toSorted()) sortedHashes[path] = hashes[path]!;
const manifest: KnowledgePackManifest = {
schema: KNOWLEDGE_PACK_SCHEMA,
kind: KNOWLEDGE_PACK_KIND,
name: input.name,
version: input.version,
producer: OKF_PRODUCER,
generated_at: isoSecond(input.now ?? new Date()),
selection: [...input.selection],
integrity: {
algorithm: "sha256",
files: sortedHashes,
digest: packDigest(input.name, input.version, sortedHashes),
},
};
const files = [
...content,
{
path: KNOWLEDGE_PACK_MANIFEST_FILENAME,
contents: JSON.stringify(manifest, null, 2) + "\n",
},
].toSorted((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
return { manifest, files };
}
// ----- Read + verify --------------------------------------------------------
export interface KnowledgePackVerification {
/** True only when every listed file is present, unmodified, and nothing else is. */
readonly verified: boolean;
/** Digest the manifest declares. */
readonly declared: string;
/** Digest recomputed from the files on disk. */
readonly computed: string;
/** One line per failed check; empty when verified. */
readonly problems: ReadonlyArray<string>;
}
export interface ReadKnowledgePack {
readonly manifest: KnowledgePackManifest;
readonly integrity: KnowledgePackVerification;
/** The OKF half, parsed by the OKF reader. */
readonly okf: ParsedOkfBundle;
/** The carried preference rows, unvalidated (the restore guards each one). */
readonly preferences: ReadonlyArray<unknown>;
}
function asRecord(value: unknown): Record<string, unknown> | null {
return value !== null && typeof value === "object" && !Array.isArray(value)
? (value as Record<string, unknown>)
: null;
}
function parseManifest(raw: unknown): KnowledgePackManifest {
const m = asRecord(raw);
if (m === null)
throw new KnowledgePackError(`${KNOWLEDGE_PACK_MANIFEST_FILENAME} must be a JSON object`);
if (m["kind"] !== KNOWLEDGE_PACK_KIND) {
throw new KnowledgePackError(`not a knowledge pack: kind is ${JSON.stringify(m["kind"])}`);
}
if (m["schema"] !== KNOWLEDGE_PACK_SCHEMA) {
throw new KnowledgePackError(
`unsupported knowledge-pack schema: expected ${KNOWLEDGE_PACK_SCHEMA}, got ${String(m["schema"])}`,
);
}
const name = typeof m["name"] === "string" ? m["name"] : "";
const version = typeof m["version"] === "string" ? m["version"] : "";
validateNameAndVersion(name, version);
const integrity = asRecord(m["integrity"]);
const fileTable = asRecord(integrity?.["files"]);
const digest = integrity?.["digest"];
if (
integrity === null ||
integrity["algorithm"] !== "sha256" ||
fileTable === null ||
typeof digest !== "string" ||
!HEX64_RE.test(digest)
) {
throw new KnowledgePackError("knowledge-pack manifest has no usable sha256 integrity block");
}
const files: Record<string, string> = {};
for (const [path, hash] of Object.entries(fileTable)) {
if (typeof hash !== "string" || !HEX64_RE.test(hash)) {
throw new KnowledgePackError(`integrity entry for ${path} is not a sha256 hex digest`);
}
files[path] = hash;
}
return {
schema: KNOWLEDGE_PACK_SCHEMA,
kind: KNOWLEDGE_PACK_KIND,
name,
version,
producer: typeof m["producer"] === "string" ? m["producer"] : "unknown",
generated_at: typeof m["generated_at"] === "string" ? m["generated_at"] : "",
selection: stringList(m["selection"]),
integrity: { algorithm: "sha256", files, digest },
};
}
/** Every regular file under `dir`, bundle-relative POSIX; symlinks reported. */
function listBundleFiles(dir: string, problems: string[]): string[] {
const out: string[] = [];
const walk = (abs: string): void => {
let entries: Dirent[];
try {
entries = readdirSync(abs, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
const child = join(abs, entry.name);
const rel = relative(dir, child).split(/[\\/]/).join(posix.sep);
if (entry.isSymbolicLink()) {
problems.push(`symbolic link in bundle: ${rel}`);
continue;
}
if (entry.isDirectory()) walk(child);
else if (entry.isFile()) out.push(rel);
}
};
walk(dir);
return out.toSorted();
}
/**
* Read a pack directory and verify it against its own manifest. A missing
* or structurally invalid `knowledge-pack.json` throws
* {@link KnowledgePackError} (this is not a pack at all). An integrity
* failure does NOT throw: preview reports it, install refuses on it.
*/
export function readKnowledgePack(dir: string): ReadKnowledgePack {
const manifestPath = join(dir, KNOWLEDGE_PACK_MANIFEST_FILENAME);
if (!existsSync(manifestPath)) {
throw new KnowledgePackError(`not a knowledge pack: ${manifestPath} is missing`);
}
let raw: unknown;
try {
raw = JSON.parse(readFileSync(manifestPath, "utf8"));
} catch (exc) {
throw new KnowledgePackError(
`${KNOWLEDGE_PACK_MANIFEST_FILENAME} is not valid JSON: ${(exc as Error).message}`,
);
}
const manifest = parseManifest(raw);
const problems: string[] = [];
const listed = manifest.integrity.files;
const computedFiles: Record<string, string> = {};
for (const [path, expected] of Object.entries(listed)) {
let abs: string;
try {
abs = ensureInsideVault(join(dir, path), dir);
} catch {
problems.push(`listed path escapes the bundle: ${path}`);
continue;
}
let bytes: string;
try {
if (lstatSync(abs).isSymbolicLink()) {
problems.push(`symbolic link in bundle: ${path}`);
continue;
}
bytes = readFileSync(abs, "utf8");
} catch {
problems.push(`listed file is missing: ${path}`);
continue;
}
const actual = sha256(bytes);
computedFiles[path] = actual;
if (actual !== expected) problems.push(`file content does not match its hash: ${path}`);
}
for (const path of listBundleFiles(dir, problems)) {
if (path === KNOWLEDGE_PACK_MANIFEST_FILENAME) continue;
if (!(path in listed)) problems.push(`file not covered by the integrity table: ${path}`);
}
if (!(OKF_MANIFEST_FILENAME in listed)) {
problems.push(`integrity table does not cover ${OKF_MANIFEST_FILENAME}`);
}
const computed = packDigest(manifest.name, manifest.version, computedFiles);
if (manifest.integrity.digest !== packDigest(manifest.name, manifest.version, listed)) {
problems.push("declared digest does not match the declared file table");
}
let okf: ParsedOkfBundle;
try {
okf = readOkfBundle(dir);
} catch (exc) {
throw new KnowledgePackError(
`knowledge pack's OKF half is unreadable: ${(exc as Error).message}`,
);
}
if (okf.pages.length !== okf.manifest.pages.length) {
problems.push(
`okf.json lists ${okf.manifest.pages.length} page(s) but ${okf.pages.length} could be read`,
);
}
let preferences: ReadonlyArray<unknown> = [];
const prefsPath = join(dir, KNOWLEDGE_PACK_PREFERENCES_FILENAME);
if (existsSync(prefsPath)) {
try {
const doc = asRecord(JSON.parse(readFileSync(prefsPath, "utf8")));
const rows = doc?.["preferences"];
if (!Array.isArray(rows)) throw new Error("no preferences array");
preferences = rows;
} catch (exc) {
problems.push(
`${KNOWLEDGE_PACK_PREFERENCES_FILENAME} is unreadable: ${(exc as Error).message}`,
);
}
}
return {
manifest,
integrity: {
verified: problems.length === 0,
declared: manifest.integrity.digest,
computed,
problems,
},
okf,
preferences,
};
}
// ----- Preview --------------------------------------------------------------
export interface KnowledgePackPreviewEntry {
readonly kind: KnowledgePackEntryKind;
readonly id: string;
readonly topic: string | null;
/** Page: the recorded vault path. Preference: null. */
readonly path: string | null;
/** Preference: the status it carried in the SOURCE vault (it lands `unconfirmed`). */
readonly status: string | null;
/** Vault-relative path the entry would be written to. */
readonly target: string;
/** Up to 240 chars, passed through the prompt-injection guard. */
readonly sample: string;
}
export type KnowledgePackConflictReason =
/** A preference with this id already exists; install skips it. */
| "id_exists"
/** A preference with this slug was retired here; install skips it. */
| "previously_retired"
/** A different local preference already claims this topic key. */
| "topic_claimed"
/** The review-lane target already exists; install skips it. */
| "review_target_exists"
/** A live page already sits at the recorded path (promotion would collide). */
| "path_exists";
export interface KnowledgePackConflict {
readonly kind: KnowledgePackEntryKind;
readonly id: string;
readonly reason: KnowledgePackConflictReason;
readonly detail: string;
}
export interface KnowledgePackPreview {
readonly schema: 1;
readonly name: string;
readonly version: string;
readonly generated_at: string;
readonly selection: ReadonlyArray<string>;
/** The provenance stamp an install would write. */
readonly stamp: string;
readonly count: number;
readonly counts: { readonly preferences: number; readonly pages: number };
readonly entries: ReadonlyArray<KnowledgePackPreviewEntry>;
readonly integrity: KnowledgePackVerification;
readonly conflicts: ReadonlyArray<KnowledgePackConflict>;
readonly privacyWarnings: ReadonlyArray<KnowledgePackWarning>;
}
function previewWarnings(text: string, id: string): string[] {
const codes = injectionCodes(text, id);
if (text.includes(REDACTION_PLACEHOLDER) || text.includes(PRIVATE_REGION_PLACEHOLDER)) {
codes.push(REDACTED_CONTENT_WARNING);
}
if (scanRawOutput(text, { redactTokens: true, redactUrlCredentials: true }).text !== text) {
// The scan also rewrites `<private>` regions; either way the content
// is something the export boundary would not have let out verbatim.
codes.push(SECRET_SHAPED_WARNING);
}
return [...new Set(codes)].toSorted();
}
function rowText(row: unknown): {
id: string;
topic: string | null;
status: string | null;
text: string;
} {
const r = asRecord(row) ?? {};
const id = typeof r["id"] === "string" ? r["id"] : "(no id)";
const topic = typeof r["topic"] === "string" ? r["topic"] : null;
const status = typeof r["status"] === "string" ? r["status"] : null;
const principle = typeof r["principle"] === "string" ? r["principle"] : "";
const body = typeof r["body"] === "string" ? r["body"] : "";
return { id, topic, status, text: body === "" ? principle : `${principle}\n${body}` };
}
function slugOf(id: string): string | null {
return id.startsWith("pref-") && id.length > 5 ? id.slice(5) : null;
}
function safePreferencePath(vault: string, slug: string): string | null {
try {
return preferencePath(vault, slug);
} catch {
return null;
}
}
function safeRetiredPath(vault: string, slug: string): string | null {
try {
return retiredPath(vault, slug);
} catch {
return null;
}
}
function preferenceConflicts(vault: string, id: string): KnowledgePackConflict[] {
const slug = slugOf(id);
if (slug === null) return [];
const live = safePreferencePath(vault, slug);
if (live !== null && existsSync(live)) {
return [{ kind: "preference", id, reason: "id_exists", detail: `Brain/preferences/${id}.md` }];
}
const retired = safeRetiredPath(vault, slug);
if (retired !== null && existsSync(retired)) {
return [
{
kind: "preference",
id,
reason: "previously_retired",
detail: `Brain/retired/ret-${slug}.md`,
},
];
}
return [];
}
/**
* What installing `pack` into `vault` would do, without writing anything:
* the manifest facts, every entry with a guarded sample and its landing
* path, the integrity verdict, conflicts with what the vault already holds,
* and privacy / prompt-injection warnings.
*/
export function previewKnowledgePack(vault: string, pack: ReadKnowledgePack): KnowledgePackPreview {
const entries: KnowledgePackPreviewEntry[] = [];
const conflicts: KnowledgePackConflict[] = [];
const warnings: KnowledgePackWarning[] = [];
const localTopics = new Map<string, string[]>();
for (const row of collectPreferenceRows(vault).rows) {
const key = topicKey(row.topic);
localTopics.set(key, [...(localTopics.get(key) ?? []), row.id]);
}
for (const row of pack.preferences) {
const { id, topic, status, text } = rowText(row);
const guarded = guardBrainContextSnippet(text, { source: { id } });
entries.push({
kind: "preference",
id,
topic,
path: null,
status,
target: `${BRAIN_PREFERENCES_REL}/${id}.md`,
sample: guarded.safeText.slice(0, SAMPLE_CHARS),
});
conflicts.push(...preferenceConflicts(vault, id));
if (topic !== null) {
const claimants = (localTopics.get(topicKey(topic)) ?? []).filter((other) => other !== id);
if (claimants.length > 0) {
conflicts.push({
kind: "preference",
id,
reason: "topic_claimed",
detail: claimants.toSorted().join(", "),
});
}
}
const codes = previewWarnings(text, id);
if (codes.length > 0) warnings.push({ kind: "preference", id, reasons: codes });
}
for (const page of pack.okf.pages) {
const path = page.entry.path;
const target = posix.join(OKF_REVIEW_REL, path);
const guarded = guardBrainContextSnippet(page.body, { source: { id: path } });
const topic = page.frontmatter["topic"];
entries.push({
kind: "page",
id: page.entry.id,
topic: typeof topic === "string" ? topic : null,
path,
status: null,
target,
sample: guarded.safeText.slice(0, SAMPLE_CHARS),
});
if (vaultFileExists(vault, target)) {
conflicts.push({ kind: "page", id: path, reason: "review_target_exists", detail: target });
}
if (vaultFileExists(vault, path)) {
conflicts.push({ kind: "page", id: path, reason: "path_exists", detail: path });
}
const codes = previewWarnings(page.body, path);
if (codes.length > 0) warnings.push({ kind: "page", id: path, reasons: codes });
}
const prefCount = pack.preferences.length;
return {
schema: 1,
name: pack.manifest.name,
version: pack.manifest.version,
generated_at: pack.manifest.generated_at,
selection: pack.manifest.selection,
stamp: formatKnowledgePackStamp(pack.manifest.name, pack.manifest.integrity.digest),
count: entries.length,
counts: { preferences: prefCount, pages: entries.length - prefCount },
entries,
integrity: pack.integrity,
conflicts,
privacyWarnings: warnings,
};
}
function vaultFileExists(vault: string, rel: string): boolean {
try {
return existsSync(ensureInsideVault(join(vault, rel), vault));
} catch {
return false;
}
}
// ----- Install --------------------------------------------------------------
export interface KnowledgePackInstallResult {
readonly name: string;
readonly version: string;
readonly stamp: string;
readonly preferences: {
readonly carried: number;
/** Ids written, each `unconfirmed` on a fresh trial window. */
readonly installed: ReadonlyArray<string>;
/** Rows skipped because the vault already holds (or retired) the id. */
readonly conflicts: ReadonlyArray<KnowledgePackConflict>;
/** Rows the audited restore refused, with its reason. */
readonly failed: ReadonlyArray<PreferenceRestoreFailureRecord>;
readonly topicKeyCollisions: ReadonlyArray<RestoredTopicKeyCollision>;
};
readonly pages: Pick<OkfImportResult, "written" | "skipped" | "errors">;
readonly privacyWarnings: ReadonlyArray<KnowledgePackWarning>;
}
export interface InstallKnowledgePackOptions {
readonly agent?: string;
readonly now?: Date;
}
/**
* Install a verified pack. Refuses (throws {@link KnowledgePackError})
* when the integrity check failed - a pack whose bytes differ from what
* its author sealed is not installed in part.
*
* Nothing lands trusted. Pages go to the OKF review lane with machinery
* stripped; preferences land `unconfirmed` on a fresh trial window with the
* source vault's lifecycle cleared. Both are stamped `knowledge_pack:
* <name>@<digest12>` by this installer. A preference whose id the vault
* already holds, or once retired, is skipped and reported - an install
* never overwrites a local rule or resurrects a rejected one.
*/
export function installKnowledgePack(
vault: string,
pack: ReadKnowledgePack,
opts: InstallKnowledgePackOptions = {},
): KnowledgePackInstallResult {
if (!pack.integrity.verified) {
throw new KnowledgePackError(
`refusing to install ${pack.manifest.name}: integrity check failed (${pack.integrity.problems.join("; ")})`,
);
}
assertVaultIdentityForWrite(vault);
const now = opts.now ?? new Date();
const stamp = formatKnowledgePackStamp(pack.manifest.name, pack.manifest.integrity.digest);
const preview = previewKnowledgePack(vault, pack);
const conflicts: KnowledgePackConflict[] = [];
const rows: unknown[] = [];
for (const row of pack.preferences) {
const found = preferenceConflicts(vault, rowText(row).id);
if (found.length > 0) conflicts.push(...found);
else rows.push(row);
}
const restored = restorePreferences(vault, rows, {
agent: opts.agent?.trim() ? opts.agent.trim() : KNOWLEDGE_PACK_DEFAULT_AGENT,
knowledgePack: stamp,
now: () => now,
});
const pages = importOkfBundle(vault, pack.okf, {
trusted: false,
now,
provenance: { [KNOWLEDGE_PACK_FIELD]: stamp },
});
for (const rel of pages.written) recordStagedFingerprint(join(vault, rel));
return {
name: pack.manifest.name,
version: pack.manifest.version,
stamp,
preferences: {
carried: pack.preferences.length,
installed: restored.restored,
conflicts,
failed: restored.failed,
topicKeyCollisions: restored.topicKeyCollisions,
},
pages: { written: pages.written, skipped: pages.skipped, errors: pages.errors },
privacyWarnings: preview.privacyWarnings,
};
}
// ----- Staged-page fingerprint ----------------------------------------------
/** JSON with object keys sorted at every level, so key order is not content. */
function canonicalJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
if (value instanceof Date) return JSON.stringify(value.toISOString());
if (value !== null && typeof value === "object") {
const entries = Object.keys(value as Record<string, unknown>)
.toSorted()
.map((k) => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`);
return `{${entries.join(",")}}`;
}
return JSON.stringify(value) ?? "null";
}
/**
* What an operator edit changes on a staged page: its body and every
* frontmatter key except this system's machinery (the review flag, the
* pack stamp and fingerprint, lifecycle and write-accounting keys).
* Trailing whitespace of the body does not count.
*/
function stagedPageFingerprint(text: string): string {
const [meta, body] = parseFrontmatterText(text);
const authored = canonicalJson(stripOkfMachinery(meta));
return sha256(`${authored}\n---\n${body.replace(/\s+$/u, "")}`);
}
/**
* Write the fingerprint of a page the installer just staged into its
* frontmatter, as one line after the stamp. Inserted as text rather than
* re-serialised, so nothing the fingerprint covers changes on the way.
*/
function recordStagedFingerprint(abs: string): void {
let text: string;
try {
text = readFileSync(abs, "utf8");
} catch {
return;
}
const stampLine = new RegExp(`^${KNOWLEDGE_PACK_FIELD}:.*$`, "mu");
const match = stampLine.exec(text);
if (match === null) return;
const at = match.index + match[0].length;
const line = `\n${KNOWLEDGE_PACK_SHA_FIELD}: ${stagedPageFingerprint(text)}`;
atomicWriteFileSync(abs, `${text.slice(0, at)}${line}${text.slice(at)}`);
}
/**
* Has the operator changed a staged page since install? A page without a
* recorded fingerprint counts as changed: nothing proves it is untouched,
* and keeping a page is the recoverable side of the choice.
*/
function stagedPageEdited(text: string, meta: FrontmatterMap): boolean {
const recorded = meta[KNOWLEDGE_PACK_SHA_FIELD];
if (typeof recorded !== "string" || !HEX64_RE.test(recorded.trim())) return true;
return stagedPageFingerprint(text) !== recorded.trim();
}
// ----- Installed entries: list + uninstall ----------------------------------
export interface KnowledgePackInstalledEntry {
readonly kind: KnowledgePackEntryKind;
readonly id: string;
/** Vault-relative POSIX path. */
readonly path: string;
/** The full stamp (`<name>@<digest12>`). */
readonly stamp: string;
/**
* Page: `staged` while under `OKF Review/`, `promoted` once moved out of
* it. Preference: its current lifecycle status.
*/
readonly state: string;
/** Preference only: evidence links it has gained in THIS vault. */
readonly localEvidence: number;
/**
* Staged page only: its content differs from what the installer wrote
* (or no install fingerprint is recorded). Always false otherwise.
*/
readonly edited: boolean;
}
function evidenceLinks(meta: FrontmatterMap): string[] {
const managed = stringList(meta["_evidenced_by"]);
return managed.length > 0 ? managed : stringList(meta["evidenced_by"]);
}
function readStamped(abs: string): { meta: FrontmatterMap; stamp: string; text: string } | null {
let text: string;
try {
text = readFileSync(abs, "utf8");
} catch {
return null;
}
if (!text.includes(KNOWLEDGE_PACK_FIELD)) return null;
const meta = parseFrontmatterText(text)[0];
const stamp = parseKnowledgePackStamp(meta[KNOWLEDGE_PACK_FIELD]);
return stamp === null ? null : { meta, stamp: `${stamp.name}@${stamp.digest}`, text };
}
function toPosix(p: string): string {
return p.split(/[\\/]/).join(posix.sep);
}
/** Every entry in the vault carrying a knowledge-pack stamp. Read-only. */
function scanInstalled(vault: string): KnowledgePackInstalledEntry[] {
const out: KnowledgePackInstalledEntry[] = [];
const prefDir = join(vault, BRAIN_PREFERENCES_REL);
let names: string[] = [];
try {
names = readdirSync(prefDir);
} catch {
names = [];
}
for (const name of names.toSorted()) {
if (!name.startsWith("pref-") || !name.endsWith(".md")) continue;
const found = readStamped(join(prefDir, name));
if (found === null) continue;
const status = found.meta["_status"] ?? found.meta["status"];
out.push({
kind: "preference",
id: name.slice(0, -3),
path: `${BRAIN_PREFERENCES_REL}/${name}`,
stamp: found.stamp,
state: typeof status === "string" ? status : "unknown",
localEvidence: evidenceLinks(found.meta).length,
edited: false,
});
}
// Pages: everything outside Brain/ - the review lane and wherever an
// operator promoted a candidate to.
const skip = new Set<string>(EXCLUDED_DIRS);
const walk = (dir: string, top: boolean): void => {
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
if (entry.name.startsWith(".")) continue;
const abs = join(dir, entry.name);
if (entry.isDirectory()) {
if (skip.has(entry.name) || (top && entry.name === BRAIN_ROOT_REL)) continue;
walk(abs, false);
continue;
}
if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) continue;
const found = readStamped(abs);
if (found === null) continue;
const rel = toPosix(relative(vault, abs));
const staged = rel.startsWith(`${OKF_REVIEW_REL}/`);
out.push({
kind: "page",
id: rel,
path: rel,
stamp: found.stamp,
state: staged ? "staged" : "promoted",
localEvidence: 0,
edited: staged && stagedPageEdited(found.text, found.meta),
});
}
};
walk(vault, true);
return out;
}
export interface InstalledKnowledgePack {
readonly name: string;
/** Distinct stamps (builds) of this pack present in the vault. */
readonly stamps: ReadonlyArray<string>;
readonly entries: ReadonlyArray<KnowledgePackInstalledEntry>;
}
/** The packs installed in `vault`, by name, with every stamped entry. Read-only. */
export function listInstalledKnowledgePacks(vault: string): ReadonlyArray<InstalledKnowledgePack> {
const byName = new Map<string, KnowledgePackInstalledEntry[]>();
for (const entry of scanInstalled(vault)) {
const name = entry.stamp.slice(0, entry.stamp.lastIndexOf("@"));
byName.set(name, [...(byName.get(name) ?? []), entry]);
}
return [...byName.keys()].toSorted().map((name) => {
const entries = byName.get(name)!;
return {
name,
stamps: [...new Set(entries.map((e) => e.stamp))].toSorted(),
entries,
};
});
}
export type KnowledgePackKeptReason =
/** The preference gained evidence links in this vault; it is no longer only the pack's. */
| "local_evidence"
/** The page was promoted out of the review lane by an operator. */
| "promoted"
/** The page is still staged, but its content changed since install. */
| "edited";
export interface KnowledgePackUninstallPlan {
readonly name: string;
readonly confirmed: boolean;
/** Entries removed (or, on a dry run, that would be). */
readonly remove: ReadonlyArray<KnowledgePackInstalledEntry>;
/** Stamped entries reported but left in place, with why. */
readonly kept: ReadonlyArray<{
readonly entry: KnowledgePackInstalledEntry;
readonly reason: KnowledgePackKeptReason;
}>;
/** Paths actually removed this run (empty on a dry run). */
readonly deleted: ReadonlyArray<string>;
readonly snapshotRunId: string | null;
readonly snapshotPath: string | null;
/** What the recovery point is worth: staged pages live outside `Brain/`. */
readonly recoverability: RecoverabilityVerdict;
readonly auditRecordId: string | null;
}
export interface UninstallKnowledgePackOptions {
/** Required true to delete; absent = dry run. */
readonly confirm?: boolean;
readonly now?: Date;
readonly agent?: string;
}
/**
* Remove the entries one pack installed - every build of it, since the
* name is the unit. DRY-RUN BY DEFAULT, like `forget-source`.
*
* Removed: stamped preferences carrying no evidence links, and stamped
* pages still staged under `OKF Review/`. Kept and reported: a preference
* that has gained evidence in this vault (the same "a shared fold is
* reported, never deleted" line `forget-source` draws for foreign
* evidence), a page an operator promoted out of the review lane, and a
* staged page whose content changed since install (its body or authored
* frontmatter no longer match the fingerprint the installer recorded).
* The destructive snapshot archives `Brain/` only, so a staged page is
* deleted only when its content is what re-installing the pack restores.
* A confirmed run removes behind the destructive-snapshot gate and
* records a `source_invalidation` continuity record naming `pack:<name>`.
*/
export function uninstallKnowledgePack(
vault: string,
name: string,
opts: UninstallKnowledgePackOptions = {},
): KnowledgePackUninstallPlan {
if (!isKnowledgePackName(name)) {
throw new KnowledgePackError(`invalid pack name ${JSON.stringify(name)}`);
}
const confirm = opts.confirm === true;
if (confirm) assertVaultIdentityForWrite(vault);
const remove: KnowledgePackInstalledEntry[] = [];
const kept: { entry: KnowledgePackInstalledEntry; reason: KnowledgePackKeptReason }[] = [];
for (const entry of scanInstalled(vault)) {
if (entry.stamp.slice(0, entry.stamp.lastIndexOf("@")) !== name) continue;
if (entry.kind === "preference" && entry.localEvidence > 0) {
kept.push({ entry, reason: "local_evidence" });
} else if (entry.kind === "page" && entry.state === "promoted") {
kept.push({ entry, reason: "promoted" });
} else if (entry.kind === "page" && entry.edited) {
kept.push({ entry, reason: "edited" });
} else {
remove.push(entry);
}
}
const blastRadius = {
brainTopLevel: remove.some((e) => e.kind === "preference"),
outsideBrainRoot: remove.some((e) => e.kind === "page"),
};
const base = { name, remove, kept };
if (!confirm || remove.length === 0) {
return {
...base,
confirmed: confirm,
deleted: [],
snapshotRunId: null,
snapshotPath: null,
recoverability: classifyRecoverability({ recoveryPoint: false, blastRadius: {} }),
auditRecordId: null,
};
}
const deleted: string[] = [];
const gated = withDestructiveSnapshot(
vault,
BRAIN_SNAPSHOT_REASON.knowledgePackUninstall,
() => {
for (const entry of remove) {
const abs = ensureInsideVault(join(vault, entry.path), vault);
rmSync(abs, { force: true });
deleted.push(entry.path);
}
},
{ ...(opts.now !== undefined ? { now: opts.now } : {}), blastRadius },
);
const agent = opts.agent?.trim() ? opts.agent.trim() : KNOWLEDGE_PACK_DEFAULT_AGENT;
const record = appendContinuitySourceInvalidation(vault, {
createdAt: isoSecond(opts.now ?? new Date()),
source: { id: `pack:${name}`, path: `pack:${name}`, kind: "knowledge-pack" },
reason: `${agent}: uninstalled ${deleted.length} knowledge-pack entr${deleted.length === 1 ? "y" : "ies"}`,
});
return {
...base,
confirmed: true,
deleted,
snapshotRunId: gated.snapshot.runId,
snapshotPath: gated.snapshot.path,
recoverability: gated.recoverability,
auditRecordId: record.id,
};
}