Runtime API Reference

export declare const CORE_SURFACE_VERSION: string;

export declare const RUNTIME_ARTIFACTS_CONTRACT: "answerup-runtime-artifacts/1";

export declare const RUNTIME_VERSION: "0.2.0-preview.1";

export declare const SUPPORTED_CORE_SURFACE: "1.0.0-rc.1";

export declare function createActionRuntime(options?: unknown): ActionRuntime;

export declare function defineAction(definition: ActionDefinition): ActionDefinition;

export interface ActionDefinition { readonly name: string; readonly version: string; readonly ground: Function; readonly authorize: Function; readonly adapter: { readonly dispatch: Function }; readonly verifier: { readonly verify: Function }; readonly claims?: Function; readonly [key: string]: unknown; }

export interface ActionRuntime { register(definition: ActionDefinition): Readonly<{ name: string; version: string }>; execute(name: string, input: unknown, context?: unknown): Promise<RuntimeExecutionResult>; reconcile(resultOrHandle: RuntimeExecutionResult | LiveReconciliationHandle): Promise<RuntimeExecutionResult>; project(result: RuntimeExecutionResult): RuntimeProjectionResult; claims(result: RuntimeExecutionResult): unknown; trace(result: RuntimeExecutionResult): unknown; conformance(action?: string | ActionDefinition): unknown; [key: string]: unknown; }

export interface LiveReconciliationHandle { readonly __answerupLiveReconciliationHandle: unique symbol; }

export interface RuntimeArtifactProjection { readonly contract: ContractVersion; readonly projectionKind: "NORMAL"; readonly projectionVersion: ProjectionVersion; readonly projectionIntegrity: "VALID" | "TRUNCATED"; readonly identities: RuntimeIdentityProjection; readonly effect: RuntimeEffectProjection; readonly claimDecision: ArtifactSlot<ClaimDecision>; readonly authorization: ArtifactSlot<Readonly<{ readonly decision: "PERMIT" | "DENY" | "INDETERMINATE" }>>; readonly grounding: ArtifactSlot<Readonly<{ readonly status: "GROUNDED" | "AMBIGUOUS" | "UNRESOLVED" | "INVALID" }>>; readonly claimPermission: RuntimeClaimProjection; readonly trace: RuntimeTraceProjection; readonly reconciliation: ArtifactSlot<"PENDING" | "RESOLVED">; }

export interface RuntimeClaimProjection { readonly decision: ArtifactSlot<ClaimDecision>; readonly claimType: ArtifactSlot<"EFFECT_COMMITTED" | "EFFECT_DISPROVED" | "EFFECT_UNKNOWN" | "EXECUTION_ATTEMPTED">; readonly binding: ArtifactSlot<Readonly<{ readonly effectIdentity: string; readonly executionIdentity: string }>>; }

export interface RuntimeEffectProjection { readonly dispatchBoundary: DispatchBoundary; readonly truth: EffectTruth; readonly resolution: ArtifactSlot<{ readonly state: EffectResolutionState; readonly observationRef?: string; readonly finalityRef?: string }>; readonly providerReference: ArtifactSlot<string>; readonly providerIdempotencyReference: ArtifactSlot<string>; }

export interface RuntimeExecutionResult { readonly __answerupRuntimeOwnedResult: unique symbol; readonly contract: ContractVersion; readonly status: EffectTruth | "CLARIFICATION_REQUIRED" | "READY"; readonly operationIdentity?: string; readonly effectIdentity?: string; readonly executionIdentity?: string; readonly attemptIdentity?: string | null; readonly adapterResult?: string; readonly effectResolution?: unknown; readonly claimPermission?: unknown; readonly safeClaims?: readonly unknown[]; readonly needsClarification?: boolean; readonly needsReconciliation?: boolean; readonly reconciliation?: LiveReconciliationHandle; readonly handle?: object; readonly trace?: readonly unknown[]; }

export interface RuntimeIdentityProjection { readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attemptIdentity: ArtifactSlot<string>; }

export interface RuntimeProjectionFailure { readonly contract: ContractVersion; readonly projectionKind: "PROJECTION_FAILURE"; readonly projectionVersion: ProjectionVersion; readonly reason: "SIZE_LIMIT"; readonly effectTruth: EffectTruth; readonly dispatchBoundary: DispatchBoundary; readonly projectionIntegrity: "FAILED"; }

export interface RuntimeProjectionResult { readonly status: "PROJECTED" | "PROJECTION_UNAVAILABLE" | "MALFORMED_INPUT"; readonly effectTruth: EffectTruth | "UNAVAILABLE"; readonly projection: ArtifactSlot<RuntimeProjectionValue>; }

export interface RuntimeTraceProjection { readonly records: readonly RuntimeTraceRecord[]; readonly truncated: boolean; readonly omittedRecordCount: number; }

export type ArtifactSlot<T> =
  | { readonly state: "available"; readonly value: T }
  | { readonly state: "unavailable"; readonly reason: UnavailableReason }
  | { readonly state: "omitted"; readonly reason: OmittedReason };

export type ClaimDecision = "PERMITTED" | "BLOCKED" | "INDETERMINATE";

export type ContractVersion = "answerup-runtime-artifacts/1";

export type DispatchBoundary = "NOT_INVOKED" | "POSSIBLY_INVOKED" | "CROSSED";

export type EffectResolutionState = "PRESENT" | "ABSENT_FINAL" | "INDETERMINATE";

export type EffectTruth = "COMMITTED" | "DISPROVED" | "UNKNOWN" | "NOT_DISPATCHED";

export type OmittedReason = "SENSITIVE" | "UNBOUNDED" | "NO_CORE_AUTHORITY" | "UNSUPPORTED";

export type ProjectionVersion = "1";

export type RuntimeProjectionValue = RuntimeArtifactProjection | RuntimeProjectionFailure;

export type RuntimeTraceRecord =
  | { readonly event: "GROUNDING_EVALUATED"; readonly sequence: number; readonly status: "GROUNDED" | "AMBIGUOUS" | "UNRESOLVED" | "INVALID"; readonly operationIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "AUTHORIZATION_EVALUATED"; readonly sequence: number; readonly decision: "PERMIT" | "DENY" | "INDETERMINATE"; readonly operationIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "EXECUTION_PREPARED"; readonly sequence: number; readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "DISPATCH_BOUNDARY_CROSSED" | "EXECUTION_ATTEMPTED"; readonly sequence: number; readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attemptIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "EFFECT_VERIFICATION_REQUESTED" | "EFFECT_PRESENT" | "EFFECT_ABSENT_FINAL" | "EFFECT_INDETERMINATE"; readonly sequence: number; readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attemptIdentity: ArtifactSlot<string>; readonly observationRef: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "CLAIM_EVALUATED" | "CLAIM_PERMITTED" | "CLAIM_BLOCKED" | "CLAIM_INDETERMINATE"; readonly sequence: number; readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes }
  | { readonly event: "RECONCILIATION_PROJECTED"; readonly sequence: number; readonly operationIdentity: ArtifactSlot<string>; readonly effectIdentity: ArtifactSlot<string>; readonly executionIdentity: ArtifactSlot<string>; readonly attemptIdentity: ArtifactSlot<string>; readonly attributes: TraceAttributes };

export type TraceAttributes = Readonly<Record<string, TraceScalar>>;

export type TraceScalar = string | number | boolean;

export type UnavailableReason = "NOT_CREATED" | "NOT_RETURNED_BY_AUTHORITY" | "NOT_APPLICABLE" | "MALFORMED";