arcane-os 0.5.9 → 0.5.11

package/docs/architecture.md

@@ -0,0 +1,303 @@
+# Architecture
+
+The CLI, future Arcane Developer graphical control panel, CI, and Codex all use
+one headless operation API. A client selects a named operation and consumes the
+same structured event stream; the GUI is not a second build system.
+
+```text
+external app repository -----+
+                              |
+Arcane OS consumer checkout --+-- CLI / future GUI / Codex / CI
+                                      |
+                               shared toolchain API
+                                      |
+                       browser package or explicit target adapter
+```
+
+## Canonical ownership and portability boundary
+
+The SDK repository is the canonical source for every mechanism that can be
+reused by a portable Arcane application. That includes shared modules,
+entities, components, themes, browser runtimes, providers, workers and assets;
+protocol, state, startup, readiness, progress, cancellation, unload and dispose
+machinery; public native contracts and adapters; the development source mount;
+and the packaging and license boundaries for that portable content. In
+particular, shared AI selected-role hydration, startup-settled state and events,
+role readiness, lifecycle and
+cancellation contracts, and the shared chat and speech components are
+SDK-owned source and contracts rather than Arcane OS–owned snapshots.
+
+Every portable application artifact materializes the complete SDK runtime,
+assets, workers, licenses and public contracts it uses. It remains self-contained whether it runs as plain
+HTML or inside an executable wrapper. It has no runtime dependency on an
+Arcane OS installation, source checkout or private Arcane OS import.
+
+Arcane OS is an SDK consumer like other applications. Its orchestrator,
+launcher, Shell, Provisioner, system AI application and internal tools use the
+same SDK modules and components rather than maintaining private runtime copies.
+Arcane OS and Core own the privileged host implementations, app/session
+admission and authorization, native transport and lifecycle, launcher and
+Shell orchestration, and system-AI policy specific to the Shell. The SDK may
+publish the capability-neutral Core bridge contract and adapters, but it does
+not embed Core or inherit another application's policy.
+
+Each application owns its branding, prompts, data, tools, business policy,
+model authorities and app-specific orchestration. Apply this decision order:
+
+| Responsibility | Canonical owner |
+|---|---|
+| Reusable by any portable application | Arcane SDK |
+| Host privilege, launcher, Shell or app/session admission | Arcane OS / Core |
+| Behavior unique to one product | That application |
+
+Do not copy a reusable implementation between the SDK, Arcane OS and an app,
+and do not create a hidden Arcane OS source dependency. Extend one neutral SDK
+contract and keep product policy in the consumer.
+
+Application and consumer tasks do not modify this repository's SDK source and
+do not hand-edit materialized `arcane/**` projections. They request a reusable
+change from an SDK source owner, or implement behavior that is specific to their
+product in that application's local source. Consumer projections change only
+through the selected public package and materializer.
+
+Development and distribution use different authority. The explicit
+`arcane dev --sdk-runtime-source <sdk-root>` development-only live source mount
+lets a refresh read the saved SDK source without copying it into the app.
+Distribution never follows that mount. It embeds the application's complete
+selected SDK projection.
+
+`runtime/arcane/` is the SDK-canonical source. Arcane OS must consume the
+selected SDK projection through the same package/source-mount boundary as
+other apps; its repository-side consumer cutover is coordinated separately and
+does not create a co-equal source. Git history records the completed ownership
+migration; the current tree has no OS-to-SDK synchronization path.
+
+## Workspace profiles
+
+An external workspace maps the exact runtime shipped by its locked `arcane-os`
+dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
+of portable runtime source. For live shared development, the explicit
+development-only SDK source mount maps the canonical SDK runtime and dependency
+paths into that consumer. Without the mount, the workspace uses its locked SDK
+projection. The development server and packager consume the same route
+destinations in both cases, so app imports do not change. Integrated
+initialization creates only app-owned files and never rewrites Arcane OS or SDK
+root configuration.
+
+The shared/Core development profile is a separate integrated-only scope selected
+with `--scope shared`. The SDK loads exactly
+`tools/integrated-development-provider.mjs` from the selected Arcane OS checkout
+as one process generation. This is a privileged host-development provider, not
+a source of portable SDK runtime content. That provider selects only one exact
+repository-relative focused `.test.mjs` through Arcane's canonical focused
+runner or Arcane's canonical development check. External workspaces cannot use
+the scope, and shared operations never enter app discovery, packaging, target
+planning, build, verification, or run paths. A generation change requires a new
+CLI process.
+Integrated app testing remains isolated to the selected `apps/<id>/test/`
+tree; it cannot recursively select Arcane root tests or another app's tests.
+External repositories retain their existing workspace-root plus selected-app
+test layout.
+
+## Development and release serving boundary
+
+Arcane applications keep one browser-first plain HTML, CSS, and JavaScript
+baseline. A native target runs that same application and progressively enhances
+it through capability-gated Arcane Core access. Browser operation must not
+depend on Core being present. A feature that genuinely requires Core reports
+its unavailability without breaking unrelated browser
+behavior or claiming that the capability exists.
+
+Rapid development uses `arcane dev`. The development server maps the selected
+application's canonical source tree and the live installed SDK/runtime routes.
+Each request reads and returns the complete current saved source, so a browser
+refresh shows source changes without packaging, copying
+files into `dist`, or restarting the server. Restarting is not a content
+synchronization step; when a refresh is stale, first verify the command, URL,
+workspace, selected app, and resolved source route.
+
+Development is an intentionally fast feedback loop. Keep each increment small
+and independently understandable so its effect has one clear cause and a
+mistake can be isolated without untangling unrelated work. A development
+operation does not implicitly run tests, checks, packaging, builds, or release
+verification. The developer invokes a focused test or check deliberately at an
+explicit checkpoint; merely refreshing source does not trigger one.
+
+Executable development uses an Arcane-owned native development wrapper around
+the same source-serving browser surface. The wrapper is an escalated browser,
+not a packaged application: it loads current source files and adds only the
+selected application's declared, capability-gated local Arcane Core access.
+It preserves the browser behavior when Core is absent, reports an unavailable
+native-only capability honestly, and never silently substitutes a release
+tree. Starting or refreshing this wrapper does not package, copy to `dist`, or
+run tests automatically. The SDK must not describe native source development as
+available until this wrapper and its explicit capability boundary are actually
+implemented.
+
+Packaging and release verification are separate explicit operations. Run
+`arcane package` to generate `dist/<id>`, then use
+`arcane run --target browser` to serve that selected release. Packaging does
+not automatically run tests or checks; those run only when the user expressly
+requests them or when required for a separately selected release output. The browser
+run command does not substitute source files. If source changes after
+packaging, the prior `dist` remains intentionally unchanged until the next
+explicit package operation. Never use packaged `dist` as the everyday
+development tree, and never treat source-serving behavior as evidence for the
+release artifact.
+
+## App and release contract
+
+The first SDK version deliberately preserves Arcane's current repository-shaped
+URLs and release schema:
+
+```text
+apps/<id>/arcane-app.json
+apps/<id>/arcane-package.json
+apps/<id>/index.html
+dist/<id>/ARCANE_APP_RELEASE.json
+```
+
+The authored schema-2 descriptor is canonical for new apps and projects an
+exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
+apps synthesize that descriptor from their schema-1 package plus the current
+native registry during migration.
+
+An external app's `arcane-packager.json` has three exact shared routes. They map
+the installed SDK runtime to `/arcane`, its vendored strong-type dependency to
+`/node_modules/strong-type`, and the SDK's `LICENSE`,
+`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. Development does
+not copy SDK runtime source into the app repository. Distribution materializes
+those selected SDK routes completely inside the portable artifact, so the
+finished app has no Arcane OS runtime dependency.
+
+Release schema 1 and builder identity `arcane-app-packager-v1` remain unchanged
+because current Arcane native consumers treat them as public contracts. Native
+builders consume the schema-2 descriptor as a separate build input while v1
+host artifacts remain unchanged.
+
+External repository delivery adds a distinct schema-1
+`arcane-app-release-bundle` envelope. Bundle creation uses an authored schema-2
+`arcane-app.json`; a synthesized package or registry projection remains valid for integrated
+packaging but is not used for an external bundle. The
+archive contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
+`payload/ARCANE_APP_RELEASE.json`, and the release inventory beneath `payload/`
+in that order. The envelope adds no repository-only source or build tooling
+beyond that selected release inventory. Individual apps remain responsible for
+their authored source policy.
+
+The bundle contract uses the documented USTAR+gzip structure. Explicit bundle
+verification parses the selected archive without extraction and rejects
+genuinely malformed structures, unsafe or colliding paths, unsupported members,
+trailing data, and incompatible bundle generations. These corrupt-artifact
+checks do not create byte-count, content-hash, provenance, or admission gates
+for ordinary development, packaging, serving, or running.
+
+Promotion preserves any prior output until the new archive is complete.
+Pre-commit failure restores that backup when doing so will not overwrite a
+concurrent change; otherwise the uncertain paths remain available for
+inspection. Ordinary results report the selected artifact and complete
+inventory without byte identities. The workflow creates no provenance,
+attestation, signing, or restrictive admission record.
+
+The governing reusable app-release contract uses one `contents: read` job to
+check out the selected caller revision, perform the caller's normal locked
+install, package and bundle one selected app, and upload that complete bundle.
+The checked-in workflow is unavailable until it matches this contract. The
+contract does not include a second verifier or privileged attestation job.
+
+## Operation ownership
+
+An invocation defaults to one workspace, one app, one command, one target, one
+architecture, one format, and one signing profile. It acknowledges before long
+work, uses one `AbortController`, supervises child processes, and routes progress
+through one serialized owned event queue. Process streams apply pause/resume
+backpressure and heartbeats coalesce. Callback failure cancels owned work, drains
+the queue, and reaches the caller or CLI exit status. Packaging preserves prior
+output until replacement is complete.
+
+Each normalized queue event is also mirrored exactly once through the shared
+`arcaneEvents` `EventManager`. That synchronous `event-pubsub` route is the
+canonical cross-cutting instrumentation surface, but it does not replace the
+owned asynchronous callback path or its backpressure. Time-travel history and
+DOM observation remain explicitly disabled unless a diagnostic session enables
+them. See [event-manager.md](event-manager.md) for the complete record, capture,
+DOM coverage, and effect-isolated playback boundaries.
+
+For `--scope shared`, the cardinality changes to one integrated workspace, one
+named operation, and either one exact test file or one development check. The
+same owned event queue and process supervisor provide acknowledgement, complete
+stream delivery with backpressure, heartbeat, cancellation, process-tree
+cleanup, and nonzero
+failure propagation. No app or target loop exists in that scope.
+
+## Complete-content ordinary path
+
+Packaging writes the complete schema-1 release inventory to
+`ARCANE_APP_RELEASE.json`. Ordinary development, packaging, serving, and run
+paths do not count, limit, hash, truncate, tail, clip, or identify content by
+bytes, and they do not require provenance or verification receipts. The
+loopback server reads and returns each complete selected source, runtime, or
+packaged file. Required credential protection, malformed-input rejection,
+applicable law, unavoidable protocol rules, and operating-system or browser
+safety remain in effect.
+
+## Native provider boundary
+
+The SDK implements protocol `arcane-native-build-plan/1` and the injected
+provider contract `arcane-native-builder/1`. Pairing is process-local; it never
+registers a mutable global provider or searches for a toolchain. For each
+supported native target, the CLI loads one fixed provider module from the
+explicit `--arcane-root` Arcane OS checkout. Provider code is bound to one
+process generation; if a pull changes loaded provider code, the caller starts a
+fresh worker. One paired toolchain can perform this lifecycle:
+
+```text
+doctor -> prepare -> plan -> build -> run
+```
+
+The portable provider reports honestly that run is unavailable because its
+result is a directory. Windows x64, Linux x64,
+Linux ARM64, and Android ARM64 implement same-process launch and owned
+cancellation when their compatible host/device requirements are present.
+Windows uses a retained per-build broker and host readiness. The
+Linux provider produces an amd64 or ARM64 DEB and runs a retained
+user-owned extraction without install or elevation. Portable, Windows, and
+Linux use the `unsigned-local-test` signing profile.
+
+The Android provider produces one development-signed APK. It contains no native
+library or ABI-specific payload, so the artifact is architecture-neutral; the
+`android-arm64` target instead binds the supported run path to one physical
+device with native ARM64 support. APK is the only Android format in this
+development provider. AAB, release signing, publishing, and update continuity
+remain outside it.
+
+The plan selects one explicit `toolchainRoot`, one app release root, its
+schema-2 descriptor, only its
+declared dependency releases, one non-overlapping output root, and one target,
+platform, architecture, format, and signing request. App source and workspace
+paths are withheld from the native provider. The provider copies the complete
+selected release rather than accepting an unrelated source path. Verification
+is a separate explicit operation for a selected release artifact.
+
+The SDK `0.5.11` 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
+declared feature, capability, and method. Missing requirements stop before
+provider build; a newer compatible Core is accepted. Browser-only apps may omit
+`minimumCoreVersion`, and missing permissions or optional security declarations
+normalize to empty records. The provider paths have
+been validated from independent workspaces. They do not copy proprietary source
+into the Arcane checkout.
+
+See [compatibility.md](compatibility.md) for the complete app and bundled-app
+compatibility rule and the required handling of breaking contract changes.
+
+Linux ARM64 shares the implemented Linux provider, focused tests, and a
+target-scoped remote evidence workflow. The recorded workflow exercised the
+native AArch64 toolchain, DEB, host/Core/bridge, sandboxed WebKit readiness, and
+owned process-group cancellation. The recorded Android development path
+exercised physical-device build, readiness, cancellation, uninstall, and
+absence behavior. Neither record establishes
+production signing, installation, publishing, update continuity, release
+acceptance, or production readiness.

package/docs/compatibility.md

@@ -0,0 +1,38 @@
+# Arcane application compatibility
+
+Arcane application compatibility is a capability contract, not an exact
+runtime-version pin. An app may run on a newer Arcane Core when the host meets
+all of the app's declared requirements.
+
+For a browser-only app, `permissions`, `security`, and
+`requirements.minimumCoreVersion` may be omitted. Missing permissions normalize
+to empty capability and method sets, and missing security normalizes to empty
+origin declarations with optional hardening disabled. Existing explicitly
+authored records remain unchanged.
+
+When the selected target actually uses Arcane Core, compatibility requires:
+
+- the requested target is declared by that app;
+- the host Core version is greater than or equal to the explicitly declared
+  `requirements.minimumCoreVersion`;
+- `requirements.arcaneProtocol` matches the host protocol generation;
+- every declared `requirements.features` entry is advertised by the host;
+- every declared `permissions.capabilities` entry is available; and
+- every declared `permissions.methods` entry is available.
+
+The effective Core floor for a native build is the highest minimum explicitly
+declared by the SDK runtime, the selected app, and its complete bundled-app
+closure. Browser-only targets do not invent a Core floor. The native build plan
+checks every member of that closure before producing output.
+
+This permits normal non-breaking Arcane upgrades. For example, an app requiring
+Core `0.8.12` can run on `0.8.13` or `0.9.0` when the required protocol,
+features, capabilities, and methods are still present. A higher version does
+not override a missing contract.
+
+Breaking changes must be visible at the contract boundary. A host must not
+continue advertising an old protocol, feature, capability, or method when its
+meaning or guarantees are no longer compatible. It must instead change the
+protocol generation or contract identifier so the incompatibility is reported
+before launch. Ordinary compatibility does not depend on byte counts, hashes,
+digests, provenance receipts, or optional security declarations.

package/docs/event-manager.md

@@ -0,0 +1,263 @@
+# Canonical SDK events and time-travel review
+
+`arcaneEvents` is the canonical synchronous SDK event authority. The module
+installs or reuses one current-protocol 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.
+
+When this module installs the authority, the global is an own, non-enumerable,
+writable, configurable data property. The created authority exposes
+`Symbol.for('arcane-os.arcane-events-authority')` and public `protocol` as
+`arcane-event-authority/1`. A later import reuses a value with that protocol and
+the required callable API. Otherwise the module installs a new authority when
+the property can be defined; installation failure reports
+`ARCANE_EVENT_AUTHORITY_INSTALL_FAILED`.
+
+Import the dedicated host-neutral entry point:
+
+```javascript
+import {
+    arcaneEvents,
+    createArcaneEventSource,
+    createEventManager,
+    projectArcaneDOMEvent,
+    PLAYBACK_RECORD_EVENT
+} from 'arcane-os/event-manager';
+```
+
+An SDK publisher owns one source handle for its lifetime and declares every
+semantic event type up front:
+
+```javascript
+const controller={};
+const events=createArcaneEventSource(controller,{
+    source:'app.editor',
+    eventTypes:['document.save.completed']
+});
+
+const unsubscribe=arcaneEvents.subscribe('document.save.completed',occurrence=>{
+    console.info('Saved',occurrence.detail.documentId);
+});
+
+const publication=events.dispatch(
+    'document.save.completed',
+    {documentId:'example',document:liveDocument},
+    {
+        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 handle exposes
+`{protocol,descriptor,source,instanceId,eventTypes,disposed,subscribe,on,once,
+addEventListener,removeEventListener,dispatch,dispatchEvent,dispose,destroy}`.
+
+`dispatch()` synchronously delivers one mutable `arcane-event-occurrence/1`
+to exact-type canonical subscribers, then an EventTarget-shaped view to the
+source's own listeners. The occurrence contains `occurrenceId`, `type`, `source`,
+`instanceId`, `operationId`, a complete plain-data snapshot in `detail`,
+`cancelable`, live `defaultPrevented`, and `preventDefault()`. When
+`publicDetail` is omitted, canonical detail is the normalized source detail;
+record values merge with explicitly supplied `publicDetail`, and other
+combinations are retained under `{compatibility,publicDetail}`. The same
+canonical detail enters optional time-travel history.
+
+Source listeners retain EventTarget compatibility: function listeners receive
+the source owner as `this`, and the source event view exposes that owner as
+both `target` and `currentTarget`. Plain records and arrays are shallow-copied;
+rich host objects remain local and are not recursively copied.
+EventTarget-shaped `addEventListener()` and `removeEventListener()` preserve
+native no-op handling 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 complete
+`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 handling, 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 DOM adapter: it
+creates one `CustomEvent`, adds the canonical identifiers to a mutable outer
+detail object, preserves any source-detail `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 direct EventManager-style diagnostics. Those handlers
+are separate from canonical `subscribe()` registrations; `off()` and `reset()`
+cannot remove canonical or source-owned registrations. SDK publishers use
+source handles. AIRuntimeState consumers use the focused subscription helpers
+or `arcaneEvents.subscribe()`.
+
+## Authority failures
+
+`ARCANE_EVENT_ERROR_CODES` maps every key below to the identical
+string value. Thrown authority errors expose that value as `error.code`:
+
+```text
+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_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
+```
+
+Listener callback failure is observational: it appears as
+`ARCANE_EVENT_LISTENER_CALLBACK_FAILED` inside the
+`arcane.event.listener.error` occurrence. Its complete public detail is
+`{code:'ARCANE_EVENT_LISTENER_CALLBACK_FAILED',reason:'listener-threw',
+eventType,occurrenceId,source,instanceId,operationId,error}`. Source disposal publishes
+`arcane.event.source.disposed` with normalized canonical detail
+`{source,instanceId,reason:'source-disposed'}` rather than throwing from committed
+source dispatch.
+
+## Enable a complete event stack
+
+Time-travel recording is disabled by default. With the flag off, the manager is
+only a pub/sub bus: it captures no history, source stack, or DOM activity.
+
+```javascript
+const events=createEventManager({
+    timeTravel:true,
+    dom:{root:document}
+});
+```
+
+It can also be enabled around a diagnostic session:
+
+```javascript
+arcaneEvents.enableTimeTravel({
+    dom:{root:document}
+});
+
+// Exercise the scenario.
+
+arcaneEvents.disableTimeTravel();
+const serialized=arcaneEvents.exportStack();
+```
+
+While enabled, every isolated-manager event receives a mutable
+`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 complete payload snapshot, completion or failure
+outcome, and dispatch duration. Recording preserves complete strings, URLs,
+public details, collections, object entries, nesting, and available source or
+error stack text. It performs no implicit redaction. Do not place credentials
+or secrets in event payloads or metadata. The durable JSON shape is published
+as `arcane-os/schemas/event-stack.json`.
+
+Recording retains the complete session until the caller clears history.
+Disabling recording stops future capture without clearing existing records. It
+never truncates, clips, tails, elides, or rotates event content. Arcane does not
+upload or persist a stack automatically.
+
+## DOM observation
+
+When a DOM root is attached while time travel is enabled, capture-phase
+listeners record the standard keyboard, pointer, mouse, touch, form, focus,
+clipboard, drag, selection, and scroll interaction set. A `MutationObserver`
+records attribute, text, insertion, and removal mutations, including old values
+where the platform exposes them. Open shadow roots present at startup or found
+in inserted nodes are observed separately; composed events are deduplicated.
+
+DOM instrumentation preserves complete input values, node markup and text,
+selectors, document and attribute URLs, keyboard/composition/input fields, and
+object-valued event details. It does not trim, clip, tail, redact, or otherwise
+shorten those values. This can include sensitive page content, so attach the
+diagnostic only when that complete capture is intended, never place credentials
+in the observed page or event payloads, and review recordings before sharing.
+`captureMutations:false` disables mutation observation, and
+`observeOpenShadowRoots:false` leaves open shadow roots outside the observer;
+interaction events remain complete.
+
+Mutation observation is an audit backstop, not proof of every renderer state
+change. It cannot see closed shadow roots, cross-origin frames, external web
+content, CSSOM/canvas drawing, most property-only writes, native/kernel activity,
+or interactions that happened before instrumentation started. Use semantic
+`instrument()` events at SDK-owned mutation boundaries when exact intent and
+causation matter.
+
+## Seek and playback
+
+`seek(sequence)` moves the diagnostic review cursor and emits
+`arcane.time-travel.seek`. It does not rewrite live DOM or application state.
+The default playback mode emits each complete record on
+`arcane.time-travel.playback.record` for a debugger or review UI:
+
+```javascript
+events.on(PLAYBACK_RECORD_EVENT,record=>reviewTimeline(record));
+await events.playback({stack:serialized,mode:'review',speed:2});
+```
+
+`speed: 0` plays immediately; a positive value preserves monotonic recorded
+delays at that multiplier. Playback supports `AbortSignal` and emits an explicit
+completed, cancelled, or failed terminal event. Recording is suppressed during
+playback so replay cannot recursively add itself to the stack.
+
+`mode: 'events'` redispatches recorded event payloads to live subscribers. That
+mode can execute application effects and is only appropriate inside an isolated
+diagnostic harness with effectful subscribers replaced. The SDK does not
+synthesize trusted browser input, restore a prior DOM snapshot, resend native
+RPC, repeat provisioning, launch processes, write storage, or repeat network or
+other privileged effects.
+
+## Browser delivery boundary
+
+The package entry point works directly in Node and through browser bundlers.
+The npm artifact bundles the exact `event-pubsub` and `strong-type` pair because
+`event-pubsub@6.1.0` uses a sibling-relative runtime import. Unbundled browser
+use must preserve that physical sibling layout and provide import-map entries
+for the public SDK entry and `event-pubsub`.
+
+The managed Arcane browser runtime ships the 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.