Recall and task continuity

export type ContinuityContextPolicyOptions = {
    id: string;
    maxRequestTokens: number;
    reservedRequestTokens: number;
};

export type IncrementalTaskSummaryPolicyOptions = {
    id: string;
    version: number;
    modelRole: string;
    maxInputBytes: number;
    maxOutputBytes: number;
    maxTokens: number;
    maxEvidenceReferences: number;
    maxUncertainties: number;
};

export declare function continuityContextPolicy(options: ContinuityContextPolicyOptions): ContextPolicy;

export declare function currentSessionRecallPolicy(id: string): RecallPolicy;

export declare function incrementalTaskSummaryPolicy(options: IncrementalTaskSummaryPolicyOptions): TaskSummaryPolicy;

/** Host-owned storage. write must acknowledge successful storage before resolving. */
export interface HistoryArchive {
    write(scope: HistoryArchiveScope, reference: HistoryArchiveReference, messages: readonly ChatMessage[]): Promise<void>;
    read(scope: HistoryArchiveScope, reference: HistoryArchiveReference): Promise<readonly ChatMessage[]>;
}

export interface HistoryArchiveReference {
    id: string;
    conversationId: string;
    messageCount: number;
    /** SHA-256 of the UTF-8 JSON message array; retrieval must match exactly. */
    digest: string;
}

export interface HistoryArchiveScope {
    identity: HarnessIdentity;
    sessionId: string;
}

export interface ResidentHistoryPolicy {
    /** Per-conversation limit at safe model/session boundaries, including pinned host instructions. */
    maxMessages: number;
    /** Optional per-conversation bound on UTF-8 JSON bytes. */
    maxBytes?: number;
    archive: HistoryArchive;
    /** Explicit host attestation for custom provider envelopes; default rejects unknown opaque data. */
    canEvict?: (messages: readonly ChatMessage[], provider?: ModelProvider) => boolean;
}

export declare class HistoryRetentionError extends Error {
    readonly code = "history_retention_unsupported";
    constructor(message: string);
}

export type EvidenceExcerpt = {
    id: string;
    reference: EvidenceReference;
    text: string;
    completeness: "complete" | "partial";
    omissions: readonly ("source_range" | "correction_context" | "negation_context")[];
    completeGroup: boolean;
};

export type EvidenceReference = {
    sourceId: string;
    sourceRevision: string;
    locator: string;
    archive?: HistoryArchiveReference;
    messageRange?: {
        start: number;
        end: number;
    };
};

export type RecallBudget = {
    maxQueryBytes: number;
    maxQueries: number;
    maxCandidates: number;
    maxDiscoveryBytes: number;
    maxExcerpts: number;
    maxExcerptBytes: number;
    maxSourceBytes: number;
    maxEvidenceTokens: number;
    deadlineMs: number;
    validationDeadlineMs: number;
    maxValidationBytes: number;
};

export type RecallCandidate = {
    id: string;
    reference: EvidenceReference;
    rank: number;
};

export type RecallDecision = {
    action: "continue";
} | {
    action: "stop";
    reason: string;
} | {
    action: "await_input";
    question: string;
};

export type RecallDiagnostic = {
    code: "query_limit" | "candidate_limit" | "byte_limit" | "token_limit" | "deadline" | "backend_failure" | "revision_changed" | "partial_evidence" | "invalid_response" | "pending_summary" | "unavailable_coverage" | "clarification_limit";
    phase: "open" | "discovery" | "read" | "assembly" | "summary" | "validation";
    message: string;
};

export type RecallOperationLimits = {
    signal: AbortSignal;
    deadline: number;
    remainingBytes: number;
    remainingTokens: number;
};

export interface RecallPolicy {
    id: string;
    query(input: {
        history: readonly ChatMessage[];
    }, ctx: RunContext): string | undefined;
    decide(result: RecallResult, ctx: RunContext): Promise<RecallDecision>;
}

export type RecallReadResult = {
    status: "found";
    excerpt: EvidenceExcerpt;
    viewRevision: string;
} | {
    status: "unavailable" | "revision_changed";
    viewRevision: string;
};

export type RecallResult = {
    status: "complete" | "no_accessible_evidence" | "partial" | "failed";
    excerpts: readonly EvidenceExcerpt[];
    diagnostics: readonly RecallDiagnostic[];
    viewRevision: string | null;
    usage: {
        queries: number;
        candidates: number;
        bytes: number;
        estimatedTokens: number;
        elapsedMs: number;
    };
};

export type RecallScope = {
    identity: HarnessIdentity;
    sessionId: string;
    projectId?: string;
    repositoryId?: string;
};

export interface RecallSession {
    readonly scope: RecallScope;
    readonly viewRevision: string;
    discover(request: {
        query: string;
        maxCandidates: number;
        maxResponseBytes: number;
    }, limits: RecallOperationLimits): Promise<{
        candidates: readonly RecallCandidate[];
        partial: boolean;
        viewRevision: string;
    }>;
    read(request: {
        reference: EvidenceReference;
        maxBytes: number;
        completeGroup?: boolean;
    }, limits: RecallOperationLimits): Promise<RecallReadResult>;
    validate(request: {
        expectedViewRevision: string;
        references: readonly EvidenceReference[];
    }, limits: RecallOperationLimits): Promise<{
        status: "valid" | "changed" | "unavailable";
        viewRevision: string;
    }>;
    close(): Promise<void>;
}

export interface RecallStore {
    readonly capabilities: {
        boundedDiscovery: boolean;
        boundedReads: boolean;
        revisionValidation: boolean;
        boundedCurrentValidation: boolean /** Explicit bounded canonical-group seek attestation; required for archival summaries. */;
        canonicalArchiveReads?: boolean;
    };
    open(scope: RecallScope, limits: RecallOperationLimits): Promise<RecallSession>;
}

export type TaskSummaryConfig = {
    policy: TaskSummaryPolicy;
    maxInputBytes: number;
    maxSummaryBytes: number;
    maxSummaryTokens: number;
    maxEvidenceReferences: number;
    maxRecordBytes: number;
    maxSummaryRecords: number;
};

export type TaskSummaryCoverage = {
    conversationId: string;
    throughArchiveOrdinal: number;
    throughArchiveId: string;
    throughArchiveDigest: string;
    throughMessage: number;
};

export type TaskSummaryDraft = {
    text: string;
    evidenceIds: readonly string[];
    uncertainties: readonly string[];
};

export interface TaskSummaryPolicy {
    id: string;
    version: number;
    update(input: {
        previous?: TaskSummaryRecord;
        additions: readonly EvidenceExcerpt[];
    }, ctx: RunContext): Promise<TaskSummaryDraft>;
}

export type TaskSummaryRecord = {
    contractVersion: 1;
    id: string;
    revision: number;
    policyId: string;
    policyVersion: number;
    recordedAt: number;
    trust: "source";
    draft: TaskSummaryDraft;
    evidence: readonly {
        id: string;
        reference: EvidenceReference;
    }[];
    coverage: TaskSummaryCoverage;
    previousRevision?: number;
    sourceViewRevision: string;
    scope: RecallScope;
};