@stackstackstack/dsh-llm 0.1.5

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned LLM stream-protocol invariants. @module @stackstackstack/dsh-llm/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "llm-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the LLM invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,100 @@
+/** Package-owned LLM stream-protocol invariants. @module @stackstackstack/dsh-llm/invariant */
+const PACKAGE_NAME = '@stackstackstack/dsh-llm';
+/** Cordis companion plugin name. */
+export const name = 'llm-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Require one chunk index to be a non-negative safe integer. */
+function validateIndex(index, fail) {
+    if (!Number.isSafeInteger(index) || index < 0) {
+        fail(`LLM stream block index must be a non-negative safe integer, got ${index}`);
+    }
+}
+/** Require a delta to address an open block of its matching type. */
+function validateDelta(open, index, expected, fail) {
+    validateIndex(index, fail);
+    const actual = open.get(index);
+    if (actual !== expected) {
+        fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`);
+    }
+}
+/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
+async function* validateStream(source, fail) {
+    const open = new Map();
+    let usageSeen = false;
+    let finished = false;
+    for await (const chunk of source) {
+        if (finished)
+            fail(`LLM stream emitted ${chunk.type} after terminal finish`);
+        switch (chunk.type) {
+            case 'block-start':
+                validateIndex(chunk.index, fail);
+                if (open.has(chunk.index))
+                    fail(`LLM stream repeated block-start index ${chunk.index}`);
+                open.set(chunk.index, chunk.blockType);
+                break;
+            case 'text-delta':
+                validateDelta(open, chunk.index, 'text', fail);
+                break;
+            case 'reasoning-delta':
+                validateDelta(open, chunk.index, 'reasoning', fail);
+                break;
+            case 'tool-call-delta':
+                validateDelta(open, chunk.index, 'tool-call', fail);
+                break;
+            case 'block-end': {
+                validateIndex(chunk.index, fail);
+                const blockType = open.get(chunk.index);
+                if (blockType === undefined)
+                    fail(`LLM stream block-end index ${chunk.index} has no open block`);
+                if (chunk.block.type !== blockType) {
+                    fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`);
+                }
+                open.delete(chunk.index);
+                break;
+            }
+            case 'usage':
+                if (usageSeen)
+                    fail('LLM stream emitted usage more than once');
+                usageSeen = true;
+                break;
+            case 'finish':
+                if (open.size > 0 && chunk.reason.kind !== 'error' && chunk.reason.kind !== 'aborted') {
+                    fail(`LLM stream finished with ${open.size} open block(s)`);
+                }
+                finished = true;
+                break;
+        }
+        yield chunk;
+    }
+    if (!finished)
+        fail('LLM stream ended without a terminal finish chunk');
+}
+/** Install validation around every provider stream. */
+const install = (ctx, fail) => {
+    ctx.on('llm/stream', (_options, next) => validateStream(next(), fail), { global: true, prepend: true });
+    ctx.on('llm/adapters-updated', () => {
+        // A disposer-time emit can outlive the service-store entry during whole-
+        // context teardown; only a live service promises a readable registry.
+        const llm = ctx.get('llm');
+        if (llm === undefined)
+            return;
+        for (const provider of llm.listProviders()) {
+            try {
+                llm.providerRetryPolicy(provider.id);
+            }
+            catch {
+                // Reaching here IS the violation: the notification promised a readable
+                // registry, and only that broken promise can make the lookup throw.
+                fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`);
+            }
+        }
+    }, { global: true });
+};
+/**
+ * Register the LLM invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/message.d.ts

@@ -0,0 +1,206 @@
+/** Message value types, identity, and immutable construction helpers. */
+import { MessageId, type CallId } from './brand.ts';
+import type { ContentBlock, StreamChunk, ToolResultBlock } from './types.ts';
+/** Provider/model identity and adapter-private replay data for an assistant message. */
+export interface AssistantProvenance {
+    /** Provider route that produced the message. */
+    provider: string;
+    /** Provider model id that produced the message. */
+    model: string;
+    /**
+     * Lossless-JSON adapter state needed to replay the provider response.
+     * `LlmRuntime` exposes it to a target adapter only when that adapter instance
+     * currently owns both this historical provider and the target provider.
+     */
+    replayState?: unknown;
+}
+/** Required source of an assistant message produced by a routed model. */
+export interface ModelMessageSource extends AssistantProvenance {
+    kind: 'model';
+}
+/** Required source of a user-role message carrying one tool result. */
+export interface ToolMessageSource {
+    kind: 'tool';
+    callId: CallId;
+}
+/**
+ * The kind of information in producer-supplied context, declared by the
+ * producer beside its provenance.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+export type ContextForm = 
+/** Instructions read out of workspace files the model is expected to follow. */
+'instructions'
+/** A catalog of items available in this session, republished as it changes. */
+ | 'catalog'
+/** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+ | 'snapshot'
+/** A one-off account of something that just happened; it supersedes nothing. */
+ | 'notice'
+/** A message another agent addressed to this one. */
+ | 'relay'
+/** Material lifted out of another session's log, possibly reduced on the way in. */
+ | 'recall';
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+export interface ContextSnapshotSection {
+    /** The contributing subsystem's name. */
+    readonly name: string;
+    /** That contribution's model-facing text, exactly as assembled. */
+    readonly text: string;
+}
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source types that carry one.
+ *
+ * Discriminated by `form` so a producer cannot select a form without the
+ * fields needed to present it: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+export type ContextFormed = {
+    readonly form?: never;
+} | {
+    readonly form: 'instructions';
+} | {
+    readonly form: 'catalog';
+} | {
+    readonly form: 'snapshot';
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[];
+} | {
+    readonly form: 'notice';
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string;
+} | {
+    readonly form: 'relay';
+} | {
+    readonly form: 'recall';
+};
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+export interface MessageSourceMap {
+    user: {
+        kind: 'user';
+    };
+    plugin: {
+        kind: 'plugin';
+        plugin: string;
+    } & ContextFormed;
+    model: ModelMessageSource;
+    tool: ToolMessageSource;
+}
+/**
+ * Bound for a `notice` summary. The account rides a collapsed transcript row
+ * and is committed to the durable log, while its inputs — task labels, goal
+ * objectives, tool arguments — are caller text with no length of their own.
+ */
+export declare const CONTEXT_SUMMARY_MAX_CHARS = 120;
+/**
+ * Bound one `notice` summary to {@link CONTEXT_SUMMARY_MAX_CHARS}.
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export declare function boundContextSummary(summary: string): string;
+/** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
+export type MessageSource = MessageSourceMap[keyof MessageSourceMap];
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+export interface Message {
+    /** Stable identity preserved across every representation boundary. */
+    readonly id: MessageId;
+    /** Provider-neutral conversation role. */
+    readonly role: 'system' | 'user' | 'assistant';
+    /** Exact model-facing blocks. */
+    readonly content: ContentBlock[];
+    /** Required source fields supplied by the producer. */
+    readonly source: MessageSource;
+}
+/** A user-role specialization of the one shared message representation. */
+export interface UserMessage extends Message {
+    readonly role: 'user';
+}
+/** A model-produced assistant specialization of the shared message representation. */
+export interface AssistantMessage extends Message {
+    readonly role: 'assistant';
+    readonly source: ModelMessageSource;
+}
+/** A tool-result specialization whose model-facing block retains call correlation. */
+export interface ToolResultMessage extends Message {
+    readonly role: 'user';
+    readonly content: [ToolResultBlock];
+    readonly source: ToolMessageSource;
+}
+type NewMessage = Omit<Message, 'id'>;
+type NewUserMessage = Omit<UserMessage, 'id' | 'role'>;
+type NewAssistantMessage = Omit<AssistantMessage, 'id' | 'role' | 'source'> & {
+    readonly source: Omit<ModelMessageSource, 'kind'> & {
+        readonly kind?: never;
+    };
+};
+/**
+ * Detach and deep-freeze a message whose identity already exists.
+ * @param message - complete message, including its stable identity.
+ * @returns an immutable snapshot that preserves the identity.
+ */
+export declare function freezeMessage<T extends Message>(message: T): T;
+/**
+ * Create one identified message and freeze it before publication.
+ * @param input - complete role, content, and source for a new message.
+ * @returns an immutable message with a fresh stable identity.
+ */
+export declare function createMessage<T extends NewMessage>(input: T & {
+    readonly id?: never;
+}): T & Pick<Message, 'id'>;
+/**
+ * Create one identified user-role message and freeze it before publication.
+ * @param input - complete content and source for a new user message.
+ * @returns an immutable user message with a fresh stable identity.
+ */
+export declare function createUserMessage<T extends NewUserMessage>(input: T & {
+    readonly id?: never;
+    readonly role?: never;
+}): T & Pick<UserMessage, 'id' | 'role'>;
+/**
+ * Create one identified model-produced assistant message and freeze it before publication.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
+ * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
+ */
+export declare function createAssistantMessage(input: NewAssistantMessage & {
+    readonly id?: never;
+    readonly role?: never;
+}): AssistantMessage;
+/** Input whose acceptance creates one tool-result message. */
+export interface ToolResultMessageInput {
+    readonly callId: CallId;
+    readonly content: ContentBlock[];
+    readonly isError: boolean;
+}
+/**
+ * Create and freeze one identified tool-result message.
+ * @param input - call identity, raw result blocks, and outcome.
+ * @returns an immutable user-role tool-result message.
+ */
+export declare function createToolResultMessage(input: ToolResultMessageInput): ToolResultMessage;
+/**
+ * Whether a stream chunk carries visible model output (the first-token
+ * boundary shared by client step timing and the whole-log sessionStats
+ * projection). Empty deltas (heartbeats, empty tool-call frames) do not count
+ * as a first token.
+ * @param chunk - the stream chunk to test.
+ * @returns true when the chunk contains a non-empty text/reasoning/tool delta.
+ */
+export declare function isTokenDelta(chunk: StreamChunk): boolean;
+export {};
+//# sourceMappingURL=message.d.ts.map

package/lib/types/message.js

@@ -0,0 +1,100 @@
+/** Message value types, identity, and immutable construction helpers. */
+import { MessageId } from "./brand.js";
+import { deepFreeze } from "./call-config.js";
+/**
+ * Bound for a `notice` summary. The account rides a collapsed transcript row
+ * and is committed to the durable log, while its inputs — task labels, goal
+ * objectives, tool arguments — are caller text with no length of their own.
+ */
+export const CONTEXT_SUMMARY_MAX_CHARS = 120;
+/**
+ * Bound one `notice` summary to {@link CONTEXT_SUMMARY_MAX_CHARS}.
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export function boundContextSummary(summary) {
+    return summary.length <= CONTEXT_SUMMARY_MAX_CHARS
+        ? summary
+        : `${summary.slice(0, CONTEXT_SUMMARY_MAX_CHARS - 1)}…`;
+}
+/**
+ * Detach and deep-freeze a message whose identity already exists.
+ * @param message - complete message, including its stable identity.
+ * @returns an immutable snapshot that preserves the identity.
+ */
+export function freezeMessage(message) {
+    return deepFreeze(structuredClone(message));
+}
+/**
+ * Create one identified message and freeze it before publication.
+ * @param input - complete role, content, and source for a new message.
+ * @returns an immutable message with a fresh stable identity.
+ */
+export function createMessage(input) {
+    return freezeMessage({
+        ...input,
+        id: MessageId(crypto.randomUUID()),
+    });
+}
+/**
+ * Create one identified user-role message and freeze it before publication.
+ * @param input - complete content and source for a new user message.
+ * @returns an immutable user message with a fresh stable identity.
+ */
+export function createUserMessage(input) {
+    return createMessage({
+        ...input,
+        role: 'user',
+    });
+}
+/**
+ * Create one identified model-produced assistant message and freeze it before publication.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
+ * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
+ */
+export function createAssistantMessage(input) {
+    return createMessage({
+        role: 'assistant',
+        content: input.content,
+        source: {
+            kind: 'model',
+            ...input.source,
+        },
+    });
+}
+/**
+ * Create and freeze one identified tool-result message.
+ * @param input - call identity, raw result blocks, and outcome.
+ * @returns an immutable user-role tool-result message.
+ */
+export function createToolResultMessage(input) {
+    return createUserMessage({
+        source: { kind: 'tool', callId: input.callId },
+        content: [{
+                type: 'tool-result',
+                toolCallId: input.callId,
+                content: input.content,
+                isError: input.isError,
+            }],
+    });
+}
+/**
+ * Whether a stream chunk carries visible model output (the first-token
+ * boundary shared by client step timing and the whole-log sessionStats
+ * projection). Empty deltas (heartbeats, empty tool-call frames) do not count
+ * as a first token.
+ * @param chunk - the stream chunk to test.
+ * @returns true when the chunk contains a non-empty text/reasoning/tool delta.
+ */
+export function isTokenDelta(chunk) {
+    switch (chunk.type) {
+        case 'text-delta':
+        case 'reasoning-delta':
+            return chunk.text !== '';
+        case 'tool-call-delta':
+            return chunk.argumentsDelta !== '' || chunk.name !== undefined;
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=message.js.map

package/lib/types/never.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
+ * new variant fails compilation at every required handler. Do not use it for declaration-merged
+ * unions such as session events or content blocks: handle known variants and explicitly fall
+ * through because plugins may add valid unknown cases.
+ * @module @stackstackstack/dsh-llm/never
+ */
+/**
+ * Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
+ * a value that escaped its type throws with diagnostics at runtime.
+ * @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
+ * @param context - optional label (e.g. the switch site) prefixed into the throw message.
+ * @returns never — it always throws, with the offending value JSON-rendered in the message.
+ */
+export declare function assertNever(value: never, context?: string): never;
+//# sourceMappingURL=never.d.ts.map

package/lib/types/never.js

@@ -0,0 +1,21 @@
+/**
+ * Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
+ * new variant fails compilation at every required handler. Do not use it for declaration-merged
+ * unions such as session events or content blocks: handle known variants and explicitly fall
+ * through because plugins may add valid unknown cases.
+ * @module @stackstackstack/dsh-llm/never
+ */
+/**
+ * Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
+ * a value that escaped its type throws with diagnostics at runtime.
+ * @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
+ * @param context - optional label (e.g. the switch site) prefixed into the throw message.
+ * @returns never — it always throws, with the offending value JSON-rendered in the message.
+ */
+export function assertNever(value, context) {
+    // JSON.stringify is typed string but returns undefined for undefined input;
+    // String() covers that and other non-serializable escapes.
+    const rendered = JSON.stringify(value) ?? String(value);
+    throw new Error(`unreachable variant${context ? ` in ${context}` : ''}: ${rendered}`);
+}
+//# sourceMappingURL=never.js.map

package/lib/types/retry-policy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Provider-owned request-retry policy configuration and resolution.
+ *
+ * Adapters expose one resolved policy per registered provider route; the
+ * optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
+ *
+ * @module @stackstackstack/dsh-llm/retry-policy
+ */
+import z from '@deepseek-ai/schemastery';
+/** Bounded exponential backoff with symmetric jitter around each local delay. */
+export interface BackoffConfig {
+    /** Initial local exponential-backoff delay in milliseconds (default 500). */
+    initialDelayMs?: number;
+    /** Maximum locally scheduled or accepted provider delay in milliseconds (default 10000). */
+    maxDelayMs?: number;
+    /** Symmetric random multiplier range around one (default 0.1). */
+    jitterRatio?: number;
+}
+/** Current bounded transient retry behavior for one provider route. */
+export interface NormalRetryPolicyConfig {
+    /** Retry only configured transient failure codes. */
+    mode: 'normal';
+    /** Maximum eligible retries after the first request (default 2). */
+    maxRetries?: number;
+    /** Stable failure codes eligible for this policy. */
+    retryableCodes?: string[];
+    /** Local exponential-backoff and jitter configuration. */
+    backoff?: BackoffConfig;
+}
+/** Unbounded retry behavior for every model-request failure on one provider route. */
+export interface AlwaysRetryPolicyConfig {
+    /** Retry every model-request failure until success, cancellation, or disposal. */
+    mode: 'always';
+    /** Local exponential-backoff and jitter configuration. */
+    backoff?: BackoffConfig;
+}
+/** Provider-owned model-request retry policy configuration. */
+export type RetryPolicyConfig = NormalRetryPolicyConfig | AlwaysRetryPolicyConfig;
+/** Fully resolved backoff shared by both retry modes. */
+export interface ResolvedRetryBackoff {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly jitterRatio: number;
+}
+/** Fully resolved bounded transient retry policy. */
+export interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {
+    readonly mode: 'normal';
+    readonly maxRetries: number;
+    readonly retryableCodes: readonly string[];
+}
+/** Fully resolved unbounded retry policy. */
+export interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {
+    readonly mode: 'always';
+}
+/** Immutable provider policy captured when its adapter route is registered. */
+export type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;
+/** Cordis schema embedded by each concrete provider configuration. */
+export declare const RetryPolicySchema: z<RetryPolicyConfig>;
+/**
+ * Validate, default, and detach one provider-owned retry policy.
+ * @param config - optional provider configuration; omission selects normal defaults.
+ * @param path - diagnostic path naming the provider config that owns the value.
+ * @returns an immutable policy safe to capture in provider registration state.
+ */
+export declare function resolveRetryPolicy(config: RetryPolicyConfig | undefined, path: string): ResolvedRetryPolicy;
+//# sourceMappingURL=retry-policy.d.ts.map

package/lib/types/retry-policy.js

@@ -0,0 +1,123 @@
+/**
+ * Provider-owned request-retry policy configuration and resolution.
+ *
+ * Adapters expose one resolved policy per registered provider route; the
+ * optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
+ *
+ * @module @stackstackstack/dsh-llm/retry-policy
+ */
+import z from '@deepseek-ai/schemastery';
+import { MAX_TIMER_DELAY_MS } from '@stackstackstack/dsh-timeout';
+import { EMPTY_RESPONSE_CODE } from "./error.js";
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 10_000;
+const DEFAULT_JITTER_RATIO = 0.1;
+const DEFAULT_RETRYABLE_CODES = Object.freeze([
+    EMPTY_RESPONSE_CODE,
+    'RATE_LIMIT',
+    'SERVER',
+    'TIMEOUT',
+    'TRANSPORT',
+]);
+const backoffSchema = z.object({
+    initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
+    maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
+    jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO),
+});
+const normalPolicySchema = z.object({
+    mode: z.const('normal').required(),
+    maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
+    retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
+    backoff: backoffSchema,
+});
+const alwaysPolicySchema = z.object({
+    mode: z.const('always').required(),
+    backoff: backoffSchema,
+});
+/** Cordis schema embedded by each concrete provider configuration. */
+export const RetryPolicySchema = z.union([
+    normalPolicySchema,
+    alwaysPolicySchema,
+]);
+const NORMAL_POLICY_KEYS = new Set([
+    'mode', 'maxRetries', 'retryableCodes', 'backoff',
+]);
+const ALWAYS_POLICY_KEYS = new Set(['mode', 'backoff']);
+const BACKOFF_KEYS = new Set(['initialDelayMs', 'maxDelayMs', 'jitterRatio']);
+function validateKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`${path}: unknown key "${key}"`);
+    }
+}
+function resolveBackoff(config, path) {
+    if (config !== undefined)
+        validateKeys(config, BACKOFF_KEYS, path);
+    const initialDelayMs = config?.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+    const maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const jitterRatio = config?.jitterRatio ?? DEFAULT_JITTER_RATIO;
+    if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (initialDelayMs > maxDelayMs) {
+        throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+    }
+    if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) {
+        throw new Error(`${path}.jitterRatio must be between 0 and 1`);
+    }
+    return Object.freeze({ initialDelayMs, maxDelayMs, jitterRatio });
+}
+/**
+ * Validate, default, and detach one provider-owned retry policy.
+ * @param config - optional provider configuration; omission selects normal defaults.
+ * @param path - diagnostic path naming the provider config that owns the value.
+ * @returns an immutable policy safe to capture in provider registration state.
+ */
+export function resolveRetryPolicy(config, path) {
+    if (config === undefined) {
+        return Object.freeze({
+            mode: 'normal',
+            maxRetries: DEFAULT_MAX_RETRIES,
+            retryableCodes: DEFAULT_RETRYABLE_CODES,
+            ...resolveBackoff(undefined, `${path}.backoff`),
+        });
+    }
+    switch (config.mode) {
+        case 'normal': {
+            validateKeys(config, NORMAL_POLICY_KEYS, path);
+            const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+            const retryableCodes = config.retryableCodes ?? [...DEFAULT_RETRYABLE_CODES];
+            if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) {
+                throw new Error(`${path}.maxRetries must be a non-negative safe integer`);
+            }
+            if (retryableCodes.length === 0) {
+                throw new Error(`${path}.retryableCodes must not be empty`);
+            }
+            if (retryableCodes.some(code => typeof code !== 'string' || code.length === 0)) {
+                throw new Error(`${path}.retryableCodes must contain only non-empty strings`);
+            }
+            if (new Set(retryableCodes).size !== retryableCodes.length) {
+                throw new Error(`${path}.retryableCodes must not contain duplicates`);
+            }
+            return Object.freeze({
+                mode: 'normal',
+                maxRetries,
+                retryableCodes: Object.freeze([...retryableCodes]),
+                ...resolveBackoff(config.backoff, `${path}.backoff`),
+            });
+        }
+        case 'always':
+            validateKeys(config, ALWAYS_POLICY_KEYS, path);
+            return Object.freeze({
+                mode: 'always',
+                ...resolveBackoff(config.backoff, `${path}.backoff`),
+            });
+        default:
+            throw new Error(`${path}.mode must be "normal" or "always"`);
+    }
+}
+//# sourceMappingURL=retry-policy.js.map