arcane-os 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "builder": "arcane-sdk-browser-runtime-v1",
4
- "sdkVersion": "0.1.1",
4
+ "sdkVersion": "0.1.2",
5
5
  "source": {
6
6
  "authority": "arcane-os-sdk",
7
7
  "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
@@ -27,6 +27,7 @@ high-level page links to the relevant deep section instead of repeating it.
27
27
  | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
28
28
  | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
29
29
  | Use provider-neutral AI | [Arcane AI contracts](core/arcane-ai-contracts.md) |
30
+ | Run a caller-authenticated local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
30
31
  | Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
31
32
  | Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
32
33
  | Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
@@ -37,7 +38,7 @@ This repository contains two related, explicitly versioned surfaces:
37
38
 
38
39
  | Surface | Source identity | Meaning |
39
40
  | --- | --- | --- |
40
- | SDK and CLI | `arcane-os` `0.1.0` | The Node.js toolchain and package exports in this checkout. |
41
+ | 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. |
41
42
  | Browser runtime | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, bundle `0.8.12`, protocol `arcane/1` | The exact 155-file runtime snapshot shipped under `runtime/`. |
42
43
  | 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. |
43
44
 
@@ -73,11 +74,13 @@ Public reference entries follow the established Arcane documentation model:
73
74
 
74
75
  ## Public runtime inventory
75
76
 
76
- The Node package exposes 158 semantic JavaScript records across 11 JavaScript
77
+ The package exposes 163 semantic JavaScript records across 12 JavaScript
77
78
  entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
78
- metadata. The [machine-readable package inventory](inventory/package-api.json)
79
- and [SDK member reference](sdk-api.md) are checked bidirectionally against every
80
- declared JavaScript export.
79
+ metadata. Ten entrypoints are Node.js control-plane surfaces,
80
+ `arcane-os/event-manager` runs in Node and browsers, and
81
+ `arcane-os/ai/browser-wasm` is browser-only. The [machine-readable package
82
+ inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
83
+ are checked bidirectionally against every declared JavaScript export.
81
84
 
82
85
  The seven update-check records are explicit on-demand checks; they do not poll,
83
86
  download, install, or self-update.
@@ -0,0 +1,335 @@
1
+ # Browser-WASM local AI
2
+
3
+ Use this browser-only entrypoint when an application deliberately owns a local
4
+ GGUF model authority and wants provider-neutral LLM lifecycle, chat, streaming,
5
+ cancellation, and structural tool-call results without an Arcane Core host.
6
+ For ordinary hosted applications, start with the [Arcane AI
7
+ contracts](../core/arcane-ai-contracts.md) and `globalThis.Arcane.ai`. This
8
+ page is the focused local-browser path beneath the normalized AI decision
9
+ guide.
10
+
11
+ The wiring example assumes a scaffolded or materialized Arcane application
12
+ with SDK `0.1.1`'s authenticated runtime tree and 86-entry browser import map.
13
+ `arcane/DBOPFS` is a managed browser-map specifier, not an npm package export.
14
+ See [browser runtime delivery](../protocols.md#browser-runtime-delivery) before
15
+ using the example in a custom host or bundler.
16
+
17
+ ```javascript
18
+ import DBOPFS from 'arcane/DBOPFS';
19
+ import {
20
+ createArcaneAI,
21
+ createBrowserModelSource,
22
+ createBrowserWasmLlmProvider,
23
+ createDbopfsModelStore
24
+ } from 'arcane-os/ai/browser-wasm';
25
+
26
+ const MODEL = Object.freeze({
27
+ id:'my-reviewed-model',
28
+ name:'model-q4.gguf',
29
+ immutableUrl:'https://models.example/revisions/4f7c/model-q4.gguf',
30
+ bytes:123456789,
31
+ sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
32
+ licenseSpdx:'Apache-2.0',
33
+ sourceRevision:'4f7c'
34
+ });
35
+
36
+ const dbopfs = globalThis.dbopfs || new DBOPFS({applicationId:'my-app'});
37
+ await dbopfs.readyPromise;
38
+ const source = createBrowserModelSource(MODEL);
39
+ const store = createDbopfsModelStore({dbopfs});
40
+ const provider = createBrowserWasmLlmProvider({source, store});
41
+ const ai = createArcaneAI({provider, loadPolicy:'manual'});
42
+
43
+ // Put this behind an explicit user action: it can download MODEL.bytes bytes.
44
+ async function loadReviewedModel() {
45
+ return ai.load({threads:1, contextTokens:4096, gpuLayers:0});
46
+ }
47
+ ```
48
+
49
+ The browser-WASM runtime closure packages the authenticated
50
+ `@wllama/wllama` `3.6.0` ESM and WebAssembly runtime plus the Wllama and
51
+ llama.cpp MIT license texts. It
52
+ packages no model weights, model catalog, CDN fallback, native provider, speech
53
+ synthesis, or transcription. Callers supply the exact model authority. `bytes`
54
+ is the expected positive byte length, not inline model data.
55
+
56
+ ## Lifecycle at a glance
57
+
58
+ `createArcaneAI()` owns one LLM controller. Its default `loadPolicy` is
59
+ `on-demand`; the first request may download and initialize the model. Use
60
+ `manual` when a user action, resource review, or progress UI must precede load.
61
+
62
+ | Operation | Result |
63
+ | --- | --- |
64
+ | `ai.status()` | Frozen `{llm: status}` wrapper. |
65
+ | `ai.load(options)` | Flat LLM status after load. |
66
+ | `ai.llm.chat(request)` / `ai.fetchRequest(request)` | Validated OpenAI-like completion. |
67
+ | `ai.llm.stream(request)` | Frozen async-iterator handle with `result` and `cancel(reason)`. |
68
+ | `ai.streamRequest(request)` | Consumes the stream and returns text or `{toolName: argumentJsonString}`. |
69
+ | `ai.unload()` | Cancels active work, releases the Wllama session, and returns flat unloaded status; verified DBOPFS cache remains. |
70
+ | `ai.dispose()` | Permanently disposes the controller; explicit `store.remove(source)` is required to delete cached model bytes. |
71
+
72
+ The controller emits `statechange` and `progress` through
73
+ `addEventListener()`, `removeEventListener()`, or `on()`. Event `detail` is the
74
+ current frozen status. Provider states are `unloaded`, `loading`, `ready`,
75
+ `unloading`, and `error`.
76
+
77
+ ## Model authority and cache admission
78
+
79
+ `createBrowserModelSource()` requires `id`, `name`, `immutableUrl`, `bytes`,
80
+ `sha256`, `licenseSpdx`, and `sourceRevision`. The URL must be absolute HTTPS
81
+ without credentials or a fragment. Revision-floating `main`, `master`, and
82
+ `latest` path segments are rejected. `name` is one filename. `bytes` is a
83
+ positive safe integer and `sha256` is exactly 64 hexadecimal characters.
84
+
85
+ `licenseSpdx` and `sourceRevision` are required provenance labels supplied by
86
+ the caller; the SDK does not independently prove the license or derive the
87
+ revision from the URL. Redirects are followed and the final URL must remain
88
+ HTTPS. Byte length and SHA-256 remain the actual admission authority.
89
+
90
+ The DBOPFS adapter stores model bytes and then commits an
91
+ `arcane.ai.browser-wasm.model.v2` completion manifest. It reopens and fully
92
+ rehashes the bytes before returning an installed receipt and again before every
93
+ verified cache reuse. Missing, malformed, stale, wrong-length, or wrong-digest
94
+ entries are removed. `load({offline:true})` never performs a model request; it
95
+ uses a fully rehashed cache or rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`.
96
+
97
+ `localOnly:true` describes inference after load. It does not mean a cache miss
98
+ cannot download. Source downloads use CORS, omit credentials and referrer,
99
+ disable HTTP caching, and honor `AbortSignal`.
100
+
101
+ ## Streaming, cancellation, and tools
102
+
103
+ ```javascript
104
+ const abort = new AbortController();
105
+ const stream = ai.llm.stream({
106
+ localOnly:true,
107
+ signal:abort.signal,
108
+ messages:[{role:'user', content:'Summarize this text.'}],
109
+ maxTokens:128
110
+ });
111
+
112
+ const cancelButton = document.querySelector('[data-cancel-local-ai]');
113
+ const cancel = () => abort.abort('user cancelled');
114
+ cancelButton.addEventListener('click', cancel, {once:true});
115
+ try {
116
+ for await (const chunk of stream) renderChunk(chunk);
117
+ const completion = await stream.result;
118
+ renderCompletion(completion);
119
+ } catch (error) {
120
+ if (error?.code !== 'ARCANE_AI_REQUEST_ABORTED') throw error;
121
+ renderCancelled();
122
+ } finally {
123
+ cancelButton.removeEventListener('click', cancel);
124
+ }
125
+ ```
126
+
127
+ An active cancellation rejects as `ARCANE_AI_REQUEST_ABORTED`. Requests are
128
+ serialized; provider status exposes `busy` and `queued`. Supported request
129
+ generation fields include temperature, top-K, top-P, min-P, repeat penalty,
130
+ maximum tokens, seed, and stop sequences. Load settings separately include
131
+ `contextTokens`, `batchTokens`, `microBatchTokens`, `threads`, and GPU-layer
132
+ count. WebGPU is optional; cross-origin isolation and hardware fields are
133
+ observations, not readiness promises.
134
+
135
+ Tool definitions, tool choice, parallel-tool-call preference, and JSON or JSON
136
+ Schema structured-output requests are passed to Wllama. Returned tool calls are
137
+ validated and surfaced as structural data. Argument payloads remain JSON
138
+ strings. The SDK never invokes a handler or executes a tool; application code
139
+ must review policy, validate arguments, choose whether to execute, and submit a
140
+ later tool result.
141
+
142
+ ## Errors and unavailable states
143
+
144
+ Invalid configuration can throw `TypeError` or `RangeError`. Operational
145
+ failures expose a stable `.code`; the internal error class is not exported.
146
+ Handle the narrow code needed by the current operation and treat other failures
147
+ as unavailable.
148
+
149
+ | Area | Stable codes |
150
+ | --- | --- |
151
+ | 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` |
152
+ | 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` |
153
+ | 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` |
154
+ | Requests | `ARCANE_AI_REQUEST_ABORTED`, `ARCANE_AI_REQUEST_FAILED`, `ARCANE_AI_INVALID_PROVIDER_RESULT`, `ARCANE_AI_LOCAL_ONLY_UNAVAILABLE`, `ARCANE_AI_ADAPTER_PROTOCOL_MISMATCH` |
155
+ | Diagnostics | `ARCANE_AI_PROBE_FAILED` |
156
+
157
+ `capabilities()` reports browser observations such as WebAssembly, OPFS,
158
+ WebGPU, secure context, cross-origin isolation, and hardware concurrency.
159
+ Feature-detect them. The authoritative Chrome behavior passes without
160
+ cross-origin isolation, so that flag is not a hard gate. `probe()` exercises
161
+ packaged Wllama backend operations only while unloaded; it neither admits nor
162
+ downloads a model.
163
+
164
+ ## BROWSER_WASM_RUNTIME_AUTHORITY
165
+
166
+ ### Overview
167
+
168
+ Deep-frozen identity for the shipped browser runtime. Its protocol is
169
+ `arcane-ai-browser-wasm/1`; the provider adapter uses
170
+ `arcane-ai-adapter/1`. It records Wllama `3.6.0`, the embedded llama.cpp
171
+ revision, authenticated module/WASM byte lengths and SHA-256 values, licenses,
172
+ and the disabled compatibility-runtime and remote-model-helper policy.
173
+
174
+ ### Value and import
175
+
176
+ ```text
177
+ const BROWSER_WASM_RUNTIME_AUTHORITY
178
+ ```
179
+
180
+ ### Availability and normalization
181
+
182
+ **Browser metadata; safely inspectable without loading a model.** The value is
183
+ an immutable receipt, not a provider instance, model catalog, or capability
184
+ grant.
185
+
186
+ ### Example
187
+
188
+ ```javascript
189
+ import {BROWSER_WASM_RUNTIME_AUTHORITY} from 'arcane-os/ai/browser-wasm';
190
+
191
+ console.log(BROWSER_WASM_RUNTIME_AUTHORITY.protocol);
192
+ console.log(BROWSER_WASM_RUNTIME_AUTHORITY.package.version); // 3.6.0
193
+ ```
194
+
195
+ ## createArcaneAI()
196
+
197
+ ### Overview
198
+
199
+ Creates the application-facing facade around a provider or an existing LLM
200
+ controller. Use this as the primary browser-local API; construct the source,
201
+ store, and Wllama provider beneath it.
202
+
203
+ ### Signature and result
204
+
205
+ ```text
206
+ createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})
207
+ ```
208
+
209
+ At least one `llm` or `provider` is required; when both are supplied, `llm`
210
+ takes precedence. `loadPolicy` is `on-demand` or `manual`. The frozen result
211
+ contains `llm`, `runtime`, `status`, `load`,
212
+ `unload`, `probe`, `fetchRequest`, `streamRequest`, and `dispose`.
213
+
214
+ ### Availability and normalization
215
+
216
+ **Browser.** It normalizes provider lifecycle and request observation without
217
+ selecting a model, changing browser permissions, contacting Arcane Core, or
218
+ creating a fallback provider.
219
+
220
+ ### Example
221
+
222
+ ```javascript
223
+ const ai = createArcaneAI({provider, loadPolicy:'manual'});
224
+ const off = ai.llm.on('statechange', event => renderStatus(event.detail));
225
+ await ai.load({offline:true});
226
+ off();
227
+ ```
228
+
229
+ ## createBrowserModelSource()
230
+
231
+ ### Overview
232
+
233
+ Validates caller-owned model provenance and creates the one cancellable HTTPS
234
+ download source accepted by this provider.
235
+
236
+ ### Signature and result
237
+
238
+ ```text
239
+ createBrowserModelSource(descriptor, { fetchImpl=null }={})
240
+ ```
241
+
242
+ The frozen source includes `kind`, the seven canonical descriptor fields,
243
+ `descriptor`, and `open({signal})`. `open()` returns a readable response body,
244
+ requested/final URLs, and `cancel()`; it does not admit bytes to the cache.
245
+
246
+ ### Availability and normalization
247
+
248
+ **Browser Fetch with CORS.** URL and metadata syntax are normalized; exact
249
+ length and SHA-256 are enforced when the store installs the stream.
250
+
251
+ ### Example
252
+
253
+ ```javascript
254
+ const source = createBrowserModelSource(MODEL);
255
+ console.log(source.id, source.bytes, source.sha256);
256
+ ```
257
+
258
+ ## createBrowserWasmLlmProvider()
259
+
260
+ ### Overview
261
+
262
+ Creates the local-only Wllama provider from genuine source and store objects
263
+ created by this module. Structural lookalikes are rejected.
264
+
265
+ ### Signature and result
266
+
267
+ ```text
268
+ createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})
269
+ ```
270
+
271
+ The frozen result exposes protocol and provider identity, model metadata,
272
+ `capabilities`, `status`, `load`, `unload`, `chat`, `stream`, `streamChat`,
273
+ `use`, `probe`, and `dispose`. Direct provider `load()` returns `{model,status}`;
274
+ the facade `ai.load()` returns the flat controller status.
275
+
276
+ ### Availability and normalization
277
+
278
+ **Browser with WebAssembly and verified DBOPFS model bytes.** Inference is local
279
+ after load. WebGPU is optional and defaults to zero GPU layers unless the caller
280
+ selects otherwise.
281
+
282
+ ### Example
283
+
284
+ ```javascript
285
+ const provider = createBrowserWasmLlmProvider({
286
+ source,
287
+ store,
288
+ loadDefaults:{threads:1, contextTokens:4096, gpuLayers:0}
289
+ });
290
+ console.log(provider.status().state); // unloaded
291
+ ```
292
+
293
+ ## createDbopfsModelStore()
294
+
295
+ ### Overview
296
+
297
+ Adapts an existing DBOPFS instance without renaming or replacing its public
298
+ methods. The adapter owns verified model-file and completion-manifest behavior.
299
+
300
+ ### Signature and result
301
+
302
+ ```text
303
+ createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})
304
+ ```
305
+
306
+ The frozen result contains `kind`, `tableName`, the original `adapter`, and
307
+ `ready`, `openVerified`, `install`, `ensure`, and `remove`. `ensure()` returns a
308
+ file, completion manifest, and cache state `verified` or `installed`.
309
+
310
+ ### Availability and normalization
311
+
312
+ **Browser with a ready DBOPFS instance and OPFS.** Cache receipts are local
313
+ integrity evidence. They are not transferable capability tokens and do not
314
+ prove model license rights.
315
+
316
+ ### Example
317
+
318
+ ```javascript
319
+ const store = createDbopfsModelStore({dbopfs});
320
+ await store.ready();
321
+ const cached = await store.openVerified(source);
322
+ console.log(cached ? 'verified cache' : 'cache miss');
323
+ ```
324
+
325
+ ## Related reference
326
+
327
+ - [Canonical `createArcaneAI()` entry](../sdk-api.md#createarcaneai) and the
328
+ sibling [`BROWSER_WASM_RUNTIME_AUTHORITY`](../sdk-api.md#browserwasmruntimeauthority),
329
+ [`createBrowserModelSource()`](../sdk-api.md#createbrowsermodelsource),
330
+ [`createBrowserWasmLlmProvider()`](../sdk-api.md#createbrowserwasmllmprovider),
331
+ and [`createDbopfsModelStore()`](../sdk-api.md#createdbopfsmodelstore) entries
332
+ - [Browser-local normalization boundary](../availability-and-normalization.md#browser-local-provider-adapter)
333
+ - [Authenticated browser runtime delivery](../protocols.md#browser-runtime-delivery)
334
+ - [Browser-WASM behavior evidence](../behavioral-testing.md#behavioral-coverage-model)
335
+ - [DBOPFS runtime module](../runtime-modules.md#dbopfsjs)
@@ -29,6 +29,7 @@ version; WebKitGTK availability must not be generalized to macOS.
29
29
  | 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. |
30
30
  | 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. |
31
31
  | 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. |
32
+ | 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. |
32
33
  | 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. |
33
34
  | 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**. |
34
35
  | 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
77
78
  instrumentation adds browser diagnostics only; it does not replay browser
78
79
  state. See [EventManager and time-travel review](event-manager.md).
79
80
 
81
+ ### Browser-local provider adapter
82
+
83
+ [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) exposes the same
84
+ `arcane-ai-adapter/1` LLM lifecycle used by `createArcaneAI()`, while its
85
+ packaged Wllama engine and caller-supplied model run inside the browser. This
86
+ surface does not require an Arcane Core method grant because it does not call a
87
+ Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and
88
+ resource limits still apply.
89
+
90
+ `localOnly:true` describes inference after load; it does not promise that load
91
+ is offline. A normal cache miss downloads from the exact caller-supplied HTTPS
92
+ URL. `load({offline:true})` permits only an existing cache entry whose model
93
+ bytes are fully rehashed, otherwise it rejects with
94
+ `ARCANE_AI_MODEL_OFFLINE_MISS`. Tool calls are result data for application
95
+ review and dispatch; the SDK never executes them.
96
+
80
97
  ### Arcane bridge-normalized
81
98
 
82
99
  Core-backed calls return promises and reject with `Arcane.Error`. Transport
@@ -37,6 +37,7 @@ release acceptance.
37
37
  | 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. |
38
38
  | 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. |
39
39
  | 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. |
40
+ | 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`. |
40
41
  | 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. |
41
42
  | 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. |
42
43
  | 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
53
54
  normalized result returned to the application. A fake provider never counts as
54
55
  native host, artifact, installation, or model-service evidence.
55
56
 
57
+ The browser-WASM guide follows the same rule: it shows exact model authority
58
+ and wiring, but leaves the download/load call behind an explicit user action.
59
+ The authoritative browser contract separately proves that admitted bytes are
60
+ hashed before DBOPFS completion metadata is committed, cached bytes are rehashed
61
+ before offline reuse, `AbortSignal` settles as `ARCANE_AI_REQUEST_ABORTED`, and
62
+ tool-call arguments are surfaced without invoking application handlers.
63
+
56
64
  ## Host and normalization cases
57
65
 
58
66
  Cross-host APIs should cover at least these cases at their owning layer:
@@ -183,8 +183,8 @@ identical executable alias.
183
183
  The generated artifact is
184
184
  `apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
185
185
  the app entry as `<script type="importmap" data-arcane-import-map>` before
186
- module loading. In SDK `0.1.0`, the authenticated physical-v1 runtime produces
187
- 85 entries and intentionally has no package-root mapping.
186
+ module loading. In SDK `0.1.1`, the authenticated physical-v1 runtime produces
187
+ 86 entries and intentionally has no package-root mapping.
188
188
 
189
189
  ### Result and safety
190
190
 
@@ -201,7 +201,7 @@ Success returns the normal selected-workspace wrapper:
201
201
  artifactRelativePath,
202
202
  entryPath,
203
203
  imports,
204
- entryCount:85,
204
+ entryCount:86,
205
205
  excludedModules:['modules/CaseEvidenceIndexer.js'],
206
206
  files:[
207
207
  {role:'artifact',path,bytes,sha256},
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "sdkVersion": "0.1.0",
3
+ "sdkVersion": "0.1.2",
4
4
  "environment": {
5
- "runtime": "Node.js",
6
- "minimumVersion": "22.23.2",
5
+ "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
6
+ "minimumVersion": "22.23.2 for Node entrypoints",
7
7
  "moduleSystem": "ESM"
8
8
  },
9
- "memberCount": 158,
9
+ "memberCount": 163,
10
10
  "members": [
11
11
  {
12
12
  "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2627,6 +2627,86 @@
2627
2627
  "availability": "Node; on-demand CLI or maintainer check only",
2628
2628
  "protocol": "Approved credential-free HTTPS registry origin",
2629
2629
  "normalization": "Returns a normalized URL object only for an exact allowed root origin"
2630
+ },
2631
+ {
2632
+ "id": "browser-wasm:BROWSER_WASM_RUNTIME_AUTHORITY",
2633
+ "name": "BROWSER_WASM_RUNTIME_AUTHORITY",
2634
+ "displayName": "BROWSER_WASM_RUNTIME_AUTHORITY",
2635
+ "kind": "constant",
2636
+ "signature": "const BROWSER_WASM_RUNTIME_AUTHORITY",
2637
+ "entrypoints": [
2638
+ "arcane-os/ai/browser-wasm"
2639
+ ],
2640
+ "primaryImport": "arcane-os/ai/browser-wasm",
2641
+ "group": "Browser-WASM local AI",
2642
+ "summary": "Deep-frozen authority for the packaged Wllama and llama.cpp runtime, authenticated JS and WASM assets, licensing, and disabled compatibility-network policy.",
2643
+ "availability": "Browser metadata; import and inspection require neither DBOPFS nor a loaded model",
2644
+ "protocol": "arcane-ai-browser-wasm/1 over the provider-neutral arcane-ai-adapter/1 boundary",
2645
+ "normalization": "Exact immutable runtime and component identity; it contains no model weights or model catalog"
2646
+ },
2647
+ {
2648
+ "id": "browser-wasm:createArcaneAI",
2649
+ "name": "createArcaneAI",
2650
+ "displayName": "createArcaneAI()",
2651
+ "kind": "function",
2652
+ "signature": "createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})",
2653
+ "entrypoints": [
2654
+ "arcane-os/ai/browser-wasm"
2655
+ ],
2656
+ "primaryImport": "arcane-os/ai/browser-wasm",
2657
+ "group": "Browser-WASM local AI",
2658
+ "summary": "Creates the provider-neutral browser AI facade and LLM lifecycle controller around one compatible provider or controller.",
2659
+ "availability": "Browser; the selected provider observes its own WebAssembly, storage, and model readiness",
2660
+ "protocol": "arcane-ai-adapter/1",
2661
+ "normalization": "Normalizes lazy or manual load, lifecycle status, cancellation, streaming completion, and structural tool-call visibility without executing tools"
2662
+ },
2663
+ {
2664
+ "id": "browser-wasm:createBrowserModelSource",
2665
+ "name": "createBrowserModelSource",
2666
+ "displayName": "createBrowserModelSource()",
2667
+ "kind": "function",
2668
+ "signature": "createBrowserModelSource(descriptor, { fetchImpl=null }={})",
2669
+ "entrypoints": [
2670
+ "arcane-os/ai/browser-wasm"
2671
+ ],
2672
+ "primaryImport": "arcane-os/ai/browser-wasm",
2673
+ "group": "Browser-WASM local AI",
2674
+ "summary": "Validates a caller-supplied immutable HTTPS model authority and creates its cancellable no-credentials download source.",
2675
+ "availability": "Browser with Fetch and a readable response body; each direct open call performs its configured HTTPS fetch",
2676
+ "protocol": "Caller-supplied exact model URL, expected byte length, SHA-256, license identifier, and source revision",
2677
+ "normalization": "Canonical frozen descriptor and download handle; byte integrity is verified by the model store before admission"
2678
+ },
2679
+ {
2680
+ "id": "browser-wasm:createBrowserWasmLlmProvider",
2681
+ "name": "createBrowserWasmLlmProvider",
2682
+ "displayName": "createBrowserWasmLlmProvider()",
2683
+ "kind": "function",
2684
+ "signature": "createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})",
2685
+ "entrypoints": [
2686
+ "arcane-os/ai/browser-wasm"
2687
+ ],
2688
+ "primaryImport": "arcane-os/ai/browser-wasm",
2689
+ "group": "Browser-WASM local AI",
2690
+ "summary": "Creates the packaged Wllama browser provider with verified model admission, serialized inference, streaming, abort, unload, and probe operations.",
2691
+ "availability": "Browser; WebAssembly required, WebGPU optional, and model loading requires verified DBOPFS bytes",
2692
+ "protocol": "arcane-ai-adapter/1 with OpenAI-like chat completion and streaming envelopes",
2693
+ "normalization": "Frozen lifecycle/status/capability records and structured tool-call data; the SDK never invokes application tools"
2694
+ },
2695
+ {
2696
+ "id": "browser-wasm:createDbopfsModelStore",
2697
+ "name": "createDbopfsModelStore",
2698
+ "displayName": "createDbopfsModelStore()",
2699
+ "kind": "function",
2700
+ "signature": "createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})",
2701
+ "entrypoints": [
2702
+ "arcane-os/ai/browser-wasm"
2703
+ ],
2704
+ "primaryImport": "arcane-os/ai/browser-wasm",
2705
+ "group": "Browser-WASM local AI",
2706
+ "summary": "Adapts an existing DBOPFS instance into an authenticated model cache that commits metadata last and rehashes cached bytes before reuse.",
2707
+ "availability": "Browser with a ready DBOPFS instance and OPFS support",
2708
+ "protocol": "arcane.ai.browser-wasm.model.v2 completion manifests over existing DBOPFS method semantics",
2709
+ "normalization": "Returns verified or installed cache receipts, fail-closed offline misses, progress snapshots, and explicit removal without changing DBOPFS public names"
2630
2710
  }
2631
2711
  ]
2632
2712
  }
@@ -104,8 +104,8 @@ import ollama from 'arcane/Ollama';
104
104
  ```
105
105
 
106
106
  The authenticated physical-v1 tree lives entirely beneath `arcane/`. It
107
- contains 155 pinned Arcane runtime files plus eight SDK browser-runtime files:
108
- 163 files in all. Runtime `strong-type` 1.1 stays under
107
+ contains 155 pinned Arcane runtime files plus 18 SDK browser-runtime files:
108
+ 173 files in all. Runtime `strong-type` 1.1 stays under
109
109
  `arcane/dependencies/strong-type/`; the focused SDK event surface lives under
110
110
  `arcane/sdk/`, with `event-pubsub` 6.1 and its sibling `strong-type` 2.0 under
111
111
  `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
114
114
  physical bytes into `dist/<id>`; targets never resolve through the consumer
115
115
  workspace's root `node_modules/`.
116
116
 
117
- In SDK `0.1.0`, the generated map has exactly 85 entries: 73 named
118
- `arcane/*` modules, nine `arcane/entities/*` modules, and these three focused or
117
+ In SDK `0.1.1`, the generated map has exactly 86 entries: 73 named
118
+ `arcane/*` modules, nine `arcane/entities/*` modules, and these four focused or
119
119
  compatibility mappings:
120
120
 
121
121
  | Browser specifier | Physical target |
122
122
  | --- | --- |
123
123
  | `arcane-os/event-manager` | `./arcane/sdk/event-manager.mjs` |
124
+ | `arcane-os/ai/browser-wasm` | `./arcane/sdk/ai/browser-wasm.mjs` |
124
125
  | `event-pubsub` | `./arcane/sdk/dependencies/event-pubsub/index.js` |
125
126
  | `./node_modules/strong-type/index.js` | `./arcane/dependencies/strong-type/index.js` |
126
127
 
@@ -167,14 +168,14 @@ heartbeat is event telemetry only and never regenerates browser state.
167
168
 
168
169
  `arcane.lock.json.sdkBrowserRuntime` persists the trusted manifest path,
169
170
  `manifestSha256`, `contentSha256`, `builder`, `sdkVersion`, and `source` record.
170
- For SDK `0.1.0` those identities are:
171
+ For SDK `0.1.1` those identities are:
171
172
 
172
173
  ```text
173
174
  manifest: node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json
174
- manifestSha256: 43baaec850291c28795f6c194001deb5febab88ccab1b033bce6597dd6f6f08f
175
- contentSha256: 0caa302bc07d4a45f5290504ec62ddce98fdf5e3412f916c10aae3d51b1e5f7c
175
+ manifestSha256: 33396b3d35322b784929270e7ca0a2a8b31d899c6e77bcb227edc95b37d0ae7d
176
+ contentSha256: 5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00
176
177
  builder: arcane-sdk-browser-runtime-v1
177
- sdkVersion: 0.1.0
178
+ sdkVersion: 0.1.1
178
179
  source.protocol: arcane-sdk-browser-runtime/1
179
180
  source.browserEntry: arcane-os/event-manager
180
181
  ```
@@ -1,6 +1,10 @@
1
1
  # Arcane OS SDK JavaScript API
2
2
 
3
- The npm package exposes a Node.js ESM control plane. It is not a browser-importable renderer API. Application code uses named modules from the managed browser map, such as `arcane/ThemeBootstrap`, uses the focused `arcane-os/event-manager` browser entry when needed, and calls `globalThis.Arcane` for capability-gated host behavior.
3
+ The npm package exposes a Node.js ESM control plane, the Node-and-browser
4
+ `arcane-os/event-manager` entrypoint, and the browser-only
5
+ `arcane-os/ai/browser-wasm` entrypoint. Application code otherwise uses named
6
+ modules from the managed browser map, such as `arcane/ThemeBootstrap`, and
7
+ calls `globalThis.Arcane` for capability-gated host behavior.
4
8
 
5
9
  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.
6
10
 
@@ -10,7 +14,7 @@ This table is the Node `package.json#exports` map: it defines package
10
14
  entrypoints for SDK/tooling code. It is distinct from the generated browser
11
15
  import map that resolves application-facing `arcane/*` modules and the focused
12
16
  EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
13
- for that 85-entry physical-runtime contract.
17
+ for that 86-entry physical-runtime contract.
14
18
 
15
19
  | Specifier | Purpose |
16
20
  | --- | --- |
@@ -25,6 +29,7 @@ for that 85-entry physical-runtime contract.
25
29
  | `arcane-os/packager` | Low-level browser app packager. |
26
30
  | `arcane-os/release-bundle` | Deterministic external release bundles. |
27
31
  | `arcane-os/event-manager` | Central synchronous events, bounded time-travel history, playback, and optional DOM instrumentation. |
32
+ | `arcane-os/ai/browser-wasm` | Caller-authenticated browser-local Wllama inference, verified DBOPFS model caching, streaming, cancellation, and structural tool-call results. |
28
33
 
29
34
  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.
30
35
 
@@ -74,14 +79,19 @@ Protocol mechanics are intentionally kept in the [deep protocol guide](protocols
74
79
  | `authenticateSharedPayloadSnapshot()` | function | `arcane-os` | Packaging and release bundles | Node |
75
80
  | `buildApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
76
81
  | `buildTarget()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
82
+ | `BROWSER_WASM_RUNTIME_AUTHORITY` | constant | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser metadata; no model or DBOPFS required to inspect |
77
83
  | `bumpVersion()` | function | `arcane-os/packager` | Packaging and release bundles | Node |
78
84
  | `bundleApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
79
85
  | `checkApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
80
86
  | `CLI_EVENT_PROTOCOL` | constant | `arcane-os` | Identity and protocol constants | Node |
81
87
  | `CLI_NAME` | constant | `arcane-os` | Identity and protocol constants | Node |
82
88
  | `createApplication()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
89
+ | `createArcaneAI()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; compatible LLM provider or controller required |
83
90
  | `createAppReleaseBundle()` | function | `arcane-os` | Packaging and release bundles | Node |
91
+ | `createBrowserModelSource()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser Fetch with a readable response body |
92
+ | `createBrowserWasmLlmProvider()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; WebAssembly and verified DBOPFS model bytes |
84
93
  | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
94
+ | `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
85
95
  | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
86
96
  | `createNativeTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
87
97
  | `createReporter()` | function | `arcane-os` | Events, processes, and testing | Node |
@@ -2645,7 +2655,7 @@ The import-map operation also reports the stable operation-specific strings
2645
2655
  `ARCANE_IMPORT_MAP_COLLISION`; package assembly can additionally report
2646
2656
  `ARCANE_IMPORT_MAP_CLEANUP_FAILED`. They are normalized `ArcaneError.code`
2647
2657
  values, but are not properties added to this frozen general registry in SDK
2648
- `0.1.0`.
2658
+ `0.1.1`.
2649
2659
 
2650
2660
  ### Value and import
2651
2661
 
@@ -3464,7 +3474,7 @@ const toolchain = createToolchain({
3464
3474
 
3465
3475
  // Only this explicit call refreshes the managed map and HTML entry.
3466
3476
  const result = await toolchain.importMap();
3467
- console.log(result.importMap.entryCount); // 85 in SDK 0.1.0
3477
+ console.log(result.importMap.entryCount); // 86 in SDK 0.1.1
3468
3478
  ```
3469
3479
 
3470
3480
  ## describeTargets()
@@ -4925,6 +4935,200 @@ const stack = parseEventStack(serialized);
4925
4935
  console.log(stack.sessionId, stack.events.length);
4926
4936
  ```
4927
4937
 
4938
+ ## BROWSER_WASM_RUNTIME_AUTHORITY
4939
+
4940
+ ### Overview
4941
+
4942
+ Deep-frozen authority for the browser-only runtime behind
4943
+ `arcane-os/ai/browser-wasm`. It records protocol
4944
+ `arcane-ai-browser-wasm/1`, `@wllama/wllama` `3.6.0`, the embedded llama.cpp
4945
+ revision, the exact packaged JavaScript and WebAssembly assets, retained MIT
4946
+ licenses, and the disabled compatibility-runtime/remote-model-helper policy.
4947
+ It contains no model weights or model catalog.
4948
+
4949
+ ### Value and import
4950
+
4951
+ ```text
4952
+ const BROWSER_WASM_RUNTIME_AUTHORITY
4953
+ ```
4954
+
4955
+ The value is available from `arcane-os/ai/browser-wasm` only. Importing and
4956
+ inspecting it does not initialize Wllama, request storage, or download a model.
4957
+
4958
+ ### Availability and normalization
4959
+
4960
+ **Browser metadata.** This is an immutable component receipt, not a provider,
4961
+ model, browser-permission grant, or proof that WebAssembly/OPFS is available.
4962
+
4963
+ ### Example
4964
+
4965
+ ```javascript
4966
+ import {BROWSER_WASM_RUNTIME_AUTHORITY} from 'arcane-os/ai/browser-wasm';
4967
+
4968
+ console.log(BROWSER_WASM_RUNTIME_AUTHORITY.protocol);
4969
+ console.log(BROWSER_WASM_RUNTIME_AUTHORITY.package.version);
4970
+ ```
4971
+
4972
+ Complete lifecycle, model authority, cache, cancellation, and tool behavior:
4973
+ [Browser-WASM local AI](ai/browser-wasm.md).
4974
+
4975
+ ## createArcaneAI()
4976
+
4977
+ ### Overview
4978
+
4979
+ Creates the application-facing LLM facade around a compatible provider or
4980
+ controller. The default `on-demand` policy loads before first use; `manual`
4981
+ requires an explicit successful `load()` before requests. When both `llm` and
4982
+ `provider` are supplied, `llm` takes precedence.
4983
+
4984
+ ### Signature and result
4985
+
4986
+ ```text
4987
+ createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})
4988
+ ```
4989
+
4990
+ At least one `llm` or `provider` is required. The frozen facade contains
4991
+ `llm`, `runtime`, `status`, `load`, `unload`, `probe`, `fetchRequest`,
4992
+ `streamRequest`, and `dispose`. `status()` returns `{llm: status}`; lifecycle
4993
+ methods return the flat LLM status. `fetchRequest()` returns the completion.
4994
+ `streamRequest()` consumes streaming and returns text or a tool-name-to-JSON-
4995
+ argument-string record. Use `ai.llm.stream()` for the async iterator.
4996
+
4997
+ ### Availability and normalization
4998
+
4999
+ **Browser.** It normalizes lifecycle, state/progress events, lazy/manual use,
5000
+ cancellation, completions, and structural tool-call visibility. It neither
5001
+ selects a provider fallback nor executes an application tool.
5002
+
5003
+ ### Example
5004
+
5005
+ ```javascript
5006
+ const ai = createArcaneAI({provider, loadPolicy:'manual'});
5007
+ const stop = ai.llm.on('progress', event => renderProgress(event.detail));
5008
+ await ai.load({offline:true});
5009
+ stop();
5010
+ ```
5011
+
5012
+ ## createBrowserModelSource()
5013
+
5014
+ ### Overview
5015
+
5016
+ Validates a caller-owned model descriptor and creates the cancellable HTTPS
5017
+ source accepted by the browser-WASM store/provider. Required fields are `id`,
5018
+ `name`, `immutableUrl`, `bytes`, `sha256`, `licenseSpdx`, and
5019
+ `sourceRevision`. `bytes` is the expected positive safe-integer byte length,
5020
+ not inline data.
5021
+
5022
+ ### Signature and result
5023
+
5024
+ ```text
5025
+ createBrowserModelSource(descriptor, { fetchImpl=null }={})
5026
+ ```
5027
+
5028
+ The URL must be absolute HTTPS with no credentials or fragment and no
5029
+ revision-floating `main`, `master`, or `latest` path. The SHA-256 value is
5030
+ exactly 64 hexadecimal characters. The frozen source exposes its canonical
5031
+ descriptor and `open({signal})`, which returns `{body, requestedUrl, finalUrl,
5032
+ cancel}`. Every direct `open()` performs the configured fetch. The SDK records
5033
+ but does not independently prove the supplied license identifier or revision.
5034
+
5035
+ ### Availability and normalization
5036
+
5037
+ **Browser Fetch with CORS and a readable response body.** Downloads omit
5038
+ credentials/referrer, disable HTTP caching, follow redirects, require a final
5039
+ HTTPS URL, compare `Content-Length` when present, and honor `AbortSignal`.
5040
+ Actual length and digest admission belongs to the DBOPFS store.
5041
+
5042
+ ### Example
5043
+
5044
+ ```javascript
5045
+ const source = createBrowserModelSource({
5046
+ id:'reviewed-model',
5047
+ name:'model-q4.gguf',
5048
+ immutableUrl:'https://models.example/revisions/4f7c/model-q4.gguf',
5049
+ bytes:123456789,
5050
+ sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
5051
+ licenseSpdx:'Apache-2.0',
5052
+ sourceRevision:'4f7c'
5053
+ });
5054
+ ```
5055
+
5056
+ ## createBrowserWasmLlmProvider()
5057
+
5058
+ ### Overview
5059
+
5060
+ Creates the packaged Wllama provider from genuine source and store objects
5061
+ created by this module. It serializes requests and exposes provider states
5062
+ `unloaded`, `loading`, `ready`, `unloading`, and `error`.
5063
+
5064
+ ### Signature and result
5065
+
5066
+ ```text
5067
+ createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})
5068
+ ```
5069
+
5070
+ The frozen provider exposes `protocol`, `id`, `model`, `capabilities`,
5071
+ `status`, `load`, `unload`, `chat`, `stream`, `streamChat`, `use`, `probe`, and
5072
+ `dispose`. Load settings include offline mode, `AbortSignal`, progress,
5073
+ threads, context/batch/micro-batch tokens, and GPU layers. Chat supports
5074
+ OpenAI-like message/generation fields, tools, tool choice, parallel tool-call
5075
+ preference, and JSON/JSON-Schema structured output. `stream()` returns a frozen
5076
+ async iterator with `result` and `cancel(reason)`.
5077
+
5078
+ ### Availability and normalization
5079
+
5080
+ **Browser with WebAssembly and a verified DBOPFS model.** WebGPU and
5081
+ cross-origin isolation are capability observations, not promised gates.
5082
+ Returned tools are validated structural data; the SDK never calls a handler.
5083
+ Cancellation normalizes to `ARCANE_AI_REQUEST_ABORTED`.
5084
+
5085
+ ### Example
5086
+
5087
+ ```javascript
5088
+ const provider = createBrowserWasmLlmProvider({
5089
+ source,
5090
+ store,
5091
+ loadDefaults:{threads:1, contextTokens:4096, gpuLayers:0}
5092
+ });
5093
+ console.log(provider.status().state); // unloaded
5094
+ ```
5095
+
5096
+ ## createDbopfsModelStore()
5097
+
5098
+ ### Overview
5099
+
5100
+ Adapts an existing DBOPFS instance into an authenticated model cache without
5101
+ renaming its public methods. The adapter commits model bytes before the
5102
+ `arcane.ai.browser-wasm.model.v2` completion manifest and then reopens and
5103
+ rehashes the stored file.
5104
+
5105
+ ### Signature and result
5106
+
5107
+ ```text
5108
+ createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})
5109
+ ```
5110
+
5111
+ The frozen result contains `kind`, `tableName`, the original `adapter`, and
5112
+ `ready`, `openVerified`, `install`, `ensure`, and `remove`. `ensure()` returns
5113
+ `{file, manifest, cache:'verified'|'installed'}`. Every cache reuse rehashes the
5114
+ actual bytes. `offline:true` never downloads and rejects a miss with
5115
+ `ARCANE_AI_MODEL_OFFLINE_MISS`. Invalid cache records are removed fail closed.
5116
+
5117
+ ### Availability and normalization
5118
+
5119
+ **Browser with a ready DBOPFS instance and OPFS.** The cache is local integrity
5120
+ evidence, not a transferable capability or license proof. Unload/dispose keep
5121
+ the cache; `store.remove(source)` explicitly deletes it.
5122
+
5123
+ ### Example
5124
+
5125
+ ```javascript
5126
+ const store = createDbopfsModelStore({dbopfs});
5127
+ await store.ready();
5128
+ const cached = await store.openVerified(source);
5129
+ console.log(cached ? 'verified cache' : 'cache miss');
5130
+ ```
5131
+
4928
5132
  ## Data export subpaths
4929
5133
 
4930
5134
  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/`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arcane-os",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
5
5
  "type": "module",
6
6
  "main": "./src/index.mjs",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "builder": "arcane-sdk-runtime-v1",
4
- "sdkVersion": "0.1.1",
4
+ "sdkVersion": "0.1.2",
5
5
  "source": {
6
6
  "repository": "https://github.com/TheWizardNexus/ARCANE-OS.git",
7
7
  "commit": "567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e",
@@ -28,7 +28,7 @@
28
28
  "const": "arcane-os"
29
29
  },
30
30
  "version": {
31
- "const": "0.1.1"
31
+ "const": "0.1.2"
32
32
  }
33
33
  }
34
34
  },
@@ -69,7 +69,7 @@
69
69
  "const": "node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json"
70
70
  },
71
71
  "manifestSha256": {
72
- "const": "33396b3d35322b784929270e7ca0a2a8b31d899c6e77bcb227edc95b37d0ae7d"
72
+ "const": "88395493b411fd5461fbb2bb065ae2b745f6d1672f796583fd248ec97f71f4f7"
73
73
  },
74
74
  "contentSha256": {
75
75
  "const": "5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00"
@@ -78,7 +78,7 @@
78
78
  "const": "arcane-sdk-browser-runtime-v1"
79
79
  },
80
80
  "sdkVersion": {
81
- "const": "0.1.1"
81
+ "const": "0.1.2"
82
82
  },
83
83
  "source": {
84
84
  "type": "object",
@@ -31,6 +31,7 @@ const MIME_TYPES=new Map([
31
31
  ['.png','image/png'],
32
32
  ['.svg','image/svg+xml; charset=utf-8'],
33
33
  ['.txt','text/plain; charset=utf-8'],
34
+ ['.wasm','application/wasm'],
34
35
  ['.webp','image/webp'],
35
36
  ['.woff','font/woff'],
36
37
  ['.woff2','font/woff2']
@@ -51,7 +52,7 @@ const PRIVATE_SOURCE_SEGMENTS=new Set([
51
52
  // development CSP from being exposed as a general network service.
52
53
  const DEVELOPMENT_CSP=[
53
54
  "default-src 'self'",
54
- "script-src 'self' 'unsafe-inline'",
55
+ "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'",
55
56
  "style-src 'self' 'unsafe-inline'",
56
57
  "img-src 'self' data: blob: http: https:",
57
58
  "font-src 'self' data:",
package/src/doctor.mjs CHANGED
@@ -8,7 +8,7 @@ import {runProcess} from './process.mjs';
8
8
  import {ARCANE_PROTOCOL,SDK_VERSION} from './constants.mjs';
9
9
  import {ERROR_CODES,ArcaneError,throwIfAborted} from './errors.mjs';
10
10
 
11
- const MINIMUM_NODE=[22,14,0];
11
+ const MINIMUM_NODE=[22,23,2];
12
12
  const WINDOWS_SERVICE_NAME='ArcaneOllama';
13
13
  const WINDOWS_SERVICE_HOST='C:\\Program Files\\Ollama\\ArcaneOllamaService.exe';
14
14
  const WINDOWS_SERVICE_COMMAND=`"${WINDOWS_SERVICE_HOST}"`;
@@ -9,7 +9,7 @@ const MANIFEST_NAME='ARCANE_SDK_BROWSER_RELEASE.json';
9
9
  const BUILDER='arcane-sdk-browser-runtime-v1';
10
10
  const PROTOCOL='arcane-sdk-browser-runtime/1';
11
11
  export const SDK_BROWSER_RUNTIME_MANIFEST_SHA256=
12
- '33396b3d35322b784929270e7ca0a2a8b31d899c6e77bcb227edc95b37d0ae7d';
12
+ '88395493b411fd5461fbb2bb065ae2b745f6d1672f796583fd248ec97f71f4f7';
13
13
  export const SDK_BROWSER_RUNTIME_CONTENT_SHA256=
14
14
  '5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00';
15
15
  const REPOSITORY='https://github.com/TheWizardNexus/arcane-os-sdk.git';