arcane-os 0.3.0 → 0.3.2

package/docs/platform-targets.md

@@ -1,108 +0,0 @@
-# Platform target contract
-
-Every target adapter implements protocol `arcane-target-adapter/1` with these
-named operations:
-
-```text
-describe -> doctor -> prepare -> plan -> build -> verify -> run
-```
-
-The available browser adapter plans from the selected workspace and schema-1
-release manifest. The SDK also implements the process-local
-`arcane-native-build-plan/1` and `arcane-native-builder/1` boundary for an
-explicitly injected provider. It binds an authenticated app release and
-schema-2 descriptor, toolchain receipt, platform, architecture, format, signing
-mode and identity, declared dependency releases, and destination. A paired
-provider must verify the built artifact before build completion, and verify/run
-reuse that exact artifact receipt.
-
-Native targets are available by explicitly pairing the SDK with fixed provider
-modules in a compatible Arcane OS checkout. Every native request also requires
-the canonical app descriptor to declare the exact target selected on the
-command line. The SDK package does not silently search for a toolchain, infer a
-descriptor target, embed the Arcane machine bundle, or substitute browser
-output. For example:
-
-```bash
-# Choose one target when creating each app repository.
-npx arcane-os@dev new my-app --path ./my-app --target portable --git
-cd my-app
-npm install
-npm exec -- arcane native-doctor --target portable --arcane-root "../Arcane OS"
-npm exec -- arcane build --target portable --arcane-root "../Arcane OS"
-
-# In an app scaffolded with --target windows-x64:
-npm exec -- arcane build --target windows-x64 --arcane-root "../Arcane OS"
-npm exec -- arcane run --target windows-x64 --arcane-root "../Arcane OS"
-
-# In an app scaffolded with --target linux-x64:
-npm exec -- arcane build --target linux-x64 --arcane-root "../Arcane OS"
-npm exec -- arcane run --target linux-x64 --arcane-root "../Arcane OS"
-
-# In an app scaffolded with --target linux-arm64, on native ARM64 Linux:
-npm exec -- arcane native-doctor --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
-npm exec -- arcane build --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
-npm exec -- arcane run --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
-
-# In an app scaffolded with --target android-arm64. The run command requires
-# one connected physical Android device with native ARM64 support:
-npm exec -- arcane native-doctor --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
-npm exec -- arcane build --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
-npm exec -- arcane run --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
-```
-
-Every native scaffold also declares the browser target, so one repository can
-use the normal browser development loop and its one selected native build. It
-includes the raster icon required by current Arcane native admission. Use the
-matching scaffold target (`portable`, `windows-x64`, `linux-x64`, `linux-arm64`,
-or `android-arm64`) before running the corresponding command.
-
-`native-prepare` remains a standalone integrity diagnostic. A receipt cannot be
-carried through a later CLI process, so the normal build recipe omits it and
-lets `build` prepare and reuse one exact toolchain state.
-
-The portable output is a verified app-scoped Arcane Core directory. It is an explicit
-portable builder payload, not an executable, and it has no direct run operation.
-The external workspace defaults to `build/portable/`; integrated Arcane work
-must use the same canonical checkout for `--workspace` and `--arcane-root`, and
-must name an `--output-root` outside that checkout.
-
-Compatibility uses the highest minimum Core version declared by the SDK runtime,
-selected app, and bundled app dependencies, plus each app's Arcane protocol and
-required features, capabilities, and methods. Newer Core versions are accepted
-when those contracts remain available. See [compatibility.md](compatibility.md)
-for the complete admission and breaking-change rule.
-
-| Target | Formats | Development status |
-|---|---|---|
-| `browser` | `directory` | Available |
-| `portable` | `portable` directory | Available with explicit `--arcane-root`; verified, not executable |
-| `windows-x64` | `exe` bundle | Available with explicit `--arcane-root`; unsigned local development only |
-| `linux-x64` | `deb` | Available with explicit `--arcane-root`; unsigned local development only |
-| `linux-arm64` | `deb` | Available with explicit `--arcane-root` on a compatible native ARM64 toolchain; unsigned local development only |
-| `android-arm64` | `apk` | Available with explicit `--arcane-root`; development-signed, architecture-neutral, and physical/native ARM64 for run |
-
-Every native target accepts one verified app release and its exact bundled
-dependency closure through the provider boundary. The providers retain the
-toolchain and artifact authority required for same-process verification and,
-where supported, launch; app source and workspace paths are not supplied to the
-provider. Linux run extracts to a user-owned development tree without package
-installation or elevation.
-
-Linux ARM64 uses the implemented Linux provider and is available only with a
-compatible native ARM64 toolchain. The target-scoped workflow at Arcane revision
-`4382043c09285ea203aa6daba1732660966ac409` built and retained-verified a native
-ARM64 DEB, proved AArch64 host/Core/bridge identities, reached WebKit readiness,
-and drained the owned process group. It loaded Ubuntu's packaged Bubblewrap
-AppArmor profile while leaving the global user-namespace restriction enabled.
-Android produces one development-signed APK with no native library or
-ABI-specific payload. The APK is therefore architecture-neutral, while
-`arcane run --target android-arm64` deliberately requires a physical device
-with native ARM64 support. The hardened path has exact-SHA physical ARM64/API 37
-build, readiness, cancellation, uninstall, and absence evidence. Both records
-are development evidence, not production readiness.
-
-Android AAB output, release signing, store publishing, and update continuity are
-deferred. Windows and Linux production signing, installation, and update
-acceptance also remain separate promotion work. The SDK never copies
-proprietary application source into the Arcane checkout to bypass the boundary.

package/docs/publishing.md

@@ -1,201 +0,0 @@
-# npm publication
-
-## Canonical main and npm channels
-
-`main` is the single canonical working and publication branch before and after
-the first release. Do not create a development branch. `-dev` versions select
-the npm `dev` dist-tag, while bare numeric stable versions select
-`latest`. These are registry channels, not Git branches.
-
-## Stable and development npm publication
-
-The package version and `publishConfig.tag` must agree exactly: `-dev` uses
-`dev`, and a bare numeric stable version uses `latest`. npm is the canonical
-SDK distribution: application repositories add an exact `arcane-os` project
-dependency and invoke its local CLI with `npm exec -- arcane`. A separate
-global installer, standalone SDK executable, NuGet package, Homebrew formula,
-or OS package is not part of this release surface.
-
-`Check` validates only package-publication authority once: package metadata,
-the executable and `.gitattributes` boundary, both authenticated runtime
-receipts, and the focused npm identity/channel/provenance contract. One
-unprivileged producer then packs one `.tgz` under pinned Node and npm versions.
-The producer writes a canonical manifest containing the source SHA,
-clean-checkout flag, package inventory, byte length, SHA-256, npm SHA-1 shasum,
-and SHA-512 integrity. One Ubuntu x64 consumer at the declared Node `22.23.2`
-floor downloads that Actions artifact by immutable artifact id, verifies the
-receipt, installs the tarball into a disposable project, exercises
-`npm exec --offline -- arcane`, and runs one small capability contract through
-the installed package's `arcane-test.mjs`. It never repacks. A final readiness
-job verifies the same artifact's identity, integrity, shasum, license inventory,
-and content boundary once. Golden snapshots, broad integration/regression and
-platform matrices, browser/process simulations, Pages, Examples, and
-presentation work are normal or post-registry checks rather than npm
-publication gates.
-
-`publish-dev.yml` can run only when manually dispatched from `main` in
-`TheWizardNexus/arcane-os-sdk`. Dispatch requires an authorized npm content
-classification. `unresolved` fails closed. `standard` permits the workflow's
-direct trusted-publishing path only when the package has no conflicting
-dual-use declaration. `dual-use` fails closed until the package includes npm's
-persistent `contentPolicy.class=dual-use` metadata and root `DISCLOSURE`, and
-the workflow is deliberately changed to `npm stage publish` plus human 2FA
-promotion. Direct trusted publishing is not permitted for that class.
-
-For the standard path, the workflow authenticates a successful `Check` push
-run for that exact `main` SHA, downloads its immutable package artifact,
-reverifies the manifest and bytes, derives `dev` or `latest` from the strict
-version, and publishes the downloaded `.tgz`. It
-never invokes `npm pack` or `npm publish .` under publication authority. A
-repository-wide concurrency group prevents simultaneous publication jobs;
-GitHub may replace an older pending dispatch, and each surviving dispatch is
-safe to rerun. Preflight rejects byte mismatches, tag rollback, malformed
-registry state, or any dist-tag other than `dev` and `latest`; an
-already-published matching version is an idempotent success. The historical
-first-version state where both tags identify `0.1.0-dev.5` is accepted only
-with its recorded integrity and shasum and only while no stable version exists.
-Post-publication verification preserves the other channel, checks integrity
-and shasum, and validates trusted-publisher provenance. It tolerates npm's
-publish-time scanning for up to 15 minutes. If
-scanning or manual review remains pending, the workflow reports that state and
-a rerun safely resumes verification without republishing immutable bytes.
-
-The unscoped package installs both `arcane` and `arcane-os`. The short command
-is the documented default; `arcane-os` is the collision-safe fallback. npm
-package names are unique, but executable names are not globally reserved.
-
-When `npm view arcane-os@dev version` reports the package unavailable, run
-`npm run pack:local` in this SDK checkout for local development, scaffold with
-`node ./bin/arcane.mjs new ...`, and install the resulting `.tgz` into the app
-with `npm install --save-dev --save-exact <path>`. Keep the tarball at the path
-recorded by `package-lock.json`; subsequent `npm ci` verifies its recorded npm
-integrity. Arcane separately requires the installed package to identify exactly
-as `arcane-os@0.1.0-dev.5` and verifies the locked runtime. A local directory
-`file:` install is intentionally unsupported because it may be linked.
-
-The first-version bootstrap established these permanent audit boundaries:
-
-1. Push the intended clean `main` commit and require the npm-critical Check
-   workflow—package authority, one producer, one installed Linux capability
-   smoke, and one identity/legal verifier—to pass.
-2. Review the uploaded tarball inventory, manifest, checksum, and license
-   notices. Ensure the Arcane OS monorepo package is private so it cannot publish
-   the same npm name accidentally.
-3. Make and record the npm content-policy decision before packing the bootstrap
-   bytes. A `standard` decision permits direct OIDC after bootstrap. A
-   `dual-use` decision requires `contentPolicy.class=dual-use`, a root
-   `DISCLOSURE` in the tarball, and staged publication with human 2FA promotion;
-   npm treats that declaration as persistent across versions.
-4. Because npm requires a package to exist before trusted or staged publishing
-   can be configured, an authorized npm maintainer must download that exact
-   green Actions artifact and publish its `.tgz` once under `dev` through an
-   interactive session with 2FA. That method is permitted for either content
-   class; the dual-use metadata and disclosure must already be inside the exact
-   tarball. Do not rebuild or repack it for this bootstrap. After the package
-   exists, standard releases may publish directly through OIDC, while dual-use
-   releases must use `npm stage publish` and human 2FA promotion.
-5. Verify the registry's `dist.integrity` and shasum. npm's required bootstrap
-   state has both `dev` and `latest` at the immutable `0.1.0-dev.5` bytes
-   until the first stable publish moves only `latest`. The sole trusted
-   publisher is the exact `publish-dev.yml` workflow and `npm` environment.
-6. Later standard development versions may use the workflow's direct OIDC
-   authority. A dual-use version must be staged and promoted with human 2FA.
-   Any missing policy decision, package bootstrap, environment, publisher
-   binding, or exact-SHA artifact is a publication blocker rather than a reason
-   to fall back to a token or repack.
-
-Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
-dependency source must be reachable by the runner. A sibling local tarball is a
-workstation workflow, not a portable GitHub dependency source; switch to the
-exact registry release (or deliberately vendor the tarball) before remote CI.
-
-## Reusable application release workflow
-
-External app repositories can call `.github/workflows/release-app.yml` by an
-immutable SDK repository revision. The reusable workflow checks out the exact
-caller SHA, installs only the caller's committed dependency lock, requires
-`arcane-os@0.1.0-dev.5`, and checks, packages, bundles, independently verifies,
-and uploads one explicitly selected app. Every third-party action reference is
-pinned to a full commit SHA. The workflow never publishes npm, creates a GitHub
-Release, loops across apps, or changes Arcane admission state.
-
-The build job holds only `contents: read`; its caller-owned checks, package
-scripts, and adapters never receive `id-token: write` or `attestations: write`.
-It uploads the exact bundle together with canonical metadata. A fresh
-caller-code-free job downloads that upload by immutable artifact id, checks out
-the called workflow's exact SDK revision, directly imports its verifier under
-supported Node 24, binds the receipt app id to the requested app, and exposes
-the independently reverified artifact, descriptor, and release identities as
-the reusable workflow outputs. This post-upload boundary prevents a background
-caller process from making the published outputs describe pre-upload bytes.
-
-GitHub artifact attestation is an explicit `attest: true` input and is false by
-default because availability for private repositories depends on the caller's
-GitHub plan. A caller that requests an unsupported attestation fails instead of
-silently producing weaker provenance. GitHub does not let a called workflow
-raise the caller job's permission ceiling. An attesting caller must therefore
-grant these permissions on the reusable-workflow job itself (prefer this
-job-scoped grant over workflow-wide authority):
-
-```yaml
-jobs:
-  release-app:
-    permissions:
-      contents: read
-      id-token: write
-      attestations: write
-    uses: TheWizardNexus/arcane-os-sdk/.github/workflows/release-app.yml@<FULL_40_CHARACTER_COMMIT_SHA>
-    with:
-      app-id: example-app
-      attest: true
-```
-
-Without that caller grant, `attest: true` fails even when the repository plan
-supports artifact attestations. When requested, a fresh privileged job
-depends on the successful post-upload verifier, downloads the same immutable
-artifact id with the pinned `actions/download-artifact` revision, checks out only
-`job.workflow_repository` at `job.workflow_sha`, selects supported Node 24 via
-the pinned `actions/setup-node` revision, and directly imports the
-dependency-free verifier from those trusted SDK source bytes. It rechecks the
-app id, bundle structure, digest, byte length, complete
-canonical metadata, and every post-upload workflow output. No package manager,
-dependency resolution, caller checkout, or caller-owned code runs while that job
-holds OIDC and attestation permissions. Whether attested or not, the upload is a
-build output.
-Arcane must verify an approved provenance or independent signature and an
-Arcane-owned authorization-lock entry before installation; the archive's
-internal checksums alone do not grant authority.
-
-Stable versioning, the npm `latest` tag, and an official GitHub release remain a
-separate explicit release decision. Current `main` development does not
-silently convert a `-dev` package into an official release. A stable release
-must publish the same source-validated and platform-smoked `.tgz` under
-`latest`; only after registry
-integrity matches may GitHub attach that `.tgz`, manifest, and checksum. Its Git
-tag and GitHub release title must both be the same bare numeric
-`MAJOR.MINOR.PATCH`. Prerelease versions do not get a misleading numeric
-GitHub release, and no release creates a Git branch for an npm dist-tag.
-
-## Documentation publication
-
-GitHub Pages publishes the static `site/` tree from the newest successful
-`main` push `Check`. A completed Check triggers the Pages job, which resolves
-the newest successful receipt at deployment time so out-of-order completion
-cannot roll the site backward. It checks out that authenticated SHA without
-persistent credentials, validates the static tree, and uploads only `site/`.
-It does not rerun the SDK test suite or execute repository build code.
-
-The deployment job holds only the read, Pages, and OIDC permissions required by
-that single checked artifact. The `github-pages` environment remains the final
-deployment authority. Documentation channels are post-registry presentation
-work and do not change the canonical source branch.
-
-## Work-amplification record
-
-The release graph is one checked `main` SHA and one npm release candidate. One
-package-authority job runs the narrow source policy and publication contract;
-one producer creates the tarball; one Ubuntu consumer executes those exact
-installed bytes; and one readiness job verifies identity and legal inventory.
-OIDC publication reuses that successful exact-SHA artifact without rebuilding.
-Platform matrices, full product regressions, Pages, and broader presentation
-work remain outside registry publication and run separately when warranted.

package/docs/reference/README.md

@@ -1,187 +0,0 @@
-# Arcane OS SDK developer reference
-
-This reference answers developer questions in this order:
-
-1. **What can the application or tool do?**
-2. **What should I import or call?**
-3. **What does a successful result look like?**
-4. **Where does it run?**
-5. **Only when needed: which transport, host, provider, or kernel boundary implements it?**
-
-The default path is capability-first. Transport and implementation detail is
-kept in the [protocol and host architecture guide](protocols.md), and every
-high-level page links to the relevant deep section instead of repeating it.
-
-## Reference map
-
-| Need | Start here |
-| --- | --- |
-| Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
-| Publish central events, capture bounded time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
-| Use the `arcane` command | [CLI reference](cli.md) |
-| Generate named browser imports or inspect the authenticated physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
-| Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
-| Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
-| Use a shared entity | [Runtime entity modules](runtime-entities.md) and [exact export contracts](core/arcane-entities.md) |
-| Load a reusable HTML component | [Runtime component catalog](runtime-components.md) |
-| Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
-| Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
-| Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
-| Run a caller-authenticated local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
-| Run caller-authenticated Whisper or Kokoro in the browser | [Browser speech providers](ai/browser-speech.md) |
-| Use Arcane Ollama | [Arcane Ollama guide](arcane-ollama.md) |
-| Understand transports and protocol switching | [Protocol and host architecture](protocols.md) |
-| Run contract and behavior tests | [Behavioral testing](behavioral-testing.md) |
-
-## Version scope and provenance
-
-This repository contains explicitly versioned surfaces with different owners:
-
-| Surface | Source identity | Meaning |
-| --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.3.0` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm`, `arcane-os/ai/browser-speech`, and portable `arcane-os/mail` entrypoints in this checkout. |
-| Browser runtime | `runtime/ARCANE_RUNTIME_RELEASE.json`, SDK `0.3.0`, protocol `arcane/1` | The SDK-canonical dynamic runtime inventory shipped under `runtime/`; the receipt binds its exact paths, bytes, inventory, and digest. |
-| Browser SDK runtime | `browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json`, SDK `0.3.0` | The dynamically derived browser closure for events, Wllama, and Browser Speech mechanisms. It contains no speech runtime, model, voice, third-party legal/notice, or corresponding-source payloads. |
-| 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. |
-
-The SDK runtime receipt and Core reference are distinct evidence and have
-different current authorities. A browser module's bytes come from the SDK
-runtime receipt. A native build selects one
-explicit Arcane OS checkout and Core. This SDK version accepts that selection
-only after its current native plan checks the exact declared protocol, version,
-features, capabilities, methods, provider contract, and identity-bound
-receipts. That current-build admission does not promise that a future SDK will
-accept this Core or that this SDK will accept a future Core. A matching protocol
-name or higher version alone is not compatibility or authority.
-
-See [Core reference provenance](core/README.md) for the imported inventory and
-the exact distinction between a documentation snapshot and shipped runtime
-bytes.
-
-## Published 0.2.3
-
-The most recently verified published package before this 0.3.0 source candidate
-is exactly `arcane-os@0.2.3` from source commit
-`d717f21d45664d20e4ed6377596db87c47492e11`. The npm `latest` dist-tag resolves
-to `0.2.3`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
-
-The singleton-event, Mail, warn-first Browser Speech, and mixed-route contracts
-documented below are newer canonical source. They are not package authority in
-`0.2.3`; consumers require the numeric 0.3.0 publication before relying on them.
-
-| Evidence | Exact value |
-| --- | --- |
-| npm integrity | `sha512-TZewkGM7dh9PdVnOtnkBO7QalJ6qyWWdKruCmsTxoHyeoG5XpqVbkNgiJhtBLhrIzgUV3vydYplxZQkIbIWoHg==` |
-| npm shasum | `8e978a23289a41db130253e6475a0c8bb0c0d73f` |
-| Immutable release tarball | `arcane-os-0.2.3.tgz`; 6,999,078 bytes; SHA-256 `857f179c2f9d4549e7691b4e6cebc49e5ab5e18600816443b26319c61fc1f85d` |
-| GitHub release | [`0.2.3`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.2.3) (tag and title are both exactly `0.2.3`) |
-| Hosted source/artifact gate | [Check run 33052271534](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33052271534) |
-| Trusted publication | [Run 33052383457](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33052383457) |
-
-The npm SLSA provenance binds the published package to that exact source commit
-and `.github/workflows/publish-dev.yml`. Hashes prove byte identity or
-consistency; provenance establishes the recorded source/workflow relationship.
-Neither claim alone proves browser hardware support, native admission, or a
-particular application's provider/model policy.
-
-## MDN-style page contract
-
-Public reference entries follow the established Arcane documentation model:
-
-- one canonical, mechanically readable inventory owns each public name;
-- every public member or module has one guide entry headed by its exact name;
-- each guide leads with an overview and the shortest safe working example;
-- parameters, return values, errors, side effects, cancellation, and events are
-  stated when they apply;
-- availability is summarized near the call, while transport mechanics are
-  folded into or deep-linked from the entry;
-- normalized results are distinguished from provider- or platform-native
-  envelopes;
-- examples do not trigger destructive, privileged, expensive, or external
-  actions merely by being copied.
-
-## Public runtime inventory
-
-The package exposes 200 semantic JavaScript records across 14 JavaScript
-entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
-metadata. Ten entrypoints are Node.js control-plane surfaces,
-`arcane-os/event-manager` and `arcane-os/mail` run in Node and browsers, and
-`arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
-The [machine-readable package
-inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
-are checked bidirectionally against every declared JavaScript export.
-
-The seven update-check records are explicit on-demand checks; they do not poll,
-download, install, or self-update.
-
-The synchronized browser payload exposes:
-
-- 84 JavaScript module artifacts under `runtime/arcane/modules/`, including
-  ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
-  mail transport;
-- 15 shared entity modules under `runtime/arcane/entities/`;
-- 39 reusable HTML-import components under `runtime/arcane/components/`;
-- seven shared CSS artifacts, security policy, images, and the vendored
-  `strong-type` dependency.
-
-The module and component catalogs enumerate every shipped artifact, including
-vendor support files that are not ESM imports. The runtime manifest remains the
-byte-level source of truth; the catalogs explain what those bytes let a
-developer do.
-
-## Normalized AI
-
-Portable applications start with the provider-neutral runtime rather than an
-Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
-
-| Need | Public surface | Availability |
-| --- | --- | --- |
-| Select, load, unload, inspect, cancel, and use LLM/STT/TTS independently | [`AIProviderRuntime.js`](runtime-modules.md#aiproviderruntimejs) | Cross-host controller; each registered provider declares its own host requirements. |
-| Observe sticky role state and startup settlement | [`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs) | Cross-host EventTarget state; observation grants no authority. |
-| Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
-| Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
-| Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebGPU/full-offload evidence, WebAssembly, and OPFS/DBOPFS. |
-| Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers, and caller-supplied immutable runtime/model bytes. |
-| Add bounded persistent history and memory | [`PersistentAIChatSession.js`](runtime-modules.md#persistentaichatsessionjs) | Browser/native WebView runtime with ChatEntity/DBOPFS and a configured chat function. |
-| Add explicit document search/context | [`DBOPFSDocumentLibrary.js`](runtime-modules.md#dbopfsdocumentlibraryjs) | Existing DBOPFS-style adapter; search occurs only after the app calls it or deliberately wires its context builder into chat. |
-
-There is no automatic local-to-cloud, browser-to-Core, provider-to-provider, or
-storage fallback. Tool calls remain structural data until application-owned
-policy and code decide whether to execute them. App prompts, model defaults,
-profiles, tools, business policy, and private data remain app-owned.
-
-An explicitly selected but unloaded model is not “ready.” `chat.html` keeps
-Send disabled and exposes a visible keyboard-operable LLM Start/Try again or
-Cancel loading control. `speech.html` and `voice-transcription.html` keep their
-recording operations unavailable and share the equivalent Start
-transcription/Try again/Cancel loading control for STT. Applications can
-override `requestAIActivation(intent)` or `requestSTTActivation(intent)`, or
-cancel the corresponding activation-request event. Imports and state
-observation emit no lifecycle intent, and default
-`startTranscription=false` does not request an STT startup load or begin an
-automatic model download. It does not unload a role started independently.
-Compatibility availability never creates ready STT/TTS state without an
-admitted, loaded provider. Shared STT cancel/destroy propagates an owned signal,
-and TTS Mute/Unmute updates the shared lifecycle owner. The selected TTS
-provider/model catalog owns its default voice; a saved OpenAI voice is not
-forwarded to another provider route.
-
-## Authority and feature detection
-
-The presence of a JavaScript function is not permission to use it. Native
-applications should inspect `Arcane.capabilities.list()` where available and
-then call the relevant status method. Android callers with `system.read` obtain
-the nested capability snapshot through `Arcane.platform.status()`.
-
-Do not infer local-AI readiness from `Arcane.runtime.current().managedLocalAI`,
-infer authorization from a transport name, or treat an Ollama model inventory
-as package admission. Each method rechecks native policy at invocation time.
-
-## Source, receipts, and licensing
-
-- [Exact SDK runtime release manifest](../../runtime/ARCANE_RUNTIME_RELEASE.json)
-- [SDK runtime authority record](../../tools/runtime-source.json)
-- [Exact browser AI runtime receipt](../../browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json)
-- [AGPL license](../../LICENSE)
-- [Commercial-license notice](../../COMMERCIAL-LICENSE.md)
-- [Third-party and distribution notice](../../NOTICE)