arcane-os 0.28.1 → 0.28.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+  `https://<current hostname>/404.html`, using the request's HTTP/1 Host or
+  HTTP/2 authority and omitting the API listener port. The redirect has an empty
+  body and uses the existing HTTP server response interface.
+- Preserve `/v1/mail` requests with query strings, CORS and OPTIONS behavior,
+  method and API errors, subscription handling, and the complete Mail provider
+  and cancellation lifecycle. Client APIs, npm resource paths, dependencies,
+  and listener configuration are unchanged.
+
 ## 0.28.1
 
 - DBOPFS initialization opens the application's existing storage scope without

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.1` 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/mail.md

@@ -712,6 +712,22 @@ browser and gateway preserve complete request and response content without
 body-size gates. With no event observer, the gateway does not construct event
 payloads or parse a second provider-request representation for observation.
 
+Requests whose path does not match `/v1/mail` receive `303 See Other` with an
+empty body and `Location: https://<current-hostname>/404.html`. The destination
+uses the request's HTTP/2 authority or HTTP/1.1 Host hostname, omits the API port,
+and replaces the requested path and query. For example:
+
+| Unmatched request URL | Redirect destination |
+| --- | --- |
+| `https://mail.thewizardnexus.com:4433/` | `https://mail.thewizardnexus.com/404.html` |
+| `https://mail.precrisis.ai:4433/missing?example=1` | `https://mail.precrisis.ai/404.html` |
+
+The HTTPS website on the current hostname owns that page. The mail listener
+only returns the redirect. Requests to `/v1/mail`, including its query-bearing
+form, retain the existing CORS policy, OPTIONS preflight, method handling, and
+structured API errors. For example, `GET /v1/mail` still receives `405`.
+Subscription verification and its automatic same-IP exception remain unchanged.
+
 The gateway returns `202` only after Resend returns a nonempty string provider id.
 Transport loss, an explicit caller-selected timeout, an invalid success body,
 or an unreadable provider response returns an explicit uncertain result and never claims

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/docs/reviews/mail-server-purpose-review.md

@@ -4,6 +4,9 @@ The [same-IP subscription exception follow-up](#same-ip-subscription-exception-f
 records the later user-selected change to when the optional verifier runs. The
 earlier inventories retain their stated historical scope; current verification
 skips requests whose actual connection source and destination IPs are equal.
+The [unmatched-route redirect follow-up](#unmatched-route-redirect-follow-up)
+records the later change from a missing-route JSON error to the hostname's
+HTTPS 404 page.
 
 | Decision | Behavior | Why it matters | Source status at this review |
 | --- | --- | --- | --- |
@@ -601,3 +604,28 @@ This follow-up records the selected behavior and source review. No local test,
 check, build, server launch, live mail send, or platform execution was performed
 by this documentation author. Release and runtime evidence remain with the
 corresponding operation's owner.
+
+## Unmatched-route redirect follow-up
+
+The user selected the Stripe server's redirect behavior for unmatched mail
+routes. The existing SDK `handleMailRequest` route decision owns this behavior:
+an unmatched path returns `303 See Other` with an empty body and a Location of
+`https://<current-hostname>/404.html`. The request authority supplies the hostname;
+the destination omits the API port and replaces the original path and query.
+The website on that hostname owns the page content.
+
+| Method or action | Gate 1: Do we care? | Gate 2: Why is it worth the work? | Gate 3: Can we remove it without losing the required result? | Decision and concrete effect |
+| --- | --- | --- | --- | --- |
+| Unmatched-path JSON `404` response | No. The selected result is navigation to the hostname's 404 page. | Keeping it would preserve the superseded response instead of the requested navigation. | Yes, when replaced with the redirect at the existing route decision. | Replace only this response with `303` and an empty body. |
+| Current-hostname HTTPS redirect without the API port | Yes. It sends visitors to the requested website page. | One request-authority parse supplies the hostname for every deployment without another setting or domain table. | No. Removing it loses the explicitly selected destination. | Keep the decision inline in the existing native request handler; add no server, dependency, proxy, or file-serving path. |
+| Matched `/v1/mail` CORS, OPTIONS, method errors, subscription verification, same-IP exception, and delivery results | Yes. Existing applications depend on these mail contracts. | An unmatched navigation does not change how an actual API request is handled or reported. | No. Redirecting actual API failures would hide the caller's delivery outcome. | Preserve `/v1/mail` and its query-bearing form, including OPTIONS preflight, `405` for unsupported methods, and structured API errors. |
+
+An unmatched request ends at its existing route branch without entering
+subscription verification, report parsing, or provider delivery. There is one
+redirect response per unmatched request, with no new asynchronous wait, DNS
+lookup, configuration read, timer, or retained state. This is a source-level
+operation description; no timing improvement or deployed result is claimed.
+
+This follow-up is based on source review. This documentation author ran no local
+tests, checks, builds, server launches, or production requests. Delivery and
+selected-package verification remain with their respective owners.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.28.1",
+  "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",
@@ -85,7 +85,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

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.
      *

package/src/mail-server.mjs

@@ -877,8 +877,21 @@ function createConfiguredMailHandler(configuration){
         });
 
         try{
-            if(request.url!==RESEND_MAIL_PATH&&!request.url?.startsWith(`${RESEND_MAIL_PATH}?`)){
-                throw new MailGatewayFault('mail_route_not_found',{statusCode:404});
+            if (request.url !== RESEND_MAIL_PATH && !request.url?.startsWith(`${RESEND_MAIL_PATH}?`)) {
+                const requestAuthority = request.authority || request.headers.host || '';
+                const hostname = new URL(`https://${requestAuthority}`).hostname;
+                response.writeHead(
+                    303,
+                    {
+                        'content-type': 'text/plain; charset=utf-8',
+                        'location': `https://${hostname}/404.html`
+                    }
+                );
+                response.end();
+                if (!request.readableEnded && !request.destroyed) {
+                    request.resume();
+                }
+                return;
             }
             const requestOrigin=request.headers.origin;
             if(requestOrigin){