@soulcraft/brainy 5.3.3 → 5.3.5

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.3.5](https://github.com/soulcraftlabs/brainy/compare/v5.3.4...v5.3.5) (2025-11-05)
+
+
+### 🐛 Bug Fixes
+
+* resolve fork + checkout workflow with COW file listing and branch persistence ([189b1b0](https://github.com/soulcraftlabs/brainy/commit/189b1b05dec4daad28a9ce7e0840ffaaf675ecfa))
+
 ### [5.3.0](https://github.com/soulcraftlabs/brainy/compare/v5.2.1...v5.3.0) (2025-11-04)
 
 - feat: add entity versioning system with critical bug fixes (v5.3.0) (c488fa8)

package/dist/brainy.js

@@ -1993,14 +1993,19 @@ export class Brainy {
             }
             // Update storage currentBranch
             this.storage.currentBranch = branch;
-            // Reload from new branch
-            // Clear indexes and reload
+            // v5.3.5 fix: Reload indexes from new branch WITHOUT recreating storage
+            // Previous implementation called init() which recreated storage, losing currentBranch
             this.index = this.setupIndex();
             this.metadataIndex = new MetadataIndexManager(this.storage);
+            await this.metadataIndex.init();
             this.graphIndex = new GraphAdjacencyIndex(this.storage);
-            // Re-initialize
-            this.initialized = false;
-            await this.init();
+            // Rebuild indexes from new branch data
+            await this.rebuildIndexesIfNeeded();
+            // Re-initialize VFS for new branch
+            if (this._vfs) {
+                this._vfs = new VirtualFileSystem(this);
+                await this._vfs.init();
+            }
         });
     }
     /**
@@ -2031,9 +2036,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/adapters/fileSystemStorage.js

@@ -736,7 +736,10 @@ export class FileSystemStorage extends BaseStorage {
             const entries = await fs.promises.readdir(fullPath, { withFileTypes: true });
             for (const entry of entries) {
                 if (entry.isFile()) {
-                    // Handle both .json and .json.gz files
+                    // v5.3.5: Handle multiple compression formats for broad compatibility
+                    // - .json.gz: Standard entity/metadata files (JSON compressed)
+                    // - .gz: COW files (refs, blobs, commits - raw compressed)
+                    // - .json: Uncompressed JSON files
                     if (entry.name.endsWith('.json.gz')) {
                         // Strip .gz extension and add the .json path
                         const normalizedName = entry.name.slice(0, -3); // Remove .gz
@@ -746,6 +749,16 @@ export class FileSystemStorage extends BaseStorage {
                             seen.add(normalizedPath);
                         }
                     }
+                    else if (entry.name.endsWith('.gz')) {
+                        // v5.3.5 fix: COW files stored as .gz (not .json.gz)
+                        // Strip .gz extension and return path
+                        const normalizedName = entry.name.slice(0, -3); // Remove .gz
+                        const normalizedPath = path.join(prefix, normalizedName);
+                        if (!seen.has(normalizedPath)) {
+                            paths.push(normalizedPath);
+                            seen.add(normalizedPath);
+                        }
+                    }
                     else if (entry.name.endsWith('.json')) {
                         const filePath = path.join(prefix, entry.name);
                         if (!seen.has(filePath)) {
@@ -755,7 +768,8 @@ export class FileSystemStorage extends BaseStorage {
                     }
                 }
                 else if (entry.isDirectory()) {
-                    const subdirPaths = await this.listObjectsUnderPath(path.join(prefix, entry.name));
+                    const subpath = path.join(prefix, entry.name);
+                    const subdirPaths = await this.listObjectsUnderPath(subpath);
                     paths.push(...subdirPaths);
                 }
             }

package/dist/storage/baseStorage.js

@@ -201,11 +201,21 @@ export class BaseStorage extends BaseStorageAdapter {
             },
             list: async (prefix) => {
                 try {
-                    const paths = await this.listObjectsUnderPath(`_cow/${prefix}`);
+                    // v5.3.5 fix: Handle file prefixes, not just directory paths
+                    // Refs are stored as files like: _cow/ref:refs/heads/main
+                    // So list('ref:') should find all files starting with '_cow/ref:'
+                    // List the _cow directory and filter by prefix
+                    const allPaths = await this.listObjectsUnderPath('_cow/');
+                    const filteredPaths = allPaths.filter(p => {
+                        // Remove _cow/ prefix to get the key
+                        const key = p.replace(/^_cow\//, '');
+                        return key.startsWith(prefix);
+                    });
                     // Remove _cow/ prefix and return relative keys
-                    return paths.map(p => p.replace(/^_cow\//, ''));
+                    return filteredPaths.map(p => p.replace(/^_cow\//, ''));
                 }
                 catch (error) {
+                    // If _cow directory doesn't exist yet, return empty array
                     return [];
                 }
             }
@@ -222,7 +232,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.5",
   "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",