import { T as TypedKey, S as Stability } from '../stage-DHgQdIcT.js';
import 'zod';
import '../interface-DMzwv0lD.js';
import '../types-ByGg__Kd.js';

/**
 * @bratsos/workflow-engine/conventions
 *
 * Well-known annotation keys for common provenance scenarios — trigger
 * context, decisions, approvals, revisions. Inspired by OpenTelemetry
 * semantic conventions: dot-namespaced flat keys, value type linked to
 * the key via TypeScript phantom-type inference.
 *
 * ## Usage
 *
 * ```ts
 * import { Trigger, Decision } from "@bratsos/workflow-engine/conventions";
 *
 * // Type-checked: value must match the TypedKey<T> parameter.
 * ctx.annotate(Decision.outcome, "low");
 * ctx.annotate(Decision.confidence, 0.42);
 * ctx.annotate(Decision.confidence, "high"); // ❌ TS error
 *
 * // Custom org-defined keys keep working with the string form:
 * ctx.annotate("acme.compliance.signoff", "alice@acme.com");
 * ```
 *
 * ## Versioning policy
 *
 * - Keys are **immutable once `stable`**. Additions only.
 * - Renames and value-type changes ship as **new keys**; the old key
 *   gets a `@deprecated` JSDoc tag.
 * - We deliberately do **not** copy OpenTelemetry's
 *   `OTEL_SEMCONV_STABILITY_OPT_IN` env-var dance — versioning is
 *   handled through semver and JSDoc.
 *
 * See `src/conventions/README.md` for the full policy.
 */

/**
 * Define a well-known annotation key. The value-type parameter `T` is
 * phantom — never set at runtime, used only for TypeScript inference
 * when the key is passed to `ctx.annotate(key, value)`.
 */
declare function typedKey<T = unknown>(key: string, meta?: {
    stability?: Stability;
    description?: string;
}): TypedKey<T>;
/**
 * Trigger conventions describe how a workflow run was initiated:
 * caller identity, source system, parent run, free-text reason.
 *
 * Attach at `run.create` time via the `annotations` parameter.
 */
declare const Trigger: {
    /** What system or path initiated the run, e.g. `"webhook:zendesk"`, `"manual:cli"`, `"schedule:cron"`. */
    readonly source: TypedKey<string>;
    /** Run ID of the prior run when this run is a follow-up / retry / chained execution. */
    readonly parentRunId: TypedKey<string>;
    /** Free-text reason — `"auto-triage on ticket create"`, `"manual rerun after policy change"`, etc. */
    readonly reason: TypedKey<string>;
    /** Actor kind discriminator — recommended values: `"user"`, `"agent"`, `"system"`. Open string. */
    readonly actorKind: TypedKey<string>;
    /** Stable identifier for the actor — user email, agent name, service identifier. */
    readonly actorId: TypedKey<string>;
};
/**
 * Decision conventions describe choices an agent or stage made
 * during execution: the chosen outcome, the reasoning, evidence,
 * alternatives that were considered.
 *
 * Attach from inside `ctx.annotate(...)` within a stage's `execute()`.
 */
declare const Decision: {
    /** The chosen outcome. Shape is consumer-defined; `unknown` here for flexibility. */
    readonly outcome: TypedKey<unknown>;
    /** Free-text rationale — why the agent picked this outcome. */
    readonly rationale: TypedKey<string>;
    /** Confidence score, typically `0`–`1`. */
    readonly confidence: TypedKey<number>;
    /** Alternative outcomes that were considered but not selected. */
    readonly alternatives: TypedKey<unknown[]>;
    /** Whether a fallback heuristic was used (e.g., AI confidence below threshold). */
    readonly usedFallback: TypedKey<boolean>;
};
/**
 * Approval conventions describe sign-off events on runs or stages.
 * Pluralization follows the OTel rule: `approvers` is plural because a
 * single approval can have multiple approvers; the value type is
 * always `string[]`, even with one approver.
 */
declare const Approval: {
    /** Identifiers of all approvers. Always an array — `["alice"]` for a single approver. */
    readonly approvers: TypedKey<string[]>;
    /** When the approval was recorded. ISO 8601. */
    readonly timestamp: TypedKey<string>;
    /** Version of the policy the approval was checked against. */
    readonly policyVersion: TypedKey<string>;
};
/**
 * Revision conventions describe a run as a revision of a prior run:
 * a deliberate redo, a corrected attempt, a manual override.
 *
 * Distinct from `Trigger.parentRunId` — that's any causal parent
 * (including independent follow-ups), revision is specifically
 * "this run supersedes that one."
 */
declare const Revision: {
    /** Run ID this revision supersedes. */
    readonly previousRunId: TypedKey<string>;
    /** Why this revision was created. */
    readonly reason: TypedKey<string>;
};

export { Approval, Decision, Revision, Stability, Trigger, TypedKey, typedKey };