@kindgi/runtime 0.0.0-bootstrap.0 → 0.1.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 (58) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +65 -1
  3. package/dist/bindings.d.ts +186 -0
  4. package/dist/bindings.d.ts.map +1 -0
  5. package/dist/bindings.js +4 -0
  6. package/dist/bindings.js.map +1 -0
  7. package/dist/derivation.d.ts +123 -0
  8. package/dist/derivation.d.ts.map +1 -0
  9. package/dist/derivation.js +249 -0
  10. package/dist/derivation.js.map +1 -0
  11. package/dist/errors.d.ts +78 -0
  12. package/dist/errors.d.ts.map +1 -0
  13. package/dist/errors.js +4 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/event-bus.d.ts +41 -0
  16. package/dist/event-bus.d.ts.map +1 -0
  17. package/dist/event-bus.js +13 -0
  18. package/dist/event-bus.js.map +1 -0
  19. package/dist/index.d.ts +11 -0
  20. package/dist/index.d.ts.map +1 -0
  21. package/dist/index.js +13 -0
  22. package/dist/index.js.map +1 -0
  23. package/dist/inputs.d.ts +160 -0
  24. package/dist/inputs.d.ts.map +1 -0
  25. package/dist/inputs.js +4 -0
  26. package/dist/inputs.js.map +1 -0
  27. package/dist/runs.d.ts +73 -0
  28. package/dist/runs.d.ts.map +1 -0
  29. package/dist/runs.js +4 -0
  30. package/dist/runs.js.map +1 -0
  31. package/dist/schedulers/registry.d.ts +142 -0
  32. package/dist/schedulers/registry.d.ts.map +1 -0
  33. package/dist/schedulers/registry.js +4 -0
  34. package/dist/schedulers/registry.js.map +1 -0
  35. package/dist/schedulers/types.d.ts +99 -0
  36. package/dist/schedulers/types.d.ts.map +1 -0
  37. package/dist/schedulers/types.js +4 -0
  38. package/dist/schedulers/types.js.map +1 -0
  39. package/dist/types.d.ts +317 -0
  40. package/dist/types.d.ts.map +1 -0
  41. package/dist/types.js +6 -0
  42. package/dist/types.js.map +1 -0
  43. package/dist/versioning.d.ts +59 -0
  44. package/dist/versioning.d.ts.map +1 -0
  45. package/dist/versioning.js +89 -0
  46. package/dist/versioning.js.map +1 -0
  47. package/package.json +50 -4
  48. package/src/bindings.ts +244 -0
  49. package/src/derivation.ts +354 -0
  50. package/src/errors.ts +92 -0
  51. package/src/event-bus.ts +51 -0
  52. package/src/index.ts +13 -0
  53. package/src/inputs.ts +169 -0
  54. package/src/runs.ts +84 -0
  55. package/src/schedulers/registry.ts +197 -0
  56. package/src/schedulers/types.ts +112 -0
  57. package/src/types.ts +378 -0
  58. package/src/versioning.ts +110 -0
@@ -0,0 +1,249 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ /** Composite key for `waitResolutions` lookups. */
4
+ export function waitResolutionKey(nodeId, tokenId) {
5
+ return `${nodeId}::${tokenId}`;
6
+ }
7
+ /** A loop-body step's key in `completedBodySteps`: the node, at its iteration of every enclosing loop. */
8
+ export function bodyStepKey(nodeId, loopContext) {
9
+ return `${nodeId}@${loopContext.path.map((p) => `${p.loopNodeId}#${p.iteration}`).join('/')}`;
10
+ }
11
+ /**
12
+ * Fold journal entries into the run state view the scheduler needs.
13
+ *
14
+ * Rules:
15
+ * - `step.started` puts the node into `inFlightNodes`.
16
+ * - `step.completed` removes it from `inFlightNodes`, adds to `completedNodes`,
17
+ * records its `output` in `nodeOutputs`, and shallow-merges any `stateDelta`
18
+ * into `state` (last-writer-wins by journal sequence).
19
+ * - `step.failed` removes it from `inFlightNodes`, adds to `failedNodes`, and
20
+ * records the failure message.
21
+ * - `edge.evaluated` records the decision keyed by edgeId.
22
+ * - `wait.suspended` moves the node from `inFlightNodes` to
23
+ * `suspendedNodes`; `wait.resumed` / `wait.cancelled` take it out of
24
+ * `suspendedNodes` and record the value / reason by
25
+ * `waitResolutionKey(nodeId, tokenId)`.
26
+ * - `step.retry-scheduled` clears the node's failed / in-flight markers
27
+ * and increments `nodeAttempts`.
28
+ * - `step.concurrency-deferred` adds the node to `deferredNodes`.
29
+ * - a `step.completed` with a `loopContext` (a loop-body step) is also
30
+ * recorded in `completedBodySteps`.
31
+ * - Every other kind is informational (run.started, run.completed, etc.).
32
+ */
33
+ export function deriveRunState(journal) {
34
+ const state = createRunState();
35
+ for (const entry of journal)
36
+ applyJournalEntry(state, entry);
37
+ return state;
38
+ }
39
+ /** The state of a run with no journal entries — `deriveRunState([])`. */
40
+ export function createRunState() {
41
+ return {
42
+ completedNodes: new Set(),
43
+ inFlightNodes: new Set(),
44
+ failedNodes: new Set(),
45
+ suspendedNodes: new Set(),
46
+ deferredNodes: new Set(),
47
+ edgeDecisions: new Map(),
48
+ nodeOutputs: new Map(),
49
+ state: {},
50
+ failureMessages: [],
51
+ waitResolutions: new Map(),
52
+ waitCancellations: new Map(),
53
+ nodeAttempts: new Map(),
54
+ completedBodySteps: new Map(),
55
+ };
56
+ }
57
+ /**
58
+ * Apply one journal entry to `state`, in place, by the rules of
59
+ * `deriveRunState` (which folds the journal with it). A runtime that
60
+ * keeps a run's state in memory reads the journal once, then applies each
61
+ * entry it writes, instead of reading the journal again.
62
+ */
63
+ export function applyJournalEntry(state, entry) {
64
+ applyEntry(state, entry);
65
+ }
66
+ /**
67
+ * A copy of `state` that later `applyJournalEntry` calls on `state` don't
68
+ * change — what a step sees should be the run as it stood when the step
69
+ * was dispatched. Values (node outputs, state values) are shared, not
70
+ * copied; the journal never changes a value in place.
71
+ */
72
+ export function cloneRunState(state) {
73
+ return {
74
+ completedNodes: new Set(state.completedNodes),
75
+ inFlightNodes: new Set(state.inFlightNodes),
76
+ failedNodes: new Set(state.failedNodes),
77
+ suspendedNodes: new Set(state.suspendedNodes),
78
+ deferredNodes: new Set(state.deferredNodes),
79
+ edgeDecisions: new Map(state.edgeDecisions),
80
+ nodeOutputs: new Map(state.nodeOutputs),
81
+ state: { ...state.state },
82
+ failureMessages: [...state.failureMessages],
83
+ waitResolutions: new Map(state.waitResolutions),
84
+ waitCancellations: new Map(state.waitCancellations),
85
+ nodeAttempts: new Map(state.nodeAttempts),
86
+ completedBodySteps: new Map(state.completedBodySteps),
87
+ };
88
+ }
89
+ function applyEntry(acc, entry) {
90
+ switch (entry.kind) {
91
+ case 'step.started':
92
+ applyStepStarted(acc, entry);
93
+ return;
94
+ case 'step.completed':
95
+ applyStepCompleted(acc, entry);
96
+ return;
97
+ case 'step.failed':
98
+ applyStepFailed(acc, entry);
99
+ return;
100
+ case 'edge.evaluated':
101
+ applyEdgeEvaluated(acc, entry);
102
+ return;
103
+ case 'wait.suspended':
104
+ applyWaitSuspended(acc, entry);
105
+ return;
106
+ case 'wait.resumed':
107
+ applyWaitResumed(acc, entry);
108
+ return;
109
+ case 'wait.cancelled':
110
+ applyWaitCancelled(acc, entry);
111
+ return;
112
+ case 'step.retry-scheduled':
113
+ applyStepRetryScheduled(acc, entry);
114
+ return;
115
+ case 'step.concurrency-deferred':
116
+ applyStepConcurrencyDeferred(acc, entry);
117
+ return;
118
+ default:
119
+ // iteration.*, fanout.*, subgraph.*, run.*, clock.read: informational.
120
+ // Derivation observes them via their paired step.* entries.
121
+ return;
122
+ }
123
+ }
124
+ function applyStepStarted(acc, entry) {
125
+ if (entry.nodeId === undefined)
126
+ return;
127
+ // Re-dispatch after wait.resumed: node moves out of suspendedNodes and
128
+ // back into inFlightNodes. Duplicate step.started entries collapse
129
+ // idempotently — first occurrence wins, subsequent ones are no-ops
130
+ // beyond ensuring the node is in inFlightNodes.
131
+ acc.suspendedNodes.delete(entry.nodeId);
132
+ // A prior step.concurrency-deferred no longer applies once the node
133
+ // starts — clear the deferred marker so the scheduler no longer treats
134
+ // this node as waiting on a lease.
135
+ acc.deferredNodes.delete(entry.nodeId);
136
+ acc.inFlightNodes.add(entry.nodeId);
137
+ }
138
+ function applyStepCompleted(acc, entry) {
139
+ if (entry.nodeId === undefined)
140
+ return;
141
+ acc.inFlightNodes.delete(entry.nodeId);
142
+ // Clear residual suspended-marker in case this completion is a body
143
+ // node re-run after a loop-level resume (the suspend was written
144
+ // against the body node too).
145
+ acc.suspendedNodes.delete(entry.nodeId);
146
+ acc.deferredNodes.delete(entry.nodeId);
147
+ acc.completedNodes.add(entry.nodeId);
148
+ const p = entry.payload;
149
+ if (p !== undefined && 'output' in p)
150
+ acc.nodeOutputs.set(entry.nodeId, p.output);
151
+ if (p?.stateDelta !== undefined) {
152
+ for (const [k, v] of Object.entries(p.stateDelta))
153
+ acc.state[k] = v;
154
+ }
155
+ if (p?.loopContext !== undefined) {
156
+ acc.completedBodySteps.set(bodyStepKey(entry.nodeId, p.loopContext), {
157
+ output: p.output,
158
+ ...(p.stateDelta !== undefined && { stateDelta: p.stateDelta }),
159
+ });
160
+ }
161
+ }
162
+ function applyStepFailed(acc, entry) {
163
+ if (entry.nodeId === undefined)
164
+ return;
165
+ acc.inFlightNodes.delete(entry.nodeId);
166
+ acc.suspendedNodes.delete(entry.nodeId);
167
+ acc.deferredNodes.delete(entry.nodeId);
168
+ acc.failedNodes.add(entry.nodeId);
169
+ const m = entry.payload?.message;
170
+ if (typeof m === 'string')
171
+ acc.failureMessages.push(m);
172
+ }
173
+ function applyEdgeEvaluated(acc, entry) {
174
+ const p = entry.payload;
175
+ if (p?.edgeId !== undefined && typeof p.decision === 'boolean') {
176
+ acc.edgeDecisions.set(p.edgeId, p.decision);
177
+ }
178
+ }
179
+ function applyWaitSuspended(acc, entry) {
180
+ if (entry.nodeId === undefined)
181
+ return;
182
+ // Handler suspended mid-flight: drop from inFlightNodes, mark suspended.
183
+ // The step.started for this node stays "logically active" — resume
184
+ // dispatch re-fires step.started, which flips node back to inFlightNodes.
185
+ acc.inFlightNodes.delete(entry.nodeId);
186
+ acc.suspendedNodes.add(entry.nodeId);
187
+ }
188
+ function applyStepRetryScheduled(acc, entry) {
189
+ if (entry.nodeId === undefined)
190
+ return;
191
+ // Retry-scheduled means: the handler just failed, the executor decided
192
+ // to retry, and is about to re-dispatch. Clear residual failure /
193
+ // in-flight markers so the node is re-dispatched cleanly on the next
194
+ // tick's ready set. Attempt counter increments monotonically.
195
+ acc.failedNodes.delete(entry.nodeId);
196
+ acc.inFlightNodes.delete(entry.nodeId);
197
+ const current = acc.nodeAttempts.get(entry.nodeId) ?? 0;
198
+ acc.nodeAttempts.set(entry.nodeId, current + 1);
199
+ }
200
+ function applyStepConcurrencyDeferred(acc, entry) {
201
+ if (entry.nodeId === undefined)
202
+ return;
203
+ // Deferred means: the dispatcher tried to acquire the lease and failed.
204
+ // The node is not yet in-flight; a subsequent step.started (once the
205
+ // lease is free) clears this marker. Duplicate deferred entries collapse
206
+ // idempotently — the node is either in deferredNodes or not, count is
207
+ // observability-only via the raw journal.
208
+ acc.deferredNodes.add(entry.nodeId);
209
+ }
210
+ function applyWaitResumed(acc, entry) {
211
+ if (entry.nodeId === undefined)
212
+ return;
213
+ acc.suspendedNodes.delete(entry.nodeId);
214
+ const p = entry.payload;
215
+ if (p !== undefined && typeof p.tokenId === 'string') {
216
+ // Record the resolved value against the (nodeId, tokenId) pair so the
217
+ // handler re-invocation reads it back through `ctx.waitForToken()`.
218
+ acc.waitResolutions.set(waitResolutionKey(entry.nodeId, p.tokenId), p.value);
219
+ }
220
+ }
221
+ function applyWaitCancelled(acc, entry) {
222
+ if (entry.nodeId === undefined)
223
+ return;
224
+ // Cancel resolves the suspension too — the node moves out of suspendedNodes
225
+ // and is redispatched so its handler re-runs, reads the cancellation
226
+ // from waitCancellations via ctx.waitForToken(), and throws
227
+ // WaitpointCancelledError to propagate through the flow as a failure.
228
+ acc.suspendedNodes.delete(entry.nodeId);
229
+ const p = entry.payload;
230
+ if (p !== undefined && typeof p.tokenId === 'string') {
231
+ const reason = typeof p.reason === 'string' ? p.reason : 'unknown';
232
+ acc.waitCancellations.set(waitResolutionKey(entry.nodeId, p.tokenId), reason);
233
+ }
234
+ }
235
+ /**
236
+ * Normalize a raw handler return into a HandlerResult shape. Bare values
237
+ * become `{ output: value }`; already-structured values pass through.
238
+ */
239
+ export function normalizeHandlerResult(raw) {
240
+ if (raw !== null && typeof raw === 'object' && 'output' in raw) {
241
+ const r = raw;
242
+ if (r.stateDelta !== undefined) {
243
+ return { output: r.output, stateDelta: r.stateDelta };
244
+ }
245
+ return { output: r.output };
246
+ }
247
+ return { output: raw };
248
+ }
249
+ //# sourceMappingURL=derivation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"derivation.js","sourceRoot":"","sources":["../src/derivation.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,78 @@
1
+ export type KernelError = RunNotFoundError | FlowMismatchError | RunAlreadyTerminalError | NodeExecutionError | JournalError | WaitpointError | HandlerMissingError | StuckRunError | RunLeaseLostError;
2
+ export interface RunNotFoundError {
3
+ readonly code: 'run-not-found';
4
+ readonly message: string;
5
+ readonly runId: string;
6
+ }
7
+ /** `resumeRun` was called with a flow whose id/version does not match the run's. */
8
+ export interface FlowMismatchError {
9
+ readonly code: 'flow-mismatch';
10
+ readonly message: string;
11
+ readonly expected: {
12
+ readonly id: string;
13
+ readonly version: string;
14
+ };
15
+ readonly got: {
16
+ readonly id: string;
17
+ readonly version: string;
18
+ };
19
+ }
20
+ /** Attempted to resume or step a run that has already completed / failed / cancelled. */
21
+ export interface RunAlreadyTerminalError {
22
+ readonly code: 'run-already-terminal';
23
+ readonly message: string;
24
+ readonly runId: string;
25
+ readonly status: string;
26
+ }
27
+ /** A node handler threw. The runtime catches, journals, and returns this. */
28
+ export interface NodeExecutionError {
29
+ readonly code: 'node-execution-error';
30
+ readonly message: string;
31
+ readonly runId: string;
32
+ readonly nodeId: string;
33
+ readonly cause: unknown;
34
+ }
35
+ /** Journal read/write failed at the storage layer. */
36
+ export interface JournalError {
37
+ readonly code: 'journal-error';
38
+ readonly message: string;
39
+ readonly cause: unknown;
40
+ }
41
+ /** Waitpoint-related error (double-completion, missing token, etc.). */
42
+ export interface WaitpointError {
43
+ readonly code: 'waitpoint-error';
44
+ readonly message: string;
45
+ readonly tokenId: string;
46
+ }
47
+ /**
48
+ * Handlers are missing for some of a flow's nodes — returned by
49
+ * `runGraph` / `resumeRun`, or by a `HandlerResolver` binding a child flow.
50
+ */
51
+ export interface HandlerMissingError {
52
+ readonly code: 'handler-missing';
53
+ readonly message: string;
54
+ readonly nodeIds: readonly string[];
55
+ }
56
+ /**
57
+ * The run's scheduling loop reached a state where no node is ready, no
58
+ * edge remains to evaluate, nothing is in flight or suspended, and the
59
+ * flow is not done. Marked failed to prevent an infinite loop.
60
+ */
61
+ export interface StuckRunError {
62
+ readonly code: 'stuck';
63
+ readonly message: string;
64
+ readonly runId: string;
65
+ }
66
+ /**
67
+ * This executor no longer holds the run's lease: another executor claimed
68
+ * it (after this one's lease expired) and owns the run now. The executor
69
+ * stops without failing or finishing the run; whoever holds the lease
70
+ * decides what happens to it. Returned by `runGraph` / `resumeRun` when a
71
+ * write is refused because the run's lease epoch moved on.
72
+ */
73
+ export interface RunLeaseLostError {
74
+ readonly code: 'run-lease-lost';
75
+ readonly message: string;
76
+ readonly runId: string;
77
+ }
78
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,uBAAuB,GACvB,kBAAkB,GAClB,YAAY,GACZ,cAAc,GACd,mBAAmB,GACnB,aAAa,GACb,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,yFAAyF;AACzF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}
package/dist/errors.js ADDED
@@ -0,0 +1,4 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ export {};
4
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}
@@ -0,0 +1,41 @@
1
+ import type { Result, TenantId } from '@kindgi/types';
2
+ /**
3
+ * Minimal structural interface the kernel calls into after each
4
+ * successful journal write. Deliberately narrower than
5
+ * `@kindgi/api`'s `EventBusBinding` so the kernel can accept
6
+ * either the API-side binding OR a plain publish-only shim without
7
+ * a hard dependency on `@kindgi/api`.
8
+ *
9
+ * The full binding (with `subscribe`) is defined in
10
+ * `packages/api/src/event-bus-binding.ts`. That type is structurally
11
+ * assignable to this one — a caller wiring the same instance into
12
+ * both sides just works.
13
+ *
14
+ * `publish` MUST NOT throw. Errors are returned in the `Result` so
15
+ * the kernel can log-and-continue: a publish failure MUST NOT roll
16
+ * back the journal append (that would be a correctness bug — the
17
+ * journal is the source of truth).
18
+ */
19
+ export interface KernelEventBusBinding {
20
+ publish(tenantId: TenantId, channel: string, doc: unknown): Promise<Result<void, {
21
+ readonly message: string;
22
+ }>>;
23
+ /**
24
+ * Publish `docs` to the channel, in order, as one write. The kernel
25
+ * writes a run's journal entries in batches and publishes each batch
26
+ * with this when the binding has it, and entry by entry with
27
+ * `publish` otherwise. Same contract as `publish`: never throws.
28
+ */
29
+ publishMany?(tenantId: TenantId, channel: string, docs: readonly unknown[]): Promise<Result<void, {
30
+ readonly message: string;
31
+ }>>;
32
+ }
33
+ /**
34
+ * Derived per-run channel name. Every kernel journal write publishes
35
+ * to this channel; SSE consumers subscribe with the same shape.
36
+ *
37
+ * Deliberately colon-namespaced so other channels (e.g.
38
+ * `kernel:trigger:<id>`) cannot collide with it.
39
+ */
40
+ export declare function kernelRunChannel(runId: string): string;
41
+ //# sourceMappingURL=event-bus.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CACL,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACvD;;;;;OAKG;IACH,WAAW,CAAC,CACV,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACxD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}
@@ -0,0 +1,13 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ /**
4
+ * Derived per-run channel name. Every kernel journal write publishes
5
+ * to this channel; SSE consumers subscribe with the same shape.
6
+ *
7
+ * Deliberately colon-namespaced so other channels (e.g.
8
+ * `kernel:trigger:<id>`) cannot collide with it.
9
+ */
10
+ export function kernelRunChannel(runId) {
11
+ return `kernel:run:${runId}`;
12
+ }
13
+ //# sourceMappingURL=event-bus.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAwCjC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,cAAc,KAAK,EAAE,CAAC;AAC/B,CAAC"}
@@ -0,0 +1,11 @@
1
+ export * from './types.js';
2
+ export * from './errors.js';
3
+ export * from './derivation.js';
4
+ export * from './versioning.js';
5
+ export * from './event-bus.js';
6
+ export * from './schedulers/types.js';
7
+ export * from './schedulers/registry.js';
8
+ export * from './inputs.js';
9
+ export * from './runs.js';
10
+ export * from './bindings.js';
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,13 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ export * from './types.js';
4
+ export * from './errors.js';
5
+ export * from './derivation.js';
6
+ export * from './versioning.js';
7
+ export * from './event-bus.js';
8
+ export * from './schedulers/types.js';
9
+ export * from './schedulers/registry.js';
10
+ export * from './inputs.js';
11
+ export * from './runs.js';
12
+ export * from './bindings.js';
13
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}
@@ -0,0 +1,160 @@
1
+ import type { Principal } from '@kindgi/authz';
2
+ import type { Flow } from '@kindgi/flow';
3
+ import type { HandlerRegistry } from '@kindgi/handler';
4
+ import type { NodeId, ProjectId, Result, RunId, TenantId } from '@kindgi/types';
5
+ import type { HandlerMissingError } from './errors.js';
6
+ import type { KernelEventBusBinding } from './event-bus.js';
7
+ import type { RunOptions } from './types.js';
8
+ /**
9
+ * Resolver contract for `subgraph` node dispatch. Structurally
10
+ * satisfied by `FlowRegistryBinding.getVersion(...)` in `@kindgi/api`.
11
+ * The runtime invokes the resolver with the PARENT run's tenantId; a
12
+ * flow registered under a different tenant returns `null`, which is
13
+ * the cross-tenant guarantee (rejection at dispatch with
14
+ * `subgraph-flow-not-found` attribution).
15
+ */
16
+ export interface FlowResolver {
17
+ getVersion(input: {
18
+ readonly tenantId: TenantId;
19
+ readonly flowId: string;
20
+ readonly version: string;
21
+ }): Promise<Flow | null>;
22
+ }
23
+ /**
24
+ * The node in a parent run that started this run as its child — a
25
+ * subgraph node's sub-run, or the agent turn an agent step launches.
26
+ * Stored on the child's row, so a parent (or a caller) can find the
27
+ * children of a run, and a resumed child can wake the parent that waits
28
+ * on it.
29
+ */
30
+ export interface ParentRunRef {
31
+ readonly runId: RunId;
32
+ readonly nodeId: NodeId;
33
+ /**
34
+ * Distinguishes children of the same node — one per loop iteration.
35
+ * The enclosing loop stack, serialized; `''` for a node outside any
36
+ * loop.
37
+ */
38
+ readonly scope: string;
39
+ }
40
+ /**
41
+ * Binds the handlers for a flow the runtime is about to run or resume —
42
+ * the root flow and every child flow a subgraph node starts. Lets a
43
+ * child flow get handlers for its own nodes instead of sharing the
44
+ * parent's registry.
45
+ */
46
+ export interface HandlerResolver {
47
+ resolve(input: {
48
+ readonly tenantId: TenantId;
49
+ readonly projectId: ProjectId;
50
+ readonly flow: Flow;
51
+ readonly dryRun: boolean;
52
+ }): Promise<Result<HandlerRegistry, HandlerMissingError>>;
53
+ }
54
+ export interface RunFlowInput {
55
+ readonly tenantId: TenantId;
56
+ /**
57
+ * Content-scope anchor. REQUIRED — every kernel run is bound to
58
+ * exactly one project inside the tenant. Callers without a natural
59
+ * project id resolve to the tenant's Default via
60
+ * `projectBinding.getDefault(tenantId)` at the caller layer.
61
+ */
62
+ readonly projectId: ProjectId;
63
+ readonly flow: Flow;
64
+ readonly handlers: HandlerRegistry;
65
+ readonly input: unknown;
66
+ readonly options?: RunOptions;
67
+ /**
68
+ * Optional flow resolver — required for flows that contain
69
+ * `subgraph` nodes. Absent resolver → subgraph nodes fail
70
+ * immediately with reason `resolver-missing`.
71
+ */
72
+ readonly flowResolver?: FlowResolver;
73
+ /**
74
+ * Internal: subgraph depth of THIS run. Populated by the runtime
75
+ * when a parent's `subgraph` node dispatches a child. External
76
+ * callers do NOT set this — it always starts at `0` for a
77
+ * top-level `RunBinding.runGraph` call.
78
+ */
79
+ readonly subgraphDepth?: number;
80
+ /** The parent node that started this run, when it is a child run. */
81
+ readonly parent?: ParentRunRef;
82
+ /**
83
+ * Run an existing `pending` row (created by `startRun`) instead of
84
+ * inserting a new one — how a caller hands back a run id before the
85
+ * run finishes.
86
+ */
87
+ readonly runId?: RunId;
88
+ /** Handlers for child flows; see `HandlerResolver`. */
89
+ readonly handlerResolver?: HandlerResolver;
90
+ /**
91
+ * Optional push-based event bus. When set, the runtime publishes
92
+ * a `JournalEntry`-shaped `doc` to `kernel:run:<runId>` after each
93
+ * successful journal write. When absent, journal writes still land
94
+ * durably.
95
+ */
96
+ readonly eventBus?: KernelEventBusBinding;
97
+ /**
98
+ * Authorization — the Principal on whose authority this run
99
+ * executes. When set together with `authz`, every `ctx.authorize` /
100
+ * `can` / `check` inside handlers is decided against this principal.
101
+ */
102
+ readonly principal?: Principal;
103
+ /**
104
+ * Authorization config — enables authorization checks inside the
105
+ * runtime. When absent, `ctx.authorize` is a no-op and tool
106
+ * invocations skip their pre-flight check.
107
+ */
108
+ readonly authz?: {
109
+ readonly fgaApiUrl: string;
110
+ };
111
+ }
112
+ export interface ResumeRunInput {
113
+ readonly tenantId: TenantId;
114
+ readonly runId: RunId;
115
+ readonly flow: Flow;
116
+ readonly handlers: HandlerRegistry;
117
+ readonly options?: RunOptions;
118
+ /** Same shape as `RunFlowInput.flowResolver`. */
119
+ readonly flowResolver?: FlowResolver;
120
+ /**
121
+ * Internal: subgraph depth of THIS run when it was originally
122
+ * started. Callers on the top level do NOT set this.
123
+ */
124
+ readonly subgraphDepth?: number;
125
+ /** Same shape + semantics as `RunFlowInput.handlerResolver`. */
126
+ readonly handlerResolver?: HandlerResolver;
127
+ /** Same shape + semantics as `RunFlowInput.eventBus`. */
128
+ readonly eventBus?: KernelEventBusBinding;
129
+ /**
130
+ * Authorization — carried through on resume so the resumed run
131
+ * keeps enforcing per-tool + per-subgraph checks.
132
+ */
133
+ readonly principal?: Principal;
134
+ readonly authz?: {
135
+ readonly fgaApiUrl: string;
136
+ };
137
+ }
138
+ export interface StartRunParams {
139
+ readonly tenantId: TenantId;
140
+ readonly projectId: ProjectId;
141
+ readonly flowId: string;
142
+ readonly flowVersion: string;
143
+ readonly input: unknown;
144
+ readonly dryRun?: boolean;
145
+ /** The parent node that starts this run, when it is a child run. */
146
+ readonly parent?: ParentRunRef;
147
+ }
148
+ export type StartRunError = {
149
+ readonly code: 'insert-failed';
150
+ readonly message: string;
151
+ };
152
+ export interface DeleteRunParams {
153
+ readonly tenantId: TenantId;
154
+ readonly runId: RunId;
155
+ }
156
+ export type DeleteRunError = {
157
+ readonly code: 'not-found' | 'delete-failed';
158
+ readonly message?: string;
159
+ };
160
+ //# sourceMappingURL=inputs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"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"}
package/dist/inputs.js ADDED
@@ -0,0 +1,4 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ export {};
4
+ //# sourceMappingURL=inputs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inputs.js","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}