@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/scripts/lib/memory/query.js

@@ -0,0 +1,56 @@
+// Block write assertions (rule heads that modify a relation).
+const WRITE_ASSERTIONS = /(^|\s)(:put|:rm|:create|:replace|:ensure|:ensure_not)(\s|$)/;
+
+// All `::foo` system ops go through an allowlist. Anything not listed here —
+// including `::remove`, `::hnsw create|drop`, `::index create|drop`, `::fts …`,
+// `::kill` — is rejected. Add entries here after confirming they are
+// side-effect-free.
+const SYSTEM_OP = /(^|\s)(::[a-zA-Z_]+)/g;
+const ALLOWED_SYSTEM_OPS = new Set([
+  '::relations',
+  '::columns',
+  '::describe',
+  '::indices',
+  '::compact',
+  '::explain',
+  '::running',
+  '::show_triggers',
+]);
+
+function validateQuery(query) {
+  if (typeof query !== 'string') throw new Error('query must be a string');
+  if (WRITE_ASSERTIONS.test(query)) {
+    throw new Error('query is read-only; write assertions (:put, :rm, :create, etc.) are not permitted');
+  }
+  for (const m of query.matchAll(SYSTEM_OP)) {
+    const op = m[2];
+    if (!ALLOWED_SYSTEM_OPS.has(op)) {
+      throw new Error(`query is read-only; system op ${op} is not permitted (allowed: ${[...ALLOWED_SYSTEM_OPS].sort().join(', ')})`);
+    }
+  }
+}
+
+function formatResult(res) {
+  const headers = res.headers ?? [];
+  const rows = (res.rows ?? []).map((row) => {
+    const obj = {};
+    headers.forEach((h, i) => { obj[h] = row[i]; });
+    return obj;
+  });
+  return { headers, rows };
+}
+
+function errorMessage(err) {
+  return err?.display ?? err?.message ?? String(err);
+}
+
+export async function runQuery(store, query) {
+  validateQuery(query);
+  let res;
+  try {
+    res = await store.db.run(query);
+  } catch (err) {
+    throw new Error(`query error: ${errorMessage(err)}`, { cause: err });
+  }
+  return formatResult(res);
+}

package/dist/scripts/lib/memory/reads.js

@@ -0,0 +1,109 @@
+import { entRelName, edgeRelName, cozoStringLit as cozoLit } from './cozo.js';
+
+export async function getEntity(store, { type, name }) {
+  const rel = entRelName(type);
+  const res = await store.db.run(`?[v] := *${rel}{name: ${cozoLit(name)}, value: v}`);
+  if (res.rows.length === 0) return null;
+  return { type, name, value: res.rows[0][0] };
+}
+
+export async function listEntities(store, { type }) {
+  const rel = entRelName(type);
+  const res = await store.db.run(`?[n, v] := *${rel}{name: n, value: v}`);
+  return res.rows.map(([name, value]) => ({ type, name, value }));
+}
+
+function filterEdgeTypes(edge_types, vocabulary) {
+  if (edge_types && edge_types.length > 0) {
+    return edge_types.filter((t) => vocabulary.edges[t]);
+  }
+  return Object.keys(vocabulary.edges);
+}
+
+async function queryOutgoing(store, rel, et, node) {
+  const res = await store.db.run(
+    `?[tt, tn] := *${rel}{from_type: ${cozoLit(node.type)}, from_name: ${cozoLit(node.name)}, to_type: tt, to_name: tn}`,
+  );
+  return res.rows.map(([tt, tn]) => ({
+    edge: { edge_type: et, from_type: node.type, from_name: node.name, to_type: tt, to_name: tn },
+    target: { type: tt, name: tn },
+  }));
+}
+
+async function queryIncoming(store, rel, et, node) {
+  const res = await store.db.run(
+    `?[ft, fn] := *${rel}{from_type: ft, from_name: fn, to_type: ${cozoLit(node.type)}, to_name: ${cozoLit(node.name)}}`,
+  );
+  return res.rows.map(([ft, fn]) => ({
+    edge: { edge_type: et, from_type: ft, from_name: fn, to_type: node.type, to_name: node.name },
+    target: { type: ft, name: fn },
+  }));
+}
+
+async function processDepthLevel(store, frontier, edgeTypes, visited) {
+  const edgesOut = [];
+  const nextFrontier = new Map();
+
+  for (const et of edgeTypes) {
+    const rel = edgeRelName(et);
+    for (const [, node] of frontier) {
+      const outgoing = await queryOutgoing(store, rel, et, node);
+      const incoming = await queryIncoming(store, rel, et, node);
+
+      for (const result of [...outgoing, ...incoming]) {
+        edgesOut.push(result.edge);
+        const key = `${result.target.type}/${result.target.name}`;
+        if (!visited.has(key)) {
+          nextFrontier.set(key, result.target);
+        }
+      }
+    }
+  }
+
+  return { edgesOut, nextFrontier };
+}
+
+function deduplicateEdges(edgesOut) {
+  const edgeKey = (e) => [e.edge_type, e.from_type, e.from_name, e.to_type, e.to_name].join('\u0000');
+  const seen = new Set();
+  const edges = [];
+  for (const e of edgesOut) {
+    const k = edgeKey(e);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    edges.push(e);
+  }
+  return edges;
+}
+
+async function expandFrontier(store, frontier, edgeTypes, visited, edgesOut) {
+  const { edgesOut: levelEdges, nextFrontier } = await processDepthLevel(store, frontier, edgeTypes, visited);
+  edgesOut.push(...levelEdges);
+
+  for (const [key, node] of nextFrontier) {
+    const ent = await getEntity(store, node);
+    visited.set(key, ent ?? { ...node, value: null });
+  }
+
+  frontier.clear();
+  for (const [k, v] of nextFrontier) frontier.set(k, v);
+  return frontier.size > 0;
+}
+
+export async function neighbours(store, { type, name, depth = 1, edge_types }, vocabulary) {
+  const edgeTypes = filterEdgeTypes(edge_types, vocabulary);
+  const visited = new Map();
+  const edgesOut = [];
+  const frontier = new Map();
+  frontier.set(`${type}/${name}`, { type, name });
+
+  const start = await getEntity(store, { type, name });
+  visited.set(`${type}/${name}`, start ?? { type, name, value: null });
+
+  for (let d = 0; d < depth; d++) {
+    const hasMore = await expandFrontier(store, frontier, edgeTypes, visited, edgesOut);
+    if (!hasMore) break;
+  }
+
+  return { entities: [...visited.values()], edges: deduplicateEdges(edgesOut) };
+}

package/dist/scripts/lib/memory/schema.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { memoryPaths } from './paths.js';
+
+export function emptySchema() {
+  return { version: 1, entities: {}, edges: {}, embeddings: null };
+}
+
+function applyDefaults(parsed) {
+  return {
+    version: parsed.version ?? 1,
+    entities: parsed.entities ?? {},
+    edges: parsed.edges ?? {},
+    embeddings: parsed.embeddings ?? null,
+  };
+}
+
+export async function loadSchema(foundryDir, io) {
+  const p = memoryPaths(foundryDir);
+  if (!(await io.exists(p.schema))) return emptySchema();
+  const text = await io.readFile(p.schema);
+  return applyDefaults(JSON.parse(text));
+}
+
+function normaliseForWrite(schema) {
+  // Full deep canonicalisation: sorts keys at every level so nested objects
+  // (e.g. `entities.<type> = { frontmatterHash: ..., other: ... }`) also
+  // stabilise. Previously only top-level `entities` and `edges` keys were
+  // sorted, leaving any per-type record order dependent on insertion order —
+  // which produced meaningless diffs across runs.
+  return canonicalise({
+    version: schema.version,
+    entities: schema.entities,
+    edges: schema.edges,
+    embeddings: schema.embeddings,
+  });
+}
+
+export async function writeSchema(foundryDir, schema, io) {
+  const p = memoryPaths(foundryDir);
+  if (!(await io.exists(p.root))) await io.mkdir(p.root);
+  const out = normaliseForWrite(schema);
+  const text = JSON.stringify(out, null, 2) + '\n';
+  await io.writeFile(p.schema, text);
+}
+
+export function bumpVersion(schema) {
+  schema.version = (schema.version ?? 0) + 1;
+  return schema.version;
+}
+
+function canonicalise(value) {
+  if (Array.isArray(value)) return value.map(canonicalise);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = canonicalise(value[k]);
+    return out;
+  }
+  return value;
+}
+
+export function hashFrontmatter(fm) {
+  const canon = JSON.stringify(canonicalise(fm ?? {}));
+  return createHash('sha256').update(canon).digest('hex');
+}

package/dist/scripts/lib/memory/search.js

@@ -0,0 +1,73 @@
+import { entRelName } from './cozo.js';
+
+function asCozoVector(v) {
+  return `vec([${v.map((n) => Number(n).toString()).join(', ')}])`;
+}
+
+function isIndexNotFoundError(err) {
+  if (!err) return false;
+  const msg = String(err.display || err.message || err);
+  return /index|not found|no such|does not exist|stored relation/i.test(msg);
+}
+
+async function searchOneType(db, type, queryVec, k) {
+  const rel = entRelName(type);
+  try {
+    const q = `?[name, value, dist] := ~${rel}:vec{ name, value | query: ${asCozoVector(queryVec)}, k: ${k}, bind_distance: dist, ef: 64 }`;
+    const res = await db.run(q);
+    return res.rows.map(([name, value, dist]) => ({ type, name, value, distance: dist }));
+  } catch (err) {
+    if (isIndexNotFoundError(err)) return [];
+    throw err;
+  }
+}
+
+function resolveTypes(typeFilter, schema) {
+  if (typeFilter && typeFilter.length > 0) return typeFilter;
+  return Object.keys(schema.entities);
+}
+
+function validateSearchParams(embedder, queryText) {
+  if (!embedder) throw new Error('search requires an embedder');
+  if (typeof queryText !== 'string' || !queryText) throw new Error('query_text required');
+}
+
+/**
+ * Semantic nearest-neighbour search over entity values.
+ *
+ * Performance characteristics:
+ * - With N entity types and k requested results, this fetches k results from
+ *   each type (N×k vectors total), then returns the global top-k.
+ * - This is necessary to get semantically correct results when top matches are
+ *   distributed across multiple entity types.
+ * - Use `type_filter` to reduce N when you know which types are relevant,
+ *   limiting the amplification factor.
+ * - Example: 10 types, k=20, no filter → fetches 200 vectors, returns 20.
+ * - Example: 10 types, k=20, filter=['class', 'finding'] → fetches 40 vectors, returns 20.
+ *
+ * @param {object} params
+ * @param {object} params.store - Memory store with schema and db
+ * @param {string} params.query_text - Text to search for
+ * @param {number} [params.k=5] - Number of results to return
+ * @param {string[]} [params.type_filter] - Restrict search to specific entity types
+ * @param {Function} params.embedder - Function to embed query text
+ * @returns {Promise<Array<{type: string, name: string, value: string, distance: number}>>}
+ */
+export async function search({ store, query_text, k = 5, type_filter, embedder }) {
+  validateSearchParams(embedder, query_text);
+
+  const types = resolveTypes(type_filter, store.schema);
+  const [queryVec] = await embedder([query_text]);
+
+  // K-amplification: fetch k from each type to ensure global top-k correctness.
+  // With N types, this fetches N×k results. The alternative (fetching k/N per
+  // type) would miss results when top matches are unevenly distributed.
+  // Callers can use type_filter to reduce N when type relevance is known.
+  const all = [];
+  for (const t of types) {
+    const hits = await searchOneType(store.db, t, queryVec, k);
+    all.push(...hits);
+  }
+  all.sort((a, b) => a.distance - b.distance);
+  return all.slice(0, k);
+}

package/dist/scripts/lib/memory/singleton.js

@@ -0,0 +1,49 @@
+import { join } from 'node:path';
+import { loadMemoryConfig } from './config.js';
+import { loadSchema } from './schema.js';
+import { loadVocabulary } from './types.js';
+import { detectDrift } from './drift.js';
+import { openStore, closeStore } from './store.js';
+import { memoryPaths } from './paths.js';
+
+const stores = new Map(); // worktreeRoot -> { store, vocabulary, config, schema }
+
+export async function getOrOpenStore({ worktreeRoot, io }) {
+  if (stores.has(worktreeRoot)) return stores.get(worktreeRoot).store;
+
+  const config = await loadMemoryConfig('foundry', io);
+  if (!config.enabled) {
+    throw new Error('memory is not enabled in foundry/memory/config.md');
+  }
+  const schema = await loadSchema('foundry', io);
+  const vocabulary = await loadVocabulary('foundry', io);
+  const drift = detectDrift({ vocabulary, schema });
+  if (drift.hasDrift) {
+    const msg = drift.items
+      .map((d) => `  - [${d.typeFamily}] ${d.typeName}: ${d.message} → use skill: ${d.suggestedSkills.join(' or ')}`)
+      .join('\n');
+    throw new Error(`memory schema drift detected; refusing to open store:\n${msg}`);
+  }
+
+  const dbAbsolutePath = join(worktreeRoot, memoryPaths('foundry').db);
+  const store = await openStore({ foundryDir: 'foundry', schema, io, dbAbsolutePath });
+  stores.set(worktreeRoot, { store, vocabulary, config, schema });
+  return store;
+}
+
+export function getContext(worktreeRoot) {
+  return stores.get(worktreeRoot) ?? null;
+}
+
+export function disposeStores() {
+  for (const [, ctx] of stores) closeStore(ctx.store);
+  stores.clear();
+}
+
+export function invalidateStore(worktreeRoot) {
+  const ctx = stores.get(worktreeRoot);
+  if (ctx) {
+    try { closeStore(ctx.store); } catch { /* ignore */ }
+    stores.delete(worktreeRoot);
+  }
+}

package/dist/scripts/lib/memory/store.js

@@ -0,0 +1,162 @@
+import { memoryPaths } from './paths.js';
+import * as cozoModule from './cozo.js';
+import {
+  entRelName,
+  edgeRelName,
+  listRelations,
+  dropRelation,
+  dropHnswIndex,
+  cozoStringLit,
+  checkpoint,
+  closeMemoryDb,
+} from './cozo.js';
+import { serialiseEntityRows, serialiseEdgeRows, parseEntityRows, parseEdgeRows } from './ndjson.js';
+
+function vecLit(v) {
+  return `vec([${v.map((n) => Number(n).toString()).join(', ')}])`;
+}
+
+async function importRelation(db, relName, rows, kind) {
+  if (rows.length === 0) return;
+  if (kind === 'entity') {
+    // Partition by presence of embedding so the two column shapes are written
+    // with matching :put headers.
+    const withVec = rows.filter((r) => Array.isArray(r.embedding));
+    const plain = rows.filter((r) => !Array.isArray(r.embedding));
+    if (plain.length > 0) {
+      const data = plain.map((r) => `[${cozoStringLit(r.name)}, ${cozoStringLit(r.value)}]`).join(', ');
+      await db.run(`?[name, value] <- [${data}]\n:put ${relName} { name => value }`);
+    }
+    if (withVec.length > 0) {
+      const data = withVec
+        .map((r) => `[${cozoStringLit(r.name)}, ${cozoStringLit(r.value)}, ${vecLit(r.embedding)}]`)
+        .join(', ');
+      await db.run(`?[name, value, embedding] <- [${data}]\n:put ${relName} { name => value, embedding }`);
+    }
+  } else {
+    const data = rows.map((r) => `[${cozoStringLit(r.from_type)}, ${cozoStringLit(r.from_name)}, ${cozoStringLit(r.to_type)}, ${cozoStringLit(r.to_name)}]`).join(', ');
+    await db.run(`?[from_type, from_name, to_type, to_name] <- [${data}]\n:put ${relName} { from_type, from_name, to_type, to_name }`);
+  }
+}
+
+async function exportEntityRelation(db, type) {
+  const res = await db.run(`?[name, value, embedding] := *ent_${type}{name, value, embedding}`);
+  return res.rows.map(([name, value, embedding]) => {
+    const row = { name, value };
+    if (Array.isArray(embedding) && embedding.length > 0) row.embedding = embedding;
+    return row;
+  });
+}
+
+async function exportEdgeRelation(db, type) {
+  const res = await db.run(`?[ft, fn, tt, tn] := *edge_${type}{from_type: ft, from_name: fn, to_type: tt, to_name: tn}`);
+  return res.rows.map(([ft, fn, tt, tn]) => ({ from_type: ft, from_name: fn, to_type: tt, to_name: tn }));
+}
+
+async function ensureDirs(p, io) {
+  if (!(await io.exists(p.root))) await io.mkdir(p.root);
+  if (!(await io.exists(p.relationsDir))) await io.mkdir(p.relationsDir);
+}
+
+async function setupEntityTypes(db, { schema, embeddingsDim, paths: p, io, cozo }) {
+  for (const type of Object.keys(schema.entities)) {
+    await cozo.createEntityRelation(db, type, embeddingsDim ? { dim: embeddingsDim } : {});
+    if (embeddingsDim) {
+      await cozo.createHnswIndex(db, entRelName(type), { dim: embeddingsDim });
+    }
+    const file = p.relationFile(type);
+    if (await io.exists(file)) {
+      const text = await io.readFile(file);
+      const rows = parseEntityRows(text);
+      await importRelation(db, entRelName(type), rows, 'entity');
+    }
+  }
+}
+
+async function setupEdgeTypes(db, { schema, paths: p, io, cozo }) {
+  for (const type of Object.keys(schema.edges)) {
+    await cozo.createEdgeRelation(db, type);
+    const file = p.relationFile(type);
+    if (await io.exists(file)) {
+      const text = await io.readFile(file);
+      const rows = parseEdgeRows(text);
+      await importRelation(db, edgeRelName(type), rows, 'edge');
+    }
+  }
+}
+
+export async function openStore({ foundryDir, schema, io, dbAbsolutePath, cozo = cozoModule }) {
+  const p = memoryPaths(foundryDir);
+  await ensureDirs(p, io);
+
+  const db = cozo.openMemoryDb(dbAbsolutePath);
+
+  // Schema setup and NDJSON import can throw (disk error, corrupt NDJSON,
+  // Cozo parse error, etc). If anything after openMemoryDb fails, the handle
+  // is otherwise unreachable — close it before rethrowing so its native
+  // resources (file descriptors, WAL lock across processes) are released.
+  try {
+    // Reconcile the on-disk Cozo database with the declared schema. Admin
+    // operations (drop-*, rename-*) update the schema + type files + NDJSON on
+    // disk and invalidate the singleton, leaving the .db file outdated until
+    // reopen. On reopen, any `ent_<t>` or `edge_<t>` relation missing from
+    // `schema` is dropped so `::relations` stays consistent with the schema
+    // and disk footprint stays bounded.
+    await reconcileRelations(db, schema);
+
+    const embeddingsDim = schema.embeddings && schema.embeddings.dimensions;
+    await setupEntityTypes(db, { schema, embeddingsDim, paths: p, io, cozo });
+    await setupEdgeTypes(db, { schema, paths: p, io, cozo });
+  } catch (err) {
+    try {
+      cozo.closeMemoryDb(db);
+    } catch {
+      // Best-effort cleanup; propagate the original error.
+    }
+    throw err;
+  }
+
+  return { db, foundryDir, schema, paths: p };
+}
+
+async function dropUnexpectedRelation(db, rel, expected) {
+  if (!/^(ent|edge)_[^:]+$/.test(rel)) return;
+  if (expected.has(rel)) return;
+  if (rel.startsWith('ent_')) {
+    await dropHnswIndex(db, rel); // no-op if absent
+  }
+  await dropRelation(db, rel);
+}
+
+async function reconcileRelations(db, schema) {
+  const expected = new Set([
+    ...Object.keys(schema.entities).map(entRelName),
+    ...Object.keys(schema.edges).map(edgeRelName),
+  ]);
+  let existing;
+  try {
+    existing = await listRelations(db);
+  } catch {
+    return; // fresh db; ::relations may error before any :create.
+  }
+  for (const rel of existing) {
+    await dropUnexpectedRelation(db, rel, expected);
+  }
+}
+
+export async function syncStore({ store, io }) {
+  const { db, schema, paths: p } = store;
+  await checkpoint(db);
+  for (const type of Object.keys(schema.entities)) {
+    const rows = await exportEntityRelation(db, type);
+    await io.writeFile(p.relationFile(type), serialiseEntityRows(rows));
+  }
+  for (const type of Object.keys(schema.edges)) {
+    const rows = await exportEdgeRelation(db, type);
+    await io.writeFile(p.relationFile(type), serialiseEdgeRows(rows));
+  }
+}
+
+export function closeStore(store) {
+  closeMemoryDb(store.db);
+}

package/dist/scripts/lib/memory/types.js

@@ -0,0 +1,93 @@
+import { join, basename, extname } from 'node:path';
+import { memoryPaths } from './paths.js';
+import { parseFrontmatter } from './frontmatter.js';
+
+function splitFrontmatter(text, filename) {
+  const parsed = parseFrontmatter(text, { filename });
+  return { frontmatter: parsed.frontmatter, body: parsed.body.trim() };
+}
+
+function validateEntity(filename, parsed) {
+  const stem = basename(filename, extname(filename));
+  const fm = parsed.frontmatter;
+  if (!fm.type || typeof fm.type !== 'string') {
+    throw new Error(`entity type ${filename}: missing frontmatter 'type'`);
+  }
+  if (fm.type !== stem) {
+    throw new Error(`entity type ${filename}: frontmatter type '${fm.type}' does not match filename stem '${stem}'`);
+  }
+  if (!parsed.body) {
+    throw new Error(`entity type ${filename}: empty body is not allowed`);
+  }
+}
+
+function isNonEmptyStringArray(v) {
+  return Array.isArray(v) && v.length > 0 && v.every((s) => typeof s === 'string' && s);
+}
+
+function validateEdgeField(filename, key, value) {
+  if (value === undefined) throw new Error(`edge type ${filename}: missing frontmatter '${key}'`);
+  if (value === 'any') return;
+  if (!isNonEmptyStringArray(value)) {
+    throw new Error(`edge type ${filename}: '${key}' must be 'any' or a non-empty list of strings`);
+  }
+}
+
+function validateEdge(filename, parsed) {
+  const stem = basename(filename, extname(filename));
+  const fm = parsed.frontmatter;
+  if (!fm.type || typeof fm.type !== 'string') {
+    throw new Error(`edge type ${filename}: missing frontmatter 'type'`);
+  }
+  if (fm.type !== stem) {
+    throw new Error(`edge type ${filename}: frontmatter type '${fm.type}' does not match filename stem '${stem}'`);
+  }
+  validateEdgeField(filename, 'sources', fm.sources);
+  validateEdgeField(filename, 'targets', fm.targets);
+  if (!parsed.body) {
+    throw new Error(`edge type ${filename}: empty body is not allowed`);
+  }
+}
+
+async function loadDir(dir, io) {
+  if (!(await io.exists(dir))) return [];
+  const entries = await io.readDir(dir);
+  return entries.filter((e) => e.endsWith('.md') && e !== '.gitkeep').sort();
+}
+
+export async function loadVocabulary(foundryDir, io) {
+  const p = memoryPaths(foundryDir);
+  const vocab = { entities: {}, edges: {} };
+
+  for (const file of await loadDir(p.entitiesDir, io)) {
+    const fullPath = join(p.entitiesDir, file);
+    const text = await io.readFile(fullPath);
+    const parsed = splitFrontmatter(text, fullPath);
+    validateEntity(file, parsed);
+    const { type } = parsed.frontmatter;
+    vocab.entities[type] = {
+      type,
+      body: parsed.body,
+      frontmatter: parsed.frontmatter,
+      file: fullPath,
+    };
+  }
+
+  for (const file of await loadDir(p.edgesDir, io)) {
+    const fullPath = join(p.edgesDir, file);
+    const text = await io.readFile(fullPath);
+    const parsed = splitFrontmatter(text, fullPath);
+    validateEdge(file, parsed);
+    const { type, sources, targets } = parsed.frontmatter;
+    vocab.edges[type] = {
+      type,
+      sources,
+      targets,
+      body: parsed.body,
+      frontmatter: parsed.frontmatter,
+      file: fullPath,
+    };
+  }
+
+  return vocab;
+}

package/dist/scripts/lib/memory/validate.js

@@ -0,0 +1,58 @@
+export const MAX_VALUE_BYTES = 4096;
+
+// Names are the primary key, get embedded in NDJSON serialisation and Cozo
+// query literals, and appear in error messages. Reject newline, CR, tab, and
+// NUL so round-trips stay lossless and users can't craft names that would
+// split across lines in the relation files.
+const FORBIDDEN_CHARS = /[\n\r\t]/;
+
+function assertValidName(label, v) {
+  if (typeof v !== 'string' || v.length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  if (FORBIDDEN_CHARS.test(v) || v.includes('\0')) {
+    throw new Error(`${label} must not contain newline, carriage return, tab, or NUL`);
+  }
+}
+
+function byteLen(s) {
+  return Buffer.byteLength(s, 'utf8');
+}
+
+export function validateEntityWrite({ type, name, value }, vocabulary) {
+  if (!vocabulary.entities[type]) {
+    throw new Error(`entity type '${type}' is not declared`);
+  }
+  assertValidName('entity name', name);
+  if (typeof value !== 'string') {
+    throw new Error(`entity value must be a string`);
+  }
+  if (value.includes('\0')) {
+    throw new Error(`entity value must not contain NUL`);
+  }
+  if (byteLen(value) > MAX_VALUE_BYTES) {
+    throw new Error(`entity value is too large: ${byteLen(value)} bytes exceeds 4KB limit`);
+  }
+}
+
+function checkEdgeRole(entities, allowed, actualType, label, edgeType) {
+  if (allowed !== 'any') {
+    if (!entities[actualType]) {
+      throw new Error(`edge ${label} type '${actualType}' is not a declared entity type`);
+    }
+    if (!allowed.includes(actualType)) {
+      throw new Error(`edge '${edgeType}' does not permit ${label} type '${actualType}' (allowed: ${allowed.join(', ')})`);
+    }
+  }
+}
+
+export function validateEdgeWrite({ edge_type, from_type, from_name, to_type, to_name }, vocabulary) {
+  const edge = vocabulary.edges[edge_type];
+  if (!edge) {
+    throw new Error(`edge type '${edge_type}' is not declared`);
+  }
+  checkEdgeRole(vocabulary.entities, edge.sources, from_type, 'source', edge_type);
+  checkEdgeRole(vocabulary.entities, edge.targets, to_type, 'target', edge_type);
+  assertValidName('from_name', from_name);
+  assertValidName('to_name', to_name);
+}