import type { GateResult } from '../prompts/errors.js';
import type { PromptRegistry } from '../prompts/registry.js';
import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
import { type ContextDiff } from './diff.js';
import { type ContextKeyring, type ContextSignature, type ContextSigner } from './signing.js';
/** A prompt a bundle uses, pinned to one content version of the prompt registry. */
export interface ContextPromptPin {
    /** The prompt's name in the registry. */
    name: string;
    /** Its content version, such as `p3f9a1c02b7de`. */
    version: string;
}
/** A tool a bundle offers: its name, description, and argument schema. The implementation stays in code. */
export interface ContextTool {
    /** The tool's name, as the model sees it. */
    name: string;
    /** What the tool does, for the model. */
    description?: string;
    /** JSON Schema for its arguments. */
    parameters?: Record<string, unknown>;
}
/** A skill: instructions for one kind of task, with the reference material it needs. */
export interface ContextSkill {
    /** When the skill applies, so an agent or a router can choose it. */
    description: string;
    /** How to do the task. */
    instructions: string;
    /** Reference material by name, such as a style guide or a schema. */
    resources?: Record<string, string>;
}
/**
 * Everything an agent runs with, versioned together: pinned prompts, named instructions, tool
 * definitions, skills, and configuration. A change to any part is a new version of the whole.
 */
export interface ContextBundleDefinition {
    /** The bundle's name, such as `support-agent`. */
    name: string;
    /** What the bundle is for. */
    description?: string;
    /** Prompts by role, such as `{ answer: { name: 'support-answer', version: 'p…' } }`. */
    prompts?: Record<string, ContextPromptPin>;
    /** Named instructions, such as a system policy or a tone guide. */
    instructions?: Record<string, string>;
    /** The tools the agent is offered. */
    tools?: ContextTool[];
    /** Skills by name. */
    skills?: Record<string, ContextSkill>;
    /** Settings the application reads, such as a model or a temperature. */
    config?: Record<string, unknown>;
    /** Application data. Not part of the version, so describing a bundle differently does not change it. */
    metadata?: Record<string, unknown>;
}
/** A committed bundle version. */
export interface ContextBundle extends ContextBundleDefinition {
    /** Its content version: `c` and 12 hex digits of a SHA-256 over everything but `metadata`. */
    version: string;
    /** ISO-8601 time it was committed. */
    createdAt: string;
    /** Why it changed, from the commit. */
    message?: string;
    /** Who committed it. */
    author?: string;
    /** The version that was newest before it. */
    parent?: string;
    /** Signatures over its content and its pinned prompts' content. Not part of the version. */
    signatures?: ContextSignature[];
}
/** Which bundle version is being used, as experiments and traces record it. */
export interface ContextReference {
    /** The bundle's name. */
    name: string;
    /** Its content version. */
    version: string;
    /** The label it was resolved through, when it was. */
    label?: string;
}
/** A label pointing at a bundle version. The same shape as a prompt label. */
export type ContextLabel = PromptLabel;
/** One recorded change to a bundle. The same shape as a prompt history entry. */
export type ContextHistoryEntry = PromptHistoryEntry;
/** What a context promotion gate is asked to judge. */
export interface ContextPromotionContext {
    /** The bundle. */
    name: string;
    /** The version being promoted. */
    bundle: ContextBundle;
    /** The label it is being promoted to. */
    to: string;
    /** The label it is being promoted from, when the promotion names one. */
    from?: string;
    /** The version `to` serves now, if any. */
    current?: ContextBundle;
    /** The hub, for gates that look things up. */
    hub: ContextHub;
}
/** Decides whether a bundle version may be promoted to a label. */
export type ContextPromotionGate = (context: ContextPromotionContext) => Promise<GateResult> | GateResult;
/** The outcome of a promotion. */
export interface ContextPromotionResult {
    /** The label after the promotion. */
    label: ContextLabel;
    /** Every gate's verdict. */
    results: GateResult[];
    /** False when the label already served the version, so nothing moved. */
    changed: boolean;
}
/** A bundle with the prompts it pins, as one document that moves between projects. */
export interface ContextBundleExport {
    /** Always `nexus-context-bundle`. */
    format: 'nexus-context-bundle';
    /** The export format's version. */
    formatVersion: 1;
    /** The bundle version. */
    bundle: ContextBundle;
    /** Every pinned prompt version, when the hub has a prompt registry. */
    prompts: PromptVersion[];
}
/** Options for a `ContextHub`. */
export interface ContextHubOptions {
    /**
     * Where bundle versions, labels, and history live: any prompt store — memory, files, Redis, or
     * Postgres — given to the hub alone. Defaults to a `MemoryPromptStore`.
     */
    store?: PromptStore;
    /** The prompt registry pinned prompts come from. Commits check each pin exists; exports carry them. */
    prompts?: PromptRegistry;
    /** Gates run before a promotion, by the label promoted to. */
    gates?: Record<string, readonly ContextPromotionGate[]>;
    /** Called after every recorded change. */
    onChange?: (entry: ContextHistoryEntry) => void | Promise<void>;
    /**
     * Signs every new version, over its content and its pinned prompts' content, so another hub can
     * check where it came from. Signing a bundle that pins prompts needs `prompts`.
     */
    signer?: ContextSigner;
    /**
     * The keys whose signatures this hub trusts, for `verify()`, and for `requireSignature`. A signature
     * by a key the keyring does not hold is kept, but never trusted.
     */
    keyring?: ContextKeyring;
    /**
     * Refuses any bundle without a valid signature by a key in `keyring`: on import, and whenever a
     * version is served through `resolve()` or `renderPrompt()`.
     */
    requireSignature?: boolean;
    /** Replaces the system clock, for tests. */
    now?: () => Date;
}
/** What `ContextHub.verify()` found. */
export interface ContextVerification {
    /** Whether a key in the keyring signed exactly this content. */
    trusted: boolean;
    /** The digest the content has now. */
    digest: string;
    /** The signature that verified, when one did. */
    signature?: ContextSignature;
}
/** Base class for context hub errors, each with a stable `code`. */
export declare class ContextHubError extends Error {
    /** Stable code, such as `CONTEXT_NOT_FOUND`. */
    readonly code: string;
    constructor(message: string, 
    /** Stable code, such as `CONTEXT_NOT_FOUND`. */
    code: string);
}
/** Raised for a bundle, version, or label that does not exist. */
export declare class ContextNotFoundError extends ContextHubError {
    /** The bundle. */
    readonly bundle: string;
    /** The version or label asked for. */
    readonly ref: string;
    constructor(
    /** The bundle. */
    bundle: string, 
    /** The version or label asked for. */
    ref: string);
}
/** Raised when a label moved while it was being changed. */
export declare class ContextConflictError extends ContextHubError {
    constructor(bundle: string, label: string);
}
/** Raised when a gate refuses a promotion. `results` holds every gate's verdict. */
export declare class ContextPromotionError extends ContextHubError {
    /** Every gate's verdict. */
    readonly results: GateResult[];
    constructor(bundle: string, to: string, 
    /** Every gate's verdict. */
    results: GateResult[]);
}
/** Raised when a bundle has no signature the hub trusts, or its signatures do not match its content. */
export declare class ContextSignatureError extends ContextHubError {
    /** The bundle. */
    readonly bundle: string;
    /** The version. */
    readonly version: string;
    constructor(
    /** The bundle. */
    bundle: string, 
    /** The version. */
    version: string, reason: string);
}
/** Raised when a bundle definition, a pin, or an import is invalid. */
export declare class ContextDefinitionError extends ContextHubError {
    constructor(message: string);
}
/**
 * The content version of a bundle: `c` and the first 12 hex digits of a SHA-256 over its name,
 * description, prompts, instructions, tools, skills, and configuration. Metadata is left out.
 */
export declare function contextVersion(definition: ContextBundleDefinition): Promise<string>;
/**
 * Versioned context bundles: prompts, instructions, tool sets, and skills versioned together,
 * labelled, promoted through gates, diffed, rolled back, and exported to move between projects.
 *
 * It works as the prompt registry does — `commit()` stores content under its version, so committing
 * unchanged content is a no-op; labels point at versions; every change is recorded — and it keeps its
 * state in a prompt store, so every adapter the prompt family has serves bundles too.
 */
export declare class ContextHub {
    private readonly options;
    /** Where versions, labels, and history live. */
    readonly store: PromptStore;
    private readonly now;
    /** Versions already verified as trusted, which never change. */
    private readonly trusted;
    constructor(options?: ContextHubOptions);
    /**
     * Commits a bundle and returns its version. Unchanged content returns the existing version and
     * records nothing; `label` points labels at the version either way. With a prompt registry, every
     * pinned prompt version must exist in it.
     */
    commit(definition: ContextBundleDefinition, options?: {
        message?: string;
        author?: string;
        label?: string | readonly string[];
    }): Promise<ContextBundle>;
    private commitSigned;
    /** A version by content version, label, or `latest`, the default. Throws `ContextNotFoundError` when there is none. */
    get(name: string, ref?: string): Promise<ContextBundle>;
    /**
     * Whether a key in the hub's keyring signed exactly this bundle's content, and its pinned prompts'
     * content as the prompt registry holds them. A version's answer never changes, so it is checked
     * once.
     */
    verify(bundle: ContextBundle): Promise<ContextVerification>;
    /** A version with the reference experiments and traces record for it. */
    resolve(name: string, ref?: string): Promise<{
        bundle: ContextBundle;
        reference: ContextReference;
    }>;
    /**
     * Renders the prompt a bundle pins for a role, through the prompt registry, recording the bundle in
     * the request's `metadata.context` beside the prompt's own reference.
     */
    renderPrompt(bundle: ContextBundle, role: string, variables?: Record<string, unknown>, options?: RenderOptions): Promise<RenderedPrompt>;
    /** Points a label at a version, without gates. Throws `ContextConflictError` if the label moved meanwhile. */
    label(name: string, label: string, ref: string, options?: {
        by?: string;
        note?: string;
    }): Promise<ContextLabel>;
    /** Removes a label. Resolves false when there was none. */
    unlabel(name: string, label: string, options?: {
        by?: string;
        note?: string;
    }): Promise<boolean>;
    /**
     * Moves `to` to a version — named directly, or whatever `from` serves — once every gate for `to`
     * allows it. Throws `ContextPromotionError` when a gate refuses, unless `force` is set, in which case
     * the refusals are still reported and recorded in the note.
     */
    promote(name: string, options: {
        to: string;
        from?: string;
        version?: string;
        by?: string;
        note?: string;
        force?: boolean;
    }): Promise<ContextPromotionResult>;
    /** Moves a label back to where it pointed before its last change. */
    rollback(name: string, label: string, options?: {
        by?: string;
        note?: string;
    }): Promise<ContextLabel>;
    /** A bundle's changes, newest first, optionally for one label. */
    history(name: string, options?: {
        label?: string;
        limit?: number;
    }): Promise<ContextHistoryEntry[]>;
    /** A bundle's versions, newest first. */
    versions(name: string, options?: {
        limit?: number;
    }): Promise<ContextBundle[]>;
    /** A bundle's labels. */
    labels(name: string): Promise<ContextLabel[]>;
    /** Every bundle's name, sorted. */
    names(): Promise<string[]>;
    /** What changed between two versions or labels of a bundle. */
    diff(name: string, from: string, to: string): Promise<ContextDiff>;
    /**
     * A bundle version as one document, with every prompt version it pins when the hub has a prompt
     * registry, so importing it elsewhere needs nothing else.
     */
    export(name: string, ref?: string): Promise<ContextBundleExport>;
    /**
     * Commits an exported bundle, and the prompts it carries into the hub's registry. Each prompt must
     * still have the version it was exported with, and the bundle its version, so an export edited by
     * hand is refused rather than imported under a version that no longer describes it.
     */
    import(exported: ContextBundleExport, options?: {
        label?: string | readonly string[];
        by?: string;
    }): Promise<ContextBundle>;
    /** Refuses a bundle without a trusted signature, when the hub requires one. */
    private assertTrusted;
    private check;
    /** What a signature over this bundle covers, with its pinned prompts read from the registry. */
    private signedContent;
    private read;
    private pointer;
    private record;
}