modelpact 2.0.2

package/dist/types/backend.js

@@ -0,0 +1,11 @@
+/**
+ * What a backend supplies; `../lifecycle` turns it into an `AiProvider`.
+ *
+ * The contract's runtime guarantees — one generation at a time, an abort that
+ * leaves the session open, a close that refuses everything after it, an
+ * overflow that fires once — are implemented once, in `../lifecycle/01_access.ts`
+ * through `05_close.ts`. A backend never sees them: it says what the model is
+ * and how to talk to it, and the order of calls is the lifecycle's business.
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/types/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/types/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types/failures.d.ts

@@ -0,0 +1,115 @@
+import type { Modality } from "./messages.js";
+import type { ContextUsage } from "./usage.js";
+/**
+ * The contract's failure vocabulary: any refusal from any provider — browser,
+ * Ollama, mock — is one of these kinds.
+ *
+ * The set is cut by the caller's next move, not by exception name: kinds merge
+ * where the reaction would be the same and split where it differs, even when
+ * the spec throws one exception for both (`unsupported-config` vs
+ * `unsupported-input`). The mechanical name-to-kind mapping lives in
+ * `failureFromError`; the kinds with no spec exception behind them (`unsupported`,
+ * `busy`, `unknown`) say so in their own docs below.
+ *
+ * Each failure carries exactly the data its kind implies. `cause` is factored
+ * into an intersection to avoid repeating it; narrowing on `kind` still works
+ * through that, which `src/types.test-d.ts` checks.
+ */
+export type AiFailure = {
+    readonly cause?: unknown;
+} & (
+/** No such API in this runtime. */
+{
+    readonly kind: "unsupported";
+}
+/** Blocked by the `language-model` Permissions-Policy (`NotAllowedError`). */
+ | {
+    readonly kind: "not-allowed";
+}
+/**
+ * The environment has a model, but not for this request. Both lists name the
+ * parts that did not fit; empty or absent means the provider did not narrow
+ * it down.
+ */
+ | {
+    readonly kind: "unsupported-config";
+    readonly languages: readonly string[];
+    readonly modalities?: readonly Modality[];
+}
+/**
+ * The message the caller built is not accepted. Kept apart from
+ * `unsupported-config` because it is a bug in the caller, not the
+ * environment — the spec throws one `NotSupportedError` for both.
+ */
+ | {
+    readonly kind: "unsupported-input";
+    readonly detail: string;
+}
+/**
+ * `QuotaExceededError`: usage passed the window. Retrying without trimming
+ * history will fail again, hence the measurement travels along.
+ */
+ | {
+    readonly kind: "context-overflow";
+    readonly usage: ContextUsage;
+}
+/** Explicit abort, or a call on a closed session — the spec throws `AbortError` for both. */
+ | {
+    readonly kind: "aborted";
+    readonly reason: string;
+}
+/** Malformed request: empty message list, misplaced system turn, conflicting options. */
+ | {
+    readonly kind: "invalid-input";
+    readonly detail: string;
+}
+/** Document not fully active. */
+ | {
+    readonly kind: "invalid-state";
+    readonly detail: string;
+}
+/**
+ * A generation is already running on this session; `detail` names the call
+ * holding it. Its own kind rather than a shade of `invalid-state`: the spec
+ * spends that one on a single condition (the document is not fully active),
+ * and the caller's move differs — wait, or open a second session.
+ *
+ * Not a spec exception: the spec says nothing about two `prompt()` calls at
+ * once, and points at `clone()` for work meant to run in parallel. A
+ * provider here has to serialize instead.
+ */
+ | {
+    readonly kind: "busy";
+    readonly detail: string;
+}
+/** The browser's own catch-all (`OperationError`). */
+ | {
+    readonly kind: "failed";
+    readonly detail: string;
+} | {
+    readonly kind: "unknown";
+});
+/** Every kind in the vocabulary, under a name; derived, and a type rather than an enum — see `AccessKind` in `./session.ts`. */
+export type FailureKind = AiFailure["kind"];
+/**
+ * Where thrown exceptions enter the vocabulary: whatever a provider caught
+ * becomes an `AiFailure`, mapped by DOMException name. This is the generic
+ * half of the mapping — a provider that knows the call site refines what a
+ * name alone cannot say (see the `NotSupportedError` and
+ * `QuotaExceededError` branches).
+ *
+ * Matches on `error.name` rather than `instanceof DOMException`, because the
+ * spec throws a plain `TypeError` that the latter would miss. The trade-off is
+ * that a genuine `TypeError` from a bug in the adapter also lands in
+ * `invalid-input`.
+ */
+export declare function failureFromError(error: unknown): AiFailure;
+/**
+ * For the boundaries where throwing is unavoidable — React error boundaries,
+ * tests. Inside the adapter, failures travel as values.
+ */
+export declare class AiError extends Error {
+    readonly failure: AiFailure;
+    constructor(failure: AiFailure);
+}
+//# sourceMappingURL=failures.d.ts.map

package/dist/types/failures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.d.ts","sourceRoot":"","sources":["../../src/types/failures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG;AACrD,mCAAmC;AACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAClC,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAClC;;;;GAIG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC3C;AACH;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACjE;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE;AACrE,6FAA6F;GAC3F;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvD,yFAAyF;GACvF;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC7D,iCAAiC;GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC7D;;;;;;;;;GASG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACpD,sDAAsD;GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAC/B,CAAC;AAEF,gIAAgI;AAChI,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CA0C1D;AAED;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS;gBAAlB,OAAO,EAAE,SAAS;CAMxC"}

package/dist/types/failures.js

@@ -0,0 +1,68 @@
+/**
+ * Where thrown exceptions enter the vocabulary: whatever a provider caught
+ * becomes an `AiFailure`, mapped by DOMException name. This is the generic
+ * half of the mapping — a provider that knows the call site refines what a
+ * name alone cannot say (see the `NotSupportedError` and
+ * `QuotaExceededError` branches).
+ *
+ * Matches on `error.name` rather than `instanceof DOMException`, because the
+ * spec throws a plain `TypeError` that the latter would miss. The trade-off is
+ * that a genuine `TypeError` from a bug in the adapter also lands in
+ * `invalid-input`.
+ */
+export function failureFromError(error) {
+    const errorName = error instanceof Error ? error.name : "";
+    const detail = error instanceof Error ? error.message : String(error);
+    const isDomException = typeof DOMException !== "undefined" && error instanceof DOMException;
+    switch (errorName) {
+        case "AbortError":
+            return { kind: "aborted", reason: detail, cause: error };
+        case "InvalidStateError":
+            return { kind: "invalid-state", detail, cause: error };
+        case "NotAllowedError":
+            return { kind: "not-allowed", cause: error };
+        case "NotSupportedError":
+            // The name covers both "wrong environment" and "wrong message" and
+            // cannot tell them apart; a provider that knows the call site must build
+            // `unsupported-input` itself. Empty list means "not narrowed down".
+            return { kind: "unsupported-config", languages: [], cause: error };
+        case "OperationError":
+            return { kind: "failed", detail, cause: error };
+        case "QuotaExceededError":
+            // The exception carries no measurement; a provider holding the session
+            // can refine this.
+            return {
+                kind: "context-overflow",
+                usage: { kind: "unknown" },
+                cause: error,
+            };
+        case "SyntaxError":
+            // The spec's SyntaxError is a DOMException; JSON.parse on a truncated
+            // frame throws a native one under the same name. Only the former means
+            // "the caller sent nonsense". A provider should still convert its own
+            // parse errors where they happen rather than let them reach here.
+            return isDomException
+                ? { kind: "invalid-input", detail, cause: error }
+                : { kind: "failed", detail, cause: error };
+        case "TypeError":
+            // No such split available: the spec throws a native TypeError too.
+            return { kind: "invalid-input", detail, cause: error };
+        default:
+            return { kind: "unknown", cause: error };
+    }
+}
+/**
+ * For the boundaries where throwing is unavoidable — React error boundaries,
+ * tests. Inside the adapter, failures travel as values.
+ */
+export class AiError extends Error {
+    failure;
+    constructor(failure) {
+        // Only the kind: the details are in `failure`, and restating them as a
+        // string would create a second version of the truth.
+        super(failure.kind, { cause: failure.cause });
+        this.failure = failure;
+        this.name = "AiError";
+    }
+}
+//# sourceMappingURL=failures.js.map

package/dist/types/failures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failures.js","sourceRoot":"","sources":["../../src/types/failures.ts"],"names":[],"mappings":"AAwEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtE,MAAM,cAAc,GAClB,OAAO,YAAY,KAAK,WAAW,IAAI,KAAK,YAAY,YAAY,CAAC;IAEvE,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC3D,KAAK,mBAAmB;YACtB,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACzD,KAAK,iBAAiB;YACpB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC/C,KAAK,mBAAmB;YACtB,mEAAmE;YACnE,yEAAyE;YACzE,oEAAoE;YACpE,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACrE,KAAK,gBAAgB;YACnB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClD,KAAK,oBAAoB;YACvB,uEAAuE;YACvE,mBAAmB;YACnB,OAAO;gBACL,IAAI,EAAE,kBAAkB;gBACxB,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;gBAC1B,KAAK,EAAE,KAAK;aACb,CAAC;QACJ,KAAK,aAAa;YAChB,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,kEAAkE;YAClE,OAAO,cAAc;gBACnB,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE;gBACjD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC/C,KAAK,WAAW;YACd,mEAAmE;YACnE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QACzD;YACE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,OAAQ,SAAQ,KAAK;IACX;IAArB,YAAqB,OAAkB;QACrC,uEAAuE;QACvE,qDAAqD;QACrD,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAH3B,YAAO,GAAP,OAAO,CAAW;QAIrC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;IACxB,CAAC;CACF"}

package/dist/types/foundations.d.ts

@@ -0,0 +1,35 @@
+declare const brand: unique symbol;
+type Brand<T, Name extends string> = T & {
+    readonly [brand]: Name;
+};
+/** Non-negative integer count of context tokens. */
+export type Tokens = Brand<number, "Tokens">;
+export declare function tokens(value: number): Tokens | null;
+/**
+ * 0..1, for download progress. A brand of its own, not `Tokens`: a ratio and a
+ * percentage (0.5 against 50) are both numbers, and swapping them is silent.
+ */
+export type Fraction = Brand<number, "Fraction">;
+export declare function fraction(value: number): Fraction | null;
+/** A plain object: not an array, `Date` or function. */
+export type JsonSchema = Brand<Record<string, unknown>, "JsonSchema">;
+export declare function jsonSchema(value: unknown): JsonSchema | null;
+/**
+ * Success or failure as one value.
+ *
+ * The failure path is visible in the signature and cannot be skipped: until
+ * `ok` is checked, `value` is not in the type. The cost is that `Result`
+ * spreads, so keep it at the adapter boundary — inside a provider's
+ * implementation, exceptions are fine.
+ */
+export type Result<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+export declare const ok: <T>(value: T) => Result<T, never>;
+export declare const err: <E>(error: E) => Result<never, E>;
+export {};
+//# sourceMappingURL=foundations.d.ts.map

package/dist/types/foundations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundations.d.ts","sourceRoot":"","sources":["../../src/types/foundations.ts"],"names":[],"mappings":"AAGA,OAAO,CAAC,MAAM,KAAK,EAAE,OAAO,MAAM,CAAC;AACnC,KAAK,KAAK,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpE,oDAAoD;AACpD,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAI7C,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInD;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEjD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEvD;AAED,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC;AAKtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAU5D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAI9C,eAAO,MAAM,EAAE,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAA0B,CAAC;AAC3E,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAA2B,CAAC"}

package/dist/types/foundations.js

@@ -0,0 +1,30 @@
+// Returns null rather than throwing: the input comes from someone else's API,
+// and the provider has to decide what to do with junk.
+export function tokens(value) {
+    // The condition to its left is what makes this `as` honest, and the same
+    // holds for every other cast in this file.
+    return Number.isInteger(value) && value >= 0 ? value : null;
+}
+export function fraction(value) {
+    return value >= 0 && value <= 1 ? value : null;
+}
+// Narrower than `object`, which in TypeScript covers arrays, `Date` and
+// functions — all of which reach `responseConstraint` and fail deep inside the
+// browser. `unknown` in: a schema almost always arrives from JSON.parse.
+export function jsonSchema(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    // The prototype, not `Array.isArray`: `Date`, `Map` and `RegExp` are objects
+    // that pass every shape check and only fail once the browser tries to read
+    // them as a schema. What JSON.parse builds carries `Object.prototype`, and
+    // `Object.create(null)` carries none.
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null
+        ? value
+        : null;
+}
+// `never` for the other side means "cannot happen here", which lets the value
+// slot into any Result<T, E> without naming E at the call site.
+export const ok = (value) => ({ ok: true, value });
+export const err = (error) => ({ ok: false, error });
+//# sourceMappingURL=foundations.js.map

package/dist/types/foundations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundations.js","sourceRoot":"","sources":["../../src/types/foundations.ts"],"names":[],"mappings":"AASA,8EAA8E;AAC9E,uDAAuD;AACvD,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,yEAAyE;IACzE,2CAA2C;IAC3C,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,KAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAQD,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC;AAKD,wEAAwE;AACxE,+EAA+E;AAC/E,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,sCAAsC;IACtC,MAAM,SAAS,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI;QACzD,CAAC,CAAE,KAAoB;QACvB,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAcD,8EAA8E;AAC9E,gEAAgE;AAChE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAI,KAAQ,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,GAAG,GAAG,CAAI,KAAQ,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC"}

package/dist/types/messages.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `system` is missing on purpose. The spec accepts a system instruction only
+ * as the very first message and throws `TypeError` otherwise; here the system
+ * text is a session option instead, so a misplaced one cannot be written.
+ */
+export type AiRole = "user" | "assistant";
+export interface AiMessage {
+    readonly role: AiRole;
+    readonly content: string;
+}
+/** Text only for now; the other two gate model selection, not message content. */
+export type Modality = "text" | "image" | "audio";
+export interface ModalityExpectation {
+    readonly type: Modality;
+    /** BCP-47 tags. */
+    readonly languages?: readonly string[];
+}
+/**
+ * What the caller needs from the model. Availability depends on the request,
+ * not only on the environment — an image input or an unsupported language can
+ * make an otherwise present model unavailable — so it is asked for up front.
+ *
+ * Tools are absent because the contract has no tool support; when they arrive
+ * they belong here too, since they take part in choosing the model.
+ */
+export interface ModelRequest {
+    readonly inputs?: readonly ModalityExpectation[];
+    readonly outputs?: readonly ModalityExpectation[];
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/types/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/types/messages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,mBAAmB;IACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACnD"}

package/dist/types/messages.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=messages.js.map

package/dist/types/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/types/messages.ts"],"names":[],"mappings":""}

package/dist/types/provider.d.ts

@@ -0,0 +1,22 @@
+import type { ModelRequest } from "./messages.js";
+import type { ModelAccess } from "./session.js";
+/**
+ * Free-form, because a backend written outside this package names itself and
+ * the package cannot know that name in advance.
+ *
+ * The exhaustive switch a persisted choice needs did not disappear, it moved:
+ * an app's registry is the only place the full set is known, and
+ * `src/providers/registry.ts` derives the union from it. `src/types.test-d.ts`
+ * holds one — add a member without a branch and the build breaks.
+ */
+export type ProviderName = string;
+export interface AiProvider {
+    readonly name: ProviderName;
+    /**
+     * The single entry point; everything else hangs off the returned access.
+     * The request travels with it because it decides the answer: asking whether
+     * a model is available without saying what for is meaningless.
+     */
+    readonly access: (request?: ModelRequest) => Promise<ModelAccess>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/types/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/types/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CACnE"}

package/dist/types/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/types/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/types/provider.ts"],"names":[],"mappings":""}

package/dist/types/session.d.ts

@@ -0,0 +1,156 @@
+import type { JsonSchema, Result } from "./foundations.js";
+import type { AiMessage } from "./messages.js";
+import type { ContextUsage } from "./usage.js";
+import type { AiFailure } from "./failures.js";
+/**
+ * Per-session options. Modalities and tools are deliberately not here: they
+ * belong to `ModelRequest`, because they decide which model gets loaded rather
+ * than how one session behaves.
+ */
+export interface SessionOptions {
+    /** A field rather than a leading history entry, which is what makes a misplaced system turn unwritable. */
+    readonly system?: string;
+    readonly history?: readonly AiMessage[];
+    /** Aborts the create, including a model download in progress. */
+    readonly signal?: AbortSignal;
+}
+export interface GenerateOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * `responseConstraint`: it constrains decoding, so the model cannot emit
+     * another shape.
+     *
+     * Honoured or refused, never ignored. A provider that cannot constrain
+     * decoding fails the call; answering anyway would hand back prose where the
+     * caller is about to run `JSON.parse`, and nothing in the Result says the
+     * constraint was dropped.
+     */
+    readonly schema?: JsonSchema;
+}
+/**
+ * One generation at a time: while a `prompt` or a `promptStream` is running,
+ * both calls fail with `busy`. A session is one transcript, and interleaving
+ * two turns into it produces a history no caller can repair; the refusal
+ * itself is `src/helpers/lifetime.ts`. Like the guarantee on `close`, this one is
+ * runtime: a type cannot say "not while that promise is pending".
+ *
+ * Callbacks are fields, not methods: `strictFunctionTypes` checks argument
+ * types strictly only on function-typed properties, while method syntax stays
+ * bivariant and would let an implementation narrow an argument.
+ */
+export interface AiSession extends EventTarget {
+    /**
+     * The transcript has outgrown the window, and the oldest turns are being
+     * dropped to fit the newest — silently, wherever the backend does it. Fires
+     * once: the window does not un-overflow, and every turn after the first is
+     * over the same line.
+     *
+     * An `onevent` property rather than a typed `addEventListener`, for the
+     * reason spelled out on `DownloadMonitor`. The event carries nothing: what a
+     * listener wants next is `usage()`, which is current by the time this fires.
+     */
+    oncontextoverflow: ((event: Event) => void) | null;
+    readonly prompt: (input: string, options?: GenerateOptions) => Promise<Result<string, AiFailure>>;
+    /**
+     * A `ReadableStream`, not a bare async iterable, so the caller keeps `tee()`,
+     * `pipeThrough()` and `cancel()`.
+     *
+     * Consume it with a reader loop: async iteration of a stream is missing in
+     * Safari, and `dom.asynciterable` is deliberately left out of `lib` so the
+     * compiler rejects `for await` here. It also hides a trap — leaving such a
+     * loop with `break` cancels generation unless you iterate
+     * `stream.values({ preventCancel: true })`.
+     *
+     * Only a failure to start lands in Result; a break after the first chunk
+     * surfaces as a stream error, and that error is an `AiError` — a reader has
+     * nowhere to put a Result, so this is the one place a failure is thrown.
+     */
+    readonly promptStream: (input: string, options?: GenerateOptions) => Promise<Result<ReadableStream<string>, AiFailure>>;
+    readonly usage: () => ContextUsage;
+    /**
+     * The conversation so far: what was handed at open, then every completed
+     * turn. An aborted or cancelled turn adds nothing, and nothing is ever
+     * dropped — `src/helpers/transcript.ts` holds both rules.
+     *
+     * It lives as long as the session does, which is one tab. Storing it is the
+     * app's, and handing it back to `open` continues the conversation where it
+     * was — that round trip is how a reload is survived, not this array. Each
+     * call is a snapshot: later turns do not write into one already handed out.
+     */
+    readonly history: () => readonly AiMessage[];
+    /**
+     * In-flight and later calls fail with `aborted`, matching `destroy()`.
+     *
+     * Types cannot carry that guarantee — a value cannot be spent in TypeScript,
+     * so the old reference stays valid. Stating it as a runtime guarantee is
+     * honest; pretending the types hold it would not be.
+     */
+    readonly close: () => void;
+}
+type OpenSession = (options?: SessionOptions) => Promise<Result<AiSession, AiFailure>>;
+/**
+ * The download monitor, shaped after the spec's `CreateMonitor`: an
+ * `EventTarget` firing `downloadprogress` with a `ProgressEvent`. The browser's
+ * own monitor satisfies this too, so a Prompt API provider can hand its one
+ * through — `src/types.test-d.ts` checks that against the ambient declaration.
+ * `src/helpers/monitor.ts` is the implementation for a provider with no browser
+ * behind it.
+ *
+ * `ondownloadprogress` is the whole surface because it is the only typed way
+ * in. An `addEventListener` overload narrowed to `downloadprogress` does not
+ * survive extending `EventTarget`: the inherited listener parameter is
+ * `EventListener`, a listener taking a `ProgressEvent` is not one, and neither
+ * this interface's implementations nor the ambient `CreateMonitor` then satisfy
+ * it (TS2420 and TS2322, measured). A caller wanting several listeners uses
+ * `addEventListener` and casts the event.
+ *
+ * What a provider owes a listener: `loaded` is 0..1, never decreasing, and
+ * `total` is 1 — see `DownloadProgressEvent` for where that normalization
+ * comes from, and `Fraction` for what carries it.
+ */
+export interface DownloadMonitor extends EventTarget {
+    ondownloadprogress: ((event: ProgressEvent) => void) | null;
+}
+/**
+ * Availability and session creation are one value, not two calls. `open`
+ * exists only on the variants where opening can work, so "create a session
+ * from an unavailable model" is not a mistake to guard against — it is
+ * unwritable.
+ */
+export type ModelAccess = {
+    readonly kind: "unavailable";
+    readonly reason: AiFailure;
+} | {
+    readonly kind: "ready";
+    readonly open: OpenSession;
+} | {
+    readonly kind: "needs-download";
+    /** True when another caller already started the fetch (`downloading` in the spec). */
+    readonly started: boolean;
+    /**
+     * The monitor is the first argument and required: this is the one branch
+     * where weights are certainly being fetched, and a silent download of
+     * hundreds of megabytes reads as a frozen UI.
+     *
+     * A callback handed the monitor, not a monitor handed back, and it runs
+     * before `open` awaits anything — subscribing after the promise settles
+     * is subscribing after the download. The spec's `monitor` option works
+     * the same way and for the same reason.
+     */
+    readonly open: (monitor: (monitor: DownloadMonitor) => void, options?: SessionOptions) => Promise<Result<AiSession, AiFailure>>;
+};
+/**
+ * The three answers, under a name — for a `Record` keyed by them, or a
+ * signature that takes the answer without the payload. Derived, so a fourth
+ * variant extends it rather than being forgotten here.
+ *
+ * A type and not an enum, which is the point: `"ready"` still passes wherever
+ * one of these is asked for, so a caller keeps writing literals and importing
+ * nothing, and none of it reaches their bundle. An enum would be a value, and
+ * a nominal one — a caller's own `"ready"` would stop being assignable.
+ * `FailureKind` and `UsageKind` are the same for the other two unions worth
+ * switching on.
+ */
+export type AccessKind = ModelAccess["kind"];
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/types/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,2GAA2G;IAC3G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C;;;;;;;;;OASG;IACH,iBAAiB,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,KACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACxC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,YAAY,EAAE,CACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,KACtB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,YAAY,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,SAAS,SAAS,EAAE,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,KAAK,WAAW,GAAG,CACjB,OAAO,CAAC,EAAE,cAAc,KACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,kBAAkB,EAAE,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAGnB;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACtD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,cAAc,KACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEN;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}

package/dist/types/session.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.js.map

package/dist/types/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":""}

package/dist/types/usage.d.ts

@@ -0,0 +1,25 @@
+import { type Tokens } from "./foundations.js";
+/**
+ * Context accounting in tokens.
+ *
+ * `unbounded` is a separate variant because the Prompt API reports `Infinity`
+ * there; as a plain number it would flow into `total - used` and produce a
+ * `remaining` that looks meaningful. `unknown` covers providers that expose no
+ * budget at all, which is cheaper than a `null` case at every call site.
+ */
+export type ContextUsage = {
+    readonly kind: "unknown";
+} | {
+    readonly kind: "unbounded";
+    readonly used: Tokens;
+} | {
+    readonly kind: "bounded";
+    readonly used: Tokens;
+    readonly total: Tokens;
+    readonly remaining: Tokens;
+};
+/** Which of the three a measurement is, under a name; as `AccessKind` in `./session.ts`. */
+export type UsageKind = ContextUsage["kind"];
+/** The checked way to build one: no fractional total, no negative `remaining`. */
+export declare function contextUsage(used: Tokens, total: number): ContextUsage;
+//# sourceMappingURL=usage.d.ts.map

package/dist/types/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/types/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN,4FAA4F;AAC5F,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAE7C,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAUtE"}

package/dist/types/usage.js

@@ -0,0 +1,16 @@
+import { tokens } from "./foundations.js";
+/** The checked way to build one: no fractional total, no negative `remaining`. */
+export function contextUsage(used, total) {
+    if (total === Infinity)
+        return { kind: "unbounded", used };
+    // Usage is allowed to pass the window — that is what fires `contextoverflow`
+    // — but "minus three tokens left" is not a value worth carrying.
+    const remaining = tokens(Math.max(0, total - used));
+    const totalTokens = tokens(total);
+    // A fractional or negative total means the API returned something
+    // unexpected; saying "unknown" beats inventing a number.
+    if (totalTokens === null || remaining === null)
+        return { kind: "unknown" };
+    return { kind: "bounded", used, total: totalTokens, remaining };
+}
+//# sourceMappingURL=usage.js.map

package/dist/types/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/types/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAe,MAAM,kBAAkB,CAAC;AAuBvD,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACtD,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3D,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,kEAAkE;IAClE,yDAAyD;IACzD,IAAI,WAAW,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAClE,CAAC"}