@independo/inderun-web 0.5.0-rc.1 → 0.5.0-rc.2

package/dist/core/route-planner.js

@@ -1,3 +1,4 @@
+import { taskProfileFor } from "./task-profiles.js";
 /**
  * {@link RoutePlanner} backed by the Rust route core compiled to WASM. The
  * module specifier is a static literal (not configurable) so bundlers such as
@@ -117,14 +118,12 @@ export function buildSharedPlannerInput(request, snapshots, networkOnline, inter
     };
 }
 /**
- * Projects the request's task onto the requirements the planner can check. A text
- * request carries text input; the speech requirements arrive with the speech request
- * shape (#245).
+ * Projects the request's task onto the requirements the planner can check, through the
+ * kind's task profile. A kind without a profile carries the kind alone, which the planner
+ * matches against declarations and nothing else.
  */
 function plannerTask(request) {
-    return request.task.kind === "text_to_text"
-        ? { kind: request.task.kind, inputs: ["text"] }
-        : { kind: request.task.kind };
+    return taskProfileFor(request.task.kind)?.plannerTask(request) ?? { kind: request.task.kind };
 }
 /**
  * Projects the dynamic capability snapshot for the planner.

package/dist/core/router.d.ts

@@ -2,7 +2,19 @@ import type { TaskRequest } from "@independo/inderun-contracts";
 import type { HostServices } from "./host.js";
 import type { ProviderAdapter } from "./provider.js";
 import type { ProviderRegistry } from "./registry.js";
+import type { BoundVoice } from "./task-profiles.js";
 import { type InteractionMode, type RoutePlanner, type SharedPlannerInput, type SharedPlannerRoutePlan } from "./route-planner.js";
+/**
+ * One provider in the planned chain, with the voice the plan bound it to (speech only).
+ */
+export interface RouteCandidate {
+    provider: ProviderAdapter;
+    /**
+     * The voice this provider must use, chosen by the planner within the request's privacy
+     * policy. Absent when the task has no voice or the provider does not list its voices.
+     */
+    voice?: BoundVoice;
+}
 /**
  * Output structure from the Router containing the chosen provider and a route selection description.
  */
@@ -15,6 +27,10 @@ export interface RouteSelection {
      * Ordered fallback providers to try if the primary provider fails before producing a final result.
      */
     fallbackProviders: ProviderAdapter[];
+    /**
+     * The whole chain in attempt order (`provider` first), each with its bound voice.
+     */
+    candidates: RouteCandidate[];
     /**
      * The shared route plan used to select this provider chain.
      */

package/dist/core/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;;;;;;OAcG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,YAAY,EAC1B,eAAe,GAAE,eAAuB,EACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC;IA0B1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,2BAA2B;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAkBzB"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/core/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOrD,OAAO,EAGL,KAAK,eAAe,EAEpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAE5B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC;;OAEG;IACH,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B;;OAEG;IACH,SAAS,EAAE,sBAAsB,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,OAAO;gBADP,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,YAAqC;IAGxD;;;;;;;;;;;;;;OAcG;IACG,WAAW,CACf,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,YAAY,EAC1B,eAAe,GAAE,eAAuB,EACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,GAChD,OAAO,CAAC,cAAc,CAAC;IA0B1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,2BAA2B;IA6BnC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAkBzB"}

package/dist/core/router.js

@@ -50,16 +50,25 @@ export class Router {
         return this.buildSelectionFromRoutePlan(snapshots, routePlan);
     }
     buildSelectionFromRoutePlan(snapshots, routePlan) {
-        const orderedProviders = routePlan.candidates
-            .map((candidate) => snapshots.find((snapshot) => snapshot.descriptor.id === candidate.providerId))
-            .filter((snapshot) => snapshot !== undefined);
-        const selected = orderedProviders[0];
+        const candidates = routePlan.candidates.flatMap((candidate) => {
+            const snapshot = snapshots.find((s) => s.descriptor.id === candidate.providerId);
+            if (snapshot === undefined)
+                return [];
+            return [
+                {
+                    provider: snapshot.provider,
+                    ...(candidate.voice !== undefined ? { voice: candidate.voice } : {})
+                }
+            ];
+        });
+        const selected = candidates[0];
         if (!selected) {
             throw createInternal("Route plan selected a provider that is no longer registered.");
         }
         return {
             provider: selected.provider,
-            fallbackProviders: orderedProviders.slice(1).map((snapshot) => snapshot.provider),
+            fallbackProviders: candidates.slice(1).map((candidate) => candidate.provider),
+            candidates,
             routePlan,
             explanation: routePlan.explanation.summary
         };

package/dist/core/task-profiles.d.ts

@@ -0,0 +1,54 @@
+import type { SharedRoutePlan, SharedRoutePlannerInput, TaskOutput, TaskRequest } from "@independo/inderun-contracts";
+import { type IndeRunException } from "./errors.js";
+/** How a task's result reaches the application: `inline`, `playback` or `artifact`. */
+export type OutputDelivery = NonNullable<TaskRequest["delivery"]>["mode"];
+/** The provider-neutral voice a route candidate is bound to. */
+export type BoundVoice = NonNullable<SharedRoutePlan["candidates"][number]["voice"]>;
+/**
+ * What the engine needs to know about one task kind (ADR 016). This table is the only
+ * place the engine branches on `task.kind`: which kinds it executes, the projection onto
+ * the planner's task requirements, and the output delivery a result must have. (Per-kind
+ * request requirements are the schema's `if`/`then` branches, checked by the validator.) Everything else — routing, fallback, cancellation, provenance — is task-agnostic,
+ * so a new task adds an entry here rather than a second execution path.
+ *
+ * The Swift (`TaskProfiles.swift`) and Kotlin (`TaskProfiles.kt`) engines keep the same
+ * table; `contracts/fixtures/task-contracts/` holds the planner projection all three must
+ * produce for each request.
+ */
+export interface TaskProfile {
+    /** The `task.kind` this profile describes. */
+    readonly kind: string;
+    /** Projects the request onto the requirements the shared planner can check. */
+    plannerTask(request: TaskRequest): SharedRoutePlannerInput["task"];
+    /** The output delivery the request asks for: `inline` for text, else `delivery.mode`. */
+    delivery(request: TaskRequest): OutputDelivery;
+}
+/**
+ * Adds a task profile. Internal and not exported from the package: a real task needs its
+ * schema kind and payload first (ADR 016). It exists so a test can prove a third task runs
+ * through routing, execution and output normalization without changing the engine.
+ * @internal
+ */
+export declare function registerTaskProfile(profile: TaskProfile): void;
+/** The profile for `kind`, or `undefined` when this engine cannot execute the task. */
+export declare function taskProfileFor(kind: string): TaskProfile | undefined;
+/**
+ * Re-checks, immediately before an attempt, that the voice the plan bound for this
+ * provider still satisfies the request's privacy policy. The planner already chose the
+ * voice inside that policy; repeating the check here keeps privacy enforceable at the
+ * last point before data reaches the provider, independent of how the plan was produced.
+ * A violation fails the attempt before commit, so the run may fall back.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the voice is allowed.
+ */
+export declare function recheckBoundVoice(request: TaskRequest, providerId: string, voice: BoundVoice | undefined): IndeRunException | undefined;
+/**
+ * Checks a provider's output against the delivery the request asked for: inline text for
+ * `inline`, a playback completion for `playback`, a media artifact for `artifact` whose
+ * media type is one the request accepts. A provider never substitutes one for another
+ * (ADR 016 §4), so a mismatch is a provider fault, not a result.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the output matches.
+ */
+export declare function checkOutput(request: TaskRequest, delivery: OutputDelivery, output: TaskOutput | undefined, providerId: string): IndeRunException | undefined;
+//# sourceMappingURL=task-profiles.d.ts.map

package/dist/core/task-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-profiles.d.ts","sourceRoot":"","sources":["../../src/core/task-profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAA4C,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9F,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAErF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACnE,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC;CAChD;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,gBAAgB,GAAG,SAAS,CAQ9B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,GACjB,gBAAgB,GAAG,SAAS,CAc9B"}

package/dist/core/task-profiles.js

@@ -0,0 +1,92 @@
+import { createCapabilityMismatch, createInternal } from "./errors.js";
+const textToText = {
+    kind: "text_to_text",
+    plannerTask: () => ({ kind: "text_to_text", inputs: ["text"] }),
+    delivery: () => "inline"
+};
+const textToSpeech = {
+    kind: "text_to_speech",
+    plannerTask: (request) => {
+        // The schema requires both for this kind; validation runs before projection.
+        const speech = request.speech;
+        const delivery = request.delivery;
+        return {
+            kind: "text_to_speech",
+            inputs: ["text"],
+            delivery: {
+                mode: delivery.mode,
+                ...(delivery.mediaTypes !== undefined ? { mediaTypes: [...delivery.mediaTypes] } : {})
+            },
+            locale: { tag: speech.locale, match: speech.localeMatch ?? "language" },
+            ...(speech.voice !== undefined
+                ? {
+                    voice: {
+                        ...(speech.voice.gender !== undefined ? { gender: speech.voice.gender } : {}),
+                        requirement: speech.voice.requirement ?? "preferred"
+                    }
+                }
+                : {})
+        };
+    },
+    delivery: (request) => request.delivery.mode
+};
+const taskProfiles = new Map([
+    [textToText.kind, textToText],
+    [textToSpeech.kind, textToSpeech]
+]);
+/**
+ * Adds a task profile. Internal and not exported from the package: a real task needs its
+ * schema kind and payload first (ADR 016). It exists so a test can prove a third task runs
+ * through routing, execution and output normalization without changing the engine.
+ * @internal
+ */
+export function registerTaskProfile(profile) {
+    taskProfiles.set(profile.kind, profile);
+}
+/** The profile for `kind`, or `undefined` when this engine cannot execute the task. */
+export function taskProfileFor(kind) {
+    return taskProfiles.get(kind);
+}
+/**
+ * Re-checks, immediately before an attempt, that the voice the plan bound for this
+ * provider still satisfies the request's privacy policy. The planner already chose the
+ * voice inside that policy; repeating the check here keeps privacy enforceable at the
+ * last point before data reaches the provider, independent of how the plan was produced.
+ * A violation fails the attempt before commit, so the run may fall back.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the voice is allowed.
+ */
+export function recheckBoundVoice(request, providerId, voice) {
+    if (voice?.networkRequired !== true || request.constraints?.privacy !== "local_required") {
+        return undefined;
+    }
+    return createCapabilityMismatch(`Provider '${providerId}' was bound to a voice that sends data off the device, which privacy=local_required forbids.`, { providerId, details: { code: "privacy_recheck_failed" } });
+}
+/**
+ * Checks a provider's output against the delivery the request asked for: inline text for
+ * `inline`, a playback completion for `playback`, a media artifact for `artifact` whose
+ * media type is one the request accepts. A provider never substitutes one for another
+ * (ADR 016 §4), so a mismatch is a provider fault, not a result.
+ *
+ * @returns The exception to fail the attempt with, or `undefined` when the output matches.
+ */
+export function checkOutput(request, delivery, output, providerId) {
+    const expected = { inline: "text", playback: "playback", artifact: "artifact" }[delivery];
+    const matches = output?.type === expected &&
+        (expected === "text"
+            ? typeof output.text === "string"
+            : expected === "playback"
+                ? output.playback !== undefined
+                : output.artifact !== undefined && acceptsMediaType(request, output.artifact.mediaType));
+    if (matches)
+        return undefined;
+    return createInternal(`Provider '${providerId}' returned ${output === undefined ? "no output" : `a '${output.type}' output`} for a '${delivery}' request.`, { providerId, details: { code: "output_mismatch" } });
+}
+/** Whether `mediaType` (parameters ignored, case-insensitive) is one the request accepts. */
+function acceptsMediaType(request, mediaType) {
+    const accepted = request.delivery?.mediaTypes;
+    if (accepted === undefined)
+        return true;
+    const base = (type) => type.split(";")[0].trim().toLowerCase();
+    return accepted.some((type) => base(type) === base(mediaType));
+}

package/dist/facade/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/facade/text.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/facade/text.ts"],"names":[],"mappings":"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"}

package/dist/facade/text.js

@@ -72,7 +72,9 @@ export function toTaskRequest(options) {
 export async function generateText(inderun, options) {
     const taskResult = await inderun.run(toTaskRequest(options));
     return {
-        text: taskResult.output.text,
+        // A text run always produces text output; the generated type is optional only because
+        // TaskOutput also describes playback and artifacts (ADR 016).
+        text: taskResult.output.text ?? "",
         finishReason: taskResult.finishReason,
         ...(taskResult.usage !== undefined ? { usage: taskResult.usage } : {}),
         runId: taskResult.runId,
@@ -135,7 +137,7 @@ function settle(outcome) {
     switch (outcome.outcome) {
         case "completed":
             return {
-                text: outcome.finalText ?? "",
+                text: outcome.finalText ?? outcome.output?.text ?? "",
                 ...(outcome.finishReason !== undefined ? { finishReason: outcome.finishReason } : {}),
                 ...(outcome.usage !== undefined ? { usage: outcome.usage } : {}),
                 runId: outcome.runId,
@@ -144,7 +146,7 @@ function settle(outcome) {
             };
         case "cancelled":
             return {
-                text: outcome.partialText ?? "",
+                text: outcome.partialText ?? outcome.output?.text ?? "",
                 finishReason: "cancelled",
                 runId: outcome.runId,
                 ...provenance,

package/dist/index.d.ts

@@ -36,7 +36,7 @@ export { AUTO_MODEL_PROFILE, type ModelProfiles } from "./core/model-profiles.js
  */
 export { IndeRun, type IndeRunOptions, type StreamHandleResult } from "./core/engine.js";
 export type { IndeRunApi } from "./core/generated/inderun-api.js";
-export type { ProviderCapabilitySnapshot, StreamRun } from "./core/provider.js";
+export type { ArtifactChunk, ArtifactLimits, ProviderCapabilitySnapshot, StreamRun } from "./core/provider.js";
 /**
  * The contract types this SDK's own signatures take and return.
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEhF;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,UAAU,EACX,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;GAGG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,aAAa,EACb,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,YAAY,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,YAAY,EACV,aAAa,EACb,cAAc,EACd,0BAA0B,EAC1B,SAAS,EACV,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,UAAU,EACX,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;GAGG;AACH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@independo/inderun-web",
-  "version": "0.5.0-rc.1",
+  "version": "0.5.0-rc.2",
   "description": "On-device AI with automatic cloud fallback for web apps. Runs ONNX Runtime or the Chrome Prompt API in the browser and falls back to an OpenAI-compatible endpoint, with streaming and cancellation behind one API.",
   "license": "MIT",
   "author": {
@@ -72,8 +72,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@independo/inderun-route-core-wasm": "^0.5.0-rc.1",
-    "@independo/inderun-contracts": "^0.5.0-rc.1"
+    "@independo/inderun-contracts": "^0.5.0-rc.2",
+    "@independo/inderun-route-core-wasm": "^0.5.0-rc.2"
   },
   "peerDependencies": {
     "@huggingface/transformers": "^4.0.0"

package/src/core/artifacts.ts

@@ -0,0 +1,280 @@
+import type { ArtifactReadRequest, MediaArtifact } from "@independo/inderun-contracts";
+import { createInternal, createUnavailable } from "./errors.js";
+
+/**
+ * Size limits of an engine's artifact store (ADR 017). Every limit is in bytes.
+ */
+export interface ArtifactLimits {
+  /** Largest single artifact a provider may write. Default 16 MiB. */
+  maxArtifactBytes?: number;
+  /** Most bytes the store holds across all undisposed artifacts. Default 64 MiB. */
+  maxStoreBytes?: number;
+  /** Most bytes one `readArtifact` call returns. Default 1 MiB. */
+  maxReadBytes?: number;
+}
+
+export const DEFAULT_ARTIFACT_LIMITS: Required<ArtifactLimits> = {
+  maxArtifactBytes: 16 * 1024 * 1024,
+  maxStoreBytes: 64 * 1024 * 1024,
+  maxReadBytes: 1024 * 1024
+};
+
+/**
+ * One range of an artifact's bytes, as `IndeRun.readArtifact` returns it.
+ */
+export interface ArtifactChunk {
+  /** The artifact the bytes belong to. */
+  artifactId: string;
+  /** Byte offset of `bytes` within the artifact. */
+  offset: number;
+  /** The bytes of this range; empty when `offset` is the artifact's end. */
+  bytes: Uint8Array;
+  /** Size of the whole artifact in bytes. */
+  totalBytes: number;
+  /** Whether this range reaches the end of the artifact. */
+  done: boolean;
+}
+
+/** What a provider declares when it starts writing an artifact. */
+export interface ArtifactSpec {
+  /** IANA media type of the bytes, e.g. `audio/wav`; parameters ride on it. */
+  mediaType: string;
+  /** Duration of time-based media in milliseconds, where the provider knows it. */
+  durationMs?: number;
+}
+
+/**
+ * Writes one artifact into the engine's store. `finish()` hands it over: it commits the run
+ * to the provider and returns the reference the provider puts in its output. A provider that
+ * fails or stops before `finish()` calls `abort()`; the engine also discards any writer an
+ * attempt left open.
+ */
+export interface ArtifactWriter {
+  /**
+   * Appends bytes. Throws `Unavailable` (`details.code: "artifact_too_large"`) once the
+   * artifact would exceed the engine's per-artifact limit; the attempt has not committed, so
+   * the run may fall back.
+   */
+  write(bytes: Uint8Array): void;
+  /**
+   * Hands the finished artifact to the engine and commits the run. Throws `Unavailable`
+   * (`artifact_store_full`) when the store has no room, and `Unavailable`
+   * (`run_not_active`) when the run was cancelled or has ended -- in both cases before
+   * committing.
+   */
+  finish(): MediaArtifact;
+  /** Discards everything written. Idempotent. */
+  abort(): void;
+}
+
+/** Where a provider creates artifacts: `RunContext.artifacts`. */
+export interface ArtifactSink {
+  create(spec: ArtifactSpec): ArtifactWriter;
+}
+
+interface StoredArtifact {
+  reference: MediaArtifact;
+  bytes: Uint8Array;
+}
+
+/**
+ * The engine-owned, in-memory artifact store (ADR 017): one per `IndeRun` instance. It holds
+ * every finished artifact until the application disposes it; there are no temporary files,
+ * so nothing outlives the process. Reads are ranged and bounded by `maxReadBytes`.
+ */
+export class ArtifactStore {
+  private readonly limits: Required<ArtifactLimits>;
+  private readonly artifacts = new Map<string, StoredArtifact>();
+  private storedBytes = 0;
+
+  constructor(limits: ArtifactLimits = {}) {
+    this.limits = { ...DEFAULT_ARTIFACT_LIMITS, ...limits };
+  }
+
+  /**
+   * Opens the artifacts of one attempt. `commit` is the attempt's commit hook; a writer's
+   * `finish()` calls it, and refuses the handoff when it returns `false`.
+   */
+  attempt(commit: () => boolean): AttemptArtifacts {
+    return new AttemptArtifacts(this, commit);
+  }
+
+  /** Reads one range. See `IndeRunApi.readArtifact` for the contract. */
+  read(request: ArtifactReadRequest): ArtifactChunk {
+    const stored = this.artifacts.get(request.artifactId);
+    if (stored === undefined) {
+      throw createUnavailable(`Artifact '${request.artifactId}' is not held by this engine.`, {
+        retryable: false,
+        details: { code: "artifact_not_found" }
+      });
+    }
+    const totalBytes = stored.bytes.byteLength;
+    const offset = request.offset ?? 0;
+    if (offset > totalBytes) {
+      const validationIssues = [
+        {
+          path: "/offset",
+          message: `offset ${offset} is beyond the artifact's ${totalBytes} bytes`
+        }
+      ];
+      throw createInternal(
+        `Validation failed for ArtifactReadRequest: /offset - ${validationIssues[0]!.message}`,
+        { details: { validationIssues } }
+      );
+    }
+    const length = Math.min(request.maxBytes ?? this.limits.maxReadBytes, this.limits.maxReadBytes);
+    const end = Math.min(offset + length, totalBytes);
+    return {
+      artifactId: request.artifactId,
+      offset,
+      // A copy: the caller may keep or mutate it without touching the stored bytes.
+      bytes: stored.bytes.slice(offset, end),
+      totalBytes,
+      done: end === totalBytes
+    };
+  }
+
+  /** Releases an artifact's bytes. Idempotent; unknown ids are ignored. */
+  dispose(artifactId: string): void {
+    const stored = this.artifacts.get(artifactId);
+    if (stored === undefined) return;
+    this.artifacts.delete(artifactId);
+    this.storedBytes -= stored.bytes.byteLength;
+  }
+
+  /** The stored reference for `artifactId`, or `undefined` once it was disposed. */
+  reference(artifactId: string): MediaArtifact | undefined {
+    return this.artifacts.get(artifactId)?.reference;
+  }
+
+  /** @internal Registers a finished artifact. */
+  store(spec: ArtifactSpec, bytes: Uint8Array): MediaArtifact {
+    if (this.storedBytes + bytes.byteLength > this.limits.maxStoreBytes) {
+      throw createUnavailable(
+        "The engine's artifact store is full; dispose artifacts to free it.",
+        {
+          details: { code: "artifact_store_full" }
+        }
+      );
+    }
+    const reference: MediaArtifact = {
+      id: `art_${randomId()}`,
+      mediaType: spec.mediaType,
+      owner: "engine",
+      lifetime: "until_disposed",
+      byteLength: bytes.byteLength,
+      ...(spec.durationMs !== undefined ? { durationMs: spec.durationMs } : {})
+    };
+    this.artifacts.set(reference.id, { reference, bytes });
+    this.storedBytes += bytes.byteLength;
+    return reference;
+  }
+
+  /** @internal The whole artifact, for writing it to an application destination. */
+  bytes(artifactId: string): Uint8Array | undefined {
+    return this.artifacts.get(artifactId)?.bytes;
+  }
+
+  /** @internal */
+  get maxArtifactBytes(): number {
+    return this.limits.maxArtifactBytes;
+  }
+}
+
+/**
+ * The artifacts one attempt created. The engine keeps the one the attempt returned and
+ * releases the rest: everything from an attempt that failed, was cancelled or lost to
+ * fallback, and anything a winning attempt finished but did not return. A returned artifact
+ * is never released behind the application's back.
+ */
+export class AttemptArtifacts implements ArtifactSink {
+  private readonly finished = new Set<string>();
+  private readonly open = new Set<ArtifactWriter>();
+  private released = false;
+
+  constructor(
+    private readonly store: ArtifactStore,
+    private readonly commit: () => boolean
+  ) {}
+
+  create(spec: ArtifactSpec): ArtifactWriter {
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    let closed = false;
+    const writer: ArtifactWriter = {
+      write: (bytes) => {
+        if (closed) throw createInternal("The artifact writer is already closed.");
+        if (size + bytes.byteLength > this.store.maxArtifactBytes) {
+          writer.abort();
+          throw createUnavailable(
+            `The artifact exceeds the engine's ${this.store.maxArtifactBytes}-byte limit.`,
+            { details: { code: "artifact_too_large" } }
+          );
+        }
+        chunks.push(bytes.slice());
+        size += bytes.byteLength;
+      },
+      finish: () => {
+        if (closed) throw createInternal("The artifact writer is already closed.");
+        const bytes = concat(chunks, size);
+        writer.abort();
+        // A provider that keeps working after its attempt ended (a late callback, say) must
+        // not leave an artifact behind that nobody owns.
+        if (this.released) {
+          throw createUnavailable("The attempt has ended; the artifact was discarded.", {
+            details: { code: "run_not_active" }
+          });
+        }
+        // Stored before the commit so a full store fails the attempt pre-commit; dropped
+        // again when the run refuses the commit.
+        const reference = this.store.store(spec, bytes);
+        if (!this.commit()) {
+          this.store.dispose(reference.id);
+          throw createUnavailable("The run is no longer active; the artifact was discarded.", {
+            details: { code: "run_not_active" }
+          });
+        }
+        this.finished.add(reference.id);
+        return reference;
+      },
+      abort: () => {
+        closed = true;
+        chunks.length = 0;
+        this.open.delete(writer);
+      }
+    };
+    this.open.add(writer);
+    return writer;
+  }
+
+  /** Whether `artifactId` was finished by this attempt and is still held. */
+  owns(artifactId: string): boolean {
+    return this.finished.has(artifactId) && this.store.reference(artifactId) !== undefined;
+  }
+
+  /** Releases every artifact of this attempt except `keep`, and closes open writers. */
+  release(keep?: string): void {
+    this.released = true;
+    for (const writer of [...this.open]) writer.abort();
+    for (const id of this.finished) {
+      if (id !== keep) this.store.dispose(id);
+    }
+    this.finished.clear();
+  }
+}
+
+function concat(chunks: Uint8Array[], size: number): Uint8Array {
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+function randomId(): string {
+  const random = new Uint8Array(12);
+  globalThis.crypto.getRandomValues(random);
+  return Array.from(random, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}