arcane-os 0.5.9 → 0.5.11

package/docs/platform-targets.md

@@ -0,0 +1,104 @@
+# Platform target contract
+
+Every target adapter implements protocol `arcane-target-adapter/1` with these
+named operations:
+
+```text
+describe -> doctor -> prepare -> plan -> build -> 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 selects an app release and schema-2 descriptor,
+toolchain, platform, architecture, format, signing mode, declared dependency
+releases, and destination. Verification is a separate operation only when the
+user explicitly selects it for the release artifact.
+
+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 the current native platform. 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 diagnostic. The normal build recipe omits
+it and lets `build` prepare the selected toolchain state.
+
+The portable output is an 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 compatibility and breaking-change rule.
+
+| Target | Formats | Development status |
+|---|---|---|
+| `browser` | `directory` | Available |
+| `portable` | `portable` directory | Available with explicit `--arcane-root`; 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 selected app release and its complete bundled
+dependency closure through the provider boundary. The providers retain the
+toolchain state required for build 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 recorded target-scoped workflow built a
+native ARM64 DEB, exercised the AArch64 host/Core/bridge, 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 recorded development path exercised physical
+ARM64 build, readiness, cancellation, uninstall, and absence behavior. 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

@@ -0,0 +1,126 @@
+# 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.
+
+Publication checks run only after the user explicitly selects an npm release.
+That selected-release workflow validates package metadata, the executable and
+`.gitattributes` boundary, the complete package inventory, version/channel
+agreement, and required license notices. One unprivileged producer packs one
+`.tgz` under the selected Node and npm versions and uploads it as one Actions
+artifact with a recorded run id, artifact id, version, and source commit. It
+does not impose byte counts, hashes, digests, provenance receipts, or unrelated
+test suites as ordinary development gates. Broader integration, regression,
+platform, browser, presentation, and documentation work remains separately
+user selected.
+
+`publish-dev.yml` can run only when manually dispatched from `main` in
+`TheWizardNexus/arcane-os-sdk`. Dispatch supplies the exact successful Check
+run id, artifact id, and numeric version. The workflow downloads that exact Check
+artifact, derives `dev` or `latest` from its version, and publishes the selected
+`.tgz`. It may check out current source only for the publication controller; it
+never repacks current source and 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 tag rollback, malformed registry state, or any
+dist-tag other than `dev` and `latest`; an already-published matching version
+is an idempotent success. Post-publication status preserves the other channel
+and reports npm's response. It tolerates npm's publish-time scanning. If
+scanning or manual review remains pending, the workflow reports that state and
+a rerun safely resumes without republishing the version.
+
+The public `0.3.2` release is fixed to package-source commit
+`445bd2d982f12e6ef8dd2b615c70512000cc5224`, selected Check run
+`33264677687`, and publication/registry run `33264829711`. Its numeric Git tag
+and GitHub release title are both `0.3.2`. Later documentation or example
+commits do not replace that package authority.
+
+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` uses that declared package.
+Arcane reads the installed package's name and version against the root
+dependency declaration. A local directory `file:` install is intentionally unsupported because
+it may be linked.
+
+The npm package already has its trusted-publishing relationship. Each later
+release therefore follows the same direct selected-artifact path: push the
+intended `main` source, manually run Check for that exact revision, review the
+resulting package inventory and legal notices, then manually dispatch
+publication with that Check run and artifact. Confirm the selected version and
+dist-tag after publication. Never rebuild or repack the artifact under
+publication authority, and never substitute a different source revision.
+
+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
+
+The checked-in reusable workflow is not an ordinary supported release path
+until its implementation matches the governing contract below.
+
+External app repositories can call `.github/workflows/release-app.yml` from a
+selected SDK repository revision. The reusable workflow checks out the selected
+caller commit, installs only the caller's committed dependency lock, packages,
+bundles, and uploads one explicitly selected app. Any tests, checks, or artifact
+verification run only because that release output was explicitly selected.
+The workflow never publishes npm, creates a GitHub Release, loops across apps,
+or changes Arcane runtime policy.
+
+The one build job holds only `contents: read`. It uses the caller's normal
+locked installation, runs one selected `arcane package`, creates one selected
+`arcane bundle`, and uploads that complete bundle. It creates no hashes, byte
+identities, receipts, provenance records, or attestation sidecars and does not
+run a second admission job.
+
+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 exact selected Check artifact under `latest`; GitHub may then
+attach that same package. 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
+
+Documentation publication occurs only when the user explicitly selects it. The
+Pages job checks out that selected `main` revision without persistent
+credentials and uploads only the static `site/` tree. It does not automatically
+run the SDK test suite, checks, generators, or repository build code.
+
+The deployment job holds only the read, Pages, and OIDC permissions required by
+that selected 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 selected `main` revision and one npm release candidate.
+One producer creates the tarball. Publication names that producer's exact Check
+run, artifact, and version and does not rebuild from a later checkout. The
+release workflow checks only the publication contract and required legal
+inventory for that selected output.
+Platform matrices, full product regressions, Pages, and broader presentation
+work remain separate user-selected operations.

package/docs/reference/README.md

@@ -0,0 +1,206 @@
+# 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.
+
+## Start with one working request
+
+Install the SDK in your application:
+
+```sh
+npm install --save-exact arcane-os@0.5.11
+```
+
+For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
+For on-device speech, follow the [browser speech quick start](ai/browser-speech.md)
+and the complete [browser AI demo](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
+Each guide names the application configuration you supply and shows the public
+call, response, cancellation, and error handling. Browser module imports use
+the SDK's [materialized import map](cli.md#arcane-import-map); installing npm
+alone does not make bare module names resolve in a browser.
+
+## Reference map
+
+| Need | Start here |
+| --- | --- |
+| Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
+| Publish central events, capture complete 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 selected 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-selected local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
+| Run caller-selected Whisper or Kokoro in the browser | [Browser speech providers](ai/browser-speech.md) |
+| Send one TWiN Cloud request or migrate saved LLM preferences | [TWiN Cloud quick start](ai/twin-cloud.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 source ownership
+
+This repository contains explicitly versioned surfaces with different owners:
+
+| Surface | Source identity | Meaning |
+| --- | --- | --- |
+| SDK and CLI | `arcane-os` `0.5.11` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and `arcane-os/speech-playback` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
+| Browser runtime | SDK `0.5.11`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| Browser SDK runtime | SDK `0.5.11`, `browser-runtime/` | The browser closure for events, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract imported into `docs/reference/core/`, with SDK-local links and package-boundary notes added explicitly. |
+
+The SDK runtime source and Core reference have different owners. A browser
+module comes from the selected SDK runtime tree. A native build selects one
+explicit Arcane OS checkout and Core, then checks the declared protocol,
+version, features, capabilities, methods, and provider contract needed by that
+build. A matching protocol name or higher version alone does not promise
+functional compatibility.
+
+See the [Core reference source notes](core/README.md) for the imported inventory
+and the distinction between a documentation snapshot and the selected runtime.
+
+## Installed documentation and release identity
+
+This reference accompanies `arcane-os@0.5.11`. The installed package includes
+the maintained `docs/` tree and `examples/wasm-ai-demo/` source alongside
+README and CHANGELOG. Open `node_modules/arcane-os/docs/reference/README.md`
+for the matching local reference. The generated website and test suites remain
+repository surfaces.
+
+Read the installed version and current registry channel separately:
+
+```sh
+npm list arcane-os
+npm view arcane-os@latest version
+```
+
+The [changelog](../../CHANGELOG.md) records changes by version; the
+[GitHub releases](https://github.com/TheWizardNexus/arcane-os-sdk/releases)
+identify the corresponding published package source. A newer website does not
+change the version installed in your application.
+
+### Historical 0.3.4 publication record
+
+The following records describe that earlier release only. They do not identify
+the current registry channel or the package covered by this reference.
+
+| Release boundary | Exact value |
+| --- | --- |
+| npm package | `arcane-os@0.3.4` |
+| Package source | `9e657b31f758a2c7943446533fe87afda206ac49` |
+| GitHub release | [`0.3.4`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.3.4) (tag and title are both exactly `0.3.4`) |
+| Selected package run | [Check run 33268940871](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33268940871) |
+| Selected publication run | [Publish run 33268987444](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33268987444) |
+
+## 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 204 semantic JavaScript records across 16 JavaScript
+entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are
+Node.js control-plane surfaces,
+`arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and
+`arcane-os/speech-playback` 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:
+
+- 82 JavaScript module artifacts under `runtime/arcane/modules/`, including
+  ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
+  mail transport;
+- 14 shared entity modules under `runtime/arcane/entities/`;
+- 39 reusable HTML-import components under `runtime/arcane/components/`;
+- seven shared CSS artifacts, images, optional physical-workspace security
+  files where present, 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 selected runtime directories
+and their current source inventories remain authoritative; the catalogs explain
+what those artifacts 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 availability, 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 runtime and model sources; Kokoro supports bounded Worker/session concurrency with automatic WebGPU-first execution and complete WASM-pool fallback. |
+| 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.
+Reported 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 local TTS
+provider/model catalog owns its default voice; a saved OpenAI-route voice is not
+forwarded to Core or browser speech.
+
+## 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 and licensing
+
+- [SDK runtime source](../../runtime/arcane)
+- [AGPL license](../../LICENSE)
+- [Commercial-license notice](../../COMMERCIAL-LICENSE.md)
+- [Third-party and distribution notice](../../NOTICE)