API Reference · public documentation
Actions API Reference
Protected-action definitions, outcome-aware plans, provider/verifier composition, exact-result live reconciliation, durable records, and bounded results.
Package-root boundary
ESM · Node >=22
import * as AnswerUp from '@answerup/actions';Documentation is public and this import is illustrative. Packages are not yet generally available; use it with the exact archives supplied through your trusted preview handoff.
Outcome-aware claim plans
const propositions = {
COMMITTED: { propositionRef: 'effect:committed' },
DISPROVED: { propositionRef: 'effect:did-not-occur' },
UNKNOWN: { propositionRef: 'observation:unresolved' },
};InitialExecutionClaimPlan, LiveReconciliationClaimPlan, and RecoveryClaimPlan are distinct boundaries. Their three entries are mutually exclusive alternatives. Authoritative truth is established first; only the matching proposition is selected for Core evaluation. Plan-based UNKNOWN authority appears through observationClaims with one of the exact historical scopes RELATED_INITIAL_VERIFICATION_OBSERVATION_ONLY, RELATED_LIVE_RECONCILIATION_OBSERVATION_ONLY, or RELATED_RECOVERY_OBSERVATION_ONLY.
Live UNKNOWN reconciliation
const initial = await runtime.run(request);
if (initial.kind === 'UNKNOWN') {
const related = await runtime.reconcile(initial, {
claimPlan: { propositions },
});
}Pass the exact returned UNKNOWN object to the same Actions runtime. Its live authority is process-local, identity-bound, and one-shot. The call performs verifier-only authoritative read-back and zero provider redispatch. The one-argument overload remains legacy proposition-specific compatibility behavior. Durable recovery is a separate host-operated DurableRecoveryRecordV2 and RecoveryClaimPlan flow; it does not happen automatically after restart.
Raw versioned declarations
These public static resources are the versioned declarations for @answerup/actions@0.2.0-preview.8. They contain no package implementation JavaScript.
curl -fsS https://build.answerup.ai/declarations/actions/0.2.0-preview.8/index.d.ts -o actions-0.2.0-preview.8.d.tsPublic package exports
Provider/verifier integration, initial execution, one-shot live read-back, and host-operated durable recovery. Every export has a stable URL fragment; the versioned declarations define these signatures.
Functions
createProtectedActionRuntimefunction
export declare function createProtectedActionRuntime<Input = unknown, Grounded = unknown>(options?: ProtectedActionRuntimeOptions): ProtectedActionRuntime<Input, Grounded>;defineProtectedActionfunction
export declare function defineProtectedAction<Input, Grounded, EffectFields extends Record<string, unknown> = Record<string, unknown>>(definition: ProtectedActionDefinition<Input, Grounded, EffectFields>): ProtectedActionDefinition<Input, Grounded, EffectFields>;Interfaces
AbsentFinalEffectResolutioninterface
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 }ActionOperationinterface
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>;
/** Accepts only the exact Actions-owned UNKNOWN object returned by this operation. */
readonly reconcile: {
/** Legacy/outcome-specific claim behavior. */
(result: UnknownResult<Grounded>): Promise<ProtectedActionResult<Grounded>>;
(result: UnknownResult<Grounded>, options: Readonly<{ claimPlan: LiveReconciliationClaimPlan }>): Promise<ProtectedActionResult<Grounded>>;
};
readonly supersede: (replacement: ActionOperation) => SupersessionResult | UnknownResult<Grounded>;
}ActionSessioninterface
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>;
}ActionTraceRecordinterface
export interface ActionTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }ActionsRecoveryAuthorityinterface
export interface ActionsRecoveryAuthority {
readonly acquire: (record: DurableRecoveryRecordV2) => Promise<ActionsRecoveryAuthorityProofV2 | null>;
readonly commit: (record: DurableRecoveryRecordV2, proof: ActionsRecoveryAuthorityProofV2, patch: ActionsRecoveryCommitPatch) => Promise<boolean>;
readonly release: (record: DurableRecoveryRecordV2, proof: ActionsRecoveryAuthorityProofV2) => Promise<void>;
}
/** Legacy/outcome-specific recovery input; it remains fail-closed on outcome mismatch. */ActionsRecoveryAuthorityProofV2interface
export interface ActionsRecoveryAuthorityProofV2 {
readonly accepted: true;
readonly durableRevision: number;
readonly durableSequence: number;
readonly acceptedLedgerRef: string;
readonly proofDigest: string;
readonly sourceRecordDigest: string;
}
interface ActionsRecoveryCommitPatchBase {
readonly observationRef?: string | null;
readonly observationVersion?: string | null;
readonly stateDigest?: string | null;
readonly finalityRef?: string | null;
readonly verificationAttemptIdentity?: string;
readonly sourceRecordDigest: string;
}ActionsRecoveryResultinterface
export interface ActionsRecoveryResult<Grounded = unknown> {
readonly result: ProtectedActionResult<Grounded>;
readonly recoveryRecord: DurableRecoveryRecord | null;
}ActionsVerifierOnlyRecoveryinterface
export interface ActionsVerifierOnlyRecovery<Grounded = unknown> {
readonly kind: "VERIFIER_ONLY_RECOVERY";
readonly operationIdentity: OperationIdentity | null;
readonly executionIdentity: ExecutionIdentity | null;
readonly effectIdentity: EffectIdentity | null;
readonly attemptIdentity: AttemptIdentity | null;
readonly reconcile: () => Promise<ActionsRecoveryResult<Grounded>>;
}AdmissionResultinterface
export interface AdmissionResult { readonly kind: "CLAIMED" | "DUPLICATE" | "IN_PROGRESS" | "REJECTED"; readonly record: DurableInvocationRecord }ApplicationTraceRecordinterface
export interface ApplicationTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */AuthoritativeStateReferenceinterface
export interface AuthoritativeStateReference { readonly observationRef?: string | null; readonly revision?: string | null; readonly stateDigest?: string | null }AuthorizationStageResultinterface
export interface AuthorizationStageResult { readonly kind: "AUTHORIZED" | "DENIED" | "INTEGRATION_FAILURE"; readonly decision?: AuthorizationResult; readonly result?: ProtectedActionResult; readonly trace: TraceView }CancelledResultinterface
export interface CancelledResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "CANCELLED"; readonly reason?: string }CandidateObservationinterface
export interface CandidateObservation {
readonly candidate: CandidateReferent;
readonly scope: SecurityDomainRef;
readonly subject: string;
readonly requestedEffect: Readonly<Record<string, unknown>>;
readonly observationRef: string;
}CandidateReferentinterface
export interface CandidateReferent {
readonly referent: string;
readonly source: "authoritative";
readonly attributes: {
readonly resource: string;
readonly [attribute: string]: string;
};
readonly evidenceRefs: readonly string[];
readonly observationRef?: string;
}CandidateSourceinterface
export interface CandidateSource { readonly candidates: readonly CandidateReferent[]; readonly observationRef: string }CapabilityRefinterface
export interface CapabilityRef { readonly capabilityId: string; readonly majorVersion: number; readonly metadata?: InputSchema }CasResultinterface
export interface CasResult { readonly accepted: boolean; readonly record: DurableInvocationRecord }
/** Design-level host store shape; not wired automatically to Runtime durable recovery in A1. */ClaimFactoryinterface
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 }ClaimPermissioninterface
export interface ClaimPermission { readonly decision: "PERMITTED" | "BLOCKED" | "INDETERMINATE"; readonly effectIdentity: EffectIdentity | null; readonly executionIdentity: ExecutionIdentity | null; readonly __opaqueClaimPermission: unique symbol }ClaimProposalinterface
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 }ClaimViewinterface
export interface ClaimView { readonly decision: ClaimPermission["decision"]; readonly reason: string; readonly claimType: TerminalSafeClaimType | 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 observationClaims?: readonly (RecoveryObservationClaimView | LiveReconciliationObservationClaimView | InitialVerificationObservationClaimView)[]; readonly permission?: RecoveryClaimPermissionView; readonly relatedResult?: RecoveryResultBinding }ClarificationInputinterface
export interface ClarificationInput { readonly clarificationId: string; readonly evidence: unknown }ClarificationStageResultinterface
export interface ClarificationStageResult { readonly kind: "NEEDS_CLARIFICATION"; readonly clarification: unknown; readonly trace: TraceView }CommittedResultinterface
export interface CommittedResult<Grounded = unknown> extends ResultCommon<Grounded, PresentEffectResolution> { readonly kind: "COMMITTED"; readonly effect: PresentEffectResolution; readonly claims: ClaimView; readonly providerDispatchOccurred: true }ConfirmationInputinterface
export interface ConfirmationInput { readonly operationIdentity: OperationIdentity; readonly evidence: unknown }ConfirmationStageResultinterface
export interface ConfirmationStageResult { readonly kind: "NEEDS_CONFIRMATION" | "INVALID_PROPOSAL"; readonly confirmation?: unknown; readonly result?: ProtectedActionResult; readonly trace: TraceView }CoreArtifactsinterface
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 }CoreTraceRecordinterface
export interface CoreTraceRecord { readonly event: ActionTraceEvent; readonly sequence: number }DeniedResultinterface
export interface DeniedResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "DENIED"; readonly authorization: AuthorizationResult }DispatchStageResultinterface
export interface DispatchStageResult { readonly kind: "DISPATCHED" | "UNKNOWN"; readonly attempt?: AttemptIdentity; readonly result?: ProtectedActionResult; readonly trace: TraceView }DisprovedResultinterface
export interface DisprovedResult<Grounded = unknown> extends ResultCommon<Grounded, AbsentFinalEffectResolution> { readonly kind: "DISPROVED"; readonly effect: AbsentFinalEffectResolution; readonly claims: ClaimView; readonly providerDispatchOccurred: true }DurableAttemptRecordinterface
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 }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */DurableEffectRecordinterface
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 }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */DurableExecutionRecordinterface
export interface DurableExecutionRecord { readonly executionIdentity: ExecutionIdentity; readonly operationIdentity: OperationIdentity; readonly effectIdentity: EffectIdentity; readonly adapterIdentity: string; readonly capability: CapabilityRef; readonly schemaVersion: string }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */DurableInvocationRecordinterface
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 }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */DurableOperationRecordinterface
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 }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */DurableRecoveryMetadatainterface
export interface DurableRecoveryMetadata {
readonly durableRevision: number;
readonly durableSequence: number;
readonly acceptedLedgerRef: string;
readonly configurationDigest: string;
}DurableResultRecordinterface
export interface DurableResultRecord { readonly invocationId: HostInvocationIdentity; readonly operationIdentity: OperationIdentity; readonly resultKind: ProtectedActionResultKind; readonly resultReference: string; readonly terminal: boolean; readonly reconciliationRequired: boolean; readonly schemaVersion: string }
/** Design-level host persistence shape; not Runtime DurableRecoveryRecord and does not reconstruct Runtime authority. */EffectStageResultinterface
export interface EffectStageResult { readonly kind: "COMMITTED" | "DISPROVED" | "UNKNOWN"; readonly effect?: EffectResolution; readonly result: ProtectedActionResult }FacadeConformanceReportinterface
export interface FacadeConformanceReport { readonly action: string | null; readonly passed: boolean; readonly checks: Readonly<Record<string, boolean | "UNSUPPORTED" | "UNEVALUATED">> }GroundingLifecycleIncidentinterface
export interface GroundingLifecycleIncident { readonly phase: "grounding"; readonly code: GroundingDiagnosticCode; readonly dispatchBoundary: "not_invoked"; readonly reference?: never }IndeterminateEffectResolutioninterface
export interface IndeterminateEffectResolution { readonly status: "UNKNOWN"; readonly effectIdentity?: EffectIdentity | null; readonly observationRef?: string | null; readonly reason?: string | null }InitialVerificationObservationClaimViewinterface
export interface InitialVerificationObservationClaimView { readonly claimType: "EFFECT_UNKNOWN"; readonly authorityScope: "RELATED_INITIAL_VERIFICATION_OBSERVATION_ONLY"; readonly bindingDigest: string }IntegrationFailureResultinterface
export interface IntegrationFailureResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "INTEGRATION_FAILURE"; readonly phase: "configuration" | "persistence" | "recovery"; readonly code: string }InvalidProposalResultinterface
export interface InvalidProposalResult extends PreDispatchResultCommon { readonly kind: "INVALID_PROPOSAL"; readonly reason: string }LeaseResultinterface
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 }LegacySafeClaiminterface
export interface LegacySafeClaim { readonly claimType: TerminalSafeClaimType }LiveReconciliationObservationClaimViewinterface
export interface LiveReconciliationObservationClaimView { readonly claimType: "EFFECT_UNKNOWN"; readonly authorityScope: "RELATED_LIVE_RECONCILIATION_OBSERVATION_ONLY"; readonly bindingDigest: string }
/** Historical authority for the exact initial verification observation; never current-state, terminal, retry, redispatch, or recovery authority. */NeedsClarificationResultinterface
export interface NeedsClarificationResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "NEEDS_CLARIFICATION"; readonly clarification: unknown }NeedsConfirmationResultinterface
export interface NeedsConfirmationResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "NEEDS_CONFIRMATION"; readonly confirmation: unknown }NotDispatchedEffectTruthinterface
export interface NotDispatchedEffectTruth { readonly status: "NOT_DISPATCHED" }OperationOptionsinterface
export interface OperationOptions { readonly sessionIdentity?: SessionIdentity; readonly deliveryId?: DeliveryIdentity; readonly hostInvocationId?: HostInvocationIdentity; readonly prepareOnly?: boolean }OperationSnapshotinterface
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 }OperationalLifecycleIncidentinterface
export interface OperationalLifecycleIncident { readonly phase: "configuration" | "persistence" | "provider" | "verifier" | "projection" | "cancellation" | "supersession" | "staleness" | "recovery"; readonly code: string; readonly dispatchBoundary: "not_invoked" | "possibly_crossed"; readonly reference?: string | null }OutcomeAwareRecoverySafeClaiminterface
export interface OutcomeAwareRecoverySafeClaim { readonly claimType: TerminalSafeClaimType; readonly polarity: "positive" | "negative"; readonly scope: "historical_effect"; readonly permission: RecoveryClaimPermissionView; readonly relatedResult: RecoveryResultBinding }PhaseTimingsinterface
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 };PreparationStageResultinterface
export interface PreparationStageResult { readonly kind: "PREPARED" | "STALE" | "INTEGRATION_FAILURE"; readonly execution?: unknown; readonly result?: ProtectedActionResult; readonly trace: TraceView }PresentEffectResolutioninterface
export interface PresentEffectResolution { readonly status: "PRESENT"; readonly effectIdentity: EffectIdentity | null; readonly observationRef?: string | null; readonly version?: string | null; readonly stateDigest?: string | null }ProposalInputinterface
export interface ProposalInput { readonly input: unknown; readonly deliveryId?: DeliveryIdentity; readonly correlationId?: string }ProposalValidationContextinterface
export interface ProposalValidationContext {
readonly source: "application" | "frontend" | "framework" | "http" | "voice" | "worker";
readonly correlationId?: string | null;
}ProtectedActionDefinitionBaseinterface
export interface ProtectedActionDefinitionBase<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;
};
/** Optional restart-safe verifier; it receives only Runtime's bounded recovery request. */
readonly recoveryVerifier?: RecoveryVerifierDefinition;
}ProtectedActionRuntimeinterface
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>>;
/**
* Performs one verifier-only live continuation for the exact Actions-owned
* UNKNOWN object returned by this runtime. Structural copies have no authority.
*/
readonly reconcile: {
/** Legacy/outcome-specific claim behavior. */
(result: UnknownResult<Grounded>): Promise<ProtectedActionResult<Grounded>>;
(result: UnknownResult<Grounded>, options: Readonly<{ claimPlan: LiveReconciliationClaimPlan }>): Promise<ProtectedActionResult<Grounded>>;
};
readonly exportRecoveryRecord: (result: UnknownResult<Grounded>, metadata: DurableRecoveryMetadata) => DurableRecoveryRecord;
/** Preferred complete outcome-aware recovery plan. */
readonly rehydrateRecovery: {
(input: Readonly<{ readonly record: DurableRecoveryRecordV2; readonly authority: ActionsRecoveryAuthority; readonly claimPlan: ActionsRecoveryClaimPlan }>): Promise<ActionsVerifierOnlyRecovery<Grounded>>;
/** Legacy/outcome-specific overload. */
(input: Readonly<{ readonly record: DurableRecoveryRecordV2; readonly authority: ActionsRecoveryAuthority; readonly claim: ActionsRecoveryClaimProposal }>): Promise<ActionsVerifierOnlyRecovery<Grounded>>;
};
readonly claims: (result: ProtectedActionResult) => ClaimView;
readonly trace: (result: ProtectedActionResult | ActionSession | ActionOperation) => TraceView;
readonly conformance: (action?: string) => FacadeConformanceReport;
}ProtectedActionRuntimeOptionsinterface
export interface ProtectedActionRuntimeOptions { readonly store?: ProtectedActionStore; readonly trace?: TraceSink; readonly strictAuthorityFields?: boolean }ProtectedActionStoreinterface
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>;
}PublicOperationSnapshotinterface
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 }ReconciliationRecordinterface
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" }ReconciliationStateinterface
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 }RecoveryClaimPermissionViewinterface
export interface RecoveryClaimPermissionView { readonly decision: "PERMITTED"; readonly claimType: TerminalSafeClaimType; readonly bindingDigest: string; readonly relatedResult: RecoveryResultBinding }
/** Historical authority for one exact accepted recovery observation; never current-state, terminal, retry, or redispatch authority. */RecoveryObservationClaimViewinterface
export interface RecoveryObservationClaimView { readonly claimType: "EFFECT_UNKNOWN"; readonly authorityScope: "RELATED_RECOVERY_OBSERVATION_ONLY"; readonly bindingDigest: string; readonly relatedResult: RecoveryResultBinding }
/** Historical authority for one exact live reconciliation observation; never current-state, terminal, retry, or redispatch authority. */RecoveryResultBindinginterface
export interface RecoveryResultBinding { readonly recoveryRecordIdentity: string; readonly durableRevision: number; readonly durableSequence: number; readonly sourceRecordDigest: string; readonly relatedResultIdentity: string; readonly semantics: "RELATED_RECOVERY_OBSERVATION_ONLY" }
/** Privacy-safe projection; this is not Core's raw ClaimPermission. */RecoveryVerifierDefinitioninterface
export interface RecoveryVerifierDefinition {
readonly verifierIdentity: string;
readonly capability: Readonly<{ readonly capabilityId: string; readonly majorVersion: number }>;
readonly configurationDigest: string;
readonly timeoutMs?: number;
readonly verify: (request: RecoveryVerifierRequest) => Promise<RecoveryVerifierResult> | RecoveryVerifierResult;
}RunRequestinterface
export interface RunRequest { readonly action: string; readonly input: unknown; readonly context: TrustedContext; readonly options?: OperationOptions }RuntimeGroundedInputinterface
export interface RuntimeGroundedInput<Grounded> {
readonly scope: SecurityDomainRef;
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;
}SessionOptionsinterface
export interface SessionOptions { readonly sessionIdentity?: SessionIdentity; readonly trustedContext?: TrustedContext }SessionSnapshotinterface
export interface SessionSnapshot { readonly sessionIdentity: SessionIdentity; readonly operationIdentities: readonly OperationIdentity[]; readonly pendingClarificationIds: readonly string[]; readonly pendingConfirmationIds: readonly string[]; readonly trace: TraceView }StaleResultinterface
export interface StaleResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "STALE"; readonly reason: string; readonly authoritativeState?: AuthoritativeStateReference }SupersededResultinterface
export interface SupersededResult<Grounded = unknown> extends PreDispatchResultCommon<Grounded> { readonly kind: "SUPERSEDED"; readonly predecessor: OperationSnapshot; readonly replacement?: OperationSnapshot }SupersessionResultinterface
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 }TraceReferenceinterface
export interface TraceReference { readonly operationIdentity?: OperationIdentity; readonly event: ActionTraceEvent; readonly sequence: number }TraceSinkinterface
export interface TraceSink { readonly append: (record: ActionTraceRecord | ApplicationTraceRecord) => void | Promise<void> }TraceViewinterface
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. */TrustedContextinterface
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 };
}UnknownEffectResultinterface
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" }UnknownProjectionFailureResultinterface
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 }Types
ActionNametype
export type ActionName = string & { readonly __answerupActionName: unique symbol };ActionTraceEventtype
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";ActionVersiontype
export type ActionVersion = string & { readonly __answerupActionVersion: unique symbol };ActionsRecoveryClaimPlantype
export type ActionsRecoveryClaimPlan = RecoveryClaimPlan;ActionsRecoveryClaimProposaltype
export type ActionsRecoveryClaimProposal = RecoveryClaimProposal;ActionsRecoveryCommitPatchtype
export type ActionsRecoveryCommitPatch = ActionsRecoveryTerminalCommitPatch | ActionsRecoveryContinuingCommitPatch;ActionsRecoveryContinuingCommitPatchtype
export type ActionsRecoveryContinuingCommitPatch = ActionsRecoveryCommitPatchBase & {
readonly status: "UNKNOWN";
readonly nextSourceRecordDigest: string;
readonly recoveryRecord: DurableRecoveryRecordV2;
};ActionsRecoveryTerminalCommitPatchtype
export type ActionsRecoveryTerminalCommitPatch = ActionsRecoveryCommitPatchBase & {
readonly status: "COMMITTED" | "DISPROVED";
readonly nextSourceRecordDigest: null;
};ActorReftype
export type ActorRef = string & { readonly __answerupActorRef: unique symbol };AttemptIdentitytype
export type AttemptIdentity = string & { readonly __answerupAttemptIdentity: unique symbol };AuthorizationResulttype
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 };CandidateGroundingResulttype
export type CandidateGroundingResult<Grounded> =
| { readonly kind: "GROUNDED"; readonly grounded: Grounded; readonly scope: SecurityDomainRef; 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 };CorrectionLineageIdentitytype
export type CorrectionLineageIdentity = string & { readonly __answerupCorrectionLineageIdentity: unique symbol };DeliveryIdentitytype
export type DeliveryIdentity = string & { readonly __answerupDeliveryIdentity: unique symbol };DurableRecoveryAuthorityProofV2type
export type DurableRecoveryAuthorityProofV2 = RuntimeDurableRecoveryProofV2;DurableRecoveryRecordtype
export type DurableRecoveryRecord = DurableRecoveryRecordV2;DurableRecoveryRecordV2type
export type DurableRecoveryRecordV2 = RuntimeDurableRecoveryRecordV2;
/** Actions durable recovery is intentionally version-2-only. */EffectIdentitytype
export type EffectIdentity = string & { readonly __answerupEffectIdentity: unique symbol };EffectResolutiontype
export type EffectResolution = PresentEffectResolution | AbsentFinalEffectResolution | IndeterminateEffectResolution;EffectTruthtype
export type EffectTruth = NotDispatchedEffectTruth | PresentEffectResolution | AbsentFinalEffectResolution | IndeterminateEffectResolution;EffectTruthStatustype
export type EffectTruthStatus = "NOT_DISPATCHED" | "PRESENT" | "ABSENT_FINAL" | "UNKNOWN";ExecutionIdentitytype
export type ExecutionIdentity = string & { readonly __answerupExecutionIdentity: unique symbol };GroundingDiagnosticCodetype
export type GroundingDiagnosticCode =
| "GROUNDING_SCOPE_MISMATCH"
| "GROUNDING_RESOURCE_DISCRIMINATOR_MISSING"
| "GROUNDING_RESOURCE_DISCRIMINATOR_MISMATCH"
| "GROUNDING_RESOURCE_DISCRIMINATION_AMBIGUOUS";GroundingStageResulttype
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 };HostInvocationIdentitytype
export type HostInvocationIdentity = string & { readonly __answerupHostInvocationIdentity: unique symbol };InputSchematype
export type InputSchema = Readonly<Record<string, unknown>>;LifecycleIncidenttype
export type LifecycleIncident = GroundingLifecycleIncident | OperationalLifecycleIncident;LifecyclePatchtype
export type LifecyclePatch = { readonly state?: LifecycleState; readonly resultKind?: ProtectedActionResultKind; readonly reconciliationRequired?: boolean; readonly sanitizedErrorCode?: string | null; readonly terminalAt?: string | null };LifecycleStatetype
export type LifecycleState = "ADMITTED" | "CLAIMED" | "EXECUTING" | "UNKNOWN" | "TERMINAL" | "QUARANTINED" | "SUPERSEDED" | "CANCELLED";OperationIdentitytype
export type OperationIdentity = string & { readonly __answerupOperationIdentity: unique symbol };ProposalValidationResulttype
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. */ProtectedActionDefinitiontype
export type ProtectedActionDefinition<Input, Grounded, EffectFields extends Record<string, unknown> = Record<string, unknown>> = ProtectedActionDefinitionBase<Input, Grounded, EffectFields> & (
| { readonly initialExecutionClaimPlan: InitialExecutionClaimPlan; readonly claims?: never }
| { readonly initialExecutionClaimPlan?: never; readonly claims?: ClaimFactory<Input, Grounded, EffectFields> }
);
/** The one bounded vocabulary shared by snapshots and persistence CAS records. */ProtectedActionResulttype
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>;ProtectedActionResultKindtype
export type ProtectedActionResultKind = "INVALID_PROPOSAL" | "NEEDS_CLARIFICATION" | "NEEDS_CONFIRMATION" | "DENIED" | "STALE" | "SUPERSEDED" | "CANCELLED" | "DISPROVED" | "COMMITTED" | "UNKNOWN" | "INTEGRATION_FAILURE";ProviderDispatchResulttype
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 };ProviderIdempotencyReferencetype
export type ProviderIdempotencyReference = string & { readonly __answerupProviderIdempotencyReference: unique symbol };ProviderReferencetype
export type ProviderReference = string & { readonly __answerupProviderReference: unique symbol };ResponseCorrelationIdtype
export type ResponseCorrelationId = string & { readonly __answerupResponseCorrelationId: unique symbol };SafeClaimtype
export type SafeClaim = LegacySafeClaim | OutcomeAwareRecoverySafeClaim;SafeClaimTypetype
export type SafeClaimType = "EFFECT_COMMITTED" | "EFFECT_DISPROVED" | "EFFECT_UNKNOWN";SecurityDomainReftype
export type SecurityDomainRef = string & { readonly __answerupSecurityDomainRef: unique symbol };SessionIdentitytype
export type SessionIdentity = string & { readonly __answerupSessionIdentity: unique symbol };SessionStageResulttype
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 };TenantReftype
export type TenantRef = string & { readonly __answerupTenantRef: unique symbol };TerminalSafeClaimTypetype
export type TerminalSafeClaimType = Exclude<SafeClaimType, "EFFECT_UNKNOWN">;TransitionKindtype
export type TransitionKind = "ADMIT" | "GROUND" | "AUTHORIZE" | "PREPARE" | "DISPATCH" | "VERIFY" | "UNKNOWN" | "SUPERSEDE" | "CANCEL" | "RECONCILE" | "TERMINAL";UnknownResulttype
export type UnknownResult<Grounded = unknown> = UnknownEffectResult<Grounded> | UnknownProjectionFailureResult<Grounded>VerifierResulttype
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 };Re-exported declarations
InitialExecutionClaimPlanre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }InitialExecutionClaimPlanPropositionre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }LiveReconciliationClaimPlanre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }LiveReconciliationClaimPlanPropositionre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }RecoveryClaimPlanre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }RecoveryClaimPlanPropositionre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }RecoveryClaimProposalre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }RecoveryVerifierRequestre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }RecoveryVerifierResultre-export
export type { LiveReconciliationClaimPlan, LiveReconciliationClaimPlanProposition, InitialExecutionClaimPlan, InitialExecutionClaimPlanProposition, RecoveryClaimProposal, RecoveryClaimPlan, RecoveryClaimPlanProposition, RecoveryVerifierRequest, RecoveryVerifierResult }Examples and deeper guidance
Executable package pages show a package-specific, non-executing import example. Use the exact declaration surface for signatures and types; no credentials or external execution are provided here.
Read the related lifecycle guidance for the package’s documented role.