/**
 * Unified protocol-linter entry points for `DataContract`.
 *
 * Two reporting modes share one rule registry:
 *
 *   - {@link validateContract} — strict; runs phased validation and
 *     throws {@link ContractValidationError} on the FIRST phase that
 *     produces errors. Used at every protocol boundary (render handler,
 *     blueprint registration, future synth output gate).
 *
 *   - {@link lintContract} — graded; runs ALL phases unconditionally
 *     and returns errors + warnings together. Used by authoring
 *     tools (synth's self-correction loop, blueprint registration's
 *     warning surfaces, future contract-author tooling).
 *
 * **Phased execution** (stop-at-first-error-class for `validateContract`):
 *
 *   ```
 *   phase 1: shape          (zod wire-shape validation)
 *   phase 2: retired        (CTR_RETIRED_FIELD — dead top-level fields)
 *   phase 3: schema-meta    (CTR_SCHEMA_META_INVALID — Ajv strict on inner schemas)
 *   phase 4: references     (CTR_REF_*, CTR_DUP_NAME, CTR_RESERVED_NAME)
 *   phase 5: schema compat  (CTR_SCHEMA_INCOMPAT)
 *   phase 6: hygiene        (LINT_*  — graded, warnings only)
 *   ```
 *
 * Errors are reported one phase at a time during strict validation so
 * the LLM gets a clean signal during iterative authoring — fixing a
 * shape bug first, then references, then schemas, then hygiene. The
 * graded mode emits every issue at once so authoring tools can
 * present a complete checklist.
 */
import { DomainError } from '../errors/domain-error.js';
/**
 * Severity classification for a {@link ContractIssue}. Strict
 * `validateContract` throws on `'error'`; graded `lintContract`
 * surfaces both, partitioned by severity.
 */
export type ContractIssueSeverity = 'error' | 'warn';
/**
 * Phase classification for a {@link ContractIssue}. Surfaced so
 * authoring tools can render issues grouped by phase + drive the
 * "fix one phase at a time" UX.
 */
export type ContractLintPhase = 'shape' | 'retired' | 'schema-meta' | 'references' | 'schema-compat' | 'hygiene';
/**
 * One observation about a contract from the linter's perspective.
 *
 * Stable-code-keyed (vs. the existing per-module `ContractViolation`
 * shape) so authoring tools can pattern-match on `code` and drive
 * fix workflows. The pre-existing per-module violation types
 * (`CrossReferenceViolation`, `NameInvariantViolation`,
 * `SchemaCompatViolation`) map into this shape via the internal
 * conversion helpers in this file; consumers of `lintContract` /
 * `validateContract` see only `ContractIssue`.
 */
export interface ContractIssue {
    /** Stable error code (e.g., 'CTR_REF_NEXT_STEP', 'CTR_DUP_NAME'). */
    readonly code: string;
    readonly severity: ContractIssueSeverity;
    readonly phase: ContractLintPhase;
    /**
     * Field path into the contract identifying the offending entry.
     * Uses dotted JS-style notation matching the per-module
     * `ContractViolation.field` convention
     * (`actionSpec.archive.nextStep`).
     */
    readonly path: string;
    /** Human-readable violation prose. */
    readonly message: string;
    /**
     * Optional remediation hint. Future hygiene-phase rules emit a
     * fix recipe here ("declare `usage` on this entry"); invariant
     * rules embed the recipe directly in `message` today.
     */
    readonly fixHint?: string;
}
/**
 * Aggregate result of {@link lintContract}. Errors and warnings are
 * partitioned at construction; consumers that want a flat list can
 * concatenate.
 */
export interface ContractLintResult {
    readonly errors: readonly ContractIssue[];
    readonly warnings: readonly ContractIssue[];
}
/**
 * Strict-mode failure. Carries the offending phase + every issue
 * the failing phase produced so error renderers can show every fix
 * in one pass without re-running the linter.
 *
 * The `phase` field discriminates the error class: shape errors
 * surface as a single rolled-up zod failure; reference / schema-compat
 * errors carry one issue per violation.
 */
export declare class ContractValidationError extends DomainError<'contract_validation_failed'> {
    readonly phase: ContractLintPhase;
    readonly issues: readonly ContractIssue[];
    constructor(phase: ContractLintPhase, issues: readonly ContractIssue[]);
}
/**
 * Strict-mode validator. Runs the four phases in order; throws
 * {@link ContractValidationError} on the FIRST phase that produces
 * errors. Used at every protocol boundary where a malformed
 * contract is a fatal author bug.
 *
 * Phases run in dependency order:
 *
 *   1. shape — zod parse fails ⇒ nothing else makes sense
 *   2. references — refs must resolve before schema-compat can read
 *      the referenced tool's schemas
 *   3. schema-compat — checks rely on resolved references
 *   4. hygiene — warnings only; never throws (handled by lintContract)
 *
 * Hygiene-only contracts (warnings without errors) pass the strict
 * gate. Use {@link lintContract} when warnings matter.
 */
export declare function validateContract(contract: unknown): void;
/**
 * Graded-mode linter. Runs ALL phases unconditionally and returns
 * errors + warnings partitioned. Suitable for authoring tools that
 * want a complete checklist of issues + suggestions rather than the
 * fail-fast posture of {@link validateContract}.
 *
 * Phase ordering still matters for diagnostics (issues are returned
 * in phase order); but graded mode never short-circuits, so an
 * author seeing a phase-2 reference error also sees the phase-4
 * hygiene warnings on the same contract.
 */
export declare function lintContract(contract: unknown): ContractLintResult;
//# sourceMappingURL=lint-contract.d.ts.map