@hraness/oh 0.2.3

package/src/cli.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const roots: string[] = [];
+const CLI_PATH = join(import.meta.dir, "cli.ts");
+const REPOSITORY_ROOT = join(import.meta.dir, "..");
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); });
+
+async function run(arguments_: readonly string[], cwd = REPOSITORY_ROOT): Promise<{ code: number; stderr: string; stdout: string }> {
+  const process_ = Bun.spawn([process.execPath, CLI_PATH, ...arguments_], { cwd,
+    stderr: "pipe", stdout: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([process_.exited,
+    new Response(process_.stdout).text(), new Response(process_.stderr).text()]);
+  return { code, stderr, stdout };
+}
+
+describe("oh CLI", () => {
+  test("initializes, writes, searches, and verifies one local database", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-test-"));
+    roots.push(root);
+    const database = join(root, "oh.sqlite");
+    expect(await run(["init", "--db", database])).toMatchObject({ code: 0, stderr: "" });
+    const put = await run(["put", "--db", database, "--kind", "entity", "--key", "entity:ada",
+      "--json", '{"name":"Ada Lovelace"}', "--operation", "op_cli"]);
+    expect(put.code).toBe(0);
+    expect(JSON.parse(put.stdout)).toMatchObject({ operationId: "op_cli", sequence: 1 });
+    const search = await run(["search", "Ada", "--db", database]);
+    expect(JSON.parse(search.stdout).results[0].record.key).toBe("entity:ada");
+    const verify = await run(["verify", "--db", database]);
+    expect(JSON.parse(verify.stdout)).toMatchObject({ operations: 1, records: 1, sqliteIntegrity: "ok" });
+  });
+
+  test("returns a distinct missing-record status", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-test-"));
+    roots.push(root);
+    const result = await run(["get", "entity:missing", "--db", join(root, "oh.sqlite")]);
+    expect(result.code).toBe(3);
+    expect(result.stdout).toBe("");
+  });
+
+  test("rejects malformed and command-invalid input before opening a database", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-invalid-test-"));
+    roots.push(root);
+    const database = join(root, "custom.sqlite");
+    const malformedJson = join(root, "malformed.json");
+    const malformedBundle = join(root, "malformed-bundle.json");
+    await writeFile(malformedJson, "not-json", "utf8");
+    await writeFile(malformedBundle, '{"v":1}', "utf8");
+    const invalidInvocations: readonly (readonly string[])[] = [
+      ["unknown"],
+      ["help", "extra"],
+      ["version", "--db", database],
+      ["init", "extra"],
+      ["init", "--dba", database],
+      ["init", "--db", ""],
+      ["init", "--db", database, "--spacee", "default"],
+      ["init", "--db", database, "--space", "bad space"],
+      ["get", "entity:ada", "--db", database, "--limit", "1"],
+      ["get", "entity:ada", "--db", database, "--db", database],
+      ["list", "--db", database, "--limit", "01"],
+      ["list", "--db", database, "--limit", "0"],
+      ["log", "--db", database, "--limit", "1001"],
+      ["search", "Ada", "--db", database, "--mode", "remote"],
+      ["search", "Ada", "--db", database, "--limit", "101"],
+      ["put", "--kind", "unknown", "--key", "entity:ada", "--json", "{}"],
+      ["put", "--kind", "entity", "--key", "bad key", "--json", "{}"],
+      ["put", "--kind", "entity", "--key", "entity:ada", "--json", "{}", "--file", malformedJson],
+      ["put", "--kind", "entity", "--key", "entity:ada", "--json", "not-json"],
+      ["put", "--kind", "entity", "--key", "entity:ada", "--file", malformedJson],
+      ["put", "--kind", "entity", "--key", "entity:ada", "--json", "{}", "--expected-generation", "+1"],
+      ["sync", "import", "--file", malformedBundle],
+      ["sync", "export", "--after", "-1"],
+      ["sync", "export", "--limit", "0"],
+    ];
+    for (const invocation of invalidInvocations) {
+      const result = await run(invocation, root);
+      expect(result.code, invocation.join(" ")).toBe(1);
+      expect(result.stderr, invocation.join(" ")).toStartWith("oh: ");
+      expect(result.stdout, invocation.join(" ")).toBe("");
+      expect(existsSync(join(root, ".oh")), invocation.join(" ")).toBe(false);
+      expect(existsSync(database), invocation.join(" ")).toBe(false);
+    }
+  });
+
+  test("serves the static contract without creating a default store", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-contract-test-"));
+    roots.push(root);
+    const database = join(root, "contract.sqlite");
+    const result = await run(["contract"], root);
+    expect(result.code).toBe(0);
+    expect(JSON.parse(result.stdout)).toMatchObject({
+      manifest: { contractId: "oh.ontology.v1" },
+      sqliteSchemaVersion: 2,
+      v: 1,
+    });
+    expect(existsSync(join(root, ".oh"))).toBe(false);
+    expect((await run(["contract", "--db", database, "--space", "contract.test"], root)).code).toBe(0);
+    expect(existsSync(database)).toBe(false);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,308 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+
+import { canonicalJson, opaqueId, safeCode, type JsonValue } from "./canonical";
+import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
+import { OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1, createKnowledgeGraphRecordV1,
+  type KnowledgeGraphRecordKindV1, type KnowledgeGraphRecordV1 } from "./graph";
+import { Oh } from "./sdk";
+import { OH_SQLITE_SCHEMA_VERSION } from "./sqlite/migrations";
+import { createOhSyncBundleV1, parseOhSyncBundleV1 } from "./sync";
+
+export const OH_PACKAGE_VERSION = "0.2.3" as const;
+
+type ParsedArguments = { options: Map<string, string[]>; positionals: string[] };
+type ValidatedInvocation = Readonly<{
+  databasePath: string;
+  putRecord: KnowledgeGraphRecordV1 | null;
+  spaceId: string;
+  syncBundle: NonNullable<ReturnType<typeof parseOhSyncBundleV1>> | null;
+}>;
+
+const KNOWN_OPTIONS = new Set([
+  "actor", "after", "db", "depends-on", "expected-generation", "file",
+  "json", "key", "kind", "limit", "mode", "operation", "space",
+]);
+const GLOBAL_OPTIONS = ["db", "space"] as const;
+const MUTATION_OPTIONS = ["actor", "expected-generation", "operation"] as const;
+
+function parseArguments(arguments_: readonly string[]): ParsedArguments {
+  const options = new Map<string, string[]>();
+  const positionals: string[] = [];
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index] as string;
+    if (!argument.startsWith("--")) {
+      if (argument.startsWith("-")) throw new TypeError(`Unknown option: ${argument}`);
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf("=");
+    const name = equals === -1 ? argument.slice(2) : argument.slice(2, equals);
+    const next = equals === -1 ? arguments_[index + 1] : argument.slice(equals + 1);
+    if (!KNOWN_OPTIONS.has(name)) throw new TypeError(`Unknown option: --${name}`);
+    if (next === undefined || next.length === 0 || (equals === -1 && next.startsWith("--"))) {
+      throw new TypeError(`Option --${name} needs a value.`);
+    }
+    if (equals === -1) index += 1;
+    const current = options.get(name) ?? [];
+    if (name !== "depends-on" && current.length !== 0) {
+      throw new TypeError(`Option --${name} may appear only once.`);
+    }
+    options.set(name, [...current, next]);
+  }
+  return { options, positionals };
+}
+
+function one(parsed: ParsedArguments, name: string, fallback?: string): string | undefined {
+  const values = parsed.options.get(name);
+  return values?.[0] ?? fallback;
+}
+
+function integer(value: string | undefined, name: string, minimum = 0,
+  maximum = Number.MAX_SAFE_INTEGER): number | undefined {
+  if (value === undefined) return undefined;
+  if (!/^(?:0|[1-9][0-9]*)$/u.test(value)) {
+    throw new TypeError(`--${name} must be a canonical integer from ${minimum} through ${maximum}.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new TypeError(`--${name} must be a canonical integer from ${minimum} through ${maximum}.`);
+  }
+  return parsed;
+}
+
+function assertAllowedOptions(parsed: ParsedArguments, allowed: readonly string[]): void {
+  const admitted = new Set(allowed);
+  for (const name of parsed.options.keys()) {
+    if (!admitted.has(name)) throw new TypeError(`Option --${name} is not valid for this command.`);
+  }
+}
+
+function assertPositionals(parsed: ParsedArguments, minimum: number, maximum = minimum): void {
+  if (parsed.positionals.length < minimum || parsed.positionals.length > maximum) {
+    throw new TypeError(`This command needs ${minimum === maximum ? String(minimum) : `${minimum} through ${maximum}`} positional argument${maximum === 1 ? "" : "s"}.`);
+  }
+}
+
+function parsedSafeCode(value: string | undefined, label: string, maximum = 128): string {
+  const parsed = safeCode(value, maximum);
+  if (parsed === null) throw new TypeError(`${label} is invalid.`);
+  return parsed;
+}
+
+function validateCommon(parsed: ParsedArguments): Pick<ValidatedInvocation, "databasePath" | "spaceId"> {
+  const databasePath = one(parsed, "db", ".oh/oh.sqlite") as string;
+  if (databasePath.length === 0 || databasePath.length > 4096 || databasePath.includes("\0")) {
+    throw new TypeError("--db is invalid.");
+  }
+  return { databasePath, spaceId: parsedSafeCode(one(parsed, "space", "default"), "--space") };
+}
+
+function validateMutation(parsed: ParsedArguments): void {
+  if (parsed.options.has("actor")) parsedSafeCode(one(parsed, "actor"), "--actor");
+  if (parsed.options.has("operation")) parsedSafeCode(one(parsed, "operation"), "--operation");
+  integer(one(parsed, "expected-generation"), "expected-generation");
+}
+
+async function validateInvocation(command: string, parsed: ParsedArguments): Promise<ValidatedInvocation> {
+  let putRecord: KnowledgeGraphRecordV1 | null = null;
+  let syncBundle: ValidatedInvocation["syncBundle"] = null;
+  if (command === "contract") {
+    assertAllowedOptions(parsed, GLOBAL_OPTIONS);
+    assertPositionals(parsed, 0);
+    return { ...validateCommon(parsed), putRecord, syncBundle };
+  }
+  if (command === "init" || command === "verify") {
+    assertAllowedOptions(parsed, GLOBAL_OPTIONS);
+    assertPositionals(parsed, 0);
+  } else if (command === "get") {
+    assertAllowedOptions(parsed, GLOBAL_OPTIONS);
+    assertPositionals(parsed, 1);
+    parsedSafeCode(parsed.positionals[0], "Record key", 512);
+  } else if (command === "list") {
+    assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "kind", "limit"]);
+    assertPositionals(parsed, 0);
+    const kind = one(parsed, "kind") as KnowledgeGraphRecordKindV1 | undefined;
+    if (kind !== undefined && !OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1.includes(kind)) {
+      throw new TypeError("Unknown record kind.");
+    }
+    integer(one(parsed, "limit"), "limit", 1, 1000);
+  } else if (command === "log") {
+    assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "limit"]);
+    assertPositionals(parsed, 0);
+    integer(one(parsed, "limit"), "limit", 1, 1000);
+  } else if (command === "search") {
+    assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "limit", "mode"]);
+    assertPositionals(parsed, 1, 1024);
+    const query = parsed.positionals.join(" ");
+    const mode = one(parsed, "mode", "keyword");
+    if (query.trim().length === 0 || query.length > 4096
+      || (mode !== "keyword" && mode !== "semantic" && mode !== "hybrid")) {
+      throw new TypeError("search needs a bounded query and a valid mode.");
+    }
+    integer(one(parsed, "limit"), "limit", 1, 100);
+  } else if (command === "put") {
+    assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, ...MUTATION_OPTIONS,
+      "depends-on", "file", "json", "key", "kind"]);
+    assertPositionals(parsed, 0);
+    validateMutation(parsed);
+    const key = parsedSafeCode(one(parsed, "key"), "--key", 512);
+    const kind = one(parsed, "kind") as KnowledgeGraphRecordKindV1 | undefined;
+    const inline = one(parsed, "json");
+    const file = one(parsed, "file");
+    if (kind === undefined || !OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1.includes(kind)
+      || (inline === undefined) === (file === undefined)) {
+      throw new TypeError("put needs --key, a valid --kind, and exactly one of --json or --file.");
+    }
+    const dependencies = (parsed.options.get("depends-on") ?? [])
+      .map((dependency) => parsedSafeCode(dependency, "--depends-on", 512)).sort();
+    const value = JSON.parse(inline ?? await readFile(file as string, "utf8")) as JsonValue;
+    putRecord = createKnowledgeGraphRecordV1({ dependencies, key, kind, v: 1, value });
+  } else if (command === "tombstone") {
+    assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, ...MUTATION_OPTIONS]);
+    assertPositionals(parsed, 1);
+    parsedSafeCode(parsed.positionals[0], "Record key", 512);
+    validateMutation(parsed);
+  } else if (command === "sync") {
+    assertPositionals(parsed, 1);
+    const action = parsed.positionals[0];
+    if (action === "export") {
+      assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "after", "limit"]);
+      integer(one(parsed, "after"), "after");
+      integer(one(parsed, "limit"), "limit", 1, 1000);
+    } else if (action === "import") {
+      assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "file"]);
+      const file = one(parsed, "file");
+      if (file === undefined) throw new TypeError("sync import needs --file.");
+      syncBundle = parseOhSyncBundleV1(JSON.parse(await readFile(file, "utf8")));
+      if (syncBundle === null) throw new TypeError("Invalid sync bundle.");
+    } else {
+      throw new TypeError("sync needs export or import.");
+    }
+  } else {
+    throw new TypeError(`Unknown command: ${command}`);
+  }
+  const common = validateCommon(parsed);
+  if (syncBundle !== null && syncBundle.spaceId !== common.spaceId) {
+    throw new TypeError("Invalid sync bundle.");
+  }
+  return { ...common, putRecord, syncBundle };
+}
+
+function print(value: unknown): void { process.stdout.write(`${canonicalJson(value)}\n`); }
+
+const HELP = `oh ${OH_PACKAGE_VERSION}
+
+Usage:
+  oh init [--db PATH] [--space ID]
+  oh put --kind KIND --key KEY (--json JSON | --file PATH) [--depends-on KEY]
+  oh get KEY
+  oh list [--kind KIND] [--limit N]
+  oh log [--limit N]
+  oh search QUERY [--mode keyword|semantic|hybrid] [--limit N]
+  oh tombstone KEY
+  oh verify
+  oh sync export [--after N] [--limit N]
+  oh sync import --file PATH
+  oh contract
+  oh version
+
+Global options: --db PATH (default .oh/oh.sqlite), --space ID (default default)
+Mutation options: --actor ID, --operation ID, --expected-generation N
+`;
+
+export async function runOhCli(arguments_: readonly string[]): Promise<number> {
+  const command = arguments_[0];
+  if (command === undefined || command === "help" || command === "--help") {
+    if (arguments_.length > 1) throw new TypeError("help does not accept arguments or options.");
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (command === "version" || command === "--version") {
+    if (arguments_.length !== 1) throw new TypeError("version does not accept arguments or options.");
+    process.stdout.write(`${OH_PACKAGE_VERSION}\n`);
+    return 0;
+  }
+  const parsed = parseArguments(arguments_.slice(1));
+  const validated = await validateInvocation(command, parsed);
+  if (command === "contract") {
+    print({ manifest: OH_CONTRACT_MANIFEST_V1, sqliteSchemaVersion: OH_SQLITE_SCHEMA_VERSION, v: 1 });
+    return 0;
+  }
+  const oh = Oh.open({ databasePath: validated.databasePath, spaceId: validated.spaceId });
+  try {
+    if (command === "init") { print({ head: oh.head(), spaceId: oh.store.spaceId, v: 1 }); return 0; }
+    if (command === "put") {
+      const record = validated.putRecord;
+      if (record === null) throw new TypeError("Invalid prepared put command.");
+      const head = oh.head();
+      const expectedGeneration = integer(one(parsed, "expected-generation"), "expected-generation");
+      const operation = oh.store.commit({ actorId: one(parsed, "actor", "agent.local") as string,
+        changes: [{ kind: "put", record, v: 1 }], expectedHead: { generation: expectedGeneration ?? head.generation,
+          operationSha256: head.operationSha256 }, operationId: one(parsed, "operation") ?? opaqueId("op_") });
+      print(operation); return 0;
+    }
+    if (command === "tombstone") {
+      const key = parsed.positionals[0];
+      if (key === undefined || parsed.positionals.length !== 1) throw new TypeError("tombstone needs one record key.");
+      const head = oh.head();
+      const expectedGeneration = integer(one(parsed, "expected-generation"), "expected-generation");
+      const record = oh.get(key);
+      if (record === null) return 3;
+      const operation = oh.store.commit({ actorId: one(parsed, "actor", "agent.local") as string,
+        changes: [{ key, kind: "tombstone", priorSha256: record.recordSha256, v: 1 }],
+        expectedHead: { generation: expectedGeneration ?? head.generation, operationSha256: head.operationSha256 },
+        operationId: one(parsed, "operation") ?? opaqueId("op_") });
+      print(operation); return 0;
+    }
+    if (command === "get") {
+      const key = parsed.positionals[0];
+      if (key === undefined || parsed.positionals.length !== 1) throw new TypeError("get needs one record key.");
+      const record = oh.get(key);
+      if (record === null) return 3;
+      print(record); return 0;
+    }
+    if (command === "list") {
+      const kind = one(parsed, "kind") as KnowledgeGraphRecordKindV1 | undefined;
+      if (kind !== undefined && !OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1.includes(kind)) throw new TypeError("Unknown record kind.");
+      const limit = integer(one(parsed, "limit"), "limit");
+      print({ records: oh.list({ ...(kind === undefined ? {} : { kind }), ...(limit === undefined ? {} : { limit }) }), v: 1 });
+      return 0;
+    }
+    if (command === "log") { print({ operations: oh.store.log(integer(one(parsed, "limit"), "limit")), v: 1 }); return 0; }
+    if (command === "search") {
+      const query = parsed.positionals.join(" ");
+      const mode = one(parsed, "mode", "keyword");
+      if (query.length === 0 || (mode !== "keyword" && mode !== "semantic" && mode !== "hybrid")) throw new TypeError("search needs a query and a valid mode.");
+      const limit = integer(one(parsed, "limit"), "limit");
+      print(await oh.search(query, { ...(limit === undefined ? {} : { limit }), mode })); return 0;
+    }
+    if (command === "verify") { print(oh.verify()); return 0; }
+    if (command === "sync") {
+      const action = parsed.positionals[0];
+      if (action === "export") {
+        const after = integer(one(parsed, "after"), "after") ?? 0;
+        const limit = integer(one(parsed, "limit"), "limit") ?? 1000;
+        print(createOhSyncBundleV1(oh.store.spaceId, oh.store.exportOperations(after, limit))); return 0;
+      }
+      if (action === "import") {
+        const bundle = validated.syncBundle;
+        if (bundle === null) throw new TypeError("Invalid prepared sync import command.");
+        let imported = 0;
+        for (const operation of bundle.operations) if (oh.store.importOperation(operation).imported) imported += 1;
+        print({ head: oh.head(), imported, v: 1 }); return 0;
+      }
+      throw new TypeError("sync needs export or import.");
+    }
+    throw new TypeError(`Unknown command: ${command}`);
+  } finally {
+    await oh.close();
+  }
+}
+
+if (import.meta.main) {
+  runOhCli(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => {
+    process.stderr.write(`oh: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/contract.ts

@@ -0,0 +1,87 @@
+import { canonicalJson, canonicalSha256, type JsonValue, type Sha256Hex } from "./canonical";
+import { OH_GRAPH_FORMAT_VERSION_V1, OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1,
+  type KnowledgeGraphRecordKindV1 } from "./graph";
+import { OH_CONTRACT_ID_V1, OH_ONTOLOGY_VERSION_V1 } from "./ontology";
+import { OH_SCHEMA_FORMAT_VERSION_V1 } from "./schema";
+
+export type OhContractManifestV1 = Readonly<{
+  contractId: typeof OH_CONTRACT_ID_V1;
+  contractSha256: Sha256Hex;
+  graphFormatVersion: typeof OH_GRAPH_FORMAT_VERSION_V1;
+  ontologyVersion: typeof OH_ONTOLOGY_VERSION_V1;
+  recordKinds: readonly KnowledgeGraphRecordKindV1[];
+  schemaFormatVersion: typeof OH_SCHEMA_FORMAT_VERSION_V1;
+  v: 1;
+}>;
+
+const manifestPayload = Object.freeze({
+  contractId: OH_CONTRACT_ID_V1,
+  graphFormatVersion: OH_GRAPH_FORMAT_VERSION_V1,
+  ontologyVersion: OH_ONTOLOGY_VERSION_V1,
+  recordKinds: OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1,
+  schemaFormatVersion: OH_SCHEMA_FORMAT_VERSION_V1,
+  v: 1 as const,
+});
+
+export const OH_CONTRACT_MANIFEST_V1: OhContractManifestV1 = Object.freeze({
+  ...manifestPayload,
+  contractSha256: canonicalSha256(manifestPayload),
+});
+
+/** Accepts only the complete, byte-equivalent V1 contract manifest. */
+export function parseOhContractManifestV1(value: unknown): OhContractManifestV1 | null {
+  try {
+    return canonicalJson(value) === canonicalJson(OH_CONTRACT_MANIFEST_V1)
+      ? OH_CONTRACT_MANIFEST_V1 : null;
+  } catch { return null; }
+}
+
+export type OhRecordCodec<T extends JsonValue = JsonValue> = Readonly<{
+  kind: KnowledgeGraphRecordKindV1;
+  parse(value: unknown): T | null;
+}>;
+
+/** Optional semantic validation layered over the immutable generic record envelope. */
+export class OhRecordCodecRegistry {
+  readonly #codecs = new Map<KnowledgeGraphRecordKindV1, OhRecordCodec>();
+  #sealed = false;
+
+  register(codec: OhRecordCodec): this {
+    if (this.#sealed) throw new TypeError("The codec registry is sealed.");
+    if (this.#codecs.has(codec.kind)) throw new TypeError(`A codec is already registered for ${codec.kind}.`);
+    this.#codecs.set(codec.kind, Object.freeze({ kind: codec.kind, parse: codec.parse }));
+    return this;
+  }
+
+  parse(kind: KnowledgeGraphRecordKindV1, value: unknown): JsonValue | null {
+    const codec = this.#codecs.get(kind);
+    if (codec !== undefined) return codec.parse(value);
+    try { canonicalJson(value); return value as JsonValue; } catch { return null; }
+  }
+
+  has(kind: KnowledgeGraphRecordKindV1): boolean {
+    return this.#codecs.has(kind);
+  }
+
+  /** Parses only through an explicitly registered codec. */
+  parseRequired(kind: KnowledgeGraphRecordKindV1, value: unknown): JsonValue | null {
+    const codec = this.#codecs.get(kind);
+    if (codec === undefined) return null;
+    try {
+      const parsed = codec.parse(value);
+      if (parsed === null) return null;
+      canonicalJson(parsed);
+      return parsed;
+    } catch { return null; }
+  }
+
+  /** Prevents the validation policy from changing after an ingress is created. */
+  seal(): this {
+    this.#sealed = true;
+    return this;
+  }
+
+  get sealed(): boolean {
+    return this.#sealed;
+  }
+}

package/src/contracts.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, test } from "bun:test";
+
+import { canonicalJson, type JsonObject, type Sha256Hex } from "./canonical";
+import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
+import { createKnowledgeGraphRecordV1, createKnowledgeGraphRevisionV1,
+  graphRevisionSha256V1, OH_GRAPH_LIMITS_V1, parseKnowledgeGraphRecordV1,
+  parseKnowledgeGraphRevisionV1, reduceKnowledgeGraphRevisionsV1 } from "./graph";
+import { createKnowledgeActivityV1, createKnowledgeAssertionV1, createKnowledgeContextV1,
+  createKnowledgeEvidenceLinkV1, createKnowledgeInquiryV1, createKnowledgeStatementV1,
+  parseKnowledgeAssertionV1, parseKnowledgeEntityV1, parseKnowledgeEvidenceLinkV1,
+  parseKnowledgeStatementV1, type KnowledgeAssertionId, type KnowledgeEntityId,
+  type KnowledgeEvidenceId, type KnowledgeInquiryId,
+  type KnowledgeSchemaRefV1 } from "./ontology";
+import { createKnowledgeSchemaRevisionV1, createKnowledgeVocabularyRevisionV1,
+  knowledgeSchemaRefV1, parseKnowledgeSchemaRevisionV1, verifyKnowledgeSchemaEvolutionV1 } from "./schema";
+
+const digest = "a".repeat(64) as Sha256Hex;
+const entityId = `kent_${"1".repeat(24)}` as KnowledgeEntityId;
+const authorId = `kent_${"2".repeat(24)}` as KnowledgeEntityId;
+const schemaRef: KnowledgeSchemaRefV1 = { code: "name", namespace: "oh.core", revision: 1,
+  schemaSha256: digest, v: 1 };
+
+describe("ontology contracts", () => {
+  test("creates content-addressed contexts, statements, and inquiries", () => {
+    const context = createKnowledgeContextV1({ dimensions: [], scenario: "actual", v: 1 });
+    expect(context.ok).toBe(true);
+    const statement = createKnowledgeStatementV1({ object: { kind: "text", language: "en", text: "Ada", v: 1 },
+      predicate: schemaRef, qualifiers: [], subject: entityId, v: 1 });
+    expect(statement.ok).toBe(true);
+    if (!statement.ok) return;
+    expect(parseKnowledgeStatementV1(statement.value)).toEqual({ ok: true, value: statement.value });
+    expect(parseKnowledgeStatementV1({ ...statement.value, subject: authorId })).toMatchObject({ ok: false });
+    const inquiry = createKnowledgeInquiryV1({ answerForm: "narrative", authorEntityId: authorId,
+      contextSha256: context.ok ? context.value.contextSha256 : null,
+      createdAt: "2026-08-27T12:00:00.000Z", inquiryId: `kinq_${"3".repeat(24)}` as KnowledgeInquiryId,
+      language: "en", parentInquiryIds: [], privacy: "public", question: "What changed?",
+      status: "open", v: 1 });
+    expect(inquiry.ok).toBe(true);
+  });
+
+  test("requires canonical set ordering", () => {
+    const statement = createKnowledgeStatementV1({ object: { kind: "set", v: 1, values: [
+      { kind: "string", v: 1, value: "z" }, { kind: "string", v: 1, value: "a" },
+    ] }, predicate: schemaRef, qualifiers: [], subject: entityId, v: 1 });
+    expect(statement).toMatchObject({ ok: false });
+    expect(createKnowledgeStatementV1({ object: { canonicalizerSha256: digest,
+      canonicalValue: "canonical extension bytes", kind: "extension", mediaType: "application/json",
+      schema: schemaRef, v: 1, valueSha256: digest }, predicate: schemaRef, qualifiers: [],
+      subject: entityId, v: 1 })).toMatchObject({ ok: false, error: { code: "digest-mismatch" } });
+  });
+
+  test("preserves entity, activity, assertion, and evidence authority laws", () => {
+    expect(parseKnowledgeEntityV1({ entityId, identityOperationId: "identity.create",
+      identityRevision: 1, redirectEntityId: null, state: "active", v: 1 })).toMatchObject({ ok: true });
+    expect(parseKnowledgeEntityV1({ entityId, identityOperationId: "identity.redirect",
+      identityRevision: 2, redirectEntityId: null, state: "redirected", v: 1 })).toMatchObject({ ok: false });
+    const activity = createKnowledgeActivityV1({ actor: { entityId: authorId, kind: "entity", v: 1 },
+      inputSha256s: [], kind: "human-entry", occurredAt: "2026-08-27T12:00:00.000Z",
+      outputSha256s: [], policySha256: digest, tool: null, v: 1 });
+    expect(activity.ok).toBe(true);
+    const assertion = createKnowledgeAssertionV1({ acceptedPurposes: [],
+      assertionId: `kast_${"4".repeat(24)}` as KnowledgeAssertionId,
+      assertor: { kind: "model", model: schemaRef, receiptSha256: digest, v: 1 }, confidence: null,
+      contextSha256: null, provenanceActivitySha256: activity.ok ? activity.value.activitySha256 : digest,
+      reviewActivitySha256: null, stance: "reports", state: "proposed", statementSha256: digest, v: 1 });
+    expect(assertion.ok).toBe(true);
+    if (!assertion.ok) return;
+    expect(parseKnowledgeAssertionV1(assertion.value)).toEqual({ ok: true, value: assertion.value });
+    const { assertionSha256: _assertionSha256, ...assertionInput } = assertion.value;
+    expect(createKnowledgeAssertionV1({ ...assertionInput, acceptedPurposes: ["publication"],
+      state: "accepted-for-purpose" })).toMatchObject({ ok: false });
+    const evidence = createKnowledgeEvidenceLinkV1({ assertionSha256: assertion.value.assertionSha256,
+      bearing: "supports", disclosure: "public", evidenceId: `kevd_${"5".repeat(24)}` as KnowledgeEvidenceId,
+      observationSha256: digest, provenanceActivitySha256: activity.ok ? activity.value.activitySha256 : digest,
+      selector: "paragraph:1", sourceEntityId: null, v: 1 });
+    expect(evidence.ok).toBe(true);
+    if (evidence.ok) {
+      expect(parseKnowledgeEvidenceLinkV1({ ...evidence.value, bearing: "contradicts" })).toMatchObject({ ok: false });
+    }
+  });
+});
+
+describe("schema evolution", () => {
+  const localized = [{ language: "en", text: "Name", v: 1 as const }];
+  const revision = (revision: number, body: JsonObject, prior: Sha256Hex | null, compatibility: "additive" | "breaking") =>
+    createKnowledgeSchemaRevisionV1({ body, code: "person", compatibility, description: localized,
+      kind: "concept", labels: localized, namespace: "oh.core", previousSchemaSha256: prior, revision, v: 1 });
+
+  test("chains revisions and rejects a false additive claim", () => {
+    const first = revision(1, { required: ["name"] }, null, "additive");
+    const second = revision(2, { optional: ["url"], required: ["name"] }, first.schemaSha256, "additive");
+    expect(parseKnowledgeSchemaRevisionV1(first)).toEqual(first);
+    expect(verifyKnowledgeSchemaEvolutionV1(first, second)).toEqual({ ok: true });
+    const falseAdditive = revision(2, { required: [] }, first.schemaSha256, "additive");
+    expect(verifyKnowledgeSchemaEvolutionV1(first, falseAdditive)).toEqual({ ok: false, reason: "false-additive-claim" });
+  });
+
+  test("builds ordered vocabulary manifests", () => {
+    const first = revision(1, { type: "object" }, null, "additive");
+    const ref = knowledgeSchemaRefV1(first);
+    const vocabulary = createKnowledgeVocabularyRevisionV1({ namespace: "oh.core", revision: 1,
+      schemaRefs: [ref], v: 1 });
+    expect(vocabulary.schemaRefs).toEqual([ref]);
+  });
+});
+
+describe("graph contracts", () => {
+  test("addresses records and deterministically reduces revisions", () => {
+    const entity = createKnowledgeGraphRecordV1({ dependencies: [], key: "entity:ada", kind: "entity",
+      v: 1, value: { entityId } });
+    const statement = createKnowledgeGraphRecordV1({ dependencies: [entity.key], key: "statement:ada-name",
+      kind: "statement", v: 1, value: { text: "Ada" } });
+    expect(parseKnowledgeGraphRecordV1(entity)).toEqual(entity);
+    const first = createKnowledgeGraphRevisionV1({ changes: [
+      { kind: "put", record: statement, v: 1 }, { kind: "put", record: entity, v: 1 },
+    ], operationId: "op_first", parent: null });
+    expect(parseKnowledgeGraphRevisionV1(first)).toEqual(first);
+    expect(first.graphRevisionSha256).toBe(graphRevisionSha256V1({ changes: first.changes,
+      operationId: first.operationId, parentGraphRevisionSha256: first.parentGraphRevisionSha256,
+      recordsSha256: first.recordsSha256, revision: first.revision }));
+    expect(first.recordRefs.find((ref) => ref.key === statement.key)?.dependencies).toEqual([entity.key]);
+    expect(() => createKnowledgeGraphRevisionV1({ changes: [{ key: entity.key, kind: "tombstone",
+      priorSha256: entity.recordSha256, v: 1 }], operationId: "op_bad_delete", parent: first }))
+      .toThrow("Missing graph dependency");
+    const updatedStatement = createKnowledgeGraphRecordV1({ dependencies: [entity.key], key: statement.key,
+      kind: "statement", v: 1, value: { text: "Ada Lovelace" } });
+    const second = createKnowledgeGraphRevisionV1({ changes: [{ kind: "put", record: updatedStatement, v: 1 }],
+      operationId: "op_second", parent: first });
+    expect(reduceKnowledgeGraphRevisionsV1([second, first])?.graphRevisionSha256).toBe(second.graphRevisionSha256);
+    expect(reduceKnowledgeGraphRevisionsV1([{ ...second, recordsSha256: digest }])).toBeNull();
+  });
+
+  test("rejects snapshots beyond the V1 record ceiling before parsing their contents", () => {
+    expect(parseKnowledgeGraphRevisionV1({
+      changes: [], graphRevisionSha256: digest, operationId: "op_oversized",
+      parentGraphRevisionSha256: null,
+      recordRefs: Array.from({ length: OH_GRAPH_LIMITS_V1.recordsPerSnapshot + 1 }),
+      recordsSha256: digest, revision: 1, v: 1,
+    })).toBeNull();
+  });
+
+  test("manifest pins every wire-level contract input", () => {
+    expect(OH_CONTRACT_MANIFEST_V1.contractId).toBe("oh.ontology.v1");
+    expect(OH_CONTRACT_MANIFEST_V1.recordKinds).toContain("statement");
+    expect(canonicalJson(OH_CONTRACT_MANIFEST_V1)).toContain(OH_CONTRACT_MANIFEST_V1.contractSha256);
+  });
+});