arcane-os 0.1.0-dev.5

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

@@ -0,0 +1,123 @@
+# 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 API while Arcane selects 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. |
+| 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).
+
+### 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

@@ -0,0 +1,86 @@
+# 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. |
+| EventManager and event stacks | Live pub/sub ordering and payload identity, nested causation, immutable/redacted snapshots, strict import, bounded overflow, seek, all playback modes/lifecycle outcomes, cancellation, and DOM start/stop/privacy behavior. | Real user journeys and browser layout belong in a browser harness; event-stack review never proves that external side effects can be replayed. |
+| CLI | Commands parse, acknowledge, select one scope, produce normalized human/JSON/NDJSON output, propagate cancellation/failure, and reject invalid cardinality. | Native build/run requires the selected real provider and host. |
+| Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
+| 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.
+
+## 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.
+
+## Test ownership
+
+The SDK owns 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.