arcane-os 0.5.9 → 0.5.11

package/docs/roadmap.md

@@ -0,0 +1,79 @@
+# Development roadmap
+
+The SDK contract keeps target names and operations stable while each current
+development provider gathers its remaining promotion evidence. Each item below
+is small enough to become a GitHub issue without combining every platform into
+one unbounded build.
+
+## Publication prerequisites
+
+- Mark the Arcane OS monorepo root package private or give it an internal-only
+  package name before the first `arcane-os` publication.
+- Decide and document the license that permits proprietary applications to
+  bundle the synchronized Arcane runtime.
+- Publish one fresh, never-reused prerelease candidate under only the npm `dev`
+  tag, verify the tarball and
+  provenance, add a second appropriate npm owner, and configure the exact
+  trusted-publisher workflow.
+
+## App admission and native extraction
+
+- Keep the implemented process-local `arcane-native-build-plan/1` and
+  `arcane-native-builder/1` lifecycle as the single provider seam for the CLI,
+  GUI, CI, and Codex. Portable, Windows x64, Linux x64, Linux ARM64, and Android
+  ARM64 pair only through an explicit compatible Arcane root and a matching
+  canonical scaffold descriptor.
+- Migrate built-in apps from the implemented schema-2 `arcane-app.json`
+  descriptor fallback to authored descriptors without changing exact v1 release
+  or native-host artifacts.
+- Update Arcane's exact-key consumers to project the new descriptor into the
+  current catalog while preserving v1 app-release admission during migration.
+- Preserve the implemented portable, Windows x64, Linux x64, Linux ARM64, and
+  Android ARM64 providers as one selected app plus its exact declared dependency
+  closure. Add new providers without weakening that release-reader boundary.
+- Extend the implemented same-process retained receipt lifecycle through an
+  authenticated Arcane host broker only when persistent cross-process reuse or
+  restartable app-scoped Core sessions are required.
+- Preserve exact packaged-artifact authority across browser and native plan,
+  verify, and run boundaries; never regress to treating a mutable path or
+  manifest file as a reusable receipt.
+- Add a manifest-declared origin policy for native enforcement and an optional
+  policy-faithful development mode. The current capability-gated loopback host
+  deliberately uses a broad development-only policy so the shared runtime can
+  exercise remote providers, media, WebSockets, and embeds.
+
+## Platform adapters
+
+- `portable`: keep the available verified app-scoped Core directory reproducible
+  from an external packed-SDK install and an explicit compatible Arcane checkout;
+  do not present it as an executable or direct-run target.
+- `windows-x64`: keep the implemented retained toolchain broker, EXE bundle,
+  authenticated host-readiness signal, and owned same-process cancellation
+  reproducible. Production signing and installation remain separate work.
+- `linux-x64`: keep the implemented single-app WebKitGTK host, verified amd64
+  DEB, user-owned extraction, and same-process cancellation reproducible. Add
+  AppImage and RPM only as distinct later format requests.
+- `linux-arm64`: keep the implemented unsigned-local-test ARM64 DEB provider,
+  focused provider tests, and exact-SHA native build/verification/readiness/
+  cancellation workflow reproducible on a compatible native ARM64 toolchain.
+  Keep AppImage, RPM, and production signing as separate future requests.
+- `android-arm64`: keep the implemented single-app, development-signed APK path
+  and exact-SHA physical/native ARM64 build/readiness/cleanup evidence
+  reproducible. The APK contains no native ABI and is architecture-neutral. Add
+  AAB, release signing, store publishing, and update continuity only as explicit
+  later promotion work.
+
+## Developer experience
+
+- Keep the integrated shared/Core profile explicit through `--scope shared`:
+  one exact repository-relative focused test or Arcane's one canonical
+  development check, never app discovery or an arbitrary package-script loop.
+- Add the Arcane Developer control panel as a client of the same operation API;
+  it stores local repository paths per user and never becomes a second builder.
+- Add authenticated GitHub artifact admission so Arcane OS installs verified
+  releases without cloning proprietary source.
+- Preserve the implemented integrated app-scoped native path: `--workspace` and
+  `--arcane-root` identify the same checkout, one app and one target are
+  selected, and `--output-root` remains outside the checkout. Future GUI clients
+  must use that path rather than introducing a second builder or an implicit
+  all-target build.

package/docs/work-amplification.md

@@ -0,0 +1,66 @@
+# Work-amplification review
+
+The default cardinality is:
+
+```text
+1 workspace x 1 app x 1 command x 1 target x 1 architecture x 1 format x 1 signing profile
+```
+
+There is no implicit all-app, all-target, or Android-flavor loop.
+Selecting `android-arm64` produces exactly one architecture-neutral APK with no
+native ABI fan-out. It does not build one artifact per ABI, an AAB, a release
+signing variant, or a publication/update artifact. Every native invocation also
+selects one explicit compatible `--arcane-root` and one app descriptor that
+already declares that target; a target list never causes provider discovery or
+additional builds.
+
+The SDK repository test cardinality is:
+
+```text
+1 repository x 4 named sets x each assigned test file exactly once
+```
+
+Unit, functional, integration, and regression scripts form one validated,
+non-overlapping inventory. The complete command adds three lightweight set
+coordinator launches compared with the former single discovery pass, but it
+does not repeat a test file, assertion, package installation, provider scan,
+build, or fixture. Smaller nested `vanilla-test` cases reuse their parent
+file's already-owned setup and cleanup boundary.
+
+Shared/Core development has a separate integrated-only cardinality:
+
+```text
+1 integrated workspace x 1 fixed provider generation x 1 operation x 1 owned process tree
+```
+
+The focused-test operation selects exactly one repository-relative
+`.test.mjs`; the development-check operation selects only Arcane's canonical
+check. The provider and package manifest are each read once for the process
+generation, and preparation launches one owned process tree. A focused fixture
+completed in about 0.14 seconds on the development laptop; the canonical check
+owns its nested npm/test process tree and performs the complete explicitly
+selected check. Tests and checks run only when the user explicitly
+selects them. Within one SDK process, one checkout admits only one
+such process tree at a time, so concurrent requests fail busy instead of
+multiplying that operation. Shared scope has no app, package, target, architecture,
+format, or signing loop and does not produce app output.
+
+## Cold-path shape
+
+- Scaffold writes the selected template files once before any separately
+  authorized dependency installation.
+- Shared browser packaging copies the complete SDK runtime, browser runtime,
+  and licensing content once for the selected app.
+- Portable build selects one app and one host platform request.
+- A bundled-app closure reuses one shared runtime selection rather than reading
+  it again for every app; each app still writes its own complete output once.
+- Windows, Linux, and Android each prepare one selected toolchain and produce
+  one requested development artifact. They do not fan out across undeclared
+  architectures, formats, or signing profiles.
+
+Invariant work includes SDK/runtime resolution and each selected provider
+generation, performed once per prepared toolchain state. App source discovery
+and release inventory occur once per selected app state. Portable assembly,
+Windows/Linux compilation, and Android APK assembly and development signing
+occur once per requested target. Complete file traversal is streamed without
+truncation, byte-count gates, byte identities, or hash-based admission.

package/examples/wasm-ai-demo/README.md

@@ -0,0 +1,80 @@
+# Arcane SDK WASM voice chat
+
+This is a source example inside the canonical Arcane SDK repository. It consumes this checkout's live `/src`, `/browser-runtime`, and `/runtime` trees. It contains no copied SDK modules, generated runtime projection, Ollama integration, or separate local AI service.
+
+For the smallest first request, start with the [browser speech quick start](../../docs/reference/ai/browser-speech.md) or [TWiN Cloud quick start](../../docs/reference/ai/twin-cloud.md). This example adds the shared Chat/Speech components, local LLM selection, persistence, and retrieval to those public APIs.
+
+## Speech defaults and inspection
+
+The demo deliberately omits `tts.execution` in `speechConfiguration(dbopfs)` so it consumes the SDK default `{device:'auto',maxConcurrentRequests:4}`. Change that application's TTS record to `execution:{device:'wasm',maxConcurrentRequests:1}` to use less memory, or choose `webgpu` explicitly. Allowed capacities are 1 through 4; Whisper and the LLM retain capacity one.
+
+Capacity 4 means up to four segments synthesize at once. Segment 5 and later wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of order, but playback waits for earlier segments and plays exact input order. Each slot owns a Worker/model session, so raising capacity trades memory for latency.
+
+Use the shared Speech component to load/unmute speech, then select **Inspect speech execution** below Chat. The button reads `ai.providerRuntime.status('tts',{execution:true}).execution` and displays requested device, selected device, capacity, active requests, and automatic WASM fallback. It is a snapshot at the moment clicked. `selectedDevice:null` means no pool is selected; `webgpu` reports the upstream execution-provider selection and does not prove physical GPU kernel overlap or audio quality. Auto may fall back to WASM with the same selected model/dtype; explicit WebGPU reports an error when it cannot load.
+
+Shared Speech still owns mute, stop, and voice controls. The example's status button inspects the public report without loading a model or reaching into private providers.
+
+## Ownership
+
+The Arcane SDK owns the shared behavior:
+
+- `<html-import>` mounts `/runtime/arcane/components/chat.html`.
+- Chat owns transcript rendering, persistence, submission state, cancellation, activation progress, and its composer.
+- Chat renders AI messages on the left and user messages on the right.
+- The nested SDK Speech component owns Talk, Stop, voice selection, mute state, and speech status.
+- `AI`, the browser-WASM provider, and DBOPFS own model loading and model persistence.
+- `ModelDefinition` owns loading and parsing the complete profile Modelfile prompt.
+- Chat creates and binds the SDK's `PersistentAIChatSession`, which owns local conversation persistence.
+- `DBOPFSDocumentLibrary` owns the profile-specific local document corpus, lexical retrieval, and complete request-context construction.
+- `PreferenceStore` owns model and profile selection persistence.
+- `startSourceExampleServer` owns live-source mounts, complete file streaming, model Range transport, TLS, and the browser-WASM isolation headers.
+
+The example owns its branded outer shell, model/profile catalog, General, PreCrisis, and BOSS prompt policy, maintained BOSS demo catalog, local-document controls, and profile-specific tool declarations. Its BOSS retrieval policy wraps the complete context returned by `DBOPFSDocumentLibrary.buildContext()`; it does not serialize document records itself. SDK Chat displays structural tool calls; the example records them through Chat's public tool-result method with the explicit `not-executed` disposition so the persisted conversation can continue without pretending an action ran. Every declared tool requires a nonempty user-facing `message`, matching the browser-WASM provider contract.
+
+Chat uses `PersistentAIChatSession`'s SDK-owned streaming seam, which composes live AI deltas with cancellation and one durable persisted turn. SDK Chat also owns the structural tool-call records and their visible disposition.
+
+## Local model assets
+
+Model weights are deliberately excluded from Git. Place the maintained GGUF shards in `examples/wasm-ai-demo/models/`, or set `ARCANE_WASM_MODEL_ROOT` to an existing local model directory before starting the server.
+
+The maintained model descriptors include each shard's known byte length as progress metadata. During a cold install, the SDK reports aggregate loaded and remaining bytes, transfer speed, estimated time, and active file or Range transfers while Chat presents the existing activation progress bar. Completed shards and completed Range parts within a shard remain available after interruption, so retry downloads only missing work.
+
+The app gives the SDK browser-speech owner the existing Whisper tiny.en FP32 and Kokoro 82M Q8 descriptors. The app does not import those runtimes or create a speech worker itself.
+
+## Local retrieval
+
+BOSS seeds the example's maintained document catalog through the SDK's `DBOPFSDocumentLibrary`. The Local knowledge control accepts user-selected text documents and merges them into the selected profile's SDK-owned document corpus. Retrieval remains isolated by profile, and every matching document is supplied in full to the current request.
+
+General uses the selected model's local-browser identity prompt. PreCrisis loads `profiles/PreCrisis.Modelfile`; BOSS loads `profiles/BOSS.Modelfile` and the maintained `rag/boss-library.json` catalog. Those are consumer-owned inputs to the SDK rather than alternate Chat, persistence, speech, or model implementations.
+
+## Run from this checkout
+
+From the canonical SDK repository root:
+
+    node .\examples\wasm-ai-demo\server.mjs
+
+The npm package includes this same maintained source. From an application with
+the exact SDK installed, run:
+
+    node ./node_modules/arcane-os/examples/wasm-ai-demo/server.mjs
+
+For the installed copy, set `ARCANE_WASM_MODEL_ROOT` to your existing model
+directory; do not store model downloads inside `node_modules`. The installed
+server resolves `/src`, `/browser-runtime`, and `/runtime` inside its selected
+SDK package. It does not require an SDK or Arcane OS source checkout.
+
+Use this repository-root command rather than a generic Live Server extension. A server rooted at the example directory cannot expose the SDK checkout's live source routes.
+
+Then open:
+
+    http://localhost:4173/examples/wasm-ai-demo/
+
+The example's thin server entry imports `startSourceExampleServer` from the SDK's public `arcane-os` root export and supplies only its paths and assets; the SDK owns serving the current checkout's direct `/src`, `/browser-runtime`, and `/runtime` paths. Open the exact URL it prints at startup. HTTP is the default; when local certificate files are present in `examples/wasm-ai-demo/tls/`, the printed URL uses HTTPS instead. To reuse an existing local certificate directory without copying it into Git, set `ARCANE_WASM_TLS_ROOT` before starting the server.
+
+For example, a local launch can point at preserved prototype assets without making them source authority:
+
+    $env:ARCANE_WASM_MODEL_ROOT = "C:\path\to\existing\models"
+    $env:ARCANE_WASM_TLS_ROOT = "C:\path\to\existing\tls"
+    node .\examples\wasm-ai-demo\server.mjs
+
+Model weights, browser profiles, caches, generated evidence, runtime reproductions, and TLS private keys remain outside the maintained example. The preserved standalone prototype is not edited or used as runtime authority.