@cilow/sdk 0.2.1 → 0.3.0

package/dist/types.d.ts

@@ -1,494 +1,817 @@
 /**
- * Cilow SDK TypeScript Type Definitions
+ * Wire types for the Cilow JSON-RPC API. These mirror `crates/cilow-api/src/wire.rs`
+ * 1:1 so the SDK is a faithful, typed view of the engine's contract.
  *
- * Comprehensive type definitions for the Cilow memory system.
- */
-/**
- * Memory tier classification based on access frequency and recency
- */
-type MemoryTier = 'hot' | 'warm' | 'cold';
-/**
- * Memory status for lifecycle management
- */
-type MemoryStatus = 'active' | 'archived' | 'deleted';
-/**
- * Core memory entity representing a stored piece of information
- */
-interface Memory {
-    /** Unique identifier for the memory */
-    id: string;
-    /** The content of the memory */
-    content: string;
-    /** Tags for categorization and filtering */
-    tags: string[];
-    /** User ID associated with this memory */
-    userId?: string;
-    /** Session ID for grouping related memories */
-    sessionId?: string;
-    /** Current tier classification */
-    tier: MemoryTier;
-    /** Memory status */
-    status: MemoryStatus;
-    /** Access count for prioritization */
-    accessCount: number;
-    /** Token count for the content */
-    tokenCount: number;
-    /** Embedding vector (if available) */
-    embedding?: number[];
-    /** Additional metadata */
-    metadata: Record<string, unknown>;
-    /** ISO timestamp of creation */
-    createdAt: string;
-    /** ISO timestamp of last update */
-    updatedAt: string;
-    /** ISO timestamp of last access */
-    lastAccessedAt: string;
-}
-/**
- * Minimal memory representation for list operations
- */
-interface MemorySummary {
-    id: string;
-    content: string;
-    tags: string[];
-    tier: MemoryTier;
-    createdAt: string;
-}
-/**
- * Options for creating a new memory
- */
-interface CreateMemoryOptions {
-    /** Tags to apply to the memory */
-    tags?: string[];
-    /** User ID to associate */
-    userId?: string;
-    /** Session ID for grouping */
-    sessionId?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-    /** Force a specific tier */
-    tier?: MemoryTier;
-}
-/**
- * Options for updating a memory
- */
-interface UpdateMemoryOptions {
-    /** New content */
-    content?: string;
-    /** New tags (replaces existing) */
-    tags?: string[];
-    /** Updated metadata (merged with existing) */
-    metadata?: Record<string, unknown>;
-    /** Force tier change */
-    tier?: MemoryTier;
-}
-/**
- * Search result containing a memory and its relevance score
- */
-interface SearchResult {
-    /** The matching memory */
-    memory: Memory;
-    /** Relevance score (0.0 - 1.0) */
-    score: number;
-    /** Matched terms or phrases */
-    matchedTerms?: string[];
-    /** Highlighted content snippets */
-    highlights?: string[];
-}
-/**
- * Search query parameters
- */
-interface SearchQuery {
-    /** The search text */
+ * Important conventions from the engine:
+ *  - Entity ids are 128-bit and cross the wire as DECIMAL STRINGS (never lossy floats).
+ *  - All times (`observed_at`, `as_of`, `now`, `at`, `valid_from`, `valid_until`) are
+ *    raw epoch MICROSECONDS (µs), not milliseconds.
+ *  - Over HTTP, `scope` is server-stamped from the bearer token; a client-supplied
+ *    scope is ignored. It is still accepted here for parity with the stdio MCP transport.
+ */
+/** The 6-level tenant scope. Over HTTP this is server-stamped from the token; all levels default to 0. */
+export interface Scope {
+    org?: number;
+    project?: number;
+    user?: number;
+    agent?: number;
+    task?: number;
+    session?: number;
+    /** Track A1: git-style branch (0/omitted = main). Prefer the `branch` NAME option on
+     *  remember/recall/answer over setting this numeric id directly. */
+    branch?: number;
+}
+export type AnswerabilityStatus = "answerable" | "partial" | "conflicting" | "stale" | "denied" | "insufficient";
+export type MemoryProposalStatus = "pending" | "accepted" | "rejected";
+export interface Workspace {
+    workspace_id: string;
+    name: string;
+    org: number;
+    user: number;
+    project: number;
+    created_at: number;
+}
+export interface EvidenceCoordinate {
+    byte_start?: number;
+    byte_end?: number;
+    page?: number;
+    time_start_ms?: number;
+    time_end_ms?: number;
+    symbol?: string;
+    json_pointer?: string;
+}
+export interface EvidenceRevision {
+    evidence_id: string;
+    workspace_id: string;
+    source_id: string;
+    source_revision: string;
+    raw_sha256: string;
+    blob_id: string;
+    mime: string;
+    coordinates: EvidenceCoordinate[];
+    trust: "untrusted" | "user_provided" | "tool_observed" | "operator_verified";
+    acl_principals: string[];
+    valid_from: number;
+    valid_to?: number;
+    transaction_time: number;
+    current: boolean;
+    supersedes?: string;
+    derived_claims: string[];
+    excerpt: string;
+    metadata: Record<string, string>;
+}
+export interface CitationRef {
+    evidence_id: string;
+    source_id: string;
+    source_revision: string;
+    blob_id: string;
+    coordinates: EvidenceCoordinate[];
+    excerpt: string;
+}
+export interface ContextProgram {
+    program_id: string;
+    workspace_id: string;
+    query: string;
+    answerability: AnswerabilityStatus;
+    reason: string;
+    token_budget: number;
+    packed_tokens: number;
+    citations: CitationRef[];
+    counterevidence: CitationRef[];
+    unresolved_questions: string[];
+    instruction_boundary: "data_only";
+    allowed_tools: string[];
+}
+export interface CandidateEnvelope {
+    query_id: string;
+    tenant_scope_digest: string;
+    as_of: number;
+    evidence_revision_id: string;
+    source_id: string;
+    source_revision: string;
+    byte_start: number;
+    byte_end: number;
+    content_sha256: string;
+    temporal_eligibility: boolean;
+    retrieval_lane: string;
+    retrieval_scores: Record<string, number>;
+    model_generation: string;
+    index_generation: string;
+}
+export interface SelectedFragmentV2 {
+    fragment_id: string;
+    evidence_revision_id: string;
+    source_id: string;
+    source_revision: string;
+    byte_start: number;
+    byte_end: number;
+    source_content_sha256: string;
+    fragment_sha256: string;
     text: string;
-    /** Maximum number of results */
-    limit?: number;
-    /** Minimum relevance score threshold (0.0 - 1.0) */
-    minRelevance?: number;
-    /** Filter by tags (AND logic) */
-    tags?: string[];
-    /** Filter by user ID */
-    userId?: string;
-    /** Filter by session ID */
-    sessionId?: string;
-    /** Filter by tier */
-    tier?: MemoryTier;
-    /** Filter by date range - start */
-    createdAfter?: string;
-    /** Filter by date range - end */
-    createdBefore?: string;
-    /** Include archived memories */
-    includeArchived?: boolean;
-    /** Search mode */
-    mode?: 'semantic' | 'keyword' | 'hybrid';
-}
-/**
- * Advanced search options for complex queries
- */
-interface AdvancedSearchOptions extends SearchQuery {
-    /** Boost recent memories */
-    recencyBoost?: number;
-    /** Boost frequently accessed memories */
-    frequencyBoost?: number;
-    /** Required tags (must have all) */
-    requiredTags?: string[];
-    /** Excluded tags (must not have any) */
-    excludedTags?: string[];
-    /** Metadata filters */
-    metadataFilters?: Record<string, unknown>;
-    /** Custom reranking function name */
-    reranker?: string;
-}
-/**
- * Node in the memory knowledge graph
- */
-interface GraphNode {
-    /** Unique node identifier */
-    id: string;
-    /** Node type/label */
-    type: string;
-    /** Display name */
+    exact_tokens: number;
+}
+export interface ContextProgramV2 {
+    schema_version: string;
+    program_id: string;
+    query_id: string;
+    workspace_id: string;
+    tenant_scope_digest: string;
+    query: string;
+    as_of: number;
+    answerability: AnswerabilityStatus;
+    reason: string;
+    model_id: string;
+    tokenizer_id: string;
+    tokenizer_sha256: string;
+    prompt_template_id: string;
+    prompt_template_sha256: string;
+    model_context_token_budget: number;
+    model_context_tokens: number;
+    audit_payload_byte_budget: number;
+    audit_payload_bytes: number;
+    candidate_policy: {
+        depth: number;
+        lanes: string[];
+        temporal_policy: string;
+        compiler_policy: string;
+    };
+    candidate_ids: string[];
+    selected_fragments: SelectedFragmentV2[];
+    composition_plan: Array<Record<string, unknown>>;
+    composition_outputs: Array<Record<string, unknown>>;
+    final_context: string;
+    final_context_sha256: string;
+    gate: {
+        score_family: string;
+        threshold: number | null;
+        score: number;
+        decision: string;
+        calibration_state: string;
+    };
+    versions: {
+        model_id: string;
+        index_generation: string;
+        compiler_version: string;
+        calibrator_version: string;
+        tokenizer_id: string;
+    };
+    receipt_id: string;
+    premise_ids: string[];
+    artifact_sha256: string;
+    instruction_boundary: "data_only";
+}
+export interface ContextTrace {
+    trace_id: string;
+    program_id: string;
+    workspace_id: string;
+    query: string;
+    candidates: Array<{
+        evidence_id: string;
+        score: number;
+        current: boolean;
+        authorized: boolean;
+    }>;
+    selected_evidence_ids: string[];
+    exclusions: Array<{
+        evidence_id: string;
+        reason: string;
+    }>;
+    gate: Record<string, string>;
+    latency_ms: number;
+    estimated_cost_usd: number;
+}
+export interface AgentEpisode {
+    episode_id: string;
+    workspace_id: string;
+    actor_id: string;
+    summary: string;
+    evidence_ids: string[];
+    occurred_at: number;
+}
+export interface MemoryProposal {
+    proposal_id: string;
+    workspace_id: string;
+    author_id: string;
+    episode_id: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    evidence_ids: string[];
+    status: MemoryProposalStatus;
+    proposed_at: number;
+    verifier_id?: string;
+    decision_reason?: string;
+}
+export interface TruthRevision {
+    truth_revision_id: string;
+    proposal_id: string;
+    workspace_id: string;
+    verifier_id: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    evidence_ids: string[];
+    projection_source_id?: string;
+    valid_from: number;
+    transaction_time: number;
+    active: boolean;
+}
+export interface WorkspaceResponse {
+    ok: boolean;
+    workspace?: Workspace;
+    error?: string;
+}
+export interface EvidenceResponse {
+    ok: boolean;
+    evidence?: EvidenceRevision;
+    error?: string;
+}
+export interface InvestigateResponse {
+    ok: boolean;
+    program?: ContextProgram;
+    trace?: ContextTrace;
+    error?: string;
+}
+export interface CompileContextResponse {
+    ok: boolean;
+    program?: ContextProgramV2;
+    error?: string;
+}
+export interface TraceResponse {
+    ok: boolean;
+    trace?: ContextTrace;
+    error?: string;
+}
+export interface EpisodeResponse {
+    ok: boolean;
+    episode?: AgentEpisode;
+    error?: string;
+}
+export interface MemoryResponse {
+    ok: boolean;
+    proposal?: MemoryProposal;
+    truth_revision?: TruthRevision;
+    error?: string;
+}
+/** Track A1 — one git-style branch: its name, numeric id (decimal string), parent, fork instant. */
+export interface Branch {
     name: string;
-    /** Node properties */
-    properties: Record<string, unknown>;
-    /** Associated memory IDs */
-    memoryIds: string[];
-    /** Creation timestamp */
-    createdAt: string;
-    /** Last update timestamp */
-    updatedAt: string;
-}
-/**
- * Edge connecting two nodes in the graph
- */
-interface GraphEdge {
-    /** Unique edge identifier */
-    id: string;
-    /** Source node ID */
-    sourceId: string;
-    /** Target node ID */
-    targetId: string;
-    /** Relationship type */
-    type: string;
-    /** Edge weight/strength */
-    weight: number;
-    /** Edge properties */
-    properties: Record<string, unknown>;
-    /** Creation timestamp */
-    createdAt: string;
-}
-/**
- * Subgraph result for graph traversal queries
- */
-interface GraphSubgraph {
-    /** Nodes in the subgraph */
-    nodes: GraphNode[];
-    /** Edges in the subgraph */
-    edges: GraphEdge[];
-    /** Central node ID (if applicable) */
-    centerId?: string;
-}
-/**
- * Options for graph traversal
- */
-interface GraphTraversalOptions {
-    /** Starting node ID */
-    startNodeId: string;
-    /** Maximum traversal depth */
-    maxDepth?: number;
-    /** Filter by relationship types */
-    relationshipTypes?: string[];
-    /** Maximum nodes to return */
-    limit?: number;
-    /** Traversal direction */
-    direction?: 'outbound' | 'inbound' | 'both';
-}
-/**
- * Memory system statistics
- */
-interface MemoryStats {
-    /** Total number of memories */
-    totalMemories: number;
-    /** Number of hot tier memories */
-    hotMemories: number;
-    /** Number of warm tier memories */
-    warmMemories: number;
-    /** Number of cold tier memories */
-    coldMemories: number;
-    /** Total token count across all memories */
-    totalTokens: number;
-    /** Average tokens per memory */
-    averageTokensPerMemory: number;
-    /** Number of unique users */
-    uniqueUsers: number;
-    /** Number of unique sessions */
-    uniqueSessions: number;
-    /** Total number of tags */
-    totalTags: number;
-    /** Storage size in bytes */
-    storageSizeBytes: number;
-    /** Stats generation timestamp */
-    generatedAt: string;
-}
-/**
- * Tag with usage count
- */
-interface TagCount {
-    /** Tag name */
-    tag: string;
-    /** Usage count */
-    count: number;
-}
-/**
- * User activity statistics
- */
-interface UserStats {
-    /** User ID */
-    userId: string;
-    /** Number of memories */
-    memoryCount: number;
-    /** Total tokens used */
-    totalTokens: number;
-    /** Number of sessions */
-    sessionCount: number;
-    /** First activity timestamp */
-    firstActivityAt: string;
-    /** Last activity timestamp */
-    lastActivityAt: string;
-}
-/**
- * Base event type
- */
-interface BaseEvent {
-    /** Event type identifier */
-    type: string;
-    /** Event timestamp */
-    timestamp: string;
-    /** Correlation ID for tracking */
-    correlationId?: string;
-}
-/**
- * Memory created event
- */
-interface MemoryCreatedEvent extends BaseEvent {
-    type: 'memory.created';
-    /** The created memory */
-    memory: Memory;
-}
-/**
- * Memory updated event
- */
-interface MemoryUpdatedEvent extends BaseEvent {
-    type: 'memory.updated';
-    /** The updated memory */
-    memory: Memory;
-    /** Changed fields */
-    changedFields: string[];
-}
-/**
- * Memory deleted event
- */
-interface MemoryDeletedEvent extends BaseEvent {
-    type: 'memory.deleted';
-    /** Deleted memory ID */
-    memoryId: string;
-}
-/**
- * Memory tier changed event
- */
-interface MemoryTierChangedEvent extends BaseEvent {
-    type: 'memory.tier_changed';
-    /** Memory ID */
-    memoryId: string;
-    /** Previous tier */
-    previousTier: MemoryTier;
-    /** New tier */
-    newTier: MemoryTier;
-}
-/**
- * Graph node created event
- */
-interface GraphNodeCreatedEvent extends BaseEvent {
-    type: 'graph.node_created';
-    /** The created node */
-    node: GraphNode;
-}
-/**
- * Graph edge created event
- */
-interface GraphEdgeCreatedEvent extends BaseEvent {
-    type: 'graph.edge_created';
-    /** The created edge */
-    edge: GraphEdge;
+    /** Numeric branch id as a decimal string (`"0"` = main). */
+    branch: string;
+    /** Parent branch's numeric id as a decimal string (`"0"` = forked from main). */
+    parent: string;
+    /** Fork instant in epoch µs; omitted for main (no fork point). */
+    fork_time?: number;
+}
+/** Track A1 — the result of `fork`. `ok=false` ⇒ rejected (see `error`); nothing was created. */
+export interface ForkResponse {
+    ok: boolean;
+    /** The created branch (absent on error). */
+    branch?: Branch;
+    /** Failure reason when `ok=false`. */
+    error?: string;
+}
+/** A `(subject, predicate, object)` triple to remember / ingest. */
+export interface Fact {
+    subject: string;
+    predicate: string;
+    object: string;
+    /** Multi-value opt-out of supersession: `true` ⇒ a new value for this `(subject, predicate)`
+     *  COEXISTS with the old one (tags, skills) instead of superseding it. Mirrors `WireFact.multi`. */
+    multi?: boolean;
+}
+/** Provenance kind of a write. `operator` (a direct agent assertion) is the default + highest-trust. */
+export type Source = "tool_call" | "structured_import" | "operator" | "llm";
+/**
+ * The MACHINE-readable abstain code carried on an abstaining `recall`/`answer`. Mirrors
+ * `crates/cilow-truth/src/conformal.rs::AbstainReason::code()` 1:1. The agent-control-flow split:
+ *  - `below_threshold` / `no_candidates` — a CALIBRATED abstain: memory genuinely lacks grounded
+ *    context for this query. Do NOT fabricate past it; ask the user or search elsewhere.
+ *  - `provider_unavailable` — an INFRASTRUCTURE abstain: the embedding provider failed, so the
+ *    semantic read could not run. Memory MAY hold the answer — retry when it recovers.
+ * Branch with `isCalibratedAbstain` / `isInfrastructureAbstain` (see `./abstain.js`) instead of
+ * matching strings by hand.
+ */
+export type ReasonCode = "below_threshold" | "no_candidates" | "provider_unavailable";
+/**
+ * WHICH LAYER STOPPED THE ANSWER (`answer` / `context_pack`, engine ≥ 2026-09-06). Mirrors
+ * `crates/cilow-api/src/wire.rs::TerminalLayer` 1:1. Only set when `abstained`.
+ *  - `structural` — nothing was retrieved at all: the fact is not in memory.
+ *  - `gate`       — candidates existed but the conformal gate / a structural check refused.
+ *  - `provider`   — an embedding or reader provider was unreachable: RETRY.
+ *  - `reader`     — the reader read the context and judged it insufficient.
+ *  - `verifier`   — the reader answered but the answer-side verification failed.
+ */
+export type TerminalLayer = "structural" | "gate" | "provider" | "reader" | "verifier";
+export declare const TERMINAL_LAYERS: readonly TerminalLayer[];
+/** The structure facet of an {@link Evidence} unit — present iff the claim lane contributed. */
+export interface EvidenceStructure {
+    /** Entity id as a decimal string (128-bit, lossless). */
+    entity: string;
+    predicate: number;
+    entity_label?: string;
+    predicate_label?: string;
+    valid_from: number;
+    /** Absent = still valid. */
+    valid_until?: number;
+    is_current: boolean;
+}
+/** Where an {@link Evidence} unit came from. Every lane fills this. */
+export interface EvidenceProvenance {
+    source_id?: string;
+    session?: number;
+    in_session?: boolean;
+    observed_at?: number;
+    document_id?: string;
+}
+/**
+ * One unit of the UNIFIED EVIDENCE VIEW on `answer` / `context_pack`: the claim, span, and verbatim
+ * lanes collapsed into one list, deduplicated by text and ordered by fused cross-lane rank.
+ * `origins` names the lanes that produced it (`structured` | `semantic` | `lexical`); a unit two
+ * lanes agree on carries both and outranks a unit that is merely top of one lane. Present on
+ * answers AND abstains — an abstain can still carry evidence worth reading.
+ */
+export interface Evidence {
+    text: string;
+    origins: string[];
+    structure?: EvidenceStructure;
+    provenance?: EvidenceProvenance;
+    /** The fused reciprocal-rank score (RRF, K = 60) this unit was ordered by. */
+    fused: number;
+}
+/** Wire result of `remember`. When `ok` is false nothing was written (see `error`). */
+export interface RememberResponse {
+    claims_emitted: number;
+    inserted: number;
+    merged: number;
+    superseded: number;
+    conflicted: number;
+    deduped: boolean;
+    nodes_indexed: number;
+    edges_added: number;
+    entities_registered: string[];
+    attributes_registered: string[];
+    /** `false` ⇒ write failed; nothing durable. Defaults true on older servers. */
+    ok?: boolean;
+    /** Failure reason when `ok` is false, or CF projection lag warning. */
+    error?: string;
+    /** Typed causal edges minted post-write. */
+    causal_edges?: number;
+    /** CF-store projection put failures (log durable; CF may lag). */
+    cf_projection_errors?: number;
+}
+/** A packed claim returned by `recall`. */
+export interface Claim {
+    /** Entity id as a decimal string (128-bit, lossless). */
+    entity: string;
+    /** Predicate id (numeric). */
+    predicate: number;
+    /** Human-readable predicate name, e.g. `employer`. Absent if unknown. */
+    predicate_label?: string;
+    /** Human-readable entity surface form, e.g. `Maya Chen`. Absent if not recorded. */
+    entity_label?: string;
+    value: string;
+    score: number;
 }
-/**
- * Connection status event
- */
-interface ConnectionStatusEvent extends BaseEvent {
-    type: 'connection.status';
-    /** Connection status */
-    status: 'connected' | 'disconnected' | 'reconnecting';
-    /** Reason for status change */
+/** The assembly receipt: which path answered and the configured gate values. */
+export interface Receipt {
+    intent: string;
+    path: string;
+    /** Canonical entity id (decimal string), if an anchor resolved. */
+    canonical_entity?: string;
+    /** Alias-class members unioned into the read (decimal strings). */
+    class_members: string[];
+    /** Best candidate's nonconformity score. */
+    best_nonconformity?: number;
+    /** The calibrated conformal threshold. */
+    q_hat?: number;
+    /** `q̂ − n` — ≥0 answered, <0 abstained. */
+    margin?: number;
+}
+/**
+ * The result of a `recall`. THE ABSTENTION CONTRACT: when `abstained` is true the
+ * engine is telling you it does not know — `claims` is empty and `reason` explains.
+ * DO NOT fabricate past an abstain.
+ */
+export interface RecallResponse {
+    abstained: boolean;
+    /**
+     * The recall trace id — pass it to `feedback` to reshape exactly the claims this read
+     * surfaced (the outcome-feedback loop). `0` if the read was not traced; a live wire recall
+     * always traces.
+     */
+    trace_id: number;
+    /** The packed claims (empty on an abstain). */
+    claims: Claim[];
+    /** The human-facing abstain reason (only set when `abstained`). */
     reason?: string;
-}
-/**
- * Union type of all events
- */
-type CilowEvent = MemoryCreatedEvent | MemoryUpdatedEvent | MemoryDeletedEvent | MemoryTierChangedEvent | GraphNodeCreatedEvent | GraphEdgeCreatedEvent | ConnectionStatusEvent;
-/**
- * Pagination parameters
- */
-interface PaginationParams {
-    /** Number of items per page */
-    limit?: number;
-    /** Offset for pagination */
-    offset?: number;
-    /** Cursor for cursor-based pagination */
-    cursor?: string;
-}
-/**
- * Paginated response wrapper
- */
-interface PaginatedResponse<T> {
-    /** Items in this page */
-    items: T[];
-    /** Total count of items */
-    total: number;
-    /** Current offset */
-    offset: number;
-    /** Items per page */
-    limit: number;
-    /** Cursor for next page */
-    nextCursor?: string;
-    /** Whether there are more items */
-    hasMore: boolean;
-}
-/**
- * API error response
- */
-interface ApiError {
-    /** Error code */
-    code: string;
-    /** Human-readable error message */
-    message: string;
-    /** Additional error details */
-    details?: Record<string, unknown>;
-    /** Request ID for debugging */
-    requestId?: string;
-}
-/**
- * Health check response
- */
-interface HealthCheck {
-    /** Service status */
-    status: 'healthy' | 'degraded' | 'unhealthy';
-    /** Service version */
-    version: string;
-    /** Uptime in seconds */
-    uptimeSeconds: number;
-    /** Component statuses */
-    components: {
-        name: string;
-        status: 'healthy' | 'degraded' | 'unhealthy';
-        latencyMs?: number;
-    }[];
-}
-/**
- * Client configuration options
- */
-interface CilowConfig {
-    /** Base URL of the Cilow API */
-    apiUrl: string;
-    /** API key for authentication */
-    apiKey: string;
-    /** Request timeout in milliseconds */
-    timeout?: number;
-    /** Number of retry attempts for failed requests */
-    retries?: number;
-    /** Custom headers to include in requests */
-    headers?: Record<string, string>;
-    /** Enable debug logging */
-    debug?: boolean;
-}
-/**
- * WebSocket configuration options
- */
-interface WebSocketConfig {
-    /** WebSocket URL (defaults to apiUrl with ws:// protocol) */
-    wsUrl?: string;
-    /** Reconnection attempts */
-    reconnectAttempts?: number;
-    /** Reconnection delay in milliseconds */
-    reconnectDelay?: number;
-    /** Heartbeat interval in milliseconds */
-    heartbeatInterval?: number;
-    /** Message queue size for offline buffering */
-    messageQueueSize?: number;
-}
-/**
- * Combined configuration for full client
- */
-interface FullCilowConfig extends CilowConfig, WebSocketConfig {
-    /** Default user ID for all operations */
-    defaultUserId?: string;
-    /** Default session ID */
-    defaultSessionId?: string;
-    /** Default tags to apply */
-    defaultTags?: string[];
-}
-/**
- * Context result for AI integrations
- */
-interface ContextResult {
-    /** Formatted context string */
-    context: string;
-    /** Number of memories used */
-    memoriesUsed: number;
-    /** Estimated token count */
-    estimatedTokens: number;
-    /** Memory IDs included */
-    memoryIds: string[];
-    /** Search scores */
-    scores: number[];
-}
-/**
- * Conversation turn for storing dialogues
- */
-interface ConversationTurn {
-    /** User's message */
-    userMessage: string;
-    /** Assistant's response */
-    assistantResponse: string;
-    /** Session ID */
-    sessionId?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Batch operation result
- */
-interface BatchResult<T> {
-    /** Successful operations */
-    succeeded: T[];
-    /** Failed operations with errors */
-    failed: {
-        item: T;
-        error: string;
-    }[];
-    /** Total operations attempted */
+    /**
+     * The MACHINE-readable abstain code an agent branches on (see `ReasonCode`). Only set when
+     * `abstained`. Prefer `isCalibratedAbstain` / `isInfrastructureAbstain` over matching by hand.
+     */
+    reason_code?: ReasonCode;
+    receipt: Receipt;
+}
+/** A citation backing an `answer`. */
+export interface Citation {
+    entity: string;
+    predicate: number;
+    predicate_label?: string;
+    entity_label?: string;
+    value: string;
+    /** Present truth. Missing on the wire means not current (do not treat as live). */
+    is_current?: boolean;
+    /** Byte/page coordinate into retained source (T8). */
+    coordinate?: {
+        byte_start?: number;
+        byte_end?: number;
+        page?: number;
+        time_start_ms?: number;
+        time_end_ms?: number;
+        symbol?: string;
+        json_pointer?: string;
+    };
+    document_id?: string;
+}
+/** Anthropic Citations API part (`type: char_location` / `page_location`). */
+export interface CitationPart {
+    type: "char_location" | "page_location" | string;
+    cited_text: string;
+    document_index: number;
+    document_title?: string;
+    start_char_index?: number;
+    end_char_index?: number;
+    start_page_number?: number;
+    end_page_number?: number;
+}
+/**
+ * The result of an `answer`. When `abstained` is true, `text` is the honored abstain
+ * message and `citations` is empty — an agent MUST NOT treat it as fact.
+ */
+/**
+ * The reader model's ACTUAL billed token ledger for a live `answer` — the honest OUTPUT side of the
+ * token-efficiency metric. `prompt_tokens` is the input the reader model actually billed (provider ground
+ * truth; reconcile against `AnswerResponse.packed_tokens`, a coarse word×1.3 ESTIMATE over claim values),
+ * `completion_tokens` is the output it produced. Absent when no live reader ran (no billed tokens).
+ */
+export interface ReaderUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+}
+export interface AnswerResponse {
+    text: string;
+    abstained: boolean;
+    citations: Citation[];
+    /** The recall trace id — pass it to `feedback`. `0`/absent if not traced; a live answer traces. */
+    trace_id?: number;
+    /** The human-facing abstain reason (only set when `abstained`). */
+    reason?: string;
+    /**
+     * The MACHINE-readable abstain code (see `ReasonCode`) — frozen-contract parity with `RecallResponse`.
+     * Only set when `abstained`. Prefer `isCalibratedAbstain` / `isInfrastructureAbstain`.
+     */
+    reason_code?: ReasonCode;
+    /** The engine's INPUT-context token estimate (word×1.3 over claim values). */
+    packed_tokens?: number;
+    /**
+     * TOKEN LEDGER: the reader model's ACTUAL billed input+output tokens. Present only when a live reader
+     * ran; absent on deterministic / non-live / abstain paths (no billed tokens).
+     */
+    reader_usage?: ReaderUsage;
+    grounding?: string;
+    pack_sufficient?: boolean | null;
+    as_of?: number;
+    citation_parts?: CitationPart[];
+    /** The routed query intent (parity with `ContextPackResponse.intent`). Absent on older servers. */
+    intent?: string;
+    /** Which layer stopped the answer (see `TerminalLayer`). Only set when `abstained`. */
+    terminal_layer?: TerminalLayer;
+    /** The unified evidence view (see `Evidence`). Present on answers AND abstains. */
+    evidence?: Evidence[];
+}
+/** One bitemporal timeline entry for an entity. */
+export interface TimelineEntry {
+    predicate: number;
+    predicate_label?: string;
+    value: string;
+    /** Valid-from instant (epoch µs). */
+    valid_from: number;
+    /** Valid-until instant (epoch µs); open intervals use the max sentinel. */
+    valid_until: number;
+    /** Whether this version is active as-of the requested `at`. */
+    active: boolean;
+}
+export interface TrackEntityResponse {
+    /** The resolved entity id (decimal string). */
+    entity: string;
+    /** The canonical id of the alias class (decimal string). */
+    canonical: string;
+    /** The alias-class members (decimal strings). */
+    class: string[];
+}
+/** The outcome an agent reports on a traced recall. */
+export type Outcome = "positive" | "negative";
+/**
+ * The result of a `feedback`. When `applied` is FALSE the feedback was REJECTED and nothing
+ * was mutated — `error` says why: `"unknown_trace"` (the trace expired from the bounded cache
+ * or never existed) or `"cross_tenant"` (the scope did not match the traced recall).
+ * When `applied` is true, the IPW-Beta update ran and the abstain gate's q̂ self-tuned toward
+ * `realized_coverage`.
+ */
+export interface FeedbackResponse {
+    applied: boolean;
+    /** Machine-checkable rejection kind when `applied` is false: `"unknown_trace"` | `"cross_tenant"`. */
+    error?: string;
+    /** How many cited claims were re-weighted (≤ the number cited; a stale citation is skipped). */
+    claims_updated: number;
+    /** How many cited claims could not be matched in the store (stale citations). */
+    claims_missed: number;
+    /** True iff the outcome was `"positive"` (reinforce) vs `"negative"` (down-weight). */
+    positive: boolean;
+    /** The conformal calibrator's realized coverage after this outcome (what q̂ self-tunes toward). */
+    realized_coverage?: number;
+}
+/**
+ * The result of a `consolidate` — the counts of what the idle-time episodic→semantic pass did.
+ * Retire-not-delete: as-of-T history is preserved.
+ */
+export interface ConsolidateResponse {
+    /** Active claims promoted episodic→semantic (corroboration ≥ threshold). */
+    promoted: number;
+    /** Transition summaries synthesized from supersession chains (e.g. "NY→SF" as one claim). */
+    transitions: number;
+    /** Stale, never-recalled claims whose salience was decayed (confidence lowered, history kept). */
+    decayed: number;
+}
+/**
+ * The result of `remember_text` (free prose → extracted facts → claims). When `ok` is false the text
+ * could not be read (`error` says why) and nothing was written.
+ */
+export interface RememberTextResponse {
+    ok: boolean;
+    /** Facts the reader extracted from the prose and wrote as claims. */
+    facts_ingested: number;
+    /**
+     * The exact triples the reader extracted and wrote, in write order. TRANSPARENCY: the reader may
+     * anchor a fact to a subject other than your `subjectHint`, so inspect these to know which entities
+     * were created — a later `forget(subjectHint)` only retires that subject's claims, not a sibling
+     * subject the reader chose. Empty on error.
+     */
+    facts: Fact[];
+    /** The underlying claim-write receipt (zeroed on error). */
+    remember: RememberResponse;
+    /** Human-readable failure reason when `ok` is false. */
+    error?: string;
+}
+/**
+ * The result of `ingest_image` (image → VLM caption + facts → claims, recallable by a text query).
+ * `ok = false` ⇒ the image could not be read (`error` says why) and nothing was written.
+ */
+export interface IngestImageResponse {
+    ok: boolean;
+    /** The VLM caption read off the image (empty on error). */
+    caption: string;
+    /** Facts written = the caption fact + every extracted fact. */
+    facts_ingested: number;
+    /**
+     * The exact triples written, in write order: the `(subjectHint, "caption", caption)` fact first, then
+     * every extracted fact. TRANSPARENCY: inspect to see which entities the reader created. Empty on error.
+     */
+    facts: Fact[];
+    remember: RememberResponse;
+    error?: string;
+}
+/**
+ * The result of `ingest_audio` (audio → transcript + facts → claims, recallable by a text query).
+ * `ok = false` ⇒ the clip could not be read (`error` says why) and nothing was written.
+ */
+export interface IngestAudioResponse {
+    ok: boolean;
+    /** The transcript read off the clip (empty on error). */
+    transcript: string;
+    /** Facts written = the transcript fact + every extracted fact. */
+    facts_ingested: number;
+    /**
+     * The exact triples written, in write order: the `(subjectHint, "transcript", transcript)` fact first,
+     * then every extracted fact. TRANSPARENCY: inspect to see which entities the reader created. Empty on error.
+     */
+    facts: Fact[];
+    remember: RememberResponse;
+    error?: string;
+}
+/**
+ * The result of `ingest_pdf` (the hybrid document path: text layer + page vision → claims, recallable by
+ * a text query). `ok = false` ⇒ the PDF could not be read (`error` says why) and nothing was written.
+ */
+export interface IngestPdfResponse {
+    ok: boolean;
+    /** The extracted text layer (for reference; the recallable memory is the facts). Empty on error. */
+    text: string;
+    /** How many pages the vision half read (0 when the reader does not rasterize). */
+    pages_read: number;
+    /** Facts written = text-layer facts + per-page (caption + facts). */
+    facts_ingested: number;
+    /** The exact triples written, in write order. TRANSPARENCY: see which entities the reader created. */
+    facts: Fact[];
+    remember: RememberResponse;
+    error?: string;
+}
+/**
+ * The result of `ingest_structured` (CSV/JSON → claims, deterministically, no LLM).
+ * `ok = false` ⇒ the data could not be parsed (`error` says why) and nothing was written.
+ */
+export interface IngestStructuredResponse {
+    ok: boolean;
+    /** Facts written = one per non-empty (subject, column/key, value). */
+    facts_ingested: number;
+    /** The exact triples written. TRANSPARENCY: see every entity/predicate/value parsed. */
+    facts: Fact[];
+    remember: RememberResponse;
+    error?: string;
+}
+/**
+ * The result of `ingest_any` — the universal NEVER-REJECT front door. `ok = false` ONLY for
+ * malformed arguments (both/neither of content_base64|text, bad base64) — never for content:
+ * unknown bytes, reader failures, and denied URL fetches are all `ok = true` with the degrade
+ * reported in `reader_error`. The original is always retained (`blob_id` = hex sha256; absent =
+ * oversize-skipped or a link-only URL ingest).
+ */
+export interface IngestAnyResponse {
+    ok: boolean;
+    /** Canonical raw evidence id for this save, when bytes were retained (currently the same as blob_id). */
+    raw_id?: string;
+    /** Raw/projection lifecycle status: derived/degraded/deduped/failed today; pending_derivation for async saves. */
+    status: string;
+    /** Future write trace id hook. */
+    trace_id?: number;
+    /** What the content was sniffed as ("image/png", "url", "unknown", ...). */
+    detected: string;
+    /** The reader family that derived claims ("image"/"audio"/"pdf"/"text"/"structured"); absent = unknown/failed. */
+    routed?: string;
+    /** The retained original's hex sha256 (for a URL: the fetched snapshot's). */
+    blob_id?: string;
+    /** True iff the bytes were already retained by this tenant (no second copy appended). */
+    blob_deduped: boolean;
+    /** TAG_BLOB chunk frames holding the original. */
+    chunks: number;
+    /** The scope-folded document entity id (decimal string) the metadata claims hang off. */
+    document_entity: string;
+    /** Mention edges minted by this ingest. */
+    mention_edges: number;
+    /** Total facts written (metadata claims + routed reader claims). */
+    facts_ingested: number;
+    /** The exact triples written, in write order (metadata first). */
+    facts: Fact[];
+    /** Why routing degraded, when it did. The ingest is still a SUCCESS. */
+    reader_error?: string;
+    /** True iff this exact ingest already ran (idempotent no-op; the reader was not re-run). */
+    deduped: boolean;
+    remember: RememberResponse;
+    /** Model/provider stamps that participated in derivation, when reported. */
+    model_ids: string[];
+    /** Edge policy decision for the write. */
+    policy_decision: string;
+    /** Mock-reader hint, when the server detects a deterministic mock extraction path. */
+    hint?: string;
+    /** Argument failure when `ok = false`. */
+    error?: string;
+}
+/**
+ * The result of `forget` (retire-not-delete) or erase (OF1 destructive). `claims_retired = 0`
+ * is a clean no-op for retire. On erase, non-zero `spans_erased` / `claim_vectors_tombstoned` /
+ * `cached_embeddings_erased` mean those lanes were destroyed. Not a complete Art.17 claim.
+ */
+export interface ForgetResponse {
+    claims_retired: number;
+    entity?: string;
+    spans_erased?: number;
+    cached_embeddings_erased?: number;
+    claim_vectors_tombstoned?: number;
+    erased?: boolean;
+}
+/**
+ * Result of `context_pack` — injectible pack + citations; no free-form synthesis (D2).
+ * When session trunk is on (`CILOW_SESSION_TRUNK=1` and `scope.session != 0`), `trunk` is the
+ * stable multi-turn prefix and `suffix` the free score-ordered tail.
+ */
+export interface ContextPackResponse {
+    pack: string;
+    trunk?: string;
+    suffix?: string;
+    trunk_len: number;
+    suffix_len: number;
+    citations: Citation[];
+    claims: Claim[];
+    abstained: boolean;
+    grounding: string;
+    grounded: boolean;
+    packed_tokens: number;
+    intent: string;
+    reason?: string;
+    reason_code?: ReasonCode;
+    trace_id?: number;
+    best_nonconformity?: number;
+    q_hat?: number;
+    margin?: number;
+    pack_sufficient?: boolean | null;
+    as_of?: number;
+    citation_parts?: CitationPart[];
+    /** Which layer stopped the pack (see `TerminalLayer`). Only set when `abstained`. */
+    terminal_layer?: TerminalLayer;
+    /** The unified evidence view (see `Evidence`). Present on packs AND abstains. */
+    evidence?: Evidence[];
+}
+/**
+ * Result of `ingest` — the one write door. The server dispatches on the content FORM (`mcp.rs`
+ * `"save" | "ingest_any" | "ingest"` arm): `facts` ride the `remember` path and answer with a
+ * `RememberResponse`; `text` / bytes / a URL ride the never-reject `ingest_any` path and answer with
+ * an `IngestAnyResponse`. This shape unifies the two receipts:
+ *  - `kind` — which path ran.
+ *  - `remember` — always present: the structured write receipt (for content, the nested reader receipt).
+ *  - `content` — the raw-durable receipt (`blob_id` / `detected` / `routed` / `reader_error`); absent for facts.
+ *  - `facts_ingested` — facts: `claims_emitted`; content: `facts_ingested`.
+ *  - `source_id` — the idempotency key the SDK actually SENT (a content hash when you passed none).
+ * `ok = false` means nothing durable was written (see `error`). A reader degrade on the content path
+ * is `ok = true` with `content.reader_error` set (the never-reject contract).
+ */
+export interface IngestResponse {
+    kind: "facts" | "content";
+    source_id: string;
+    ok: boolean;
+    facts_ingested: number;
+    deduped: boolean;
+    remember: RememberResponse;
+    content?: IngestAnyResponse;
+    /** Content path only — facts writes are not traced today. */
+    trace_id?: number;
+    error?: string;
+}
+/** One cited claim in an `ExplainReport` (`graph_types.rs::ExplainCited`), labels resolved server-side. */
+export interface ExplainCited {
+    entity_label?: string;
+    predicate_label?: string;
+    value: string;
+    /** The inclusion probability the claim was recalled under (the IPW denominator `feedback` re-weights by). */
+    inclusion_pi: number;
+}
+/**
+ * The `explain` report (`graph_types.rs::ExplainReport`) — the trust surface: WHY a traced read
+ * surfaced what it surfaced and how close it ran to the grounding threshold.
+ * `best_nonconformity <= q_hat` is what "grounded" means (see `isGrounded`); `q_hat` is the tenant's
+ * threshold at explain time and `target_alpha` the per-intent miscoverage target the read was decided at.
+ */
+export interface ExplainReport {
+    abstained: boolean;
+    /** The best candidate's realized nonconformity (lower = better grounded). Absent/null on an abstain. */
+    best_nonconformity?: number | null;
+    q_hat: number;
+    target_alpha: number;
+    cited: ExplainCited[];
+}
+/**
+ * Result of `explain` (`wire.rs::ExplainResponse`). `found = false` is IN-BAND, not an exception:
+ * `error` is `unknown_trace` (expired from the bounded cache or never existed) or `cross_tenant`
+ * (the same opaque guard `feedback` applies). `report` is present iff `found`. Read-only — explaining
+ * never consumes the feedback trace.
+ */
+export interface ExplainResponse {
+    found: boolean;
+    error?: "unknown_trace" | "cross_tenant" | string;
+    report?: ExplainReport;
+}
+/** One retained blob's metadata on the wire (no bytes — call `blobGet` for those). */
+export interface BlobInfo {
+    /** Hex sha256 content address. */
+    blob_id: string;
+    mime: string;
+    byte_len: number;
+    source_id: string;
+    observed_at: number;
+    metadata: Array<[string, string]>;
+    /** Number of stored chunks (large blobs are chunked). */
+    chunks: number;
+}
+/**
+ * The result of `blobGet`. `found:false` with no `error` ⇒ ordinary tenant miss. `error` in
+ * {invalid_id, invalid_range, storage, corrupt} ⇒ a RANGE read failed — never treat as absence.
+ * On a range read `byte_len` is the returned window and `total_len` the complete blob length.
+ */
+export interface BlobGetResponse {
+    found: boolean;
+    data_base64?: string;
+    mime?: string;
+    byte_len?: number;
+    total_len?: number;
+    error?: string;
+}
+/** The result of `blobMeta`. `found:false` ⇒ this tenant retains no such blob. */
+export interface BlobMetaResponse {
+    found: boolean;
+    info?: BlobInfo;
+}
+/** The result of `blobList` — this tenant's retained originals, deterministically ordered. */
+export interface BlobListResponse {
+    blobs: BlobInfo[];
     total: number;
 }
-/**
- * Check if an event is a memory event
- */
-declare function isMemoryEvent(event: CilowEvent): event is MemoryCreatedEvent | MemoryUpdatedEvent | MemoryDeletedEvent;
-/**
- * Check if an event is a graph event
- */
-declare function isGraphEvent(event: CilowEvent): event is GraphNodeCreatedEvent | GraphEdgeCreatedEvent;
-/**
- * Check if an object is an API error
- */
-declare function isApiError(obj: unknown): obj is ApiError;
-
-export { type AdvancedSearchOptions, type ApiError, type BaseEvent, type BatchResult, type CilowConfig, type CilowEvent, type ConnectionStatusEvent, type ContextResult, type ConversationTurn, type CreateMemoryOptions, type FullCilowConfig, type GraphEdge, type GraphEdgeCreatedEvent, type GraphNode, type GraphNodeCreatedEvent, type GraphSubgraph, type GraphTraversalOptions, type HealthCheck, type Memory, type MemoryCreatedEvent, type MemoryDeletedEvent, type MemoryStats, type MemoryStatus, type MemorySummary, type MemoryTier, type MemoryTierChangedEvent, type MemoryUpdatedEvent, type PaginatedResponse, type PaginationParams, type SearchQuery, type SearchResult, type TagCount, type UpdateMemoryOptions, type UserStats, type WebSocketConfig, isApiError, isGraphEvent, isMemoryEvent };
+//# sourceMappingURL=types.d.ts.map