arcane-os 0.5.10 → 0.5.12

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.12
+
+- Add optional `voice`, `speed`, `pauseAfterMs`, and `waitForPlayback` fields to
+  `AI.streamTTS(text, end, options)`. Complete passages can enter the existing
+  segmented generation queue immediately, retain their authored pauses on the
+  audio clock, and await their own playback completion. Existing calls still
+  return after preparation; stop and terminal failure settle playback waits
+  as `false`, while autoplay permission waiting remains pending.
+- Restore `AI.fetch(...)` and `AI.streamMessage(...)` after their unintended
+  removal during source cleanup. Their existing signatures, callbacks, return
+  behavior, and private inference plumbing remain available alongside
+  `fetchRequest({...})` and `streamRequest({...})`; callers do not need to
+  migrate. Restore chat-memory callers and document both public forms as
+  sharing the current provider implementations.
+- Update maintained SDK references and their generated pages, omit obsolete
+  provider context-token guidance, and describe current native defaults and
+  Winlogon bindings without treating them
+  as retired SDK APIs. Native Core implementations and upstream dependencies
+  are not changed by this SDK cleanup.
+
+## 0.5.11
+
+- Default browser Kokoro TTS to four concurrent synthesis slots in both the
+  high-level AI configuration and direct provider. Explicit capacities 1–4
+  remain supported; LLM and Whisper/STT capacity remains one. Overflow waits
+  in the provider-neutral FIFO queue, and playback retains exact input order
+  with contiguous AudioContext scheduling. Each slot owns a Worker/model
+  session, trading memory for latency without promising physical GPU overlap.
+- Add opt-in live execution details through
+  `ai.providerRuntime.status('tts', {execution: true}).execution`, including
+  requested and selected device, capacity, and active requests. Existing
+  no-option status snapshots keep their behavior; automatic WASM fallback is
+  observable without private provider access.
+- Front-load basic browser speech and TWiN examples, document exact saved
+  preference migration, refresh current reference inventories and generated
+  site content, and include maintained `docs/` and the browser AI demo source
+  in the installed package. Documentation deployment now uses an explicit
+  selected-main Pages workflow.
+
 ## 0.5.10
 
 - Show one Windows performance-GPU flag advisory for the current Chromium

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.5.10` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.12` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -29,16 +29,99 @@ The app repository's exact dependency and lockfile select the SDK; changing that
 selection is an explicit repository update. Tests and checks run only when the
 user expressly selects them, or when required for a selected release output.
 
+## Beginner quick start
+
+Create one browser application, install its pinned SDK, and start its source
+server:
+
+```bash
+npx arcane-os@0.5.12 new hello-speech --path ./hello-speech --target browser
+cd hello-speech
+npm install
+npm run dev
+```
+
+Open the URL printed by the server. The generated page owns its import map and
+Arcane theme; its application module is `apps/hello-speech/modules/App.js`.
+`arcane/AI` is a managed **browser import**, not an npm-exported Node inference
+module.
+
+For a first spoken sentence, copy the application-owned
+[`speech-selection.js` configuration from the speech quick start](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/browser-speech.md#quick-start-say-one-sentence)
+beside `App.js`, then use this module. That one configuration file defines the
+upstream runtime, model, dtype, and voice. This module creates the application's
+DBOPFS store; the SDK creates and manages its speech providers and Workers.
+
+```javascript
+import arcaneThemeReady from 'arcane/ThemeBootstrap';
+import AI, { AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL } from 'arcane/AI';
+import DBOPFS from 'arcane/DBOPFS';
+import { speechSelection } from './speech-selection.js';
+
+await arcaneThemeReady;
+const dbopfs = new DBOPFS();
+await dbopfs.readyPromise;
+const ai = new AI();
+await ai.configureBrowserSpeech({
+  protocol: AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL,
+  id: 'hello-speech',
+  dbopfs,
+  tts: {
+    providerId: 'hello-kokoro',
+    model: speechSelection.model,
+    runtime: speechSelection.runtime,
+    offline: false
+  }
+});
+
+const button = document.createElement('button');
+button.textContent = 'Load voice and say hello';
+document.body.append(button);
+button.addEventListener('click', async function sayHello() {
+  button.disabled = true;
+  try {
+    await ai.setSpeechMuted(false);
+    console.log(ai.providerRuntime.status('tts', { execution: true }).execution);
+    const prepared = await ai.streamTTS('Hello from Arcane. ', true);
+    console.log('Speech preparation completed:', prepared);
+  } catch (error) {
+    console.error(error.code, error.message);
+  } finally {
+    button.disabled = false;
+  }
+});
+```
+
+The button explicitly loads/unmutes the selected model and requests speech.
+The first load can download the app-selected runtime/model/voice; the browser
+may need another audio-unlock gesture after a long load. Keep the complete
+visual response available alongside speech.
+
+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.
+
+Continue with [streaming chunks, device selection, cancellation, status, and cleanup](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/browser-speech.md),
+the [tiny TWiN Cloud request and saved-preference migration](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/twin-cloud.md),
+or the [maintained WASM voice-chat example](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
+The installed package also includes `docs/` and the maintained example source:
+open `node_modules/arcane-os/docs/reference/ai/browser-speech.md`,
+`node_modules/arcane-os/docs/reference/ai/twin-cloud.md`, or
+`node_modules/arcane-os/examples/wasm-ai-demo/README.md` locally. Public links
+above work from both npm and GitHub.
+
 ## Developer API reference
 
-Start with the [capability-first developer reference](docs/reference/README.md).
+Start with the [capability-first developer reference](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/README.md).
 It follows Arcane's MDN-style model and covers every public package export, CLI
 command, synchronized runtime module, entity, component, Arcane Core member,
-and Arcane Ollama method. Use the [availability and normalization matrix](docs/reference/availability-and-normalization.md)
+and Arcane Ollama method. Use the [availability and normalization matrix](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/availability-and-normalization.md)
 to distinguish Node, browser, native, cloud, and cross-host behavior; protocol
-mechanics are kept in the folded/deep-linked [protocol guide](docs/reference/protocols.md).
-The [behavioral-testing guide](docs/reference/behavioral-testing.md) explains the
-executable contract, while the [machine-readable inventories](docs/reference/inventory/)
+mechanics are kept in the folded/deep-linked [protocol guide](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/protocols.md).
+The [behavioral-testing guide](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/behavioral-testing.md) explains the
+executable contract, while the [machine-readable inventories](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/docs/reference/inventory/)
 make completeness independently checkable.
 
 ## Central event instrumentation
@@ -54,7 +137,7 @@ off-by-default diagnostic option.
 
 Recording is off by default. Once explicitly enabled, a session retains its
 complete recorded content until the caller clears it or disables recording.
-Review [the EventManager guide](docs/event-manager.md)
+Review [the EventManager guide](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/event-manager.md)
 before enabling DOM values, node content, event details, source stacks, or live
 event redispatch. Password targets, text-entry details, clipboard data, URL
 attributes, and common credential keys are excluded or redacted by default.
@@ -90,10 +173,18 @@ Kokoro (`LOCAL_SPEACH` / `kokoro`) owns speech synthesis. Neither audio route
 uses the TWiN key, and neither requires a cloud audio key.
 
 The built-in provider and default-model preference sentinel are both `TWIN`.
-Applications upgrading saved `OPENAI` LLM selections must explicitly update
-those app-owned settings to `TWIN`. The SDK provides no built-in `OPENAI` alias
-and does not rewrite saved preferences. Actual upstream model identifiers remain
-unchanged.
+Applications upgrading saved preference tuples must replace only uppercase
+`OPENAI` in slot 0 (LLM provider) and slot 3 (default-model sentinel) with
+`TWIN` through the existing application preference owner before importing
+`AI.js` or any module that imports it, and before AI preference hydration.
+Use dynamic import after migration; module evaluation can instantiate AI
+immediately when the user is already ready. Keep every other
+value unchanged, including `openai-gpt-oss-120b` and `openai-gpt-oss-20b`.
+The SDK provides no built-in `OPENAI` alias and does not rewrite saved
+preferences. OpenAI-compatible wire terminology and the separate Core
+`provider:'openai'` contract are unchanged. The
+[TWiN quick start and migration recipe](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/twin-cloud.md)
+show the exact application-owned operation.
 
 `fetchRequest()` and `streamRequest()` accept the provider-neutral
 `reasoningEffort` option with `none`, `low`, `medium`, `high`, or `max`. TWiN
@@ -110,6 +201,8 @@ profile. Each descriptor uses one ordered `files` array, so monolithic and
 split GGUF models share the same contract:
 
 ```js
+import { createBrowserModelSource } from 'arcane-os/ai/browser-wasm';
+
 const source=createBrowserModelSource({
     id:'app-model',
     files:[
@@ -157,7 +250,7 @@ provider factories. The package contains the plain-JavaScript provider and
 Worker machinery, not speech runtimes, models, voices, or a CDN default. An app
 must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
-silently falls back or prevents text chat. Kokoro defaults to a two-slot Worker
+silently falls back or prevents text chat. Kokoro defaults to a four-slot Worker
 and model-session pool: it selects WebGPU when the browser can load the complete
 pool and otherwise recreates that pool on WASM. Apps may select `webgpu` or
 `wasm` explicitly and may set the bounded TTS capacity from one through four.
@@ -204,10 +297,9 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.5.10 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.12 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
-npm run check
 npm run dev
 ```
 
@@ -215,7 +307,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.5.10
+npm install --save-dev --save-exact arcane-os@0.5.12
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -231,7 +323,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.5.10` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.12` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -246,14 +338,12 @@ tarball install in the app's package manifest and lock:
 ```bash
 # From the arcane-os-sdk checkout
 npm ci
-npm run check
 npm run pack:local
 node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.10.tgz
-npm run check
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.12.tgz
 npm ci
 ```
 
@@ -262,7 +352,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.5.10` registry package and
+the local declaration with the exact `arcane-os@0.5.12` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -393,14 +483,15 @@ npm run test:integration
 npm run test:regression
 ```
 
-Use a named set while iterating or `npm test` for the complete suite. Large
+Run a named set or `npm test` only when explicitly selecting that verification,
+or when required for a selected release output. Large
 fixtures stay inside one isolated file process and expose smaller nested cases,
 so the report shows the individual behaviors without repeating setup, builds,
 package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.10` exposes one browser target and five explicitly paired
+Version `0.5.12` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The
@@ -502,11 +593,11 @@ artifact. Portable output is never represented as an executable, and unsigned
 or development-signed evidence is never represented as production signing or
 release acceptance.
 
-See [docs/platform-targets.md](docs/platform-targets.md) for the matrix and
-[docs/architecture.md](docs/architecture.md) for the boundary. The exact
+See [docs/platform-targets.md](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/platform-targets.md) for the matrix and
+[docs/architecture.md](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/architecture.md) for the boundary. The exact
 minimum-version and required-contract compatibility rule is documented in
-[docs/compatibility.md](docs/compatibility.md). The issue-ready
-extraction sequence is tracked in [docs/roadmap.md](docs/roadmap.md).
+[docs/compatibility.md](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/compatibility.md). The issue-ready
+extraction sequence is tracked in [docs/roadmap.md](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/roadmap.md).
 
 ## Canonical app descriptor
 

package/browser-runtime/ai/browser-speech-providers.mjs

@@ -21,7 +21,7 @@ const TTS_SAMPLE_RATE = 24_000;
 const TTS_RESPONSE_FORMAT = "wav";
 const TTS_EXECUTION_DEVICES = new Set(["auto", "webgpu", "wasm"]);
 const DEFAULT_TTS_EXECUTION_DEVICE = "auto";
-const DEFAULT_TTS_MAX_CONCURRENT_REQUESTS = 2;
+const DEFAULT_TTS_MAX_CONCURRENT_REQUESTS = 4;
 const MAX_TTS_CONCURRENT_REQUESTS = 4;
 const ROLE_REQUEST_REASON = completeValue({
   stt: "stt-transcription-cancelled",

package/docs/architecture.md

@@ -0,0 +1,303 @@
+# Architecture
+
+The CLI, future Arcane Developer graphical control panel, CI, and Codex all use
+one headless operation API. A client selects a named operation and consumes the
+same structured event stream; the GUI is not a second build system.
+
+```text
+external app repository -----+
+                              |
+Arcane OS consumer checkout --+-- CLI / future GUI / Codex / CI
+                                      |
+                               shared toolchain API
+                                      |
+                       browser package or explicit target adapter
+```
+
+## Canonical ownership and portability boundary
+
+The SDK repository is the canonical source for every mechanism that can be
+reused by a portable Arcane application. That includes shared modules,
+entities, components, themes, browser runtimes, providers, workers and assets;
+protocol, state, startup, readiness, progress, cancellation, unload and dispose
+machinery; public native contracts and adapters; the development source mount;
+and the packaging and license boundaries for that portable content. In
+particular, shared AI selected-role hydration, startup-settled state and events,
+role readiness, lifecycle and
+cancellation contracts, and the shared chat and speech components are
+SDK-owned source and contracts rather than Arcane OS–owned snapshots.
+
+Every portable application artifact materializes the complete SDK runtime,
+assets, workers, licenses and public contracts it uses. It remains self-contained whether it runs as plain
+HTML or inside an executable wrapper. It has no runtime dependency on an
+Arcane OS installation, source checkout or private Arcane OS import.
+
+Arcane OS is an SDK consumer like other applications. Its orchestrator,
+launcher, Shell, Provisioner, system AI application and internal tools use the
+same SDK modules and components rather than maintaining private runtime copies.
+Arcane OS and Core own the privileged host implementations, app/session
+admission and authorization, native transport and lifecycle, launcher and
+Shell orchestration, and system-AI policy specific to the Shell. The SDK may
+publish the capability-neutral Core bridge contract and adapters, but it does
+not embed Core or inherit another application's policy.
+
+Each application owns its branding, prompts, data, tools, business policy,
+model authorities and app-specific orchestration. Apply this decision order:
+
+| Responsibility | Canonical owner |
+|---|---|
+| Reusable by any portable application | Arcane SDK |
+| Host privilege, launcher, Shell or app/session admission | Arcane OS / Core |
+| Behavior unique to one product | That application |
+
+Do not copy a reusable implementation between the SDK, Arcane OS and an app,
+and do not create a hidden Arcane OS source dependency. Extend one neutral SDK
+contract and keep product policy in the consumer.
+
+Application and consumer tasks do not modify this repository's SDK source and
+do not hand-edit materialized `arcane/**` projections. They request a reusable
+change from an SDK source owner, or implement behavior that is specific to their
+product in that application's local source. Consumer projections change only
+through the selected public package and materializer.
+
+Development and distribution use different authority. The explicit
+`arcane dev --sdk-runtime-source <sdk-root>` development-only live source mount
+lets a refresh read the saved SDK source without copying it into the app.
+Distribution never follows that mount. It embeds the application's complete
+selected SDK projection.
+
+`runtime/arcane/` is the SDK-canonical source. Arcane OS must consume the
+selected SDK projection through the same package/source-mount boundary as
+other apps; its repository-side consumer cutover is coordinated separately and
+does not create a co-equal source. Git history records the completed ownership
+migration; the current tree has no OS-to-SDK synchronization path.
+
+## Workspace profiles
+
+An external workspace maps the exact runtime shipped by its locked `arcane-os`
+dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
+of portable runtime source. For live shared development, the explicit
+development-only SDK source mount maps the canonical SDK runtime and dependency
+paths into that consumer. Without the mount, the workspace uses its locked SDK
+projection. The development server and packager consume the same route
+destinations in both cases, so app imports do not change. Integrated
+initialization creates only app-owned files and never rewrites Arcane OS or SDK
+root configuration.
+
+The shared/Core development profile is a separate integrated-only scope selected
+with `--scope shared`. The SDK loads exactly
+`tools/integrated-development-provider.mjs` from the selected Arcane OS checkout
+as one process generation. This is a privileged host-development provider, not
+a source of portable SDK runtime content. That provider selects only one exact
+repository-relative focused `.test.mjs` through Arcane's canonical focused
+runner or Arcane's canonical development check. External workspaces cannot use
+the scope, and shared operations never enter app discovery, packaging, target
+planning, build, verification, or run paths. A generation change requires a new
+CLI process.
+Integrated app testing remains isolated to the selected `apps/<id>/test/`
+tree; it cannot recursively select Arcane root tests or another app's tests.
+External repositories retain their existing workspace-root plus selected-app
+test layout.
+
+## Development and release serving boundary
+
+Arcane applications keep one browser-first plain HTML, CSS, and JavaScript
+baseline. A native target runs that same application and progressively enhances
+it through capability-gated Arcane Core access. Browser operation must not
+depend on Core being present. A feature that genuinely requires Core reports
+its unavailability without breaking unrelated browser
+behavior or claiming that the capability exists.
+
+Rapid development uses `arcane dev`. The development server maps the selected
+application's canonical source tree and the live installed SDK/runtime routes.
+Each request reads and returns the complete current saved source, so a browser
+refresh shows source changes without packaging, copying
+files into `dist`, or restarting the server. Restarting is not a content
+synchronization step; when a refresh is stale, first verify the command, URL,
+workspace, selected app, and resolved source route.
+
+Development is an intentionally fast feedback loop. Keep each increment small
+and independently understandable so its effect has one clear cause and a
+mistake can be isolated without untangling unrelated work. A development
+operation does not implicitly run tests, checks, packaging, builds, or release
+verification. The developer invokes a focused test or check deliberately at an
+explicit checkpoint; merely refreshing source does not trigger one.
+
+Executable development uses an Arcane-owned native development wrapper around
+the same source-serving browser surface. The wrapper is an escalated browser,
+not a packaged application: it loads current source files and adds only the
+selected application's declared, capability-gated local Arcane Core access.
+It preserves the browser behavior when Core is absent, reports an unavailable
+native-only capability honestly, and never silently substitutes a release
+tree. Starting or refreshing this wrapper does not package, copy to `dist`, or
+run tests automatically. The SDK must not describe native source development as
+available until this wrapper and its explicit capability boundary are actually
+implemented.
+
+Packaging and release verification are separate explicit operations. Run
+`arcane package` to generate `dist/<id>`, then use
+`arcane run --target browser` to serve that selected release. Packaging does
+not automatically run tests or checks; those run only when the user expressly
+requests them or when required for a separately selected release output. The browser
+run command does not substitute source files. If source changes after
+packaging, the prior `dist` remains intentionally unchanged until the next
+explicit package operation. Never use packaged `dist` as the everyday
+development tree, and never treat source-serving behavior as evidence for the
+release artifact.
+
+## App and release contract
+
+The first SDK version deliberately preserves Arcane's current repository-shaped
+URLs and release schema:
+
+```text
+apps/<id>/arcane-app.json
+apps/<id>/arcane-package.json
+apps/<id>/index.html
+dist/<id>/ARCANE_APP_RELEASE.json
+```
+
+The authored schema-2 descriptor is canonical for new apps and projects an
+exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
+apps synthesize that descriptor from their schema-1 package plus the current
+native registry during migration.
+
+An external app's `arcane-packager.json` has three exact shared routes. They map
+the installed SDK runtime to `/arcane`, its vendored strong-type dependency to
+`/node_modules/strong-type`, and the SDK's `LICENSE`,
+`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. Development does
+not copy SDK runtime source into the app repository. Distribution materializes
+those selected SDK routes completely inside the portable artifact, so the
+finished app has no Arcane OS runtime dependency.
+
+Release schema 1 and builder identity `arcane-app-packager-v1` remain unchanged
+because current Arcane native consumers treat them as public contracts. Native
+builders consume the schema-2 descriptor as a separate build input while v1
+host artifacts remain unchanged.
+
+External repository delivery adds a distinct schema-1
+`arcane-app-release-bundle` envelope. Bundle creation uses an authored schema-2
+`arcane-app.json`; a synthesized package or registry projection remains valid for integrated
+packaging but is not used for an external bundle. The
+archive contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
+`payload/ARCANE_APP_RELEASE.json`, and the release inventory beneath `payload/`
+in that order. The envelope adds no repository-only source or build tooling
+beyond that selected release inventory. Individual apps remain responsible for
+their authored source policy.
+
+The bundle contract uses the documented USTAR+gzip structure. Explicit bundle
+verification parses the selected archive without extraction and rejects
+genuinely malformed structures, unsafe or colliding paths, unsupported members,
+trailing data, and incompatible bundle generations. These corrupt-artifact
+checks do not create byte-count, content-hash, provenance, or admission gates
+for ordinary development, packaging, serving, or running.
+
+Promotion preserves any prior output until the new archive is complete.
+Pre-commit failure restores that backup when doing so will not overwrite a
+concurrent change; otherwise the uncertain paths remain available for
+inspection. Ordinary results report the selected artifact and complete
+inventory without byte identities. The workflow creates no provenance,
+attestation, signing, or restrictive admission record.
+
+The governing reusable app-release contract uses one `contents: read` job to
+check out the selected caller revision, perform the caller's normal locked
+install, package and bundle one selected app, and upload that complete bundle.
+The checked-in workflow is unavailable until it matches this contract. The
+contract does not include a second verifier or privileged attestation job.
+
+## Operation ownership
+
+An invocation defaults to one workspace, one app, one command, one target, one
+architecture, one format, and one signing profile. It acknowledges before long
+work, uses one `AbortController`, supervises child processes, and routes progress
+through one serialized owned event queue. Process streams apply pause/resume
+backpressure and heartbeats coalesce. Callback failure cancels owned work, drains
+the queue, and reaches the caller or CLI exit status. Packaging preserves prior
+output until replacement is complete.
+
+Each normalized queue event is also mirrored exactly once through the shared
+`arcaneEvents` `EventManager`. That synchronous `event-pubsub` route is the
+canonical cross-cutting instrumentation surface, but it does not replace the
+owned asynchronous callback path or its backpressure. Time-travel history and
+DOM observation remain explicitly disabled unless a diagnostic session enables
+them. See [event-manager.md](event-manager.md) for the complete record, capture,
+DOM coverage, and effect-isolated playback boundaries.
+
+For `--scope shared`, the cardinality changes to one integrated workspace, one
+named operation, and either one exact test file or one development check. The
+same owned event queue and process supervisor provide acknowledgement, complete
+stream delivery with backpressure, heartbeat, cancellation, process-tree
+cleanup, and nonzero
+failure propagation. No app or target loop exists in that scope.
+
+## Complete-content ordinary path
+
+Packaging writes the complete schema-1 release inventory to
+`ARCANE_APP_RELEASE.json`. Ordinary development, packaging, serving, and run
+paths do not count, limit, hash, truncate, tail, clip, or identify content by
+bytes, and they do not require provenance or verification receipts. The
+loopback server reads and returns each complete selected source, runtime, or
+packaged file. Required credential protection, malformed-input rejection,
+applicable law, unavoidable protocol rules, and operating-system or browser
+safety remain in effect.
+
+## Native provider boundary
+
+The SDK implements protocol `arcane-native-build-plan/1` and the injected
+provider contract `arcane-native-builder/1`. Pairing is process-local; it never
+registers a mutable global provider or searches for a toolchain. For each
+supported native target, the CLI loads one fixed provider module from the
+explicit `--arcane-root` Arcane OS checkout. Provider code is bound to one
+process generation; if a pull changes loaded provider code, the caller starts a
+fresh worker. One paired toolchain can perform this lifecycle:
+
+```text
+doctor -> prepare -> plan -> build -> run
+```
+
+The portable provider reports honestly that run is unavailable because its
+result is a directory. Windows x64, Linux x64,
+Linux ARM64, and Android ARM64 implement same-process launch and owned
+cancellation when their compatible host/device requirements are present.
+Windows uses a retained per-build broker and host readiness. The
+Linux provider produces an amd64 or ARM64 DEB and runs a retained
+user-owned extraction without install or elevation. Portable, Windows, and
+Linux use the `unsigned-local-test` signing profile.
+
+The Android provider produces one development-signed APK. It contains no native
+library or ABI-specific payload, so the artifact is architecture-neutral; the
+`android-arm64` target instead binds the supported run path to one physical
+device with native ARM64 support. APK is the only Android format in this
+development provider. AAB, release signing, publishing, and update continuity
+remain outside it.
+
+The plan selects one explicit `toolchainRoot`, one app release root, its
+schema-2 descriptor, only its
+declared dependency releases, one non-overlapping output root, and one target,
+platform, architecture, format, and signing request. App source and workspace
+paths are withheld from the native provider. The provider copies the complete
+selected release rather than accepting an unrelated source path. Verification
+is a separate explicit operation for a selected release artifact.
+
+The SDK `0.5.12` runtime requires Arcane `0.8.12` or newer. Compatibility
+is contractual rather than exact-version pinning: the prepared Core must meet
+the highest minimum declared by the runtime, selected app, and bundled app
+dependencies; keep each app's Arcane protocol generation; and provide every
+declared feature, capability, and method. Missing requirements stop before
+provider build; a newer compatible Core is accepted. Browser-only apps may omit
+`minimumCoreVersion`, and missing permissions or optional security declarations
+normalize to empty records. The provider paths have
+been validated from independent workspaces. They do not copy proprietary source
+into the Arcane checkout.
+
+See [compatibility.md](compatibility.md) for the complete app and bundled-app
+compatibility rule and the required handling of breaking contract changes.
+
+Linux ARM64 shares the implemented Linux provider, focused tests, and a
+target-scoped remote evidence workflow. The recorded workflow exercised the
+native AArch64 toolchain, DEB, host/Core/bridge, sandboxed WebKit readiness, and
+owned process-group cancellation. The recorded Android development path
+exercised physical-device build, readiness, cancellation, uninstall, and
+absence behavior. Neither record establishes
+production signing, installation, publishing, update continuity, release
+acceptance, or production readiness.

package/docs/compatibility.md

@@ -0,0 +1,38 @@
+# Arcane application compatibility
+
+Arcane application compatibility is a capability contract, not an exact
+runtime-version pin. An app may run on a newer Arcane Core when the host meets
+all of the app's declared requirements.
+
+For a browser-only app, `permissions`, `security`, and
+`requirements.minimumCoreVersion` may be omitted. Missing permissions normalize
+to empty capability and method sets, and missing security normalizes to empty
+origin declarations with optional hardening disabled. Existing explicitly
+authored records remain unchanged.
+
+When the selected target actually uses Arcane Core, compatibility requires:
+
+- the requested target is declared by that app;
+- the host Core version is greater than or equal to the explicitly declared
+  `requirements.minimumCoreVersion`;
+- `requirements.arcaneProtocol` matches the host protocol generation;
+- every declared `requirements.features` entry is advertised by the host;
+- every declared `permissions.capabilities` entry is available; and
+- every declared `permissions.methods` entry is available.
+
+The effective Core floor for a native build is the highest minimum explicitly
+declared by the SDK runtime, the selected app, and its complete bundled-app
+closure. Browser-only targets do not invent a Core floor. The native build plan
+checks every member of that closure before producing output.
+
+This permits normal non-breaking Arcane upgrades. For example, an app requiring
+Core `0.8.12` can run on `0.8.13` or `0.9.0` when the required protocol,
+features, capabilities, and methods are still present. A higher version does
+not override a missing contract.
+
+Breaking changes must be visible at the contract boundary. A host must not
+continue advertising an old protocol, feature, capability, or method when its
+meaning or guarantees are no longer compatible. It must instead change the
+protocol generation or contract identifier so the incompatibility is reported
+before launch. Ordinary compatibility does not depend on byte counts, hashes,
+digests, provenance receipts, or optional security declarations.