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

• 包索引: @codesoul-co/hypha-core
• 源码: packages/core/src/contracts/execution-store.ts
• 导出数: 16

模块用法

用于声明并运行时校验契约。Execution store 模块公开 14 接口、2 类型。

从包入口导入

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

// 完整导出列表见下方。

使用要点

• 16 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用 import type，运行时不应依赖它们。

公共导出

Symbol	种类	签名	说明
ExecutionIdempotencyQuery	接口	interface ExecutionIdempotencyQuery	Execution Idempotency Query 接口，共包含 5 个公开字段或方法。
ExecutionLease	接口	interface ExecutionLease	Execution Lease 接口，共包含 7 个公开字段或方法。
ExecutionLeaseAcquireRequest	接口	interface ExecutionLeaseAcquireRequest	Execution Lease Acquire Request 接口，共包含 8 个公开字段或方法。
ExecutionLeaseGuard	接口	interface ExecutionLeaseGuard	Execution Lease Guard 接口，共包含 3 个公开字段或方法。
ExecutionLeaseReleaseRequest	接口	interface ExecutionLeaseReleaseRequest	Execution Lease Release Request 接口，共包含 7 个公开字段或方法。
ExecutionLeaseRenewRequest	接口	interface ExecutionLeaseRenewRequest	Execution Lease Renew Request 接口，共包含 7 个公开字段或方法。
ExecutionRecord	接口	interface ExecutionRecord	Execution Record 接口，共包含 14 个公开字段或方法。
ExecutionRecordCompareAndSetRequest	接口	interface ExecutionRecordCompareAndSetRequest	Execution Record Compare And Set Request 接口，共包含 6 个公开字段或方法。
ExecutionRecordCreateRequest	接口	interface ExecutionRecordCreateRequest	Execution Record Create Request 接口，共包含 3 个公开字段或方法。
ExecutionRecordPage	接口	interface ExecutionRecordPage	Execution Record Page 接口，共包含 2 个公开字段或方法。
ExecutionRecordQuery	接口	interface ExecutionRecordQuery	Execution Record Query 接口，共包含 10 个公开字段或方法。
ExecutionRecoveryAssessment	接口	interface ExecutionRecoveryAssessment	Execution Recovery Assessment 接口，共包含 6 个公开字段或方法。
ExecutionStore	接口	interface ExecutionStore	Execution Store 接口，共包含 10 个公开字段或方法。
ExecutionStoreFactory	接口	interface ExecutionStoreFactory	Execution Store Factory 接口，共包含 2 个公开字段或方法。
ExecutionIdempotencyResolution	类型	type ExecutionIdempotencyResolution = { status: 'miss'; } | { status: 'match'; record: ExecutionRecord; } | { status: 'conflict'; recordId: string; existingFingerprint: string; }	Execution Idempotency Resolution 公共类型别名；完整类型表达式见声明。
ExecutionRecoveryDisposition	类型	type ExecutionRecoveryDisposition = 'not_started' | 'provider_queryable' | 'provider_completed_result_missing' | 'provider_state_unknown'	Execution Recovery Disposition 公共类型别名；完整类型表达式见声明。

ExecutionIdempotencyQuery

Execution Idempotency Query 接口，共包含 5 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionIdempotencyQuery } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
fingerprint	属性	fingerprint: string	公开属性；类型、只读和可选状态以签名列为准。
idempotencyKey	属性	idempotencyKey: string	公开属性；类型、只读和可选状态以签名列为准。
tenantId	属性	tenantId?: string	公开属性；类型、只读和可选状态以签名列为准。
userId	属性	userId: string	公开属性；类型、只读和可选状态以签名列为准。
workspaceId	属性	workspaceId: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionLease

Execution Lease 接口，共包含 7 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionLease } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
acquiredAt	属性	acquiredAt: string	公开属性；类型、只读和可选状态以签名列为准。
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
expiresAt	属性	expiresAt: string	公开属性；类型、只读和可选状态以签名列为准。
fencingToken	属性	fencingToken: number	公开属性；类型、只读和可选状态以签名列为准。
heartbeatAt	属性	heartbeatAt: string	公开属性；类型、只读和可选状态以签名列为准。
id	属性	id: string	公开属性；类型、只读和可选状态以签名列为准。
ownerId	属性	ownerId: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionLeaseAcquireRequest

Execution Lease Acquire Request 接口，共包含 8 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionLeaseAcquireRequest } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
acquiredAt	属性	acquiredAt: string	公开属性；类型、只读和可选状态以签名列为准。
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
expectedRevision	属性	expectedRevision: number	公开属性；类型、只读和可选状态以签名列为准。
idempotencyKey	属性	idempotencyKey?: string	公开属性；类型、只读和可选状态以签名列为准。
operationId	属性	operationId: string	公开属性；类型、只读和可选状态以签名列为准。
ownerId	属性	ownerId: string	公开属性；类型、只读和可选状态以签名列为准。
requestedLeaseId	属性	requestedLeaseId: string	公开属性；类型、只读和可选状态以签名列为准。
ttlMs	属性	ttlMs: number	公开属性；类型、只读和可选状态以签名列为准。

ExecutionLeaseGuard

Execution Lease Guard 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionLeaseGuard } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
fencingToken	属性	fencingToken: number	公开属性；类型、只读和可选状态以签名列为准。
leaseId	属性	leaseId: string	公开属性；类型、只读和可选状态以签名列为准。
ownerId	属性	ownerId: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionLeaseReleaseRequest

Execution Lease Release Request 接口，共包含 7 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionLeaseReleaseRequest } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
expectedRevision	属性	expectedRevision: number	公开属性；类型、只读和可选状态以签名列为准。
idempotencyKey	属性	idempotencyKey?: string	公开属性；类型、只读和可选状态以签名列为准。
leaseGuard	属性	leaseGuard: ExecutionLeaseGuard	公开属性；类型、只读和可选状态以签名列为准。
operationId	属性	operationId: string	公开属性；类型、只读和可选状态以签名列为准。
reason	属性	reason?: string	公开属性；类型、只读和可选状态以签名列为准。
releasedAt	属性	releasedAt: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionLeaseRenewRequest

Execution Lease Renew Request 接口，共包含 7 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionLeaseRenewRequest } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
expectedRevision	属性	expectedRevision: number	公开属性；类型、只读和可选状态以签名列为准。
heartbeatAt	属性	heartbeatAt: string	公开属性；类型、只读和可选状态以签名列为准。
idempotencyKey	属性	idempotencyKey?: string	公开属性；类型、只读和可选状态以签名列为准。
leaseGuard	属性	leaseGuard: ExecutionLeaseGuard	公开属性；类型、只读和可选状态以签名列为准。
operationId	属性	operationId: string	公开属性；类型、只读和可选状态以签名列为准。
ttlMs	属性	ttlMs: number	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecord

Execution Record 接口，共包含 14 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecord } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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;
}

契约成员

成员	种类	签名	说明
attempt	属性	attempt: number	公开属性；类型、只读和可选状态以签名列为准。
createdAt	属性	createdAt: string	公开属性；类型、只读和可选状态以签名列为准。
id	属性	id: string	公开属性；类型、只读和可选状态以签名列为准。
idempotencyFingerprint	属性	idempotencyFingerprint?: string	公开属性；类型、只读和可选状态以签名列为准。
lease	属性	lease?: ExecutionLease	公开属性；类型、只读和可选状态以签名列为准。
providerExecutionRef	属性	providerExecutionRef?: string	公开属性；类型、只读和可选状态以签名列为准。
providerId	属性	providerId: string	公开属性；类型、只读和可选状态以签名列为准。
request	属性	request: CommandExecutionRequest	公开属性；类型、只读和可选状态以签名列为准。
result	属性	result?: CommandExecutionResult	公开属性；类型、只读和可选状态以签名列为准。
revision	属性	revision: number	公开属性；类型、只读和可选状态以签名列为准。
sandboxId	属性	sandboxId?: string	公开属性；类型、只读和可选状态以签名列为准。
status	属性	status: CommandExecutionStatus	公开属性；类型、只读和可选状态以签名列为准。
terminalReceipt	属性	terminalReceipt?: ExecutionReceipt	Immutable Provider terminal evidence persisted before Artifact finalization and terminal CAS. Once present, Store implementations must reject removal or replacement.
updatedAt	属性	updatedAt: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecordCompareAndSetRequest

Execution Record Compare And Set Request 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecordCompareAndSetRequest } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
expectedRevision	属性	expectedRevision: number	公开属性；类型、只读和可选状态以签名列为准。
idempotencyKey	属性	idempotencyKey?: string	公开属性；类型、只读和可选状态以签名列为准。
leaseGuard	属性	leaseGuard?: ExecutionLeaseGuard	公开属性；类型、只读和可选状态以签名列为准。
next	属性	next: ExecutionRecord	公开属性；类型、只读和可选状态以签名列为准。
operationId	属性	operationId: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecordCreateRequest

Execution Record Create Request 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecordCreateRequest } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
idempotencyKey	属性	idempotencyKey?: string	公开属性；类型、只读和可选状态以签名列为准。
operationId	属性	operationId: string	公开属性；类型、只读和可选状态以签名列为准。
record	属性	record: ExecutionRecord	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecordPage

Execution Record Page 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecordPage } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
cursor	属性	cursor?: string	公开属性；类型、只读和可选状态以签名列为准。
records	属性	records: ExecutionRecord[]	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecordQuery

Execution Record Query 接口，共包含 10 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecordQuery } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
cursor	属性	cursor?: string	公开属性；类型、只读和可选状态以签名列为准。
leaseExpiresBefore	属性	leaseExpiresBefore?: string	公开属性；类型、只读和可选状态以签名列为准。
limit	属性	limit?: number	公开属性；类型、只读和可选状态以签名列为准。
providerId	属性	providerId?: string	公开属性；类型、只读和可选状态以签名列为准。
runId	属性	runId?: string	公开属性；类型、只读和可选状态以签名列为准。
statuses	属性	statuses?: CommandExecutionStatus[]	公开属性；类型、只读和可选状态以签名列为准。
tenantId	属性	tenantId?: string	公开属性；类型、只读和可选状态以签名列为准。
updatedBefore	属性	updatedBefore?: string	公开属性；类型、只读和可选状态以签名列为准。
userId	属性	userId?: string	公开属性；类型、只读和可选状态以签名列为准。
workspaceId	属性	workspaceId?: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionRecoveryAssessment

Execution Recovery Assessment 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionRecoveryAssessment } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
assessedAt	属性	assessedAt: string	公开属性；类型、只读和可选状态以签名列为准。
disposition	属性	disposition: ExecutionRecoveryDisposition	公开属性；类型、只读和可选状态以签名列为准。
executionId	属性	executionId: string	公开属性；类型、只读和可选状态以签名列为准。
providerStatusRef	属性	providerStatusRef?: string	公开属性；类型、只读和可选状态以签名列为准。
reason	属性	reason?: string	公开属性；类型、只读和可选状态以签名列为准。
recordRevision	属性	recordRevision: number	公开属性；类型、只读和可选状态以签名列为准。

ExecutionStore

Execution Store 接口，共包含 10 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionStore } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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>;
}

契约成员

成员	种类	签名	说明
acquireLease	方法	acquireLease(request: ExecutionLeaseAcquireRequest): Promise<ExecutionRecord>	公开方法；参数与返回类型以签名列为准。
close	方法	close?(): Promise<void>	公开方法；参数与返回类型以签名列为准。
compareAndSet	方法	compareAndSet(request: ExecutionRecordCompareAndSetRequest): Promise<ExecutionRecord>	公开方法；参数与返回类型以签名列为准。
create	方法	create(request: ExecutionRecordCreateRequest): Promise<ExecutionRecord>	公开方法；参数与返回类型以签名列为准。
get	方法	get(executionId: string): Promise<ExecutionRecord | null>	公开方法；参数与返回类型以签名列为准。
health	方法	health(): Promise<ProviderHealth>	公开方法；参数与返回类型以签名列为准。
list	方法	list(query?: ExecutionRecordQuery): Promise<ExecutionRecordPage>	公开方法；参数与返回类型以签名列为准。
releaseLease	方法	releaseLease(request: ExecutionLeaseReleaseRequest): Promise<ExecutionRecord>	公开方法；参数与返回类型以签名列为准。
renewLease	方法	renewLease(request: ExecutionLeaseRenewRequest): Promise<ExecutionRecord>	公开方法；参数与返回类型以签名列为准。
resolveIdempotency	方法	resolveIdempotency(query: ExecutionIdempotencyQuery): Promise<ExecutionIdempotencyResolution>	公开方法；参数与返回类型以签名列为准。

ExecutionStoreFactory

Execution Store Factory 接口，共包含 2 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExecutionStoreFactory } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

契约成员

成员	种类	签名	说明
create	方法	create(): Promise<ExecutionStore>	公开方法；参数与返回类型以签名列为准。
storeId	属性	readonly storeId: string	公开属性；类型、只读和可选状态以签名列为准。

ExecutionIdempotencyResolution

Execution Idempotency Resolution 公共类型别名；完整类型表达式见声明。

• 种类: 类型
• 导入: import type { ExecutionIdempotencyResolution } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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

ExecutionRecoveryDisposition

Execution Recovery Disposition 公共类型别名；完整类型表达式见声明。

• 种类: 类型
• 导入: import type { ExecutionRecoveryDisposition } from '@codesoul-co/hypha-core';
• 源码模块: contracts/execution-store

声明

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