@soulcraft/brainy 5.3.2 → 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
  *
@@ -132,10 +133,12 @@ export class BlobStorage {
         }
         else {
             // Small blob: single write
-            await this.adapter.put(`blob:${hash}`, finalData);
+            const prefix = options.type || 'blob';
+            await this.adapter.put(`${prefix}:${hash}`, finalData);
         }
         // Write metadata
-        await this.adapter.put(`blob-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
+        const prefix = options.type || 'blob';
+        await this.adapter.put(`${prefix}-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
         // Update cache (write-through)
         this.addToCache(hash, data, metadata);
         // Update stats
@@ -160,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);
@@ -169,17 +181,27 @@ export class BlobStorage {
             }
             this.stats.cacheMisses++;
         }
-        // Read from storage
-        const data = await this.adapter.get(`blob:${hash}`);
-        if (!data) {
-            throw new Error(`Blob not found: ${hash}`);
+        // Try to read metadata to determine type (for backward compatibility)
+        // Try commit, tree, then blob prefixes
+        let prefix = null;
+        let metadataBuffer;
+        let metadata;
+        for (const tryPrefix of ['commit', 'tree', 'blob']) {
+            metadataBuffer = await this.adapter.get(`${tryPrefix}-meta:${hash}`);
+            if (metadataBuffer) {
+                prefix = tryPrefix;
+                metadata = JSON.parse(metadataBuffer.toString());
+                break;
+            }
         }
-        // Read metadata
-        const metadataBuffer = await this.adapter.get(`blob-meta:${hash}`);
-        if (!metadataBuffer) {
+        if (!prefix || !metadata) {
             throw new Error(`Blob metadata not found: ${hash}`);
         }
-        const metadata = JSON.parse(metadataBuffer.toString());
+        // Read from storage using determined prefix
+        const data = await this.adapter.get(`${prefix}:${hash}`);
+        if (!data) {
+            throw new Error(`Blob not found: ${hash}`);
+        }
         // Decompress if needed
         let finalData = data;
         if (metadata.compression === 'zstd' && !options.skipDecompression) {
@@ -209,9 +231,14 @@ export class BlobStorage {
         if (this.cache.has(hash)) {
             return true;
         }
-        // Check storage
-        const exists = await this.adapter.get(`blob:${hash}`);
-        return exists !== undefined;
+        // Check storage - try all prefixes for backward compatibility
+        for (const prefix of ['commit', 'tree', 'blob']) {
+            const exists = await this.adapter.get(`${prefix}:${hash}`);
+            if (exists !== undefined) {
+                return true;
+            }
+        }
+        return false;
     }
     /**
      * Delete a blob from storage
@@ -230,10 +257,19 @@ export class BlobStorage {
         if (refCount > 0) {
             return;
         }
+        // Determine prefix by checking which one exists
+        let prefix = 'blob';
+        for (const tryPrefix of ['commit', 'tree', 'blob']) {
+            const exists = await this.adapter.get(`${tryPrefix}:${hash}`);
+            if (exists !== undefined) {
+                prefix = tryPrefix;
+                break;
+            }
+        }
         // Delete blob data
-        await this.adapter.delete(`blob:${hash}`);
+        await this.adapter.delete(`${prefix}:${hash}`);
         // Delete metadata
-        await this.adapter.delete(`blob-meta:${hash}`);
+        await this.adapter.delete(`${prefix}-meta:${hash}`);
         // Remove from cache
         this.removeFromCache(hash);
         // Update stats
@@ -246,11 +282,15 @@ export class BlobStorage {
      * @returns Blob metadata
      */
     async getMetadata(hash) {
-        const data = await this.adapter.get(`blob-meta:${hash}`);
-        if (!data) {
-            return undefined;
+        // Try to read metadata with type-aware prefix (backward compatible)
+        // Try commit, tree, then blob prefixes
+        for (const prefix of ['commit', 'tree', 'blob']) {
+            const data = await this.adapter.get(`${prefix}-meta:${hash}`);
+            if (data) {
+                return JSON.parse(data.toString());
+            }
         }
-        return JSON.parse(data.toString());
+        return undefined;
     }
     /**
      * Batch write multiple blobs in parallel
@@ -277,8 +317,16 @@ export class BlobStorage {
      * @returns Array of blob hashes
      */
     async listBlobs() {
-        const keys = await this.adapter.list('blob:');
-        return keys.map((key) => key.replace(/^blob:/, ''));
+        // List all types of blobs
+        const hashes = new Set();
+        for (const prefix of ['commit', 'tree', 'blob']) {
+            const keys = await this.adapter.list(`${prefix}:`);
+            keys.forEach((key) => {
+                const hash = key.replace(new RegExp(`^${prefix}:`), '');
+                hashes.add(hash);
+            });
+        }
+        return Array.from(hashes);
     }
     /**
      * Get storage statistics
@@ -349,7 +397,8 @@ export class BlobStorage {
     async writeMultipart(hash, data, metadata) {
         // For now, just write as single blob
         // TODO: Implement actual multipart upload for S3/R2/GCS
-        await this.adapter.put(`blob:${hash}`, data);
+        const prefix = metadata.type || 'blob';
+        await this.adapter.put(`${prefix}:${hash}`, data);
     }
     /**
      * Increment reference count for a blob
@@ -360,7 +409,8 @@ export class BlobStorage {
             throw new Error(`Cannot increment ref count, blob not found: ${hash}`);
         }
         metadata.refCount++;
-        await this.adapter.put(`blob-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
+        const prefix = metadata.type || 'blob';
+        await this.adapter.put(`${prefix}-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
         return metadata.refCount;
     }
     /**
@@ -372,7 +422,8 @@ export class BlobStorage {
             return 0;
         }
         metadata.refCount = Math.max(0, metadata.refCount - 1);
-        await this.adapter.put(`blob-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
+        const prefix = metadata.type || 'blob';
+        await this.adapter.put(`${prefix}-meta:${hash}`, Buffer.from(JSON.stringify(metadata)));
         return metadata.refCount;
     }
     /**

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.2",
+  "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",