braid-blob 0.0.20 → 0.0.22

package/AI-README.md

@@ -0,0 +1,466 @@
+# AI-README.md
+
+Machine-optimized documentation for braid-blob library.
+
+## DEVELOPMENT_BEST_PRACTICES
+
+```
+REPOSITORY: braid-org/braid-blob
+MAIN_BRANCH: master
+NPM_PACKAGE: braid-blob
+
+VERSION_BUMP_WORKFLOW:
+  1. Make code changes
+  2. Update package.json version (increment patch: 0.0.X -> 0.0.X+1)
+  3. Git commit with formatted message (see below)
+  4. Git push to origin/master
+  5. npm publish
+
+COMMIT_MESSAGE_FORMAT:
+  Pattern: "{version} - {brief description of changes}"
+  Style: concise, lowercase, describes what was added/fixed/changed
+  Examples:
+    - "0.0.20 - adds test.js test runner"
+    - "0.0.19 - adds URL support for get/put operations and sync function for bidirectional synchronization"
+    - "0.0.18 - fixes meta filename case collision issue on case-insensitive filesystems, updates to url-file-db 0.0.8"
+    - "0.0.17 - refactors to use url-file-db, separates meta and blob storage, adds new test infrastructure"
+  Footer:
+    🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+    Co-Authored-By: Claude <noreply@anthropic.com>
+
+GIT_WORKFLOW:
+  - Always stage all changes: git add -A
+  - Commit message uses heredoc for proper formatting
+  - Push immediately after commit
+  - No feature branches (direct to master)
+  - Force-add ignored files if explicitly requested: git add -f
+
+NPM_PUBLISH_WORKFLOW:
+  - Run after git push completes
+  - Command: npm publish
+  - No additional flags needed
+  - Warnings about repository field normalization are expected and safe
+
+TESTING_BEFORE_PUBLISH:
+  - Run: npm test (node test/test.js)
+  - Or: npm run test:browser (browser-based tests)
+  - Tests use local server on port 8889
+  - All tests must pass before publishing
+
+DEPENDENCY_UPDATES:
+  - Update package.json dependency version
+  - Mention dependency update in commit message
+  - Format: "updates to {package}@{version}"
+  - Example: "0.0.18 - ... updates to url-file-db 0.0.8"
+
+RESOLVED_ISSUES:
+  - url-file-db < 0.0.13: Bug where reading non-existent files returned "index" file contents
+    - Fixed in url-file-db 0.0.13+ (properly returns null for non-existent files)
+    - Caused "test sync local to remote" to fail with unexpected "shared content"
+    - url-file-db 0.0.15+ also relaxed path requirements (no longer requires leading "/")
+```
+
+## MODULE_STRUCTURE
+
+```
+EXPORT: create_braid_blob() -> braid_blob_instance
+MODULE_TYPE: CommonJS
+MAIN_ENTRY: index.js
+DEPENDENCIES: [braid-http, url-file-db, fs, path]
+```
+
+## DATA_MODEL
+
+```
+braid_blob_instance = {
+  // Configuration
+  db_folder: string = './braid-blob-db'           // blob storage location
+  meta_folder: string = './braid-blob-meta'       // metadata storage location
+  peer: string | null                             // peer identifier (auto-generated if null)
+
+  // Runtime state
+  cache: object                                   // internal cache
+  key_to_subs: Map<key, Map<peer, subscription>> // subscription tracking
+  db: url_file_db_instance                        // blob storage backend
+  meta_db: url_file_db_instance                   // metadata storage backend
+
+  // Methods
+  init: async () -> void
+  put: async (key, body, options) -> version_string
+  get: async (key, options) -> result_object | null
+  serve: async (req, res, options) -> void
+  sync: async (a, b, options) -> void
+}
+```
+
+## VERSION_SYSTEM
+
+```
+VERSION_FORMAT: "{peer_id}-{timestamp}"
+EXAMPLE: "abc123xyz-1699564820000"
+COMPARISON_RULES:
+  1. Compare numeric length of timestamp
+  2. If equal, lexicographic compare timestamp
+  3. If equal, lexicographic compare full version string
+MERGE_TYPE: last-write-wins (lww)
+```
+
+## METADATA_SCHEMA
+
+```json
+{
+  "event": "peer_id-timestamp",
+  "content_type": "mime/type"
+}
+```
+
+## API_METHODS
+
+### put(key, body, options)
+
+```
+INPUT:
+  key: string | URL
+    - string: local key for storage
+    - URL: remote endpoint for HTTP PUT
+  body: Buffer | string
+  options: {
+    version?: [string]           // explicit version (default: auto-generated)
+    content_type?: string         // MIME type
+    peer?: string                 // peer identifier
+    skip_write?: boolean          // skip disk write (for external changes)
+    signal?: AbortSignal          // for URL mode
+    headers?: object              // for URL mode
+  }
+
+OUTPUT: version_string
+
+SIDE_EFFECTS:
+  - Writes blob to db_folder via url-file-db
+  - Writes metadata to meta_folder/db
+  - Notifies active subscriptions (except originating peer)
+  - If key instanceof URL: makes remote HTTP PUT via braid_fetch
+
+VERSION_LOGIC:
+  - If options.version provided: use options.version[0]
+  - Else: generate "{peer}-{max(Date.now(), last_version_seq+1)}"
+  - Only write if new version > existing version (lww)
+```
+
+### get(key, options)
+
+```
+INPUT:
+  key: string | URL
+    - string: local key to retrieve
+    - URL: remote endpoint for HTTP GET
+  options: {
+    subscribe?: callback(update)  // enable subscription mode
+    header_cb?: callback(result)  // called before body read
+    before_send_cb?: callback(result) // called before subscription starts
+    head?: boolean                // HEAD mode (no body)
+    parents?: [version]           // fork-point for subscriptions
+    version?: [version]           // request specific version
+    peer?: string                 // peer identifier
+    signal?: AbortSignal          // for URL mode
+    dont_retry?: boolean          // for URL mode subscriptions
+  }
+
+OUTPUT:
+  - If subscribe: result_object with unsubscribe callback
+  - If URL + subscribe: Response object or Promise rejection
+  - If URL + !subscribe: ArrayBuffer
+  - If local + !subscribe: {body: Buffer, version: [string], content_type: string}
+  - If not found: null
+
+result_object: {
+  version: [string]
+  content_type?: string
+  body?: Buffer               // only if !subscribe
+  unsubscribe?: function      // only if subscribe
+  sent?: boolean              // true if immediate update sent
+}
+
+SUBSCRIPTION_BEHAVIOR:
+  - Immediate update sent if: no parents OR local_version > parents
+  - Future updates sent when put() called
+  - Subscription callback receives: {body: Buffer, version: [string], content_type: string}
+
+ERROR_HANDLING:
+  - Throws "unkown version: {version}" if requested version > local version
+  - Returns 309 status code via serve() when version unknown
+```
+
+### serve(req, res, options)
+
+```
+INPUT:
+  req: http.IncomingMessage (braidified)
+  res: http.ServerResponse (braidified)
+  options: {
+    key?: string  // override URL-based key extraction
+  }
+
+HTTP_METHOD_MAPPING:
+  GET:
+    - Calls get() with req.subscribe, req.parents, req.version, req.peer
+    - Sets headers: Editable, Accept-Subscribe, Merge-Type, Version/Current-Version
+    - Returns 404 if not found
+    - Returns 406 if Content-Type not in Accept header
+    - Returns 309 if requested version > server version
+
+  HEAD:
+    - Same as GET but no body
+
+  PUT:
+    - Calls put() with body, req.version, req.headers['content-type'], req.peer
+    - Returns Version header with new version
+
+  DELETE:
+    - Deletes from db and meta_db
+    - Returns 204 No Content
+
+  OPTIONS:
+    - Returns empty response
+
+CONCURRENCY:
+  - All operations on same key serialized via within_fiber()
+  - Different keys process in parallel
+```
+
+### sync(a, b, options)
+
+```
+INPUT:
+  a: string | URL  // local key or remote endpoint
+  b: string | URL  // local key or remote endpoint
+  options: {
+    // options.my_unsync set by function, call to stop sync
+  }
+
+OUTPUT: void (async, runs indefinitely)
+
+BEHAVIOR_MATRIX:
+  a=local, b=local:
+    - Bidirectional subscription
+    - Updates to a -> put(b), updates to b -> put(a)
+
+  a=local, b=URL (or a=URL, b=local - swapped internally):
+    - Fork-point detection via HEAD request with local version
+    - If server has local version: subscribe with parents=local_version
+    - If server lacks local version: subscribe without parents (full sync)
+    - Local changes pushed to remote via PUT
+    - Remote changes pulled to local via subscription
+    - Auto-reconnect on error with 1 second delay
+    - Respects options.my_unsync() for clean shutdown
+
+  a=URL, b=URL:
+    - Bidirectional subscription
+    - Updates from a -> put(b), updates from b -> put(a)
+
+ERROR_RECOVERY:
+  - Remote sync: catches errors, disconnects, retries after 1s
+  - Checks 'closed' flag before retry
+  - AbortController cleanup on disconnect
+```
+
+## UTILITY_FUNCTIONS
+
+```
+compare_events(a, b) -> -1 | 0 | 1
+  Compares version strings by timestamp length, then timestamp value, then full string
+
+get_event_seq(event) -> string
+  Extracts timestamp portion after last '-'
+
+ascii_ify(string) -> string
+  Escapes non-ASCII characters as \uXXXX for HTTP headers
+
+version_to_header(version_array) -> string
+  Converts ["v1", "v2"] -> '"v1", "v2"' for HTTP headers
+
+within_fiber(id, func) -> Promise
+  Serializes async operations per ID to prevent race conditions
+
+slurp(req) -> Promise<Buffer>
+  Reads entire HTTP request body
+
+isAcceptable(contentType, acceptHeader) -> boolean
+  Checks if contentType matches Accept header patterns
+```
+
+## STORAGE_LAYOUT
+
+```
+db_folder/
+  {url_file_db structure}
+  - Blob data stored via url-file-db
+  - Key mapping: URL-safe encoding of keys
+
+meta_folder/
+  peer.txt          # Peer ID (auto-generated if missing)
+  db/               # url-file-db for metadata
+    {encoded_key}.txt  # JSON: {event: version, content_type: mime}
+```
+
+## PROTOCOL_DETAILS
+
+```
+HTTP_HEADERS:
+  Request:
+    Subscribe: true                  # enable subscription mode
+    Version: "v1", "v2"             # specific version (for GET)
+    Parents: "v1", "v2"             # fork-point for subscriptions
+    Content-Type: mime/type          # for PUT
+    Accept: mime/type                # for GET (406 if mismatch)
+
+  Response:
+    Version: "v1"                    # for PUT response
+    Current-Version: "v1"            # for subscribed GET
+    Editable: true
+    Accept-Subscribe: true
+    Merge-Type: lww
+    Content-Type: mime/type
+
+STATUS_CODES:
+  200 OK               # successful GET/PUT
+  204 No Content       # successful DELETE
+  309 Custom           # "Version Unknown Here" - requested version not found
+  404 Not Found        # resource doesn't exist
+  406 Not Acceptable   # Content-Type not in Accept header
+
+BRAID_UPDATE_FORMAT:
+  Version: "v1"\r\n
+  Merge-Type: lww\r\n
+  Content-Length: N\r\n
+  \r\n
+  {body}
+```
+
+## KEY_BEHAVIORS
+
+```
+INITIALIZATION:
+  - init() called lazily by put/get/serve
+  - init() runs once (subsequent calls return same promise)
+  - Creates db and meta_db url-file-db instances
+  - Loads or generates peer ID
+
+SUBSCRIPTION_MANAGEMENT:
+  - key_to_subs: Map<string, Map<string, {sendUpdate}>>
+  - Outer key: resource key
+  - Inner key: peer identifier
+  - Prevents echo: put() doesn't notify originating peer
+  - Serialized updates: subscribe_chain ensures sequential callback execution
+
+FILE_WATCHING:
+  - url-file-db monitors db_folder for external changes
+  - External changes trigger put() with skip_write: true
+  - Subscriptions notified of external changes
+
+CONCURRENCY_CONTROL:
+  - within_fiber(key, fn) serializes operations per key
+  - Uses promise chain stored in within_fiber.chains[key]
+  - Prevents concurrent modification of same resource
+  - Automatic cleanup when chain completes
+```
+
+## INTEGRATION_PATTERNS
+
+```
+BASIC_SERVER:
+  require('http').createServer((req, res) => {
+    braid_blob.serve(req, res)
+  }).listen(PORT)
+
+CUSTOM_KEY_MAPPING:
+  braid_blob.serve(req, res, {
+    key: extract_key_from_url(req.url)
+  })
+
+REMOTE_REPLICATION:
+  await braid_blob.sync('local-key', new URL('http://remote/path'))
+
+BIDIRECTIONAL_SYNC:
+  await braid_blob.sync(
+    new URL('http://server1/key'),
+    new URL('http://server2/key')
+  )
+
+PROGRAMMATIC_ACCESS:
+  // Local storage
+  await braid_blob.put('key', Buffer.from('data'), {version: ['v1']})
+  const result = await braid_blob.get('key')
+
+  // Remote storage
+  await braid_blob.put(new URL('http://remote/key'), Buffer.from('data'))
+  const data = await braid_blob.get(new URL('http://remote/key'))
+
+SUBSCRIPTION_EXAMPLE:
+  await braid_blob.get('key', {
+    subscribe: async (update) => {
+      console.log('Version:', update.version)
+      console.log('Body:', update.body.toString())
+    }
+  })
+```
+
+## DEPENDENCIES_DETAIL
+
+```
+braid-http:
+  - http_server (braidify): Adds Braid protocol support to Node.js HTTP
+  - fetch (braid_fetch): Braid-aware fetch implementation
+  - Handles: Subscribe headers, Version headers, streaming updates
+
+url-file-db (^0.0.15):
+  - Bidirectional URL ↔ filesystem mapping
+  - Collision-resistant encoding (case-insensitive filesystem safe)
+  - File watching for external changes
+  - Separate instances for blobs (db) and metadata (meta_db)
+  - API change in 0.0.15: use get_canonical_path() instead of url_path_to_canonical_path()
+  - Fixed in 0.0.13+: properly returns null for non-existent files (not "index" content)
+```
+
+## ERROR_CONDITIONS
+
+```
+"unkown version: {version}"
+  - GET with version/parents newer than local version
+  - Results in 309 status via serve()
+
+AbortError:
+  - sync() handles when AbortController triggered
+  - Ignored silently in local→remote sync
+
+Connection errors (sync):
+  - Caught and trigger reconnect after 1s delay
+  - Stops retry if closed flag set
+
+File not found:
+  - get() returns null for non-existent keys
+  - serve() returns 404
+
+Content-Type mismatch:
+  - serve() returns 406 if Content-Type not in Accept header
+```
+
+## TESTING_INFRASTRUCTURE
+
+```
+TEST_RUNNER: test/test.js
+  - Runs in Node.js or browser
+  - Uses /eval endpoint for isolated test execution
+  - Browser mode: Opens puppeteer, loads test.html
+
+TEST_SUITE: test/tests.js
+  - 40+ test cases covering:
+    - Basic put/get operations
+    - Subscriptions and updates
+    - Version conflict resolution
+    - Remote operations (URL mode)
+    - Sync functionality
+    - Error handling
+    - Edge cases (version unknown, fork-points)
+```

package/index.js

@@ -1,6 +1,5 @@
 var {http_server: braidify, fetch: braid_fetch} = require('braid-http'),
     {url_file_db} = require('url-file-db'),
-    fs = require('fs'),
     path = require('path')
 
 function create_braid_blob() {
@@ -9,9 +8,8 @@ function create_braid_blob() {
         meta_folder: './braid-blob-meta',
         cache: {},
         key_to_subs: {},
-        peer: null, // we'll try to load this from a file, if not set by the user
-        db: null, // url-file-db instance for blob storage
-        meta_db: null // url-file-db instance for meta storage
+        peer: null, // will be auto-generated if not set by the user
+        db: null // url-file-db instance with integrated meta storage
     }
 
     braid_blob.init = async () => {
@@ -21,25 +19,20 @@ function create_braid_blob() {
         await braid_blob.init()
 
         async function real_init() {
-            // Create url-file-db instance for blob storage
-            braid_blob.db = await url_file_db.create(braid_blob.db_folder, async (key) => {
-                // File changed externally, notify subscriptions
-                var body = await braid_blob.db.read(key)
-                await braid_blob.put(key, body, { skip_write: true })
-            })
-
-            // Create url-file-db instance for meta storage (in a subfolder)
-            // This will create both meta_folder and the db subfolder with recursive: true
-            braid_blob.meta_db = await url_file_db.create(`${braid_blob.meta_folder}/db`)
+            // Create url-file-db instance with integrated meta storage
+            braid_blob.db = await url_file_db.create(
+                braid_blob.db_folder,
+                braid_blob.meta_folder,
+                async (key) => {
+                    // File changed externally, notify subscriptions
+                    var body = await braid_blob.db.read(key)
+                    await braid_blob.put(key, body, { skip_write: true })
+                }
+            )
 
-            // establish a peer id (stored at root of meta_folder, sibling to db subfolder)
-            if (!braid_blob.peer)
-                try {
-                    braid_blob.peer = await fs.promises.readFile(`${braid_blob.meta_folder}/peer.txt`, 'utf8')
-                } catch (e) {}
+            // establish a peer id if not already set
             if (!braid_blob.peer)
                 braid_blob.peer = Math.random().toString(36).slice(2)
-            await fs.promises.writeFile(`${braid_blob.meta_folder}/peer.txt`, braid_blob.peer)
         }
     }
 
@@ -69,11 +62,8 @@ function create_braid_blob() {
 
         await braid_blob.init()
 
-        // Read the meta data from meta_db
-        var meta = {}
-        var meta_content = await braid_blob.meta_db.read(key)
-        if (meta_content)
-            meta = JSON.parse(meta_content.toString('utf8'))
+        // Read the meta data using new meta API
+        var meta = braid_blob.db.get_meta(key) || {}
 
         var their_e =
             !options.version ?
@@ -93,11 +83,12 @@ function create_braid_blob() {
             if (!options.skip_write)
                 await braid_blob.db.write(key, body)
 
-            // Write the meta data
+            // Update only the fields we want to change in metadata
+            var meta_updates = { event: their_e }
             if (options.content_type)
-                meta.content_type = options.content_type
+                meta_updates.content_type = options.content_type
 
-            await braid_blob.meta_db.write(key, JSON.stringify(meta))
+            await braid_blob.db.update_meta(key, meta_updates)
 
             // Notify all subscriptions of the update
             // (except the peer which made the PUT request itself)
@@ -153,11 +144,8 @@ function create_braid_blob() {
 
         await braid_blob.init()
 
-        // Read the meta data from meta_db
-        var meta = {}
-        var meta_content = await braid_blob.meta_db.read(key)
-        if (meta_content)
-            meta = JSON.parse(meta_content.toString('utf8'))
+        // Read the meta data using new meta API
+        var meta = braid_blob.db.get_meta(key) || {}
         if (meta.event == null) return null
 
         var result = {
@@ -223,7 +211,10 @@ function create_braid_blob() {
     braid_blob.serve = async (req, res, options = {}) => {
         await braid_blob.init()
 
-        if (!options.key) options.key = url_file_db.get_key(req.url)
+        if (!options.key) {
+            var url = new URL(req.url, 'http://localhost')
+            options.key = url_file_db.get_canonical_path(url.pathname)
+        }
 
         braidify(req, res)
         if (res.is_multiplexer) return
@@ -235,12 +226,6 @@ function create_braid_blob() {
         var body = req.method === 'PUT' && await slurp(req)
 
         await within_fiber(options.key, async () => {
-            // Read the meta data from meta_db
-            var meta = {}
-            var meta_content = await braid_blob.meta_db.read(options.key)
-            if (meta_content)
-                meta = JSON.parse(meta_content.toString('utf8'))
-
             if (req.method === 'GET' || req.method === 'HEAD') {
                 if (!res.hasHeader("editable")) res.setHeader("Editable", "true")
                 if (!req.subscribe) res.setHeader("Accept-Subscribe", "true")
@@ -298,16 +283,15 @@ function create_braid_blob() {
                 }
             } else if (req.method === 'PUT') {
                 // Handle PUT request to update binary files
-                meta.event = await braid_blob.put(options.key, body, {
+                var event = await braid_blob.put(options.key, body, {
                     version: req.version,
                     content_type: req.headers['content-type'],
                     peer: req.peer
                 })
-                res.setHeader("Version", version_to_header(meta.event != null ? [meta.event] : []))
+                res.setHeader("Version", version_to_header(event != null ? [event] : []))
                 res.end('')
             } else if (req.method === 'DELETE') {
                 await braid_blob.db.delete(options.key)
-                await braid_blob.meta_db.delete(options.key)
                 res.statusCode = 204 // No Content
                 res.end('')
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braid-blob",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Library for collaborative blobs over http using braid.",
   "author": "Braid Working Group",
   "repository": "braid-org/braid-blob",
@@ -11,6 +11,6 @@
   },
   "dependencies": {
     "braid-http": "~1.3.82",
-    "url-file-db": "~0.0.8"
+    "url-file-db": "^0.0.19"
   }
 }

package/test/tests.js

@@ -34,7 +34,7 @@ runTest(
 )
 
 runTest(
-    "test that peer is same the second time we run from same db folder",
+    "test that peer is different each time we create a new instance",
     async () => {
         var r1 = await braid_fetch(`/eval`, {
             method: 'POST',
@@ -62,7 +62,7 @@ runTest(
                 await require('fs').promises.rm(db, { recursive: true, force: true })
                 await require('fs').promises.rm(meta, { recursive: true, force: true })
 
-                res.end('' + (bb1.peer === bb2.peer))
+                res.end('' + (bb1.peer !== bb2.peer))
             })()`
         })
         return await r1.text()
@@ -100,6 +100,39 @@ runTest(
     'test_peer'
 )
 
+runTest(
+    "test that manually set peer persists through initialization",
+    async () => {
+        var r1 = await braid_fetch(`/eval`, {
+            method: 'POST',
+            body: `void (async () => {
+                var test_id = 'test-db-' + Math.random().toString(36).slice(2)
+                var db = __dirname + '/' + test_id + '-db'
+                var meta = __dirname + '/' + test_id + '-meta'
+
+                // Create instance with manually set peer
+                var bb1 = braid_blob.create_braid_blob()
+                bb1.db_folder = db
+                bb1.meta_folder = meta
+                bb1.peer = 'custom-peer-id-123'
+
+                // Initialize (should keep our custom peer)
+                await bb1.init()
+
+                var peer_after_init = bb1.peer
+
+                // Clean up
+                await require('fs').promises.rm(db, { recursive: true, force: true })
+                await require('fs').promises.rm(meta, { recursive: true, force: true })
+
+                res.end(peer_after_init === 'custom-peer-id-123' ? 'true' : 'false: ' + peer_after_init)
+            })()`
+        })
+        return await r1.text()
+    },
+    'true'
+)
+
 runTest(
     "test that PUTing with shorter event id doesn't do anything.",
     async () => {
@@ -1142,6 +1175,140 @@ runTest(
     '309'
 )
 
+runTest(
+    "test multiple writes preserve correct mtime across restarts",
+    async () => {
+        var r1 = await braid_fetch(`/eval`, {
+            method: 'POST',
+            body: `void (async () => {
+                var fs = require('fs').promises
+                var test_id = 'test-multi-write-' + Math.random().toString(36).slice(2)
+                var db_folder = __dirname + '/' + test_id + '-db'
+                var meta_folder = __dirname + '/' + test_id + '-meta'
+                var test_key = 'test-file'
+
+                try {
+                    // Create first braid_blob instance
+                    var bb1 = braid_blob.create_braid_blob()
+                    bb1.db_folder = db_folder
+                    bb1.meta_folder = meta_folder
+
+                    // First write
+                    await bb1.put(test_key, Buffer.from('content1'), {
+                        version: ['version-1']
+                    })
+
+                    // Wait a bit to ensure different mtime
+                    await new Promise(resolve => setTimeout(resolve, 50))
+
+                    // Second write to same file (this is where the bug would occur)
+                    await bb1.put(test_key, Buffer.from('content2'), {
+                        version: ['version-2']
+                    })
+
+                    var result1 = await bb1.get(test_key)
+
+                    // Now restart and check
+                    var bb2 = braid_blob.create_braid_blob()
+                    bb2.db_folder = db_folder
+                    bb2.meta_folder = meta_folder
+
+                    // This should NOT trigger a file change callback
+                    var result2 = await bb2.get(test_key)
+
+                    // Version should still be version-2, not regenerated
+                    var correct_version = (result2.version[0] === 'version-2')
+                    var content_correct = (result2.body.toString() === 'content2')
+
+                    // Clean up
+                    await fs.rm(db_folder, { recursive: true, force: true })
+                    await fs.rm(meta_folder, { recursive: true, force: true })
+
+                    res.end(correct_version && content_correct ? 'true' :
+                            'false: version=' + result2.version[0] + ', content=' + result2.body.toString())
+                } catch (e) {
+                    // Clean up even on error
+                    await fs.rm(db_folder, { recursive: true, force: true })
+                    await fs.rm(meta_folder, { recursive: true, force: true })
+                    res.end('error: ' + e.message)
+                }
+            })()`
+        })
+        return await r1.text()
+    },
+    'true'
+)
+
+runTest(
+    "test that files keep same event ID across restarts when not edited",
+    async () => {
+        var r1 = await braid_fetch(`/eval`, {
+            method: 'POST',
+            body: `void (async () => {
+                var fs = require('fs').promises
+                var test_id = 'test-persist-event-' + Math.random().toString(36).slice(2)
+                var db_folder = __dirname + '/' + test_id + '-db'
+                var meta_folder = __dirname + '/' + test_id + '-meta'
+                var test_key = 'test-file'
+                var test_content = 'test content that should not change'
+
+                try {
+                    // Create first braid_blob instance
+                    var bb1 = braid_blob.create_braid_blob()
+                    bb1.db_folder = db_folder
+                    bb1.meta_folder = meta_folder
+
+                    // Put a file with specific version
+                    var version1 = await bb1.put(test_key, Buffer.from(test_content), {
+                        version: ['test-peer-123456']
+                    })
+
+                    // Get the file to verify it has the expected version
+                    var result1 = await bb1.get(test_key)
+
+                    // Check what metadata was saved
+                    var meta1 = bb1.db.get_meta(test_key)
+                    var debug_info = 'meta1: ' + JSON.stringify(meta1) + '; '
+
+                    // Wait a bit to ensure file system has settled
+                    await new Promise(resolve => setTimeout(resolve, 100))
+
+                    // Now create a second braid_blob instance with the same folders
+                    // This simulates a restart
+                    var bb2 = braid_blob.create_braid_blob()
+                    bb2.db_folder = db_folder
+                    bb2.meta_folder = meta_folder
+
+                    // Initialize bb2 by doing a get (this triggers init)
+                    var result2 = await bb2.get(test_key)
+
+                    // Check what metadata bb2 sees
+                    var meta2 = bb2.db.get_meta(test_key)
+                    debug_info += 'meta2: ' + JSON.stringify(meta2) + '; '
+
+                    // The version should be the same - no new event ID generated
+                    var versions_match = (result1.version[0] === result2.version[0])
+                    var both_have_expected = (result1.version[0] === 'test-peer-123456')
+
+                    // Clean up
+                    await fs.rm(db_folder, { recursive: true, force: true })
+                    await fs.rm(meta_folder, { recursive: true, force: true })
+
+                    res.end(versions_match && both_have_expected ? 'true' :
+                            'false: v1=' + result1.version[0] + ', v2=' + result2.version[0] + ' | ' + debug_info)
+                } catch (e) {
+                    // Clean up even on error
+                    await fs.rm(db_folder, { recursive: true, force: true })
+                    await fs.rm(meta_folder, { recursive: true, force: true })
+                    res.end('error: ' + e.message)
+                }
+            })()`
+        })
+        return await r1.text()
+    },
+    'true'
+)
+
 }
 
 // Export for Node.js (CommonJS)

package/.claude/settings.local.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node test/test.js:*)",
-      "Bash(lsof:*)",
-      "Bash(xargs kill -9)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}