arcane-os 0.86.1 → 0.88.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.88.0
+
+- Add optional `signal` and `startLanguageModel` controls to `AI.setAI`,
+  `configureProviders`, `transitionAI`, and `transitionProviders`, preserving
+  their existing arguments, return values, and eager default. Explicitly
+  deferred selections stay unloaded through later readiness notifications;
+  an explicit runtime load or startup can activate them.
+- Keep cancellation and supersession with the owning selection. Accepted
+  cleanup settles before a cancelled transition can configure or preload a
+  replacement, and stale continuations cannot alter a newer selection.
+  Completed activation is independent of a later caller abort.
+- Preserve truthful busy, loaded `unloading` state while an accepted request
+  finishes cancellation; new inference remains unavailable during cleanup.
+- Preserve keyboard focus in the shared theme switcher during asynchronous
+  selection. Pending choices remain focusable and expose `aria-disabled` while
+  repeated activation is ignored; completion never overrides an intentional
+  focus move. Unavailable Skin choices remain natively disabled.
+
+## 0.87.0
+
+- Add `createDocumentAcquisitionService` through
+  `arcane-os/core/document-acquisition` and `acquireCoreDocument` through
+  `arcane-os/document-acquisition`. Applications can acquire selected HTTP(S)
+  documents through their existing native Core without depending on browser
+  cross-origin access.
+- Preserve complete response bodies, requested and final URLs, response
+  metadata and ordered redirect evidence. An optional application-owned
+  destination predicate runs before each native request; domain selection and
+  document interpretation remain application policy.
+- Correlate semantic progress and cancellation with the existing Core request,
+  preserve complete error evidence, and return browser bodies as `Blob`
+  objects. Native service disposal cancels and joins its owned operations.
+  No dependency or compiled native host change is required.
+
 ## 0.86.1
 
 - Include the existing public `arcane-os/ai/model-observation` export in

package/README.md

@@ -25,7 +25,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.86.1` SDK contract. Development applications declare
+This checkout defines the `0.88.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/contracts.mjs

@@ -19,6 +19,7 @@ export const CORE_METHOD_CONTRACTS={
     'capabilities.list':{input:'empty-object',output:'{app,grants,methods}'},
     'platform.status':{input:'empty-object-v1',output:'platform-status-v1'},
     'network.status':{input:'empty-object-v1',output:'network-status-v1',meaning:'A non-loopback interface is present; this is not proof of Internet reachability.'},
+    'documents.acquire':{input:'{url}',output:'document-acquisition-result-v1',meaning:'Complete HTTP(S) GET response and redirects; native application owns any optional destination predicate. Request-scoped documents.progress events.'},
     'apps.list':{input:'empty-object-v1',output:'application-catalog-v1'},
     'apps.launch':{input:'application-launch-v1',output:'application-launch-result-v1',meaning:'Host acceptance, not application readiness.'},
     'external.open':{input:'external-open-v1',output:'external-open-result-v1',meaning:'Host acceptance, not confirmation of a user action.'},

package/browser-runtime/document-acquisition.mjs

@@ -0,0 +1,112 @@
+import Is from './dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from './core/client.mjs';
+import {CoreError, serializeCoreError} from './core/contracts.mjs';
+
+const is = new Is(false);
+
+/** Acquires one complete document through the application's installed native service. */
+export async function acquireCoreDocument({url, client = getInstalledCoreClient(), signal, onProgress} = {}) {
+    if (!is.function(client?.invoke) || !is.function(client?.events?.on)) {
+        throw new CoreError({
+            code: 'DOCUMENT_ACQUISITION_CORE_UNAVAILABLE',
+            message: 'Document acquisition requires an available native Core connection.'
+        });
+    }
+    if (!is.string(url) || url === '') {
+        throw new TypeError('Document acquisition url must be a nonempty string.');
+    }
+    if (onProgress !== undefined && !is.function(onProgress)) {
+        throw new TypeError('Document acquisition onProgress must be a function.');
+    }
+    const controller = new AbortController();
+    const operationSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    operationSignal.throwIfAborted();
+    const observers = new Set();
+    let requestId;
+    let active = true;
+    const observerErrors = [];
+
+    function retainObserverFailure(error) {
+        observerErrors.push(error);
+        controller.abort(error);
+    }
+
+    const unsubscribe = client.events.on('documents.progress', function documentProgress(progress) {
+        if (!active || operationSignal.aborted || !requestId || progress.requestId !== requestId || !onProgress) return;
+        let observation;
+        try { observation = Promise.resolve(onProgress(progress)); }
+        catch (error) { retainObserverFailure(error); return; }
+        observers.add(observation);
+        function observed() { observers.delete(observation); }
+        observation.then(observed, function failed(error) {
+            observed();
+            retainObserverFailure(error);
+        });
+    });
+
+    let result;
+    let failed = false;
+    let failure;
+    try {
+        result = await client.invoke('documents.acquire', {url}, {
+            signal: operationSignal, timeoutMs: 0,
+            onRequest(request) { requestId = request.requestId; }
+        });
+    } catch (error) {
+        failed = true;
+        failure = error;
+    } finally {
+        active = false;
+        try { unsubscribe(); } catch (error) { observerErrors.push(error); }
+        await Promise.allSettled([...observers]);
+    }
+    if (failed) failure = decodeFailure(failure);
+    let document;
+    if (!failed) {
+        const {redirects, ...response} = result;
+        document = {...decodeResponse(response), redirects: redirects.map(decodeResponse)};
+    }
+    if (observerErrors.length) {
+        const error = !failed && observerErrors.length === 1
+            ? new CoreError({...serializeCoreError(observerErrors[0]), cause: observerErrors[0]})
+            : new AggregateError(
+                failed ? [failure, ...observerErrors] : observerErrors,
+                'Document acquisition progress observers failed.',
+                failed ? {cause: failure} : undefined
+            );
+        if (document) {
+            const {requestedUrl, finalUrl, redirects, ...response} = document;
+            error.documentAcquisition = {requestedUrl, requestUrl: finalUrl, redirects, response};
+        } else if (failure?.documentAcquisition) {
+            error.documentAcquisition = failure.documentAcquisition;
+        }
+        throw error;
+    }
+    if (failed) throw failure;
+    operationSignal.throwIfAborted();
+    return document;
+}
+
+function decodeFailure(error) {
+    if (!error?.documentAcquisition) return error;
+    const {response, redirects, ...metadata} = error.documentAcquisition;
+    return new CoreError({
+        ...serializeCoreError(error),
+        documentAcquisition: {
+            ...metadata,
+            redirects: redirects.map(decodeResponse),
+            ...(response ? {response: decodeResponse(response)} : {})
+        }
+    });
+}
+
+function decodeResponse(response) {
+    const {body, ...metadata} = response;
+    if (body.encoding !== 'base64') {
+        throw new TypeError(`Unsupported document transport encoding ${body.encoding}.`);
+    }
+    const content = Uint8Array.from(globalThis.atob(body.data), function decodeCharacter(character) {
+        return character.charCodeAt(0);
+    });
+    return {...metadata, body: new Blob([content], {type: metadata.mediaType ?? ''})};
+}

package/docs/reference/README.md

@@ -71,6 +71,7 @@ alone does not make bare module names resolve in a browser.
 | Expose application-owned tools and static resources through Node STDIO | [MCP STDIO server](mcp-stdio.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
 | Observe existing renderer and Core model state, progress and failures | [Existing model observation](model-observation.md) |
+| Acquire complete HTTP(S) documents and redirect responses through an application-selected native Core service | [Native document acquisition](document-acquisition.md) |
 | Generate complete local PNG images with a retained native model | [Local image generation](local-image-generation.md) |
 | Select FLUX.2 Klein 4B and its three complementary model resources | [FLUX.2 Klein 4B through Core](local-image-flux.md) |
 | Select the complete SDXL Base 1.0 checkpoint for generation and whole-image editing | [SDXL Base 1.0 through Core](local-image-sdxl.md) |

package/docs/reference/document-acquisition.md

@@ -0,0 +1,159 @@
+# Native document acquisition
+
+`acquireCoreDocument` from `arcane-os/document-acquisition` retrieves one
+HTTP(S) document through the application's selected native Core service.
+`createDocumentAcquisitionService` from `arcane-os/core/document-acquisition`
+owns the reusable native acquisition. It performs a GET, follows redirects
+manually, and retains the complete response bodies without parsing or rewriting
+the document. Applications own source selection, document interpretation,
+enumeration, storage, and any destination predicate.
+
+## Application composition
+
+Select an application-owned native factory through the existing
+[`native.services` composition](core-native-packaging.md#explicit-application-services).
+Include its source through the application's `package.nativeResources` as
+described there. The factory runs in the native Core process; its options are
+JSON data, while its predicate is an ordinary locally imported function.
+Functions are never serialized through Core RPC.
+
+```js
+// native/documents.mjs, owned by the application
+import {createDocumentAcquisitionService} from 'arcane-os/core/document-acquisition';
+
+export default function createDocuments() {
+    return createDocumentAcquisitionService();
+}
+```
+
+```json
+{
+    "native": {
+        "services": [{"module": "native/documents.mjs"}]
+    }
+}
+```
+
+The ordinary service works without a predicate. When an application selects a
+destination restriction, its native factory supplies
+`createDocumentAcquisitionService({destinationPredicate})`. The SDK awaits
+`destinationPredicate(destinationUrl, {requestedUrl, previousUrl, signal})`
+before **every** HTTP(S) request, including the first URL and each redirect.
+Return `true` to request that destination. Any other return value declines it
+with `DOCUMENT_DESTINATION_DECLINED`. A thrown or rejected error remains the
+acquisition error's original `cause`. The predicate receives the resolved URL
+string, the caller's original URL string, the prior response URL or `null`, and
+the operation's signal. It stays local to the application's native process.
+
+An asynchronous predicate must finish or honor its signal so native shutdown
+can join it. There is no automatic retry or redirect-count limit. The caller
+can cancel its operation, including a repeating redirect chain. Redirects
+with statuses 301, 302, 303, 307, and 308 follow their `Location`, resolved
+against the response URL. A response without a redirect destination is returned
+as received. The service performs GET on each destination; it does not submit
+forms or add application credentials.
+
+## Browser API
+
+```js
+import {acquireCoreDocument} from 'arcane-os/document-acquisition';
+
+const cancellation = new AbortController();
+const document = await acquireCoreDocument({
+    url: selectedDocumentUrl,
+    signal: cancellation.signal,
+    onProgress(progress) {
+        status.textContent = progress.phase;
+    }
+});
+
+// The original entity content is available even for an HTTP error response.
+const completeContent = document.body; // Blob
+const receivedSuccessfully = document.ok;
+```
+
+The options are `{url, client?, signal?, onProgress?}`. `client` defaults to the
+installed Core client. The helper invokes `documents.acquire` with `{url}`;
+callbacks and the signal stay local. It uses existing request cancellation and
+`documents.progress` subscriptions, with no extra event bus or transport.
+There is no implicit request timeout. The caller owns any selected deadline
+through its signal.
+
+The native service must be selected by the application. An absent Core client
+reports `DOCUMENT_ACQUISITION_CORE_UNAVAILABLE`; an installed Core without the
+service returns its existing unavailable-method error. Browser-only preview
+does not acquire native capability and does not silently switch to browser
+Fetch. Portable Windows, Linux, and macOS applications use their existing Core
+transport; Android requires its host to provide this same native service.
+
+The result contains:
+
+| Field | Meaning |
+| --- | --- |
+| `requestedUrl` | Caller-supplied URL string, retained unchanged. |
+| `finalUrl` / `url` | Final response URL reported by Fetch. |
+| `status`, `statusText`, `ok` | Actual Fetch response status fields. `ok:false` is returned with its body, not replaced by a generic error. |
+| `headers` | All entries exposed by the Fetch `Headers` object, represented as `[name, value]` pairs. |
+| `mediaType` | Complete `Content-Type` field value exposed by Fetch, or `null`. |
+| `body` | Complete entity content as a `Blob` in the browser and a `Uint8Array` in native calls. |
+| `complete` | `true` after the response body reaches its end. |
+| `redirects` | Ordered preceding response records, each with `url`, status fields, headers, media type, body, and completion state. |
+
+The content is the response entity supplied by Fetch, including Fetch's normal
+content-decoding behavior. It is not a capture of compressed network framing.
+Likewise, headers reflect Fetch's casing and combination behavior; the SDK does
+not invent original wire casing or unavailable header distinctions. Document
+content is never converted to text, normalized, summarized, or wrapped in
+instructions. Query and progress metadata remain outside the content.
+
+## Progress, cancellation, and errors
+
+Progress records contain `phase`, `completed`, `total:1`, `unit:'documents'`,
+`requestedUrl`, and the current `url`. Browser records additionally contain
+the originating `requestId`. Phases are `accepted`, `destination`, `request`,
+`response`, `redirect`, and `complete`. The completed count becomes one only
+after the final response has been fully acquired, including an HTTP error
+response. Status fields, not acquisition progress, establish HTTP success.
+Progress does not measure content and carries no document body.
+
+The browser helper filters request-correlated events and removes its listener
+on every settlement. Synchronous or asynchronous progress callbacks are
+observed; all accepted callback promises settle before the helper settles.
+A callback failure cancels the request and remains observable. Simultaneous
+operation and callback failures are retained in an `AggregateError`.
+If a callback or subscription cleanup fails after the complete response has
+arrived, that response remains in the error's `documentAcquisition` evidence;
+the original callback failure remains its `cause` or an aggregated error.
+Callbacks must finish or honor the application's cancellation signal.
+
+Native acquisition errors retain the original thrown value as `cause` and
+include `documentAcquisition: {requestedUrl, requestUrl, redirects, response?}`.
+Every acquired redirect body is retained. If reading a response fails, its
+available original content is retained with `complete:false`; that record is
+explicitly incomplete. Cleanup failures remain observable alongside the
+original error. On errors delivered through Core, the browser helper restores
+the response and redirect bodies as Blobs and retains the native error record.
+
+An abort uses the existing Core client's immediate local rejection and sends
+request cancellation to the native owner. That local cancellation does not
+wait for a native error record or return its response evidence. The native
+owner cancels and joins its active response reader. Independent acquisitions
+remain concurrent, and cancelling one request leaves sibling requests active.
+Service `dispose()` aborts and joins all of that service's active operations.
+
+## Native calls and transport
+
+The synchronous factory accepts `{destinationPredicate?, signal?}` and returns
+the existing Core service definition plus
+`acquire({url, signal?, onProgress?})` and idempotent asynchronous `dispose()`.
+Direct native results and error evidence contain `Uint8Array` bodies (Node
+Buffers implement that interface). The optional factory signal controls the
+service lifetime; a per-call signal controls only that acquisition.
+
+At the JSON RPC boundary only, each body becomes
+`{encoding:'base64', data:'...'}`. One final response carries the complete result
+and ordered redirect records. The browser decodes those transport fields into
+Blobs. This path buffers complete response bodies; phase events are not a
+body stream and do not supply streaming backpressure. Existing Core lifecycle,
+request routing, and connection-close cancellation retain ownership of the
+operation through native settlement.

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

@@ -1,17 +1,45 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.86.0",
+  "sdkVersion": "0.87.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 306,
+  "memberCount": 308,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "core-document-acquisition:createDocumentAcquisitionService",
+      "name": "createDocumentAcquisitionService",
+      "displayName": "createDocumentAcquisitionService()",
+      "kind": "function",
+      "signature": "createDocumentAcquisitionService({destinationPredicate,signal}={})",
+      "entrypoints": ["arcane-os/core/document-acquisition"],
+      "primaryImport": "arcane-os/core/document-acquisition",
+      "group": "Native document acquisition",
+      "summary": "Acquires complete HTTP(S) documents in the native Core process with application-owned destination selection before every request.",
+      "availability": "Node Core on Windows, Linux and macOS; Android requires the same service through its host adaptation",
+      "protocol": "arcane/1 documents.acquire and request-correlated documents.progress; selected through the existing application-native service factory contract",
+      "normalization": "Returns name:documents, methods, acquire({url,signal,onProgress}) and idempotent asynchronous dispose(). GET follows 301/302/303/307/308 manually, awaiting the optional native destinationPredicate(url,{requestedUrl,previousUrl,signal}) before every request; only true proceeds. Omission leaves ordinary acquisition functional. Results retain requestedUrl, finalUrl/url, actual Fetch status/statusText/ok, all exposed header entries, mediaType, complete Uint8Array body and ordered complete redirect records, including non-2xx bodies. Fetch entity decoding is distinct from compressed wire framing. Errors retain their cause and complete available response evidence, with interrupted bodies marked complete:false. Independent jobs remain concurrent; cancellation stops the selected job and dispose aborts and joins all owned work. Progress is phase/document-count information, never content measurement. Base64 is used only at JSON transport; no parsing, text transformation, storage, automatic retry or application domain policy. See document-acquisition.md for composition, fields and lifecycle."
+    },
+    {
+      "id": "document-acquisition:acquireCoreDocument",
+      "name": "acquireCoreDocument",
+      "displayName": "acquireCoreDocument()",
+      "kind": "function",
+      "signature": "async acquireCoreDocument({url,client=getInstalledCoreClient(),signal,onProgress}={})",
+      "entrypoints": ["arcane-os/document-acquisition"],
+      "primaryImport": "arcane-os/document-acquisition",
+      "group": "Native document acquisition",
+      "summary": "Retrieves a complete selected document as a Blob through the application's existing native Core connection.",
+      "availability": "JavaScript with an existing Core client and explicitly composed documents service; no browser-only Fetch fallback",
+      "protocol": "documents.acquire({url}) with existing cancellation and correlated documents.progress subscriptions",
+      "normalization": "Preserves complete native response metadata and ordered redirect evidence, decoding only transport base64 into Blobs. The installed Core client is the default; unavailable Core reports DOCUMENT_ACQUISITION_CORE_UNAVAILABLE and a missing service uses the existing Core method error. The native application owns the optional destination predicate; no function crosses RPC. onProgress receives complete phase/document-count records plus requestId; accepted synchronous/asynchronous callbacks are observed and joined on settlement, listener cleanup always runs, and simultaneous operation/callback failures remain observable. The caller signal owns cancellation and any deadline; timeoutMs is disabled for the acquisition. Existing Core cancellation rejects locally and sends native cancellation without waiting for a native error evidence response. Complete bodies are buffered for one final RPC response; progress events are not streaming body backpressure. See document-acquisition.md for public usage and errors."
+    },
     {
       "id": "core-model-observation:createModelObservationService",
       "name": "createModelObservationService",

package/docs/reference/local-ai.md

@@ -267,6 +267,23 @@ owners; they are separate from this runtime service.
 
 ### Selected Ollama model readiness
 
+High-level `AI.setAI()` and `AI.transitionAI()` accept optional
+`{signal,startLanguageModel}` after their six existing preference arguments;
+`configureProviders()` and `transitionProviders()` accept it as their second
+argument. The default remains eager. `startLanguageModel:false` registers the
+built-in adapter and commits the selected provider/model without preloading it,
+including when later Ollama-ready, credential, or residency callbacks arrive.
+Activate that selection explicitly with `ai.providerRuntime.load('llm',{signal})`
+or `ai.startProviders({startLanguageModel:true,signal})`.
+
+Transition cancellation waits for accepted old-provider cleanup and prevents a
+subsequent configuration or preload. Cancellation during the first owned preload
+reaches the native request, retaining the already-committed selection and its real
+runtime state. A newer selection supersedes older pending transition work.
+Cancelled activation stays inactive through readiness callbacks; a caller abort
+after successful settlement does not unload the ready model. These selection
+controls do not change the ownership of separate callers joining an existing load.
+
 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

package/docs/reference/model-observation.md

@@ -45,6 +45,13 @@ retain their separate [app-control contract](native-app-control.md).
 
 ## Attach existing renderer owners
 
+SDK 0.86.1 adds the public `arcane-os/ai/model-observation` export to normal
+generated browser import maps. Development applications keep `arcane-os` on
+`latest`; after updating through their existing dependency workflow, run
+`arcane import-map` before building or serving. The mapping uses the same
+published browser module and changes no observation runtime behavior. Regenerate
+through the public command rather than editing map entries by hand.
+
 ```js
 import * as aiRuntimeState from 'arcane-os/ai-runtime-state';
 import {attachModelObservation} from 'arcane-os/ai/model-observation';

package/docs/reference/protocols.md

@@ -943,6 +943,21 @@ switches, or falls back implicitly. Generic provider-promise settlement is not
 a claim that underlying work stopped; only a provider's documented positive
 acknowledgement or destructive worker teardown can prove that stronger fact.
 
+High-level built-in selection has its own activation boundary:
+`AI.setAI(...sixPreferences,{signal,startLanguageModel:false})`,
+`AI.transitionAI(...sixPreferences,{signal,startLanguageModel:false})`,
+`AI.configureProviders(selections,{signal,startLanguageModel:false})`, and
+`AI.transitionProviders(selections,{signal,startLanguageModel:false})` register
+the selected adapters and keep the AI tuple and runtime routes together without
+an implicit LLM load. The omitted option remains eager. Deferred or cancelled
+activation remains inactive through later readiness callbacks; explicit runtime
+load or startup can activate that selected route. Accepted transition cleanup
+settles independently, cancellation is checked before configuring/preloading the
+replacement, and the first owned load receives the caller signal. Newer accepted
+selections supersede older pending work without allowing older continuations to
+alter the newer selection. After settlement, later caller abort does not unload
+the completed model. This does not change same-route runtime-load join ownership.
+
 `startAIRuntime({startLanguageModel:false,startTranscription:false})` is the
 explicit startup boundary for browser-WASM LLM and default STT activation. It
 leaves the selected LLM unloaded until the shared chat control publishes an

package/docs/reference/runtime-components.md

@@ -2084,8 +2084,12 @@ changing these attributes later does not reconfigure an existing instance.
 `setMode()` updates pressed state and the host's `data-mode` only. `refresh()`
 loads the existing ThemeManager state, updates selection and Skin availability,
 and resolves with the complete manager state. Clicking a choice uses the same
-manager persistence/activation operation; buttons remain disabled while that
-operation is pending. Presentation configuration preserves that pending state.
+manager persistence/activation operation. While it is pending, choices expose
+`aria-disabled="true"` and ignore repeated activation while remaining in the
+keyboard focus flow. Native disabling remains for an unavailable Skin choice.
+Selection does not move focus when it completes or fails, so the initiating
+button retains focus unless the user moves elsewhere. Presentation configuration
+preserves that pending state; an actual reorder retains its focus behavior above.
 
 The host inherits text color. Existing `--app-bar-border` (falling back to
 `--border-color`), `--app-bar-accent` (then `--secondary-color`),

package/docs/reference/runtime-modules.md

@@ -257,10 +257,41 @@ provider. `transitionAI()` and `transitionProviders()` are deliberate
 cross-role transitions: each stops queued audio, unloads the current LLM, STT,
 and TTS roles, then applies the replacement configuration. `transitionAI()`
 returns aggregate runtime status; `transitionProviders()` returns the configured
-three-role route configuration. Selected TWiN Cloud `TWIN` LLM, `OLLAMA` LLM,
-and Core `LOCAL_SPEACH` STT/TTS built-in routes expose truthful capability-only
-readiness through internal provider/2 adapters without probing, downloading, or
-hiding a load. Explicit speech preference slots remain unchanged, including a
+three-role route configuration.
+
+`setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and
+`transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)`
+preserve their six positional preference arguments. `configureProviders(selections,options)`
+and `transitionProviders(selections,options)` accept the same optional
+`{signal=null,startLanguageModel=true}` controls. Omission preserves eager built-in
+LLM activation. `startLanguageModel:false` still registers built-in adapters and
+updates both the runtime routes and AI preference tuple, while leaving the selected
+LLM unloaded. Readiness events, credential changes, and native residency observations
+retain that deferred intent; an explicit `providerRuntime.load('llm',{signal})` or
+`startProviders({startLanguageModel:true,signal})` can activate it. Deferral never
+changes the selected model or substitutes another provider.
+
+An already-aborted signal rejects before selection changes. During an asynchronous
+transition, accepted old-provider cleanup finishes, then cancellation prevents new
+configuration or preload. A newer accepted selection supersedes pending older
+transition work; older completion cannot configure, load, or clean up the newer
+selection. Once replacement routes are committed, cancellation reaches the first
+owned load and leaves that replacement explicitly selected with its actual runtime
+state. Later readiness callbacks do not restart the cancelled activation. Completed
+selection/load settlement detaches its caller signal, so later abort never unloads
+the ready model. `setAI()` retains its synchronous boolean and `configureProviders()`
+its synchronous route result; their asynchronous readiness remains observable through
+the provider runtime. Rejected synchronous configuration preserves the prior owned
+selection/load. A selection accepted by a synchronous registration or configuration
+listener supersedes the older continuation before it can apply preferences or load.
+These controls do not change cancellation ownership for a
+separate caller joining an already-pending runtime load.
+
+Selected TWiN Cloud `TWIN` LLM, `OLLAMA` LLM,
+and Core `LOCAL_SPEACH` STT/TTS built-in routes use internal provider/2 adapters.
+TWiN Cloud and Core speech expose capability readiness; Ollama explicitly
+preloads its selected model and confirms its residency before reporting ready.
+Explicit speech preference slots remain unchanged, including a
 selected external provider that the application registers after AI startup.
 TWiN Cloud availability
 requires the selected LLM route, its model, a credential, and `fetch`; Core speech

package/docs/reference/sdk-api.md

@@ -57,6 +57,8 @@ runtime layouts.
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
 | `arcane-os/core/model-observation` | Passive observation of an existing Core and its actual native model service owners. |
 | `arcane-os/ai/model-observation` | Attach existing renderer model owners and subscribe through an existing Core client. |
+| `arcane-os/document-acquisition` | Acquire complete document and redirect bodies through the selected native Core service. |
+| `arcane-os/core/document-acquisition` | Native HTTP(S) GET service, application-owned destination predicate and acquisition lifecycle. |
 | `arcane-os/core/development` | App-service composition and document-owned Core transport during source development, independently of local AI. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
 | `arcane-os/core/host` | Node-only reusable Core host lifecycle, app-selected native launch defaults and shared native location resolution. |
@@ -425,6 +427,8 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `createModelObservationService()` | function | `arcane-os/core/model-observation` | Existing model observation | Node with an existing Core runtime and optional existing native model services |
 | `attachModelObservation()` | function | `arcane-os/ai/model-observation` | Existing model observation | JavaScript with an existing Core client and optional existing renderer owners |
 | `subscribeModelObservation()` | function | `arcane-os/ai/model-observation` | Existing model observation | JavaScript with an existing Core client and composed observation service |
+| `acquireCoreDocument()` | function | `arcane-os/document-acquisition` | Native document acquisition | Browser or native WebView with an existing Core client and selected document service |
+| `createDocumentAcquisitionService()` | function | `arcane-os/core/document-acquisition` | Native document acquisition | Node Core on Windows, Linux and macOS; Android requires host adaptation |
 | `encodeCoreFrame()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
 | `createCoreFrameDecoder()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
 | `startCoreStdio()` | function | `arcane-os/core/stdio` | Native Core stdio transport | Node |
@@ -7671,6 +7675,64 @@ promises may await `close()` without becoming its completion barrier. It starts
 no model, refresh, polling, endpoint discovery, host or reconnect. See
 [observation records and limits](model-observation.md#read-or-subscribe-from-an-existing-client).
 
+## acquireCoreDocument()
+
+```text
+acquireCoreDocument({url,client,signal,onProgress}={})
+```
+
+Import from `arcane-os/document-acquisition`. The asynchronous helper uses the
+supplied or installed Core client to invoke `documents.acquire` with `{url}`.
+The application must compose the native document service. Missing Core reports
+`DOCUMENT_ACQUISITION_CORE_UNAVAILABLE`; a missing service retains the existing
+unavailable-method error. Browser-only previews have no browser Fetch fallback.
+
+Resolves with `{requestedUrl,finalUrl,url,status,statusText,ok,headers,mediaType,
+body,complete,redirects}`. The final body and every ordered redirect body are
+complete `Blob` values. An HTTP error response retains its status and content;
+`ok:false` is a result, not a generic acquisition error. Headers and entity
+content reflect Fetch's public response, including ordinary content decoding.
+
+`signal` cancels this request; there is no implicit timeout. `onProgress` receives
+request-correlated `documents.progress` records with phases, document counts
+and status fields, never body content. All accepted callback promises settle
+before the helper settles. Callback failures cancel acquisition and remain
+observable; concurrent operation and callback failures retain an `AggregateError`.
+A late callback or subscription cleanup failure retains the completed response
+in `error.documentAcquisition` with the original cause or aggregated failures.
+Every settlement removes the subscription. Local abort rejects immediately and
+does not wait for native error evidence. See
+[complete result, progress and error records](document-acquisition.md).
+
+## createDocumentAcquisitionService()
+
+```text
+createDocumentAcquisitionService({destinationPredicate,signal}={})
+```
+
+Import from `arcane-os/core/document-acquisition`. This synchronous factory
+returns the Core service definition with `documents.acquire`, direct
+`acquire({url,signal,onProgress})` and idempotent asynchronous `dispose()`.
+Select it through the application's existing native service composition. The
+ordinary service performs HTTP(S) GET acquisition without a predicate.
+
+An application-selected `destinationPredicate(destinationUrl,
+{requestedUrl,previousUrl,signal})` runs locally before every actual GET,
+including the first destination and each redirect. Only `true` permits the
+request; other returns produce `DOCUMENT_DESTINATION_DECLINED`, and a thrown
+or rejected value remains the original cause. The predicate is never serialized.
+Redirects retain every response body; no automatic retry or redirect-count cap
+is imposed. The caller can cancel a repeating redirect chain.
+
+Direct results and error evidence retain `Uint8Array` bodies. Acquisition errors
+keep the original cause and `documentAcquisition` response/redirect records;
+an interrupted body read retains available content marked `complete:false`.
+Only Core JSON transport encodes bodies as base64; the browser restores Blobs.
+The factory signal owns the service lifetime; each call signal owns only its
+request and leaves sibling acquisitions active. `dispose()` aborts and joins all
+active operations. Bodies are buffered completely; progress is not a body stream.
+See [native composition and lifecycle](document-acquisition.md).
+
 ## createPortableNativeProvider()
 
 ### Overview