@cosmicdrift/kumiko-framework 0.406.0 → 0.410.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 (212) hide show
  1. package/AGENTS.md +4 -2
  2. package/agents/api/framework-db.md +1 -0
  3. package/agents/api/framework-engine.md +17 -2
  4. package/agents/api/framework-ui-types.md +15 -0
  5. package/agents/api/renderer-web.md +156 -2
  6. package/agents/api/types.md +113 -71
  7. package/agents/api.md +4 -4
  8. package/agents/boot-rules.md +744 -0
  9. package/agents/examples/anonymous-access.md +23 -1
  10. package/agents/examples/contact.md +173 -0
  11. package/agents/examples/delivery-notifications.md +34 -1
  12. package/agents/examples/record-detail-layout.md +13 -2
  13. package/agents/examples/search.md +65 -3
  14. package/agents/examples/secrets-demo.md +96 -2
  15. package/agents/examples/tenant-inactivity.md +138 -0
  16. package/agents/examples.md +2 -0
  17. package/agents/features-index.md +4 -0
  18. package/agents/features.md +25 -1
  19. package/agents/widgets.md +12 -1
  20. package/dist/api/export/export-rows.js +1 -0
  21. package/dist/compliance/index.d.ts +1 -1
  22. package/dist/db/event-store-executor-read-where.js +15 -5
  23. package/dist/db/index.d.ts +1 -1
  24. package/dist/db/index.js +1 -1
  25. package/dist/db/migrate-generator.js +3 -1
  26. package/dist/db/queries/event-consumer.js +11 -7
  27. package/dist/db/queries/event-store.d.ts +2 -1
  28. package/dist/db/queries/event-store.js +25 -6
  29. package/dist/db/queries/rls-boot-catalog.js +3 -1
  30. package/dist/db/queries/session-advisory-lock.d.ts +7 -0
  31. package/dist/db/queries/session-advisory-lock.js +23 -0
  32. package/dist/db/query.js +7 -10
  33. package/dist/db/row-level-security-connection.js +4 -2
  34. package/dist/engine/access.js +5 -1
  35. package/dist/engine/active-membership.js +1 -0
  36. package/dist/engine/boot-validator/access-declarations.js +76 -33
  37. package/dist/engine/boot-validator/action-wiring.js +8 -6
  38. package/dist/engine/boot-validator/agent-effect-rules.d.ts +12 -0
  39. package/dist/engine/boot-validator/agent-effect-rules.js +12 -0
  40. package/dist/engine/boot-validator/agent-effect.d.ts +2 -0
  41. package/dist/engine/boot-validator/agent-effect.js +20 -0
  42. package/dist/engine/boot-validator/boot-context.js +5 -1
  43. package/dist/engine/boot-validator/boot-environment-rules.d.ts +12 -0
  44. package/dist/engine/boot-validator/boot-environment-rules.js +12 -0
  45. package/dist/engine/boot-validator/boot-phases-app.js +5 -1
  46. package/dist/engine/boot-validator/boot-phases.js +3 -1
  47. package/dist/engine/boot-validator/boot-rules.d.ts +2624 -0
  48. package/dist/engine/boot-validator/boot-rules.js +58 -0
  49. package/dist/engine/boot-validator/bundled-lists-table.js +23 -9
  50. package/dist/engine/boot-validator/config-deps.js +71 -23
  51. package/dist/engine/boot-validator/config-edit-action-rules.d.ts +17 -0
  52. package/dist/engine/boot-validator/config-edit-action-rules.js +17 -0
  53. package/dist/engine/boot-validator/config-key-rules.d.ts +117 -0
  54. package/dist/engine/boot-validator/config-key-rules.js +117 -0
  55. package/dist/engine/boot-validator/custom-screen-write-qns.js +6 -2
  56. package/dist/engine/boot-validator/derived-sql-fields-rules.d.ts +77 -0
  57. package/dist/engine/boot-validator/derived-sql-fields-rules.js +77 -0
  58. package/dist/engine/boot-validator/derived-sql-fields.js +53 -17
  59. package/dist/engine/boot-validator/detail-screens.js +10 -4
  60. package/dist/engine/boot-validator/entity-declaration-rules.d.ts +92 -0
  61. package/dist/engine/boot-validator/entity-declaration-rules.js +92 -0
  62. package/dist/engine/boot-validator/entity-handler-access-rules.d.ts +102 -0
  63. package/dist/engine/boot-validator/entity-handler-access-rules.js +102 -0
  64. package/dist/engine/boot-validator/entity-handler.d.ts +0 -7
  65. package/dist/engine/boot-validator/entity-handler.js +259 -355
  66. package/dist/engine/boot-validator/entity-image-variants.d.ts +2 -0
  67. package/dist/engine/boot-validator/entity-image-variants.js +91 -0
  68. package/dist/engine/boot-validator/entity-list-aggregate-options.js +8 -2
  69. package/dist/engine/boot-validator/entity-reference-embedded-rules.d.ts +117 -0
  70. package/dist/engine/boot-validator/entity-reference-embedded-rules.js +117 -0
  71. package/dist/engine/boot-validator/entity-select-image-rules.d.ts +122 -0
  72. package/dist/engine/boot-validator/entity-select-image-rules.js +122 -0
  73. package/dist/engine/boot-validator/entity-select.d.ts +8 -0
  74. package/dist/engine/boot-validator/entity-select.js +197 -0
  75. package/dist/engine/boot-validator/entity-structure-rules.d.ts +107 -0
  76. package/dist/engine/boot-validator/entity-structure-rules.js +107 -0
  77. package/dist/engine/boot-validator/field-conditions-rules.d.ts +92 -0
  78. package/dist/engine/boot-validator/field-conditions-rules.js +92 -0
  79. package/dist/engine/boot-validator/field-conditions.js +67 -22
  80. package/dist/engine/boot-validator/form-derivations-rules.d.ts +77 -0
  81. package/dist/engine/boot-validator/form-derivations-rules.js +77 -0
  82. package/dist/engine/boot-validator/form-derivations.js +52 -18
  83. package/dist/engine/boot-validator/global-tenancy.js +13 -7
  84. package/dist/engine/boot-validator/handler-declaration-rules.d.ts +77 -0
  85. package/dist/engine/boot-validator/handler-declaration-rules.js +77 -0
  86. package/dist/engine/boot-validator/handler-field-references-rules.d.ts +22 -0
  87. package/dist/engine/boot-validator/handler-field-references-rules.js +22 -0
  88. package/dist/engine/boot-validator/handler-field-references.js +14 -6
  89. package/dist/engine/boot-validator/list-bulk-actions-rules.d.ts +42 -0
  90. package/dist/engine/boot-validator/list-bulk-actions-rules.js +42 -0
  91. package/dist/engine/boot-validator/list-bulk-actions.js +29 -11
  92. package/dist/engine/boot-validator/list-column-layout.js +22 -10
  93. package/dist/engine/boot-validator/list-query-rules.d.ts +107 -0
  94. package/dist/engine/boot-validator/list-query-rules.js +107 -0
  95. package/dist/engine/boot-validator/list-table-aggregate-options.js +43 -15
  96. package/dist/engine/boot-validator/list-table-aggregate-query.js +7 -3
  97. package/dist/engine/boot-validator/list-table-aggregate-rules.d.ts +82 -0
  98. package/dist/engine/boot-validator/list-table-aggregate-rules.js +82 -0
  99. package/dist/engine/boot-validator/list-table-export-options.js +19 -7
  100. package/dist/engine/boot-validator/list-table-options.js +33 -13
  101. package/dist/engine/boot-validator/list-table-reject-unknown-keys.js +6 -2
  102. package/dist/engine/boot-validator/list-table-rules.d.ts +132 -0
  103. package/dist/engine/boot-validator/list-table-rules.js +132 -0
  104. package/dist/engine/boot-validator/nav-rules.d.ts +42 -0
  105. package/dist/engine/boot-validator/nav-rules.js +42 -0
  106. package/dist/engine/boot-validator/nav.js +33 -17
  107. package/dist/engine/boot-validator/ownership-rules.d.ts +27 -0
  108. package/dist/engine/boot-validator/ownership-rules.js +27 -0
  109. package/dist/engine/boot-validator/ownership.js +28 -12
  110. package/dist/engine/boot-validator/parent-ref.js +32 -20
  111. package/dist/engine/boot-validator/projection-list-screens.js +76 -35
  112. package/dist/engine/boot-validator/query-output-columns.js +9 -3
  113. package/dist/engine/boot-validator/query-refs.js +20 -10
  114. package/dist/engine/boot-validator/query-rules.d.ts +37 -0
  115. package/dist/engine/boot-validator/query-rules.js +37 -0
  116. package/dist/engine/boot-validator/read-gate.js +14 -10
  117. package/dist/engine/boot-validator/record-owned.js +5 -1
  118. package/dist/engine/boot-validator/related-list-table-rules.js +17 -7
  119. package/dist/engine/boot-validator/screens-actions-rules.d.ts +185 -0
  120. package/dist/engine/boot-validator/screens-actions-rules.js +185 -0
  121. package/dist/engine/boot-validator/screens-actions.js +169 -93
  122. package/dist/engine/boot-validator/screens-dashboard-chart-rules.d.ts +87 -0
  123. package/dist/engine/boot-validator/screens-dashboard-chart-rules.js +87 -0
  124. package/dist/engine/boot-validator/screens-dashboard-rules.d.ts +227 -0
  125. package/dist/engine/boot-validator/screens-dashboard-rules.js +227 -0
  126. package/dist/engine/boot-validator/screens-dashboard.js +222 -85
  127. package/dist/engine/boot-validator/screens-forms-layout-rules.d.ts +122 -0
  128. package/dist/engine/boot-validator/screens-forms-layout-rules.js +122 -0
  129. package/dist/engine/boot-validator/screens-forms-rules.d.ts +152 -0
  130. package/dist/engine/boot-validator/screens-forms-rules.js +152 -0
  131. package/dist/engine/boot-validator/screens-forms.js +240 -112
  132. package/dist/engine/boot-validator/screens-kind-config-edit.js +72 -16
  133. package/dist/engine/boot-validator/screens-kind-entity-edit.js +15 -7
  134. package/dist/engine/boot-validator/screens-kind-entity-list.js +57 -32
  135. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.d.ts +92 -0
  136. package/dist/engine/boot-validator/screens-kind-projection-detail-rules.js +92 -0
  137. package/dist/engine/boot-validator/screens-kind-projection-detail.js +85 -47
  138. package/dist/engine/boot-validator/screens-kind-rules.d.ts +137 -0
  139. package/dist/engine/boot-validator/screens-kind-rules.js +137 -0
  140. package/dist/engine/boot-validator/screens-kind-secret-mint.js +18 -8
  141. package/dist/engine/boot-validator/screens-kind-shared.js +40 -22
  142. package/dist/engine/boot-validator/screens-lists-rules.d.ts +82 -0
  143. package/dist/engine/boot-validator/screens-lists-rules.js +82 -0
  144. package/dist/engine/boot-validator/screens-lists.js +90 -45
  145. package/dist/engine/boot-validator/screens-rules.d.ts +57 -0
  146. package/dist/engine/boot-validator/screens-rules.js +57 -0
  147. package/dist/engine/boot-validator/screens.js +17 -12
  148. package/dist/engine/boot-validator/transaction-phases.js +12 -4
  149. package/dist/engine/boot-validator/transfer-graph.js +17 -11
  150. package/dist/engine/boot-validator/url-prefill-fields.js +9 -5
  151. package/dist/engine/boot-validator/workspaces.js +11 -5
  152. package/dist/engine/boot-validator/zod-shape.js +6 -2
  153. package/dist/engine/entity-handlers.d.ts +1 -0
  154. package/dist/engine/entity-handlers.js +3 -0
  155. package/dist/engine/entity-list-runtime-options.js +23 -29
  156. package/dist/engine/extensions/tenant-data.d.ts +3 -0
  157. package/dist/engine/factories.d.ts +1 -1
  158. package/dist/engine/factories.js +4 -3
  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.js +7 -12
  181. package/dist/logging/utils.js +30 -60
  182. package/dist/observability/metrics-handle.js +10 -21
  183. package/dist/pipeline/cascade-handler.js +7 -6
  184. package/dist/pipeline/dispatch-query.js +18 -5
  185. package/dist/pipeline/dispatch-shared.d.ts +1 -0
  186. package/dist/pipeline/dispatch-shared.js +3 -1
  187. package/dist/pipeline/dispatch-write.js +10 -12
  188. package/dist/pipeline/dispatcher.js +12 -14
  189. package/dist/pipeline/event-dispatcher-admin.js +9 -8
  190. package/dist/pipeline/event-dispatcher-delivery.d.ts +19 -1
  191. package/dist/pipeline/event-dispatcher-delivery.js +121 -29
  192. package/dist/pipeline/event-dispatcher.d.ts +5 -1
  193. package/dist/pipeline/event-dispatcher.js +28 -21
  194. package/dist/pipeline/handler-context-phase-denials.js +2 -0
  195. package/dist/pipeline/multi-stream-apply-context.js +12 -20
  196. package/dist/pipeline/system-hooks.d.ts +4 -1
  197. package/dist/pipeline/system-hooks.js +79 -6
  198. package/dist/pipeline/system-identity-switch.js +10 -7
  199. package/dist/search/build-search-snippet.d.ts +9 -0
  200. package/dist/search/build-search-snippet.js +40 -0
  201. package/dist/search/index.d.ts +1 -0
  202. package/dist/search/index.js +1 -0
  203. package/dist/search/meilisearch-adapter.d.ts +32 -0
  204. package/dist/search/meilisearch-adapter.js +153 -56
  205. package/dist/search/meilisearch-chunking.d.ts +21 -0
  206. package/dist/search/meilisearch-chunking.js +96 -0
  207. package/dist/search/reindex-entity.d.ts +1 -0
  208. package/dist/search/reindex-entity.js +97 -52
  209. package/dist/ui-types/index.d.ts +1 -1
  210. package/dist/upgrade-cli.js +3 -14
  211. package/package.json +3 -3
  212. package/src/changes.json +79 -0
@@ -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;
@@ -7,7 +7,7 @@ import { createFallbackLogger } from "../logging/utils.js";
7
7
  import { getFallbackMeter, getFallbackTracer } from "../observability/fallback.js";
8
8
  import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, } from "../observability/standard-metrics.js";
9
9
  import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
10
- import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
10
+ import { acquireConsumerState, consumerInstanceId, deliverConsumerTurn, emitLagFromTx, fetchPendingEvents, markProcessing, pendingFetchLimit, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
11
11
  import { mergeContiguousGapRanges, partitionBurntGaps, splitRangeExcludingIds, toIdRanges, } from "./pending-gap-ranges.js";
12
12
  const DEFAULT_BATCH_SIZE = 200;
13
13
  const DEFAULT_POLL_MS = 100;
@@ -15,6 +15,7 @@ const DEFAULT_MAX_ATTEMPTS = 10;
15
15
  const DEFAULT_REARM_COOLDOWN_MS = 5 * 60_000;
16
16
  const DEFAULT_MAX_REARM_COUNT = 3;
17
17
  const PENDING_GAPS_WARN_THRESHOLD = 1000;
18
+ const DEFAULT_MAX_PENDING_GAP_RANGES = 2 * PENDING_GAPS_WARN_THRESHOLD;
18
19
  // Only these say the database socket itself is gone; timeouts, schema or pool errors do not
19
20
  // imply the dedicated LISTEN connection dropped.
20
21
  const CONNECTION_LOSS_CODES = new Set([
@@ -36,7 +37,7 @@ function isConnectionLossError(e) {
36
37
  const PASS_FAILURE_BASE_BACKOFF_MS = 1_000;
37
38
  const PASS_FAILURE_MAX_BACKOFF_MS = 60_000;
38
39
  export function createEventDispatcher(options) {
39
- const { db, consumers, context, batchSize = DEFAULT_BATCH_SIZE, pollIntervalMs = DEFAULT_POLL_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS, rearmCooldownMs = DEFAULT_REARM_COOLDOWN_MS, maxRearmCount = DEFAULT_MAX_REARM_COUNT, } = options;
40
+ const { db, consumers, context, batchSize = DEFAULT_BATCH_SIZE, pollIntervalMs = DEFAULT_POLL_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS, rearmCooldownMs = DEFAULT_REARM_COOLDOWN_MS, maxRearmCount = DEFAULT_MAX_REARM_COUNT, maxPendingGapRanges = DEFAULT_MAX_PENDING_GAP_RANGES, } = options;
40
41
  // Fail-fast on misconfigured per-instance wiring. Catching this at
41
42
  // construction surfaces the problem in boot logs instead of first
42
43
  // delivery attempt — where it would land as a confusing preRegister
@@ -344,14 +345,16 @@ export function createEventDispatcher(options) {
344
345
  // xmin BEFORE the fetch: a range is provably burnt only once this has
345
346
  // passed the xmax recorded with it. Only needed when ranges exist.
346
347
  const xminNow = pendingGaps.length > 0 ? await selectSnapshotXmin(tx) : "0";
347
- const events = await fetchPendingEvents(tx, oldCursor, batchSize, toIdRanges(pendingGaps));
348
- const fetchedIds = events.map((e) => e.id);
349
- const truncated = events.length === batchSize;
348
+ const pendingRanges = toIdRanges(pendingGaps);
349
+ const pendingLimit = pendingFetchLimit(consumer, batchSize);
350
+ const events = await fetchPendingEvents(tx, oldCursor, batchSize, pendingRanges, pendingLimit);
351
+ const pendingFetchedIds = events.filter((e) => e.id <= oldCursor).map((e) => e.id);
352
+ const pendingTruncated = pendingFetchedIds.length === pendingLimit;
350
353
  // Burnt: no visible id this turn, the fetch is proven to have
351
- // covered the range (LIMIT can otherwise cut it off early), and
354
+ // covered the range (the pending LIMIT can otherwise cut it off early), and
352
355
  // xmin passed its recorded xmax — every xact that could still
353
356
  // produce a row has finished without one ever appearing.
354
- const { burnt: burntGaps, surviving: survivingGaps } = partitionBurntGaps(pendingGaps, fetchedIds, truncated, xminNow);
357
+ const { burnt: burntGaps, surviving: survivingGaps } = partitionBurntGaps(pendingGaps, pendingFetchedIds, pendingTruncated, xminNow);
355
358
  // skip: nothing to deliver and no burnt gap to clean up. The
356
359
  // doPass idle pre-check (selectIdleConsumerKeys) already keeps the
357
360
  // common idle case out of this transaction entirely — reaching
@@ -365,18 +368,19 @@ export function createEventDispatcher(options) {
365
368
  return;
366
369
  }
367
370
  await markProcessing(tx, consumer.name, instanceId);
368
- const outcome = events.length > 0
369
- ? await deliverEvents(consumer, events, context, maxAttempts, acquired.state)
370
- : {
371
- cursor: oldCursor,
372
- attempts: acquired.state.attempts,
373
- lastError: acquired.state.lastError,
374
- deadLettered: false,
375
- processed: 0,
376
- failed: 0,
377
- failedEventId: acquired.state.lastFailedEventId,
378
- resolvedPendingIds: [],
379
- };
371
+ const { deliverable, outcome } = await deliverConsumerTurn({
372
+ tx,
373
+ consumer,
374
+ events,
375
+ state: acquired.state,
376
+ context,
377
+ maxAttempts,
378
+ pendingRanges,
379
+ pendingLimit,
380
+ pendingGapCount: survivingGaps.length,
381
+ maxPendingGapRanges,
382
+ });
383
+ const fetchedIds = deliverable.map((e) => e.id);
380
384
  processed = outcome.processed;
381
385
  failed = outcome.failed;
382
386
  // Carve delivered/skip-applied ids out of the surviving ranges —
@@ -396,8 +400,11 @@ export function createEventDispatcher(options) {
396
400
  newGapBounds.push([prev + 1n, id - 1n]);
397
401
  prev = id;
398
402
  }
399
- const xmaxNow = newGapBounds.length > 0 ? await selectSnapshotXmax(tx) : "";
400
- const newGaps = newGapBounds.map(([from, to]) => ({
403
+ // Held ids are visible rows, so partitionBurntGaps never burns them; xmax only keeps
404
+ // the entry shape uniform.
405
+ const heldBounds = outcome.heldNewIds.map((id) => [id, id]);
406
+ const xmaxNow = newGapBounds.length > 0 || heldBounds.length > 0 ? await selectSnapshotXmax(tx) : "";
407
+ const newGaps = [...newGapBounds, ...heldBounds].map(([from, to]) => ({
401
408
  from: from.toString(),
402
409
  to: to.toString(),
403
410
  xmax: xmaxNow,
@@ -21,11 +21,13 @@ export function dropOutsideTransaction(handlerContext) {
21
21
  if (handlerContext.db)
22
22
  attachOutsideTransaction(handlerContext.db, undefined);
23
23
  }
24
+ // guard:dup-ok error factory; only the message differs from its siblings, InternalError is the shared constructor
24
25
  function beforeTransactionDenied(surface) {
25
26
  return new InternalError({
26
27
  message: `ctx.${surface} is not available before the transaction; move it into the handler`,
27
28
  });
28
29
  }
30
+ // guard:dup-ok error factory; only the message differs from its siblings, InternalError is the shared constructor
29
31
  export function withoutTransactionDenied(surface) {
30
32
  return new InternalError({
31
33
  message: `ctx.${surface} is not available without an open transaction; run the write through ctx.dispatch.write so it gets its own transaction`,
@@ -3,32 +3,24 @@ import { upcastStoredEvents } from "../event-store/upcaster.js";
3
3
  import { appendDomainEventCore } from "./append-event-core.js";
4
4
  import { asTypedAppendEventFn } from "./typed-append-event.js";
5
5
  export function createMultiStreamApplyContext(deps) {
6
+ const appendWithLabel = async (callSiteLabel, args) => {
7
+ await appendDomainEventCore({
8
+ registry: deps.registry,
9
+ db: deps.db,
10
+ tenantId: deps.tenantId,
11
+ userId: deps.userId,
12
+ callSiteLabel,
13
+ ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
14
+ }, args);
15
+ };
6
16
  return {
7
17
  registry: deps.registry,
8
18
  ...(deps.files ? { files: deps.files } : {}),
9
19
  ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
10
20
  ...(deps.secrets ? { secrets: deps.secrets } : {}),
11
21
  ...(deps.jobs ? { jobs: deps.jobs } : {}),
12
- appendEvent: asTypedAppendEventFn(async (args) => {
13
- await appendDomainEventCore({
14
- registry: deps.registry,
15
- db: deps.db,
16
- tenantId: deps.tenantId,
17
- userId: deps.userId,
18
- callSiteLabel: "MSP-apply ctx.appendEvent",
19
- ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
20
- }, args);
21
- }),
22
- unsafeAppendEvent: async (args) => {
23
- await appendDomainEventCore({
24
- registry: deps.registry,
25
- db: deps.db,
26
- tenantId: deps.tenantId,
27
- userId: deps.userId,
28
- callSiteLabel: "MSP-apply ctx.unsafeAppendEvent",
29
- ...(deps.callerFeature && { callerFeature: deps.callerFeature }),
30
- }, args);
31
- },
22
+ appendEvent: asTypedAppendEventFn((args) => appendWithLabel("MSP-apply ctx.appendEvent", args)),
23
+ unsafeAppendEvent: (args) => appendWithLabel("MSP-apply ctx.unsafeAppendEvent", args),
32
24
  loadAggregate: async (aggregateId, options) => {
33
25
  const events = options?.asOf
34
26
  ? await loadAggregateAsOf(deps.db, aggregateId, deps.tenantId, options.asOf)
@@ -14,7 +14,10 @@ export type SearchOperation = {
14
14
  readonly entityType: string;
15
15
  readonly entityId: EntityId;
16
16
  };
17
- export declare function createSearchEventConsumer(searchAdapter: SearchAdapter, registry: Registry): EventConsumer;
17
+ export type SearchEventConsumerOptions = {
18
+ readonly now?: () => number;
19
+ };
20
+ export declare function createSearchEventConsumer(searchAdapter: SearchAdapter, registry: Registry, options?: SearchEventConsumerOptions): EventConsumer;
18
21
  export declare function decryptSearchableSubjectFields(entityName: string, state: Record<string, unknown>, registry: Registry): Promise<Record<string, unknown>>;
19
22
  export declare function hasErasedSearchableSubjectField(entityName: string, state: Record<string, unknown>, registry: Registry): boolean;
20
23
  export declare function buildSearchDocument(entityName: string, entityId: EntityId, state: Record<string, unknown>, registry: Registry): Promise<SearchDocument | null>;