arcane-os 0.2.2 → 0.3.0

package/docs/architecture.md

@@ -200,7 +200,7 @@ length with an EOF growth probe, and rechecked by handle and pathname identity.
 Every cumulative path prefix has one case-folded spelling and one file/directory
 kind; prefix topology conflicts and the complete portable Windows device-name
 set fail before creation or admission.
-The current SDK admits only the explicitly compatible `0.2.2` bundle
+The current SDK admits only the explicitly compatible `0.3.0` bundle
 generation and rejects zero-byte payload releases.
 
 Promotion retains any prior output as an identity-bound backup until the new
@@ -320,7 +320,7 @@ through SDK-bound verified readers rather than accepting a mutable source path
 as authority. Build completion requires provider verification, and later
 verify/run calls receive the exact artifact receipt.
 
-The SDK `0.2.2` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.3.0` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/event-manager.md

@@ -1,46 +1,176 @@
-# Central event instrumentation and time-travel review
+# Canonical SDK events and time-travel review
 
-`EventManager` is the preferred event instrumentation surface for new Arcane
-SDK code. It composes `event-pubsub` for synchronous delivery and adds Arcane's
-optional diagnostic record around that bus. Existing SDK operation queues mirror
-their normalized events through the shared `arcaneEvents` manager exactly once
-without replacing their awaited callback, backpressure, cancellation, or failure
-semantics.
+`arcaneEvents` is the canonical synchronous SDK event authority. The module
+installs or reuses exactly one branded authority at `globalThis.arcaneEvents` in
+each JavaScript realm, even when the same source is loaded through duplicate
+module URLs. It is not a cross-frame, worker, process, native-host, or cloud bus.
+
+`EventManager` remains the isolated diagnostics API. `new EventManager()` and
+`createEventManager()` each create an independent `event-pubsub` bus whose
+`on()`, `emit()`, and `instrument()` handlers are strict: a synchronous listener
+failure propagates to that publisher. Use `arcaneEvents.subscribe()` and
+`createArcaneEventSource()` for canonical SDK semantic events instead.
+
+The installed global is an own, non-enumerable, non-writable, non-configurable
+data property. Its authority brand is
+`Symbol.for('arcane-os.arcane-events-authority')`, and both the brand value and
+public `protocol` are exactly `arcane-event-authority/1`. A later import reuses
+the object only when its property, brand, protocol, and required callable API
+descriptors are compatible. An inherited value, accessor, unbranded value,
+mutable descriptor, incompatible protocol, incomplete API, or failed install is
+rejected; the SDK never replaces or wraps a competing global.
 
 Import the dedicated host-neutral entry point:
 
 ```javascript
 import {
     arcaneEvents,
+    createArcaneEventSource,
     createEventManager,
+    projectArcaneDOMEvent,
     PLAYBACK_RECORD_EVENT
 } from 'arcane-os/event-manager';
 ```
 
-Prefer one manager for an application or process boundary. Publish semantic
-events through `instrument()` when source and correlation metadata are known:
+An SDK publisher owns one source handle for its lifetime and declares every
+semantic event type up front:
 
 ```javascript
-arcaneEvents.on('document.save.completed',event=>{
-    console.info('Saved',event.documentId);
+const controller={};
+const events=createArcaneEventSource(controller,{
+    source:'app.editor',
+    eventTypes:['document.save.completed']
 });
 
-arcaneEvents.instrument(
+const unsubscribe=arcaneEvents.subscribe('document.save.completed',occurrence=>{
+    console.info('Saved',occurrence.detail.documentId);
+});
+
+const publication=events.dispatch(
     'document.save.completed',
-    {documentId:'example'},
+    Object.freeze({documentId:'example',document:liveDocument}),
     {
-        source:'app:example',
-        category:'operation',
-        correlationId:'save-42'
+        operationId:'save-42',
+        publicDetail:{documentId:'example'},
+        cancelable:false
     }
 );
+
+projectArcaneDOMEvent(editorElement,publication.occurrence);
+unsubscribe();
+```
+
+`createArcaneEventSource(owner,options)` is the public wrapper for
+`arcaneEvents.createSource(owner,options)`. `options` is the closed record
+`{source,eventTypes,onListenerError?}`. Each non-null object or function owner
+may have one active source, and the returned frozen handle exposes
+`{protocol,descriptor,source,instanceId,eventTypes,disposed,subscribe,on,once,
+addEventListener,removeEventListener,dispatch,dispatchEvent,dispose,destroy}`.
+
+`dispatch()` synchronously delivers one immutable `arcane-event-occurrence/1`
+to exact-type canonical subscribers, then an EventTarget-compatible view to the
+source's own listeners. The occurrence contains `occurrenceId`, `type`, `source`,
+`instanceId`, `operationId`, deeply frozen privacy-admitted `detail`,
+`cancelable`, live `defaultPrevented`, and `preventDefault()`. The richer
+compatibility detail remains local to the authority for source listeners and
+optional DOM projection; it is not placed on the canonical bus or in time-travel
+history.
+
+Source listeners retain EventTarget compatibility: function listeners receive
+the source owner as `this`, and the frozen compatibility view exposes that owner
+as both `target` and `currentTarget`. Already-frozen compatibility detail retains
+its identity. Other plain records and arrays are shallow-copied and frozen;
+rich host objects remain local and are not recursively frozen.
+EventTarget-shaped `addEventListener()` and `removeEventListener()` preserve
+native no-op admission for null or non-listener callbacks; strict `subscribe()`
+and `on()` still reject an invalid handler.
+
+Canonical delivery is observational. Every active listener runs in registration
+order. A listener failure publishes one privacy-safe
+`arcane.event.listener.error` occurrence and is reported through `reportError`
+or `console.error`; it does not undo committed domain work or make
+`dispatch()` throw. An optional source `onListenerError(error,errorOccurrence)`
+callback receives the raw failure and its canonical listener-error occurrence
+only at that owner-local boundary; `errorOccurrence` is `null` only when the
+secondary error occurrence itself could not be constructed. Subscriber
+promises are not awaited, so keep completion, backpressure, and asynchronous
+failure in the SDK-owned queue or operation that owns them. There is no second
+Promise-returning publication bus: `dispatch()`, cancellation admission, sticky
+state commits, and listener installation remain synchronous. Owned promises and
+`createEventQueue()` own asynchronous work, ordering, failure, and backpressure;
+an `AbortSignal` removes a subscription but does not claim that already-started
+provider, host, or queue work stopped.
+
+`arcaneEvents.subscribe(type,handler,{once=false,signal}={})` returns an
+idempotent unsubscribe function whose `.dispose` property is the same function.
+An already-aborted signal installs nothing, and abort removes the registration
+deterministically. Source `on()` follows the same lifecycle. EventTarget-shaped
+`addEventListener()`/`removeEventListener()` calls deduplicate by
+type/listener/capture. Calling a source's idempotent `dispose()` emits its final
+`arcane.event.source.disposed` occurrence, removes its registrations, and frees
+the owner to register a later source.
+
+Cancellation is synchronous and observational. For a cancelable occurrence,
+canonical or source listeners may call `preventDefault()`; `dispatch()` then
+returns `{occurrence,accepted:false}`. Callers decide whether cancellation gates
+their domain operation. `projectArcaneDOMEvent()` is a one-way compatibility
+projection: it creates one `CustomEvent`, adds the canonical identifiers to a
+frozen outer detail object, preserves any compatibility `source` value, exposes
+the canonical emitter as `arcaneSource`, propagates DOM cancellation back to the
+occurrence, and never republishes the DOM event into the authority. It returns `false`
+without dispatching when the occurrence is already canceled.
+
+The authority also retains `on`, `once`, `off`, `reset`, `emit`, `instrument`,
+and `forward` for legacy direct EventManager-style diagnostics. Those handlers
+are separate from canonical `subscribe()` registrations; `off()` and `reset()`
+cannot remove canonical or source-owned registrations. New SDK publishers must
+use source handles. Authority-level `dispatchEvent()` exists only as a deprecated
+EventTarget admission adapter for older `aiRuntimeEvents` callers.
+
+`aiRuntimeEvents` is itself deprecated. It is a frozen, state-free
+EventTarget-compatible view over the `AIRuntimeState` source registered with
+this authority; it has no listener registry, `EventTarget`, or lifecycle state
+of its own. New consumers use the focused AIRuntimeState subscription helpers
+or `arcaneEvents.subscribe()`.
+
+## Stable authority failures
+
+`ARCANE_EVENT_ERROR_CODES` is frozen and maps every key below to the identical
+string value. Thrown authority errors expose that value as `error.code`:
+
+```text
+ARCANE_EVENT_AUTHORITY_ACCESSOR_COLLISION
+ARCANE_EVENT_AUTHORITY_VALUE_COLLISION
+ARCANE_EVENT_AUTHORITY_DESCRIPTOR_MISMATCH
+ARCANE_EVENT_AUTHORITY_PROTOCOL_MISMATCH
+ARCANE_EVENT_AUTHORITY_API_MISMATCH
+ARCANE_EVENT_AUTHORITY_INSTALL_FAILED
+ARCANE_EVENT_SOURCE_INVALID
+ARCANE_EVENT_SOURCE_ALREADY_REGISTERED
+ARCANE_EVENT_SOURCE_DISPOSED
+ARCANE_EVENT_SOURCE_EVENT_TYPE_UNDECLARED
+ARCANE_EVENT_COMPATIBILITY_DETAIL_INVALID
+ARCANE_EVENT_OCCURRENCE_INVALID
+ARCANE_EVENT_OCCURRENCE_SEQUENCE_EXHAUSTED
+ARCANE_EVENT_SOURCE_SEQUENCE_EXHAUSTED
+ARCANE_EVENT_LISTENER_CALLBACK_FAILED
+ARCANE_EVENT_DOM_DETAIL_COLLISION
+ARCANE_EVENT_DOM_TARGET_INVALID
+ARCANE_EVENT_DOM_OPTIONS_INVALID
+ARCANE_EVENT_SUBSCRIPTION_TYPE_INVALID
+ARCANE_EVENT_SUBSCRIPTION_HANDLER_INVALID
+ARCANE_EVENT_SUBSCRIPTION_OPTIONS_INVALID
+ARCANE_EVENT_SUBSCRIPTION_SIGNAL_INVALID
+ARCANE_EVENT_DISPATCH_EVENT_INVALID
 ```
 
-`on`, `once`, `off`, `emit`, `reset`, and `list` retain the synchronous
-`event-pubsub` contract. Synchronous subscriber exceptions propagate to the
-publisher. Subscriber promises are not awaited, so use the SDK's owned event
-queues for work whose completion, failure, or cancellation depends on an
-asynchronous callback.
+Listener callback failure is observational: it appears as
+`ARCANE_EVENT_LISTENER_CALLBACK_FAILED` inside the frozen
+`arcane.event.listener.error` occurrence. Its frozen public detail is
+`{code:'ARCANE_EVENT_LISTENER_CALLBACK_FAILED',reason:'listener-threw',
+eventType,occurrenceId,source,instanceId,operationId}`. Source disposal publishes
+`arcane.event.source.disposed` with public detail
+`{reason:'source-disposed'}` rather than throwing from committed source dispatch.
 
 ## Enable a bounded, complete event stack
 
@@ -71,7 +201,7 @@ arcaneEvents.disableTimeTravel();
 const serialized=arcaneEvents.exportStack();
 ```
 
-While enabled, every manager event receives an immutable
+While enabled, every isolated-manager event receives an immutable
 `arcane-event-stack/1` record containing the session and event ids, sequence,
 UTC and monotonic timestamps, source/category, correlation and causation ids,
 nested dispatch depth, a bounded payload snapshot, completion or failure
@@ -159,8 +289,6 @@ The npm artifact bundles the exact `event-pubsub` and `strong-type` pair because
 use must preserve that physical sibling layout and provide import-map entries
 for the public SDK entry and `event-pubsub`.
 
-The current `0.1.0-dev.5` hash-pinned Arcane browser runtime does not yet
-bootstrap or package this SDK-authored module. Built-in Shell, Provisioner, and
-native Arcane application instrumentation therefore belongs in the downstream
-Arcane OS integration work; this SDK release does not claim automatic coverage
-inside those surfaces.
+The managed Arcane browser runtime ships the authenticated focused entry and its
+dependency closure. Its import map resolves `arcane-os/event-manager` exactly;
+query, fragment, and subpath variants are not alternate authority identities.

package/docs/reference/README.md

@@ -39,9 +39,9 @@ This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.2.1` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
-| Browser runtime | SDK source commit `36fbe1418af3d5c343d105ee7c9456360c57785d`, SDK `0.2.1`, protocol `arcane/1` | The SDK-canonical exact 160-file runtime shipped under `runtime/`; Arcane OS commit `c540014afe69f14cf5ae60493b7295f36dbcec64` is legacy projection provenance, not a second source authority. |
-| Browser SDK runtime | SDK source commit `36fbe1418af3d5c343d105ee7c9456360c57785d`, SDK `0.2.1` | The exact 25-file authenticated browser closure: EventManager/DOM instrumentation and pinned event dependencies, Wllama runtime assets, and SDK browser speech provider/store/Worker mechanisms. It contains no model weights or speech adapter/model bytes. |
+| SDK and CLI | `arcane-os` `0.3.0` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm`, `arcane-os/ai/browser-speech`, and portable `arcane-os/mail` entrypoints in this checkout. |
+| Browser runtime | `runtime/ARCANE_RUNTIME_RELEASE.json`, SDK `0.3.0`, protocol `arcane/1` | The SDK-canonical dynamic runtime inventory shipped under `runtime/`; the receipt binds its exact paths, bytes, inventory, and digest. |
+| Browser SDK runtime | `browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json`, SDK `0.3.0` | The dynamically derived browser closure for events, Wllama, and Browser Speech mechanisms. It contains no speech runtime, model, voice, third-party legal/notice, or corresponding-source payloads. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract derived into `docs/reference/core/`. Canonical inventory and focused-member content was verified unchanged at Arcane OS `main` commit `13f3ce0ae34f77a3495331c8b4c30b1bb105f8ed`; SDK-local provenance, link, and package-boundary annotations are added explicitly. |
 
 The SDK runtime receipt and Core reference are distinct evidence and have
@@ -58,26 +58,25 @@ See [Core reference provenance](core/README.md) for the imported inventory and
 the exact distinction between a documentation snapshot and shipped runtime
 bytes.
 
-## Published 0.2.1
+## Published 0.2.3
 
-The published package is exactly `arcane-os@0.2.1` from source commit
-`36fbe1418af3d5c343d105ee7c9456360c57785d`. The npm `latest` dist-tag resolves
-to `0.2.1`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
+The most recently verified published package before this 0.3.0 source candidate
+is exactly `arcane-os@0.2.3` from source commit
+`d717f21d45664d20e4ed6377596db87c47492e11`. The npm `latest` dist-tag resolves
+to `0.2.3`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
 
-The provider supersession, legacy speech readiness, fail-closed compatibility,
-explicit STT activation/cancellation, TTS lifecycle, and route-owned voice
-corrections documented below are newer canonical source. They are not package
-authority in `0.2.1`; consumers require a fresh numeric publication before
-relying on them.
+The singleton-event, Mail, warn-first Browser Speech, and mixed-route contracts
+documented below are newer canonical source. They are not package authority in
+`0.2.3`; consumers require the numeric 0.3.0 publication before relying on them.
 
 | Evidence | Exact value |
 | --- | --- |
-| npm integrity | `sha512-FJ7zCFvQVZEMLQ8kn9IqddnFkfw397S87tENfLULwt0bN5hYn22wmN2zU50BqYC4zDKI/fdf4Rcl5G6A6KwlCg==` |
-| npm shasum | `9b21aea206582e367b8220ad45475ce69af5365a` |
-| Immutable release tarball | `arcane-os-0.2.1.manifest.json`; artifact `9623565709`; 6,951,752 bytes; SHA-256 `c9ebe6d5c0f8f808707a00ca055ef1fe142a3a51715df43f7da427be31c95808` |
-| GitHub release | [`0.2.1`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.2.1) (tag and title are both exactly `0.2.1`) |
-| Hosted source/artifact gate | [Check run 33013624030](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33013624030) |
-| Trusted publication | [Run 33013804158](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33013804158) |
+| npm integrity | `sha512-TZewkGM7dh9PdVnOtnkBO7QalJ6qyWWdKruCmsTxoHyeoG5XpqVbkNgiJhtBLhrIzgUV3vydYplxZQkIbIWoHg==` |
+| npm shasum | `8e978a23289a41db130253e6475a0c8bb0c0d73f` |
+| Immutable release tarball | `arcane-os-0.2.3.tgz`; 6,999,078 bytes; SHA-256 `857f179c2f9d4549e7691b4e6cebc49e5ab5e18600816443b26319c61fc1f85d` |
+| GitHub release | [`0.2.3`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.2.3) (tag and title are both exactly `0.2.3`) |
+| Hosted source/artifact gate | [Check run 33052271534](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33052271534) |
+| Trusted publication | [Run 33052383457](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33052383457) |
 
 The npm SLSA provenance binds the published package to that exact source commit
 and `.github/workflows/publish-dev.yml`. Hashes prove byte identity or
@@ -103,10 +102,10 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 169 semantic JavaScript records across 13 JavaScript
+The package exposes 200 semantic JavaScript records across 14 JavaScript
 entrypoints, plus eight JSON Schemas, its exact runtime manifest, and package
 metadata. Ten entrypoints are Node.js control-plane surfaces,
-`arcane-os/event-manager` runs in Node and browsers, and
+`arcane-os/event-manager` and `arcane-os/mail` run in Node and browsers, and
 `arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
 The [machine-readable package
 inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
@@ -117,7 +116,7 @@ download, install, or self-update.
 
 The synchronized browser payload exposes:
 
-- 83 JavaScript module artifacts under `runtime/arcane/modules/`, including
+- 84 JavaScript module artifacts under `runtime/arcane/modules/`, including
   ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
   mail transport;
 - 15 shared entity modules under `runtime/arcane/entities/`;
@@ -139,7 +138,7 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | --- | --- | --- |
 | Select, load, unload, inspect, cancel, and use LLM/STT/TTS independently | [`AIProviderRuntime.js`](runtime-modules.md#aiproviderruntimejs) | Cross-host controller; each registered provider declares its own host requirements. |
 | Observe sticky role state and startup settlement | [`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs) | Cross-host EventTarget state; observation grants no authority. |
-| Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml) and [`speech.html`](runtime-components.md#speechhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent. |
+| Offer explicit selected-model start/cancel UI | [`chat.html`](runtime-components.md#chathtml), [`speech.html`](runtime-components.md#speechhtml), and [`voice-transcription.html`](runtime-components.md#voice-transcriptionhtml) | Browser/native WebView components; user activation emits a cancelable request before any LLM or STT load intent, and recording stays disabled without sticky ready STT. |
 | Use Core-normalized chat | [`globalThis.Arcane.ai`](core/arcane-ai-contracts.md) | Native/Core only when separately admitted. |
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebGPU/full-offload evidence, WebAssembly, and OPFS/DBOPFS. |
 | Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers, and caller-supplied immutable runtime/model bytes. |
@@ -153,11 +152,12 @@ profiles, tools, business policy, and private data remain app-owned.
 
 An explicitly selected but unloaded model is not “ready.” `chat.html` keeps
 Send disabled and exposes a visible keyboard-operable LLM Start/Try again or
-Cancel loading control. `speech.html` keeps Hold to talk unavailable and offers
-the equivalent Start transcription/Try again/Cancel loading control for STT.
-Applications can override `requestAIActivation(intent)` or
-`requestSTTActivation(intent)`, or cancel the corresponding activation-request
-event. Imports and state observation emit no lifecycle intent, and default
+Cancel loading control. `speech.html` and `voice-transcription.html` keep their
+recording operations unavailable and share the equivalent Start
+transcription/Try again/Cancel loading control for STT. Applications can
+override `requestAIActivation(intent)` or `requestSTTActivation(intent)`, or
+cancel the corresponding activation-request event. Imports and state
+observation emit no lifecycle intent, and default
 `startTranscription=false` does not request an STT startup load or begin an
 automatic model download. It does not unload a role started independently.
 Compatibility availability never creates ready STT/TTS state without an