/**
 * The ACTION composite (SPEC §13.6): a long-running command as a pattern over the journal +
 * records + events — zero new transport. `action` is a command MARKER, never a class: an
 * action's submissions are `class: journal`, its accept/reject is the durable decision fact
 * (§13.4), and there is no reply-rail answer to recover.
 *
 * THE RESULT FACT IS THE SINGLE TERMINAL ARBITER; THE STATUS ONLY EVER FOLLOWS IT, and every
 * authority coordinate is bound to the PERSISTED accepted goal, never a caller claim. The
 * pieces, each owned by the §13.9 principal named on its row:
 *  - the GOAL BIND (canonicalizer): a create-only CAS on
 *    `epf.<e>.goal.<caller triple>.<goalId>.bind` carrying the accepted fingerprint, BEFORE
 *    acceptance — the bind keys on `goalId` and stops a second distinct submission before
 *    acceptance and effect. A bind whose winner crashed BEFORE acceptance (no goal record) is
 *    ORPHANED, and a same-fingerprint resubmission ADOPTS it ({@link resolveGoalSubmission}).
 *  - the GOAL RECORD (commit path): `goal.<e>.<caller triple>.<goalId>` spec (the accepted
 *    definition — the trusted source every later seam validates against) + status (the CURRENT
 *    state projection). The status vocabulary is `accepted → running ⇄ waiting → terminal`,
 *    `cancelling` between a cancel and its terminal. A TERMINAL status exists ONLY as the
 *    projection of the committed result fact ({@link projectGoalTerminal}); {@link
 *    transitionGoal} refuses terminal targets, so the status never leads the journal. Every
 *    EXECUTOR-authored transition on a TARGET-PINNED goal proves the executor's fresh
 *    lifecycle/epoch currency (§13.6 item 7: a superseded epoch cannot commit transitions).
 *  - the TERMINAL RESULT (commit path): a create-only CAS on
 *    `epf.<e>.goal.<caller triple>.<goalId>.result` — the ONE commit point where completion,
 *    cancel, expiry-deny, and the readiness `uncertain` settle race, first terminal fact wins
 *    uniformly. The raw CAS is PRIVATE; the public commit takes a CLOSED CAUSE whose
 *    authoritative predicate is verified INSIDE the boundary (a `complete` proves executor
 *    currency, a `cancel` proves the goal is `cancelling`, a `readiness` proves the deadline
 *    passed) and DERIVES the terminal state from the cause — a raw state is never accepted.
 *  - the TOMBSTONE (§13.6 item 5): the summary lives INSIDE the one immutable result fact;
 *    retaining the fact the full idempotency horizon satisfies both retention minimums, and
 *    early payload eviction is a serving-layer policy answered with {@link goalTombstone}.
 *  - PROGRESS rides per-goal events, read-scoped to the caller at mint time.
 *
 * Every seam takes a BRANDED {@link ActionContext} bonding the record store + fact stream +
 * space, so a composition mixup cannot read an accepted spec from space A and project through
 * space B. Clocks are inputs everywhere (`now`, `acceptedAt`): the owner's clock decides.
 */
import type { KV } from "@nats-io/kv";
import { type JetStreamClient, type JetStreamManager } from "@nats-io/jetstream";
import { type NatsConnection } from "@nats-io/transport-node";
import { EpEnvelopeError } from "./endpoint-envelope.js";
import { type EpCaller, type ParsedEpRequest } from "./endpoint-subjects.js";
import { type Receipt, type ReceiptStoreContext } from "./endpoint-receipt.js";
/** A trusted, space-bonded action context: the KV + JS + JSM all DERIVE from one binding-layer
 *  connection and one space by the constructor (never injected independently — a branded bundle
 *  of split resources would still split accepted state from terminal authority), so a
 *  composition mixup can never read an accepted spec through one broker and commit its terminal
 *  through another. BRANDED: a hand-assembled structural look-alike is rejected at every seam,
 *  not just discouraged. */
export interface ActionContext {
    kv: KV;
    js: JetStreamClient;
    jsm: JetStreamManager;
    space: string;
}
export declare function actionContext(nc: NatsConnection, space: string): Promise<ActionContext>;
/** A CONSTRUCTION-BOUND owner-authority proof: minted only from the branded context by the
 *  commit principal itself, and accepted only against THAT context. This replaces a raw
 *  `ownerAuthored` boolean — a flag any caller could set by typo or confusion — with a value
 *  that cannot be hand-assembled and cannot leak across contexts: owner authority over a
 *  target-pinned goal's pause/deny is proven by construction, never asserted (SPEC 13.6). */
export interface OwnerCommitProof {
    readonly space: string;
}
export declare function ownerCommitProof(ctx: ActionContext): OwnerCommitProof;
/** A GATE-MINTED clearance: the only key that opens a GUARDED goal's edge into `running`
 *  (SPEC 13.6: a guarded command MUST NOT effect until the guard answered allow, and `running`
 *  IS effecting). The mint lives behind a ONE-SHOT claim that THE guard gate module takes at
 *  load, so no other holder of an action context can mint gate passage - an owner proof
 *  deliberately does NOT satisfy this edge (any context holder mints owner proofs; only the
 *  gate, whose allow/release/reconcile arms verified the guard's answer, mints clearance). */
export interface GuardClearance {
    readonly goalId: string;
}
/** ONE-SHOT handoff of the clearance mint to THE gate (endpoint-guard claims it at module
 *  load; the package always loads it). Every later call is a loud refusal: there is exactly
 *  one gate, so a second claimant is by definition not it (SPEC 13.6). */
export declare function claimGuardClearanceMint(): (ctx: ActionContext, goalId: string) => GuardClearance;
/** A goal's coordinates: the owning endpoint + the caller triple + the client-chosen goalId. */
export interface GoalRef {
    endpoint: string;
    caller: EpCaller;
    goalId: string;
}
/** Snapshot a caller-supplied ref to a validated DETACHED copy at seam entry, BEFORE the first
 *  await: a shared mutable ref can otherwise split one operation's identity across its reads,
 *  its CAS, and its terminal publish. Exported for the guard seams, which detach the goal they
 *  bind, resume, and project against the same discipline. */
export declare function snapshotRef(ref: GoalRef): GoalRef;
/** Derive a goal ref STRUCTURALLY from the broker-authenticated request (§13.6): the caller
 *  triple comes from the subject the broker admitted, DETACHED so a later mutation of the parsed
 *  request cannot retarget it, never from body fields — a seam taking this ref addresses only
 *  the authenticated caller's own goals. */
export declare function goalRefOf(request: ParsedEpRequest, goalId: string): GoalRef;
/** The goal's terminal-result fact subject — the ONE subject SPEC §13.2 reserves (reserved subjects, `goal.<cOwner>.<cActor>.<cUid>.<goalId>.result`),
 *  `epf.<e>.goal.<cOwner>.<cActor>.<cUid>.<goalId>.result`, with NO epoch token.
 *
 *  An earlier revision epoch-scoped this (`…result.<execEpoch>`) to fence a live-superseded
 *  committer by giving each executor epoch its own create-only subject. That was non-conformant
 *  AND wrong: the window it addressed is "commit the fact, then die before the projection", where
 *  the pre-restart fact is the LEGITIMATE outcome, not a corpse's guess. Scoping by epoch hid that
 *  winner from every post-restart reader, let the successor commit a SECOND contradictory terminal
 *  at the new epoch, and surfaced the wrong one to callers (executed repro: a real `succeeded`
 *  read back as `uncertain`). One goal has one terminal, on one subject, first-fact-wins globally.
 *  The fence against a superseded committer is the §13.1 takeover barrier, which revokes and
 *  cluster-verify-evicts the family BEFORE it advances the process epoch. */
export declare function goalResultSubject(space: string, ref: GoalRef): string;
/** The per-goal progress EVENT topic tail (§13.2 reserved topics). */
export declare function goalProgressTopic(ref: GoalRef): string[];
/** The bind fact: the goalId's accepted fingerprint, immutable for the goal's lifetime. */
export interface GoalBindFact {
    v: 1;
    goalId: string;
    fingerprint: string;
}
/** Bind a goal to its accepted fingerprint BEFORE acceptance (the canonicalizer's seam): a
 *  create-only CAS per goalId. The winner proceeds; a loser reads the recorded bind and decides
 *  (same fingerprint = retry, different = `conflict` before acceptance and effect). The subject
 *  derives from the goal ref — ONE entry-derived identity (a caller derives it from the
 *  broker-authenticated request via {@link goalRefOf} exactly once), never body fields. */
export declare function bindGoal(ctx: ActionContext, ref: GoalRef, fingerprint: string): Promise<{
    bound: true;
} | {
    bound: false;
    existing: GoalBindFact;
}>;
/** The submission-vs-bind verdict (§13.6 item 5 + orphan recovery). */
export type GoalSubmissionVerdict = {
    kind: "new";
} | {
    kind: "cached";
    bind: GoalBindFact;
    result?: GoalResultFact;
} | {
    kind: "adopted";
    bind: GoalBindFact;
} | {
    kind: "conflict";
    bind: GoalBindFact;
};
/** Resolve a goal submission against the bind rail (the canonicalizer's composed seam): NEW
 *  work (bind won); the caller's retry serving the CACHED decision/outcome (same fingerprint +
 *  a persisted goal whose spec AGREES with the bind); orphan ADOPTION (same fingerprint, no goal
 *  record — the bind winner crashed pre-acceptance); or `conflict` (different fingerprint). A
 *  persisted spec whose fingerprint disagrees with the bind is a loud `internal` (garbled
 *  authority chain), never a silent cached serve. */
export declare function resolveGoalSubmission(ctx: ActionContext, request: ParsedEpRequest, goalId: string, fingerprint: string): Promise<GoalSubmissionVerdict>;
/** The §13.6 single status vocabulary for every long-running surface. */
export declare const GOAL_STATES: readonly ["accepted", "running", "waiting", "cancelling", "succeeded", "failed", "cancelled", "expired", "uncertain"];
export type GoalState = (typeof GOAL_STATES)[number];
/** All five are TERMINAL and immutable; first-terminal-fact-wins applies uniformly. */
export declare const GOAL_TERMINAL_STATES: readonly GoalState[];
/** The legal §13.6 transitions: `accepted → running ⇄ waiting`, `cancelling` between a cancel
 *  and its terminal, every non-terminal may project a terminal, a terminal absorbs. */
export declare function isLegalGoalTransition(from: GoalState, to: GoalState): boolean;
/** The goal SPEC (written once at acceptance): the accepted definition every later seam
 *  validates against — the terminal commit stamps ITS fingerprint from here, the readiness
 *  settle reads ITS bound from here, and a target-pinned goal fences on ITS target lifecycle. */
export interface GoalSpecValue {
    v: 1;
    goalId: string;
    fingerprint: string;
    command: string;
    caller: {
        id: string;
        lifecycleUid: string;
    };
    target?: {
        owner: string;
        actor: string;
        lifecycleUid: string;
        mappingRevision: number;
    };
    /** The ACCEPTING incarnation's process epoch (§13.1), recorded at acceptance. Paired with the
     *  terminal fact's {@link GoalResultFact.committer} epoch, it is what makes a terminal
     *  ATTRIBUTABLE: `committed == accepted` is the executor answering for its OWN work and stays
     *  valid FOREVER however far the current epoch advances (this is what keeps the legitimate
     *  pre-restart winner readable — the property HIGH-1 lost); `committed > accepted` is a
     *  successor settling inherited work; `committed < accepted` cannot happen and is refused as
     *  garbled. Present exactly when the endpoint commits under an epoch at all. */
    acceptedEpoch?: number;
    /** The accepted submission's request id — the goal's ADDRESS for its durable acceptance fact
     *  (`epf.<e>.dec.<triple>.<id>`), written at acceptance when it is known. The raw submission
     *  (EPJ) is age-evicted, so receipt reconstruction after a crash reads the acceptance THROUGH
     *  this address and proves the chain (id + sourceSeq + fingerprint) before minting (§13.10). */
    requestId: string;
    /** The guard endpoint named by the command's VERIFIED `ai.cotal.guarded` trait value,
     *  recorded at acceptance. Its PRESENCE is what {@link transitionGoal} enforces: a guarded
     *  goal's edge into `running` opens only with THE gate's {@link GuardClearance} - an
     *  unrecorded guard binding is unenforceable, so the acceptance path MUST record it
     *  (SPEC 13.6/13.7). */
    guard?: string;
    sourceSeq: number;
    acceptedAt: number;
    readinessDeadlineMs?: number;
}
/** Read the persisted accepted goal (`undefined` = never accepted). A DEL marker refuses. */
export declare function readGoalSpec(ctx: ActionContext, ref: GoalRef): Promise<{
    value: GoalSpecValue;
    revision: number;
} | undefined>;
/** The goal STATUS value: the current state projection. State-dependent fields are CLOSED. */
export interface GoalStatusValue extends Record<string, unknown> {
    state: GoalState;
    checkpoint?: {
        token: string;
        deadlineGeneration: number;
    };
    cancelMode?: "graceful" | "terminate";
    observedSpecRevision: number;
}
/** Create the goal record at acceptance, IDEMPOTENTLY (spec create-only, then the `accepted`
 *  status): a crash between the two writes (or an adopted-retry replay) re-reads the spec,
 *  requires it CONTENT-IDENTICAL, and ensures the status — no stranded spec-only goal. */
export declare function createGoal(ctx: ActionContext, ref: GoalRef, spec: Omit<GoalSpecValue, "v" | "goalId">): Promise<{
    specRevision: number;
}>;
/** Read the goal's current status projection (`undefined` = unknown goal). */
export declare function readGoalStatus(ctx: ActionContext, ref: GoalRef): Promise<{
    value: GoalStatusValue;
    revision: number;
} | undefined>;
/** Leader-read a goal's status projection by ref ALONE (no {@link ActionContext}) — a fencing read
 *  for a caller OUTSIDE the action module. The retirement drain uses it to decide whether an
 *  accepted ACTION goal is still `accepted` (never entered `running`, the guard/currency-fenced
 *  effecting edge, so provably never effected) before it may create-only cancel it: a `cancelled`
 *  terminal must mean the effect did NOT run (SPEC 13.6). `undefined` = no goal record at all
 *  (never created ⇒ never ran). Leader-served (read-your-writes), so a running executor's
 *  transition is never missed as a stale absence and a mis-read never authorizes a false cancel. */
export declare function readGoalStatusByRefLeader(jsm: JetStreamManager, space: string, ref: GoalRef): Promise<GoalStatusValue | undefined>;
/** The executor's authenticated identity (subject/creds, never a body claim), required when a
 *  goal's spec pins a target lifecycle (§13.6 item 7). */
export interface GoalExecutor {
    lifecycleUid: string;
    epoch: number;
}
/** CAS the goal's status through the NON-TERMINAL machine. A TERMINAL target is REFUSED (a
 *  terminal status exists only as {@link projectGoalTerminal}). An EXECUTOR-authored PROGRESS
 *  transition (`running`/`waiting`) on a TARGET-PINNED goal MUST prove the executor's fresh
 *  currency; a `cancelling` transition is owner/caller-authored (its authority is the cancel's
 *  broker-authenticated caller, {@link requestGoalCancel}) and takes no executor; an OWNER pause
 *  (guard hold → `waiting`) may declare `ownerAuthored`. A target-pinned progress transition
 *  with neither executor nor `ownerAuthored` is refused. */
export declare function transitionGoal(ctx: ActionContext, ref: GoalRef, to: GoalState, opts?: {
    fields?: Partial<Pick<GoalStatusValue, "checkpoint" | "cancelMode">>;
    executor?: GoalExecutor;
    resolveCurrentEpoch?: (target: {
        owner: string;
        actor: string;
        lifecycleUid: string;
    }) => Promise<number | null> | number | null;
    epochResolveBudgetMs?: number;
    /** The owner's own commit principal drives this (guard-hold pause/release): a
     *  CONSTRUCTION-BOUND {@link ownerCommitProof} from THIS context, never a raw flag. */
    owner?: OwnerCommitProof;
    /** THE gate's construction-bound {@link GuardClearance} - REQUIRED on a GUARDED goal's
     *  edge into `running` (SPEC 13.6 MUST-NOT-effect-until-allow; an owner proof does NOT
     *  satisfy this edge, since any context holder mints owner proofs). */
    clearance?: GuardClearance;
}): Promise<GoalStatusValue>;
/** Project the WINNING terminal fact onto the status — the ONLY path a status reaches a terminal
 *  state, and the crash reconciler for a commit that fenced the fact but died before projecting.
 *  Cross-checks the fact's fingerprint against the persisted spec (a terminal fact whose
 *  fingerprint disagrees with the accepted goal is a garbled authority chain). One goal has ONE
 *  terminal subject (§13.2 reserved subjects), so the projection follows the one committed fact — there is no
 *  epoch to resolve and no per-epoch variant of "the winner". */
export declare function projectGoalTerminal(ctx: ActionContext, ref: GoalRef): Promise<GoalStatusValue>;
export type GoalOutcomeState = "succeeded" | "failed" | "cancelled" | "expired" | "uncertain";
/** The goal's terminal fact + the §13.6 item-5 tombstone summary in one immutable artifact. */
export interface GoalResultFact {
    v: 1;
    goalId: string;
    fingerprint: string;
    state: GoalOutcomeState;
    outcomeDigest: string;
    data?: unknown;
    /** WHO committed this terminal, and under which process epoch. The fact records its own
     *  authorship so a reader can tell the accepting executor's own answer from a successor's
     *  settle of inherited work; without it a terminal is anonymous and neither case is
     *  distinguishable from the other. Judged against the goal spec's `acceptedEpoch`, never
     *  against the CURRENT epoch — comparing to current is precisely what hid the legitimate
     *  pre-restart winner, because a corpse's fact and a real pre-restart winner's fact are
     *  byte-identical to a reader looking only at "is this epoch stale". */
    committer?: {
        instanceId: string;
        epoch: number;
    };
    ts: number;
}
/** Build the retirement-cancelled goal terminal (§13.8 option (i)): the FIRST-CLASS `cancelled`
 *  outcome state the goal union ALREADY carries — no new wire shape — bound to the acceptance's
 *  fingerprint, with the retirement attribution riding the digest-bound payload
 *  (`data.cancelledBy = { opId, target }`). Published create-only on the goal's result subject,
 *  so a racing real commit wins by landing first (first-terminal-wins, §13.8). A retirement
 *  cancels only ITS OWN target's accepted goals. */
export declare function goalCancelledResultOf(acceptance: {
    fingerprint: string;
    request: Record<string, unknown>;
    target?: {
        owner: string;
        actor: string;
        lifecycleUid: string;
    };
}, cancelled: {
    opId: string;
    target: {
        owner: string;
        actor: string;
        lifecycleUid: string;
    };
}, ts: number): GoalResultFact;
/** The §13.6 item-5 tombstone serving form for a payload-evicted retry. */
export declare function goalTombstone(fact: GoalResultFact): GoalResultFact;
/** Closed validation, IDENTITY-BOUND to the ref, with the tombstone digest RE-VERIFIED. */
export declare function parseGoalResultFact(raw: unknown, subject: string, ref: GoalRef): GoalResultFact;
/** Read the goal's cached terminal outcome (`undefined` = not terminal yet). ONE goal, ONE
 *  terminal subject (§13.2 reserved subjects), read exactly (never a wildcard `last_by_subj` — the append-shadow
 *  lesson): a committed terminal is surfaced to every reader, in every incarnation, forever. */
export declare function readGoalResult(ctx: ActionContext, ref: GoalRef): Promise<GoalResultFact | undefined>;
/** What receipt emission needs beyond the action context: the receipt store bonded to the SAME
 *  space AND the same connection, the EMITTING instance recorded as EVIDENCE (who produced this
 *  attestation - after a crash the reconciling instance records ITSELF here, so this is never
 *  proof of who EXECUTED the goal, and never redemption authority; the executed outcome's
 *  authority is the committed terminal fact alone), and the receipts-scoped signer + key. */
export interface ReceiptEmissionWiring {
    store: ReceiptStoreContext;
    instance: {
        id: string;
        instanceId: string;
        epoch: number;
    };
    signer: {
        keyId: string;
    };
    keyPair: {
        sign(input: Uint8Array): Uint8Array;
    };
}
/** One emission attempt's outcome: `emitted` (this attempt's receipt won the create-only CAS)
 *  or `converged` (a receipt already attests these facts — an earlier attempt's or a racing
 *  emitter's, ADOPTED only after it proves agreement with the facts). A recorded receipt that
 *  DISAGREES with the committed facts is a loud `conflict`, never adopted. */
export type ReceiptEmissionResult = {
    outcome: "emitted" | "converged";
    receipt: Receipt;
};
/** The durable backstop for the §13.10 MUST-emit guarantee: re-derive and publish the receipt
 *  for a goal whose terminal committed but whose emission was omitted (a crash between the
 *  terminal CAS and the publish, or a commit made without emission wiring). Reads the persisted
 *  spec and the committed terminal FRESH, then runs the SAME emission seam the inline path uses.
 *  `no-terminal` = nothing to attest yet (the goal simply is not terminal — never an error). */
export declare function reconcileReceiptEmission(ctx: ActionContext, wiring: ReceiptEmissionWiring, args: {
    ref: GoalRef;
    now: number;
}): Promise<ReceiptEmissionResult | {
    outcome: "no-terminal";
}>;
/** A deny's AUTHORITATIVE PREDICATE (§13.6): a bare `deny` proves nothing, so the commit
 *  boundary requires and VERIFIES one of:
 *   - `hold-expired`: the named checkpoint's recorded spec must BIND this exact goal and its
 *     recorded one-use settlement must be `expired` (the arbiter's own fact — a live or resumed
 *     hold never denies);
 *   - `owner`: the owner's construction-bound {@link ownerCommitProof} from THIS context (a
 *     guard-verdict deny the owner itself is committing). */
export type GoalDenial = {
    kind: "hold-expired";
    token: string;
} | {
    kind: "owner";
    owner: OwnerCommitProof;
};
/** The closed terminal CAUSE (§13.6): the public commit accepts ONLY these, each with its own
 *  authoritative predicate verified inside the boundary; the terminal state is DERIVED, never a
 *  raw caller value.
 *   - `complete`: the executor's own outcome (`succeeded`|`failed`), proving fresh currency for
 *     a target-pinned goal;
 *   - `cancel`: `cancelled`, requiring the goal to be `cancelling` (a cancel was requested);
 *   - `deny`: `failed`, requiring the verified {@link GoalDenial} predicate (a bare deny cause
 *     is refused — any commit-seam holder could otherwise fail any accepted goal);
 *   - `readiness`: `uncertain`, the OWNER's deadline settlement, requiring `now` past the
 *     persisted acceptance-relative readiness deadline (no executor — a target-pinned goal's
 *     owner deadline is reachable). */
export type GoalCommitCause = {
    cause: "complete";
    state: "succeeded" | "failed";
    data?: unknown;
    executor?: GoalExecutor;
    resolveCurrentEpoch?: (target: {
        owner: string;
        actor: string;
        lifecycleUid: string;
    }) => Promise<number | null> | number | null;
    epochResolveBudgetMs?: number;
} | {
    cause: "cancel";
    data?: unknown;
} | {
    cause: "deny";
    denial: GoalDenial;
    data?: unknown;
} | {
    cause: "readiness";
    data?: unknown;
};
/** Commit the goal's terminal state at the ONE mediated commit point, BOUND to the persisted
 *  accepted goal and its CAUSE (see {@link GoalCommitCause}). First terminal fact wins uniformly
 *  (completion, cancel, deny, and readiness race here); a loser observes the winner and its
 *  projection converges. Every operation input detaches at ENTRY (single-read, before the first
 *  await): a caller mutating cause/state/data/executor across the spec read changes nothing.
 *
 *  RECEIPT EMISSION (§13.10): with `receipts` wired, the commit emits the terminal's receipt
 *  INLINE, best-effort, for the WINNING fact (won or lost — the terminal is committed either
 *  way and emission is idempotent). Invalid wiring refuses at ENTRY, before any terminal
 *  commits; a RUNTIME emission failure after the irreversible commit surfaces as
 *  `receiptEmission: { outcome: "failed" }` — it never masks the committed terminal, and
 *  {@link reconcileReceiptEmission} is the durable backstop that converges it. */
export declare function commitGoalResult(ctx: ActionContext, args: {
    ref: GoalRef;
    now: number;
    receipts?: ReceiptEmissionWiring;
    committer?: {
        instanceId: string;
        epoch: number;
    };
} & GoalCommitCause): Promise<{
    won: boolean;
    fact: GoalResultFact;
    status: GoalStatusValue;
    receiptEmission?: ReceiptEmissionResult | {
        outcome: "failed";
        error: EpEnvelopeError;
    };
}>;
/** The reverse-DNS detail kind carrying a goal's cached terminal fact on an error (§13.3). */
export declare const GOAL_TERMINAL_DETAIL_KIND = "ai.cotal.goal.terminal";
/** The reserved `cancel` command's handler seam. The goal ref derives STRUCTURALLY from the
 *  broker-authenticated request (a caller cancels only its own goals). Unknown = failed-
 *  precondition; terminal = failed-precondition with the cached outcome on error.details;
 *  otherwise the status transitions to `cancelling` (owner/caller-authored — no executor) and
 *  the owner later commits the `cancel` cause. A completion that landed during the transition is
 *  observed AFTER it and converges the projection. */
export declare function requestGoalCancel(ctx: ActionContext, args: {
    request: ParsedEpRequest;
    goalId: string;
    mode: "graceful" | "terminate";
}): Promise<GoalStatusValue>;
/** Settle a goal `uncertain` at its persisted acceptance-relative readiness deadline (the
 *  `readiness` cause). The bound is read from the PERSISTED spec; a target-pinned goal is
 *  REACHABLE (readiness is the owner's deadline, not an executor completion, so no executor is
 *  required). A racing late success that committed first wins and this returns the winner. */
export declare function settleGoalUncertain(ctx: ActionContext, args: {
    ref: GoalRef;
    now: number;
    committer?: {
        instanceId: string;
        epoch: number;
    };
    reason?: string;
}): Promise<{
    won: boolean;
    fact: GoalResultFact;
    status: GoalStatusValue;
}>;
/** One reconcile-index entry: a pointer to a goal ref plus the ACCEPTING executor's instanceId —
 *  the coordinates a SUCCESSOR incarnation needs to find + settle an orphaned in-flight goal it
 *  never held in memory. `iid` is the accepting incarnation's instanceId: a single-manager
 *  successor (a fresh instanceId) reconciles every entry, but it is the hook a multi-instance
 *  sweep filters on (never settle a goal a still-LIVE sibling instance owns — a filter-only add,
 *  no schema change). The acceptance clock is NOT duplicated here (it lives in the goal spec the
 *  sweep reads); for one (endpoint, iid) a concurrent same-goalId retry writes the byte-IDENTICAL
 *  entry (create-only idempotent). The readiness budget IS duplicated into the acceptance floor:
 *  a concurrent retry may need to serve a synchronous follower before the goal spec create lands,
 *  and returning the accepted identity without the bound that makes following it safe would recreate
 *  an unbounded/early-timeout acceptance. The goal spec remains settlement authority. */
export interface GoalIndexEntry {
    v: 1;
    endpoint: string;
    owner: string;
    actor: string;
    uid: string;
    goalId: string;
    iid: string;
    /** THE ACCEPTANCE FLOOR (H2). The identity the accepting incarnation ALLOCATED for this goal,
     *  written here because this entry is the only durable record that exists BEFORE the acceptance
     *  is acked — the goal spec does not carry it and the terminal fact does not exist yet. Without
     *  it, a concurrent same-goalId attempt that loses the bind has nothing truthful to serve while
     *  the winner is still in flight, and the honest answers are only "here is what the winner
     *  allocated" or a refusal. OPTIONAL for read compatibility with entries written before this
     *  field existed; absent means the floor was never persisted and a reader must refuse rather
     *  than invent one. */
    allocated?: {
        name: string;
        actor: string;
        uid: string;
        readinessDeadlineMs?: number;
    };
    /** An OPAQUE relay payload the accepting endpoint must be able to serve back after a restart —
     *  the durable half of a goal whose work is handed to another process (a seat's `turn` rides
     *  this: the run coordinates and rendered context the seat pulls). The substrate gives it no
     *  meaning and no shape beyond "a bounded string": what it says is the endpoint's contract with
     *  its puller, exactly as the goal command's args are. Absent on every goal that carries none. */
    note?: string;
}
export declare function parseGoalIndexEntry(raw: unknown, key: string): GoalIndexEntry;
/** Record an accepted goal in the endpoint's reconcile index, CREATE-ONLY and BEFORE the bind
 *  (must-5 Q-B): the atomicity is `index-CAS-before-bind`, so recoverability is clean either side
 *  of a crash — a crash AFTER this write and BEFORE the bind leaves an index entry whose goal
 *  status is absent (the sweep treats it as a no-goal and clears it); a crash BEFORE it leaves no
 *  entry, so the acceptance was never durable. `iid` is the accepting incarnation's instanceId.
 *  Idempotent for an adopted or concurrent same-goalId retry (a byte-identical pointer). */
export declare function recordGoalIndex(ctx: ActionContext, ref: GoalRef, iid: string, allocated?: {
    name: string;
    actor: string;
    uid: string;
    readinessDeadlineMs?: number;
}, note?: string): Promise<{
    recorded: true;
} | {
    recorded: false;
    existing: GoalIndexEntry;
}>;
/** Delete an index entry once its goal is terminal (or after a sweep settles it): a terminal goal
 *  is never reconciled again. Idempotent — an absent entry is a no-op. */
export declare function clearGoalIndex(ctx: ActionContext, ref: GoalRef): Promise<void>;
/** Read ONE reconcile-index entry over the goal-writer's own bonded KV — the durable answer to
 *  "who accepted this goalId, and what identity did they allocate for it", available from the
 *  moment of acceptance rather than only once a terminal exists. Absent means no incarnation ever
 *  durably accepted it. */
export declare function readGoalIndex(ctx: ActionContext, ref: GoalRef): Promise<GoalIndexEntry | undefined>;
/** Enumerate the endpoint's in-flight reconcile index over a RAW records KV: a successor's boot
 *  sweep opens it with the PROVISIONER credential (records CONSUMER.CREATE), never the goal-writer
 *  (which holds no enumeration grant), and settles each unterminal goal so an accepted goal is
 *  never dropped across a manager restart. Returns each recorded GoalRef + the accepting `iid` (the
 *  hook a multi-instance sweep filters on so it never settles a live sibling's goal). */
export declare function listGoalIndex(kv: KV, endpoint: string): Promise<{
    ref: GoalRef;
    iid: string;
    allocated?: GoalIndexEntry["allocated"];
    note?: string;
}[]>;
/** Classify a resubmission against the recorded bind: same fingerprint = retry (cached), else
 *  `conflict`. {@link resolveGoalSubmission} composes this with the orphaned-bind recovery. */
export declare function classifyGoalReuse(existing: GoalBindFact, submittedFingerprint: string): "cached" | "conflict";
//# sourceMappingURL=endpoint-action.d.ts.map