@tansr/serve 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -12130,6 +12130,104 @@ declare function createMemoryBlobStore(options?: MemoryBlobStoreOptions): Segmen
     keys(): string[];
 };
 
+interface FsBlobStoreOptions {
+    /** 根目录(不存在则首次操作创建);只作冷层 */
+    dir: string;
+    /** 覆写能力自述(测试用,如模拟无条件写后端;行为不随之变——一致性测试套据此揭示「自述不实」) */
+    capabilities?: Partial<BlobStoreCapabilities>;
+}
+declare function createFsBlobStore(options: FsBlobStoreOptions): SegmentBlobStore;
+
+interface StorageConformanceOptions {
+    /** 大对象体量;缺省 16 MiB(正式认证建议 1 GiB) */
+    largeObjectBytes?: number;
+    /** 大对象 put / get 各自允许的 RSS 峰值增量;缺省 64 MiB */
+    rssBudgetBytes?: number;
+    /** list 最终一致可见窗口;0 = 须立即可见;缺省 0 */
+    eventualConsistencyMs?: number;
+    /** 隔离前缀;缺省 `conformance-<random>` */
+    keyPrefix?: string;
+    /** 并发封存用例的键数;缺省 16 */
+    concurrency?: number;
+    /** 结束时不清理(排障) */
+    keepObjects?: boolean;
+    signal?: AbortSignal;
+}
+interface StorageConformanceCase {
+    id: string;
+    passed: boolean;
+    detail: string;
+    /** 因能力自述不适用而跳过(计 passed) */
+    skipped?: boolean;
+    durationMs: number;
+}
+interface StorageConformanceReport {
+    cases: StorageConformanceCase[];
+    /** 全部用例 passed */
+    passed: boolean;
+    capabilities: BlobStoreCapabilities;
+    startedAt: string;
+    durationMs: number;
+}
+declare function runStorageConformance(store: SegmentBlobStore, options?: StorageConformanceOptions): Promise<StorageConformanceReport>;
+
+/**
+ * 混沌包装器 `createChaosBlobStore(inner, faults)`(doc/119 IO-14)——把任一 `SegmentBlobStore` 包成
+ * 会出故障的后端,供一致性测试套 / 对抗验收(doc/119 §1.2 A1–A14)注入:
+ *
+ *   failPut              put 立即失败(true / 按键谓词 / 前 N 次),kind = putErrorKind(缺省 transient)
+ *   failPutAfterBytes    put 消费体到 N 字节后失败(连接中断;体已部分读出,不得留半对象)
+ *   putErrorKind         注入的 put 失败分类(transient | permanent | not_found | precondition_failed)
+ *   eventualListLagMs    list 对「最近 lag 毫秒内 put 的键」不可见(最终一致);capabilities.consistency 报 eventual
+ *   dropListEntries      list 丢项(按键谓词 / 概率 0–1)
+ *   corruptSegmentKeys   get 对匹配键返回翻转首字节的体(篡改;A4)
+ *   abortMidStream       get 的流在首块之后以 transient 出错(下载中断;A7)
+ *   latencyMs            每次调用前延迟(定值 / [min,max] 均匀)
+ *
+ * `faults` 对象**按引用持有**,测试可运行时翻转(如愈合 failPut 观察追平);`stats` 记各类注入次数。
+ * 不改语义的调用原样透传;内层错误原样上抛(不二次包装)。
+ */
+
+type KeyPredicate = boolean | ((key: string) => boolean);
+interface ChaosFaults {
+    /** put 立即失败:true / 按键谓词 / 数字 = 前 N 次 put 失败 */
+    failPut?: KeyPredicate | number;
+    /** put 读体至 N 字节后失败(不留半对象) */
+    failPutAfterBytes?: number;
+    /** 注入的 put 失败分类;缺省 transient */
+    putErrorKind?: StoreErrorKind;
+    /** transient 时附带的 retryAfterMs 提示 */
+    retryAfterMs?: number;
+    /** list 对最近 lag 毫秒内 put 的键不可见 */
+    eventualListLagMs?: number;
+    /** list 丢项:按键谓词 / 概率(0–1) */
+    dropListEntries?: KeyPredicate | number;
+    /** get 返回篡改体(首字节翻转)的键 */
+    corruptSegmentKeys?: KeyPredicate;
+    /** get 流在首块后以 transient 出错 */
+    abortMidStream?: KeyPredicate;
+    /** 每次调用前延迟 */
+    latencyMs?: number | {
+        min: number;
+        max: number;
+    };
+}
+interface ChaosStats {
+    putFailures: number;
+    putTruncated: number;
+    listHidden: number;
+    listDropped: number;
+    corruptedGets: number;
+    abortedGets: number;
+    calls: Record<'put' | 'get' | 'head' | 'list' | 'delete', number>;
+}
+interface ChaosBlobStore extends SegmentBlobStore {
+    readonly faults: ChaosFaults;
+    readonly stats: ChaosStats;
+    readonly inner: SegmentBlobStore;
+}
+declare function createChaosBlobStore(inner: SegmentBlobStore, faults?: ChaosFaults, now?: () => number): ChaosBlobStore;
+
 /** 会话身份(冷层键形 `<tenant>/<endUserKey>/<sessionId>/<volumeId>/…` 与清单分域所需)+ 热层目录 */
 interface ColdSessionRef {
     sessionId: string;
@@ -18559,5 +18657,5 @@ declare function alignHistoryPage(messages: readonly IRMessage[], offset: number
  */
 declare function sliceHistoryPage(messages: readonly IRMessage[], offset: number, limit: number | undefined): HistoryPage;
 
-export { AGENT_SESSION_CONTRACT_VERSION, AUDIO_INPUT_PATTERN, AUDIO_LANGUAGE_MAX_CHARS, AUDIO_MAX_BODY_BYTES, AUDIO_PROMPT_MAX_CHARS, AUDIO_ROUTE_SEGMENTS, AUDIO_SPEECH_FORMATS, AUDIO_SPEECH_INPUT_MAX_CHARS, AUDIO_VOICE_MAX_CHARS, AgentSessionBridge, AgentSessionCreateError, AgentSessionStoreError, AppTokenMintError, AudioSpeechBodySchema, AudioTranscriptionsBodySchema, BUILTIN_CAPABILITY_PROFILES, CHECKPOINT_EXPORT_CONTENT_TYPE, CHECKPOINT_IMPORT_MAX_BODY_BYTES, CHECKPOINT_IMPORT_SEGMENT, CHECKPOINT_LABEL_MAX_CHARS, CLIENT_TOOL_NAME_PATTERN, COMPACT_INSTRUCTIONS_MAX_CHARS, CONTROL_FRAME, CheckpointBodySchema, CheckpointOptionSchema, ClientToolDeclSchema, ClientToolNameConflictError, CompactBodySchema, CreateSessionBodySchema, DEFAULT_BUNDLE_CACHE_TTL_MS, DEFAULT_SSE_FLUSH_SLICE_MS, DEFAULT_SSE_HEARTBEAT_MS, DEFAULT_SSE_RETRY_MS, END_USER_ID_PATTERN, EXCLUDE_TOKEN_PATTERN, EventRingBuffer, IMAGE_MIME_PATTERN, ImageGenDataSchema, LOG_EVENT, LOG_EVENT_NAMES, MemorySessionEventLog, MessageBlockSchema, MessagesBodySchema, OBSERVABILITY_PATHS, OPENMETRICS_CONTENT_TYPE, PermissionReceiptSchema, QuestionReceiptSchema, REPLAY_GAP_EVENT, REQUEST_ID_HEADER, ReceiptContentSchema, RestoreBodySchema, SEGMENTED_STORE_DEFAULTS, SERVER_MESSAGE_KEY, SERVER_MESSAGE_KEYS, SERVE_RUNTIME_ENV, SERVE_RUNTIME_ENV_NAMES, SESSION_ID_SHARD_MAX, ServeSessionDriver, SetCwdBodySchema, SpeechDataSchema, SseTransport, StoreError, TURN_END_NOTIFY_SIGNATURE_HEADER, ToolParameterSpecSchema, ToolResultReceiptSchema, TranscriptDataSchema, TurnEndNotifier, V2_ASSEMBLY_MESSAGE_KEY, V2_ASSEMBLY_MESSAGE_KEYS, V2_CTX_PERSIST_MESSAGE_KEY, V2_CTX_PERSIST_MESSAGE_KEYS, V2_ERROR_CODE, V2_LIMITS, VideoGenDataSchema, alignHistoryPage, appliedRuntimeEnvByGroup, assertSessionIdShard, buildRemoteTool, createAgentSessionFactory, createAppTokenMinter, createBundleCache, createMemoryBlobStore, createMetricsRegistry, createPlatformServeSessionFactory, createPlatformSessionAssembler, createServeAgentSessionStore, createServeCheckpointStore, createUpstreamGovernor, defaultMetrics, encodeAgentStreamFrame, encodeKernelEventFrame, encodeSseComment, encodeSseFrame, endUserKeyOf, extractBearerToken, getRequestContext, isAuthorized, isControlFrameType, isExcluded, isLoopbackHost, isSessionHistoryStore, kernelMetricsFor, negotiateLocale, parseExcludeTokens, parseHistoryPageQuery, parseMediaArtifact, registerBuiltinLocales, rejectionCodeOf, renderOpenMetrics, resolvePlatformAdjudicator, resolveRequestId, resolveServeRuntimeOptions, resolveUpstreamFetch, routeTemplateOf, runIdleCompaction, serveMetricsFor, sessionIdShardOf, sessionIdShardPrefix, sessionTitleOf, setLocale, shardedSessionId, sliceHistoryPage, slowSubscriberGapFrame, startServer, sumRingStats, toCheckpointMetaView, toStoreError, tokenMatches, translateMintError, translateUpstreamAssemblyErrors, upstreamAgentOptions, upstreamOriginOf };
-export type { AdjudicationPosture, AdmissionDecision, AdmissionOptions, AdmissionReadiness, AdmissionRejectReason, AdmissionStats, AgentCheckpointOptions, AgentCheckpointResult, AgentCheckpointStore, AgentCheckpointsOptions, AgentCompactOptions, AgentCompactResult, AgentControlEvent, AgentCreateErrorCode, AgentCwdPolicy, AgentDeleteCheckpointResult, AgentExportCheckpointResult, AgentGovernanceOptions, AgentGovernanceStats, AgentImportCheckpointOptions, AgentImportCheckpointResult, AgentInterruptOptions, AgentInterruptSource, AgentListCheckpointsResult, AgentPlatformAudioFace, AgentPlatformAudioResult, AgentRestoreOptions, AgentRestoreResult, AgentSessionBridgeOptions, AgentSessionCreateInit, AgentSessionCreateResult, AgentSessionFactory, AgentSessionFactoryBuild, AgentSessionHandle, AgentSessionsOptions, AgentSetCwdResult, AgentStoreCommitMeta, AgentStoreForkInput, AgentStoreReader, AgentStoredCwdChange, AgentStoredSessionMeta, AgentStoredSessionRecord, AgentStreamEvent, AlignedHistoryPage, AppTokenMintErrorKind, AppTokenMinter, AppTokenMinterStats, ApprovalCredentialSink, AssembledBundleAdjudicator, AssembledSessionModel, AttachOptions, AudioRouteSegment, AudioSpeechBody, AudioTranscriptionsBody, AuxFastSource, BlobListEntry, BlobMeta, BlobStoreCapabilities, BundleCache, BundleCacheStats, ByteRange, CheckpointBody, ClientToolDecl, StoredSessionMeta$1 as ColdStoredSessionMeta, ColdTierEvent, ColdTierEventType, ColdTierStats, CompactBody, ControlFrameName, ControlFramePayload, CounterMetric, CreateAgentSessionFactoryOptions, CreateAppTokenMinterOptions, CreateBundleCacheOptions, CreatePlatformSessionAssemblerOptions, CreateServeAgentSessionStoreOptions, CreateServeCheckpointStoreOptions, CreateSessionBody, DrainOptions, DrainReport, EventRingBufferOptions, EventRingBufferStats, GaugeMetric, HistogramMetric, HistoryPage, HistoryPageQuery, HttpServerOptions, IdleCompactionInput, IdleCompactionResult, ImageGenData, LoadQuery, LoadResult, LogEventName, MediaArtifact, MemoryBlobStoreOptions, MessageBlock, MessagesBody, MetricLabels, MetricSnapshot, MetricsRegistry, MetricsSnapshot, OverloadReason, ParsedHistoryQuery, PermissionReceipt, PermissionRequestPayload, PlatformAdjudicationOptions, PlatformAgentSessionOptions, PlatformServeSessionFactoryOptions, PlatformSessionAssemblerInput, PlatformUpstreamStats, PutOptions, PutResult, QuestionReceipt, QuestionRequestPayload, RateLimitDecision, ReadinessProbe, ReceiptOutcome, RemoteToolBuild, ReplayGapNotice, RequestClosedPayload, RequestContext, RestoreBody, RingBufferSummary, SegmentBlobStore, SegmentedStorePolicy, ServeAgentSessionStore, ServeCwdRebinder, ServeIdleCompactOptions, ServeIdleCompactResult, ServeLogFormat, ServeLogLevel, ServeLogger, ServeMetrics, ServeObservabilityOptions, ServeRestoreHistoryResult, ServeRuntimeEnvGroup, ServeRuntimeEnvKind, ServeRuntimeEnvSpec, ServeRuntimeEnvWarning, ServeRuntimeOptions, ServeRuntimeServerOptions, ServeRuntimeSessionOptions, ServeRuntimeV2Options, ServeSessionDriverOptions, ServeSessionExtras, ServeSessionFactory, ServeSetCwdResult, ServeStats, ServeTurnEndInfo, ServerHandle, SessionEventLog, SessionEventLogContext, SessionEventLogFactory, SessionEventLogRead, SessionFactory, SessionGovernanceStats, SessionHandle, SessionHistoryStore, SessionIndexStore, SessionInit, SessionModelAssembler, SessionSendOutcome, SetCwdBody, SharedMcpTool, SpeechData, SseFrame, SseOptions, SseTransportOptions, SseTransportStats, StartServerOptions, StoreErrorKind, StoreErrorOptions, StoreInput, StoredSessionMeta, StreamTransform, SubscriberWriter, SubscriberWriterStats, SubscribersGoneContext, SubscribersGoneDecision, ToolCancelPayload, ToolRequestPayload, ToolResultReceipt, TranscriptData, TurnEndNotifierBreakerState, TurnEndNotifierOptions, TurnEndNotifierStats, TurnEndNotifyFailure, TurnEndNotifyPayload, TurnEndNotifyStatus, UpstreamGovernor, UpstreamGovernorEvent, UpstreamGovernorLike, UpstreamGovernorOptions, UpstreamGovernorStats, UpstreamOriginStats, UpstreamRejectReason, V1GovernanceOptions, V1SessionsOptions, V2CheckpointList, V2CheckpointMeta, V2CompactResult, V2ErrorCode, V2RestoreResult, V2SessionMetaView, V2SessionStatus, V2SetCwdResult, VideoGenData, WireToolParameterSpec };
+export { AGENT_SESSION_CONTRACT_VERSION, AUDIO_INPUT_PATTERN, AUDIO_LANGUAGE_MAX_CHARS, AUDIO_MAX_BODY_BYTES, AUDIO_PROMPT_MAX_CHARS, AUDIO_ROUTE_SEGMENTS, AUDIO_SPEECH_FORMATS, AUDIO_SPEECH_INPUT_MAX_CHARS, AUDIO_VOICE_MAX_CHARS, AgentSessionBridge, AgentSessionCreateError, AgentSessionStoreError, AppTokenMintError, AudioSpeechBodySchema, AudioTranscriptionsBodySchema, BUILTIN_CAPABILITY_PROFILES, CHECKPOINT_EXPORT_CONTENT_TYPE, CHECKPOINT_IMPORT_MAX_BODY_BYTES, CHECKPOINT_IMPORT_SEGMENT, CHECKPOINT_LABEL_MAX_CHARS, CLIENT_TOOL_NAME_PATTERN, COMPACT_INSTRUCTIONS_MAX_CHARS, CONTROL_FRAME, CheckpointBodySchema, CheckpointOptionSchema, ClientToolDeclSchema, ClientToolNameConflictError, CompactBodySchema, CreateSessionBodySchema, DEFAULT_BUNDLE_CACHE_TTL_MS, DEFAULT_SSE_FLUSH_SLICE_MS, DEFAULT_SSE_HEARTBEAT_MS, DEFAULT_SSE_RETRY_MS, END_USER_ID_PATTERN, EXCLUDE_TOKEN_PATTERN, EventRingBuffer, IMAGE_MIME_PATTERN, ImageGenDataSchema, LOG_EVENT, LOG_EVENT_NAMES, MemorySessionEventLog, MessageBlockSchema, MessagesBodySchema, OBSERVABILITY_PATHS, OPENMETRICS_CONTENT_TYPE, PermissionReceiptSchema, QuestionReceiptSchema, REPLAY_GAP_EVENT, REQUEST_ID_HEADER, ReceiptContentSchema, RestoreBodySchema, SEGMENTED_STORE_DEFAULTS, SERVER_MESSAGE_KEY, SERVER_MESSAGE_KEYS, SERVE_RUNTIME_ENV, SERVE_RUNTIME_ENV_NAMES, SESSION_ID_SHARD_MAX, ServeSessionDriver, SetCwdBodySchema, SpeechDataSchema, SseTransport, StoreError, TURN_END_NOTIFY_SIGNATURE_HEADER, ToolParameterSpecSchema, ToolResultReceiptSchema, TranscriptDataSchema, TurnEndNotifier, V2_ASSEMBLY_MESSAGE_KEY, V2_ASSEMBLY_MESSAGE_KEYS, V2_CTX_PERSIST_MESSAGE_KEY, V2_CTX_PERSIST_MESSAGE_KEYS, V2_ERROR_CODE, V2_LIMITS, VideoGenDataSchema, alignHistoryPage, appliedRuntimeEnvByGroup, assertSessionIdShard, buildRemoteTool, createAgentSessionFactory, createAppTokenMinter, createBundleCache, createChaosBlobStore, createFsBlobStore, createMemoryBlobStore, createMetricsRegistry, createPlatformServeSessionFactory, createPlatformSessionAssembler, createServeAgentSessionStore, createServeCheckpointStore, createUpstreamGovernor, defaultMetrics, encodeAgentStreamFrame, encodeKernelEventFrame, encodeSseComment, encodeSseFrame, endUserKeyOf, extractBearerToken, getRequestContext, isAuthorized, isControlFrameType, isExcluded, isLoopbackHost, isSessionHistoryStore, kernelMetricsFor, negotiateLocale, parseExcludeTokens, parseHistoryPageQuery, parseMediaArtifact, registerBuiltinLocales, rejectionCodeOf, renderOpenMetrics, resolvePlatformAdjudicator, resolveRequestId, resolveServeRuntimeOptions, resolveUpstreamFetch, routeTemplateOf, runIdleCompaction, runStorageConformance, serveMetricsFor, sessionIdShardOf, sessionIdShardPrefix, sessionTitleOf, setLocale, shardedSessionId, sliceHistoryPage, slowSubscriberGapFrame, startServer, sumRingStats, toCheckpointMetaView, toStoreError, tokenMatches, translateMintError, translateUpstreamAssemblyErrors, upstreamAgentOptions, upstreamOriginOf };
+export type { AdjudicationPosture, AdmissionDecision, AdmissionOptions, AdmissionReadiness, AdmissionRejectReason, AdmissionStats, AgentCheckpointOptions, AgentCheckpointResult, AgentCheckpointStore, AgentCheckpointsOptions, AgentCompactOptions, AgentCompactResult, AgentControlEvent, AgentCreateErrorCode, AgentCwdPolicy, AgentDeleteCheckpointResult, AgentExportCheckpointResult, AgentGovernanceOptions, AgentGovernanceStats, AgentImportCheckpointOptions, AgentImportCheckpointResult, AgentInterruptOptions, AgentInterruptSource, AgentListCheckpointsResult, AgentPlatformAudioFace, AgentPlatformAudioResult, AgentRestoreOptions, AgentRestoreResult, AgentSessionBridgeOptions, AgentSessionCreateInit, AgentSessionCreateResult, AgentSessionFactory, AgentSessionFactoryBuild, AgentSessionHandle, AgentSessionsOptions, AgentSetCwdResult, AgentStoreCommitMeta, AgentStoreForkInput, AgentStoreReader, AgentStoredCwdChange, AgentStoredSessionMeta, AgentStoredSessionRecord, AgentStreamEvent, AlignedHistoryPage, AppTokenMintErrorKind, AppTokenMinter, AppTokenMinterStats, ApprovalCredentialSink, AssembledBundleAdjudicator, AssembledSessionModel, AttachOptions, AudioRouteSegment, AudioSpeechBody, AudioTranscriptionsBody, AuxFastSource, BlobListEntry, BlobMeta, BlobStoreCapabilities, BundleCache, BundleCacheStats, ByteRange, ChaosBlobStore, ChaosFaults, ChaosStats, CheckpointBody, ClientToolDecl, StoredSessionMeta$1 as ColdStoredSessionMeta, ColdTierEvent, ColdTierEventType, ColdTierStats, CompactBody, ControlFrameName, ControlFramePayload, CounterMetric, CreateAgentSessionFactoryOptions, CreateAppTokenMinterOptions, CreateBundleCacheOptions, CreatePlatformSessionAssemblerOptions, CreateServeAgentSessionStoreOptions, CreateServeCheckpointStoreOptions, CreateSessionBody, DrainOptions, DrainReport, EventRingBufferOptions, EventRingBufferStats, FsBlobStoreOptions, GaugeMetric, HistogramMetric, HistoryPage, HistoryPageQuery, HttpServerOptions, IdleCompactionInput, IdleCompactionResult, ImageGenData, KeyPredicate, LoadQuery, LoadResult, LogEventName, MediaArtifact, MemoryBlobStoreOptions, MessageBlock, MessagesBody, MetricLabels, MetricSnapshot, MetricsRegistry, MetricsSnapshot, OverloadReason, ParsedHistoryQuery, PermissionReceipt, PermissionRequestPayload, PlatformAdjudicationOptions, PlatformAgentSessionOptions, PlatformServeSessionFactoryOptions, PlatformSessionAssemblerInput, PlatformUpstreamStats, PutOptions, PutResult, QuestionReceipt, QuestionRequestPayload, RateLimitDecision, ReadinessProbe, ReceiptOutcome, RemoteToolBuild, ReplayGapNotice, RequestClosedPayload, RequestContext, RestoreBody, RingBufferSummary, SegmentBlobStore, SegmentedStorePolicy, ServeAgentSessionStore, ServeCwdRebinder, ServeIdleCompactOptions, ServeIdleCompactResult, ServeLogFormat, ServeLogLevel, ServeLogger, ServeMetrics, ServeObservabilityOptions, ServeRestoreHistoryResult, ServeRuntimeEnvGroup, ServeRuntimeEnvKind, ServeRuntimeEnvSpec, ServeRuntimeEnvWarning, ServeRuntimeOptions, ServeRuntimeServerOptions, ServeRuntimeSessionOptions, ServeRuntimeV2Options, ServeSessionDriverOptions, ServeSessionExtras, ServeSessionFactory, ServeSetCwdResult, ServeStats, ServeTurnEndInfo, ServerHandle, SessionEventLog, SessionEventLogContext, SessionEventLogFactory, SessionEventLogRead, SessionFactory, SessionGovernanceStats, SessionHandle, SessionHistoryStore, SessionIndexStore, SessionInit, SessionModelAssembler, SessionSendOutcome, SetCwdBody, SharedMcpTool, SpeechData, SseFrame, SseOptions, SseTransportOptions, SseTransportStats, StartServerOptions, StorageConformanceCase, StorageConformanceOptions, StorageConformanceReport, StoreErrorKind, StoreErrorOptions, StoreInput, StoredSessionMeta, StreamTransform, SubscriberWriter, SubscriberWriterStats, SubscribersGoneContext, SubscribersGoneDecision, ToolCancelPayload, ToolRequestPayload, ToolResultReceipt, TranscriptData, TurnEndNotifierBreakerState, TurnEndNotifierOptions, TurnEndNotifierStats, TurnEndNotifyFailure, TurnEndNotifyPayload, TurnEndNotifyStatus, UpstreamGovernor, UpstreamGovernorEvent, UpstreamGovernorLike, UpstreamGovernorOptions, UpstreamGovernorStats, UpstreamOriginStats, UpstreamRejectReason, V1GovernanceOptions, V1SessionsOptions, V2CheckpointList, V2CheckpointMeta, V2CompactResult, V2ErrorCode, V2RestoreResult, V2SessionMetaView, V2SessionStatus, V2SetCwdResult, VideoGenData, WireToolParameterSpec };