Actions API Reference

export declare function createProtectedActionRuntime<Input = unknown, Grounded = unknown>(options?: ProtectedActionRuntimeOptions): ProtectedActionRuntime<Input, Grounded>;

export declare function defineProtectedAction<Input, Grounded, EffectFields extends Record<string, unknown> = Record<string, unknown>>(definition: ProtectedActionDefinition<Input, Grounded, EffectFields>): ProtectedActionDefinition<Input, Grounded, EffectFields>;

export interface AbsentFinalEffectResolution { readonly status: "ABSENT_FINAL"; readonly effectIdentity: EffectIdentity | null; readonly observationRef?: string | null; readonly finalityRef?: string | null; readonly version?: string | null; readonly stateDigest?: string | null }

export interface ActionOperation<Input = unknown, Grounded = unknown> {
  readonly operationIdentity: OperationIdentity | null;
  readonly snapshot: OperationSnapshot<Input, Grounded>;
  readonly ground: (candidates: CandidateSource) => Promise<GroundingStageResult<Grounded>>;
  readonly requestClarification: () => ClarificationStageResult;
  readonly clarify: (response: ClarificationInput) => Promise<GroundingStageResult<Grounded>>;
  readonly requestConfirmation: () => ConfirmationStageResult;
  readonly confirm: (response: ConfirmationInput) => ConfirmationStageResult;
  readonly authorize: () => Promise<AuthorizationStageResult>;
  readonly prepare: () => Promise<PreparationStageResult>;
  readonly dispatch: () => Promise<DispatchStageResult>;
  readonly verifyEffect: () => Promise<EffectStageResult>;
  readonly cancel: (reason?: string) => CancelledResult | UnknownResult<Grounded>;
  readonly reconcile: (handle: LiveReconciliationHandle) => Promise<ProtectedActionResult<Grounded>>;
  readonly supersede: (replacement: ActionOperation) => SupersessionResult | UnknownResult<Grounded>;
}

export interface ActionSession<Input = unknown, Grounded = unknown> {
  readonly sessionIdentity: SessionIdentity;
  readonly snapshot: SessionSnapshot;
  readonly accept: (input: ProposalInput) => Promise<SessionStageResult<Input, Grounded>>;
  readonly operation: (action: string, input: unknown) => ActionOperation<unknown, Grounded>;
}

export interface ActionTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }

export interface AdmissionResult { readonly kind: "CLAIMED" | "DUPLICATE" | "IN_PROGRESS" | "REJECTED"; readonly record: DurableInvocationRecord }

export interface ApplicationTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }

export interface AuthoritativeStateReference { readonly observationRef?: string | null; readonly revision?: string | null; readonly stateDigest?: string | null }

export interface AuthorizationStageResult { readonly kind: "AUTHORIZED" | "DENIED" | "INTEGRATION_FAILURE"; readonly decision?: AuthorizationResult; readonly result?: ProtectedActionResult; readonly trace: TraceView }

export interface CancelledResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "CANCELLED"; readonly reason?: string }

export interface CandidateObservation {
  readonly candidate: CandidateReferent;
  readonly scope: string;
  readonly subject: string;
  readonly requestedEffect: Readonly<Record<string, unknown>>;
  readonly observationRef: string;
}

export interface CandidateReferent {
  readonly referent: string;
  readonly source: "authoritative";
  readonly attributes: Readonly<Record<string, string>>;
  readonly evidenceRefs: readonly string[];
  readonly observationRef?: string;
}

export interface CandidateSource { readonly candidates: readonly CandidateReferent[]; readonly observationRef: string }

export interface CapabilityRef { readonly capabilityId: string; readonly majorVersion: number; readonly metadata?: InputSchema }

export interface CasResult { readonly accepted: boolean; readonly record: DurableInvocationRecord }

export interface ClaimFactory<Input, Grounded, EffectFields> { readonly build: (input: { readonly input: Input; readonly grounded: RuntimeGroundedInput<Grounded>; readonly effectFields: EffectFields; readonly operationIdentity: OperationIdentity; readonly executionIdentity: ExecutionIdentity; readonly effectIdentity: EffectIdentity; readonly claimType: SafeClaimType }) => ClaimProposal }

export interface ClaimPermission { readonly decision: "PERMITTED" | "BLOCKED" | "INDETERMINATE"; readonly effectIdentity: EffectIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly __opaqueClaimPermission: unique symbol }

export interface ClaimProposal { readonly claimType: SafeClaimType; readonly effectIdentity: EffectIdentity; readonly executionIdentity: ExecutionIdentity; readonly subjectRef: string; readonly propositionRef?: string | null; readonly polarity: "positive" | "negative"; readonly scope: "historical_effect"; readonly attributes: Readonly<Record<string, string | number | boolean | null>>; readonly displayText?: string | null }

export interface ClaimView { readonly decision: ClaimPermission["decision"]; readonly reason: string; readonly claimType: SafeClaimType | null; readonly effectIdentity: EffectIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly subjectRef: string | null; readonly scope: "historical_effect" | null; readonly evidenceRefs: readonly string[]; readonly safeClaims: readonly SafeClaim[]; readonly permission?: ClaimPermission }

export interface ClarificationInput { readonly clarificationId: string; readonly evidence: unknown }

export interface ClarificationStageResult { readonly kind: "NEEDS_CLARIFICATION"; readonly clarification: unknown; readonly trace: TraceView }

export interface CommittedResult<Grounded = unknown> extends ResultCommon<Grounded, PresentEffectResolution> { readonly kind: "COMMITTED"; readonly effect: PresentEffectResolution; readonly claims: ClaimView; readonly providerDispatchOccurred: true }

export interface ConfirmationInput { readonly operationIdentity: OperationIdentity; readonly evidence: unknown }

export interface ConfirmationStageResult { readonly kind: "NEEDS_CONFIRMATION" | "INVALID_PROPOSAL"; readonly confirmation?: unknown; readonly result?: ProtectedActionResult; readonly trace: TraceView }

export interface CoreArtifacts { readonly operationIdentity: OperationIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly effectIdentity: EffectIdentity | null; readonly attemptIdentity: AttemptIdentity | null; readonly effectStatus: EffectTruthStatus; readonly claimDecision: ClaimPermission["decision"] | null }

export interface CoreTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }

export interface DeniedResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "DENIED"; readonly authorization: AuthorizationResult }

export interface DispatchStageResult { readonly kind: "DISPATCHED" | "UNKNOWN"; readonly attempt?: AttemptIdentity; readonly result?: ProtectedActionResult; readonly trace: TraceView }

export interface DisprovedResult<Grounded = unknown> extends ResultCommon<Grounded, AbsentFinalEffectResolution> { readonly kind: "DISPROVED"; readonly effect: AbsentFinalEffectResolution; readonly claims: ClaimView; readonly providerDispatchOccurred: true }

export interface DurableAttemptRecord { readonly attemptIdentity: AttemptIdentity; readonly executionIdentity: ExecutionIdentity; readonly effectIdentity: EffectIdentity; readonly operationIdentity: OperationIdentity; readonly outcome: "NOT_STARTED" | "IN_FLIGHT" | "ACKNOWLEDGED" | "FAILED" | "UNKNOWN"; readonly providerReference: ProviderReference | null; readonly providerIdempotencyReference: ProviderIdempotencyReference | null; readonly schemaVersion: string }

export interface DurableEffectRecord { readonly effectIdentity: EffectIdentity; readonly operationIdentity: OperationIdentity; readonly executionIdentity: ExecutionIdentity; readonly capability: CapabilityRef; readonly observationRef: string | null; readonly stateDigest: string | null; readonly status: "UNRESOLVED" | "COMMITTED" | "DISPROVED" | "UNKNOWN"; readonly schemaVersion: string }

export interface DurableExecutionRecord { readonly executionIdentity: ExecutionIdentity; readonly operationIdentity: OperationIdentity; readonly effectIdentity: EffectIdentity; readonly adapterIdentity: string; readonly capability: CapabilityRef; readonly schemaVersion: string }

export interface DurableInvocationRecord { readonly invocationId: HostInvocationIdentity; readonly deliveryId: DeliveryIdentity; readonly tenantRef: TenantRef; readonly actorRef: ActorRef; readonly actionName: string; readonly actionVersion: string; readonly state: LifecycleState; readonly revision: number; readonly ownerId: string | null; readonly fenceToken: string | null; readonly resultKind: ProtectedActionResultKind | null; readonly reconciliationRequired: boolean; readonly sanitizedErrorCode: string | null }

export interface DurableOperationRecord { readonly operationIdentity: OperationIdentity; readonly sessionIdentity: SessionIdentity | null; readonly actionName: string; readonly actionVersion: string; readonly tenantRef: TenantRef; readonly actorRef: ActorRef; readonly predecessorOperationIdentity: OperationIdentity | null; readonly replacementOperationIdentity: OperationIdentity | null; readonly serializedCoreReferences: Readonly<Record<string, string | null>>; readonly schemaVersion: string }

export interface DurableResultRecord { readonly invocationId: HostInvocationIdentity; readonly operationIdentity: OperationIdentity; readonly resultKind: ProtectedActionResultKind; readonly resultReference: string; readonly terminal: boolean; readonly reconciliationRequired: boolean; readonly schemaVersion: string }

export interface EffectStageResult { readonly kind: "COMMITTED" | "DISPROVED" | "UNKNOWN"; readonly effect?: EffectResolution; readonly result: ProtectedActionResult }

export interface FacadeConformanceReport { readonly action: string | null; readonly passed: boolean; readonly checks: Readonly<Record<string, boolean | "UNSUPPORTED" | "UNEVALUATED">> }

export interface IndeterminateEffectResolution { readonly status: "UNKNOWN"; readonly effectIdentity?: EffectIdentity | null; readonly observationRef?: string | null; readonly reason?: string | null }

export interface IntegrationFailureResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "INTEGRATION_FAILURE"; readonly phase: "configuration" | "persistence" | "recovery"; readonly code: string }

export interface InvalidProposalResult extends PreDispatchResultCommon { readonly kind: "INVALID_PROPOSAL"; readonly reason: string }

export interface LeaseResult { readonly kind: "ACQUIRED" | "IN_PROGRESS" | "TERMINAL" | "FENCED"; readonly ownerId: string | null; readonly fenceToken: string | null; readonly leaseExpiresAt: string | null; readonly revision: number }

export interface LifecycleIncident { readonly phase: "persistence" | "provider" | "verifier" | "projection" | "cancellation" | "supersession" | "staleness" | "recovery"; readonly code: string; readonly dispatchBoundary: "not_invoked" | "possibly_crossed"; readonly reference?: string | null }

export interface LiveReconciliationHandle {
  readonly __answerupLiveReconciliationHandle: unique symbol;
}

/** The one bounded vocabulary shared by snapshots and persistence CAS records. */

export interface NeedsClarificationResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "NEEDS_CLARIFICATION"; readonly clarification: unknown }

export interface NeedsConfirmationResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "NEEDS_CONFIRMATION"; readonly confirmation: unknown }

export interface NotDispatchedEffectTruth { readonly status: "NOT_DISPATCHED" }

export interface OperationOptions { readonly sessionIdentity?: SessionIdentity; readonly deliveryId?: DeliveryIdentity; readonly hostInvocationId?: HostInvocationIdentity; readonly prepareOnly?: boolean }

export interface OperationSnapshot<Input = unknown, Grounded = unknown> { readonly actionName: string; readonly actionVersion: string; readonly operationIdentity: OperationIdentity | null; readonly input: Input; readonly grounded: Grounded | null; readonly lifecycleState: LifecycleState; readonly predecessorOperationIdentity: OperationIdentity | null; readonly replacementOperationIdentity: OperationIdentity | null; readonly coreArtifacts: CoreArtifacts; readonly trace: TraceView }

export interface PhaseTimings { readonly total: number; readonly validation: number | null; readonly trustedContext: number | null; readonly grounding: number | null; readonly clarificationConfirmation: number | null; readonly authorization: number | null; readonly preparation: number | null; readonly providerDispatch: number | null; readonly authoritativeVerification: number | null; readonly claimEvaluation: number | null; readonly projection: number | null }
interface ResultCommon<Grounded, Truth extends EffectTruth> { readonly kind: ProtectedActionResultKind; readonly operation: PublicOperationSnapshot | null; readonly trace: TraceView; readonly timings: PhaseTimings; readonly core?: CoreArtifacts; readonly lifecycle: LifecycleState; readonly effectTruth: Truth; readonly incidents: readonly LifecycleIncident[] }
type PreDispatchResultCommon<Grounded = unknown> = ResultCommon<Grounded, NotDispatchedEffectTruth> & { readonly providerDispatchOccurred: false };

export interface PreparationStageResult { readonly kind: "PREPARED" | "STALE" | "INTEGRATION_FAILURE"; readonly execution?: unknown; readonly result?: ProtectedActionResult; readonly trace: TraceView }

export interface PresentEffectResolution { readonly status: "PRESENT"; readonly effectIdentity: EffectIdentity | null; readonly observationRef?: string | null; readonly version?: string | null; readonly stateDigest?: string | null }

export interface ProposalInput { readonly input: unknown; readonly deliveryId?: DeliveryIdentity; readonly correlationId?: string }

export interface ProposalValidationContext {
  readonly source: "application" | "frontend" | "framework" | "http" | "voice" | "worker";
  readonly correlationId?: string | null;
}

export interface ProtectedActionDefinition<Input, Grounded, EffectFields extends Record<string, unknown> = Record<string, unknown>> {
  readonly name: string;
  readonly version: string;
  readonly description?: string;
  readonly inputSchema?: InputSchema;
  readonly validateProposal: (input: unknown, context: ProposalValidationContext) => ProposalValidationResult<Input>;
  readonly ground: (input: Input, context: TrustedContext) => Promise<CandidateGroundingResult<Grounded>> | CandidateGroundingResult<Grounded>;
  readonly authorize: (input: { readonly input: Input; readonly context: TrustedContext; readonly grounded: RuntimeGroundedInput<Grounded> }) => Promise<AuthorizationResult> | AuthorizationResult;
  readonly provider: {
    readonly dispatch: (input: { readonly input: Input; readonly context: TrustedContext; readonly grounded: RuntimeGroundedInput<Grounded>; readonly operationIdentity: OperationIdentity; readonly executionIdentity: ExecutionIdentity; readonly effectIdentity: EffectIdentity; readonly attemptIdentity: AttemptIdentity }) => Promise<ProviderDispatchResult>;
    readonly adapterIdentity?: string;
    readonly capability?: CapabilityRef;
  };
  readonly verifier: {
    /** Frozen Runtime supplies input, context, grounded, effectIdentity, and its verification-attempt marker only. */
    readonly verify: (input: { readonly input: Input; readonly context: TrustedContext; readonly grounded: RuntimeGroundedInput<Grounded>; readonly effectIdentity: EffectIdentity; readonly attemptIdentity: "verification" }) => Promise<VerifierResult>;
    readonly verifierIdentity?: string;
  };
  readonly claims?: ClaimFactory<Input, Grounded, EffectFields>;
}

export interface ProtectedActionRuntime<Input = unknown, Grounded = unknown> {
  readonly register: <Input2, Grounded2, EffectFields extends Record<string, unknown> = Record<string, unknown>>(action: ProtectedActionDefinition<Input2, Grounded2, EffectFields>) => { readonly name: string; readonly version: string };
  readonly run: <Grounded2>(request: RunRequest) => Promise<ProtectedActionResult<Grounded2>>;
  readonly reconcile: (handle: LiveReconciliationHandle) => Promise<ProtectedActionResult<Grounded>>;
  readonly claims: (result: ProtectedActionResult) => ClaimView;
  readonly trace: (result: ProtectedActionResult | ActionSession | ActionOperation) => TraceView;
  readonly conformance: (action?: string) => FacadeConformanceReport;
}

export interface ProtectedActionRuntimeOptions { readonly store?: ProtectedActionStore; readonly trace?: TraceSink; readonly strictAuthorityFields?: boolean }

export interface ProtectedActionStore {
  readonly admit: (input: { readonly deliveryId: DeliveryIdentity; readonly tenantRef: TenantRef; readonly actorRef: ActorRef; readonly actionName: string; readonly actionVersion: string; readonly logicalEffectKey?: string | null }) => Promise<AdmissionResult>;
  readonly acquireLease: (input: { readonly invocationId: HostInvocationIdentity; readonly ownerId: string; readonly expectedRevision: number }) => Promise<LeaseResult>;
  readonly transition: (input: { readonly invocationId: HostInvocationIdentity; readonly ownerId: string; readonly fenceToken: string; readonly expectedRevision: number; readonly expectedState: LifecycleState; readonly transitionKind: TransitionKind; readonly transitionIdentity: string; readonly patch: LifecyclePatch }) => Promise<CasResult>;
  readonly atomicCommit: (input: { readonly invocationId: HostInvocationIdentity; readonly ownerId: string; readonly fenceToken: string; readonly expectedRevision: number; readonly expectedState: LifecycleState; readonly transitionKind: TransitionKind; readonly transitionIdentity: string; readonly patch: LifecyclePatch; readonly operation?: DurableOperationRecord; readonly execution?: DurableExecutionRecord; readonly effect?: DurableEffectRecord; readonly attempt?: DurableAttemptRecord; readonly result?: DurableResultRecord; readonly traceReferences?: readonly TraceReference[] }) => Promise<CasResult>;
  readonly loadOperation: (operationIdentity: OperationIdentity) => Promise<DurableOperationRecord | null>;
  readonly loadInvocation: (invocationId: HostInvocationIdentity) => Promise<DurableInvocationRecord | null>;
  readonly listReconciliation: () => Promise<readonly ReconciliationRecord[]>;
  readonly appendTraceReference: (reference: TraceReference) => Promise<void>;
}

export interface PublicOperationSnapshot { readonly actionName: string; readonly actionVersion: string; readonly operationIdentity: OperationIdentity | null; readonly input: null; readonly grounded: null; readonly lifecycleState: LifecycleState; readonly predecessorOperationIdentity: null; readonly replacementOperationIdentity: null; readonly coreArtifacts: CoreArtifacts; readonly trace: TraceView }

export interface ReconciliationRecord { readonly operationIdentity: OperationIdentity; readonly effectIdentity: EffectIdentity; readonly executionIdentity: ExecutionIdentity; readonly attemptIdentity: AttemptIdentity; readonly reason: string; readonly state: "PENDING" | "IN_PROGRESS" | "RESOLVED" | "QUARANTINED" }

export interface ReconciliationState { readonly kind: "IN_PROCESS_ONLY" | "REHYDRATION_REQUIRED"; readonly effectIdentity: EffectIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly attemptIdentity: AttemptIdentity | null; readonly needsReconciliation: true }

export interface RunRequest { readonly action: string; readonly input: unknown; readonly context: TrustedContext; readonly options?: OperationOptions }

export interface RuntimeGroundedInput<Grounded> {
  readonly scope: string;
  readonly subject: string;
  readonly requestedEffect: Readonly<Record<string, unknown>>;
  readonly candidates: readonly CandidateReferent[];
  readonly subjectAttributes?: Readonly<Record<string, string>>;
  readonly annotations?: readonly unknown[];
  readonly facadeGrounded: Grounded;
}

export interface SafeClaim { readonly claimType: SafeClaimType; readonly effectIdentity: EffectIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly subjectRef: null; readonly propositionRef?: null; readonly polarity: "positive" | "negative"; readonly scope: "historical_effect"; readonly attributes: Readonly<Record<string, never>>; readonly permission: ClaimPermission }

export interface SessionOptions { readonly sessionIdentity?: SessionIdentity; readonly trustedContext?: TrustedContext }

export interface SessionSnapshot { readonly sessionIdentity: SessionIdentity; readonly operationIdentities: readonly OperationIdentity[]; readonly pendingClarificationIds: readonly string[]; readonly pendingConfirmationIds: readonly string[]; readonly trace: TraceView }

export interface StaleResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "STALE"; readonly reason: string; readonly authoritativeState?: AuthoritativeStateReference }

export interface SupersededResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "SUPERSEDED"; readonly predecessor: OperationSnapshot; readonly replacement?: OperationSnapshot }

export interface SupersessionResult { readonly accepted: boolean; readonly predecessor: OperationSnapshot; readonly replacement: OperationSnapshot; readonly reason: "superseded" | "target_ambiguous" | "target_unresolved" | "invalid" | "already_superseded"; readonly trace: TraceView }

export interface TraceReference { readonly operationIdentity?: OperationIdentity; readonly event: ActionTraceEvent; readonly sequence: number }

export interface TraceSink { readonly append: (record: ActionTraceRecord | ApplicationTraceRecord) => void | Promise<void> }

export interface TraceView { readonly contract: "answerup-actions-trace/1"; readonly records: readonly ActionTraceRecord[]; readonly truncated: boolean; readonly omittedRecordCount: number }
/** Actions exposes only the closed event and projection-local order; Runtime attributes are never model-facing. */

export interface TrustedContext {
  readonly tenant: { readonly tenantRef: TenantRef; readonly securityDomainRef: SecurityDomainRef };
  readonly actor: { readonly actorRef: ActorRef; readonly assurance: string; readonly subjectRef?: string };
  readonly authorization: { readonly scopeRef: string; readonly policyRevision: string };
  readonly provider: { readonly accountRef: string; readonly scopeRef?: string };
  readonly authoritativeState?: { readonly revision?: string; readonly observationRef?: string };
  readonly delivery: { readonly deliveryId: DeliveryIdentity; readonly source: string };
  readonly hostInvocation: { readonly invocationId: HostInvocationIdentity; readonly ownerId?: string };
  readonly correlation?: { readonly requestId?: string; readonly responseTurnId?: ResponseCorrelationId; readonly frameworkCallId?: string };
}

export interface UnknownEffectResult<Grounded = unknown> extends ResultCommon<Grounded, IndeterminateEffectResolution> { readonly kind: "UNKNOWN"; readonly effect: IndeterminateEffectResolution; readonly reconciliation: ReconciliationState; readonly claims: ClaimView; readonly providerDispatchOccurred: true; readonly code?: string; readonly phase?: "verifier" | "recovery" | "provider" | "projection" }

export interface UnknownProjectionFailureResult<Grounded = unknown> extends ResultCommon<Grounded, { readonly status: "UNKNOWN" }> { readonly kind: "UNKNOWN"; readonly phase: "projection"; readonly code: "PROJECTION_FAILED"; readonly effect: { readonly status: "UNKNOWN"; readonly effectIdentity?: EffectIdentity | null }; readonly reconciliation: ReconciliationState; readonly providerDispatchOccurred: true; readonly claims?: never; readonly core?: never }

export type ActionName = string & { readonly __answerupActionName: unique symbol };

export type ActionTraceEvent = "EXECUTION_PREPARED" | "DISPATCH_BOUNDARY_CROSSED" | "EXECUTION_ATTEMPTED" | "EFFECT_VERIFICATION_REQUESTED" | "EFFECT_PRESENT" | "EFFECT_ABSENT_FINAL" | "EFFECT_INDETERMINATE" | "CLAIM_EVALUATED" | "CLAIM_PERMITTED" | "CLAIM_BLOCKED" | "CLAIM_INDETERMINATE" | "RECONCILIATION_PROJECTED";

export type ActionVersion = string & { readonly __answerupActionVersion: unique symbol };

export type ActorRef = string & { readonly __answerupActorRef: unique symbol };

export type AttemptIdentity = string & { readonly __answerupAttemptIdentity: unique symbol };

export type AuthorizationResult =
  | "PERMIT" | "DENY" | "INDETERMINATE"
  | { readonly decision: "PERMIT" | "DENY" | "INDETERMINATE"; readonly policyObservationRef?: string | null; readonly stateObservationRef?: string | null; readonly policyRevision?: string | null; readonly factDigest?: string | null; readonly reasonRef?: string | null };

export type CandidateGroundingResult<Grounded> =
  | { readonly kind: "GROUNDED"; readonly grounded: Grounded; readonly scope: string; readonly subject: string; readonly requestedEffect: Readonly<Record<string, unknown>>; readonly candidates: readonly CandidateReferent[]; readonly observationRef: string }
  | { readonly kind: "AMBIGUOUS" | "UNRESOLVED" | "INVALID"; readonly clarificationRequired: true; readonly reason: string; readonly candidates: readonly CandidateReferent[]; readonly observationRef?: string | null };

export type CorrectionLineageIdentity = string & { readonly __answerupCorrectionLineageIdentity: unique symbol };

export type DeliveryIdentity = string & { readonly __answerupDeliveryIdentity: unique symbol };

export type EffectIdentity = string & { readonly __answerupEffectIdentity: unique symbol };

export type EffectResolution = PresentEffectResolution | AbsentFinalEffectResolution | IndeterminateEffectResolution;

export type EffectTruth = NotDispatchedEffectTruth | PresentEffectResolution | AbsentFinalEffectResolution | IndeterminateEffectResolution;

export type EffectTruthStatus = "NOT_DISPATCHED" | "PRESENT" | "ABSENT_FINAL" | "UNKNOWN";

export type ExecutionIdentity = string & { readonly __answerupExecutionIdentity: unique symbol };

export type GroundingStageResult<Grounded> = { readonly kind: "GROUNDED"; readonly operation: ActionOperation<unknown, Grounded>; readonly grounded: Grounded; readonly core: CoreArtifacts; readonly trace: TraceView } | { readonly kind: "NEEDS_CLARIFICATION"; readonly clarification: unknown; readonly trace: TraceView } | { readonly kind: "INVALID_PROPOSAL"; readonly result: InvalidProposalResult };

export type HostInvocationIdentity = string & { readonly __answerupHostInvocationIdentity: unique symbol };

export type InputSchema = Readonly<Record<string, unknown>>;

export type LifecyclePatch = { readonly state?: LifecycleState; readonly resultKind?: ProtectedActionResultKind; readonly reconciliationRequired?: boolean; readonly sanitizedErrorCode?: string | null; readonly terminalAt?: string | null };

export type LifecycleState = "ADMITTED" | "CLAIMED" | "EXECUTING" | "UNKNOWN" | "TERMINAL" | "QUARANTINED" | "SUPERSEDED" | "CANCELLED";

export type LifecycleStatus = LifecycleState;

export type OperationIdentity = string & { readonly __answerupOperationIdentity: unique symbol };

export type ProposalValidationResult<Input> =
  | { readonly valid: true; readonly input: Input }
  | { readonly valid: false; readonly kind: "INVALID_PROPOSAL"; readonly code: string; readonly field?: string | null };

/** Tool/documentation metadata only; its presence is never runtime validation. */

export type ProtectedActionResult<Grounded = unknown> = InvalidProposalResult | NeedsClarificationResult<Grounded> | NeedsConfirmationResult<Grounded> | DeniedResult<Grounded> | StaleResult<Grounded> | SupersededResult<Grounded> | CancelledResult<Grounded> | DisprovedResult<Grounded> | CommittedResult<Grounded> | UnknownResult<Grounded> | IntegrationFailureResult<Grounded>;

export type ProtectedActionResultKind = "INVALID_PROPOSAL" | "NEEDS_CLARIFICATION" | "NEEDS_CONFIRMATION" | "DENIED" | "STALE" | "SUPERSEDED" | "CANCELLED" | "DISPROVED" | "COMMITTED" | "UNKNOWN" | "INTEGRATION_FAILURE";

export type ProviderDispatchResult =
  | { readonly kind: "ACKNOWLEDGED"; readonly providerReference?: ProviderReference | null; readonly providerIdempotencyReference?: ProviderIdempotencyReference | null }
  | { readonly kind: "REJECTED"; readonly code?: string | null }
  | { readonly kind: "PRECONDITION_FAILED"; readonly code?: string | null }
  | { readonly kind: "UNCERTAIN"; readonly reason?: string | null };

export type ProviderIdempotencyReference = string & { readonly __answerupProviderIdempotencyReference: unique symbol };

export type ProviderReference = string & { readonly __answerupProviderReference: unique symbol };

export type ResponseCorrelationId = string & { readonly __answerupResponseCorrelationId: unique symbol };

export type SafeClaimType = "EFFECT_COMMITTED" | "EFFECT_DISPROVED" | "EFFECT_UNKNOWN";

export type SecurityDomainRef = string & { readonly __answerupSecurityDomainRef: unique symbol };

export type SessionIdentity = string & { readonly __answerupSessionIdentity: unique symbol };

export type SessionStageResult<Input, Grounded> = { readonly kind: "ADMITTED"; readonly session: ActionSession<Input, Grounded>; readonly operation: ActionOperation<Input, Grounded> } | { readonly kind: "INVALID_PROPOSAL"; readonly result: InvalidProposalResult };

export type TenantRef = string & { readonly __answerupTenantRef: unique symbol };

export type TransitionKind = "ADMIT" | "GROUND" | "AUTHORIZE" | "PREPARE" | "DISPATCH" | "VERIFY" | "UNKNOWN" | "SUPERSEDE" | "CANCEL" | "RECONCILE" | "TERMINAL";

export type UnknownResult<Grounded = unknown> = UnknownEffectResult<Grounded> | UnknownProjectionFailureResult<Grounded>

export type VerifierResult =
  | { readonly kind: "PRESENT"; readonly observationRef: string; readonly version?: string | null; readonly stateDigest?: string | null }
  | { readonly kind: "ABSENT_FINAL"; readonly observationRef: string; readonly finalityRef: string; readonly version?: string | null; readonly stateDigest?: string | null }
  | { readonly kind: "INDETERMINATE"; readonly observationRef?: string | null; readonly reason?: string | null };