@hraness/oh 0.3.2 → 0.4.0

package/src/errors.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isOhConflictError,
+  isOhDependencyError,
+  isOhIntegrityError,
+  isOhOperationSizeError,
+  isOhProfileError,
+  OhConflictError,
+  OhDependencyError,
+  OhIntegrityError,
+  OhOperationSizeError,
+  OhProfileError,
+} from "./errors";
+
+const CORE_ERRORS = [
+  {
+    brand: "@hraness/oh/OhConflictError/v1",
+    ErrorClass: OhConflictError,
+    guard: isOhConflictError,
+    name: "OhConflictError",
+  },
+  {
+    brand: "@hraness/oh/OhIntegrityError/v1",
+    ErrorClass: OhIntegrityError,
+    guard: isOhIntegrityError,
+    name: "OhIntegrityError",
+  },
+  {
+    brand: "@hraness/oh/OhDependencyError/v1",
+    ErrorClass: OhDependencyError,
+    guard: isOhDependencyError,
+    name: "OhDependencyError",
+  },
+  {
+    brand: "@hraness/oh/OhProfileError/v1",
+    ErrorClass: OhProfileError,
+    guard: isOhProfileError,
+    name: "OhProfileError",
+  },
+] as const;
+
+describe("Oh public error identity", () => {
+  for (const { brand, ErrorClass, guard, name } of CORE_ERRORS) {
+    test(`brands ${name} without changing its public constructor`, () => {
+      const error = new ErrorClass("preserved message");
+      expect(Error.isError(error)).toBe(true);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ErrorClass);
+      expect(guard(error)).toBe(true);
+      expect(error).toMatchObject({ message: "preserved message", name });
+      expect(Object.keys(error)).toEqual(["name"]);
+
+      const copied = Object.create(Error.prototype) as Record<PropertyKey, unknown>;
+      Object.defineProperty(copied, Symbol.for(brand), {
+        configurable: false,
+        value: true,
+        writable: false,
+      });
+      expect(Error.isError(copied)).toBe(false);
+      expect(guard(copied)).toBe(false);
+      expect(copied instanceof ErrorClass).toBe(false);
+    });
+  }
+
+  test("preserves native subclass identity while exposing the branded base", () => {
+    class NarrowConflictError extends OhConflictError {}
+
+    const base = new OhConflictError("base");
+    const narrow = new NarrowConflictError("narrow");
+    expect(base).not.toBeInstanceOf(NarrowConflictError);
+    expect(narrow).toBeInstanceOf(NarrowConflictError);
+    expect(narrow).toBeInstanceOf(OhConflictError);
+    expect(isOhConflictError(narrow)).toBe(true);
+  });
+
+  test("does not make every operation-size error an instance of a subclass", () => {
+    class NarrowSizeError extends OhOperationSizeError {}
+
+    const base = new OhOperationSizeError(2, 1);
+    const narrow = new NarrowSizeError(2, 1);
+    expect(base).not.toBeInstanceOf(NarrowSizeError);
+    expect(narrow).toBeInstanceOf(NarrowSizeError);
+    expect(narrow).toBeInstanceOf(OhOperationSizeError);
+    expect(isOhOperationSizeError(narrow)).toBe(true);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,185 @@
+export const OH_OPERATION_SIZE_ERROR_CODE_V1 = "oh.operation-size.v1" as const;
+
+const OH_CONFLICT_ERROR_BRAND_V1 = Symbol.for("@hraness/oh/OhConflictError/v1");
+const OH_DEPENDENCY_ERROR_BRAND_V1 = Symbol.for("@hraness/oh/OhDependencyError/v1");
+const OH_INTEGRITY_ERROR_BRAND_V1 = Symbol.for("@hraness/oh/OhIntegrityError/v1");
+const OH_OPERATION_SIZE_ERROR_BRAND_V1 = Symbol.for("@hraness/oh/OhOperationSizeError/v1");
+const OH_PROFILE_ERROR_BRAND_V1 = Symbol.for("@hraness/oh/OhProfileError/v1");
+
+function immutableOwnValue(value: object, key: PropertyKey): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor !== undefined
+      && descriptor.get === undefined
+      && descriptor.set === undefined
+      && descriptor.configurable === false
+      && descriptor.writable === false
+    ? descriptor.value
+    : undefined;
+}
+
+function brandNativeError(value: Error, brand: symbol): void {
+  Object.defineProperty(value, brand, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false,
+  });
+}
+
+function hasNativeErrorBrand(value: unknown, brand: symbol): boolean {
+  try {
+    return Error.isError(value) && immutableOwnValue(value, brand) === true;
+  } catch {
+    return false;
+  }
+}
+
+function hasNativeSubclassInstance(constructor: Function, value: unknown): boolean {
+  return Function.prototype[Symbol.hasInstance].call(constructor, value);
+}
+
+/** Recognizes a compare-and-swap conflict across separately bundled Oh entrypoints. */
+export function isOhConflictError(value: unknown): value is OhConflictError {
+  return hasNativeErrorBrand(value, OH_CONFLICT_ERROR_BRAND_V1);
+}
+
+export class OhConflictError extends Error {
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    return this === OhConflictError
+      ? isOhConflictError(value)
+      : hasNativeSubclassInstance(this, value);
+  }
+
+  constructor(message: string) {
+    super(message);
+    this.name = "OhConflictError";
+    brandNativeError(this, OH_CONFLICT_ERROR_BRAND_V1);
+  }
+}
+
+/** Recognizes an authority-integrity failure across separately bundled Oh entrypoints. */
+export function isOhIntegrityError(value: unknown): value is OhIntegrityError {
+  return hasNativeErrorBrand(value, OH_INTEGRITY_ERROR_BRAND_V1);
+}
+
+export class OhIntegrityError extends Error {
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    return this === OhIntegrityError
+      ? isOhIntegrityError(value)
+      : hasNativeSubclassInstance(this, value);
+  }
+
+  constructor(message: string) {
+    super(message);
+    this.name = "OhIntegrityError";
+    brandNativeError(this, OH_INTEGRITY_ERROR_BRAND_V1);
+  }
+}
+
+/** Recognizes a missing-dependency failure across separately bundled Oh entrypoints. */
+export function isOhDependencyError(value: unknown): value is OhDependencyError {
+  return hasNativeErrorBrand(value, OH_DEPENDENCY_ERROR_BRAND_V1);
+}
+
+export class OhDependencyError extends Error {
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    return this === OhDependencyError
+      ? isOhDependencyError(value)
+      : hasNativeSubclassInstance(this, value);
+  }
+
+  constructor(message: string) {
+    super(message);
+    this.name = "OhDependencyError";
+    brandNativeError(this, OH_DEPENDENCY_ERROR_BRAND_V1);
+  }
+}
+
+/** Recognizes a store-profile refusal across separately bundled Oh entrypoints. */
+export function isOhProfileError(value: unknown): value is OhProfileError {
+  return hasNativeErrorBrand(value, OH_PROFILE_ERROR_BRAND_V1);
+}
+
+export class OhProfileError extends Error {
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    return this === OhProfileError
+      ? isOhProfileError(value)
+      : hasNativeSubclassInstance(this, value);
+  }
+
+  constructor(message: string) {
+    super(message);
+    this.name = "OhProfileError";
+    brandNativeError(this, OH_PROFILE_ERROR_BRAND_V1);
+  }
+}
+
+/**
+ * Recognizes this precommit refusal across separately bundled Oh entrypoints.
+ * Native Error identity plus immutable branded fields excludes copied plain
+ * objects while preserving one stable discriminator for package consumers.
+ */
+export function isOhOperationSizeError(value: unknown): value is OhOperationSizeError {
+  try {
+    if (!Error.isError(value) || !(value instanceof RangeError)) return false;
+    const operationBytes = immutableOwnValue(value, "operationBytes");
+    const maximumOperationBytes = immutableOwnValue(value, "maximumOperationBytes");
+    return immutableOwnValue(value, OH_OPERATION_SIZE_ERROR_BRAND_V1) === true
+      && immutableOwnValue(value, "code") === OH_OPERATION_SIZE_ERROR_CODE_V1
+      && Number.isSafeInteger(operationBytes)
+      && (operationBytes as number) > 0
+      && Number.isSafeInteger(maximumOperationBytes)
+      && (maximumOperationBytes as number) > 0
+      && (operationBytes as number) > (maximumOperationBytes as number);
+  } catch {
+    return false;
+  }
+}
+
+export class OhOperationSizeError extends RangeError {
+  declare readonly code: typeof OH_OPERATION_SIZE_ERROR_CODE_V1;
+  declare readonly maximumOperationBytes: number;
+  declare readonly operationBytes: number;
+
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    return this === OhOperationSizeError
+      ? isOhOperationSizeError(value)
+      : hasNativeSubclassInstance(this, value);
+  }
+
+  constructor(operationBytes: number, maximumOperationBytes: number) {
+    if (!Number.isSafeInteger(operationBytes) || operationBytes < 1
+      || !Number.isSafeInteger(maximumOperationBytes) || maximumOperationBytes < 1
+      || operationBytes <= maximumOperationBytes) {
+      throw new TypeError("Invalid Oh operation size refusal.");
+    }
+    super(`The ${operationBytes}-byte operation exceeds the host-declared ${maximumOperationBytes}-byte canonical bound.`);
+    this.name = "OhOperationSizeError";
+    Object.defineProperties(this, {
+      [OH_OPERATION_SIZE_ERROR_BRAND_V1]: {
+        configurable: false,
+        enumerable: false,
+        value: true,
+        writable: false,
+      },
+      code: {
+        configurable: false,
+        enumerable: true,
+        value: OH_OPERATION_SIZE_ERROR_CODE_V1,
+        writable: false,
+      },
+      maximumOperationBytes: {
+        configurable: false,
+        enumerable: true,
+        value: maximumOperationBytes,
+        writable: false,
+      },
+      operationBytes: {
+        configurable: false,
+        enumerable: true,
+        value: operationBytes,
+        writable: false,
+      },
+    });
+  }
+}

package/src/graph.ts

@@ -19,12 +19,12 @@ export const OH_GRAPH_LIMITS_V1 = Object.freeze({
   recordsPerSnapshot: 65_536,
 });
 
-export const OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1 = [
+export const OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1 = Object.freeze([
   "activity", "assertion", "context", "dependency-manifest", "edition", "entity",
   "evidence", "identity-operation", "inquiry", "inquiry-event", "review-decision",
   "rights-decision", "schema", "shape", "statement", "type-membership", "view",
   "vocabulary",
-] as const;
+] as const);
 export type KnowledgeGraphRecordKindV1 = (typeof OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1)[number];
 
 export type KnowledgeGraphRecordV1 = Readonly<{

package/src/libsql.test.ts

@@ -18,6 +18,7 @@ import {
   OH_WORKING_STORE_PROFILE_V1,
   OhConflictError,
   OhIntegrityError,
+  OhOperationSizeError,
   OhProfileError,
   OhPurgedSpaceError,
 } from "./store";
@@ -341,6 +342,41 @@ describe("direct libSQL Oh authority", () => {
     client.close();
   });
 
+  test("honors the host-declared operation byte bound before replay or persistence", async () => {
+    const client = await bootstrappedClient();
+    const authority = await createOhLibSqlStoreAuthorityV1(client, {
+      profile: OH_CANONICAL_STORE_PROFILE_V1, realmId: "realm:operation-bound", spaceId: "operation-bound",
+    });
+    const empty = await authority.store.head();
+    const firstChanges = [{ kind: "put" as const,
+      record: entity("entity:bounded", "Bounded"), v: 1 as const }];
+    const first = await authority.store.commit({ actorId: "agent.bound", changes: firstChanges,
+      expectedHead: empty, operationId: "op_bounded_first" });
+
+    const replayError: unknown = await authority.store.commit({ actorId: "agent.bound", changes: firstChanges,
+      expectedHead: empty, maximumOperationBytes: 1,
+      operationId: "op_bounded_first" }).catch((error: unknown) => error);
+    const commitError: unknown = await authority.store.commit({ actorId: "agent.bound", changes: [{ kind: "put",
+      record: entity("entity:rejected", "Rejected"), v: 1 }], expectedHead: await authority.store.head(),
+    maximumOperationBytes: 1, operationId: "op_bounded_rejected" }).catch((error: unknown) => error);
+    for (const error of [replayError, commitError]) {
+      expect(error).toBeInstanceOf(OhOperationSizeError);
+      expect(error).toBeInstanceOf(RangeError);
+      expect(error).toMatchObject({ maximumOperationBytes: 1,
+        operationBytes: expect.any(Number) });
+    }
+
+    expect(await authority.store.head()).toMatchObject({
+      operationSha256: first.operationSha256,
+      sequence: 1,
+    });
+    expect(client.database.query<{ count: number }, [string]>(`SELECT count(*) AS count
+      FROM oh_authority_operations WHERE space_id = ?`).get("operation-bound")?.count).toBe(1);
+    expect((await authority.store.snapshot()).records.map(({ key }) => key)).toEqual(["entity:bounded"]);
+    await authority.store.close();
+    client.close();
+  });
+
   test("uses compare-and-swap guards to leave no partial remote mutation", async () => {
     const client = await bootstrappedClient();
     const first = await createOhLibSqlStoreAuthorityV1(client, {

package/src/libsql.ts

@@ -11,7 +11,11 @@ import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
 import { canonicalKnowledgeGraphChangesV1, knowledgeGraphRecordRefV1, OH_GRAPH_LIMITS_V1,
   parseKnowledgeGraphRecordV1,
   type KnowledgeGraphRecordV1 } from "./graph";
-import { parseOhOperationV1, type OhOperationV1 } from "./operation";
+import {
+  OH_OPERATION_MAX_BYTES_V1,
+  parseOhOperationV1,
+  type OhOperationV1,
+} from "./operation";
 import {
   createOhDependencyClosureV1,
   createOhSpacePurgeReceiptV1,
@@ -21,6 +25,7 @@ import {
   OH_WORKING_STORE_PROFILE_V1,
   OhConflictError,
   OhIntegrityError,
+  OhOperationSizeError,
   OhProfileError,
   OhPurgedSpaceError,
   parseOhHeadRefV1,
@@ -1261,8 +1266,14 @@ class OhLibSqlStoreV1 implements OhStoreV1 {
     this.#assertOpen();
     const actorId = safeCode(input.actorId);
     const operationId = safeCode(input.operationId);
+    const maximumOperationBytes = input.maximumOperationBytes ?? OH_OPERATION_MAX_BYTES_V1;
     const changes = canonicalKnowledgeGraphChangesV1(input.changes);
-    if (actorId === null || operationId === null || changes.length === 0) throw new TypeError("Invalid Oh commit input.");
+    if (actorId === null || operationId === null || changes.length === 0
+      || !Number.isSafeInteger(maximumOperationBytes)
+      || maximumOperationBytes < 1
+      || maximumOperationBytes > OH_OPERATION_MAX_BYTES_V1) {
+      throw new TypeError("Invalid Oh commit input.");
+    }
     if (changes.length > OH_LIBSQL_STORE_LIMITS_V1.changesPerCommit) {
       throw new RangeError("A direct libSQL commit exceeds its change-count bound.");
     }
@@ -1277,6 +1288,10 @@ class OhLibSqlStoreV1 implements OhStoreV1 {
       if (duplicate.actorId !== actorId || canonicalJson(duplicate.changes) !== canonicalJson(changes)) {
         throw new OhConflictError("The operation ID is already bound to different content.");
       }
+      const operationBytes = utf8ByteLength(canonicalJson(duplicate));
+      if (operationBytes > maximumOperationBytes) {
+        throw new OhOperationSizeError(operationBytes, maximumOperationBytes);
+      }
       return duplicate;
     }
     if (!Number.isSafeInteger(input.expectedHead.generation) || input.expectedHead.generation < 0
@@ -1286,9 +1301,15 @@ class OhLibSqlStoreV1 implements OhStoreV1 {
     }
     const snapshot = await this.#currentMaterializedSnapshot(current, OH_GRAPH_LIMITS_V1.recordsPerSnapshot);
     const transition = transitionOhSnapshotV1({ actorId, changes,
-      instant: input.instant ?? canonicalNow(), operationId, snapshot, spaceId: this.binding.spaceId });
+      instant: input.instant ?? canonicalNow(), maximumOperationBytes,
+      operationId, snapshot, spaceId: this.binding.spaceId });
     const operation = transition.operation;
-    if (utf8ByteLength(canonicalJson(operation)) > OH_LIBSQL_STORE_LIMITS_V1.operationBytes) {
+    const operationJson = canonicalJson(operation);
+    const operationBytes = utf8ByteLength(operationJson);
+    if (operationBytes > maximumOperationBytes) {
+      throw new OhOperationSizeError(operationBytes, maximumOperationBytes);
+    }
+    if (operationBytes > OH_LIBSQL_STORE_LIMITS_V1.operationBytes) {
       throw new RangeError("A direct libSQL operation exceeds its canonical byte bound.");
     }
     const existsOperation = "EXISTS (SELECT 1 FROM oh_authority_operations WHERE operation_sha256 = ?)";
@@ -1301,7 +1322,7 @@ class OhLibSqlStoreV1 implements OhStoreV1 {
           WHERE space_id = ? AND generation = ? AND head_operation_sha256 IS ?)`,
       args: [operation.operationSha256, this.binding.spaceId, operation.sequence, operation.operationId,
         operation.parentOperationSha256, operation.graphRevisionSha256, operation.recordsSha256,
-        canonicalJson(operation), operation.instant, this.binding.spaceId, current.generation,
+        operationJson, operation.instant, this.binding.spaceId, current.generation,
         current.operationSha256],
     }];
     for (const [ordinal, change] of operation.changes.entries()) {