arcane-os 0.1.0-dev.5

package/docs/reference/core/arcane-ai-contracts.md

@@ -0,0 +1,873 @@
+# Arcane AI Data Contracts
+
+This reference defines the request and result objects used by Arcane's
+provider-neutral AI, local AI, speech, isolated-inference, and direct Ollama
+APIs. Start with the method index in the [Arcane API Reference](arcane-api.md).
+
+The type names below are documentation notation for plain JavaScript values.
+They are not TypeScript declarations.
+
+## Contract conventions
+
+| Input style | Unknown keys | Object rules |
+|---|---|---|
+| Exact record | Rejected | A plain object with exactly the documented own data properties. Every field is required unless marked optional. Arrays, accessors, symbol keys, and non-plain objects are rejected. |
+| Closed object | Rejected at the documented level | A plain object containing only the documented top-level keys. Provider-native nested values may have additional provider-defined structure. |
+| Settings object | Currently ignored | A plain object whose documented keys are read. Callers should still send only documented keys. |
+
+`Required` means the caller must supply the field. `Conditional` means the field
+is required only under the condition in its constraints. A safe integer passes
+`Number.isSafeInteger`. Byte limits use UTF-8 unless a row says characters,
+encoded text, or decoded bytes.
+
+Authorization and host admission occur before method-specific validation. An
+unauthorized caller can therefore receive a capability or host error before an
+input error. Rejections use `Arcane.Error`; never parse its human-readable
+message as a protocol value.
+
+These rows define the portable caller contract. Some provider-settings and
+speech validators currently coerce or ignore particular off-contract values
+differently on desktop Core and Android. Callers must send the documented types
+and keys and must not depend on permissive host behavior or uniform rejection of
+invalid input. The provider-neutral AI, local-AI, speech, and direct Ollama
+methods in this document currently use method-local validators rather than
+canonical entries in `method-contracts.json`; catalog metadata must not invent
+semantic attributes that the registry does not define.
+
+## Provider-neutral AI
+
+### AI chat request
+
+`Arcane.ai.chat(request)` accepts a closed `AIChatRequest`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `messages` | [`AIChatMessage[]`](#ai-chat-message) | Yes | 1-128 records; combined content at most 512 KiB | Conversation sent to the configured provider. |
+| `expectedProvider` | `"ollama" \| "openai"` | No | Omitted means no caller-side provider binding | Rejects with `AI_PROVIDER_CHANGED` when the configured provider changed before dispatch. |
+| `format` | `"json" \| "" \| null` | No | Omit, `null`, or `""` for text | Portable output-format control. |
+| `model` | `string` | No | Local model pattern `[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}` | Local Ollama override. The OpenAI path always uses the configured, account-validated model. |
+| `options` | JSON object | No | Ollama only | Provider-native generation options. |
+| `tools` | JSON array | No | Ollama only | Provider-native tool definitions. |
+| `keep_alive` | JSON value | No | Ollama only | Provider-native model-residency control. |
+| `think` | JSON value | No | Ollama only | Provider-native reasoning control. |
+| `logprobs` | JSON value | No | Ollama only | Provider-native log-probability control. |
+| `top_logprobs` | JSON value | No | Ollama only | Provider-native log-probability count. |
+
+For a provider-portable request, send only `messages`, optional
+`expectedProvider`, and optional `format`.
+
+```js
+const profile = await Arcane.ai.profile();
+
+const result = await Arcane.ai.chat({
+  expectedProvider: profile.provider,
+  messages: [
+    { role: "system", content: "Answer briefly and accurately." },
+    { role: "user", content: "What models are available?" }
+  ]
+});
+```
+
+### AI chat message
+
+Every `AIChatMessage` is an exact record.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `role` | `"system" \| "user" \| "assistant"` | Yes | Exact lowercase value | Message author role. |
+| `content` | `string` | Yes | Nonempty; at most 131,072 characters | Message text. |
+
+No other message fields are accepted.
+
+### AI chat result
+
+`AIChatResult` is normalized across configured Ollama and OpenAI chat.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"arcane-ollama" \| "openai"` | Yes | - | Provider that completed the request. |
+| `model` | `string` | Yes | Bounded provider model identifier | Model used for the response. |
+| `message.role` | `"assistant"` | Yes | - | Normalized response role. |
+| `message.content` | `string` | Yes | At most 4 MiB retained | Assistant response text. |
+| `message.thinking` | `string` | No | Ollama only; at most 4 MiB retained | Provider reasoning text when present. |
+| `message.toolCalls` | `array` | No | Ollama provider-native records | Tool calls when present. |
+| `done` | `boolean` | Yes | OpenAI returns `true` | Completion flag. |
+| `doneReason` | `string \| null` | Yes | At most 128 characters | Completion reason. |
+| `promptEvalCount` | `integer \| null` | Yes | Nonnegative when present | Prompt token/evaluation count. |
+| `evalCount` | `integer \| null` | Yes | Nonnegative when present | Completion token/evaluation count. |
+
+### AI profile
+
+`Arcane.ai.profile()` returns `AIProfile`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"ollama" \| "openai"` | Yes | - | Selected provider. |
+| `model` | `string` | Yes | Effective configured model | Model used by provider-neutral chat. |
+| `configured` | `boolean` | Yes | - | Required provider configuration is present. |
+| `local` | `boolean` | Yes | `true` only for Ollama | Whether inference remains local. |
+| `responseLength` | `"low" \| "medium" \| "high"` | Yes | Legacy invalid/missing state resolves to `"medium"` | Conversational response target, not a provider token limit. |
+
+An OpenAI profile is returned only after Arcane proves a protected credential
+exists and the configured model is available to that account.
+
+### AI provider settings input
+
+`Arcane.ai.saveProviderSettings(settings)` reads the documented fields from an
+`AIProviderSettingsInput` patch. Omitted keys preserve the current value. Send
+only these keys and the documented value types; do not rely on a host ignoring
+unknown fields or coercing `removeToken`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"ollama" \| "openai"` | No | Current provider | Provider to select. |
+| `openAIModel` | `string` | Conditional | Pattern `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`; required for OpenAI | Account-accessible OpenAI model. |
+| `responseLength` | `"low" \| "medium" \| "high"` | No | Current value | Conversational response target. |
+| `token` | `string` | No | Trimmed, starts with `sk-`, 20-512 characters | Replacement OpenAI credential. It is protected and never returned. |
+| `removeToken` | `boolean` | No | Only `true` requests deletion | Removes the stored credential. A supplied `token` becomes the final credential. |
+
+Arcane verifies the selected OpenAI model when OpenAI is selected and validates
+a supplied replacement credential before persistence. Ollama-selected settings
+may retain a dormant OpenAI model; Arcane revalidates it before a later switch
+to OpenAI. Credential and settings mutations are rolled back together when
+possible if the save fails.
+
+### AI provider settings result
+
+`Arcane.ai.providerSettings()` and a successful save return
+`AIProviderSettingsResult`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"ollama" \| "openai"` | Yes | - | Selected provider. |
+| `openAIModel` | `string` | Yes | May be empty when OpenAI is not selected | Saved OpenAI model. |
+| `openAIConfigured` | `boolean` | Yes | - | A protected credential exists. |
+| `responseLength` | `"low" \| "medium" \| "high"` | Yes | - | Saved response target. |
+
+Credentials are never included.
+
+### Local AI inventory
+
+`Arcane.ai.models()` returns `LocalAIInventory`, not a bare array. This is raw
+diagnostic inventory, not the admitted application selector catalog.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"arcane-ollama"` | Yes | - | Catalog source. |
+| `models` | `OllamaInventoryModel[]` | Yes | At most 512 records | Normalized installed inventory. |
+
+Each `OllamaInventoryModel` contains:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `name` | `string` | Yes | Local model-name pattern | Installed model identifier. |
+| `modifiedAt` | `string \| null` | Yes | At most 64 characters | Provider timestamp when available. |
+| `sizeBytes` | `integer \| null` | Yes | Nonnegative safe integer | Installed size when valid. |
+| `digest` | `string \| null` | Yes | Lowercase 64-character hexadecimal digest | Model digest when valid. |
+| `family` | `string \| null` | Yes | At most 128 characters | Provider-reported family. |
+| `parameterSize` | `string \| null` | Yes | At most 64 characters | Provider parameter-size label. |
+| `quantization` | `string \| null` | Yes | At most 64 characters | Provider quantization label. |
+
+### AI provider model catalog
+
+`Arcane.ai.providerModels()` returns `AIProviderModelCatalog` after querying the
+protected OpenAI credential's account.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `provider` | `"openai"` | Yes | - | Catalog source. |
+| `models` | `string[]` | Yes | Each value matches the OpenAI model pattern | Sorted account-accessible identifiers. |
+
+This method can perform a network request. It does not return Ollama models.
+
+## Local AI discovery and lifecycle
+
+### Local AI status v2
+
+`Arcane.localAI.status()` takes no arguments and returns `LocalAIStatusV2`.
+Concurrent callers in one Core process can share the same active discovery.
+An admitted development Android provider uses the same schema version with the
+exact `user-managed-loopback` discriminator described below.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `schemaVersion` | `2` | Yes | Literal | Status schema. |
+| `providerMode` | `"user-managed-loopback"` | Android only | Omitted by desktop Core | Identifies the narrow Android provider without changing `Arcane.runtime.current().managedLocalAI`, which remains false. |
+| `runtime` | object | Yes | Desktop Core or bounded Android provider identity | Runtime authority and whether desktop native resource admission is active. |
+| `policy` | object | Yes | See below | Package-bound model policy. |
+| `ollama` | object | Yes | See below | Ollama discovery state. |
+| `admission` | object | Yes | See below | Native-admission summary. |
+| `speech` | object | Yes | See below | Independent speech readiness. |
+| `models` | object | Yes | `{ollama, speech, transcription}` arrays | Admitted catalogs. |
+
+`policy` fields:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `verified_only` | `boolean` | Yes | Package policy | Whether only declared verified models are considered. |
+| `source` | `"package-bound-application-policy"` | Yes | Literal | Policy source. |
+| `unverifiedInferenceAuthorized` | `boolean` | Yes | Requires explicit package authority | Whether installed unverified models may be considered for inference. |
+
+`ollama` fields:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `available` | `boolean` | Yes | - | Core obtained a valid bounded catalog. |
+| `modelCapabilitiesVerified` | `boolean` | Yes | - | Capability discovery completed. |
+| `nativeAdmissionEnforced` | `boolean` | Yes | `true` for desktop Core; `false` for Android user-managed loopback | Whether desktop native resource admission is enforced. Android still applies its generated package-policy and provider-inspection boundary. |
+| `activeParallelRequests` | `integer` | Desktop Core | Positive safe integer | Current machine-wide managed Ollama parallel request count used for active-fit evidence. |
+| `errorCode` | `string \| null` | Yes | Normalized code | Discovery failure code. |
+
+`admission` fields:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `policyVersion` | `integer` | Yes | Currently `1` | Resource-policy version. |
+| `enforcedBy` | `string` | Yes | Bounded host-owned identifier | Admission authority; renderers must not interpret it as reusable authorization. |
+| `evaluatedModels` | `integer` | Yes | Nonnegative | Candidate count evaluated. |
+| `admittedModels` | `integer` | Yes | 0 through `evaluatedModels` | Candidate count admitted at one parallel request. A model can still have `runnable:false` when the active machine-wide parallel count exceeds its current model-specific ceiling. |
+| `rejected` | `array` | Yes | `{id, compatibility}` records | Rejected candidates and admission evidence. |
+
+`speech` fields:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `available` | `boolean` | Yes | - | Synthesis or transcription is available. |
+| `reachable` | `boolean` | Yes | - | Core validated the health endpoint. |
+| `synthesisAvailable` | `boolean` | Yes | - | Kokoro readiness. |
+| `transcriptionAvailable` | `boolean` | Yes | - | Whisper readiness. |
+| `synthesisErrorCode` | `string \| null` | Yes | - | Synthesis failure/readiness code. |
+| `transcriptionErrorCode` | `string \| null` | Yes | - | Transcription failure/readiness code. |
+| `errorCode` | `string \| null` | Yes | - | Overall speech failure code. |
+
+`models.ollama` contains [`LocalAIModel`](#local-ai-model) records.
+`models.speech` and `models.transcription` contain
+[`LocalAIServiceModel`](#local-ai-service-model) records. An unavailable service
+resolves as service-local status data where possible; it never silently changes
+providers.
+
+For `providerMode:"user-managed-loopback"`, the Android host calls only the
+fixed `127.0.0.1:11434` Ollama service and fixed host-owned loopback speech
+service. It returns only installed package-policy models that passed its bounded
+provider inspection, repeats model admission before `ollama.chat`, and merges
+the independently bounded Kokoro and Whisper role health and catalogs. The host
+does not expose recovery or model mutation. The renderer never calls either
+loopback API directly.
+
+Android Linux Terminal, Ollama, and every model lifecycle action remain user-owned. Plain
+loopback Ollama has no caller authentication; other local applications or
+processes may call it, race the host's checks, contend for resources, or deny
+service. This is unsigned development behavior, not release support, managed
+service ownership, or an isolated-inference guarantee. Android exposes no
+application-owned isolated-question or repository extension unless generated
+package and method policy explicitly admit it.
+
+### Local AI model
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `id`, `name` | `string` | Yes | Equal model identifiers | Snapshot selection identifier and Ollama name. |
+| `provider` | `"ollama"` | Yes | Literal | Provider. |
+| `roles` | `array` | Yes | Currently empty | Reserved role catalog. |
+| `managed` | `boolean` | Yes | - | Declared by package policy. |
+| `installed` | `boolean` | Yes | - | Runnable alias or authorized model is installed. |
+| `admitted` | `true` | Yes | Literal | Current serial-fit admission. This is not proof that the active parallel setting fits. |
+| `runnable`, `creatable`, `pullable`, `verified` | `boolean` | Yes | - | Managed lifecycle state. `runnable:false` can mean the active parallel setting exceeds the model's current ceiling. |
+| `capabilitiesVerified`, `available` | `true` | Yes | Literal | Capability and availability proof. |
+| `modifiedAt` | `string \| null` | Yes | - | Installed timestamp. |
+| `sizeBytes` | `integer \| null` | Yes | Nonnegative safe integer | Model size. |
+| `digest` | `string \| null` | Yes | 64-character hexadecimal value | Installed digest. |
+| `family`, `parameterSize`, `quantization` | `string \| null` | Yes | Bounded diagnostic strings | Provider metadata. |
+| `compatibility` | [`ModelResourceAdmission`](#model-resource-admission) | Yes | `admitted:true` | Native resource and definition evidence. |
+
+This record is snapshot evidence, not reusable authorization. Core re-admits the
+exact model and requested context before inference.
+
+### Local AI service model
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `id` | `"kokoro" \| "whisper-small"` | Yes | - | Model identifier. |
+| `name` | `"Kokoro" \| "Whisper Small"` | Yes | - | Display name. |
+| `provider` | `"speech"` | Yes | Literal | Service provider. |
+| `roles` | `["tts"] \| ["stt"]` | Yes | One role | Supported operation. |
+| `available` | `true` | Yes | Literal | Availability in this snapshot. |
+| `engine` | `string` | Yes | Health-validated identifier | Native engine. |
+
+### Model resource admission
+
+`ModelResourceAdmission` is a union. Early failures can omit diagnostic fields;
+callers must not assume every field exists.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `policyVersion` | `integer` | Yes | Currently `1` | Resource-policy version. |
+| `admitted` | `boolean` | Yes | - | Current fit decision. |
+| `status` | `"compatible" \| "incompatible" \| "evidence-unavailable"` | Yes | - | Admission classification. |
+| `code` | `string \| null` | Yes | `null` on success | Stable result code. |
+| `message` | `string` | Yes | At most 512 characters | Human-readable result. |
+| `resolution` | `string \| null` | Yes | At most 512 characters | Suggested remediation. |
+| `operation` | `"inference" \| "create" \| "pull"` | No | Evidence-dependent | Evaluated operation. |
+| `model` | `string` | No | At most 256 characters | Evaluated model. |
+| `modelBytes`, `downloadBytes`, `contextTokens`, `nativeContextTokens`, `kvCacheBytes` | `integer \| null` | No | Positive when present | Model, transfer, requested/native context, and K/V-cache evidence. |
+| `parallelism` | `integer` | No | Positive safe integer | Parallel request count evaluated by this admission record. |
+| `activeParallelRequests` | `integer` | No | Positive safe integer | Current machine-wide managed Ollama setting observed for the snapshot. |
+| `maxAllowedParallelRequests` | `integer \| null` | No | `null`, 0, or a positive safe integer | Largest count admitted by the same immutable model/resource snapshot. It is solved directly from the model's K/V-cache equation and available working-set bytes, without a product ceiling. `null` means evidence was unavailable; `0` means even one request was proven memory-incompatible. |
+| `activeParallelRequestsAllowed` | `boolean \| null` | No | - | Whether the active count is within `maxAllowedParallelRequests`; `null` preserves unknown evidence. |
+| `runtimeHeadroomBytes`, `requiredWorkingSetBytes` | `integer` | No | Positive | Derived working-set requirements. |
+| `requiredAdditionalBytes`, `availableWorkingSetBytes` | `integer` | No | Nonnegative | Additional requirement and available capacity. |
+| `loadedModelBytes`, `targetResidentBytes` | `integer` | No | Nonnegative | Current residency evidence. |
+| `checks` | [`ModelResourceCheck[]`](#model-resource-checks) | No | - | Individual capacity checks. |
+| `definitionVerified`, `baseModelInstalled`, `creationRequired`, `pullRequired` | `boolean` | No | Managed workflows | Managed lifecycle evidence. |
+| `registryEvidence` | object | No | Opaque diagnostic shape | Preflight detail; never an authorization token. |
+
+Other bounded diagnostics may appear on failures. Branch on `admitted`,
+`status`, and `code`; treat additional evidence as display-only.
+
+### Model resource checks
+
+A working-set `ModelResourceCheck` contains:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `id` | `"working-set"` | Yes | Literal | Check identifier. |
+| `ok` | `boolean` | Yes | - | Pass/fail result. |
+| `requiredBytes`, `totalRequiredBytes`, `availableBytes` | `integer` | Yes | Nonnegative | Required additional, required total, and available bytes. |
+| `systemFreeBytes`, `systemReserveBytes`, `usableSystemBytes` | `integer` | Yes | Nonnegative | System-memory evidence. |
+| `usableGpuBytes`, `loadedModelBytes`, `targetResidentBytes` | `integer` | Yes | Nonnegative | Accelerator and residency evidence. |
+
+A pull may add a `"model-store"` check with `ok`, `requiredBytes`,
+`availableBytes`, `storageFreeBytes`, and `storageReserveBytes`.
+
+Admission proves only current fit. It does not prove safety, output quality,
+license, provenance, supplier identity, future capacity, or stability under
+later concurrent workloads.
+
+### Local AI platform result
+
+`Arcane.localAI.ensurePlatform()` takes no arguments. It is a Provisioner-only,
+exclusive post-install reconciliation. It retries when settings change during
+the operation and rejects with `ARCANE_AI_PROFILE_CHANGED` after three stale
+plans instead of overwriting newer settings.
+
+`LocalAIPlatformResult` always contains an [`ArcaneOperation`](#arcane-operation)
+and one of these branches.
+
+OpenAI-selected branch:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `local` | object | Yes | `{available:false, reason:"openai-selected"}` | Local reconciliation was intentionally skipped. |
+| `fallback.provider` | `"openai"` | Yes | Literal | Explicit selected provider. |
+| `fallback.model` | `string` | Yes | Protected-credential account-validated model | Selected OpenAI model. |
+| `fallback.configured` | `true` | Yes | Literal | Required credential and model are valid. |
+| `loaded` | object | Yes | `{loaded:false, provider:"openai", model}` | No local model was loaded. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Exclusive operation receipt. |
+
+Local branch:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `local.available` | `true` | Yes | Literal | Local AI is available. |
+| `local.model` | `string` | Yes | Managed selected model | Ready model definition. |
+| `local.alias` | `string` | Yes | Managed alias | Selected runtime alias. |
+| `local.variant` | `string` | Yes | Arcane model variant | Selected size. |
+| `local.compatibility` | [`ModelResourceAdmission`](#model-resource-admission) | Yes | `admitted:true` | Final native admission. |
+| `local.recommendationDegraded` | `boolean` | Yes | - | Automatic selection used a smaller candidate after capacity rejection. |
+| `local.candidateFailures` | `array` | Yes | Empty unless an earlier automatic candidate failed | Bounded prior failures. |
+| `fallback` | `null` | Yes | - | Arcane did not silently change providers. |
+| `loaded` | object | Yes | See below | Managed boot-load result. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Exclusive operation receipt. |
+
+Each candidate failure is `{variant, kind, code, message, resolution}`. `kind`
+is `"capacity"`, `"evidence-unavailable"`, or `"fatal"`; only a capacity
+failure allows Automatic mode to try the next smaller candidate.
+
+`loaded` is a union. Both branches contain `loaded`, `provider`, and `model`.
+The successful local branch also contains `keepAlive` and `contextLength`, where
+`contextLength:null` means Automatic.
+
+### Local AI recovery request
+
+`Arcane.localAI.recover(request)` accepts an exact `LocalAIRecoveryRequest`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `services` | `string[]` | Yes | Nonempty, duplicate-free subset of `"ollama"` and `"speech"` | Existing Arcane-managed services to start and verify. |
+
+### Local AI recovery result
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `ready` | `true` | Yes | Literal | All requested services are ready. |
+| `services` | `array` | Yes | Canonical Ollama-then-speech order | Per-service results. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Privileged exclusive operation. |
+
+Every service result is exact:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `id` | `"ollama" \| "speech"` | Yes | - | Service identifier. |
+| `serviceName` | `"ArcaneOllama" \| "ArcaneLocalSpeech"` | Yes | - | Operating-system service name. |
+| `endpoint` | `string` | Yes | Fixed `127.0.0.1` health/version endpoint | Verified loopback endpoint. |
+| `state` | `"running"` | Yes | Literal | Verified state. |
+| `ready` | `true` | Yes | Literal | Readiness proof. |
+| `started` | `boolean` | Yes | - | This request issued the start. |
+
+Recovery starts an existing approved registration. It does not install,
+replace, stop, or silently reconfigure a service.
+
+### Local AI parallel request configuration
+
+`Arcane.localAI.setParallelRequests(request)` accepts an exact
+`LocalAIParallelRequestsRequest`:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | `string` | Yes | Exact app-owned verified model identifier | Model whose declared definition and native metadata govern the calculation and subsequent load. |
+| `parallelRequests` | `integer` | Yes | Nonnegative safe integer | `0` requests the maximum currently allowed; a positive value is a requested ceiling and is clamped down when necessary. |
+| `contextTokens` | `integer` | No | Positive safe integer; defaults to verified Modelfile `num_ctx` | Exact per-request context evaluated and used to load the model. The model's native metadata, rather than an Arcane product range, supplies the maximum. |
+
+A successful `LocalAIParallelRequestsResult` contains:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `schemaVersion` | `1` | Yes | Literal | Result schema. |
+| `model` | `string` | Yes | Exact verified alias | Model ensured and loaded. |
+| `contextTokens`, `nativeContextTokens` | `integer \| null` | Yes | Positive safe integers when present | Requested context and model-native limit when metadata provides one. |
+| `requestedParallelRequests` | `integer` | Yes | Nonnegative safe integer | Caller input. |
+| `requestMode` | `"maximum-allowed" \| "requested-ceiling"` | Yes | Derived from input | Interpretation of the request. |
+| `previousParallelRequests` | `integer` | Yes | Positive safe integer | Proven setting before the operation. |
+| `maxAllowedParallelRequests` | `integer` | Yes | Positive safe integer | Largest count admitted by the resource state used for the effective decision. A changed path uses a fresh stopped-service snapshot. |
+| `allowedParallelRequests`, `effectiveParallelRequests` | `integer` | Yes | Positive safe integers; equal | Clamped target and proven effective count used for the load. |
+| `requestedAllowed`, `clamped` | `boolean` | Yes | - | Whether a positive request fit without reduction and whether reduction occurred. Auto (`0`) is allowed and is not called clamped. |
+| `changed`, `restarted` | `boolean` | Yes | - | Whether the final service setting changed and whether the managed service actually restarted. A resource change observed after stopping can make `restarted:true` and `changed:false`; the receipt reports both facts independently. |
+| `healthy`, `loaded` | `true` | Yes | Literal | Post-operation service and model readiness. |
+| `loadedModel` | object | Yes | `{name,contextLength}` | Bounded `/api/ps` confirmation; provider-reported `contextLength` may represent runner allocation. |
+| `serviceScope` | `"machine"` | Yes | Literal | The Ollama setting is global even though Arcane selected it from one model's evidence. |
+| `unloadedModels` | `string[]` | Yes | Bounded pre-restart identifiers | Resident models evicted by the restart; empty on a no-op. |
+| `definitionVerified` | `true` | Yes | Literal | Exact alias was verified after any required create/repair. |
+| `modelSource` | `"verified-alias" \| "installed-base" \| "registry-preflight"` | Yes | - | Evidence source used for the pre-change capacity calculation. |
+| `admission` | [`ModelResourceAdmission`](#model-resource-admission) | Yes | `admitted:true` | Fresh active-setting admission after ensure/repair and before load. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Privileged exclusive operation receipt. |
+
+Core snapshots one exact model/resource state and solves the maximum directly
+from the model metadata's K/V-cache byte ratio and the snapshot's available
+working-set bytes. There is no candidate-count search and no Arcane product
+ceiling. The largest exact integer representable by the JavaScript/JSON API is a
+transport constraint, not a model-capacity claim. The result is a current
+memory/resource admission with explicit reserves, not a performance optimum or
+a promise of future availability. If the tentative target already equals the
+current setting, Core does not stop Ollama. Otherwise the guarded transaction
+stops and proves the service, takes one fresh stopped-service resource snapshot,
+re-solves the effective count, changes only `OLLAMA_NUM_PARALLEL` when that final
+count differs, and starts/proves the service. This unloads every resident Ollama
+model and can terminate in-flight local inference.
+It then ensures or repairs the exact alias, loads it with the requested context
+and indefinite residency, and returns only after `/api/ps` confirms the model.
+If loading fails after a setting change, Core attempts to restore the prior count.
+The operation does not drain unrelated Core processes or direct loopback clients.
+Automatic mutation is currently implemented only by the managed Microsoft NT
+adapter. Linux validates the request but returns a `501` manual-systemd error;
+Android's user-managed loopback mode does not invoke this desktop Core method.
+
+### Arcane operation
+
+Successful mutating AI methods include `ArcaneOperation`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `id` | `string` | Yes | UUID | Operation identifier. |
+| `type` | `string` | Yes | Method-specific | Operation type. |
+| `status` | `string` | Yes | Successful returned operations are `"completed"` | State. |
+| `startedAt` | ISO timestamp `string` | Yes | - | Start time. |
+| `completedAt` | ISO timestamp `string \| null` | Yes | Present on completion | Completion time. |
+| `progress` | `number` | Yes | 0-100; success is 100 | Latest progress. |
+| `currentStep` | `string \| null` | Yes | - | Latest visible step. |
+| `progressDetails` | `object \| null` | Yes | Operation-specific | Structured progress. |
+| `credentials` | `array` | Yes | Normally empty for AI lifecycle work | Host-issued credential artifacts, if any; do not log or persist them. |
+| `error` | `object \| null` | Yes | `null` on success | Normalized operation error. |
+
+## Speech
+
+### Speech status
+
+`Arcane.speech.status()` takes no arguments and returns `SpeechStatus`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `ready` | `boolean` | Yes | `true` only when TTS and STT are ready | Aggregate readiness. |
+| `synthesisAvailable` | `boolean` | Yes | Core/native-host field | Independent Kokoro readiness. |
+| `transcriptionAvailable` | `boolean` | Yes | Core/native-host field | Independent Whisper readiness. |
+| `status` | `string` | Yes | Bounded health identifier | Native service state. |
+| `ttsEngine` | `string` | Yes | Health-validated | Text-to-speech engine. |
+| `sttEngine` | `string` | Yes | Health-validated | Speech-to-text engine. |
+
+Unlike `localAI.status()`, this direct call rejects when Core cannot reach and
+validate the speech health response.
+
+### Speech synthesis request
+
+`Arcane.speech.synthesize(request)` accepts the portable
+`SpeechSynthesisRequest` fields below. Supply the documented primitive types and
+lowercase values; do not rely on host-specific coercion or empty-string
+defaulting.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `input` | `string` | Yes | Trimmed, nonempty, at most 4,000 characters | Text to synthesize. |
+| `model` | `"kokoro"` | No | Default `"kokoro"`; only supported value | Synthesis model. |
+| `voice` | `string` | No | Default `"af_heart"`; `[a-z0-9][a-z0-9_-]{0,63}` | Kokoro voice. |
+| `responseFormat` | `"opus" \| "wav"` | No | Default `"opus"` | Audio format. |
+| `speed` | `number` | No | Default `1`; 0.5-2 inclusive | Speaking speed. |
+
+### Speech synthesis result
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `audioBase64` | `string` | Yes | Base64 for 1 byte through 6 MiB of audio | Encoded audio. |
+| `contentType` | `"audio/ogg" \| "audio/wav"` | Yes | Matches the result encoding | Media type. |
+
+### Speech transcription request
+
+`Arcane.speech.transcribe(request)` accepts an exact
+`SpeechTranscriptionRequest`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `audioBase64` | `string` | Yes | Canonical base64; encoded at most 8 MiB; decoded 1 byte through 6 MiB | Media bytes labeled as WebM. The bridge validates encoding and bounds, while the fixed speech service parses the container. |
+| `mimeType` | `string` | No | Default `"audio/webm"`; base type must be `audio/webm` | Media type; codec parameters may follow. |
+| `model` | `string` | No | Default `"whisper-small"`; `whisper(?:[._-][a-z0-9]+)*` | Whisper identifier. The fixed service rejects unsupported variants. |
+
+### Speech transcription result
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `text` | `string` | Yes | Trimmed; response limited to 64 KiB | Transcript. |
+
+Application-owned inference extensions define their request, callback, proof,
+and isolation schemas with the owning package. They are included in the same
+developer-reference completeness check but do not become generic Arcane AI
+contracts merely because Core transports them.
+
+## Direct Ollama API
+
+Direct Ollama calls are local Core APIs, not provider-neutral contracts. Their
+request objects are closed top-level plain objects. Core rejects unknown
+top-level fields, non-JSON-compatible values, and encoded requests larger than
+8 MiB. Nested provider-native objects are forwarded for Ollama to validate.
+
+### Ollama model name
+
+Every required `OllamaModelName` matches:
+
+```text
+[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}
+```
+
+### Ollama show options
+
+`Arcane.ollama.show(model, options)` accepts `OllamaShowOptions`:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `verbose` | `boolean` | No | Provider default | Requests verbose metadata. |
+
+The wrapper supplies the validated `model` field.
+
+### Ollama generate request
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Model to run. |
+| `prompt` | `string` | Provider | - | Generation prompt. |
+| `suffix` | `string` | No | Provider-native | Text after the generated insertion. |
+| `images` | `array` | No | Provider-native base64 values | Multimodal input. |
+| `format` | JSON value | No | Text, JSON, or schema format | Output format. |
+| `options` | object | No | Provider-native; `num_ctx` is 1,024-262,144 when supplied | Runtime options. |
+| `system`, `template` | `string` | No | Provider-native | Prompt controls. |
+| `context` | `array` | No | Provider-native | Legacy context tokens. |
+| `raw` | `boolean` | No | Provider-native | Raw prompt mode. |
+| `keep_alive` | `string \| number` | No | Provider-native | Residency. |
+| `think`, `logprobs`, `top_logprobs` | JSON value | No | Provider-native | Reasoning/log-probability controls. |
+
+See [Ollama's generate API](https://docs.ollama.com/api/generate).
+
+### Ollama chat request
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Model to run. |
+| `messages` | `array` | Provider | Provider-native records | Conversation. |
+| `tools` | `array` | No | Provider-native | Tool definitions. |
+| `format` | JSON value | No | Provider-native | Output format or schema. |
+| `options` | object | No | Provider-native; `num_ctx` is 1,024-262,144 when supplied | Runtime options. |
+| `keep_alive` | `string \| number` | No | Provider-native | Residency. |
+| `think`, `logprobs`, `top_logprobs` | JSON value | No | Provider-native | Reasoning/log-probability controls. |
+
+See [Ollama's chat API](https://docs.ollama.com/api/chat).
+
+### Ollama embed request
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Embedding model. |
+| `input` | `string \| array` | Provider | Provider-native | Text or batch to embed. |
+| `truncate` | `boolean` | No | Provider-native | Allow truncation. |
+| `dimensions` | `integer` | No | Provider-native | Embedding dimensions. |
+| `keep_alive` | `string \| number` | No | Provider-native | Residency. |
+| `options` | object | No | Provider-native; `num_ctx` is 1,024-262,144 when supplied | Runtime options. |
+
+See [Ollama's embed API](https://docs.ollama.com/api/embed).
+
+### Ollama pull options
+
+`Arcane.ollama.pull(model, options, streamOptions)` accepts:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `insecure` | `boolean` | No | Provider-native | Insecure-registry control. |
+
+The raw application call always rejects; see
+[Raw Ollama management restrictions](#raw-ollama-management-restrictions).
+
+### Ollama push options
+
+`Arcane.ollama.push(model, options, streamOptions)` accepts:
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `insecure` | `boolean` | No | Provider-native | Insecure-registry control. |
+
+Push is allowed only for a model authorized by verified package policy.
+
+### Ollama create request
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Alias to create. |
+| `from` | [`OllamaModelName`](#ollama-model-name) | Conditional | Required by Arcane's managed verified workflow | Base model. |
+| `files`, `adapters` | object | No | Provider-native; forbidden by Arcane's managed path | File/adapter mappings. |
+| `template`, `system` | `string` | No | Provider-native | Stored prompt configuration. |
+| `license` | `string \| array` | No | Provider-native | License text. |
+| `parameters` | object | No | Provider-native | Model parameters. |
+| `messages` | `array` | No | Provider-native | Stored messages. |
+| `quantize` | `string` | No | Provider-native | Quantization request. |
+
+Arcane permits creation only when alias, base, SYSTEM text, and parameters
+exactly match the package-owned verified definition. Reserved Arcane and
+rollback aliases reject. See [Ollama's create API](https://docs.ollama.com/api/create).
+
+### Ollama stream controls
+
+Generate, chat, pull, push, and create accept `OllamaStreamControls` in the
+document; these controls are not sent as provider request fields.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `onChunk` | [`OllamaChunkCallback`](#ollama-chunk-callback) | No | - | Receives provider-native chunks. |
+| `signal` | `AbortSignal` | No | Genuine signal object | Stops renderer observation and sends a best-effort host cancellation control. Whether host work stops depends on the method. |
+| `timeoutMs` | `number` | No | Callers must supply a positive finite number; method default otherwise | Renderer request timeout. The current wrapper coerces this value, so do not depend on acceptance of another type. |
+
+Callers must not send internal `stream` or `streamId`; the wrapper creates them.
+
+### Ollama chunk callback
+
+An `OllamaChunkCallback` is called as `onChunk(chunk, metadata)`. `chunk` is a
+provider-native JSON object. `metadata` is `{operation, streamId}`. A callback
+may be passed directly in place of `OllamaStreamControls`.
+
+### Ollama provider responses
+
+Direct Ollama methods return bounded provider-native envelopes. Arcane does not
+normalize their nested fields into the provider-neutral entities above. Core
+requires valid JSON, caps a response at 12 MiB, parses newline-delimited stream
+data, and resolves a stream with its final provider chunk.
+
+Fields can change with the installed Ollama version. Use the official
+[Ollama API reference](https://docs.ollama.com/api/introduction) for the
+provider response entities.
+
+- `version()` returns the version envelope.
+- `models()` and `list()` return the tags envelope, not `model[]`.
+- `running()` returns the running-model envelope, not `model[]`.
+- `show`, `generate`, `chat`, `embed`, `push`, `create`, and `delete` return
+  their corresponding provider-native envelope.
+
+### Raw Ollama management restrictions
+
+`Arcane.ollama.pull()` and `Arcane.ollama.copy()` always reject and therefore
+return `Promise<never>` to an application. A raw pull lacks integrity-bound
+pre-download evidence; the managed lifecycle owns registry/GGUF preflight and
+native admission. Raw alias copy is reserved to the managed selection workflow.
+
+`push`, `create`, and `delete` require verified package policy and reject
+reserved aliases. Unverified-model mode is inference-only and never pulls,
+creates, copies, pushes, deletes, or repairs a model.
+
+## Ollama selection and settings
+
+### Arcane model preference
+
+`Arcane.ollama.select(preference)` accepts `ArcaneModelPreference`:
+
+| Value | Meaning |
+|---|---|
+| `"auto"` | Try the bounded automatic candidate sequence. |
+| `"3b"`, `"8b"`, `"12b"`, `"20b"`, `"120b"` | Explicit managed Arcane model size. |
+
+The value is a preference enum, not an arbitrary model name.
+
+### Arcane model selection
+
+`Arcane.ollama.selection()` and `settings()` return `ArcaneModelSelection`.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `preference` | [`ArcaneModelPreference`](#arcane-model-preference) | Yes | - | Saved preference. |
+| `recommendedVariant`, `effectiveVariant` | `string` | Yes | Managed variants | Recommended and resolved sizes. |
+| `model`, `alias` | `string` | Yes | - | Variant model and stable managed alias. |
+| `activeVariant` | `string \| null` | Yes | Managed variant | Persisted active state. |
+| `defaultModel` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Default inference model. |
+| `bootLoad` | `boolean` | Yes | - | Load during managed startup. |
+| `bootKeepAlive` | `"5m" \| "30m" \| "1h" \| "24h" \| "-1"` | Yes | - | Boot residency. |
+| `contextLength` | `integer` | Yes | `0` or 1,024-262,144; `0` is Automatic | Saved context. |
+| `provider` | `"ollama" \| "openai"` | Yes | - | Saved provider. |
+| `openAIModel` | `string` | Yes | - | Saved OpenAI model. |
+| `responseLength` | `"low" \| "medium" \| "high"` | Yes | - | Response target. |
+| `openAIConfigured` | `boolean` | Yes | - | Protected credential exists. |
+| `gpu` | object | Yes | Bounded diagnostic snapshot | Accelerator evidence. |
+| `recommendationPending` | `boolean` | Yes | - | Automatic selection awaits persisted admission. |
+
+`gpu` contains `devices` (at most 16 `{name, memoryBytes}` records),
+`totalMemoryBytes`, `largestMemoryBytes`, `memoryReliable`, and `source`.
+
+### Arcane model selection result
+
+A successful `select()` returns `ArcaneModelSelectionResult` plus
+[`ArcaneOperation`](#arcane-operation).
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model`, `alias`, `variant`, `preference`, `recommendedVariant` | `string` | Yes | Managed values | Selected model identity. |
+| `created`, `aliasChanged` | `boolean` | Yes | - | Mutation effects. |
+| `baseModel` | `string` | Yes | - | Verified base. |
+| `modelsRoot` | `string \| null` | Yes | Host path | Model store. |
+| `gpu`, `evidence` | object | Yes | Bounded diagnostics | Native and definition evidence. |
+| `compatibility` | [`ModelResourceAdmission`](#model-resource-admission) | Yes | `admitted:true` | Final admission. |
+| `recommendationDegraded` | `boolean` | No | Automatic only | Smaller capacity candidate selected. |
+| `candidateFailures` | `array` | No | Automatic only | Earlier bounded failures. |
+| `rollbackSnapshotRetained` | `boolean` | Yes | - | A recovery snapshot remains because cleanup could not be proven. |
+| `recoveryAlias` | `string \| null` | Yes | Reserved alias when retained | Alias an administrator can use for recovery. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Selection operation. |
+
+### Arcane AI settings input
+
+`Arcane.ollama.saveSettings(settings)` reads only runtime-owned fields. Unknown
+keys, including stale provider/model preference fields from an old screen, are
+ignored so they cannot overwrite newer provider selection.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `defaultModel` | [`OllamaModelName`](#ollama-model-name) | No | Current value | Default runtime model. |
+| `bootLoad` | `boolean` | No | Current value | Load at managed startup. |
+| `bootKeepAlive` | `"5m" \| "30m" \| "1h" \| "24h" \| "-1"` | No | Current value | Boot residency. |
+| `contextLength` | `integer` | No | `0` or 1,024-262,144 | Runtime context; `0` is Automatic. |
+
+Use `select()` for the managed size preference and
+`saveProviderSettings()` for provider, OpenAI model, credential, and response
+length.
+
+### Arcane AI settings result
+
+A successful settings save returns `ArcaneAISettingsResult`: the complete
+[`ArcaneModelSelection`](#arcane-model-selection) snapshot after the mutation,
+plus `operation` as an [`ArcaneOperation`](#arcane-operation). It does not return
+the selection-only mutation fields such as `created`, `baseModel`, or
+`aliasChanged`.
+
+### Arcane brain definition
+
+`Arcane.ollama.createBrain(definition)` reads `ArcaneBrainDefinition`; unknown
+keys are currently ignored and should not be sent.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `baseModel` | [`OllamaModelName`](#ollama-model-name) | Yes | - | Base model. |
+| `name` | `string` | No | Default `"my-brain"`; normalized to a 1-64 character slug | Brain name. |
+| `contextLength` | `integer` | No | `0` for inherited/automatic; use 1,024-262,144 explicitly | Requested context. |
+| `makeDefault` | `boolean` | No | Default `false` | Make the created model the default. |
+
+### Arcane brain result
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `model` | `string` | Yes | `arcane-<slug>:latest` | Created model. |
+| `baseModel` | `string` | Yes | - | Base model. |
+| `defaultModel` | `boolean` | Yes | - | Became the default. |
+| `operation` | [`ArcaneOperation`](#arcane-operation) | Yes | Completed | Creation operation. |
+
+### Ollama service settings state
+
+`Arcane.ollama.serviceSettings()` returns a platform-dependent native state.
+Microsoft NT reports effective settings and support state. Callers must
+feature-detect platform-specific fields rather than assume one cross-platform
+exact object.
+
+### Ollama service settings input
+
+`Arcane.ollama.saveServiceSettings(settings)` applies defaults to omitted fields;
+send the complete desired `OllamaServiceSettingsInput`. Unknown keys are
+currently ignored and should not be sent.
+
+| Field | Type | Required | Constraints / default | Description |
+|---|---|---:|---|---|
+| `contextLength` | `integer` | No | Default `0`; 0-262,144 | Service context. |
+| `keepAlive` | `string` | No | Default `"5m"`; `"-1"`, `"0"`, or 1-9,999 plus `m`/`h` | Residency. |
+| `maxLoadedModels` | `integer` | No | Default `1`; 0-16 | Loaded-model limit. |
+| `numParallel` | `integer` | No | Default `1`; 1-16 | Parallel requests. |
+| `maxQueue` | `integer` | No | Default `512`; 1-4,096 | Queue limit. |
+| `flashAttention` | `boolean` | No | Default `false` | Flash attention. |
+| `kvCacheType` | `"f16" \| "q8_0" \| "q4_0"` | No | Default `"f16"` | K/V-cache format. |
+| `noCloud` | `boolean` | No | Default `true` | Prevent Ollama cloud behavior. |
+
+### Ollama service settings result
+
+A successful save returns the platform result plus
+[`ArcaneOperation`](#arcane-operation). Microsoft NT currently reports requested
+and effective settings, support/clamping detail, restart state, and post-change
+health. Require `healthy === true` where that field exists.
+
+## Errors and capability boundaries
+
+| Method group | Required authority | Additional restriction |
+|---|---|---|
+| Provider-neutral chat/profile and local status | `ai.inference` | Configured provider; local status is served by desktop Core or an explicitly admitted Android `user-managed-loopback` host, distinguished by `providerMode` and runtime fields. |
+| Raw local inventory | `ai.models.read` | Settings, Shell, and Terminal diagnostics. |
+| Provider settings/OpenAI model catalog | `ai.settings.manage` | Settings only. |
+| `localAI.ensurePlatform()` | `provisioning.manage` | Provisioner type; exclusive. |
+| `localAI.recover()` | `ai.inference` | Approved recovery apps; privileged and exclusive. |
+| `localAI.setParallelRequests()` | `ai.runtime.manage` | Sole registered grantee; desktop Core only; privileged and exclusive. |
+| Speech | `ai.inference` | Requires local speech host. |
+| Raw Ollama reads | `ai.models.read` | Diagnostic apps only. |
+| Raw Ollama inference | `ai.inference` | Exact model is re-admitted. |
+| Ollama mutations | `ai.models.manage` | Verified package policy; raw pull/copy reject. |
+| Runtime/provider/service settings | `ai.settings.manage` | Settings restrictions; service mutation is privileged/exclusive. |
+
+Additional invariants:
+
+- Raw inventory must not populate an application model selector. Use the
+  admitted `Arcane.localAI.status().models.ollama` catalog.
+- Browser runtimes gain no local Ollama authority from the shared API
+  vocabulary. Android exposes only its explicitly admitted projection (currently
+  `ollama.chat()` for approved applications), not desktop lifecycle or model
+  mutation authority.
+- Unverified installed-model inference additionally requires
+  `ai.models.unverified.inference` and remains inference-only.
+- Arcane never silently changes from Ollama to OpenAI after local discovery or
+  admission failure.
+- Provider credentials are never returned to renderers.
+- Status, admission, progress, registry evidence, and model records are
+  observations, not grants or reusable authorization.
+- Core rechecks current package policy, model identity, and resources at the
+  operation boundary.