/** Project-private working-set handoffs.
 *
 * Handoffs carry bounded session context—scope, evidence, uncertainty,
 * declared boundaries, and the next safe action—without pretending to grant
 * authority or privately message another DID. Doctrine: docs/HANDOFFS.md.
 */
import { type HttpConfig } from "./_http.js";
export type HandoffStatus = "active" | "blocked" | "complete";
export type HandoffState = "absent" | "current" | "stale";
export type HandoffFactSource = "self_observed" | "peer_reported" | "tool_output";
export type HandoffConfidence = "low" | "medium" | "high";
export type HandoffVerificationResult = "passed" | "failed" | "not_run";
export interface HandoffFact {
    statement: string;
    source: HandoffFactSource;
    refs?: string[];
}
export interface HandoffInference {
    statement: string;
    confidence: HandoffConfidence;
    refs?: string[];
}
export interface HandoffVerification {
    check: string;
    result: HandoffVerificationResult;
    detail?: string | null;
}
export interface HandoffWorkingSet {
    paths: string[];
    scope: string[];
}
export interface HandoffAuthority {
    /** Writer-declared coordination boundary; never a permission grant. */
    allowed: string[];
    /** Writer-declared limit; never a platform authorization check. */
    not_authorized: string[];
}
export interface HandoffEpistemicState {
    facts: HandoffFact[];
    inferences: HandoffInference[];
    unknowns: string[];
}
export interface HandoffWriteOpts {
    /** Active identity UUID in the bearer project. */
    agent_id: string;
    task_summary: string;
    /** Defaults to active. */
    status?: HandoffStatus;
    from_facet?: string | null;
    to_facet?: string | null;
    /** Defaults to empty paths and scope. */
    working_set?: HandoffWorkingSet;
    /** Defaults to empty declared boundaries. */
    authority?: HandoffAuthority;
    /** Defaults to empty facts, inferences, and unknowns. */
    epistemic_state?: HandoffEpistemicState;
    changes?: string[];
    verification?: HandoffVerification[];
    next_safe_action: string;
    do_not_assume?: string[];
    /** ISO-8601; server requires future and no more than 30 days ahead. */
    valid_until: string;
    /** Append-only revision pointer. Must be this identity's prior handoff. */
    supersedes_handoff_id?: string | null;
    /** Omit to preserve legacy latest-per-identity lineage behavior. Set true
     * to start an explicit independent lineage. It cannot be combined with
     * `supersedes_handoff_id`; an explicitly supplied false remains legacy. */
    starts_new_lineage?: boolean;
    /** Optional 8-256 character caller key for the API's Redis-backed replay
     * cache. This reduces sequential retry duplication while Redis is healthy;
     * it is fail-open and does not reserve concurrent in-flight writes. */
    idempotency_key?: string;
}
export interface HandoffRecord {
    id: string;
    project_id: string;
    author_agent_id: string;
    title: string;
    body: string | null;
    supersedes_handoff_id: string | null;
    lineage_mode: "legacy_latest_per_author" | "explicit";
    occurred_at: string;
    created_at: string;
    provenance: "self_declared_project_bearer";
    version: 1;
    ts: string;
    task_summary: string;
    status: HandoffStatus;
    from_facet: string | null;
    to_facet: string | null;
    working_set: HandoffWorkingSet;
    authority: HandoffAuthority;
    epistemic_state: HandoffEpistemicState;
    changes: string[];
    verification: HandoffVerification[];
    next_safe_action: string;
    do_not_assume: string[];
    valid_until: string;
}
export interface HandoffResponse {
    handoff: HandoffRecord | null;
    state: HandoffState;
    scope: "project_private";
    authority_note: string;
}
export interface HandoffSurface {
    active: HandoffRecord[];
    stale: HandoffRecord[];
    /** Complete, row-budget truncated, or unavailable because composition failed. */
    projection_status: "complete" | "truncated" | "unavailable";
    /**
     * True when the server stopped at its bounded candidate-row budget. When
     * true, active/stale may omit older independent lineages.
     */
    truncated: boolean;
    /** True only when active/stale contain the complete current leaf set. */
    leaf_set_complete: boolean;
    candidate_rows_considered: number;
    candidate_row_limit: number;
    /**
     * Diagnostic lower edge of the candidate window, or null when no edge was
     * observed. This is not a resume cursor.
     */
    candidate_window_end_id: string | null;
    scope: "project_private";
    authority_note: string;
    write: "POST /v1/handoff";
    read_latest: "GET /v1/handoff?agent_id=<identity_id>";
}
export interface HandoffResumeOpts {
    /** Optional identity voice used to build the focused wake fragment. The
     * returned handoff working set remains explicitly project-scoped. */
    identity_id?: string;
}
export interface HandoffResumeResponse {
    _scope_boundary?: Record<string, unknown> | null;
    you_have_handoffs: HandoffSurface;
}
/** Client for `/v1/handoff`.
 *
 * `write()` always appends. To correct a prior snapshot, send a new body
 * with `supersedes_handoff_id`; do not mutate history in place.
 */
export declare class HandoffClient {
    private readonly http;
    private readonly onWrite?;
    /** @internal */
    constructor(http: HttpConfig, onWrite?: () => void);
    write(opts: HandoffWriteOpts): Promise<HandoffResponse>;
    /** Read one active project identity's newest snapshot. A stale latest
     * handoff remains stale; the API intentionally never falls back. */
    get(agent_id: string): Promise<HandoffResponse>;
    /** Read the bounded current project working-set projection through the
     * focused wake fragment. Check `leaf_set_complete` before treating it as the
     * complete leaf set. This call is intentionally uncached: it is the
     * session-resume seam, not a five-minute orientation cache. */
    resume(opts?: HandoffResumeOpts): Promise<HandoffResumeResponse>;
    private req;
}