arcane-os 0.3.0 → 0.3.2

package/docs/reference/arcane-ollama.md

@@ -1,288 +0,0 @@
-# Arcane Ollama
-
-Arcane Ollama lets an admitted application use local Ollama without knowing the
-service port, service account, model directory, host process, or native
-transport. Application code imports one browser module and calls one API:
-
-```javascript
-import ollama from '/arcane/modules/Ollama.js';
-
-const reply = await ollama.chatText({
-    model: 'arcane:latest',
-    messages: [{role: 'user', content: 'Summarize this record.'}]
-});
-
-console.log(reply);
-```
-
-The module never connects directly to `localhost:11434`. It delegates to the
-capability-gated `globalThis.Arcane.ollama` bridge. Core binds application
-identity, checks the exact method and package-owned model policy, admits native
-resources, and calls the managed ArcaneOllama service.
-
-This npm package exposes the synchronized browser client only. It does not
-bundle, install, start, or grant an Arcane Core or ArcaneOllama service. Every
-native call therefore requires a separately installed, compatible Arcane host,
-an app-scoped admitted Core session, the required capabilities, and a service
-that is ready under native policy. Import success alone proves none of those
-conditions.
-
-## What developers can do
-
-| Capability | Preferred call | Result style |
-| --- | --- | --- |
-| Check whether the admitted service answers | `ollama.readiness()` | Arcane-normalized frozen readiness snapshot |
-| Generate text | `ollama.generateText(request)` | Arcane helper string |
-| Chat and return only assistant text | `ollama.chatText(request)` | Arcane helper string |
-| Use full generation/chat/tool/provider fields | `ollama.generate()` / `ollama.chat()` | Bounded Ollama provider-native envelope |
-| Create embeddings | `ollama.embed()` | Bounded Ollama provider-native envelope |
-| Read raw version/model/running/show inventory | `version()`, `models()`, `list()`, `running()`, `show()` | Provider-native diagnostic envelope |
-| Unload one model | `ollama.unload(model)` | Translates to generate with `prompt: ""` and `keep_alive: 0` |
-| Read managed selection/runtime/service settings | `selection()`, `settings()`, `serviceSettings()` | Arcane-managed snapshot; some service fields are platform-dependent |
-| Change managed selection/runtime/service settings | `select()`, `saveSettings()`, `saveServiceSettings()` | Arcane-managed result plus operation receipt |
-| Run admitted raw model mutations | `pull()`, `push()`, `create()`, `copy()`, `delete()` | Policy-bound provider-native result; several calls are intentionally denied to ordinary apps |
-| Create an Arcane-managed brain alias | `createBrain()` | Arcane-managed model/default result plus operation receipt |
-
-## Fast start
-
-### 1. Feature-detect the module
-
-```javascript
-import ollama from '/arcane/modules/Ollama.js';
-
-const readiness = await ollama.readiness();
-
-if (!readiness.ready) {
-    console.info('Local AI is unavailable:', readiness.errorCode);
-}
-```
-
-`readiness()` catches a failed `version()` call and returns a frozen object:
-
-```text
-{ ready: boolean, version: string|null, errorCode: string|null }
-```
-
-It is a connectivity convenience, not model admission or inference readiness.
-Use `Arcane.localAI.status()` when the application needs the package-filtered
-runnable model catalog.
-
-### 2. Read admitted models
-
-```javascript
-const access = await globalThis.Arcane.capabilities.list();
-
-if (!access.methods.includes('localAI.status')) {
-    throw new Error('This application is not admitted for local AI.');
-}
-
-const status = await globalThis.Arcane.localAI.status();
-console.table(status.models.ollama);
-```
-
-Populate product UI from this filtered catalog. `ollama.models()` is the raw
-diagnostic inventory for admitted Settings, Shell, or Terminal journeys; it is
-not the application's package-admitted model list.
-
-### 3. Stream a chat response
-
-```javascript
-let text = '';
-
-const final = await ollama.chat({
-    model: 'arcane:latest',
-    messages: [{role: 'user', content: 'Explain the evidence.'}]
-}, {
-    onChunk(chunk) {
-        text += chunk.message?.content ?? '';
-    },
-    signal: AbortSignal.timeout(60_000)
-});
-
-console.log(text, final.done);
-```
-
-Arcane correlates chunks to the originating request. The final promise resolves
-with Ollama's final bounded chunk/envelope.
-
-## Complete module API
-
-`/arcane/modules/Ollama.js` exports the `Ollama` class, a frozen `ollama`
-singleton, and that singleton as the default export. It also installs the
-non-writable `globalThis.arcaneOllama` convenience and emits
-`arcane-ollama-ready`. The pinned class defines exactly 24 public methods: the
-20 bridge delegates below and the four normalized helpers that follow.
-
-### Raw bridge methods
-
-| Module method | Delegation | Capability/use | Detailed Core guide |
-| --- | --- | --- | --- |
-| `version()` | `Arcane.ollama.version()` | Raw service version diagnostic. | [version](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaversion) |
-| `models()` | `Arcane.ollama.models()` | Raw installed-model diagnostic. | [models](core/reference/arcane-api/ai-and-ollama.md#arcaneollamamodels) |
-| `list()` | Calls `Arcane.ollama.models()` | Module alias for `models()`; it does not call the bridge's separate `list` alias. | [list](core/reference/arcane-api/ai-and-ollama.md#arcaneollamalist) |
-| `running()` | `Arcane.ollama.running()` | Raw resident-model diagnostic. | [running](core/reference/arcane-api/ai-and-ollama.md#arcaneollamarunning) |
-| `show(model, options)` | `Arcane.ollama.show(...)` | Raw bounded model metadata. | [show](core/reference/arcane-api/ai-and-ollama.md#arcaneollamashow) |
-| `generate(request, options)` | `Arcane.ollama.generate(...)` | Admitted generation; optional chunk callback/signal/timeout. | [generate](core/reference/arcane-api/ai-and-ollama.md#arcaneollamagenerate) |
-| `chat(request, options)` | `Arcane.ollama.chat(...)` | Admitted chat/tools; optional chunk callback/signal/timeout. | [chat](core/reference/arcane-api/ai-and-ollama.md#arcaneollamachat) |
-| `embed(request)` | `Arcane.ollama.embed(...)` | Admitted embeddings. | [embed](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaembed) |
-| `pull(model, options, streamOptions)` | `Arcane.ollama.pull(...)` | Managed/policy-bound pull; denied to ordinary raw app flow. | [pull](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapull) |
-| `push(model, options, streamOptions)` | `Arcane.ollama.push(...)` | Raw push is policy-restricted/denied where documented. | [push](core/reference/arcane-api/ai-and-ollama.md#arcaneollamapush) |
-| `create(request, options)` | `Arcane.ollama.create(...)` | Exact package-owned verified definition only. | [create](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreate) |
-| `copy(source, destination)` | `Arcane.ollama.copy(...)` | Intentionally denied to applications; managed selection owns aliases. | [copy](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacopy) |
-| `delete(model)` | `Arcane.ollama.delete(...)` | Destructive exact package-owned verified model deletion. | [delete](core/reference/arcane-api/ai-and-ollama.md#arcaneollamadelete) |
-| `selection()` | `Arcane.ollama.selection()` | Reads managed model preference/effective state. | [selection](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselection) |
-| `select(preference)` | `Arcane.ollama.select(...)` | Runs managed size-selection/download/alias workflow. | [select](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaselect) |
-| `settings()` | `Arcane.ollama.settings()` | Reads managed runtime/provider settings. | [settings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasettings) |
-| `saveSettings(settings)` | `Arcane.ollama.saveSettings(...)` | Saves runtime-owned default/load/context settings. | [saveSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasavesettings) |
-| `createBrain(definition)` | `Arcane.ollama.createBrain(...)` | Creates a managed `arcane-<slug>:latest` alias. | [createBrain](core/reference/arcane-api/ai-and-ollama.md#arcaneollamacreatebrain) |
-| `serviceSettings()` | `Arcane.ollama.serviceSettings()` | Reads host-level Ollama service configuration/support. | [serviceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamaservicesettings) |
-| `saveServiceSettings(settings)` | `Arcane.ollama.saveServiceSettings(...)` | Applies privileged machine-wide service settings/restart. | [saveServiceSettings](core/reference/arcane-api/ai-and-ollama.md#arcaneollamasaveservicesettings) |
-
-### Normalized helper methods
-
-## `ollama.readiness()`
-
-### Overview
-
-Calls `version()` and converts success/failure into a frozen readiness snapshot.
-It never throws for service unavailability.
-
-### Return value
-
-`{ready:true, version, errorCode:null}` on success, or
-`{ready:false, version:null, errorCode}` on failure. A string version and an
-object `{version}` are both accepted.
-
-### Example
-
-```javascript
-const {ready, version, errorCode} = await ollama.readiness();
-console.log(ready ? version : errorCode);
-```
-
-## `ollama.generateText()`
-
-### Overview
-
-Calls `generate()` and coerces the final envelope's `response` field to a
-string with `String(response?.response || '')`. Valid Ollama responses document
-`response` as a string. If an out-of-contract response supplies a truthy
-nonstring, the helper stringifies it; a missing, null, undefined, or other
-falsy nonstring value becomes an empty string.
-
-### Example
-
-```javascript
-const text = await ollama.generateText({
-    model: 'arcane:latest',
-    prompt: 'Write one sentence.'
-});
-```
-
-## `ollama.chatText()`
-
-### Overview
-
-Calls `chat()` and coerces the final envelope's `message.content` field to a
-string with `String(response?.message?.content || '')`. Valid Ollama responses
-document `message.content` as a string. If an out-of-contract response supplies
-a truthy nonstring, the helper stringifies it; a missing, null, undefined, or
-other falsy nonstring value becomes an empty string. Use `chat()` when tool
-calls, metrics, context, or optional provider fields matter.
-
-### Example
-
-```javascript
-const text = await ollama.chatText({
-    model: 'arcane:latest',
-    messages: [{role: 'user', content: 'Hello'}]
-});
-```
-
-## `ollama.unload()`
-
-### Overview
-
-Translates `unload(model)` to:
-
-```javascript
-ollama.generate({model, prompt: '', keep_alive: 0});
-```
-
-It returns the raw final generation envelope. It is a convenience request, not
-a proof that no other admitted client reloaded the model concurrently.
-
-### Example
-
-```javascript
-async function unloadAfterTheUserChooses(model) {
-    return ollama.unload(model);
-}
-```
-
-## Availability matrix
-
-| Host | Inference | Raw inventory | Managed model/settings mutation | Notes |
-| --- | --- | --- | --- | --- |
-| Microsoft NT desktop Core | Yes when `ai.inference` is admitted | Settings/Shell/Terminal with `ai.models.read` | Admitted Settings/Shell journeys with management capabilities and privilege where required | Full managed ArcaneOllama service path. |
-| Linux desktop Core | Yes when admitted | Admitted diagnostics | Managed workflows where implemented; administrator-owned service settings can return manual/unsupported guidance | Same application API, different host/service implementation. |
-| Android WebView | Narrow admitted chat/inference projection for configured user-managed loopback | No general desktop raw inventory | No desktop model/service management | `managedLocalAI` remains false; listener reachability is not management authority. |
-| Development HTTP bridge | Only when connected to an admitted Core-backed development host | Host/method dependent | Host/method dependent; never production authority | Development transport, not a standalone-browser upgrade. |
-| Standalone browser | No Arcane Ollama | No | No | `ARCANE_OLLAMA_UNAVAILABLE`. |
-| Cloud/OpenAI | Not through `Arcane.ollama` | No | No | Use an explicitly selected `AI.js` cloud profile; no automatic fallback. |
-
-## Capabilities and policy
-
-- `ai.inference` admits package-filtered local generation, chat, and embeddings.
-- `ai.models.read` admits raw model diagnostics only to authorized system apps.
-- `ai.models.manage` admits policy-bound managed model lifecycle operations.
-- `ai.settings.manage` admits Settings-owned runtime/service configuration.
-- `ai.models.unverified.inference` is an explicit inference-only exception for
-  already installed, hardware-admitted unverified models when the package says
-  `verified_only:false`; it does not admit model mutation.
-
-The method allowlist is necessary but not sufficient. Exact package-owned model
-definitions, reserved aliases, native resources, platform support, installed
-state, and exclusive mutation policy remain authoritative.
-
-## Raw versus normalized behavior
-
-The module intentionally has two levels:
-
-| Boundary | Normalized by Arcane | Intentionally preserved |
-| --- | --- | --- |
-| Missing bridge | Throws coded `ARCANE_OLLAMA_UNAVAILABLE`. | Nothing reaches a provider. |
-| Core call | Promise settlement, capability/policy errors, request limits, diagnostics, stream ids/chunks. | Bounded Ollama success fields and optional provider detail. |
-| `readiness()` | Frozen Boolean/version/error-code snapshot. | Provider error detail is reduced to `errorCode`. |
-| `generateText()` / `chatText()` | Uses `String(value || '')`: documented string values pass through, truthy nonstrings stringify, and falsy nonstrings become empty. | Tool calls, timings, context, and other fields are discarded. |
-| `unload()` | Stable translation to `keep_alive:0`. | Final generation envelope remains provider-native. |
-
-## Streaming, cancellation, and uncertain mutation state
-
-`generate`, `chat`, `pull`, `push`, and `create` accept stream controls through
-the bridge forms documented on their detailed pages. Core cooperatively cancels
-admitted inference methods where documented. For pull, push, create, selection,
-settings, or service mutation, abort/timeout/page teardown can stop renderer
-observation without proving host work rolled back.
-
-After an uncertain model mutation, refresh the relevant raw inventory,
-`selection()`, `settings()`, `serviceSettings()`, or `localAI.status()` before
-retrying. Do not stack a second mutation merely because the renderer timed out.
-
-## Behavioral testing
-
-The SDK behavior suite uses an explicit fake `Arcane.ollama` to prove:
-
-- every wrapper forwards the exact argument objects and provider-native result;
-- stream options and signals are not rewritten;
-- bridge absence throws `ARCANE_OLLAMA_UNAVAILABLE` before provider work;
-- `readiness()` returns frozen success/failure snapshots;
-- `generateText()` and `chatText()` use the pinned `String(value || '')`
-  behavior: truthy nonstrings stringify and falsy nonstrings become empty;
-- `unload()` sends exactly `{model, prompt: "", keep_alive: 0}`.
-
-Those tests prove the shipped renderer module. Live Core dispatch, cancellation,
-ArcaneOllama health, real model pulls, GPU admission, service restart, and
-rollback remain Arcane OS host/integration evidence.
-
-Deep implementation path: [Arcane Ollama protocol](protocols.md#arcane-ollama-protocol-path).

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

@@ -1,183 +0,0 @@
-# Availability and normalization
-
-Use this page to choose an API by capability. The compact labels tell you where
-it runs; the [protocol guide](protocols.md) contains the implementation detail.
-
-## Availability labels
-
-| Label | Meaning |
-| --- | --- |
-| **Node** | Runs in the SDK's supported Node.js process. It is not a renderer API. |
-| **Browser** | Uses standard browser APIs and can run without a native host when its own dependencies are available. |
-| **Native** | Requires an admitted `globalThis.Arcane` host method or a native target provider. |
-| **Cloud** | Calls a remote provider over HTTPS and needs provider configuration and network policy. |
-| **Cross-host** | Keeps one application contract usable across supported hosts. Execution may stay in-process, use a registered provider, or cross a documented Arcane WebView2, WebKitGTK, Android WebView, or development HTTP transport. |
-| **Provider-native** | Intentionally returns the underlying provider's bounded envelope instead of an Arcane-normalized entity. |
-
-“Available” never means “authorized.” App grants, method allowlists, host
-policy, package-owned model policy, platform support, and dependency readiness
-are independent checks.
-
-The current native host/target matrix covers Microsoft NT, Linux, and Android
-where listed. It exposes no macOS target or Core host contract in this SDK
-version; WebKitGTK availability must not be generalized to macOS.
-
-## Capability-first matrix
-
-| What the developer wants to do | Preferred surface | Availability | Normalization |
-| --- | --- | --- | --- |
-| Scaffold, inspect, test, package, bundle, build, verify, or run an app | `arcane` CLI or `arcane-os` package functions | **Node**; native targets invoke one explicit provider | CLI events and SDK errors/results are normalized by versioned SDK contracts. Native artifact receipts remain target-specific inside a common receipt lifecycle. |
-| Publish application events or review a bounded event history | `arcane-os/event-manager` | **Node** and **Browser**; optional DOM capture needs a browser DOM or compatible host | Live listeners receive original arguments. Recorded payloads and metadata become bounded, redacted, deeply frozen `arcane-event-stack/1` snapshots. The stack format is local diagnostic data, not a host transport. |
-| Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
-| Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, closed route/configuration records, and validated authority/status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` fails closed and creates no fallback. |
-| Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, OPFS/DBOPFS, WebGPU, requested full offload, and admitted adapter/buffer/queue/fence evidence are required; no CPU fallback | The facade normalizes multi-model lifecycle, status, security precedence, effective-check disclosure, streaming, cancellation, and structural tool-call visibility. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
-| Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | STT/TTS use independent provider/2 lifecycle and status. Immutable artifact authority, manifest-last cache, strict offline admission, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model bytes or cloud fallback are supplied. |
-| Preserve bounded chat history and memory | `/arcane/modules/PersistentAIChatSession.js` | **Browser / native WebView** with ChatEntity/DBOPFS and a configured chat function | Existing DBOPFS names and memory semantics are preserved. Live-context commit is atomic; durable persistence is explicit and coherent across user/assistant/tool turns. |
-| Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, bounded lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs bounded retrieval for each prepared chat send. |
-| Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
-| Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
-| Use OpenAI from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level AI chat/text behavior is normalized by the module; raw provider diagnostics and some response detail remain provider-specific. No automatic cloud fallback is inferred from local failure. |
-| Use local or cloud speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser**, **Native**, or **Cloud**, depending on the selected speech profile | The helper normalizes application-facing audio/text behavior; native and cloud request/response plumbing differs below that boundary. |
-| Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
-| Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |
-
-## The normalized application path
-
-For ordinary cross-platform application code:
-
-```javascript
-const runtime = globalThis.Arcane?.runtime?.current?.();
-
-if (!runtime?.connected) {
-    throw new Error('Open this application through an Arcane host.');
-}
-
-const access = await globalThis.Arcane.capabilities.list();
-
-if (!access.methods.includes('localAI.status')) {
-    throw new Error('This application is not admitted for local AI.');
-}
-
-const status = await globalThis.Arcane.localAI.status();
-console.log(status.ready, status.models);
-```
-
-This code does not select WebView2, WebKitGTK, or an HTTP bridge. It calls one
-Arcane API. The host chooses its transport, and Core applies the bound
-application identity and method policy.
-
-## Normalization levels
-
-### Fully SDK-normalized
-
-The Node toolchain uses `ArcaneError`, stable SDK error codes, structured
-`arcane-cli-events/1` records, normalized target descriptors, and authenticated
-receipt objects. Platform providers can add bounded target detail but cannot
-silently substitute a different target or artifact kind.
-
-The central EventManager is also host-neutral JavaScript. Its synchronous live
-bus preserves listener argument identity, while its optional history owns a
-separate diagnostic normalization boundary: snapshots are bounded, redacted,
-deeply frozen, and strictly importable as `arcane-event-stack/1`. DOM
-instrumentation adds browser diagnostics only; it does not replay browser
-state. See [EventManager and time-travel review](event-manager.md).
-
-### Browser-local provider adapter
-
-[`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) exposes the same
-provider-neutral lifecycle used by `createArcaneAI()`, while its packaged
-Wllama engine and caller-supplied model run inside the browser. This
-surface does not require an Arcane Core method grant because it does not call a
-Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and
-resource limits still apply.
-
-The shipped `0.3.0` runtime requires WebGPU and has no CPU fallback. A successful
-load requests full GPU offload (`gpuLayers: 99999`) and admits actual adapter,
-full-offload, buffer, queue, and settled-fence evidence. `navigator.gpu`
-presence by itself is not readiness. The provider emits the instrumented
-`arcane.ai.browser-wasm.webgpu.adapter.selected` capability event only after
-admitted adapter selection evidence.
-
-`localOnly:true` describes inference after load; it does not promise that load
-is offline. A normal cache miss downloads from the exact caller-supplied HTTPS
-URL. App, provider/model-binding, and load-operation options use
-`{security:{secure?:boolean, checks?:{byteLength?:boolean, sha256?:boolean}}}`.
-Fields resolve independently from load operation to provider/model binding to
-app configuration to the SDK default `secure:false`; omitted fields inherit.
-The resolved `secure` value supplies the default for both checks, and an
-explicit per-check boolean overrides that default.
-
-An enabled check requires and verifies its matching descriptor field. A
-disabled byte-length check permits `bytes` to be absent and never compares an
-expected size, although the actual downloaded or cached byte count is always
-recorded for storage and progress metadata. A disabled SHA-256 check permits
-`sha256` to be absent and performs no hash or digest-only reread. Status reports
-the effective checks and distinguishes unchecked integrity from successful
-verification of the enabled checks. Only enabled checks fail closed, while
-successful Wllama model loading remains mandatory. `load({offline:true})` permits only a compatible
-cache entry and otherwise rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`. Tool
-calls are result data for application review and dispatch; the SDK never
-executes them.
-
-[`arcane-os/ai/browser-speech`](ai/browser-speech.md) implements the sibling
-`stt` and `tts` provider/2 roles. Each caller-authenticated Whisper or Kokoro
-provider has its own load, use, cancellation, unload, dispose, cache, Worker,
-status, and error state. The SDK supplies neither speech adapter runtime bytes
-nor model/voice bytes; every immutable file is application-owned and admitted
-through an SDK-created authority and DBOPFS artifact store.
-
-The projected [`AIProviderRuntime`](runtime-modules.md#aiproviderruntimejs)
-normalizes those browser providers and can admit an externally supplied native
-or cloud provider/2 adapter. `AI.js` also supplies compatibility adapters for
-an already-selected legacy OpenAI route, Ollama route, or admitted Core speech
-route. SDK `0.3.0` publishes no privileged Core implementation, credential,
-model, or speech-runtime authority, and those adapters never probe, select,
-download, or fall back. The sticky
-[`AIRuntimeState`](runtime-modules.md#airuntimestatejs) surface keeps
-application UI independent of transport. A selected route remains explicit:
-browser failure is not permission to invoke Core or cloud.
-
-### Arcane bridge-normalized
-
-Core-backed calls return promises and reject with `Arcane.Error`. Transport
-selection, request correlation, JSON framing, capability denial, diagnostics,
-and public operation events are normalized at the bridge. Method data contracts
-remain authoritative; a method that documents platform-dependent fields is not
-silently widened into a fictional common shape.
-
-### Helper-normalized
-
-Renderer helpers can deliberately collapse provider detail. For example,
-`ollama.chatText()` returns a string extracted from the final chat envelope and
-`ollama.generateText()` returns a string extracted from the final generation
-envelope. `ollama.readiness()` returns a frozen `{ready, version, errorCode}`
-snapshot.
-
-### Provider-native within an Arcane boundary
-
-Direct `Arcane.ollama.chat()`, `generate()`, `show()`, `embed()`, and lifecycle
-methods return bounded Ollama-compatible envelopes. Arcane still owns admission,
-limits, error normalization, chunk correlation, and host transport, but it does
-not rename every provider response field. Feature-detect optional Ollama fields
-and use the high-level helpers when an application needs a smaller common
-contract.
-
-### Platform-dependent by design
-
-Host service settings, machine evidence, permissions, installation state, and
-native build artifacts can differ between Microsoft NT, Linux, Android, and a
-development browser. Those methods provide a stable outer contract and mark
-platform-specific fields or unsupported states. `supported: false` is a valid
-result where documented; it is not permission to bypass the host from renderer
-code.
-
-## No implicit protocol or provider fallback
-
-Arcane can expose the same method over different host transports, but it does
-not reinterpret a failed native call as authorization to send data to a cloud
-provider. Provider selection is explicit application/user profile state. A
-remote or development HTTP bridge transports an admitted Arcane call; it is not
-an automatic OpenAI fallback and does not turn a standalone browser into a
-native host.
-
-Deep details: [protocol selection and host boundaries](protocols.md).

package/docs/reference/behavioral-testing.md

@@ -1,133 +0,0 @@
-# Behavioral testing
-
-Reference completeness and runtime behavior are different gates. The SDK uses
-both.
-
-Completeness is bidirectional: implementation additions require documentation,
-and documentation keys that no longer exist fail just as visibly.
-
-## Fast contract path
-
-```bash
-npm run test:unit
-npm run test:functional
-```
-
-Unit coverage verifies schemas, descriptors, target contracts, error behavior,
-and public reference inventories. Functional coverage exercises CLI parsing and
-output, the development server, runtime verification, packaging, scaffolding,
-events, and the generated documentation/site contract.
-
-## Full development gate
-
-```bash
-npm run check
-```
-
-The full check validates source policy and the exact synchronized runtime
-manifest, then runs the non-overlapping unit, functional, integration, and
-regression sets. It remains development evidence; it is not native artifact or
-release acceptance.
-
-## Behavioral coverage model
-
-| Surface | Minimum behavior proved locally | Heavier evidence boundary |
-| --- | --- | --- |
-| Package entrypoints | Every declared JavaScript export imports; documented names match; constants and synchronous validators preserve their public contracts. | None for import itself. Operations that invoke tools use the matching boundary below. |
-| Canonical events, EventManager, and event stacks | One branded/versioned `globalThis.arcaneEvents` per realm, fail-closed collision admission, duplicate-module reuse, declared source ownership, canonical/source delivery order, frozen occurrence metadata, exact cancellation, AbortSignal cleanup, disposable subscriptions, source teardown/re-registration, observational listener failure, EventTarget compatibility, one-way DOM projection, deprecated state-free `aiRuntimeEvents`, live isolated-bus pub/sub, nested causation, immutable/redacted stacks, strict import, bounded overflow, seek, playback, and DOM privacy/lifecycle. | Real user journeys and browser layout belong in a browser harness; an occurrence, EventTarget/DOM projection, or event-stack review never proves that external side effects stopped, completed, or can be replayed. |
-| CLI | Commands parse, acknowledge, select one scope, produce normalized human/JSON/NDJSON output, propagate cancellation/failure, and reject invalid cardinality. | Native build/run requires the selected real provider and host. |
-| Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
-| Provider-neutral AI runtime and chat/speech activation | Provider/2 registration, closed three-role configuration, opt-in STT startup, legacy Cloud/Core speech readiness, independent LLM/STT/TTS load/unload/status, latest-request-wins settlement, owned STT signals, TTS mute lifecycle, route-owned voice defaults, sticky-state-only readiness for both speech components, shared selected-unloaded activation request/cancellation/error behavior, fail-closed programmatic voice recording, public transcript-replacement supersession of late transcribe/save/complete settlement, `AI.fetchSTT` callback-position compatibility, stale-callback suppression, and absence of silent provider fallback are exercised against bounded providers and host callbacks. | Real model/runtime admission remains the selected provider's evidence boundary; provider-promise settlement, state, an abort signal, or an activation event does not by itself prove underlying provider work stopped or native, cloud, or browser-model availability. |
-| Browser-WASM local AI | The exact exported namespace, canonical ordered `{id, files:[{name?,url,bytes?,sha256?},...]}` descriptor plus its one-file compatibility input, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest capability/status reasons, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | An optional explicit `secure:true` verification may install the packed SDK into a real Chrome app, load authenticated Wllama 3.6.0 JS/WASM assets, perform a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and verified offline reuse. That heavyweight hardening proof is not an ordinary publication gate or an implicit model download. |
-| Browser speech | Caller-owned Whisper/Kokoro authority, independent STT/TTS routes, ordinary direct upstream runtime/model authority, explicit `secure:true` graph admission, manifest-last DBOPFS cache, strict offline admission, independent Worker lifecycle, pre-Worker versus in-Worker cancellation, Blob/File STT conversion, WAV TTS conversion, and no cloud fallback are exercised with bounded synthetic artifacts and adapters. | A real runtime/model/voice download and actual transcription or synthesis use the application's selected upstream packages/providers, browser media support, and explicit user action. Optional strict graph evidence remains scoped to `secure:true`. |
-| Persistent chat and document context | Atomic in-memory/history commit, explicit per-turn persistence, single structural tool-call sequencing, bounded bootstrap/search/context, caller-source `evaluate()` budgets, cancellation, and reject versus `preserve-readable` partial coverage are exercised with app-scoped adapters. | Live Core/provider inference and durable browser storage remain separate authorities; tests never treat a fake chat function or in-memory adapter as host/storage proof. |
-| Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
-| Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |
-| Native providers | Plan/provider protocol, explicit target, receipt authentication, artifact reader, and unavailable-path honesty are tested with bounded fixtures. | Exact Windows, Linux, or Android artifact verification and launch must run on that actual platform/architecture. |
-
-## Executable examples
-
-Examples should be safe to run repeatedly and should stop at the last boundary
-they can honestly prove. Documentation examples that would download a model,
-restart a service, create a user, install software, log out, delete a model, or
-launch an external resource define a function but do not invoke it.
-
-Behavior tests replace real authority with an explicit fake only for the public
-client contract. They must assert the exact request sent to the fake and the
-normalized result returned to the application. A fake provider never counts as
-native host, artifact, installation, or model-service evidence.
-
-The browser-WASM guide follows the same rule: it shows exact model authority
-and wiring, but leaves the download/load call behind an explicit user action.
-Focused contracts cover the plain security shape and fieldwise precedence from
-load operation to provider/model binding to app configuration to SDK default
-`secure:false`. They prove that omitted values inherit, the resolved `secure`
-value defaults both checks, and explicit per-check booleans override that
-default.
-
-The default path proves actual bytes are counted and persisted and Wllama
-confirms a loaded model without requiring descriptor `bytes` or `sha256`.
-Disabled byte-length checks never compare an expected count; disabled SHA-256
-checks never instantiate hashing or reread a multi-gigabyte file solely for a
-digest. Enabled-check cases prove the matching descriptor field is required and
-fail closed on mismatch. Status cases distinguish effective checks, per-check
-outcomes, and unchecked versus enabled-check-verified integrity. The authoritative
-browser contract separately proves the enabled secure path hashes stored and
-cached bytes, `AbortSignal` settles as `ARCANE_AI_REQUEST_ABORTED`, and tool-call
-arguments are surfaced without invoking application handlers. Model license
-metadata is never treated as runtime admission evidence.
-
-## Host and normalization cases
-
-Cross-host APIs should cover at least these cases at their owning layer:
-
-1. standalone browser with no `Arcane` host;
-2. development HTTP transport with normalized request/error settlement;
-3. native transport with capability admitted;
-4. native transport with method or capability denied;
-5. platform-dependent `supported: false` result where documented;
-6. provider-native success envelope passed through unchanged;
-7. helper-normalized text/readiness result;
-8. stream chunk correlation and late/foreign chunk rejection;
-9. abort or timeout behavior, including whether host work can continue;
-10. explicit provider selection with no implicit local-to-cloud fallback.
-
-Central-event changes additionally cover the exact retention boundary:
-`maxEvents` ordinary records plus one terminal
-`TIME_TRAVEL_OVERFLOW_EVENT`, recording disabled, DOM observation stopped,
-continued unrecorded live delivery, rejection when re-enabling before
-`clearHistory()`, and strict acceptance of only a terminal overflow marker.
-DOM cases assert that private values, credentials, sensitive attributes, URLs,
-and markup remain redacted under every capture-option combination.
-
-The focused singleton contract also owns these cases in
-`test/event-manager.test.mjs`: global property/brand/protocol/API descriptor
-admission; same-object reuse across duplicate module URLs and package
-entrypoints; exact `subscribe(type,handler,{once,signal})` behavior; idempotent
-`unsubscribe()`/`unsubscribe.dispose()`; one active
-`createSource(owner,{source,eventTypes,onListenerError})` handle; immutable
-`arcane-event-occurrence/1` values and privacy separation; synchronous
-cancellation; dispatch-safe removal and reentry; final source disposal;
-EventTarget deduplication/admission; one-way `CustomEvent` projection; and
-nonrecursive listener-error publication. Runtime behavior tests own the
-`aiRuntimeEvents` compatibility view and each migrated module/component's
-instance-scoped projection and cleanup. Reference-completeness tests own the
-public export names and exact focused-guide coverage.
-
-Canonical event publication itself is deliberately synchronous and
-observational. Tests must not await listener return values or present
-`arcaneEvents` as backpressure. Promise settlement, async callback failure, and
-ordered delivery belong to the operation promise or `createEventQueue()` test
-that owns that work. Abort-driven listener removal proves cleanup only; it does
-not prove already-started host, provider, worker, or queue work stopped.
-
-## Test ownership
-
-The SDK owns the singleton authority, its per-realm source adapters, package and
-managed-browser projections, focused event/source/DOM contracts, runtime
-compatibility views, package, CLI, synchronized renderer, documentation, and
-injected provider-boundary behavior. Arcane OS owns live Core dispatch, native host
-bridges, capability policy, host service adapters, and real ArcaneOllama
-integration. A change that crosses both repositories needs focused tests at both
-owners; copying a Core test into this package would not make the SDK the Core
-implementation owner.