arcane-os 0.1.2 → 0.2.0

package/browser-runtime/ai/wllama/index.mjs

@@ -3476,6 +3476,395 @@ var Wllama = class {
     return workerResources;
   }
 };
+(function applyArcaneWllamaProjection() {
+  const protocol = "arcane-wllama-webgpu-evidence/1";
+  const emptyWorkerTelemetry = `{protocol:"${protocol}",adapter:null,bufferCount:0,bufferBytes:0,queueSubmissions:0,commandBuffers:0,queueFenceRequests:0,queueFenceCompletions:0,invalid:false}`;
+
+  function replaceSingle(source, search, replacement, label) {
+    const first = source.indexOf(search);
+    const last = source.lastIndexOf(search);
+    if (first < 0 || first !== last) {
+      throw new Error(`Pinned Wllama ${label} projection anchor must occur exactly once.`);
+    }
+    return `${source.slice(0, first)}${replacement}${source.slice(first + search.length)}`;
+  }
+
+  const adapterAnchor = "if(adapter){WebGPU.Internals.jsObjectInsert(adapterPtr,adapter)";
+  const adapterProjection = `if(adapter){(function arcaneRecordSelectedWebgpuAdapter(){const key="__arcaneWllamaWebgpuTelemetry";const previous=globalThis[key]??${emptyWorkerTelemetry};const info=adapter.info??{};const text=value=>typeof value==="string"?value.slice(0,256):"";const next={selected:true,vendorId:null,vendor:text(info.vendor),architecture:text(info.architecture),deviceId:null,name:text(info.device),description:text(info.description)};const conflicts=previous.adapter!==null&&JSON.stringify(previous.adapter)!==JSON.stringify(next);globalThis[key]={protocol:"${protocol}",adapter:previous.adapter??next,bufferCount:previous.bufferCount,bufferBytes:previous.bufferBytes,queueSubmissions:previous.queueSubmissions,commandBuffers:previous.commandBuffers,queueFenceRequests:previous.queueFenceRequests,queueFenceCompletions:previous.queueFenceCompletions,invalid:previous.invalid||conflicts}})();WebGPU.Internals.jsObjectInsert(adapterPtr,adapter)`;
+  WLLAMA_EMSCRIPTEN_CODE = replaceSingle(
+    WLLAMA_EMSCRIPTEN_CODE,
+    adapterAnchor,
+    adapterProjection,
+    "WebGPU adapter selection",
+  );
+
+  const bufferAnchor = "var buffer;try{buffer=device.createBuffer(desc)}catch(ex){return false}WebGPU.Internals.jsObjectInsert(bufferPtr,buffer)";
+  const bufferProjection = `${bufferAnchor};(function arcaneRecordWebgpuBuffer(){const key="__arcaneWllamaWebgpuTelemetry";const previous=globalThis[key]??${emptyWorkerTelemetry};const size=desc.size;const bufferCount=previous.bufferCount+1;const bufferBytes=previous.bufferBytes+size;globalThis[key]={protocol:"${protocol}",adapter:previous.adapter,bufferCount:Number.isSafeInteger(bufferCount)?bufferCount:previous.bufferCount,bufferBytes:Number.isSafeInteger(size)&&size>0&&Number.isSafeInteger(bufferBytes)?bufferBytes:previous.bufferBytes,queueSubmissions:previous.queueSubmissions,commandBuffers:previous.commandBuffers,queueFenceRequests:previous.queueFenceRequests,queueFenceCompletions:previous.queueFenceCompletions,invalid:previous.invalid||!Number.isSafeInteger(size)||size<1||!Number.isSafeInteger(bufferCount)||!Number.isSafeInteger(bufferBytes)}})()`;
+  WLLAMA_EMSCRIPTEN_CODE = replaceSingle(
+    WLLAMA_EMSCRIPTEN_CODE,
+    bufferAnchor,
+    bufferProjection,
+    "WebGPU buffer",
+  );
+
+  const queueAnchor = "queue.submit(cmds)};function _wgpuQueueWriteBuffer";
+  const queueProjection = `queue.submit(cmds);(function arcaneRecordWebgpuSubmission(){const key="__arcaneWllamaWebgpuTelemetry";const previous=globalThis[key]??${emptyWorkerTelemetry};const queueSubmissions=previous.queueSubmissions+1;const commandBuffers=previous.commandBuffers+cmds.length;globalThis[key]={protocol:"${protocol}",adapter:previous.adapter,bufferCount:previous.bufferCount,bufferBytes:previous.bufferBytes,queueSubmissions:Number.isSafeInteger(queueSubmissions)?queueSubmissions:previous.queueSubmissions,commandBuffers:Number.isSafeInteger(commandBuffers)?commandBuffers:previous.commandBuffers,queueFenceRequests:previous.queueFenceRequests,queueFenceCompletions:previous.queueFenceCompletions,invalid:previous.invalid||!Number.isSafeInteger(queueSubmissions)||!Number.isSafeInteger(commandBuffers)}})()};function _wgpuQueueWriteBuffer`;
+  WLLAMA_EMSCRIPTEN_CODE = replaceSingle(
+    WLLAMA_EMSCRIPTEN_CODE,
+    queueAnchor,
+    queueProjection,
+    "WebGPU queue",
+  );
+
+  const fenceAnchor = "runtimeKeepalivePush();WebGPU.Internals.futureInsert(futureId,queue.onSubmittedWorkDone().then(()=>{";
+  const fenceProjection = `runtimeKeepalivePush();(function arcaneRecordWebgpuFenceRequest(){const key="__arcaneWllamaWebgpuTelemetry";const previous=globalThis[key]??${emptyWorkerTelemetry};const queueFenceRequests=previous.queueFenceRequests+1;globalThis[key]={protocol:"${protocol}",adapter:previous.adapter,bufferCount:previous.bufferCount,bufferBytes:previous.bufferBytes,queueSubmissions:previous.queueSubmissions,commandBuffers:previous.commandBuffers,queueFenceRequests:Number.isSafeInteger(queueFenceRequests)?queueFenceRequests:previous.queueFenceRequests,queueFenceCompletions:previous.queueFenceCompletions,invalid:previous.invalid||!Number.isSafeInteger(queueFenceRequests)}})();WebGPU.Internals.futureInsert(futureId,queue.onSubmittedWorkDone().then(function arcaneRecordWebgpuFenceCompletion(){(function arcaneCommitWebgpuFenceCompletion(){const key="__arcaneWllamaWebgpuTelemetry";const previous=globalThis[key]??${emptyWorkerTelemetry};const queueFenceCompletions=previous.queueFenceCompletions+1;globalThis[key]={protocol:"${protocol}",adapter:previous.adapter,bufferCount:previous.bufferCount,bufferBytes:previous.bufferBytes,queueSubmissions:previous.queueSubmissions,commandBuffers:previous.commandBuffers,queueFenceRequests:previous.queueFenceRequests,queueFenceCompletions:Number.isSafeInteger(queueFenceCompletions)?queueFenceCompletions:previous.queueFenceCompletions,invalid:previous.invalid||!Number.isSafeInteger(queueFenceCompletions)||queueFenceCompletions>previous.queueFenceRequests}})();`;
+  WLLAMA_EMSCRIPTEN_CODE = replaceSingle(
+    WLLAMA_EMSCRIPTEN_CODE,
+    fenceAnchor,
+    fenceProjection,
+    "WebGPU submitted-work fence",
+  );
+
+  const workerAnchor = "  if (verb === 'module.init') {";
+  const workerProjection = `  if (verb === 'arcane.telemetry') {\n    const observed = globalThis.__arcaneWllamaWebgpuTelemetry;\n    const adapter = observed?.adapter?.selected === true ? {\n      selected: true,\n      vendorId: null,\n      vendor: typeof observed.adapter.vendor === 'string' ? observed.adapter.vendor.slice(0, 256) : '',\n      architecture: typeof observed.adapter.architecture === 'string' ? observed.adapter.architecture.slice(0, 256) : '',\n      deviceId: null,\n      name: typeof observed.adapter.name === 'string' ? observed.adapter.name.slice(0, 256) : '',\n      description: typeof observed.adapter.description === 'string' ? observed.adapter.description.slice(0, 256) : '',\n    } : null;\n    msg({\n      callbackId,\n      result: {\n        protocol: '${protocol}',\n        adapter,\n        bufferCount: Number.isSafeInteger(observed?.bufferCount) ? observed.bufferCount : 0,\n        bufferBytes: Number.isSafeInteger(observed?.bufferBytes) ? observed.bufferBytes : 0,\n        queueSubmissions: Number.isSafeInteger(observed?.queueSubmissions) ? observed.queueSubmissions : 0,\n        commandBuffers: Number.isSafeInteger(observed?.commandBuffers) ? observed.commandBuffers : 0,\n        queueFenceRequests: Number.isSafeInteger(observed?.queueFenceRequests) ? observed.queueFenceRequests : 0,\n        queueFenceCompletions: Number.isSafeInteger(observed?.queueFenceCompletions) ? observed.queueFenceCompletions : 0,\n        invalid: observed?.invalid === true,\n      },\n    });\n    return;\n  }\n\n${workerAnchor}`;
+  LLAMA_CPP_WORKER_CODE = replaceSingle(
+    LLAMA_CPP_WORKER_CODE,
+    workerAnchor,
+    workerProjection,
+    "Worker telemetry",
+  );
+
+  function sanitizeWorkerTelemetry(value) {
+    function nonNegativeCounter(candidate) {
+      return Number.isSafeInteger(candidate) && candidate >= 0 ? candidate : 0;
+    }
+    function adapterText(candidate) {
+      return typeof candidate === "string" && candidate.length <= 256 ? candidate : "";
+    }
+    const rawAdapter = value?.adapter;
+    const adapterInvalid = rawAdapter !== undefined && rawAdapter !== null && (
+      typeof rawAdapter !== "object"
+      || rawAdapter.selected !== true
+      || rawAdapter.vendorId !== null
+      || typeof rawAdapter.vendor !== "string"
+      || rawAdapter.vendor.length > 256
+      || typeof rawAdapter.architecture !== "string"
+      || rawAdapter.architecture.length > 256
+      || rawAdapter.deviceId !== null
+      || typeof rawAdapter.name !== "string"
+      || rawAdapter.name.length > 256
+      || typeof rawAdapter.description !== "string"
+      || rawAdapter.description.length > 256
+    );
+    const adapter = rawAdapter?.selected === true ? Object.freeze({
+      selected: true,
+      vendorId: null,
+      vendor: adapterText(rawAdapter.vendor),
+      architecture: adapterText(rawAdapter.architecture),
+      deviceId: null,
+      name: adapterText(rawAdapter.name),
+      description: adapterText(rawAdapter.description),
+    }) : null;
+    return Object.freeze({
+      protocol,
+      adapter,
+      bufferCount: nonNegativeCounter(value?.bufferCount),
+      bufferBytes: nonNegativeCounter(value?.bufferBytes),
+      queueSubmissions: nonNegativeCounter(value?.queueSubmissions),
+      commandBuffers: nonNegativeCounter(value?.commandBuffers),
+      queueFenceRequests: nonNegativeCounter(value?.queueFenceRequests),
+      queueFenceCompletions: nonNegativeCounter(value?.queueFenceCompletions),
+      invalid: value?.invalid === true || value?.protocol !== protocol || adapterInvalid,
+    });
+  }
+
+  const proxyEvidence = new WeakMap();
+  const sessionEvidence = new WeakMap();
+
+  function proxyRecord(proxy) {
+    let record = proxyEvidence.get(proxy);
+    if (!record) {
+      record = {
+        cancellationSequence: 0,
+        cancellation: null,
+        cleanupSequence: 0,
+        cleanup: null,
+        worker: sanitizeWorkerTelemetry(null),
+      };
+      proxyEvidence.set(proxy, record);
+    }
+    return record;
+  }
+
+  function cancellationRecord(proxy, value) {
+    const evidence = proxyRecord(proxy);
+    const sequence = evidence.cancellationSequence + 1;
+    evidence.cancellationSequence = sequence;
+    const record = Object.freeze({
+      sequence,
+      requestId: typeof value.requestId === "number" || typeof value.requestId === "string"
+        ? value.requestId
+        : null,
+      responseName: value.responseName === "cncl_res" ? value.responseName : null,
+      acknowledged: value.acknowledged === true,
+      failed: value.failed === true,
+    });
+    evidence.cancellation = record;
+    return record;
+  }
+
+  const originalAction = ProxyToWorker.prototype.wllamaAction;
+  Object.defineProperty(ProxyToWorker.prototype, "wllamaAction", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneWllamaAction(name, body) {
+      if (name !== "cancel") return originalAction.call(this, name, body);
+      try {
+        const result = await originalAction.call(this, name, body);
+        cancellationRecord(this, {
+          requestId: body?.req_id,
+          responseName: result?._name,
+          acknowledged: result?._name === "cncl_res" && result?.success === true,
+          failed: false,
+        });
+        return result;
+      } catch (error) {
+        cancellationRecord(this, {
+          requestId: body?.req_id,
+          responseName: null,
+          acknowledged: false,
+          failed: true,
+        });
+        throw error;
+      }
+    },
+  });
+
+  Object.defineProperty(ProxyToWorker.prototype, "arcaneTelemetry", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneTelemetry() {
+      const value = await this.pushTask({
+        verb: "arcane.telemetry",
+        args: [],
+        callbackId: this.taskId++,
+      });
+      const evidence = proxyRecord(this);
+      evidence.worker = sanitizeWorkerTelemetry(value);
+      return Object.freeze({
+        protocol,
+        worker: evidence.worker,
+        cancellation: evidence.cancellation,
+        cleanup: evidence.cleanup,
+      });
+    },
+  });
+
+  const originalWorkerExit = ProxyToWorker.prototype.wllamaExit;
+  Object.defineProperty(ProxyToWorker.prototype, "wllamaExit", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneWllamaExit(...args) {
+      const hadWorker = Boolean(this.worker);
+      const result = await originalWorkerExit.apply(this, args);
+      if (hadWorker) {
+        const evidence = proxyRecord(this);
+        const sequence = evidence.cleanupSequence + 1;
+        evidence.cleanupSequence = sequence;
+        evidence.cleanup = Object.freeze({
+          sequence,
+          kind: "worker-terminated",
+          nativeUnload: false,
+          physicalVramReclamation: "not-observed",
+        });
+      }
+      return result;
+    },
+  });
+
+  function projectionFailure(code, message, cause) {
+    const error = new Error(message, cause === undefined ? undefined : { cause });
+    error.name = "ArcaneWllamaProjectionError";
+    error.code = code;
+    return error;
+  }
+
+  function cancellationError(reason) {
+    if (reason instanceof Error) return reason;
+    const error = new Error(reason ? String(reason) : "The Wllama operation was cancelled.");
+    error.name = "AbortError";
+    return error;
+  }
+
+  function noWorkerCleanup() {
+    return Object.freeze({
+      sequence: 0,
+      kind: "no-worker-observed-at-exit",
+      nativeUnload: false,
+      physicalVramReclamation: "not-applicable",
+    });
+  }
+
+  function proxySnapshot(proxy, cleanup = null) {
+    const evidence = proxy ? proxyRecord(proxy) : null;
+    return Object.freeze({
+      protocol,
+      worker: evidence?.worker ?? sanitizeWorkerTelemetry(null),
+      cancellation: evidence?.cancellation ?? null,
+      cleanup: evidence?.cleanup ?? cleanup,
+    });
+  }
+
+  Object.defineProperty(Wllama.prototype, "arcaneTelemetry", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneTelemetry() {
+      const exited = sessionEvidence.get(this) ?? null;
+      if (!this.proxy || exited?.cleanup) return exited ?? proxySnapshot(null);
+      return this.proxy.arcaneTelemetry();
+    },
+  });
+
+  const originalExit = Wllama.prototype.exit;
+  Object.defineProperty(Wllama.prototype, "exit", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneExit(...args) {
+      const proxy = this.proxy;
+      const hadWorker = Boolean(proxy?.worker);
+      let result;
+      try {
+        result = await originalExit.apply(this, args);
+      } catch (error) {
+        throw projectionFailure(
+          "ARCANE_AI_WORKER_TERMINATION_UNCONFIRMED",
+          "Wllama exit failed before Worker termination could be confirmed.",
+          error,
+        );
+      }
+      let snapshot = proxySnapshot(proxy, hadWorker ? null : noWorkerCleanup());
+      if (hadWorker && snapshot.cleanup?.kind !== "worker-terminated") {
+        throw projectionFailure(
+          "ARCANE_AI_WORKER_TERMINATION_UNCONFIRMED",
+          "Wllama exit did not confirm Worker termination.",
+        );
+      }
+      sessionEvidence.set(this, snapshot);
+      return result;
+    },
+  });
+
+  Object.defineProperty(Wllama.prototype, "arcaneTerminate", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneTerminate() {
+      const existing = sessionEvidence.get(this) ?? null;
+      if (!this.proxy) {
+        const snapshot = existing ?? proxySnapshot(null, noWorkerCleanup());
+        sessionEvidence.set(this, snapshot);
+        return snapshot;
+      }
+      await this.exit();
+      const snapshot = await this.arcaneTelemetry();
+      if (!["worker-terminated", "no-worker-observed-at-exit"].includes(snapshot.cleanup?.kind)) {
+        throw projectionFailure(
+          "ARCANE_AI_WORKER_TERMINATION_UNCONFIRMED",
+          "Wllama cleanup did not confirm its Worker termination boundary.",
+        );
+      }
+      return snapshot;
+    },
+  });
+
+  const originalLoadModel = Wllama.prototype.loadModel;
+  Object.defineProperty(Wllama.prototype, "arcaneLoadModel", {
+    configurable: false,
+    writable: false,
+    value: async function arcaneLoadModel(files, params = {}, signal = null) {
+      if (signal !== null && typeof signal !== "object") {
+        throw new TypeError("Arcane Wllama load cancellation requires an AbortSignal or null.");
+      }
+      if (signal?.aborted) throw cancellationError(signal.reason);
+      const descriptor = Object.getOwnPropertyDescriptor(this, "proxy");
+      if (!descriptor?.configurable || !("value" in descriptor) || descriptor.get || descriptor.set) {
+        throw projectionFailure(
+          "ARCANE_AI_WLLAMA_PROJECTION_INVALID",
+          "Pinned Wllama proxy state is not an inspectable configurable data property.",
+        );
+      }
+
+      sessionEvidence.delete(this);
+      const session = this;
+      let proxy = descriptor.value;
+      let resolveProxyAssigned;
+      const proxyAssigned = new Promise(function captureAssignedProxy(resolve) {
+        resolveProxyAssigned = resolve;
+      });
+      if (proxy) resolveProxyAssigned(proxy);
+      Object.defineProperty(this, "proxy", {
+        enumerable: descriptor.enumerable,
+        configurable: true,
+        get: function arcaneReadLoadingProxy() {
+          return proxy;
+        },
+        set: function arcaneRecordLoadingProxy(value) {
+          proxy = value;
+          if (value) resolveProxyAssigned(value);
+        },
+      });
+
+      let restored = false;
+      function restoreProxyProperty() {
+        if (restored) return;
+        restored = true;
+        Object.defineProperty(session, "proxy", { ...descriptor, value: proxy });
+      }
+      const loadPromise = Promise.resolve().then(function beginProjectedModelLoad() {
+        return originalLoadModel.call(session, files, params);
+      });
+      loadPromise.finally(restoreProxyProperty).catch(function ignoreObservedLoadSettlement() {});
+      if (!signal) return loadPromise;
+
+      let onAbort;
+      const aborted = new Promise(function captureProjectedLoadCancellation(resolve, reject) {
+        onAbort = function terminateProjectedLoadAfterAbort() {
+          const reason = cancellationError(signal.reason);
+          const activeProxy = proxy
+            ? Promise.resolve(proxy)
+            : Promise.race([
+              proxyAssigned,
+              loadPromise.then(
+                function projectedLoadFinishedWithoutProxy() { return null; },
+                function projectedLoadFailedWithoutProxy() { return null; },
+              ),
+            ]);
+          activeProxy.then(function terminateAssignedLoadProxy() {
+            return session.arcaneTerminate();
+          }).then(
+            function rejectAfterConfirmedLoadTermination() { reject(reason); },
+            function rejectWithLoadTerminationFailure(error) { reject(error); },
+          );
+        };
+      });
+      signal.addEventListener?.("abort", onAbort, { once: true });
+      if (signal.aborted) onAbort();
+      try {
+        const result = await Promise.race([loadPromise, aborted]);
+        if (signal.aborted) {
+          await session.arcaneTerminate();
+          throw cancellationError(signal.reason);
+        }
+        return result;
+      } finally {
+        signal.removeEventListener?.("abort", onAbort);
+      }
+    },
+  });
+
+  Object.freeze(ProxyToWorker.prototype);
+  Object.freeze(Wllama.prototype);
+})();
+
 export {
   CacheManager,
   LogLevel,

package/docs/architecture.md

@@ -7,37 +7,142 @@ same structured event stream; the GUI is not a second build system.
 ```text
 external app repository -----+
                               |
-integrated Arcane checkout ---+-- CLI / future GUI / Codex / CI
+Arcane OS consumer checkout --+-- CLI / future GUI / Codex / CI
                                       |
                                shared toolchain API
                                       |
                        browser package or explicit target adapter
 ```
 
+## Canonical ownership and portability boundary
+
+The SDK repository is the canonical source for every mechanism that can be
+reused by a portable Arcane application. That includes shared modules,
+entities, components, themes, browser runtimes, providers, workers and assets;
+protocol, state, startup, readiness, progress, cancellation, unload and dispose
+machinery; public native contracts and adapters; the development source mount;
+and the packaging, license, receipt and verification boundaries for those
+portable bytes. In particular, shared AI selected-role hydration,
+startup-settled state and events, fail-closed role readiness, lifecycle and
+cancellation contracts, and the shared chat and speech components are
+SDK-owned source and contracts rather than Arcane OS–owned snapshots.
+
+Every portable application artifact materializes an immutable, locked and
+verified projection of the SDK runtime bytes, assets, workers, licenses and
+public contracts it uses. It remains self-contained whether it runs as plain
+HTML or inside an executable wrapper. It has no runtime dependency on an
+Arcane OS installation, source checkout or private Arcane OS import.
+
+Arcane OS is an SDK consumer like other applications. Its orchestrator,
+launcher, Shell, Provisioner, system AI application and internal tools use the
+same SDK modules and components rather than maintaining private runtime copies.
+Arcane OS and Core own the privileged host implementations, app/session
+admission and authorization, native transport and lifecycle, launcher and
+Shell orchestration, and system-AI policy specific to the Shell. The SDK may
+publish the capability-neutral Core bridge contract and adapters, but it does
+not embed Core or inherit another application's policy.
+
+Each application owns its branding, prompts, data, tools, business policy,
+model authorities and app-specific orchestration. Apply this decision order:
+
+| Responsibility | Canonical owner |
+|---|---|
+| Reusable by any portable application | Arcane SDK |
+| Host privilege, launcher, Shell or app/session admission | Arcane OS / Core |
+| Behavior unique to one product | That application |
+
+Do not copy a reusable implementation between the SDK, Arcane OS and an app,
+and do not create a hidden Arcane OS source dependency. Extend one neutral SDK
+contract and keep product policy in the consumer.
+
+Development and distribution use different authority. The explicit
+`arcane dev --sdk-runtime-source <sdk-root>` development-only live source mount
+lets a refresh read the saved SDK source without copying it into the app.
+Distribution never follows that mount. It embeds and verifies the application's
+locked immutable SDK projection.
+
+`tools/runtime-source.json` declares SDK-canonical authority for
+`runtime/arcane/` and retains the prior Arcane OS source only as legacy
+provenance for migrated compatibility bytes. The old OS-to-SDK synchronization
+direction is retired and fails closed. Arcane OS must consume a locked SDK
+projection through the same package/source-mount boundary as other apps; its
+repository-side consumer cutover is coordinated separately and does not create
+a co-equal source.
+
 ## Workspace profiles
 
 An external workspace maps the exact runtime shipped by its locked `arcane-os`
-dependency. An integrated workspace maps the live `arcane/` and
-`node_modules/strong-type` directories already owned by the Arcane checkout.
-The development server and packager consume the same route destinations in
-both cases, so app imports do not change. Integrated initialization creates
-only app-owned files and never rewrites Arcane root configuration.
+dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
+of portable runtime source. For live shared development, the explicit
+development-only SDK source mount maps the canonical SDK runtime and dependency
+paths into that consumer. Without the mount, the workspace uses its locked SDK
+projection. The development server and packager consume the same route
+destinations in both cases, so app imports do not change. Integrated
+initialization creates only app-owned files and never rewrites Arcane OS or SDK
+root configuration.
 
 The shared/Core development profile is a separate integrated-only scope selected
 with `--scope shared`. The SDK loads exactly
-`tools/integrated-development-provider.mjs` from the selected Arcane checkout as
-one process generation. That provider admits only one exact repository-relative
-focused `.test.mjs` through Arcane's canonical focused runner or Arcane's
-canonical development check. External workspaces cannot use the scope, and
-shared operations never enter app discovery, packaging, target planning, build,
-verification, or run paths. Provider bytes and filesystem identity are
-authenticated before and after the owned child operation; a generation change
-poisons that pairing and requires a new CLI process.
+`tools/integrated-development-provider.mjs` from the selected Arcane OS checkout
+as one process generation. This is a privileged host-development provider, not
+a source of portable SDK runtime bytes. That provider admits only one exact
+repository-relative focused `.test.mjs` through Arcane's canonical focused
+runner or Arcane's canonical development check. External workspaces cannot use
+the scope, and shared operations never enter app discovery, packaging, target
+planning, build, verification, or run paths. Provider bytes and filesystem
+identity are authenticated before and after the owned child operation; a
+generation change poisons that pairing and requires a new CLI process.
 Integrated app testing remains isolated to the selected `apps/<id>/test/`
 tree; it cannot recursively select Arcane root tests or another app's tests.
 External repositories retain their existing workspace-root plus selected-app
 test layout.
 
+## Development and release serving boundary
+
+Arcane applications keep one browser-first plain HTML, CSS, and JavaScript
+baseline. A native target runs that same application and progressively enhances
+it through capability-gated Arcane Core access. Browser operation must not
+depend on Core being present. A feature that genuinely requires Core fails
+closed and explains its unavailability without breaking unrelated browser
+behavior or claiming that the capability exists.
+
+Rapid development uses `arcane dev`. The development server maps the selected
+application's canonical source tree and the live installed SDK/runtime routes.
+Each request reads the current saved source into the existing bounded response
+snapshot, so a browser refresh shows source changes without packaging, copying
+files into `dist`, or restarting the server. Restarting is not a content
+synchronization step; when a refresh is stale, first verify the command, URL,
+workspace, selected app, and resolved source route.
+
+Development is an intentionally fast feedback loop. Keep each increment small
+and independently understandable so its effect has one clear cause and a
+mistake can be isolated without untangling unrelated work. A development
+operation does not implicitly run tests, checks, packaging, builds, or release
+verification. The developer invokes a focused test or check deliberately at an
+explicit checkpoint; merely refreshing source does not trigger one.
+
+Executable development uses an Arcane-owned native development wrapper around
+the same source-serving browser surface. The wrapper is an escalated browser,
+not a packaged application: it loads current source files and adds only the
+selected application's declared, capability-gated local Arcane Core access.
+It preserves the browser behavior when Core is absent, fails closed for an
+unavailable native-only capability, and never silently substitutes a release
+tree. Starting or refreshing this wrapper does not package, copy to `dist`, or
+run tests automatically. The SDK must not describe native source development as
+available until this wrapper and its explicit capability boundary are actually
+implemented.
+
+Package and release verification use a separate explicit boundary. Run
+`arcane package` to generate and verify `dist/<id>`, then use
+`arcane run --target browser` to serve only that verified release. Distribution
+automatically runs the selected application's required tests before accepting,
+serving, or launching `dist` and fails closed on any test failure. The browser
+run command does not substitute source files. If source changes after
+packaging, the prior `dist` remains intentionally unchanged until the next
+explicit package operation. Never use packaged `dist` as the everyday
+development tree, and never treat source-serving behavior as evidence for the
+release artifact.
+
 ## App and release contract
 
 The first SDK version deliberately preserves Arcane's current repository-shaped
@@ -55,11 +160,13 @@ exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
 apps synthesize that descriptor from their schema-1 package plus the current
 native registry during migration.
 
-An external app's `arcane-packager.json` has three exact shared routes. They map the
-installed SDK runtime to `/arcane`, its vendored strong-type dependency to
+An external app's `arcane-packager.json` has three exact shared routes. They map
+the installed SDK runtime to `/arcane`, its vendored strong-type dependency to
 `/node_modules/strong-type`, and the SDK's `LICENSE`,
-`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. The app does not
-copy Arcane runtime source into its repository.
+`COMMERCIAL-LICENSE.md`, and `NOTICE` to `/licenses/arcane-os`. Development does
+not copy SDK runtime source into the app repository. Distribution materializes
+those exact locked SDK routes inside the portable artifact and verifies their
+immutable inventory, so the finished app has no Arcane OS runtime dependency.
 
 Release schema 1 and builder identity `arcane-app-packager-v1` remain unchanged
 because current Arcane native admission treats them as exact contracts. Native
@@ -93,7 +200,7 @@ length with an EOF growth probe, and rechecked by handle and pathname identity.
 Every cumulative path prefix has one case-folded spelling and one file/directory
 kind; prefix topology conflicts and the complete portable Windows device-name
 set fail before creation or admission.
-The current SDK admits only the explicitly compatible `0.1.0-dev.5` bundle
+The current SDK admits only the explicitly compatible `0.2.0` bundle
 generation and rejects zero-byte payload releases.
 
 Promotion retains any prior output as an identity-bound backup until the new
@@ -150,8 +257,11 @@ failure propagation. No app or target loop exists in that scope.
 
 ## Verification receipts
 
-Runtime verification binds the exact SDK version, upstream Arcane commit,
-runtime inventory, byte counts, and SHA-256 hashes. Packaging writes the full
+Runtime verification binds the exact SDK version, canonical SDK source
+identity, runtime inventory, byte counts, and SHA-256 hashes. During the
+source-ownership migration it may additionally record imported Arcane OS
+provenance for compatibility bytes, but that field does not transfer canonical
+ownership. Packaging writes the full
 schema-1 release inventory to `ARCANE_APP_RELEASE.json`; its operation result
 returns a deeply immutable, process-authenticated receipt that binds the
 canonical location, app policy, complete inventory, content digest, and verified
@@ -210,7 +320,7 @@ through SDK-bound verified readers rather than accepting a mutable source path
 as authority. Build completion requires provider verification, and later
 verify/run calls receive the exact artifact receipt.
 
-The SDK `0.1.0-dev.5` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.2.0` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/README.md

@@ -38,7 +38,7 @@ This repository contains two related, explicitly versioned surfaces:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.1.1` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` entrypoint in this checkout. |
+| SDK and CLI | `arcane-os` `0.1.2` | The Node.js toolchain plus the browser-only `arcane-os/ai/browser-wasm` entrypoint 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. |