arcane-os 0.62.0 → 0.64.0

package/src/local-ai/whisper/install.mjs

@@ -0,0 +1,274 @@
+import {createWriteStream} from 'node:fs';
+import {copyFile, cp, mkdir, readdir, stat, unlink} from 'node:fs/promises';
+import path from 'node:path';
+import {Readable} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import Is from 'strong-type';
+import packageMetadata from '../../../package.json' with {type: 'json'};
+import {ArcaneError, ERROR_CODES, throwIfAborted} from '../../errors.mjs';
+import {extractLocalAIArchive} from '../archive.mjs';
+
+const is = new Is(false);
+
+/** Functional selection keys share preparation, never identify model content. */
+export function whisperRuntimeSelection(requirement, includeModels = true) {
+    const {models, modelId, helperRoot, helperVersion, ...runtime} = requirement;
+    return JSON.stringify({
+        ...runtime,
+        ...(includeModels ? {models, modelId} : {}),
+        helperVersion: helperVersion ?? packageMetadata.version,
+        helperRoot: helperRoot ?? (is.string(requirement.helperExecutable) ? path.dirname(requirement.helperExecutable) : undefined)
+    });
+}
+
+export async function installedWhisperRuntime(record, signal, includeModels = true) {
+    if (!is.array(record?.variants) || record.variants.length === 0 || !is.array(record.models)) return false;
+    const files = [record.helperExecutable, record.decoderExecutable];
+    const directories = [record.root, record.helperRoot ?? (is.string(record.helperExecutable) ? path.dirname(record.helperExecutable) : undefined), record.decoderRoot];
+    for (const variant of record.variants) {
+        files.push(variant.executable);
+        directories.push(variant.root, variant.libraryDirectory);
+    }
+    if (includeModels) for (const model of record.models) files.push(model.path);
+    for (const location of directories) {
+        throwIfAborted(signal);
+        if (!is.string(location) || !(await stat(location)).isDirectory()) return false;
+    }
+    for (const location of files) {
+        throwIfAborted(signal);
+        if (!is.string(location) || !(await stat(location)).isFile()) return false;
+    }
+    return true;
+}
+
+async function findWhisperFile(root, filename, signal) {
+    const directories = [root];
+    for (const directory of directories) {
+        throwIfAborted(signal);
+        for (const entry of await readdir(directory, {withFileTypes: true})) {
+            const location = path.join(directory, entry.name);
+            if (entry.name === filename && (entry.isFile() || entry.isSymbolicLink())) return location;
+            if (entry.isDirectory()) directories.push(location);
+        }
+    }
+    throw new ArcaneError(ERROR_CODES.operationFailed, `The selected Whisper dependency tree does not contain ${filename}.`);
+}
+
+async function downloadWhisperResource(url, filename, {signal, onEvent, upstreamResponse}) {
+    await onEvent({
+        type: 'local-ai.install.downloading',
+        message: `Downloading ${path.basename(filename)}.`,
+        data: {id: 'whisper.cpp', asset: path.basename(filename)}
+    });
+    const response = await upstreamResponse(url, signal);
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(filename, {flags: 'wx'}), {signal});
+}
+
+async function prepareWhisperArchive(url, root, options) {
+    const filename = path.posix.basename(new URL(url).pathname);
+    const archive = path.join(path.dirname(root), `${path.basename(root)}-${filename}`);
+    await downloadWhisperResource(url, archive, options);
+    await options.onEvent({
+        type: 'local-ai.install.extracting',
+        message: `Extracting ${filename}.`,
+        data: {id: 'whisper.cpp', asset: filename}
+    });
+    await extractLocalAIArchive({archive, directory: root, signal: options.signal, onEvent: options.onEvent});
+    await unlink(archive);
+}
+
+async function copyWhisperTree(source, destination, signal) {
+    throwIfAborted(signal);
+    await cp(path.resolve(source), destination, {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: function retainCompleteWhisperTree() {
+            throwIfAborted(signal);
+            return true;
+        }
+    });
+    throwIfAborted(signal);
+}
+
+function copiedWhisperLocation(sourceRoot, destinationRoot, location) {
+    const root = path.resolve(sourceRoot);
+    const relative = path.relative(root, path.resolve(root, location));
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'A Whisper library, helper, or decoder path must belong to its selected complete runtime tree so the native bundle can retain it.');
+    }
+    return path.join(destinationRoot, relative);
+}
+
+function defaultWhisperVariants(requirement, platform, architecture) {
+    if (requirement.variants) return requirement.variants;
+    if (platform !== 'win32' || architecture !== 'x64' || requirement.version !== '1.9.4') {
+        throw new ArcaneError(ERROR_CODES.targetUnavailable, `Automatic Whisper distributions are available for 1.9.4 on win32/x64. Supply complete runtime variants for ${requirement.version} on ${platform}/${architecture}.`);
+    }
+    if (requirement.backend === 'metal') {
+        throw new ArcaneError(ERROR_CODES.targetUnavailable, 'The selected Windows Whisper distribution has no Metal backend.');
+    }
+    return [
+        ...(requirement.backend === 'cpu' ? [] : [{
+            backend: 'cuda',
+            url: 'https://github.com/ggml-org/whisper.cpp/releases/download/b5130/whisper-cublas-12.4.0-bin-x64.zip'
+        }]),
+        {
+            backend: 'cpu',
+            url: 'https://github.com/ggml-org/whisper.cpp/releases/download/b5130/whisper-bin-x64.zip'
+        }
+    ];
+}
+
+/** Prepare complete runtime trees under the shared install attempt owner. */
+export async function installWhisperDistribution(requirement, options) {
+    const {root, platform, architecture, onEvent, reusable} = options;
+    const controller = new AbortController();
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const preparation = {...options, signal};
+    const variants = reusable?.runtime.variants ?? defaultWhisperVariants(requirement, platform, architecture);
+    if (!requirement.helperExecutable && !requirement.helperUrl && (platform !== 'win32' || architecture !== 'x64')) {
+        throw new ArcaneError(ERROR_CODES.targetUnavailable, `Supply the Arcane Whisper helperExecutable or helperUrl for ${platform}/${architecture}.`);
+    }
+    if (!requirement.decoderExecutable && !requirement.decoderUrl && (platform !== 'win32' || architecture !== 'x64')) {
+        throw new ArcaneError(ERROR_CODES.targetUnavailable, `Supply a complete decoder tree through decoderExecutable and decoderRoot, or decoderUrl, for ${platform}/${architecture}.`);
+    }
+    const helperName = `arcane-whisper${platform === 'win32' ? '.exe' : ''}`;
+    const helperRoot = path.join(root, 'helper');
+    let helperExecutable = path.join(helperRoot, helperName);
+    const decoderRoot = path.join(root, 'decoder');
+    const models = [];
+    const preparedVariants = [];
+    let decoderExecutable;
+    await mkdir(root, {recursive: true});
+
+    const jobs = variants.map(function variantPreparation(variant, index) {
+        return async function prepareSelectedVariant() {
+            const variantRoot = path.join(root, `variant-${index}-${variant.backend}`);
+            const selectedLibraryDirectory = variant.libraryDirectory
+                ? copiedWhisperLocation(variant.root ?? variantRoot, variantRoot, variant.libraryDirectory)
+                : undefined;
+            if (variant.root) await copyWhisperTree(variant.root, variantRoot, signal);
+            else await prepareWhisperArchive(variant.url, variantRoot, preparation);
+            const libraryName = platform === 'win32' ? 'whisper.dll' : platform === 'darwin' ? 'libwhisper.dylib' : 'libwhisper.so';
+            const libraryDirectory = selectedLibraryDirectory ?? path.dirname(await findWhisperFile(variantRoot, libraryName, signal));
+            preparedVariants[index] = {backend: variant.backend, root: variantRoot, libraryDirectory};
+        };
+    });
+    jobs.push(async function prepareHelper() {
+        const existingHelper = reusable?.runtime.helperExecutable ?? requirement.helperExecutable;
+        if (existingHelper) {
+            const source = path.resolve(existingHelper);
+            const sourceRoot = path.resolve(reusable
+                ? reusable.runtime.helperRoot ?? path.dirname(source)
+                : requirement.helperRoot ?? path.dirname(source));
+            helperExecutable = copiedWhisperLocation(sourceRoot, helperRoot, source);
+            await copyWhisperTree(sourceRoot, helperRoot, signal);
+            return;
+        }
+        const helperVersion = requirement.helperVersion ?? packageMetadata.version;
+        const helperUrl = requirement.helperUrl ?? `https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/${helperVersion}/arcane-whisper-windows-x64.tar.gz`;
+        await prepareWhisperArchive(helperUrl, helperRoot, preparation);
+        helperExecutable = await findWhisperFile(helperRoot, helperName, signal);
+    });
+    jobs.push(async function prepareDecoder() {
+        const existingDecoder = reusable?.runtime.decoderExecutable ?? requirement.decoderExecutable;
+        if (existingDecoder) {
+            const source = path.resolve(existingDecoder);
+            const sourceRoot = path.resolve(reusable?.runtime.decoderRoot ?? requirement.decoderRoot ?? path.dirname(source));
+            decoderExecutable = copiedWhisperLocation(sourceRoot, decoderRoot, source);
+            await copyWhisperTree(sourceRoot, decoderRoot, signal);
+            return;
+        }
+        await prepareWhisperArchive(
+            requirement.decoderUrl ?? 'https://github.com/GyanD/codexffmpeg/releases/download/9.0.2/ffmpeg-9.0.2-essentials_build.zip',
+            decoderRoot,
+            preparation
+        );
+        decoderExecutable = await findWhisperFile(decoderRoot, `ffmpeg${platform === 'win32' ? '.exe' : ''}`, signal);
+    });
+    for (const [index, model] of requirement.models.entries()) {
+        jobs.push(async function prepareSelectedModel() {
+            const modelRoot = path.join(root, 'models', String(index));
+            await mkdir(modelRoot, {recursive: true});
+            const filename = model.path ? path.basename(model.path) : model.filename ?? path.posix.basename(new URL(model.url).pathname);
+            const destination = path.join(modelRoot, filename);
+            const priorIndex = reusable?.requirement.models.findIndex(function sameSelectedModel(candidate) {
+                return JSON.stringify(candidate) === JSON.stringify(model);
+            }) ?? -1;
+            let source = model.path;
+            if (priorIndex >= 0) {
+                const priorPath = reusable.runtime.models[priorIndex]?.path;
+                if (priorPath) {
+                    try {
+                        if ((await stat(priorPath)).isFile()) source = priorPath;
+                    } catch (error) {
+                        if (error.code !== 'ENOENT') throw error;
+                    }
+                }
+            }
+            if (source) await copyFile(path.resolve(source), destination);
+            else await downloadWhisperResource(model.url, destination, preparation);
+            models[index] = {...model, path: destination};
+        });
+    }
+    let nextJob = 0;
+    const failures = [];
+    async function prepareWhisperDependencies() {
+        while (nextJob < jobs.length) {
+            throwIfAborted(signal);
+            const job = jobs[nextJob++];
+            try {
+                await job();
+            } catch (error) {
+                failures.push(error);
+                controller.abort(error);
+            }
+        }
+    }
+    const workers = await Promise.allSettled(Array.from({length: Math.min(3, jobs.length)}, function startWhisperDependencyWorker() {
+        return prepareWhisperDependencies();
+    }));
+    for (const worker of workers) if (worker.status === 'rejected') failures.push(worker.reason);
+    throwIfAborted(options.signal);
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) throw new AggregateError(failures, 'Whisper dependency preparation failed.');
+    const locations = {
+        version: requirement.version,
+        backend: requirement.backend,
+        helperRoot,
+        helperExecutable,
+        helperVersion: requirement.helperVersion ?? packageMetadata.version,
+        decoderRoot,
+        decoderExecutable,
+        variants: preparedVariants.map(function completedWhisperVariant(variant) {
+            return {...variant, executable: helperExecutable};
+        }),
+        models,
+        ...(requirement.modelId ? {modelId: requirement.modelId} : models.length === 1 ? {modelId: models[0].id} : {})
+    };
+    if (!await installedWhisperRuntime({...locations, root}, signal)) {
+        throw new ArcaneError(ERROR_CODES.operationFailed, 'Whisper preparation did not produce the selected helper, decoder, runtime directories, and model files.');
+    }
+    await onEvent({type: 'local-ai.install.prepared', message: 'Whisper runtime, decoder, helper, and selected models are prepared.', data: {id: 'whisper.cpp'}});
+    return locations;
+}
+
+export function bundledWhisperRuntime(runtime, relativeRoot) {
+    function bundledWhisperPath(location) {
+        return path.posix.join(relativeRoot, path.relative(runtime.root, location).split(path.sep).join('/'));
+    }
+    return {
+        ...runtime,
+        root: relativeRoot,
+        helperRoot: bundledWhisperPath(runtime.helperRoot ?? path.dirname(runtime.helperExecutable)),
+        helperExecutable: bundledWhisperPath(runtime.helperExecutable),
+        decoderRoot: bundledWhisperPath(runtime.decoderRoot),
+        decoderExecutable: bundledWhisperPath(runtime.decoderExecutable),
+        variants: runtime.variants.map(function bundledWhisperVariant(variant) {
+            return {...variant, root: bundledWhisperPath(variant.root), libraryDirectory: bundledWhisperPath(variant.libraryDirectory), executable: bundledWhisperPath(variant.executable)};
+        }),
+        models: runtime.models.map(function bundledWhisperModel(model) {
+            return {...model, path: bundledWhisperPath(model.path)};
+        })
+    };
+}

package/src/local-ai/whisper/native/CMakeLists.txt

@@ -0,0 +1,98 @@
+cmake_minimum_required(VERSION 3.26)
+project(ArcaneWhisper LANGUAGES CXX)
+
+set(WHISPER_SOURCE_DIRECTORY "" CACHE PATH "Matching upstream whisper.cpp source directory")
+set(WHISPER_RUNTIME_DIRECTORY "" CACHE PATH "Selected complete upstream runtime directory")
+
+find_path(WHISPER_INCLUDE_DIRECTORY whisper.h
+    PATHS "${WHISPER_SOURCE_DIRECTORY}/include" REQUIRED NO_DEFAULT_PATH)
+find_path(GGML_INCLUDE_DIRECTORY ggml-backend.h
+    PATHS "${WHISPER_SOURCE_DIRECTORY}/ggml/include" REQUIRED NO_DEFAULT_PATH)
+
+function(import_whisper_library name)
+    if(WIN32)
+        find_file(${name}_DLL "${name}.dll"
+            PATHS "${WHISPER_RUNTIME_DIRECTORY}" "${WHISPER_RUNTIME_DIRECTORY}/bin"
+            REQUIRED NO_DEFAULT_PATH)
+        find_library(${name}_IMPORT_LIBRARY NAMES "${name}"
+            PATHS "${WHISPER_RUNTIME_DIRECTORY}" "${WHISPER_RUNTIME_DIRECTORY}/lib"
+            NO_DEFAULT_PATH)
+        if(NOT ${name}_IMPORT_LIBRARY)
+            if(NOT MSVC)
+                message(FATAL_ERROR "This upstream Windows runtime needs MSVC to generate its missing import library.")
+            endif()
+            get_filename_component(compiler_directory "${CMAKE_CXX_COMPILER}" DIRECTORY)
+            find_program(DUMPBIN_EXECUTABLE dumpbin HINTS "${compiler_directory}" REQUIRED)
+            find_program(LIB_EXECUTABLE lib HINTS "${compiler_directory}" REQUIRED)
+            execute_process(COMMAND "${DUMPBIN_EXECUTABLE}" /NOLOGO /EXPORTS "${${name}_DLL}"
+                OUTPUT_VARIABLE export_table ERROR_VARIABLE export_error RESULT_VARIABLE export_result)
+            if(NOT export_result EQUAL 0)
+                message(FATAL_ERROR "${export_table}${export_error}")
+            endif()
+            file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${name}-exports.txt" "${export_table}${export_error}")
+            string(REGEX MATCHALL "[\r\n][ \t]+[0-9]+[ \t]+[0-9A-Fa-f]+[ \t]+[0-9A-Fa-f]+[ \t]+[^ \t\r\n]+" rows "${export_table}")
+            set(definition "LIBRARY ${name}.dll\nEXPORTS\n")
+            foreach(row IN LISTS rows)
+                string(REGEX REPLACE "^[\r\n][ \t]+[0-9]+[ \t]+[0-9A-Fa-f]+[ \t]+[0-9A-Fa-f]+[ \t]+" "" symbol "${row}")
+                string(APPEND definition "${symbol}\n")
+            endforeach()
+            set(definition_path "${CMAKE_CURRENT_BINARY_DIR}/${name}.def")
+            set(${name}_IMPORT_LIBRARY "${CMAKE_CURRENT_BINARY_DIR}/${name}.lib")
+            file(WRITE "${definition_path}" "${definition}")
+            if(CMAKE_SYSTEM_PROCESSOR MATCHES "[Aa][Rr][Mm]64|aarch64" OR CMAKE_GENERATOR_PLATFORM STREQUAL "ARM64")
+                set(import_machine ARM64)
+            elseif(CMAKE_SIZEOF_VOID_P EQUAL 8)
+                set(import_machine X64)
+            else()
+                set(import_machine X86)
+            endif()
+            execute_process(COMMAND "${LIB_EXECUTABLE}" /NOLOGO "/DEF:${definition_path}"
+                "/OUT:${${name}_IMPORT_LIBRARY}" "/MACHINE:${import_machine}"
+                OUTPUT_VARIABLE import_output ERROR_VARIABLE import_error RESULT_VARIABLE import_result)
+            if(NOT import_result EQUAL 0)
+                message(FATAL_ERROR "${import_output}${import_error}")
+            endif()
+        endif()
+        add_library(upstream_${name} SHARED IMPORTED)
+        set_target_properties(upstream_${name} PROPERTIES
+            IMPORTED_LOCATION "${${name}_DLL}"
+            IMPORTED_IMPLIB "${${name}_IMPORT_LIBRARY}")
+    else()
+        find_library(${name}_LIBRARY NAMES "${name}"
+            PATHS "${WHISPER_RUNTIME_DIRECTORY}" "${WHISPER_RUNTIME_DIRECTORY}/lib"
+            REQUIRED NO_DEFAULT_PATH)
+        add_library(upstream_${name} SHARED IMPORTED)
+        set_target_properties(upstream_${name} PROPERTIES IMPORTED_LOCATION "${${name}_LIBRARY}")
+    endif()
+endfunction()
+
+import_whisper_library(whisper)
+import_whisper_library(ggml)
+find_package(Threads REQUIRED)
+
+add_executable(arcane-whisper main.cpp)
+target_compile_features(arcane-whisper PRIVATE cxx_std_17)
+target_compile_definitions(arcane-whisper PRIVATE WHISPER_SHARED GGML_SHARED)
+target_include_directories(arcane-whisper PRIVATE "${WHISPER_INCLUDE_DIRECTORY}" "${GGML_INCLUDE_DIRECTORY}")
+target_link_libraries(arcane-whisper PRIVATE upstream_whisper upstream_ggml Threads::Threads)
+if(MSVC)
+    target_compile_options(arcane-whisper PRIVATE /utf-8 /EHsc)
+endif()
+if(APPLE)
+    set_target_properties(arcane-whisper PROPERTIES INSTALL_RPATH "@loader_path;@loader_path/../lib")
+elseif(UNIX)
+    set_target_properties(arcane-whisper PROPERTIES INSTALL_RPATH "$ORIGIN;$ORIGIN/../lib")
+endif()
+install(TARGETS arcane-whisper RUNTIME DESTINATION bin)
+
+if(WIN32 AND MSVC)
+    # The published Whisper DLLs and this helper share the release MSVC CRT.
+    # Keep its permitted app-local redistributables beside the executable.
+    set(CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION bin)
+    set(CMAKE_INSTALL_DEBUG_LIBRARIES FALSE)
+    set(CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY FALSE)
+    set(CMAKE_INSTALL_UCRT_LIBRARIES FALSE)
+    set(CMAKE_INSTALL_MFC_LIBRARIES FALSE)
+    set(CMAKE_INSTALL_OPENMP_LIBRARIES TRUE)
+    include(InstallRequiredSystemLibraries)
+endif()

package/src/local-ai/whisper/native/NOTICE

@@ -0,0 +1,18 @@
+Arcane Whisper native helper
+Copyright (c) The Wizard Nexus and contributors.
+
+The first-party helper source is licensed under AGPL-3.0-only; see LICENSE.
+Matching source and build instructions are included in source/ and in the
+corresponding Arcane SDK numeric release.
+
+This Windows helper distribution includes unmodified Microsoft Visual C++
+release runtime libraries from the installed Visual Studio 2022 Redistributable
+tree. Those files retain Microsoft's terms. Their published distribution list
+and application-local deployment documentation are available at:
+https://learn.microsoft.com/en-us/visualstudio/releases/2022/redistribution
+https://learn.microsoft.com/en-us/cpp/windows/redistributing-visual-cpp-files
+
+The helper uses the public whisper.cpp and GGML interfaces. Their MIT license
+is included as licenses/whisper-LICENSE. The upstream runtime archives, model
+and FFmpeg decoder are acquired separately through their selected upstream
+distribution routes; they are not included in this helper archive.

package/src/local-ai/whisper/native/README.md

@@ -0,0 +1,104 @@
+# Persistent Whisper helper
+
+This first-party executable links the public C API from the selected upstream
+whisper.cpp runtime. The current integration selects whisper.cpp 1.9.4/b5130.
+The matching upstream headers and complete runtime remain in their installed
+locations; they are not copied into SDK source. CMake builds only this helper.
+
+`buildWhisperHelper` in `../build.mjs` takes the runtime's `directory`, matching
+upstream `sourceDirectory`, and a task-owned `outputRoot`. Optional `cmake`,
+`generator`, `cmakeArgs`, and `env` select an already available host toolchain.
+Its `signal` and `onEvent` use the SDK process owner. The result names the
+helper executable and retains complete configure, build, and installation
+diagnostics. On Windows, when the upstream distribution omits import libraries,
+the selected MSVC `dumpbin` and `lib` generate ordinary import libraries from
+the actual DLL exports. This does not rebuild Whisper, ggml, or CUDA.
+The Windows MSVC installation also uses CMake's
+`InstallRequiredSystemLibraries` module to place the selected release CRT and
+OpenMP redistributables beside the helper in `bin/`. Debug runtimes, MFC, and
+Windows Universal CRT files are excluded; Windows 10/11 supplies the latter.
+An explicit `-DMSVC_REDIST_DIR=...` in `cmakeArgs` can select the permitted
+installed compiler redistributable tree for that build.
+
+Windows uses the selected runtime directory in the child process's `PATH`.
+Linux and macOS use their normal library loader configuration for that runtime.
+The helper source uses standard C++17, with Windows binary standard-stream
+mode as its only host-specific source adaptation. Android needs its native host
+to provide the executable, upstream runtime, decoder, and process integration.
+Availability of this source does not establish execution on another platform.
+
+## Launch and commands
+
+Launch with these arguments:
+
+```text
+arcane-whisper --model-base64 MODEL_PATH --runtime-base64 RUNTIME_PATH --backend gpu --threads 4
+```
+
+Both path arguments are the base64 encoding of the complete UTF-8 path. The
+backend is `gpu` or `cpu`. The optional thread argument selects native inference
+threads; its default is the host's reported hardware concurrency, or one when
+the host does not report it. The parent keeps runtime library resolution and
+the backend directory aligned with the same selected runtime tree.
+
+Each stdin command ends with one LF. The displayed `TAB` means an actual tab:
+
+```text
+transcribe TAB REQUEST_ID TAB PCM_PATH_BASE64 TAB LANGUAGE_BASE64 TAB TRANSLATE
+cancel TAB REQUEST_ID
+shutdown
+```
+
+Request identifiers are parent-generated control identifiers. Paths and
+languages use lossless base64 framing; `TRANSLATE` is `0` or `1`. The language
+is a Whisper language name/code, `auto`, or empty for detection. The PCM file is
+the complete decoded recording in mono 16 kHz f32le format. The decoder owns
+that required representation; the helper adds no trimming, voice-activity
+filter, duration restriction, offset, or audio normalization. The original
+recording remains with the request owner. The native `whisper_full` signed-int
+sample argument is an upstream representational limit; a recording it cannot
+represent produces an explicit error without silently shortening the input.
+
+## Events and ownership
+
+Stdout contains complete JSON records, one per LF, each explicitly flushed.
+Native diagnostics remain complete on stderr.
+
+| `type` | Fields and meaning |
+| --- | --- |
+| `loading` | `model`, `requestedBackend`; the retained context is being initialized. |
+| `ready` | `model`, `requestedBackend`, `observedBackend`, `backendEvidence`; model initialization and state allocation returned successfully. |
+| `accepted` | `requestId`; this request owns the retained context. |
+| `progress` | `requestId`, `progress`; the actual upstream percentage callback, not an elapsed-time prediction. |
+| `segment` | `requestId`, `index`, `text`, `start`, `end`; an actual newly produced native segment, in original callback order. |
+| `complete` | `requestId`, `language`, `duration`, `text`, `segments`; the full native result after the inference worker joined. |
+| `cancelled` | `requestId`; the cancellation was observed and the actual inference worker joined. |
+| `error` | `requestId`, `message`; an actual operation failure. Startup failures use an empty request identifier. `code: "WHISPER_INFERENCE_FAILED"` identifies only a nonzero return from `whisper_full` after cancellation has been excluded. |
+| `stopped` | The command reader joined and the retained context was freed. Process exit remains the parent's lifetime boundary. |
+
+Segment start/end and recording duration are in seconds. Text preserves native
+segment whitespace. Complete text concatenates the native segments in order,
+with no trimming, inserted separators, or rewritten model output. No segment is
+fabricated from tokens or inferred progress. The helper uses upstream greedy
+decoding defaults with independent request context, zero offset, and the full
+decoded duration.
+
+The public C API has no context-backend getter. `observedBackend` therefore
+reports the backend identified by completed native initialization logs, with
+`backendEvidence: "runtime-log"`; it is null if those logs provided no usable
+observation. It does not promise that every operation runs on a GPU. GPU
+failure and CPU runtime selection belong to the parent runtime owner.
+
+One active inference uses the retained context. A separate command reader can
+set its cancellation flag while computation runs. Both the native encoder and
+compute abort callbacks observe that flag. Native work drains before the main
+dispatcher joins the inference worker and emits a terminal event. Upstream may
+finish an already running GPU operation before observing cancellation.
+Callbacks produced before native cancellation finishes remain complete events;
+the parent owns whether a cancelled operation may affect its visible result.
+
+`shutdown` and stdin EOF cancel active inference, join it and the command
+reader, and free the model. Model loading has no public upstream cancellation
+callback, so the parent cancels loading by terminating and joining its exact
+helper process. A different selected model likewise belongs to a new retained
+helper lifetime after the previous owner drains.