arcane-os 0.2.2 → 0.3.0

package/docs/reference/ai/browser-wasm.md

@@ -9,7 +9,7 @@ page is the focused local-browser path beneath the normalized AI decision
 guide.
 
 The wiring example assumes a scaffolded or materialized Arcane application
-with SDK `0.2.1`'s authenticated runtime tree and generated browser import map.
+with SDK `0.3.0`'s runtime tree and generated browser import map.
 `arcane/DBOPFS` is a managed browser-map specifier, not an npm package export.
 See [browser runtime delivery](../protocols.md#browser-runtime-delivery) before
 using the example in a custom host or bundler.
@@ -128,8 +128,9 @@ default for its check.
 An enabled byte-length check requires descriptor `bytes` and compares it with
 the actual cached or downloaded byte count. A disabled byte-length check permits
 `bytes` to be absent and never rejects a cached or downloaded model by comparing
-it with an expected size. The store still counts and records the observed byte
-length for storage and progress metadata on every install and cache reuse.
+it with an expected size. The store still counts and records the
+observed byte length for storage and progress metadata on every install and
+cache reuse.
 
 An enabled SHA-256 check requires descriptor `sha256` and hashes the actual
 stored or cached file. A disabled SHA-256 check permits `sha256` to be absent
@@ -158,8 +159,8 @@ console.log(integrity.byteLength.observed); // actual cached/downloaded bytes
 For one-file compatibility, older descriptors can supply `immutableUrl` as the
 URL alias and `name` as a cache-filename hint. If both `url` and
 `immutableUrl` are present, they must match. Legacy `licenseSpdx` and
-`sourceRevision` properties are not canonical descriptor fields or runtime
-admission checks; applications remain responsible for model selection,
+`sourceRevision` properties are
+not canonical descriptor fields or runtime admission checks; applications remain responsible for model selection,
 provenance, and license compliance. Version-2/3 compatibility is internal; a
 new successful completion is always recorded as version 4 without inventing an
 integrity result.
@@ -316,8 +317,8 @@ The SDK default is `secure:false`; `ai.load({security})` can override inherited
 fields for that operation.
 
 When `llm` is an existing `ModelController`, that controller keeps the security
-and load policy with which it was created. This function does not reapply its
-`loadPolicy` argument in that case, and supplying `security` alongside the
+and load policy with which it was created. This function
+does not reapply its `loadPolicy` argument in that case, and supplying `security` alongside the
 existing controller throws `TypeError`. Passing a provider instead creates a
 new controller with the requested policy and security.
 
@@ -490,6 +491,16 @@ localOnly:true,catalog,inspect,status,load,request,unload,dispose}`. Inspection
 returns `arcane-ai-model-authority/1` only for an exact catalog selection.
 `request()` admits only `chat` and `stream` and preserves structural tool data.
 
+### Availability and normalization
+
+The adapter is available anywhere the caller can supply an admitted
+`arcane-ai-browser-wasm/1` provider object. It performs only the versioned
+provider-shape normalization into `arcane-ai-provider/2`; it does not create a
+runtime, choose or download a model, grant host capability, change local-only
+behavior, or make an arbitrary provider authoritative. Provider lifecycle,
+cancellation, catalog selection, and failures remain owned by the wrapped
+provider and are forwarded through the normalized role contract.
+
 ### Example
 
 ```javascript

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

@@ -91,7 +91,7 @@ surface does not require an Arcane Core method grant because it does not call a
 Core host. Browser Fetch, CORS, storage policy, secure-context behavior, and
 resource limits still apply.
 
-The shipped `0.2.1` runtime requires WebGPU and has no CPU fallback. A successful
+The shipped `0.3.0` runtime requires WebGPU and has no CPU fallback. A successful
 load requests full GPU offload (`gpuLayers: 99999`) and admits actual adapter,
 full-offload, buffer, queue, and settled-fence evidence. `navigator.gpu`
 presence by itself is not readiness. The provider emits the instrumented
@@ -128,8 +128,11 @@ through an SDK-created authority and DBOPFS artifact store.
 
 The projected [`AIProviderRuntime`](runtime-modules.md#aiproviderruntimejs)
 normalizes those browser providers and can admit an externally supplied native
-or cloud provider/2 adapter. SDK `0.2.1` does not publish a native, Core, or
-cloud provider/2 adapter. The sticky
+or cloud provider/2 adapter. `AI.js` also supplies compatibility adapters for
+an already-selected legacy OpenAI route, Ollama route, or admitted Core speech
+route. SDK `0.3.0` publishes no privileged Core implementation, credential,
+model, or speech-runtime authority, and those adapters never probe, select,
+download, or fall back. The sticky
 [`AIRuntimeState`](runtime-modules.md#airuntimestatejs) surface keeps
 application UI independent of transport. A selected route remains explicit:
 browser failure is not permission to invoke Core or cloud.

package/docs/reference/behavioral-testing.md

@@ -34,12 +34,12 @@ release acceptance.
 | Surface | Minimum behavior proved locally | Heavier evidence boundary |
 | --- | --- | --- |
 | Package entrypoints | Every declared JavaScript export imports; documented names match; constants and synchronous validators preserve their public contracts. | None for import itself. Operations that invoke tools use the matching boundary below. |
-| EventManager and event stacks | Live pub/sub ordering and payload identity, nested causation, immutable/redacted snapshots, strict import, bounded overflow, seek, all playback modes/lifecycle outcomes, cancellation, and DOM start/stop/privacy behavior. | Real user journeys and browser layout belong in a browser harness; event-stack review never proves that external side effects can be replayed. |
+| Canonical events, EventManager, and event stacks | One branded/versioned `globalThis.arcaneEvents` per realm, fail-closed collision admission, duplicate-module reuse, declared source ownership, canonical/source delivery order, frozen occurrence metadata, exact cancellation, AbortSignal cleanup, disposable subscriptions, source teardown/re-registration, observational listener failure, EventTarget compatibility, one-way DOM projection, deprecated state-free `aiRuntimeEvents`, live isolated-bus pub/sub, nested causation, immutable/redacted stacks, strict import, bounded overflow, seek, playback, and DOM privacy/lifecycle. | Real user journeys and browser layout belong in a browser harness; an occurrence, EventTarget/DOM projection, or event-stack review never proves that external side effects stopped, completed, or can be replayed. |
 | CLI | Commands parse, acknowledge, select one scope, produce normalized human/JSON/NDJSON output, propagate cancellation/failure, and reject invalid cardinality. | Native build/run requires the selected real provider and host. |
 | Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
-| Provider-neutral AI runtime and chat/speech activation | Provider/2 registration, closed three-role configuration, opt-in STT startup, legacy Cloud/Core speech readiness, independent LLM/STT/TTS load/unload/status, latest-request-wins settlement, owned STT signals, TTS mute lifecycle, route-owned voice defaults, sticky-state-only speech readiness, selected-unloaded activation request/cancellation/error events, stale-callback suppression, and absence of silent provider fallback are exercised against bounded providers and host callbacks. | Real model/runtime admission remains the selected provider's evidence boundary; provider-promise settlement, state, an abort signal, or an activation event does not by itself prove underlying provider work stopped or native, cloud, or browser-model availability. |
-| Browser-WASM local AI | The exact exported namespace, canonical ordered `{id, files:[{name?,url,bytes?,sha256?},...]}` descriptor plus its one-file compatibility input, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest capability/status reasons, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | The publication gate installs the packed SDK into a real Chrome app, loads the authenticated Wllama 3.6.0 JS/WASM assets, configures `secure:true`, performs a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and a verified offline reload with zero model requests. It is an explicit heavyweight capability gate, not an implicit model download in every local `npm run check`. |
-| Browser speech | Caller-owned Whisper/Kokoro authority, closed runtime graph, app/provider/load security precedence, manifest-last DBOPFS cache, strict offline admission, independent Worker lifecycle, pre-Worker versus in-Worker cancellation, Blob/File STT conversion, WAV TTS conversion, and no cloud fallback are exercised with bounded synthetic artifacts and adapters. | A real runtime/model/voice download and actual transcription or synthesis require the application's admitted immutable artifacts, licenses, browser media support, and explicit user action. |
+| Provider-neutral AI runtime and chat/speech activation | Provider/2 registration, closed three-role configuration, opt-in STT startup, legacy Cloud/Core speech readiness, independent LLM/STT/TTS load/unload/status, latest-request-wins settlement, owned STT signals, TTS mute lifecycle, route-owned voice defaults, sticky-state-only readiness for both speech components, shared selected-unloaded activation request/cancellation/error behavior, fail-closed programmatic voice recording, public transcript-replacement supersession of late transcribe/save/complete settlement, `AI.fetchSTT` callback-position compatibility, stale-callback suppression, and absence of silent provider fallback are exercised against bounded providers and host callbacks. | Real model/runtime admission remains the selected provider's evidence boundary; provider-promise settlement, state, an abort signal, or an activation event does not by itself prove underlying provider work stopped or native, cloud, or browser-model availability. |
+| Browser-WASM local AI | The exact exported namespace, canonical ordered `{id, files:[{name?,url,bytes?,sha256?},...]}` descriptor plus its one-file compatibility input, fieldwise app/provider/load security precedence, default-unchecked and secure-check paths, observed-byte persistence, honest capability/status reasons, provider/facade lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, and structural-only tool behavior run with bounded deterministic providers. | An optional explicit `secure:true` verification may install the packed SDK into a real Chrome app, load authenticated Wllama 3.6.0 JS/WASM assets, perform a cold exact-length/SHA-256 model install, real inference, in-flight cancellation, unload, and verified offline reuse. That heavyweight hardening proof is not an ordinary publication gate or an implicit model download. |
+| Browser speech | Caller-owned Whisper/Kokoro authority, independent STT/TTS routes, ordinary direct upstream runtime/model authority, explicit `secure:true` graph admission, manifest-last DBOPFS cache, strict offline admission, independent Worker lifecycle, pre-Worker versus in-Worker cancellation, Blob/File STT conversion, WAV TTS conversion, and no cloud fallback are exercised with bounded synthetic artifacts and adapters. | A real runtime/model/voice download and actual transcription or synthesis use the application's selected upstream packages/providers, browser media support, and explicit user action. Optional strict graph evidence remains scoped to `secure:true`. |
 | Persistent chat and document context | Atomic in-memory/history commit, explicit per-turn persistence, single structural tool-call sequencing, bounded bootstrap/search/context, caller-source `evaluate()` budgets, cancellation, and reject versus `preserve-readable` partial coverage are exercised with app-scoped adapters. | Live Core/provider inference and durable browser storage remain separate authorities; tests never treat a fake chat function or in-memory adapter as host/storage proof. |
 | Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
 | Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |
@@ -100,10 +100,33 @@ continued unrecorded live delivery, rejection when re-enabling before
 DOM cases assert that private values, credentials, sensitive attributes, URLs,
 and markup remain redacted under every capture-option combination.
 
+The focused singleton contract also owns these cases in
+`test/event-manager.test.mjs`: global property/brand/protocol/API descriptor
+admission; same-object reuse across duplicate module URLs and package
+entrypoints; exact `subscribe(type,handler,{once,signal})` behavior; idempotent
+`unsubscribe()`/`unsubscribe.dispose()`; one active
+`createSource(owner,{source,eventTypes,onListenerError})` handle; immutable
+`arcane-event-occurrence/1` values and privacy separation; synchronous
+cancellation; dispatch-safe removal and reentry; final source disposal;
+EventTarget deduplication/admission; one-way `CustomEvent` projection; and
+nonrecursive listener-error publication. Runtime behavior tests own the
+`aiRuntimeEvents` compatibility view and each migrated module/component's
+instance-scoped projection and cleanup. Reference-completeness tests own the
+public export names and exact focused-guide coverage.
+
+Canonical event publication itself is deliberately synchronous and
+observational. Tests must not await listener return values or present
+`arcaneEvents` as backpressure. Promise settlement, async callback failure, and
+ordered delivery belong to the operation promise or `createEventQueue()` test
+that owns that work. Abort-driven listener removal proves cleanup only; it does
+not prove already-started host, provider, worker, or queue work stopped.
+
 ## Test ownership
 
-The SDK owns package, CLI, synchronized renderer, documentation, and injected
-provider-boundary behavior. Arcane OS owns live Core dispatch, native host
+The SDK owns the singleton authority, its per-realm source adapters, package and
+managed-browser projections, focused event/source/DOM contracts, runtime
+compatibility views, package, CLI, synchronized renderer, documentation, and
+injected provider-boundary behavior. Arcane OS owns live Core dispatch, native host
 bridges, capability policy, host service adapters, and real ArcaneOllama
 integration. A change that crosses both repositories needs focused tests at both
 owners; copying a Core test into this package would not make the SDK the Core

package/docs/reference/cli.md

@@ -31,6 +31,9 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane update-check` | Performs one explicit, read-only npm dist-tag query for the installed SDK version. |
 | `arcane targets` | Lists target ids, declared status, formats, architectures, signing profiles, methods, and pairing reason. |
 | `arcane repo status\|pull\|push` | Runs one selected repository operation for the current app workspace. |
+| `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in Windows Credential Manager. |
+| `arcane mail send` | Performs one explicit, idempotency-keyed Resend attempt from a bounded JSON report on redirected stdin. |
+| `arcane mail serve` | Starts one authenticated numeric-loopback Arcane-to-Resend gateway with exact app, Origin, and recipient admission. |
 
 ## Parser-wide options
 
@@ -42,21 +45,30 @@ meaning and cardinality rules:
 | `--path` | directory | `new` |
 | `--display-name` | string | `new`, `init` |
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
-| `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`. |
+| `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`; also the exact `mail serve` caller id. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
-| `--host` / `--port` | host / integer 0–65535 | Browser `dev` and `run`; defaults to `127.0.0.1:8000`. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to `127.0.0.1:8000`; `mail serve` defaults to `127.0.0.1:8025` and admits numeric loopback only. |
 | `--target` | target id | `new`, `init`, native diagnostics, `build`, `run` |
 | `--format` / `--signing` | target-supported values | Native diagnostics, `build`, `run` |
 | `--output-root` | directory | Native `build` and `run` |
 | `--scope` | `app` or `shared` | `test`, `check`; defaults to `app`. |
 | `--test-file` | repository-relative `.test.mjs` | `test --scope shared` only |
 | `--artifact` | bundle path | `bundle`, `verify-bundle` |
+| `--profile` | credential profile id | `mail send`, `mail serve` |
+| `--from` | verified sender | `mail send`, `mail serve` |
+| `--origin` | exact browser origin | `mail serve` |
+| `--allow-to` | one to 50 comma-separated addresses | `mail serve` |
+| `--report-key` | 8–128 safe characters | `mail send`; caller-owned stable Resend idempotency key |
+| `--request-timeout` | integer 1000–600000 ms | `mail send`, `mail serve` |
 | `--output` | `human`, `json`, `ndjson` | Every invocation; the final occurrence wins. |
 | `--git` | flag | `new` |
 | `--skip-tests` | flag | `check --scope app` |
 | `--dry-run` | flag | `package`; parser-supported on `build` with the boundary below |
 | `--require-local-ai` | flag | `doctor` |
 | `--overwrite` | flag | `bundle` only |
+| `--secret-stdin` | flag | `mail key set`; requires redirected input |
+| `--app-key-stdin` | flag | `mail serve`; requires redirected input |
+| `--report-stdin` | flag | `mail send`; requires redirected JSON input |
 | `--help`, `-h` | flag | Prints help and exits zero. |
 | `--version`, `-v` | flag | Prints the exact SDK version and exits zero. |
 
@@ -185,10 +197,11 @@ identical executable alias.
 The generated artifact is
 `apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
 the app entry as `<script type="importmap" data-arcane-import-map>` before
-module loading. In SDK `0.2.1`, the complete authenticated physical-v1 runtime
-produces 91 entries and intentionally has no package-root mapping. That count
-describes the shipped SDK closure; the command receipt remains authoritative
-for the exact map written to the selected application.
+module loading. In SDK `0.3.0`, the complete physical-v1 runtime derives its
+entries from the installed runtime and browser-runtime inventories and
+intentionally has no package-root mapping. The command receipt remains
+authoritative for the exact map written to the selected application; no fixed
+entry count is a release contract.
 
 ### Result and safety
 
@@ -207,7 +220,7 @@ Success returns the normal selected-workspace wrapper:
         documentPaths,
         documentCount:1,
         imports,
-        entryCount:91,
+        entryCount:Object.keys(imports).length,
         excludedModules:['modules/CaseEvidenceIndexer.js'],
         files:[
             {role:'artifact',path,bytes,sha256},
@@ -573,8 +586,8 @@ Success returns:
 ```javascript
 {
     packageName:'arcane-os',
-    currentVersion:'0.2.0',
-    registryVersion:'0.2.1',
+    currentVersion:'0.2.1',
+    registryVersion:'0.2.2',
     tag:'latest',
     status:'update-available', // or 'current' or 'ahead'
     updateAvailable:true,
@@ -648,6 +661,101 @@ loop across workspaces.
 npm exec -- arcane repo status
 ```
 
+## `arcane mail`
+
+### Resend credential profiles
+
+The credential subcommands select one local profile:
+
+```text
+arcane mail key set <profile> [--secret-stdin]
+arcane mail key status <profile>
+arcane mail key delete <profile>
+```
+
+`key set` reads the Resend API key from a hidden terminal prompt. The
+`--secret-stdin` form is for deliberately redirected non-interactive input and
+rejects a TTY before reading. The key is sent to the Windows Credential Manager
+helper over child-process stdin, never argv, and no plaintext fallback is
+created. Status reports only whether the profile exists. Delete returns the
+selected profile with `exists:false`; it intentionally does not distinguish a
+new deletion from an already-absent profile. Non-Windows hosts fail closed.
+
+Machine output for `key set` requires `--secret-stdin`. Raw CLI arguments are
+not included in acceptance events, and usage errors do not echo unknown option
+or positional values.
+
+### One-shot provider send
+
+`mail send` performs exactly one Resend provider attempt without starting a
+loopback server:
+
+```text
+arcane mail send --profile <profile> --from <verified-sender> --report-key <id> --report-stdin [--request-timeout <ms>]
+```
+
+`--report-stdin` is mandatory and rejects a terminal before attaching input
+listeners. It accepts one UTF-8 JSON object up to 52 MiB using the existing
+gateway report shape:
+
+```json
+{
+  "type": "report",
+  "to": ["recipient@example.com"],
+  "subject": "Example",
+  "text": "Message content"
+}
+```
+
+The exact closed report keys are `type`, `to`, `subject`, and at least one of
+`text` or `html`. Direct CLI sending requires one to 50 explicit unique
+recipients, including for `error` reports. The Resend credential comes only
+from the selected Windows Credential Manager profile; neither it nor report
+content is accepted through argv, environment variables, or result fields.
+
+The caller owns `--report-key`. It must contain 8–128 ASCII letters, digits,
+periods, underscores, colons, or hyphens. Reuse the same key only with the same
+byte-equivalent logical report when deliberately reconciling or retrying an
+ambiguous attempt. The CLI never retries automatically.
+
+Exit zero means Resend returned a successful response with a valid provider
+acceptance id. The privacy-safe result contains only provider, status,
+classification, request id, provider id, provider HTTP status, and recipient
+count. It proves provider API acceptance, not inbox delivery. Permanent,
+retryable, and ambiguous outcomes exit nonzero with only normalized code,
+status, retry, uncertainty, and count metadata. Cancellation before the
+provider attempt exits 130 without sending; cancellation, timeout, or transport
+loss after the attempt begins is ambiguous because Resend may have accepted it.
+
+### Authenticated local gateway
+
+`mail serve` starts one owned Node HTTP gateway:
+
+```text
+arcane mail serve --profile <profile> --from <verified-sender> --app <id> --origin <exact-origin> --allow-to <addresses> [--app-key-stdin] [--host 127.0.0.1] [--port 8025] [--request-timeout <ms>]
+```
+
+The selected credential profile supplies only the server-side Resend API key.
+A separate local mail app key is read through a hidden prompt. Structured
+output requires `--app-key-stdin` with redirected input; the app key is never an
+argv value or part of the server result. The browser must use the same value as
+`arcane.config.mail.appKey`.
+
+The CLI admits only numeric loopback host values accepted by the gateway. The
+gateway also binds the exact app id, Origin, sender, and recipient allowlist,
+and it requires the separate app key by default. `--allow-to` accepts one to 50
+comma-separated unique recipients. `--request-timeout` is the one provider
+attempt timeout in milliseconds and defaults to `30000`.
+
+After binding, `server.ready` reports only sanitized lifecycle fields such as
+protocol, app id, loopback address, port, URL, and caller-authentication mode.
+The command owns the server until its lifecycle ends or `SIGINT`/`SIGTERM`
+cancels it. Neither Resend nor local app credentials, sender/recipient policy,
+or message content appear in the result or observer events.
+
+See [Mail gateway and durable outbox](mail.md) for request, retry,
+idempotency, DBOPFS, and provider-acceptance semantics.
+
 ## Machine output
 
 `--output json` returns one complete JSON document after structured progress is

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

@@ -9,7 +9,7 @@ They are not TypeScript declarations.
 
 ## Portable SDK AI and Core AI
 
-The SDK `0.2.1` has two related but separate normalized boundaries:
+The SDK `0.3.0` has two related but separate normalized boundaries:
 
 | Boundary | Use | Host |
 |---|---|---|