/**
 * "Show your work" — consumer-facing derivation walk.
 *
 * A derivation walk is the plain-language story of how a single certified (or
 * generated) answer was produced: the value, the governed block that owns it,
 * the business terms and metrics/dimensions it draws on, the dbt model/source
 * it ultimately reads from, and the freshness/owner/review state that makes it
 * trustworthy.
 *
 * It is NOT the raw author lineage graph. It deliberately hides depth: a flat,
 * ordered list of steps the UI can reveal one level at a time. The structured
 * payload is assembled entirely from data that already exists —
 * `queryBusiness360` (businessDefinition / businessComposition /
 * technicalSources / consumers / gaps / evidence) plus the answer's source
 * block governance fields — so no lineage is rebuilt and no schema changes.
 */
import type { Business360Result } from './query.js';
/** The kind of node a derivation step represents, ordered roughly value → source. */
export type DerivationStepKind = 'value' | 'block' | 'term' | 'metric' | 'dimension' | 'model' | 'source' | 'consumer';
/**
 * One node in the derivation walk. Intentionally flat and plain-language: the
 * UI reveals steps progressively rather than drawing edges.
 */
export interface DerivationStep {
    kind: DerivationStepKind;
    /** Human-readable label, e.g. the block name or term name. */
    name: string;
    /** Governing owner (person/team), when known. */
    owner?: string;
    /** Certification/review status, when known (e.g. certified, review, draft). */
    status?: string;
    /** Optional one-line plain-language detail for this step. */
    detail?: string;
}
/**
 * The consumer-facing derivation payload. `trustLabel` and `freshness` are
 * OPTIONAL: they are populated from whatever exists today and are designed to
 * be filled in later by the trust-label / freshness-aware-trust features.
 */
export interface DerivationWalk {
    /** The headline value the answer reported, when there is a single one. */
    value?: string;
    /** One-sentence plain-language summary of the derivation. */
    summary: string;
    /** Ordered walk: value → block → term/metric → dbt model/source. */
    steps: DerivationStep[];
    /** Canonical trust label, when available (optional; sibling feature fills this in). */
    trustLabel?: string;
    /** Freshness marker for the upstream data, when available (optional sibling feature). */
    freshness?: string;
    /** Interpretation caveats drawn from the block's `caveats`. */
    caveats?: string[];
}
/**
 * Minimal governance descriptor for the answer's source block. Both
 * `ManifestBlock` and the agent's `KGNode` are structurally compatible, so the
 * builder can accept either without coupling to a specific package.
 */
export interface DerivationFocusBlock {
    name: string;
    owner?: string;
    status?: string;
    /** Review cadence, e.g. "monthly". Surfaced verbatim in the walk. */
    reviewCadence?: string;
    /** Interpretation caveats. Surfaced verbatim and as the walk's `caveats`. */
    caveats?: string[];
    /** Business term names this block implements. */
    termRefs?: string[];
    /** Semantic metric references. */
    metricRefs?: string[];
    /** Semantic dimension references. */
    dimensionRefs?: string[];
    /** Business outcome / decision the block supports. */
    businessOutcome?: string;
    decisionUse?: string;
    /**
     * Freshness-aware trust — effective data health rolled up from the block's
     * transitive dbt upstreams (`ManifestBlock.dataState`). When present and not
     * `fresh`, the walk's `freshness` marker is derived from it so "show your
     * work" reflects stale/failed upstream data, not just certification.
     */
    dataState?: 'fresh' | 'stale' | 'failed' | 'unknown';
    /** Plain-language explanation of `dataState`. */
    dataStateDetail?: string;
}
export interface BuildDerivationWalkInput {
    /** Business-360 payload for the focus block/term (from `queryBusiness360`). */
    business360: Business360Result;
    /** The answer's source block governance fields (caveats / reviewCadence / refs). */
    block?: DerivationFocusBlock;
    /** The headline value, when the answer reported a single number/string. */
    value?: string;
    /**
     * Whether this answer is a generated (Tier-2) draft. When true the walk ends
     * with the appropriate review-required state instead of a certified close.
     */
    generated?: boolean;
    /** Optional canonical trust label (optional sibling feature). */
    trustLabel?: string;
    /** Optional freshness marker (optional sibling feature). */
    freshness?: string;
    /** Max steps of any single kind to include (keeps the walk compact). Default 3. */
    maxPerKind?: number;
}
/**
 * Assemble a consumer-facing derivation walk from an already-computed
 * `queryBusiness360` result plus the answer's source block. Pure and
 * synchronous — safe to call from a browser bundle.
 */
export declare function buildDerivationWalk(input: BuildDerivationWalkInput): DerivationWalk;
//# sourceMappingURL=derivation.d.ts.map