arcane-os 0.1.1 → 0.2.0

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

@@ -0,0 +1,394 @@
+# 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.2`'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',
+    url:'https://models.example/revisions/4f7c/model-q4.gguf',
+    bytes:123456789,
+    sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
+});
+
+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',
+    security:{secure:true}
+});
+
+// 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 an optional 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; the 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, security, and cache admission
+
+The canonical model descriptor is `{id, url, bytes?, sha256?}`. `id` and `url`
+are required. The URL must be absolute HTTPS without credentials or a fragment;
+revision-floating `main`, `master`, and `latest` path segments are rejected.
+When supplied, `bytes` is a positive safe integer and `sha256` is exactly 64
+hexadecimal characters.
+
+App, provider/model-binding, and load-operation options use the same
+plain-JavaScript shape:
+
+```javascript
+{
+    security:{
+        secure:true,
+        checks:{byteLength:true, sha256:true}
+    }
+}
+```
+
+The SDK default is `secure:false`. Security fields resolve independently from
+the load operation, then provider/model binding, then app configuration, then
+the SDK default. Omitted fields inherit; they do not become `false`. After
+resolution, `secure:true` makes both checks enabled by default and
+`secure:false` makes both checks disabled by default. An explicit inherited or
+lower-scope `checks.byteLength` or `checks.sha256` boolean overrides that secure
+default for its check.
+
+An enabled byte-length check requires descriptor `bytes` and compares it with
+the actual cached or downloaded byte count. A disabled byte-length check permits
+`bytes` to be absent and never rejects a cached or downloaded model by comparing
+it with an expected size. The store still counts and records the observed byte
+length for storage and progress metadata on every install and cache reuse.
+
+An enabled SHA-256 check requires descriptor `sha256` and hashes the actual
+stored or cached file. A disabled SHA-256 check permits `sha256` to be absent
+and does not hash or reread a multi-gigabyte model solely to produce a digest.
+Only enabled checks fail closed. Regardless of optional integrity checks, a
+load succeeds only after Wllama reports that the model is loaded.
+
+The DBOPFS adapter commits an `arcane.ai.browser-wasm.model.v3` completion
+manifest with the observed byte length. Status reports the effective
+`security.secure`, both effective check booleans, and per-check integrity
+outcomes. Overall integrity is `verified` when every enabled check succeeded,
+`pending` while an enabled check is running, and `unchecked` when neither check
+is enabled. Before completion an enabled check reports `pending`; after a
+successful load each check independently reports `verified` or `unchecked`.
+`load({offline:true})` never
+performs a model request; it uses a compatible cached entry or rejects with
+`ARCANE_AI_MODEL_OFFLINE_MISS`.
+
+```javascript
+const {security, integrity} = ai.status().llm;
+console.log(security.secure, security.checks.byteLength, security.checks.sha256);
+console.log(integrity.state); // 'unchecked' or 'verified'
+console.log(integrity.byteLength.observed); // actual cached/downloaded bytes
+```
+
+For compatibility, older descriptors can supply `immutableUrl` as the URL alias
+and `name` as a cache-filename hint. If both `url` and `immutableUrl` are
+present, they must match. Legacy `licenseSpdx` and `sourceRevision` properties
+are not canonical descriptor fields or runtime admission checks; applications
+remain responsible for model selection, provenance, and license compliance.
+Version-2 cache manifests can be migrated to version 3 when their model identity
+matches, without inventing an integrity result.
+
+`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`, `ARCANE_AI_SECURITY_RELOAD_REQUIRED` |
+| 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/2`; 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', security }={})
+```
+
+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`.
+`security` is the app-level security configuration inherited by provider loads.
+The SDK default is `secure:false`; `ai.load({security})` can override inherited
+fields for that operation.
+
+### 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 a caller-owned canonical `{id, url, bytes?, sha256?}` descriptor 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 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 optional metadata syntax are normalized.
+Expected length and SHA-256 are enforced only when their effective checks are
+enabled for load.
+
+### 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={}, security, 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.
+Provider `security` supplies the provider/model-binding scope. Direct
+`provider.load({security})` and facade `ai.load({security})` supply the
+operation scope.
+
+### Availability and normalization
+
+**Browser with WebAssembly and DBOPFS model bytes.** Inference is local after a
+successful Wllama load. WebGPU is optional and defaults to zero GPU layers
+unless the caller selects otherwise. Status discloses effective checks and
+whether enabled integrity checks are pending, unchecked, or verified.
+
+### 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 model-file, observed-byte, optional-check, 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, observed byte count, integrity detail, and cache state
+`cached` or `installed`. `openVerified()` remains a compatibility helper that
+requires both byte-length and SHA-256 verification.
+
+### Availability and normalization
+
+**Browser with a ready DBOPFS instance and OPFS.** A cache receipt reports only
+the checks actually performed. Unchecked cache metadata is not integrity
+evidence, and no cache receipt is a transferable capability token or proof of
+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 HTTPS model URL unless `offline:true` | The facade normalizes lifecycle, status, security precedence, effective-check disclosure, streaming, cancellation, and structural tool-call visibility. The canonical model descriptor is `{id, url, bytes?, sha256?}`; license is application provenance policy, not a runtime admission check. |
 | 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,36 @@ 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. App, provider/model-binding, and load-operation options use
+`{security:{secure?:boolean, checks?:{byteLength?:boolean, sha256?:boolean}}}`.
+Fields resolve independently from load operation to provider/model binding to
+app configuration to the SDK default `secure:false`; omitted fields inherit.
+The resolved `secure` value supplies the default for both checks, and an
+explicit per-check boolean overrides that default.
+
+An enabled check requires and verifies its matching descriptor field. A
+disabled byte-length check permits `bytes` to be absent and never compares an
+expected size, although the actual downloaded or cached byte count is always
+recorded for storage and progress metadata. A disabled SHA-256 check permits
+`sha256` to be absent and performs no hash or digest-only reread. Status reports
+the effective checks and distinguishes unchecked integrity from successful
+verification of the enabled checks. Only enabled checks fail closed, while
+successful Wllama model loading remains mandatory. `load({offline:true})` permits only a compatible
+cache entry and otherwise 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 exported namespace, canonical `{id, url, bytes?, sha256?}` descriptor, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest status, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, 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, configures `secure:true`, 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,26 @@ 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.
+Focused contracts cover the plain security shape and fieldwise precedence from
+load operation to provider/model binding to app configuration to SDK default
+`secure:false`. They prove that omitted values inherit, the resolved `secure`
+value defaults both checks, and explicit per-check booleans override that
+default.
+
+The default path proves actual bytes are counted and persisted and Wllama
+confirms a loaded model without requiring descriptor `bytes` or `sha256`.
+Disabled byte-length checks never compare an expected count; disabled SHA-256
+checks never instantiate hashing or reread a multi-gigabyte file solely for a
+digest. Enabled-check cases prove the matching descriptor field is required and
+fail closed on mismatch. Status cases distinguish effective checks, per-check
+outcomes, and unchecked versus enabled-check-verified integrity. The authoritative
+browser contract separately proves the enabled secure path hashes stored and
+cached bytes, `AbortSignal` settles as `ARCANE_AI_REQUEST_ABORTED`, and tool-call
+arguments are surfaced without invoking application handlers. Model license
+metadata is never treated as runtime admission evidence.
+
 ## Host and normalization cases
 
 Cross-host APIs should cover at least these cases at their owning layer:

package/docs/reference/cli.md

@@ -183,8 +183,8 @@ 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.0`, the authenticated physical-v1 runtime produces
-85 entries and intentionally has no package-root mapping.
+module loading. In SDK `0.1.2`, the authenticated physical-v1 runtime produces
+86 entries and intentionally has no package-root mapping.
 
 ### Result and safety
 
@@ -201,7 +201,7 @@ Success returns the normal selected-workspace wrapper:
         artifactRelativePath,
         entryPath,
         imports,
-        entryCount:85,
+        entryCount:86,
         excludedModules:['modules/CaseEvidenceIndexer.js'],
         files:[
             {role:'artifact',path,bytes,sha256},
@@ -555,7 +555,7 @@ Success returns:
 {
     packageName:'arcane-os',
     currentVersion:'0.1.0',
-    registryVersion:'0.1.1',
+    registryVersion:'0.1.2',
     tag:'latest',
     status:'update-available', // or 'current' or 'ahead'
     updateAvailable:true,

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.1.0",
+  "sdkVersion": "0.2.0",
   "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/2 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', security }={})",
+      "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, fieldwise app/provider/load security inheritance from SDK secure:false, 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 canonical caller-supplied {id, url, bytes?, sha256?} descriptor and creates its cancellable no-credentials HTTPS download source.",
+      "availability": "Browser with Fetch and a readable response body; each direct open call performs its configured HTTPS fetch",
+      "protocol": "Caller-supplied immutable HTTPS model URL with optional expected byte length and SHA-256",
+      "normalization": "Canonical frozen descriptor and download handle; expected fields are required and enforced only for their effective enabled checks, and model license is not runtime admission"
+    },
+    {
+      "id": "browser-wasm:createBrowserWasmLlmProvider",
+      "name": "createBrowserWasmLlmProvider",
+      "displayName": "createBrowserWasmLlmProvider()",
+      "kind": "function",
+      "signature": "createBrowserWasmLlmProvider({ source, store, loadDefaults={}, security, 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 effective-check disclosure, honest integrity status, serialized inference, streaming, abort, unload, and probe operations.",
+      "availability": "Browser; WebAssembly required, WebGPU optional, enabled checks fail closed, and successful Wllama loading is always required",
+      "protocol": "arcane-ai-adapter/1 with OpenAI-like chat completion and streaming envelopes",
+      "normalization": "Frozen lifecycle/status/security/integrity records and structured tool-call data; security fields inherit by scope and 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 a model cache that records observed bytes, commits metadata last, and hashes only when SHA-256 checking is enabled.",
+      "availability": "Browser with a ready DBOPFS instance and OPFS support",
+      "protocol": "arcane.ai.browser-wasm.model.v3 completion manifests over existing DBOPFS method semantics",
+      "normalization": "Returns cached or installed receipts with observed byte count and per-check outcomes; disabled expected-length and SHA-256 checks do not compare or hash, while enabled checks fail closed"
     }
   ]
 }

package/docs/reference/protocols.md

@@ -104,8 +104,8 @@ import ollama from 'arcane/Ollama';
 ```
 
 The authenticated physical-v1 tree lives entirely beneath `arcane/`. It
-contains 155 pinned Arcane runtime files plus eight SDK browser-runtime files:
-163 files in all. Runtime `strong-type` 1.1 stays under
+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
@@ -114,13 +114,14 @@ 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.0`, the generated map has exactly 85 entries: 73 named
-`arcane/*` modules, nine `arcane/entities/*` modules, and these three focused or
+In SDK `0.1.2`, 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` |
 
@@ -167,14 +168,14 @@ heartbeat is event telemetry only and never regenerates browser state.
 
 `arcane.lock.json.sdkBrowserRuntime` persists the trusted manifest path,
 `manifestSha256`, `contentSha256`, `builder`, `sdkVersion`, and `source` record.
-For SDK `0.1.0` those identities are:
+For SDK `0.1.2` those identities are:
 
 ```text
 manifest: node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json
-manifestSha256: 43baaec850291c28795f6c194001deb5febab88ccab1b033bce6597dd6f6f08f
-contentSha256: 0caa302bc07d4a45f5290504ec62ddce98fdf5e3412f916c10aae3d51b1e5f7c
+manifestSha256: 88395493b411fd5461fbb2bb065ae2b745f6d1672f796583fd248ec97f71f4f7
+contentSha256: 5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00
 builder: arcane-sdk-browser-runtime-v1
-sdkVersion: 0.1.0
+sdkVersion: 0.1.2
 source.protocol: arcane-sdk-browser-runtime/1
 source.browserEntry: arcane-os/event-manager
 ```