@hraness/wordcell 0.20.0 → 0.21.0

package/src/oh/authority.ts

@@ -0,0 +1,193 @@
+import { Database } from "bun:sqlite";
+import { isProxy } from "node:util/types";
+import { canonicalJson, canonicalSha256, type KnowledgeGraphChangeV1, type KnowledgeGraphRecordV1 } from "@hraness/oh";
+import {
+  createOhProjectionDatasetV1, createOhProjectionFactV1, createOhProjectionSnapshotV1,
+  evaluateOhProjectionV1, parseOhProjectionResultV1, type OhProjectionProofV1,
+} from "@hraness/oh/projection";
+import { createOhSqliteStoreAuthorityV1 } from "@hraness/oh/sqlite";
+import { createOhStoreProfileV1, OH_WORKING_STORE_PROFILE_V1, type OhStoreV1 } from "@hraness/oh/store";
+import {
+  GRAPH_LIMITS, GraphAuthorityError, type GraphAuthority, type GraphProof,
+  type GraphQueryLimits, type GraphQueryRequest, type GraphQueryResult, type GraphSnapshot,
+} from "../graph-authority-model";
+import { compileGraphProgram, normalizeGraphQueryRequest } from "./programs";
+import { GRAPH_EXTRACTOR_SHA256, GRAPH_MANIFEST_KEY, manifestGraphRecord, parseGraphSnapshot, sourceGraphRecord } from "./snapshot";
+import { deepFreeze, detachedData, exactKeys } from "./validation";
+import { validateOhCacheSchema } from "./schema";
+
+export type OhGraphAdapterOptions = Readonly<{
+  databasePath?: string;
+  databaseBytes?: Uint8Array;
+  writable?: boolean;
+}>;
+const MAXIMUM_CACHE_OPERATIONS = 1_024;
+
+function cacheError(error: unknown): GraphAuthorityError {
+  return error instanceof GraphAuthorityError ? error : new GraphAuthorityError("corrupt-cache", "The graph cache failed Oh integrity verification; rebuild it from Markdown.");
+}
+
+/** Paths identify coordinator-owned staging files. Read-only verification accepts bytes only. */
+export async function openOhGraphAdapter(input: GraphSnapshot, options: OhGraphAdapterOptions = {}): Promise<GraphAuthority> {
+  const snapshot = parseGraphSnapshot(input);
+  if (options === null || typeof options !== "object" || isProxy(options)
+    || (Object.getPrototypeOf(options) !== Object.prototype && Object.getPrototypeOf(options) !== null)
+    || Reflect.ownKeys(options).some(key => typeof key !== "string" || !Object.getOwnPropertyDescriptor(options, key)?.enumerable
+      || !("value" in Object.getOwnPropertyDescriptor(options, key)!))) throw new GraphAuthorityError("invalid-input", "Graph adapter options must be plain data fields.");
+  exactKeys(options as Record<string, unknown>, [], ["databasePath", "databaseBytes", "writable"]);
+  if ((options.databasePath !== undefined && options.databaseBytes !== undefined)
+    || (options.databasePath !== undefined && (typeof options.databasePath !== "string" || options.databasePath.length === 0 || options.writable !== true))
+    || (options.databaseBytes !== undefined && (!(options.databaseBytes instanceof Uint8Array) || options.databaseBytes.byteLength < 1 || options.databaseBytes.byteLength > GRAPH_LIMITS.sourceBytes || options.writable === true))
+    || (options.writable !== undefined && typeof options.writable !== "boolean")) throw new GraphAuthorityError("invalid-input", "Use writable staging paths or read-only cache bytes, never both.");
+  const readonly = options.databaseBytes !== undefined;
+  let records: KnowledgeGraphRecordV1[], expected: KnowledgeGraphRecordV1[];
+  try {
+    records = snapshot.records.map(sourceGraphRecord);
+    expected = [...records, manifestGraphRecord(snapshot)].sort((a, b) => a.key < b.key ? -1 : 1);
+  } catch (error) {
+    if (error instanceof RangeError) throw new GraphAuthorityError("budget", "A graph source record exceeds the Oh record byte limit.");
+    throw new GraphAuthorityError("invalid-input", "Graph source records are not valid Oh records.");
+  }
+  const profile = createOhStoreProfileV1({
+    applicationProfileSha256: canonicalSha256({ vaultIdentity: snapshot.vaultIdentity, extractorSha256: GRAPH_EXTRACTOR_SHA256 }),
+    capabilities: OH_WORKING_STORE_PROFILE_V1.capabilities,
+    profileId: "wordcell.graph.working.v1", profileKind: "working", v: 1,
+  });
+  const spaceId = "wordcell.graph";
+  let database: Database | undefined;
+  let store: OhStoreV1 | undefined;
+  let closed = false;
+  try {
+    database = readonly
+      ? Database.deserialize(new Uint8Array(options.databaseBytes!), { strict: true })
+      : new Database(options.databasePath ?? ":memory:", { create: true, strict: true });
+    database.exec("PRAGMA trusted_schema = OFF");
+    const hasSchema = validateOhCacheSchema(database);
+    if (hasSchema) {
+      const spaces = database.query<{ space_id: string }, []>("SELECT space_id FROM oh_spaces LIMIT 2").all();
+      const bindings = database.query<{ binding_json: string }, []>("SELECT binding_json FROM oh_space_bindings LIMIT 2").all();
+      if (spaces.length !== 1 || spaces[0]?.space_id !== spaceId || bindings.length !== 1) throw new GraphAuthorityError("corrupt-cache", "Graph cache does not contain one bound Wordcell space.");
+      const binding = JSON.parse(bindings[0]!.binding_json) as { profile?: { profileSha256?: unknown } };
+      if (binding.profile?.profileSha256 !== profile.profileSha256) throw new GraphAuthorityError("stale", "Graph cache belongs to a different vault or extractor profile.");
+      const count = database.query<{ count: number }, []>(`SELECT count(*) AS count FROM (SELECT 1 FROM oh_operations LIMIT ${MAXIMUM_CACHE_OPERATIONS + 1})`).get()?.count;
+      if (!Number.isSafeInteger(count) || count! > MAXIMUM_CACHE_OPERATIONS) throw new GraphAuthorityError("budget", "Graph cache history exceeds its replay bound; run graph rebuild --fresh.");
+    } else if (readonly) throw new GraphAuthorityError("corrupt-cache", "Graph cache has no Oh authority schema.");
+    database.exec("PRAGMA foreign_keys = ON; PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; PRAGMA busy_timeout = 5000");
+    store = createOhSqliteStoreAuthorityV1({ database, profile, realmId: `wordcell:${snapshot.vaultIdentity}`, spaceId }).store;
+    await store.verify();
+    const current = await store.snapshot({ maximumRecords: GRAPH_LIMITS.notes + 1 });
+    if (canonicalJson(current.records) !== canonicalJson(expected)) {
+      if (readonly) throw new GraphAuthorityError("stale", "Graph cache does not match the current Markdown snapshot.");
+      if (current.head.sequence >= MAXIMUM_CACHE_OPERATIONS) throw new GraphAuthorityError("budget", "Graph cache history is full; run graph rebuild --fresh.");
+      if (current.records.some(record => record.key !== GRAPH_MANIFEST_KEY && !/^edition:note\/[0-9a-f]{64}$/u.test(record.key))) throw new GraphAuthorityError("corrupt-cache", "Graph cache contains foreign records.");
+      const prior = new Map(current.records.map(record => [record.key, record]));
+      const next = new Map(expected.map(record => [record.key, record]));
+      const changes: KnowledgeGraphChangeV1[] = [];
+      for (const record of expected) if (prior.get(record.key)?.recordSha256 !== record.recordSha256) changes.push({ kind: "put", record, v: 1 });
+      for (const record of current.records) if (!next.has(record.key)) changes.push({ kind: "tombstone", key: record.key, priorSha256: record.recordSha256, v: 1 });
+      await store.commit({ actorId: "wordcell.graph", changes, expectedHead: current.head,
+        // Disposable projections use a fixed logical genesis instant, never wall-clock evidence.
+        // Persisted authorities retain real timestamps and their distinct operation history.
+        ...(options.databasePath === undefined ? { instant: "1970-01-01T00:00:00.000Z" } : {}),
+        operationId: `graph:${snapshot.revision}:${current.head.sequence}`, maximumOperationBytes: GRAPH_LIMITS.sourceBytes });
+    }
+    const selectedStore = store;
+    const materialized = await selectedStore.snapshot({ maximumRecords: GRAPH_LIMITS.notes + 1 });
+    if (canonicalJson(materialized.records) !== canonicalJson(expected)) throw new GraphAuthorityError("corrupt-cache", "Graph reconciliation did not retain exact source records.");
+    const projectionSnapshot = createOhProjectionSnapshotV1({ ...materialized, spaceId });
+    const recordMap = new Map(records.map((record, index) => [record.key, { record, source: snapshot.records[index]! }]));
+    const assertOpen = () => { if (closed) throw new GraphAuthorityError("closed", "The graph authority is closed."); };
+    const assertCurrent = async () => {
+      assertOpen();
+      if (canonicalJson(await selectedStore.head()) !== canonicalJson(materialized.head)) throw new GraphAuthorityError("stale", "Graph authority head changed after opening.");
+    };
+    function mapProof(proof: OhProjectionProofV1, budget: { remaining: number }): GraphProof {
+      const reserve = (value: unknown) => {
+        budget.remaining -= Buffer.byteLength(canonicalJson(value)) + 16;
+        if (budget.remaining < 0) throw new GraphAuthorityError("budget", "Graph proof source labels exceed the outward result byte limit.");
+      };
+      if (proof.kind === "truncated") {
+        const result = { kind: proof.kind, relation: proof.relation, tuple: proof.tuple, reason: proof.reason };
+        reserve(result); return result;
+      }
+      if (proof.kind === "derived") {
+        const result = { kind: proof.kind, relation: proof.relation, tuple: proof.tuple,
+          ruleId: proof.ruleId, ruleSha256: proof.ruleSha256, premisesTruncated: proof.premisesTruncated };
+        reserve(result);
+        return { ...result, premises: proof.premises.map(premise => mapProof(premise, budget)) };
+      }
+      const result = { kind: "fact" as const, relation: proof.relation, tuple: proof.tuple, sources: proof.sources.map(reference => {
+        const bound = recordMap.get(reference.key);
+        if (bound === undefined || bound.record.recordSha256 !== reference.recordSha256) throw new GraphAuthorityError("corrupt-cache", "Projection proof contains an unbound source record.");
+        return { key: reference.key, recordSha256: reference.recordSha256, noteId: bound.source.id,
+          path: bound.source.path, contentSha256: bound.source.contentSha256 };
+      }) };
+      reserve(result); return result;
+    }
+    async function query(value: GraphQueryRequest): Promise<GraphQueryResult> {
+      assertOpen();
+      const request = normalizeGraphQueryRequest(value);
+      await assertCurrent();
+      const limits = request.limits as Required<GraphQueryLimits>;
+      const program = compileGraphProgram(request);
+      const facts = snapshot.records.flatMap((source, index) => {
+        const record = records[index]!;
+        const sources = [{ key: record.key, recordSha256: record.recordSha256, v: 1 as const }];
+        const items = source.facts.map(fact => createOhProjectionFactV1({ ...fact, sources }));
+        if (request.program !== "scope-route" && source.id === request.note) items.push(createOhProjectionFactV1({ relation: "wordcell.selected", tuple: [source.id], sources }));
+        if ((request.program === "shared-tags" || request.program === "shared-concepts") && source.id !== request.note) items.push(createOhProjectionFactV1({ relation: "wordcell.peer", tuple: [source.id], sources }));
+        if (request.program === "shared-concepts" && !source.facts.some(fact => fact.relation === "wordcell.concept")) items.push(createOhProjectionFactV1({ relation: "wordcell.ordinary", tuple: [source.id], sources }));
+        return items;
+      });
+      try {
+        const dataset = createOhProjectionDatasetV1({ extractorSha256: GRAPH_EXTRACTOR_SHA256, factPackId: "wordcell.graph-facts", factPackRevision: 1, facts, snapshot: projectionSnapshot });
+        const result = evaluateOhProjectionV1({ ...program, dataset, snapshot: projectionSnapshot, options: {
+          maximumDerivedTuples: limits.derivedTuples, maximumRounds: limits.rounds, maximumWorkUnits: limits.workUnits,
+          maximumProofDepth: limits.proofDepth, maximumProofNodes: limits.proofNodes, maximumTotalProofNodes: limits.totalProofNodes, maximumResultBytes: limits.resultBytes,
+        } });
+        if (parseOhProjectionResultV1(result, result.identity.projectionSha256) === null) throw new GraphAuthorityError("corrupt-cache", "Oh returned an invalid bounded projection result.");
+        await assertCurrent();
+        const proofBudget = { remaining: limits.resultBytes };
+        const output: GraphQueryResult = { schemaVersion: 1, authority: "derived", vaultIdentity: snapshot.vaultIdentity,
+          revision: snapshot.revision, projectionSha256: result.identity.projectionSha256,
+          request, columns: program.columns, rows: result.rows.map(row => ({ values: row.values,
+            proofs: row.proofs.map(proof => mapProof(proof, proofBudget)), proofsTruncated: row.proofsTruncated, supportCount: row.supportCount })),
+          limits, truncated: result.stats.truncated, proofsTruncated: result.stats.proofsTruncated,
+          truncationReasons: result.stats.truncationReasons, stats: { baseFacts: result.stats.baseFacts,
+            derivedFacts: result.stats.derivedFacts, workUnits: result.stats.workUnits, rounds: result.stats.rounds,
+            proofNodes: result.stats.proofNodes, queryMatches: result.stats.queryMatches } };
+        if (Buffer.byteLength(canonicalJson(output)) > limits.resultBytes) throw new GraphAuthorityError("budget", "Graph result with source labels exceeds the outward result byte limit.");
+        return deepFreeze(output);
+      } catch (error) {
+        if (error instanceof GraphAuthorityError) throw error;
+        if (error instanceof RangeError) throw new GraphAuthorityError("budget", error.message);
+        throw error;
+      }
+    }
+    return Object.freeze({
+      query,
+      verifyResult: async (value: unknown) => {
+        assertOpen();
+        try {
+          const result = detachedData(value, GRAPH_LIMITS.resultBytes * 4) as GraphQueryResult;
+          if (result === null || typeof result !== "object" || Array.isArray(result)
+            || result.vaultIdentity !== snapshot.vaultIdentity || result.revision !== snapshot.revision) return false;
+          const verified = await query(result.request);
+          return canonicalJson(result) === canonicalJson(verified);
+        } catch { return false; }
+      },
+      verify: async () => {
+        await assertCurrent();
+        await selectedStore.verify();
+        const actual = await selectedStore.snapshot({ maximumRecords: GRAPH_LIMITS.notes + 1 });
+        if (canonicalJson(actual.records) !== canonicalJson(expected)) throw new GraphAuthorityError("corrupt-cache", "Graph cache differs from its exact snapshot.");
+        return deepFreeze({ schemaVersion: 1 as const, status: "verified" as const, vaultIdentity: snapshot.vaultIdentity,
+          revision: snapshot.revision, records: snapshot.records.length, facts: snapshot.factCount });
+      },
+      close: async () => { if (!closed) { closed = true; await selectedStore.close(); } },
+    });
+  } catch (error) {
+    try { if (store !== undefined) await store.close(); else database?.close(); } catch { /* preserve original failure */ }
+    throw cacheError(error);
+  }
+}

package/src/oh/programs.ts

@@ -0,0 +1,99 @@
+import {
+  createOhProjectionLiteralV1 as literal,
+  createOhProjectionQueryV1,
+  createOhProjectionRulePackV1,
+  createOhProjectionRuleV1,
+  ohProjectionConstantV1 as constant,
+  ohProjectionVariableV1 as variable,
+  type OhProjectionLiteralV1,
+  type OhProjectionRuleV1,
+  type OhProjectionTermV1,
+} from "@hraness/oh/projection";
+import { type GraphQueryLimits, type GraphQueryRequest } from "../graph-authority-model";
+import { validateGraphQueryRequest } from "../graph-query";
+import { detachedData } from "./validation";
+
+export const DEFAULT_GRAPH_QUERY_LIMITS: Required<GraphQueryLimits> = Object.freeze({
+  rows: 100, workUnits: 1_000_000, derivedTuples: 50_000, rounds: 32,
+  proofDepth: 32, proofNodes: 256, totalProofNodes: 8_192, resultBytes: 1_048_576,
+});
+
+/** Validate before scanning a vault or opening any storage. Returned requests include all defaults. */
+export function normalizeGraphQueryRequest(input: unknown): GraphQueryRequest {
+  const request = validateGraphQueryRequest(detachedData(input, 64 * 1024));
+  const depth = request.program === "reachability" || request.program === "relation-closure"
+    ? { depth: request.depth ?? 3 } : {};
+  return Object.freeze({ ...request, ...depth,
+    limits: Object.freeze({ ...DEFAULT_GRAPH_QUERY_LIMITS, ...request.limits }) });
+}
+
+const atom = (relation: string, ...terms: OhProjectionTermV1[]) => literal({ relation, terms });
+
+export function compileGraphProgram(request: GraphQueryRequest) {
+  const rules: OhProjectionRuleV1[] = [];
+  const add = (ruleId: string, head: OhProjectionLiteralV1, ...body: OhProjectionLiteralV1[]) => {
+    rules.push(createOhProjectionRuleV1({ ruleId: `wordcell.${ruleId}`, head, body }));
+  };
+  const a = variable("source"), b = variable("target"), line = variable("line"), predicate = variable("predicate");
+  let columns: string[];
+  let where: OhProjectionLiteralV1[];
+  switch (request.program) {
+    case "backlinks": {
+      add("backlink.link", atom("wordcell.answer", a, b, line, constant("link"), constant("")), atom("wordcell.link", a, b, line));
+      add("backlink.relation", atom("wordcell.answer", a, b, line, constant("relation"), predicate), atom("wordcell.relation", a, b, predicate, line));
+      columns = ["source", "target", "line", "kind", "predicate"];
+      where = [atom("wordcell.answer", a, b, line, variable("kind"), predicate), atom("wordcell.selected", b)];
+      break;
+    }
+    case "reachability":
+    case "relation-closure": {
+      const relation = request.program === "relation-closure";
+      const edge = "wordcell.edge";
+      if (relation) add("edge.relation", atom(edge, a, b), atom("wordcell.relation", a, b, constant(request.predicate), line));
+      else {
+        add("edge.link", atom(edge, a, b), atom("wordcell.link", a, b, line));
+        add("edge.relation", atom(edge, a, b), atom("wordcell.relation", a, b, predicate, line));
+      }
+      const source = constant(request.note);
+      // Positive walks of exact lengths 1..depth. Cycles may return the starting note,
+      // and a destination reached at different lengths produces one row per length.
+      add("walk.1", atom("wordcell.walk.1", b), atom(edge, source, b));
+      for (let depth = 1; depth <= (request.depth ?? 3); depth += 1) {
+        if (depth > 1) add(`walk.${depth}`, atom(`wordcell.walk.${depth}`, b), atom(`wordcell.walk.${depth - 1}`, a), atom(edge, a, b));
+        add(`walk.answer.${depth}`, atom("wordcell.answer", source, b, constant(depth)), atom(`wordcell.walk.${depth}`, b));
+      }
+      columns = ["source", "target", "depth"];
+      where = [atom("wordcell.answer", a, b, variable("depth"))];
+      break;
+    }
+    case "scope-route": {
+      add("scope", atom("wordcell.answer", a, constant(request.scope)), atom("wordcell.scope", a, constant(request.scope)));
+      columns = ["note", "scope"];
+      where = [atom("wordcell.answer", variable("note"), variable("scope"))];
+      break;
+    }
+    case "shared-tags": {
+      const note = variable("note"), other = variable("other"), tag = variable("tag");
+      add("shared.tags", atom("wordcell.answer", note, other, tag), atom("wordcell.selected", note), atom("wordcell.tag", note, tag), atom("wordcell.tag", other, tag), atom("wordcell.peer", other));
+      columns = ["note", "other", "tag"];
+      where = [atom("wordcell.answer", note, other, tag)];
+      break;
+    }
+    case "shared-concepts": {
+      const note = variable("note"), other = variable("other"), concept = variable("concept");
+      add("concept.link", atom("wordcell.concept-edge", a, b), atom("wordcell.link", a, b, line), atom("wordcell.concept", b));
+      add("concept.relation", atom("wordcell.concept-edge", a, b), atom("wordcell.relation", a, b, predicate, line), atom("wordcell.concept", b));
+      add("concept.reverse-link", atom("wordcell.concept-edge", a, b), atom("wordcell.link", b, a, line), atom("wordcell.concept", b));
+      add("concept.reverse-relation", atom("wordcell.concept-edge", a, b), atom("wordcell.relation", b, a, predicate, line), atom("wordcell.concept", b));
+      add("shared.concepts", atom("wordcell.answer", note, other, concept), atom("wordcell.selected", note), atom("wordcell.ordinary", note), atom("wordcell.concept-edge", note, concept), atom("wordcell.concept-edge", other, concept), atom("wordcell.peer", other), atom("wordcell.ordinary", other));
+      columns = ["note", "other", "concept"];
+      where = [atom("wordcell.answer", note, other, concept)];
+      break;
+    }
+  }
+  return {
+    columns,
+    query: createOhProjectionQueryV1({ queryId: `wordcell.${request.program}`, find: columns, where, limit: request.limits?.rows ?? DEFAULT_GRAPH_QUERY_LIMITS.rows }),
+    rulePack: createOhProjectionRulePackV1({ rulePackId: `wordcell.${request.program}`, rulePackRevision: 1, rules }),
+  };
+}

package/src/oh/schema.ts

@@ -0,0 +1,40 @@
+import { Database } from "bun:sqlite";
+import { canonicalJson } from "@hraness/oh";
+import { applyOhSqliteMigrations } from "@hraness/oh/sqlite";
+import { GraphAuthorityError } from "../graph-authority-model";
+
+type SchemaEntry = Readonly<{ type: string; name: string; tbl_name: string; sql: string | null;
+  nameLength: number; tableNameLength: number; sqlLength: number | null }>;
+const MAXIMUM_SCHEMA_ENTRIES = 256;
+const MAXIMUM_SCHEMA_SQL_LENGTH = 16_384;
+let expectedSchema: string | undefined;
+
+function schemaEntries(database: Database): SchemaEntry[] {
+  // Only SQLite's own catalog is read before its named objects are authenticated.
+  // Bound both the row count and text copied out of a potentially hostile cache.
+  const entries = database.query<SchemaEntry, []>(`SELECT type,
+    substr(name, 1, 257) AS name, length(name) AS nameLength,
+    substr(tbl_name, 1, 257) AS tbl_name, length(tbl_name) AS tableNameLength,
+    substr(sql, 1, ${MAXIMUM_SCHEMA_SQL_LENGTH + 1}) AS sql, length(sql) AS sqlLength
+    FROM main.sqlite_schema LIMIT ${MAXIMUM_SCHEMA_ENTRIES + 1}`).all();
+  if (entries.length > MAXIMUM_SCHEMA_ENTRIES || entries.some(entry => entry.nameLength > 256
+    || entry.tableNameLength > 256 || (entry.sqlLength ?? 0) > MAXIMUM_SCHEMA_SQL_LENGTH)) {
+    throw new GraphAuthorityError("corrupt-cache", "Graph cache schema exceeds its metadata bounds.");
+  }
+  return entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.type < b.type ? -1 : 1);
+}
+
+/** Reject altered tables, virtual tables, indexes, foreign views and triggers before any data query or migration. */
+export function validateOhCacheSchema(database: Database): boolean {
+  const entries = schemaEntries(database);
+  if (entries.length === 0) return false;
+  if (expectedSchema === undefined) {
+    const trusted = new Database(":memory:", { strict: true });
+    try {
+      applyOhSqliteMigrations(trusted);
+      expectedSchema = canonicalJson(schemaEntries(trusted));
+    } finally { trusted.close(); }
+  }
+  if (canonicalJson(entries) !== expectedSchema) throw new GraphAuthorityError("corrupt-cache", "Graph cache schema differs from the pinned Oh schema; rebuild it from Markdown.");
+  return true;
+}

package/src/oh/snapshot.ts

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { canonicalJson, canonicalSha256, createKnowledgeGraphRecordV1, type JsonValue } from "@hraness/oh";
+import { GRAPH_LIMITS, GraphAuthorityError, type GraphSnapshot, type GraphSourceRecord } from "../graph-authority-model";
+import { isCanonicalNoteId, isCanonicalRelationPredicate } from "../graph";
+import { validateRepositoryScopeSelection } from "../repository-memory";
+import { detachedData, exactKeys, deepFreeze } from "./validation";
+
+const digest = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{64}$/u.test(value);
+const fail = (message: string): never => { throw new GraphAuthorityError("invalid-input", message); };
+const nonempty = (value: unknown): value is string => typeof value === "string" && value.length > 0 && Buffer.byteLength(value) <= GRAPH_LIMITS.atomBytes;
+const path = (value: unknown): value is string => nonempty(value) && !value.startsWith("/") && !value.includes("\\") && !value.split("/").some(part => part === "" || part === "." || part === "..");
+
+export const GRAPH_EXTRACTOR_PROFILE = Object.freeze({
+  schemaVersion: 1,
+  id: "wordcell.graph-facts.v1",
+  relations: { note: ["id", "path", "title", "type"], link: ["source", "target", "line"],
+    relation: ["source", "target", "predicate", "line"], "external-relation": ["source", "uri", "predicate", "line"],
+    tag: ["id", "tag"], scope: ["id", "scope"], concept: ["id"] },
+  selectors: "selected is the requested note; peers are all other notes; ordinary excludes type concept; scope is an exact constant",
+  semantics: "positive walks of lengths 1..depth; shared concepts connect ordinary notes to concepts through explicit links or typed relations in either direction",
+});
+export const GRAPH_EXTRACTOR_SHA256 = canonicalSha256(GRAPH_EXTRACTOR_PROFILE);
+export const GRAPH_MANIFEST_KEY = "view:wordcell/manifest";
+
+export function parseGraphSnapshot(input: unknown): GraphSnapshot {
+  const snapshot = detachedData(input, GRAPH_LIMITS.sourceBytes) as GraphSnapshot;
+  if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) fail("Invalid graph snapshot.");
+  exactKeys(snapshot as unknown as Record<string, unknown>, ["schemaVersion", "vaultIdentity", "revision", "catalogNoteId", "sourceDigests", "records", "factCount"]);
+  if (snapshot.schemaVersion !== 1 || !digest(snapshot.vaultIdentity) || !digest(snapshot.revision) || !nonempty(snapshot.catalogNoteId)
+    || !Array.isArray(snapshot.records) || snapshot.records.length > GRAPH_LIMITS.notes || !Array.isArray(snapshot.sourceDigests)
+    || snapshot.sourceDigests.length > GRAPH_LIMITS.notes + 1 || !Number.isSafeInteger(snapshot.factCount)
+    || snapshot.factCount < 0 || snapshot.factCount > GRAPH_LIMITS.facts) fail("Invalid graph snapshot identity or bounds.");
+  const sourceDigests = new Map<string, string>();
+  let lastPath = "";
+  for (const source of snapshot.sourceDigests) {
+    if (source === null || typeof source !== "object" || Array.isArray(source)) fail("Invalid graph source digest.");
+    exactKeys(source as unknown as Record<string, unknown>, ["path", "contentSha256"]);
+    if (!path(source.path) || source.path <= lastPath || !digest(source.contentSha256)) fail("Graph source digests must be sorted unique paths and hashes.");
+    sourceDigests.set(source.path, source.contentSha256); lastPath = source.path;
+  }
+  const ids = new Set<string>(), paths = new Set<string>();
+  let lastKey = "", count = 0;
+  for (const record of snapshot.records) {
+    if (record === null || typeof record !== "object" || Array.isArray(record)) fail("Invalid graph source record.");
+    exactKeys(record as unknown as Record<string, unknown>, ["key", "id", "path", "documentId", "contentSha256", "facts"]);
+    if (!nonempty(record.id) || !isCanonicalNoteId(record.id) || record.path !== `${record.id}.md` || !path(record.path) || !digest(record.contentSha256)
+      || (record.documentId !== null && !nonempty(record.documentId)) || !Array.isArray(record.facts)
+      || ids.has(record.id) || paths.has(record.path) || record.id === snapshot.catalogNoteId) fail("Invalid or duplicated graph source identity.");
+    const identity = record.documentId === null ? `path:${record.id}` : `document:${record.documentId}`;
+    const expectedKey = `edition:note/${createHash("sha256").update(identity).digest("hex")}`;
+    if (record.key !== expectedKey || record.key <= lastKey || sourceDigests.get(record.path) !== record.contentSha256) fail("Graph source key, order or digest differs.");
+    lastKey = record.key; ids.add(record.id); paths.add(record.path);
+    let lastFact = "", noteFacts = 0;
+    for (const fact of record.facts) {
+      if (fact === null || typeof fact !== "object" || Array.isArray(fact)) fail("Invalid graph fact.");
+      exactKeys(fact as unknown as Record<string, unknown>, ["relation", "tuple"]);
+      if (!Array.isArray(fact.tuple) || fact.tuple[0] !== record.id) fail("Graph facts must belong to their source note.");
+      const key = canonicalJson([fact.relation, fact.tuple]);
+      if (key <= lastFact) fail("Graph facts must be sorted and unique.");
+      lastFact = key;
+      for (const value of fact.tuple) if (Buffer.byteLength(canonicalJson(value)) > GRAPH_LIMITS.atomBytes) fail("Graph atom exceeds its byte bound.");
+      const tuple = fact.tuple;
+      switch (fact.relation) {
+        case "wordcell.note":
+          if (tuple.length !== 4 || tuple[1] !== record.path || typeof tuple[2] !== "string" || typeof tuple[3] !== "string") fail("Invalid note fact.");
+          noteFacts += 1; break;
+        case "wordcell.link":
+          if (tuple.length !== 3 || !nonempty(tuple[1]) || !Number.isSafeInteger(tuple[2]) || (tuple[2] as number) < 0) fail("Invalid link fact.");
+          break;
+        case "wordcell.relation":
+        case "wordcell.external-relation":
+          if (tuple.length !== 4 || !nonempty(tuple[1]) || !nonempty(tuple[2]) || !Number.isSafeInteger(tuple[3]) || (tuple[3] as number) < 0) fail("Invalid relation fact.");
+          if (!isCanonicalRelationPredicate(tuple[2] as string)) fail("Invalid relation predicate.");
+          if (fact.relation === "wordcell.external-relation" && !(tuple[1] as string).startsWith("kb://")) fail("Invalid external relation target.");
+          break;
+        case "wordcell.tag":
+        case "wordcell.scope":
+          if (tuple.length !== 2 || !nonempty(tuple[1])) fail("Invalid tag or scope fact.");
+          if (fact.relation === "wordcell.scope") {
+            try { validateRepositoryScopeSelection([tuple[1] as string]); } catch { fail("Invalid repository scope fact."); }
+          }
+          break;
+        case "wordcell.concept":
+          if (tuple.length !== 1) fail("Invalid concept fact.");
+          break;
+        default: fail("Unknown graph fact relation.");
+      }
+      count += 1;
+      if (count > GRAPH_LIMITS.facts) fail("Graph fact count exceeds its limit.");
+    }
+    if (noteFacts !== 1) fail("Every graph record must contain exactly one note fact.");
+    const type = record.facts.find(fact => fact.relation === "wordcell.note")!.tuple[3];
+    if (record.facts.some(fact => fact.relation === "wordcell.concept") !== ((type as string).normalize("NFC").toLocaleLowerCase("en-US") === "concept")) fail("Concept facts must match authored note type.");
+  }
+  for (const record of snapshot.records) for (const fact of record.facts) {
+    if ((fact.relation === "wordcell.link" || fact.relation === "wordcell.relation") && !ids.has(fact.tuple[1] as string)) fail("Internal graph fact target is absent.");
+  }
+  if ([...sourceDigests.keys()].some(source => !paths.has(source) && source !== `${snapshot.catalogNoteId}.md`)) fail("Graph source inventory contains an unrepresented non-catalog note.");
+  if (count !== snapshot.factCount || canonicalSha256({ schemaVersion: 1, vaultIdentity: snapshot.vaultIdentity,
+    catalogNoteId: snapshot.catalogNoteId, sourceDigests: snapshot.sourceDigests, records: snapshot.records }) !== snapshot.revision) fail("Graph snapshot revision or fact count differs.");
+  return deepFreeze(snapshot);
+}
+
+export function sourceGraphRecord(record: GraphSourceRecord) {
+  return createKnowledgeGraphRecordV1({ key: record.key, kind: "edition", dependencies: [], v: 1,
+    value: JSON.parse(canonicalJson(record)) as JsonValue });
+}
+
+export function manifestGraphRecord(snapshot: GraphSnapshot) {
+  return createKnowledgeGraphRecordV1({ key: GRAPH_MANIFEST_KEY, kind: "view", dependencies: [], v: 1,
+    value: JSON.parse(canonicalJson({ schemaVersion: 1, vaultIdentity: snapshot.vaultIdentity, revision: snapshot.revision,
+      catalogNoteId: snapshot.catalogNoteId, sourceDigests: snapshot.sourceDigests,
+      records: snapshot.records.length, facts: snapshot.factCount, extractorSha256: GRAPH_EXTRACTOR_SHA256 })) as JsonValue });
+}

package/src/oh/validation.ts

@@ -0,0 +1,61 @@
+import { isProxy } from "node:util/types";
+import { canonicalJson } from "@hraness/oh";
+import { GraphAuthorityError } from "../graph-authority-model";
+
+/** Detach foreign data without invoking getters, prototypes, proxies or toJSON. */
+export function detachedData(input: unknown, maximumBytes: number): unknown {
+  const seen = new Set<object>();
+  let nodes = 0, bytes = 0;
+  function visit(value: unknown, depth: number): unknown {
+    nodes += 1;
+    if (nodes > 1_000_000 || depth > 192) throw new GraphAuthorityError("budget", "Graph input exceeds structural bounds.");
+    if (value === null || typeof value === "boolean") { bytes += 5; return value; }
+    if (typeof value === "string") {
+      bytes += Buffer.byteLength(value) + 2;
+      if (bytes > maximumBytes) throw new GraphAuthorityError("budget", "Graph input exceeds its byte bound.");
+      return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) { bytes += 32; return value; }
+    if (typeof value !== "object" || value === null || isProxy(value) || seen.has(value)) throw new GraphAuthorityError("invalid-input", "Graph input must be acyclic plain data.");
+    seen.add(value);
+    const array = Array.isArray(value);
+    if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new GraphAuthorityError("invalid-input", "Graph input must contain plain objects.");
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 200_000 || keys.some(key => typeof key !== "string")) throw new GraphAuthorityError("budget", "Graph input has too many fields.");
+    const output: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    if (array && keys.length !== value.length + 1) throw new GraphAuthorityError("invalid-input", "Graph arrays must be dense.");
+    for (const key of keys as string[]) {
+      if (array && key === "length") continue;
+      if (array && (!/^(0|[1-9][0-9]*)$/u.test(key) || Number(key) >= value.length)) throw new GraphAuthorityError("invalid-input", "Graph array has extra fields.");
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+      if (!descriptor.enumerable || !("value" in descriptor)) throw new GraphAuthorityError("invalid-input", "Graph input accessors are forbidden.");
+      bytes += Buffer.byteLength(key) + 4;
+      if (bytes > maximumBytes) throw new GraphAuthorityError("budget", "Graph input exceeds its byte bound.");
+      output[key] = visit(descriptor.value, depth + 1);
+    }
+    seen.delete(value);
+    return array ? Array.from({ length: (value as unknown[]).length }, (_, index) => output[String(index)]) : output;
+  }
+  const value = visit(input, 0);
+  try {
+    const encoded = canonicalJson(value);
+    if (Buffer.byteLength(encoded) > maximumBytes) throw new GraphAuthorityError("budget", "Graph input exceeds its canonical byte bound.");
+    return JSON.parse(encoded) as unknown;
+  } catch (error) {
+    if (error instanceof GraphAuthorityError) throw error;
+    throw new GraphAuthorityError("invalid-input", "Graph input is not canonical JSON data.");
+  }
+}
+
+export function exactKeys(value: Record<string, unknown>, required: readonly string[], optional: readonly string[] = []): void {
+  const keys = Object.keys(value);
+  if (required.some(key => !keys.includes(key)) || keys.some(key => !required.includes(key) && !optional.includes(key))) throw new GraphAuthorityError("invalid-input", "Graph input has missing or unexpected fields.");
+}
+
+export function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value)) deepFreeze(item);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/sdk.ts

@@ -2,6 +2,11 @@ import { resolve } from "node:path";
 
 import type { MetadataObject, Note } from "./graph.js";
 import { lookupNote } from "./graph.js";
+import { openGraphAuthority } from "./graph-authority.js";
+import type { GraphAuthority, GraphQueryRequest, GraphQueryResult } from "./graph-authority-model.js";
+import { validateGraphPercolationOptions, validateGraphQueryRequest } from "./graph-query.js";
+import { percolateWithGraph, type GraphPercolationResult } from "./graph-percolation.js";
+import type { PercolateOptions } from "./percolate.js";
 import {
   GitHistoryError,
   gitHistoryForNotes,
@@ -229,6 +234,9 @@ export type OpenKnowledgeBaseOptions = {
 };
 
 export type KnowledgeBaseDependencies = {
+  /** Read-only, in-memory graph authority over this session's single vault scan. */
+  readonly openGraphAuthority?: typeof openGraphAuthority;
+  readonly percolateWithGraph?: typeof percolateWithGraph;
   readonly scanVault?: typeof scanVault;
   readonly semantic?: SemanticDependencies;
   readonly openSemanticSearchSession?: typeof openSemanticSearchSession;
@@ -250,6 +258,12 @@ export type KnowledgeBaseSession = {
     note: string,
     options?: Omit<NavigateLinksOptions, "direction">,
   ) => LinkNeighborhood;
+  /** Bounded named graph programs, evaluated against this session's original snapshot. */
+  readonly graphQuery: (request: GraphQueryRequest) => Promise<GraphQueryResult>;
+  /** Verify evidence against the same snapshot and named program; never accepts a foreign revision. */
+  readonly graphVerifyResult: (value: unknown) => Promise<boolean>;
+  /** Source-scoped advisory suggestions with separate positive graph proofs. */
+  readonly percolateWithProofs: (options: PercolateOptions & Readonly<{ note: string }>) => Promise<GraphPercolationResult>;
   readonly search: (options: KnowledgeBaseSearchOptions) => Promise<KnowledgeBaseSearchResult>;
   readonly history: (
     noteIds: readonly string[],
@@ -524,10 +538,23 @@ export async function openKnowledgeBase(
     ? undefined
     : Promise.resolve(injectedSemantic);
   let gitPromise: Promise<GitHistoryIndexResult> | undefined;
+  let graphAuthorityPromise: Promise<GraphAuthority> | undefined;
+  let graphOperationTail: Promise<void> = Promise.resolve();
 
   const assertOpen = (): void => {
     if (closeRequested) throw new Error("Knowledge-base session is closed.");
   };
+  const withGraphOperation = <T>(operation: () => Promise<T>): Promise<T> => {
+    assertOpen();
+    const pending = graphOperationTail.then(operation);
+    graphOperationTail = pending.then(() => undefined, () => undefined);
+    return pending;
+  };
+  const withGraphAuthority = <T>(operation: (authority: GraphAuthority) => Promise<T>): Promise<T> =>
+    withGraphOperation(async () => {
+      graphAuthorityPromise ??= (dependencies.openGraphAuthority ?? openGraphAuthority)(snapshot);
+      return operation(await graphAuthorityPromise);
+    });
   const semantic = (): Promise<SemanticSearchSession> => {
     assertOpen();
     semanticPromise ??= (dependencies.openSemanticSearchSession
@@ -980,6 +1007,17 @@ export async function openKnowledgeBase(
       ...linkOptions,
       direction: "in",
     }),
+    graphQuery: async (request) => {
+      assertOpen();
+      const checked = validateGraphQueryRequest(request);
+      return withGraphAuthority((authority) => authority.query(checked));
+    },
+    graphVerifyResult: async (value) => withGraphAuthority((authority) => authority.verifyResult(value)),
+    percolateWithProofs: async (percolateOptions) => {
+      assertOpen();
+      const checked = validateGraphPercolationOptions(percolateOptions);
+      return withGraphOperation(() => (dependencies.percolateWithGraph ?? percolateWithGraph)(snapshot, checked));
+    },
     search,
     history: async (noteIds, historyOptions = {}) => {
       assertOpen();
@@ -1000,12 +1038,19 @@ export async function openKnowledgeBase(
     close: () => {
       if (closePromise !== undefined) return closePromise;
       closeRequested = true;
-      closePromise = semanticPromise === undefined
-        ? Promise.resolve()
-        : semanticPromise.then(
-            (session) => session.close(),
-            () => undefined,
-          );
+      closePromise = (async () => {
+        const semanticClose = semanticPromise === undefined
+          ? Promise.resolve()
+          : semanticPromise.then((session) => session.close(), () => undefined);
+        const graphClose = graphOperationTail.then(async () => {
+          await graphAuthorityPromise?.then((authority) => authority.close(), () => undefined);
+        });
+        const results = await Promise.allSettled([semanticClose, graphClose]);
+        const errors = results.filter((result): result is PromiseRejectedResult => result.status === "rejected")
+          .map((result) => result.reason as unknown);
+        if (errors.length === 1) throw errors[0];
+        if (errors.length > 1) throw new AggregateError(errors, "Knowledge-base stores could not close.");
+      })();
       return closePromise;
     },
   };