@codesoul-co/hypha-storage / recovery

• Package index: @codesoul-co/hypha-storage
• Source: packages/storage/src/recovery.ts
• Exports: 5

Using this module

Use the Recovery module for handling bounded recovery, retry, or degradation. It exports 2 functions, 2 interfaces, 1 type.

Import from the package entrypoint

import {
  adviseStorageRecovery,
  classifyStorageFailure,
} from '@codesoul-co/hypha-storage';

import type {
  StorageFailureContext,
  StorageRecoveryAdvice,
  StorageRecoveryOperation,
} from '@codesoul-co/hypha-storage';

Usage patterns

• Use the 3 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.

Public exports

Symbol	Kind	Signature	Description
adviseStorageRecovery	function	adviseStorageRecovery(failure: RecoveryFailure): StorageRecoveryAdvice	Advise Storage Recovery function with 1 public call signature; parameters and return types are listed below.
classifyStorageFailure	function	classifyStorageFailure(error: unknown, context: StorageFailureContext): RecoveryFailure	Converts provider-specific storage errors into the shared recovery contract. Mutations default to an unknown commit state unless a receipt or the caller proves otherwise; this prevents blind replay after an ambiguous disconnect.
StorageFailureContext	interface	interface StorageFailureContext	Storage Failure Context interface with 17 public fields or methods.
StorageRecoveryAdvice	interface	interface StorageRecoveryAdvice	Storage Recovery Advice interface with 6 public fields or methods.
StorageRecoveryOperation	type	type StorageRecoveryOperation = 'read' | 'query' | 'list' | 'write' | 'update' | 'delete' | 'transaction_begin' | 'transaction_commit' | 'transaction_rollback' | 'event_append' | 'artifact_write' | 'artifact_delete' | 'lease_acquire' | 'lease_renew' | 'lease_release' | 'snapshot' | 'restore'	Public type alias for Storage Recovery Operation; the declaration contains its complete type expression.

adviseStorageRecovery

Advise Storage Recovery function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { adviseStorageRecovery } from '@codesoul-co/hypha-storage';
• Source module: recovery

Declaration

export declare function adviseStorageRecovery(failure: RecoveryFailure): StorageRecoveryAdvice;

Call signature

adviseStorageRecovery(failure: RecoveryFailure): StorageRecoveryAdvice

Parameters

Parameter	Type	Required	Description
failure	RecoveryFailure	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: StorageRecoveryAdvice
• Description: The return contract is defined by the type shown above.

classifyStorageFailure

Converts provider-specific storage errors into the shared recovery contract. Mutations default to an unknown commit state unless a receipt or the caller proves otherwise; this prevents blind replay after an ambiguous disconnect.

• Kind: function
• Import: import { classifyStorageFailure } from '@codesoul-co/hypha-storage';
• Source module: recovery

Declaration

export declare function classifyStorageFailure(error: unknown, context: StorageFailureContext): RecoveryFailure;

Call signature

classifyStorageFailure(error: unknown, context: StorageFailureContext): RecoveryFailure

Converts provider-specific storage errors into the shared recovery contract. Mutations default to an unknown commit state unless a receipt or the caller proves otherwise; this prevents blind replay after an ambiguous disconnect.

Parameters

Parameter	Type	Required	Description
error	unknown	Yes	Required parameter; accepted values are defined by the type column.
context	StorageFailureContext	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: RecoveryFailure
• Description: The return contract is defined by the type shown above.

StorageFailureContext

Storage Failure Context interface with 17 public fields or methods.

• Kind: interface
• Import: import type { StorageFailureContext } from '@codesoul-co/hypha-storage';
• Source module: recovery

Declaration

export interface StorageFailureContext {
    id: string;
    operation: StorageRecoveryOperation;
    providerId: string;
    role: StorageRole;
    engine?: StorageEngine;
    resourceKey?: string;
    occurredAt?: string;
    providerRevision?: string;
    specRevision?: string;
    policyRevision?: string;
    expectedRevision?: string | number;
    observedRevision?: string | number;
    idempotencyKey?: string;
    input?: unknown;
    sideEffectState?: RecoverySideEffectState;
    compensationAvailable?: boolean;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
compensationAvailable	property	compensationAvailable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
engine	property	engine?: StorageEngine	Public property; its type, readonly modifier and optionality are shown in the signature.
expectedRevision	property	expectedRevision?: string | number	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.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
input	property	input?: unknown	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
observedRevision	property	observedRevision?: string | number	Public property; its type, readonly modifier and optionality are shown in the signature.
occurredAt	property	occurredAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operation	property	operation: StorageRecoveryOperation	Public property; its type, readonly modifier and optionality are shown in the signature.
policyRevision	property	policyRevision?: 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.
providerRevision	property	providerRevision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
resourceKey	property	resourceKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
role	property	role: StorageRole	Public property; its type, readonly modifier and optionality are shown in the signature.
sideEffectState	property	sideEffectState?: RecoverySideEffectState	Public property; its type, readonly modifier and optionality are shown in the signature.
specRevision	property	specRevision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

StorageRecoveryAdvice

Storage Recovery Advice interface with 6 public fields or methods.

• Kind: interface
• Import: import type { StorageRecoveryAdvice } from '@codesoul-co/hypha-storage';
• Source module: recovery

Declaration

export interface StorageRecoveryAdvice {
    strategy: RecoveryStrategy;
    reason: string;
    requireReconciliation: boolean;
    refreshRevisionBeforeRetry: boolean;
    mayUseCompatibleReplica: boolean;
    invalidateDerivedCaches: boolean;
}

Contract members

Member	Kind	Signature	Description
invalidateDerivedCaches	property	invalidateDerivedCaches: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
mayUseCompatibleReplica	property	mayUseCompatibleReplica: boolean	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.
refreshRevisionBeforeRetry	property	refreshRevisionBeforeRetry: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
requireReconciliation	property	requireReconciliation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
strategy	property	strategy: "fail" | "retry" | "human_review" | "reconcile" | "fallback" | "degrade" | "compensate" | "wait" | "quarantine" | "cancel"	Public property; its type, readonly modifier and optionality are shown in the signature.

StorageRecoveryOperation

Public type alias for Storage Recovery Operation; the declaration contains its complete type expression.

• Kind: type
• Import: import type { StorageRecoveryOperation } from '@codesoul-co/hypha-storage';
• Source module: recovery

Declaration

export type StorageRecoveryOperation = 'read' | 'query' | 'list' | 'write' | 'update' | 'delete' | 'transaction_begin' | 'transaction_commit' | 'transaction_rollback' | 'event_append' | 'artifact_write' | 'artifact_delete' | 'lease_acquire' | 'lease_renew' | 'lease_release' | 'snapshot' | 'restore';