/**
 * Chat Transcript Contract v2
 *
 * First-class message identity, monotonic sequence, strict enums. Designed to
 * replace the v1 contract (contracts.ts ReadChatResult + types.ts ChatMessage)
 * during the A2 big-bang. This module defines the contract; it does not yet
 * change runtime behaviour. v1 keeps working until A2 flips the switch.
 *
 * Invariants v2 enforces (and v1 does not):
 *   1. Every ChatMessageV2 has providerUnitKey, bubbleId, sequence — none optional.
 *   2. sequence is a monotonic integer per (sessionId, source) tuple. Producers
 *      never reuse it; consumers MAY assume strict ordering.
 *   3. providerUnitKey is stable across re-reads: the same logical message
 *      always yields the same key even if its index shifts or content is
 *      edited mid-stream. Producers derive it from provider-owned identifiers
 *      (turn id, native message id), not from content hashes or array index.
 *   4. timestamp is producer-asserted wall-clock; orderingTimestamp is monotonic
 *      and used for snapshot diffs. 1ms fallback increments are forbidden — if
 *      a producer cannot supply a stable monotonic value, the daemon assigns
 *      sequence at ingest and orderingTimestamp = ingestedAt.
 *   5. visibility / source / role / kind are strict unions. No `(string & {})`
 *      escape hatches.
 *   6. Coverage is exactly one of full/tail/current-turn. Mixing it with
 *      partialReason or unavailableReason is a contract violation.
 *   7. workspace / sessionId are explicit on every ReadChatResultV2; the daemon
 *      no longer infers them from message bodies.
 */
import type { MessagePart, ToolCallInfo } from './contracts.js';
export declare const CHAT_CONTRACT_VERSION_V1: "1.0";
export declare const CHAT_CONTRACT_VERSION_V2: "2.0";
export type ChatContractVersion = typeof CHAT_CONTRACT_VERSION_V1 | typeof CHAT_CONTRACT_VERSION_V2;
export declare const SUPPORTED_CHAT_CONTRACT_VERSIONS: readonly ChatContractVersion[];
export declare const CHAT_ROLES_V2: readonly ["user", "assistant", "system"];
export type ChatRoleV2 = typeof CHAT_ROLES_V2[number];
export declare const CHAT_MESSAGE_KINDS_V2: readonly ["standard", "thought", "tool", "terminal", "system"];
export type ChatMessageKindV2 = typeof CHAT_MESSAGE_KINDS_V2[number];
export declare const CHAT_VISIBILITIES_V2: readonly ["user", "debug", "internal", "hidden"];
export type ChatVisibilityV2 = typeof CHAT_VISIBILITIES_V2[number];
export declare const CHAT_AUDIENCES_V2: readonly ["chat", "debug", "trace", "internal"];
export type ChatAudienceV2 = typeof CHAT_AUDIENCES_V2[number];
export declare const CHAT_SOURCES_V2: readonly ["assistant_text", "tool_call", "terminal_command", "runtime_activity", "runtime_status", "provider_chrome", "control"];
export type ChatSourceV2 = typeof CHAT_SOURCES_V2[number];
export declare const CHAT_BUBBLE_STATES_V2: readonly ["draft", "streaming", "final", "removed"];
export type ChatBubbleStateV2 = typeof CHAT_BUBBLE_STATES_V2[number];
/**
 * Stable identity of a single chat message. All fields are required in v2.
 *
 * - providerUnitKey: provider-owned canonical id. Must be derivable from
 *   provider primitives (native message id, turn id, bubble id), NOT from
 *   array index or content hash. Stable across re-reads of the same logical
 *   message even if neighbours change.
 * - bubbleId: dashboard-owned bubble identity. May equal providerUnitKey when
 *   the provider already exposes a bubble-grained id; otherwise daemon
 *   derives it deterministically from providerUnitKey (e.g. `bubble:${key}`).
 * - sequence: monotonic integer per (sessionId, source). Strictly increasing
 *   over the lifetime of the session. Used for snapshot diffs and dedup.
 * - turnKey: stable identifier for the conversation turn this message belongs
 *   to. Required so consumers can group messages without re-deriving turns.
 */
export interface MessageIdentityV2 {
    providerUnitKey: string;
    bubbleId: string;
    sequence: number;
    turnKey: string;
}
/**
 * Producer-asserted wall-clock time (ms since epoch). Forward jumps are
 * permitted; consumers MUST NOT rely on this for ordering.
 */
export type ChatTimestampMs = number;
/**
 * Monotonic ordering value (ms since epoch, but assigned by the daemon at
 * ingest to guarantee monotonicity even if the producer's wall clock skews).
 * Used by snapshot diffs in place of timestamp.
 */
export type ChatOrderingTimestampMs = number;
export interface ChatMessageV2 extends MessageIdentityV2 {
    role: ChatRoleV2;
    kind: ChatMessageKindV2;
    content: string | MessagePart[];
    bubbleState: ChatBubbleStateV2;
    timestamp: ChatTimestampMs;
    orderingTimestamp: ChatOrderingTimestampMs;
    visibility: ChatVisibilityV2;
    audience: ChatAudienceV2;
    source: ChatSourceV2;
    /** Sender display name (for shared sessions). Empty string when unused. */
    senderName: string;
    /** Tool calls associated with this message. Empty array when none. */
    toolCalls: ToolCallInfo[];
    /** Producer-defined metadata. Daemon never inspects this except for passthrough. */
    meta: Readonly<Record<string, unknown>>;
}
export interface WorkspaceContextV2 {
    /** Absolute realpath of the workspace the session is reading from. */
    workspacePath: string;
    /** Workspace the session was intended to operate on (may differ during cross-workspace ops). */
    intendedWorkspacePath: string;
}
export interface SessionContextV2 {
    /** Provider-owned session id (e.g. claude.jsonl uuid, codex session_meta.id). */
    providerSessionId: string;
    /** Optional daemon-side history alias used to disambiguate within a workspace. */
    historySessionId?: string;
}
/**
 * v1 allowed `coverage='full'` to coexist with `partialReason`/`unavailableReason`,
 * which is a contract lie. v2 makes the three states mutually exclusive.
 */
export type CoverageHintV2 = {
    kind: 'full';
} | {
    kind: 'tail';
    tailMessageCount: number;
} | {
    kind: 'current-turn';
    turnKey: string;
} | {
    kind: 'partial';
    partialReason: string;
} | {
    kind: 'unavailable';
    unavailableReason: string;
};
export type CanonicalHistoryModeV2 = 'native-source' | 'disabled' | 'materialized-mirror';
export interface CanonicalHistoryDeclarationV2 {
    contractVersion: ChatContractVersion;
    format: string;
    mode: CanonicalHistoryModeV2;
    watchPath?: string;
    scripts: {
        readSession: string;
        listSessions: string;
    };
}
export type ReadChatStatusV2 = 'idle' | 'generating' | 'waiting_approval' | 'error' | 'panel_hidden' | 'streaming';
export type ReadChatTurnStatusV2 = 'open' | 'waiting_approval' | 'complete' | 'error';
export interface ReadChatResultV2 {
    contractVersion: typeof CHAT_CONTRACT_VERSION_V2;
    workspace: WorkspaceContextV2;
    session: SessionContextV2;
    coverage: CoverageHintV2;
    status: ReadChatStatusV2;
    messages: ChatMessageV2[];
    currentTurnId: string;
    turnStatus: ReadChatTurnStatusV2;
    transcriptAuthority: 'provider' | 'daemon';
}
export declare class ChatContractViolationError extends Error {
    readonly violationPath: string;
    readonly contractVersion: ChatContractVersion;
    constructor(contractVersion: ChatContractVersion, violationPath: string, detail: string);
}
/**
 * Validate a v2 read_chat payload. Throws ChatContractViolationError on the
 * first violation. v2 invariants beyond per-field checks:
 *   - messages[*].sequence strictly increasing
 *   - messages[*].orderingTimestamp monotonic non-decreasing
 *   - coverage union is well-formed
 */
export declare function assertReadChatResultV2Payload(raw: unknown): ReadChatResultV2;
export declare function isSupportedChatContractVersion(value: unknown): value is ChatContractVersion;
/**
 * Read a provider's declared chat contract version from its parsed
 * provider.json `canonicalHistory.contractVersion` field.
 *
 * - Absent or unrecognized → treated as v1 (legacy behaviour preserved during
 *   the A1 transition). A2 will tighten this to reject unsupported versions
 *   at provider load time.
 * - Present and supported → returned as-is.
 *
 * The returned version drives which validator (assertReadChatResultV2Payload
 * vs the legacy validateReadChatResultPayload) processes the provider's
 * read_chat output.
 */
export declare function readDeclaredChatContractVersion(canonicalHistory: unknown): ChatContractVersion;
