@cilow/sdk 0.2.0 → 0.3.0

package/dist/types.d.ts

@@ -0,0 +1,817 @@
+/**
+ * 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.
+ *
+ * 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;
+    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;
+    /** 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;
+}
+/** 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=types.d.ts.map