Availability and normalization

Use this page to choose an API by capability. The compact labels tell you where it runs; the protocol guide contains the implementation detail.

Shared type predicates

SDK-owned JavaScript uses the declared strong-type dependency for type predicates. Node and managed renderer modules import Is from strong-type; browser providers and workers use their shipped relative dependency path. Component scripts import it within their own asynchronous component scope. Publication bootstrap tools import the shipped runtime dependency by relative path so they remain available before npm dependency installation. The dependency pin and both shipped projections use 2.0.1. Update them together through the published dependency workflow when another version is needed.

Reuse one non-throwing instance per module or component:

import Is from 'strong-type';

const is=new Is(false);

function requireText(value){
    if(!is.string(value))throw new TypeError('Text is required.');
    return value;
}

The predicates classify values without coercing them. Existing API owners keep their defaults, domain constraints, complete payloads, and public error behavior. Use number for primitive numbers, finite for finite numbers, and integer or safeInteger for the corresponding integer contract. object includes null; retain a contract's separate null and array handling. plainObject is narrower than a general non-array object check and must not silently reject previously accepted class instances.

Constructor identity checks, diagnostic type labels, foreign-language source, and isolated generated script bodies retain native operators where a replacement would change their contract or execution scope. DBOPFSWorker.js and SystemPlatformPresentation.js retain their few native predicates to preserve classic-script loading and synchronous availability. Upstream dependency source is consumed unchanged. Non-throwing strong-type array and constructor probes return false when a probe throws; SDK branching continues through its owning error path.

Availability labels

“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

The normalized application path

For ordinary cross-platform application code:

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, and normalized target descriptors. Platform providers can add complete 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 complete, redact credentials and explicitly protected private fields, and are importable as arcane-event-stack/1. DOM instrumentation adds browser diagnostics only; it does not replay browser state. See EventManager and time-travel review.

Browser-local provider adapter

arcane-os/ai/browser-wasm 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 current browser runtime requires WebGPU and has no CPU fallback. A successful load requests full GPU offload (gpuLayers: 99999). navigator.gpu presence by itself is not readiness. The provider emits the instrumented arcane.ai.browser-wasm.webgpu.adapter.selected capability event after adapter selection.

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 may use {security:{secure?:boolean}}. The SDK default is secure:false, and omitted security leaves ordinary model loading fully functional. Download byte counts, remaining bytes, rate, and ETA are observational progress only. Optional member bytes values may initialize progress and HTTP Range planning, but neither declared nor observed byte measures validate, admit, identify, hash, or decide cache reuse for model content. Completed split members and deterministic Range parts within any member are retained across an interrupted install so retry fetches only missing work. Exact part length is used only to recognize a completed HTTP transport frame. Zero-length whole entries and incomplete Range sets cannot become cache hits; failed or incorrectly framed active parts are removed. After a complete current representation exists, the store attempts to remove redundant Range fragments; cleanup failure is warned without hiding the usable model. Optional secure:true records intent only; historical checking remains disabled until a separately authorized user review. 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; every declaration and emitted call requires nonempty user-facing arguments.message, and the SDK never executes them. An ordered assistant call array remains pending until the application records exactly one matching executed, declined, cancelled, or not-executed role:'tool' result with nonblank user-facing content for every pending ID in one atomic batch. The direct browser provider and its v1-to-provider/2 adapter validate the same request history, declarations, and terminal structural-call contract. Structured completions contain exactly one top-level message or choices envelope, every choice is validated, and the ordinary stream iterator exposes complete content and reasoning projections from every choice in provider order while its private pump continues even when the terminal result is awaited first. Structural deltas remain private until validation; terminal-only calls are valid, while observed calls must preserve their choice, order, identity, exact arguments, and extension fields at settlement. Complete provider chunks and terminal envelopes remain available through explicit data, response, or inspection surfaces.

arcane-os/ai/browser-speech implements the sibling stt and tts provider/2 roles. Each caller-selected 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 nor model/voice content; every selected file is application-owned and stored through the SDK-created DBOPFS adapter.

Kokoro defaults to {device:'auto',maxConcurrentRequests:4}. Automatic selection attempts the complete Worker/session pool on WebGPU when exposed and recreates the complete pool on WASM if WebGPU loading rejects. Explicit webgpu or wasm disables that fallback. Each accepted synthesis owns one pool slot, and provider-neutral FIFO backpressure preserves later requests. Whisper remains one WASM Worker.

For high-level speech, read ai.providerRuntime.status('tts', {execution:true}).execution after load. Kokoro reports requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount; requested auto with selected wasm identifies fallback. selectedDevice is null while unloaded. The default status() remains the sticky lifecycle snapshot; execution is an explicit provider read, and inspection errors propagate. Neither state proves physical GPU kernel overlap. See the copyable speech quick start.

Materialized speech graphs use their file inventory as a routing table, not an admission policy. Known downloaded imports, fetches, Workers, and cache reads route to their materialized URLs; unmapped operations fall through to the native browser API with caller options preserved, and native cache writes are not disabled.

The projected AIProviderRuntime normalizes those browser providers and can admit an externally supplied native or cloud provider/2 adapter. AI.js also supplies built-in adapters for an already-selected TWiN Cloud LLM route, Ollama route, or admitted local Core speech route. Its built-in audio selections are on-device only: saved OPENAI speech selections migrate to LOCAL_SPEACH with whisper-small for STT and kokoro for TTS. The SDK publishes no privileged Core implementation, credential, model, or speech-runtime authority, and those adapters never probe, select, download, or fall back. The sticky AIRuntimeState 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 complete Ollama-compatible envelopes. Arcane still owns 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.