arcane-os 0.2.3 → 0.3.1

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.3` bundle
+The current SDK admits only the explicitly compatible `0.3.1` 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.3` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.3.1` 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.3` | 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 `f97ac4f2e7cc92a00a3a466c38a67446dd112acf`, SDK `0.2.3`, 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 `f97ac4f2e7cc92a00a3a466c38a67446dd112acf`, SDK `0.2.3` | 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,25 +58,23 @@ 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.2
+## Published 0.3.0
 
-The published package is exactly `arcane-os@0.2.2` from source commit
-`d5326d206bf0bec6ad82d53605e666841aa79899`. The npm `latest` dist-tag resolves
-to `0.2.2`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
+The verified published package is exactly `arcane-os@0.3.0` from source commit
+`72239d0221279b461f1be08b02a70105f4cf7364`. The npm `latest` dist-tag resolves
+to `0.3.0`; the separate `dev` dist-tag remains `0.1.0-dev.5`.
 
-The admission-aware `voice-transcription.html` lifecycle and shared
-`createSTTActivationController()` contract documented below are newer canonical
-source. They are not package authority in `0.2.2`; consumers require a fresh
-numeric publication before relying on them.
+The singleton-event, Mail, warn-first Browser Speech, and independent mixed-route
+contracts documented below are included in this exact package authority.
 
 | Evidence | Exact value |
 | --- | --- |
-| npm integrity | `sha512-JnLzZ4+FqX9tMgRv8HMcaCPSFx3xNNRf8BF8T03fD2ymg2g8cIGZRdD/3Tbd9PLtpx1PIKCpxz6nCP6ztnu1Nw==` |
-| npm shasum | `0b0d314acce48dcb5518470cd45a54221589d4d4` |
-| Immutable release tarball | `arcane-os-0.2.2.manifest.json`; artifact `9631659213`; 6,993,999 bytes; SHA-256 `e0fe1a556b603f67f5e3c142be7154b433312d3c0f3b58632df2e7fc43cc0ca7` |
-| GitHub release | [`0.2.2`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.2.2) (tag and title are both exactly `0.2.2`) |
-| Hosted source/artifact gate | [Check run 33034955277](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33034955277) |
-| Trusted publication | [Run 33035086265](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33035086265) |
+| npm integrity | `sha512-dh7QfM1ur48hOyMez1XWjym/LJcOAYy+Xl3KcvVQ6ewwX5N7ER82PQx6LE+zSb5sHVtz4TOU2AuARsrFNSwuVw==` |
+| npm shasum | `94075dad9c3974b0e069ecfe09f8d612d8a30ea7` |
+| Immutable release tarball | `arcane-os-0.3.0.tgz`; 7,230,292 bytes; SHA-256 `4afdb8113d8408b03917b73ce45e25bf4d302577fc6f199165d4931dda8ca081` |
+| GitHub release | [`0.3.0`](https://github.com/TheWizardNexus/arcane-os-sdk/releases/tag/0.3.0) (tag and title are both exactly `0.3.0`) |
+| Hosted source/artifact gate | [Check run 33130699235](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33130699235) |
+| Trusted publication | [Run 33131083176](https://github.com/TheWizardNexus/arcane-os-sdk/actions/runs/33131083176) |
 
 The npm SLSA provenance binds the published package to that exact source commit
 and `.github/workflows/publish-dev.yml`. Hashes prove byte identity or
@@ -102,10 +100,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)
@@ -116,7 +114,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/`;