@codesoul-co/hypha-core / contracts/execution-store

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/contracts/execution-store.ts
• Exports: 16

Using this module

Use the Execution store module for declaring and runtime-validating contracts. It exports 14 interfaces, 2 types.

Import from the package entrypoint

import type {
  ExecutionIdempotencyQuery,
  ExecutionLease,
  ExecutionLeaseAcquireRequest,
  ExecutionLeaseGuard,
  ExecutionLeaseReleaseRequest,
  ExecutionLeaseRenewRequest,
  ExecutionRecord,
  ExecutionRecordCompareAndSetRequest,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 16 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.

Public exports

Symbol	Kind	Signature	Description
ExecutionIdempotencyQuery	interface	interface ExecutionIdempotencyQuery	Execution Idempotency Query interface with 5 public fields or methods.
ExecutionLease	interface	interface ExecutionLease	Execution Lease interface with 7 public fields or methods.
ExecutionLeaseAcquireRequest	interface	interface ExecutionLeaseAcquireRequest	Execution Lease Acquire Request interface with 8 public fields or methods.
ExecutionLeaseGuard	interface	interface ExecutionLeaseGuard	Execution Lease Guard interface with 3 public fields or methods.
ExecutionLeaseReleaseRequest	interface	interface ExecutionLeaseReleaseRequest	Execution Lease Release Request interface with 7 public fields or methods.
ExecutionLeaseRenewRequest	interface	interface ExecutionLeaseRenewRequest	Execution Lease Renew Request interface with 7 public fields or methods.
ExecutionRecord	interface	interface ExecutionRecord	Execution Record interface with 14 public fields or methods.
ExecutionRecordCompareAndSetRequest	interface	interface ExecutionRecordCompareAndSetRequest	Execution Record Compare And Set Request interface with 6 public fields or methods.
ExecutionRecordCreateRequest	interface	interface ExecutionRecordCreateRequest	Execution Record Create Request interface with 3 public fields or methods.
ExecutionRecordPage	interface	interface ExecutionRecordPage	Execution Record Page interface with 2 public fields or methods.
ExecutionRecordQuery	interface	interface ExecutionRecordQuery	Execution Record Query interface with 10 public fields or methods.
ExecutionRecoveryAssessment	interface	interface ExecutionRecoveryAssessment	Execution Recovery Assessment interface with 6 public fields or methods.
ExecutionStore	interface	interface ExecutionStore	Execution Store interface with 10 public fields or methods.
ExecutionStoreFactory	interface	interface ExecutionStoreFactory	Execution Store Factory interface with 2 public fields or methods.
ExecutionIdempotencyResolution	type	type ExecutionIdempotencyResolution = { status: 'miss'; } | { status: 'match'; record: ExecutionRecord; } | { status: 'conflict'; recordId: string; existingFingerprint: string; }	Public type alias for Execution Idempotency Resolution; the declaration contains its complete type expression.
ExecutionRecoveryDisposition	type	type ExecutionRecoveryDisposition = 'not_started' | 'provider_queryable' | 'provider_completed_result_missing' | 'provider_state_unknown'	Public type alias for Execution Recovery Disposition; the declaration contains its complete type expression.

ExecutionIdempotencyQuery

Execution Idempotency Query interface with 5 public fields or methods.

• Kind: interface
• Import: import type { ExecutionIdempotencyQuery } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionIdempotencyQuery {
    tenantId?: string;
    userId: string;
    workspaceId: string;
    idempotencyKey: string;
    fingerprint: string;
}

Contract members

Member	Kind	Signature	Description
fingerprint	property	fingerprint: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLease

Execution Lease interface with 7 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLease } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionLease {
    id: string;
    executionId: string;
    ownerId: string;
    fencingToken: number;
    acquiredAt: string;
    expiresAt: string;
    heartbeatAt: string;
}

Contract members

Member	Kind	Signature	Description
acquiredAt	property	acquiredAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expiresAt	property	expiresAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
fencingToken	property	fencingToken: number	Public property; its type, readonly modifier and optionality are shown in the signature.
heartbeatAt	property	heartbeatAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
ownerId	property	ownerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLeaseAcquireRequest

Execution Lease Acquire Request interface with 8 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLeaseAcquireRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionLeaseAcquireRequest {
    operationId: string;
    executionId: string;
    expectedRevision: number;
    requestedLeaseId: string;
    ownerId: string;
    ttlMs: number;
    acquiredAt: string;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
acquiredAt	property	acquiredAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
ownerId	property	ownerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requestedLeaseId	property	requestedLeaseId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
ttlMs	property	ttlMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLeaseGuard

Execution Lease Guard interface with 3 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLeaseGuard } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionLeaseGuard {
    leaseId: string;
    ownerId: string;
    fencingToken: number;
}

Contract members

Member	Kind	Signature	Description
fencingToken	property	fencingToken: number	Public property; its type, readonly modifier and optionality are shown in the signature.
leaseId	property	leaseId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
ownerId	property	ownerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLeaseReleaseRequest

Execution Lease Release Request interface with 7 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLeaseReleaseRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionLeaseReleaseRequest {
    operationId: string;
    executionId: string;
    expectedRevision: number;
    leaseGuard: ExecutionLeaseGuard;
    releasedAt: string;
    reason?: string;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
leaseGuard	property	leaseGuard: ExecutionLeaseGuard	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
releasedAt	property	releasedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLeaseRenewRequest

Execution Lease Renew Request interface with 7 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLeaseRenewRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionLeaseRenewRequest {
    operationId: string;
    executionId: string;
    expectedRevision: number;
    leaseGuard: ExecutionLeaseGuard;
    ttlMs: number;
    heartbeatAt: string;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
heartbeatAt	property	heartbeatAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
leaseGuard	property	leaseGuard: ExecutionLeaseGuard	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
ttlMs	property	ttlMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecord

Execution Record interface with 14 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecord } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecord {
    id: string;
    revision: number;
    request: CommandExecutionRequest;
    status: CommandExecutionStatus;
    providerId: string;
    providerExecutionRef?: string;
    sandboxId?: string;
    attempt: number;
    idempotencyFingerprint?: string;
    /**
     * Immutable Provider terminal evidence persisted before Artifact finalization and terminal CAS.
     * Once present, Store implementations must reject removal or replacement.
     */
    terminalReceipt?: ExecutionReceipt;
    result?: CommandExecutionResult;
    lease?: ExecutionLease;
    createdAt: string;
    updatedAt: string;
}

Contract members

Member	Kind	Signature	Description
attempt	property	attempt: number	Public property; its type, readonly modifier and optionality are shown in the signature.
createdAt	property	createdAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyFingerprint	property	idempotencyFingerprint?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
lease	property	lease?: ExecutionLease	Public property; its type, readonly modifier and optionality are shown in the signature.
providerExecutionRef	property	providerExecutionRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
request	property	request: CommandExecutionRequest	Public property; its type, readonly modifier and optionality are shown in the signature.
result	property	result?: CommandExecutionResult	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: CommandExecutionStatus	Public property; its type, readonly modifier and optionality are shown in the signature.
terminalReceipt	property	terminalReceipt?: ExecutionReceipt	Immutable Provider terminal evidence persisted before Artifact finalization and terminal CAS. Once present, Store implementations must reject removal or replacement.
updatedAt	property	updatedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecordCompareAndSetRequest

Execution Record Compare And Set Request interface with 6 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecordCompareAndSetRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecordCompareAndSetRequest {
    operationId: string;
    executionId: string;
    expectedRevision: number;
    leaseGuard?: ExecutionLeaseGuard;
    next: ExecutionRecord;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
leaseGuard	property	leaseGuard?: ExecutionLeaseGuard	Public property; its type, readonly modifier and optionality are shown in the signature.
next	property	next: ExecutionRecord	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecordCreateRequest

Execution Record Create Request interface with 3 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecordCreateRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecordCreateRequest {
    operationId: string;
    record: ExecutionRecord;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
record	property	record: ExecutionRecord	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecordPage

Execution Record Page interface with 2 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecordPage } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecordPage {
    records: ExecutionRecord[];
    cursor?: string;
}

Contract members

Member	Kind	Signature	Description
cursor	property	cursor?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
records	property	records: ExecutionRecord[]	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecordQuery

Execution Record Query interface with 10 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecordQuery } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecordQuery {
    tenantId?: string;
    userId?: string;
    workspaceId?: string;
    runId?: string;
    providerId?: string;
    statuses?: CommandExecutionStatus[];
    leaseExpiresBefore?: string;
    updatedBefore?: string;
    limit?: number;
    cursor?: string;
}

Contract members

Member	Kind	Signature	Description
cursor	property	cursor?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
leaseExpiresBefore	property	leaseExpiresBefore?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
limit	property	limit?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
runId	property	runId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
statuses	property	statuses?: CommandExecutionStatus[]	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
updatedBefore	property	updatedBefore?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionRecoveryAssessment

Execution Recovery Assessment interface with 6 public fields or methods.

• Kind: interface
• Import: import type { ExecutionRecoveryAssessment } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionRecoveryAssessment {
    executionId: string;
    recordRevision: number;
    disposition: ExecutionRecoveryDisposition;
    assessedAt: string;
    providerStatusRef?: string;
    reason?: string;
}

Contract members

Member	Kind	Signature	Description
assessedAt	property	assessedAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
disposition	property	disposition: ExecutionRecoveryDisposition	Public property; its type, readonly modifier and optionality are shown in the signature.
executionId	property	executionId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerStatusRef	property	providerStatusRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
recordRevision	property	recordRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionStore

Execution Store interface with 10 public fields or methods.

• Kind: interface
• Import: import type { ExecutionStore } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionStore {
    create(request: ExecutionRecordCreateRequest): Promise<ExecutionRecord>;
    get(executionId: string): Promise<ExecutionRecord | null>;
    list(query?: ExecutionRecordQuery): Promise<ExecutionRecordPage>;
    resolveIdempotency(query: ExecutionIdempotencyQuery): Promise<ExecutionIdempotencyResolution>;
    compareAndSet(request: ExecutionRecordCompareAndSetRequest): Promise<ExecutionRecord>;
    acquireLease(request: ExecutionLeaseAcquireRequest): Promise<ExecutionRecord>;
    renewLease(request: ExecutionLeaseRenewRequest): Promise<ExecutionRecord>;
    releaseLease(request: ExecutionLeaseReleaseRequest): Promise<ExecutionRecord>;
    health(): Promise<ProviderHealth>;
    close?(): Promise<void>;
}

Contract members

Member	Kind	Signature	Description
acquireLease	method	acquireLease(request: ExecutionLeaseAcquireRequest): Promise<ExecutionRecord>	Public method; parameters and return type are shown in the signature.
close	method	close?(): Promise<void>	Public method; parameters and return type are shown in the signature.
compareAndSet	method	compareAndSet(request: ExecutionRecordCompareAndSetRequest): Promise<ExecutionRecord>	Public method; parameters and return type are shown in the signature.
create	method	create(request: ExecutionRecordCreateRequest): Promise<ExecutionRecord>	Public method; parameters and return type are shown in the signature.
get	method	get(executionId: string): Promise<ExecutionRecord | null>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
list	method	list(query?: ExecutionRecordQuery): Promise<ExecutionRecordPage>	Public method; parameters and return type are shown in the signature.
releaseLease	method	releaseLease(request: ExecutionLeaseReleaseRequest): Promise<ExecutionRecord>	Public method; parameters and return type are shown in the signature.
renewLease	method	renewLease(request: ExecutionLeaseRenewRequest): Promise<ExecutionRecord>	Public method; parameters and return type are shown in the signature.
resolveIdempotency	method	resolveIdempotency(query: ExecutionIdempotencyQuery): Promise<ExecutionIdempotencyResolution>	Public method; parameters and return type are shown in the signature.

ExecutionStoreFactory

Execution Store Factory interface with 2 public fields or methods.

• Kind: interface
• Import: import type { ExecutionStoreFactory } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export interface ExecutionStoreFactory {
    readonly storeId: string;
    create(): Promise<ExecutionStore>;
}

Contract members

Member	Kind	Signature	Description
create	method	create(): Promise<ExecutionStore>	Public method; parameters and return type are shown in the signature.
storeId	property	readonly storeId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionIdempotencyResolution

Public type alias for Execution Idempotency Resolution; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ExecutionIdempotencyResolution } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export type ExecutionIdempotencyResolution = {
    status: 'miss';
} | {
    status: 'match';
    record: ExecutionRecord;
} | {
    status: 'conflict';
    recordId: string;
    existingFingerprint: string;
};

ExecutionRecoveryDisposition

Public type alias for Execution Recovery Disposition; the declaration contains its complete type expression.

• Kind: type
• Import: import type { ExecutionRecoveryDisposition } from '@codesoul-co/hypha-core';
• Source module: contracts/execution-store

Declaration

export type ExecutionRecoveryDisposition = 'not_started' | 'provider_queryable' | 'provider_completed_result_missing' | 'provider_state_unknown';