/**
 * VariableEnvelope — Structured variable tracking with provenance.
 *
 * Replaces ad-hoc `Record<string, string>` variable bags with a
 * structured, auditable format. Every variable carries metadata about
 * where it came from, when it was resolved, and its content hash for
 * cache invalidation.
 *
 * Canonical field names: `values` and `provenance`.
 * The storage layer (Content Lake) may adapt these to different names
 * on serialization (e.g., `vars`/`meta`), but the domain model always
 * uses the canonical names defined here.
 *
 * @see docs/design-docs/architecture-overhaul/domain-model.md (canonical)
 */
/** Where a variable's value originated */
export type VariableSource = {
    type: "fixture";
    fixtureId: string;
} | {
    type: "inline";
    definedIn: "task" | "suite";
} | {
    type: "environment";
    envVar: string;
} | {
    type: "derived";
    expression: string;
    inputs: string[];
} | {
    type: "fetched";
    url: string;
} | {
    type: "previous-result";
    resultId: string;
    field: string;
};
/** Provenance metadata for a single variable */
export interface VariableProvenance {
    /** Where this variable's value came from */
    source: VariableSource;
    /** When the variable was resolved (ISO 8601 timestamp) */
    resolvedAt: string;
    /** Time-to-live in seconds (for fetched/cached variables) */
    ttl?: number;
    /** Content-addressable hash for cache invalidation */
    hash: string;
}
/** Schema declaration for a variable — enables compile-time template validation */
export interface VariableDeclaration {
    /** Variable name (matches the key in `values`) */
    name: string;
    /** Expected type of the variable's value */
    type: "string" | "number" | "boolean" | "json" | "markdown" | "unknown";
    /** Whether the variable must be present for the task to run */
    required: boolean;
    /** Human-readable description */
    description?: string;
    /** Default value used when the variable is not provided */
    default?: unknown;
}
/**
 * A structured container for all variables flowing through an evaluation step.
 *
 * The envelope enables:
 * - **Cache invalidation** — if a variable's content hash changes, downstream
 *   results are invalidated.
 * - **Audit trails** — every variable in a result can be traced back to its
 *   origin.
 * - **Type checking** — declarations allow compile-time validation of prompt
 *   templates against available variables.
 */
export interface VariableEnvelope {
    /** The resolved key-value pairs available to prompt templates */
    values: Record<string, unknown>;
    /** Provenance metadata for each variable (keyed by variable name) */
    provenance: Record<string, VariableProvenance>;
    /** Schema declarations for type-safe access */
    declarations: VariableDeclaration[];
}
