Core API Reference

export declare const AUTHORIZATION_TRACE_EVENTS: readonly ["AUTHORIZATION_REQUESTED", "AUTHORIZATION_PERMITTED", "AUTHORIZATION_DENIED", "AUTHORIZATION_INDETERMINATE"];

export declare const CLAIM_DECISIONS: readonly ["PERMITTED", "BLOCKED", "INDETERMINATE"];

export declare const CLAIM_POLARITIES: readonly ["positive", "negative"];

export declare const CLAIM_REASONS: readonly ["EFFECT_COMMITTED", "EFFECT_DISPROVED", "EFFECT_UNKNOWN", "ATTEMPT_ONLY", "WRONG_EFFECT", "WRONG_SUBJECT", "VALUE_MISMATCH", "WORKFLOW_NOT_ESTABLISHED", "UNSUPPORTED_CLAIM_TYPE", "CLAIM_INVALID", "EVIDENCE_MISSING", "EVIDENCE_CONFLICT"];

export declare const CLAIM_SCOPES: readonly ["historical_effect", "attempt_status"];

export declare const CLAIM_TRACE_EVENTS: readonly ["CLAIM_EVALUATED", "CLAIM_PERMITTED", "CLAIM_BLOCKED", "CLAIM_INDETERMINATE"];

export declare const CLAIM_TYPES: readonly ["EFFECT_COMMITTED", "EFFECT_DISPROVED", "EFFECT_UNKNOWN", "EXECUTION_ATTEMPTED"];

export declare const CONFIRMATION_TRACE_EVENTS: readonly ["CONFIRMATION_REQUESTED", "CONFIRMATION_TARGET_RESOLVED", "CONFIRMATION_TARGET_AMBIGUOUS", "CONFIRMATION_EVIDENCE_ACCEPTED", "OPERATION_CONFIRMED"];

export declare const CORE_CONFORMANCE_CHECKS: readonly ["identity_stability", "evidence_provenance", "ai_proposal_separation", "capability_declaration", "action_contract_shape", "adapter_authority_containment", "retry_idempotency", "provider_neutrality"];

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

export declare const CORE_TRACE_CONTRACT: "core-trace-hooks/1";

export declare const DISPATCH_PATHS: readonly ["direct", "capability"];

export declare const DURABILITY_RECOVERY_CAPABILITIES: readonly ["EXACT_EFFECT_RECONCILIATION"];

export declare const EFFECT_RESOLUTION_TRACE_EVENTS: readonly ["EFFECT_VERIFICATION_REQUESTED", "EFFECT_COMMITTED", "EFFECT_DISPROVED", "EFFECT_STILL_UNKNOWN"];

export declare const EVIDENCE_KINDS: readonly ["human_verbatim", "human_structured", "external_ai_proposal", "media_reference"];

export declare const EXECUTION_TRACE_EVENTS: readonly ["EXECUTION_PREPARED", "EXECUTION_ATTEMPTED", "ADAPTER_ACKNOWLEDGED", "EXECUTION_FAILED", "EXECUTION_OUTCOME_UNKNOWN"];

export declare const FRONTEND_CAPABILITIES: readonly ["text_io", "realtime_voice", "interruption", "async_delivery", "continuous_session", "display", "authenticated_identity", "multimodal_capture", "external_ai_mediation", "handoff"];

export declare const OUTCOME_CLASSES: readonly OutcomeClass[];

export declare const REFERENT_TRACE_EVENTS: readonly ["REFERENT_CANDIDATES_OBSERVED", "AMBIGUITY_DETECTED", "CLARIFICATION_REQUIRED", "CLARIFICATION_EVIDENCE_ACCEPTED", "REFERENT_GROUNDED", "OPERATION_GROUNDED", "GROUNDING_BLOCKED"];

export declare const SUPERSESSION_TRACE_EVENTS: readonly ["CORRECTION_EVIDENCE_ACCEPTED", "SUPERSESSION_TARGET_GROUNDED", "OPERATION_SUPERSEDED", "SUPERSESSION_BLOCKED"];

export declare function acceptCanonicalIngress(sub: CanonicalIngressSubmission): CanonicalIngressAcceptance;

export declare function acceptNormalizedInboundTurn(turn: NormalizedInboundTurn): IngressAcceptance;

// integration/effect-identity.d.ts
import { type CapabilityRef } from "./contracts";

export declare function bindClarificationResponse(input: {
    clarification: ClarificationState;
    evidence: RequesterEvidenceProof;
}): ClarificationResponseContext | null;

export declare function bindConfirmationResponse(input: {
    target: ConfirmationTargetResolution;
}): ConfirmationResponseBinding | null;

export declare function bindEvidenceDiscriminator(input: {
    evidence: RequesterEvidenceProof;
    key: string;
    sourceSpan: {
        start: number;
        end: number;
    };
    responseContext?: ClarificationResponseContext;
}): EvidenceDiscriminator | null;

export declare function buildIngressProvenance(sub: CanonicalIngressSubmission, acceptance: CanonicalIngressAcceptance): Record<string, unknown>;

// integration/trace-hooks.d.ts
import { type CanonicalIngressAcceptance, type CanonicalIngressSubmission } from "./ingress-contract";

export declare function capabilityLabel(ref: CapabilityRef): string;

export declare function composeAuthoritySurrogateDigest(kind: string, ids: Record<string, unknown>): string;

export declare function composeEffectKeyDigest(input: EffectIdentityInput): string;

// integration/ingress-contract.d.ts
import { type NormalizedInboundTurn } from "./contracts";

export declare function confirmOperation(input: {
    response: ConfirmationResponseBinding;
}): ConfirmationResult;

export declare function correlateTraceRecords(records: CoreTraceRecord[]): TraceCorrelation;

// operation-state.d.ts

export declare function createAuthorizationContext(input: {
    operation: OperationLifecycle;
    authority: AuthorizationAuthority;
    actor: AuthorizationActorContext;
    target: AuthorizationTarget;
    confirmationRequirement: ConfirmationRequirement;
    confirmationDecision?: ConfirmationDecision | null;
}): AuthorizationContext | null;

export declare function createCapabilityExecutorSlot(label: string, capabilityName: string): CapabilityExecutorSlot;

export declare function createCorrectionEvidence(input: {
    predecessorEvidence: readonly EvidenceDiscriminator[];
    replacementEvidence: readonly EvidenceDiscriminator[];
}): CorrectionEvidence | null;

export declare function createOperationLifecycle(input: {
    groundedOperation: GroundedOperation;
}): OperationLifecycle | null;

export declare function createRecoveryContext(input: {
    authority: unknown;
    request: unknown;
}): Promise<RecoveryContext | null>;

export declare function createReferentTraceRecord(input: {
    event: ReferentTraceEvent;
    correlationId?: string;
    operationId: string;
    clarificationId?: string | null;
    observationRef?: string | null;
    candidateRefs?: readonly string[];
    evidenceRefs?: readonly string[];
    referent?: string | null;
    predecessorOperationIdentity?: string;
    replacementOperationIdentity?: string;
}): ReferentTraceRecord;

export declare function currentDispatchPath(): DispatchPath;

export declare function currentEffectResolution(executionContext: unknown): EffectResolution | null;

export declare function currentRecoveryEffectResolution(recoveryContext: unknown): EffectResolution | null;

// execution.d.ts
import { type CapabilityRef } from "./integration/contracts";
import { type ReferentTraceRecord } from "./integration/trace-hooks";
import { type OperationLifecycle } from "./supersession";
import { type AuthorizationContext, type AuthorizationDecision } from "./authorization";

export declare function dispatchExecution(context: unknown, options?: {
    retry?: boolean;
}): Promise<ExecutionDispatchResult>;

export declare function effectTraceRecord(input: {
    capability: string;
    effectKeyDigest: string;
    authoritySurrogateDigest: string;
    outcomeClass: string;
    evidenceKeyDigests: string[];
}): EffectTraceRecord;

export declare function evaluateAuthorization(input: {
    context: AuthorizationContext;
}): AuthorizationDecision;

export declare function evaluateClaim(proposalInput: unknown, evidenceInput: unknown): ClaimPermission | null;

export declare function evaluateGrounding(input: {
    proposal: OperationProposal;
    candidateSet: ReferentCandidateSet;
    evidence: readonly EvidenceDiscriminator[];
}): GroundingDecision;

export declare function executionClaimBinding(context: unknown): {
    subjectDigest: string;
    attributesDigest: string;
} | null;

export declare function getRequesterEvidenceMetadata(proof: RequesterEvidenceProof): {
    text: string;
    sequence: number;
    proof: RequesterEvidenceProof;
} | null;

export declare function getRequesterEvidenceSequence(): number;

export declare function groundOperation(input: {
    proposal: OperationProposal;
    resolution: ReferentResolution;
}): GroundedOperation | null;

export declare function ingressTraceRecord(sub: CanonicalIngressSubmission, acceptance: CanonicalIngressAcceptance): IngressTraceRecord;

export declare function isCoreGroundedOperation(value: unknown): value is GroundedOperation;

export declare function isCoreOperationLifecycle(value: unknown): value is OperationLifecycle;

export declare function isOperationActionable(value: unknown): boolean;

export declare function isOperationSuperseded(operationIdentity: string): boolean;

// recovery.d.ts
import { type CapabilityRef } from "./integration/contracts";

export declare function issueRequesterEvidence(submission: CanonicalIngressSubmission): RequesterEvidenceProof | null;

export declare function markOperationSuperseded(operationIdentity: string): void;

export declare function normalizeGroundingValue(value: string): string;

export declare function opaqueDigest(value: unknown): string;

// integration/core-ingress.d.ts
import type { NormalizedInboundTurn } from "./contracts";

export declare function prepareExecution(input: {
    operation: OperationLifecycle;
    authorizationDecision: AuthorizationDecision;
    authorizationContext: AuthorizationContext;
    adapter: ExecutionAdapter;
    effect: ExecutionEffectInput;
    freshnessAuthority?: ExecutionFreshnessAuthority;
}): ExecutionContext | null;

export declare function recoveryClaimBinding(value: unknown): {
    subjectDigest: string;
    attributesDigest: string;
} | null;

// referent.d.ts
import { type CanonicalIngressSubmission } from "./integration/ingress-contract";
import { type ReferentTraceRecord } from "./integration/trace-hooks";

export declare function recoveryContextBinding(value: unknown): RecoveryContext | null;

export declare function registerAuthorizationAuthority(input: {
    authorityIdentity: string;
    evaluate: (request: AuthorizationAuthorityRequest) => AuthorizationAuthorityResult;
}): AuthorizationAuthority | null;

export declare function registerDurabilityRecoveryAuthority(input: DurabilityRecoveryAuthority): DurabilityRecoveryAuthority | null;

export declare function registerEffectVerifier(input: EffectVerifier): EffectVerifier | null;

export declare function registerExecutionAdapter(input: ExecutionAdapter): ExecutionAdapter | null;

export declare function registerExecutionFreshnessAuthority(input: ExecutionFreshnessAuthority): ExecutionFreshnessAuthority | null;

export declare function requestConfirmation(input: {
    operation: OperationLifecycle;
    acceptedAffirmatives: readonly string[];
}): ConfirmationContext | null;

export declare function requireClarification(input: {
    proposal: OperationProposal;
    evidence: readonly EvidenceDiscriminator[];
    resolution: ReferentResolution;
}): ClarificationState;

export declare function resolveClarification(input: {
    state: ClarificationState;
    clarification: ClarificationEvidence;
    candidateSet: ReferentCandidateSet;
}): ClarificationResolution;

// supersession.d.ts
import { type ReferentTraceRecord } from "./integration/trace-hooks";
import { type EvidenceDiscriminator, type GroundedOperation } from "./referent";

export declare function resolveConfirmationTarget(input: {
    contexts: readonly ConfirmationContext[];
    evidence: RequesterEvidenceProof;
    sourceSpan: {
        start: number;
        end: number;
    };
}): ConfirmationTargetResolution;

export declare function resolveReferent(input: {
    proposal: OperationProposal;
    candidateSet: ReferentCandidateSet;
    evidence: readonly EvidenceDiscriminator[];
}): ReferentResolution;

export declare function resolveSupersessionTarget(input: {
    correction: CorrectionEvidence;
    candidates: readonly OperationLifecycle[];
    replacement: OperationLifecycle;
}): SupersessionTargetResolution;

export declare function runCoreConformance(subject: ConformanceSubject): Promise<ConformanceReport>;

// core-dist/index.d.ts

export declare function runWithDispatchPath<R>(path: DispatchPath, fn: () => R): R;
type AnyFn = (...args: any[]) => Promise<unknown>;

export declare function supersedeOperation(input: {
    target: SupersessionTargetResolution;
}): SupersessionResult;

export declare function validateAuthorizationDecision(decision: unknown, operation: unknown, expectedContext: unknown): boolean;

// claim-permission.d.ts
import { type ReferentTraceRecord } from "./integration/trace-hooks";

export declare function validateClaimPermission(permission: unknown, proposalInput: unknown): boolean;

// confirmation.d.ts
import { type ReferentTraceRecord } from "./integration/trace-hooks";
import { type RequesterEvidenceProof } from "./referent";
import { type OperationLifecycle } from "./supersession";

export declare function validateConfirmationDecision(decision: unknown, operation: unknown): boolean;

// core-dist/conformance.d.ts
import { type BackendActionDescriptor, type FrontendAdapterManifest, type OutcomeClass } from "../integration/contracts";
import { type CanonicalIngressSubmission, type FrontendCapabilityProfile } from "../integration/ingress-contract";

export declare function validateEffectResolution(resolution: unknown, effectIdentity: unknown, executionContext: unknown): boolean;

export declare function validateEvidenceDiscriminator(evidence: readonly EvidenceDiscriminator[]): EvidenceBindingValidation;

export declare function validateExecutionAttempt(attempt: unknown, context: unknown): boolean;

// index.d.ts

export declare function validateRecoveryContext(value: unknown): value is RecoveryContext;

export declare function validateReferentCandidateSet(candidateSet: ReferentCandidateSet): CandidateSetValidation;

export declare function verifyEffect(input: {
    executionContext: unknown;
    attempt: unknown;
} | {
    recoveryContext: unknown;
}): Promise<EffectResolution | null>;

export interface AuthorizationActorContext {
    actorRef: string;
    assurance: string;
    securityDomainRef: string;
    subjectRef?: string;
    resourceRef: string;
    
    attributes?: Readonly<Record<string, string>>;
}

export interface AuthorizationAuthority {
    authorityIdentity: string;
}

export interface AuthorizationAuthorityRequest {
    requestId: string;
    operationIdentity: string;
    operationId: string;
    actor: Readonly<AuthorizationActorContext>;
    target: Readonly<AuthorizationTarget>;
    confirmationRequirement: ConfirmationRequirement;
    confirmationDecisionId: string | null;
}

export interface AuthorizationAuthorityResult {
    decision: AuthorizationDecisionStatus;
    policyObservationRef?: string | null;
    stateObservationRef?: string | null;
    factDigest?: string | null;
    
    authorityReasonRef?: string | null;
}

export interface AuthorizationContext {
    authorizationContextId: string;
    operationIdentity: string;
    operation: OperationLifecycle;
    authorityIdentity: string;
    actor: Readonly<AuthorizationActorContext>;
    target: Readonly<AuthorizationTarget>;
    confirmationRequirement: ConfirmationRequirement;
    confirmationDecisionId: string | null;
    trace: readonly ReferentTraceRecord[];
}

export interface AuthorizationDecision {
    authorizationDecisionId: string;
    authorizationContextId: string;
    operationIdentity: string;
    authorityIdentity: string;
    decision: AuthorizationDecisionStatus;
    reason: AuthorizationReason;
    policyObservationRef: string | null;
    stateObservationRef: string | null;
    factDigest: string | null;
    trace: readonly ReferentTraceRecord[];
}

export interface AuthorizationTarget {
    resourceRef: string;
    securityDomainRef: string;
    subjectRef?: string;
}

export interface BackendActionDescriptor {
    capabilityRef: CapabilityRef;
    provider: string;
    inputFields: Record<string, string>;
    effectFields: string[];
    outcomeMapping: Record<string, OutcomeClass>;
    minAssurance: string;
    compensationRef: string | null;
    credentialSeam: string;
    useRestriction?: string;
}

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

export interface CandidateSetValidation {
    valid: boolean;
    reasons: string[];
}

export interface CanonicalIngressAcceptance {
    accepted: boolean;
    reasons: string[];
    
    groundingAdmissible: boolean;
    
    canonicalKeyDigest: string | null;
}

export interface CanonicalIngressSubmission {
    turn: NormalizedInboundTurn;
    capabilityProfile: FrontendCapabilityProfile;
    participant?: ParticipantContext;
    aiProposals?: ExternalAiProposal[];
    
    capturedAt?: Date;
}

export interface CapabilityExecutorSlot {
    register(fn: AnyFn): void;
    has(): boolean;
    
    invoke(...args: unknown[]): Promise<unknown>;
    
    __resetForTests(): void;
}

export interface CapabilityRef {
    capabilityId: string;
    majorVersion: number;
}

export interface ClaimEvidence {
    effectResolution?: unknown;
    executionContext?: unknown;
    recoveryContext?: unknown;
    executionAttempt?: unknown;
}

export interface ClaimPermission {
    permissionIdentity: string;
    claimIdentity: string;
    decision: ClaimDecisionStatus;
    reason: ClaimReason;
    claimType: ClaimType;
    effectIdentity: string | null;
    executionIdentity: string | null;
    subjectRef: string;
    scope: ClaimScope;
    polarity: ClaimPolarity;
    attributesDigest: string;
    evidenceRefs: readonly string[];
    trace: readonly ReferentTraceRecord[];
}

export interface ClarificationEvidence {
    clarificationId: string;
    evidence: EvidenceDiscriminator;
}

export interface ClarificationRequest {
    clarificationId: string;
    operationId: string;
    reason: "ambiguous" | "unresolved";
    candidateRefs: readonly ReferentRef[];
    observationRef: string | null;
}

export interface ClarificationResolution {
    accepted: boolean;
    state: ClarificationState;
    grounding: ReferentResolution;
    trace: readonly ReferentTraceRecord[];
    reason?: "wrong_clarification_id" | "already_resolved" | "invalid_candidate_set" | "invalid_evidence" | "invalid_state" | "operation_superseded";
}

export interface ClarificationResponseContext {
    responseIdentity: string;
    clarificationId: string;
    operationId: string;
    evidenceIdentity: string;
}

export interface ClarificationState {
    request: ClarificationRequest;
    status: "pending" | "resolved";
    proposal: OperationProposal;
    evidence: readonly EvidenceDiscriminator[];
    groundedReferent: ReferentRef | null;
    trace: readonly ReferentTraceRecord[];
}

export interface ConfirmationContext {
    confirmationContextId: string;
    operationIdentity: string;
    operation: OperationLifecycle;
    acceptedAffirmatives: readonly string[];
    issuedEvidenceSequence: number;
    status: ConfirmationContextStatus;
    trace: readonly ReferentTraceRecord[];
}

export interface ConfirmationDecision {
    confirmationDecisionId: string;
    confirmationContextId: string;
    operationIdentity: string;
    evidenceIdentity: string;
    status: "confirmed";
    trace: readonly ReferentTraceRecord[];
}

export interface ConfirmationEvidence {
    semantic: "affirmative";
    evidence: RequesterEvidenceProof;
    sourceSpan: {
        start: number;
        end: number;
    };
    normalizedValue: string;
}

export interface ConfirmationResponseBinding {
    responseBindingId: string;
    confirmationContextId: string;
    operationIdentity: string;
    evidenceIdentity: string;
    evidence: ConfirmationEvidence;
    targetResolution: ConfirmationTargetResolution;
    trace: readonly ReferentTraceRecord[];
}

export interface ConfirmationResult {
    accepted: boolean;
    decision: ConfirmationDecision | null;
    reason: ConfirmationResultReason;
    trace: readonly ReferentTraceRecord[];
}

export interface ConfirmationTargetResolution {
    status: ConfirmationTargetStatus;
    target: ConfirmationContext | null;
    evidence: ConfirmationEvidence | null;
    candidateContexts: readonly ConfirmationContext[];
    trace: readonly ReferentTraceRecord[];
    reason: string;
}

export interface ConformanceCheckResult {
    check: CoreConformanceCheck;
    passed: boolean;
    
    details: string[];
}

export interface ConformanceReport {
    contract: "core-conformance/1";
    passed: boolean;
    results: ConformanceCheckResult[];
    
    reportDigest: string;
}

export interface ConformanceSubject {
    frontend: {
        manifest: FrontendAdapterManifest;
        profile: FrontendCapabilityProfile;
        
        makeSubmission(seed: {
            key: string;
            text: string;
        }): CanonicalIngressSubmission;
    };
    action: {
        descriptor: BackendActionDescriptor;
        
        execute(input: Record<string, unknown>): Promise<{
            nativeOutcome: string;
            effectFields: Record<string, unknown>;
        }>;
        
        sampleInput: Record<string, unknown>;
    };
    
    referenceDescriptor?: BackendActionDescriptor;
}

export interface CorrectionEvidence {
    correctionIdentity: string;
    predecessorEvidence: readonly EvidenceDiscriminator[];
    replacementEvidence: readonly EvidenceDiscriminator[];
    evidenceRefs: readonly string[];
}

export interface DurabilityRecoveryAuthority {
    authorityIdentity: string;
    capability: DurabilityRecoveryCapability;
    recover(request: DurabilityRecoveryRequest): Promise<unknown>;
}

export interface DurabilityRecoveryProof {
    accepted: true;
    tenantScope: string;
    executionIdentity: string;
    effectIdentity: string;
    attemptIdentity: string;
    operationIdentity: string;
    subjectDigest: string;
    attributesDigest: string;
    adapterIdentity: string;
    capability: CapabilityRef;
    verifierIdentity: string;
    convergence: "NOT_SUPPORTED";
    boundary: "CROSSED" | "POSSIBLY_CROSSED";
    issuingCoreVersion: string;
    artifactSchemaVersion: string;
    canonicalizationVersion: string;
    configurationDigest: string;
    durableRevision: number;
    durableSequence: number;
    acceptedLedgerRef: string;
    proofDigest: string;
}

export interface DurabilityRecoveryRequest {
    recoveryRequestIdentity: string;
    tenantScope: string;
    executionIdentity: string;
    effectIdentity: string;
    attemptIdentity: string;
    operationIdentity: string;
    subjectDigest: string;
    attributesDigest: string;
    adapterIdentity: string;
    capability: CapabilityRef;
    verifierIdentity: string;
    convergence: "NOT_SUPPORTED";
    issuingCoreVersion: string;
    artifactSchemaVersion: string;
    canonicalizationVersion: string;
    configurationDigest: string;
}

export interface EffectIdentityInput {
    
    capability: string;
    
    authoritySurrogate: string;
    
    resolvedReferentIds: Record<string, unknown>;
    
    effectFields: Record<string, unknown>;
}

export interface EffectResolution {
    resolutionIdentity: string;
    status: EffectResolutionStatus;
    reason: EffectResolutionReason;
    effectIdentity: string;
    executionIdentity: string;
    executionContextId: string;
    operationIdentity: string;
    verifierIdentity: string | null;
    capability: CapabilityRef;
    observationRef: string | null;
    observationVersion: string | null;
    stateDigest: string | null;
    finalityRef: string | null;
    verificationAttemptIdentity: string;
    trace: readonly ReferentTraceRecord[];
}

export interface EffectTraceRecord {
    contract: typeof CORE_TRACE_CONTRACT;
    stage: "effect";
    
    capability: string;
    
    effectKeyDigest: string;
    authoritySurrogateDigest: string;
    
    outcomeClass: string;
    
    evidenceKeyDigests: string[];
}

export interface EffectVerifier {
    verifierIdentity: string;
    capability: CapabilityRef;
    verify(request: EffectVerifierRequest): Promise<unknown>;
}

export interface EffectVerifierRequest {
    verificationAttemptIdentity: string;
    effectIdentity: string;
    executionIdentity: string;
    executionContextId: string;
    operationIdentity: string;
    capability: CapabilityRef;
    attemptIdentity: string;
    attemptOutcome: "ACKNOWLEDGED" | "UNKNOWN";
}

export interface EvidenceBindingValidation {
    valid: boolean;
    reasons: string[];
}

export interface EvidenceDiscriminator {
    bindingIdentity: string;
    evidenceIdentity: string;
    key: string;
    value: string;
    sourceSpan: {
        start: number;
        end: number;
    };
    clarificationResponseIdentity?: string;
}

export interface ExecutionAdapter {
    adapterIdentity: string;
    capability: CapabilityRef;
    effectIdentityConvergence: EffectIdentityConvergence;
    acknowledgementSemantics: "APPARENT";
    invoke(request: ExecutionAdapterRequest): Promise<unknown>;
}

export interface ExecutionAdapterRequest {
    executionIdentity: string;
    attemptIdentity: string;
    effectIdentity: string;
    operationIdentity: string;
    capability: CapabilityRef;
}

export interface ExecutionAttempt {
    attemptIdentity: string;
    executionIdentity: string;
    effectIdentity: string;
    executionContextId: string;
    adapterIdentity: string;
    outcome: ExecutionAttemptOutcome;
    retryable: boolean;
    providerReference: string | null;
    freshnessObservationRef: string | null;
    trace: readonly ReferentTraceRecord[];
}

export interface ExecutionContext {
    executionContextId: string;
    executionIdentity: string;
    effectIdentity: string;
    operationIdentity: string;
    operation: OperationLifecycle;
    authorizationDecisionId: string;
    authorizationContextId: string;
    adapterIdentity: string;
    capability: CapabilityRef;
    freshnessObservationRef: string | null;
    trace: readonly ReferentTraceRecord[];
}

export interface ExecutionDispatchResult {
    executionContext: ExecutionContext | null;
    attempt: ExecutionAttempt | null;
    outcome: ExecutionAttemptOutcome;
    reason: ExecutionReason;
    duplicate: boolean;
}

export interface ExecutionEffectInput {
    capability: string;
    resolvedReferentIds: Record<string, unknown>;
    effectFields: Record<string, unknown>;
}

export interface ExecutionFreshnessAuthority {
    authorityIdentity: string;
    evaluate(request: ExecutionFreshnessAuthorityRequest): ExecutionFreshnessResult | Promise<ExecutionFreshnessResult>;
}

export interface ExecutionFreshnessAuthorityRequest {
    executionContextId: string;
    executionIdentity: string;
    operationIdentity: string;
    effectIdentity: string;
}

export interface ExecutionFreshnessResult {
    status: "CURRENT" | "STALE" | "INDETERMINATE";
    observationRef?: string | null;
}

export interface ExternalAiProposal {
    interpretation: string;
    claimedSourceSpan?: string;
    model: string;
    mediationRef?: string;
}

export interface FrontendAdapterManifest {
    capabilityRef: CapabilityRef;
    provider: string;
    modality: string;
    delivery: string;
    supportsHumanStructured: boolean;
    routingFactKinds: string[];
    deliveryIdempotency: {
        keyKind: string;
    };
    deliveryReceipts: {
        supported: boolean;
        kinds: ("delivered" | "failed")[];
    };
    assuranceLevels: string[];
}

export interface FrontendCapabilityProfile {
    declared: FrontendCapability[];
}

export interface GroundedOperation {
    operationId: string;
    capability: string;
    referent: ReferentRef;
    evidenceRefs: readonly string[];
    observationRef: string;
    grounding: "grounded";
    
    executionEligibility: "not_evaluated";
    trace: readonly ReferentTraceRecord[];
    groundingEvidence: readonly EvidenceDiscriminator[];
}

export interface GroundedReferentResolution extends ReferentResolutionBase {
    status: "grounded";
    referent: ReferentRef;
    candidate: CandidateReferent;
}

export interface GroundingDecision {
    resolution: ReferentResolution;
    groundingBlocked: boolean;
}

export interface IngressAcceptance {
    accepted: boolean;
    reasons: string[];
}

export interface IngressTraceRecord {
    contract: typeof CORE_TRACE_CONTRACT;
    stage: "ingress";
    
    canonicalKeyDigest: string | null;
    accepted: boolean;
    groundingAdmissible: boolean;
    
    provenance: Record<string, unknown>;
}

export interface NonGroundedReferentResolution extends ReferentResolutionBase {
    status: "ambiguous" | "unresolved" | "invalid";
}

export interface NormalizedInboundTurn {
    provider: string;
    providerRef: string;
    routingFacts: Record<string, string>;
    evidenceClass: {
        kind: string;
        captureQuality: string;
    };
    payload: Record<string, unknown>;
    idempotencyKey: {
        provider: string;
        key: string;
    };
    receivedAt: Date;
}

export interface OperationLifecycle {
    operationIdentity: string;
    groundedOperation: GroundedOperation;
    groundingEvidence: readonly EvidenceDiscriminator[];
    lifecycleState: OperationLifecycleState;
    supersededBy: string | null;
    predecessor: string | null;
    trace: readonly ReferentTraceRecord[];
}

export interface OperationProposal {
    operationId: string;
    correlationId?: string;
    capability: string;
    proposalSource: "model" | "application";
    evidenceRefs: readonly string[];
    referentHint?: ReferentRef;
    effectContext?: Readonly<Record<string, unknown>>;
}

export interface ParticipantContext {
    actorRef: string;
    assurance?: string;
}

export interface RecoveryContext {
    recoveryContextIdentity: string;
    tenantScope: string;
    executionIdentity: string;
    effectIdentity: string;
    attemptIdentity: string;
    operationIdentity: string;
    subjectDigest: string;
    attributesDigest: string;
    adapterIdentity: string;
    capability: CapabilityRef;
    verifierIdentity: string;
    convergence: "NOT_SUPPORTED";
    boundary: "CROSSED" | "POSSIBLY_CROSSED";
    authorityIdentity: string;
    acceptedLedgerRef: string;
    durableRevision: number;
    durableSequence: number;
    issuingCoreVersion: string;
    artifactSchemaVersion: string;
    canonicalizationVersion: string;
    configurationDigest: string;
    reconciliationOnly: true;
}

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

export interface ReferentResolutionBase {
    status: GroundingStatus;
    operationId: string;
    observationRef: string | null;
    admissibleCandidates: readonly CandidateReferent[];
    evidenceRefs: readonly string[];
    reason: string;
    trace: readonly ReferentTraceRecord[];
    groundingEvidence: readonly EvidenceDiscriminator[];
}

export interface ReferentTraceRecord {
    contract: typeof CORE_TRACE_CONTRACT;
    stage: "referent";
    event: ReferentTraceEvent;
    correlationId: string;
    operationId: string;
    clarificationId: string | null;
    observationRef: string | null;
    candidateRefDigests: string[];
    evidenceRefs: string[];
    referentDigest: string | null;
    predecessorOperationIdentity?: string;
    replacementOperationIdentity?: string;
}

export interface RequesterEvidenceProof {
    evidenceIdentity: string;
    canonicalKeyDigest: string;
    evidenceKind: "human_verbatim";
}

export interface SupersessionDecision {
    decisionIdentity: string;
    predecessor: OperationLifecycle;
    replacement: OperationLifecycle;
    correction: CorrectionEvidence;
    trace: readonly ReferentTraceRecord[];
}

export interface SupersessionResult {
    accepted: boolean;
    predecessor: OperationLifecycle;
    replacement: OperationLifecycle;
    decision: SupersessionDecision | null;
    trace: readonly ReferentTraceRecord[];
    reason: "superseded" | "target_ambiguous" | "target_unresolved" | "invalid" | "already_superseded";
}

export interface SupersessionTargetResolution {
    status: SupersessionTargetStatus;
    correction: CorrectionEvidence;
    target: OperationLifecycle | null;
    replacement: OperationLifecycle;
    candidates: readonly OperationLifecycle[];
    trace: readonly ReferentTraceRecord[];
    reason: string;
}

export interface TraceCorrelation {
    
    chains: {
        effect: EffectTraceRecord;
        evidence: IngressTraceRecord[];
        
        fullyGrounded: boolean;
    }[];
    
    unconsumedEvidence: IngressTraceRecord[];
    
    lifecycle?: ReferentTraceRecord[];
    
    correlationDigest: string;
}

export type AdapterDispatchBoundary = "not_crossed" | "crossed";

export type AuthorizationDecisionStatus = "PERMIT" | "DENY" | "INDETERMINATE";

export type AuthorizationReason = "POLICY_PERMITTED" | "POLICY_DENIED" | "POLICY_UNAVAILABLE" | "AUTHORITY_UNAVAILABLE" | "AUTHORITY_ERROR" | "INVALID_AUTHORITY_RESULT" | "CONFIRMATION_REQUIRED" | "OPERATION_NOT_ACTIONABLE" | "CONTEXT_INVALID";

export type ClaimDecisionStatus = (typeof CLAIM_DECISIONS)[number];

export type ClaimPolarity = (typeof CLAIM_POLARITIES)[number];

export type ClaimProposal = (ClaimProposalBase & {
    claimType: "EFFECT_COMMITTED" | "EFFECT_DISPROVED" | "EFFECT_UNKNOWN";
    effectIdentity: string;
    executionIdentity: string;
    scope: "historical_effect";
}) | (ClaimProposalBase & {
    claimType: "EXECUTION_ATTEMPTED";
    effectIdentity: string;
    executionIdentity: string;
    scope: "attempt_status";
});

export type ClaimReason = (typeof CLAIM_REASONS)[number];

export type ClaimScalar = string | number | boolean | null;
interface ClaimProposalBase {
    claimType: ClaimType;
    effectIdentity?: string | null;
    executionIdentity: string;
    subjectRef: string;
    propositionRef?: string | null;
    polarity: ClaimPolarity;
    scope: ClaimScope;
    attributes: Record<string, ClaimScalar>;
    
    displayText?: string | null;
    
    permitted?: unknown;
    verified?: unknown;
    modelConfident?: unknown;
}

export type ClaimScope = (typeof CLAIM_SCOPES)[number];

export type ClaimType = (typeof CLAIM_TYPES)[number];

export type ConfirmationContextStatus = "pending" | "consumed" | "invalidated";

export type ConfirmationRequirement = "NONE" | "AFFIRMATIVE_REQUIRED";

export type ConfirmationResultReason = "confirmed" | "invalid" | "context_invalidated" | "context_consumed" | "operation_not_actionable" | "target_ambiguous" | "target_unresolved";

export type ConfirmationTargetStatus = "resolved" | "ambiguous" | "unresolved" | "invalid";

export type CoreConformanceCheck = (typeof CORE_CONFORMANCE_CHECKS)[number];

export type CoreTraceRecord = IngressTraceRecord | EffectTraceRecord | ReferentTraceRecord;

export type DispatchPath = (typeof DISPATCH_PATHS)[number];

export type DurabilityRecoveryCapability = (typeof DURABILITY_RECOVERY_CAPABILITIES)[number];

export type EffectIdentityConvergence = "SUPPORTED" | "NOT_SUPPORTED";

export type EffectResolutionReason = "EFFECT_PRESENT" | "EFFECT_ABSENT_FINAL" | "VERIFIER_UNAVAILABLE" | "VERIFIER_ERROR" | "INVALID_VERIFIER_RESULT" | "VERIFIER_INDETERMINATE" | "VERIFIER_CONFLICT" | "EFFECT_CONTEXT_INVALID" | "EFFECT_TERMINAL" | "EFFECT_VERIFICATION_IN_FLIGHT";

export type EffectResolutionStatus = "COMMITTED" | "DISPROVED" | "UNKNOWN";

export type EffectVerificationResultStatus = "PRESENT" | "ABSENT_FINAL" | "INDETERMINATE" | "CONFLICT";

export type EffectVerifierResult = {
    status: "PRESENT";
    observationRef: string;
    observationVersion?: string | null;
    stateDigest?: string | null;
} | {
    status: "ABSENT_FINAL";
    observationRef: string;
    finalityRef: string;
    observationVersion?: string | null;
    stateDigest?: string | null;
} | {
    status: "INDETERMINATE";
    observationRef?: string | null;
    observationVersion?: string | null;
    stateDigest?: string | null;
    reason?: "VERIFIER_UNAVAILABLE" | "VERIFIER_INDETERMINATE";
} | {
    status: "CONFLICT";
    observationRef?: string | null;
    observationVersion?: string | null;
    stateDigest?: string | null;
    reason?: "VERIFIER_CONFLICT";
};

export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];

export type ExecutionAdapterResult = {
    status: "acknowledged";
    dispatchBoundary: "crossed";
    providerReference?: string | null;
} | {
    status: "failed";
    dispatchBoundary: "not_crossed";
    retryable: boolean;
    code?: string | null;
} | {
    status: "unknown";
    dispatchBoundary: "crossed";
    code?: string | null;
};

export type ExecutionAttemptOutcome = "NOT_STARTED" | "IN_FLIGHT" | "ACKNOWLEDGED" | "FAILED" | "UNKNOWN";

export type ExecutionReason = "PREPARED" | "ADAPTER_ACKNOWLEDGED" | "AUTHORIZATION_INVALID" | "OPERATION_NOT_ACTIONABLE" | "ADAPTER_UNAVAILABLE" | "CAPABILITY_MISMATCH" | "FRESHNESS_STALE" | "FRESHNESS_INDETERMINATE" | "ADAPTER_REJECTED" | "ADAPTER_UNAVAILABLE_RESULT" | "MALFORMED_ADAPTER_RESULT" | "DISPATCH_UNKNOWN" | "ALREADY_DISPATCHED" | "RETRY_CONVERGENCE_UNSUPPORTED" | "CONTEXT_INVALID";

export type FrontendCapability = (typeof FRONTEND_CAPABILITIES)[number];

export type GroundingStatus = "grounded" | "ambiguous" | "unresolved" | "invalid";

export type OperationLifecycleState = "current" | "superseded";

export type OutcomeClass = "succeeded" | "rejected_invalid_input" | "rejected_policy" | "duplicate_suppressed" | "provider_unavailable" | "provider_fault" | "unknown_commit";

export type ReferentRef = string;

export type ReferentResolution = GroundedReferentResolution | NonGroundedReferentResolution;

export type ReferentTraceEvent = (typeof REFERENT_TRACE_EVENTS)[number] | (typeof SUPERSESSION_TRACE_EVENTS)[number] | (typeof CONFIRMATION_TRACE_EVENTS)[number] | (typeof AUTHORIZATION_TRACE_EVENTS)[number] | (typeof EXECUTION_TRACE_EVENTS)[number] | (typeof EFFECT_RESOLUTION_TRACE_EVENTS)[number] | (typeof CLAIM_TRACE_EVENTS)[number];

export type SupersessionTargetStatus = "target_grounded" | "target_ambiguous" | "target_unresolved" | "invalid";