arcane-os 0.66.0 → 0.68.0

package/docs/reference/core-repositories.md

@@ -24,7 +24,8 @@ 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.
+The factory's first operation that prepares a checkout creates necessary parent
+directories. The read-only `configuration` operation never prepares one.
 No existing data is moved, copied, deleted, renamed or migrated. `appRoot`,
 `stateRoot`, preferences, OPFS and the existing CLI/workspace defaults remain
 independent and unchanged.
@@ -47,7 +48,7 @@ await repository.close();
 ```
 
 `createRepositoryWorkspace({name,directory,dataRoot,remote,branch,gitIdentity,onEvent,run}={})`
-returns `{directory,open,status,pull,push,write,close,drain,dispose}`. The `directory`
+returns `{directory,open,status,configuration,pull,push,write,close,drain,dispose}`. The `directory`
 property is the absolute selected working path.
 
 - Omit `directory` to select `<repositoriesRoot>/<name>`. The application supplies
@@ -67,15 +68,17 @@ property is the absolute selected working path.
   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;
+The open/status/configuration methods accept `{signal}={}` and return promises;
+pull/push accept `{target,signal}={}` with an optional captured destination.
 `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. |
+| `configuration` | Observes the existing working root, symbolic HEAD, origin and configured upstream. It never clones, initializes or fetches. |
+| `pull` | Prepares the checkout if needed, then runs clean-checkout, fast-forward-only `repositoryPull`, optionally using the operation's selected target. |
+| `push` | Prepares the checkout if needed, then runs `repositoryPush`, optionally using the operation's selected target, preserving 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. |
 
@@ -87,6 +90,83 @@ 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.
 
+## Existing checkout configuration and selected targets
+
+`configuration({signal}={})` observes an existing checkout without invoking
+`open`, creating directories, cloning, initializing, fetching or changing Git
+configuration. A missing repository reports the actual Git failure. A bare
+cache or nested checkout directory reports `ARCANE_REPOSITORY_DIRECTORY_INVALID`.
+Its result is:
+
+```text
+{
+    repositoryRoot,
+    headRef: fullSymbolicRef | null,
+    origin: {urls: [...], pushUrls: [...]},
+    upstream: {remoteNames: [...], mergeRefs: [...], urls: [...], pushUrls: [...]} | null
+}
+```
+
+`repositoryRoot` is this owner's absolute selected working root. `headRef` is
+the complete symbolic HEAD, including an unborn branch, or `null` for detached
+HEAD. `upstream` is `null` when HEAD does not name a local branch. Otherwise its
+arrays contain that branch's configured `remote` and `merge` values; `urls` and
+`pushUrls` observe the effective last configured remote name. A `.` remote
+means the local repository and has no remote URL arrays. Origin is observed
+independently, even when it is not the upstream.
+
+Arrays retain configured order, repeated values, complete UTF-8 strings and
+empty strings. `[]` means unset; `['']` means an explicit empty value. The
+reader honors configured includes and ordinary Git configuration precedence.
+Unset push URLs do not imply that Git cannot push: Git retains its normal URL
+fallback and rewrite behavior. These are configuration observations, not
+resolved endpoints, authentication, account identity or ownership proof.
+The SDK neither queries a credential helper nor changes configuration here.
+
+Metadata uses the shared raw-Git-text reader. Lifecycle/stderr events remain
+with the process owner, raw stdout remains parser-owned, and undecodable text
+reports `ARCANE_GIT_CONFIGURATION_NOT_TEXT`. Failures retain complete raw
+stdout, process diagnostics and causal errors using the identity reader's
+documented attachment behavior. One observation uses four read-only Git
+commands for an attached local branch, or three otherwise. Results are not a
+transaction with later work or external Git activity. The app owns any decision
+that the current checkout corresponds to its selected repository and branch.
+
+The optional `target:{remote,ref}` on `pull`, `push` and `write` selects that
+operation's Git destination. Both fields are nonempty strings representable by
+the native process transport. The SDK captures their exact strings when the
+call is accepted; later edits to the target object or UI selection cannot
+redirect queued or active work. Git owns ref parsing, URL interpretation,
+credentials, hooks and remote outcomes. This target is independent of the
+factory's `remote`/`branch`, which remain initial-clone inputs only.
+
+```javascript
+const observed = await repository.configuration({signal});
+// The app decides whether observed.headRef and configured URLs match its choice.
+const target = {remote: connection.locator, ref: connection.ref};
+await repository.pull({target, signal});
+const result = await repository.write({files: selectedFiles, message, target, signal});
+```
+
+A targeted pull uses `git pull --ff-only -- <remote> <ref>:`. The trailing colon
+is Git's source-only fetch framing; the fetched history is integrated into the
+current branch. It does not switch branches or reset files/history. The existing
+clean-checkout requirement remains. A targeted push uses
+`git push --no-follow-tags -- <remote> HEAD:<ref>`: current HEAD is published to
+the selected ref, without force or implicit configured tag following. Existing
+history is still sent when Git needs it. Ordinary conflicting Git settings or
+remote rejection remain actual failures; no settings are rewritten.
+
+Omitting `target` preserves ordinary configured pull/push behavior and its
+existing result shape. Targeted pull/push results add the captured `target` and
+complete `stdout`/`stderr` alongside the existing `action`, `repositoryRoot`,
+`branch` and compatibility `output` field. Writer results and failure outcomes
+add that same captured `target`. There is no hidden pre-write pull, branch
+selection, retry, reset, force, reversal or recommit. The app decides when to
+observe, refresh, write and publish. See Git's [pull](https://git-scm.com/docs/git-pull),
+[push](https://git-scm.com/docs/git-push) and [configuration](https://git-scm.com/docs/git-config)
+contracts.
+
 ## Git identity configuration
 
 ```javascript
@@ -215,7 +295,7 @@ const result = await repository.write({
 });
 ```
 
-`write({files:[{path,content}],message,signal}={})` requires at least one explicit
+`write({files:[{path,content}],message,target,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;
@@ -239,9 +319,10 @@ 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, the optional
+message is streamed unchanged through standard input. Without `target`, one
+ordinary `git push` then uses that repository's existing remote/ref configuration, the optional
 process-local identity selection above, existing credentials and hooks.
+With `target`, the final push uses the selected current-HEAD mapping above.
 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.
@@ -252,7 +333,8 @@ 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.
+refs selected by the repository's ordinary push configuration when no explicit
+target is supplied.
 
 ### Result and failure outcomes
 
@@ -275,6 +357,8 @@ Successful completion returns:
 
 Each output record retains complete stdout/stderr. `code` and the process
 termination `signal` are included when a completed process result is available.
+When supplied, `target:{remote,ref}` is included in the result or failure outcome
+with the original accepted strings.
 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

package/docs/reference/core-runtime.md

@@ -66,11 +66,34 @@ service's startup before invoking its handler. State errors use the shared
 complete diagnostic serialization; the startup promise retains its original
 rejection value.
 
-Each lifecycle hook receives `{application, service, emit}`. Each request handler
-receives `(parameters, {application, service, emit, requestId, signal})`, with
+Each lifecycle hook receives `{application, service, emit, getService}`. Each request handler
+receives `(parameters, {application, service, emit, getService, requestId, signal})`, with
 `this` bound to its service definition. A hook or handler may publish a complete
 service-owned event through `emit(event, data)`.
 
+### Native service composition
+
+`await runtime.getService(name)` and `await context.getService(name)` return the
+actual registered service definition after that service's shared startup
+promise. A lookup can start its selected dependency before `runtime.start()`;
+it waits for that dependency alone, with no renderer, transport request or
+all-service readiness barrier. Concurrent lookups reuse the same startup and
+return the same object. Applications keep their service dependencies acyclic.
+
+Use the returned service's documented native members, such as
+[`getONNXRuntime()`](local-ai.md#native-service-owners), for same-process
+composition. RPC handlers remain owned by the dispatcher; calling entries in
+`service.methods` directly does not supply request tracking or cancellation.
+No service lookup is exposed over the browser protocol.
+
+An unregistered name rejects with `CORE_SERVICE_UNAVAILABLE`. Startup failure
+rejects with the original error. New lookups reject with `CORE_CLOSING` once
+shutdown begins; an already accepted lookup still settles with its startup.
+Lookup provides readiness, not a lifetime lease or ownership transfer. Retain
+each acquired native owner according to its own documented cleanup contract,
+and use that retained handle during disposal rather than requesting a new one.
+Independent services still dispose concurrently.
+
 ## State and frames
 
 `runtime.current()` returns dispatcher state, application, version, per-service
@@ -100,6 +123,20 @@ The shared `arcane-os/core/contracts` module owns `CORE_PROTOCOL` (`arcane/1`),
 availability errors remain observable; unavailable services are not replaced
 with browser behavior.
 
+A request with no registered handler retains code `METHOD_NOT_ALLOWED` and
+adds the exact `method`, its first dotted `namespace`, and a `reason`.
+`core-namespace-unavailable` means the dispatcher has neither a service with
+that name nor any registered method in that namespace. Otherwise the reason is
+`core-method-unavailable`; the built-in `system`, `app`, and `version`
+namespaces also count as present. This is a dispatch lookup result before any
+handler or permission decision, not a capability-discovery call. A read-only
+or partially registered service therefore never appears wholly absent.
+Handler/startup/permission errors remain unchanged and acquire none of these
+lookup markers. Generic or older `METHOD_NOT_ALLOWED` errors do not establish
+namespace absence. An optional browser adapter may recognize the exact absent
+namespace and method according to its own documented contract; the dispatcher
+does not select or create another implementation.
+
 Events have `{protocol, type:'event', event, data, time}`:
 
 - `core.ready`: the dispatcher is connected; service/model readiness is separate.
@@ -133,9 +170,13 @@ the handler runs. A service that does not finish or respond to cancellation is
 still unfinished; the SDK does not report a forced timeout as successful cleanup.
 
 Use `lifetime:'service'` for accepted work, such as a save, that must survive a
-renderer cancellation or disconnect. These operations are not aborted by the
-request cancellation controls or by normal Core shutdown. The service still
-owns its persistence, queueing and failure semantics.
+renderer cancellation or disconnect. The dispatcher does not abort these
+operations through request cancellation controls or its own shutdown. The
+service still owns its persistence, queueing and failure semantics. A composing
+host or native service can abort its own lifetime signal during shutdown;
+in-flight native inference can therefore be cancelled even when the dispatcher
+retains a service-lifetime response. Service lifetime does not promise survival
+of native host shutdown.
 
 `runtime.close()` is idempotent and retains the same completion promise. It stops
 accepting new requests, cancels request-lifetime operations, waits for accepted

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

@@ -1,17 +1,59 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.65.0",
+  "sdkVersion": "0.67.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 290,
+  "memberCount": 293,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-decisions:createNativeDecisionModel",
+      "name": "createNativeDecisionModel",
+      "displayName": "createNativeDecisionModel()",
+      "kind": "function",
+      "signature": "createNativeDecisionModel({onnx,modelAssets,workingDirectory,paths,model='onnx-community/laya-typed-decisions-ONNX',revision='main',dtype='fp32',sessionOptions,executionPreference='gpu',signal}={})",
+      "entrypoints": ["arcane-os/local-ai/decisions"],
+      "primaryImport": "arcane-os/local-ai/decisions",
+      "group": "Native typed decisions",
+      "summary": "Explicit native Laya FP32 option scoring through an existing ONNX owner and a tokenizer Worker.",
+      "availability": "Node on Windows/Linux/macOS with selected ONNX Runtime and model files; Android needs host adaptation",
+      "protocol": "Shared browser/native decision encoding with native named tensor results",
+      "normalization": "Returns load/evaluate/classify/current/status/subscribe/unload/dispose; preserves complete separate state/question/options/type and original rows, raw scores and every graph output. Explicit load prepares selected upstream files or uses caller-owned paths; GPU preference attempts advertised providers then CPU. Cancellation retires the shared activation; files remain retained through actual ONNX and tokenizer Worker exit. No chat history or duplicate inference engine."
+    },
+    {
+      "id": "core-decisions:createNativeDecisionService",
+      "name": "createNativeDecisionService",
+      "displayName": "createNativeDecisionService()",
+      "kind": "function",
+      "signature": "createNativeDecisionService(configuration={}, {appRoot=process.cwd()}={})",
+      "entrypoints": ["arcane-os/core/decisions"],
+      "primaryImport": "arcane-os/core/decisions",
+      "group": "Native typed decisions",
+      "summary": "Renderer-independent native Laya service reusing the registered local-AI and model-assets owners.",
+      "availability": "Node Core with selected native ONNX and model files",
+      "protocol": "arcane/1 decisions.status/load/evaluate/unload and decisions.state",
+      "normalization": "Registration starts no model or tokenizer. Explicit load obtains dependency-ready same-process owners and reacquires getONNXRuntime after recovery. Native load/evaluate/classify/current/subscribe/unload/dispose preserve complete results; RPC uses the existing tensor codec. Unload has accepted service lifetime; host shutdown cancels request-lifetime load/evaluation."
+    },
+    {
+      "id": "core-decisions:default",
+      "name": "default",
+      "displayName": "createNativeDecisionService default export",
+      "kind": "function",
+      "signature": "default as createNativeDecisionService",
+      "entrypoints": ["arcane-os/core/decisions"],
+      "primaryImport": "arcane-os/core/decisions",
+      "group": "Native typed decisions",
+      "summary": "Default binding for the same native decision Core service factory.",
+      "availability": "Node Core runtime",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createNativeDecisionService export"
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -164,7 +206,7 @@
       "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. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and no config file is written."
+      "normalization": "Returns directory, open, status, configuration, pull, push, write and identical close/drain/dispose hooks. Only missing or empty destinations clone; existing roots are preserved. configuration observes the existing root, symbolic HEAD, origin URL/pushURL arrays and branch remote/merge/upstream URL arrays without clone/init/fetch, preserving unset, empty and repeated values. Explicit paths remain selected. Same-directory operations serialize within the process; cancellation and shutdown join accepted process work. pull/push/write accept a captured target {remote,ref} for current-branch fast-forward pull or non-force current-HEAD selected-ref push; omission retains ordinary configured behavior. write snapshots exact text and paths, stages/commits only literal owned paths and preserves unrelated staged files and Git filters. Complete outputs and causal failures retain confirmed local/committed/pushed and uncertain outcomes plus the supplied target. Optional gitIdentity captures name/email/username for child Git operations only; omitted fields remain inherited and no config file is written."
     },
     {
       "id": "core-repositories:readGitIdentity",
@@ -227,14 +269,14 @@
       "name": "createCoreImageRuntime",
       "displayName": "createCoreImageRuntime()",
       "kind": "function",
-      "signature": "createCoreImageRuntime({client=getInstalledCoreClient(),signal,onEvent}={})",
+      "signature": "createCoreImageRuntime({client,signal,onEvent}={})",
       "entrypoints": ["arcane-os/ai/core-image"],
       "primaryImport": "arcane-os/ai/core-image",
       "group": "Core local images",
       "summary": "Uses an available Core image service for generation and original-PNG editing with synchronous Thinking acknowledgement, lifecycle replay and complete PNG Blobs.",
       "availability": "Browser/native WebView with an available Core image service; construction opens no connection or model",
       "protocol": "arcane/1 image.status/load/generate/edit/unload and image.state/progress",
-      "normalization": "Returns load/generate/edit/unload/inspect/current/subscribe/close; edit preserves the complete original PNG Blob/File through transport with explicit strength; timeoutMs is zero, close cancels only this accessor and explicit unload owns the shared model"
+      "normalization": "Returns load/generate/edit/unload/inspect/current/subscribe/close; omitted client follows installation/replacement/retirement, explicit client including null remains fixed. Retirement cancels owned work and clears readiness; late old-client output is suppressed. Edit preserves the complete original PNG Blob/File through transport with explicit strength; timeoutMs is zero, close cancels only this accessor and explicit unload owns the shared model"
     },
     {
       "id": "core-image-service:createLocalImageService",
@@ -290,7 +332,7 @@
       "summary": "Owns selected native working-file projections and engine retain handles while original stored model files remain unchanged.",
       "availability": "Node Core with an application-selected working directory",
       "protocol": "arcane/1 modelAssets.open/write/complete/release/status and modelAssets.state",
-      "normalization": "Returns current/retain/dispose and Core service lifecycle; final native release joins writes and closes before deleting only its working projection"
+      "normalization": "Returns current/prepare/retain/release/dispose and Core service lifecycle. Explicit prepare({id,workingDirectory,members:[{path,url}],signal,onProgress}) streams complete upstream members through the existing file owner and reports file/phase progress. release(id) relinquishes preparation ownership; cancellation and cleanup join fetches/writes. Native retains survive until actual engine release before deleting only the owned working projection. Startup downloads nothing."
     },
     {
       "id": "core-model-assets-service:default",
@@ -318,21 +360,21 @@
       "summary": "Owns explicitly loaded ONNX graphs and complete named tensor inference in retained native workers.",
       "availability": "Node on Windows/Linux/macOS x64/arm64 with prepared onnxruntime-node; Android needs host adaptation",
       "protocol": "Per-session worker lifecycle with structured-clone tensors and replaying state",
-      "normalization": "Returns load/run/unload/current/subscribe/close; explicit model and session IDs; native calls may delay worker termination, and close observes actual exit"
+      "normalization": "Returns load/run/unload/current/subscribe/close; load accepts executionPreference gpu for advertised provider creation attempts then CPU, while explicit sessionOptions.executionProviders takes precedence. Complete execution diagnostics distinguish configured providers from physical acceleration. stopping revokes new runs while exited records actual Worker exit; recoverable run errors preserve the session. Cleanup joins exit and output delivery even when termination fails."
     },
     {
       "id": "core-onnx:createCoreONNXRuntime",
       "name": "createCoreONNXRuntime",
       "displayName": "createCoreONNXRuntime()",
       "kind": "function",
-      "signature": "createCoreONNXRuntime({client=getInstalledCoreClient()}={})",
+      "signature": "createCoreONNXRuntime({client}={})",
       "entrypoints": ["arcane-os/ai/core-onnx"],
       "primaryImport": "arcane-os/ai/core-onnx",
       "group": "Core local AI",
       "summary": "Accesses local system ONNX through an existing Core client with complete tensor transport.",
       "availability": "Browser with available Core ONNX service; construction installs no runtime or model",
       "protocol": "arcane/1 onnx.status/load/run/unload and localai.state",
-      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; preserves typed and string tensors; accessor close cancels its requests without closing shared Core or implicitly unloading shared models"
+      "normalization": "Returns load/run/unload/inspect/current/subscribe/close; omitted client follows late installation/replacement/retirement and reads current status, while explicit client including null stays fixed. Retirement clears readiness and cancels owned work; late old-client results are suppressed. Preserves typed and string tensors; close removes subscriptions and cancels requests without closing shared Core or implicitly unloading shared models"
     },
     {
       "id": "root:createGitTextSnapshot",
@@ -409,14 +451,14 @@
       "name": "createCoreLocalAIProvider",
       "displayName": "createCoreLocalAIProvider()",
       "kind": "function",
-      "signature": "createCoreLocalAIProvider({client=getInstalledCoreClient(),id='llama.cpp'}={})",
+      "signature": "createCoreLocalAIProvider({client,id='llama.cpp'}={})",
       "entrypoints": ["arcane-os/ai/core-local"],
       "primaryImport": "arcane-os/ai/core-local",
       "group": "Core local AI",
       "summary": "Browser llama.cpp provider through an explicitly connected Core, with application-owned model selection and complete response streaming.",
       "availability": "Browser with an available Core local AI service; construction installs no runtime or model",
       "protocol": "arcane-ai-provider/2 LLM lifecycle over arcane/1",
-      "normalization": "Preserves complete payloads and original parsed chunks; waits for the exact requested model and cancels on observed readiness loss"
+      "normalization": "Preserves complete payloads and original parsed chunks; waits for the exact requested model and cancels on observed readiness loss. Omitted client follows installation/replacement/retirement; explicit client including null stays fixed. Inspect reports load capability separately from loaded readiness; disposal releases only an actually retained selection through its captured client. Provider/2 role state reconciles at existing operation boundaries, not through an idle state subscription."
     },
     {
       "id": "core-local-ai:createLocalAIService",
@@ -430,7 +472,7 @@
       "summary": "Composes selected native llama.cpp, Ollama and ONNX engines as a Core service with retained process/worker ownership and model lifecycle.",
       "availability": "Node with selected upstream runtime distributions or available configured system services",
       "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE, Ollama native HTTP/NDJSON and ONNX tensor transport",
-      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup; independent services, complete responses and exact owned-process cleanup"
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup. getONNXRuntime() returns the actual prepared ONNX owner for native composition after context.getService('local-ai'); callers reacquire after recovery and retain the acquired handle for cleanup. llama.status/models observe without starting or restarting an engine. Independent services, complete responses and exact owned-process cleanup remain unchanged."
     },
     {
       "id": "core-local-ai:default",
@@ -493,14 +535,14 @@
       "name": "createBrowserDecisionModel",
       "displayName": "createBrowserDecisionModel()",
       "kind": "function",
-      "signature": "createBrowserDecisionModel({family,model,revision,device,runtime})",
+      "signature": "createBrowserDecisionModel({family,model,revision,device,dtype,runtime}={})",
       "entrypoints": ["arcane-os/ai/browser-decisions"],
       "primaryImport": "arcane-os/ai/browser-decisions",
       "group": "Browser typed decisions",
-      "summary": "Explicit-load Laya FP16 and Julia-1 FP32 decisions with complete inputs and graph results.",
+      "summary": "Explicit-load Laya and Julia-1 decisions with caller-selected precision, complete inputs and graph results.",
       "availability": "Browser module Workers and the selected Transformers.js backend; import/construction starts no model load",
       "protocol": "Caller-owned state/question/options rows; five-input decision graph; native Worker request/result lifecycle",
-      "normalization": "Full field tokenization, raw logits and unrounded softmax; no policy thresholds, storage or precision fallback"
+      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged to the upstream loader; no policy thresholds, storage or precision fallback"
     },
     {
       "id": "root:acceptWebSocket",
@@ -2106,13 +2148,13 @@
       "name": "repositoryPull",
       "displayName": "repositoryPull()",
       "kind": "function",
-      "signature": "async repositoryPull({ workspaceRoot=process.cwd(), signal, onEvent, run=runProcess }={})",
+      "signature": "async repositoryPull({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})",
       "entrypoints": [
         "arcane-os"
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Runs one fast-forward-only pull after proving the selected repository worktree is clean.",
+      "summary": "Runs one fast-forward-only pull into the selected clean worktree, optionally from a captured remote/ref target.",
       "availability": "Node; network-assisted Git",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2122,13 +2164,13 @@
       "name": "repositoryPush",
       "displayName": "repositoryPush()",
       "kind": "function",
-      "signature": "async repositoryPush({ workspaceRoot=process.cwd(), signal, onEvent, run=runProcess }={})",
+      "signature": "async repositoryPush({ workspaceRoot=process.cwd(), target, signal, onEvent, run=runProcess }={})",
       "entrypoints": [
         "arcane-os"
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Pushes the selected attached branch through the repository's configured remote and credentials.",
+      "summary": "Pushes the attached branch through ordinary configured Git or an explicit captured current-HEAD destination without force.",
       "availability": "Node; network-assisted Git",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -4276,7 +4318,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently, preserves complete results/errors, cancels only request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
+      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
     },
     {
       "id": "core-stdio:encodeCoreFrame",

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

@@ -967,8 +967,9 @@
     {
       "file": "runtime/arcane/components/theme-switcher.html",
       "name": "theme-switcher.html",
-      "purpose": "Selects and refreshes system, light, dark, or custom theme mode.",
+      "purpose": "Selects and refreshes system, light, dark, or custom theme mode with per-instance choices and labels.",
       "methods": [
+        "configure()",
         "setMode()",
         "refresh()"
       ],

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

@@ -1083,7 +1083,7 @@
       "summary": "Loads and updates schema-defined app preferences through native storage with a narrow browser fallback.",
       "availability": "Browser/native hybrid",
       "protocol": "Arcane.preferences or app-scoped localStorage + per-realm globalThis.arcaneEvents authority",
-      "normalization": "Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise retains complete serial per-key compatibility, never retries a rejected dispatched batch serially, and only exact unsupported native capability changes future operations to the browser fallback.",
+      "normalization": "Complete values and operation context retained; the default adapter recognizes only exact missing preferences namespace/matching method or existing Android unsupported capability before selecting existing app-scoped localStorage. Single operations retry once after disposal/cancellation checks; partial-service and genuine failures reject unchanged. An advertised rejected batch is never retried serially, and its original rejection is preserved before later local operations.",
       "surface": "Event/error constants, default `PreferenceStore`, re-exported `Preference`/schema; load/set/setAll/reset APIs, required adapter get/set/delete plus optional setMany, state-free EventTarget/on compatibility, and `dispose()`."
     },
     {
@@ -1291,10 +1291,10 @@
       "exports": [
         "default"
       ],
-      "summary": "Reads or applies native appearance, returning an explicit unsupported browser state when no bridge exists.",
+      "summary": "Reads or applies native appearance, returning an explicit unsupported result when the bridge or optional namespace is absent.",
       "availability": "Browser/native hybrid",
       "protocol": "Arcane.appearance",
-      "normalization": "Absent bridge normalized; native result/error preserved.",
+      "normalization": "Absent bridge keeps its browser result. Exact missing appearance namespace/matching method returns supported:false with the complete original diagnostic; no platform guess or cached absence. Partial-method, permission, transport, cancellation and other genuine errors reject unchanged; available() is callable bridge presence only.",
       "surface": "default `SystemAppearance`; `available()`, `current()`, `apply()`."
     },
     {