feat(das-client): atom-handle hashing ported from hyperon_das/hasher.py with MD5 parity vectors

Author: MesTTo

packages/das-client/src/handle.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { namedTypeHash, terminalHash, compositeHash, expressionHash } from "./handle";
+
+// Parity vectors: MD5 of the exact strings the Python reference (`hyperon_das/hasher.py`) hashes,
+// computed independently via `md5sum`. Matching these guarantees handle parity with the Python/Rust
+// DAS clients (a wrong handle makes every query miss).
+describe("DAS atom-handle hashing (parity with hyperon_das/hasher.py)", () => {
+  it("named_type_hash", () => {
+    expect(namedTypeHash("Concept")).toBe("d99a604c79ce3c2e76a2f43488d5d4c3");
+  });
+  it("terminal_hash joins type and name with a space", () => {
+    expect(terminalHash("Concept", "human")).toBe("af12f10f9ae2002a1607ba0b47ba8407");
+  });
+  it("composite_hash joins element handles with a space", () => {
+    expect(compositeHash(["a", "b", "c"])).toBe("06f0760ec7f18687a7fbc0ddbf1b1722");
+  });
+  it("expression_hash = composite of [typeHash, ...elements]", () => {
+    // expression_hash("a", ["b","c"]) === composite_hash(["a","b","c"])
+    expect(expressionHash("a", ["b", "c"])).toBe(compositeHash(["a", "b", "c"]));
+  });
+});

packages/das-client/src/handle.ts

@@ -0,0 +1,42 @@
+// DAS atom-handle hashing, a faithful port of the Python reference `hyperon_das/hasher.py`.
+// Handles are deterministic MD5 hashes of joined strings; getting these byte-identical to the
+// Python/Rust clients is the prerequisite for every query (a wrong handle means every match misses).
+// Node-only (uses node:crypto), like the rest of the bus client.
+import { createHash } from "node:crypto";
+
+const JOINING_CHAR = " ";
+const MAX_LITERAL_OR_SYMBOL_SIZE = 10000;
+const MAX_HASHABLE_STRING_SIZE = 100000;
+
+export function computeHash(input: string): string {
+  return createHash("md5").update(input, "utf8").digest("hex");
+}
+
+/** Hash of a named type (`named_type_hash`). */
+export function namedTypeHash(name: string): string {
+  return computeHash(name);
+}
+
+/** Hash of a terminal node `(type, name)` (`terminal_hash`). */
+export function terminalHash(type: string, name: string): string {
+  if (type.length + name.length >= MAX_HASHABLE_STRING_SIZE)
+    throw new Error("Invalid (too large) terminal name");
+  return computeHash(`${type}${JOINING_CHAR}${name}`);
+}
+
+/** Hash of a composite of element handles (`composite_hash`). */
+export function compositeHash(elements: readonly string[]): string {
+  let total = 0;
+  for (const e of elements) {
+    if (e.length > MAX_LITERAL_OR_SYMBOL_SIZE)
+      throw new Error("Invalid (too large) composite elements");
+    total += e.length;
+  }
+  if (total >= MAX_HASHABLE_STRING_SIZE) throw new Error("Invalid (too large) composite elements");
+  return computeHash(elements.join(JOINING_CHAR));
+}
+
+/** Hash of an expression: the type hash followed by the element handles (`expression_hash`). */
+export function expressionHash(typeHash: string, elements: readonly string[]): string {
+  return compositeHash([typeHash, ...elements]);
+}

packages/das-client/src/index.ts

@@ -12,3 +12,4 @@
 // @metta-ts/das-gateway). See README.
 export { type DasTransport, MockTransport } from "./transport";
 export { DasSpace } from "./das-space";
+export { computeHash, namedTypeHash, terminalHash, compositeHash, expressionHash } from "./handle";

packages/das-client/tsconfig.json

@@ -1,5 +1,13 @@
 {
   "extends": "../../tsconfig.base.json",
-  "include": ["src"],
-  "compilerOptions": { "outDir": "dist", "rootDir": "src" }
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": [
+      "node"
+    ]
+  }
 }