arcane-os 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.59.0
+
+- Reconcile marked generated PWA references when a root application's PWA is
+  disabled. Add explicit `importMap({retireGeneratedPwa:true})` retirement for
+  the caller-confirmed generated root manifest reference and four standard PWA
+  output files. Ordinary disabled refresh preserves unmarked references and
+  files; authored content, unselected pages and browser storage remain intact.
+- Forward the native host's selected state directory to Core service factories
+  as a launch-context default. Every explicit launch JSON field takes precedence
+  unchanged. Windows launcher source now supplies the same separate argument;
+  using that launcher correction requires the matching rebuilt host archive.
+- Forward optional `Arcane.speech.synthesize(request, {signal})` cancellation
+  through the existing request lifetime, preserving complete payloads and the
+  180,000 ms default. Actual engine interruption remains service-owned; no new
+  speech engine, runtime dependency or data migration is introduced.
+
 ## 0.58.0
 
 - Add native ONNX sessions through `arcane-os/local-ai/onnx` and browser Core

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.58.0` SDK contract. Development applications declare
+This checkout defines the `0.59.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/core/client.mjs

@@ -568,7 +568,7 @@ export function createCoreFacade(client){
             remove:name=>invoke('environment.delete',{name})},
         mail:{send:request=>invoke('mail.send',request??{},{timeoutMs:450000})},
         speech:{status:()=>invoke('speech.status',{},{timeoutMs:10000}),
-            synthesize:request=>invoke('speech.synthesize',request??{},{timeoutMs:180000}),
+            synthesize:(request,options)=>invoke('speech.synthesize',request??{},{timeoutMs:180000,signal:options?.signal}),
             transcribe:request=>invoke('speech.transcribe',request??{},{timeoutMs:180000})},
         localAI:{status:()=>invoke('localai.status',{},{timeoutMs:15000}),
             ensurePlatform:()=>invoke('localai.platform.ensure',{},long),recover:request=>invoke('localai.services.recover',request??{},long),

package/docs/reference/README.md

@@ -53,8 +53,12 @@ alone does not make bare module names resolve in a browser.
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
+| Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
+| Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
+| Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
 | Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
+| Compose a Mac application with an architecture-matched host | [macOS application composition](core-native-packaging.md#macos-application-composition) |
 | 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) |
 | Choose a normalized typed browser decision surface | [Browser typed decisions](ai/browser-decisions.md) |

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

@@ -58,12 +58,12 @@ false when a probe throws; SDK branching continues through its owning error path
 policy, package-owned model policy, platform support, and dependency readiness
 are independent checks.
 
-Windows x64 has an SDK-owned precompiled WebView2/SEA host; Linux and Android
-retain their explicit checkout providers where listed. The SDK also includes
-macOS Foundation process-adapter source, separately from an executable target,
-renderer bridge, artifact or run command. A composed macOS host may combine that
-source with the reusable Node Core runtime, stdio transport and portable payload.
-Source availability does not establish macOS compilation or execution.
+Windows x64 and macOS ARM64/x64 have SDK-owned provider and host composition
+source. Their assembly paths require the matching numeric release's native
+host archive; npm publication alone does not supply that archive or establish
+platform execution. The macOS provider composes AppKit, WebKit and the shared
+Node Core payload. Linux and Android retain their explicit checkout providers
+where listed. See [native output and host requirements](core-native-packaging.md).
 
 ## Capability-first matrix
 
@@ -88,10 +88,14 @@ Source availability does not establish macOS compilation or execution.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Connect browser code to an existing Core transport | `arcane-os/core/client` and `arcane-os/core/contracts` | **Browser / native WebView** with an admitted transport; explicit development HTTP remains opt-in | The reusable client owns `arcane/1` correlation, readiness, cancellation, events, facades, and complete native error fidelity. It supplies no service, policy, or host process. |
 | Compose native Core services and framed stdio hosting | `arcane-os/core/runtime`, `arcane-os/core/stdio`, and `arcane-os/core/host` | **Node** on Windows, Linux, or macOS; the composing native host supplies its process and bridge | The SDK owns reusable dispatch, per-service lifecycle, request/service work ownership, cooperative cancellation, drain, and stdio framing. Product identity, policy, privileges, models, storage, and services remain host-owned. |
-| Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; portable platform selection is currently Windows or Linux, while separately composed hosts may use the payload | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
+| Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; explicit Windows, Linux or macOS platform selection | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
 | Assemble and run a Windows executable | [`arcane-os/native/windows-provider`](core-native-packaging.md#windows-executable) | **Node** for assembly; Windows x64, .NET Framework 4.6.2+ and WebView2 for execution | Uses the installed SDK version's precompiled release asset and explicit app services. Complete diagnostics and accepted service work drain on run cancellation; no OS checkout or application-side native compiler is required. |
+| Compose a macOS application bundle | [`arcane-os/native/macos-provider`](core-native-packaging.md#macos-application-composition) | **Node** assembly with matching host archive; matching Darwin ARM64/x64 for execution | Complete portable content stays in Resources. AppKit/WebKit launch, stable packaged origin, document activation and graceful Core drain remain host-owned. Source implementation is separate from a built/published host archive or actual Mac execution. |
+| Persist application-owned Core preferences | [`arcane-os/core/preferences`](core-preferences.md) | **Node** Core service; renderer uses existing `Arcane.preferences` methods | Application-selected file and exact keys/JSON values, ordered in-process writes and service-lifetime drain. Unreadable storage remains untouched; saved values do not set operating-system preferences. |
+| Read complete selected text from Git | [`createGitTextSnapshot`](git-text-snapshot.md) from `arcane-os` | **Node** with Git on Windows, Linux or macOS; Android requires host adaptation | One selected revision, complete UTF-8 content and independent result copies. A dedicated bare object cache leaves working checkouts untouched; shared refresh and drain own actual completion. |
 | Use application-selected llama.cpp/Ollama through Core | [`arcane-os/core/local-ai`, `arcane-os/ai/core-local`](local-ai.md) | **Node** native service; **Browser / native WebView** provider through an explicit Core connection | Independent runtime/model lifecycle, complete streaming and cancellation. Official runtime preparation follows explicit app requirements; model selection and business policy stay app-owned. |
 | Run native ONNX tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | **Node** Windows/Linux/macOS x64/arm64; **Browser / native WebView** through available Core | Explicit graph loading, retained workers and complete tensor outputs. Android requires host adaptation. Native calls can delay worker termination; cleanup observes actual exit. |
+| Label speakers in caller-fed mono audio | [`arcane-os/diarization`, `arcane-os/core/diarization`](diarization.md) | **Node** with built helper, selected official NeMo libraries and Nemotron model; official CPU archives cover Windows x64 and Linux/macOS x64/arm64 | Independent retained streams, complete timed segments and optional probability frames. Generic labels are not personal identities or speech transcripts; cancellation and close observe native cleanup. Android needs host adaptation. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |

package/docs/reference/core-client.md

@@ -77,6 +77,13 @@ The compatibility facade retains its operation-specific timeouts and streaming
 callbacks. Streaming IDs and isolated-operation IDs are separate protocol
 correlation fields alongside the supplied request fields.
 
+`Arcane.speech.synthesize(request, {signal})` forwards the optional cancellation
+signal through the same request lifetime. Existing one-argument calls retain
+the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
+signal sends no synthesis request; an in-flight abort sends `request.cancel`
+and suppresses late responses. Actual synthesis interruption depends on the
+registered speech service and its engine; the facade supplies no speech engine.
+
 ## Events and request lifetime
 
 `events.on(name, listener)`, `once(name, listener)` and

package/docs/reference/core-native-packaging.md

@@ -212,10 +212,14 @@ details and [the client contract](core-client.md) for native bridge integration.
 
 The generated Core entry accepts `--arcane-launch-config <path>`. The public
 `readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
-`arcane-os/core/host` reads that explicitly selected JSON object. Without the
-flag it returns `{}`. Missing files, missing flag values and malformed JSON
-report their actual errors; the reader does not search for configuration,
-rewrite it or change the process environment.
+`arcane-os/core/host` reads that explicitly selected JSON object. A native host
+can separately supply `--arcane-host-state-root <directory>` for the reader's
+`stateRoot` default. Every field in the explicit JSON object takes precedence
+unchanged, including an explicitly present `stateRoot` with a relative, null or
+other application-owned value. With neither argument the reader returns `{}`.
+Missing files, missing argument values and malformed JSON report their actual
+errors; the reader does not search for configuration, resolve or validate the
+state directory, rewrite the file or change the process environment.
 
 The generated entry supplies an artifact-derived `appRoot` and then applies the
 complete explicit launch context. Every service factory receives that same
@@ -224,7 +228,10 @@ launcher can supply the user's selected `workspaceRoot` and writable
 `stateRoot` at launch instead of embedding this machine's paths in an app
 package. The host owns those selections; the SDK does not choose a product's
 workspace, namespace, saved preferences or models. JSON values and additional
-application-owned fields remain unchanged.
+application-owned fields remain unchanged, including an app-selected
+`preferencesFile`. The state directory supplies no preference filename and
+triggers no stored-data discovery or migration. Linux and other composing hosts
+may pass the same separate argument; the reader chooses no platform directory.
 
 ## Selected local-AI runtimes
 
@@ -305,8 +312,11 @@ Arcane.exe --arcane-launch-config path/to/launch.json
 The complete JSON object reaches the service factories as their second
 argument. A supplied `stateRoot` also owns the WebView2 profile and diagnostic
 directory. Otherwise the launcher uses the current user's local application
-data under `Arcane/<app-id>`. The launcher does not invent an application
-workspace. Relative launch-file paths resolve from the invocation's working
+data under `Arcane/<app-id>`. It forwards that actual host selection through
+`--arcane-host-state-root`, so ordinary double-click startup supplies `stateRoot`
+to every Core service factory. The complete explicit launch context still takes
+precedence without rewriting its fields. The launcher does not invent an
+application workspace. Relative launch-file paths resolve from the invocation's working
 directory. `--close-on-stdin-eof` is an explicit process-owner option used by the
 SDK runner; an ordinary double-clicked window closes through its own UI.
 
@@ -414,7 +424,9 @@ owner and published `node-http-server`, not a second HTTP implementation.
 `context.stateRoot` takes precedence over the launcher's separate
 `--arcane-host-state-root` argument. The launcher defaults to
 `~/Library/Application Support/Arcane/<app-id>`; an explicitly supplied launch
-file remains unchanged and is forwarded to Core. The first successful listener
+file remains unchanged and is forwarded to Core. The shared launch reader also
+supplies that host default to every application service factory, with explicit
+launch fields taking precedence. The first successful listener
 stores its selected port in `packaged-web-origin.json`. Later launches reuse it;
 a port conflict or unreadable saved record is reported without changing origins
 or discarding stored state.

package/docs/reference/inventory/package-api.json

@@ -4175,10 +4175,10 @@
       "entrypoints": ["arcane-os/core/host"],
       "primaryImport": "arcane-os/core/host",
       "group": "Native Core host composition",
-      "summary": "Reads the complete JSON object explicitly selected by --arcane-launch-config for native service launch context.",
+      "summary": "Reads explicit launch JSON with the separately supplied native host stateRoot default for service launch context.",
       "availability": "Node, including the selected external-entry SEA launcher",
       "protocol": "Explicit launch arguments and JSON configuration",
-      "normalization": "Returns an empty record without the flag; preserves every supplied field and value, surfaces file and JSON failures, and performs no configuration search, rewrite or environment mutation"
+      "normalization": "Optional --arcane-host-state-root <directory> supplies the stateRoot default; every explicit --arcane-launch-config JSON field takes precedence unchanged, including relative or null stateRoot and application-owned preferencesFile. Returns an empty record with neither argument; surfaces missing argument values, file and JSON failures; performs no directory selection, path resolution, configuration search, rewrite, migration or environment mutation"
     },
     {
       "id": "core-host:startCoreHost",

package/docs/reference/pwa.md

@@ -94,14 +94,81 @@ packaging use that layout directly:
   packaged installation ID remains `./`, and an explicit `manifest.id` remains
   authoritative. An ID identifies the installation; it does not generate a
   directory or a redirect.
-- Authored resources follow their normal include/exclude selection. Generation
-  does not delete existing files, stored application data, or worker caches.
+- Authored resources follow their normal include/exclude selection. Ordinary
+  generation preserves existing files, stored application data, and worker caches.
+  Explicit retirement of confirmed generated source output is described below.
 
 Generated and offline app files are committed. GitHub Actions consume those
 committed files rather than generating them. Actual multi-app workspaces keep
 their explicit `appsRoot: "apps"` layout. This source/package contract does not
 establish any particular installed application's browser lifecycle.
 
+### Disable source PWA generation and retire generated output
+
+Set `package.pwa.enabled:false` in `arcane-app.json` (or `pwa.enabled:false` in
+an authored schema-1 `arcane-package.json`), then run the public import-map
+operation. For standalone `appsRoot:"."` applications, disabled refresh removes
+active `data-arcane-pwa` registration scripts and matching manifest relationships
+marked `data-arcane-manifest` from the selected application documents. Root source
+generation marks only manifest links it newly inserts; it does not claim an
+existing unmarked link as its own. A wholly omitted `pwa` record does not select
+source retirement.
+
+By default, unmarked manifest references and all existing PWA files remain in
+place. This preserves authored resources that happen to use the standard names.
+Older SDK source generation emitted an unmarked manifest link. When the
+application owner has established that this link and the four standard root
+outputs are SDK-generated, use the same public toolchain with an explicit
+ownership declaration:
+
+```js
+import {createToolchain} from 'arcane-os';
+
+const toolchain = createToolchain({workspaceRoot: process.cwd(), appId: 'my-app'});
+await toolchain.importMap({retireGeneratedPwa: true});
+```
+
+Before retirement, remove any explicit entries for these generated outputs from
+the application's `package.include` selection. They are generated output, not
+required source input; leaving a deleted file as a required input would make the
+next inspection fail. Keep authored selection changes with the application
+owner. Confirm that unselected documents or separately hosted pages do not still
+need the retiring files; this operation does not rewrite those pages.
+
+With PWA disabled, `retireGeneratedPwa:true` also removes selected-document
+manifest relationships resolving to the root `arcane.webmanifest`, including
+older unmarked generated links, and deletes exactly these confirmed generated
+files at the application root:
+
+- `arcane.webmanifest`
+- `arcane-offline.json`
+- `arcane-sw.js`
+- `arcane-pwa.mjs`
+
+The option is an application-owner declaration of generated ownership, not a
+filename-based inference. Omit it when any listed file or matching manifest
+reference is authored or its ownership is unknown. It is available through
+`createToolchain().importMap()` and `executeOperation('import-map', options)`;
+there is no new CLI flag. The ordinary CLI refresh performs marked-reference
+retirement only. An enabled descriptor ignores this retirement option and
+continues normal generation.
+
+With the source selection updated, repeated retirement accepts already-absent
+generated files. The
+`import-map.root-files.completed` event reports the paths actually removed in
+`retiredPwa`. Re-enabling PWA regenerates its normal root output and references.
+The operation leaves other files (including a separate `manifest.json`), other
+link relationships, inactive HTML, unselected documents, SDK mappings, and
+application content unchanged. It never unregisters an already registered
+service worker, clears caches, or changes browser saved data. Existing browser
+registrations therefore keep their own lifecycle; source retirement is not a
+claim that an installed browser PWA was removed. Package-output behavior below
+is unchanged.
+
+Reference updates finish before file removal begins. Cancellation or a file
+error is reported without undoing earlier completed changes; a later call can
+finish retirement. The operation does not claim an all-or-nothing transaction.
+
 ### Authored host root and app entry
 
 An authored `index.html` at the source host root keeps `/` separate from the

package/docs/reference/sdk-api.md

@@ -58,6 +58,10 @@ runtime layouts.
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle with explicitly supplied services. |
 | `arcane-os/core/packaged-web` | Core-owned packaged web listener with a persisted loopback origin and ready/failure events. |
+| `arcane-os/core/preferences` | Existing preference RPC methods with an application-selected file, ordered writes and owned drain. |
+| `arcane-os/core/diarization` | Lazy native speaker-diarization service, explicit stream methods and lifecycle/result events. |
+| `arcane-os/diarization` | Retained Nemotron model helper and independent caller-fed audio streams. |
+| `arcane-os/diarization/build` | First-party helper compilation against explicitly installed NeMo-Speech.cpp libraries. |
 | `arcane-os/core/local-ai` | Native llama.cpp, Ollama and ONNX Core service, model readiness, complete responses and owned lifecycle. See [local AI through Core](local-ai.md). |
 | `arcane-os/local-ai` | Official runtime installation and native artifact bundling for selected llama.cpp/Ollama/ONNX requirements and NeMo libraries. |
 | `arcane-os/local-ai/onnx` | Retained native ONNX worker sessions with explicit graph loading and complete tensor inference. |
@@ -389,6 +393,12 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `arcaneNativeBuilderProvider` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
 | `arcaneNativeBuilderProvider default export` | singleton | `arcane-os/native/macos-provider` | macOS native provider | Node assembly; matching Darwin architecture and selected host asset |
 | `createPackagedWebService()` | function | `arcane-os/core/packaged-web` | Native packaged web serving | Node Core lifetime; actual listener readiness before navigation |
+| `createPreferencesService()` | function | `arcane-os/core/preferences` | Core preference persistence | Node Core runtime with an application-selected file |
+| `createPreferencesService default export` | function | `arcane-os/core/preferences` | Core preference persistence | Same Core service factory |
+| `createDiarization()` | function | `arcane-os/diarization` | Native speaker diarization | Node with a built helper, selected NeMo libraries and caller-selected model |
+| `buildDiarizationHelper()` | function | `arcane-os/diarization/build` | Native speaker diarization | Node with installed CMake/C++17 toolchain and selected runtime |
+| `createDiarizationService()` | function | `arcane-os/core/diarization` | Native speaker diarization | Node Core runtime with explicitly selected helper, runtime and model |
+| `createDiarizationService default export` | function | `arcane-os/core/diarization` | Native speaker diarization | Same Core service factory |
 | `createCoreLocalAIProvider()` | function | `arcane-os/ai/core-local` | Core local AI | Browser/native WebView with an available Core connection |
 | `createLocalAIService()` | function | `arcane-os/core/local-ai` | Core local AI | Node with selected llama.cpp/Ollama/ONNX runtimes |
 | `createONNXRuntime()` | function | `arcane-os/local-ai/onnx` | Core local AI | Node with prepared Microsoft ONNX runtime |
@@ -7415,6 +7425,137 @@ errors, with no silent new origin. Startup rejection belongs to the Core
 and lifecycle completion. No application launch payload is rewritten, no model
 is loaded, and the ordinary server's HTTPS default is unchanged.
 
+## createPreferencesService()
+
+### Overview
+
+Supplies the five existing `Arcane.preferences` methods using an application-selected
+JSON file. Construction performs no filesystem work. Preference names, defaults,
+schemas and writable location remain application-owned.
+
+### Signature and result
+
+```text
+createPreferencesService({file}={})
+```
+
+Import from `arcane-os/core/preferences`. The returned Core service exposes
+`preferences.list/get/set/setMany/delete`, `drain()` and `dispose()`. Writes use
+`lifetime:'service'`, preserve complete JSON values and existing document metadata,
+and acknowledge after the new content is flushed and the selected file replaced.
+Operations selecting the same resolved filename share an ordered in-process queue.
+Unreadable or malformed files report their errors without being replaced; a missing
+file starts with empty entries. Unrepresentable JSON values fail before replacement.
+
+```javascript
+import {createPreferencesService} from 'arcane-os/core/preferences';
+
+const preferences = createPreferencesService({file: selectedPreferenceFile});
+```
+
+Register the service with the existing Core owner. Its drain/dispose stops new
+acceptance, waits for accepted work and exposes failures; subsequent calls reject
+with `CORE_CLOSING`. See [method results, storage and service composition](core-preferences.md).
+
+## createPreferencesService default export
+
+The default export from `arcane-os/core/preferences` is the same
+`createPreferencesService` factory, with identical arguments, method results
+and lifecycle:
+
+```javascript
+import createPreferencesService from 'arcane-os/core/preferences';
+```
+
+## createDiarization()
+
+### Overview
+
+Retains one caller-selected Nemotron model in its first-party native helper and
+accepts independent mono-audio streams. Results contain generic timed speaker
+labels; they do not identify people or perform speech recognition.
+
+### Signature and result
+
+```text
+createDiarization({executable,modelPath,runtime,onEvent}={})
+```
+
+Import from `arcane-os/diarization`. Supply absolute helper/model paths and the
+selected runtime's library locations. The returned owner starts the helper and
+exposes `ready`, `completion`, `current()`, replaying `subscribe()`,
+`openStream()`, `diarize()` and `close()`. Readiness resolves only after model
+loading. Each stream owns `push`, `finish`, `cancel`, `completion` and `current`;
+pushes preserve mono float32 input, use backpressure and return the latest timed
+segment snapshot. Caller callbacks may receive every probability frame.
+
+```javascript
+import {createDiarization} from 'arcane-os/diarization';
+
+const speakers = createDiarization({executable, modelPath, runtime});
+const result = await speakers.diarize({audio: monoSamples, sampleRate: 16000});
+await speakers.close();
+```
+
+Load, callback, process and cleanup failures remain observable. Cancellation
+suppresses later results for its stream and closes it after accepted native
+commands; the C ABI supplies no immediate interrupt. Close drains owned work
+and observes helper exit. See [complete audio, callback and cancellation contracts](diarization.md).
+
+## buildDiarizationHelper()
+
+```text
+async buildDiarizationHelper({runtime,outputRoot,signal,onEvent}={})
+```
+
+Import from `arcane-os/diarization/build`. Builds the first-party helper for the
+current host using installed CMake/C++17 tools and the selected runtime's
+`cmakeDirectory`. Returns `{platform,architecture,root,executable,diagnostics}`
+after configure, compile and install, retaining complete command diagnostics.
+Missing inputs or actual tool failures reject through the shared process owner;
+no compiler, model or runtime is downloaded by this function.
+
+```javascript
+import {buildDiarizationHelper} from 'arcane-os/diarization/build';
+
+const helper = await buildDiarizationHelper({runtime, outputRoot: helperDirectory});
+```
+
+See [runtime preparation, helper placement and platform support](diarization.md#runtime-and-helper).
+
+## createDiarizationService()
+
+```text
+createDiarizationService(options={},launch={})
+```
+
+Import from `arcane-os/core/diarization`. This synchronous `native.services`
+factory accepts `{executable,modelPath,runtime,onEvent}` and the native launch
+context. Relative executable/model paths use `workspaceRoot`, then `appRoot`,
+then the current directory. It supplies `diarization.status`, `diarization.load`,
+`diarization.open`, `diarization.push`, `diarization.finish`, `diarization.cancel`
+and `diarization.recording`, state/update/probability events and drain/dispose hooks.
+The first actual operation loads the model, independently of Core startup.
+
+```javascript
+import {createDiarizationService} from 'arcane-os/core/diarization';
+
+const service = createDiarizationService({executable, modelPath, runtime}, launch);
+```
+
+Session audio has service lifetime and explicit cancellation; a recording's
+request cancellation closes only that recording. Complete float32 samples use
+the documented Core transport framing. See [inputs, results, events and lifetime](diarization.md#core-service).
+
+## createDiarizationService default export
+
+The default binding from `arcane-os/core/diarization` is exactly the named
+`createDiarizationService` factory, with the same selection and service lifecycle:
+
+```javascript
+import createDiarizationService from 'arcane-os/core/diarization';
+```
+
 ## readCoreLaunchContext()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/core/host.mjs

@@ -6,13 +6,22 @@ import {startCoreStdio} from './stdio.mjs';
 const is = new Is(false);
 
 /**
- * Read only the explicitly supplied --arcane-launch-config filename.
- * Return the complete JSON object for the service factories' second argument;
- * field meanings belong to the launch owner and individual services.
+ * The host's separate state-root argument supplies a launch-context default.
+ * Every field in an explicitly selected launch JSON object takes precedence
+ * unchanged; field meanings belong to the launch owner and individual services.
  */
 export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {}) {
+    const stateFlag = argv.indexOf('--arcane-host-state-root');
+    const defaults = {};
+    if (stateFlag !== -1) {
+        const stateRoot = argv[stateFlag + 1];
+        if (stateRoot === undefined || stateRoot === '') {
+            throw new TypeError('--arcane-host-state-root requires a directory.');
+        }
+        defaults.stateRoot = stateRoot;
+    }
     const flag = argv.indexOf('--arcane-launch-config');
-    if (flag === -1) return {};
+    if (flag === -1) return defaults;
     const filename = argv[flag + 1];
     if (filename === undefined || filename === '') {
         throw new TypeError('--arcane-launch-config requires a filename.');
@@ -21,7 +30,7 @@ export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {})
     if (context === null || !is.object(context) || is.array(context)) {
         throw new TypeError('Core launch configuration must be a JSON object.');
     }
-    return context;
+    return {...defaults, ...context};
 }
 
 /** Compose app services with the shared dispatcher and draining transport. */

package/src/core/hosts/windows/ArcaneLauncher.cs

@@ -69,7 +69,10 @@ namespace Arcane.Core.Hosts.Windows
                     Title = name,
                     ClassicClientSource = File.ReadAllText(Path.Combine(directory, RequiredString(client, "source"))),
                     CoreExecutable = Path.Combine(directory, "runtime", "ArcaneCore.exe"),
-                    CoreArguments = launchFilename == null ? String.Empty : "--arcane-launch-config " + QuoteArgument(launchFilename),
+                    // Forward the actual host selection separately; Core keeps
+                    // every explicit launch-record field unchanged.
+                    CoreArguments = "--arcane-host-state-root " + QuoteArgument(profileParent)
+                        + (launchFilename == null ? String.Empty : " --arcane-launch-config " + QuoteArgument(launchFilename)),
                     // Relative explicit launch filenames retain their caller's
                     // meaning; the SEA locates its loader beside its executable.
                     CoreWorkingDirectory = Environment.CurrentDirectory

package/src/import-map.mjs

@@ -2091,8 +2091,8 @@ function scanHtmlStructure(html){
     return {scripts,links,bases,metas,elements,styles,headClose,bodyClose};
 }
 
-/** Remove generated PWA references from a selected output document without changing authored content. */
-export function removePwaEntryReferences(html, {documentUrl, manifestUrl} = {}) {
+/** Retire active PWA references; source refresh may restrict removal to marked ownership. */
+export function removePwaEntryReferences(html, {documentUrl, manifestUrl, markedManifestOnly = false} = {}) {
     if (!is.string(html)) throw new TypeError('PWA entry HTML must be a string.');
     const structure = scanHtmlStructure(html);
     const manifest = new URL(manifestUrl, documentUrl);
@@ -2106,6 +2106,7 @@ export function removePwaEntryReferences(html, {documentUrl, manifestUrl} = {})
     const edits = [];
     for (const link of structure.links) {
         const attributes = parseTagAttributes(link.open);
+        if (markedManifestOnly && !attributes.has('data-arcane-manifest')) continue;
         const href = htmlAttributeView(attributes.get('href') ?? '');
         const rel = htmlAttributeView(attributes.get('rel') ?? '');
         if (!href?.decoded || !rel) continue;
@@ -2152,7 +2153,7 @@ export function removePwaEntryReferences(html, {documentUrl, manifestUrl} = {})
 }
 
 /** Update only active PWA entry references; registration never orders application startup. */
-export function applyPwaEntryReferences(html,{manifestUrl,bootstrapUrl}={}){
+export function applyPwaEntryReferences(html,{manifestUrl,bootstrapUrl,markGeneratedManifest=false}={}){
     if(!is.string(html))throw new TypeError('PWA entry HTML must be a string.');
     if(!is.string(manifestUrl)||!manifestUrl||!is.string(bootstrapUrl)||!bootstrapUrl){
         throw new TypeError('PWA manifestUrl and bootstrapUrl must be nonempty strings.');
@@ -2223,7 +2224,10 @@ export function applyPwaEntryReferences(html,{manifestUrl,bootstrapUrl}={}){
             });
         }
     }
-    if(!manifestFound)additions.push(`<link rel="manifest" href="${attributeText(manifestUrl)}">`);
+    if(!manifestFound){
+        const marker=markGeneratedManifest?' data-arcane-manifest':'';
+        additions.push(`<link rel="manifest" href="${attributeText(manifestUrl)}"${marker}>`);
+    }
     let bootstrapFound=false;
     for(const script of structure.scripts){
         if(!parseTagAttributes(script.open).has('data-arcane-pwa'))continue;

package/src/toolchain.mjs

@@ -1,7 +1,7 @@
 import Is from 'strong-type';
 import path from 'node:path';
 import {resolveAppRoot,resolvePackageOutputRoot} from './app-layout.mjs';
-import {readdir,lstat,realpath,mkdir,readFile,writeFile} from 'node:fs/promises';
+import {readdir,lstat,realpath,mkdir,readFile,writeFile,unlink} from 'node:fs/promises';
 import {createWorkspace,initWorkspace} from './scaffold.mjs';
 import {
     discoverApps as discoverWorkspaceApps,
@@ -12,8 +12,14 @@ import {
 } from './workspace.mjs';
 import {loadArcaneIntegratedProvider} from './integrated-provider-loader.mjs';
 import {collectSourcePwaAssets,startDevServer} from './dev-server.mjs';
-import {applyPwaEntryReferences,generateImportMap,readApplicationTestImportMapContext} from './import-map.mjs';
-import {createPwaArtifacts} from './pwa.mjs';
+import {applyPwaEntryReferences,generateImportMap,readApplicationTestImportMapContext,removePwaEntryReferences} from './import-map.mjs';
+import {
+    createPwaArtifacts,
+    PWA_MANIFEST_NAME,
+    PWA_OFFLINE_MANIFEST_NAME,
+    PWA_WORKER_NAME,
+    PWA_BOOTSTRAP_NAME
+} from './pwa.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
 import {refreshAppPackageProjection} from './app-descriptor.mjs';
@@ -293,7 +299,7 @@ async function validatePreparedRuntime(prepared,{signal}={}){
     return validation;
 }
 
-async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperationLease}={}){
+async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperationLease}={},retireGeneratedPwa=false){
     const manifest=prepared.validation.app.manifest;
     const inspected=await inspectPackagedApp({
         workspaceRoot:prepared.workspaceRoot,
@@ -322,12 +328,12 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
         onEvent
     });
     if(prepared.validation.config.appsRoot==='.'){
-        await refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent});
+        await refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent,retireGeneratedPwa});
     }
     return importMap;
 }
 
-async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent}){
+async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent,retireGeneratedPwa=false}){
     const {workspaceRoot,appId}=prepared;
     const manifest=prepared.validation.app.manifest;
     const installed=await readInstalledSdkLayout(workspaceRoot,prepared.validation.config);
@@ -385,21 +391,44 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
         await mkdir(path.dirname(filePath),{recursive:true});
         await writeFile(filePath,file.content,'utf8');
     }
-    if(pwa){
+    const pwaDisabled=manifest.pwa?.enabled===false;
+    const retireConfirmedOutput=pwaDisabled&&retireGeneratedPwa===true;
+    if(pwa||pwaDisabled){
         for(const document of inspected.browserDocuments){
             throwIfAborted(signal);
             const filePath=path.join(prepared.appRoot,...document.path.split('/'));
             const content=await readFile(filePath,'utf8');
-            await writeFile(filePath,applyPwaEntryReferences(content,{
+            const updated=pwa?applyPwaEntryReferences(content,{
                 manifestUrl:`/${pwa.entryAssets.manifest}`,
-                bootstrapUrl:`/${pwa.entryAssets.bootstrap}`
-            }),'utf8');
+                bootstrapUrl:`/${pwa.entryAssets.bootstrap}`,
+                markGeneratedManifest:true
+            }):removePwaEntryReferences(content,{
+                documentUrl:new URL(`/${document.path.split('/').map(encodeURIComponent).join('/')}`,sourceOrigin),
+                manifestUrl:`/${PWA_MANIFEST_NAME}`,
+                markedManifestOnly:!retireConfirmedOutput
+            });
+            if(updated!==content)await writeFile(filePath,updated,'utf8');
+        }
+    }
+    const retiredPwa=[];
+    if(retireConfirmedOutput){
+        // The caller declares these standard outputs generated, not merely same-named authored files.
+        // Remove selected references before retiring their targets; browser storage is untouched.
+        for(const relative of [PWA_MANIFEST_NAME,PWA_OFFLINE_MANIFEST_NAME,PWA_WORKER_NAME,PWA_BOOTSTRAP_NAME]){
+            throwIfAborted(signal);
+            try{
+                await unlink(path.join(workspaceRoot,relative));
+                retiredPwa.push(relative);
+            }catch(error){
+                if(error.code!=='ENOENT')throw error;
+            }
         }
     }
     await emit(onEvent,{
         type:'import-map.root-files.completed',appId,
         navigation:[],
-        pwa:pwa?.files.map(file=>file.path)??[]
+        pwa:pwa?.files.map(file=>file.path)??[],
+        retiredPwa
     });
 }
 
@@ -408,7 +437,7 @@ async function importMapApplication(options={}){
     const prepared=await preparedWorkspace({...options,allowMissingManagedImportMap:true});
     const importMap=await ownedWork(
         'import-map',
-        context=>refreshPreparedImportMap(prepared,context),
+        context=>refreshPreparedImportMap(prepared,context,options.retireGeneratedPwa===true),
         {...options,workspaceRoot:prepared.workspaceRoot}
     );
     await validatePreparedRuntime(prepared,{signal:options.signal});