@chipmobilesdk/rn-ai 0.3.0 → 0.5.0

package/lib/typescript/module/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAiB,CAAC;AACjD,YAAY,EACX,QAAQ,EACR,cAAc,EACd,eAAe,EACf,aAAa,EACb,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,KAAK,EACL,aAAa,GACb,MAAM,oBAAiB,CAAC;AAEzB,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,4BAAyB,CAAC;AAC/F,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,4BAAyB,CAAC;AAI5F,YAAY,EACX,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,gBAAgB,GAChB,MAAM,uBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAoB,CAAC;AAE5F,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAsB,CAAC;AACvD,YAAY,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,eAAe,EACf,eAAe,GACf,MAAM,0BAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAe,CAAC;AAC1E,YAAY,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GAChB,MAAM,kBAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAsB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,8BAA2B,CAAC;AACpG,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA2B,CAAC"}

package/lib/typescript/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/typescript/module/react/hooks.d.ts

@@ -0,0 +1,37 @@
+import type { AiBehaviorState, AiClient, ChatRequest, QuotaSnapshot } from '../core/aiClient.js';
+import type { AiError } from '../diagnostics/errors.js';
+export type AiChatStatus = 'idle' | 'loading' | 'streaming' | 'done' | 'error' | 'rate-limited';
+export interface UseAiChatResult {
+    send(request: ChatRequest): void;
+    cancel(): void;
+    status: AiChatStatus;
+    /** Accumulated streamed text, flushed on an interval rather than per token. */
+    text: string;
+    error?: AiError;
+    retryAt?: Date;
+    quota?: QuotaSnapshot;
+}
+export interface UseAiChatOptions {
+    /**
+     * How often the accumulated text reaches the screen, in milliseconds.
+     *
+     * A model streams 30–100 tokens a second, and a render per token is 30–100
+     * renders of the whole transcript a second on the JS thread (PERF-12). At the
+     * default a long answer costs about 20 renders a second instead, and the last
+     * tokens are always flushed with the terminal state. `0` renders per token.
+     */
+    flushIntervalMs?: number;
+}
+export declare function useAiChat(client: AiClient, options?: UseAiChatOptions): UseAiChatResult;
+export interface UseAiQuotaResult {
+    quota?: QuotaSnapshot;
+    status: 'loading' | 'ready' | 'error';
+    refresh(): void;
+}
+export declare function useAiQuota(client: AiClient): UseAiQuotaResult;
+/**
+ * The client's behavior state (config source and whether AI is enabled), live:
+ * re-renders when the kill switch flips or the config state moves (AI-09).
+ */
+export declare function useAiBehaviorState(client: AiClient): AiBehaviorState;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/typescript/module/react/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,eAAe,EACf,QAAQ,EAER,WAAW,EACX,aAAa,EACb,MAAM,qBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAAuB,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;AAEhG,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,MAAM,IAAI,IAAI,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA2G3F;AAED,MAAM,WAAW,gBAAgB;IAChC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACtC,OAAO,IAAI,IAAI,CAAC;CAChB;AAgBD,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,gBAAgB,CAqC7D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,CAEpE"}

package/lib/typescript/module/transport/sseClient.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Minimal SSE reader over XMLHttpRequest (research R2).
+ *
+ * React Native's fetch does not reliably expose ReadableStream on Hermes, so
+ * we use XHR incremental text delivery (readyState LOADING + onprogress) —
+ * the same mechanism community SSE libraries use — with zero dependencies.
+ * The gateway never compresses SSE responses (contract), which keeps
+ * incremental delivery intact on both platforms.
+ */
+export interface SseRequest {
+    url: string;
+    method?: 'GET' | 'POST';
+    headers?: Record<string, string>;
+    /** JSON string body for POST requests. */
+    body?: string;
+    /** Hard limit on the whole request. Rarely right for a stream; prefer the two below. */
+    timeoutMs?: number;
+    /** Fails with `onError(0, 'timeout')` if response headers have not arrived by then. */
+    connectTimeoutMs?: number;
+    /** Fails with `onError(0, 'timeout')` when no chunk arrives for this long. Reset per chunk. */
+    idleTimeoutMs?: number;
+}
+/** What the response said besides its body. Absent for a failure with no response. */
+export interface SseResponseInfo {
+    /** A response header, or null. `Retry-After` is the one this package reads. */
+    getHeader(name: string): string | null;
+}
+export interface SseHandlers {
+    /** One call per `data:` event payload (raw string, already de-framed). */
+    onData(payload: string): void;
+    /** Stream closed normally (transport level; `[DONE]` handling is the caller's). */
+    onEnd(): void;
+    /** Transport or HTTP error. `status` is 0 for network failures. */
+    onError(status: number, bodyText: string, response?: SseResponseInfo): void;
+}
+export interface SseHandle {
+    cancel(): void;
+}
+/**
+ * The transport port: how this package makes a streaming request.
+ *
+ * A published port rather than `typeof requestSse`, so the default reader's
+ * own signature is not part of the public API (AI-18): an app may inject its
+ * own transport, and this package may change how `requestSse` is written
+ * without that being a breaking change.
+ */
+export type StreamTransport = (request: SseRequest, handlers: SseHandlers) => SseHandle;
+/**
+ * Parse complete `data:` events out of `text` starting at `fromIndex`.
+ *
+ * Both line endings are accepted. A proxy that normalises to CRLF — an API
+ * gateway or a corporate middlebox — used to make every event invisible until
+ * the stream closed, because only `\n\n` counted as a separator (AI-22).
+ */
+export declare function drainSseEvents(text: string, fromIndex: number, emit: (payload: string) => void): number;
+export declare function requestSse(request: SseRequest, handlers: SseHandlers): SseHandle;
+//# sourceMappingURL=sseClient.d.ts.map

package/lib/typescript/module/transport/sseClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseClient.d.ts","sourceRoot":"","sources":["../../../../src/transport/sseClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC/B,+EAA+E;IAC/E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC3B,0EAA0E;IAC1E,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mFAAmF;IACnF,KAAK,IAAI,IAAI,CAAC;IACd,mEAAmE;IACnE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CAC5E;AAED,MAAM,WAAW,SAAS;IACzB,MAAM,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,KAAK,SAAS,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,MAAM,CAiBR;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,GAAG,SAAS,CA0GhF"}

package/lib/typescript/module/transport/timeouts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Time limits for every network call the client makes (AI-04).
+ *
+ * Without them a stalled mobile connection left `useAiChat` in `loading` or
+ * `streaming`, and `useAiQuota` in `loading`, until the user gave up.
+ */
+export interface AiTimeouts {
+    /** Request sent → response headers received, for the chat stream. */
+    connectMs: number;
+    /** Longest silence allowed between two chunks of the chat stream. */
+    idleMs: number;
+    /** Behavior-config fetch, including reading the body. */
+    configMs: number;
+    /** Quota fetch, including reading the body. */
+    quotaMs: number;
+}
+/**
+ * The gateway sends headers only once the model has answered, so `connectMs`
+ * also covers time to first token on a large image prompt.
+ */
+export declare const DEFAULT_AI_TIMEOUTS: AiTimeouts;
+/**
+ * Runs `run` with an abort signal and rejects with `onTimeout()` after `ms`.
+ * The race matters as much as the signal: an injected `fetchFn` (or an old
+ * polyfill) may ignore the signal entirely.
+ */
+export declare function withTimeout<T>(ms: number, run: (signal: AbortSignal | undefined) => Promise<T>, onTimeout: () => Error): Promise<T>;
+//# sourceMappingURL=timeouts.d.ts.map

package/lib/typescript/module/transport/timeouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../../../src/transport/timeouts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IAC1B,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,UAKjC,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,EACpD,SAAS,EAAE,MAAM,KAAK,GACpB,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/package.json

@@ -1,15 +1,23 @@
 {
 	"name": "@chipmobilesdk/rn-ai",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"private": false,
 	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"source": "./src/index.ts",
+	"main": "./lib/commonjs/index.js",
+	"module": "./lib/module/index.js",
+	"types": "./lib/typescript/commonjs/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
+			"chipmobilesdk-source": "./src/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/index.d.ts",
+				"default": "./lib/module/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/index.d.ts",
+				"default": "./lib/commonjs/index.js"
+			}
 		}
 	},
 	"files": [
@@ -17,23 +25,43 @@
 		"!src/**/__tests__",
 		"skills",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"lib"
 	],
 	"sideEffects": false,
 	"scripts": {
+		"build": "bob build",
 		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
-		"pack:check": "npm pack --dry-run"
+		"pack:check": "npm pack --dry-run",
+		"prepack": "npm run build"
 	},
 	"dependencies": {
-		"@chipmobilesdk/rn-core": "^0.1.0"
+		"@chipmobilesdk/rn-core": "^0.2.0"
 	},
 	"peerDependencies": {
-		"@chipmobilesdk/rn-auth": ">=0.2.0",
-		"react": ">=19",
-		"react-native": ">=0.85"
+		"react": ">=19"
 	},
 	"publishConfig": {
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"
+	},
+	"react-native-builder-bob": {
+		"source": "src",
+		"output": "lib",
+		"targets": [
+			[
+				"commonjs",
+				{
+					"esm": true
+				}
+			],
+			[
+				"module",
+				{
+					"esm": true
+				}
+			],
+			"typescript"
+		]
 	}
 }

package/skills/sdk-rn-ai/SKILL.md

@@ -19,6 +19,14 @@ and a typed error model.
 - Handling AI request failure, cancellation, or streaming state
 - Localising AI-related user messages
 
+## The token source is an interface, not rn-auth
+
+`createAiClient` takes `auth: TokenProvider` — one method,
+`requestAccessToken(resourceKey, { forceRefresh })`. rn-auth's controller satisfies it,
+so passing `auth` straight in is the usual wiring, but rn-auth is not a dependency or a
+peer of this package: an app with its own token source implements the interface and
+installs nothing extra. Do not reach for anything else on the object you pass.
+
 ## The app owns more than you expect
 
 This package deliberately does not handle everything. The README has an
@@ -31,18 +39,49 @@ read it before assuming a behaviour is built in.
 screen unmounts, otherwise the response resolves against a dead component. Verify
 teardown on every screen that uses it.
 
+## Cache the config, or every launch waits for the network
+
+`createAiClient({ storage })` takes an `AiConfigCache`. Without one the behavior config
+lives in memory only, so each cold start blocks the first chat on a network fetch.
+`configCacheFromKeyValue(port)` adapts rn-core's `KeyValuePort` (MMKV through
+`openDurable`), which is how the demo app wires it.
+
+## What the config document is allowed to say
+
+`configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the
+document must name the same `appId`, and its `schemaVersion` must be one the installed
+release supports. `allowedHosts` pins the hosts the document may point at. A document
+that breaks any of these is a `config-unavailable` error, not a request sent anyway:
+this is where the app's bearer token would go.
+
+## Errors carry a reason
+
+`AiError.code` is what happened; `AiError.cause` is the code underneath (the gateway's,
+or rn-auth's). `network` means the request never arrived and a retry may work;
+`session-expired` means sign-in is needed; `not-entitled` means premium. Use
+`messageKeyForError(error)` for the copy — one key per code, nothing to map by hand.
+
 ## Public API
 
 Runtime:
 
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
+- `createAiClient(...)` — the client: `chat`, `getQuota`, `lastQuota`, `reloadConfig`,
+  `getBehaviorState`, `subscribe`
+- `useAiChat(client, { flushIntervalMs })` → `UseAiChatResult` (`send`, `cancel`,
+  `status`, `text`, `error`, `retryAt`, `quota`), with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`; `useAiBehaviorState(...)` for the kill switch
+- `configCacheFromKeyValue(port)`, `SUPPORTED_SCHEMA_VERSION`
 - `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+- `aiMessages`, `aiMessage`, `aiMessageSet`, `messageKeyForError`
+- `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`, `SSE_DONE_SENTINEL` — the gateway contract
 
 Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
 
+## Streamed text is batched
+
+`useAiChat` flushes accumulated deltas every 50 ms rather than rendering per token; pass
+`flushIntervalMs: 0` for per-token rendering. Do not add your own buffering on top.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:

package/src/config/behaviorConfig.ts

@@ -1,4 +1,4 @@
-import { createListenerSet, createSingleFlight } from '@chipmobilesdk/rn-core';
+import { createListenerSet, createSingleFlight, type KeyValuePort } from '@chipmobilesdk/rn-core';
 
 import { AiError } from '../diagnostics/errors';
 import { DEFAULT_AI_TIMEOUTS, withTimeout } from '../transport/timeouts';
@@ -35,18 +35,84 @@ export class MemoryConfigCache implements AiConfigCache {
 	}
 }
 
+/**
+ * An `AiConfigCache` over rn-core's synchronous `KeyValuePort` (AI-10).
+ *
+ * Without a durable cache every launch waits for the network before the first
+ * chat, which is exactly what the cache-first design exists to avoid. Open the
+ * port the way the app opens its other durable state, for example
+ * `openDurable(() => createMMKV({ id: 'app' }))`.
+ */
+export function configCacheFromKeyValue(port: KeyValuePort): AiConfigCache {
+	return {
+		async get(key) {
+			return port.getString(key) ?? null;
+		},
+		async set(key, value) {
+			port.set(key, value);
+		},
+	};
+}
+
 export type BehaviorState = 'unloaded' | 'ready-network' | 'ready-cache' | 'unavailable';
 
+/** The newest document layout this release understands. */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+
+/** Bounds on the remote-configured recovery, so a bad document cannot stall a chat. */
+const MAX_SILENT_RETRIES = 5;
+const MIN_REFRESH_TTL_SECONDS = 30;
+const DEFAULT_REFRESH_TTL_SECONDS = 21_600;
+
 const numbers = (value: unknown): number[] | undefined =>
 	Array.isArray(value) ? value.filter((n): n is number => Number.isFinite(n)) : undefined;
 
-/** Parse + validate; unknown fields ignored (forward compatibility). */
-export function parseBehaviorConfig(json: string): AppBehaviorConfig {
+const positiveInt = (value: unknown, fallback: number): number =>
+	typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+
+function invalid(reason: string): never {
+	throw new AiError('config-unavailable', `behavior config ${reason}`);
+}
+
+/** https, or http on a development machine: a bearer token travels to this host. */
+export function isTrustedUrl(url: string): boolean {
+	if (/^https:\/\//i.test(url)) {
+		return true;
+	}
+	return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+
+function hostOf(url: string): string {
+	return url
+		.replace(/^[a-z]+:\/\//i, '')
+		.split(/[/:?#]/)[0]!
+		.toLowerCase();
+}
+
+export interface ParseBehaviorConfigOptions {
+	/** The app this document must be for; a document for another app is refused. */
+	expectedAppId?: string;
+	/** Hosts `api.baseUrl` may name. Any host is accepted when omitted. */
+	allowedHosts?: readonly string[];
+}
+
+/**
+ * Parse + validate; unknown fields ignored (forward compatibility).
+ *
+ * Every field this package acts on is checked here, because the document is
+ * remote and the alternative is a TypeError inside an XHR callback, a revalidate
+ * on every single request, or a bearer token sent to a host nobody vetted
+ * (AI-06, AI-07).
+ */
+export function parseBehaviorConfig(
+	json: string,
+	options: ParseBehaviorConfigOptions = {},
+): AppBehaviorConfig {
 	let raw: Record<string, unknown>;
 	try {
 		raw = JSON.parse(json) as Record<string, unknown>;
 	} catch {
-		throw new AiError('config-unavailable', 'behavior config is not valid JSON');
+		invalid('is not valid JSON');
 	}
 	const api = raw.api as Partial<AppBehaviorConfig['api']> | undefined;
 	if (
@@ -54,17 +120,42 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		typeof api?.baseUrl !== 'string' ||
 		!Array.isArray(api.scopes)
 	) {
-		throw new AiError('config-unavailable', 'behavior config is missing required fields');
+		invalid('is missing required fields');
+	}
+
+	const schemaVersion = positiveInt(raw.schemaVersion, 1);
+	if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
+		// A newer layout may mean something different by the same field names.
+		invalid(`declares schema version ${schemaVersion}, newer than ${SUPPORTED_SCHEMA_VERSION}`);
+	}
+	if (options.expectedAppId !== undefined && raw.appId !== options.expectedAppId) {
+		// The cache key and the request path carry the app id; a document for
+		// another app would send this app's traffic somewhere else entirely.
+		invalid(`is for another app (${raw.appId})`);
+	}
+
+	const baseUrl = api.baseUrl.replace(/\/$/, '');
+	if (!isTrustedUrl(baseUrl)) {
+		invalid('names a baseUrl that is not https');
 	}
+	if (options.allowedHosts && !options.allowedHosts.includes(hostOf(baseUrl))) {
+		invalid(`names a baseUrl outside the allowed hosts (${hostOf(baseUrl)})`);
+	}
+
 	const recovery = (raw.recovery ?? {}) as Partial<AppBehaviorConfig['recovery']>;
 	const features = (raw.features ?? {}) as Partial<AppBehaviorConfig['features']>;
 	return {
-		schemaVersion: Number(raw.schemaVersion ?? 1),
+		schemaVersion,
 		appId: raw.appId,
-		configVersion: Number(raw.configVersion ?? 0),
-		refreshTtlSeconds: Number(raw.refreshTtlSeconds ?? 21600),
+		configVersion: positiveInt(raw.configVersion, 0),
+		// A TTL that was NaN made `isFresh` false forever, so every request
+		// revalidated over the network (AI-06).
+		refreshTtlSeconds: Math.max(
+			MIN_REFRESH_TTL_SECONDS,
+			positiveInt(raw.refreshTtlSeconds, DEFAULT_REFRESH_TTL_SECONDS),
+		),
 		api: {
-			baseUrl: api.baseUrl.replace(/\/$/, ''),
+			baseUrl,
 			scopes: api.scopes.filter((s): s is string => typeof s === 'string'),
 			supportsStreaming: api.supportsStreaming !== false,
 		},
@@ -73,9 +164,12 @@ export function parseBehaviorConfig(json: string): AppBehaviorConfig {
 		// throw a TypeError inside the XHR error callback, where nothing caught it.
 		recovery: {
 			reloadOnHttpStatus: numbers(recovery.reloadOnHttpStatus) ?? [404, 410],
-			maxSilentRetries: Number.isFinite(recovery.maxSilentRetries)
-				? Number(recovery.maxSilentRetries)
-				: 1,
+			maxSilentRetries: Math.min(
+				MAX_SILENT_RETRIES,
+				Number.isFinite(recovery.maxSilentRetries)
+					? Math.max(0, Number(recovery.maxSilentRetries))
+					: 1,
+			),
 			retryBackoffMs: numbers(recovery.retryBackoffMs) ?? [500, 2000],
 		},
 		features: { aiEnabled: features.aiEnabled !== false },
@@ -96,6 +190,8 @@ export interface BehaviorConfigDeps {
 	now?: () => number;
 	/** Limit on one config fetch, body included. Defaults to 10 s. */
 	timeoutMs?: number;
+	/** Hosts the document's `api.baseUrl` may name. */
+	allowedHosts?: readonly string[];
 }
 
 /**
@@ -113,7 +209,7 @@ export class BehaviorConfigManager {
 	 * chat and a quota call together, and each used to fetch the config itself.
 	 */
 	private readonly cacheRead = createSingleFlight<void>();
-	private readonly networkFetch = createSingleFlight<AppBehaviorConfig | undefined>();
+	private readonly networkFetch = createSingleFlight<AppBehaviorConfig>();
 	private currentState: BehaviorState = 'unloaded';
 	private readonly stateListeners = createListenerSet<[]>();
 
@@ -134,12 +230,24 @@ export class BehaviorConfigManager {
 	}
 
 	constructor(private deps: BehaviorConfigDeps) {
+		if (!isTrustedUrl(deps.configUrl)) {
+			// The document decides where the tokens go, so where it comes from
+			// matters as much (AI-07).
+			throw new AiError('config-unavailable', 'configUrl must be https');
+		}
 		this.cacheKey = `rn-ai:config:${deps.appId}`;
 		this.cache = deps.cache ?? new MemoryConfigCache();
 		this.fetchFn = deps.fetchFn ?? fetch;
 		this.now = deps.now ?? Date.now;
 	}
 
+	private parse(json: string): AppBehaviorConfig {
+		return parseBehaviorConfig(json, {
+			expectedAppId: this.deps.appId,
+			...(this.deps.allowedHosts ? { allowedHosts: this.deps.allowedHosts } : {}),
+		});
+	}
+
 	private isFresh(envelope: CacheEnvelope, config: AppBehaviorConfig): boolean {
 		return this.now() - envelope.fetchedAt < config.refreshTtlSeconds * 1000;
 	}
@@ -154,44 +262,62 @@ export class BehaviorConfigManager {
 		if (!stored) return;
 		try {
 			const envelope = JSON.parse(stored) as CacheEnvelope;
-			this.current = { config: parseBehaviorConfig(envelope.configJson), envelope };
+			this.current = { config: this.parse(envelope.configJson), envelope };
 			this.setState('ready-cache');
 		} catch {
 			// corrupted cache entries are ignored, not fatal
 		}
 	}
 
-	private fetchNetwork(): Promise<AppBehaviorConfig | undefined> {
+	private fetchNetwork(): Promise<AppBehaviorConfig> {
 		return this.networkFetch.run(() => this.fetchFromNetwork());
 	}
 
-	private async fetchFromNetwork(): Promise<AppBehaviorConfig | undefined> {
+	/** One attempt; `conditional` sends the stored ETag when there is one. */
+	private async fetchOnce(
+		conditional: boolean,
+	): Promise<{ status: number; text: string; etag?: string }> {
 		const headers: Record<string, string> = {};
-		if (this.current?.envelope.etag) {
-			headers['If-None-Match'] = this.current.envelope.etag;
+		const etag = this.current?.envelope.etag;
+		if (conditional && etag) {
+			headers['If-None-Match'] = etag;
 		}
 		// Bounded: with no cache, a hung fetch used to block every chat and quota call.
-		const { response, configJson } = await withTimeout(
+		return withTimeout(
 			this.deps.timeoutMs ?? DEFAULT_AI_TIMEOUTS.configMs,
 			async signal => {
-				const res = await this.fetchFn(this.deps.configUrl, { headers, signal });
-				return { response: res, configJson: res.ok && res.status !== 304 ? await res.text() : '' };
+				const response = await this.fetchFn(this.deps.configUrl, { headers, signal });
+				return {
+					status: response.status,
+					text: response.ok && response.status !== 304 ? await response.text() : '',
+					etag: response.headers.get('etag') ?? undefined,
+				};
 			},
 			() => new AiError('config-unavailable', 'config fetch timed out'),
 		);
-		if (response.status === 304 && this.current) {
-			this.current.envelope.fetchedAt = this.now();
-			await this.persist(this.current.envelope);
-			this.setState('ready-network');
-			return this.current.config;
+	}
+
+	private async fetchFromNetwork(): Promise<AppBehaviorConfig> {
+		let result = await this.fetchOnce(true);
+		if (result.status === 304) {
+			if (this.current) {
+				this.current.envelope.fetchedAt = this.now();
+				await this.persist(this.current.envelope);
+				this.setState('ready-network');
+				return this.current.config;
+			}
+			// Not-modified against a cache that is no longer there (it was cleared,
+			// or it failed to parse). Asking again without the ETag is the answer;
+			// reporting `config fetch failed: 304` was not (AI-17).
+			result = await this.fetchOnce(false);
 		}
-		if (!response.ok) {
-			throw new AiError('config-unavailable', `config fetch failed: ${response.status}`);
+		if (result.status < 200 || result.status >= 300) {
+			throw new AiError('config-unavailable', `config fetch failed: ${result.status}`);
 		}
-		const config = parseBehaviorConfig(configJson);
+		const config = this.parse(result.text);
 		const envelope: CacheEnvelope = {
-			configJson,
-			etag: response.headers.get('etag') ?? undefined,
+			configJson: result.text,
+			etag: result.etag,
 			fetchedAt: this.now(),
 		};
 		this.current = { config, envelope };
@@ -218,16 +344,11 @@ export class BehaviorConfigManager {
 			return this.current.config;
 		}
 		try {
-			const fetched = await this.fetchNetwork();
-			if (fetched) return fetched;
+			return await this.fetchNetwork();
 		} catch (e) {
 			if (this.current) return this.current.config; // stale beats broken
 			this.setState('unavailable');
 			throw e instanceof AiError ? e : new AiError('config-unavailable', String(e));
 		}
-		// fetchNetwork only returns undefined when a 304 raced an empty cache.
-		if (this.current) return (this.current as { config: AppBehaviorConfig }).config;
-		this.setState('unavailable');
-		throw new AiError('config-unavailable', 'no configuration available');
 	}
 }