arcane-os 0.28.2 → 0.28.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.28.3
+
+- Add explicit `DBOPFS.removeEmptyTable(tableName)` for removing an existing
+  empty table directory through native non-recursive OPFS removal. It reports
+  `removed`, `absent`, or `not-empty` and preserves nonempty tables and file
+  targets without creating, scanning, or clearing them.
+- Invalidate the logical/physical table alias and cached handles after removal
+  or confirmed absence. Existing recursive `deleteTable()` and
+  `clearAllStorage()` behavior remains unchanged. This release performs no
+  automatic cleanup or saved-data migration; npm paths and dependencies remain
+  unchanged.
+
 ## 0.28.2
 
 - Redirect unmatched Mail server routes with `303 See Other` to

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.28.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.28.3` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/inventory/runtime-modules.json

@@ -550,11 +550,11 @@
         "DBOPFS_REASONS",
         "default"
       ],
-      "summary": "Provides app-scoped OPFS tables, worker I/O, backup/restore, compression, and CRUD/batch APIs.",
+      "summary": "Provides app-scoped OPFS tables, explicit non-recursive empty-table removal, worker I/O, backup/restore, compression, and CRUD/batch APIs.",
       "availability": "Browser / native WebView",
       "protocol": "OPFS, DBOPFSWorker, Compression Streams, and per-realm globalThis.arcaneEvents authority",
-      "normalization": "App scope and recognized file parsing are normalized; nonblank unreadable JSONL rows remain complete raw strings, and DOM/storage errors are preserved.",
-      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs."
+      "normalization": "App scope and recognized file parsing are normalized; nonblank unreadable JSONL rows remain complete raw strings, empty-table removal reports removed, absent, or not-empty after a create:false directory lookup and without scanning or recursively clearing a directory, same-named files are preserved, aliases and cached handles are invalidated only when the directory is gone, and unexpected DOM/storage errors are preserved.",
+      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs including removeEmptyTable(tableName)."
     },
     {
       "file": "runtime/arcane/modules/DBOPFSDocumentLibrary.js",

package/docs/reference/runtime-modules.md

@@ -1783,7 +1783,7 @@ Provides app-scoped OPFS tables, worker I/O, backup/restore, compression, and CR
 
 ### Public surface
 
-default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs.
+default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs. `removeEmptyTable(tableName)` resolves one explicitly selected existing directory without creating or scanning it, then removes it only when OPFS confirms that it is empty. It never creates, clears, or recursively removes the target. It resolves a mutable record with `status` set to `removed`, `absent`, or `not-empty`, the matching `removed` boolean, and the logical `tableName` plus physical `directoryName`; a same-named file and unexpected platform errors reject without removal.
 
 Exact exports: `DBOPFS_EVENT_TYPES`, `DBOPFS_REASONS`, `default`.
 
@@ -1793,7 +1793,10 @@ Exact exports: `DBOPFS_EVENT_TYPES`, `DBOPFS_REASONS`, `default`.
 are normalized. Each readable JSONL row becomes its parsed value; a nonblank
 unreadable row remains in its original string form so the owning application
 can display, diagnose, or recover it without silent data loss. DOM and storage
-errors remain observable. Transport: OPFS, DBOPFSWorker, Compression Streams.
+errors remain observable. The logical `memories` table continues to map to the
+physical `memory` directory, and successful or already-absent empty-table
+removal invalidates both alias and cached-handle state. Transport: OPFS,
+DBOPFSWorker, Compression Streams.
 [Deep protocol details](protocols.md).
 
 ### Example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.28.2",
+  "version": "0.28.3",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/modules/DBOPFS.js

@@ -286,6 +286,25 @@ class DBOPFS {
         return `${tableName}:${fileName}`
     }
 
+    /**
+     * Invalidates every known cache key for one logical/physical table pair.
+     * @private
+     * @param {string} tableName
+     * @param {string} directoryName
+     * @param {string} registeredTableName
+     */
+    #forgetTable(tableName,directoryName,registeredTableName){
+        for(const name of new Set([
+            tableName,
+            directoryName,
+            registeredTableName
+        ])){
+            delete this.#tables[name]
+            delete this.#tableHandles[name]
+            delete this.#tableHandlePromises[name]
+        }
+    }
+
     /** @type {boolean} */
     ready=false;
 
@@ -825,6 +844,66 @@ class DBOPFS {
         return true
     }
 
+    /**
+     * Removes one existing table only when its physical directory is empty.
+     * The target is resolved as an existing directory without creating or
+     * scanning it. Native non-recursive OPFS removal owns the emptiness
+     * decision, so this method never clears or recursively removes a table.
+     *
+     * @param {string} tableName
+     * @returns {Promise<{
+     *   status:'removed'|'absent'|'not-empty',
+     *   removed:boolean,
+     *   tableName:string,
+     *   directoryName:string
+     * }>}
+     */
+    async removeEmptyTable(tableName){
+        if(!this.ready){
+            await this.readyPromise;
+        }
+
+        const directoryName=directoryNameForTable(tableName);
+        const registeredTableName=tableNameForDirectory(directoryName);
+
+        try{
+            await this.#db.getDirectoryHandle(directoryName,{create:false})
+            await this.#db.removeEntry(directoryName)
+        }catch(error){
+            if(error.name==='InvalidModificationError'){
+                return {
+                    status:'not-empty',
+                    removed:false,
+                    tableName:registeredTableName,
+                    directoryName
+                }
+            }
+
+            if(error.name!=='NotFoundError'){
+                arcaneLogging.error(error)
+                throw error
+            }
+
+            this.#forgetTable(tableName,directoryName,registeredTableName)
+
+            return {
+                status:'absent',
+                removed:false,
+                tableName:registeredTableName,
+                directoryName
+            }
+        }
+
+        this.#forgetTable(tableName,directoryName,registeredTableName)
+
+        return {
+            status:'removed',
+            removed:true,
+            tableName:registeredTableName,
+            directoryName
+        }
+    }
+
     /**
      * Clears only the current application's OPFS database.
      *