import { Placeholders } from "../contracts/placeholders.type.mjs";
import { PromptValidationResult, PromptsValidateOptions } from "../prompts/prompts-manager.type.mjs";
import { InstructionContract, PersonaContract, PromptRefineOptions, RefinedSystemPromptContract, RefinedSystemPromptOptions, SystemPromptBlockContract, SystemPromptContract, SystemPromptMergeOptions, SystemPromptMeta } from "../contracts/system-prompt.contract.mjs";

//#region ../ai/src/system-prompt/refined-system-prompt.d.ts
/**
 * Prompt-world collaborators injected by `system-prompt.ts` when it
 * constructs the wrapper. Dependency-injected (not imported) so this module
 * never imports `system-prompt.ts` / `prompts-manager.ts` back — both would
 * close import cycles.
 */
type RefinedSystemPromptDeps = {
  /** Construct a plain `SystemPrompt` (used by `refinePrompt()`). */buildPrompt(blocks: readonly SystemPromptBlockContract[], meta?: SystemPromptMeta): SystemPromptContract; /** `ai.prompts.validate(target, options)` — the contract's validate sugar. */
  validatePrompt(target: SystemPromptContract, options?: PromptsValidateOptions): Promise<PromptValidationResult>;
};
/**
 * Concrete `RefinedSystemPromptContract` — the compiled form of a prompt.
 *
 * **Role.** A lazy prompt compiler: it wraps a human-authored
 * `SystemPromptContract` and, on first use (agent path via `materialize()`,
 * or explicitly via `refine()` / `refinePrompt()`), rewrites the raw source
 * template into a model-optimized version through the configured refiner
 * model, pins the result, and serves it from `resolve()` thereafter.
 *
 * **Responsibility.**
 * - Owns: the compile pipeline (store lookup → refiner call → placeholder
 *   parity acceptance → single repair attempt → pin), single-flight
 *   de-duplication, and the never-throw fallback on the agent path.
 * - Does NOT own: the source prompt's composition (delegated to the wrapped
 *   builder), placeholder rendering (each block's `resolve()`), or where a
 *   shared store persists (any `RefinedPromptStoreLike`).
 *
 * Trust rules (locked in `plans/warlock-4.7.0.md` §F4):
 * 1. Lockfile posture — pinned until an input changes, never re-compiled
 *    silently over time (the store key hashes recipe version + model +
 *    criteria + source template).
 * 2. Prose, never contract — the exact `{{placeholder}}` set must survive
 *    (`parityIssues`), or the rewrite is rejected.
 * 3. Advisory with fallback — `materialize()` never throws; the original
 *    text is always a valid prompt. Explicit `refine()` throws
 *    `PromptRefinementError` instead (routes/CI need failures).
 * 4. Reviewable — `refine()` exposes the compiled text; `refinePrompt()`
 *    makes it a first-class prompt with `refinedFrom` provenance.
 *
 * Builder chaining (`persona()` / `instruction()` / `merge()` / `meta()`)
 * derives a NEW source and re-wraps it with the same refinement options —
 * editing a compiled prompt naturally invalidates its pin (new source ⇒ new
 * key). Forks follow the base builder's meta rules (they stay anonymous).
 *
 * Users construct via `systemPrompt(...).refined(options)` —
 * `new RefinedSystemPrompt()` is not the public API.
 */
declare class RefinedSystemPrompt implements RefinedSystemPromptContract {
  private readonly sourcePrompt;
  private readonly options;
  private readonly deps;
  /** The pinned refined template, once compiled (in-memory mirror of the store). */
  private refinedTemplate?;
  /** Cached single-instruction block list for the compiled template. */
  private refinedBlocks?;
  /** Single-flight: the in-progress compilation shared by concurrent callers. */
  private inflight?;
  /**
   * Monotonic compile-run id. Only the LATEST-started compilation may pin
   * its result (instance + store) — a superseded run (e.g. a slow lazy
   * compile overlapped by an explicit `{ fresh: true }`) still returns its
   * text to its own awaiters but never overwrites the newer pin.
   */
  private compileGeneration;
  /** Settled-compile failures — gates the lazy path off after the cap. */
  private compileFailures;
  /** The lazy path warns at most once per instance when falling back. */
  private warnedFallback;
  constructor(sourcePrompt: SystemPromptContract, options: RefinedSystemPromptOptions, deps: RefinedSystemPromptDeps);
  /** The human-authored prompt this wrapper compiles. */
  get source(): SystemPromptContract;
  /**
   * Compiled blocks once materialized (a single instruction holding the
   * refined template), the source's blocks until then — so every consumer,
   * including the `ai.prompts` duck-type guards, always sees a real prompt.
   */
  get blocks(): readonly SystemPromptBlockContract[];
  /**
   * Identity delegates to the source — a compiled prompt IS its source
   * prompt (same `name@version` stamped on agent reports); the compiled text
   * is an implementation detail of how it renders. The updater form renames
   * the SOURCE and re-wraps, so refinement survives a rename (and the new
   * source text registers under the new name per base-builder rules).
   */
  meta(): SystemPromptMeta | undefined;
  meta(meta: SystemPromptMeta): RefinedSystemPromptContract;
  /** Derive a new source with the persona set, re-wrapped (pin invalidates). */
  persona(value: PersonaContract | string): RefinedSystemPromptContract;
  /** Derive a new source with the instruction appended, re-wrapped (pin invalidates). */
  instruction(value: InstructionContract | string): RefinedSystemPromptContract;
  /**
   * Fold blocks / a contract / a registered name into the SOURCE and re-wrap
   * — same three forms as the base builder's `merge`.
   */
  merge(...blocks: readonly SystemPromptBlockContract[]): RefinedSystemPromptContract;
  merge(source: SystemPromptContract): RefinedSystemPromptContract;
  merge(name: string, options?: SystemPromptMergeOptions): RefinedSystemPromptContract;
  /**
   * Render the compiled template when pinned, the source otherwise —
   * synchronous by contract, so laziness lives in `materialize()` /
   * `refine()`, never here.
   */
  resolve(placeholders?: Placeholders): string;
  /**
   * Validate THIS prompt (the compiled text once pinned, the source before)
   * — sugar over `ai.prompts.validate(this, options)`, same as the base
   * builder.
   */
  validate(options?: PromptsValidateOptions): Promise<PromptValidationResult>;
  /** Re-configure refinement for the same source (new options, fresh pin state). */
  refined(options: RefinedSystemPromptOptions): RefinedSystemPromptContract;
  /**
   * The advisory hook the agent input builder awaits before its synchronous
   * `resolve()`. Compiles + pins on first call; a refiner failure is warned
   * once and swallowed — the original prompt is always a valid prompt.
   *
   * Bounded retries: after {@link MAX_LAZY_COMPILE_ATTEMPTS} settled compile
   * failures this becomes a no-op for the instance lifetime, so a
   * persistently-broken refiner can't tax every agent run with its failure
   * latency. The explicit `refine()` stays live (and a success re-arms the
   * pin for everyone).
   */
  materialize(): Promise<void>;
  /**
   * Compile now (or read the pin) and return the refined template string —
   * placeholders intact. Throws `PromptRefinementError` on failure; pass
   * `{ fresh: true }` to force a new take past the pin.
   */
  refine(options?: PromptRefineOptions): Promise<string>;
  /**
   * Compile and wrap the refined template in a new plain `SystemPrompt` —
   * one instruction block, `refinedFrom` / `refinerModel` provenance, the
   * source's `required` keys carried over, and NO name (never
   * auto-registers).
   */
  refinePrompt(options?: PromptRefineOptions): Promise<SystemPromptContract>;
  /** Re-wrap a derived source with the same refinement options. */
  private rewrap;
  /**
   * One compilation pipeline for all three surfaces. `fresh` bypasses the
   * instance pin AND the store read, and SUPERSEDES any compile already in
   * flight: it claims the shared in-flight slot (so concurrent lazy callers
   * join it instead of duplicating work) and bumps the compile generation
   * (so the superseded run can no longer pin a stale result over it).
   */
  private compile;
  /**
   * The actual compile run: store lookup (unless skipped) → refiner call →
   * parity acceptance → pin. Pinning (instance + store) is gated on the
   * run still being the latest-started generation — a superseded run
   * returns its text but never overwrites the newer pin.
   */
  private compileUncached;
  /**
   * The refiner model call: one attempt plus one parity-repair re-ask.
   * Throws `PromptRefinementError` — `materialize()` is the layer that
   * downgrades failures to a fallback.
   */
  private runRefiner;
  /** The one-shot refiner agent — named distinctively for observer reports. */
  private buildRefinerAgent;
  /**
   * Deterministic pin key: any input change (recipe version, refiner model,
   * criteria, source template) yields a new key, so stale pins are simply
   * never read — the lockfile invalidation rule.
   */
  private storeKey;
  /** Pin the compiled template on the instance. */
  private adopt;
  /**
   * One `[warlock-ai]` console warning per instance when the lazy path first
   * falls back to the original text — mirroring the package's warn-once
   * convention; suppressed under tests.
   */
  private warnFallbackOnce;
}
//#endregion
export { RefinedSystemPrompt };
//# sourceMappingURL=refined-system-prompt.d.mts.map