/**
 * Zod schema + gate-to-atom mapping for the ADR-051 evidence atom grammar.
 *
 * `cleo verify <task-id> --evidence "<atoms>"` accepts a semicolon-delimited
 * list of evidence atoms. Each atom carries a kind prefix and a payload. The
 * grammar lives in three places today:
 *
 *   1. {@link EvidenceAtomSchema} — Zod discriminated union covering every
 *      parseable atom shape (this file).
 *   2. {@link GATE_EVIDENCE_REQUIREMENTS} — gate → satisfying atom-combination
 *      map (this file).
 *   3. `packages/core/src/tasks/evidence.ts` — runtime parser + filesystem /
 *      git / tool validators. The runtime parser delegates to
 *      {@link parseEvidenceString} below for the syntactic split.
 *
 * The schema is exposed for LLM agents and IDE tooling that want to validate
 * an evidence string client-side BEFORE invoking `cleo verify`. The CLI
 * runtime continues to perform the full filesystem-aware validation pass
 * because Zod cannot check that a commit SHA is reachable or that a file
 * exists on disk.
 *
 * The atom shapes here mirror the `ParsedAtom` union in
 * `packages/core/src/tasks/evidence.ts` exactly. Behavior parity with the
 * pre-T10337 ad-hoc parser is required — see the T10337 test suite for the
 * full parity matrix.
 *
 * @task T10337
 * @saga T10326
 * @adr ADR-051
 */
import { z } from 'zod';
import type { VerificationGate } from './task.js';
/**
 * `commit:<sha>` atom — references a git commit by full or short SHA.
 *
 * Format: `commit:<7-40 hex chars>`. The schema accepts any 7-40-character
 * lowercase hex SHA; the runtime validator additionally checks reachability
 * from the task branch and the AC-file content-intersect rule (T9245).
 *
 * @task T832
 */
export declare const commitAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"commit">;
    sha: z.ZodString;
}, z.core.$strip>;
/**
 * `files:<p1,p2,...>` atom — list of file paths that the task touched.
 *
 * Format: `files:<comma-separated paths>`. The runtime validator additionally
 * stats each path and records its sha256.
 *
 * @task T832
 */
export declare const filesAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"files">;
    paths: z.ZodArray<z.ZodString>;
}, z.core.$strip>;
/**
 * `test-run:<path>` atom — path to a structured test runner JSON output
 * (vitest, jest, pytest, cargo-nextest, etc.).
 *
 * Format: `test-run:<absolute or project-relative path>`. The runtime validator
 * loads the file, parses the JSON, and rejects when failedTests > 0 or
 * totalTests === 0.
 *
 * @task T832
 */
export declare const testRunAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"test-run">;
    path: z.ZodString;
}, z.core.$strip>;
/**
 * `tool:<name>` atom — runs a project-resolved canonical tool and accepts
 * exit-code 0.
 *
 * Format: `tool:<canonical name or legacy alias>`. Canonical names: `test`,
 * `build`, `lint`, `typecheck`, `audit`, `security-scan`. Legacy aliases
 * (`pnpm-test`, `tsc`, `biome`, `cargo-test`, `pytest`, …) still resolve via
 * the runtime resolver (ADR-061 / T1534).
 *
 * @task T832
 * @task T1534
 */
export declare const toolAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"tool">;
    tool: z.ZodString;
}, z.core.$strip>;
/**
 * `url:<href>` atom — soft evidence pointing to an external artifact (docs,
 * dashboard, etc.).
 *
 * Format: `url:<http(s)://...>`. The runtime validator requires the
 * `http://` or `https://` scheme.
 *
 * @task T832
 */
export declare const urlAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"url">;
    url: z.ZodString;
}, z.core.$strip>;
/**
 * `note:<text>` atom — free-form note used for soft evidence and waivers.
 *
 * Format: `note:<1-512 chars>`. The runtime validator caps the note at 512
 * characters to keep the gate-evidence record bounded.
 *
 * @task T832
 */
export declare const noteAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"note">;
    note: z.ZodString;
}, z.core.$strip>;
/**
 * `decision:<id>` atom — references a `brain_decisions` row that IS the
 * canonical artifact for a decision-only task. Satisfies the `implemented`
 * gate when combined with `files:` pointing to a research note or with
 * `note:` (T1875).
 *
 * Format: `decision:<id>` (e.g. `decision:D-arch-001`). The runtime validator
 * looks up the row and requires `confirmation_state` ∈ {`accepted`,
 * `proposed`}.
 *
 * @task T1875
 */
export declare const decisionAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"decision">;
    decisionId: z.ZodString;
}, z.core.$strip>;
/**
 * `pr:<number>` atom — references a GitHub PR by number. Satisfies BOTH
 * `testsPassed` and `qaPassed` simultaneously when the PR is MERGED and every
 * required-workflow check is green (T9764). Extended in T9838 to satisfy
 * `implemented` because the merge commit IS the landing artifact.
 *
 * Format: `pr:<positive integer>` (e.g. `pr:357`).
 *
 * @task T9764
 * @task T9838
 */
export declare const prAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"pr">;
    prNumber: z.ZodNumber;
}, z.core.$strip>;
/**
 * `loc-drop:<fromLines>:<toLines>` atom — proves that a migrated engine shed
 * lines. Required for the `implemented` gate when the task carries the
 * `engine-migration` label (T1604).
 *
 * Format: `loc-drop:<non-negative integer>:<non-negative integer>`.
 * The schema admits any non-negative pair; the runtime validator additionally
 * requires `fromLines > 0` and `toLines <= fromLines`.
 *
 * @task T1604
 */
export declare const locDropAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"loc-drop">;
    fromLines: z.ZodNumber;
    toLines: z.ZodNumber;
}, z.core.$strip>;
/**
 * `callsite-coverage:<symbol>:<sourcePath>` atom — proves that an exported
 * symbol has ≥1 production callsite outside its own source file, test files,
 * and dist directories. Required for the `implemented` gate when the task
 * carries the `callsite-coverage` label (T1605).
 *
 * @task T1605
 */
export declare const callsiteCoverageAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"callsite-coverage">;
    symbolName: z.ZodString;
    relativeSourcePath: z.ZodString;
}, z.core.$strip>;
/**
 * Strict AC UUID regex (lowercase, hyphenated 8-4-4-4-12 with v4/v5 major
 * version nibble and `[89ab]` variant nibble). T10586 keeps legacy random
 * UUIDv4 AC ids valid while allowing deterministic UUIDv5-shaped ids derived
 * from task id + source key.
 *
 * Validators MUST reject mixed-case to prevent silent dedupe failures — the
 * canonical column casing is lowercase per ADR-079-r1 §2.1.
 *
 * @task T10506
 * @adr ADR-079-r2 §2.1
 */
export declare const AC_UUID_REGEX: RegExp;
/**
 * Positional-alias regex for `satisfies:` atom target-AC identifiers per
 * ADR-079-r2 §2.1 ABNF (`ac-alias` production). Format: `AC<1-4 digits>`
 * (capped at AC9999 — three orders of magnitude above realistic per-task AC
 * counts).
 *
 * @task T10506
 * @adr ADR-079-r2 §2.1
 */
export declare const AC_ALIAS_REGEX: RegExp;
/**
 * Task-id regex for `satisfies:` atom target-task identifiers per ADR-079-r2
 * §2.1 ABNF (`task-id` production). Format: `T<1-7 digits>` (capped at
 * T9999999 — three orders of magnitude above current CLEO task IDs as of
 * 2026-05-24).
 *
 * @task T10506
 * @adr ADR-079-r2 §2.1
 */
export declare const SATISFIES_TASK_ID_REGEX: RegExp;
/**
 * Version-pin regex for `satisfies:` atom optional `@<ts>` suffix per
 * ADR-079-r2 §2.1 ABNF (`version-pin` production). Format: `YYYYMMDDhhmmss`
 * (ISO-8601-basic timestamp, 14 digits).
 *
 * @task T10506
 * @adr ADR-079-r2 §2.1
 */
export declare const SATISFIES_VERSION_PIN_REGEX: RegExp;
/**
 * `satisfies:<task-id>#<ac-id>[@<version-pin>]` atom — cross-task AC binding
 * per ADR-079-r2 §2.1 (full grammar) and ADR-079-r1 §2.4 (basic shape).
 *
 * Format:
 *
 *   - `satisfies:T1234#a1b2c3d4-5e6f-4890-abcd-ef1234567890`   — canonical
 *     UUID form (preferred for long-lived specs).
 *   - `satisfies:T1234#AC2`                                    — positional
 *     alias form (preferred in fresh PRs where the target task's AC list
 *     is stable).
 *   - `satisfies:T1234#AC2@20260524223045`                     — alias +
 *     optional version-pin (Validator emissions where pin-on-mint is
 *     required by ADR-079-r2 §3.4).
 *
 * Exactly ONE of `targetAcId` (UUID form) or `targetAcAlias` (alias form)
 * is populated per parsed atom. `versionPin` is always optional.
 *
 * ## Scope
 *
 * This Zod schema covers PARSING ONLY. The runtime validator semantics —
 * the 5-check accept/reject pipeline (target exists, target not terminal,
 * AC exists, same-saga scope rule) — ship in T10507 alongside the
 * `evidence_satisfies_bindings` side-effect table.
 *
 * Per ADR-079-r2 §2.2 the maximum atom length is 120 chars; the schema does
 * NOT enforce length here because the per-field regexes already cap the
 * surface (`satisfies:` + 8-char T+digits + `#` + 36-char UUID + `@` +
 * 14-char pin = 78 chars max — well under 120).
 *
 * @task T10506
 * @adr ADR-079-r2 §2.1
 * @adr ADR-079-r1 §2.4
 */
export declare const satisfiesAtomSchema: z.ZodObject<{
    kind: z.ZodLiteral<"satisfies">;
    targetTaskId: z.ZodString;
    targetAcId: z.ZodOptional<z.ZodString>;
    targetAcAlias: z.ZodOptional<z.ZodString>;
    versionPin: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
/**
 * Zod discriminated union covering every parseable evidence atom prefix.
 *
 * Use `EvidenceAtomSchema.safeParse(atom)` to validate a single atom client-
 * side BEFORE invoking `cleo verify`. The runtime parser in
 * `packages/core/src/tasks/evidence.ts` performs filesystem/git/tool checks
 * on top of this syntactic schema.
 *
 * Atom kinds:
 *   - `commit`             — git commit SHA (T832)
 *   - `files`              — touched file paths (T832)
 *   - `test-run`           — structured test runner JSON (T832)
 *   - `tool`               — project-resolved tool exit code (T832 / T1534)
 *   - `url`                — soft external pointer (T832)
 *   - `note`               — free-form note (T832)
 *   - `decision`           — brain_decisions row reference (T1875)
 *   - `pr`                 — merged-PR retroactive proof (T9764 / T9838)
 *   - `loc-drop`           — engine-migration LOC reduction (T1604)
 *   - `callsite-coverage`  — exported-symbol production callsite (T1605)
 *   - `satisfies`          — cross-task AC binding (T10506 / ADR-079-r2;
 *                            validator semantics ship in T10507)
 *
 * @task T10337
 * @adr ADR-051
 */
export declare const EvidenceAtomSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
    kind: z.ZodLiteral<"commit">;
    sha: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"files">;
    paths: z.ZodArray<z.ZodString>;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"test-run">;
    path: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"tool">;
    tool: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"url">;
    url: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"note">;
    note: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"decision">;
    decisionId: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"pr">;
    prNumber: z.ZodNumber;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"loc-drop">;
    fromLines: z.ZodNumber;
    toLines: z.ZodNumber;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"callsite-coverage">;
    symbolName: z.ZodString;
    relativeSourcePath: z.ZodString;
}, z.core.$strip>, z.ZodObject<{
    kind: z.ZodLiteral<"satisfies">;
    targetTaskId: z.ZodString;
    targetAcId: z.ZodOptional<z.ZodString>;
    targetAcAlias: z.ZodOptional<z.ZodString>;
    versionPin: z.ZodOptional<z.ZodString>;
}, z.core.$strip>], "kind">;
/**
 * Inferred TypeScript type for a parsed evidence atom.
 *
 * This is the pre-validation shape emitted by {@link parseEvidenceString}
 * — distinct from the post-validation `EvidenceAtom` in `./task.ts` which
 * carries fields populated by the runtime validator (sha256, exitCode, etc.).
 *
 * @task T10337
 */
export type EvidenceAtom = z.infer<typeof EvidenceAtomSchema>;
/** Discriminant union of every atom kind accepted by {@link EvidenceAtomSchema}. */
export type EvidenceAtomKind = EvidenceAtom['kind'];
/**
 * Per-gate evidence requirement spec.
 *
 * Each entry of `oneOf` is a satisfying atom-combination — the gate is
 * satisfied IFF EVERY kind listed in at least ONE of the combinations is
 * present among the supplied atoms.
 *
 * A single-element combination `['pr']` means "one `pr:` atom alone
 * satisfies the gate". A two-element combination `['commit', 'files']` means
 * "both a `commit:` atom AND a `files:` atom must be present".
 *
 * @task T10337
 * @adr ADR-051 §2.3
 */
export interface GateEvidenceRequirement {
    /** Alternative satisfying combinations — ANY one is sufficient. */
    oneOf: ReadonlyArray<ReadonlyArray<EvidenceAtomKind>>;
}
/**
 * Mapping from each {@link VerificationGate} to its satisfying atom
 * combinations. Mirrors the legacy `GATE_EVIDENCE_MINIMUMS` table in
 * `packages/core/src/tasks/evidence.ts` exactly — behavior parity required
 * by T10337.
 *
 * ## Why two alternatives for `implemented`?
 *
 * The `implemented` gate accepts six different evidence shapes:
 *
 *   - `[commit, files]`   — standard: commit SHA + touched file list.
 *   - `[commit, note]`    — deletion-safe: commit SHA + descriptive note
 *                           (when the implementation deleted files there
 *                           are none left to anchor `files:`).
 *   - `[decision, files]` — decision-only task: brain_decisions row +
 *                           research-note file (T1875).
 *   - `[decision, note]`  — decision-only task without research note.
 *   - `[pr]`              — merged-PR retroactive proof (T9838 extension
 *                           of T9764).
 *
 * ## Why is `qaPassed` listed as `['tool']` not `['tool', 'tool']`?
 *
 * The pre-T10337 runtime enforced "at least one atom of kind `tool` is
 * present" — it did NOT count distinct tool names. The convention `tool:lint`
 * + `tool:typecheck` is documented in AGENTS.md as best-practice but the
 * gate is satisfied by a single tool atom (e.g. `tool:test` when test
 * already runs lint + typecheck pre-flight). Behavior parity requires that
 * single-tool atoms continue to pass.
 *
 * @task T10337
 * @adr ADR-051 §2.3
 */
export declare const GATE_EVIDENCE_REQUIREMENTS: Readonly<Record<VerificationGate, GateEvidenceRequirement>>;
/**
 * Result of {@link validateEvidenceForGate}.
 *
 * Success carries no extra payload (the caller already holds the atom list).
 * Failure carries:
 *   - {@link EvidenceValidationFailure.message} — the legacy single-line
 *     `Gate '<gate>' requires evidence: [<combo>] OR [<combo>]` format,
 *     preserved byte-for-byte for backward-compat with surfaces and tests
 *     that match against it.
 *   - {@link EvidenceValidationFailure.hint} — a richer, multi-line,
 *     example-bearing remediation hint suitable for CLI `fix:` surfaces.
 *     Added by T9949 so `E_EVIDENCE_INSUFFICIENT` errors point clearly at
 *     the alternative atom the caller needs (e.g. "this gate requires
 *     real proof — note: alone is not accepted; use commit+files,
 *     commit+note, or pr instead").
 */
export interface EvidenceValidationFailure {
    readonly ok: false;
    readonly message: string;
    readonly hint: string;
}
export type EvidenceValidationResult = {
    readonly ok: true;
} | EvidenceValidationFailure;
/**
 * Format the satisfying-combinations spec for a gate as the legacy
 * `[commit AND files] OR [pr]` string used in CLI error messages.
 *
 * Exposed so consumers can render the same hint text without re-computing it.
 *
 * @task T10337
 */
export declare function formatGateRequirement(gate: VerificationGate): string;
/**
 * Produce a multi-line, example-bearing remediation hint for a gate.
 *
 * Designed for CLI `fix:` surfaces so `E_EVIDENCE_INSUFFICIENT` errors point
 * the caller at the specific alternative atom shape they need. The hint lists
 * every satisfying combination as a copy-pasteable `cleo verify` invocation
 * plus a note-specific clarification when the gate does NOT accept `note:`
 * alone.
 *
 * The motivating bug (T9949) was that note-only deliverables (decision-only
 * tasks, deletion-only refactors) hit `E_EVIDENCE_INSUFFICIENT` with the
 * legacy single-line error and had to consult ADR-051 to figure out which
 * additional atom kind the gate required. The richer hint inlines the answer.
 *
 * @param gate - Verification gate the hint is for.
 * @returns Multi-line remediation hint suitable for an `engineError({fix:})`
 *   surface. Always ends in a clarifying sentence about whether `note:` alone
 *   is accepted for the gate.
 *
 * @example
 * ```ts
 * formatGateRequirementHint('implemented');
 * // "Gate 'implemented' requires programmatic evidence. Use ONE of:
 * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;files:path/a.ts,path/b.ts'
 * //   - cleo verify T#### --gate implemented --evidence 'commit:<sha>;note:<short description>'
 * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;files:path/a.ts,path/b.ts'
 * //   - cleo verify T#### --gate implemented --evidence 'decision:D-arch-001;note:<short description>'
 * //   - cleo verify T#### --gate implemented --evidence 'pr:357'
 * // Note: 'note:' alone is NOT accepted for this gate — pair it with 'commit:' or 'decision:'."
 * ```
 *
 * @task T9949
 * @adr ADR-051 §2.3
 */
export declare function formatGateRequirementHint(gate: VerificationGate): string;
/**
 * Check whether a set of parsed atoms satisfies the requirement spec for
 * `gate`.
 *
 * Returns `{ ok: true }` when ANY combination in `GATE_EVIDENCE_REQUIREMENTS[gate].oneOf`
 * is fully present in `atoms` (matched by kind). Returns
 * `{ ok: false, message }` otherwise — the message matches the legacy
 * `checkGateEvidenceMinimum()` format byte-for-byte so error surfaces do not
 * regress.
 *
 * Atoms must already be parsed (via {@link parseEvidenceString} or
 * {@link EvidenceAtomSchema}); the helper does NOT re-validate the atom
 * payload. Use {@link EvidenceAtomSchema.safeParse} first if the input came
 * from an untrusted source.
 *
 * @param gate - Verification gate being checked.
 * @param atoms - Already-parsed evidence atoms.
 * @returns Pass / fail with a human-readable failure message.
 *
 * @example
 * ```ts
 * const atoms = parseEvidenceString('commit:abc1234;files:src/foo.ts');
 * validateEvidenceForGate('implemented', atoms); // { ok: true }
 * validateEvidenceForGate('testsPassed', atoms);
 * // { ok: false, message: "Gate 'testsPassed' requires evidence: [test-run] OR [tool] OR [pr]" }
 * ```
 *
 * @task T10337
 * @adr ADR-051 §2.3
 */
export declare function validateEvidenceForGate(gate: VerificationGate, atoms: ReadonlyArray<{
    kind: EvidenceAtomKind;
}>): EvidenceValidationResult;
/**
 * Error class thrown by {@link parseEvidenceString} when the input is
 * malformed. Carries a {@link reason} suitable for the CLI `fix:` hint.
 *
 * Pure data — no dependency on `@cleocode/contracts/errors` (which would
 * pull the CleoError import surface into every consumer that just wants
 * syntactic validation).
 *
 * @task T10337
 */
export declare class EvidenceParseError extends Error {
    /** Hint text suitable for an `fix:` message in the CLI surface. */
    readonly fix: string;
    constructor(message: string, fix: string);
}
/**
 * Parse the raw CLI `--evidence` string into structured atoms.
 *
 * Syntax:
 * ```
 * evidence-list := atom (';' atom)*
 * atom          := kind ':' payload
 * ```
 *
 * The payload format depends on `kind`:
 *
 *   - `files`             — comma-separated paths
 *   - `loc-drop`          — `<fromLines>:<toLines>` (two integers)
 *   - `callsite-coverage` — `<symbolName>:<relativeSourcePath>`
 *   - `pr`                — positive integer
 *   - everything else     — opaque payload string until the next `;`
 *
 * A `state:MERGED` modifier may follow a `pr:<num>` atom and is consumed
 * in-place (no separate atom is emitted) — see T9838. Any other usage of
 * `state:` is rejected.
 *
 * Whitespace surrounding the `;` separators and around `kind`/`payload` is
 * trimmed. Empty chunks are skipped (consecutive `;;` is tolerated).
 *
 * @param raw - Raw `--evidence` string.
 * @returns Parsed atoms ready for {@link validateEvidenceForGate} or for
 *   the runtime validator in `packages/core/src/tasks/evidence.ts`.
 * @throws {@link EvidenceParseError} when the input is malformed.
 *
 * @example
 * ```ts
 * parseEvidenceString('commit:abc1234;files:src/foo.ts,src/bar.ts;tool:lint');
 * // [
 * //   { kind: 'commit', sha: 'abc1234' },
 * //   { kind: 'files', paths: ['src/foo.ts', 'src/bar.ts'] },
 * //   { kind: 'tool', tool: 'lint' },
 * // ]
 * ```
 *
 * @task T10337
 * @adr ADR-051
 */
export declare function parseEvidenceString(raw: string): EvidenceAtom[];
//# sourceMappingURL=evidence-atom-schema.d.ts.map