@codesoul-co/hypha-memory / external-provider-acceptance

• 包索引: @codesoul-co/hypha-memory
• 源码: packages/memory/src/external-provider-acceptance.ts
• 导出数: 8

模块用法

用于把外部或本地 Provider 绑定到 Hypha Port。External provider acceptance 模块公开 2 函数、6 接口。

从包入口导入

import {
  assertContractShape,
  runExternalProviderAcceptance,
} from '@codesoul-co/hypha-memory';

import type {
  ExternalProviderAcceptanceEvidence,
  ExternalProviderAcceptanceEvidenceInput,
  ExternalProviderAcceptanceFixture,
  ExternalProviderAcceptanceHooks,
  ExternalProviderAcceptanceReport,
  ExternalProviderFailureProbe,
} from '@codesoul-co/hypha-memory';

使用要点

• 6 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用 import type，运行时不应依赖它们。
• 2 个函数是该模块的直接操作入口；每个 overload 的必需/可选参数与返回类型均在下方列出。

公共导出

Symbol	种类	签名	说明
assertContractShape	函数	assertContractShape(client: ExternalMemoryClient): void	Assert Contract Shape 函数，提供 1 个公开调用签名；参数与返回类型见下表。
runExternalProviderAcceptance	函数	runExternalProviderAcceptance(client: ExternalMemoryClient, fixture: ExternalProviderAcceptanceFixture, signal?: AbortSignal, evidenceInput?: ExternalProviderAcceptanceEvidenceInput, hooks?: ExternalProviderAcceptanceHooks): Promise<ExternalProviderAcceptanceReport>	Provider-neutral management acceptance flow shared by every external client.
ExternalProviderAcceptanceEvidence	接口	interface ExternalProviderAcceptanceEvidence	External Provider Acceptance Evidence 接口，共包含 8 个公开字段或方法。
ExternalProviderAcceptanceEvidenceInput	接口	interface ExternalProviderAcceptanceEvidenceInput	External Provider Acceptance Evidence Input 接口，共包含 6 个公开字段或方法。
ExternalProviderAcceptanceFixture	接口	interface ExternalProviderAcceptanceFixture	External Provider Acceptance Fixture 接口，共包含 9 个公开字段或方法。
ExternalProviderAcceptanceHooks	接口	interface ExternalProviderAcceptanceHooks	External Provider Acceptance Hooks 接口，共包含 6 个公开字段或方法。
ExternalProviderAcceptanceReport	接口	interface ExternalProviderAcceptanceReport	External Provider Acceptance Report 接口，共包含 15 个公开字段或方法。
ExternalProviderFailureProbe	接口	interface ExternalProviderFailureProbe	External Provider Failure Probe 接口，共包含 3 个公开字段或方法。

assertContractShape

Assert Contract Shape 函数，提供 1 个公开调用签名；参数与返回类型见下表。

• 种类: 函数
• 导入: import { assertContractShape } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export declare function assertContractShape(client: ExternalMemoryClient): void;

调用签名

assertContractShape(client: ExternalMemoryClient): void

参数

参数	类型	必需	说明
client	ExternalMemoryClient	是	必需参数；接受的值由类型列定义。

返回值

• 类型: void
• 说明: 不返回值。

runExternalProviderAcceptance

Provider-neutral management acceptance flow shared by every external client.

• 种类: 函数
• 导入: import { runExternalProviderAcceptance } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export declare function runExternalProviderAcceptance(client: ExternalMemoryClient, fixture: ExternalProviderAcceptanceFixture, signal?: AbortSignal, evidenceInput?: ExternalProviderAcceptanceEvidenceInput, hooks?: ExternalProviderAcceptanceHooks): Promise<ExternalProviderAcceptanceReport>;

调用签名

runExternalProviderAcceptance(client: ExternalMemoryClient, fixture: ExternalProviderAcceptanceFixture, signal?: AbortSignal, evidenceInput?: ExternalProviderAcceptanceEvidenceInput, hooks?: ExternalProviderAcceptanceHooks): Promise<ExternalProviderAcceptanceReport>

Provider-neutral management acceptance flow shared by every external client.

参数

参数	类型	必需	说明
client	ExternalMemoryClient	是	必需参数；接受的值由类型列定义。
fixture	ExternalProviderAcceptanceFixture	是	必需参数；接受的值由类型列定义。
signal	AbortSignal	否	可选参数；接受的值由类型列定义。
evidenceInput	ExternalProviderAcceptanceEvidenceInput	否	可选参数；接受的值由类型列定义。
hooks	ExternalProviderAcceptanceHooks	否	可选参数；接受的值由类型列定义。

返回值

• 类型: Promise<ExternalProviderAcceptanceReport>
• 说明: 返回值契约由上述类型定义。

ExternalProviderAcceptanceEvidence

External Provider Acceptance Evidence 接口，共包含 8 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderAcceptanceEvidence } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderAcceptanceEvidence {
    commitSha: string;
    providerId: string;
    providerVersion: string;
    profileHash: string;
    capabilitySnapshot: MemoryManagementCapabilities;
    environmentHash: string;
    startedAt: string;
    finishedAt: string;
}

契约成员

成员	种类	签名	说明
capabilitySnapshot	属性	capabilitySnapshot: MemoryManagementCapabilities	公开属性；类型、只读和可选状态以签名列为准。
commitSha	属性	commitSha: string	公开属性；类型、只读和可选状态以签名列为准。
environmentHash	属性	environmentHash: string	公开属性；类型、只读和可选状态以签名列为准。
finishedAt	属性	finishedAt: string	公开属性；类型、只读和可选状态以签名列为准。
profileHash	属性	profileHash: string	公开属性；类型、只读和可选状态以签名列为准。
providerId	属性	providerId: string	公开属性；类型、只读和可选状态以签名列为准。
providerVersion	属性	providerVersion: string	公开属性；类型、只读和可选状态以签名列为准。
startedAt	属性	startedAt: string	公开属性；类型、只读和可选状态以签名列为准。

ExternalProviderAcceptanceEvidenceInput

External Provider Acceptance Evidence Input 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderAcceptanceEvidenceInput } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderAcceptanceEvidenceInput {
    commitSha: string;
    providerId: string;
    providerVersion: string;
    profileHash: string;
    environmentHash: string;
    now?: () => string;
}

契约成员

成员	种类	签名	说明
commitSha	属性	commitSha: string	公开属性；类型、只读和可选状态以签名列为准。
environmentHash	属性	environmentHash: string	公开属性；类型、只读和可选状态以签名列为准。
now	方法	now?(): string	公开方法；参数与返回类型以签名列为准。
profileHash	属性	profileHash: string	公开属性；类型、只读和可选状态以签名列为准。
providerId	属性	providerId: string	公开属性；类型、只读和可选状态以签名列为准。
providerVersion	属性	providerVersion: string	公开属性；类型、只读和可选状态以签名列为准。

ExternalProviderAcceptanceFixture

External Provider Acceptance Fixture 接口，共包含 9 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderAcceptanceFixture } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderAcceptanceFixture {
    add: MemoryAddRequest;
    search: ManagedMemorySearchRequest;
    list: MemoryListRequest;
    get(memoryId: string): MemoryGetRequest;
    update(memoryId: string): ManagedMemoryUpdateRequest;
    history(memoryId: string): MemoryHistoryRequest;
    delete(memoryId: string): ManagedMemoryDeleteRequest;
    forbiddenGet?(memoryId: string): MemoryGetRequest;
    resolveMemoryId(result: {
        addedIds: string[];
        searchedIds: string[];
        listedIds: string[];
    }): string | undefined;
}

契约成员

成员	种类	签名	说明
add	属性	add: MemoryAddRequest	公开属性；类型、只读和可选状态以签名列为准。
delete	方法	delete(memoryId: string): ManagedMemoryDeleteRequest	公开方法；参数与返回类型以签名列为准。
forbiddenGet	方法	forbiddenGet?(memoryId: string): MemoryGetRequest	公开方法；参数与返回类型以签名列为准。
get	方法	get(memoryId: string): MemoryGetRequest	公开方法；参数与返回类型以签名列为准。
history	方法	history(memoryId: string): MemoryHistoryRequest	公开方法；参数与返回类型以签名列为准。
list	属性	list: MemoryListRequest	公开属性；类型、只读和可选状态以签名列为准。
resolveMemoryId	方法	resolveMemoryId(result: { addedIds: string[]; searchedIds: string[]; listedIds: string[]; }): string | undefined	公开方法；参数与返回类型以签名列为准。
search	属性	search: ManagedMemorySearchRequest	公开属性；类型、只读和可选状态以签名列为准。
update	方法	update(memoryId: string): ManagedMemoryUpdateRequest	公开方法；参数与返回类型以签名列为准。

ExternalProviderAcceptanceHooks

External Provider Acceptance Hooks 接口，共包含 6 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderAcceptanceHooks } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderAcceptanceHooks {
    settleAdd?(result: ManagedMemoryWriteResult, signal?: AbortSignal): Promise<void>;
    preparePagination?(signal?: AbortSignal): Promise<void>;
    verifyRestart?(memoryId: string, signal?: AbortSignal): Promise<void>;
    verifyDelete?(memoryId: string, signal?: AbortSignal): Promise<void>;
    failureProbes?: readonly ExternalProviderFailureProbe[];
    cleanup?(signal?: AbortSignal): Promise<void>;
}

契约成员

成员	种类	签名	说明
cleanup	方法	cleanup?(signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。
failureProbes	属性	failureProbes?: readonly ExternalProviderFailureProbe[]	公开属性；类型、只读和可选状态以签名列为准。
preparePagination	方法	preparePagination?(signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。
settleAdd	方法	settleAdd?(result: ManagedMemoryWriteResult, signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。
verifyDelete	方法	verifyDelete?(memoryId: string, signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。
verifyRestart	方法	verifyRestart?(memoryId: string, signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。

ExternalProviderAcceptanceReport

External Provider Acceptance Report 接口，共包含 15 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderAcceptanceReport } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderAcceptanceReport {
    status: 'passed';
    capabilities: MemoryManagementCapabilities;
    memoryId: string;
    addStatus: string;
    searchCount: number;
    listCount: number;
    updateStatus?: string;
    historyCount?: number;
    deleteStatus: string;
    healthStatus: string;
    paginationPageCount: number;
    scopeIsolationVerified: boolean;
    restartVerified: boolean;
    failureProbeCount: number;
    evidence?: ExternalProviderAcceptanceEvidence;
}

契约成员

成员	种类	签名	说明
addStatus	属性	addStatus: string	公开属性；类型、只读和可选状态以签名列为准。
capabilities	属性	capabilities: MemoryManagementCapabilities	公开属性；类型、只读和可选状态以签名列为准。
deleteStatus	属性	deleteStatus: string	公开属性；类型、只读和可选状态以签名列为准。
evidence	属性	evidence?: ExternalProviderAcceptanceEvidence	公开属性；类型、只读和可选状态以签名列为准。
failureProbeCount	属性	failureProbeCount: number	公开属性；类型、只读和可选状态以签名列为准。
healthStatus	属性	healthStatus: string	公开属性；类型、只读和可选状态以签名列为准。
historyCount	属性	historyCount?: number	公开属性；类型、只读和可选状态以签名列为准。
listCount	属性	listCount: number	公开属性；类型、只读和可选状态以签名列为准。
memoryId	属性	memoryId: string	公开属性；类型、只读和可选状态以签名列为准。
paginationPageCount	属性	paginationPageCount: number	公开属性；类型、只读和可选状态以签名列为准。
restartVerified	属性	restartVerified: boolean	公开属性；类型、只读和可选状态以签名列为准。
scopeIsolationVerified	属性	scopeIsolationVerified: boolean	公开属性；类型、只读和可选状态以签名列为准。
searchCount	属性	searchCount: number	公开属性；类型、只读和可选状态以签名列为准。
status	属性	status: "passed"	公开属性；类型、只读和可选状态以签名列为准。
updateStatus	属性	updateStatus?: string	公开属性；类型、只读和可选状态以签名列为准。

ExternalProviderFailureProbe

External Provider Failure Probe 接口，共包含 3 个公开字段或方法。

• 种类: 接口
• 导入: import type { ExternalProviderFailureProbe } from '@codesoul-co/hypha-memory';
• 源码模块: external-provider-acceptance

声明

export interface ExternalProviderFailureProbe {
    id: string;
    expectedCodes: readonly NormalizedMemoryError['code'][];
    run(signal?: AbortSignal): Promise<void>;
}

契约成员

成员	种类	签名	说明
expectedCodes	属性	expectedCodes: readonly ("MEMORY_INVALID_INPUT" | "MEMORY_EXTRACTION_SOURCE_UNAVAILABLE" | "MEMORY_EXTRACTION_FAILED" | "MEMORY_EXTRACTION_CURSOR_CONFLICT" | "MEMORY_MAINTENANCE_CONFLICT" | "MEMORY_RANKING_FAILED" | "MEMORY_IDEMPOTENCY_CONFLICT" | "MEMORY_SCOPE_DENIED" | "MEMORY_PERMISSION_DENIED" | "MEMORY_NOT_FOUND" | "MEMORY_REVISION_CONFLICT" | "MEMORY_PROVIDER_NOT_INSTALLED" | "MEMORY_PROVIDER_UNAVAILABLE" | ...	公开属性；类型、只读和可选状态以签名列为准。
id	属性	id: string	公开属性；类型、只读和可选状态以签名列为准。
run	方法	run(signal?: AbortSignal): Promise<void>	公开方法；参数与返回类型以签名列为准。