agent-qa 0.1.21 → 0.2.1

package/dist/index.d.ts

@@ -1,19 +1,144 @@
-import { AgentQaConfig } from '@vostride/agent-qa-core';
+import { AgentQaConfig, resolveKnowledgeRoot } from '@vostride/agent-qa-core';
 export * from '@vostride/agent-qa-core';
+import { MaskFn, CompletedRunHandoff, Benefit, CrossCheck, CanaryOutcome, RecordId, Anchor, RunAnalysisArtifact, MisdirectionRecordResult, TrustPriorTable, CurationSnapshot, ResolvePromotionPosture, ScopeKey } from '@vostride/agent-qa-schema';
+import { CuratorAuthor, LocalCurationCapabilities, CurationCandidateProjection, EnqueueCurationCandidateProjectionOutcome, OpenServingKnowledgeReaderConfig } from '@vostride/agent-qa-agent-local';
+import { ModelProfile, ResolvedModelAuth, createModel, resolveCapabilities, createTokenAccounting } from '@vostride/agent-qa-model';
+import { KnowledgeHintReader } from '@vostride/agent-qa-runner';
+import { loadCompletedRunHandoff } from '@vostride/agent-qa-runner-local';
+import { runSafetyScope } from '@vostride/agent-qa-safety-local';
+import { z } from 'zod';
 
+/**
+ * A committed config the parser cannot read, named by WHERE and never by WHAT (395-14 · F-01).
+ *
+ * WHY A NAMED CLASS AND NOT A BARE `Error`. This throw leaves the loader through every config op,
+ * through `resolveConfig`, and — via `refusalMessage` — into a chat turn's answer and its session
+ * jsonl. A caller that wants to recognise the case (F-03's typed-refusal arm, later) needs
+ * something better than a substring match on a sentence; `name` and `configPath` are that. The
+ * message itself carries the path because the surfaces this reaches print a message and nothing
+ * else.
+ *
+ * NO MEMBER INTERPOLATES THE CAUGHT ERROR'S OWN TEXT. `yaml` pretty-prints its parse errors with a
+ * verbatim excerpt of the person's source, which was measured carrying a planted credential out of
+ * three ops.
+ *
+ * AND THE CAUSE IS SANITIZED TOO, BECAUSE THE RUNTIME READS THE CAUSE CHAIN (395-16 · CR-01).
+ * An earlier revision of this class attached the raw `YAMLParseError` as `cause` on the reasoning
+ * that no composed member reads it. That reasoning was false of the runtime, and shipped as a
+ * defect: a thrown value is read by far more than the code that composed it. Node's DEFAULT
+ * UNCAUGHT PRINTER renders an error with `util.inspect`, which walks `cause` and prints it under a
+ * `[cause]:` header — `agent-qa config show` awaited this loader bare and crash-printed the
+ * person's own file back at them. `console.error(err)` does the same thing, structured loggers
+ * (pino, winston) serialize the chain, and crash reporters upload it. So the cause carried here is
+ * a fresh `Error` holding THE SAME POSITION-ONLY SENTENCE as the message: a debugger still gets a
+ * chain to walk, and every one of those readers gets a position and nothing else. The caught value
+ * is not reachable from this error by any property.
+ */
+declare class ConfigFileNotYamlError extends Error {
+    readonly configPath: string;
+    constructor(configPath: string, cause: unknown);
+}
+/**
+ * THE READ AND THE PARSE GET SEPARATE CATCHES, and that separation is load-bearing.
+ *
+ * `Config file not found: <path>` is matched verbatim by the live lane's third-arm detection
+ * (`scripts/395-live-from-zero.sh:514`) and folded by `coveringGrantInForce`; a non-ENOENT read
+ * fault (EISDIR, EACCES) is a fact about the filesystem and not about the file's content, and is
+ * rethrown untouched. Only the PARSE throw is reworded — one guard, aimed at one channel.
+ */
 declare function loadConfigFile(configPath: string): Promise<unknown>;
+/**
+ * The absent-file case, RECOGNISABLE WITHOUT A SUBSTRING MATCH ON ITS OWN SENTENCE (395-27 · WR-02).
+ *
+ * The message is BYTE-IDENTICAL to the bare `Error` this replaces, because that exact string is
+ * matched by the live lane's third-arm detection (`scripts/395-live-from-zero.sh:514`), folded by
+ * `coveringGrantInForce`, and pinned by `(E1)`. Nothing about what any surface PRINTS changes.
+ *
+ * What changes is that `showAction` can now ask WHICH fault this is by `instanceof` instead of by
+ * `message.startsWith(...)` — the reasoning `ConfigFileNotYamlError` above already wrote down: a
+ * caller that wants to recognise the case needs something better than a substring match on a
+ * sentence, and a sentence-matching caller is one rewording away from silently taking the wrong arm.
+ */
+declare class ConfigFileNotFoundError extends Error {
+    readonly configPath: string;
+    constructor(configPath: string);
+}
 declare function loadRequiredConfigFile(configPath: string): Promise<unknown>;
 declare function loadEnvOverrides(): Record<string, unknown>;
 declare function mergeConfigs(file: unknown, env: Record<string, unknown>, flags: Record<string, unknown>): unknown;
 declare function deepMerge(base: unknown, override: unknown): unknown;
 declare function mergeWithTestConfig(globalConfig: unknown, testConfig: unknown, flagOverrides: Record<string, unknown>): unknown;
+/**
+ * The one shaping `resolveConfig` applies before validating (395-01: exported, not moved).
+ *
+ * EXPORTED so the config-mutation validate port can run the SAME three steps a real run runs —
+ * merge, normalize, parse. A port that skipped this would refuse a candidate whose only problem is
+ * a key `resolveConfig` deletes, which is a proposal blocked by a rule nothing enforces.
+ */
+declare function normalizeConfigForValidation(config: unknown): unknown;
 declare function mergeUseBlocks(globalUse: Record<string, unknown> | undefined, suiteUse: Record<string, unknown> | undefined, testUse: Record<string, unknown> | undefined, cliFlags: Record<string, unknown>): Record<string, unknown>;
-declare function formatConfigDebug(globalConfig: unknown, testConfig: unknown, flagOverrides: Record<string, unknown>): string;
+declare function formatConfigDebug(globalConfig: unknown, testConfig: unknown, flagOverrides: Record<string, unknown>, mask: MaskFn): string;
+/**
+ * The privacy declaration alone, read out of the RAW document without validating it
+ * (Phase 398 gap round — finding F-1 / review CR-01).
+ *
+ * WHY THIS EXISTS. The composition roots that emit telemetry read their config through a tolerant
+ * `try { resolveConfig() } catch { undefined }`, because refusing a surface over its telemetry
+ * configuration would be refusing the capability over the telemetry (T-398-32). That posture is
+ * right and is unchanged. What was wrong is that the `catch` collapsed TWO different states into
+ * one `undefined`:
+ *
+ *   1. there is no config file — nothing was ever declared, and
+ *   2. there IS one, it declares `analytics.privacy: true`, and it failed schema validation for
+ *      some unrelated reason (a missing `use.mobile.appState`, a legacy key, a typo three levels
+ *      away).
+ *
+ * In state 2 a user set a shipped privacy control and was transmitted anyway, silently, with the
+ * surface working normally so nothing ever looked wrong. A product cannot ship a config field and
+ * then honour it only when the REST of the document happens to validate.
+ *
+ * READING IS NOT VALIDATING. Extracting one boolean from a parsed document does not require the
+ * document to be well-formed anywhere else, so honouring the declaration costs the availability
+ * posture nothing: the surface still opens, still scaffolds, still runs.
+ *
+ * IT READS THE SAME FILE THE VALIDATOR READ. The path expression and the loader are literally the
+ * ones `resolveConfig` uses, immediately below — not a second spelling of "where the config lives".
+ * A privacy read that consults a different file than the validator did would be a new defect
+ * wearing this fix's clothes.
+ *
+ * THE UNPARSEABLE ARM FAILS CLOSED. If the file exists but is not YAML at all, no reader can tell
+ * whether the declaration is in there. The cost of opting out is lost telemetry; the cost of the
+ * other choice is transmitting against a declaration that may be sitting in the file. For a
+ * privacy control the doubt resolves toward the user. A MISSING file is not doubt — nothing was
+ * declared — so it stays `undefined`.
+ */
+declare function readAnalyticsPrivacyDeclaration(configPath?: string): Promise<{
+    analytics: {
+        privacy: boolean;
+    };
+} | undefined>;
 declare function resolveConfig(options: {
     configPath?: string;
     flags?: Record<string, unknown>;
     loadAuthPlugins?: boolean;
 }): Promise<AgentQaConfig>;
+declare function loadConfigPlugins(config: AgentQaConfig, configPath: string): Promise<void>;
+/** Resolve the writer-gated knowledge root without making each CLI surface import core directly. */
+declare function resolveConfiguredKnowledgeRoot(config: AgentQaConfig, configDir: string): string;
+/**
+ * The same root, from a RAW config (407 D-18/D-19).
+ *
+ * `doctor` deliberately loads the config unvalidated so it can REPORT on a broken one, so it
+ * never has an `AgentQaConfig` to hand the resolver above. The schema's own `dir` default is what
+ * makes the root knowable from a config that never mentions `knowledge` at all — reproducing that
+ * default at a call site would be a second answer to "where does this project keep its knowledge".
+ *
+ * `null` means the question has no answer for this host: the config could not be read, or its
+ * `knowledge` block is malformed enough that the directory cannot be named. It does NOT mean the
+ * directory is missing — that is the caller's own existence check, because "configured but absent"
+ * and "not configured" read the same to a resolver and differently to a person.
+ */
+declare function resolveRawConfigKnowledgeRoot(config: Record<string, unknown> | null, configPath: string): string | null;
 
 interface ResolvedTarget {
     name: string;
@@ -24,6 +149,8 @@ interface ResolvedTarget {
     appPackage?: string;
     appActivity?: string;
     device?: string;
+    /** D-06 (phase 401), 432 D-18: the target's declared environment; `undefined` means undeclared. */
+    environment?: 'local' | 'shared' | 'production';
 }
 interface TargetSummary {
     name: string;
@@ -32,9 +159,495 @@ interface TargetSummary {
 declare function resolveTarget(config: AgentQaConfig, targetName: string): ResolvedTarget;
 declare function listTargets(config: AgentQaConfig): TargetSummary[];
 
-declare function purgeTest(testPath: string, cacheDir: string, configContent?: string): Promise<number>;
-declare function purgeAll(cacheDir: string, force: boolean): Promise<number>;
+/**
+ * Per-test targeting is not possible under the redesigned cache: keys are opaque,
+ * content-addressed over masked step text + a runtime screenIdentityHash, and carry no raw
+ * step text on disk (D-06). `--test` therefore clears the whole branch-namespaced cache so
+ * the requested test's stale plans are guaranteed gone.
+ */
+declare function purgeTest(_testPath: string, cacheDir: string): Promise<number>;
+declare function purgeAll(cacheDir: string): Promise<number>;
+
+/** Provisional M2 malformed-output retry cap; intentionally not a user-facing config key. */
+declare const CURATOR_RETRY_CAP = 2;
+/** Provisional M2 neighbor presentation cap; intentionally not a user-facing config key. */
+declare const CURATOR_MAX_NEIGHBORS = 12;
+interface BuildCuratorAuthorDependencies {
+    /** The run's already-resolved registry profile. It is reused verbatim (D-03). */
+    profile: ModelProfile;
+    auth: ResolvedModelAuth;
+    mask: MaskFn;
+    createModelImpl?: typeof createModel;
+    resolveCapabilitiesImpl?: typeof resolveCapabilities;
+    createTokenAccountingImpl?: typeof createTokenAccounting;
+    signal?: AbortSignal;
+}
+/**
+ * Build the CLI-owned Curator author over the run's already-resolved model. The returned function
+ * reads no config and every provider call therefore traverses createModel's registry middleware.
+ */
+declare function buildCuratorAuthor(deps: BuildCuratorAuthorDependencies): CuratorAuthor;
+
+declare const nudgeResponseSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strict>;
+type NudgeResponse = z.infer<typeof nudgeResponseSchema>;
+
+interface NudgeDaemonOptions {
+    /** Resolved configured root; defaults only for legacy project-local callers. */
+    readonly knowledgeRoot?: string;
+    /** Absolute wall-clock deadline shared with the caller's complete operation. */
+    readonly deadlineMs?: number;
+    /** Request an empty terminal receipt when the caller gates completion on it. */
+    readonly requireReceipt?: boolean;
+    readonly signal?: AbortSignal;
+}
+/** Best-effort curation wake-up returning the durable session identity when acknowledged. */
+declare function nudgeDaemon(agentQaRoot: string, options?: NudgeDaemonOptions): Promise<NudgeResponse | undefined>;
+
+declare const completionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    runId: z.ZodString;
+    candidateId: z.ZodString;
+    attributedObservationId: z.ZodString;
+    observedStateDigest: z.ZodString;
+    result: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"ablated">;
+        crossCheck: z.ZodEnum<{
+            flipped: "flipped";
+            held: "held";
+            inconclusive: "inconclusive";
+            "not-run": "not-run";
+        }>;
+        corpusDigest: z.ZodString;
+        k: z.ZodNumber;
+        baseSeed: z.ZodNumber;
+        seeds: z.ZodArray<z.ZodNumber>;
+        seedHonored: z.ZodBoolean;
+        spend: z.ZodObject<{
+            modelCalls: z.ZodNumber;
+            screens: z.ZodNumber;
+            promptTokens: z.ZodNumber;
+            completionTokens: z.ZodNumber;
+        }, z.core.$strict>;
+        gate2Dir: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"error">;
+        message: z.ZodLiteral<"ablation-error">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"unavailable">;
+        reason: z.ZodLiteral<"ablation-unavailable">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"no-eval-root">;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+type CompletedCanaryAblation = z.infer<typeof completionSchema>;
+
+interface CanaryAblationInput {
+    handoff: CompletedRunHandoff;
+    runDir: string;
+    candidateId: string;
+    runId: string;
+    testId: string;
+    testIndex: number;
+    stepIndex: number;
+    attributedObservationId: string;
+}
+type CanaryAblationResult = {
+    kind: 'ablated';
+    crossCheck: CrossCheck;
+    corpusDigest: string;
+    k: number;
+    baseSeed: number;
+    seeds: number[];
+    seedHonored: boolean;
+    spend: {
+        modelCalls: number;
+        screens: number;
+        promptTokens: number;
+        completionTokens: number;
+    };
+    gate2Dir: string;
+} | {
+    kind: 'no-eval-root';
+} | {
+    kind: 'unavailable';
+    reason: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+type CanaryCorpusDigestResult = {
+    kind: 'digest';
+    corpusDigest: string;
+} | {
+    kind: 'no-eval-root';
+} | {
+    kind: 'unavailable';
+    reason: string;
+};
+interface CanaryAblation {
+    isNovel(input: {
+        product: string;
+        stateDigest: string;
+    }): Promise<boolean>;
+    stage(input: CanaryAblationInput & {
+        product: string;
+        stateDigest: string;
+        benefit: Benefit;
+    }): Promise<{
+        kind: 'staged' | 'already-staged' | 'not-novel' | 'no-eval-root' | 'target-unavailable' | 'write-conflict';
+    } | {
+        kind: 'unavailable';
+        reason: string;
+    } | {
+        kind: 'error';
+        message: string;
+    }>;
+    ablate(input: CanaryAblationInput): Promise<CanaryAblationResult>;
+    corpusDigest(): Promise<CanaryCorpusDigestResult>;
+    resolveCaps?(): Promise<{
+        maxAblations: number;
+        source: string;
+    }>;
+}
+interface CanaryCreditCounters {
+    credited: number;
+    rideAlongUncredited: number;
+    ablationCapExceeded: number;
+    ablationHeld: number;
+    ablationInconclusive: number;
+    ablationError: number;
+    rerunExcluded: number;
+    nonSignal: Record<NonSignalClass, number>;
+    staged: number;
+    stagingRefused: number;
+}
+interface CanaryCreditInput {
+    completedAblations: readonly CompletedCanaryAblation[];
+    saveCompletedAblation: (entry: CompletedCanaryAblation) => void;
+    maxAblations: number;
+    knowledgeRoot: string;
+    readBundleStateDigests: LocalCurationCapabilities['readCanonicalBundleStateDigests'];
+    attributions: readonly ProjectedCanaryAttribution[];
+    ablation?: CanaryAblation;
+    handoff: CompletedRunHandoff;
+    runDir: string;
+    observationIdOf: (outcome: CanaryOutcome) => string;
+}
+
+type NonSignalClass = 'environment' | 'timeout' | 'flake';
+interface ProjectCanaryOutcomesInput {
+    handoff: CompletedRunHandoff;
+    /**
+     * The run's persisted analysis artifact when one exists (389-06, D-10). Data, not a port:
+     * `emitCanaryOutcomes` loads it from the fold's own `runDir`; the pure projection takes it
+     * as an argument so identical (handoff, artifact) bytes keep yielding identical outcomes.
+     */
+    artifact?: RunAnalysisArtifact;
+    /**
+     * The circularity arbiter's per-record rows (422-16, D-20), when the handoff's own published
+     * sidecar is not the copy the caller holds — `emitCanaryOutcomes` supplies this only for the
+     * durable-recovery case below. ABSENT here means "read `handoff.misdirectionEvidence`", which
+     * is itself absent on every run written before 422. Data, never a port.
+     */
+    misdirectionEvidence?: readonly MisdirectionRecordResult[];
+    resolveCandidateAnchors: (id: RecordId) => CandidateAnchorResolution;
+}
+type CandidateAnchorResolution = {
+    kind: 'resolved';
+    anchors: Anchor[];
+} | {
+    kind: 'unresolved';
+    reason: 'not-found' | 'invalid' | 'lookup-error';
+    detail?: string;
+};
+type EmitCanaryOutcomeResult = {
+    kind: 'non-signal';
+    class: NonSignalClass;
+} | {
+    kind: 'emitted';
+} | {
+    kind: 'refused';
+    reason: 'emit-error';
+} | {
+    kind: 'unresolved';
+    reason: Extract<CandidateAnchorResolution, {
+        kind: 'unresolved';
+    }>['reason'];
+    detail?: string;
+};
+type EmitCanaryOutcomeDetail = {
+    staged?: never;
+    benefit?: never;
+    crossCheck?: never;
+    corpusDigestMoved?: never;
+    misdirectionFlipped?: never;
+    candidateId?: never;
+    stepIndex?: never;
+    testId: string;
+    testIndex: number;
+    outcome: {
+        kind: 'rerun-excluded';
+    };
+} | {
+    staged?: true;
+    benefit: CanaryOutcome['benefit'];
+    crossCheck?: CrossCheck;
+    corpusDigestMoved?: true;
+    /**
+     * 422-16 (D-20): this row reached the harmed-outcome writer on the arbiter's CAUSAL evidence,
+     * not on anchor contact. Distinct from `crossCheck` beside it, which is the Gate-2 ABLATION's
+     * answer about a positive — two different cross-checks, and conflating them would read a
+     * removal that proved harm as a removal that proved benefit.
+     */
+    misdirectionFlipped?: true;
+    candidateId: RecordId;
+    testId: string;
+    testIndex: number;
+    stepIndex: number;
+    outcome: EmitCanaryOutcomeResult;
+};
+interface EmitCanaryOutcomeReport {
+    canary: CanaryCreditCounters;
+    emitted: number;
+    refused: number;
+    unresolved: number;
+    /** D-12: per-source split of the planSource attribution stream; totals cover BOTH sources. */
+    procedure: {
+        emitted: number;
+        refused: number;
+        unresolved: number;
+    };
+    /**
+     * 422-16 (D-20): rows the arbiter's FLIPPED evidence sent to the harmed-outcome writer carry
+     * `misdirectionFlipped` on their DETAIL, and are counted from there rather than from a
+     * fourth total here. Two reasons, both deliberate. The consequence is the ordinary harmed
+     * outcome, so a parallel total would invite a reader to add it to `emitted`. And a required
+     * new member on this report would break every existing `emitCanaryOutcomes` double in the
+     * tree — the tail reads the rows it already renders, exactly as `candidateSummaryLine` does.
+     */
+    details: EmitCanaryOutcomeDetail[];
+}
+interface EmitCanaryOutcomesOptions {
+    credit?: Partial<Pick<CanaryCreditInput, 'ablation' | 'maxAblations' | 'readBundleStateDigests'>>;
+    handoff: CompletedRunHandoff;
+    /** Absolute agent-qa-knowledge root used for store lookup and durable queue emission. */
+    knowledgeRoot: string;
+    /** Absolute completed-run directory retained to keep the two post-verdict emit seams aligned. */
+    runDir: string;
+    emit: (outcome: CanaryOutcome) => void;
+}
+type AttributionSource = 'served-brief' | 'procedure-replay';
+type ProjectedCanaryAttribution = {
+    kind: 'rerun-excluded';
+    testId: string;
+    testIndex: number;
+} | {
+    kind: 'non-signal';
+    source: AttributionSource;
+    class: NonSignalClass;
+    candidateId: RecordId;
+    testId: string;
+    testIndex: number;
+    stepIndex: number;
+} | {
+    kind: 'outcome';
+    source: AttributionSource;
+    outcome: CanaryOutcome;
+    /** 422-16 (D-20): selected by the arbiter's flipped row rather than by anchor contact. */
+    misdirectionFlipped?: true;
+} | {
+    kind: 'unresolved';
+    source: AttributionSource;
+    candidateId: RecordId;
+    testId: string;
+    testIndex: number;
+    stepIndex: number;
+    reason: Extract<CandidateAnchorResolution, {
+        kind: 'unresolved';
+    }>['reason'];
+    detail?: string;
+};
+/** Pure Pin-1 projection: identical handoff + canonical snapshot yields identical outcome bytes. */
+declare function projectCanaryOutcomes(input: ProjectCanaryOutcomesInput): CanaryOutcome[];
+/** Resolves anchors read-only, credits evidence, then emits every attribution in isolation. */
+declare function emitCanaryOutcomes(opts: EmitCanaryOutcomesOptions): Promise<EmitCanaryOutcomeReport>;
+
+interface EmitCurationCandidatesOptions {
+    handoff: CompletedRunHandoff;
+    /** Absolute completed-run directory containing runner-local's blobs/ subdirectory. */
+    runDir: string;
+    /** Absolute agent-qa-knowledge root that owns the durable queue. */
+    knowledgeRoot: string;
+    mask?: MaskFn;
+}
+type EmitCandidateOutcome = EnqueueCurationCandidateProjectionOutcome | {
+    kind: 'refused';
+    reason: 'artifact-io-error';
+};
+interface EmitCandidateDetail {
+    candidateId?: string;
+    /** The projecting candidate's kind: per-kind outcome attribution from the report alone (381-50). */
+    kind: CurationCandidateProjection['kind'];
+    outcome: EmitCandidateOutcome;
+}
+interface EmitReport {
+    enqueued: number;
+    coalesced: number;
+    capExceeded: number;
+    refused: number;
+    details: EmitCandidateDetail[];
+}
+/**
+ * Resolves runner-local artifact blobs and synchronously publishes each candidate in isolation.
+ * Queue publication owns temp-write, fsync, cap enforcement, and atomic rename semantics.
+ */
+declare function emitCurationCandidates(opts: EmitCurationCandidatesOptions): EmitReport;
+
+type ResolveTrustPriors = () => TrustPriorTable | undefined;
+
+type RunCurationContext = {
+    readonly mask: MaskFn;
+    readonly knowledgeRoot: string;
+} | {
+    readonly handBack: string;
+};
+declare function resolveRunCurationContext(input: {
+    readonly agentQaRoot: string;
+    readonly runId: string;
+    readonly drainerKnowledgeRoot: string;
+}): Promise<RunCurationContext>;
+
+declare const CURATION_TAIL_RECEIPT_FILE = "curation-tail-receipt.json";
+/** The receipt's key set and stamp must match exactly; anything else refolds the run once. */
+declare const CURATION_TAIL_RECEIPT_SCHEMA_VERSION = 2;
+interface CurationTailReceipt {
+    /** Fixed successful membership; absent on handed-off receipts and when no validated snapshot was recorded. */
+    snapshot?: CurationSnapshot;
+    /** Counts recorded beside the snapshot. */
+    curated?: number;
+    deprecated?: number;
+    canary: CanaryCreditCounters;
+    schemaVersion: typeof CURATION_TAIL_RECEIPT_SCHEMA_VERSION;
+    runId: string;
+    handoffDigest: string;
+    /**
+     * Run-outcome projection component: a version bump refolds already-receipted runs.
+     *
+     * This field alone only re-RUNS them (393 CR-02). The per-run fold behind it short-circuits on
+     * the durable applied-runs marker, so what actually re-derives the rows at a new version is the
+     * once-per-sweep `reconcileRunOutcomesProjection` below; the receipts then rewrite here at the
+     * new version through this same sweep.
+     */
+    projectionVersion: number;
+    drainKind: 'drained' | 'handed-off';
+    /** The standing writer that accepted the handoff; null when this run drained inline. */
+    handoffHolderPid: number | null;
+    /** Stable run-side provenance, ordered before the receipt bytes are committed. */
+    candidateIds: string[];
+}
+type CurationTailModelDeps = Pick<BuildCuratorAuthorDependencies, 'profile' | 'auth'>;
+interface CurationTailLogger {
+    warn(message: string): void;
+    /** 381-50: carries the per-run candidate summary line — diagnosis, never control flow. */
+    info?(message: string): void;
+}
+interface CurationTailOperations {
+    /** 2026-09-07, 418 D-01: eval-composing hosts bind this in Plan 05; BYOM omits it. */
+    canaryAblation?: CanaryAblation;
+    loadCompletedRunHandoff: typeof loadCompletedRunHandoff;
+    resolveKnowledgeRoot: typeof resolveKnowledgeRoot;
+    runSafetyScope: typeof runSafetyScope;
+    emitCurationCandidates: typeof emitCurationCandidates;
+    openKnowledgeReader(config: OpenServingKnowledgeReaderConfig): KnowledgeHintReader;
+    emitCanaryOutcomes: typeof emitCanaryOutcomes;
+    foldRunOutcomes: LocalCurationCapabilities['foldRunOutcomes'];
+    reconcileRunOutcomesProjection: LocalCurationCapabilities['reconcileRunOutcomesProjection'];
+    acquireWriterLease: LocalCurationCapabilities['maintenance']['acquireWriterLease'];
+    releaseLease: LocalCurationCapabilities['maintenance']['releaseLease'];
+    buildCuratorAuthor: typeof buildCuratorAuthor;
+    drainQueue: LocalCurationCapabilities['drainQueue'];
+    listCompletedRunDirs(agentQaRoot: string): string[];
+    readCurationTailReceipt(runDir: string): CurationTailReceipt | undefined;
+    writeCurationTailReceipt(runDir: string, receipt: CurationTailReceipt): void;
+    nudgeDaemon: typeof nudgeDaemon;
+    resolveRunCurationContext: typeof resolveRunCurationContext;
+}
+/**
+ * Writer authority the CALLER already holds (388-02, Pitfall 7).
+ *
+ * The fold acquires no lease of its own when this is present. That is not an optimisation: a
+ * process holding the writer lease that calls `acquireWriterLease` again is told `held` — by
+ * itself — and would hand its own work off to nobody (the 387-08 D-18 shape).
+ */
+interface CurationWriterAuthority {
+    leaseId: string;
+    epoch: number;
+}
+interface RunCurationTailOptions {
+    resolveTrustPriors?: ResolveTrustPriors;
+    maxAblations?: number;
+    /** Built once by the caller; synchronous per candidate inside writer authority. */
+    resolvePromotionPosture?: ResolvePromotionPosture;
+    /** 418 D-13: reuse prepared identity but bind each swept handoff's own ordinal. */
+    resolvePromotionPostureForRun?: (buildOrdinal: number, scope?: ScopeKey) => Promise<ResolvePromotionPosture | undefined>;
+    runId: string;
+    /** Absolute `.agent-qa` runtime root the run handoff lives under. */
+    agentQaRoot: string;
+    knowledgeConfig: {
+        dir: string;
+    };
+    configDir: string;
+    mask?: MaskFn;
+    /** The exact already-resolved planner profile and auth used by the run. */
+    modelDeps?: CurationTailModelDeps;
+    signal?: AbortSignal;
+    log: CurationTailLogger;
+    /** 388-02: the sweep runs under the post-run tail's held lease when there is one. */
+    authority?: CurationWriterAuthority;
+    /** 388-02 (D-03): absolute wall-clock stop point shared with the one post-run budget. */
+    deadlineMs?: number;
+    /** Focused test seam. Production callers omit it. */
+    operations?: Partial<CurationTailOperations>;
+}
+declare function curationTailHandoffDigest(handoff: unknown): string;
+/**
+ * Run the post-verdict curation fold. The caller fixes its exit code before awaiting this function;
+ * every failure is logged here and intentionally resolves so learning can never change the verdict.
+ */
+declare function runCurationTail(opts: RunCurationTailOptions): Promise<void>;
+interface RunVerdictFirstCurationTailOptions {
+    /** The complete verdict-derived process code, fixed before the tail begins. */
+    exitCode: number;
+    detach: boolean;
+    /**
+     * The durable hand-off, run BEFORE the detach short-circuit (388-02, D-03 / Pitfall 3).
+     *
+     * `--detach` means "do not spend this process on the work", not "do not record that the
+     * work exists". The enqueue is the record; the drain is the spending. Putting it inside
+     * `runTail` would have made a detached run the one posture that silently loses its
+     * analysis, which is the opposite of what detaching asks for.
+     */
+    enqueue?(): Promise<void>;
+    runTail(): Promise<void>;
+    /**
+     * The user-facing close-out, run on BOTH paths (388-04, D-08).
+     *
+     * The detach short-circuit below returns before `runTail`, and the one posture that most
+     * needs a line about work left queued is exactly that one — so this cannot live inside the
+     * tail. It is told which gate was applied rather than inferring it, because the gate is
+     * this function's own knowledge and nothing downstream can see it.
+     */
+    finish?(input: {
+        detached: boolean;
+    }): Promise<void>;
+    /** Defensive call-site boundary; runCurationTail itself already never rejects. */
+    onUnexpectedError?(error: unknown): void;
+}
+/** Await the optional tail without permitting it to replace the already-fixed verdict code. */
+declare function runVerdictFirstCurationTail(opts: RunVerdictFirstCurationTailOptions): Promise<number>;
 
 declare const VERSION: string;
 
-export { type ResolvedTarget, type TargetSummary, VERSION, deepMerge, formatConfigDebug, listTargets, loadConfigFile, loadEnvOverrides, loadRequiredConfigFile, mergeConfigs, mergeUseBlocks, mergeWithTestConfig, purgeAll, purgeTest, resolveConfig, resolveTarget };
+export { type BuildCuratorAuthorDependencies, CURATION_TAIL_RECEIPT_FILE, CURATION_TAIL_RECEIPT_SCHEMA_VERSION, CURATOR_MAX_NEIGHBORS, CURATOR_RETRY_CAP, ConfigFileNotFoundError, ConfigFileNotYamlError, type CurationTailLogger, type CurationTailModelDeps, type CurationTailOperations, type CurationTailReceipt, type EmitCanaryOutcomeDetail, type EmitCanaryOutcomeReport, type EmitCanaryOutcomeResult, type EmitCanaryOutcomesOptions, type ProjectCanaryOutcomesInput, type ResolvedTarget, type RunCurationTailOptions, type RunVerdictFirstCurationTailOptions, type TargetSummary, VERSION, buildCuratorAuthor, curationTailHandoffDigest, deepMerge, emitCanaryOutcomes, formatConfigDebug, listTargets, loadConfigFile, loadConfigPlugins, loadEnvOverrides, loadRequiredConfigFile, mergeConfigs, mergeUseBlocks, mergeWithTestConfig, normalizeConfigForValidation, projectCanaryOutcomes, purgeAll, purgeTest, readAnalyticsPrivacyDeclaration, resolveConfig, resolveConfiguredKnowledgeRoot, resolveRawConfigKnowledgeRoot, resolveTarget, runCurationTail, runVerdictFirstCurationTail };