arcane-os 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.2
+
+- Preserved complete application, document, model, message, event, process,
+  mail, and diagnostic content across the ordinary SDK runtime and tooling.
+- Removed ordinary byte, hash, digest, receipt, provenance, exact-inventory,
+  truncation, clipping, freeze, and unapproved hardening gates while retaining
+  unavoidable transport framing and credential protection at their owners.
+- Added the complete browser-WASM chat, speech, persistence, structural-tool,
+  source-example serving, descriptor, packaging, and application-test contracts
+  required by SDK consumers, with optional security remaining opt-in.
+- Limited the npm package to consumer runtime, source, schema, CLI/tooling, and
+  required root metadata; examples, documentation, generated site output, and
+  tests remain repository-owned follow-up surfaces outside the published package.
+
+## 0.3.1
+
+- Restored ordinary warn-first Browser Speech operation with explicit
+  `secure:false` defaults, one concise load warning, and truthful
+  `unchecked`/`pending`/`verified`/`failed` integrity telemetry while keeping
+  strict authenticated-graph admission behind explicit `secure:true`.
+- Added atomic hydration for exact saved-but-unregistered STT/TTS selections
+  without a transient provider fallback, including independent mixed
+  browser/Cloud/Core role ownership and mismatch-safe rollback.
+- Continued to resolve speech runtimes, models, voices, and providers from
+  their upstream npm/fetch distribution paths; the SDK package redistributes
+  none of those third-party payloads or their legal corpora.
+
 ## 0.3.0
 
 - Added the branded, versioned, per-realm `globalThis.arcaneEvents` authority

package/README.md

@@ -19,15 +19,15 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.3.0` SDK contract. Applications pin one exact npm
-version and lockfile; registry state is deliberately not baked into immutable
-application artifacts.
+This checkout defines the `0.3.2` SDK contract. Applications pin one exact npm
+version and lockfile; registry state is deliberately not baked into application
+artifacts.
 
 That registry query is a maintainer action, not an application behavior. Apps
 never poll npm for SDK updates or replace their own SDK or synchronized runtime.
 The app repository's exact dependency and lockfile select the SDK; changing that
-selection is an explicit repository update followed by the normal validation
-and release gates.
+selection is an explicit repository update. Tests and checks run only when the
+user expressly selects them, or when required for a selected release output.
 
 ## Developer API reference
 
@@ -47,14 +47,14 @@ Use `arcane-os/event-manager` as the primary instrumentation surface for new
 SDK code. Its shared `arcaneEvents` bus is powered by `event-pubsub`; SDK-owned
 operation queues already mirror their normalized events through it while
 preserving awaited delivery and cancellation. An opt-in `timeTravel` flag adds
-timestamped causal event stacks, bounded snapshots, export/import, seek and safe
-review playback. Attaching a DOM root records interactions and mutation records,
+complete timestamped causal event stacks, export/import, seek and safe review
+playback. Attaching a DOM root records interactions and mutation records,
 including supported open shadow roots. Source-stack capture is a separate,
 off-by-default diagnostic option.
 
-Recording is off by default. A session is complete until its configured event
-limit; reaching that limit appends an overflow marker and disables recording
-instead of silently evicting history. Review [the EventManager guide](docs/event-manager.md)
+Recording is off by default. Once explicitly enabled, a session retains its
+complete recorded content until the caller clears it or disables recording.
+Review [the EventManager guide](docs/event-manager.md)
 before enabling DOM values, node content, event details, source stacks, or live
 event redispatch. Password targets, text-entry details, clipboard data, URL
 attributes, and common credential keys are excluded or redacted by default.
@@ -63,28 +63,21 @@ attributes, and common credential keys are excluded or redacted by default.
 
 The SDK repository is the canonical source for portable shared runtime modules,
 entities, components, themes, browser providers and workers, public contracts,
-and their packaged byte receipts. Portable applications consume those
+and their packaged content. Portable applications consume those
 SDK-owned paths and never read an Arcane OS install or source checkout at
 runtime. Arcane OS is a consumer of this contract; its repository-side cutover
 is coordinated separately and cannot become a second source authority.
 
 The source-authority cutover is complete. `runtime/arcane/` is authored here,
-and its generated manifest authenticates the complete portable inventory. The
-old Arcane OS-to-SDK synchronization direction is retired and fails closed; it
-cannot overwrite SDK-canonical source. Regenerate the receipt only after an
-authorized SDK source change:
-
-```bash
-node tools/runtime-manifest.mjs --write
-npm run check
-```
+and applications copy the complete portable inventory selected by the package.
+The old Arcane OS-to-SDK synchronization direction is retired; it cannot
+overwrite SDK-canonical source.
 
 `tools/runtime-source.json` declares the SDK authority and retains the prior
-Arcane OS commit only as legacy provenance for migrated compatibility bytes.
+Arcane OS commit only as migration history.
 Arcane OS must consume the same locked SDK projection as other applications;
 any remaining OS-side duplicate is legacy consumer migration state, not source
-authority. The generated runtime manifest is the published content-addressed
-byte receipt.
+authority.
 
 ## Browser-local AI
 
@@ -103,17 +96,18 @@ const source=createBrowserModelSource({
 });
 ```
 
-Expected `bytes` and `sha256` values are optional while the inherited app
-security policy leaves those checks disabled. Enabling either check requires
-that field on every member. The DBOPFS store admits all members in order and
-commits its completion manifest last. Capability reports evaluate each
+Model members require only their names and URLs. The ordinary path does not
+count, limit, hash, or identify model content by its byte representation.
+Optional hardening is inactive unless the caller explicitly selects
+`secure:true`. The DBOPFS store processes all members in order and commits its
+completion record last. Capability reports evaluate each
 app-supplied model as `compatible`, `incompatible`, or `unknown`; the app can
 render that result without the SDK inventing or filtering its catalog.
 
 `arcane-os/ai/browser-speech` exposes independent Whisper STT and Kokoro TTS
 provider factories. The package contains the plain-JavaScript provider and
 Worker machinery, not speech runtimes, models, voices, or a CDN default. An app
-must supply each immutable runtime/model authority explicitly. Speech roles
+must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
 silently falls back or prevents text chat.
 
@@ -132,7 +126,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.3.0 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.3.2 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -143,7 +137,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.3.0
+npm install --save-dev --save-exact arcane-os@0.3.2
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -159,7 +153,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.3.0` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.3.2` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -180,18 +174,17 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.3.0.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.3.2.tgz
 npm run check
 npm ci
 ```
 
 Adjust the relative tarball path for your layout and keep that `.tgz` at the
-same location. npm records its integrity in `package-lock.json`, while Arcane
-still verifies the installed package name and exact version, the locked runtime
-identity, and the runtime bytes. Local directory `file:` dependencies are not
+same location. The lockfile retains the selected package dependency while
+Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.3.0` registry package and
+the local declaration with the exact `arcane-os@0.3.2` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -237,8 +230,9 @@ app-test behavior.
 Integrated native app builds are also implemented. `--workspace` and
 `--arcane-root` must resolve to the same Arcane checkout, one `--app` and one
 declared native target are selected, and `--output-root` must resolve outside
-that checkout. The SDK then uses the same package, plan, provider, retained
-verification, and same-process run lifecycle as an external app repository.
+that checkout. The SDK then uses the same package, plan, provider, and
+same-process run lifecycle as an external app repository. Verification remains
+an explicit operation for a selected release output.
 
 ## Commands
 
@@ -246,6 +240,7 @@ verification, and same-process run lifecycle as an external app repository.
 arcane new <id> [--path <directory>] [--display-name <name>] [--target <target>] [--git]
 arcane init [id] [--workspace <directory>] [--display-name <name>] [--target <target>]
 arcane doctor [--workspace <directory>] [--arcane-root <directory>]
+arcane import-map [--workspace <directory>] [--app <id>]
 arcane dev [--app <id>] [--host 127.0.0.1] [--port 8000]
 arcane test [--app <id>] [--scope app]
 arcane test --scope shared --test-file <repo-relative.test.mjs>
@@ -265,13 +260,13 @@ arcane repo status|pull|push
 
 All commands support `--output human|json|ndjson`. Machine modes keep stdout
 structured. Every operation emits or reports acceptance before filesystem,
-network, hashing, test, process, or service work begins.
+network, explicitly requested test, process, or service work begins.
 
 ## External application release bundles
 
-An authored schema-2 `arcane-app.json` can be sealed with one already packaged
-and verified browser release. The bundle contains only the canonical descriptor,
-the release manifest, and the exact `dist/<id>/` payload inventory:
+An authored schema-2 `arcane-app.json` can be bundled with one already packaged
+browser release. The bundle contains only the canonical descriptor, the release
+manifest, and the complete selected `dist/<id>/` payload inventory:
 
 ```bash
 npm exec -- arcane package --app my-app
@@ -280,55 +275,32 @@ npm exec -- arcane verify-bundle dist/my-app-1.0.0.arcane-app.tar.gz
 ```
 
 `bundle` creates `dist/<id>-<version>.arcane-app.tar.gz` by default. It refuses
-an existing destination unless `--overwrite` is explicit, preserves the prior
-file until the promoted replacement has passed no-follow, single-link,
-byte-length, and SHA-256 revalidation, and restores the prior file on
-cancellation or pre-commit failure only while both the promoted pathname and
-prior backup retain their respective full recorded identity tuples, each
-pinned by an open handle. If the promoted path is replaced or changed in
-place, it and the prior backup are preserved; if the backup is changed or
-missing, the valid promoted output is preserved instead of being deleted.
-Operation locks carry a random nonce
-and filesystem identity; a replaced lock is preserved and reported as degraded
-cleanup instead of being removed by pathname.
-
-The archive uses one byte-exact USTAR+gzip encoding and publishes its v1 JSON
-contract at `arcane-os/schemas/arcane-app-bundle.json`. Verification rejects
-links, devices, extension headers, unsafe or colliding paths, alternate gzip
-members, noncanonical metadata, trailing data, expansion bombs, and every
-descriptor, policy, inventory, size, or hash mismatch. The envelope adds no
-repository-only source or tooling beyond the exact authenticated release
-inventory; each app owns its leak/source policy, and Arcane's source-free runtime
-gates remain separate. Source controls, payloads, and bundle artifacts must remain single-link regular files at their exact
-recorded length through a final identity check; an appended byte, concurrent
-growth, path replacement, or hard link fails closed. NFC paths use defined
-UTF-8 byte ordering, covered by one pinned golden bundle digest on every
-supported Node/runner combination. This SDK accepts only the explicitly listed
-`0.3.0` bundle generation; structural validity does not imply cross-SDK
-compatibility, and a release with zero payload bytes cannot be created. Portable
-path validation rejects file/directory prefix conflicts, case-colliding prefix
-spellings, and Windows device aliases including superscript COM/LPT digits.
-
-Successful creation and verification return complete consistency metadata for
-the artifact digest/bytes, descriptor canonical/file/package digests and byte
-length, and release manifest/policy/content digests, file count, and payload
-bytes. Those values are consistency evidence for the exact archive, not
-installation authority.
-
-Internal hashes establish consistency, not permission to install. Arcane
-admission must also authenticate the archive through its approved repository
-provenance or independent signature and match that identity to an Arcane-owned
-authorization lock. The reusable `.github/workflows/release-app.yml` workflow
+an existing destination unless `--overwrite` is explicit and preserves the
+prior file until the replacement is complete. Cancellation or failure before
+commit restores the prior output when that can be done without overwriting a
+concurrent change. A conflicting or uncertain path is preserved for inspection.
+
+The archive uses the documented USTAR+gzip structure and publishes its v1 JSON
+contract at `arcane-os/schemas/arcane-app-bundle.json`. When the user explicitly
+selects bundle verification, it rejects malformed archives, links, devices,
+unsafe or colliding paths, unsupported archive members, trailing data, and
+inconsistent descriptor or inventory structure. These checks reject corrupt
+selected artifacts; they do not impose byte-count, hash, provenance, or
+admission gates on ordinary development, packaging, serving, or running.
+Portable path validation rejects file/directory prefix conflicts,
+case-colliding prefix spellings, and Windows device aliases including
+superscript COM/LPT digits.
+
+The reusable `.github/workflows/release-app.yml` workflow
 builds one selected app in a `contents: read` job with no OIDC or attestation
 authority. An always-run fresh job downloads the uploaded artifact by immutable
-artifact id, checks out only the reusable workflow's exact SDK revision, uses
-supported Node 24, directly imports the trusted verifier, rechecks the selected
-app id and complete metadata, and becomes the sole source of reusable outputs.
+artifact id, checks out only the reusable workflow's selected SDK revision, uses
+supported Node 24, and checks the selected app id and complete inventory.
 When requested, a third job downloads that same artifact id, independently
 repeats those checks against the post-upload outputs, and alone receives narrow
 OIDC/attestation permissions. No package manager, dependency resolution, caller
 checkout, check, or adapter runs with that authority. An unattested uploaded
-artifact is still not an authorized Arcane app by itself.
+artifact remains an ordinary build output.
 
 ## SDK test sets
 
@@ -350,15 +322,15 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.3.0` exposes one browser target and five explicitly paired
-native development targets: a verified non-runnable portable directory, a
+Version `0.3.2` exposes one browser target and five explicitly paired
+native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The
 `android-arm64` APK is architecture-neutral because it contains no native ABI;
 the target name identifies its supported physical/native ARM64 run profile.
 
-Every native build requires an explicit Arcane OS checkout that passes this SDK
-version's admission checks and a canonical app descriptor that declares the
+Every native build requires an explicit Arcane OS checkout compatible with this
+SDK version and a canonical app descriptor that declares the
 exact selected target. The SDK never searches for or silently selects a mutable
 toolchain root. Scaffold a separate
 repository with the matching `--target`, or add and validate that target in the
@@ -395,17 +367,16 @@ The browser remains available from the same repository. A native command does
 not infer a missing descriptor target from `--target` and never substitutes a
 browser package.
 
-`native-prepare` is available as a standalone toolchain-integrity diagnostic.
-Do not run it immediately before `build`: receipts are process-owned, and the
-build command prepares and reuses its own exact toolchain state once.
+`native-prepare` is available as a standalone toolchain diagnostic. Do not run
+it automatically: the build command prepares the selected toolchain itself.
 
-The build authenticates the selected app release and descriptor, requires the
+The build reads the selected app release and descriptor, requires the
 Core to meet the highest minimum declared by the SDK runtime, selected app, and
 bundled dependencies, keep their declared Arcane protocol, and provide every
 required feature, capability, and method. A Core reporting a higher version is
 accepted only when it passes those same current-SDK checks; this is not a promise
-that future SDK or Core releases will remain compatible. The build copies
-release bytes through verified readers. Portable emits an app-scoped
+that future SDK or Core releases will remain compatible. The build copies the
+complete selected release. Portable emits an app-scoped
 Arcane Core payload under `build/portable/`; that directory is not executable
 and `arcane run --target portable` is intentionally unavailable. Windows emits
 an app-scoped executable bundle under `build/windows-x64/`. Linux emits an
@@ -413,8 +384,9 @@ app-scoped amd64 DEB under `build/linux-x64/` or ARM64 DEB under
 `build/linux-arm64/`. Android emits one development-signed, architecture-neutral
 APK under `build/android-arm64/`; there is no native ABI payload, and its run
 path requires a physical device with native ARM64 support. Executable `run`
-performs package, prepare, plan, build, verify, launch, and owned cancellation
-in one process because native receipts are process-owned.
+performs package, prepare, plan, build, launch, and owned cancellation in one
+process. Verification occurs only when explicitly selected for that release
+output.
 
 The Windows x64 and Linux x64 paths have been exercised end to end from
 independent external repositories. Windows compiled, verified, reached an
@@ -423,15 +395,13 @@ while a valid installed publisher-continuity pin remained present. Linux x64
 built and verified a real DEB and launched it under WSLg without installation
 or `sudo`.
 
-At Arcane source revision `4382043c09285ea203aa6daba1732660966ac409`, the
-official native ARM64 workflow built and retained-verified a 21,232,932-byte
-ARM64 DEB, proved AArch64 host, Core, and bridge binaries, reached WebKit
+At the recorded Arcane source revision, the native ARM64 workflow built an
+ARM64 DEB, exercised its AArch64 host, Core, and bridge, reached WebKit
 load-finished readiness, and drained its owned process group. The workflow kept
 Ubuntu's AppArmor user-namespace restriction enabled and loaded the packaged
-Bubblewrap profile. At revision `be6732ab71cbecb43d037aaad994ade5f2f4d1b6`,
-the hardened Android path passed build, retained verification, exact
-process/generation/nonce readiness, cancellation, uninstall, and absence checks
-on a physical ARM64/API 37 device. These are development results, not production
+Bubblewrap profile. The recorded Android development path exercised build,
+readiness, cancellation, uninstall, and absence behavior on a physical ARM64
+device. These are development results, not production
 signing, store-publishing, release, or promotion evidence.
 
 | Capability | Ready now |
@@ -440,11 +410,11 @@ signing, store-publishing, release, or promotion evidence.
 | External proprietary-source repository workflow | Yes, subject to the distribution license below |
 | Integrated Arcane checkout workflow | Yes |
 | ArcaneOllama managed-service check | Yes on supported Windows hosts |
-| SDK native plan/provider/receipt boundary | Yes |
-| Portable app-scoped Core directory | Yes, with explicit `--arcane-root`; verified but not directly runnable |
+| SDK native plan/provider boundary | Yes |
+| Portable app-scoped Core directory | Yes, with explicit `--arcane-root`; not directly runnable |
 | Windows x64 EXE bundle | Yes, unsigned local development with explicit `--arcane-root` |
 | Linux x64 DEB | Yes, unsigned local development with explicit `--arcane-root` |
-| Linux ARM64 DEB | Yes, unsigned local development on a compatible native ARM64 toolchain with explicit `--arcane-root`; exact-SHA native build, verification, WebKit readiness, and cancellation evidence is recorded |
+| Linux ARM64 DEB | Yes, unsigned local development on a compatible native ARM64 toolchain with explicit `--arcane-root`; native build, WebKit readiness, and cancellation evidence is recorded |
 | Android ARM64 APK | Yes, development-signed and architecture-neutral with explicit `--arcane-root`; a physical/native ARM64 device is required for run |
 
 Android supports APK only in this development profile. AAB, release signing,
@@ -456,15 +426,15 @@ release acceptance.
 
 See [docs/platform-targets.md](docs/platform-targets.md) for the matrix and
 [docs/architecture.md](docs/architecture.md) for the boundary. The exact
-minimum-version and required-contract admission rule is documented in
+minimum-version and required-contract compatibility rule is documented in
 [docs/compatibility.md](docs/compatibility.md). The issue-ready
 extraction sequence is tracked in [docs/roadmap.md](docs/roadmap.md).
 
 ## Canonical app descriptor
 
 New apps own `apps/<id>/arcane-app.json` schema 2. It contains publisher,
-permissions, security, native presentation, Core requirements, and target
-intent, and deterministically projects the exact schema-1
+optional permissions and security declarations, native presentation, optional
+Core requirements, and target intent, and deterministically projects the schema-1
 `arcane-package.json` required by the current browser packager. The pinned
 schema-1 apps recognized by this SDK are accepted through a read-only projection
 of the current native registry until each app adopts the authored descriptor.
@@ -478,13 +448,12 @@ read-only managed-service assessment where the host supports one. Native apps
 use an app-scoped Arcane Core and `Arcane.localAI.status()` in this SDK version.
 Ollama is optional for packaging and non-AI applications.
 
-The loopback development server uses an unguessable session capability and a
-broad development-only content policy so the shared runtime can exercise remote
-providers, media, WebSockets, and embeds. It is not a production security
-boundary. Declared origins remain native policy input through the approved
-Arcane descriptor; enforcement for any additional target is roadmap scope, not
-a compatibility promise. Served files are verified into bounded response
-snapshots before headers; the current development limit is 64 MiB per file.
+The loopback development server serves complete selected files and does not
+apply byte-count or truncation gates. Optional hardening is inactive unless the
+caller explicitly selects `secure:true`. Required credential protection,
+malformed-request rejection, and unavoidable browser or operating-system safety
+remain in effect. Declared origins remain native policy input only when the app
+explicitly authors them.
 
 ## Licensing