@turbomem/okf 0.2.0

package/dist/index.cjs

@@ -0,0 +1,269 @@
+'use strict';
+
+var path = require('path');
+var fs2 = require('fs/promises');
+var matter = require('gray-matter');
+var fg = require('fast-glob');
+var unified = require('unified');
+var remarkParse = require('remark-parse');
+var unistUtilVisit = require('unist-util-visit');
+var zod = require('zod');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefault(path);
+var fs2__default = /*#__PURE__*/_interopDefault(fs2);
+var matter__default = /*#__PURE__*/_interopDefault(matter);
+var fg__default = /*#__PURE__*/_interopDefault(fg);
+var remarkParse__default = /*#__PURE__*/_interopDefault(remarkParse);
+
+// src/parser.ts
+function normalizeRelativePath(relativePath) {
+  return relativePath.split(path__default.default.sep).join("/");
+}
+function resolveLinkHref(href, documentPath, bundleRoot) {
+  const withoutFragment = href.split("#")[0] ?? href;
+  if (withoutFragment.startsWith("/")) {
+    return path__default.default.join(bundleRoot, withoutFragment.slice(1));
+  }
+  return path__default.default.resolve(path__default.default.dirname(documentPath), withoutFragment);
+}
+function extractLinks(body, documentPath, bundleRoot, followLinks) {
+  const links = [];
+  const tree = unified.unified().use(remarkParse__default.default).parse(body);
+  unistUtilVisit.visit(tree, "link", (node) => {
+    const linkNode = node;
+    const href = linkNode.url;
+    const text = linkNode.children?.[0]?.type === "text" ? linkNode.children[0].value ?? "" : "";
+    if (href.startsWith("http://") || href.startsWith("https://")) {
+      links.push({ text, href });
+      return;
+    }
+    const link = { text, href };
+    if (followLinks) {
+      const resolvedAbsolute = resolveLinkHref(href, documentPath, bundleRoot);
+      link.resolvedPath = normalizeRelativePath(path__default.default.relative(bundleRoot, resolvedAbsolute));
+    }
+    links.push(link);
+  });
+  return links;
+}
+function normalizeFrontmatter(data) {
+  const normalized = { ...data };
+  if (normalized.timestamp instanceof Date) {
+    normalized.timestamp = normalized.timestamp.toISOString();
+  }
+  return normalized;
+}
+async function parseDocument(filePath, bundleRoot, options = {}) {
+  const { followLinks = true } = options;
+  const raw = await fs2__default.default.readFile(filePath, "utf-8");
+  const { data, content } = matter__default.default(raw);
+  const relativePath = normalizeRelativePath(path__default.default.relative(bundleRoot, filePath));
+  const links = extractLinks(content, filePath, bundleRoot, followLinks);
+  return {
+    path: filePath,
+    relativePath,
+    frontmatter: normalizeFrontmatter(data),
+    body: content,
+    links
+  };
+}
+async function parseBundle(rootDir, options = {}) {
+  const absoluteRoot = path__default.default.resolve(rootDir);
+  const ignorePatterns = options.ignore ?? [];
+  const filePaths = await fg__default.default("**/*.md", {
+    cwd: absoluteRoot,
+    absolute: true,
+    ignore: ignorePatterns
+  });
+  const documents = await Promise.all(
+    filePaths.map((fp) => parseDocument(fp, absoluteRoot, options))
+  );
+  const index = /* @__PURE__ */ new Map();
+  for (const doc of documents) {
+    index.set(doc.relativePath, doc);
+  }
+  return { root: absoluteRoot, documents, index };
+}
+var frontmatterSchema = zod.z.object({
+  type: zod.z.string().min(1, "type field must be a non-empty string"),
+  title: zod.z.string().optional(),
+  description: zod.z.string().optional(),
+  resource: zod.z.string().url("resource must be a valid URL").optional(),
+  tags: zod.z.array(zod.z.string()).optional(),
+  timestamp: zod.z.string().datetime({ offset: true }).optional()
+}).passthrough();
+function validateDocument(doc) {
+  const errors = [];
+  const warnings = [];
+  const result = frontmatterSchema.safeParse(doc.frontmatter);
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      errors.push({
+        path: doc.relativePath,
+        message: issue.message,
+        rule: "frontmatter-schema"
+      });
+    }
+  }
+  if (!doc.body.trim()) {
+    warnings.push({
+      path: doc.relativePath,
+      message: "Document body is empty",
+      rule: "empty-body"
+    });
+  }
+  if (doc.frontmatter.timestamp) {
+    const d = Date.parse(doc.frontmatter.timestamp);
+    if (isNaN(d)) {
+      errors.push({
+        path: doc.relativePath,
+        message: `timestamp "${doc.frontmatter.timestamp}" is not a valid ISO 8601 date`,
+        rule: "timestamp-format"
+      });
+    }
+  }
+  return { errors, warnings };
+}
+function validateBundle(bundle) {
+  const allErrors = [];
+  const allWarnings = [];
+  for (const doc of bundle.documents) {
+    const { errors, warnings } = validateDocument(doc);
+    allErrors.push(...errors);
+    allWarnings.push(...warnings);
+  }
+  for (const doc of bundle.documents) {
+    for (const link of doc.links) {
+      if (link.resolvedPath && !bundle.index.has(link.resolvedPath)) {
+        allWarnings.push({
+          path: doc.relativePath,
+          message: `Cross-link "${link.href}" does not resolve to a known concept in this bundle`,
+          rule: "unresolved-cross-link"
+        });
+      }
+    }
+  }
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+function serializeDocument(frontmatter, body) {
+  return matter__default.default.stringify(body, frontmatter);
+}
+async function writeDocument(outputPath, frontmatter, body, options = {}) {
+  const { overwrite = false } = options;
+  let exists = false;
+  try {
+    await fs2__default.default.access(outputPath);
+    exists = true;
+  } catch {
+    exists = false;
+  }
+  if (exists && !overwrite) {
+    throw new Error(`File already exists: ${outputPath}. Pass overwrite: true to replace it.`);
+  }
+  await fs2__default.default.mkdir(path__default.default.dirname(outputPath), { recursive: true });
+  const content = serializeDocument(frontmatter, body);
+  await fs2__default.default.writeFile(outputPath, content, "utf-8");
+}
+async function writeIndex(dirPath, title, description, options = {}) {
+  const indexPath = path__default.default.join(dirPath, "index.md");
+  await writeDocument(
+    indexPath,
+    { type: "index", title, description },
+    `# ${title}
+
+${description}
+`,
+    options
+  );
+}
+
+// src/graph.ts
+function buildGraph(bundle) {
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = [];
+  for (const doc of bundle.documents) {
+    nodes.set(doc.relativePath, {
+      document: doc,
+      outgoing: [],
+      incoming: []
+    });
+  }
+  for (const doc of bundle.documents) {
+    const fromNode = nodes.get(doc.relativePath);
+    for (const link of doc.links) {
+      if (!link.resolvedPath) continue;
+      const toNode = nodes.get(link.resolvedPath);
+      if (!toNode) continue;
+      const edge = {
+        from: doc,
+        to: toNode.document,
+        linkText: link.text
+      };
+      edges.push(edge);
+      fromNode.outgoing.push(edge);
+      toNode.incoming.push(edge);
+    }
+  }
+  return { nodes, edges };
+}
+function reachableFrom(graph, startRelativePath) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [startRelativePath];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (visited.has(current)) continue;
+    visited.add(current);
+    const node = graph.nodes.get(current);
+    if (!node) continue;
+    for (const edge of node.outgoing) {
+      queue.push(edge.to.relativePath);
+    }
+  }
+  return [...visited];
+}
+
+// src/turbomem.ts
+function documentToFacts(doc) {
+  const facts = [];
+  const fm = doc.frontmatter;
+  const parts = [`[${fm.type}]`];
+  if (fm.title) parts.push(fm.title);
+  if (fm.description) parts.push("\u2014", fm.description);
+  if (fm.resource) parts.push(`(resource: ${fm.resource})`);
+  if (fm.tags?.length) parts.push(`tags: ${fm.tags.join(", ")}`);
+  facts.push(parts.join(" "));
+  const body = doc.body.trim();
+  if (body) {
+    facts.push(`${fm.title ?? doc.relativePath} details: ${body}`);
+  }
+  return facts;
+}
+function bundleToFacts(bundle) {
+  return bundle.documents.flatMap(documentToFacts);
+}
+async function addFromBundle(memory, bundle, scope = {}) {
+  const facts = bundleToFacts(bundle);
+  if (facts.length === 0) return [];
+  return memory.addFacts(facts, scope);
+}
+
+exports.addFromBundle = addFromBundle;
+exports.buildGraph = buildGraph;
+exports.bundleToFacts = bundleToFacts;
+exports.documentToFacts = documentToFacts;
+exports.parseBundle = parseBundle;
+exports.parseDocument = parseDocument;
+exports.reachableFrom = reachableFrom;
+exports.serializeDocument = serializeDocument;
+exports.validateBundle = validateBundle;
+exports.validateDocument = validateDocument;
+exports.writeDocument = writeDocument;
+exports.writeIndex = writeIndex;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/parser.ts","../src/validator.ts","../src/writer.ts","../src/graph.ts","../src/turbomem.ts"],"names":["path","unified","remarkParse","visit","fs","matter","fg","z"],"mappings":"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","file":"index.cjs","sourcesContent":["import path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport matter from \"gray-matter\";\nimport fg from \"fast-glob\";\nimport { unified } from \"unified\";\nimport remarkParse from \"remark-parse\";\nimport { visit } from \"unist-util-visit\";\nimport type { OKFBundle, OKFDocument, OKFLink, OKFFrontmatter, ParseOptions } from \"./types.js\";\n\nfunction normalizeRelativePath(relativePath: string): string {\n  return relativePath.split(path.sep).join(\"/\");\n}\n\nfunction resolveLinkHref(href: string, documentPath: string, bundleRoot: string): string {\n  const withoutFragment = href.split(\"#\")[0] ?? href;\n  if (withoutFragment.startsWith(\"/\")) {\n    return path.join(bundleRoot, withoutFragment.slice(1));\n  }\n  return path.resolve(path.dirname(documentPath), withoutFragment);\n}\n\nfunction extractLinks(\n  body: string,\n  documentPath: string,\n  bundleRoot: string,\n  followLinks: boolean,\n): OKFLink[] {\n  const links: OKFLink[] = [];\n  const tree = unified().use(remarkParse).parse(body);\n\n  visit(tree, \"link\", (node) => {\n    const linkNode = node as { url: string; children?: Array<{ type?: string; value?: string }> };\n    const href = linkNode.url;\n    const text = linkNode.children?.[0]?.type === \"text\" ? (linkNode.children[0].value ?? \"\") : \"\";\n\n    if (href.startsWith(\"http://\") || href.startsWith(\"https://\")) {\n      links.push({ text, href });\n      return;\n    }\n\n    const link: OKFLink = { text, href };\n    if (followLinks) {\n      const resolvedAbsolute = resolveLinkHref(href, documentPath, bundleRoot);\n      link.resolvedPath = normalizeRelativePath(path.relative(bundleRoot, resolvedAbsolute));\n    }\n    links.push(link);\n  });\n\n  return links;\n}\n\nfunction normalizeFrontmatter(data: Record<string, unknown>): OKFFrontmatter {\n  const normalized = { ...data };\n  if (normalized.timestamp instanceof Date) {\n    normalized.timestamp = normalized.timestamp.toISOString();\n  }\n  return normalized as OKFFrontmatter;\n}\n\nexport async function parseDocument(filePath: string, bundleRoot: string, options: ParseOptions = {}): Promise<OKFDocument> {\n  const { followLinks = true } = options;\n  const raw = await fs.readFile(filePath, \"utf-8\");\n  const { data, content } = matter(raw);\n\n  const relativePath = normalizeRelativePath(path.relative(bundleRoot, filePath));\n  const links = extractLinks(content, filePath, bundleRoot, followLinks);\n\n  return {\n    path: filePath,\n    relativePath,\n    frontmatter: normalizeFrontmatter(data as Record<string, unknown>),\n    body: content,\n    links,\n  };\n}\n\nexport async function parseBundle(rootDir: string, options: ParseOptions = {}): Promise<OKFBundle> {\n  const absoluteRoot = path.resolve(rootDir);\n  const ignorePatterns = options.ignore ?? [];\n\n  const filePaths = await fg(\"**/*.md\", {\n    cwd: absoluteRoot,\n    absolute: true,\n    ignore: ignorePatterns,\n  });\n\n  const documents = await Promise.all(\n    filePaths.map((fp) => parseDocument(fp, absoluteRoot, options)),\n  );\n\n  const index = new Map<string, OKFDocument>();\n  for (const doc of documents) {\n    index.set(doc.relativePath, doc);\n  }\n\n  return { root: absoluteRoot, documents, index };\n}\n","import { z } from \"zod\";\nimport type {\n  OKFBundle,\n  OKFDocument,\n  OKFValidationResult,\n  OKFValidationError,\n  OKFValidationWarning,\n} from \"./types.js\";\n\nconst frontmatterSchema = z\n  .object({\n    type: z.string().min(1, \"type field must be a non-empty string\"),\n    title: z.string().optional(),\n    description: z.string().optional(),\n    resource: z.string().url(\"resource must be a valid URL\").optional(),\n    tags: z.array(z.string()).optional(),\n    timestamp: z.string().datetime({ offset: true }).optional(),\n  })\n  .passthrough();\n\nexport function validateDocument(doc: OKFDocument): {\n  errors: OKFValidationError[];\n  warnings: OKFValidationWarning[];\n} {\n  const errors: OKFValidationError[] = [];\n  const warnings: OKFValidationWarning[] = [];\n\n  const result = frontmatterSchema.safeParse(doc.frontmatter);\n  if (!result.success) {\n    for (const issue of result.error.issues) {\n      errors.push({\n        path: doc.relativePath,\n        message: issue.message,\n        rule: \"frontmatter-schema\",\n      });\n    }\n  }\n\n  if (!doc.body.trim()) {\n    warnings.push({\n      path: doc.relativePath,\n      message: \"Document body is empty\",\n      rule: \"empty-body\",\n    });\n  }\n\n  if (doc.frontmatter.timestamp) {\n    const d = Date.parse(doc.frontmatter.timestamp);\n    if (isNaN(d)) {\n      errors.push({\n        path: doc.relativePath,\n        message: `timestamp \"${doc.frontmatter.timestamp}\" is not a valid ISO 8601 date`,\n        rule: \"timestamp-format\",\n      });\n    }\n  }\n\n  return { errors, warnings };\n}\n\nexport function validateBundle(bundle: OKFBundle): OKFValidationResult {\n  const allErrors: OKFValidationError[] = [];\n  const allWarnings: OKFValidationWarning[] = [];\n\n  for (const doc of bundle.documents) {\n    const { errors, warnings } = validateDocument(doc);\n    allErrors.push(...errors);\n    allWarnings.push(...warnings);\n  }\n\n  for (const doc of bundle.documents) {\n    for (const link of doc.links) {\n      if (link.resolvedPath && !bundle.index.has(link.resolvedPath)) {\n        allWarnings.push({\n          path: doc.relativePath,\n          message: `Cross-link \"${link.href}\" does not resolve to a known concept in this bundle`,\n          rule: \"unresolved-cross-link\",\n        });\n      }\n    }\n  }\n\n  return {\n    valid: allErrors.length === 0,\n    errors: allErrors,\n    warnings: allWarnings,\n  };\n}\n","import path from \"node:path\";\nimport fs from \"node:fs/promises\";\nimport matter from \"gray-matter\";\nimport type { OKFFrontmatter, WriteOptions } from \"./types.js\";\n\nexport function serializeDocument(frontmatter: OKFFrontmatter, body: string): string {\n  return matter.stringify(body, frontmatter as Record<string, unknown>);\n}\n\nexport async function writeDocument(\n  outputPath: string,\n  frontmatter: OKFFrontmatter,\n  body: string,\n  options: WriteOptions = {},\n): Promise<void> {\n  const { overwrite = false } = options;\n\n  let exists = false;\n  try {\n    await fs.access(outputPath);\n    exists = true;\n  } catch {\n    exists = false;\n  }\n\n  if (exists && !overwrite) {\n    throw new Error(`File already exists: ${outputPath}. Pass overwrite: true to replace it.`);\n  }\n\n  await fs.mkdir(path.dirname(outputPath), { recursive: true });\n  const content = serializeDocument(frontmatter, body);\n  await fs.writeFile(outputPath, content, \"utf-8\");\n}\n\nexport async function writeIndex(\n  dirPath: string,\n  title: string,\n  description: string,\n  options: WriteOptions = {},\n): Promise<void> {\n  const indexPath = path.join(dirPath, \"index.md\");\n  await writeDocument(\n    indexPath,\n    { type: \"index\", title, description },\n    `# ${title}\\n\\n${description}\\n`,\n    options,\n  );\n}\n","import type { OKFBundle, OKFGraph, OKFNode, OKFEdge } from \"./types.js\";\n\nexport function buildGraph(bundle: OKFBundle): OKFGraph {\n  const nodes = new Map<string, OKFNode>();\n  const edges: OKFEdge[] = [];\n\n  for (const doc of bundle.documents) {\n    nodes.set(doc.relativePath, {\n      document: doc,\n      outgoing: [],\n      incoming: [],\n    });\n  }\n\n  for (const doc of bundle.documents) {\n    const fromNode = nodes.get(doc.relativePath)!;\n\n    for (const link of doc.links) {\n      if (!link.resolvedPath) continue;\n      const toNode = nodes.get(link.resolvedPath);\n      if (!toNode) continue;\n\n      const edge: OKFEdge = {\n        from: doc,\n        to: toNode.document,\n        linkText: link.text,\n      };\n\n      edges.push(edge);\n      fromNode.outgoing.push(edge);\n      toNode.incoming.push(edge);\n    }\n  }\n\n  return { nodes, edges };\n}\n\nexport function reachableFrom(graph: OKFGraph, startRelativePath: string): string[] {\n  const visited = new Set<string>();\n  const queue = [startRelativePath];\n\n  while (queue.length > 0) {\n    const current = queue.shift()!;\n    if (visited.has(current)) continue;\n    visited.add(current);\n\n    const node = graph.nodes.get(current);\n    if (!node) continue;\n\n    for (const edge of node.outgoing) {\n      queue.push(edge.to.relativePath);\n    }\n  }\n\n  return [...visited];\n}\n","import type { OKFBundle, OKFDocument } from \"./types.js\";\n\nexport interface OKFMemoryScope {\n  userId?: string;\n  agentId?: string;\n  sessionId?: string;\n}\n\nexport interface OKFMemory {\n  addFacts: (facts: string[], scope: OKFMemoryScope) => Promise<unknown[]>;\n}\n\nexport function documentToFacts(doc: OKFDocument): string[] {\n  const facts: string[] = [];\n  const fm = doc.frontmatter;\n\n  const parts: string[] = [`[${fm.type}]`];\n  if (fm.title) parts.push(fm.title);\n  if (fm.description) parts.push(\"—\", fm.description);\n  if (fm.resource) parts.push(`(resource: ${fm.resource})`);\n  if (fm.tags?.length) parts.push(`tags: ${fm.tags.join(\", \")}`);\n\n  facts.push(parts.join(\" \"));\n\n  const body = doc.body.trim();\n  if (body) {\n    facts.push(`${fm.title ?? doc.relativePath} details: ${body}`);\n  }\n\n  return facts;\n}\n\nexport function bundleToFacts(bundle: OKFBundle): string[] {\n  return bundle.documents.flatMap(documentToFacts);\n}\n\nexport async function addFromBundle(\n  memory: OKFMemory,\n  bundle: OKFBundle,\n  scope: OKFMemoryScope = {},\n): Promise<unknown[]> {\n  const facts = bundleToFacts(bundle);\n  if (facts.length === 0) return [];\n  return memory.addFacts(facts, scope);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,92 @@
+interface OKFFrontmatter {
+    type: string;
+    title?: string;
+    description?: string;
+    resource?: string;
+    tags?: string[];
+    timestamp?: string;
+    [key: string]: unknown;
+}
+interface OKFDocument {
+    path: string;
+    relativePath: string;
+    frontmatter: OKFFrontmatter;
+    body: string;
+    links: OKFLink[];
+}
+interface OKFLink {
+    text: string;
+    href: string;
+    resolvedPath?: string;
+}
+interface OKFBundle {
+    root: string;
+    documents: OKFDocument[];
+    index: Map<string, OKFDocument>;
+}
+interface OKFNode {
+    document: OKFDocument;
+    outgoing: OKFEdge[];
+    incoming: OKFEdge[];
+}
+interface OKFEdge {
+    from: OKFDocument;
+    to: OKFDocument;
+    linkText: string;
+}
+interface OKFGraph {
+    nodes: Map<string, OKFNode>;
+    edges: OKFEdge[];
+}
+interface OKFValidationResult {
+    valid: boolean;
+    errors: OKFValidationError[];
+    warnings: OKFValidationWarning[];
+}
+interface OKFValidationError {
+    path: string;
+    message: string;
+    rule: string;
+}
+interface OKFValidationWarning {
+    path: string;
+    message: string;
+    rule: string;
+}
+interface ParseOptions {
+    ignore?: string[];
+    followLinks?: boolean;
+}
+interface WriteOptions {
+    overwrite?: boolean;
+}
+
+declare function parseDocument(filePath: string, bundleRoot: string, options?: ParseOptions): Promise<OKFDocument>;
+declare function parseBundle(rootDir: string, options?: ParseOptions): Promise<OKFBundle>;
+
+declare function validateDocument(doc: OKFDocument): {
+    errors: OKFValidationError[];
+    warnings: OKFValidationWarning[];
+};
+declare function validateBundle(bundle: OKFBundle): OKFValidationResult;
+
+declare function serializeDocument(frontmatter: OKFFrontmatter, body: string): string;
+declare function writeDocument(outputPath: string, frontmatter: OKFFrontmatter, body: string, options?: WriteOptions): Promise<void>;
+declare function writeIndex(dirPath: string, title: string, description: string, options?: WriteOptions): Promise<void>;
+
+declare function buildGraph(bundle: OKFBundle): OKFGraph;
+declare function reachableFrom(graph: OKFGraph, startRelativePath: string): string[];
+
+interface OKFMemoryScope {
+    userId?: string;
+    agentId?: string;
+    sessionId?: string;
+}
+interface OKFMemory {
+    addFacts: (facts: string[], scope: OKFMemoryScope) => Promise<unknown[]>;
+}
+declare function documentToFacts(doc: OKFDocument): string[];
+declare function bundleToFacts(bundle: OKFBundle): string[];
+declare function addFromBundle(memory: OKFMemory, bundle: OKFBundle, scope?: OKFMemoryScope): Promise<unknown[]>;
+
+export { type OKFBundle, type OKFDocument, type OKFEdge, type OKFFrontmatter, type OKFGraph, type OKFLink, type OKFMemory, type OKFMemoryScope, type OKFNode, type OKFValidationError, type OKFValidationResult, type OKFValidationWarning, type ParseOptions, type WriteOptions, addFromBundle, buildGraph, bundleToFacts, documentToFacts, parseBundle, parseDocument, reachableFrom, serializeDocument, validateBundle, validateDocument, writeDocument, writeIndex };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+interface OKFFrontmatter {
+    type: string;
+    title?: string;
+    description?: string;
+    resource?: string;
+    tags?: string[];
+    timestamp?: string;
+    [key: string]: unknown;
+}
+interface OKFDocument {
+    path: string;
+    relativePath: string;
+    frontmatter: OKFFrontmatter;
+    body: string;
+    links: OKFLink[];
+}
+interface OKFLink {
+    text: string;
+    href: string;
+    resolvedPath?: string;
+}
+interface OKFBundle {
+    root: string;
+    documents: OKFDocument[];
+    index: Map<string, OKFDocument>;
+}
+interface OKFNode {
+    document: OKFDocument;
+    outgoing: OKFEdge[];
+    incoming: OKFEdge[];
+}
+interface OKFEdge {
+    from: OKFDocument;
+    to: OKFDocument;
+    linkText: string;
+}
+interface OKFGraph {
+    nodes: Map<string, OKFNode>;
+    edges: OKFEdge[];
+}
+interface OKFValidationResult {
+    valid: boolean;
+    errors: OKFValidationError[];
+    warnings: OKFValidationWarning[];
+}
+interface OKFValidationError {
+    path: string;
+    message: string;
+    rule: string;
+}
+interface OKFValidationWarning {
+    path: string;
+    message: string;
+    rule: string;
+}
+interface ParseOptions {
+    ignore?: string[];
+    followLinks?: boolean;
+}
+interface WriteOptions {
+    overwrite?: boolean;
+}
+
+declare function parseDocument(filePath: string, bundleRoot: string, options?: ParseOptions): Promise<OKFDocument>;
+declare function parseBundle(rootDir: string, options?: ParseOptions): Promise<OKFBundle>;
+
+declare function validateDocument(doc: OKFDocument): {
+    errors: OKFValidationError[];
+    warnings: OKFValidationWarning[];
+};
+declare function validateBundle(bundle: OKFBundle): OKFValidationResult;
+
+declare function serializeDocument(frontmatter: OKFFrontmatter, body: string): string;
+declare function writeDocument(outputPath: string, frontmatter: OKFFrontmatter, body: string, options?: WriteOptions): Promise<void>;
+declare function writeIndex(dirPath: string, title: string, description: string, options?: WriteOptions): Promise<void>;
+
+declare function buildGraph(bundle: OKFBundle): OKFGraph;
+declare function reachableFrom(graph: OKFGraph, startRelativePath: string): string[];
+
+interface OKFMemoryScope {
+    userId?: string;
+    agentId?: string;
+    sessionId?: string;
+}
+interface OKFMemory {
+    addFacts: (facts: string[], scope: OKFMemoryScope) => Promise<unknown[]>;
+}
+declare function documentToFacts(doc: OKFDocument): string[];
+declare function bundleToFacts(bundle: OKFBundle): string[];
+declare function addFromBundle(memory: OKFMemory, bundle: OKFBundle, scope?: OKFMemoryScope): Promise<unknown[]>;
+
+export { type OKFBundle, type OKFDocument, type OKFEdge, type OKFFrontmatter, type OKFGraph, type OKFLink, type OKFMemory, type OKFMemoryScope, type OKFNode, type OKFValidationError, type OKFValidationResult, type OKFValidationWarning, type ParseOptions, type WriteOptions, addFromBundle, buildGraph, bundleToFacts, documentToFacts, parseBundle, parseDocument, reachableFrom, serializeDocument, validateBundle, validateDocument, writeDocument, writeIndex };