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.
- package/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json +1 -1
- package/docs/reference/README.md +8 -5
- package/docs/reference/ai/browser-wasm.md +335 -0
- package/docs/reference/availability-and-normalization.md +17 -0
- package/docs/reference/behavioral-testing.md +8 -0
- package/docs/reference/cli.md +3 -3
- package/docs/reference/inventory/package-api.json +84 -4
- package/docs/reference/protocols.md +9 -8
- package/docs/reference/sdk-api.md +208 -4
- package/package.json +1 -1
- package/runtime/ARCANE_RUNTIME_RELEASE.json +1 -1
- package/schemas/arcane-lock.schema.json +3 -3
- package/src/dev-server.mjs +2 -1
- package/src/doctor.mjs +1 -1
- package/src/sdk-browser-runtime.mjs +1 -1
package/docs/reference/README.md
CHANGED
|
@@ -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.
|
|
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
|
|
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.
|
|
79
|
-
|
|
80
|
-
|
|
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:
|
package/docs/reference/cli.md
CHANGED
|
@@ -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.
|
|
187
|
-
|
|
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:
|
|
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.
|
|
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":
|
|
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
|
|
108
|
-
|
|
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.
|
|
118
|
-
`arcane/*` modules, nine `arcane/entities/*` modules, and these
|
|
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.
|
|
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:
|
|
175
|
-
contentSha256:
|
|
175
|
+
manifestSha256: 33396b3d35322b784929270e7ca0a2a8b31d899c6e77bcb227edc95b37d0ae7d
|
|
176
|
+
contentSha256: 5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00
|
|
176
177
|
builder: arcane-sdk-browser-runtime-v1
|
|
177
|
-
sdkVersion: 0.1.
|
|
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
|
|
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
|
|
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.
|
|
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); //
|
|
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
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"const": "arcane-os"
|
|
29
29
|
},
|
|
30
30
|
"version": {
|
|
31
|
-
"const": "0.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": "
|
|
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.
|
|
81
|
+
"const": "0.1.2"
|
|
82
82
|
},
|
|
83
83
|
"source": {
|
|
84
84
|
"type": "object",
|
package/src/dev-server.mjs
CHANGED
|
@@ -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,
|
|
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
|
-
'
|
|
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';
|