arcane-os 0.1.2 → 0.2.0

package/docs/reference/sdk-api.md

@@ -29,7 +29,7 @@ for that 86-entry physical-runtime contract.
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
 | `arcane-os/event-manager` | Central synchronous events, bounded time-travel history, playback, and optional DOM instrumentation. |
-| `arcane-os/ai/browser-wasm` | Caller-authenticated browser-local Wllama inference, verified DBOPFS model caching, streaming, cancellation, and structural tool-call results. |
+| `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, configurable DBOPFS model checks, streaming, cancellation, and structural tool-call results. |
 
 JSON schemas, the runtime manifest, and `package.json` are data-only export subpaths. In Node ESM, import JSON with `with {type: 'json'}`, or resolve and read it explicitly.
 
@@ -89,7 +89,7 @@ Protocol mechanics are intentionally kept in the [deep protocol guide](protocols
 | `createArcaneAI()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; compatible LLM provider or controller required |
 | `createAppReleaseBundle()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `createBrowserModelSource()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser Fetch with a readable response body |
-| `createBrowserWasmLlmProvider()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; WebAssembly and verified DBOPFS model bytes |
+| `createBrowserWasmLlmProvider()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser; WebAssembly and DBOPFS model bytes |
 | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
 | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -2655,7 +2655,7 @@ The import-map operation also reports the stable operation-specific strings
 `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.1`.
+`0.1.2`.
 
 ### Value and import
 
@@ -3474,7 +3474,7 @@ const toolchain = createToolchain({
 
 // Only this explicit call refreshes the managed map and HTML entry.
 const result = await toolchain.importMap();
-console.log(result.importMap.entryCount); // 86 in SDK 0.1.1
+console.log(result.importMap.entryCount); // 86 in SDK 0.1.2
 ```
 
 ## describeTargets()
@@ -4941,7 +4941,7 @@ console.log(stack.sessionId, stack.events.length);
 
 Deep-frozen authority for the browser-only runtime behind
 `arcane-os/ai/browser-wasm`. It records protocol
-`arcane-ai-browser-wasm/1`, `@wllama/wllama` `3.6.0`, the embedded llama.cpp
+`arcane-ai-browser-wasm/2`, `@wllama/wllama` `3.6.0`, the embedded llama.cpp
 revision, the exact packaged JavaScript and WebAssembly assets, retained MIT
 licenses, and the disabled compatibility-runtime/remote-model-helper policy.
 It contains no model weights or model catalog.
@@ -4984,7 +4984,7 @@ requires an explicit successful `load()` before requests. When both `llm` and
 ### Signature and result
 
 ```text
-createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand' }={})
+createArcaneAI({ llm=null, provider=null, loadPolicy='on-demand', security }={})
 ```
 
 At least one `llm` or `provider` is required. The frozen facade contains
@@ -4994,6 +4994,12 @@ methods return the flat LLM status. `fetchRequest()` returns the completion.
 `streamRequest()` consumes streaming and returns text or a tool-name-to-JSON-
 argument-string record. Use `ai.llm.stream()` for the async iterator.
 
+App and load-operation security use
+`{security:{secure?:boolean, checks?:{byteLength?:boolean, sha256?:boolean}}}`.
+The SDK/app default is `secure:false`. Each omitted field inherits and an
+operation field overrides the corresponding app field. The provider/model
+binding scope, documented below, sits between those scopes.
+
 ### Availability and normalization
 
 **Browser.** It normalizes lifecycle, state/progress events, lazy/manual use,
@@ -5014,10 +5020,9 @@ stop();
 ### Overview
 
 Validates a caller-owned model descriptor and creates the cancellable HTTPS
-source accepted by the browser-WASM store/provider. Required fields are `id`,
-`name`, `immutableUrl`, `bytes`, `sha256`, `licenseSpdx`, and
-`sourceRevision`. `bytes` is the expected positive safe-integer byte length,
-not inline data.
+source accepted by the browser-WASM store/provider. The canonical descriptor is
+`{id, url, bytes?, sha256?}`. `id` and `url` are required. `bytes`, when
+present, is the expected positive safe-integer byte length, not inline data.
 
 ### Signature and result
 
@@ -5026,30 +5031,34 @@ createBrowserModelSource(descriptor, { fetchImpl=null }={})
 ```
 
 The URL must be absolute HTTPS with no credentials or fragment and no
-revision-floating `main`, `master`, or `latest` path. The SHA-256 value is
-exactly 64 hexadecimal characters. The frozen source exposes its canonical
+revision-floating `main`, `master`, or `latest` path. A supplied SHA-256 value
+is exactly 64 hexadecimal characters. The frozen source exposes its canonical
 descriptor and `open({signal})`, which returns `{body, requestedUrl, finalUrl,
-cancel}`. Every direct `open()` performs the configured fetch. The SDK records
-but does not independently prove the supplied license identifier or revision.
+reportedBytes, cancel}`. `reportedBytes` is the nullable valid nonnegative
+`Content-Length` observation; it is not an unconditional admission check. Every
+direct `open()` performs the configured fetch.
+
+For compatibility, `immutableUrl` remains an alias for `url` and `name` can
+remain a cache-filename hint; `url` and `immutableUrl` must match when both are
+present. Legacy `licenseSpdx` and `sourceRevision` properties are not canonical
+descriptor fields, runtime admission checks, or proof of license rights.
 
 ### Availability and normalization
 
 **Browser Fetch with CORS and a readable response body.** Downloads omit
 credentials/referrer, disable HTTP caching, follow redirects, require a final
-HTTPS URL, compare `Content-Length` when present, and honor `AbortSignal`.
-Actual length and digest admission belongs to the DBOPFS store.
+HTTPS URL, and honor `AbortSignal`. The DBOPFS store always counts and records
+actual bytes; it compares expected length or hashes bytes only when the
+corresponding effective check is enabled.
 
 ### Example
 
 ```javascript
 const source = createBrowserModelSource({
     id:'reviewed-model',
-    name:'model-q4.gguf',
-    immutableUrl:'https://models.example/revisions/4f7c/model-q4.gguf',
+    url:'https://models.example/revisions/4f7c/model-q4.gguf',
     bytes:123456789,
-    sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
-    licenseSpdx:'Apache-2.0',
-    sourceRevision:'4f7c'
+    sha256:'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
 });
 ```
 
@@ -5064,7 +5073,7 @@ created by this module. It serializes requests and exposes provider states
 ### Signature and result
 
 ```text
-createBrowserWasmLlmProvider({ source, store, loadDefaults={}, logger=console }={})
+createBrowserWasmLlmProvider({ source, store, loadDefaults={}, security, logger=console }={})
 ```
 
 The frozen provider exposes `protocol`, `id`, `model`, `capabilities`,
@@ -5075,12 +5084,24 @@ OpenAI-like message/generation fields, tools, tool choice, parallel tool-call
 preference, and JSON/JSON-Schema structured output. `stream()` returns a frozen
 async iterator with `result` and `cancel(reason)`.
 
+Provider `security` is the provider/model-binding scope. Security fields resolve
+independently by precedence: load operation, provider/model binding, app SDK
+configuration, then SDK default `secure:false`. Omitted fields inherit. After
+resolution, `secure:true` enables both byte-length and SHA-256 checks by default;
+`secure:false` disables both by default. An explicit per-check boolean overrides
+the resolved secure default. Enabled checks require their corresponding
+descriptor fields and fail closed; disabled checks permit those fields to be
+absent. Changing effective checks for an already loaded or in-flight model
+requires unload and reload.
+
 ### Availability and normalization
 
-**Browser with WebAssembly and a verified DBOPFS model.** WebGPU and
-cross-origin isolation are capability observations, not promised gates.
-Returned tools are validated structural data; the SDK never calls a handler.
-Cancellation normalizes to `ARCANE_AI_REQUEST_ABORTED`.
+**Browser with WebAssembly and a DBOPFS model.** A load succeeds only after
+Wllama confirms the model is loaded. WebGPU and cross-origin isolation are
+capability observations, not promised gates. Status discloses effective
+`security` and per-check `integrity`; unchecked bytes are never labeled SHA-256
+verified. Returned tools are validated structural data; the SDK never calls a
+handler. Cancellation normalizes to `ARCANE_AI_REQUEST_ABORTED`.
 
 ### Example
 
@@ -5088,6 +5109,7 @@ Cancellation normalizes to `ARCANE_AI_REQUEST_ABORTED`.
 const provider = createBrowserWasmLlmProvider({
     source,
     store,
+    security:{secure:true},
     loadDefaults:{threads:1, contextTokens:4096, gpuLayers:0}
 });
 console.log(provider.status().state); // unloaded
@@ -5097,10 +5119,10 @@ console.log(provider.status().state); // unloaded
 
 ### Overview
 
-Adapts an existing DBOPFS instance into an authenticated model cache without
-renaming its public methods. The adapter commits model bytes before the
-`arcane.ai.browser-wasm.model.v2` completion manifest and then reopens and
-rehashes the stored file.
+Adapts an existing DBOPFS instance into a model cache without renaming its
+public methods. The adapter commits model bytes before the
+`arcane.ai.browser-wasm.model.v3` completion manifest and always records the
+observed downloaded or cached byte length.
 
 ### Signature and result
 
@@ -5110,14 +5132,22 @@ createDbopfsModelStore({ dbopfs, tableName='arcane_ai_browser_models' }={})
 
 The frozen result contains `kind`, `tableName`, the original `adapter`, and
 `ready`, `openVerified`, `install`, `ensure`, and `remove`. `ensure()` returns
-`{file, manifest, cache:'verified'|'installed'}`. Every cache reuse rehashes the
-actual bytes. `offline:true` never downloads and rejects a miss with
-`ARCANE_AI_MODEL_OFFLINE_MISS`. Invalid cache records are removed fail closed.
-
-### Availability and normalization
-
-**Browser with a ready DBOPFS instance and OPFS.** The cache is local integrity
-evidence, not a transferable capability or license proof. Unload/dispose keep
+the file, manifest, `observedBytes`, integrity detail, and
+`cache:'cached'|'installed'`. `openVerified()` is a compatibility helper that
+forces both checks on. Ordinary install/reuse compares expected length only
+when effective `checks.byteLength` is true and hashes only when effective
+`checks.sha256` is true. `offline:true` never downloads and rejects a miss with
+`ARCANE_AI_MODEL_OFFLINE_MISS`. Version-2 manifests with matching model identity
+can migrate to version 3 without fabricating verification.
+
+### Availability and normalization
+
+**Browser with a ready DBOPFS instance and OPFS.** The cache reports only checks
+actually performed. Disabled byte-length checks do not compare descriptor
+`bytes`, disabled SHA-256 checks do not hash or reread solely for a digest, and
+overall integrity is `verified` when every enabled check succeeds or
+`unchecked` when neither check is enabled. Cache
+metadata is not a transferable capability or license proof. Unload/dispose keep
 the cache; `store.remove(source)` explicitly deletes it.
 
 ### Example

package/docs/work-amplification.md

@@ -50,10 +50,14 @@ format, or signing loop and does not produce app output.
 
 - Scaffold: approximately 15-25 files, less than 100 KiB, target under one
   second before an optional dependency installation.
-- Shared browser payload: 166 files / 3,478,345 bytes, comprising the exact
-  155-file / 3,320,994-byte Arcane-upstream runtime receipt, the separate
-  8-file / 118,385-byte SDK browser-runtime receipt, and three SDK licensing
-  files / 38,966 bytes, verified once per exact SDK installation state.
+- Shared browser payload: 188 files / 12,854,565 bytes, comprising the exact
+  160-file / 3,549,207-byte SDK-canonical runtime receipt, the separate
+  25-file / 9,265,304-byte SDK browser-runtime receipt, and three SDK licensing
+  files / 40,054 canonical LF bytes, verified once per exact SDK installation
+  state.
+  The SDK is the canonical owner of portable shared runtime. The receipt keeps
+  the prior Arcane OS identity only as migration provenance and binds the
+  SDK-owned inventory once without multiplying payload verification.
 - Small browser package: app bytes plus the shared runtime, copied and inventoried
   once into an atomic staging directory.
 - Portable build: one explicitly selected app and one host platform request. In

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -14,6 +14,7 @@
     "./events": "./src/events.mjs",
     "./event-manager": "./src/event-manager.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
+    "./ai/browser-speech": "./browser-runtime/ai/browser-speech.mjs",
     "./testing": "./src/testing.mjs",
     "./targets": "./src/targets/index.mjs",
     "./native": "./src/native-plan.mjs",
@@ -32,6 +33,9 @@
     "./schemas/target-adapter.json": "./schemas/target-adapter.schema.json",
     "./package.json": "./package.json"
   },
+  "imports": {
+    "#arcane/persistent-ai-chat-session": "./runtime/arcane/modules/PersistentAIChatSession.js"
+  },
   "files": [
     "bin/",
     "browser-runtime/",
@@ -49,8 +53,8 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/cli.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/packaging.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime-sync.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/site.test.mjs test/update-check.test.mjs",
-    "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/packaging.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime-sync.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/native-provider-generation.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && node tools/runtime-manifest.mjs --verify && node tools/sdk-browser-runtime-manifest.mjs --verify && npm test",
     "check:release": "node tools/check-source.mjs --package-only && node tools/runtime-manifest.mjs --verify && node tools/sdk-browser-runtime-manifest.mjs --verify && npm run test:release",

package/runtime/ARCANE_RUNTIME_RELEASE.json

@@ -1,16 +1,21 @@
 {
   "schemaVersion": 1,
   "builder": "arcane-sdk-runtime-v1",
-  "sdkVersion": "0.1.2",
+  "sdkVersion": "0.2.0",
   "source": {
-    "repository": "https://github.com/TheWizardNexus/ARCANE-OS.git",
-    "commit": "567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e",
-    "bundleVersion": "0.8.12",
-    "protocol": "arcane/1"
+    "authority": "sdk-canonical",
+    "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
+    "path": "runtime/arcane",
+    "protocol": "arcane/1",
+    "legacyProjection": {
+      "repository": "https://github.com/TheWizardNexus/ARCANE-OS.git",
+      "commit": "c540014afe69f14cf5ae60493b7295f36dbcec64",
+      "bundleVersion": "0.8.12"
+    }
   },
-  "fileCount": 155,
-  "totalBytes": 3320994,
-  "contentSha256": "7b1b583b4adf6a6ec794da6f0c03c553cdee79784dab75094d83ee24f9637098",
+  "fileCount": 160,
+  "totalBytes": 3549207,
+  "contentSha256": "fa3bcddb5479817971a400049dbeff8431c6499d708e9a8b714176715c5a015a",
   "files": [
     {
       "path": "arcane/components/app-bar.html",
@@ -34,8 +39,8 @@
     },
     {
       "path": "arcane/components/chat.html",
-      "bytes": 44659,
-      "sha256": "770a27248ef16ee4e23618250374b9c0a54f7632a1ec2e59087a77473986209f"
+      "bytes": 52132,
+      "sha256": "42d4769a074e70b5c2768e850eaf29a25c93ee9e8734724b72b2ad585e19b2ca"
     },
     {
       "path": "arcane/components/conversation-view.html",
@@ -154,8 +159,8 @@
     },
     {
       "path": "arcane/components/speech.html",
-      "bytes": 10912,
-      "sha256": "170324cb17057460efe72201cea5e7bd58d0b4b3d9b4f884e44d62e5d4f6daa0"
+      "bytes": 38217,
+      "sha256": "61786685b7f4f257da77db2cbbe8230b379c56292ad635081f5b0763d5f48e1e"
     },
     {
       "path": "arcane/components/summary-strip.html",
@@ -254,8 +259,8 @@
     },
     {
       "path": "arcane/entities/Chat.js",
-      "bytes": 16273,
-      "sha256": "6353af820d4912c8945681effdc9f9787b790a69700b2724be5649639743a90f"
+      "bytes": 25366,
+      "sha256": "20ece4ea4537693c49580dda723e392af152792c25006686ce2f75c7c906984d"
     },
     {
       "path": "arcane/entities/CommunicationMessage.js",
@@ -369,8 +374,8 @@
     },
     {
       "path": "arcane/modules/AI.js",
-      "bytes": 60674,
-      "sha256": "a53b71a1b6b4c629f6baa97ab81882858b60d1cb04320b661508c569d66b2170"
+      "bytes": 81061,
+      "sha256": "8e34445ad394064dae970583147b635de81d878a6caebb8a60d64b34dbc9e658"
     },
     {
       "path": "arcane/modules/AIPreferenceRuntime.js",
@@ -382,6 +387,11 @@
       "bytes": 2594,
       "sha256": "7fd028fd9e7f3eb309a6a2b7612a5fc67d4c7289adc4168d681224579220ac09"
     },
+    {
+      "path": "arcane/modules/AIProviderRuntime.js",
+      "bytes": 83261,
+      "sha256": "32aa65b464ea9a9317d47f382063fc052e1f47e63e6c65c28e58898e0ab4911a"
+    },
     {
       "path": "arcane/modules/AIResponseLength.js",
       "bytes": 1941,
@@ -392,6 +402,11 @@
       "bytes": 17587,
       "sha256": "905af15d5d4912a68fa96ea44b0f6ac2eef90c69c6486ce507e00a7850acd626"
     },
+    {
+      "path": "arcane/modules/AIRuntimeState.js",
+      "bytes": 24783,
+      "sha256": "8b9bfaf208eb44455b581d8e700cec785044f81595dcf839dcdfa3e06ed0f5fa"
+    },
     {
       "path": "arcane/modules/AnsiText.js",
       "bytes": 2373,
@@ -484,8 +499,8 @@
     },
     {
       "path": "arcane/modules/ConfiguredAIChatSession.js",
-      "bytes": 10582,
-      "sha256": "378559117479eaae4977a127b3dbc02002fcff1768f817a4a5a878b79a04eee3"
+      "bytes": 21462,
+      "sha256": "12e02b169be6867d82ef8be75bcb1c2b367e778609e8d065389ed109d896c4c8"
     },
     {
       "path": "arcane/modules/ConversationActionItems.js",
@@ -517,6 +532,11 @@
       "bytes": 30099,
       "sha256": "eef077c318032626cf3c455e0619dfd6a729e916c367fd4fffac72c6dcb50745"
     },
+    {
+      "path": "arcane/modules/DBOPFSDocumentLibrary.js",
+      "bytes": 29977,
+      "sha256": "4c551b5917d1577b8b46b08457cf762d7ab7548222abd6f4a72c7c7ab5c697b7"
+    },
     {
       "path": "arcane/modules/DBOPFSWorker.js",
       "bytes": 3928,
@@ -537,6 +557,11 @@
       "bytes": 3799,
       "sha256": "da1eaab03aa5d5ee64d236b5d6bd11a792c811110a1d57fa43d43e26ff97d169"
     },
+    {
+      "path": "arcane/modules/DocumentLexicalSearch.js",
+      "bytes": 12977,
+      "sha256": "f83a8428e5080cd61bbecac39104a768457d4c7b4825acaf9add9286c6b84b09"
+    },
     {
       "path": "arcane/modules/DocumentNavigation.js",
       "bytes": 7194,
@@ -632,6 +657,11 @@
       "bytes": 3624,
       "sha256": "2e3f8b07c6e0acb1ebf8e1327b208242dff9c55abdd6bedc288abf6692caf43d"
     },
+    {
+      "path": "arcane/modules/PersistentAIChatSession.js",
+      "bytes": 10890,
+      "sha256": "4bb4980e09f3cfcf20ca7c5130e1e133042554b8e1fae4fd613e0e2a9acdbee0"
+    },
     {
       "path": "arcane/modules/PreferenceStore.js",
       "bytes": 3794,
@@ -694,8 +724,8 @@
     },
     {
       "path": "arcane/modules/StaticDocumentCatalog.js",
-      "bytes": 56002,
-      "sha256": "ec512ec054d2fdc1d7ced29d1038257bb6f9872920f442376b906783f12bb6e1"
+      "bytes": 47189,
+      "sha256": "002ab228c2ec80006c6365eb5bbdde33e5951c7424ca15aa16b4d9663bcc77f8"
     },
     {
       "path": "arcane/modules/SystemAppearance.js",