arcane-os 0.1.0 → 0.1.2

package/docs/reference/event-manager.md

@@ -16,7 +16,10 @@ The API is capability-first:
 
 All 20 JavaScript exports are available from both `arcane-os` and
 `arcane-os/event-manager`. The bindings are identical, so choose the focused
-subpath when event instrumentation is the only SDK capability you need.
+subpath when event instrumentation is the only SDK capability you need. Node
+can resolve either package entrypoint. The generated browser map intentionally
+exposes only the focused `arcane-os/event-manager` entry, not the Node package
+root.
 
 ## Quick start
 
@@ -53,15 +56,21 @@ bounded, export intentionally, then call `clearHistory()`.
 
 | Capability | Node | Browser renderer | Native/Core host | Remote or cloud | Normalization |
 | --- | --- | --- | --- | --- | --- |
-| Pub/sub, semantic instrumentation, parse/export, seek, playback | Yes | Yes, through a bundler or import map | Only when the SDK module runs in that JavaScript host | No automatic transport | Same synchronous API; optional immutable JSON-like snapshots |
+| Pub/sub, semantic instrumentation, parse/export, seek, playback | Yes | Yes, through a bundler or the managed Arcane import map | Only when the SDK module runs in that JavaScript host | No automatic transport | Same synchronous API; optional immutable JSON-like snapshots |
 | DOM selectors and target descriptions | With DOM-like values or a test shim | Yes | No native UI observation | No | Stable diagnostic descriptors |
 | DOM interaction and mutation capture | No native DOM | Yes | No | No | DOM activity becomes semantic event-stack records |
 | Event-stack schema | Yes | Yes | Data contract only | Can be transported explicitly by the developer | `arcane-event-stack/1` |
 
-An unbundled browser must serve and map `arcane-os` and `event-pubsub`. The
-hash-pinned Arcane browser runtime does not automatically inject this SDK-authored
-module into Shell, Provisioner, Core, or built-in apps. There is no transparent
-fallback to `arcane/1`, HTTP, WebSocket, Ollama, or a cloud event service.
+In an external or physical-v1 integrated workspace, the managed browser map
+resolves `arcane-os/event-manager` to
+`./arcane/sdk/event-manager.mjs` and its private bare dependency
+`event-pubsub` to
+`./arcane/sdk/dependencies/event-pubsub/index.js`. The canonical
+integrated-legacy workspace retains its older physical routes instead. The
+hash-pinned Arcane browser runtime does not inject this SDK-authored module into
+Shell, Provisioner, Core, or built-in apps. There is no transparent fallback to
+the Node package root, `arcane/1`, HTTP, WebSocket, Ollama, or a cloud event
+service.
 
 ## Export summary
 

package/docs/reference/inventory/package-api.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.1.0-dev.5",
+  "sdkVersion": "0.1.2",
   "environment": {
-    "runtime": "Node.js",
-    "minimumVersion": "22.23.2",
+    "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
+    "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 158,
+  "memberCount": 163,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2627,6 +2627,86 @@
       "availability": "Node; on-demand CLI or maintainer check only",
       "protocol": "Approved credential-free HTTPS registry origin",
       "normalization": "Returns a normalized URL object only for an exact allowed root origin"
+    },
+    {
+      "id": "browser-wasm:BROWSER_WASM_RUNTIME_AUTHORITY",
+      "name": "BROWSER_WASM_RUNTIME_AUTHORITY",
+      "displayName": "BROWSER_WASM_RUNTIME_AUTHORITY",
+      "kind": "constant",
+      "signature": "const BROWSER_WASM_RUNTIME_AUTHORITY",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Deep-frozen authority for the packaged Wllama and llama.cpp runtime, authenticated JS and WASM assets, licensing, and disabled compatibility-network policy.",
+      "availability": "Browser metadata; import and inspection require neither DBOPFS nor a loaded model",
+      "protocol": "arcane-ai-browser-wasm/1 over the provider-neutral arcane-ai-adapter/1 boundary",
+      "normalization": "Exact immutable runtime and component identity; it contains no model weights or model catalog"
+    },
+    {
+      "id": "browser-wasm:createArcaneAI",
+      "name": "createArcaneAI",
+      "displayName": "createArcaneAI()",
+      "kind": "function",
+      "signature": "createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Creates the provider-neutral browser AI facade and LLM lifecycle controller around one compatible provider or controller.",
+      "availability": "Browser; the selected provider observes its own WebAssembly, storage, and model readiness",
+      "protocol": "arcane-ai-adapter/1",
+      "normalization": "Normalizes lazy or manual load, lifecycle status, cancellation, streaming completion, and structural tool-call visibility without executing tools"
+    },
+    {
+      "id": "browser-wasm:createBrowserModelSource",
+      "name": "createBrowserModelSource",
+      "displayName": "createBrowserModelSource()",
+      "kind": "function",
+      "signature": "createBrowserModelSource(descriptor, { fetchImpl=null }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Validates a caller-supplied immutable HTTPS model authority and creates its cancellable no-credentials download source.",
+      "availability": "Browser with Fetch and a readable response body; each direct open call performs its configured HTTPS fetch",
+      "protocol": "Caller-supplied exact model URL, expected byte length, SHA-256, license identifier, and source revision",
+      "normalization": "Canonical frozen descriptor and download handle; byte integrity is verified by the model store before admission"
+    },
+    {
+      "id": "browser-wasm:createBrowserWasmLlmProvider",
+      "name": "createBrowserWasmLlmProvider",
+      "displayName": "createBrowserWasmLlmProvider()",
+      "kind": "function",
+      "signature": "createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Creates the packaged Wllama browser provider with verified model admission, serialized inference, streaming, abort, unload, and probe operations.",
+      "availability": "Browser; WebAssembly required, WebGPU optional, and model loading requires verified DBOPFS bytes",
+      "protocol": "arcane-ai-adapter/1 with OpenAI-like chat completion and streaming envelopes",
+      "normalization": "Frozen lifecycle/status/capability records and structured tool-call data; the SDK never invokes application tools"
+    },
+    {
+      "id": "browser-wasm:createDbopfsModelStore",
+      "name": "createDbopfsModelStore",
+      "displayName": "createDbopfsModelStore()",
+      "kind": "function",
+      "signature": "createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})",
+      "entrypoints": [
+        "arcane-os/ai/browser-wasm"
+      ],
+      "primaryImport": "arcane-os/ai/browser-wasm",
+      "group": "Browser-WASM local AI",
+      "summary": "Adapts an existing DBOPFS instance into an authenticated model cache that commits metadata last and rehashes cached bytes before reuse.",
+      "availability": "Browser with a ready DBOPFS instance and OPFS support",
+      "protocol": "arcane.ai.browser-wasm.model.v2 completion manifests over existing DBOPFS method semantics",
+      "normalization": "Returns verified or installed cache receipts, fail-closed offline misses, progress snapshots, and explicit removal without changing DBOPFS public names"
     }
   ]
 }

package/docs/reference/protocols.md

@@ -47,6 +47,14 @@ These protocols normalize orchestration and evidence. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
+Managed browser imports have three supported control-plane entrypoints. The CLI
+uses `arcane import-map`; Node callers use
+`executeOperation('import-map', options)` or
+`createToolchain(defaults).importMap(options)`. These are three routes to the
+same app-scoped operation, not three import-map formats. There is no exported
+`importMapApplication()` function, `generateImportMap()` function, or
+`arcane-os/import-map` package subpath.
+
 ## Central events and time-travel data
 
 `arcane-os/event-manager` is host-neutral JavaScript. Its live event path is
@@ -83,18 +91,106 @@ surface, DOM privacy defaults, playback modes, and recovery behavior.
 
 ## Browser runtime delivery
 
-External and integrated workspaces keep the same application URLs. Runtime ESM
-is served beneath `/arcane`, the vendored dependency beneath
-`/node_modules/strong-type`, and license material beneath
-`/licenses/arcane-os`. A browser import such as:
+External and modern integrated workspaces keep the same application URLs and a
+browser-standard import map. Each selected app owns
+`apps/<id>/modules/arcane.importmap.json`; the exact canonical JSON is also
+embedded in its HTML entry as a managed `<script type="importmap"
+data-arcane-import-map>`. The map follows `<base>` and precedes module scripts,
+classic scripts, and module preloads, so application code can use stable named
+imports such as:
 
 ```javascript
-import ollama from '/arcane/modules/Ollama.js';
+import ollama from 'arcane/Ollama';
+```
+
+The authenticated physical-v1 tree lives entirely beneath `arcane/`. It
+contains 155 pinned Arcane runtime files plus 18 SDK browser-runtime files:
+173 files in all. Runtime `strong-type` 1.1 stays under
+`arcane/dependencies/strong-type/`; the focused SDK event surface lives under
+`arcane/sdk/`, with `event-pubsub` 6.1 and its sibling `strong-type` 2.0 under
+`arcane/sdk/dependencies/`. This URL-key separation prevents the runtime and SDK
+dependency versions from aliasing one another. Development serves the selected
+app plus that authenticated tree. Packaging copies the same map, app entry, and
+physical bytes into `dist/<id>`; targets never resolve through the consumer
+workspace's root `node_modules/`.
+
+In SDK `0.1.1`, the generated map has exactly 86 entries: 73 named
+`arcane/*` modules, nine `arcane/entities/*` modules, and these four focused or
+compatibility mappings:
+
+| Browser specifier | Physical target |
+| --- | --- |
+| `arcane-os/event-manager` | `./arcane/sdk/event-manager.mjs` |
+| `arcane-os/ai/browser-wasm` | `./arcane/sdk/ai/browser-wasm.mjs` |
+| `event-pubsub` | `./arcane/sdk/dependencies/event-pubsub/index.js` |
+| `./node_modules/strong-type/index.js` | `./arcane/dependencies/strong-type/index.js` |
+
+There is no `arcane-os` package-root mapping, bare `strong-type` mapping, or
+catch-all `arcane/` prefix. Host-internal `CaseEvidenceIndexer.js` is explicitly
+excluded; classic scripts, workers, stylesheets, and other non-ESM assets use
+their documented URL or host loading contract rather than invented package
+bindings.
+
+The imported module can be pure browser logic, standard-Web-API logic, or a
+client of `globalThis.Arcane`. Import-map resolution is not a new Arcane wire
+protocol, Core capability, network authority, or provider fallback. Import
+transport and host RPC remain separate layers.
+
+The canonical integrated-legacy Arcane OS root is the documented exception. It
+retains its physical `/arcane` and `/node_modules/strong-type` routes, returns
+an `integrated-legacy` skip receipt, and does not create the managed map pair.
+
+<details>
+<summary>Refresh lifecycle and two-file commit behavior</summary>
+
+Scaffolding (`new` and `init`) creates the map. `dev` refreshes once before
+binding. Non-dry-run `package`, browser `build`, and paired native packaging
+refresh before collecting source. `test`, `check`, `verify`, `bundle`, and
+browser `run` do not refresh. Dry-run packaging/build validates an existing map
+without rewriting it, and `import-map` itself has no supported dry-run.
+
+Generation stages the artifact and HTML entry beside their destinations,
+checks directory and file identity under the workspace-operation lock, and
+uses backups to restore the prior pair after a handled pre-commit failure.
+Success reports `committed: true` and SHA-256/byte-length records for both
+files. Cleanup failures after commit remain warnings on the valid receipt;
+packaging rejects them rather than publishing ambiguous state. This is a
+bounded handled-error transaction, not a claim of one filesystem-atomic rename
+for both files and not a durable crash journal.
+
+No app watches, polls, downloads, or self-updates this map. An active operation's
+heartbeat is event telemetry only and never regenerates browser state.
+
+</details>
+
+<details>
+<summary>SDK browser-runtime admission and exact receipt fields</summary>
+
+`arcane.lock.json.sdkBrowserRuntime` persists the trusted manifest path,
+`manifestSha256`, `contentSha256`, `builder`, `sdkVersion`, and `source` record.
+For SDK `0.1.1` those identities are:
+
+```text
+manifest: node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json
+manifestSha256: 33396b3d35322b784929270e7ca0a2a8b31d899c6e77bcb227edc95b37d0ae7d
+contentSha256: 5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00
+builder: arcane-sdk-browser-runtime-v1
+sdkVersion: 0.1.1
+source.protocol: arcane-sdk-browser-runtime/1
+source.browserEntry: arcane-os/event-manager
 ```
 
-uses browser ESM in every renderer. The imported module can be pure browser
-logic, standard-Web-API logic, or a client of `globalThis.Arcane`. Import
-transport and host RPC are separate layers.
+The `source` record also binds the `arcane-os-sdk` authority/repository and the
+exact `event-pubsub` 6.1.0 and `strong-type` 2.0.0 package identities. Before a
+workspace tree is admitted, the same-process verifier returns
+`schemaVersion`, `kind`, `canonicalLocation`, `rootIdentity`, `manifestPath`,
+`manifestSha256`, `manifestIdentity`, `builder`, `sdkVersion`, `source`,
+`files`, `fileCount`, `totalBytes`, `contentSha256`, `identities`,
+`sourceIdentities`, and `directories`. Those object-identity-bound verifier
+receipts are authority inside the issuing process; reconstructing the same JSON
+does not recreate authority.
+
+</details>
 
 ## Arcane application protocol
 
@@ -190,7 +286,7 @@ Arcane normalizes the outer promise/error and stream lifecycle. `chatText`,
 
 ## Explicit cloud provider path
 
-`/arcane/modules/AI.js` can use an explicitly selected and configured cloud
+`arcane/AI` can use an explicitly selected and configured cloud
 profile over HTTPS. That path is not Core transport fallback. The module adapts
 the selected provider into its high-level application behavior, while provider
 diagnostics and optional fields can remain provider-specific. Native policy and
@@ -231,11 +327,14 @@ The common contract ends where platform truth must remain different:
 
 ## Receipt and generation boundaries
 
-SDK runtime, app releases, bundles, native plans, providers, and artifacts use
-identity-bound receipts. A receipt binds the exact location, filesystem
-identity, bytes/inventory hashes, policy, toolchain, platform/architecture,
-signer/trust result where applicable, and generation. Mutation invalidates the
-receipt before bytes or authority change.
+SDK runtime, app releases, import-map artifact/entry pairs, bundles, native
+plans, providers, and artifacts use identity-bound receipts. The import-map
+receipt binds each committed relative path, byte length, and SHA-256 in
+addition to its exact imports, entry count, exclusions, and cleanup state. A
+runtime or release receipt binds the exact location, filesystem identity,
+bytes/inventory hashes, policy, toolchain, platform/architecture, signer/trust
+result where applicable, and generation. Mutation invalidates the receipt
+before bytes or authority change.
 
 Process-local receipts do not authorize reuse across Shell, Core, providers, or
 other processes. Cross-process reuse requires an authenticated shared host or

package/docs/reference/sdk-api.md

@@ -1,11 +1,21 @@
 # Arcane OS SDK JavaScript API
 
-The npm package exposes a Node.js ESM control plane. It is not a browser-importable renderer API. Use the synchronized modules under `/arcane/` for application code and use `globalThis.Arcane` for capability-gated native calls.
+The npm package exposes a Node.js ESM control plane, the Node-and-browser
+`arcane-os/event-manager` entrypoint, and the browser-only
+`arcane-os/ai/browser-wasm` entrypoint. Application code otherwise uses named
+modules from the managed browser map, such as `arcane/ThemeBootstrap`, and
+calls `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.
 
 ## Import map
 
+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 that 86-entry physical-runtime contract.
+
 | Specifier | Purpose |
 | --- | --- |
 | `arcane-os` | Complete high-level SDK surface. |
@@ -19,6 +29,7 @@ This page is the canonical inventory for every JavaScript name reachable through
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
 | `arcane-os/event-manager` | Central synchronous events, bounded time-travel history, playback, and optional DOM instrumentation. |
+| `arcane-os/ai/browser-wasm` | Caller-authenticated browser-local Wllama inference, verified DBOPFS model caching, streaming, cancellation, and structural tool-call results. |
 
 JSON schemas, the runtime manifest, and `package.json` are data-only export subpaths. In Node ESM, import JSON with `with {type: 'json'}`, or resolve and read it explicitly.
 
@@ -68,14 +79,19 @@ Protocol mechanics are intentionally kept in the [deep protocol guide](protocols
 | `authenticateSharedPayloadSnapshot()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `buildApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `buildTarget()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
+| `BROWSER_WASM_RUNTIME_AUTHORITY` | constant | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser metadata; no model or DBOPFS required to inspect |
 | `bumpVersion()` | function | `arcane-os/packager` | Packaging and release bundles | Node |
 | `bundleApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `checkApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `CLI_EVENT_PROTOCOL` | constant | `arcane-os` | Identity and protocol constants | Node |
 | `CLI_NAME` | constant | `arcane-os` | Identity and protocol constants | Node |
 | `createApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
+| `createArcaneAI()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; compatible LLM provider or controller required |
 | `createAppReleaseBundle()` | function | `arcane-os` | Packaging and release bundles | Node |
+| `createBrowserModelSource()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser Fetch with a readable response body |
+| `createBrowserWasmLlmProvider()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; WebAssembly and verified DBOPFS model bytes |
 | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
+| `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
 | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createNativeTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createReporter()` | function | `arcane-os` | Events, processes, and testing | Node |
@@ -2634,6 +2650,13 @@ Frozen registry of stable SDK error-code strings.
 registry, timeout, HTTP, or response failure; caller cancellation remains the
 separate `ERROR_CODES.cancelled` value.
 
+The import-map operation also reports the stable operation-specific strings
+`ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, and
+`ARCANE_IMPORT_MAP_COLLISION`; package assembly can additionally report
+`ARCANE_IMPORT_MAP_CLEANUP_FAILED`. They are normalized `ArcaneError.code`
+values, but are not properties added to this frozen general registry in SDK
+`0.1.1`.
+
 ### Value and import
 
 ```text
@@ -3417,9 +3440,12 @@ async function usecreateApplication(...arguments_) {
 
 Returns a frozen convenience object that applies shared defaults to every headless application operation.
 
-The object includes `updateCheck(options)`, which merges defaults with the
-explicit call options and invokes `checkSdkUpdate()` once. Constructing the
-toolchain does not check, poll, schedule, download, install, or mutate anything.
+The object includes `importMap(options)`, which merges defaults with explicit
+call options and performs one selected app's authenticated map refresh. The
+equivalent generic route is `execute('import-map', options)`. It also includes
+`updateCheck(options)`, which invokes `checkSdkUpdate()` once. Constructing the
+toolchain does not check, poll, schedule, download, install, regenerate, or
+mutate anything.
 
 ### Signature and result
 
@@ -3440,14 +3466,15 @@ import {createToolchain} from 'arcane-os';
 
 const toolchain = createToolchain({
     workspaceRoot: process.cwd(),
+    appId:'hello-world',
     onEvent(event) {
         console.info(event.type);
     }
 });
 
-// Only this explicit call performs the single bounded registry request.
-const status = await toolchain.updateCheck();
-console.log(status.status);
+// Only this explicit call refreshes the managed map and HTML entry.
+const result = await toolchain.importMap();
+console.log(result.importMap.entryCount); // 86 in SDK 0.1.1
 ```
 
 ## describeTargets()
@@ -3512,9 +3539,18 @@ async function usedevelopApplication(...arguments_) {
 
 Dispatches one named headless SDK operation with normalized acceptance, events, cancellation, and failure.
 
+The exact command `'import-map'` dispatches one app-scoped authenticated refresh
+and returns `{workspaceRoot, workspaceMode, appId, importMap}`. A normal
+`importMap` value binds the generated imports and the committed map/HTML file
+hashes; the canonical integrated-legacy layout returns its documented skip
+record instead. This route mutates the two managed application files and has no
+supported dry-run.
+
 The exact command `'update-check'` dispatches one `checkSdkUpdate(options)`
-call. Dispatch never installs a recurring task and never causes another command
-to check for updates implicitly.
+call. Dispatch never installs a recurring task, polls application state, or
+causes another command to check for updates implicitly. There is no exported
+`importMapApplication()` or `generateImportMap()` binding and no
+`arcane-os/import-map` package subpath.
 
 ### Signature and result
 
@@ -3533,8 +3569,11 @@ Import it from `arcane-os` or `arcane-os/toolchain`. The signature above states
 ```javascript
 import {executeOperation} from 'arcane-os';
 
-const result = await executeOperation('update-check');
-console.log(result.status, result.registryVersion);
+const result = await executeOperation('import-map', {
+    workspaceRoot:process.cwd(),
+    appId:'hello-world'
+});
+console.log(result.importMap.committed, result.importMap.entryCount);
 ```
 
 ## packageApplication()
@@ -4896,6 +4935,200 @@ const stack = parseEventStack(serialized);
 console.log(stack.sessionId, stack.events.length);
 ```
 
+## BROWSER_WASM_RUNTIME_AUTHORITY
+
+### Overview
+
+Deep-frozen authority for the browser-only runtime behind
+`arcane-os/ai/browser-wasm`. It records protocol
+`arcane-ai-browser-wasm/1`, `@wllama/wllama` `3.6.0`, the embedded llama.cpp
+revision, the exact packaged JavaScript and WebAssembly assets, retained MIT
+licenses, and the disabled compatibility-runtime/remote-model-helper policy.
+It contains no model weights or model catalog.
+
+### Value and import
+
+```text
+const BROWSER_WASM_RUNTIME_AUTHORITY
+```
+
+The value is available from `arcane-os/ai/browser-wasm` only. Importing and
+inspecting it does not initialize Wllama, request storage, or download a model.
+
+### Availability and normalization
+
+**Browser metadata.** This is an immutable component receipt, not a provider,
+model, browser-permission grant, or proof that WebAssembly/OPFS is available.
+
+### 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);
+```
+
+Complete lifecycle, model authority, cache, cancellation, and tool behavior:
+[Browser-WASM local AI](ai/browser-wasm.md).
+
+## createArcaneAI()
+
+### Overview
+
+Creates the application-facing LLM facade around a compatible provider or
+controller. The default `on-demand` policy loads before first use; `manual`
+requires an explicit successful `load()` before requests. When both `llm` and
+`provider` are supplied, `llm` takes precedence.
+
+### Signature and result
+
+```text
+createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})
+```
+
+At least one `llm` or `provider` is required. The frozen facade contains
+`llm`, `runtime`, `status`, `load`, `unload`, `probe`, `fetchRequest`,
+`streamRequest`, and `dispose`. `status()` returns `{llm: status}`; lifecycle
+methods return the flat LLM status. `fetchRequest()` returns the completion.
+`streamRequest()` consumes streaming and returns text or a tool-name-to-JSON-
+argument-string record. Use `ai.llm.stream()` for the async iterator.
+
+### Availability and normalization
+
+**Browser.** It normalizes lifecycle, state/progress events, lazy/manual use,
+cancellation, completions, and structural tool-call visibility. It neither
+selects a provider fallback nor executes an application tool.
+
+### Example
+
+```javascript
+const ai = createArcaneAI({provider, loadPolicy:'manual'});
+const stop = ai.llm.on('progress', event => renderProgress(event.detail));
+await ai.load({offline:true});
+stop();
+```
+
+## createBrowserModelSource()
+
+### Overview
+
+Validates a caller-owned model descriptor and creates the cancellable HTTPS
+source accepted by the browser-WASM store/provider. Required fields are `id`,
+`name`, `immutableUrl`, `bytes`, `sha256`, `licenseSpdx`, and
+`sourceRevision`. `bytes` is the expected positive safe-integer byte length,
+not inline data.
+
+### Signature and result
+
+```text
+createBrowserModelSource(descriptor, { fetchImpl=null }={})
+```
+
+The URL must be absolute HTTPS with no credentials or fragment and no
+revision-floating `main`, `master`, or `latest` path. The SHA-256 value is
+exactly 64 hexadecimal characters. The frozen source exposes its canonical
+descriptor and `open({signal})`, which returns `{body, requestedUrl, finalUrl,
+cancel}`. Every direct `open()` performs the configured fetch. The SDK records
+but does not independently prove the supplied license identifier or revision.
+
+### Availability and normalization
+
+**Browser Fetch with CORS and a readable response body.** Downloads omit
+credentials/referrer, disable HTTP caching, follow redirects, require a final
+HTTPS URL, compare `Content-Length` when present, and honor `AbortSignal`.
+Actual length and digest admission belongs to the DBOPFS store.
+
+### Example
+
+```javascript
+const source = createBrowserModelSource({
+    id:'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'
+});
+```
+
+## createBrowserWasmLlmProvider()
+
+### Overview
+
+Creates the packaged Wllama provider from genuine source and store objects
+created by this module. It serializes requests and exposes provider states
+`unloaded`, `loading`, `ready`, `unloading`, and `error`.
+
+### Signature and result
+
+```text
+createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})
+```
+
+The frozen provider exposes `protocol`, `id`, `model`, `capabilities`,
+`status`, `load`, `unload`, `chat`, `stream`, `streamChat`, `use`, `probe`, and
+`dispose`. Load settings include offline mode, `AbortSignal`, progress,
+threads, context/batch/micro-batch tokens, and GPU layers. Chat supports
+OpenAI-like message/generation fields, tools, tool choice, parallel tool-call
+preference, and JSON/JSON-Schema structured output. `stream()` returns a frozen
+async iterator with `result` and `cancel(reason)`.
+
+### Availability and normalization
+
+**Browser with WebAssembly and a verified DBOPFS model.** WebGPU and
+cross-origin isolation are capability observations, not promised gates.
+Returned tools are validated structural data; the SDK never calls a handler.
+Cancellation normalizes to `ARCANE_AI_REQUEST_ABORTED`.
+
+### 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 into an authenticated model cache without
+renaming its public methods. The adapter commits model bytes before the
+`arcane.ai.browser-wasm.model.v2` completion manifest and then reopens and
+rehashes the stored file.
+
+### 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
+`{file, manifest, cache:'verified'|'installed'}`. Every cache reuse rehashes the
+actual bytes. `offline:true` never downloads and rejects a miss with
+`ARCANE_AI_MODEL_OFFLINE_MISS`. Invalid cache records are removed fail closed.
+
+### Availability and normalization
+
+**Browser with a ready DBOPFS instance and OPFS.** The cache is local integrity
+evidence, not a transferable capability or license proof. Unload/dispose keep
+the cache; `store.remove(source)` explicitly deletes it.
+
+### Example
+
+```javascript
+const store = createDbopfsModelStore({dbopfs});
+await store.ready();
+const cached = await store.openVerified(source);
+console.log(cached ? 'verified cache' : 'cache miss');
+```
+
 ## Data export subpaths
 
 The package also exposes the exact runtime manifest, eight JSON Schemas (including `arcane-os/schemas/event-stack.json`), and its package manifest. These are data contracts, not callable JavaScript members. See [schema and manifest contracts](../architecture.md) and the files under `schemas/`.