@maximem/synap-js-sdk 0.4.7 → 0.5.1

package/dist/errors-Bl3vY1eb.d.cts

@@ -0,0 +1,382 @@
+/**
+ * In-memory TTL cache for context bundles pushed over gRPC.
+ *
+ * Port of `maximem_synap/cache/anticipation_cache.py`.
+ *
+ * ## Why this is a faithful port and not a simplification
+ *
+ * `@maximem/synap-vercel-adk` already contains a native TS anticipation cache,
+ * and it is a simplification: a hardcoded 30-minute TTL, a plain BM25 threshold
+ * with no per-query derivation, and none of the gates below. Shipping that as
+ * the SDK's cache would mean two retrieval behaviors under one brand, which is
+ * gotcha G-C. Every gate here exists because a specific eval failed without it:
+ *
+ *  - **Recall bypass** runs BEFORE scoring. The measured false hit scored 2.86
+ *    at coverage 1.00, so no score-side gate could ever have caught it.
+ *  - **The novel-term gate** is suppressed below a 200-stem corpus, because at
+ *    cold start ordinary English trips it on nearly every query.
+ *  - **The per-query threshold** scales down for short queries, which otherwise
+ *    cannot reach the nominal score at all.
+ *  - **The coverage gate** catches a bundle that clears BM25 on one shared
+ *    token ("account") while lacking the asked-for fact.
+ *
+ * All thresholds come from the shared behavior contract.
+ */
+/** Sentinel scope that matches any requester. */
+declare const ANY_SCOPE = "_any";
+interface BundleItem {
+    item_id?: string;
+    content?: string;
+    [key: string]: unknown;
+}
+interface ContextBundle {
+    bundleId: string;
+    entityId?: string | null;
+    conversationId?: string | null;
+    itemsByType: Record<string, BundleItem[]>;
+    /** Server hint; may only SHORTEN the global TTL, never extend it. */
+    ttlHintSeconds?: number | null;
+    /** Which anticipation pattern produced this bundle. Diagnostics only. */
+    bundleType?: string | null;
+    /** The queries the server anticipated. Diagnostics only. */
+    searchQueries?: readonly string[] | null;
+    /**
+     * The scope rung the server retrieved this bundle at, as `rungKey` writes
+     * one. Absent from anything an older server sent, which reads as "named no
+     * rung" rather than as "matches anything".
+     */
+    scopeRung?: string | null;
+}
+interface LookupResult {
+    itemsByType: Record<string, BundleItem[]>;
+    bundleIds: string[];
+    score: number;
+    coverage: number;
+}
+interface LookupParams {
+    searchQuery?: readonly string[] | null;
+    entityId?: string | null;
+    customerId?: string | null;
+    clientId?: string | null;
+    conversationId?: string | null;
+    /**
+     * The rung this request names, from its `scope_path`. A SECOND, independent
+     * dimension and NOT another tier of the entity funnel: the funnel widens and
+     * the rung does not, because a rung is a boundary and a boundary that widens
+     * is not one.
+     */
+    scopeRung?: string | null;
+    maxItems?: number;
+}
+type ExitReason = 'empty' | 'recall_bypass' | 'no_query_tokens' | 'novel_term_gate' | 'empty_corpus' | 'no_items_above_threshold' | 'coverage_gate' | 'hit';
+interface LookupTelemetry {
+    searchQuery: string[];
+    entityId: string | null;
+    customerId: string | null;
+    clientId: string | null;
+    conversationId: string | null;
+    scopeRung: string | null;
+    scopeFilterAccepted: string[];
+    novelTermRatio: number | null;
+    bm25Threshold: number | null;
+    bm25QueryTokens: string[];
+    itemsPicked: unknown[];
+    itemsRejected: unknown[];
+    coverage: number | null;
+    hit: boolean;
+    exitReason: ExitReason;
+}
+interface SnapshotItemPreview {
+    type: string;
+    scope: string | null;
+    content: string;
+}
+interface SnapshotItemRecord {
+    bundle_id: string;
+    item_type: string;
+    tokens: string[];
+    content: string;
+}
+interface SnapshotBundle {
+    bundle_id: string;
+    entity_id: string;
+    conversation_id: string | null;
+    bundle_type: string | null;
+    search_queries: string[];
+    scope_counts: Record<string, number>;
+    total_items: number;
+    items: SnapshotItemPreview[];
+}
+interface AnticipationCacheSnapshot {
+    total_entries: number;
+    total_item_records: number;
+    scope_breakdown_overall: Record<string, number>;
+    corpus_vocab_size: number;
+    corpus_vocab_sample: string[];
+    item_records: SnapshotItemRecord[];
+    bundles: SnapshotBundle[];
+}
+interface AnticipationCacheOptions {
+    ttlSeconds?: number;
+    maxBundles?: number;
+    /** Injected in tests. Defaults to a monotonic clock. */
+    now?: () => number;
+    onLookup?: (telemetry: LookupTelemetry) => void;
+}
+declare class AnticipationCache {
+    #private;
+    private readonly ttlSeconds;
+    private readonly maxBundles;
+    private readonly now;
+    private readonly onLookup;
+    private entries;
+    private items;
+    private corpusVocab;
+    private bm25;
+    private bm25Dirty;
+    constructor(options?: AnticipationCacheOptions);
+    get size(): number;
+    get itemCount(): number;
+    store(bundle: ContextBundle): void;
+    lookup(params: LookupParams): LookupResult | null;
+    /**
+     * Drop this entity's bundles after a write, so the cache stops serving a
+     * pre-write view. Gated on the flag: this is the write-path hook.
+     */
+    invalidateEntity(entityId: string): number;
+    /**
+     * Unconditionally drop this entity's bundles. Backs `cache.clear_user` and
+     * `cache.clear_customer`, which are explicit user requests and so are not
+     * gated on the invalidate-on-write flag.
+     */
+    dropEntity(entityId: string): number;
+    /**
+     * A read-only diagnostic projection of the cache.
+     *
+     * Backs `client.anticipation_cache_snapshot()` and mirrors Python's shape
+     * key for key, including snake_case keys: this output gets logged, diffed
+     * and pasted into issues across both SDKs, so it is a wire format.
+     *
+     * Note the 140-character content previews. That is Python's literal, and it
+     * is deliberately NOT the 120 of `telemetry.content_preview_chars` from the
+     * contract, which caps lookup telemetry rather than this snapshot.
+     */
+    snapshot(): AnticipationCacheSnapshot;
+    /**
+     * The freshest `user_summary` bundle for this entity, or null.
+     *
+     * `entityId` is REQUIRED, and a missing one refuses the lookup rather than
+     * falling back to the freshest summary across all users. Python hardened this
+     * for exactly that reason: the permissive version could splice user A's
+     * summary into user B's response on the conversation-scope path.
+     */
+    lookupUserSummary(entityId: string | null | undefined, scopeRung?: string | null): Record<string, unknown> | null;
+    /**
+     * Drop every bundle belonging to one conversation.
+     *
+     * Backs the `compaction_update` signal on the Listen stream: a compaction
+     * rewrites the conversation's summary, so any bundle built from the previous
+     * state is stale and must not keep serving for the rest of its TTL.
+     *
+     * Unlike `dropEntity`, client-scope bundles are NOT spared: a bundle is only
+     * dropped here if it is bound to this specific conversation, and a shared
+     * client-scope bundle has no conversation id to match.
+     */
+    dropConversation(conversationId: string): number;
+    clear(): void;
+    private miss;
+    private fire;
+    private freshnessLookup;
+    /**
+     * The widened scope-match set for a request.
+     *
+     * A narrower-scope request also matches broader-scope bundles for the same
+     * customer or client. Falsy ids are dropped so an empty customer_id cannot
+     * accidentally match bundles keyed at "".
+     */
+    private buildAcceptedScope;
+    /**
+     * The rung is checked FIRST and it never widens. Everything else here widens
+     * deliberately: a user-scope request reaches customer-shared bundles, and a
+     * conversation-scope request reaches user-scope ones. A rung is the opposite
+     * kind of thing, so it is checked before the tiers and no amount of widening
+     * can put a cross-rung bundle back in.
+     */
+    private getValidBundleIds;
+    private effectiveTtl;
+    private evictExpired;
+    private dropBundle;
+}
+
+/**
+ * Synap SDK error taxonomy.
+ *
+ * Mirrors `maximem_synap/models/errors.py` 1:1, including the four
+ * backward-compatibility aliases at the bottom. If you add an error to one
+ * SDK, add it to the other in the same change.
+ *
+ * ## Why every error carries a `.code`
+ *
+ * This package ships dual ESM + CJS. A consumer whose dependency graph pulls
+ * in both formats gets *two* copies of every class in this file, and then:
+ *
+ *     try { ... } catch (e) { if (e instanceof SynapError) { ... } }
+ *
+ * silently evaluates to `false` against the copy from the other format. Error
+ * handling stops working and nothing throws to tell you. `.code` is a plain
+ * string, so it is immune. Prefer it at package boundaries:
+ *
+ *     if (isSynapError(e) && e.code === 'rate_limit') { ... }
+ *
+ * `Symbol.hasInstance` is also wired up on the base class, so `instanceof`
+ * works across realms too -- but `.code` is the documented contract.
+ */
+/** Stable, format-independent discriminators. Never renumber or reuse. */
+type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
+interface SynapErrorOptions {
+    correlationId?: string | null;
+    cause?: unknown;
+}
+declare class SynapError extends Error {
+    /**
+     * The single declaration site for each subclass's code.
+     *
+     * It is `static` rather than a class field on purpose. Under
+     * `useDefineForClassFields` (the default at our ES2022 target) a class field
+     * is an *instance* property, so it is invisible from the constructor object.
+     * `Symbol.hasInstance` below only has the constructor to work with, so a
+     * field would leave it unable to tell `AuthenticationError` from
+     * `RateLimitError` -- it would report every Synap error as an instance of
+     * every other one.
+     */
+    static readonly errorCode: SynapErrorCode;
+    /** True for errors where a retry may succeed. Static for the same reason. */
+    static readonly isTransient: boolean;
+    /** Own, enumerable, so logs and JSON.stringify include it. */
+    readonly code: SynapErrorCode;
+    readonly correlationId: string | null;
+    readonly transient: boolean;
+    constructor(message: string, options?: SynapErrorOptions);
+    static [Symbol.hasInstance](instance: unknown): boolean;
+}
+/** Type guard that works across ESM/CJS copies and realms. */
+declare function isSynapError(e: unknown): e is SynapError;
+declare class SynapTransientError extends SynapError {
+    static readonly errorCode: SynapErrorCode;
+    static readonly isTransient: boolean;
+}
+declare class SynapPermanentError extends SynapError {
+    static readonly errorCode: SynapErrorCode;
+    static readonly isTransient: boolean;
+}
+declare class NetworkTimeoutError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+}
+/**
+ * Rate limit exceeded (HTTP 429, gRPC RESOURCE_EXHAUSTED).
+ *
+ * Also carries the two credit stops the server reports as 429, because both
+ * recover with time or a plan change rather than with a retry of this request:
+ * `reason: 'trial_limit_reached'` (the Trial cap is spent, see `upgradeUrl`)
+ * and `reason: 'subscription_inactive'` (a paid plan whose subscription is past
+ * due, unpaid or cancelled, see `manageUrl`). `reason` is null for an ordinary
+ * rate limit and against a server too old to send one.
+ */
+declare class RateLimitError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+    readonly retryAfterSeconds: number | null;
+    /** Machine-readable cause, when the stop was a credit stop. */
+    readonly reason: string | null;
+    /** Where a Trial customer upgrades. Python calls this `upgrade_url`. */
+    readonly upgradeUrl: string | null;
+    /** Where billing is managed. Python calls this `manage_url`. */
+    readonly manageUrl: string | null;
+    constructor(message: string, options?: SynapErrorOptions & {
+        retryAfterSeconds?: number | null;
+        reason?: string | null;
+        upgradeUrl?: string | null;
+        manageUrl?: string | null;
+    });
+}
+declare class ServiceUnavailableError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class AgentUnavailableError extends SynapTransientError {
+    static readonly errorCode: SynapErrorCode;
+    constructor(message?: string, options?: SynapErrorOptions);
+}
+/**
+ * The caller's credit wallet cannot cover this request.
+ *
+ * HTTP 402, and gRPC RESOURCE_EXHAUSTED with credit-related trailing metadata.
+ * Permanent by design: retrying without topping up burns quota and never
+ * succeeds. This is the error behind "the agent forgot" reports where retrieval
+ * silently returns nothing.
+ */
+declare class InsufficientCreditsError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+    readonly balanceCredits: number | null;
+    readonly requiredCredits: number | null;
+    /** Where the balance can be viewed. Python calls this `recovery_url`. */
+    readonly recoveryUrl: string | null;
+    /** Where a redeem code can be entered. Python calls this `redeem_url`. */
+    readonly redeemUrl: string | null;
+    /**
+     * Machine-readable cause. `'overages_disabled'` means the plan is paid and
+     * the balance is spent, but the account has not allowed usage past zero, so
+     * the work stops until someone allows overages or adds credits. Null when an
+     * older server did not send one.
+     */
+    readonly reason: string | null;
+    /** Where that setting and billing are managed. Python calls this `manage_url`. */
+    readonly manageUrl: string | null;
+    constructor(message: string, options?: SynapErrorOptions & {
+        balanceCredits?: number | null;
+        requiredCredits?: number | null;
+        recoveryUrl?: string | null;
+        redeemUrl?: string | null;
+        reason?: string | null;
+        manageUrl?: string | null;
+    });
+}
+declare class InvalidInputError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+/**
+ * Raised by `validateInstanceId` before any network call, matching Python's
+ * `utils/validators.py`. The message text is identical in both SDKs.
+ */
+declare class InvalidInstanceIdError extends InvalidInputError {
+    static readonly errorCode: SynapErrorCode;
+}
+/** See the note on InvalidInstanceIdError. Raised by `validateConversationId`. */
+declare class InvalidConversationIdError extends InvalidInputError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class AuthenticationError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ContextNotFoundError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ConflictError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class TranscriptConflictError extends ConflictError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class SessionExpiredError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ListeningAlreadyActiveError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare class ListeningNotActiveError extends SynapPermanentError {
+    static readonly errorCode: SynapErrorCode;
+}
+declare const SDKError: typeof SynapError;
+declare const TransientError: typeof SynapTransientError;
+declare const PermanentError: typeof SynapPermanentError;
+declare const ConnectionError: typeof NetworkTimeoutError;
+
+export { AnticipationCache as A, type BundleItem as B, ConflictError as C, isSynapError as D, type ExitReason as E, InsufficientCreditsError as I, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, InvalidConversationIdError as i, InvalidInputError as j, InvalidInstanceIdError as k, ListeningNotActiveError as l, type LookupParams as m, type LookupResult as n, type LookupTelemetry as o, SDKError as p, ServiceUnavailableError as q, SessionExpiredError as r, type SnapshotBundle as s, type SnapshotItemPreview as t, type SnapshotItemRecord as u, type SynapErrorCode as v, type SynapErrorOptions as w, SynapPermanentError as x, SynapTransientError as y, TransientError as z };