arcane-os 0.24.1 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.26.0
+
+- Add explicit installed-package browser runtime routes. Source development,
+  managed import maps, application test-map resolution, and PWA resource
+  selection can use the npm dependency directly without a generated workspace
+  runtime or lock. Keep existing browser URLs, aliases, and materialized layouts.
+- Let a shared package route select its complete source directory with
+  `include: ["."]`. Portable app output includes the selected runtime,
+  dependencies, assets, and notices without requiring the SDK at deployment.
+- Expose lowercase public module subpaths for shared AI preferences, provider
+  state, model definitions, conversation helpers, application data, document
+  libraries, and local AI readiness. Browser maps and Node package resolution
+  select the same canonical implementations; browser runtime requirements remain.
+- Share the existing portable Mail aggregation with browser import maps while
+  preserving the `arcane-os/mail` API and Node mail CLI used by server consumers.
+
+## 0.25.0
+
+- Automatically skip configured mail subscription verification when the actual
+  requester connection IP equals the server-side IP of that connection. This
+  lets services sharing that IP and local development send without a subscription
+  key. Other requester IPs, including other intranet machines, still use the
+  configured verification callback.
+- Use native connection addresses for HTTP/1 and HTTP/2, with no environment
+  setting, domain lookup, forwarded-header interpretation, or special loopback rule.
+  Preserve CORS, report handling, provider delivery, and existing caller APIs.
+- Document the IP rule and its purpose gates; update focused test source for
+  the exemption and the remaining subscription-verification paths.
+
 ## 0.24.1
 
 - Add a mail CLI parameter table with command scope, purpose, and defaults.

package/README.md

@@ -19,10 +19,19 @@ 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.24.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.26.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
+External browser apps can use the installed npm package directly, without a
+generated workspace `arcane/` directory or `arcane.lock.json`. Select the
+[four installed-package routes](docs/reference/protocols.md#installed-package-browser-routes)
+in `arcane-packager.json`: development, managed import maps, and PWA resources
+read the installed SDK while keeping `/arcane/...` browser URLs. Portable app
+packages still contain their selected runtime. Existing materialized workspaces
+and the scaffold's current layout remain supported. Node services continue to
+use the installed CLI or public imports such as `arcane-os/mail`.
+
 The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433
 by default. Configure its host, port, origin list, certificate paths, and other
 mail settings in `arcane.config.json.mail`; keep provider keys in the ignored
@@ -31,7 +40,11 @@ Existing root credential, profile, and TLS settings remain supported. Browser
 mail defaults to `/v1/mail` on the current domain, and multiple applications can
 share one server with explicit allowed origins. Subscription verification is disabled
 until a `verifySubscription` callback is configured; that callback receives the
-application name and bearer subscription key before each provider attempt.
+application name and bearer subscription key before provider attempts from other
+requester IPs. Requests whose actual connection source IP equals the server-side
+IP of that connection automatically skip subscription verification, including
+local development. Other intranet machines still need verification. The exception
+requires no environment setting or domain lookup.
 See the [method and action gate report](docs/reviews/mail-server-purpose-review.md)
 for the removals, retained responsibilities, and naming decisions.
 
@@ -58,7 +71,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.12.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.26.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

package/docs/architecture.md

@@ -84,13 +84,22 @@ runtime materialization, serving, and coordination with other writers. This
 path requires no application descriptor or `apps/<id>/` layout and leaves the
 app-scoped toolchain operation unchanged.
 
-An external workspace maps the exact runtime shipped by its locked `arcane-os`
-dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
+An external workspace can select `installed-v1` routes directly from its
+`node_modules/arcane-os` installation, without a workspace `arcane/` tree or
+`arcane.lock.json`. The SDK reads the installed package version and maps its
+runtime, browser runtime, runtime dependency, and licenses to the established
+browser destinations. Existing `physical-v1` workspaces and the explicit
+materializer remain supported; scaffolding retains its existing physical
+layout. See [installed-package routes](reference/protocols.md#installed-package-browser-routes)
+for the configuration and npm-alias form.
+
+An Arcane OS checkout is an integrated SDK consumer, not the owner
 of portable runtime source. For live shared development, the explicit
 development-only SDK source mount maps the canonical SDK runtime and dependency
-paths into that consumer. Without the mount, the workspace uses its locked SDK
-projection. The development server and packager consume the same route
-destinations in both cases, so app imports do not change. Integrated
+paths into that consumer. Without the mount, integrated workspaces retain their
+physical projection; external workspaces select either layout above. The development server,
+import-map generator, packager, and PWA inventory consume the same route
+destinations, so app imports do not change. Integrated
 initialization creates only app-owned files and never rewrites Arcane OS or SDK
 root configuration.
 
@@ -235,13 +244,14 @@ exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
 apps synthesize that descriptor from their schema-1 package plus the current
 native registry during migration.
 
-An external app's `arcane-packager.json` has three exact shared routes. They map
-the installed SDK runtime to `/arcane`, its vendored strong-type dependency to
-`/node_modules/strong-type`, and the SDK's `LICENSE`,
-`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. Development does
-not copy SDK runtime source into the app repository. Distribution materializes
-those selected SDK routes completely inside the portable artifact, so the
-finished app has no Arcane OS runtime dependency.
+An external app can use four `installed-v1` shared routes in
+`arcane-packager.json`: the installed SDK's `runtime/arcane` maps to `/arcane`,
+`browser-runtime` to `/arcane/sdk`, `runtime/strong-type` to
+`/arcane/dependencies/strong-type`, and its three license files to
+`/licenses/arcane-os`. Source serving and import-map generation read those
+installed files without creating a workspace runtime copy. Distribution copies
+the selected routes completely inside the portable artifact, preserving the
+same URLs. Existing physical `arcane/` routes retain their behavior.
 
 Release schema 1 and builder identity `arcane-app-packager-v1` remain unchanged
 because current Arcane native consumers treat them as public contracts. Native

package/docs/reference/cli.md

@@ -184,7 +184,7 @@ npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 
 ### Overview
 
-Refreshes one selected application's physical browser runtime map, generates
+Refreshes one selected application's browser runtime map, generates
 its standard browser import map, discovers every directly navigable
 `.html`/`.htm` document admitted by the selected descriptor's existing
 include/exclude rules, and commits the map artifact plus those managed documents
@@ -211,10 +211,10 @@ The generated artifact is
 `apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
 the configured entry and every other admitted browser document as `<script
 type="importmap" data-arcane-import-map>` before module loading. The complete
-physical-v1 runtime derives its entries from the installed runtime and
-browser-runtime inventories. It intentionally has no package-root mapping;
+runtime map derives its entries from the selected runtime and browser-runtime
+inventories. It intentionally has no package-root mapping;
 portable runtime subpaths such as `arcane-os/preference-store` and
-`arcane-os/speech-playback` instead map directly to their canonical projected
+`arcane-os/speech-playback` instead map directly to their canonical runtime
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
@@ -224,6 +224,15 @@ list. External and modern integrated routes require `components`, `css`,
 may omit only an optional trailing `security` include. The external license
 route remains separate and second.
 
+External applications can instead select the four ordered
+[`installed-v1` routes](protocols.md#installed-package-browser-routes) in
+`arcane-packager.json`. This reads directly from the installed SDK package and
+requires neither a workspace `arcane/` directory nor `arcane.lock.json`.
+The generated browser destinations remain `arcane/`, `arcane/sdk/`, and
+`arcane/dependencies/strong-type/`; an npm alias changes package source paths,
+not those browser URLs. The SDK version comes from that installed package.
+Existing physical workspaces and scaffold output remain supported unchanged.
+
 ### Result and safety
 
 Success returns the normal selected-workspace wrapper:
@@ -308,9 +317,12 @@ Starts one development server for one selected app and maps the exact
 workspace/runtime routes. It defaults to HTTPS on localhost; `--public` enables access
 from other devices on the network, using HTTPS by default.
 
-For an external workspace, the server exposes the selected projected
-`arcane/` root, including `arcane/sdk` and `arcane/dependencies`, alongside the
-application. Integrated workspaces retain their configured physical routes.
+For an external workspace, the server exposes the selected SDK routes alongside
+the application. `installed-v1` serves directly from the installed package
+under `/arcane`, `/arcane/sdk`, and `/arcane/dependencies/strong-type`, without
+creating a workspace runtime directory. Existing `physical-v1` workspaces serve
+their projected `arcane/` root. Integrated workspaces retain their configured
+physical routes.
 The explicit live-source SDK mapping remains unchanged and does not replace the
 installed projection.
 
@@ -504,6 +516,11 @@ shared route destinations. When selected shared content supplies no root
 Source document bases and resource URLs therefore retain their development
 layout. Packaging does not run tests or checks automatically.
 
+For `installed-v1`, the same four configured source routes supply the complete
+selected SDK content directly from `node_modules`. Only the portable output
+receives copies; no workspace `arcane/` projection is required. Its runtime URLs,
+managed import-map targets, and PWA inventory destinations match source serving.
+
 ```text
 arcane package [--app <id>] [--dry-run]
 ```
@@ -985,7 +1002,16 @@ application with `Authorization: Bearer <subscription_key>`.
 Subscription verification is disabled when no callback is configured. The
 programmatic `createToolchain().mail({action: 'serve', ...})` path accepts
 `verifySubscription({appName, subscriptionKey, signal})`; supplying that callback
-enables verification before each provider attempt. It must resolve to `true`
+enables verification for requests whose actual connection source IP differs
+from the server-side IP of that connection. The gateway compares the native
+`request.socket.remoteAddress` with `request.socket.localAddress`. A nonempty,
+equal requester IP skips subscription verification and needs neither a bearer
+key nor an application header for that check. No environment setting or domain
+lookup is involved. Local development qualifies under the same rule; another
+machine on an intranet still needs verification. Missing connection metadata
+does not qualify. CORS and the remaining mail requirements still apply.
+
+For requests requiring verification, the callback must resolve to `true`
 to accept the request. An invalid subscription receives 401; verifier service
 failure receives retryable 503; cancellation stops verification before sending.
 The callback connects the actual TWiN Stripe endpoint when its contract is
@@ -1016,7 +1042,7 @@ deadline. `mail.bodyTimeoutMs` selects the optional request-body deadline.
 After binding, `server.ready` reports lifecycle fields such as
 protocol, optional app label, bind address, port, URL, and `callerAuthentication`
 (`none` or `subscription`). Human output states whether verification is disabled
-or configured.
+or configured; configured verification includes the automatic same-IP exception.
 The command owns the server until its lifecycle ends or `SIGINT`/`SIGTERM`
 cancels it. The server's Resend credential remains outside results and events;
 per-request observer events preserve the complete delivery, report, provider

package/docs/reference/mail.md

@@ -115,7 +115,8 @@ An absent key, `null`, or an empty string omits the Authorization header; the
 transport does not block initial setup because a key is missing. Explicit
 `subscriptionKey: null` or `subscriptionKey: ''` also skips User lookup.
 A supplied value of another type is rejected. A gateway with subscription
-verification configured owns rejection of requests without a usable key.
+verification configured owns rejection of requests without a usable key,
+subject to its [automatic same-IP exception](#automatic-same-ip-exception).
 
 For a caller-owned key and shared endpoint:
 
@@ -586,10 +587,40 @@ Subscription verification is disabled during initial setup when
 subscription key. Starting the ordinary CLI gateway uses this mode. This does
 not claim that a subscription was checked.
 
+### Automatic same-IP exception
+
+The gateway automatically skips subscription verification when the incoming
+connection's nonempty `request.socket.remoteAddress` equals
+`request.socket.localAddress`. This also applies when a verifier is configured
+and the request has no subscription key or supplies an invalid one. The
+verification callback is not called for that request.
+
+No `.arcane.env.json` setting or domain allowlist is needed. The comparison uses
+the actual source and destination IP addresses exposed by Node's request socket
+for HTTP/1.1 and HTTP/2. It adds no DNS lookup, configuration read, cache, or
+interface scan. `Origin`, `Host`, `Forwarded`, and `X-Forwarded-For` do not
+establish the connection's IP equality.
+
+| Caller connection | Subscription behavior with a verifier configured |
+| --- | --- |
+| The verification service connects to mail using the same source and destination IP | Skips subscription checking, allowing its service-generated emails without a subscriber key. |
+| A local development request has equal source and destination IPs, including an ordinary loopback connection | Uses the same automatic exception. There is no special loopback rule. |
+| Another machine on the same intranet connects from a different IP | Uses the configured subscription verifier. Sharing a network or subnet supplies no exception. |
+| Two services on one machine connect through different interface IPs | Uses the configured subscription verifier when the actual addresses differ. Machine identity alone supplies no exception. |
+| The request has no usable socket source address | Uses the configured subscription verifier; absent addresses do not count as equal. |
+
+The exception skips only subscription checking. Existing CORS, route, method,
+idempotency-key, report, recipient, and provider handling still apply. The gateway
+continues to require its Resend provider credential and reports acceptance only
+after the provider accepts the email.
+
+### Verification callback contract
+
 The hosting process enables verification by supplying the programmatic
 `verifySubscription` function through
 `createToolchain().mail({action:'serve', verifySubscription, ...options})`.
-The server then reports `callerAuthentication: 'subscription'`. The callback
+The server then reports `callerAuthentication: 'subscription'`, identifying the
+configured mode while retaining the same-IP exception above. The callback
 contract is:
 
 ```javascript
@@ -602,13 +633,15 @@ The gateway also treats any other returned value as invalid. `appName` is the
 exact incoming `X-Mail-App` value, `subscriptionKey` is the incoming Bearer
 key, and `signal` follows the request lifecycle. These control fields stay
 separate from the mail report and Resend payload. The verifier runs for each
-POST request before any provider attempt; results are not cached.
+POST request outside the same-IP exception before any provider attempt; results
+are not cached.
 
 `X-Mail-App` identifies the originating app so the verifier can select that
 app's subscription account, such as the appropriate Stripe account for `BOSS`
 or `TWiN`. It is separate from the gateway's optional `--app` event label.
 The missing-header and Bearer errors below apply only when `verifySubscription`
-is configured. Ordinary `mail serve` does not require either header.
+is configured and the same-IP exception does not apply. Ordinary `mail serve`
+does not require either header.
 
 | Configured-verifier outcome | Gateway response |
 | --- | --- |
@@ -654,10 +687,14 @@ error report, and trigger another mail event. Subscriber failures cannot change
 an already committed mail result, though global capture can report them as new
 errors. This is a source-level possibility, not evidence of a deployed loop.
 
-For a verification service that sends its own emails, its host integration must
-also avoid the circular request path `mail -> verify subscription -> send mail ->
-verify subscription`. The SDK supplies a callback for verification; it does not
-choose that service's caller flow or enable it in ordinary CLI startup.
+For a verification service's own emails sent through the same IP, the gateway
+skips its subscription callback and proceeds to provider delivery. That removes
+the circular dependency `mail -> verify subscription -> send mail -> verify
+subscription` for this connection path. Connections from a different IP still
+use the configured callback, whose owning service must preserve a verification
+path that can return without recursively depending on another verification.
+The exception does not change the separate browser event-subscriber behavior
+described above.
 
 ## Gateway request lifecycle
 

package/docs/reference/protocols.md

@@ -61,13 +61,19 @@ explicit identity fails, and the selected page then must pass exact path-relativ
 base validation.
 Included HTML with neither signal is a component fragment and remains a
 complete package file.
-`arcane-os/preference-store` and `arcane-os/speech-playback` are the two
-portable subpaths that resolve directly to canonical runtime-module namespaces
-from both Node package exports and managed browser keys;
+Public lowercase runtime subpaths resolve directly to canonical runtime-module
+namespaces from both Node package exports and managed browser keys. These
+include `arcane-os/preference-store`, `arcane-os/speech-playback`,
+`arcane-os/ai-preference-tuple`, `arcane-os/ai-preference-runtime`,
+`arcane-os/ai-provider-runtime`, `arcane-os/ai-runtime-state`,
+`arcane-os/model-definition`, `arcane-os/conversation-timebox`,
+`arcane-os/conversation-action-items`, `arcane-os/conversation-closing-report`,
+and `arcane-os/chat-records`.
 `arcane/PreferenceStore` and `arcane/SpeechPlayback` remain their established
 browser import-map names. The additional portable `arcane-os/speech-text`
 subpath owns shared speech-input cleanup and has the same
-managed browser key. There is
+managed browser key. `arcane-os/mail` remains the existing Mail aggregation.
+There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.
 Explicit host document lists use the separate root-exported
@@ -90,6 +96,68 @@ materializes the complete required SDK runtime,
 browser-runtime, and managed-import-map closure inside that app's own artifact.
 No application polls for SDK changes.
 
+## Installed-package browser routes
+
+An external application can serve and package its installed SDK directly,
+without creating a top-level `arcane/` directory or requiring
+`arcane.lock.json`. Select `installed-v1` through these four ordered routes in
+the existing schema-1 `arcane-packager.json`; no additional layout field is
+needed:
+
+```json
+{
+  "schemaVersion": 1,
+  "appsRoot": "apps",
+  "distRoot": "dist",
+  "sharedPayloads": {
+    "browser-runtime": [
+      {
+        "source": "node_modules/arcane-os/runtime/arcane",
+        "destination": "arcane",
+        "include": ["components", "css", "entities", "img", "modules"],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os/browser-runtime",
+        "destination": "arcane/sdk",
+        "include": ["."],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os/runtime/strong-type",
+        "destination": "arcane/dependencies/strong-type",
+        "include": ["."],
+        "exclude": []
+      },
+      {
+        "source": "node_modules/arcane-os",
+        "destination": "licenses/arcane-os",
+        "include": ["LICENSE", "COMMERCIAL-LICENSE.md", "NOTICE"],
+        "exclude": []
+      }
+    ]
+  }
+}
+```
+
+The first include list also accepts a final `security` entry. An npm alias such
+as `arcane-sdk` substitutes `node_modules/arcane-sdk` for the package prefix in
+all four source paths. Destinations remain unchanged. Package selection and SDK
+version come from the installed dependency, not a generated runtime lock.
+
+`arcane import-map`, `arcane dev`, packaging, and generated PWA inventories use
+the same logical destinations. Source serving and map generation read installed
+files without materializing them into the workspace. A selected portable
+package copies its complete selected resources inside the artifact, preserving
+the same browser URLs and saved managed import maps.
+
+Existing `physical-v1` configurations whose first source is `arcane` remain
+supported. The explicit materializer below still refreshes those projections,
+and scaffolding retains its existing physical layout. Selecting `installed-v1`
+does not delete any preexisting workspace files. The separate host-document
+`generateDocumentImportMaps()` API continues to accept an already materialized
+runtime; its input contract is unchanged.
+
 ## Installed SDK runtime materialization
 
 `materializeInstalledSdkRuntime()` is the Node entrypoint for refreshing one

package/docs/reference/pwa.md

@@ -108,6 +108,15 @@ app's `arcane-app.json`. Startup refreshes that app's generated
 maps and starting the server. No packaging or `dist` output is required.
 Package-only applications retain their existing descriptor workflow.
 
+With the external [`installed-v1` routes](protocols.md#installed-package-browser-routes),
+the server inventories the selected SDK directly in `node_modules`. Runtime
+resources retain their public `arcane/`, `arcane/sdk/`, and
+`arcane/dependencies/strong-type/` URLs, so offline selections use those logical
+paths rather than package filesystem paths. No workspace `arcane/` tree or
+`arcane.lock.json` is needed. Packaging uses the same route selection and copies
+the selected resources into the portable output; existing physical projections
+remain supported.
+
 Add a file or directory to `package.include` to make it part of the app's
 resources. A new file inside an already included directory needs no separate
 entry. `package.include` is an application resource selection, not a file list

package/docs/reference/sdk-api.md

@@ -5,11 +5,12 @@ The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
 `arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
-Those package subpaths are distinct from application-facing projection modules
-in the managed browser map, such as `arcane/AIProviderRuntime`,
-`arcane/AIRuntimeState`, and `arcane/ThemeBootstrap`. Applications use those
-mapped runtime modules and call `globalThis.Arcane` for capability-gated host
-behavior; they are not additional `package.json#exports` entrypoints.
+Lowercase runtime subpaths also expose existing module namespaces through both
+Node package exports and managed browser imports, as listed below. Established
+browser names such as `arcane/AIProviderRuntime`, `arcane/AIRuntimeState`, and
+`arcane/ThemeBootstrap` remain managed-map names rather than Node package
+entrypoints. Applications call `globalThis.Arcane` for capability-gated host
+behavior.
 
 This page is the canonical inventory for every JavaScript name reachable through `package.json#exports`. The same binding can appear at the root and a focused subpath; those entrypoints are listed together. The root workspace `discoverApps` and the low-level packager `discoverApps` are intentionally separate records because they are different functions.
 
@@ -19,7 +20,8 @@ This table is the Node `package.json#exports` map: it defines package
 entrypoints for SDK/tooling code. It is distinct from the generated browser
 import map that resolves application-facing `arcane/*` modules and the focused
 EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
-for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
+for the shared browser destinations used by installed-package and physical
+runtime layouts.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -36,6 +38,21 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/event-manager` | Central synchronous events, complete time-travel history, playback, and optional DOM instrumentation. |
 | `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
+| `arcane-os/ai` | Existing `AI.js` provider-neutral inference and speech namespace. |
+| `arcane-os/ai-preference-tuple` | Existing `AIPreferenceTuple.js` module namespace. |
+| `arcane-os/ai-preference-runtime` | Existing `AIPreferenceRuntime.js` module namespace. |
+| `arcane-os/ai-provider-runtime` | Existing `AIProviderRuntime.js` provider selection and lifecycle namespace. |
+| `arcane-os/ai-runtime-state` | Existing `AIRuntimeState.js` state and event namespace. |
+| `arcane-os/model-definition` | Existing `ModelDefinition.js` module namespace. |
+| `arcane-os/conversation-timebox` | Existing `ConversationTimebox.js` module namespace. |
+| `arcane-os/conversation-action-items` | Existing `ConversationActionItems.js` module namespace. |
+| `arcane-os/conversation-closing-report` | Existing `ConversationClosingReport.js` module namespace. |
+| `arcane-os/chat-records` | Existing `ChatRecords.js` module namespace. |
+| `arcane-os/app-data-scope` | Existing `AppDataScope.js` application storage scope namespace. |
+| `arcane-os/core-local-model-catalog` | Existing `CoreLocalModelCatalog.js` local model catalog namespace. |
+| `arcane-os/dbopfs-document-library` | Existing `DBOPFSDocumentLibrary.js` document storage namespace. |
+| `arcane-os/local-ai-readiness` | Existing `LocalAIReadiness.js` local AI readiness namespace. |
+| `arcane-os/ollama-model-identifier` | Existing `OllamaModelIdentifier.js` model identifier namespace. |
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
 | `arcane-os/speech-text` | Speech-input formatting cleanup for complete text and streamed chunks. |
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
@@ -45,6 +62,18 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
+These lowercase runtime-module entrypoints expose their existing exports; they
+do not duplicate the module implementations or change their platform and
+lifecycle requirements. Node resolves them inside the installed package, while
+the managed browser map resolves the same names to the selected runtime URLs.
+Node package resolution does not make browser-only operations available in
+Node: a module still needs its documented browser globals, storage, media,
+Worker, or host capabilities when its initialization or operation uses them.
+Use `arcane-os/mail` for the existing Mail aggregation rather than importing a
+private runtime file. Its package facade and managed browser entry both expose
+the canonical `MailApi.mjs` aggregation and the same Mail, outbox, and transport
+bindings.
+
 Eight JSON schemas and `package.json` are data-only export subpaths. In Node ESM, import JSON with `with {type: 'json'}`, or resolve and read it explicitly.
 
 ### Managed AI narration
@@ -1496,6 +1525,11 @@ After full runtime replacement, it writes or replaces semantic
 `arcane.lock.json` from the actual installed dependency name, package name,
 package version, alias source, and projected roots.
 
+This operation remains available for physical workspace projections. External
+applications using [installed-package routes](protocols.md#installed-package-browser-routes)
+read directly from their installed dependency and do not need to call it or
+create `arcane.lock.json` before serving, refreshing app import maps, or packaging.
+
 ### Signature and result
 
 ```text
@@ -3643,6 +3677,10 @@ certPath, keyPath, tls, signal, onEvent}` and serves one validated
 workspace application plus its complete SDK or integrated runtime. Packaged mode uses
 `{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, certPath, keyPath, tls,
 signal, onEvent}` and serves the complete selected release files.
+External source mode accepts both the installed-package route layout and the
+existing physical runtime layout. Installed-package mode serves the configured
+SDK resources directly from `node_modules` at their logical browser URLs;
+it does not create a workspace `arcane/` directory or require `arcane.lock.json`.
 `host` defaults to `127.0.0.1` and accepts an
 explicit network address or hostname. Use `0.0.0.0` for all IPv4 interfaces or
 `::` for the platform's IPv6 wildcard listeners. `port` selects the HTTPS
@@ -3866,8 +3904,10 @@ async validateWorkspace({
 
 Import it from `arcane-os`. It resolves to a validation result with
 `valid`, `workspaceMode`, `workspaceRoot`, `appId`, `appRoot`, the selected
-configuration/application, lock data, and completed checks. For an external
-workspace it additionally returns the exact installed package authority:
+configuration/application, lock data where the layout uses it, and completed
+checks. External `installed-v1` selection reads package metadata directly and
+does not require a workspace `arcane.lock.json` or runtime projection. For an
+external workspace the result additionally includes the installed package:
 
 ```javascript
 {
@@ -3876,17 +3916,17 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.18',
+    packageVersion,
     runtimeRoot,
     browserRuntimeRoot
   }
 }
 ```
 
-The dependency can be named `arcane-os` or be one exact npm alias for
-`npm:arcane-os@0.5.18`. The selected installation must still be one direct,
-physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.18`; duplicate canonical/alias declarations reject.
+The dependency can be named `arcane-os` or use an npm alias for the selected
+`arcane-os` version. The configured package source must match that declaration;
+`packageVersion` reports the installed package's version. Duplicate
+canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/docs/reviews/mail-server-purpose-review.md

@@ -1,5 +1,10 @@
 [Roshi's Codex PRIME] The gateway review and its portable credential follow-up apply the same three purpose gates. The gateway removals preserve complete delivery outcomes, configured CORS and recipient policy, and the optional subscription verifier. Mail credentials now belong in the user-selected `.arcane.env.json`, with one portable Node implementation for Windows, Linux, and macOS and a compatible Node host as the Android adaptation boundary. The original gateway inventory below uses baseline `f055e05`; the credential follow-up reviews the Windows storage implementation present at SDK `0.18.0`. Commit, package, publication, and actual platform execution outcomes belong to the delivery record rather than to this source-review report.
 
+The [same-IP subscription exception follow-up](#same-ip-subscription-exception-follow-up)
+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.
+
 | Decision | Behavior | Why it matters | Source status at this review |
 | --- | --- | --- | --- |
 | Remove | Loopback-only admission, manual header reconstruction, address/origin normalization, local payload grammar, manual content-length scan, dead queue knobs | These restrict supported use, rewrite supplied values, or repeat work already owned elsewhere. | Removed from the inspected source; naming-only changes carry no runtime claim. |
@@ -541,3 +546,58 @@ global error handler; it is not an automatic server response to an ordinary
 mail failure. This is a static source-path finding, not an observed production
 incident or an executed reproduction. This documentation clarification changes
 no error, subscription, retry, or delivery behavior.
+
+## Same-IP subscription exception follow-up
+
+The user selected an automatic same-IP exception so the verification service can
+send its own emails without a subscriber key. This supersedes the proposed
+domain exception in `.arcane.env.json`; neither an environment setting nor a
+domain allowlist is needed. The reusable decision belongs in the SDK's existing
+`handleMailRequest`, immediately at its subscription-verification branch.
+Application-owned messages, sender choices, subscription accounts, and the
+verification callback remain with their existing owners.
+
+The condition is a nonempty `request.socket.remoteAddress` equal to
+`request.socket.localAddress`. Matching requests skip `verifyMailSubscription`
+and the configured `verifySubscription` callback, including when the request
+has no subscriber key or supplies an invalid one. Requests with different or
+unavailable socket addresses retain the configured verification path. Omitting
+the callback continues to select the existing no-verification setup.
+
+| 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 |
+| --- | --- | --- | --- | --- |
+| Automatic source/destination IP equality at `handleMailRequest` | Yes. The verifier needs to send service mail without a subscriber key. | It identifies the exact connection case the user selected using already-available socket fields. | No. Removing the exception would restore the verifier's dependency on subscription checking for its own mail. | Keep one inline equality decision with a nonempty source address. No new helper or configuration owner. |
+| Subscription checking for a matching connection | The subscription-verification capability matters; this particular call does not. | Requiring it for the verifier's own email adds an unnecessary dependency and can create a circular service call. | Yes. The user expressly permits these senders regardless of their subscription. | Skip the callback and its asynchronous wait for matching requests. A callback that contacts the verification service makes no such request on this path. |
+| Proposed `.arcane.env.json` domain exception, DNS resolution, address cache, and interface enumeration | No. The selected rule is actual IP equality and requires no setup. | These would introduce configuration, I/O, retained state, or a broader machine/domain interpretation absent from the selected outcome. | Yes. Native request socket fields already supply both values. | Add none. Secret files, named provider profiles, and current configuration loading remain unchanged. |
+| `Origin`, `Host`, `Forwarded`, or `X-Forwarded-For` as evidence of matching connection IPs | No. These request fields do not define the native socket endpoints. | Reading them for this exception would change its meaning and duplicate unrelated routing or CORS concerns. | Yes. The actual socket exposes the relevant addresses directly. | Keep header handling at its existing owner; none of these headers selects the exception. |
+| Special loopback, intranet, subnet, or same-machine rules | No. The selected condition is equal IPs. | A larger address policy would grant a different exception and add work. | Yes. Equal local-development addresses already use the ordinary equality path. | Add none. Another intranet machine with a different IP still uses configured verification. Services on one machine using different interface IPs may also require it. |
+| CORS, routing, methods, idempotency, report/recipient handling, provider result, and cancellation | Yes. These continue to determine the actual mail outcome. | Skipping subscription checking does not change the requested delivery or lifecycle contracts. | No. Their retained behavior supports complete delivery and honest results. | Preserve these owners and their current ordering. Provider acceptance remains separate from the subscription decision. |
+
+The operation graph adds one synchronous connection-address comparison at the
+existing request owner. A matching request avoids subscription header checking,
+callback invocation, and its asynchronous verification wait, then uses the
+ordinary provider path. There is no new file read, DNS request, timer, polling,
+cache, helper, shared-state lock, startup barrier, or per-platform process.
+Requests continue independently under the existing handler lifecycle. These are
+source-level operation changes, not measured timing improvements.
+
+The selected `node-http-server` raw-request hook supplies the native Node request.
+HTTP/1.1 and HTTP/2 both expose the needed address properties; the same Node
+contract applies on Windows, Linux, and macOS, with Android requiring a compatible
+Node host. The local socket address is the actual destination used by the
+connection, including when the listener binds `0.0.0.0`.
+[Node socket addresses](https://nodejs.org/api/net.html#socketlocaladdress) and
+[HTTP/2 request sockets](https://nodejs.org/api/http2.html#requestsocket)
+document these properties.
+
+For equal connection IPs, the verification service's own mail proceeds without
+calling that service again. This removes its circular subscription dependency
+on this path. It does not claim that arbitrary callback code or a repeatedly
+failing browser mail-event subscriber cannot create a separate feedback loop.
+The existing error and retry distinctions remain documented in the
+[mail reference](../reference/mail.md#error-reports-and-retries).
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -17,6 +17,21 @@
     "./browser-device": "./browser-runtime/browser-device.mjs",
     "./pwa": "./browser-runtime/pwa.mjs",
     "./preference-store": "./runtime/arcane/modules/PreferenceStore.js",
+    "./ai": "./runtime/arcane/modules/AI.js",
+    "./ai-preference-tuple": "./runtime/arcane/modules/AIPreferenceTuple.js",
+    "./ai-preference-runtime": "./runtime/arcane/modules/AIPreferenceRuntime.js",
+    "./ai-provider-runtime": "./runtime/arcane/modules/AIProviderRuntime.js",
+    "./ai-runtime-state": "./runtime/arcane/modules/AIRuntimeState.js",
+    "./model-definition": "./runtime/arcane/modules/ModelDefinition.js",
+    "./conversation-timebox": "./runtime/arcane/modules/ConversationTimebox.js",
+    "./conversation-action-items": "./runtime/arcane/modules/ConversationActionItems.js",
+    "./conversation-closing-report": "./runtime/arcane/modules/ConversationClosingReport.js",
+    "./chat-records": "./runtime/arcane/modules/ChatRecords.js",
+    "./app-data-scope": "./runtime/arcane/modules/AppDataScope.js",
+    "./core-local-model-catalog": "./runtime/arcane/modules/CoreLocalModelCatalog.js",
+    "./dbopfs-document-library": "./runtime/arcane/modules/DBOPFSDocumentLibrary.js",
+    "./local-ai-readiness": "./runtime/arcane/modules/LocalAIReadiness.js",
+    "./ollama-model-identifier": "./runtime/arcane/modules/OllamaModelIdentifier.js",
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
@@ -69,7 +84,7 @@
     "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:integration": "node ./bin/arcane-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:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.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",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",

package/runtime/arcane/modules/MailApi.mjs

@@ -0,0 +1,19 @@
+export {
+    default,
+    default as Mail,
+    resolveMailConfig
+} from './Mail.js';
+export {
+    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
+    MAIL_OUTBOX_PROTOCOL,
+    MAIL_OUTBOX_STATES,
+    MAIL_OUTBOX_TABLE,
+    MailOutbox,
+    createMailOutbox
+} from './MailOutbox.mjs';
+export {
+    MailTransportError,
+    normalizeMailEndpoint,
+    sendMailReport,
+    serializeMailReport
+} from './MailTransport.mjs';

package/src/dev-server.mjs

@@ -6,6 +6,7 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
+import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
 import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
 import {createEventQueue} from './event-queue.mjs';
@@ -436,6 +437,7 @@ function sharedPathAllowed(relative,route){
     });
     if(excluded)return false;
     return route.include.some(item=>{
+        if(item==='.')return true;
         const candidate=inventoryKey(item);
         return comparable===candidate||comparable.startsWith(`${candidate}/`);
     });
@@ -471,11 +473,16 @@ async function sourceRoutes(workspaceRoot,appId,{
             mappings:[appMapping,...sdkSource.mappings]
         };
     }
-    if(resolved.config.workspaceMode==='integrated'){
+    if(resolved.config.workspaceMode==='integrated'
+        ||resolved.config.browserRuntimeLayout==='installed-v1'){
+        const installed=resolved.config.browserRuntimeLayout==='installed-v1'
+            ?await readInstalledSdkLayout(resolved.workspaceRoot,resolved.config)
+            :null;
         return {
             workspaceRoot:resolved.workspaceRoot,
-            workspaceMode:'integrated',
+            workspaceMode:resolved.config.workspaceMode,
             config:resolved.config,
+            ...(installed?{installed}:{}),
             appId:resolved.appId,
             app:resolved.app.manifest,
             startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
@@ -579,7 +586,7 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
             }
         }
         for (const selected of mapping.include ?? ['']) {
-            await visitSourceResource(selected ? selected.split('/') : []);
+            await visitSourceResource(selected && selected!=='.' ? selected.split('/') : []);
         }
     }
     const origin = 'http://arcane.invalid';
@@ -866,7 +873,7 @@ async function startOwnedDevServer({
     const mappings=deterministicMappings(routeSet.mappings);
     const versionPath = mode === 'source'
         ? sdkRuntimeSourceRoot === undefined
-            ? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
+            ? routeSet.installed?.versionPath ?? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
             : path.join(routeSet.runtime.sourceRoot, 'package.json')
         : undefined;
     const [generatorInputs, initialAssetVersion, versionInput] = await Promise.all(
@@ -897,6 +904,9 @@ async function startOwnedDevServer({
     );
     async function selectedAssetVersion(){
         if(mode!=='source')return undefined;
+        if(routeSet.installed)return JSON.parse(await readFile(
+            routeSet.installed.versionPath,'utf8'
+        )).version;
         return sdkRuntimeSourceRoot===undefined
             ?readWorkspaceAssetVersion(routeSet.workspaceRoot)
             :JSON.parse(await readFile(

package/src/import-map.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {pathToFileURL} from 'node:url';
 import {SDK_VERSION} from './constants.mjs';
 import {listRuntimeFiles} from './runtime.mjs';
+import {readInstalledSdkLayout,installedRuntimeFiles,installedRuntimeTarget} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -19,7 +20,23 @@ const SDK_BROWSER_AI_ENTRY='sdk/ai/browser-wasm.mjs';
 const SDK_BROWSER_SPEECH_ENTRY='sdk/ai/browser-speech.mjs';
 const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
     ['arcane-os/preference-store','modules/PreferenceStore.js'],
-    ['arcane-os/speech-playback','modules/SpeechPlayback.js']
+    ['arcane-os/speech-playback','modules/SpeechPlayback.js'],
+    ['arcane-os/ai','modules/AI.js'],
+    ['arcane-os/ai-preference-tuple','modules/AIPreferenceTuple.js'],
+    ['arcane-os/ai-preference-runtime','modules/AIPreferenceRuntime.js'],
+    ['arcane-os/ai-provider-runtime','modules/AIProviderRuntime.js'],
+    ['arcane-os/ai-runtime-state','modules/AIRuntimeState.js'],
+    ['arcane-os/model-definition','modules/ModelDefinition.js'],
+    ['arcane-os/conversation-timebox','modules/ConversationTimebox.js'],
+    ['arcane-os/conversation-action-items','modules/ConversationActionItems.js'],
+    ['arcane-os/conversation-closing-report','modules/ConversationClosingReport.js'],
+    ['arcane-os/chat-records','modules/ChatRecords.js'],
+    ['arcane-os/app-data-scope','modules/AppDataScope.js'],
+    ['arcane-os/core-local-model-catalog','modules/CoreLocalModelCatalog.js'],
+    ['arcane-os/dbopfs-document-library','modules/DBOPFSDocumentLibrary.js'],
+    ['arcane-os/local-ai-readiness','modules/LocalAIReadiness.js'],
+    ['arcane-os/ollama-model-identifier','modules/OllamaModelIdentifier.js'],
+    ['arcane-os/mail','modules/MailApi.mjs']
 ]);
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
@@ -1436,9 +1453,10 @@ async function physicalRuntime(workspaceRoot,signal){
 }
 
 async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
+    const installed=await readInstalledSdkLayout(resolvedWorkspace);
     const [runtime,version]=await Promise.all([
-        physicalRuntime(resolvedWorkspace,signal),
-        pwaEnabled?null:readWorkspaceAssetVersion(resolvedWorkspace)
+        installed?installedRuntimeFiles(resolvedWorkspace,installed,signal):physicalRuntime(resolvedWorkspace,signal),
+        pwaEnabled?null:installed?.version??readWorkspaceAssetVersion(resolvedWorkspace)
     ]);
     const built=await buildImportMap({files:runtime.files,signal,version});
     const json=`${JSON.stringify({imports:built.imports},null,2).replaceAll('<','\\u003c')}\n`;
@@ -1446,6 +1464,8 @@ async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
 }
 
 export async function readWorkspaceAssetVersion(workspaceRoot){
+    const installed=await readInstalledSdkLayout(workspaceRoot);
+    if(installed)return installed.version;
     let source;
     try{source=await readFileFromDisk(path.join(workspaceRoot,'arcane.lock.json'),'utf8');}
     catch(error){
@@ -2434,10 +2454,17 @@ export async function readApplicationTestImportMapContext({
         ||is.array(document.imports)){
         fail('Application test import-map artifact must contain an imports object.');
     }
+    const installed=await readInstalledSdkLayout(resolvedWorkspaceRoot);
+    const imports=installed?Object.fromEntries(Object.entries(document.imports).map(
+        function installedApplicationTestTarget([specifier,target]){
+            return [specifier,is.string(target)&&target.startsWith('./')
+                ?`./${installedRuntimeTarget(target.slice(2),installed)}`:target];
+        }
+    )):document.imports;
     return createApplicationTestImportMapContext({
         applicationRoot:resolvedWorkspaceRoot,
         boundary:'source',
-        imports:document.imports,
+        imports,
         signal
     });
 }

package/src/mail-api.mjs

@@ -1,19 +1,2 @@
-export {
-    default,
-    default as Mail,
-    resolveMailConfig
-} from '../runtime/arcane/modules/Mail.js';
-export {
-    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
-    MAIL_OUTBOX_PROTOCOL,
-    MAIL_OUTBOX_STATES,
-    MAIL_OUTBOX_TABLE,
-    MailOutbox,
-    createMailOutbox
-} from '../runtime/arcane/modules/MailOutbox.mjs';
-export {
-    MailTransportError,
-    normalizeMailEndpoint,
-    sendMailReport,
-    serializeMailReport
-} from '../runtime/arcane/modules/MailTransport.mjs';
+export {default} from '../runtime/arcane/modules/MailApi.mjs';
+export * from '../runtime/arcane/modules/MailApi.mjs';

package/src/mail-server.mjs

@@ -899,8 +899,16 @@ function createConfiguredMailHandler(configuration){
             if(request.method!=='POST'){
                 throw new MailGatewayFault('mail_method_not_allowed',{statusCode:405});
             }
-            if(configuration.verifySubscription){
-                appId=await verifyMailSubscription(request,configuration,requestController.signal);
+            if (configuration.verifySubscription) {
+                const requesterIp = request.socket?.remoteAddress;
+                const serverIp = request.socket?.localAddress;
+                if (!requesterIp || requesterIp !== serverIp) {
+                    appId = await verifyMailSubscription(
+                        request,
+                        configuration,
+                        requestController.signal
+                    );
+                }
             }
             idempotencyKey=requireRequestHeader(request,'idempotency-key');
             const requestText=await readRequestBodyText(request,{

package/src/packager/core.mjs

@@ -136,12 +136,13 @@ function isGlobLike(value){
     return /[*?\[\]{}]/u.test(value);
 }
 
-function validatePathList(value,label,{required=false}={}){
+function validatePathList(value,label,{required=false,allowRoot=false}={}){
     if(!is.array(value)||(required&&value.length===0)){
         fail(`${label} must be ${required?'a non-empty':'an'} array of literal relative paths.`);
     }
     const normalized=value.map((entry,index)=>{
-        const item=normalizeRelativePath(entry,`${label}[${index}]`);
+        const item=allowRoot?normalizeRelativeRoot(entry,`${label}[${index}]`)
+            :normalizeRelativePath(entry,`${label}[${index}]`);
         if(isGlobLike(item))fail(`${label}[${index}] must be literal; directories include descendants.`);
         return item;
     });
@@ -151,7 +152,8 @@ function validatePathList(value,label,{required=false}={}){
     if(required){
         for(let left=0;left<normalized.length;left+=1){
             for(let right=left+1;right<normalized.length;right+=1){
-                if(sameOrDescendant(normalized[left],normalized[right])
+                if(normalized[left]==='.'||normalized[right]==='.'
+                    ||sameOrDescendant(normalized[left],normalized[right])
                     ||sameOrDescendant(normalized[right],normalized[left])){
                     fail(`${label} has overlapping paths: ${normalized[left]} and ${normalized[right]}`);
                 }
@@ -256,7 +258,7 @@ function validateSharedRoute(route,label){
     assertOnlyKeys(route,new Set(['source','destination','include','exclude']),label);
     const source=normalizeRelativeRoot(route.source,`${label}.source`);
     const destination=normalizeRelativeRoot(route.destination,`${label}.destination`);
-    const include=validatePathList(route.include,`${label}.include`,{required:true});
+    const include=validatePathList(route.include,`${label}.include`,{required:true,allowRoot:true});
     const exclude=validatePathList(route.exclude??[],`${label}.exclude`);
     if(source==='.'||source==='apps'||source.startsWith('apps/')
         ||source==='dist'||source.startsWith('dist/')||source==='node_modules'
@@ -421,7 +423,7 @@ async function loadContext(requestedWorkspaceRoot,appId){
 }
 
 function destinationJoin(root,relative){
-    return root==='.'?relative:`${root}/${relative}`;
+    return relative==='.'?root:root==='.'?relative:`${root}/${relative}`;
 }
 
 function appPackagePath(context, relative) {
@@ -442,12 +444,13 @@ async function collectSelectedPath({
     records,
     destinations,
     signal,
-    label
+    label,
+    allowRoot=false
 }){
     throwIfAborted(signal);
     if(isExcluded(selected,excludes))return;
     if(reject(selected))fail(`${label} selects a reserved private or generated path: ${selected}.`);
-    const absolute=resolveInside(sourceRoot,selected,label);
+    const absolute=resolveInside(sourceRoot,selected,label,{allowRoot});
     let info;
     try{info=await lstat(absolute);}
     catch(error){
@@ -455,15 +458,16 @@ async function collectSelectedPath({
         throw error;
     }
     if(info.isSymbolicLink())fail(`${label} contains a symbolic link or junction: ${selected}.`);
+    if(selected==='.'&&!info.isDirectory())fail(`${label} root selection must be a directory.`);
     if(info.isDirectory()){
         const entries=await readdir(absolute,{withFileTypes:true});
         entries.sort((left,right)=>compareText(left.name,right.name));
         for(const entry of entries){
-            const child=`${selected}/${entry.name}`;
+            const child=destinationJoin(selected,entry.name);
             await collectSelectedPath({
                 sourceRoot,
                 selected:child,
-                destination:`${destination}/${entry.name}`,
+                destination:destinationJoin(destination,entry.name),
                 excludes,
                 reject,
                 records,
@@ -515,7 +519,8 @@ async function collectPackageRecords(context,{signal}={}){
                     records,
                     destinations,
                     signal,
-                    label:`sharedPayloads.${sharedId}`
+                    label:`sharedPayloads.${sharedId}`,
+                    allowRoot:true
                 });
             }
         }

package/src/sdk-runtime-layout.mjs

@@ -0,0 +1,99 @@
+import Is from 'strong-type';
+import {readFile,readdir} from 'node:fs/promises';
+import path from 'node:path';
+
+const is=new Is(false);
+
+// The browser URLs stay the same; only the source of their files changes.
+export function installedSdkRoutes(packageSource,{security=false}={}){
+    return [
+        {
+            source:`${packageSource}/runtime/arcane`,destination:'arcane',
+            include:['components','css','entities','img','modules',...(security?['security']:[])],exclude:[]
+        },
+        {
+            source:`${packageSource}/browser-runtime`,destination:'arcane/sdk',
+            include:['.'],exclude:[]
+        },
+        {
+            source:`${packageSource}/runtime/strong-type`,destination:'arcane/dependencies/strong-type',
+            include:['.'],exclude:[]
+        },
+        {
+            source:packageSource,destination:'licenses/arcane-os',
+            include:['LICENSE','COMMERCIAL-LICENSE.md','NOTICE'],exclude:[]
+        }
+    ];
+}
+
+export function installedSdkPackageSource(config){
+    const routes=config?.sharedPayloads?.['browser-runtime'];
+    if(!is.array(routes)||routes.length!==4)return null;
+    const source=routes[3]?.source;
+    if(!is.string(source)||!/^node_modules\/(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(source))return null;
+    const expected=installedSdkRoutes(source,{security:routes[0]?.include?.at(-1)==='security'});
+    return routes.every(function matchesInstalledRoute(route,index){
+        const wanted=expected[index];
+        return route?.source===wanted.source&&route?.destination===wanted.destination
+            &&is.array(route.include)&&route.include.length===wanted.include.length
+            &&route.include.every(function matchesSelectedPath(value,item){return value===wanted.include[item];})
+            &&(route.exclude===undefined||(is.array(route.exclude)&&route.exclude.length===0));
+    })?source:null;
+}
+
+export async function readInstalledSdkLayout(workspaceRoot,config){
+    if(config===undefined){
+        try{config=JSON.parse(await readFile(path.join(workspaceRoot,'arcane-packager.json'),'utf8'));}
+        catch(error){if(error.code==='ENOENT')return null;throw error;}
+    }
+    const packageSource=installedSdkPackageSource(config);
+    if(packageSource===null)return null;
+    const packageRoot=path.join(workspaceRoot,...packageSource.split('/'));
+    const versionPath=path.join(packageRoot,'package.json');
+    const manifest=JSON.parse(await readFile(versionPath,'utf8'));
+    if(manifest.name!=='arcane-os'||!is.string(manifest.version)||!manifest.version){
+        const error=new Error('The installed SDK runtime must identify its arcane-os package version.');
+        error.code='ARCANE_WORKSPACE_INVALID';
+        throw error;
+    }
+    return {packageSource,packageRoot,versionPath,version:manifest.version,routes:config.sharedPayloads['browser-runtime']};
+}
+
+export async function installedRuntimeFiles(workspaceRoot,layout,signal){
+    const files=[];
+    async function visit(directory,logical){
+        signal?.throwIfAborted();
+        const entries=await readdir(directory,{withFileTypes:true});
+        for(const entry of entries){
+            signal?.throwIfAborted();
+            const relative=logical?`${logical}/${entry.name}`:entry.name;
+            if(entry.isDirectory())await visit(path.join(directory,entry.name),relative);
+            else if(entry.isFile())files.push(relative);
+        }
+    }
+    for(const route of layout.routes){
+        if(route.destination!=='arcane'&&!route.destination.startsWith('arcane/'))continue;
+        const prefix=route.destination==='arcane'?'':route.destination.slice('arcane/'.length);
+        for(const selected of route.include){
+            const suffix=selected==='.'?'':selected;
+            await visit(
+                path.join(workspaceRoot,...route.source.split('/'),suffix),
+                [prefix,suffix].filter(Boolean).join('/')
+            );
+        }
+    }
+    return {files:files.sort()};
+}
+
+export function installedRuntimeTarget(relative,layout){
+    for(const route of [...layout.routes].sort(function longestDestinationFirst(left,right){
+        return right.destination.length-left.destination.length;
+    })){
+        if(!relative.startsWith(`${route.destination}/`))continue;
+        const suffix=relative.slice(route.destination.length+1);
+        if(route.include.some(function includesRuntimeTarget(selected){
+            return selected==='.'||suffix===selected||suffix.startsWith(`${selected}/`);
+        }))return `${route.source}/${suffix}`;
+    }
+    return relative;
+}

package/src/workspace.mjs

@@ -9,6 +9,7 @@ import {
 import {loadAppDescriptor} from './app-descriptor.mjs';
 import {SDK_NAME as EXPECTED_SDK_NAME} from './constants.mjs';
 import {inspectImportMapHtml} from './import-map.mjs';
+import {installedSdkPackageSource} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -159,6 +160,13 @@ function classifyRootConfig(config){
     const validated=validatePackagerRootConfig(config,ROOT_CONFIG_NAME);
     const routes=validated.sharedPayloads['browser-runtime'];
     if(!is.array(routes))fail(`${ROOT_CONFIG_NAME} must define browser-runtime routes.`);
+    const installedPackageSource=installedSdkPackageSource(validated);
+    if(installedPackageSource!==null){
+        return {
+            ...validated,workspaceMode:'external',browserRuntimeLayout:'installed-v1',
+            sdkPackageSource:installedPackageSource
+        };
+    }
     const externalPackageSource=routes.length===2
         &&dependencyNameForSdkPackageSource(routes[1]?.source)!==null
         ?routes[1].source