@soulcraft/brainy 5.3.3 → 5.3.4

package/dist/brainy.js

@@ -2031,9 +2031,11 @@ export class Brainy {
             // Get current state statistics
             const entityCount = await this.getNounCount();
             const relationshipCount = await this.getVerbCount();
+            // v5.3.4: Import NULL_HASH constant
+            const { NULL_HASH } = await import('./storage/cow/constants.js');
             // Build commit object using builder pattern
             const builder = CommitBuilder.create(blobStorage)
-                .tree('0000000000000000000000000000000000000000000000000000000000000000') // Empty tree hash for now
+                .tree(NULL_HASH) // Empty tree hash (sentinel value)
                 .message(options?.message || 'Snapshot commit')
                 .author(options?.author || 'unknown')
                 .timestamp(Date.now())

package/dist/storage/baseStorage.js

@@ -222,7 +222,9 @@ export class BaseStorage extends BaseStorageAdapter {
         const mainRef = await this.refManager.getRef('main');
         if (!mainRef) {
             // Create initial commit with empty tree
-            const emptyTreeHash = '0000000000000000000000000000000000000000000000000000000000000000';
+            // v5.3.4: Use NULL_HASH constant instead of hardcoded string
+            const { NULL_HASH } = await import('./cow/constants.js');
+            const emptyTreeHash = NULL_HASH;
             // Import CommitBuilder
             const { CommitBuilder } = await import('./cow/CommitObject.js');
             // Create initial commit object

package/dist/storage/cow/BlobStorage.js

@@ -14,6 +14,7 @@
  * @module storage/cow/BlobStorage
  */
 import { createHash } from 'crypto';
+import { NULL_HASH, isNullHash } from './constants.js';
 /**
  * State-of-the-art content-addressable blob storage
  *
@@ -162,6 +163,15 @@ export class BlobStorage {
      * @returns Blob data
      */
     async read(hash, options = {}) {
+        // v5.3.4 fix: Guard against NULL hash (sentinel value)
+        // NULL_HASH ('0000...0000') is used as a sentinel for "no parent" or "empty tree"
+        // It should NEVER be read as actual blob data
+        if (isNullHash(hash)) {
+            throw new Error(`Cannot read NULL hash (${NULL_HASH}): ` +
+                `This is a sentinel value indicating "no parent commit" or "empty tree". ` +
+                `If you're seeing this error from CommitObject.walk(), there's a bug in commit traversal logic. ` +
+                `If you're seeing this from TreeObject operations, there's a bug in tree handling.`);
+        }
         // Check cache first
         if (!options.skipCache) {
             const cached = this.getFromCache(hash);

package/dist/storage/cow/CommitObject.js

@@ -15,6 +15,7 @@
  * @module storage/cow/CommitObject
  */
 import { BlobStorage } from './BlobStorage.js';
+import { isNullHash } from './constants.js';
 /**
  * CommitBuilder: Fluent API for building commit objects
  *
@@ -269,7 +270,10 @@ export class CommitObject {
     static async *walk(blobStorage, startHash, options) {
         let currentHash = startHash;
         let depth = 0;
-        while (currentHash) {
+        // v5.3.4 fix: Guard against NULL hash (sentinel for "no parent")
+        // The initial commit has parent = null or NULL_HASH ('0000...0000')
+        // We must stop walking when we reach it, not try to read it
+        while (currentHash && !isNullHash(currentHash)) {
             // Check max depth
             if (options?.maxDepth && depth >= options.maxDepth) {
                 break;
@@ -291,7 +295,7 @@ export class CommitObject {
             if (options?.stopAt && currentHash === options.stopAt) {
                 break;
             }
-            // Move to parent
+            // Move to parent (can be null or NULL_HASH for initial commit)
             currentHash = commit.parent;
             depth++;
         }

package/dist/storage/cow/constants.d.ts

@@ -0,0 +1,48 @@
+/**
+ * COW Storage Constants
+ *
+ * Sentinel values and utilities for Copy-On-Write storage system.
+ *
+ * @module storage/cow/constants
+ */
+/**
+ * NULL_HASH - Sentinel value for "no parent commit" or "empty tree"
+ *
+ * In Git-like COW systems, we need a way to represent:
+ * - Initial commit (has no parent)
+ * - Empty tree (contains no files)
+ *
+ * We use a 64-character zero hash as a sentinel value.
+ * This should NEVER be used as an actual content hash.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * const builder = CommitBuilder.create(storage)
+ *   .tree(NULL_HASH)  // Empty tree
+ *   .parent(null)      // No parent (use null, not NULL_HASH)
+ *   .build()
+ * ```
+ */
+export declare const NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Check if a hash is the NULL sentinel value
+ *
+ * @param hash - Hash to check (can be string or null)
+ * @returns true if hash is null or NULL_HASH
+ *
+ * @example
+ * ```typescript
+ * if (isNullHash(commit.parent)) {
+ *   console.log('This is the initial commit')
+ * }
+ * ```
+ */
+export declare function isNullHash(hash: string | null | undefined): boolean;
+/**
+ * Check if a hash is valid (non-null, non-empty, proper format)
+ *
+ * @param hash - Hash to check
+ * @returns true if hash is a valid SHA-256 hash
+ */
+export declare function isValidHash(hash: string | null | undefined): boolean;

package/dist/storage/cow/constants.js

@@ -0,0 +1,57 @@
+/**
+ * COW Storage Constants
+ *
+ * Sentinel values and utilities for Copy-On-Write storage system.
+ *
+ * @module storage/cow/constants
+ */
+/**
+ * NULL_HASH - Sentinel value for "no parent commit" or "empty tree"
+ *
+ * In Git-like COW systems, we need a way to represent:
+ * - Initial commit (has no parent)
+ * - Empty tree (contains no files)
+ *
+ * We use a 64-character zero hash as a sentinel value.
+ * This should NEVER be used as an actual content hash.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * const builder = CommitBuilder.create(storage)
+ *   .tree(NULL_HASH)  // Empty tree
+ *   .parent(null)      // No parent (use null, not NULL_HASH)
+ *   .build()
+ * ```
+ */
+export const NULL_HASH = '0000000000000000000000000000000000000000000000000000000000000000';
+/**
+ * Check if a hash is the NULL sentinel value
+ *
+ * @param hash - Hash to check (can be string or null)
+ * @returns true if hash is null or NULL_HASH
+ *
+ * @example
+ * ```typescript
+ * if (isNullHash(commit.parent)) {
+ *   console.log('This is the initial commit')
+ * }
+ * ```
+ */
+export function isNullHash(hash) {
+    return hash === null || hash === undefined || hash === NULL_HASH;
+}
+/**
+ * Check if a hash is valid (non-null, non-empty, proper format)
+ *
+ * @param hash - Hash to check
+ * @returns true if hash is a valid SHA-256 hash
+ */
+export function isValidHash(hash) {
+    if (isNullHash(hash)) {
+        return false;
+    }
+    // SHA-256 hash must be exactly 64 hexadecimal characters
+    return typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash);
+}
+//# sourceMappingURL=constants.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.3.3",
+  "version": "5.3.4",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",