arcane-os 0.1.0 → 0.1.2

package/browser-runtime/ai/wllama/llama.cpp-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 The ggml authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/publishing.md

@@ -16,19 +16,22 @@ dependency and invoke its local CLI with `npm exec -- arcane`. A separate
 global installer, standalone SDK executable, NuGet package, Homebrew formula,
 or OS package is not part of this release surface.
 
-`Check` validates the source once, then one unprivileged producer packs one
-`.tgz` under pinned Node and npm versions. The producer writes a canonical
-manifest containing the source SHA, clean-checkout flag, package inventory,
-byte length, SHA-256, npm SHA-1 shasum, and SHA-512 integrity. Windows x64,
-Linux x64, and a real macOS arm64 runner use the declared Node `22.23.2` floor
-and each download that same Actions
-artifact by immutable artifact id. They never repack it. Each runner verifies
-the receipt, installs the tarball into a disposable project, exercises
+`Check` validates only package-publication authority once: package metadata,
+the executable and `.gitattributes` boundary, both authenticated runtime
+receipts, and the focused npm identity/channel/provenance contract. One
+unprivileged producer then packs one `.tgz` under pinned Node and npm versions.
+The producer writes a canonical manifest containing the source SHA,
+clean-checkout flag, package inventory, byte length, SHA-256, npm SHA-1 shasum,
+and SHA-512 integrity. One Ubuntu x64 consumer at the declared Node `22.23.2`
+floor downloads that Actions artifact by immutable artifact id, verifies the
+receipt, installs the tarball into a disposable project, exercises
 `npm exec --offline -- arcane`, and runs one small capability contract through
-the installed package's `arcane-test.mjs`. A final readiness job verifies the
-same artifact's identity, integrity, shasum, license inventory, and content
-boundary once. Browser/process simulations, Pages, Examples, and presentation
-work are post-registry follow-through rather than npm publication gates.
+the installed package's `arcane-test.mjs`. It never repacks. A final readiness
+job verifies the same artifact's identity, integrity, shasum, license inventory,
+and content boundary once. Golden snapshots, broad integration/regression and
+platform matrices, browser/process simulations, Pages, Examples, and
+presentation work are normal or post-registry checks rather than npm
+publication gates.
 
 `publish-dev.yml` can run only when manually dispatched from `main` in
 `TheWizardNexus/arcane-os-sdk`. Dispatch requires an authorized npm content
@@ -72,8 +75,9 @@ as `arcane-os@0.1.0-dev.5` and verifies the locked runtime. A local directory
 
 The first-version bootstrap established these permanent audit boundaries:
 
-1. Push the intended clean `main` commit and require the complete Check workflow,
-   including the exact-artifact Windows/Linux/macOS matrix, to pass.
+1. Push the intended clean `main` commit and require the npm-critical Check
+   workflow—package authority, one producer, one installed Linux capability
+   smoke, and one identity/legal verifier—to pass.
 2. Review the uploaded tarball inventory, manifest, checksum, and license
    notices. Ensure the Arcane OS monorepo package is private so it cannot publish
    the same npm name accidentally.
@@ -189,8 +193,9 @@ work and do not change the canonical source branch.
 ## Work-amplification record
 
 The release graph is one checked `main` SHA and one npm release candidate. One
-source-validation job runs the suite once; one producer creates the tarball;
-three small installed-package consumers execute those exact bytes on Windows,
-Linux, and macOS; and one readiness job verifies identity and legal inventory.
+package-authority job runs the narrow source policy and publication contract;
+one producer creates the tarball; one Ubuntu consumer executes those exact
+installed bytes; and one readiness job verifies identity and legal inventory.
 OIDC publication reuses that successful exact-SHA artifact without rebuilding.
-Pages and broader presentation work follow registry verification separately.
+Platform matrices, full product regressions, Pages, and broader presentation
+work remain outside registry publication and run separately when warranted.

package/docs/reference/README.md

@@ -19,6 +19,7 @@ high-level page links to the relevant deep section instead of repeating it.
 | Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
 | Publish central events, capture bounded time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
 | Use the `arcane` command | [CLI reference](cli.md) |
+| Generate named browser imports or inspect the authenticated physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
 | Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
 | Use a shared entity | [Runtime entity modules](runtime-entities.md) and [exact export contracts](core/arcane-entities.md) |
@@ -26,6 +27,7 @@ high-level page links to the relevant deep section instead of repeating it.
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI | [Arcane AI contracts](core/arcane-ai-contracts.md) |
+| Run a caller-authenticated local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
 | Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
 | Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
 | Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
@@ -36,7 +38,7 @@ This repository contains two related, explicitly versioned surfaces:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.1.0-dev.5` | The Node.js toolchain and package exports in this checkout. |
+| SDK and CLI | `arcane-os` `0.1.1` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` entrypoint in this checkout. |
 | Browser runtime | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, bundle `0.8.12`, protocol `arcane/1` | The exact 155-file runtime snapshot shipped under `runtime/`. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract derived into `docs/reference/core/`. Canonical inventory and focused-member content was verified unchanged at Arcane OS `main` commit `13f3ce0ae34f77a3495331c8b4c30b1bb105f8ed`; SDK-local provenance, link, and package-boundary annotations are added explicitly. |
 
@@ -72,11 +74,13 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The Node package exposes 158 semantic JavaScript records across 11 JavaScript
+The package exposes 163 semantic JavaScript records across 12 JavaScript
 entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
-metadata. The [machine-readable package inventory](inventory/package-api.json)
-and [SDK member reference](sdk-api.md) are checked bidirectionally against every
-declared JavaScript export.
+metadata. Ten entrypoints are Node.js control-plane surfaces,
+`arcane-os/event-manager` runs in Node and browsers, and
+`arcane-os/ai/browser-wasm` is browser-only. The [machine-readable package
+inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
+are checked bidirectionally against every declared JavaScript export.
 
 The seven update-check records are explicit on-demand checks; they do not poll,
 download, install, or self-update.

package/docs/reference/ai/browser-wasm.md

@@ -0,0 +1,335 @@
+# Browser-WASM local AI
+
+Use this browser-only entrypoint when an application deliberately owns a local
+GGUF model authority and wants provider-neutral LLM lifecycle, chat, streaming,
+cancellation, and structural tool-call results without an Arcane Core host.
+For ordinary hosted applications, start with the [Arcane AI
+contracts](../core/arcane-ai-contracts.md) and `globalThis.Arcane.ai`. This
+page is the focused local-browser path beneath the normalized AI decision
+guide.
+
+The wiring example assumes a scaffolded or materialized Arcane application
+with SDK `0.1.1`'s authenticated runtime tree and 86-entry browser import map.
+`arcane/DBOPFS` is a managed browser-map specifier, not an npm package export.
+See [browser runtime delivery](../protocols.md#browser-runtime-delivery) before
+using the example in a custom host or bundler.
+
+```javascript
+import DBOPFS from 'arcane/DBOPFS';
+import {
+    createArcaneAI,
+    createBrowserModelSource,
+    createBrowserWasmLlmProvider,
+    createDbopfsModelStore
+} from 'arcane-os/ai/browser-wasm';
+
+const MODEL = Object.freeze({
+    id:'my-reviewed-model',
+    name:'model-q4.gguf',
+    immutableUrl:'https://models.example/revisions/4f7c/model-q4.gguf',
+    bytes:123456789,
+    sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+    licenseSpdx:'Apache-2.0',
+    sourceRevision:'4f7c'
+});
+
+const dbopfs = globalThis.dbopfs || new DBOPFS({applicationId:'my-app'});
+await dbopfs.readyPromise;
+const source = createBrowserModelSource(MODEL);
+const store = createDbopfsModelStore({dbopfs});
+const provider = createBrowserWasmLlmProvider({source, store});
+const ai = createArcaneAI({provider, loadPolicy:'manual'});
+
+// Put this behind an explicit user action: it can download MODEL.bytes bytes.
+async function loadReviewedModel() {
+    return ai.load({threads:1, contextTokens:4096, gpuLayers:0});
+}
+```
+
+The browser-WASM runtime closure packages the authenticated
+`@wllama/wllama` `3.6.0` ESM and WebAssembly runtime plus the Wllama and
+llama.cpp MIT license texts. It
+packages no model weights, model catalog, CDN fallback, native provider, speech
+synthesis, or transcription. Callers supply the exact model authority. `bytes`
+is the expected positive byte length, not inline model data.
+
+## Lifecycle at a glance
+
+`createArcaneAI()` owns one LLM controller. Its default `loadPolicy` is
+`on-demand`; the first request may download and initialize the model. Use
+`manual` when a user action, resource review, or progress UI must precede load.
+
+| Operation | Result |
+| --- | --- |
+| `ai.status()` | Frozen `{llm: status}` wrapper. |
+| `ai.load(options)` | Flat LLM status after load. |
+| `ai.llm.chat(request)` / `ai.fetchRequest(request)` | Validated OpenAI-like completion. |
+| `ai.llm.stream(request)` | Frozen async-iterator handle with `result` and `cancel(reason)`. |
+| `ai.streamRequest(request)` | Consumes the stream and returns text or `{toolName: argumentJsonString}`. |
+| `ai.unload()` | Cancels active work, releases the Wllama session, and returns flat unloaded status; verified DBOPFS cache remains. |
+| `ai.dispose()` | Permanently disposes the controller; explicit `store.remove(source)` is required to delete cached model bytes. |
+
+The controller emits `statechange` and `progress` through
+`addEventListener()`, `removeEventListener()`, or `on()`. Event `detail` is the
+current frozen status. Provider states are `unloaded`, `loading`, `ready`,
+`unloading`, and `error`.
+
+## Model authority and cache admission
+
+`createBrowserModelSource()` requires `id`, `name`, `immutableUrl`, `bytes`,
+`sha256`, `licenseSpdx`, and `sourceRevision`. The URL must be absolute HTTPS
+without credentials or a fragment. Revision-floating `main`, `master`, and
+`latest` path segments are rejected. `name` is one filename. `bytes` is a
+positive safe integer and `sha256` is exactly 64 hexadecimal characters.
+
+`licenseSpdx` and `sourceRevision` are required provenance labels supplied by
+the caller; the SDK does not independently prove the license or derive the
+revision from the URL. Redirects are followed and the final URL must remain
+HTTPS. Byte length and SHA-256 remain the actual admission authority.
+
+The DBOPFS adapter stores model bytes and then commits an
+`arcane.ai.browser-wasm.model.v2` completion manifest. It reopens and fully
+rehashes the bytes before returning an installed receipt and again before every
+verified cache reuse. Missing, malformed, stale, wrong-length, or wrong-digest
+entries are removed. `load({offline:true})` never performs a model request; it
+uses a fully rehashed cache or rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`.
+
+`localOnly:true` describes inference after load. It does not mean a cache miss
+cannot download. Source downloads use CORS, omit credentials and referrer,
+disable HTTP caching, and honor `AbortSignal`.
+
+## Streaming, cancellation, and tools
+
+```javascript
+const abort = new AbortController();
+const stream = ai.llm.stream({
+    localOnly:true,
+    signal:abort.signal,
+    messages:[{role:'user', content:'Summarize this text.'}],
+    maxTokens:128
+});
+
+const cancelButton = document.querySelector('[data-cancel-local-ai]');
+const cancel = () => abort.abort('user cancelled');
+cancelButton.addEventListener('click', cancel, {once:true});
+try {
+    for await (const chunk of stream) renderChunk(chunk);
+    const completion = await stream.result;
+    renderCompletion(completion);
+} catch (error) {
+    if (error?.code !== 'ARCANE_AI_REQUEST_ABORTED') throw error;
+    renderCancelled();
+} finally {
+    cancelButton.removeEventListener('click', cancel);
+}
+```
+
+An active cancellation rejects as `ARCANE_AI_REQUEST_ABORTED`. Requests are
+serialized; provider status exposes `busy` and `queued`. Supported request
+generation fields include temperature, top-K, top-P, min-P, repeat penalty,
+maximum tokens, seed, and stop sequences. Load settings separately include
+`contextTokens`, `batchTokens`, `microBatchTokens`, `threads`, and GPU-layer
+count. WebGPU is optional; cross-origin isolation and hardware fields are
+observations, not readiness promises.
+
+Tool definitions, tool choice, parallel-tool-call preference, and JSON or JSON
+Schema structured-output requests are passed to Wllama. Returned tool calls are
+validated and surfaced as structural data. Argument payloads remain JSON
+strings. The SDK never invokes a handler or executes a tool; application code
+must review policy, validate arguments, choose whether to execute, and submit a
+later tool result.
+
+## Errors and unavailable states
+
+Invalid configuration can throw `TypeError` or `RangeError`. Operational
+failures expose a stable `.code`; the internal error class is not exported.
+Handle the narrow code needed by the current operation and treat other failures
+as unavailable.
+
+| Area | Stable codes |
+| --- | --- |
+| Source and download | `ARCANE_AI_MODEL_SOURCE_INVALID`, `ARCANE_AI_MODEL_SOURCE_UNAVAILABLE`, `ARCANE_AI_MODEL_DOWNLOAD_FAILED`, `ARCANE_AI_MODEL_REDIRECT_BLOCKED`, `ARCANE_AI_MODEL_SIZE_MISMATCH`, `ARCANE_AI_MODEL_DIGEST_MISMATCH` |
+| Cache and storage | `ARCANE_AI_MODEL_CACHE_REJECTED`, `ARCANE_AI_MODEL_OFFLINE_MISS`, `ARCANE_AI_STORAGE_UNAVAILABLE`, `ARCANE_AI_STORAGE_READ_FAILED`, `ARCANE_AI_STORAGE_DELETE_FAILED` |
+| Lifecycle | `ARCANE_AI_UNAVAILABLE`, `ARCANE_AI_NOT_READY`, `ARCANE_AI_LOAD_FAILED`, `ARCANE_AI_UNLOAD_FAILED`, `ARCANE_AI_DISPOSE_FAILED`, `ARCANE_AI_DISPOSED`, `ARCANE_AI_OPERATION_SUPERSEDED` |
+| Requests | `ARCANE_AI_REQUEST_ABORTED`, `ARCANE_AI_REQUEST_FAILED`, `ARCANE_AI_INVALID_PROVIDER_RESULT`, `ARCANE_AI_LOCAL_ONLY_UNAVAILABLE`, `ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH` |
+| Diagnostics | `ARCANE_AI_PROBE_FAILED` |
+
+`capabilities()` reports browser observations such as WebAssembly, OPFS,
+WebGPU, secure context, cross-origin isolation, and hardware concurrency.
+Feature-detect them. The authoritative Chrome behavior passes without
+cross-origin isolation, so that flag is not a hard gate. `probe()` exercises
+packaged Wllama backend operations only while unloaded; it neither admits nor
+downloads a model.
+
+## BROWSER_WASM_RUNTIME_AUTHORITY
+
+### Overview
+
+Deep-frozen identity for the shipped browser runtime. Its protocol is
+`arcane-ai-browser-wasm/1`; the provider adapter uses
+`arcane-ai-adapter/1`. It records Wllama `3.6.0`, the embedded llama.cpp
+revision, authenticated module/WASM byte lengths and SHA-256 values, licenses,
+and the disabled compatibility-runtime and remote-model-helper policy.
+
+### Value and import
+
+```text
+const BROWSER_WASM_RUNTIME_AUTHORITY
+```
+
+### Availability and normalization
+
+**Browser metadata; safely inspectable without loading a model.** The value is
+an immutable receipt, not a provider instance, model catalog, or capability
+grant.
+
+### Example
+
+```javascript
+import {BROWSER_WASM_RUNTIME_AUTHORITY} from 'arcane-os/ai/browser-wasm';
+
+console.log(BROWSER_WASM_RUNTIME_AUTHORITY.protocol);
+console.log(BROWSER_WASM_RUNTIME_AUTHORITY.package.version); // 3.6.0
+```
+
+## createArcaneAI()
+
+### Overview
+
+Creates the application-facing facade around a provider or an existing LLM
+controller. Use this as the primary browser-local API; construct the source,
+store, and Wllama provider beneath it.
+
+### Signature and result
+
+```text
+createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})
+```
+
+At least one `llm` or `provider` is required; when both are supplied, `llm`
+takes precedence. `loadPolicy` is `on-demand` or `manual`. The frozen result
+contains `llm`, `runtime`, `status`, `load`,
+`unload`, `probe`, `fetchRequest`, `streamRequest`, and `dispose`.
+
+### Availability and normalization
+
+**Browser.** It normalizes provider lifecycle and request observation without
+selecting a model, changing browser permissions, contacting Arcane Core, or
+creating a fallback provider.
+
+### Example
+
+```javascript
+const ai = createArcaneAI({provider, loadPolicy:'manual'});
+const off = ai.llm.on('statechange', event => renderStatus(event.detail));
+await ai.load({offline:true});
+off();
+```
+
+## createBrowserModelSource()
+
+### Overview
+
+Validates caller-owned model provenance and creates the one cancellable HTTPS
+download source accepted by this provider.
+
+### Signature and result
+
+```text
+createBrowserModelSource(descriptor, { fetchImpl=null }={})
+```
+
+The frozen source includes `kind`, the seven canonical descriptor fields,
+`descriptor`, and `open({signal})`. `open()` returns a readable response body,
+requested/final URLs, and `cancel()`; it does not admit bytes to the cache.
+
+### Availability and normalization
+
+**Browser Fetch with CORS.** URL and metadata syntax are normalized; exact
+length and SHA-256 are enforced when the store installs the stream.
+
+### Example
+
+```javascript
+const source = createBrowserModelSource(MODEL);
+console.log(source.id, source.bytes, source.sha256);
+```
+
+## createBrowserWasmLlmProvider()
+
+### Overview
+
+Creates the local-only Wllama provider from genuine source and store objects
+created by this module. Structural lookalikes are rejected.
+
+### Signature and result
+
+```text
+createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})
+```
+
+The frozen result exposes protocol and provider identity, model metadata,
+`capabilities`, `status`, `load`, `unload`, `chat`, `stream`, `streamChat`,
+`use`, `probe`, and `dispose`. Direct provider `load()` returns `{model,status}`;
+the facade `ai.load()` returns the flat controller status.
+
+### Availability and normalization
+
+**Browser with WebAssembly and verified DBOPFS model bytes.** Inference is local
+after load. WebGPU is optional and defaults to zero GPU layers unless the caller
+selects otherwise.
+
+### Example
+
+```javascript
+const provider = createBrowserWasmLlmProvider({
+    source,
+    store,
+    loadDefaults:{threads:1, contextTokens:4096, gpuLayers:0}
+});
+console.log(provider.status().state); // unloaded
+```
+
+## createDbopfsModelStore()
+
+### Overview
+
+Adapts an existing DBOPFS instance without renaming or replacing its public
+methods. The adapter owns verified model-file and completion-manifest behavior.
+
+### Signature and result
+
+```text
+createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})
+```
+
+The frozen result contains `kind`, `tableName`, the original `adapter`, and
+`ready`, `openVerified`, `install`, `ensure`, and `remove`. `ensure()` returns a
+file, completion manifest, and cache state `verified` or `installed`.
+
+### Availability and normalization
+
+**Browser with a ready DBOPFS instance and OPFS.** Cache receipts are local
+integrity evidence. They are not transferable capability tokens and do not
+prove model license rights.
+
+### Example
+
+```javascript
+const store = createDbopfsModelStore({dbopfs});
+await store.ready();
+const cached = await store.openVerified(source);
+console.log(cached ? 'verified cache' : 'cache miss');
+```
+
+## Related reference
+
+- [Canonical `createArcaneAI()` entry](../sdk-api.md#createarcaneai) and the
+  sibling [`BROWSER_WASM_RUNTIME_AUTHORITY`](../sdk-api.md#browserwasmruntimeauthority),
+  [`createBrowserModelSource()`](../sdk-api.md#createbrowsermodelsource),
+  [`createBrowserWasmLlmProvider()`](../sdk-api.md#createbrowserwasmllmprovider),
+  and [`createDbopfsModelStore()`](../sdk-api.md#createdbopfsmodelstore) entries
+- [Browser-local normalization boundary](../availability-and-normalization.md#browser-local-provider-adapter)
+- [Authenticated browser runtime delivery](../protocols.md#browser-runtime-delivery)
+- [Browser-WASM behavior evidence](../behavioral-testing.md#behavioral-coverage-model)
+- [DBOPFS runtime module](../runtime-modules.md#dbopfsjs)

package/docs/reference/availability-and-normalization.md

@@ -29,6 +29,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Scaffold, inspect, test, package, bundle, build, verify, or run an app | `arcane` CLI or `arcane-os` package functions | **Node**; native targets invoke one explicit provider | CLI events and SDK errors/results are normalized by versioned SDK contracts. Native artifact receipts remain target-specific inside a common receipt lifecycle. |
 | Publish application events or review a bounded event history | `arcane-os/event-manager` | **Node** and **Browser**; optional DOM capture needs a browser DOM or compatible host | Live listeners receive original arguments. Recorded payloads and metadata become bounded, redacted, deeply frozen `arcane-event-stack/1` snapshots. The stack format is local diagnostic data, not a host transport. |
 | Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
+| Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; WebAssembly and OPFS/DBOPFS are required, WebGPU is optional, and a cache miss uses the caller's admitted HTTPS model URL unless `offline:true` | The facade normalizes lifecycle, status, streaming, cancellation, and structural tool-call visibility. Model URL, byte length, SHA-256, license identifier, and revision remain explicit caller authority. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use OpenAI from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level AI chat/text behavior is normalized by the module; raw provider diagnostics and some response detail remain provider-specific. No automatic cloud fallback is inferred from local failure. |
@@ -77,6 +78,22 @@ deeply frozen, and strictly importable as `arcane-event-stack/1`. DOM
 instrumentation adds browser diagnostics only; it does not replay browser
 state. See [EventManager and time-travel review](event-manager.md).
 
+### Browser-local provider adapter
+
+[`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) exposes the same
+`arcane-ai-adapter/1` LLM lifecycle used by `createArcaneAI()`, while its
+packaged Wllama engine and caller-supplied model run inside the browser. This
+surface does not require an Arcane Core method grant because it does not call a
+Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and
+resource limits still apply.
+
+`localOnly:true` describes inference after load; it does not promise that load
+is offline. A normal cache miss downloads from the exact caller-supplied HTTPS
+URL. `load({offline:true})` permits only an existing cache entry whose model
+bytes are fully rehashed, otherwise it rejects with
+`ARCANE_AI_MODEL_OFFLINE_MISS`. Tool calls are result data for application
+review and dispatch; the SDK never executes them.
+
 ### Arcane bridge-normalized
 
 Core-backed calls return promises and reject with `Arcane.Error`. Transport

package/docs/reference/behavioral-testing.md

@@ -37,6 +37,7 @@ release acceptance.
 | EventManager and event stacks | Live pub/sub ordering and payload identity, nested causation, immutable/redacted snapshots, strict import, bounded overflow, seek, all playback modes/lifecycle outcomes, cancellation, and DOM start/stop/privacy behavior. | Real user journeys and browser layout belong in a browser harness; event-stack review never proves that external side effects can be replayed. |
 | CLI | Commands parse, acknowledge, select one scope, produce normalized human/JSON/NDJSON output, propagate cancellation/failure, and reject invalid cardinality. | Native build/run requires the selected real provider and host. |
 | Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
+| Browser-WASM local AI | The exact five-export namespace, runtime authority, model-source validation, DBOPFS adapter contract, provider/facade lifecycle, lazy/manual policy, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | The publication gate installs the packed SDK into a real Chrome app, loads the authenticated Wllama 3.6.0 JS/WASM assets, performs a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and a verified offline reload with zero model requests. It is an explicit heavyweight capability gate, not an implicit model download in every local `npm run check`. |
 | Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
 | Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |
 | Native providers | Plan/provider protocol, explicit target, receipt authentication, artifact reader, and unavailable-path honesty are tested with bounded fixtures. | Exact Windows, Linux, or Android artifact verification and launch must run on that actual platform/architecture. |
@@ -53,6 +54,13 @@ client contract. They must assert the exact request sent to the fake and the
 normalized result returned to the application. A fake provider never counts as
 native host, artifact, installation, or model-service evidence.
 
+The browser-WASM guide follows the same rule: it shows exact model authority
+and wiring, but leaves the download/load call behind an explicit user action.
+The authoritative browser contract separately proves that admitted bytes are
+hashed before DBOPFS completion metadata is committed, cached bytes are rehashed
+before offline reuse, `AbortSignal` settles as `ARCANE_AI_REQUEST_ABORTED`, and
+tool-call arguments are surfaced without invoking application handlers.
+
 ## Host and normalization cases
 
 Cross-host APIs should cover at least these cases at their owning layer:

package/docs/reference/cli.md

@@ -16,6 +16,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane new <id>` | Creates one external app workspace. |
 | `arcane init [id]` | Initializes one app in an external or integrated workspace without rewriting unrelated files. |
 | `arcane doctor` | Reads and reports Node/tooling, SDK runtime, workspace, optional Arcane source recognition, and supported managed ArcaneOllama readiness. |
+| `arcane import-map` | Authenticates and refreshes one app's managed browser import map and matching HTML entry. |
 | `arcane dev` | Starts one owned browser development server for one selected app. |
 | `arcane test` | Runs one app test boundary or one explicit integrated shared test file. |
 | `arcane check` | Validates one app boundary or the canonical integrated shared check. |
@@ -162,6 +163,88 @@ failure into a failed doctor result.
 npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 ```
 
+## `arcane import-map`
+
+### Overview
+
+Authenticates one selected application's physical browser runtime, generates
+its standard browser import map, and commits the map artifact and matching
+managed HTML entry as one bounded refresh.
+
+```text
+arcane import-map [--workspace <directory>] [--app <id>]
+```
+
+`--workspace` defaults to the current directory. `--app` selects one app when
+the workspace does not already identify exactly one. The command accepts no
+positional arguments and supports app scope only. `arcane-os import-map` is the
+identical executable alias.
+
+The generated artifact is
+`apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
+the app entry as `<script type="importmap" data-arcane-import-map>` before
+module loading. In SDK `0.1.1`, the authenticated physical-v1 runtime produces
+86 entries and intentionally has no package-root mapping.
+
+### Result and safety
+
+Success returns the normal selected-workspace wrapper:
+
+```javascript
+{
+    workspaceRoot,
+    workspaceMode, // 'external' or 'integrated'
+    appId,
+    importMap:{
+        appId,
+        artifactPath,
+        artifactRelativePath,
+        entryPath,
+        imports,
+        entryCount:86,
+        excludedModules:['modules/CaseEvidenceIndexer.js'],
+        files:[
+            {role:'artifact',path,bytes,sha256},
+            {role:'entry',path,bytes,sha256}
+        ],
+        cleanupWarnings,
+        committed:true
+    }
+}
+```
+
+The two file records bind the committed byte length and SHA-256 for the artifact
+and HTML entry. A post-commit observer failure preserves delivery as a successful
+receipt with `eventDelivery.status === 'degraded'` and
+`ARCANE_EVENT_DELIVERY_FAILED`; it does not roll back valid application bytes.
+Packaging refuses a committed refresh that reports cleanup warnings.
+
+The canonical integrated-legacy workspace has a deliberate compatibility
+result instead of an artifact: `importMap.skipped` is `true`,
+`importMap.compatibility` is `'integrated-legacy'`, and the reason states that
+the physical two-route browser runtime is retained.
+
+`new` and `init` generate the map during scaffolding. `dev` refreshes it once
+before binding; non-dry-run `package` and browser `build` refresh it before
+collection. Paired native packaging refreshes each packaged app. `test`,
+`check`, `verify`, `bundle`, and browser `run` do not regenerate it. There is no
+watcher, polling, scheduled refresh, download, or self-update behavior.
+
+There is no supported `--dry-run` for `import-map`: do not pass that parser-wide
+flag because this command performs the real commit. Import-map-specific failures
+use `ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, or
+`ARCANE_IMPORT_MAP_COLLISION`; packaging can additionally report
+`ARCANE_IMPORT_MAP_CLEANUP_FAILED`. Workspace, policy, usage, busy, and
+cancellation failures retain their normal SDK codes.
+
+### Example
+
+```bash
+npm exec -- arcane import-map --workspace . --app hello-world --output json
+```
+
+Deep details: [authenticated browser delivery and receipts](protocols.md#browser-runtime-delivery).
+
 ## `arcane dev`
 
 ### Overview
@@ -471,9 +554,9 @@ Success returns:
 ```javascript
 {
     packageName:'arcane-os',
-    currentVersion:'0.1.0-dev.4',
-    registryVersion:'0.1.0-dev.5',
-    tag:'dev',
+    currentVersion:'0.1.0',
+    registryVersion:'0.1.1',
+    tag:'latest',
     status:'update-available', // or 'current' or 'ahead'
     updateAvailable:true,
     registry:'https://registry.npmjs.org',