arcane-os 0.5.10 → 0.5.12

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.

package/docs/platform-targets.md

@@ -0,0 +1,104 @@
+# Platform target contract
+
+Every target adapter implements protocol `arcane-target-adapter/1` with these
+named operations:
+
+```text
+describe -> doctor -> prepare -> plan -> build -> run
+```
+
+The available browser adapter plans from the selected workspace and schema-1
+release manifest. The SDK also implements the process-local
+`arcane-native-build-plan/1` and `arcane-native-builder/1` boundary for an
+explicitly injected provider. It selects an app release and schema-2 descriptor,
+toolchain, platform, architecture, format, signing mode, declared dependency
+releases, and destination. Verification is a separate operation only when the
+user explicitly selects it for the release artifact.
+
+Native targets are available by explicitly pairing the SDK with fixed provider
+modules in a compatible Arcane OS checkout. Every native request also requires
+the canonical app descriptor to declare the exact target selected on the
+command line. The SDK package does not silently search for a toolchain, infer a
+descriptor target, embed the Arcane machine bundle, or substitute browser
+output. For example:
+
+```bash
+# Choose one target when creating each app repository.
+npx arcane-os@dev new my-app --path ./my-app --target portable --git
+cd my-app
+npm install
+npm exec -- arcane native-doctor --target portable --arcane-root "../Arcane OS"
+npm exec -- arcane build --target portable --arcane-root "../Arcane OS"
+
+# In an app scaffolded with --target windows-x64:
+npm exec -- arcane build --target windows-x64 --arcane-root "../Arcane OS"
+npm exec -- arcane run --target windows-x64 --arcane-root "../Arcane OS"
+
+# In an app scaffolded with --target linux-x64:
+npm exec -- arcane build --target linux-x64 --arcane-root "../Arcane OS"
+npm exec -- arcane run --target linux-x64 --arcane-root "../Arcane OS"
+
+# In an app scaffolded with --target linux-arm64, on native ARM64 Linux:
+npm exec -- arcane native-doctor --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
+npm exec -- arcane build --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
+npm exec -- arcane run --target linux-arm64 --arcane-root "../Arcane OS" --format deb --signing unsigned-local-test
+
+# In an app scaffolded with --target android-arm64. The run command requires
+# one connected physical Android device with native ARM64 support:
+npm exec -- arcane native-doctor --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
+npm exec -- arcane build --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
+npm exec -- arcane run --target android-arm64 --arcane-root "../Arcane OS" --format apk --signing development
+```
+
+Every native scaffold also declares the browser target, so one repository can
+use the normal browser development loop and its one selected native build. It
+includes the raster icon required by the current native platform. Use the
+matching scaffold target (`portable`, `windows-x64`, `linux-x64`, `linux-arm64`,
+or `android-arm64`) before running the corresponding command.
+
+`native-prepare` remains a standalone diagnostic. The normal build recipe omits
+it and lets `build` prepare the selected toolchain state.
+
+The portable output is an app-scoped Arcane Core directory. It is an explicit
+portable builder payload, not an executable, and it has no direct run operation.
+The external workspace defaults to `build/portable/`; integrated Arcane work
+must use the same canonical checkout for `--workspace` and `--arcane-root`, and
+must name an `--output-root` outside that checkout.
+
+Compatibility uses the highest minimum Core version declared by the SDK runtime,
+selected app, and bundled app dependencies, plus each app's Arcane protocol and
+required features, capabilities, and methods. Newer Core versions are accepted
+when those contracts remain available. See [compatibility.md](compatibility.md)
+for the complete compatibility and breaking-change rule.
+
+| Target | Formats | Development status |
+|---|---|---|
+| `browser` | `directory` | Available |
+| `portable` | `portable` directory | Available with explicit `--arcane-root`; not executable |
+| `windows-x64` | `exe` bundle | Available with explicit `--arcane-root`; unsigned local development only |
+| `linux-x64` | `deb` | Available with explicit `--arcane-root`; unsigned local development only |
+| `linux-arm64` | `deb` | Available with explicit `--arcane-root` on a compatible native ARM64 toolchain; unsigned local development only |
+| `android-arm64` | `apk` | Available with explicit `--arcane-root`; development-signed, architecture-neutral, and physical/native ARM64 for run |
+
+Every native target accepts one selected app release and its complete bundled
+dependency closure through the provider boundary. The providers retain the
+toolchain state required for build and, where supported, launch; app source and
+workspace paths are not supplied to the provider. Linux run extracts to a
+user-owned development tree without package installation or elevation.
+
+Linux ARM64 uses the implemented Linux provider and is available only with a
+compatible native ARM64 toolchain. The recorded target-scoped workflow built a
+native ARM64 DEB, exercised the AArch64 host/Core/bridge, reached WebKit readiness,
+and drained the owned process group. It loaded Ubuntu's packaged Bubblewrap
+AppArmor profile while leaving the global user-namespace restriction enabled.
+Android produces one development-signed APK with no native library or
+ABI-specific payload. The APK is therefore architecture-neutral, while
+`arcane run --target android-arm64` deliberately requires a physical device
+with native ARM64 support. The recorded development path exercised physical
+ARM64 build, readiness, cancellation, uninstall, and absence behavior. Both records
+are development evidence, not production readiness.
+
+Android AAB output, release signing, store publishing, and update continuity are
+deferred. Windows and Linux production signing, installation, and update
+acceptance also remain separate promotion work. The SDK never copies
+proprietary application source into the Arcane checkout to bypass the boundary.

package/docs/publishing.md

@@ -0,0 +1,126 @@
+# npm publication
+
+## Canonical main and npm channels
+
+`main` is the single canonical working and publication branch before and after
+the first release. Do not create a development branch. `-dev` versions select
+the npm `dev` dist-tag, while bare numeric stable versions select
+`latest`. These are registry channels, not Git branches.
+
+## Stable and development npm publication
+
+The package version and `publishConfig.tag` must agree exactly: `-dev` uses
+`dev`, and a bare numeric stable version uses `latest`. npm is the canonical
+SDK distribution: application repositories add an exact `arcane-os` project
+dependency and invoke its local CLI with `npm exec -- arcane`. A separate
+global installer, standalone SDK executable, NuGet package, Homebrew formula,
+or OS package is not part of this release surface.
+
+Publication checks run only after the user explicitly selects an npm release.
+That selected-release workflow validates package metadata, the executable and
+`.gitattributes` boundary, the complete package inventory, version/channel
+agreement, and required license notices. One unprivileged producer packs one
+`.tgz` under the selected Node and npm versions and uploads it as one Actions
+artifact with a recorded run id, artifact id, version, and source commit. It
+does not impose byte counts, hashes, digests, provenance receipts, or unrelated
+test suites as ordinary development gates. Broader integration, regression,
+platform, browser, presentation, and documentation work remains separately
+user selected.
+
+`publish-dev.yml` can run only when manually dispatched from `main` in
+`TheWizardNexus/arcane-os-sdk`. Dispatch supplies the exact successful Check
+run id, artifact id, and numeric version. The workflow downloads that exact Check
+artifact, derives `dev` or `latest` from its version, and publishes the selected
+`.tgz`. It may check out current source only for the publication controller; it
+never repacks current source and never invokes `npm pack` or `npm publish .`
+under publication authority. A
+repository-wide concurrency group prevents simultaneous publication jobs;
+GitHub may replace an older pending dispatch, and each surviving dispatch is
+safe to rerun. Preflight rejects tag rollback, malformed registry state, or any
+dist-tag other than `dev` and `latest`; an already-published matching version
+is an idempotent success. Post-publication status preserves the other channel
+and reports npm's response. It tolerates npm's publish-time scanning. If
+scanning or manual review remains pending, the workflow reports that state and
+a rerun safely resumes without republishing the version.
+
+The public `0.3.2` release is fixed to package-source commit
+`445bd2d982f12e6ef8dd2b615c70512000cc5224`, selected Check run
+`33264677687`, and publication/registry run `33264829711`. Its numeric Git tag
+and GitHub release title are both `0.3.2`. Later documentation or example
+commits do not replace that package authority.
+
+The unscoped package installs both `arcane` and `arcane-os`. The short command
+is the documented default; `arcane-os` is the collision-safe fallback. npm
+package names are unique, but executable names are not globally reserved.
+
+When `npm view arcane-os@dev version` reports the package unavailable, run
+`npm run pack:local` in this SDK checkout for local development, scaffold with
+`node ./bin/arcane.mjs new ...`, and install the resulting `.tgz` into the app
+with `npm install --save-dev --save-exact <path>`. Keep the tarball at the path
+recorded by `package-lock.json`; subsequent `npm ci` uses that declared package.
+Arcane reads the installed package's name and version against the root
+dependency declaration. A local directory `file:` install is intentionally unsupported because
+it may be linked.
+
+The npm package already has its trusted-publishing relationship. Each later
+release therefore follows the same direct selected-artifact path: push the
+intended `main` source, manually run Check for that exact revision, review the
+resulting package inventory and legal notices, then manually dispatch
+publication with that Check run and artifact. Confirm the selected version and
+dist-tag after publication. Never rebuild or repack the artifact under
+publication authority, and never substitute a different source revision.
+
+Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
+dependency source must be reachable by the runner. A sibling local tarball is a
+workstation workflow, not a portable GitHub dependency source; switch to the
+exact registry release (or deliberately vendor the tarball) before remote CI.
+
+## Reusable application release workflow
+
+The checked-in reusable workflow is not an ordinary supported release path
+until its implementation matches the governing contract below.
+
+External app repositories can call `.github/workflows/release-app.yml` from a
+selected SDK repository revision. The reusable workflow checks out the selected
+caller commit, installs only the caller's committed dependency lock, packages,
+bundles, and uploads one explicitly selected app. Any tests, checks, or artifact
+verification run only because that release output was explicitly selected.
+The workflow never publishes npm, creates a GitHub Release, loops across apps,
+or changes Arcane runtime policy.
+
+The one build job holds only `contents: read`. It uses the caller's normal
+locked installation, runs one selected `arcane package`, creates one selected
+`arcane bundle`, and uploads that complete bundle. It creates no hashes, byte
+identities, receipts, provenance records, or attestation sidecars and does not
+run a second admission job.
+
+Stable versioning, the npm `latest` tag, and an official GitHub release remain a
+separate explicit release decision. Current `main` development does not
+silently convert a `-dev` package into an official release. A stable release
+must publish the exact selected Check artifact under `latest`; GitHub may then
+attach that same package. Its Git
+tag and GitHub release title must both be the same bare numeric
+`MAJOR.MINOR.PATCH`. Prerelease versions do not get a misleading numeric
+GitHub release, and no release creates a Git branch for an npm dist-tag.
+
+## Documentation publication
+
+Documentation publication occurs only when the user explicitly selects it. The
+Pages job checks out that selected `main` revision without persistent
+credentials and uploads only the static `site/` tree. It does not automatically
+run the SDK test suite, checks, generators, or repository build code.
+
+The deployment job holds only the read, Pages, and OIDC permissions required by
+that selected artifact. The `github-pages` environment remains the final
+deployment authority. Documentation channels are post-registry presentation
+work and do not change the canonical source branch.
+
+## Work-amplification record
+
+The release graph is one selected `main` revision and one npm release candidate.
+One producer creates the tarball. Publication names that producer's exact Check
+run, artifact, and version and does not rebuild from a later checkout. The
+release workflow checks only the publication contract and required legal
+inventory for that selected output.
+Platform matrices, full product regressions, Pages, and broader presentation
+work remain separate user-selected operations.