@ferricstore/ferricstore 0.2.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/README.md +72 -3
  2. package/dist/index.cjs +2618 -554
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +247 -33
  5. package/dist/index.d.ts +247 -33
  6. package/dist/index.js +2621 -562
  7. package/dist/index.js.map +1 -1
  8. package/docs/api/assets/hierarchy.js +1 -1
  9. package/docs/api/assets/navigation.js +1 -1
  10. package/docs/api/assets/search.js +1 -1
  11. package/docs/api/classes/ClaimHydrationError.html +5 -5
  12. package/docs/api/classes/ConnectionClosedError.html +5 -5
  13. package/docs/api/classes/FerricStoreClient.html +7 -3
  14. package/docs/api/classes/FerricStoreError.html +5 -5
  15. package/docs/api/classes/FlowAlreadyExistsError.html +5 -5
  16. package/docs/api/classes/FlowBatchError.html +5 -5
  17. package/docs/api/classes/FlowNotFoundError.html +5 -5
  18. package/docs/api/classes/FlowQueryError.html +42 -0
  19. package/docs/api/classes/FlowWrongStateError.html +5 -5
  20. package/docs/api/classes/InvalidCommandError.html +5 -5
  21. package/docs/api/classes/LeaseRenewalError.html +5 -5
  22. package/docs/api/classes/LockHeldError.html +5 -5
  23. package/docs/api/classes/LockNotOwnedError.html +5 -5
  24. package/docs/api/classes/NativeAdapter.html +3 -3
  25. package/docs/api/classes/OverloadedError.html +5 -5
  26. package/docs/api/classes/QueueCompletionError.html +5 -5
  27. package/docs/api/classes/ReconnectingExecutor.html +4 -4
  28. package/docs/api/classes/RequestTimeoutError.html +5 -5
  29. package/docs/api/classes/RerouteError.html +5 -5
  30. package/docs/api/classes/StaleLeaseError.html +5 -5
  31. package/docs/api/classes/StalePolicyGenerationError.html +39 -0
  32. package/docs/api/classes/TopologyNativeAdapterPool.html +3 -3
  33. package/docs/api/classes/Workflow.html +1 -1
  34. package/docs/api/classes/WorkflowWorker.html +2 -2
  35. package/docs/api/functions/classifyServerError.html +1 -1
  36. package/docs/api/functions/isReconnectableClosedConnectionError.html +1 -1
  37. package/docs/api/functions/mapException.html +1 -1
  38. package/docs/api/functions/projectFlowQuery.html +1 -0
  39. package/docs/api/hierarchy.html +1 -1
  40. package/docs/api/index.html +36 -5
  41. package/docs/api/interfaces/AdminListOptions.html +1 -1
  42. package/docs/api/interfaces/CancelOptions.html +2 -2
  43. package/docs/api/interfaces/CompleteOptions.html +2 -2
  44. package/docs/api/interfaces/CompleteOutcome.html +1 -1
  45. package/docs/api/interfaces/CreateManyOptions.html +1 -1
  46. package/docs/api/interfaces/EffectCompensateOptions.html +1 -1
  47. package/docs/api/interfaces/EffectConfirmOptions.html +1 -1
  48. package/docs/api/interfaces/EffectFailOptions.html +1 -1
  49. package/docs/api/interfaces/EffectStatusOptions.html +1 -1
  50. package/docs/api/interfaces/ExtendLeaseOptions.html +2 -2
  51. package/docs/api/interfaces/FailOptions.html +2 -2
  52. package/docs/api/interfaces/FailOutcome.html +1 -1
  53. package/docs/api/interfaces/FerricStoreClientFromUrlOptions.html +1 -1
  54. package/docs/api/interfaces/FerricStoreClientOptions.html +1 -1
  55. package/docs/api/interfaces/FlowEventProjectionField.html +4 -0
  56. package/docs/api/interfaces/FlowExplainResult.html +10 -0
  57. package/docs/api/interfaces/FlowPolicyBackoffSnapshot.html +5 -0
  58. package/docs/api/interfaces/FlowPolicyOptions.html +8 -4
  59. package/docs/api/interfaces/FlowPolicyRetentionSnapshot.html +3 -0
  60. package/docs/api/interfaces/FlowPolicyRetrySnapshot.html +4 -0
  61. package/docs/api/interfaces/FlowPolicySnapshot.html +17 -0
  62. package/docs/api/interfaces/FlowPolicyStateSnapshot.html +6 -0
  63. package/docs/api/interfaces/FlowQueryCountResult.html +7 -0
  64. package/docs/api/interfaces/FlowQueryErrorPosition.html +4 -0
  65. package/docs/api/interfaces/FlowQueryIndex.html +9 -0
  66. package/docs/api/interfaces/FlowQueryIndexFormat.html +7 -0
  67. package/docs/api/interfaces/FlowQueryIndexRegistry.html +3 -0
  68. package/docs/api/interfaces/FlowQueryIndexStatus.html +8 -0
  69. package/docs/api/interfaces/FlowQueryPage.html +3 -0
  70. package/docs/api/interfaces/FlowQueryQuality.html +5 -0
  71. package/docs/api/interfaces/FlowQueryRecordsResult.html +8 -0
  72. package/docs/api/interfaces/FlowQueryUsage.html +12 -0
  73. package/docs/api/interfaces/FlowRunProjectionField.html +4 -0
  74. package/docs/api/interfaces/HistoryOptions.html +2 -2
  75. package/docs/api/interfaces/InvocationCreateOptions.html +2 -2
  76. package/docs/api/interfaces/LeaseMutationOptions.html +2 -2
  77. package/docs/api/interfaces/LimitListOptions.html +1 -1
  78. package/docs/api/interfaces/MutateOptions.html +2 -2
  79. package/docs/api/interfaces/NamedValueMutation.html +1 -1
  80. package/docs/api/interfaces/ProtocolCommand.html +2 -2
  81. package/docs/api/interfaces/ReadOptions.html +5 -3
  82. package/docs/api/interfaces/ReclaimOptions.html +1 -1
  83. package/docs/api/interfaces/RequestContext.html +2 -2
  84. package/docs/api/interfaces/RequestContextOptions.html +2 -2
  85. package/docs/api/interfaces/RetryOptions.html +2 -2
  86. package/docs/api/interfaces/RetryOutcome.html +1 -1
  87. package/docs/api/interfaces/RunStepsItem.html +2 -2
  88. package/docs/api/interfaces/RunStepsManyOptions.html +2 -2
  89. package/docs/api/interfaces/SearchOptions.html +4 -3
  90. package/docs/api/interfaces/StepContinueOptions.html +3 -3
  91. package/docs/api/interfaces/TDigestCreateOptions.html +1 -1
  92. package/docs/api/interfaces/TDigestMergeOptions.html +1 -1
  93. package/docs/api/interfaces/TransitionOptions.html +2 -2
  94. package/docs/api/interfaces/TransitionOutcome.html +1 -1
  95. package/docs/api/modules.html +1 -1
  96. package/docs/api/types/ConnectionRequestDisposition.html +1 -1
  97. package/docs/api/types/FlowPolicyBackoffKind.html +1 -0
  98. package/docs/api/types/FlowProjectionField.html +1 -0
  99. package/docs/api/types/FlowProjectionShape.html +1 -0
  100. package/docs/api/types/FlowQueryInteger.html +1 -0
  101. package/docs/api/types/FlowQueryParameter.html +1 -0
  102. package/docs/api/types/FlowQueryParameters.html +1 -0
  103. package/docs/api/types/FlowQueryRecord.html +1 -0
  104. package/docs/api/types/FlowQueryResult.html +1 -0
  105. package/docs/api/types/ManagementPairs.html +1 -1
  106. package/docs/api/types/SearchStateMeta.html +1 -1
  107. package/docs/api/variables/COMMAND_OPCODES.html +1 -1
  108. package/docs/api/variables/FERRICSTORE_MINIMUM_SERVER_VERSION.html +1 -1
  109. package/docs/api/variables/FERRICSTORE_NATIVE_PROTOCOL_VERSION.html +1 -1
  110. package/docs/api/variables/FERRICSTORE_SDK_VERSION.html +1 -1
  111. package/docs/api/variables/FlowProjection.html +1 -0
  112. package/docs/api/variables/MAX_FLOW_POLICY_GENERATION.html +1 -0
  113. package/package.json +4 -3
package/dist/index.d.cts CHANGED
@@ -45,6 +45,10 @@ declare class FlowWrongStateError extends FerricStoreError {
45
45
  declare class StaleLeaseError extends FerricStoreError {
46
46
  readonly code = "stale_lease";
47
47
  }
48
+ /** FLOW.POLICY.SET expected_generation did not match the stored generation. */
49
+ declare class StalePolicyGenerationError extends FerricStoreError {
50
+ readonly code = "stale_policy_generation";
51
+ }
48
52
  declare class FlowAlreadyExistsError extends FerricStoreError {
49
53
  readonly code = "flow_already_exists";
50
54
  }
@@ -321,7 +325,6 @@ declare const COMMAND_OPCODES: {
321
325
  readonly "FLOW.VALUE.PUT": 523;
322
326
  readonly "FLOW.VALUE.MGET": 524;
323
327
  readonly "FLOW.SIGNAL": 525;
324
- readonly "FLOW.LIST": 526;
325
328
  readonly "FLOW.CREATE_MANY": 527;
326
329
  readonly "FLOW.COMPLETE_MANY": 528;
327
330
  readonly "FLOW.TRANSITION_MANY": 529;
@@ -330,13 +333,7 @@ declare const COMMAND_OPCODES: {
330
333
  readonly "FLOW.CANCEL_MANY": 532;
331
334
  readonly "FLOW.RECLAIM": 533;
332
335
  readonly "FLOW.REWIND": 534;
333
- readonly "FLOW.TERMINALS": 535;
334
- readonly "FLOW.FAILURES": 536;
335
- readonly "FLOW.BY_PARENT": 537;
336
- readonly "FLOW.BY_ROOT": 538;
337
- readonly "FLOW.BY_CORRELATION": 539;
338
336
  readonly "FLOW.INFO": 540;
339
- readonly "FLOW.STUCK": 541;
340
337
  readonly "FLOW.POLICY.SET": 542;
341
338
  readonly "FLOW.POLICY.GET": 543;
342
339
  readonly "FLOW.SPAWN_CHILDREN": 544;
@@ -355,7 +352,7 @@ declare const COMMAND_OPCODES: {
355
352
  readonly "FLOW.STATS": 557;
356
353
  readonly "FLOW.ATTRIBUTES": 558;
357
354
  readonly "FLOW.ATTRIBUTE_VALUES": 559;
358
- readonly "FLOW.SEARCH": 560;
355
+ readonly "FLOW.QUERY": 561;
359
356
  readonly "FLOW.EFFECT.RESERVE": 576;
360
357
  readonly "FLOW.EFFECT.CONFIRM": 577;
361
358
  readonly "FLOW.EFFECT.FAIL": 578;
@@ -405,6 +402,8 @@ interface ProtocolCommand {
405
402
  readonly laneId?: number;
406
403
  /** @internal Correlated compact claim shape used to decode a direct response without guessing. */
407
404
  readonly compactClaimMode?: CompactClaimMode;
405
+ /** @internal Exact top-level item count expected from a compact collection response. */
406
+ readonly compactResponseItems?: number;
408
407
  /** @internal Correlated compact claim shapes for native pipeline response items. */
409
408
  readonly pipelineClaimModes?: readonly (CompactClaimMode | undefined)[];
410
409
  /** @internal Parsed routing metadata retained when a command uses COMMAND_EXEC. */
@@ -960,6 +959,10 @@ interface FlowStatePolicy {
960
959
  }
961
960
  type FlowStatePolicyLike = FlowStatePolicy | RetryPolicy;
962
961
  interface FlowPolicyOptions {
962
+ /** Replace the complete stored policy instead of applying the default deep patch. */
963
+ replace?: boolean;
964
+ /** Compare-and-swap generation. Must be a nonnegative JavaScript safe integer. */
965
+ expectedGeneration?: number;
963
966
  state?: string;
964
967
  mode?: FlowStateMode;
965
968
  retry?: RetryPolicy;
@@ -967,7 +970,7 @@ interface FlowPolicyOptions {
967
970
  retentionTtlMs?: number;
968
971
  /** Type-level maximum active lifetime for newly created Flows. */
969
972
  maxActiveMs?: MaxActiveMs;
970
- /** Type-level attribute names projected for FLOW.SEARCH. An empty array clears the index list. */
973
+ /** Type-level attribute names projected for Flow queries. An empty array clears the index list. */
971
974
  indexedAttributes?: readonly string[];
972
975
  indexedStateMeta?: string;
973
976
  }
@@ -1058,15 +1061,17 @@ interface CancelOptions extends Omit<MutateOptions, "payload"> {
1058
1061
  ttlMs?: number;
1059
1062
  }
1060
1063
  interface ReadOptions {
1061
- partitionKey?: string;
1064
+ partitionKey: string;
1062
1065
  count?: number;
1063
1066
  fromMs?: number;
1064
1067
  toMs?: number;
1068
+ /** Newest-first when true. Flow query conveniences default to true. */
1065
1069
  rev?: boolean;
1066
1070
  state?: string;
1067
1071
  terminalOnly?: boolean;
1068
1072
  includeCold?: boolean;
1069
1073
  consistentProjection?: boolean;
1074
+ attributes?: Record<string, CommandArgument>;
1070
1075
  }
1071
1076
  interface HistoryOptions {
1072
1077
  partitionKey?: string;
@@ -1108,6 +1113,117 @@ declare class FlowBatchError extends FerricStoreError {
1108
1113
  constructor(operation: string, cause: unknown, completedItems: readonly FlowBatchCompletedItem[]);
1109
1114
  }
1110
1115
 
1116
+ type FlowQueryParameter = string | Buffer | boolean | number | bigint;
1117
+ type FlowQueryParameters = Readonly<Record<string, FlowQueryParameter>>;
1118
+ type FlowQueryRecord = Readonly<Record<string, unknown>>;
1119
+ type FlowQueryInteger = number | bigint;
1120
+ interface FlowQueryPage {
1121
+ readonly hasMore: boolean;
1122
+ readonly cursor?: string;
1123
+ }
1124
+ interface FlowQueryQuality {
1125
+ readonly exactness: string;
1126
+ readonly freshness: string;
1127
+ readonly coverage: string;
1128
+ readonly pagination: string;
1129
+ }
1130
+ interface FlowQueryUsage {
1131
+ readonly rangeSeeks: number;
1132
+ readonly rangePages: number;
1133
+ readonly scannedEntries: number;
1134
+ readonly scannedBytes: number;
1135
+ readonly hydratedRecords: number;
1136
+ readonly residualChecks: number;
1137
+ readonly duplicateEntries: number;
1138
+ readonly resultRecords: number;
1139
+ readonly responseBytes: number;
1140
+ readonly memoryHighWaterBytes: number;
1141
+ readonly wallTimeUs: number;
1142
+ }
1143
+ interface FlowQueryResultBase {
1144
+ readonly version: "ferric.flow.query.result/v1";
1145
+ readonly quality: FlowQueryQuality;
1146
+ readonly usage: FlowQueryUsage;
1147
+ readonly raw: Readonly<Record<string, unknown>>;
1148
+ }
1149
+ interface FlowQueryRecordsResult extends FlowQueryResultBase {
1150
+ readonly kind: "records";
1151
+ readonly records: readonly FlowQueryRecord[];
1152
+ readonly page: FlowQueryPage;
1153
+ }
1154
+ interface FlowQueryCountResult extends FlowQueryResultBase {
1155
+ readonly kind: "count";
1156
+ readonly count: FlowQueryInteger;
1157
+ }
1158
+ type FlowQueryResult = FlowQueryRecordsResult | FlowQueryCountResult;
1159
+ interface FlowQueryErrorPosition {
1160
+ readonly byte: number;
1161
+ readonly line: number;
1162
+ readonly column: number;
1163
+ }
1164
+ declare class FlowQueryError extends FerricStoreError {
1165
+ readonly code: string;
1166
+ readonly detail?: string;
1167
+ readonly hint?: string;
1168
+ readonly position?: FlowQueryErrorPosition;
1169
+ readonly context?: Readonly<Record<string, unknown>>;
1170
+ constructor(options: {
1171
+ readonly code: string;
1172
+ readonly message: string;
1173
+ readonly detail?: string;
1174
+ readonly hint?: string;
1175
+ readonly retryable: boolean;
1176
+ readonly safeToRetry: boolean;
1177
+ readonly retryAfterMs: number;
1178
+ readonly position?: FlowQueryErrorPosition;
1179
+ readonly context?: Readonly<Record<string, unknown>>;
1180
+ readonly raw: unknown;
1181
+ readonly cause?: unknown;
1182
+ });
1183
+ }
1184
+ interface FlowExplainResult {
1185
+ readonly version: "ferric.flow.explain/v1";
1186
+ readonly queryFingerprint: string;
1187
+ readonly status: "planned" | "rejected" | "executed";
1188
+ readonly plan: Readonly<Record<string, unknown>>;
1189
+ readonly estimate: Readonly<Record<string, unknown>>;
1190
+ readonly bounds: Readonly<Record<string, unknown>>;
1191
+ readonly actual?: FlowQueryUsage;
1192
+ readonly diagnostic?: FlowQueryError;
1193
+ readonly raw: Readonly<Record<string, unknown>>;
1194
+ }
1195
+ interface FlowQueryIndexRegistry {
1196
+ readonly epoch: FlowQueryInteger;
1197
+ readonly catalogVersion: FlowQueryInteger;
1198
+ }
1199
+ interface FlowQueryIndexFormat {
1200
+ readonly queryRow: string;
1201
+ readonly key: string;
1202
+ readonly entry: string;
1203
+ readonly reverse: string;
1204
+ readonly counter?: string;
1205
+ readonly raw: Readonly<Record<string, unknown>>;
1206
+ }
1207
+ interface FlowQueryIndex {
1208
+ readonly id: string;
1209
+ readonly version: FlowQueryInteger;
1210
+ readonly buildId: string;
1211
+ readonly state: string;
1212
+ readonly queryable: boolean;
1213
+ readonly coveringFields: readonly string[];
1214
+ readonly format: FlowQueryIndexFormat;
1215
+ readonly raw: Readonly<Record<string, unknown>>;
1216
+ }
1217
+ interface FlowQueryIndexStatus {
1218
+ readonly contractVersion: "ferric.flow.query.indexes/v1";
1219
+ readonly observedAtMs: number;
1220
+ readonly statisticsMaxAgeMs: number;
1221
+ readonly registry: FlowQueryIndexRegistry;
1222
+ readonly services: Readonly<Record<string, unknown>>;
1223
+ readonly indexes: readonly FlowQueryIndex[];
1224
+ readonly raw: Readonly<Record<string, unknown>>;
1225
+ }
1226
+
1111
1227
  declare class FerricStoreClientBase {
1112
1228
  readonly executor: CommandExecutor;
1113
1229
  readonly codec: Codec;
@@ -1823,8 +1939,77 @@ declare class FerricStoreManagementClient extends FerricStoreClientCore {
1823
1939
  governanceLedger(id: string, options?: GovernanceLedgerOptions): Promise<FlowAdminRecord[]>;
1824
1940
  }
1825
1941
 
1942
+ /** @internal Query-planner surface shared by the complete Flow client. */
1943
+ declare class FerricStoreFlowQueryClient extends FerricStoreManagementClient {
1944
+ query(query: string, params?: FlowQueryParameters): Promise<FlowQueryResult>;
1945
+ explain(query: string, params?: FlowQueryParameters): Promise<FlowExplainResult>;
1946
+ explainAnalyze(query: string, params?: FlowQueryParameters): Promise<FlowExplainResult>;
1947
+ queryIndexes(indexId?: string): Promise<FlowQueryIndexStatus>;
1948
+ list(type: string, options: ReadOptions): Promise<FlowRecord[]>;
1949
+ search(type: string, options: SearchOptions): Promise<FlowRecord[]>;
1950
+ terminals(type: string, options: ReadOptions): Promise<FlowRecord[]>;
1951
+ failures(type: string, options: ReadOptions): Promise<FlowRecord[]>;
1952
+ byParent(parentFlowId: string, options: ReadOptions): Promise<FlowRecord[]>;
1953
+ byRoot(rootFlowId: string, options: ReadOptions): Promise<FlowRecord[]>;
1954
+ byCorrelation(correlationId: string, options: ReadOptions): Promise<FlowRecord[]>;
1955
+ stuck(type: string, options: {
1956
+ partitionKey: string;
1957
+ count?: number;
1958
+ olderThanMs?: number;
1959
+ nowMs?: number;
1960
+ }): Promise<FlowRecord[]>;
1961
+ protected records(values: unknown[]): FlowRecord[];
1962
+ private executeFlowQuery;
1963
+ private executeFlowRecordQuery;
1964
+ private executeExplain;
1965
+ private throwFlowQueryError;
1966
+ }
1967
+
1968
+ declare const MAX_FLOW_POLICY_GENERATION: number;
1969
+ type FlowPolicyBackoffKind = "none" | "fixed" | "linear" | "exponential";
1970
+ interface FlowPolicyBackoffSnapshot {
1971
+ readonly kind: FlowPolicyBackoffKind;
1972
+ readonly baseMs: number;
1973
+ readonly maxMs: number;
1974
+ readonly jitterPct: number;
1975
+ }
1976
+ interface FlowPolicyRetrySnapshot {
1977
+ readonly maxRetries: number;
1978
+ readonly backoff: FlowPolicyBackoffSnapshot;
1979
+ readonly exhaustedTo: string;
1980
+ }
1981
+ interface FlowPolicyRetentionSnapshot {
1982
+ readonly ttlMs: number;
1983
+ readonly historyMaxEvents: number;
1984
+ }
1985
+ interface FlowPolicyStateSnapshot {
1986
+ readonly mode: FlowStateMode;
1987
+ readonly maxActiveMs?: number;
1988
+ readonly retry: FlowPolicyRetrySnapshot;
1989
+ readonly retention: FlowPolicyRetentionSnapshot;
1990
+ readonly governance?: Readonly<Record<string, unknown>>;
1991
+ }
1992
+ /** Resolved policy state returned by FLOW.POLICY.SET and FLOW.POLICY.GET. */
1993
+ interface FlowPolicySnapshot {
1994
+ readonly type: string;
1995
+ /** Server-allocated monotonic generation in the JavaScript safe-integer range. */
1996
+ readonly generation: number;
1997
+ readonly state?: string;
1998
+ readonly version?: string | number;
1999
+ readonly mode?: FlowStateMode;
2000
+ readonly maxActiveMs?: number;
2001
+ readonly retry: FlowPolicyRetrySnapshot;
2002
+ readonly retention: FlowPolicyRetentionSnapshot;
2003
+ readonly indexedAttributes: readonly string[];
2004
+ readonly indexedStateMeta?: string;
2005
+ readonly governance?: Readonly<Record<string, unknown>>;
2006
+ readonly states?: Readonly<Record<string, FlowPolicyStateSnapshot>>;
2007
+ /** Original protocol value for forward-compatible fields not yet modeled by the SDK. */
2008
+ readonly raw: unknown;
2009
+ }
2010
+
1826
2011
  /** @internal Read, policy, and shared Flow helpers kept off the primary implementation module. */
1827
- declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
2012
+ declare class FerricStoreFlowSupportClient extends FerricStoreFlowQueryClient {
1828
2013
  rewind(id: string, options?: {
1829
2014
  partitionKey?: string;
1830
2015
  toEvent?: string;
@@ -1840,20 +2025,7 @@ declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
1840
2025
  values?: readonly string[];
1841
2026
  valueMaxBytes?: number;
1842
2027
  }): Promise<FlowRecord<TPayload> | undefined>;
1843
- list(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
1844
- search(type: string, options?: SearchOptions): Promise<FlowRecord[]>;
1845
- terminals(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
1846
- failures(type: string, options?: ReadOptions): Promise<FlowRecord[]>;
1847
- byParent(parentFlowId: string, options?: ReadOptions): Promise<FlowRecord[]>;
1848
- byRoot(rootFlowId: string, options?: ReadOptions): Promise<FlowRecord[]>;
1849
- byCorrelation(correlationId: string, options?: ReadOptions): Promise<FlowRecord[]>;
1850
2028
  info(type: string): Promise<Record<string, unknown>>;
1851
- stuck(type: string, options?: {
1852
- partitionKey?: string;
1853
- count?: number;
1854
- olderThanMs?: number;
1855
- nowMs?: number;
1856
- }): Promise<FlowRecord[]>;
1857
2029
  history(id: string, options?: HistoryOptions): Promise<unknown[]>;
1858
2030
  spawnChildren(parentId: string, children: ChildSpec[], options?: {
1859
2031
  groupId?: string;
@@ -1872,18 +2044,16 @@ declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
1872
2044
  values?: Record<string, unknown>;
1873
2045
  valueRefs?: Record<string, string>;
1874
2046
  }): Promise<unknown>;
1875
- installPolicy(type: string, options?: FlowPolicyOptions): Promise<unknown>;
2047
+ installPolicy(type: string, options?: FlowPolicyOptions): Promise<FlowPolicySnapshot>;
1876
2048
  policyGet(type: string, options?: {
1877
2049
  state?: string;
1878
- }): Promise<Record<string, unknown>>;
2050
+ }): Promise<FlowPolicySnapshot>;
1879
2051
  retentionCleanup(): Promise<Record<string, unknown>>;
1880
2052
  protected executeProducerWrite(args: CommandArgument[]): Promise<unknown>;
1881
2053
  protected recordOrGet(response: unknown, id: string, partitionKey: string | undefined): Promise<FlowRecord>;
1882
- protected records(values: unknown[]): FlowRecord[];
1883
2054
  protected recordsOrResponse(value: unknown): unknown[] | unknown;
1884
2055
  protected flowManyLimitError(operation: string): Error;
1885
2056
  protected executeIndependentManyChunks<T>(operation: string, items: readonly T[], capture: (item: T) => T, execute: (batchItems: T[]) => Promise<unknown[] | unknown>): Promise<unknown[]>;
1886
- private indexQuery;
1887
2057
  protected appendPartitionOptions(args: CommandArgument[], options: {
1888
2058
  partitionKey?: string;
1889
2059
  partitionKeys?: string[];
@@ -2027,6 +2197,50 @@ declare class FerricStoreClient extends FerricStoreProducerClient {
2027
2197
  }): Promise<unknown[] | unknown>;
2028
2198
  }
2029
2199
 
2200
+ declare const FIELD_BRAND: unique symbol;
2201
+ type FlowProjectionShape = "record" | "records";
2202
+ interface FlowRunProjectionField {
2203
+ readonly source: "runs";
2204
+ readonly selector: string;
2205
+ readonly [FIELD_BRAND]: true;
2206
+ }
2207
+ interface FlowEventProjectionField {
2208
+ readonly source: "events";
2209
+ readonly selector: string;
2210
+ readonly [FIELD_BRAND]: true;
2211
+ }
2212
+ type FlowProjectionField = FlowRunProjectionField | FlowEventProjectionField;
2213
+ declare const FlowProjection: Readonly<{
2214
+ run: Readonly<{
2215
+ id: FlowRunProjectionField;
2216
+ type: FlowRunProjectionField;
2217
+ state: FlowRunProjectionField;
2218
+ version: FlowRunProjectionField;
2219
+ priority: FlowRunProjectionField;
2220
+ partitionKey: FlowRunProjectionField;
2221
+ createdAtMs: FlowRunProjectionField;
2222
+ updatedAtMs: FlowRunProjectionField;
2223
+ nextRunAtMs: FlowRunProjectionField;
2224
+ leaseDeadlineMs: FlowRunProjectionField;
2225
+ attempts: FlowRunProjectionField;
2226
+ runState: FlowRunProjectionField;
2227
+ maxActiveMs: FlowRunProjectionField;
2228
+ parentFlowId: FlowRunProjectionField;
2229
+ rootFlowId: FlowRunProjectionField;
2230
+ correlationId: FlowRunProjectionField;
2231
+ attributes: FlowRunProjectionField;
2232
+ stateMetadata: FlowRunProjectionField;
2233
+ attribute(name: string): FlowRunProjectionField;
2234
+ stateMeta(state: string, name: string): FlowRunProjectionField;
2235
+ }>;
2236
+ event: Readonly<{
2237
+ id: FlowEventProjectionField;
2238
+ fields: FlowEventProjectionField;
2239
+ field(name: string): FlowEventProjectionField;
2240
+ }>;
2241
+ }>;
2242
+ declare function projectFlowQuery(query: string, shape: FlowProjectionShape, ...fields: readonly FlowProjectionField[]): string;
2243
+
2030
2244
  type Outcome = TransitionOutcome | CompleteOutcome | RetryOutcome | FailOutcome;
2031
2245
  interface NamedValueMutation {
2032
2246
  values?: Record<string, unknown>;
@@ -2330,7 +2544,7 @@ declare class Workflow {
2330
2544
  worker(options?: WorkerConfig & {
2331
2545
  states?: string[];
2332
2546
  }): WorkflowWorker;
2333
- installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<unknown>;
2547
+ installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<FlowPolicySnapshot>;
2334
2548
  stateNames(): string[];
2335
2549
  stateRegistration(name: string): StateRegistration | undefined;
2336
2550
  }
@@ -2353,13 +2567,13 @@ declare class WorkflowWorker {
2353
2567
  }
2354
2568
 
2355
2569
  /** TypeScript SDK package version. */
2356
- declare const FERRICSTORE_SDK_VERSION = "0.2.0";
2570
+ declare const FERRICSTORE_SDK_VERSION = "0.5.0";
2357
2571
  /** Oldest FerricStore server supported by this breaking beta contract. */
2358
- declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.8.0";
2359
- /** Native framing and opcode ABI version; unchanged by FerricStore 0.8. */
2572
+ declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.0";
2573
+ /** Native framing and opcode ABI version; unchanged by FerricStore 0.11. */
2360
2574
  declare const FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
2361
2575
 
2362
2576
  /** @deprecated Use RequestDisposition; retained for source compatibility. */
2363
2577
  type ConnectionRequestDisposition = RequestDisposition;
2364
2578
 
2365
- export { type AdminListOptions, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowMaxActiveFailure, FlowNotFoundError, type FlowPolicyOptions, type FlowRecord, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, retry, transition };
2579
+ export { type AdminListOptions, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowEventProjectionField, type FlowExplainResult, type FlowMaxActiveFailure, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, FlowProjection, type FlowProjectionField, type FlowProjectionShape, type FlowQueryCountResult, FlowQueryError, type FlowQueryErrorPosition, type FlowQueryIndex, type FlowQueryIndexFormat, type FlowQueryIndexRegistry, type FlowQueryIndexStatus, type FlowQueryInteger, type FlowQueryPage, type FlowQueryParameter, type FlowQueryParameters, type FlowQueryQuality, type FlowQueryRecord, type FlowQueryRecordsResult, type FlowQueryResult, type FlowQueryUsage, type FlowRecord, type FlowRunProjectionField, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, projectFlowQuery, retry, transition };