arcane-os 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.61.0
+
+- Add retained local image generation through Core, with public native runtime,
+  Core service and browser accessor entrypoints. Applications keep ownership of
+  prompts, styles, saved images and associations.
+- Select the approved stable-diffusion.cpp runtime and Stable Diffusion 1.4
+  checkpoint through existing local-AI configuration. Runtime installation and
+  model storage/preparation remain separate; model setup uses the existing
+  DBOPFS model store and a retained Core working-file projection.
+- Preserve complete prompts and PNG results, synchronous transient Thinking
+  acknowledgement, observable model state and progress, actual cancellation
+  joining, and native context/file cleanup. Preparation does not block page
+  rendering or unrelated Core services.
+- Expose model-assets preparation and service entrypoints alongside image
+  generation. Native contexts retain working files until actual unload; the
+  browser accessor closes only its own requests and subscriptions.
+- Built-in distributions select CPU on Windows and Linux and the same upstream
+  Metal/CPU archive on macOS. Windows CUDA preparation remains separate pending
+  work; publication does not claim GPU-first Windows or PM execution.
+- Keep optional engine/binding acquisition in the selected application's
+  existing installer workflow. No engine binaries or model checkpoint are added
+  to the npm package, and its declared dependency tree is unchanged.
+
 ## 0.60.0
 
 - Add `Arcane.window.setTheme(presentation, {signal})` for the current native

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.60.0` SDK contract. Development applications declare
+This checkout defines the `0.61.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/ai/core-image.mjs

@@ -0,0 +1,360 @@
+import Is from '../dependencies/strong-type/index.js';
+import {getInstalledCoreClient} from '../core/client.mjs';
+import {CoreError, serializeCoreError} from '../core/contracts.mjs';
+import {createArcaneEventSource} from '../event-manager.mjs';
+
+const is = new Is(false);
+
+function unavailable(message) {
+    return new CoreError(
+        {code: 'ARCANE_IMAGE_CORE_UNAVAILABLE', message}
+    );
+}
+
+/** Decode the complete JSON transport representation without retaining it. */
+function decodeImage(image) {
+    const {data, encoding, ...metadata} = image;
+    if (encoding !== 'base64') {
+        throw new TypeError('Core image results require base64 transport encoding.');
+    }
+    const decoded = Uint8Array.from(
+        globalThis.atob(data),
+        function decodeImageCharacter(character) {
+            return character.charCodeAt(0);
+        }
+    );
+    const blob = new Blob(
+        [decoded],
+        {type: metadata.mediaType}
+    );
+    return {...metadata, blob};
+}
+
+/** Browser access to the selected native image service; no result persistence. */
+export function createCoreImageRuntime(
+    {client = getInstalledCoreClient(), signal, onEvent} = {}
+) {
+    const owner = {};
+    const events = createArcaneEventSource(
+        owner,
+        {source: 'core-image', eventTypes: ['image.state']}
+    );
+    const lifetime = new AbortController();
+    const lifetimeSignal = signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal;
+    const pending = new Set();
+    let state = {
+        id: 'stable-diffusion.cpp',
+        installed: false,
+        available: false,
+        selectedModel: null,
+        loaded: false,
+        state: client ? 'unknown' : 'unavailable',
+        backend: null,
+        devices: [],
+        resources: {},
+        progress: null,
+        error: null,
+        models: []
+    };
+    let revision = 0;
+    let closed = false;
+    let closing;
+
+    function current() {
+        const requests = [...pending].map(
+            function requestState(request) {
+                return {
+                    method: request.method,
+                    streamId: request.streamId,
+                    status: request.status,
+                    progress: request.progress
+                };
+            }
+        );
+        return {
+            ...state,
+            requests,
+            status: !closed && requests.some(
+                function generationPending(request) {
+                    return request.status === 'Thinking';
+                }
+            ) ? 'Thinking' : null,
+            busy: pending.size > 0,
+            closed
+        };
+    }
+
+    function reportObserverFailure(error) {
+        globalThis.console?.error('Core image observer failed.', error);
+    }
+
+    function notifyListener(listener, value) {
+        const result = listener(value);
+        if (result && is.function(result.then)) {
+            // Observers own their callback lifetimes and may await close().
+            Promise.resolve(result).catch(reportObserverFailure);
+        }
+    }
+
+    function observe(callback, value) {
+        if (!is.function(callback)) {
+            return;
+        }
+        try {
+            notifyListener(callback, value);
+        } catch (error) {
+            reportObserverFailure(error);
+        }
+    }
+
+    function publish() {
+        const snapshot = current();
+        events.dispatch('image.state', snapshot);
+        if (snapshot.closed === closed) {
+            observe(
+                onEvent,
+                {type: 'image.state', data: snapshot}
+            );
+        }
+        return snapshot;
+    }
+
+    function accept(value) {
+        if (closed) {
+            return;
+        }
+        state = value;
+        revision += 1;
+        publish();
+    }
+
+    const unsubscribe = client?.events.on('image.state', accept)
+        ?? function noCoreSubscription() {};
+
+    function invoke(method, parameters, {signal: requestSignal, onProgress} = {}) {
+        if (closed) {
+            throw unavailable('The Core image accessor is closed.');
+        }
+        if (!client) {
+            throw unavailable('Local image generation requires an available Core connection.');
+        }
+        const operationSignal = requestSignal
+            ? AbortSignal.any([requestSignal, lifetimeSignal]) : lifetimeSignal;
+        operationSignal.throwIfAborted();
+        const request = {
+            method,
+            revision,
+            streamId: parameters.streamId,
+            status: method === 'image.generate' ? 'Thinking' : null,
+            progress: null,
+            task: null
+        };
+        let stopProgress;
+        if (request.streamId) {
+            stopProgress = client.events.on(
+                'image.progress',
+                function imageProgress(value) {
+                    if (closed || operationSignal.aborted || value.streamId !== request.streamId) {
+                        return;
+                    }
+                    request.progress = value.progress;
+                    publish();
+                    if (closed || operationSignal.aborted) {
+                        return;
+                    }
+                    observe(onProgress, value.progress);
+                    if (closed || operationSignal.aborted) {
+                        return;
+                    }
+                    observe(
+                        onEvent,
+                        {type: 'image.progress', data: value}
+                    );
+                }
+            );
+        }
+        request.task = Promise.resolve().then(
+            async function executeImageRequest() {
+                operationSignal.throwIfAborted();
+                observe(
+                    onEvent,
+                    {type: 'image.request', data: {method, parameters}}
+                );
+                operationSignal.throwIfAborted();
+                const result = await client.invoke(
+                    method,
+                    parameters,
+                    {signal: operationSignal, timeoutMs: 0}
+                );
+                operationSignal.throwIfAborted();
+                if (method === 'image.generate') {
+                    const images = result.images.map(decodeImage);
+                    operationSignal.throwIfAborted();
+                    const decoded = {...result, images};
+                    observe(
+                        onEvent,
+                        {type: 'image.result', data: decoded}
+                    );
+                    operationSignal.throwIfAborted();
+                    return decoded;
+                }
+                return result;
+            }
+        ).catch(
+            function imageRequestFailed(error) {
+                if (!closed && !operationSignal.aborted) {
+                    if (method !== 'image.status' || revision === request.revision) {
+                        state = {...state, error: serializeCoreError(error)};
+                    }
+                    observe(
+                        onEvent,
+                        {type: 'image.error', data: {method, error: serializeCoreError(error)}}
+                    );
+                }
+                throw error;
+            }
+        ).finally(
+            function releaseImageRequest() {
+                stopProgress?.();
+                pending.delete(request);
+                if (!closed) {
+                    publish();
+                }
+            }
+        );
+        pending.add(request);
+        // Acknowledgement precedes transport, preparation, model loading and inference.
+        publish();
+        return request.task;
+    }
+
+    async function inspect({signal: requestSignal} = {}) {
+        const before = revision;
+        try {
+            const result = await invoke(
+                'image.status',
+                {},
+                {signal: requestSignal}
+            );
+            if (!closed && revision === before) {
+                accept(result);
+            }
+            return current();
+        } catch (error) {
+            if (!closed && !requestSignal?.aborted && revision === before) {
+                accept(
+                    {...state, available: false, state: 'unavailable', error: serializeCoreError(error)}
+                );
+            }
+            throw error;
+        }
+    }
+
+    async function load({model, context, assetProjectionId, resourcePaths, signal: requestSignal} = {}) {
+        const before = revision;
+        const result = await invoke(
+            'image.load',
+            {model, context, assetProjectionId, resourcePaths},
+            {signal: requestSignal}
+        );
+        if (!closed && revision === before) {
+            accept(result);
+        }
+        return result;
+    }
+
+    function generate(
+        {model, prompt, parameters, assetProjectionId, resourcePaths, signal: requestSignal, onProgress} = {}
+    ) {
+        const streamId = client?.uuid?.() ?? globalThis.crypto.randomUUID();
+        return invoke(
+            'image.generate',
+            {model, prompt, parameters, streamId, assetProjectionId, resourcePaths},
+            {signal: requestSignal, onProgress}
+        );
+    }
+
+    async function unload({signal: requestSignal} = {}) {
+        const before = revision;
+        const result = await invoke(
+            'image.unload',
+            {},
+            {signal: requestSignal}
+        );
+        if (!closed && revision === before) {
+            accept(result);
+        }
+        return result;
+    }
+
+    function subscribe(listener, {replay = true, signal: subscriptionSignal} = {}) {
+        if (!is.function(listener)) {
+            throw new TypeError('An image state listener must be a function.');
+        }
+        if (closed) {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+            return function closedSubscription() {};
+        }
+        const stop = events.on(
+            'image.state',
+            function imageStateChanged(event) {
+                notifyListener(listener, event.detail);
+            },
+            {signal: subscriptionSignal}
+        );
+        try {
+            if (replay && !subscriptionSignal?.aborted) {
+                notifyListener(listener, current());
+            }
+        } catch (error) {
+            stop();
+            throw error;
+        }
+        return stop;
+    }
+
+    function close() {
+        if (closing) {
+            return closing;
+        }
+        closed = true;
+        closing = Promise.resolve().then(
+            async function closeImageAccessor() {
+                await Promise.allSettled(
+                    [...pending].map(
+                        function requestCompletion(request) {
+                            return request.task;
+                        }
+                    )
+                );
+            }
+        );
+        lifetime.abort();
+        lifetimeSignal.removeEventListener('abort', close);
+        unsubscribe();
+        state = {...state, available: false, state: 'closed'};
+        publish();
+        events.dispose();
+        return closing;
+    }
+
+    lifetimeSignal.addEventListener(
+        'abort',
+        close,
+        {once: true}
+    );
+    if (lifetimeSignal.aborted) {
+        close();
+    } else if (client) {
+        // Subscribe before the snapshot request so a later lifecycle event wins.
+        inspect().catch(
+            function initialImageStateUnavailable(error) {
+                globalThis.console?.error('Core image initial state unavailable.', error);
+            }
+        );
+    }
+
+    return {load, generate, unload, inspect, current, subscribe, close};
+}

package/docs/reference/local-image-generation.md

@@ -0,0 +1,267 @@
+# Local image generation through Core
+
+The SDK's local image service runs selected stable-diffusion.cpp models in a
+retained native context. The browser uses Core for model lifecycle and complete
+PNG results. Applications own image prompts, style choices, character identity,
+associations and saved results.
+
+Runtime installation, model asset preparation, model loading and image
+generation are separate operations. The service starts promptly and retains
+runtime preparation in the background. `image.status` remains callable during
+preparation; rendering and unrelated Core services continue independently.
+
+## Selection and model assets
+
+Select the runtime in `arcane-app.json` under `native.localAI`, or in the
+corresponding package projection's `localAI` record:
+
+```json
+{
+    "runtimes": [
+        {
+            "id": "stable-diffusion.cpp",
+            "version": "master-929-3f8527a",
+            "backend": "auto",
+            "models": ["sd14"]
+        }
+    ]
+}
+```
+
+`sd14` selects the Stable Diffusion 1.4 definition and its official
+`sd-v1-4.ckpt` resource. A model definition contains `id`, `name`, `family`,
+`resources`, `context`, `defaults` and `operations`. Selection supplies the
+model's resource metadata; runtime installation does not independently download
+or bundle model files. The shared model asset owner prepares selected browser
+assets and supplies a Core working projection for native path-based loading.
+
+The first published distribution path selects CPU on Windows and Linux.
+On macOS, `auto` selects the same upstream universal runtime's built-in Metal
+backend, with CPU fallback; explicit `cpu` remains available. A caller-supplied
+runtime archive with `backend: 'auto'` uses its available accelerated device
+with CPU fallback. Built-in Windows CUDA distribution preparation is a separate
+pending addition. Actual backend/device availability and failures
+come from the runtime, separately from hardware metadata or an installed archive.
+Cancellation, invalid model input and inference failures retain their actual
+errors. Model loading has no native cancellation handle before its constructor
+returns; cancellation joins that call and releases its returned context before
+the operation settles.
+
+The complete prepared projection has an `id`, a `directory`, a `members` list
+and `release()`. `resourcePaths` maps native model resource roles to exact
+projection member paths. For the selected checkpoint, the role is `model`.
+The member name must match the preparation result. See
+[Model assets through Core](model-assets.md) for the shared preparation
+lifecycle. Core acquires its own
+retain before loading. The caller can release its preparation ownership after
+successful `load()` acknowledgement: Core retains the files while its native
+context needs them. Release caller ownership when loading fails too; native
+cleanup keeps its own retain through actual completion. A later
+`generate({model: 'sd14', ...})` reuses that prepared selection. Replacing or
+unloading the context releases displaced projections
+after actual native operations settle. Core shutdown joins owned operations
+before releasing retained model files.
+
+`model` also accepts a complete prepared model descriptor. Native callers can
+supply actual resource paths directly. The browser projection arguments supply
+the native paths through the shared asset service and preserve the remaining
+descriptor fields. The image service creates no second model downloader or
+durable model store.
+
+## Browser accessor
+
+```js
+import {createCoreImageRuntime} from 'arcane-os/ai/core-image';
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+import {createBrowserModelSource, createDbopfsModelStore} from 'arcane-os/ai/browser-wasm';
+
+const page = new AbortController();
+window.addEventListener(
+    'pagehide',
+    function detachImagePage() {
+        page.abort();
+    },
+    {once: true}
+);
+
+const images = createCoreImageRuntime(
+    {signal: page.signal}
+);
+
+images.subscribe(
+    function showImageStatus(snapshot) {
+        statusElement.textContent = snapshot.status ?? snapshot.state;
+    }
+);
+
+const selected = (await images.inspect()).models.find(
+    function selectedCheckpoint(model) {
+        return model.id === 'sd14';
+    }
+);
+const resource = selected.resources.model;
+const source = createBrowserModelSource(
+    {
+        id: selected.id,
+        files: [
+            {name: resource.filename, url: resource.url}
+        ]
+    }
+);
+const store = createDbopfsModelStore(
+    {dbopfs, downloadConcurrency: 4}
+);
+const stored = await store.ensure(
+    source,
+    {signal: page.signal, offline: false}
+);
+const projection = await prepareCoreModelAssets(
+    {
+        workingDirectory: '.arcane/model-working',
+        members: source.files.map(
+            function preparedCheckpoint(member, index) {
+                return {path: member.name, file: stored.files[index]};
+            }
+        ),
+        signal: page.signal
+    }
+);
+
+try {
+    await images.load(
+        {
+            model: 'sd14',
+            assetProjectionId: projection.id,
+            resourcePaths: {
+                model: 'sd-v1-4.ckpt'
+            },
+            signal: page.signal
+        }
+    );
+} finally {
+    await projection.release();
+}
+
+const result = await images.generate(
+    {
+        model: 'sd14',
+        prompt: 'Portrait of a dignified raccoon astronaut holding a tiny moon cactus.',
+        signal: page.signal,
+        onProgress(progress) {
+            console.log(progress);
+        }
+    }
+);
+
+for (const image of result.images) {
+    const url = URL.createObjectURL(image.blob);
+    const preview = new Image();
+    preview.alt = 'Generated raccoon astronaut portrait';
+    function releasePreviewURL() {
+        URL.revokeObjectURL(url);
+    }
+    preview.addEventListener(
+        'load',
+        releasePreviewURL,
+        {once: true}
+    );
+    preview.addEventListener(
+        'error',
+        releasePreviewURL,
+        {once: true}
+    );
+    preview.src = url;
+    imageContainer.append(preview);
+}
+```
+
+The example uses the application's existing `dbopfs` instance and existing
+`statusElement` and `imageContainer` elements. The published model store accepts
+the selected checkpoint as an ordinary resource: `ensure()` returns complete
+ordered `Blob` or `File` members after its resumable download. Range support
+allows concurrent transfer within a member; those transfer parts remain the
+store's concern. Use `offline: true` to require an already complete stored model.
+The store does not select or run the image engine. In source development,
+load the development Core bootstrap described
+in [Local AI through Core](local-ai.md#development) before constructing the
+accessor. Native hosts install their Core client through the existing host path.
+An ordinary browser without Core reports local image generation as unavailable.
+
+| Member | Contract |
+|---|---|
+| `createCoreImageRuntime({client?, signal?, onEvent?})` | Uses the installed Core client by default, subscribes to lifecycle events and asynchronously reads one initial status snapshot. It returns immediately. |
+| `load({model, context?, assetProjectionId?, resourcePaths?, signal?})` | Loads the selected model and returns authoritative service state after native completion. `context` supplies native context options. |
+| `generate({model, prompt, parameters?, assetProjectionId?, resourcePaths?, signal?, onProgress?})` | Returns the complete result with `images: [{blob, mediaType, width, height}]`. Additional runtime result metadata remains present. |
+| `unload({signal?})` | Explicitly unloads the shared selected native context and returns its resulting state. |
+| `inspect({signal?})` | Reads current Core status without waiting for model or runtime preparation. |
+| `current()` | Synchronously returns the retained lifecycle snapshot and this accessor's transient request status. |
+| `subscribe(listener, {replay = true, signal?})` | Observes `image.state` and immediately replays the current snapshot by default; returns an unsubscribe function. |
+| `close()` | Cancels this accessor's requests, removes subscriptions and joins its request promises. It leaves the shared Core client and selected model under their existing owners. |
+
+Generation publishes `status: 'Thinking'` synchronously when accepted, before
+transport, preparation, model loading or inference waits. This remains transient
+status until the complete image result arrives. Native sampling progress is
+reported as progress, with no fabricated image chunks or conversation turns.
+The accessor's `requests` records contain method, stream ID, status and progress;
+they contain no saved prompt or image history.
+
+The authoritative lifecycle snapshot includes `selectedModel`, `loaded`,
+`state`, `backend`, `progress`, `error`, native resource paths and device state.
+Service metadata adds runtime `id`, installation/availability state and selected
+model definitions, including their resource metadata before engine preparation
+finishes. Installed files do not imply a loaded model. A late status
+response never overwrites a newer lifecycle event.
+
+Prompts and parameters pass unchanged to the native runtime. Native option
+names, supported model operations and defaults belong to that runtime and the
+selected model definition. A prompt containing U+0000 or an unpaired UTF-16
+surrogate cannot pass unchanged through the native UTF-8 C-string boundary and
+reports that incompatibility.
+
+The request signal propagates through Core to the owning native operation.
+Aborted requests produce no late image result or progress callback. Request
+invocations use `timeoutMs: 0`; there is no arbitrary image-generation timeout.
+Errors retain their actual details on rejected promises and diagnostic events.
+Applications choose concise ordinary status text and keep complete engineering
+details in their diagnostic surface, outside durable chat history.
+
+`onEvent` observes `image.state`, `image.progress`, `image.request`,
+`image.result` and `image.error` records. Observer failures are reported to the
+developer console and do not replace inference results. Observers own their
+asynchronous callback lifetimes. The SDK persists no prompt, result, transcript
+or application-owned image association.
+
+## Core service and transport
+
+`createLocalImageService(configuration, options)` is exported from
+`arcane-os/core/image`. `configuration` is the selected `localAI` record.
+Options are `appRoot`, installed `runtimes`, `signal`, `onEvent`, an optional
+`prepare` callback and the existing `modelAssets` service instance.
+
+`prepare({appRoot, configuration, requirement, signal, onEvent})` returns one
+installed runtime record. Preparation runs once per service. That record carries
+`libraryPath`, `bindingModulePath`, `backend`, `variants` and model definitions.
+Runtime variants preserve their native backend, library path and runtime root.
+The service retains one native runtime and subscribes to its current-state
+replay. Expensive model execution belongs to that runtime's worker.
+
+| Method/event | Parameters or result |
+|---|---|
+| `image.status` | Immediate lifecycle snapshot. |
+| `image.load` | `{model, context?, assetProjectionId?, resourcePaths?}`; returns lifecycle snapshot. |
+| `image.generate` | `{model, prompt, parameters?, streamId?, assetProjectionId?, resourcePaths?}`; returns complete encoded images. |
+| `image.unload` | Empty parameters; returns lifecycle snapshot after unload. |
+| `image.state` | Complete service lifecycle snapshot. Service and browser `subscribe()` provide current-state replay. |
+| `image.progress` | `{streamId, requestId, status: 'Thinking', progress}` for the corresponding generation request. |
+
+Core's JSON transport represents each complete PNG as
+`{data, encoding: 'base64', mediaType: 'image/png', width, height}`. The browser
+decodes that complete representation into a `Blob` and preserves its metadata.
+There is no result resizing, clipping, storage write or application policy at
+this transport boundary.
+
+One service prepares one selected runtime, retains one selected native context
+and performs one native generation per request. The native owner serializes
+only competing operations on that context. Independent Core services and page
+rendering remain concurrent. Native platform execution evidence and package
+publication are separate from this source/API description.

package/docs/reference/model-assets.md

@@ -42,13 +42,16 @@ try {
     // Native loading takes its own retain handle before using these files.
     await projection.release();
 }
-const result = await image.generate({
-    model: 'sd14',
-    prompt: 'A dignified raccoon who has been put in charge of the moon.',
-    signal
-});
-// Display or save the complete returned image through the application owner.
-await image.unload();
+try {
+    const result = await image.generate({
+        model: 'sd14',
+        prompt: 'A dignified raccoon who has been put in charge of the moon.',
+        signal
+    });
+    // Display or save the complete returned image through the application owner.
+} finally {
+    await image.unload();
+}
 ```
 
 This example assumes that the application selected the `sd14` model and its