@everfur/sdk 0.1.0 → 0.3.0

package/dist/requestFunnel-CjW7uDuA.d.ts

@@ -0,0 +1,87 @@
+import { c as EverfurResult, b as EverfurErrorCode } from './EverfurResult-DN9pL2Ab.js';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CwbfmxzJ.js';
+import { d as EverfurRequest, F as Frame } from './config-DW60uRb9.js';
+import { A as AuthContext } from './identity-BMx2SUOM.js';
+
+/** Why the funnel stopped, or kept going. Every settle and every retry names one. */
+type FunnelRetryReason = 'ok' | 'aborted' | 'terminal-code' | 'attempts-exhausted' | 'daily-quota-exhausted' | 'burst-throttle' | 'retryable-code' | 'server-reset-beyond-budget';
+/**
+ * One funnel observation. Codes, statuses and ids ONLY: `wireMessage` is untrusted, healthcare-adjacent
+ * free text and must never leave the SDK through a telemetry sink, so it is structurally absent here.
+ */
+interface FunnelEvent {
+    /** Stable call-site name, e.g. `records.createRequest`. */
+    readonly call: string;
+    readonly phase: 'attempt' | 'retry' | 'settled' | 'stream.open';
+    readonly method: string;
+    readonly path: string;
+    /** 0-based attempt index. */
+    readonly attempt: number;
+    readonly ok?: boolean;
+    readonly code?: EverfurErrorCode;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` of the failing response, when the server sent one. The support-ticket join key. */
+    readonly requestId?: string;
+    /** The client-minted key, when this request carried one. Never a caller-supplied value. */
+    readonly idempotencyKey?: string;
+    readonly reason?: FunnelRetryReason;
+    readonly delayMs?: number;
+}
+interface FunnelObserver {
+    onEvent(event: FunnelEvent): void;
+}
+/** The timer seam, mirroring the shape core already uses, so a test drives the deadline deterministically. */
+interface FunnelTimers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+interface RequestFunnelDeps {
+    readonly auth: AuthContext;
+    readonly observer?: FunnelObserver;
+    readonly timers?: FunnelTimers;
+    /** Injected for deterministic jitter in tests. */
+    readonly rng?: () => number;
+    /** Injected so a test asserts the backoff schedule without burning wall-clock time. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Total attempts (initial try plus retries) before a retryable failure surfaces. */
+    readonly maxAttempts?: number;
+    /**
+     * The partner's `EverfurConfig.errorPolicy`. Consulted per FAILURE, because both of its knobs are keyed
+     * on the error code, which is not known until one arrives. It can only NARROW what the funnel would do
+     * on its own: see `decideRetry`.
+     */
+    readonly errorPolicy?: ErrorPolicyPort;
+    readonly unaryTimeoutMs?: number;
+    /**
+     * Idempotency-key minter. Injected ONLY for deterministic tests. It is never reachable from partner
+     * code and never fed a caller-supplied value: the whole point is that the SDK owns the key.
+     */
+    readonly newIdempotencyKey?: () => string;
+}
+interface FunnelSendOptions {
+    /**
+     * Force the idempotency decision. Omit to derive it from the method (mutating -> minted). Pass `false`
+     * for a mutating request the server does not dedup and that must not claim to be idempotent.
+     */
+    readonly idempotent?: boolean;
+    /** Per-call attempt ceiling override (a poll loop that owns its own budget passes 1). */
+    readonly maxAttempts?: number;
+}
+interface RequestFunnel {
+    /** The ONE unary path: headers, auth, deadline, retry, idempotency, request-id, telemetry. */
+    send<T>(call: string, req: EverfurRequest, opts?: FunnelSendOptions): Promise<EverfurResult<T>>;
+    /**
+     * Resolve device auth onto a request (bearer XOR publishable key, caller auth headers stripped).
+     * Rejects only when the TokenProvider fails; the caller settles that into its own terminal outcome.
+     */
+    authorize(req: EverfurRequest): Promise<EverfurRequest>;
+    /**
+     * Open an SSE stream. NOT idempotency-wrapped and NOT buffered: frames are yielded as they arrive.
+     * `req` is expected to have been through `authorize`.
+     */
+    stream(call: string, req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+}
+declare function createRequestFunnel(deps: RequestFunnelDeps): RequestFunnel;
+
+export { type FunnelSendOptions as F, type RequestFunnel as R, type RequestFunnelDeps as a, createRequestFunnel as c };

package/dist/requestFunnel-L-BQfi0z.d.cts

@@ -0,0 +1,87 @@
+import { c as EverfurResult, b as EverfurErrorCode } from './EverfurResult-DN9pL2Ab.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+import { d as EverfurRequest, F as Frame } from './config-CzTZGlfF.cjs';
+import { A as AuthContext } from './identity-DI4eVx9S.cjs';
+
+/** Why the funnel stopped, or kept going. Every settle and every retry names one. */
+type FunnelRetryReason = 'ok' | 'aborted' | 'terminal-code' | 'attempts-exhausted' | 'daily-quota-exhausted' | 'burst-throttle' | 'retryable-code' | 'server-reset-beyond-budget';
+/**
+ * One funnel observation. Codes, statuses and ids ONLY: `wireMessage` is untrusted, healthcare-adjacent
+ * free text and must never leave the SDK through a telemetry sink, so it is structurally absent here.
+ */
+interface FunnelEvent {
+    /** Stable call-site name, e.g. `records.createRequest`. */
+    readonly call: string;
+    readonly phase: 'attempt' | 'retry' | 'settled' | 'stream.open';
+    readonly method: string;
+    readonly path: string;
+    /** 0-based attempt index. */
+    readonly attempt: number;
+    readonly ok?: boolean;
+    readonly code?: EverfurErrorCode;
+    readonly httpStatus?: number;
+    /** `X-Request-ID` of the failing response, when the server sent one. The support-ticket join key. */
+    readonly requestId?: string;
+    /** The client-minted key, when this request carried one. Never a caller-supplied value. */
+    readonly idempotencyKey?: string;
+    readonly reason?: FunnelRetryReason;
+    readonly delayMs?: number;
+}
+interface FunnelObserver {
+    onEvent(event: FunnelEvent): void;
+}
+/** The timer seam, mirroring the shape core already uses, so a test drives the deadline deterministically. */
+interface FunnelTimers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+interface RequestFunnelDeps {
+    readonly auth: AuthContext;
+    readonly observer?: FunnelObserver;
+    readonly timers?: FunnelTimers;
+    /** Injected for deterministic jitter in tests. */
+    readonly rng?: () => number;
+    /** Injected so a test asserts the backoff schedule without burning wall-clock time. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Total attempts (initial try plus retries) before a retryable failure surfaces. */
+    readonly maxAttempts?: number;
+    /**
+     * The partner's `EverfurConfig.errorPolicy`. Consulted per FAILURE, because both of its knobs are keyed
+     * on the error code, which is not known until one arrives. It can only NARROW what the funnel would do
+     * on its own: see `decideRetry`.
+     */
+    readonly errorPolicy?: ErrorPolicyPort;
+    readonly unaryTimeoutMs?: number;
+    /**
+     * Idempotency-key minter. Injected ONLY for deterministic tests. It is never reachable from partner
+     * code and never fed a caller-supplied value: the whole point is that the SDK owns the key.
+     */
+    readonly newIdempotencyKey?: () => string;
+}
+interface FunnelSendOptions {
+    /**
+     * Force the idempotency decision. Omit to derive it from the method (mutating -> minted). Pass `false`
+     * for a mutating request the server does not dedup and that must not claim to be idempotent.
+     */
+    readonly idempotent?: boolean;
+    /** Per-call attempt ceiling override (a poll loop that owns its own budget passes 1). */
+    readonly maxAttempts?: number;
+}
+interface RequestFunnel {
+    /** The ONE unary path: headers, auth, deadline, retry, idempotency, request-id, telemetry. */
+    send<T>(call: string, req: EverfurRequest, opts?: FunnelSendOptions): Promise<EverfurResult<T>>;
+    /**
+     * Resolve device auth onto a request (bearer XOR publishable key, caller auth headers stripped).
+     * Rejects only when the TokenProvider fails; the caller settles that into its own terminal outcome.
+     */
+    authorize(req: EverfurRequest): Promise<EverfurRequest>;
+    /**
+     * Open an SSE stream. NOT idempotency-wrapped and NOT buffered: frames are yielded as they arrive.
+     * `req` is expected to have been through `authorize`.
+     */
+    stream(call: string, req: EverfurRequest, signal: AbortSignal): AsyncIterable<Frame>;
+}
+declare function createRequestFunnel(deps: RequestFunnelDeps): RequestFunnel;
+
+export { type FunnelSendOptions as F, type RequestFunnel as R, type RequestFunnelDeps as a, createRequestFunnel as c };

package/dist/{resolve-Dq_4_agU.d.ts → resolve-D4Ywz5OS.d.cts}

@@ -2,7 +2,7 @@
  * Every entitlement key the PUBLIC contract declares. Internal packs are absent by construction (the
  * projection redacts them), so this union is exactly what a partner surface may require.
  */
-type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "photo.checkup.execute" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "video.gait.execute";
+type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "partner_events.event.read" | "partner_events.inbound.create" | "pets.health.update" | "pets.profile.delete" | "pets.profile.update" | "photo.checkup.execute" | "records.clinic.create" | "records.record.create" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "televet.visit.create" | "video.gait.execute";
 
 interface LevelGrant {
     /** capability keys this level permits */
@@ -24,7 +24,7 @@ interface ResolvedEntitlements {
  */
 declare function resolveEntitlements(levels: readonly LevelGrant[]): ResolvedEntitlements;
 /** Coarse UI capability ids. NOT valid entitlement keys; bridged to resource keys by `requires`. */
-type CapabilityName = 'chat' | 'records' | 'video' | 'photo' | 'animations';
+type CapabilityName = 'chat' | 'records' | 'recordsClinic' | 'video' | 'photo' | 'animations' | 'televet';
 type DisabledLevel = 'contract' | 'partner_config' | 'user_entitlement' | 'version_floor' | 'kill_switch'
 /**
  * The SDK itself is not configured (no publishableKey, or no resolvable apiBaseUrl), so NOTHING can be
@@ -72,7 +72,13 @@ declare function requires(name: CapabilityName): readonly EverfurCapabilityKey[]
  */
 declare function deniedDecisionsFor(level: DisabledLevel, reason: string): readonly EntitlementDecision[];
 interface DecideOptions {
-    /** true during first resolve or while serving a stale value -> skeleton, never a flash of enabled UI. */
+    /**
+     * The first verdict of the scope is still being fetched. It pends ONLY a capability the decision set leaves
+     * undecided (a required key absent from it): a gate then shows its skeleton rather than the fail-closed
+     * off-state it would have to retract when the verdict lands. A capability every key of which the set already
+     * decides renders that decision at once, granted (chat, on the compiled floor) or denied (every key of a
+     * disabled runtime), so a verdict in flight never adds a loading step to what the floor has settled.
+     */
     readonly isPending?: boolean;
 }
 /**
@@ -83,4 +89,4 @@ interface DecideOptions {
  */
 declare function decideCapability(name: CapabilityName, decisions: readonly EntitlementDecision[], opts?: DecideOptions): CapabilityDecision;
 
-export { type CapabilityDecision as C, type DecideOptions as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDisabled as a, type CapabilityName as b, type DisabledLevel as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };
+export { type CapabilityName as C, type DisabledLevel as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDecision as a, type CapabilityDisabled as b, type DecideOptions as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };

package/dist/{resolve-Dq_4_agU.d.cts → resolve-D4Ywz5OS.d.ts}

@@ -2,7 +2,7 @@
  * Every entitlement key the PUBLIC contract declares. Internal packs are absent by construction (the
  * projection redacts them), so this union is exactly what a partner surface may require.
  */
-type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "photo.checkup.execute" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "video.gait.execute";
+type EverfurCapabilityKey = "animations.state.read" | "chat.conversation.read" | "chat.message.create" | "partner_events.event.read" | "partner_events.inbound.create" | "pets.health.update" | "pets.profile.delete" | "pets.profile.update" | "photo.checkup.execute" | "records.clinic.create" | "records.record.create" | "records.record.export" | "records.record.read" | "records.record.share" | "records.upload.create" | "televet.visit.create" | "video.gait.execute";
 
 interface LevelGrant {
     /** capability keys this level permits */
@@ -24,7 +24,7 @@ interface ResolvedEntitlements {
  */
 declare function resolveEntitlements(levels: readonly LevelGrant[]): ResolvedEntitlements;
 /** Coarse UI capability ids. NOT valid entitlement keys; bridged to resource keys by `requires`. */
-type CapabilityName = 'chat' | 'records' | 'video' | 'photo' | 'animations';
+type CapabilityName = 'chat' | 'records' | 'recordsClinic' | 'video' | 'photo' | 'animations' | 'televet';
 type DisabledLevel = 'contract' | 'partner_config' | 'user_entitlement' | 'version_floor' | 'kill_switch'
 /**
  * The SDK itself is not configured (no publishableKey, or no resolvable apiBaseUrl), so NOTHING can be
@@ -72,7 +72,13 @@ declare function requires(name: CapabilityName): readonly EverfurCapabilityKey[]
  */
 declare function deniedDecisionsFor(level: DisabledLevel, reason: string): readonly EntitlementDecision[];
 interface DecideOptions {
-    /** true during first resolve or while serving a stale value -> skeleton, never a flash of enabled UI. */
+    /**
+     * The first verdict of the scope is still being fetched. It pends ONLY a capability the decision set leaves
+     * undecided (a required key absent from it): a gate then shows its skeleton rather than the fail-closed
+     * off-state it would have to retract when the verdict lands. A capability every key of which the set already
+     * decides renders that decision at once, granted (chat, on the compiled floor) or denied (every key of a
+     * disabled runtime), so a verdict in flight never adds a loading step to what the floor has settled.
+     */
     readonly isPending?: boolean;
 }
 /**
@@ -83,4 +89,4 @@ interface DecideOptions {
  */
 declare function decideCapability(name: CapabilityName, decisions: readonly EntitlementDecision[], opts?: DecideOptions): CapabilityDecision;
 
-export { type CapabilityDecision as C, type DecideOptions as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDisabled as a, type CapabilityName as b, type DisabledLevel as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };
+export { type CapabilityName as C, type DisabledLevel as D, type EntitlementDecision as E, type LevelGrant as L, type ResolvedEntitlements as R, type CapabilityDecision as a, type CapabilityDisabled as b, type DecideOptions as c, decideCapability as d, deniedDecisionsFor as e, resolveEntitlements as f, requires as r };

package/dist/{runtime-BgQnA594.d.cts → runtime-B8s-_hv8.d.cts}

@@ -1,14 +1,16 @@
-import { E as EntitlementDecision, b as CapabilityName } from './resolve-Dq_4_agU.cjs';
-import { C as ClientBranding, F as FetchEntitlementsArgs, c as EntitlementResolution, w as PetProfileInput, R as RegisteredPet } from './petsRepository-BEGb97M9.cjs';
-import { E as EverfurResult } from './EverfurResult-D92-uL82.cjs';
-import { A as AuthContext, T as TokenProvider } from './identity-Brl-lDd6.cjs';
-import { U as UserRef, P as PetRef, a as ConversationId } from './ids-CJ1S6adf.cjs';
-import { T as TransportPort, k as EventSourceFactory } from './config-BSjBdxrZ.cjs';
+import { T as TransportPort, p as EventSourceFactory, G as SdkPlatform } from './config-CzTZGlfF.cjs';
+import { E as EntitlementDecision, C as CapabilityName } from './resolve-D4Ywz5OS.cjs';
+import { P as PetProfileInput, R as RegisteredPet, c as PetProfilePatch } from './casesRepository-DHwtGRYY.cjs';
+import { c as EverfurResult } from './EverfurResult-DN9pL2Ab.cjs';
+import { J as EntitlementResolution, C as ClientBranding, M as FetchEntitlementsArgs, c as EverfurThemeInput } from './entitlementRepository-DKdXFgTo.cjs';
+import { A as AuthContext, T as TokenProvider } from './identity-DI4eVx9S.cjs';
+import { U as UserRef, P as PetRef, C as ConversationId } from './ids-B2GAAifq.cjs';
 import { I as ImageCachePort, K as KvPort } from './cacheEpoch-DknKn3S0.cjs';
 import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
-import { E as ErrorPolicyPort, C as ChatController } from './ChatController-CpUMvvZf.cjs';
-import { F as FileHandle } from './FilePort-BabWrv7I.cjs';
+import { U as UploadPort, m as ChatController } from './ports-DEBzEhbp.cjs';
 import { C as CameraPort } from './CameraPort-Cv31Pz7g.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+import { U as UploadTransport } from './ports-BN6RHF9W.cjs';
 
 /**
  * Opt-in encrypted secret storage. Backed by a Keychain / Keystore native peer through an rn-layer adapter.
@@ -69,6 +71,13 @@ interface EntitlementPollerDeps {
     readonly update: (decisions: readonly EntitlementDecision[], branding: ClientBranding | null) => void;
     /** Optional region hint forwarded to the endpoint. */
     readonly region?: string;
+    /** Called synchronously as each fetch starts; the runtime marks the store pending for a scope's first one. */
+    readonly onFetch?: () => void;
+    /**
+     * Called when a fetch settles for the current scope, whatever the outcome (`updated` after `update`,
+     * `notModified`, `failed`, a thrown resolve). Not called for a fetch a refresh() or stop() superseded.
+     */
+    readonly onSettled?: () => void;
     readonly telemetry?: TelemetryPort;
     /** Test seam; defaults to global timers (unref'd so a live poll never pins a Node event loop). */
     readonly scheduler?: PollScheduler;
@@ -89,56 +98,15 @@ interface EntitlementPoller {
      * the next request must be UNCONDITIONAL (no If-None-Match) to force a fresh 200 for the new scope.
      */
     refresh(): void;
+    /**
+     * Settle ONE verdict fetch and report it: the poll already in flight when one is (the warm-up rides the
+     * first tick rather than racing it), otherwise a fresh one. On a poller that was never started it fetches
+     * once and arms nothing. Resolves null when a stop() or refresh() superseded the fetch before it landed.
+     */
+    prime(): Promise<EntitlementResolution | null>;
 }
 declare function createEntitlementPoller(deps: EntitlementPollerDeps): EntitlementPoller;
 
-/** The presigned POST/PUT policy returned by `/uploads/initiate` (SPEC-11b §2.1). */
-interface PresignedPolicy {
-    /** Absolute S3 endpoint URL to POST/PUT the bytes at. */
-    readonly url: string;
-    /** POST-policy form fields to include with the upload (empty for a plain PUT). */
-    readonly fields: Readonly<Record<string, string>>;
-    /** The owned-uploads-prefixed key the analyze call then references. */
-    readonly s3Key: string;
-    /** epoch seconds the policy expires; telemetry only. */
-    readonly expiresAt: number | null;
-}
-/**
- * The native upload seam. It PUTs `file` at the presigned `target` (SPEC-11b §2.1). `idempotencyKey` is reused
- * on every retry so a re-uploaded identical file dedupes server-side. A network failure REJECTS; the controller
- * normalizes that to a `mediaUploadFailed` and exposes a retake affordance (never auto-retried, SPEC-00 §3.2).
- *
- * NOTE: the spine `FilePort.presignedPut(file, { idempotencyKey, signal })` has no slot for the presigned
- * target; this richer port is the shape it must grow to. See the manifest gap note.
- */
-interface UploadPort {
-    presignedPut(file: FileHandle, opts: {
-        readonly target: PresignedPolicy;
-        readonly idempotencyKey: string;
-        readonly signal?: AbortSignal;
-    }): Promise<void>;
-}
-
-interface UploadPolicyWire {
-    readonly upload_id: string;
-    readonly upload_url: string;
-    readonly upload_fields: Readonly<Record<string, string>>;
-    readonly expires_in_seconds: number;
-    readonly max_content_length: number;
-}
-/**
- * Platform-specific: the rn adapter binds `expo-file-system` (uploadAsync) behind `optionalModule`; the
- * controller stays platform-neutral and never sees a native module. Resolves on S3's 204; rejects on a
- * policy 403 / stream failure, which the controller normalizes to a typed `mediaUploadFailed` (never a throw
- * that escapes the controller).
- */
-interface UploadTransport {
-    postMultipart(policy: UploadPolicyWire, file: FileHandle, opts: {
-        readonly onProgress?: (fraction: number) => void;
-        readonly signal?: AbortSignal;
-    }): Promise<void>;
-}
-
 /**
  * The public init config the host passes at EverfurProvider mount: the lean client subset
  * (publishableKey / apiBaseUrl / contractVersion / transport / debug) PLUS the host-seam ports. The client
@@ -189,8 +157,8 @@ interface RuntimeUser {
     readonly userRef: UserRef;
     readonly getToken: TokenProvider;
 }
-/** Opaque, permissive theme input; server branding merges ON TOP. Sanitized downstream. */
-type RuntimeTheme = Readonly<Record<string, string | number | boolean>>;
+/** The client `theme` prop as the provider hands it over (tolerant shape; sanitized by the theme provider). */
+type RuntimeTheme = EverfurThemeInput;
 interface CreateEverfurRuntimeInput {
     readonly config: EverfurRuntimeConfig;
     /** null => general (anonymous) mode: pk alone on the wire. */
@@ -221,6 +189,12 @@ interface CapabilityServices {
     readonly uploadTransport: UploadTransport;
     readonly imageCache: ImageCachePort;
     readonly kv: KvPort;
+    /**
+     * The API base URL the transport was built for (the config's, or the environment's), or null with an
+     * injected transport and no base URL. A relative link the server returns (a share link's path) is
+     * resolved against this origin, never opened raw.
+     */
+    readonly apiBaseUrl: string | null;
 }
 /**
  * The ONE ref-counted capability registry (SPEC-10 §7.4). Chat (the spine) is acquired by its typed method;
@@ -236,6 +210,12 @@ interface CapabilityRegistry {
     /** Chat is the spine capability; the registry constructs + ref-counts it directly. */
     acquireChat(scope: ChatScope): ChatController;
     releaseChat(controller: ChatController): void;
+    /**
+     * The live controller for a scope WITHOUT taking a hold, or null. A mount reads it synchronously on its
+     * first render so a scope `prepare()` primed renders its settled snapshot at once (no bootstrapping frame),
+     * then takes its hold through `acquireChat` in the commit effect as before.
+     */
+    peekChat(scope: ChatScope): ChatController | null;
     /**
      * Ref-counted acquire for the tree-shakeable capabilities. Two calls with the same (kind, scopeKey) under
      * the current epoch share ONE controller; the last release disposes it via `destroy`.
@@ -249,7 +229,12 @@ type ChatControllerRegistry = CapabilityRegistry;
 /** The already-resolved server verdict the capability hooks render (never re-folded here). */
 interface EntitlementSnapshot {
     readonly decisions: readonly EntitlementDecision[];
-    /** true during the first resolve or while serving a stale value -> skeleton, never a flash of UI. */
+    /**
+     * The first verdict of the current scope is still being fetched. `decideCapability` pends only what the
+     * decisions leave undecided: a key absent from the compiled floor (records) shows its skeleton, a key the
+     * floor grants (chat) renders at once. false once that fetch settles, whatever it settled to (a failure keeps
+     * the floor: fail-closed, never a skeleton left up), and always on a runtime that never fetched.
+     */
     readonly isPending: boolean;
     /**
      * Server-driven theme branding from the SAME entitlements body (orthogonal to decisions). null/absent =>
@@ -267,6 +252,48 @@ interface EntitlementStore {
     subscribe(listener: () => void): () => void;
     getSnapshot(): EntitlementSnapshot;
 }
+interface PrepareOptions {
+    /**
+     * The pet the first chat mount will be scoped to. Names it and the warm-up ALSO primes that scope's chat
+     * bootstrap (conversation + suggested prompts), held for the first mount. It registers nothing: a pet the
+     * partner has not upserted is registered with `registerPet`, not here.
+     */
+    readonly petRef?: PetRef;
+}
+/**
+ * `ready`: token minted (when a user is set), verdict resolved, chat primed (when a pet was named).
+ * `partial`: the token is ready but the verdict fetch or the chat prime settled to an error; surfaces still
+ * mount and self-heal (the poller re-polls, the first send recreates the conversation).
+ * `failed`: nothing authenticated can proceed: the mint failed, or the runtime is disposed / not configured.
+ */
+type PrepareStatus = 'ready' | 'partial' | 'failed';
+/** The settled warm-up. Each step carries the same `EverfurError` the surfaces settle to; nothing throws. */
+interface PrepareResult {
+    readonly status: PrepareStatus;
+    /** Milliseconds from the `prepare()` call to settlement: the login-to-ready number, also on telemetry. */
+    readonly durationMs: number;
+    /** The session-token mint. `ok` without a user (anonymous mode mints nothing). */
+    readonly session: EverfurResult<void>;
+    /** The entitlement verdict fetch into the store every gate reads. */
+    readonly entitlements: EverfurResult<void>;
+    /** The chat prime for `petRef`; absent when no pet was named. */
+    readonly chat?: EverfurResult<void>;
+}
+/**
+ * What a before-logout hook receives: who is leaving, and an auth context that keeps signing requests for the
+ * length of the hook budget even though the runtime drops the live identity synchronously right after the hooks
+ * start. The bearer is read from the identity's cache at that instant (or minted then, if none was cached), so a
+ * request the hook issues after an `await` still goes out under the signed-out user, never re-minted afterwards.
+ */
+interface BeforeLogoutContext {
+    readonly userRef: UserRef;
+    readonly auth: AuthContext;
+}
+/**
+ * A hook that runs when a signed-in user is about to leave (`logout()`, `setUser(null)`, a switch to another
+ * user). It may return a promise; `logout()` waits for it up to `LOGOUT_HOOK_BUDGET_MS` and never fails on it.
+ */
+type BeforeLogoutHook = (context: BeforeLogoutContext) => unknown;
 interface EverfurRuntime {
     readonly registry: CapabilityRegistry;
     /**
@@ -277,6 +304,19 @@ interface EverfurRuntime {
      * dead runtime.
      */
     readonly isDisposed: boolean;
+    /**
+     * Bumped by every re-scope. React surfaces put this in their acquire-effect deps so an imperative
+     * verb that changes no identity STRING still re-acquires.
+     *
+     * WHY THIS EXISTS. `logout()` on an already-anonymous runtime rotates the session id and re-scopes,
+     * but nothing a React effect watches changes: `userRef` is null on both sides, so the context memo
+     * republishes the same object and the effect never re-runs. The mounted surface kept serving the
+     * PREVIOUS anonymous visitor's scope, because the captured AuthContext holds the OLD session id and
+     * the widget plane derives anonymous identity as `anon-{session_id}`. On a shared device that is one
+     * visitor reading the last one's conversation. The epoch is the only thing that changes in that
+     * transition, so it is the only honest dep.
+     */
+    readonly scopeEpoch: number;
     readonly entitlements: EntitlementStore;
     /** null => logout: drops the cached bearer and re-scopes every open capability. */
     setUser(user: RuntimeUser | null): void;
@@ -290,6 +330,14 @@ interface EverfurRuntime {
      * calling `setUser(nextUser)`.
      */
     logout(): Promise<void>;
+    /**
+     * Run `hook` BEFORE a signed-in user leaves: on `logout()`, on `setUser(null)` and on a switch to another user,
+     * with the leaving user's `userRef` and a grace auth that still signs requests. Started synchronously, before
+     * the bearer drops and the capabilities re-scope; `logout()` additionally awaits it, bounded by
+     * `LOGOUT_HOOK_BUDGET_MS`, and a hook that throws, rejects or hangs never fails or delays sign-out beyond that.
+     * The per-user KV sweep runs after the hooks. Returns the unsubscribe. Nothing runs for an anonymous runtime.
+     */
+    onBeforeLogout(hook: BeforeLogoutHook): () => void;
     /** Re-scopes pet-bound controllers in the same commit. */
     setActivePet(pet: PetRef | null): void;
     /**
@@ -302,6 +350,19 @@ interface EverfurRuntime {
      * way to call it. This is that way. Idempotent: the route is an upsert keyed on `pet_ref`.
      */
     registerPet(pet: PetRef, profile?: PetProfileInput): Promise<EverfurResult<RegisteredPet>>;
+    /**
+     * Change part of a registered pet's profile (`PATCH /widget/v1/pets/{pet_ref}`). An omitted field is unchanged,
+     * `null` clears it. An unknown pet settles to the not-found error.
+     */
+    updatePet(pet: PetRef, patch: PetProfilePatch): Promise<EverfurResult<RegisteredPet>>;
+    /** Delete a pet profile (`DELETE /widget/v1/pets/{pet_ref}`); the server also retires its Records data. */
+    deletePet(pet: PetRef): Promise<EverfurResult<void>>;
+    /**
+     * Permanently erase everything Everfur holds for the current user (`DELETE /widget/v1/me`). A failure is
+     * retryable and a repeat call resumes the erasure. It does not sign the user out: call `logout()` or
+     * `setUser(null)` afterwards so mounted surfaces stop showing the erased data.
+     */
+    eraseUserData(): Promise<EverfurResult<void>>;
     /**
      * Replace the rendered entitlement verdict (a future poller / a manifest refresh). The SERVER stays
      * authoritative: this only feeds the render store, so the pending/enabled paths become reachable while a
@@ -310,6 +371,14 @@ interface EverfurRuntime {
     updateEntitlements(next: EntitlementSnapshot): void;
     /** Navigate / mount a prebuilt capability screen (host-routed). No-op at the spine. */
     open(capability: CapabilityName): void;
+    /**
+     * Warm up during the partner's OWN login so no Everfur surface adds a loading step of its own: mint the
+     * session token, resolve the entitlement verdict into the gate store and, when a pet is named, prime its
+     * chat bootstrap. Concurrent calls coalesce onto one run; a settled `ready` is returned again without I/O
+     * until the identity or pet re-scopes; a `partial` / `failed` run is retried on the next call. Never
+     * throws. Emits `sdk.prepare.timing` (`durationMs`, `status`) on the host telemetry sink once per run.
+     */
+    prepare(opts?: PrepareOptions): Promise<PrepareResult>;
     /**
      * Idempotent teardown: aborts in-flight capability requests, tears down every open SSE stream, and stops
      * the entitlement poller (an in-flight entitlement poll's result is DROPPED, not aborted mid-flight).
@@ -333,6 +402,12 @@ interface CreateRuntimeOptions {
      * through). Absent (web/expo, or an injected transport) => the fetch-body streaming path is used.
      */
     readonly eventSourceFactory?: EventSourceFactory;
+    /**
+     * Host-wiring seam: which entry point built this runtime, sent as X-Everfur-SDK-Platform on every request.
+     * The rn facade leaves it at the default; the web facade names `web`. Never read from partner config, for
+     * the reason on `SdkPlatform`.
+     */
+    readonly platform?: SdkPlatform;
 }
 /**
  * Construct the runtime once (EverfurProvider mount). Builds the transport (injected test seam, else the
@@ -346,4 +421,4 @@ interface CreateRuntimeOptions {
  */
 declare function createEverfurRuntime(input: CreateEverfurRuntimeInput, opts?: CreateRuntimeOptions): EverfurRuntime;
 
-export { type CapabilityKind as C, type EntitlementPoller as E, type LogLevel as L, MIN_POLL_INTERVAL_SECONDS as M, NULL_SECURE_STORE as N, type PollScheduler as P, type RuntimeTheme as R, type SecureStorePort as S, type TimerHandle as T, type UploadPort as U, type CapabilityRegistry as a, type CapabilityServices as b, type ChatControllerRegistry as c, type ChatScope as d, type CreateEverfurRuntimeInput as e, type CreateRuntimeOptions as f, type EntitlementPollerDeps as g, type EntitlementSnapshot as h, type EntitlementStore as i, type EverfurRuntime as j, type EverfurRuntimeConfig as k, type LogRecord as l, type LogSink as m, type RuntimeUser as n, createEntitlementPoller as o, createEverfurRuntime as p, type UploadTransport as q, type PresignedPolicy as r, type UploadPolicyWire as s };
+export { type BeforeLogoutContext as B, type CapabilityKind as C, type EntitlementSnapshot as E, type LogLevel as L, MIN_POLL_INTERVAL_SECONDS as M, NULL_SECURE_STORE as N, type PrepareOptions as P, type RuntimeTheme as R, type SecureStorePort as S, type TimerHandle as T, type LogRecord as a, type LogSink as b, type PrepareResult as c, type PrepareStatus as d, type BeforeLogoutHook as e, type CapabilityRegistry as f, type CapabilityServices as g, type ChatControllerRegistry as h, type ChatScope as i, type CreateEverfurRuntimeInput as j, type CreateRuntimeOptions as k, type EntitlementPoller as l, type EntitlementPollerDeps as m, type EntitlementStore as n, type EverfurRuntime as o, type EverfurRuntimeConfig as p, type PollScheduler as q, type RuntimeUser as r, createEntitlementPoller as s, createEverfurRuntime as t };