@cosmicdrift/kumiko-framework 0.405.0 → 0.409.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 (214) hide show
  1. package/agents/api/framework-db.md +1 -0
  2. package/agents/api/framework-engine.md +18 -2
  3. package/agents/api/framework-ui-types.md +15 -0
  4. package/agents/api/renderer-web.md +156 -2
  5. package/agents/api/types.md +113 -71
  6. package/agents/api.md +4 -4
  7. package/agents/boot-rules.md +743 -0
  8. package/agents/examples/contact.md +167 -0
  9. package/agents/examples/delivery-notifications.md +34 -1
  10. package/agents/examples/lane-routing.md +13 -0
  11. package/agents/examples/record-detail-layout.md +13 -2
  12. package/agents/examples/search.md +65 -3
  13. package/agents/examples/secrets-demo.md +96 -2
  14. package/agents/examples/tenant-inactivity.md +138 -0
  15. package/agents/examples.md +2 -0
  16. package/agents/features-index.md +4 -0
  17. package/agents/features.md +24 -1
  18. package/agents/widgets.md +12 -1
  19. package/dist/api/export/export-rows.js +1 -0
  20. package/dist/compliance/index.d.ts +1 -1
  21. package/dist/db/event-store-executor-read-where.js +15 -5
  22. package/dist/db/index.d.ts +1 -1
  23. package/dist/db/index.js +1 -1
  24. package/dist/db/migrate-generator.js +3 -1
  25. package/dist/db/queries/event-consumer.js +11 -7
  26. package/dist/db/queries/event-store.d.ts +2 -1
  27. package/dist/db/queries/event-store.js +25 -6
  28. package/dist/db/queries/rls-boot-catalog.js +3 -1
  29. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  30. package/dist/db/queries/session-advisory-lock.js +23 -0
  31. package/dist/db/query.js +7 -10
  32. package/dist/db/row-level-security-connection.js +4 -2
  33. package/dist/engine/active-membership.js +1 -0
  34. package/dist/engine/boot-validator/access-declarations.js +57 -33
  35. package/dist/engine/boot-validator/action-wiring.js +8 -6
  36. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  37. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  38. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  39. package/dist/engine/boot-validator/agent-effect.js +20 -0
  40. package/dist/engine/boot-validator/boot-context.js +5 -1
  41. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  42. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  43. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  44. package/dist/engine/boot-validator/boot-phases.js +3 -1
  45. package/dist/engine/boot-validator/boot-rules.d.ts +2619 -0
  46. package/dist/engine/boot-validator/boot-rules.js +58 -0
  47. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  48. package/dist/engine/boot-validator/config-deps.js +71 -23
  49. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  50. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  51. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  52. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  53. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  54. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  55. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  56. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  57. package/dist/engine/boot-validator/detail-screens.js +10 -4
  58. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  59. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  60. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  61. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  62. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  63. package/dist/engine/boot-validator/entity-handler.js +259 -355
  64. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  65. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  66. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  67. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  68. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  69. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  70. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  71. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  72. package/dist/engine/boot-validator/entity-select.js +197 -0
  73. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  74. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  75. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  76. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  77. package/dist/engine/boot-validator/field-conditions.js +67 -22
  78. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  79. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  80. package/dist/engine/boot-validator/form-derivations.js +52 -18
  81. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  82. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +72 -0
  83. package/dist/engine/boot-validator/handler-declaration-rules.js +72 -0
  84. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  85. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  86. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  87. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  88. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  89. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  90. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  91. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  92. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  93. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  94. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  95. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  96. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  97. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  98. package/dist/engine/boot-validator/list-table-options.js +33 -13
  99. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  100. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  101. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  102. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  103. package/dist/engine/boot-validator/nav-rules.js +42 -0
  104. package/dist/engine/boot-validator/nav.js +29 -15
  105. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  106. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  107. package/dist/engine/boot-validator/ownership.js +28 -12
  108. package/dist/engine/boot-validator/parent-ref.js +32 -20
  109. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  110. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  111. package/dist/engine/boot-validator/query-refs.js +20 -10
  112. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  113. package/dist/engine/boot-validator/query-rules.js +37 -0
  114. package/dist/engine/boot-validator/read-gate.js +14 -10
  115. package/dist/engine/boot-validator/record-owned.js +5 -1
  116. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  117. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  118. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  119. package/dist/engine/boot-validator/screens-actions.js +169 -93
  120. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  121. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  122. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  123. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  124. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  125. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  126. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  127. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  128. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  129. package/dist/engine/boot-validator/screens-forms.js +240 -112
  130. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  131. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  132. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  133. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  134. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  135. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  136. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  137. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  138. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  139. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  140. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  141. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  142. package/dist/engine/boot-validator/screens-lists.js +90 -45
  143. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  144. package/dist/engine/boot-validator/screens-rules.js +57 -0
  145. package/dist/engine/boot-validator/screens.js +17 -12
  146. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  147. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  148. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  149. package/dist/engine/boot-validator/workspaces.js +11 -5
  150. package/dist/engine/boot-validator/zod-shape.js +6 -2
  151. package/dist/engine/entity-handlers.d.ts +1 -0
  152. package/dist/engine/entity-handlers.js +3 -0
  153. package/dist/engine/entity-list-runtime-options.js +23 -29
  154. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  155. package/dist/engine/extensions/tenant-resource.d.ts +1 -0
  156. package/dist/engine/factories.d.ts +1 -1
  157. package/dist/engine/factories.js +4 -3
  158. package/dist/engine/feature-config-events-jobs.js +7 -0
  159. package/dist/engine/index.d.ts +4 -2
  160. package/dist/engine/index.js +2 -0
  161. package/dist/engine/project-app-schema-for-roles.js +29 -14
  162. package/dist/engine/registry-facade.js +7 -8
  163. package/dist/engine/registry-validate.js +5 -1
  164. package/dist/engine/soft-delete-cleanup.d.ts +1 -0
  165. package/dist/engine/soft-delete-cleanup.js +5 -0
  166. package/dist/engine/steps/describe-workflow-step-error.js +1 -0
  167. package/dist/es-ops/operations-schema.d.ts +1 -1
  168. package/dist/event-store/ensure-dead-letter-table.d.ts +2 -0
  169. package/dist/event-store/ensure-dead-letter-table.js +10 -0
  170. package/dist/event-store/rebuild-dead-letter.js +2 -8
  171. package/dist/event-store/upcaster-dead-letter.js +2 -8
  172. package/dist/files/copy-pending-file-refs-to-tenant.d.ts +28 -0
  173. package/dist/files/copy-pending-file-refs-to-tenant.js +87 -0
  174. package/dist/files/file-routes.d.ts +1 -1
  175. package/dist/files/file-routes.js +21 -6
  176. package/dist/files/index.d.ts +2 -0
  177. package/dist/files/index.js +1 -0
  178. package/dist/i18n/required-surface-keys.js +1 -0
  179. package/dist/jobs/job-runner-helpers.js +1 -0
  180. package/dist/jobs/job-runner-schedulers.d.ts +2 -2
  181. package/dist/jobs/job-runner-schedulers.js +8 -4
  182. package/dist/jobs/job-runner.js +14 -16
  183. package/dist/logging/utils.js +30 -60
  184. package/dist/observability/metrics-handle.js +10 -21
  185. package/dist/pipeline/cascade-handler.js +7 -6
  186. package/dist/pipeline/dispatch-query.js +18 -5
  187. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  188. package/dist/pipeline/dispatch-shared.js +3 -1
  189. package/dist/pipeline/dispatch-write.js +10 -12
  190. package/dist/pipeline/dispatcher.js +12 -14
  191. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  192. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  193. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  194. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  195. package/dist/pipeline/event-dispatcher.js +28 -21
  196. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  197. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  198. package/dist/pipeline/system-hooks.d.ts +4 -1
  199. package/dist/pipeline/system-hooks.js +79 -6
  200. package/dist/pipeline/system-identity-switch.js +10 -7
  201. package/dist/search/build-search-snippet.d.ts +9 -0
  202. package/dist/search/build-search-snippet.js +40 -0
  203. package/dist/search/index.d.ts +1 -0
  204. package/dist/search/index.js +1 -0
  205. package/dist/search/meilisearch-adapter.d.ts +32 -0
  206. package/dist/search/meilisearch-adapter.js +153 -56
  207. package/dist/search/meilisearch-chunking.d.ts +21 -0
  208. package/dist/search/meilisearch-chunking.js +96 -0
  209. package/dist/search/reindex-entity.d.ts +1 -0
  210. package/dist/search/reindex-entity.js +97 -52
  211. package/dist/ui-types/index.d.ts +1 -1
  212. package/dist/upgrade-cli.js +3 -14
  213. package/package.json +3 -3
  214. package/src/changes.json +85 -0
@@ -20,35 +20,31 @@ export function createFallbackLogger(namespace, logger) {
20
20
  debug: (msg, data) => child.debug(msg, data),
21
21
  };
22
22
  }
23
+ const levelLogger = (level, sinkFor) => {
24
+ return (msg, data) => {
25
+ const sink = sinkFor();
26
+ if (sink) {
27
+ sink(msg, data);
28
+ }
29
+ else {
30
+ writeConsole(console[level], `[${namespace}] ${msg}`, data);
31
+ }
32
+ };
33
+ };
23
34
  if (logger) {
35
+ const prefixedSink = (level) => {
36
+ return () => {
37
+ const write = logger[level];
38
+ return write && ((msg, data) => write.call(logger, `[${namespace}] ${msg}`, data));
39
+ };
40
+ };
24
41
  return {
25
- info(msg, data) {
26
- if (logger.info) {
27
- logger.info(`[${namespace}] ${msg}`, data);
28
- }
29
- else {
30
- writeConsole(console.info, `[${namespace}] ${msg}`, data);
31
- }
32
- },
42
+ info: levelLogger("info", prefixedSink("info")),
33
43
  error(msg, data) {
34
44
  logger.error(`[${namespace}] ${msg}`, data);
35
45
  },
36
- warn(msg, data) {
37
- if (logger.warn) {
38
- logger.warn(`[${namespace}] ${msg}`, data);
39
- }
40
- else {
41
- writeConsole(console.warn, `[${namespace}] ${msg}`, data);
42
- }
43
- },
44
- debug(msg, data) {
45
- if (logger.debug) {
46
- logger.debug(`[${namespace}] ${msg}`, data);
47
- }
48
- else {
49
- writeConsole(console.debug, `[${namespace}] ${msg}`, data);
50
- }
51
- },
46
+ warn: levelLogger("warn", prefixedSink("warn")),
47
+ debug: levelLogger("debug", prefixedSink("debug")),
52
48
  };
53
49
  }
54
50
  let cachedParent = null;
@@ -62,43 +58,17 @@ export function createFallbackLogger(namespace, logger) {
62
58
  }
63
59
  return cachedChild;
64
60
  };
65
- return {
66
- info(msg, data) {
67
- const child = resolveProcessChild();
68
- if (child) {
69
- child.info(msg, data);
70
- }
71
- else {
72
- writeConsole(console.info, `[${namespace}] ${msg}`, data);
73
- }
74
- },
75
- error(msg, data) {
61
+ const processChildSink = (level) => {
62
+ return () => {
76
63
  const child = resolveProcessChild();
77
- if (child) {
78
- child.error(msg, data);
79
- }
80
- else {
81
- writeConsole(console.error, `[${namespace}] ${msg}`, data);
82
- }
83
- },
84
- warn(msg, data) {
85
- const child = resolveProcessChild();
86
- if (child) {
87
- child.warn(msg, data);
88
- }
89
- else {
90
- writeConsole(console.warn, `[${namespace}] ${msg}`, data);
91
- }
92
- },
93
- debug(msg, data) {
94
- const child = resolveProcessChild();
95
- if (child) {
96
- child.debug(msg, data);
97
- }
98
- else {
99
- writeConsole(console.debug, `[${namespace}] ${msg}`, data);
100
- }
101
- },
64
+ return child ? (msg, data) => child[level](msg, data) : undefined;
65
+ };
66
+ };
67
+ return {
68
+ info: levelLogger("info", processChildSink("info")),
69
+ error: levelLogger("error", processChildSink("error")),
70
+ warn: levelLogger("warn", processChildSink("warn")),
71
+ debug: levelLogger("debug", processChildSink("debug")),
102
72
  };
103
73
  }
104
74
  // A full Logger for contexts whose typed surface promises one (ctx.obs.log) but that have no
@@ -50,28 +50,17 @@ function tryBuildMetricName(featureName, shortName) {
50
50
  }
51
51
  }
52
52
  export function createSafeMetricsHandle(meter, featureName) {
53
+ const ifRegistered = (shortName, record) => {
54
+ const name = tryBuildMetricName(featureName, shortName);
55
+ // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
56
+ if (name === undefined || !meter.definitions().has(name))
57
+ return;
58
+ record(name);
59
+ };
53
60
  return {
54
- inc(shortName, labels, value) {
55
- const name = tryBuildMetricName(featureName, shortName);
56
- // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
57
- if (name === undefined || !meter.definitions().has(name))
58
- return;
59
- meter.counter(name).inc(value, labels);
60
- },
61
- observe(shortName, value, labels) {
62
- const name = tryBuildMetricName(featureName, shortName);
63
- // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
64
- if (name === undefined || !meter.definitions().has(name))
65
- return;
66
- meter.histogram(name).observe(value, labels);
67
- },
68
- set(shortName, value, labels) {
69
- const name = tryBuildMetricName(featureName, shortName);
70
- // skip: invalid featureName or unregistered name are the documented no-op contract of this handle
71
- if (name === undefined || !meter.definitions().has(name))
72
- return;
73
- meter.gauge(name).set(value, labels);
74
- },
61
+ inc: (shortName, labels, value) => ifRegistered(shortName, (name) => meter.counter(name).inc(value, labels)),
62
+ observe: (shortName, value, labels) => ifRegistered(shortName, (name) => meter.histogram(name).observe(value, labels)),
63
+ set: (shortName, value, labels) => ifRegistered(shortName, (name) => meter.gauge(name).set(value, labels)),
75
64
  };
76
65
  }
77
66
  // Fallback for contexts where the feature is unknown (e.g. system-hooks,
@@ -116,15 +116,16 @@ const THROUGH_ON_DELETE = {
116
116
  cascade: deleteThroughRows,
117
117
  setNull: leaveChildrenUnchanged,
118
118
  };
119
- async function rejectReferencedParent(run, link) {
120
- const row = await fetchOne(run.db, link.table, { [link.foreignKey]: run.parentId });
119
+ async function rejectIfReferenced(run, table, key, blockingEntity) {
120
+ const row = await fetchOne(run.db, table, { [key]: run.parentId });
121
121
  if (row)
122
- throw deleteRestrictedError(run, link.target);
122
+ throw deleteRestrictedError(run, blockingEntity);
123
+ }
124
+ async function rejectReferencedParent(run, link) {
125
+ await rejectIfReferenced(run, link.table, link.foreignKey, link.target);
123
126
  }
124
127
  async function rejectReferencedThroughRows(run, link) {
125
- const row = await fetchOne(run.db, link.table, { [link.sourceKey]: run.parentId });
126
- if (row)
127
- throw deleteRestrictedError(run, link.throughTable);
128
+ await rejectIfReferenced(run, link.table, link.sourceKey, link.throughTable);
128
129
  }
129
130
  function deleteRestrictedError(run, blockingEntity) {
130
131
  return new ConflictError({
@@ -3,7 +3,7 @@ import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards
3
3
  import { hasAccess } from "../engine/access.js";
4
4
  import { tenantOverrideDenied } from "../engine/cross-tenant.js";
5
5
  import { filterReadFields } from "../engine/field-access.js";
6
- import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
6
+ import { NotFoundError, ValidationError, validationErrorFromZod } from "../errors/index.js";
7
7
  import { assertNoSecretLeak } from "../secrets/leak-guard.js";
8
8
  import { runInDispatchScope } from "./dispatch-scope.js";
9
9
  import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
@@ -53,16 +53,29 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx, outerNoti
53
53
  // so other handlers never see the flag. Visibility filters still apply
54
54
  // downstream (see HandlerContext.includeDeleted) — safe from raw input.
55
55
  const includeDeleted = propertyOf(parsed.data, "includeDeleted") === true;
56
+ const onlyDeleted = propertyOf(parsed.data, "onlyDeleted") === true;
57
+ if (includeDeleted && onlyDeleted) {
58
+ throw new ValidationError({
59
+ fields: [
60
+ {
61
+ path: "onlyDeleted",
62
+ code: "conflicts_with_include_deleted",
63
+ i18nKey: "errors.validation.onlyDeleted",
64
+ },
65
+ ],
66
+ });
67
+ }
68
+ const trash = { includeDeleted, onlyDeleted };
56
69
  // A resolved member (ctx.dispatch.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
57
70
  return isMemberResolutionPrincipal(user)
58
- ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))
59
- : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx, outerNotifySink);
71
+ ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, trash, user, origin, readOnlyTx))
72
+ : runQueryHandler(ctx, type, handler, parsed.data, trash, user, origin, tx, outerNotifySink);
60
73
  }
61
- async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user, origin, tx, outerNotifySink) {
74
+ async function runQueryHandler(ctx, type, handler, payload, trash, user, origin, tx, outerNotifySink) {
62
75
  const { registry } = ctx;
63
76
  const handlerContext = await buildHandlerContext(ctx, type, user, origin, {
64
77
  tx,
65
- includeDeleted,
78
+ ...trash,
66
79
  outerNotifySink,
67
80
  });
68
81
  let result = await handler.handler({ type, payload, user }, handlerContext);
@@ -63,6 +63,7 @@ export type BuildHandlerContextOptions = {
63
63
  tx?: DbTx;
64
64
  afterCommitHooks?: AfterCommitHook[];
65
65
  includeDeleted?: boolean;
66
+ onlyDeleted?: boolean;
66
67
  transactionScope?: HandlerTransactionScope;
67
68
  outerNotifySink?: AfterCommitHook[];
68
69
  phase?: HandlerPhase;
@@ -74,7 +74,7 @@ export function isMemberResolutionPrincipal(user) {
74
74
  return user.origin === "member-resolution";
75
75
  }
76
76
  export async function buildHandlerContext(ctx, type, user, origin, options = {}) {
77
- const { tx, afterCommitHooks, includeDeleted, outerNotifySink, phase = "handler", transactionScope = tx ? "inTransaction" : "withoutTransaction", } = options;
77
+ const { tx, afterCommitHooks, includeDeleted, onlyDeleted, outerNotifySink, phase = "handler", transactionScope = tx ? "inTransaction" : "withoutTransaction", } = options;
78
78
  const readOnlyForTenant = phase === "beforeTransaction";
79
79
  const scope = resolveHandlerContextScope({ ctx, type, user, origin, tx, transactionScope });
80
80
  const dbFacet = buildHandlerDbFacet(scope);
@@ -133,6 +133,7 @@ export async function buildHandlerContext(ctx, type, user, origin, options = {})
133
133
  // ctx.user as a convenience alias for event.user. Identity switches still use queryAs/writeAs.
134
134
  user,
135
135
  ...(includeDeleted && { includeDeleted: true }),
136
+ ...(onlyDeleted && { onlyDeleted: true }),
136
137
  dispatch: dispatchFacet.dispatch,
137
138
  events: eventStoreFacet.events,
138
139
  auth: authFacet.auth,
@@ -533,6 +534,7 @@ function buildAuthClaimsContext(ctx, user) {
533
534
  ...(configAccessor && { config: configAccessor }),
534
535
  };
535
536
  }
537
+ // guard:dup-ok the single runInSystemRowLevelSecurityScope call with this entry point's own reason
536
538
  export function resolveAuthClaimsFn(ctx, user) {
537
539
  return runInSystemRowLevelSecurityScope("auth claims resolution reads memberships before a tenant is known", () => resolveAuthClaimsInScope(ctx, user));
538
540
  }
@@ -118,6 +118,14 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
118
118
  return;
119
119
  }
120
120
  const result = data;
121
+ const queueAfterCommit = (run) => {
122
+ afterCommitHooks.push(async () => {
123
+ const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, {
124
+ transactionScope: "postCommit",
125
+ });
126
+ await run(afterCommitContext);
127
+ });
128
+ };
121
129
  // Projections run FIRST, inside the tx, before any user postSave/postDelete
122
130
  // hooks. If a projection apply() throws, the whole tx rolls back — the
123
131
  // event and the auto-projection row go with it. Running before the hooks
@@ -126,22 +134,12 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
126
134
  if (result.kind === "save") {
127
135
  await settleSaveFileRefs(handlerContext, result, user);
128
136
  await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
129
- afterCommitHooks.push(async () => {
130
- const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, {
131
- transactionScope: "postCommit",
132
- });
133
- await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
134
- });
137
+ queueAfterCommit((afterCommitContext) => lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit));
135
138
  }
136
139
  else if (result.kind === "delete") {
137
140
  await lifecycle.runPreDelete(type, result, handlerContext);
138
141
  await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
139
- afterCommitHooks.push(async () => {
140
- const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, {
141
- transactionScope: "postCommit",
142
- });
143
- await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
144
- });
142
+ queueAfterCommit((afterCommitContext) => lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit));
145
143
  }
146
144
  }
147
145
  // Shared write pipeline: validates, executes handler, runs lifecycle + side effects.
@@ -15,6 +15,15 @@ import { createMemberReaderFn } from "./member-reader.js";
15
15
  import { createTenantTimezoneCache } from "./tenant-timezone-cache.js";
16
16
  import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
17
17
  const dispatcherInternals = new WeakMap();
18
+ function originAwareInternalsOrThrow(internals, method, qn) {
19
+ if (!internals) {
20
+ throw new InternalError({
21
+ message: `JobContext.${method}("${qn}") carries a gated origin but this dispatcher has no ` +
22
+ "registered origin-aware internals — refusing to fall open to the ungated path.",
23
+ });
24
+ }
25
+ return internals;
26
+ }
18
27
  // Adapts Dispatcher's (type, payload, user) call shape to DispatchWriteRef's
19
28
  // (user, qn, payload) — JobRunner.attachDispatcher needs the latter.
20
29
  export function dispatcherToWriteRef(dispatcher) {
@@ -22,25 +31,14 @@ export function dispatcherToWriteRef(dispatcher) {
22
31
  return {
23
32
  write: (user, qn, payload, inheritedOrigin) => {
24
33
  if (inheritedOrigin && isPersonalDataGated(inheritedOrigin)) {
25
- if (!internals) {
26
- throw new InternalError({
27
- message: `JobContext.write("${qn}") carries a gated origin but this dispatcher has no ` +
28
- "registered origin-aware internals — refusing to fall open to the ungated path.",
29
- });
30
- }
31
- return internals.writeWithOrigin(qn, payload, user, inheritedOrigin);
34
+ return originAwareInternalsOrThrow(internals, "write", qn).writeWithOrigin(qn, payload, user, inheritedOrigin);
32
35
  }
33
36
  return dispatcher.write(qn, payload, user);
34
37
  },
38
+ // guard:dup-ok query twin of write; the gate is shared via originAwareInternalsOrThrow, the return types differ
35
39
  queryAs: (user, qn, payload, inheritedOrigin) => {
36
40
  if (inheritedOrigin && isPersonalDataGated(inheritedOrigin)) {
37
- if (!internals) {
38
- throw new InternalError({
39
- message: `JobContext.queryAs("${qn}") carries a gated origin but this dispatcher has no ` +
40
- "registered origin-aware internals — refusing to fall open to the ungated path.",
41
- });
42
- }
43
- return internals.queryWithOrigin(qn, payload, user, inheritedOrigin);
41
+ return originAwareInternalsOrThrow(internals, "queryAs", qn).queryWithOrigin(qn, payload, user, inheritedOrigin);
44
42
  }
45
43
  return dispatcher.query(qn, payload, user);
46
44
  },
@@ -75,23 +75,24 @@ async function applyConsumerStatusTransition(db, name, instanceId, targetStatus)
75
75
  }
76
76
  return normalizeConsumerState(updated);
77
77
  }
78
- export async function restartConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
78
+ const RESTART_WRONG_STATUS_HINT = 'Restart only applies to dead consumers; use "enable" for a disabled one.';
79
+ const ENABLE_WRONG_STATUS_HINT = 'Enable only flips disabled → idle; use "restart" for a dead consumer.';
80
+ async function returnConsumerToIdleFrom(db, name, instanceId, requiredStatus, wrongStatusHint) {
79
81
  const before = await requireConsumerRow(db, name, instanceId);
80
- if (before.status !== "dead") {
81
- throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`);
82
+ if (before.status !== requiredStatus) {
83
+ throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is not ${requiredStatus} (status="${before.status}"). ${wrongStatusHint}`);
82
84
  }
83
85
  return applyConsumerStatusTransition(db, name, instanceId, "idle");
84
86
  }
87
+ export async function restartConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
88
+ return returnConsumerToIdleFrom(db, name, instanceId, "dead", RESTART_WRONG_STATUS_HINT);
89
+ }
85
90
  export async function disableConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
86
91
  await requireConsumerRow(db, name, instanceId);
87
92
  return applyConsumerStatusTransition(db, name, instanceId, "disabled");
88
93
  }
89
94
  export async function enableConsumer(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
90
- const before = await requireConsumerRow(db, name, instanceId);
91
- if (before.status !== "disabled") {
92
- throw new ConsumerTransitionError("wrong-status", `Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`);
93
- }
94
- return applyConsumerStatusTransition(db, name, instanceId, "idle");
95
+ return returnConsumerToIdleFrom(db, name, instanceId, "disabled", ENABLE_WRONG_STATUS_HINT);
95
96
  }
96
97
  // A pool connection opens its own transaction; inside a handler transaction the
97
98
  // locked read and writes join it, confined to a savepoint.
@@ -52,7 +52,8 @@ export declare function selectIdleConsumerKeys(db: DbConnection, pairs: Readonly
52
52
  export declare function preRegisterConsumers(db: DbConnection, consumers: readonly EventConsumer[], dispatcherInstanceId: string | undefined): Promise<void>;
53
53
  export declare function consumerInstanceId(consumer: EventConsumer, dispatcherInstanceId: string | undefined): string;
54
54
  export declare function markProcessing(tx: DbTx, name: string, instanceId: string): Promise<void>;
55
- export declare function fetchPendingEvents(tx: DbTx, cursor: bigint, batchSize: number, pendingRanges?: readonly PendingIdRange[]): Promise<ReadonlyArray<StoredEventRow>>;
55
+ export declare function fetchPendingEvents(tx: DbTx, cursor: bigint, batchSize: number, pendingRanges?: readonly PendingIdRange[], pendingLimit?: number): Promise<ReadonlyArray<StoredEventRow>>;
56
+ export declare function pendingFetchLimit(consumer: EventConsumer, batchSize: number): number;
56
57
  export type DeliveryOutcome = {
57
58
  readonly cursor: bigint;
58
59
  readonly attempts: number;
@@ -62,8 +63,25 @@ export type DeliveryOutcome = {
62
63
  readonly failed: number;
63
64
  readonly failedEventId: bigint | null;
64
65
  readonly resolvedPendingIds: readonly bigint[];
66
+ readonly heldNewIds: readonly bigint[];
65
67
  };
66
68
  export declare function deliverEvents(consumer: EventConsumer, events: ReadonlyArray<StoredEventRow>, context: AppContext, maxAttempts: number, state: ConsumerStateRow): Promise<DeliveryOutcome>;
69
+ export type ConsumerTurnInput = {
70
+ readonly tx: DbTx;
71
+ readonly consumer: EventConsumer;
72
+ readonly events: ReadonlyArray<StoredEventRow>;
73
+ readonly state: ConsumerStateRow;
74
+ readonly context: AppContext;
75
+ readonly maxAttempts: number;
76
+ readonly pendingRanges: readonly PendingIdRange[];
77
+ readonly pendingLimit: number;
78
+ readonly pendingGapCount: number;
79
+ readonly maxPendingGapRanges: number;
80
+ };
81
+ export declare function deliverConsumerTurn(input: ConsumerTurnInput): Promise<{
82
+ readonly deliverable: ReadonlyArray<StoredEventRow>;
83
+ readonly outcome: DeliveryOutcome;
84
+ }>;
67
85
  export type PersistedConsumerOutcome = DeliveryOutcome & {
68
86
  readonly pendingGaps: readonly PendingGapEntry[];
69
87
  };
@@ -2,7 +2,7 @@
2
2
  import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
3
3
  import { requestContext } from "../api/request-context.js";
4
4
  import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
5
- import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries/event-store.js";
5
+ import { selectEventsHeadId, selectPendingAndNewEventRows, selectTenantIdsInRangesAbove, } from "../db/queries/event-store.js";
6
6
  import { coerceRow } from "../db/query.js";
7
7
  import { extractTableInfo } from "../db/table-info.js";
8
8
  import { qnScope } from "../engine/qualified-name.js";
@@ -145,11 +145,36 @@ export async function markProcessing(tx, name, instanceId) {
145
145
  // processConsumer). Fetching them alongside the plain `id > cursor` window
146
146
  // means a row that committed late becomes visible and deliverable the next
147
147
  // time this consumer's turn runs, instead of being permanently skipped.
148
- export async function fetchPendingEvents(tx, cursor, batchSize, pendingRanges = []) {
149
- const rawRows = await selectPendingAndNewEventRows(tx, cursor, pendingRanges, batchSize);
148
+ export async function fetchPendingEvents(tx, cursor, batchSize, pendingRanges = [], pendingLimit = batchSize) {
149
+ const rawRows = await selectPendingAndNewEventRows(tx, cursor, pendingRanges, batchSize, pendingLimit);
150
150
  const info = extractTableInfo(eventsTable);
151
151
  return rawRows.map((row) => coerceRow(row, info));
152
152
  }
153
+ // Pending ids of a batch consumer get at most half the batch: a batch handler that keeps
154
+ // holding events must not starve every newer event of the consumer. Per-event consumers never
155
+ // hold, so their pending ids are late commits that drain on their own and keep the full batch.
156
+ export function pendingFetchLimit(consumer, batchSize) {
157
+ if (!consumer.batchHandler)
158
+ return batchSize;
159
+ return Math.max(1, Math.floor(batchSize / 2));
160
+ }
161
+ // When the pending part of a batch consumer's fetch was capped, newer events of a tenant with
162
+ // pending events left out of it are withheld this turn; they fall between delivered ids and so
163
+ // become pending gaps themselves. No consumer sees a tenant's event before an older one it is
164
+ // still holding.
165
+ async function withholdNewEventsOfTenantsWithUnfetchedPending(tx, consumer, events, cursor, pendingRanges, pendingLimit) {
166
+ if (!consumer.batchHandler)
167
+ return events;
168
+ const pendingIds = events.filter((event) => event.id <= cursor).map((event) => event.id);
169
+ const lastPendingId = pendingIds.at(-1);
170
+ if (lastPendingId === undefined || pendingIds.length < pendingLimit) {
171
+ return events;
172
+ }
173
+ const tenantsLeftOut = await selectTenantIdsInRangesAbove(tx, pendingRanges, lastPendingId);
174
+ if (tenantsLeftOut.size === 0)
175
+ return events;
176
+ return events.filter((event) => event.id <= cursor || !tenantsLeftOut.has(event.tenantId));
177
+ }
153
178
  // Deliver events to the consumer's handler in events.id order, or — when
154
179
  // the consumer wires a batchHandler — through it in one call first. Halt-
155
180
  // on-poison: a throw breaks the per-event loop, the cursor stays at the
@@ -181,22 +206,9 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
181
206
  lastError = null;
182
207
  };
183
208
  if (consumer.batchHandler && events.length > 0) {
184
- const batchSucceeded = await tryApplyBatch(consumer, events, context);
185
- if (batchSucceeded) {
186
- for (const row of events)
187
- resolve(row.id);
188
- processed = events.length;
189
- return {
190
- cursor,
191
- attempts,
192
- lastError,
193
- deadLettered,
194
- processed,
195
- failed,
196
- failedEventId,
197
- resolvedPendingIds,
198
- };
199
- }
209
+ const batch = await tryApplyBatch(consumer, events, context);
210
+ if (batch.applied)
211
+ return outcomeOfAppliedBatch(events, state, batch);
200
212
  // fall through to the per-event loop below; the batch failure itself
201
213
  // does NOT bump attempts — only a per-event failure does.
202
214
  }
@@ -233,6 +245,82 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
233
245
  failed,
234
246
  failedEventId,
235
247
  resolvedPendingIds,
248
+ heldNewIds: [],
249
+ };
250
+ }
251
+ // Only a batch consumer that holds events can pile up pending gaps faster than they burn: a
252
+ // tenant stuck for days leaves one range per run of its events between other tenants' events.
253
+ // Past the limit the consumer takes no new events, so the set cannot grow, and a pass that
254
+ // delivers nothing counts as a failed attempt. That ends in the existing dead, rearm and
255
+ // rearm-exhausted path instead of an unbounded cursor row; every tenant then waits.
256
+ function isIntakePausedByPendingGapLimit(consumer, pendingGapCount, maxPendingGapRanges) {
257
+ return consumer.batchHandler !== undefined && pendingGapCount >= maxPendingGapRanges;
258
+ }
259
+ // Skipping the first held event frees one range only and the next pass is back at the limit,
260
+ // so the message points at the held tenant, whose index has to be fixed.
261
+ function escalateIntakePausedOutcome(outcome, state, deliverable, pendingGapCount, maxPendingGapRanges, effectiveMaxAttempts) {
262
+ const firstHeld = outcome.failedEventId ?? state.lastFailedEventId;
263
+ const heldTenant = deliverable.find((event) => event.id === firstHeld)?.tenantId ?? "unknown";
264
+ const lastError = `${pendingGapCount} pending gap ranges reached the limit of ${maxPendingGapRanges}; ` +
265
+ `no new events are taken until the held events of tenant ${heldTenant} drain ` +
266
+ `(first held event ${firstHeld ?? "unknown"})`;
267
+ if (outcome.processed > 0)
268
+ return { ...outcome, lastError };
269
+ const attempts = state.attempts + 1;
270
+ return {
271
+ ...outcome,
272
+ attempts,
273
+ lastError,
274
+ failedEventId: firstHeld,
275
+ deadLettered: attempts >= effectiveMaxAttempts,
276
+ };
277
+ }
278
+ export async function deliverConsumerTurn(input) {
279
+ const { tx, consumer, events, state, context, maxAttempts } = input;
280
+ const cursor = state.lastProcessedEventId;
281
+ const intakePaused = isIntakePausedByPendingGapLimit(consumer, input.pendingGapCount, input.maxPendingGapRanges);
282
+ const withheld = await withholdNewEventsOfTenantsWithUnfetchedPending(tx, consumer, events, cursor, input.pendingRanges, input.pendingLimit);
283
+ const deliverable = intakePaused ? withheld.filter((event) => event.id <= cursor) : withheld;
284
+ const delivered = deliverable.length > 0
285
+ ? await deliverEvents(consumer, deliverable, context, maxAttempts, state)
286
+ : {
287
+ cursor,
288
+ attempts: state.attempts,
289
+ lastError: state.lastError,
290
+ deadLettered: false,
291
+ processed: 0,
292
+ failed: 0,
293
+ failedEventId: state.lastFailedEventId,
294
+ resolvedPendingIds: [],
295
+ heldNewIds: [],
296
+ };
297
+ const outcome = intakePaused
298
+ ? escalateIntakePausedOutcome(delivered, state, deliverable, input.pendingGapCount, input.maxPendingGapRanges, consumer.errorPolicy?.maxAttempts ?? maxAttempts)
299
+ : delivered;
300
+ return { deliverable, outcome };
301
+ }
302
+ // Held rows count as failed and leave lastError set, but the cursor still moves past them:
303
+ // the caller turns the new ones into pending gaps.
304
+ function outcomeOfAppliedBatch(events, state, batch) {
305
+ const startCursor = state.lastProcessedEventId;
306
+ const isHeld = (row) => batch.held.has(String(row.id));
307
+ const deliveredIds = events.filter((row) => !isHeld(row)).map((row) => row.id);
308
+ const heldIds = events.filter(isHeld).map((row) => row.id);
309
+ const newIds = events.map((row) => row.id).filter((id) => id > startCursor);
310
+ const anyDelivered = deliveredIds.length > 0;
311
+ let lastError = anyDelivered ? null : (state.lastError ?? null);
312
+ if (heldIds.length > 0 && batch.heldReason !== null)
313
+ lastError = batch.heldReason;
314
+ return {
315
+ cursor: newIds.at(-1) ?? startCursor,
316
+ attempts: anyDelivered ? 0 : state.attempts,
317
+ lastError,
318
+ deadLettered: false,
319
+ processed: deliveredIds.length,
320
+ failed: heldIds.length,
321
+ failedEventId: heldIds[0] ?? null,
322
+ resolvedPendingIds: deliveredIds.filter((id) => id <= startCursor),
323
+ heldNewIds: heldIds.filter((id) => id > startCursor),
236
324
  };
237
325
  }
238
326
  // Shared requestContext scope for one apply — event-derived fields
@@ -267,23 +355,27 @@ async function applyEvent(consumer, row, context) {
267
355
  await consumer.handler(stored, context);
268
356
  });
269
357
  }
270
- // Runs the consumer's batchHandler for the whole turn under one
271
- // requestContext scope, attempted before the per-event loop. Returns
272
- // false on failure instead of rethrowing — the caller falls back to
273
- // per-event delivery for the exact same events, so a batch failure must
274
- // not itself count as an applyEvent failure or bump attempts.
275
358
  async function tryApplyBatch(consumer, events, context) {
359
+ const held = new Set();
360
+ let heldReason = null;
361
+ const turn = {
362
+ holdForRetry: (eventIds, reason) => {
363
+ for (const id of eventIds)
364
+ held.add(id);
365
+ heldReason ??= reason;
366
+ },
367
+ };
276
368
  try {
277
- await applyBatch(consumer, events, context);
278
- return true;
369
+ await applyBatch(consumer, events, context, turn);
370
+ return { applied: true, held, heldReason };
279
371
  }
280
372
  catch (e) {
281
373
  const errMessage = e instanceof Error ? e.message : String(e);
282
374
  context.log?.warn(`event-dispatcher: ${consumer.name} batch of ${events.length} failed, falling back to per-event delivery: ${errMessage}`);
283
- return false;
375
+ return { applied: false };
284
376
  }
285
377
  }
286
- async function applyBatch(consumer, events, context) {
378
+ async function applyBatch(consumer, events, context, turn) {
287
379
  const batchHandler = consumer.batchHandler;
288
380
  // skip: deliverEvents only calls this for consumers that wire a batchHandler.
289
381
  if (!batchHandler)
@@ -298,7 +390,7 @@ async function applyBatch(consumer, events, context) {
298
390
  if (!lastStored)
299
391
  return;
300
392
  await requestContext.run(buildConsumerRequestScope(consumer, lastStored), async () => {
301
- await batchHandler(stored, context);
393
+ await batchHandler(stored, context, turn);
302
394
  });
303
395
  }
304
396
  // Best-effort mode: record the error on the skip counter so ops can alert on
@@ -3,7 +3,10 @@ import type { PgListenClient } from "../db/connection.ts";
3
3
  import type { AppContext } from "../engine/types/index.ts";
4
4
  import type { StoredEvent } from "../event-store/index.ts";
5
5
  export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
6
- export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: AppContext) => Promise<void>;
6
+ export type EventConsumerBatchHandler = (events: readonly StoredEvent[], ctx: AppContext, turn: BatchTurnControl) => Promise<void>;
7
+ export type BatchTurnControl = {
8
+ readonly holdForRetry: (eventIds: readonly string[], reason: string) => void;
9
+ };
7
10
  export type EventConsumerErrorPolicy = {
8
11
  readonly skipApplyErrors?: boolean;
9
12
  readonly maxAttempts?: number;
@@ -44,6 +47,7 @@ export type EventDispatcherOptions = {
44
47
  readonly maxAttempts?: number;
45
48
  readonly rearmCooldownMs?: number;
46
49
  readonly maxRearmCount?: number;
50
+ readonly maxPendingGapRanges?: number;
47
51
  readonly tracer?: Tracer;
48
52
  readonly meter?: Meter;
49
53
  readonly instanceId?: string;