@atomic-chat/core 0.5.1 → 0.13.2

package/dist/contracts/decision.d.ts

@@ -0,0 +1,394 @@
+/**
+ * The decision model: a small model that answers typed questions with probabilities in one forward
+ * pass. It runs as its own core module, outside the sessions registry
+ * (ADR 2026-09-30-the-decision-model-is-its-own-core-module), on one of two engines
+ * (ADR 2026-10-06-run-decision-models-on-upstream-llamacpp):
+ *  - `turboquant`: `llama-server --decision` of the TurboQuant fork (release 1.7.0 on), which also
+ *    serves the router (`/v1/router/score`) and converts laya checkpoint folders;
+ *  - `upstream`: ggml-org llama.cpp (b11370 on), which serves `/v1/systemone` for a GGUF stamped with
+ *    `<arch>.decision.type` (laya, openjev, lev, kev, nimble, clef). No router.
+ *
+ * Two halves live here:
+ *  - the engine's wire contract (`DECISION.md` in atomic-llama-cpp-turboquant, API version 1, which
+ *    upstream's `/v1/systemone` shares for requests), mirrored as types only. Fields the engine may
+ *    add later are tolerated: every object keeps an index signature, and nothing in the core rejects
+ *    an unknown key;
+ *  - the core's own surface: the settings section, the status, the fail-open outcome and the events.
+ *
+ * Browser-safe: types and constants only. snake_case throughout, like the engine and `settings.json`.
+ */
+/** `/props.decision.api_version` this core speaks. Anything else is treated as an unsupported engine. */
+export declare const DECISION_API_VERSION = 1;
+/**
+ * Which decision API an engine speaks, decided by the model file: a laya checkpoint folder or a GGUF
+ * the fork converted (`decision.layout`, architecture `laya`) is `turboquant`; a GGUF with
+ * `<arch>.decision.type` is `upstream`.
+ */
+export type DecisionDialect = 'turboquant' | 'upstream';
+export type DecisionQuestionType = 'noul' | 'choice' | 'score';
+export interface DecisionQuestion {
+    type: DecisionQuestionType;
+    /** Any JSON value for the laya layout; a non-string is rendered as compact JSON by the engine. */
+    instructions: unknown;
+    /** `choice`: `{label: description|null}` or `[label, …]`; `score`: `[level, …]`; `noul`: `{true?, false?}`. */
+    criteria?: unknown;
+    /** `noul` only: `{"false": str, "true": str}`. */
+    labels?: {
+        false: string;
+        true: string;
+    } | null;
+    [extra: string]: unknown;
+}
+export type DecisionTruncation = 'allow' | 'error';
+export interface SystemoneRequest {
+    model?: string;
+    state: unknown;
+    questions: Record<string, DecisionQuestion>;
+    truncation?: DecisionTruncation;
+    [extra: string]: unknown;
+}
+export interface DecisionAnswer {
+    type: DecisionQuestionType;
+    /** `noul`: P(true). */
+    noul?: number;
+    /** `choice`: the first argmax, the label as given (a number stays a number). */
+    choice?: unknown;
+    /** `score`: sum(i * p_i). */
+    score?: number;
+    probabilities?: Record<string, number>;
+    legend?: Record<string, unknown>;
+    confidence: number;
+    [extra: string]: unknown;
+}
+export interface DecisionRuntimeInfo {
+    layout: string;
+    format: string;
+    plan: string;
+    spec_sha256: string;
+    calibration: string;
+    [extra: string]: unknown;
+}
+export interface DecisionTimings {
+    queue_ms: number;
+    render_ms: number;
+    compute_ms: number;
+    [extra: string]: unknown;
+}
+/** Upstream llama.cpp answers only `answers` and `usage.{input,output}_tokens`; the rest is the fork's. */
+export interface SystemoneResponse {
+    model?: string;
+    answers: Record<string, DecisionAnswer>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        evaluated_tokens?: number;
+        [extra: string]: unknown;
+    };
+    latency_ms?: number;
+    timings?: DecisionTimings;
+    warnings?: string[];
+    runtime?: DecisionRuntimeInfo;
+    [extra: string]: unknown;
+}
+/** One measured or missing skill check of an executor card (`atomic.executor-card/1`). */
+export type ExecutorCheck = {
+    skill: string;
+    status: 'measured';
+    /** Integers only: the engine rejects floats so Python and C++ render the same text. */
+    passed: number;
+    total: number;
+    criterion?: string;
+    source?: string;
+    version?: string;
+    [extra: string]: unknown;
+} | {
+    skill: string;
+    status: 'missing';
+    source?: string;
+    version?: string;
+    [extra: string]: unknown;
+};
+export interface ExecutorCard {
+    schema?: 'atomic.executor-card/1' | string;
+    name: string;
+    kind: string;
+    description?: string;
+    /** At most 32. */
+    checks?: ExecutorCheck[];
+    [extra: string]: unknown;
+}
+export interface RouterCandidate {
+    /** `[A-Za-z0-9._:/@+-]{1,128}`, unique within a request. */
+    id: string;
+    card: ExecutorCard;
+    [extra: string]: unknown;
+}
+export interface RouterScoreRequest {
+    model?: string;
+    task: string;
+    criterion: string;
+    candidates: RouterCandidate[];
+    truncation?: DecisionTruncation;
+    [extra: string]: unknown;
+}
+export interface RouterScore {
+    id: string;
+    /** Independent per candidate: the scores do not sum to 1, and there is no threshold or argmax. */
+    p_success: number;
+    /** The raw z = s_true - s_false, for recalibration. */
+    logit: number;
+    calibrated: boolean;
+    input_tokens: number;
+    truncated_tokens: number;
+    [extra: string]: unknown;
+}
+export interface RouterScoreResponse {
+    object: 'router.scores';
+    model: string;
+    scores: RouterScore[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        passes: number;
+        [extra: string]: unknown;
+    };
+    latency_ms: number;
+    timings?: DecisionTimings;
+    runtime: DecisionRuntimeInfo;
+    warnings: string[];
+    [extra: string]: unknown;
+}
+/** Reasons a decision handler puts in its error envelope (DECISION.md "Errors"). */
+export declare const DECISION_ENGINE_REASONS: readonly ["MALFORMED_JSON", "BODY_NOT_OBJECT", "INVALID_REQUEST", "UNKNOWN_QUESTION_TYPE", "EMPTY_INSTRUCTIONS", "TOO_FEW_OPTIONS", "TOO_MANY_OPTIONS", "INVALID_NOUL_CRITERIA", "UNSUPPORTED_NUMBER", "UNSUPPORTED_CRITERIA_VALUE", "TOO_MANY_QUESTIONS", "INVALID_CARD", "DUPLICATE_CANDIDATE_ID", "INVALID_CANDIDATE_ID", "TOO_MANY_CANDIDATES", "BODY_TOO_LARGE", "PROMPT_TOO_LONG", "CARD_TOO_LONG", "CRITERION_TOO_LONG", "OPTIONS_TRUNCATED", "STATE_TRUNCATED", "OVERLOADED", "INTERNAL", "ROUTER_NOT_CALIBRATED", "UNAVAILABLE"];
+/** A known reason, or a string a newer engine added. */
+export type DecisionEngineReason = (typeof DECISION_ENGINE_REASONS)[number] | (string & {});
+/**
+ * `{"error": {...}}` of a decision handler. Middleware answers (401, 503 while loading, 404) carry no
+ * `reason`, which is why it is optional here.
+ */
+export interface DecisionEngineError {
+    code?: number;
+    type?: string;
+    reason?: DecisionEngineReason;
+    message: string;
+    /** JSON path of the bad field. */
+    param?: string;
+    [extra: string]: unknown;
+}
+export interface DecisionLimits {
+    max_questions?: number;
+    max_candidates?: number;
+    max_options?: number;
+    max_checks?: number;
+    max_tokens?: number;
+    max_card_tokens?: number;
+    max_card_field_bytes?: number;
+    max_body_bytes?: number;
+    [extra: string]: unknown;
+}
+/** The `decision` block of `GET /props`. Only `api_version` is required by the core. */
+export interface DecisionProps {
+    api_version: number;
+    endpoints?: string[];
+    layout?: string;
+    format?: string;
+    model_id?: string;
+    model_version?: string;
+    spec_version?: number;
+    spec_sha256?: string;
+    spec_source?: 'gguf' | 'file' | 'default' | string;
+    question_types?: string[];
+    limits?: DecisionLimits;
+    confidence?: string;
+    calibration?: {
+        method?: string;
+        calibrated?: boolean;
+        version?: string;
+        [extra: string]: unknown;
+    };
+    router?: {
+        available?: boolean;
+        calibrated?: boolean;
+        method?: string;
+        card_schema?: string;
+        card_renderer?: string;
+        [extra: string]: unknown;
+    };
+    plan?: Record<string, unknown>;
+    /** `gguf` for `-m FILE`, `checkpoint-dir` for `-m DIR`. */
+    source?: 'gguf' | 'checkpoint-dir' | (string & {});
+    /** The cached GGUF a checkpoint folder was loaded from; `null` for `gguf`. */
+    cache_path?: string | null;
+    /** How a checkpoint folder was loaded; `null` for `gguf`. */
+    checkpoint?: DecisionCheckpointInfo | null;
+    [extra: string]: unknown;
+}
+/** `/props.decision.checkpoint`: the conversion of a checkpoint folder into the GGUF cache. */
+export interface DecisionCheckpointInfo {
+    dir?: string;
+    cache_dir?: string;
+    key?: string;
+    outtype?: DecisionConvertType | (string & {});
+    /** The cached GGUF was reused; `convert_ms` is then 0. */
+    cache_hit?: boolean;
+    convert_ms?: number;
+    /** `LAYA_CONVERT_VERSION` of the engine's converter. */
+    converter?: number;
+    [extra: string]: unknown;
+}
+/** `--decision-convert-type`: what a checkpoint folder is converted to. */
+export type DecisionConvertType = 'f16' | 'f32';
+export declare const DECISION_CONVERT_TYPES: readonly DecisionConvertType[];
+/** `capabilities` values `GET /v1/models` lists for a decision process. */
+export type DecisionCapability = 'decision' | 'systemone' | 'router_score' | (string & {});
+/**
+ * `settings.json` → `decision`. The model is a file or folder the app downloaded (its registry is the
+ * app's); the core only runs it. A relative `model_path` / `spec_path` is resolved against the data
+ * folder.
+ */
+export interface DecisionSettings {
+    /** Off by default: nothing is spawned until the app turns it on and names a model. */
+    enabled: boolean;
+    /**
+     * The decision GGUF (a laya model, any GGUF stamped with `decision.spec`, or an upstream one with
+     * `<arch>.decision.type`), or a laya Hugging Face checkpoint folder, which the fork converts once
+     * into `<data>/decision/gguf-cache`. The file decides the engine (`DecisionDialect`).
+     */
+    model_path: string;
+    /** `--mmproj` for an upstream model that reads images (openjev, clef); empty = none. Ignored by the fork. */
+    mmproj_path: string;
+    /**
+     * `-c` for an upstream model, also its batch (the decision outputs are read from one batch); 0 = the
+     * core picks (`UPSTREAM_DECISION_DEFAULT_CTX`, capped at the trained context). Ignored by the fork.
+     */
+    ctx_size: number;
+    /** `-a`: the name the engine answers with; empty = the file name, or the folder name for a checkpoint. */
+    model_id: string;
+    /** `--decision-spec`: a spec or a bare `calibration.json` replacing the embedded one; empty = none. */
+    spec_path: string;
+    /** `-t`; 0 = the core picks (the physical core count, capped, see `decisionThreads`). */
+    threads: number;
+    /** Budget of one `scoreCandidates` / `decide` call before it fails open, in milliseconds. */
+    timeout_ms: number;
+    /** Unload after this many seconds without a call; 0 keeps the model resident. */
+    idle_unload_secs: number;
+    /** How long a start may take before it counts as failed. */
+    startup_timeout_secs: number;
+    /** `--decision-allow-uncalibrated`: serve `/v1/router/score` with `calibrated: false` scores. */
+    allow_uncalibrated: boolean;
+    /** An explicit `llama-server` to run instead of an installed build of the model's engine; empty = resolve one. */
+    engine_path: string;
+    /** `--decision-convert-type` for a checkpoint folder; ignored for a GGUF. */
+    convert_type: DecisionConvertType;
+}
+export declare const DEFAULT_DECISION_SETTINGS: DecisionSettings;
+export type DecisionState = 
+/** Turned off in settings. */
+'disabled'
+/** Enabled, not running (never started, unloaded, or idle-unloaded); the next call starts it. */
+ | 'idle' | 'starting' | 'ready'
+/** The process died after it was ready; a restart is scheduled. */
+ | 'restarting'
+/** A start failed, or restarts gave up; `error` says why. Cleared by `load` or a settings change. */
+ | 'failed'
+/**
+ * No installed build of the model's engine can run it: no fork build speaks `--decision` (or it
+ * speaks another API version), or no upstream build is new enough for the model's decision type.
+ */
+ | 'unsupported';
+/** The providers whose builds can run a decision model, one per dialect. */
+export type DecisionEngineProvider = 'llamacpp' | 'llamacpp-upstream';
+/** Which `llama-server` runs the decision model, and why the core trusts it. */
+export interface DecisionEngineInfo {
+    path: string;
+    /** `<version>/<backend>` of the installed pack; `null` for an explicit `engine_path`. */
+    version_backend: string | null;
+    /** Fork semver from the release tag (`b10269-1.7.0` → `1.7.0`); `null` when the tag has none. */
+    fork_version: string | null;
+    /**
+     * Whether the tag alone says the build is new enough: for the fork the `-h` probe has the last
+     * word, for upstream the build number is the gate.
+     */
+    version_gate: boolean | null;
+    /** The API the engine is started for. */
+    dialect: DecisionDialect;
+    /** The provider whose pack it is; `null` for an explicit `engine_path`. */
+    provider: DecisionEngineProvider | null;
+}
+export interface DecisionStatus {
+    state: DecisionState;
+    enabled: boolean;
+    /** Resolved absolute model path, or `null` when none is configured. */
+    model_path: string | null;
+    engine: DecisionEngineInfo | null;
+    pid: number | null;
+    port: number | null;
+    /** `/props.decision` of the running process. */
+    props: DecisionProps | null;
+    /** Capabilities the running process lists in `/v1/models`. */
+    capabilities: DecisionCapability[];
+    /**
+     * Crashes counted towards giving up: one per unexpected exit or failed restart, back to zero after
+     * a process stays up for a minute, or on an explicit load or a settings change.
+     */
+    restarts: number;
+    error: {
+        code: string;
+        message: string;
+        details?: string;
+    } | null;
+    /** Milliseconds since the epoch of the last state change. */
+    since: number;
+}
+/** Why a call answered without the model's opinion. The caller then applies its default policy. */
+export type DecisionUnavailableReason = 'disabled' | 'not_configured' | 'unsupported' | 'starting' | 'failed' | 'not_running' | 'timeout' | 'overloaded' | 'aborted'
+/**
+ * The router has no calibration and the process runs without `--decision-allow-uncalibrated`: a
+ * configuration state, not a caller bug. Answered without a request when `/props.decision.router`
+ * says `available: false`, else read from the engine's 501 `ROUTER_NOT_CALIBRATED`.
+ */
+ | 'not_calibrated'
+/** The engine refused the request (4xx/5xx with its envelope in `error`), or it could not be serialized. */
+ | 'rejected' | 'transport_error' | 'invalid_response';
+/**
+ * What `scoreCandidates` and `decide` resolve to. They never throw into the caller: a chat turn must
+ * not fail because the router could not answer (fail-open).
+ */
+export type DecisionOutcome<T> = {
+    unavailable: false;
+    result: T;
+    elapsed_ms: number;
+} | {
+    unavailable: true;
+    reason: DecisionUnavailableReason;
+    message: string;
+    elapsed_ms: number;
+    /** The engine's HTTP status, when it answered. */
+    status?: number;
+    /** The engine's error envelope, when it answered with one. */
+    error?: DecisionEngineError;
+};
+/** `POST /atomic/v1/decision/score` body. */
+export interface DecisionScoreRequest {
+    task: string;
+    criterion: string;
+    candidates: RouterCandidate[];
+    truncation?: DecisionTruncation;
+    /** Overrides `settings.decision.timeout_ms` for this call. */
+    timeout_ms?: number;
+}
+/** `POST /atomic/v1/decision/decide` body. */
+export interface DecisionDecideRequest {
+    state: unknown;
+    questions: Record<string, DecisionQuestion>;
+    truncation?: DecisionTruncation;
+    timeout_ms?: number;
+}
+/** `decision:state`: every status change. */
+export type DecisionStateEvent = DecisionStatus;
+/** `decision:error`: a failure nobody is awaiting (a crash, a restart that failed, restarts given up). */
+export interface DecisionErrorEvent {
+    code: string;
+    message: string;
+    details?: string;
+}

package/dist/contracts/decision.js

@@ -0,0 +1,69 @@
+/**
+ * The decision model: a small model that answers typed questions with probabilities in one forward
+ * pass. It runs as its own core module, outside the sessions registry
+ * (ADR 2026-09-30-the-decision-model-is-its-own-core-module), on one of two engines
+ * (ADR 2026-10-06-run-decision-models-on-upstream-llamacpp):
+ *  - `turboquant`: `llama-server --decision` of the TurboQuant fork (release 1.7.0 on), which also
+ *    serves the router (`/v1/router/score`) and converts laya checkpoint folders;
+ *  - `upstream`: ggml-org llama.cpp (b11370 on), which serves `/v1/systemone` for a GGUF stamped with
+ *    `<arch>.decision.type` (laya, openjev, lev, kev, nimble, clef). No router.
+ *
+ * Two halves live here:
+ *  - the engine's wire contract (`DECISION.md` in atomic-llama-cpp-turboquant, API version 1, which
+ *    upstream's `/v1/systemone` shares for requests), mirrored as types only. Fields the engine may
+ *    add later are tolerated: every object keeps an index signature, and nothing in the core rejects
+ *    an unknown key;
+ *  - the core's own surface: the settings section, the status, the fail-open outcome and the events.
+ *
+ * Browser-safe: types and constants only. snake_case throughout, like the engine and `settings.json`.
+ */
+/** `/props.decision.api_version` this core speaks. Anything else is treated as an unsupported engine. */
+export const DECISION_API_VERSION = 1;
+/** Reasons a decision handler puts in its error envelope (DECISION.md "Errors"). */
+export const DECISION_ENGINE_REASONS = [
+    'MALFORMED_JSON',
+    'BODY_NOT_OBJECT',
+    'INVALID_REQUEST',
+    'UNKNOWN_QUESTION_TYPE',
+    'EMPTY_INSTRUCTIONS',
+    'TOO_FEW_OPTIONS',
+    'TOO_MANY_OPTIONS',
+    'INVALID_NOUL_CRITERIA',
+    'UNSUPPORTED_NUMBER',
+    'UNSUPPORTED_CRITERIA_VALUE',
+    'TOO_MANY_QUESTIONS',
+    'INVALID_CARD',
+    'DUPLICATE_CANDIDATE_ID',
+    'INVALID_CANDIDATE_ID',
+    'TOO_MANY_CANDIDATES',
+    'BODY_TOO_LARGE',
+    'PROMPT_TOO_LONG',
+    'CARD_TOO_LONG',
+    'CRITERION_TOO_LONG',
+    'OPTIONS_TRUNCATED',
+    'STATE_TRUNCATED',
+    'OVERLOADED',
+    'INTERNAL',
+    'ROUTER_NOT_CALIBRATED',
+    'UNAVAILABLE',
+];
+export const DECISION_CONVERT_TYPES = ['f16', 'f32'];
+export const DEFAULT_DECISION_SETTINGS = {
+    enabled: false,
+    model_path: '',
+    mmproj_path: '',
+    ctx_size: 0,
+    model_id: '',
+    spec_path: '',
+    threads: 0,
+    // One systemone question takes 0.1-0.3 s on a CPU and a router pass per candidate 0.1-0.8 s
+    // (DECISION.md); 500 ms timed out on ordinary x86 machines. A caller with a tighter budget passes
+    // its own `timeout_ms`.
+    timeout_ms: 2000,
+    idle_unload_secs: 0,
+    startup_timeout_secs: 60,
+    allow_uncalibrated: false,
+    engine_path: '',
+    convert_type: 'f16',
+};
+//# sourceMappingURL=decision.js.map

package/dist/contracts/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../../src/contracts/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yGAAyG;AACzG,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AA+IrC,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,gBAAgB;IAChB,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;IACvB,oBAAoB;IACpB,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;IACvB,oBAAoB;IACpB,4BAA4B;IAC5B,oBAAoB;IACpB,cAAc;IACd,wBAAwB;IACxB,sBAAsB;IACtB,qBAAqB;IACrB,gBAAgB;IAChB,iBAAiB;IACjB,eAAe;IACf,oBAAoB;IACpB,mBAAmB;IACnB,iBAAiB;IACjB,YAAY;IACZ,UAAU;IACV,uBAAuB;IACvB,aAAa;CACL,CAAA;AA+EV,MAAM,CAAC,MAAM,sBAAsB,GAAmC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAkDpF,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,CAAC;IACV,4FAA4F;IAC5F,kGAAkG;IAClG,wBAAwB;IACxB,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,CAAC;IACnB,oBAAoB,EAAE,EAAE;IACxB,kBAAkB,EAAE,KAAK;IACzB,WAAW,EAAE,EAAE;IACf,YAAY,EAAE,KAAK;CACpB,CAAA"}

package/dist/contracts/diffusion.d.ts

@@ -80,6 +80,12 @@ export interface LoadDiffusionModelRequest {
     defaults: DiffusionFamilyDefaults;
     ranges: DiffusionFamilyRanges;
     offload: DiffusionOffloadPolicy;
+    /**
+     * The policy to move to when the model runs out of memory under `offload`: the load, or the job,
+     * that ran out is retried once with it, and the session keeps it until the next load. Ignored when
+     * it equals `offload`.
+     */
+    offloadFallback?: DiffusionOffloadPolicy;
     engine?: DiffusionEngineId;
     /** `--threads`, for CPU backends. */
     threads?: number;
@@ -289,14 +295,6 @@ export interface DiffusionBackendInstallRecord {
     installedAtMs: number;
     dir: string;
 }
-export interface FinalizeBackendInstallArgs {
-    dir: string;
-    tag: string;
-    backendId: string;
-    backend: DiffusionBackend;
-    engine: DiffusionEngineId;
-    sha256?: string;
-}
 /** Sent by the app once per core generation, before anything else. */
 export interface DiffusionConfig {
     /** Must be the core's own data folder. */
@@ -366,15 +364,63 @@ export interface VideoGenerateRequest {
     /** Reserved for `image-to-video`: the last frame. */
     endImage?: ImageSource;
 }
+/** Which memory a video generation competes for: Apple's unified memory, a discrete GPU's, or system RAM. */
+export type VideoMemoryPool = 'unified' | 'vram' | 'system';
+/** `fits`: at most 80 % of the budget; `tight`: at most 100 %; `exceeds`: past it, into swap. */
+export type VideoMemoryVerdict = 'fits' | 'tight' | 'exceeds';
+/** `heuristic`: the core's model of the family and the machine; `history`: calibrated by this machine's clips. */
+export type VideoEstimateBasis = 'heuristic' | 'history';
+/**
+ * What a video request will cost on this machine with the loaded model, before it runs. Answered by
+ * `POST /atomic/v1/diffusion/video/estimate` and carried by `VideoJob.estimate`.
+ */
+export interface VideoEstimate {
+    memory: {
+        requiredBytes: number;
+        budgetBytes: number;
+        /** The pool that decided the verdict. */
+        pool: VideoMemoryPool;
+        verdict: VideoMemoryVerdict;
+    };
+    /** Whole seconds, `0 < low <= high`; `null` when the verdict is `exceeds`: time in swap is unpredictable. */
+    seconds: {
+        low: number;
+        high: number;
+    } | null;
+    basis: VideoEstimateBasis;
+}
+/** How far a tiled VAE decode got: tiles finished out of the pass the engine announced. */
+export interface VideoDecodeTiles {
+    done: number;
+    total: number;
+}
 /** One clip per job, so no batch fields. */
 export interface VideoJobProgress {
     phase: VideoJobPhase;
     step: number;
     totalSteps: number;
-    /** 0..1 estimate for the whole job. */
+    /** 0..1 estimate for the whole job; never decreases and stays below 1 until the job is over. */
     fraction: number;
+    /**
+     * Seconds left for the whole job: encoding, the remaining steps and the VAE decode. Before the
+     * first measured step it comes from `VideoJob.estimate`; once a tiled decode finished a tile, from
+     * the measured time per tile. A forecast that is spent is doubled rather than dropped. `null` when
+     * unknown, once every tile of a tiled decode is done, and while saving.
+     */
     etaSeconds: number | null;
+    /**
+     * The decode's tiles while a tiled decode runs; absent in every other phase, for a decode in one
+     * graph, and from older cores. A retried decode starts a new pass from `done: 0`.
+     */
+    decodeTiles?: VideoDecodeTiles;
+    /** Since the runner started the job. */
     elapsedMs: number;
+    /**
+     * The steps, or the tiles of a tiled decode, slowed down sharply (a sign of swapping or a stalled
+     * engine); once set it stays set for the job. Always sent by this core; absent from older cores,
+     * which a client reads as `false`.
+     */
+    slowdown?: boolean;
 }
 export interface VideoJob {
     id: string;
@@ -389,6 +435,8 @@ export interface VideoJob {
     /** Zero or one item. */
     outputs: GalleryVideoItem[];
     error?: DiffusionErrorBody;
+    /** The estimate for this request, taken when the job started; absent when it could not be made. */
+    estimate?: VideoEstimate;
 }
 /** Written as `<jobId>.json` beside the video (WebM has no text chunk). Enough to reproduce the clip. */
 export interface VideoRecipe {
@@ -426,6 +474,11 @@ export interface VideoRecipe {
     };
     createdAtMs: number;
     durationMs: number;
+    /**
+     * From the last sampling step to the saved clip: the VAE decode and the file's encoding. Absent
+     * for a clip made before it was recorded, or when no sampling step was seen.
+     */
+    decodeMs?: number;
 }
 export interface GalleryVideoItem {
     /** The job id (32 hex characters); also the file stem. */

package/dist/contracts/embedding.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The embedding model (ADR 2026-10-07-embedding-models-are-their-own-core-module): one stock llama.cpp
+ * `llama-server --embedding` the app turns on for the Local API Server's `/v1/embeddings`, outside the
+ * sessions registry like the decision model. The model is a GGUF the app downloaded (its catalog is
+ * the app's, `atomic-chat-conf/models/embedding.json`), plus a projector for one that reads images or
+ * audio; the core only runs it.
+ */
+/** The pooling a model is started with (`--pooling`); empty in the settings = the GGUF's own. */
+export declare const EMBEDDING_POOLINGS: readonly ["mean", "cls", "last"];
+export type EmbeddingPooling = (typeof EMBEDDING_POOLINGS)[number];
+/** What one input may hold, as the running process reports it (`/props.modalities`). */
+export type EmbeddingModality = 'text' | 'image' | 'audio' | 'video';
+/** The provider whose builds run embedding models. */
+export type EmbeddingEngineProvider = 'llamacpp-upstream';
+/**
+ * `settings.json` → `embedding`. A relative `model_path` / `mmproj_path` is resolved against the data
+ * folder.
+ */
+export interface EmbeddingSettings {
+    /** Off by default: nothing is spawned until the app turns it on and names a model. */
+    enabled: boolean;
+    /** The embedding GGUF. */
+    model_path: string;
+    /** `--mmproj` for a model that reads images or audio; empty = text only. */
+    mmproj_path: string;
+    /** `-a`: the name API clients pass as `model`; empty = the file name without `.gguf`. */
+    model_id: string;
+    /**
+     * `-c`, and `-b`/`-ub`: an encoder reads one whole input (media tokens included) per batch. 0 = the
+     * core picks (`EMBEDDING_DEFAULT_CTX`, capped at the trained context).
+     */
+    ctx_size: number;
+    /** `--pooling`; empty = the model's own (`<arch>.pooling_type`). */
+    pooling: '' | EmbeddingPooling;
+    /** `--image-max-tokens`; 0 = the engine's own (at most half the batch). */
+    image_max_tokens: number;
+    /** `-t`; 0 = llama.cpp's own default. */
+    threads: number;
+    /** Unload after this many seconds without a request; 0 keeps the model resident. */
+    idle_unload_secs: number;
+    /** How long a start may take before it counts as failed. */
+    startup_timeout_secs: number;
+    /** An explicit `llama-server` to run instead of an installed llama.cpp build; empty = resolve one. */
+    engine_path: string;
+}
+export declare const DEFAULT_EMBEDDING_SETTINGS: EmbeddingSettings;
+export type EmbeddingState = 
+/** Turned off in settings. */
+'disabled'
+/** Enabled, not running (never started, unloaded, or idle-unloaded); the next request starts it. */
+ | 'idle' | 'starting' | 'ready'
+/** The process died after it was ready; a restart is scheduled. */
+ | 'restarting'
+/** A start failed, or restarts gave up; `error` says why. Cleared by `load` or a settings change. */
+ | 'failed'
+/** No installed llama.cpp build is new enough for the model (`EMBEDDING_ENGINE_UNSUPPORTED`). */
+ | 'unsupported';
+/** Which `llama-server` runs the embedding model. */
+export interface EmbeddingEngineInfo {
+    path: string;
+    /** `<version>/<backend>` of the installed pack; `null` for an explicit `engine_path`. */
+    version_backend: string | null;
+    /** The provider whose pack it is; `null` for an explicit `engine_path`. */
+    provider: EmbeddingEngineProvider | null;
+}
+export interface EmbeddingStatus {
+    state: EmbeddingState;
+    enabled: boolean;
+    /** Resolved absolute model path, or `null` when none is configured. */
+    model_path: string | null;
+    /** The name API clients pass as `model`, or `null` when no model is configured. */
+    model_id: string | null;
+    engine: EmbeddingEngineInfo | null;
+    pid: number | null;
+    port: number | null;
+    /** Length of the vectors the running process returns; `null` until it is ready. */
+    dims: number | null;
+    /** What one input may hold; `[]` until the process is ready. */
+    modalities: EmbeddingModality[];
+    /**
+     * Crashes counted towards giving up: one per unexpected exit or failed restart, back to zero after
+     * a process stays up for a minute, or on an explicit load or a settings change.
+     */
+    restarts: number;
+    error: EmbeddingErrorEvent | null;
+    /** Milliseconds since the epoch of the last state change. */
+    since: number;
+}
+/** `embedding:state`: every status change. */
+export type EmbeddingStateEvent = EmbeddingStatus;
+/** `embedding:error`: a failure nobody is awaiting (a crash, a restart that failed, restarts given up). */
+export interface EmbeddingErrorEvent {
+    code: string;
+    message: string;
+    details?: string;
+}
+/** `POST /atomic/v1/embedding/embed`: what the process answered, relayed as it came. */
+export interface EmbeddingEmbedResponse {
+    /** The engine's HTTP status. */
+    status: number;
+    /** The engine's JSON answer (the OpenAI list, or its error envelope). */
+    body: unknown;
+}