arcane-os 0.1.0-dev.5 → 0.1.1

package/docs/publishing.md

@@ -1,42 +1,37 @@
-# Development publication
-
-## Current branch stage
-
-Until the first official SDK release, `main` is the single canonical working,
-integration, publication, and documentation branch. Pull requests and pushes
-target `main`, and the complete Node/platform matrix runs there. Do not use a
-separate development branch during this prerelease stage.
-
-After the first official release, ordinary work will move to a long-lived
-`dev` branch while `main` remains the canonical released line. That transition
-must be made as one explicit release change that updates branch protections,
-checks, trusted publication rules, documentation channels, and contributor
-instructions together. The future branch name alone grants no authority.
-
-## Development npm publication
-
-The current development npm version is `0.1.0-dev.5` and `publishConfig.tag` is
-`dev`, so a development publication does not become the default `latest`
-release. Query `npm view arcane-os@dev version` for current registry
-availability; immutable package documentation does not assert mutable registry
-state. 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. Vanilla Test's C# and Rust lifecycles do not turn this JavaScript SDK
-into a .NET or Rust package.
-
-`Check` first runs the development suite, then one unprivileged producer packs
-one `.tgz` under pinned Node and npm versions. The producer writes a canonical
-manifest containing the source SHA, clean-checkout flag, package inventory,
-byte length, SHA-256, npm SHA-1 shasum, and SHA-512 integrity. Windows x64,
-Linux x64, and a real macOS arm64 runner use the declared Node `22.23.2` floor
-and each download that same Actions
-artifact by immutable artifact id. They never repack it. Each runner verifies
-the receipt, installs the tarball into a disposable project, exercises
-`npm exec --offline -- arcane`, and runs a test imported from
-`arcane-os/testing` through the installed package's `arcane-test.mjs`. A final
-readiness job fails unless the producer and the complete native matrix pass.
+# 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.
+
+`Check` validates only package-publication authority once: package metadata,
+the executable and `.gitattributes` boundary, both authenticated runtime
+receipts, and the focused npm identity/channel/provenance contract. One
+unprivileged producer then packs one `.tgz` under pinned Node and npm versions.
+The producer writes a canonical manifest containing the source SHA,
+clean-checkout flag, package inventory, byte length, SHA-256, npm SHA-1 shasum,
+and SHA-512 integrity. One Ubuntu x64 consumer at the declared Node `22.23.2`
+floor downloads that Actions artifact by immutable artifact id, verifies the
+receipt, installs the tarball into a disposable project, exercises
+`npm exec --offline -- arcane`, and runs one small capability contract through
+the installed package's `arcane-test.mjs`. It never repacks. A final readiness
+job verifies the same artifact's identity, integrity, shasum, license inventory,
+and content boundary once. Golden snapshots, broad integration/regression and
+platform matrices, browser/process simulations, Pages, Examples, and
+presentation work are normal or post-registry checks rather than npm
+publication gates.
 
 `publish-dev.yml` can run only when manually dispatched from `main` in
 `TheWizardNexus/arcane-os-sdk`. Dispatch requires an authorized npm content
@@ -49,14 +44,19 @@ promotion. Direct trusted publishing is not permitted for that class.
 
 For the standard path, the workflow authenticates a successful `Check` push
 run for that exact `main` SHA, downloads its immutable package artifact,
-reverifies the manifest and bytes, and publishes the downloaded `.tgz`. It
+reverifies the manifest and bytes, derives `dev` or `latest` from the strict
+version, and publishes the downloaded `.tgz`. It
 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 byte mismatches, a backward `dev` move, or any
-dist-tag other than `dev`; an already-published matching version is an
-idempotent success. Post-publication
-verification tolerates npm's publish-time scanning for up to 15 minutes. If
+safe to rerun. Preflight rejects byte mismatches, tag rollback, malformed
+registry state, or any dist-tag other than `dev` and `latest`; an
+already-published matching version is an idempotent success. The historical
+first-version state where both tags identify `0.1.0-dev.5` is accepted only
+with its recorded integrity and shasum and only while no stable version exists.
+Post-publication verification preserves the other channel, checks integrity
+and shasum, and validates trusted-publisher provenance. It tolerates npm's
+publish-time scanning for up to 15 minutes. If
 scanning or manual review remains pending, the workflow reports that state and
 a rerun safely resumes verification without republishing immutable bytes.
 
@@ -73,10 +73,11 @@ integrity. Arcane separately requires the installed package to identify exactly
 as `arcane-os@0.1.0-dev.5` and verifies the locked runtime. A local directory
 `file:` install is intentionally unsupported because it may be linked.
 
-Before the first development publish, or while the registry package is absent:
+The first-version bootstrap established these permanent audit boundaries:
 
-1. Push the intended clean `main` commit and require the complete Check workflow,
-   including the exact-artifact Windows/Linux/macOS matrix, to pass.
+1. Push the intended clean `main` commit and require the npm-critical Check
+   workflow—package authority, one producer, one installed Linux capability
+   smoke, and one identity/legal verifier—to pass.
 2. Review the uploaded tarball inventory, manifest, checksum, and license
    notices. Ensure the Arcane OS monorepo package is private so it cannot publish
    the same npm name accidentally.
@@ -93,12 +94,10 @@ Before the first development publish, or while the registry package is absent:
    tarball. Do not rebuild or repack it for this bootstrap. After the package
    exists, standard releases may publish directly through OIDC, while dual-use
    releases must use `npm stage publish` and human 2FA promotion.
-5. Allow for npm publish-time scanning, then verify the registry's
-   `dist.integrity` equals the manifest, verify `dev` is
-   the only dist-tag, add a second appropriate owner, and configure npm trusted
-   publishing for the exact `publish-dev.yml` workflow and `npm` environment.
-   For a dual-use classification, grant stage-only trust instead of direct
-   publish authority.
+5. Verify the registry's `dist.integrity` and shasum. npm's required bootstrap
+   state has both `dev` and `latest` at the immutable `0.1.0-dev.5` bytes
+   until the first stable publish moves only `latest`. The sole trusted
+   publisher is the exact `publish-dev.yml` workflow and `npm` environment.
 6. Later standard development versions may use the workflow's direct OIDC
    authority. A dual-use version must be staged and promoted with human 2FA.
    Any missing policy decision, package bootstrap, environment, publisher
@@ -170,12 +169,12 @@ internal checksums alone do not grant authority.
 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 same matrix-tested `.tgz` under `latest`; only after registry
+must publish the same source-validated and platform-smoked `.tgz` under
+`latest`; only after registry
 integrity matches may GitHub attach that `.tgz`, manifest, and checksum. Its Git
 tag and GitHub release title must both be the same bare numeric
-`MAJOR.MINOR.PATCH`. The first stable change must also activate the documented
-`dev`/`main` branch transition and protections; prerelease versions do not get a
-misleading numeric GitHub release.
+`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
 
@@ -188,16 +187,15 @@ It does not rerun the SDK test suite or execute repository build code.
 
 The deployment job holds only the read, Pages, and OIDC permissions required by
 that single checked artifact. The `github-pages` environment remains the final
-deployment authority. A separate `/dev/` documentation channel is deferred to
-the same explicit post-release branch transition described above.
+deployment authority. Documentation channels are post-registry presentation
+work and do not change the canonical source branch.
 
 ## Work-amplification record
 
-The prerelease branch cardinality is one checked `main` SHA, one npm release
-candidate, one static site, and one Pages artifact. Four source-check jobs cover
-two supported Node lines on Windows and Linux. One producer creates the npm
-tarball once; three native consumers execute those exact bytes on Windows,
-Linux, and macOS; one readiness gate aggregates them. Development publication
-and Pages authenticate and reuse that successful exact-SHA evidence. Neither
-rebuilds the SDK package or reruns the suite, and Pages does not create a second
-site placement.
+The release graph is one checked `main` SHA and one npm release candidate. One
+package-authority job runs the narrow source policy and publication contract;
+one producer creates the tarball; one Ubuntu consumer executes those exact
+installed bytes; and one readiness job verifies identity and legal inventory.
+OIDC publication reuses that successful exact-SHA artifact without rebuilding.
+Platform matrices, full product regressions, Pages, and broader presentation
+work remain outside registry publication and run separately when warranted.

package/docs/reference/README.md

@@ -19,6 +19,7 @@ high-level page links to the relevant deep section instead of repeating it.
 | Use the Node.js package API | [SDK JavaScript API](sdk-api.md) |
 | Publish central events, capture bounded time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
 | Use the `arcane` command | [CLI reference](cli.md) |
+| Generate named browser imports or inspect the authenticated physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
 | Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
 | Use a shared entity | [Runtime entity modules](runtime-entities.md) and [exact export contracts](core/arcane-entities.md) |
@@ -36,7 +37,7 @@ This repository contains two related, explicitly versioned surfaces:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.1.0-dev.5` | The Node.js toolchain and package exports in this checkout. |
+| SDK and CLI | `arcane-os` `0.1.0` | The Node.js toolchain and package exports in this checkout. |
 | Browser runtime | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, bundle `0.8.12`, protocol `arcane/1` | The exact 155-file runtime snapshot shipped under `runtime/`. |
 | 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. |
 

package/docs/reference/cli.md

@@ -16,6 +16,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane new <id>` | Creates one external app workspace. |
 | `arcane init [id]` | Initializes one app in an external or integrated workspace without rewriting unrelated files. |
 | `arcane doctor` | Reads and reports Node/tooling, SDK runtime, workspace, optional Arcane source recognition, and supported managed ArcaneOllama readiness. |
+| `arcane import-map` | Authenticates and refreshes one app's managed browser import map and matching HTML entry. |
 | `arcane dev` | Starts one owned browser development server for one selected app. |
 | `arcane test` | Runs one app test boundary or one explicit integrated shared test file. |
 | `arcane check` | Validates one app boundary or the canonical integrated shared check. |
@@ -162,6 +163,88 @@ failure into a failed doctor result.
 npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 ```
 
+## `arcane import-map`
+
+### Overview
+
+Authenticates one selected application's physical browser runtime, generates
+its standard browser import map, and commits the map artifact and matching
+managed HTML entry as one bounded refresh.
+
+```text
+arcane import-map [--workspace <directory>] [--app <id>]
+```
+
+`--workspace` defaults to the current directory. `--app` selects one app when
+the workspace does not already identify exactly one. The command accepts no
+positional arguments and supports app scope only. `arcane-os import-map` is the
+identical executable alias.
+
+The generated artifact is
+`apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
+the app entry as `<script type="importmap" data-arcane-import-map>` before
+module loading. In SDK `0.1.0`, the authenticated physical-v1 runtime produces
+85 entries and intentionally has no package-root mapping.
+
+### Result and safety
+
+Success returns the normal selected-workspace wrapper:
+
+```javascript
+{
+    workspaceRoot,
+    workspaceMode, // 'external' or 'integrated'
+    appId,
+    importMap:{
+        appId,
+        artifactPath,
+        artifactRelativePath,
+        entryPath,
+        imports,
+        entryCount:85,
+        excludedModules:['modules/CaseEvidenceIndexer.js'],
+        files:[
+            {role:'artifact',path,bytes,sha256},
+            {role:'entry',path,bytes,sha256}
+        ],
+        cleanupWarnings,
+        committed:true
+    }
+}
+```
+
+The two file records bind the committed byte length and SHA-256 for the artifact
+and HTML entry. A post-commit observer failure preserves delivery as a successful
+receipt with `eventDelivery.status === 'degraded'` and
+`ARCANE_EVENT_DELIVERY_FAILED`; it does not roll back valid application bytes.
+Packaging refuses a committed refresh that reports cleanup warnings.
+
+The canonical integrated-legacy workspace has a deliberate compatibility
+result instead of an artifact: `importMap.skipped` is `true`,
+`importMap.compatibility` is `'integrated-legacy'`, and the reason states that
+the physical two-route browser runtime is retained.
+
+`new` and `init` generate the map during scaffolding. `dev` refreshes it once
+before binding; non-dry-run `package` and browser `build` refresh it before
+collection. Paired native packaging refreshes each packaged app. `test`,
+`check`, `verify`, `bundle`, and browser `run` do not regenerate it. There is no
+watcher, polling, scheduled refresh, download, or self-update behavior.
+
+There is no supported `--dry-run` for `import-map`: do not pass that parser-wide
+flag because this command performs the real commit. Import-map-specific failures
+use `ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, or
+`ARCANE_IMPORT_MAP_COLLISION`; packaging can additionally report
+`ARCANE_IMPORT_MAP_CLEANUP_FAILED`. Workspace, policy, usage, busy, and
+cancellation failures retain their normal SDK codes.
+
+### Example
+
+```bash
+npm exec -- arcane import-map --workspace . --app hello-world --output json
+```
+
+Deep details: [authenticated browser delivery and receipts](protocols.md#browser-runtime-delivery).
+
 ## `arcane dev`
 
 ### Overview
@@ -471,9 +554,9 @@ Success returns:
 ```javascript
 {
     packageName:'arcane-os',
-    currentVersion:'0.1.0-dev.4',
-    registryVersion:'0.1.0-dev.5',
-    tag:'dev',
+    currentVersion:'0.1.0',
+    registryVersion:'0.1.1',
+    tag:'latest',
     status:'update-available', // or 'current' or 'ahead'
     updateAvailable:true,
     registry:'https://registry.npmjs.org',

package/docs/reference/event-manager.md

@@ -16,7 +16,10 @@ The API is capability-first:
 
 All 20 JavaScript exports are available from both `arcane-os` and
 `arcane-os/event-manager`. The bindings are identical, so choose the focused
-subpath when event instrumentation is the only SDK capability you need.
+subpath when event instrumentation is the only SDK capability you need. Node
+can resolve either package entrypoint. The generated browser map intentionally
+exposes only the focused `arcane-os/event-manager` entry, not the Node package
+root.
 
 ## Quick start
 
@@ -53,15 +56,21 @@ bounded, export intentionally, then call `clearHistory()`.
 
 | Capability | Node | Browser renderer | Native/Core host | Remote or cloud | Normalization |
 | --- | --- | --- | --- | --- | --- |
-| Pub/sub, semantic instrumentation, parse/export, seek, playback | Yes | Yes, through a bundler or import map | Only when the SDK module runs in that JavaScript host | No automatic transport | Same synchronous API; optional immutable JSON-like snapshots |
+| Pub/sub, semantic instrumentation, parse/export, seek, playback | Yes | Yes, through a bundler or the managed Arcane import map | Only when the SDK module runs in that JavaScript host | No automatic transport | Same synchronous API; optional immutable JSON-like snapshots |
 | DOM selectors and target descriptions | With DOM-like values or a test shim | Yes | No native UI observation | No | Stable diagnostic descriptors |
 | DOM interaction and mutation capture | No native DOM | Yes | No | No | DOM activity becomes semantic event-stack records |
 | Event-stack schema | Yes | Yes | Data contract only | Can be transported explicitly by the developer | `arcane-event-stack/1` |
 
-An unbundled browser must serve and map `arcane-os` and `event-pubsub`. The
-hash-pinned Arcane browser runtime does not automatically inject this SDK-authored
-module into Shell, Provisioner, Core, or built-in apps. There is no transparent
-fallback to `arcane/1`, HTTP, WebSocket, Ollama, or a cloud event service.
+In an external or physical-v1 integrated workspace, the managed browser map
+resolves `arcane-os/event-manager` to
+`./arcane/sdk/event-manager.mjs` and its private bare dependency
+`event-pubsub` to
+`./arcane/sdk/dependencies/event-pubsub/index.js`. The canonical
+integrated-legacy workspace retains its older physical routes instead. The
+hash-pinned Arcane browser runtime does not inject this SDK-authored module into
+Shell, Provisioner, Core, or built-in apps. There is no transparent fallback to
+the Node package root, `arcane/1`, HTTP, WebSocket, Ollama, or a cloud event
+service.
 
 ## Export summary
 
@@ -235,11 +244,11 @@ Seeking never rewrites DOM, storage, native state, processes, or network state.
 
 ```javascript
 await events.playback({
-    stack=null,
-    fromSequence=1,
-    toSequence=Number.MAX_SAFE_INTEGER,
-    speed=0,
-    mode='review',
+    stack:null,
+    fromSequence:1,
+    toSequence:Number.MAX_SAFE_INTEGER,
+    speed:0,
+    mode:'review',
     signal,
     onRecord
 });

package/docs/reference/inventory/package-api.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.1.0-dev.5",
+  "sdkVersion": "0.1.0",
   "environment": {
     "runtime": "Node.js",
     "minimumVersion": "22.23.2",

package/docs/reference/protocols.md

@@ -47,6 +47,14 @@ These protocols normalize orchestration and evidence. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
+Managed browser imports have three supported control-plane entrypoints. The CLI
+uses `arcane import-map`; Node callers use
+`executeOperation('import-map', options)` or
+`createToolchain(defaults).importMap(options)`. These are three routes to the
+same app-scoped operation, not three import-map formats. There is no exported
+`importMapApplication()` function, `generateImportMap()` function, or
+`arcane-os/import-map` package subpath.
+
 ## Central events and time-travel data
 
 `arcane-os/event-manager` is host-neutral JavaScript. Its live event path is
@@ -83,18 +91,105 @@ surface, DOM privacy defaults, playback modes, and recovery behavior.
 
 ## Browser runtime delivery
 
-External and integrated workspaces keep the same application URLs. Runtime ESM
-is served beneath `/arcane`, the vendored dependency beneath
-`/node_modules/strong-type`, and license material beneath
-`/licenses/arcane-os`. A browser import such as:
+External and modern integrated workspaces keep the same application URLs and a
+browser-standard import map. Each selected app owns
+`apps/<id>/modules/arcane.importmap.json`; the exact canonical JSON is also
+embedded in its HTML entry as a managed `<script type="importmap"
+data-arcane-import-map>`. The map follows `<base>` and precedes module scripts,
+classic scripts, and module preloads, so application code can use stable named
+imports such as:
 
 ```javascript
-import ollama from '/arcane/modules/Ollama.js';
+import ollama from 'arcane/Ollama';
+```
+
+The authenticated physical-v1 tree lives entirely beneath `arcane/`. It
+contains 155 pinned Arcane runtime files plus eight SDK browser-runtime files:
+163 files in all. Runtime `strong-type` 1.1 stays under
+`arcane/dependencies/strong-type/`; the focused SDK event surface lives under
+`arcane/sdk/`, with `event-pubsub` 6.1 and its sibling `strong-type` 2.0 under
+`arcane/sdk/dependencies/`. This URL-key separation prevents the runtime and SDK
+dependency versions from aliasing one another. Development serves the selected
+app plus that authenticated tree. Packaging copies the same map, app entry, and
+physical bytes into `dist/<id>`; targets never resolve through the consumer
+workspace's root `node_modules/`.
+
+In SDK `0.1.0`, the generated map has exactly 85 entries: 73 named
+`arcane/*` modules, nine `arcane/entities/*` modules, and these three focused or
+compatibility mappings:
+
+| Browser specifier | Physical target |
+| --- | --- |
+| `arcane-os/event-manager` | `./arcane/sdk/event-manager.mjs` |
+| `event-pubsub` | `./arcane/sdk/dependencies/event-pubsub/index.js` |
+| `./node_modules/strong-type/index.js` | `./arcane/dependencies/strong-type/index.js` |
+
+There is no `arcane-os` package-root mapping, bare `strong-type` mapping, or
+catch-all `arcane/` prefix. Host-internal `CaseEvidenceIndexer.js` is explicitly
+excluded; classic scripts, workers, stylesheets, and other non-ESM assets use
+their documented URL or host loading contract rather than invented package
+bindings.
+
+The imported module can be pure browser logic, standard-Web-API logic, or a
+client of `globalThis.Arcane`. Import-map resolution is not a new Arcane wire
+protocol, Core capability, network authority, or provider fallback. Import
+transport and host RPC remain separate layers.
+
+The canonical integrated-legacy Arcane OS root is the documented exception. It
+retains its physical `/arcane` and `/node_modules/strong-type` routes, returns
+an `integrated-legacy` skip receipt, and does not create the managed map pair.
+
+<details>
+<summary>Refresh lifecycle and two-file commit behavior</summary>
+
+Scaffolding (`new` and `init`) creates the map. `dev` refreshes once before
+binding. Non-dry-run `package`, browser `build`, and paired native packaging
+refresh before collecting source. `test`, `check`, `verify`, `bundle`, and
+browser `run` do not refresh. Dry-run packaging/build validates an existing map
+without rewriting it, and `import-map` itself has no supported dry-run.
+
+Generation stages the artifact and HTML entry beside their destinations,
+checks directory and file identity under the workspace-operation lock, and
+uses backups to restore the prior pair after a handled pre-commit failure.
+Success reports `committed: true` and SHA-256/byte-length records for both
+files. Cleanup failures after commit remain warnings on the valid receipt;
+packaging rejects them rather than publishing ambiguous state. This is a
+bounded handled-error transaction, not a claim of one filesystem-atomic rename
+for both files and not a durable crash journal.
+
+No app watches, polls, downloads, or self-updates this map. An active operation's
+heartbeat is event telemetry only and never regenerates browser state.
+
+</details>
+
+<details>
+<summary>SDK browser-runtime admission and exact receipt fields</summary>
+
+`arcane.lock.json.sdkBrowserRuntime` persists the trusted manifest path,
+`manifestSha256`, `contentSha256`, `builder`, `sdkVersion`, and `source` record.
+For SDK `0.1.0` those identities are:
+
+```text
+manifest: node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json
+manifestSha256: 43baaec850291c28795f6c194001deb5febab88ccab1b033bce6597dd6f6f08f
+contentSha256: 0caa302bc07d4a45f5290504ec62ddce98fdf5e3412f916c10aae3d51b1e5f7c
+builder: arcane-sdk-browser-runtime-v1
+sdkVersion: 0.1.0
+source.protocol: arcane-sdk-browser-runtime/1
+source.browserEntry: arcane-os/event-manager
 ```
 
-uses browser ESM in every renderer. The imported module can be pure browser
-logic, standard-Web-API logic, or a client of `globalThis.Arcane`. Import
-transport and host RPC are separate layers.
+The `source` record also binds the `arcane-os-sdk` authority/repository and the
+exact `event-pubsub` 6.1.0 and `strong-type` 2.0.0 package identities. Before a
+workspace tree is admitted, the same-process verifier returns
+`schemaVersion`, `kind`, `canonicalLocation`, `rootIdentity`, `manifestPath`,
+`manifestSha256`, `manifestIdentity`, `builder`, `sdkVersion`, `source`,
+`files`, `fileCount`, `totalBytes`, `contentSha256`, `identities`,
+`sourceIdentities`, and `directories`. Those object-identity-bound verifier
+receipts are authority inside the issuing process; reconstructing the same JSON
+does not recreate authority.
+
+</details>
 
 ## Arcane application protocol
 
@@ -190,7 +285,7 @@ Arcane normalizes the outer promise/error and stream lifecycle. `chatText`,
 
 ## Explicit cloud provider path
 
-`/arcane/modules/AI.js` can use an explicitly selected and configured cloud
+`arcane/AI` can use an explicitly selected and configured cloud
 profile over HTTPS. That path is not Core transport fallback. The module adapts
 the selected provider into its high-level application behavior, while provider
 diagnostics and optional fields can remain provider-specific. Native policy and
@@ -231,11 +326,14 @@ The common contract ends where platform truth must remain different:
 
 ## Receipt and generation boundaries
 
-SDK runtime, app releases, bundles, native plans, providers, and artifacts use
-identity-bound receipts. A receipt binds the exact location, filesystem
-identity, bytes/inventory hashes, policy, toolchain, platform/architecture,
-signer/trust result where applicable, and generation. Mutation invalidates the
-receipt before bytes or authority change.
+SDK runtime, app releases, import-map artifact/entry pairs, bundles, native
+plans, providers, and artifacts use identity-bound receipts. The import-map
+receipt binds each committed relative path, byte length, and SHA-256 in
+addition to its exact imports, entry count, exclusions, and cleanup state. A
+runtime or release receipt binds the exact location, filesystem identity,
+bytes/inventory hashes, policy, toolchain, platform/architecture, signer/trust
+result where applicable, and generation. Mutation invalidates the receipt
+before bytes or authority change.
 
 Process-local receipts do not authorize reuse across Shell, Core, providers, or
 other processes. Cross-process reuse requires an authenticated shared host or

package/docs/reference/sdk-api.md

@@ -1,11 +1,17 @@
 # Arcane OS SDK JavaScript API
 
-The npm package exposes a Node.js ESM control plane. It is not a browser-importable renderer API. Use the synchronized modules under `/arcane/` for application code and use `globalThis.Arcane` for capability-gated native calls.
+The npm package exposes a Node.js ESM control plane. It is not a browser-importable renderer API. Application code uses named modules from the managed browser map, such as `arcane/ThemeBootstrap`, uses the focused `arcane-os/event-manager` browser entry when needed, and calls `globalThis.Arcane` for capability-gated host behavior.
 
 This page is the canonical inventory for every JavaScript name reachable through `package.json#exports`. The same binding can appear at the root and a focused subpath; those entrypoints are listed together. The root workspace `discoverApps` and the low-level packager `discoverApps` are intentionally separate records because they are different functions.
 
 ## Import map
 
+This table is the Node `package.json#exports` map: it defines package
+entrypoints for SDK/tooling code. It is distinct from the generated browser
+import map that resolves application-facing `arcane/*` modules and the focused
+EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
+for that 85-entry physical-runtime contract.
+
 | Specifier | Purpose |
 | --- | --- |
 | `arcane-os` | Complete high-level SDK surface. |
@@ -2634,6 +2640,13 @@ Frozen registry of stable SDK error-code strings.
 registry, timeout, HTTP, or response failure; caller cancellation remains the
 separate `ERROR_CODES.cancelled` value.
 
+The import-map operation also reports the stable operation-specific strings
+`ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, and
+`ARCANE_IMPORT_MAP_COLLISION`; package assembly can additionally report
+`ARCANE_IMPORT_MAP_CLEANUP_FAILED`. They are normalized `ArcaneError.code`
+values, but are not properties added to this frozen general registry in SDK
+`0.1.0`.
+
 ### Value and import
 
 ```text
@@ -3417,9 +3430,12 @@ async function usecreateApplication(...arguments_) {
 
 Returns a frozen convenience object that applies shared defaults to every headless application operation.
 
-The object includes `updateCheck(options)`, which merges defaults with the
-explicit call options and invokes `checkSdkUpdate()` once. Constructing the
-toolchain does not check, poll, schedule, download, install, or mutate anything.
+The object includes `importMap(options)`, which merges defaults with explicit
+call options and performs one selected app's authenticated map refresh. The
+equivalent generic route is `execute('import-map', options)`. It also includes
+`updateCheck(options)`, which invokes `checkSdkUpdate()` once. Constructing the
+toolchain does not check, poll, schedule, download, install, regenerate, or
+mutate anything.
 
 ### Signature and result
 
@@ -3440,14 +3456,15 @@ import {createToolchain} from 'arcane-os';
 
 const toolchain = createToolchain({
     workspaceRoot: process.cwd(),
+    appId:'hello-world',
     onEvent(event) {
         console.info(event.type);
     }
 });
 
-// Only this explicit call performs the single bounded registry request.
-const status = await toolchain.updateCheck();
-console.log(status.status);
+// Only this explicit call refreshes the managed map and HTML entry.
+const result = await toolchain.importMap();
+console.log(result.importMap.entryCount); // 85 in SDK 0.1.0
 ```
 
 ## describeTargets()
@@ -3512,9 +3529,18 @@ async function usedevelopApplication(...arguments_) {
 
 Dispatches one named headless SDK operation with normalized acceptance, events, cancellation, and failure.
 
+The exact command `'import-map'` dispatches one app-scoped authenticated refresh
+and returns `{workspaceRoot, workspaceMode, appId, importMap}`. A normal
+`importMap` value binds the generated imports and the committed map/HTML file
+hashes; the canonical integrated-legacy layout returns its documented skip
+record instead. This route mutates the two managed application files and has no
+supported dry-run.
+
 The exact command `'update-check'` dispatches one `checkSdkUpdate(options)`
-call. Dispatch never installs a recurring task and never causes another command
-to check for updates implicitly.
+call. Dispatch never installs a recurring task, polls application state, or
+causes another command to check for updates implicitly. There is no exported
+`importMapApplication()` or `generateImportMap()` binding and no
+`arcane-os/import-map` package subpath.
 
 ### Signature and result
 
@@ -3533,8 +3559,11 @@ Import it from `arcane-os` or `arcane-os/toolchain`. The signature above states
 ```javascript
 import {executeOperation} from 'arcane-os';
 
-const result = await executeOperation('update-check');
-console.log(result.status, result.registryVersion);
+const result = await executeOperation('import-map', {
+    workspaceRoot:process.cwd(),
+    appId:'hello-world'
+});
+console.log(result.importMap.committed, result.importMap.entryCount);
 ```
 
 ## packageApplication()