arcane-os 0.28.0 → 0.28.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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
+  creating product-specific table directories. Applications create the tables
+  they need through the existing `getTableHandle(name)` API after readiness.
+- Create tables on demand and coalesce concurrent requests for the same physical
+  table. Logical `memories` and physical `memory` retain one shared handle and
+  deletion path. Existing directory discovery, complete reads and exports, CRUD,
+  worker fallback, events, application identity and saved data remain supported.
+- Explicit `clearAllStorage()` leaves the cleared application scope empty rather
+  than recreating default folders. This update performs no saved-data migration
+  or automatic removal of existing folders. The 0.28.0 npm resource paths remain
+  unchanged.
+
 ## 0.28.0
 
 - Expose existing runtime modules and entities directly through

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.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.28.2` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

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/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.0",
+  "version": "0.28.2",
   "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/components/file-manager.html

@@ -1905,7 +1905,7 @@
         let tableNames=dirs;
 
         if(!tableNames?.length){
-            tableNames=await dbopfs.getTableNames(Boolean(layout));
+            tableNames=await dbopfs.getTableNames(true);
         }
         if(destroyed||sequence!==gridLoadSequence){
             return [];

package/runtime/arcane/modules/DBOPFS.js

@@ -16,20 +16,20 @@ const dbopfsReasons={
 export const DBOPFS_EVENT_TYPES={...dbopfsEventTypes};
 export const DBOPFS_REASONS={...dbopfsReasons};
 
-const DEFAULT_TABLE_DIRECTORIES={
-    users:'users',
-    scores:'scores',
-    chats:'chats',
-    notes:'notes',
-    documents:'documents',
-    songs:'songs',
-    images:'images',
-    journal_entries:'journal_entries',
-    streams_of_consciousness:'streams_of_consciousness',
-    reports:'reports',
-    errors:'errors',
+const TABLE_DIRECTORY_ALIASES={
     memories:'memory'
 };
+const DIRECTORY_TABLE_ALIASES={
+    memory:'memories'
+};
+
+function directoryNameForTable(tableName=''){
+    return TABLE_DIRECTORY_ALIASES[tableName]||tableName;
+}
+
+function tableNameForDirectory(directoryName=''){
+    return DIRECTORY_TABLE_ALIASES[directoryName]||directoryName;
+}
 
 function parseFileValue(fileName='',textContent=''){
     let value=textContent;
@@ -79,6 +79,11 @@ if(navigator.storage?.persist){
  * Handles to directories inside OPFS.
  */
 
+/**
+ * @typedef {Object<string,Promise<FileSystemDirectoryHandle>>} DBOPFSTableHandlePromises
+ * Pending table handle requests keyed by logical table name.
+ */
+
 /**
  * @typedef {Object<string,Promise>} DBOPFSWriteLocks
  * Promise based write locks to serialize writes to the same file.
@@ -119,6 +124,9 @@ class DBOPFS {
     /** @type {DBOPFSTableHandles} */
     #tableHandles={}
 
+    /** @type {DBOPFSTableHandlePromises} */
+    #tableHandlePromises={}
+
     /** @type {DBOPFSTables} */
     #tables={}
 
@@ -297,7 +305,7 @@ class DBOPFS {
     }
 
     /**
-     * Initializes OPFS database and default tables.
+     * Initializes the application OPFS database scope.
      * Dispatches `dbopfs-ready` event when complete.
      *
      * @returns {Promise<void>}
@@ -313,7 +321,6 @@ class DBOPFS {
         this.#applicationId=scope.applicationId;
         this.#storagePath=scope.path;
         this.#db=scope.directory;
-        await this.#createDefaultTables();
 
         this.ready=true;
 
@@ -338,15 +345,6 @@ class DBOPFS {
         projectArcaneDOMEvent(window,occurrence);
     }
 
-    async #createDefaultTables(){
-        for(const [alias,directoryName]of Object.entries(DEFAULT_TABLE_DIRECTORIES)){
-            this.#tableHandles[alias]=await this.#db.getDirectoryHandle(
-                directoryName,
-                {create:true}
-            );
-        }
-    }
-
     /**
      * Canonical application identity owning this database.
      *
@@ -403,19 +401,49 @@ class DBOPFS {
             await this.readyPromise;
         }
 
-        if(!this.#tableHandles[tableName]){
-            const existingHandle=Object.values(this.#tableHandles).find(
-                handle=>handle.name===tableName
-            )
+        const directoryName=directoryNameForTable(tableName);
+        const registeredTableName=tableNameForDirectory(directoryName);
 
-            if(existingHandle){
-                return existingHandle
+        if(this.#tableHandles[registeredTableName]){
+            return this.#tableHandles[registeredTableName];
+        }
+
+        const existingHandle=Object.values(this.#tableHandles).find(
+            function matchingTableDirectory(handle){
+                return handle.name===directoryName;
             }
+        );
 
-            this.#tableHandles[tableName]=await this.#db.getDirectoryHandle(tableName,{create:true});
+        if(existingHandle){
+            this.#tableHandles[registeredTableName]=existingHandle;
+            return existingHandle;
         }
 
-        return this.#tableHandles[tableName];
+        if(!this.#tableHandlePromises[registeredTableName]){
+            const handlePromise=this.#db.getDirectoryHandle(
+                directoryName,
+                {create:true}
+            ).then(
+                function registerRequestedTable(handle){
+                    this.#tableHandles[registeredTableName]=handle;
+                    return handle;
+                }.bind(this)
+            );
+            this.#tableHandlePromises[registeredTableName]=handlePromise;
+
+            function clearTableHandlePromise(){
+                if(this.#tableHandlePromises[registeredTableName]===handlePromise){
+                    delete this.#tableHandlePromises[registeredTableName];
+                }
+            }
+
+            handlePromise.then(
+                clearTableHandlePromise.bind(this),
+                clearTableHandlePromise.bind(this)
+            );
+        }
+
+        return this.#tableHandlePromises[registeredTableName];
     }
 
     /**
@@ -779,11 +807,17 @@ class DBOPFS {
      * @returns {Promise<boolean>}
      */
     async deleteTable(tableName){
+        const directoryName=directoryNameForTable(tableName);
+        const registeredTableName=tableNameForDirectory(directoryName);
+
         try{
-            await this.#db.removeEntry(tableName,{recursive:true})
+            await this.#db.removeEntry(directoryName,{recursive:true})
 
             delete this.#tables[tableName]
-            delete this.#tableHandles[tableName]
+            delete this.#tables[directoryName]
+            delete this.#tables[registeredTableName]
+            delete this.#tableHandles[registeredTableName]
+            delete this.#tableHandlePromises[registeredTableName]
         }catch(error){
             arcaneLogging.error(error)
         }
@@ -807,8 +841,8 @@ class DBOPFS {
 
         this.#tables={}
         this.#tableHandles={}
+        this.#tableHandlePromises={}
         this.#writeLocks={}
-        await this.#createDefaultTables()
 
         return this
     }
@@ -864,12 +898,15 @@ class DBOPFS {
                 continue
             }
 
+            const registeredTableName=tableNameForDirectory(name);
             const registered=Object.values(this.#tableHandles).some(
-                tableHandle=>tableHandle.name===name
-            )
+                function matchingDiscoveredDirectory(tableHandle){
+                    return tableHandle.name===name;
+                }
+            );
 
             if(!registered){
-                this.#tableHandles[name]=handle
+                this.#tableHandles[registeredTableName]=handle
             }
 
             tableNames.push(name)

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){