arcane-os 0.63.0 → 0.65.0

package/docs/reference/core-repositories.md

@@ -0,0 +1,258 @@
+# Native repository workspaces
+
+`arcane-os/core/repositories` owns a persistent native location for connected
+repositories, separate from application code and application preferences.
+Applications choose their connection names, remotes, branches, files and Core
+methods. Importing the module and constructing an owner perform no I/O.
+
+## Persistent locations
+
+`resolveArcaneDataPaths({dataRoot}={})` returns absolute
+`{dataRoot,repositoriesRoot}` paths without creating directories:
+
+| Host | Default dataRoot | repositoriesRoot |
+|---|---|---|
+| Windows | `%LOCALAPPDATA%/ArcaneData`, or `~/AppData/Local/ArcaneData` when that variable is empty | `<dataRoot>/Repos` |
+| Linux | `$XDG_DATA_HOME/ArcaneData` when `XDG_DATA_HOME` is absolute, otherwise `~/.local/share/ArcaneData` | `<dataRoot>/Repos` |
+| macOS | `~/Library/Application Support/ArcaneData` | `<dataRoot>/Repos` |
+| Android or another adapted host | Explicit `dataRoot` supplied by the host, such as its app files directory followed by `ArcaneData` | `<dataRoot>/Repos` |
+
+An explicit `dataRoot` selects that directory directly; the SDK does not append
+another `ArcaneData`. Relative explicit paths resolve from the process working
+directory. Unsupported default platforms report `ARCANE_DATA_ROOT_REQUIRED`.
+The Android host also supplies Git/process execution through the existing
+process-adapter contract; this module does not install Git or choose shared
+Android storage.
+
+The factory's first actual operation creates necessary parent directories.
+No existing data is moved, copied, deleted, renamed or migrated. `appRoot`,
+`stateRoot`, preferences, OPFS and the existing CLI/workspace defaults remain
+independent and unchanged.
+
+## One connected working checkout
+
+```javascript
+import {createRepositoryWorkspace} from 'arcane-os/core/repositories';
+
+const repository = createRepositoryWorkspace({
+    name: 'moon-cheese-dispatches',
+    remote: applicationConnection.remote,
+    branch: applicationConnection.branch
+});
+
+const opened = await repository.open({signal});
+// opened.directory is <ArcaneData>/Repos/moon-cheese-dispatches.
+const status = await repository.status({signal});
+await repository.close();
+```
+
+`createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run}={})`
+returns `{directory,open,status,pull,push,write,close,drain,dispose}`. The `directory`
+property is the absolute selected working path.
+
+- Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
+  one nonempty directory name for each distinct connection; the SDK neither
+  derives it from a remote nor maintains a connection registry. Names are one
+  component, excluding `.`/`..` and slash/backslash separators. Choose distinct
+  names under the host filesystem's ordinary case rules.
+- Supply `directory` to use an existing application-selected path instead.
+  This takes precedence over `name` and `dataRoot`; relative paths resolve from
+  the process working directory. The path is not relocated or rewritten.
+- `remote` is required only when a missing or empty destination needs cloning.
+  `branch`, when supplied, is passed unchanged to Git's `clone --branch` option;
+  otherwise Git selects the remote's default branch. Existing checkouts keep
+  their own branch, remote, tracked files, untracked files and local changes.
+- `onEvent` and optional `run` use the existing SDK process owner. The default
+  adapter is `runProcess`; Git must be available on PATH. Credentials and
+  authentication remain with Git and the native host. The SDK adds no download,
+  credential store, polling, network retry or process supervisor.
+
+The open/status/pull/push methods accept `{signal}={}` and return promises;
+`write` accepts the complete file/message request described below:
+
+| Method | Result and side effect |
+|---|---|
+| `open` | For a missing/empty destination, runs one clone and returns `{directory,cloned:true,stdout,stderr}` with complete process output. For an existing working repository root, returns `{directory,cloned:false}` after read-only inspection. Later opens on that owner reuse preparation. |
+| `status` | Prepares the checkout if needed, then returns the existing `repositoryStatus` result unchanged. |
+| `pull` | Prepares the checkout if needed, then runs the existing clean-checkout, fast-forward-only `repositoryPull` operation unchanged. |
+| `push` | Prepares the checkout if needed, then runs the existing `repositoryPush` operation unchanged, preserving its support for unrelated uncommitted working files. |
+| `write` | Writes exact caller-selected text files, stages and commits only their literal paths, then performs one ordinary non-force push. Returns confirmed operation outcomes; see below. |
+| `close`, `drain`, `dispose` | The same idempotent operation: stop accepting new calls and await accepted work and its process/event cleanup. They retain the repository on disk. |
+
+Opening an existing repository never pulls, switches branches, resets, changes
+its remote or rewrites files. A nonempty destination that is a bare repository,
+a subdirectory of another checkout, or ordinary non-repository data is left
+untouched and reports its Git error or `ARCANE_REPOSITORY_DIRECTORY_INVALID`.
+A failed or cancelled clone reports the actual failure; any remaining directory
+is retained for application-owned inspection. There is no automatic deletion or
+destructive retry. Filesystem failures and complete Git diagnostics propagate.
+
+## Write, commit and push selected text
+
+```javascript
+const result = await repository.write({
+    files: [{path: 'dispatches/moon-cheese.md', content: completeAuthoredText}],
+    message: authoredCommitMessage,
+    signal
+});
+```
+
+`write({files:[{path,content}],message,signal}={})` requires at least one explicit
+file, a nonempty commit message and string content (including an empty string).
+Paths name working files relative to this repository, not its root, outside
+paths or Git-owned `.git` metadata. Strings must be representable as UTF-8;
+native filenames cannot contain NUL. Incompatible input reports a `TypeError`
+before any write, rather than replacing text. Content may contain NUL, BOM,
+CRLF, leading/trailing whitespace and every ordinary Unicode character.
+
+The method copies the selected records and their original strings synchronously
+when called. Later changes to the caller's array, file records or selected UI
+connection cannot alter accepted work. It does not freeze the caller's objects,
+add document labels, normalize line endings, trim content or wrap documents.
+The workspace's originally selected directory remains the operation owner.
+
+After preparing that checkout, it creates needed parent directories and writes
+each complete file using the ordinary native UTF-8 filesystem API. These are
+caller-owned replacements, not an append-only policy or a multi-file atomic
+transaction. Applications choose which paths and content may be replaced.
+Ordinary filesystem behavior, including existing symlinks, remains with the
+native host.
+
+One `git --literal-pathspecs add -- <paths>` stages only those exact names.
+One `git --literal-pathspecs commit --only --cleanup=verbatim --file - -- <paths>`
+commits only those paths, leaving unrelated staged paths staged. The original
+message is streamed unchanged through standard input. One ordinary `git push`
+then uses that repository's existing remote/ref configuration, identity,
+credentials and hooks. There is no implicit pull, branch switch, forced push,
+hook bypass, automatic retry, rollback or reset. If Git reports no changes to
+commit, that actual failure is returned; the SDK creates no empty commit.
+These are Git's documented [selected-path commit](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---only)
+and [literal pathspec](https://git-scm.com/docs/git#Documentation/git.txt---literal-pathspecs) semantics.
+
+Existing Git attributes, clean filters, EOL settings and hooks continue to apply
+when Git stages/commits content. The filesystem write preserves the original
+text; this API does not claim that repository-configured filters leave Git blob
+text identical. It preserves those settings. A push may also send existing history or other
+refs selected by the repository's ordinary push configuration.
+
+### Result and failure outcomes
+
+Successful completion returns:
+
+```text
+{
+    directory,
+    state: 'pushed',
+    stage: 'complete',
+    paths: [originalSelectedPath, ...],
+    writtenPaths: [confirmedWrittenPath, ...],
+    written: true,
+    staged: true,
+    committed: true,
+    pushed: true,
+    outputs: [{stage: 'prepare'|'stage'|'commit'|'push', stdout, stderr, code?, signal?}, ...]
+}
+```
+
+Each output record retains complete stdout/stderr. `code` and the process
+termination `signal` are included when a completed process result is available.
+An in-progress write also records its current `path` on a failure outcome.
+`writtenPaths` records successful filesystem writes in input order; `written`
+becomes true only after every requested write succeeds. The other booleans
+record successful Git command completion. **False means success is unconfirmed,
+not that files, the index, HEAD or the remote certainly remained unchanged.**
+
+- `local`: no successful commit or push has been confirmed. Inspect
+  `writtenPaths`, `written`, `staged` and `stage` for actual local progress.
+- `committed`: Git completed the commit; no successful push has been confirmed.
+  Cancellation before push keeps this result rather than claiming delivery.
+- `pushed`: Git reported successful completion of the push. A later observer
+  error retains that confirmed result while still reporting the observer error.
+- `uncertain`: an attempted file write, commit or push did not supply successful
+  completion evidence. Partial files or index changes can remain, and a remote
+  can accept updates before a connection failure hides the acknowledgement.
+  Previously confirmed `writtenPaths`, `committed` or `pushed` evidence remains
+  present. A known pre-spawn failure does not invent a dispatched side effect.
+
+After operation acceptance and execution begins, failures reject with an
+`ArcaneError` whose `cause` is the original complete failure and whose `details`
+is the outcome above. The code/message retain the original failure when
+available, and nested process details remain available through its cause.
+Input errors, a pre-aborted/queued-aborted request or a call after closing reject
+before writer execution and have the existing TypeError/cancellation/closing
+contract. No success is fabricated from an error string or callback.
+
+Cancellation is checked before each subsequent filesystem/Git action. Active
+Git cancellation drains through the existing process owner. Completion is
+recorded before checking cancellation for the next action: an accepted commit
+is retained if push has not begun, and an accepted push is retained if an
+observer subsequently fails. Failed operations leave their actual files and
+index state available for inspection; the application chooses recovery.
+Await or retain the write promise and connect the workspace's terminal drain
+to its Core service lifetime. The application still owns any decision to make
+that Core method service-lifetime rather than request-lifetime work.
+
+## Ownership, concurrency and shutdown
+
+Calls targeting the same resolved path spelling in one Node process run in
+acceptance order, including separate owners selecting that path. Windows keys
+are case-insensitive. The queue does not resolve symlink aliases or macOS case
+variants; applications use one consistent path for a shared connection.
+This prevents overlapping Git/index writes and duplicate successful cloning.
+Different directories proceed
+independently. Applications coordinate separate processes and their own direct
+file/Git writes; this module does not create a daemon or cross-process lock.
+
+A pre-aborted call starts no work. A queued aborted operation does not run when
+its turn arrives. Active cancellation reaches the existing process owner, which
+terminates its owned process tree and joins complete output/event cleanup.
+Shutdown drains accepted operations rather than deleting data or terminating
+the host early. Calls after close reject with `CORE_CLOSING`; a failed operation
+still pending when close begins rejects that drain through an `AggregateError`.
+The caller retains each operation's complete result or failure separately.
+
+The cold path is one selected connection, one parent-directory creation and one
+Git clone. Opening an existing checkout uses one read-only Git command. A
+prepared owner's status/pull/push use their existing repository operation graph.
+An accepted writer uses one filesystem write per explicitly selected file,
+then one add, one commit and one push, stopping at the first failure.
+There is no scan across applications, connections, models or platforms. Git
+progress, process-starting/completion, heartbeat and cancellation events use
+the existing `onEvent` owner with complete output and backpressure.
+An awaited event callback must not await another operation or shutdown for the
+same directory, including calls through another workspace owner: that operation
+needs the observing callback to finish. Schedule such follow-up without awaiting
+it inside that callback, and retain/observe its promise at the application owner.
+
+Compose this owner inside an application-selected Core service. Bind only the
+application's chosen methods, pass each request's `context.signal`, and return
+`drain: repository.drain` and `dispose: repository.dispose` from that service.
+Keep initialization at the repository operation that needs it; page rendering
+and unrelated services do not wait for a clone. This module installs no browser
+RPC, chooses no application service and changes no Core launch configuration.
+
+## Bare snapshots stay separate
+
+[`createGitTextSnapshot`](git-text-snapshot.md) continues to require its explicit
+dedicated bare `cacheDirectory`. It neither becomes a working checkout nor
+changes existing callers' caches. A new native caller can place that distinct
+cache under the shared location without changing the snapshot contract:
+
+```javascript
+import path from 'node:path';
+import {createGitTextSnapshot} from 'arcane-os';
+import {resolveArcaneDataPaths} from 'arcane-os/core/repositories';
+
+const {repositoriesRoot} = resolveArcaneDataPaths();
+const snapshot = createGitTextSnapshot({
+    cacheDirectory: path.join(repositoriesRoot, 'moon-cheese-reader-cache'),
+    remote: applicationConnection.remote,
+    ref: applicationConnection.ref,
+    selectPath: applicationSelectPath
+});
+```
+
+Never assign the same directory to a bare snapshot and a writable workspace.
+Applications retain remote/ref selection, document parsing, scores, messages,
+saved connection state and refresh policy. Existing explicit repository paths
+continue to operate where they already are.

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

@@ -1,17 +1,185 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.62.0",
+  "sdkVersion": "0.64.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 274,
+  "memberCount": 288,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-whisper:createWhisperRuntime",
+      "name": "createWhisperRuntime",
+      "displayName": "createWhisperRuntime()",
+      "kind": "function",
+      "signature": "createWhisperRuntime({runtime,prepare,modelId,temporaryDirectory,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/whisper"],
+      "primaryImport": "arcane-os/local-ai/whisper",
+      "group": "Core native speech",
+      "summary": "Retains a selected native Whisper helper/model across complete recordings with actual correlated recovery and joined cancellation.",
+      "availability": "Node with prepared matching helper, Whisper libraries, decoder and model; Android needs host process adaptation",
+      "protocol": "Persistent first-party native helper with replaying whisper.state and complete transcription results",
+      "normalization": "Returns current/subscribe/load/transcribe/unload/close; preserves complete original media and text/segment results; one accepted transcription, exact requestId control metadata, eligible auto GPU-to-CPU recovery once, truthful unloaded recovery and terminal errors, joined decoder/helper cleanup"
+    },
+    {
+      "id": "local-ai-whisper:default",
+      "name": "default",
+      "displayName": "createWhisperRuntime default export",
+      "kind": "function",
+      "signature": "default as createWhisperRuntime",
+      "entrypoints": ["arcane-os/local-ai/whisper"],
+      "primaryImport": "arcane-os/local-ai/whisper",
+      "group": "Core native speech",
+      "summary": "Default binding for the same retained native Whisper engine factory.",
+      "availability": "Node with the matching prepared native resources",
+      "protocol": "Native Whisper engine lifecycle",
+      "normalization": "Binding identity equals the named createWhisperRuntime export"
+    },
+    {
+      "id": "local-ai-whisper-build:buildWhisperHelper",
+      "name": "buildWhisperHelper",
+      "displayName": "buildWhisperHelper()",
+      "kind": "function",
+      "signature": "async buildWhisperHelper({runtime,outputRoot,cmake='cmake',generator,cmakeArgs=[],env,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/whisper/build"],
+      "primaryImport": "arcane-os/local-ai/whisper/build",
+      "group": "Core native speech",
+      "summary": "Builds and installs the first-party persistent helper against matching prepared Whisper headers and runtime libraries.",
+      "availability": "Node with installed CMake/C++17 toolchain matching the selected platform and architecture",
+      "protocol": "Owned configure/build/install process lifecycle",
+      "normalization": "Returns platform/architecture/root/executable/runtimeDirectory and complete configure/compile/install diagnostics; preserves cancellation and process failures, installs no model or toolchain, performs no inference"
+    },
+    {
+      "id": "codex-app-server:createCodexAppServerSession",
+      "name": "createCodexAppServerSession",
+      "displayName": "createCodexAppServerSession()",
+      "kind": "function",
+      "signature": "createCodexAppServerSession({executable,args,cwd,env,clientInfo,capabilities}={})",
+      "entrypoints": ["arcane-os/codex/app-server"],
+      "primaryImport": "arcane-os/codex/app-server",
+      "group": "Native Codex sessions",
+      "summary": "Creates an explicit native Codex App Server JSONL session without starting its process until connect.",
+      "availability": "Node with caller-selected native executable on Windows, Linux and macOS; Android requires host process adaptation",
+      "protocol": "Native Codex App Server JSONL",
+      "normalization": "Complete request/result/notification objects; ordered live delta/item callbacks, actual terminal turn outcomes and exact stored-turn recovery. Server requests retain real IDs and explicit replies. No automatic thread selection, retry, approval or desktop-task attachment."
+    },
+    {
+      "id": "codex-app-server:openCodexAppServerSession",
+      "name": "openCodexAppServerSession",
+      "displayName": "openCodexAppServerSession()",
+      "kind": "function",
+      "signature": "async openCodexAppServerSession(options)",
+      "entrypoints": ["arcane-os/codex/app-server"],
+      "primaryImport": "arcane-os/codex/app-server",
+      "group": "Native Codex sessions",
+      "summary": "Creates and connects the same explicit native session, disposing it before rejecting failed initialization.",
+      "availability": "Node with caller-selected native Codex executable",
+      "protocol": "Native Codex App Server JSONL",
+      "normalization": "Returns the connected session; creates or resumes no thread and changes no provider or authentication selection."
+    },
+    {
+      "id": "mcp-stdio:createMcpStdioServer",
+      "name": "createMcpStdioServer",
+      "displayName": "createMcpStdioServer()",
+      "kind": "function",
+      "signature": "createMcpStdioServer({serverInfo,instructions,tools=[],resources=[],onDiagnostic}={})",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "Owns one MCP STDIO session for caller-authored tools and static resources.",
+      "availability": "Node streams on Windows, Linux and macOS; Android requires host adaptation",
+      "protocol": "MCP 2025-11-25 initialize-era JSON-RPC newline transport",
+      "normalization": "Explicit CallToolResult/ReadResourceResult preserve complete content. Returns start, cancel, drain, close and closed; concurrent handlers, ordered output, cooperative cancellation and graceful EOF drain. No process launch or application-service ownership."
+    },
+    {
+      "id": "mcp-stdio:MCP_PROTOCOL_VERSION",
+      "name": "MCP_PROTOCOL_VERSION",
+      "displayName": "MCP_PROTOCOL_VERSION",
+      "kind": "constant",
+      "signature": "MCP_PROTOCOL_VERSION",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "The explicit supported MCP initialization profile, 2025-11-25.",
+      "availability": "Node",
+      "protocol": "MCP initialization version negotiation",
+      "normalization": "Later profiles and optional unimplemented capabilities are not implied."
+    },
+    {
+      "id": "mcp-stdio:McpProtocolError",
+      "name": "McpProtocolError",
+      "displayName": "McpProtocolError",
+      "kind": "class",
+      "signature": "new McpProtocolError(code,message,data)",
+      "entrypoints": ["arcane-os/mcp/stdio"],
+      "primaryImport": "arcane-os/mcp/stdio",
+      "group": "MCP STDIO",
+      "summary": "Represents an explicit JSON-RPC failure with complete message and optional data.",
+      "availability": "Node",
+      "protocol": "JSON-RPC error object",
+      "normalization": "Preserves code, message and supplied data; ordinary tool domain failures use CallToolResult.isError."
+    },
+    {
+      "id": "core-repositories:resolveArcaneDataPaths",
+      "name": "resolveArcaneDataPaths",
+      "displayName": "resolveArcaneDataPaths()",
+      "kind": "function",
+      "signature": "resolveArcaneDataPaths({dataRoot}={})",
+      "entrypoints": ["arcane-os/core/repositories"],
+      "primaryImport": "arcane-os/core/repositories",
+      "group": "Native repository workspaces",
+      "summary": "Resolves persistent per-user ArcaneData and Repos locations without I/O or migration.",
+      "availability": "Node on Windows, Linux and macOS; Android supplies its persistent dataRoot",
+      "protocol": "Native filesystem paths",
+      "normalization": "Returns absolute dataRoot and repositoriesRoot; explicit dataRoot takes precedence, otherwise uses LocalAppData, XDG data home or user Application Support. Changes no launch, preference, workspace or user data."
+    },
+    {
+      "id": "core-repositories:createRepositoryWorkspace",
+      "name": "createRepositoryWorkspace",
+      "displayName": "createRepositoryWorkspace()",
+      "kind": "function",
+      "signature": "createRepositoryWorkspace({name,directory,dataRoot,remote,branch,onEvent,run=runProcess}={})",
+      "entrypoints": ["arcane-os/core/repositories"],
+      "primaryImport": "arcane-os/core/repositories",
+      "group": "Native repository workspaces",
+      "summary": "Owns one selected native working checkout with ArcaneData/Repos defaults and existing Git/process lifecycle.",
+      "availability": "Node with Git on Windows, Linux and macOS; Android requires host process adaptation",
+      "protocol": "Git working repository and SDK process adapter",
+      "normalization": "Returns directory, open, status, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are inspected without rewriting, resetting or pulling. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. write snapshots exact selected text and paths, writes files, stages/commits only literal owned paths and non-force pushes, preserving unrelated staged files and ordinary Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes."
+    },
+    {
+      "id": "core-speech:createSpeechService",
+      "name": "createSpeechService",
+      "displayName": "createSpeechService()",
+      "kind": "function",
+      "signature": "createSpeechService({stt,tts,signal}={})",
+      "entrypoints": ["arcane-os/core/speech"],
+      "primaryImport": "arcane-os/core/speech",
+      "group": "Core native speech",
+      "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
+      "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
+      "protocol": "arcane/1 speech.status/transcribe/synthesize with speech.state/progress",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown; no engine installation or automatic provider selection"
+    },
+    {
+      "id": "core-speech:default",
+      "name": "default",
+      "displayName": "createSpeechService default export",
+      "kind": "function",
+      "signature": "default as createSpeechService",
+      "entrypoints": ["arcane-os/core/speech"],
+      "primaryImport": "arcane-os/core/speech",
+      "group": "Core native speech",
+      "summary": "Default binding for the same injected-engine native speech service factory.",
+      "availability": "Node Core with host-supplied engines",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createSpeechService export"
+    },
     {
       "id": "local-ai-image:createImageRuntime",
       "name": "createImageRuntime",
@@ -4026,6 +4194,34 @@
       "protocol": "arcane/1 renderer client ownership",
       "normalization": "Recognizes ESM and classic SDK installation identity; returns null after close or terminal failure and does not treat a foreign Arcane facade as an SDK client"
     },
+    {
+      "id": "core-client:subscribeCoreClient",
+      "name": "subscribeCoreClient",
+      "displayName": "subscribeCoreClient()",
+      "kind": "function",
+      "signature": "subscribeCoreClient(listener,{global=globalThis,emitCurrent=true,signal}={})",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Observes exact SDK client installation and retirement with current-state replay without creating a transport.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "Core client installation lifecycle",
+      "normalization": "Preserves client and error identities; reports current, installed, closed and transport-failed with previousClient; returns idempotent unsubscribe and supports AbortSignal. Installation does not imply runtime, service or model readiness"
+    },
+    {
+      "id": "core-development:createDevelopmentCore",
+      "name": "createDevelopmentCore",
+      "displayName": "createDevelopmentCore()",
+      "kind": "function",
+      "signature": "createDevelopmentCore({appRoot=process.cwd(),application,version,services=[],serviceModules=[],context={},getReplayEvents,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/core/development", "arcane-os"],
+      "primaryImport": "arcane-os/core/development",
+      "group": "Core source development",
+      "summary": "Composes application Core services and document-owned HTTP/SSE transport independently of local AI.",
+      "availability": "Node on Windows, Linux and macOS; Android requires host adaptation",
+      "protocol": "arcane/1 over source-development HTTP/SSE",
+      "normalization": "Returns ready, handler, current and close synchronously; preserves factory options and explicit context, current lifecycle replay, correlated responses and chunks, document cancellation, accepted service work and owned drain. Explicit bootstrap does not block rendering or start application processes"
+    },
     {
       "id": "core-classic-source:createCoreClassicSource",
       "name": "createCoreClassicSource",
@@ -4150,7 +4346,7 @@
       "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
       "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
       "protocol": "arcane-native-builder/1 windows-x64 provider",
-      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",

package/docs/reference/inventory/runtime-modules.json

@@ -120,6 +120,7 @@
         "AI_RUNTIME_STARTUP_EVENT",
         "AI_RUNTIME_STATES",
         "AI_RUNTIME_STATE_EVENT",
+        "continuesAIRuntimeOperation",
         "getAIRuntimeState",
         "publishAIRuntimeRoleState",
         "publishAIRuntimeRolesState",
@@ -131,8 +132,8 @@
       "summary": "Sticky mutable LLM, speech-to-text, and text-to-speech lifecycle snapshots, intents, subscriptions, and startup-settlement barriers.",
       "availability": "Cross-host in-process state contract; actual role readiness remains provider specific",
       "protocol": "arcane-ai-runtime-state/1 over the per-realm globalThis.arcaneEvents authority",
-      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; events report state but grant no authority.",
-      "surface": "Protocol/event/role/state constants; snapshot, state subscribe/publish, intent request/subscribe, and `startAIRuntime({startMuted,startTranscription,signal})` returning `{barrier,settled,cancel}`."
+      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; unloaded recovery/error may retain the exact busy operation until settlement, without readiness for new inference.",
+      "surface": "Protocol/event/role/state constants; snapshot, state subscribe/publish, intent request/subscribe, continuesAIRuntimeOperation(previous,current,operationId) for the real continuing runtime operation, and `startAIRuntime({startMuted,startTranscription,signal})` returning `{barrier,settled,cancel}`."
     },
     {
       "file": "runtime/arcane/modules/AnsiText.js",

package/docs/reference/local-ai.md

@@ -1,7 +1,7 @@
 # Local AI through Core
 
-Core owns native llama.cpp and Ollama processes, ONNX worker sessions and
-selected local image generation. The browser retains its own
+Core owns native llama.cpp and Ollama processes, ONNX worker sessions,
+selected local image generation and retained Whisper transcription. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
@@ -43,14 +43,41 @@ preserved when its version cannot be established.
 
 Both public application/package schemas accept `stable-diffusion.cpp` as a
 string or runtime-record ID. Its record additionally accepts `backend`
-(`auto`, `cpu` or `metal`) and `models`, an array of `sd14` or complete model
-descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
+(`auto`, `cpu` or `metal`) and `models`, an array of `sd14`, `flux2-klein-4b`, `sdxl-base-1.0` or
+complete model descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
 selects `auto`; omitted models leaves model selection empty. Windows/Linux
 distribution defaults use CPU; the selected universal Mac archive supports
 Metal with CPU fallback. Installation obtains the upstream library and its
 managed `koffi@3.3.2` binding, without installing a model. Complete model
 descriptors keep their resources, context, defaults and operations separate.
 See [image selection and model preparation](local-image-generation.md#selection-and-model-assets).
+The [FLUX.2 Klein 4B guide](local-image-flux.md) describes its diffusion model,
+VAE and Qwen text-conditioning resources, four-step defaults and `txt2img`
+operation. Each model retains its own supported operation set.
+
+The [SDXL Base 1.0 guide](local-image-sdxl.md) describes its complete checkpoint,
+embedded text encoders and original VAE, 1024-by-1024 default canvas and
+`txt2img` operation. Selecting a family retains the shared native context,
+progress, cancellation and complete PNG result contract.
+
+For native transcription, select a `whisper.cpp` runtime record with a `models`
+array and an explicit `modelId` when selecting more than one model. For example,
+`{id: 'whisper.cpp', backend: 'auto', models: ['whisper-small'], modelId: 'whisper-small'}`
+selects the multilingual small model. Installation prepares its native
+libraries, persistent SDK helper, FFmpeg decoder and selected model files;
+loading and transcription remain separate operations. Development and native
+assembly compose it through the shared speech service without changing the
+browser's selected STT route. See [native Whisper](local-whisper.md) for the
+complete configuration, platform, media and shutdown contracts.
+
+The selected model stays loaded across recordings. An eligible native
+accelerated failure may drain that helper and retry the same complete recording
+once on the prepared CPU backend. That accepted request retains its actual
+request identity while `recovering` is unloaded and busy; new inference remains
+blocked until actual readiness. Cancellation, unload, close, replacement and
+transport loss retain their owning cancellation behavior. A terminal engine
+failure reaches the original request as its actual error rather than a
+fabricated readiness success. See [native speech reconciliation](native-speech.md).
 
 `llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
@@ -190,6 +217,52 @@ Those methods use Ollama's native API. Streaming uses the existing
 such as selection, settings and brain creation remain with their existing
 owners; they are separate from this runtime service.
 
+### Selected Ollama model readiness
+
+The built-in `OLLAMA` LLM provider loads its selected model through Ollama's
+empty `generate` request and separately confirms that selected model in
+`running()` (`/api/ps`). A model catalog entry, a connected bridge, and a
+successful preload response alone do not establish a ready model. Ollama's
+empty preload response echoes the requested name; resident snapshots use its
+shortest tagged name. Comparison applies Ollama's default `registry.ollama.ai`
+host, `library` namespace and `latest` tag, so `moon-raccoon` and
+`registry.ollama.ai/library/moon-raccoon:latest` identify the same resident
+model. This comparison leaves outbound model names and payloads unchanged.
+The provider preserves Ollama's configured/default retention duration.
+
+Core refreshes and emits `localai.state` after its Ollama generation, chat,
+embedding and catalog-changing operations, including a failed or cancelled
+operation while the service remains available. Explicit `running()` inspection
+also publishes the actual resident-model snapshot. An SDK-owned process exit
+publishes its unavailable state through the existing process owner.
+Successes and failures belong to their observation order and engine lifetime;
+an older observation cannot replace newer state or a recovered engine's state.
+The complete current failure remains available through the owning state surface.
+
+The LLM provider subscribes before loading and retains that observation while
+loaded. An observed selected-model unload, replacement, unavailable service or
+service error revokes readiness and cancels the active request through the shared
+AI runtime. Each inference checks current residency before dispatch and again
+before accepting its terminal result. These `running({signal})` calls carry the
+owning request's cancellation through Core to `/api/ps`. Streaming chunks still
+arrive immediately through their existing path. Explicit provider unloading sends Ollama's
+`keep_alive: 0` release request; another client can independently reload a model.
+
+Ollama's documented public API exposes resident snapshots, not an ongoing
+resident-model event subscription. Core adds no timer polling. External changes
+between observations, including idle eviction or another client's model load,
+remain unobserved until a subsequent owned operation or explicit inspection.
+There is also an upstream race between a snapshot and the following request;
+these checks do not claim an atomic reservation of the daemon's model state.
+Applications consume the shared provider lifecycle rather than treating a stale
+idle snapshot as proof for their next inference. `Ollama.readiness()` remains a
+service-connectivity result and does not establish selected-model readiness.
+
+Upstream references: [resident models](https://docs.ollama.com/api/ps),
+[model-name defaults and comparison](https://github.com/ollama/ollama/blob/main/types/model/name.go),
+[preload response and resident-name handling](https://github.com/ollama/ollama/blob/main/server/routes.go),
+[preload and retention](https://docs.ollama.com/faq#how-can-i-preload-a-model-into-ollama-to-get-faster-response-times).
+
 ## Browser llama.cpp provider
 
 ```js

package/docs/reference/local-image-flux.md

@@ -45,7 +45,7 @@ model pipeline, rather than three independent image generators.
 | Native role | Resource | Purpose |
 | --- | --- | --- |
 | `diffusion_model` | [flux-2-klein-4b.safetensors](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B/resolve/e7b7dc27f91deacad38e78976d1f2b499d76a294/flux-2-klein-4b.safetensors) | Distilled image generation model. |
-| `vae` | [full_encoder_small_decoder.safetensors](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/resolve/a3efc24f613ef42d9428af62fdbd6f5fd8856c4a/full_encoder_small_decoder.safetensors) | Complete image encoder and the smaller FLUX.2 decoder. |
+| `vae` | [`full_encoder_small_decoder.safetensors`](https://huggingface.co/black-forest-labs/FLUX.2-small-decoder/resolve/a3efc24f613ef42d9428af62fdbd6f5fd8856c4a/full_encoder_small_decoder.safetensors) | Complete image encoder and the smaller FLUX.2 decoder. |
 | `llm` | [Qwen3-4B-Q8_0.gguf](https://huggingface.co/Qwen/Qwen3-4B-GGUF/resolve/bc640142c66e1fdd12af0bd68f40445458f3869b/Qwen3-4B-Q8_0.gguf) | Qwen3-4B text conditioning inside the image engine. |
 
 The selected upstream records identify these resources as Apache-2.0. The