botmux-workflow-core 3.55.0 → 3.57.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.
@@ -35,15 +35,217 @@ export interface V3LoopRef {
35
35
  iteration: number;
36
36
  bodyNodeId: string;
37
37
  }
38
+ /** Where an external goal-node handoff is delivered (design §5.1). */
39
+ export type V3ExternalPlacement = 'topic' | 'main';
40
+ /** Per-message idempotency keys, frozen in `nodeHandoffPrepared` so a
41
+ * re-dispatch after a crash reuses the exact same keys. */
42
+ export interface V3HandoffIdempotency {
43
+ /** Node card (topic placement only). */
44
+ nodeCard?: string;
45
+ handoff: string;
46
+ }
47
+ /**
48
+ * Why a runtime flow revision needs the initiator's confirmation before it
49
+ * takes effect (design §13.5 / M1). `callerNotInitiator` covers every edit
50
+ * made in a turn neither opened by the run's initiator nor woken by this
51
+ * run's own events; the rest are the §13.5 categories.
52
+ */
53
+ export type V3RevisionConfirmReason = 'callerNotInitiator' | 'newBot' | 'hostNode' | 'gateRelaxed' | 'budgetExpanded';
54
+ /**
55
+ * State changes a revision makes to already-dispatched work, folded
56
+ * atomically with its `dagRevised` event (one journal line, so a crash can
57
+ * never apply the new definition without its invalidations or vice versa).
58
+ */
59
+ export interface V3RevisionEffects {
60
+ /** Current instances invalidated by a definition change, reassignment or
61
+ * rerun — materialized exactly like `nodeInstanceSuperseded`: the node
62
+ * re-dispatches a fresh instance (and re-passes its gate). `waitId` names a
63
+ * pending gate wait voided by the change. */
64
+ supersede?: Array<{
65
+ nodeId: string;
66
+ instanceId: string;
67
+ waitId?: string;
68
+ }>;
69
+ /** Removed nodes that had already been dispatched or gated: neutral
70
+ * cancellation of that exact instance/attempt (only ever via this effect,
71
+ * never a separate `nodeCancelled`). `waitId` = a pending gate it voids. */
72
+ cancel?: Array<{
73
+ nodeId: string;
74
+ instanceId?: string;
75
+ attemptId?: string;
76
+ waitId?: string;
77
+ }>;
78
+ /** Blocked instances whose gate approval no longer covers their changed
79
+ * definition: the approval is dropped and their next retry runs as a
80
+ * fresh instance that must pass the gate again, however it is triggered. */
81
+ regate?: Array<{
82
+ nodeId: string;
83
+ instanceId: string;
84
+ }>;
85
+ /** Done nodes re-run with Revisit semantics; each consumes revisit budget. */
86
+ rerun?: string[];
87
+ /** Revisit budget the initiator's own edit lifted for its re-runs (M2 乙):
88
+ * each entry is one more revisit, counted exactly like a
89
+ * `revisitBudgetGranted` (`pair` = that node onto itself, `run` =
90
+ * run-wide) and attributed to this revision's `by`. In this event, never
91
+ * a separate line, so a crash cannot leave a lift without its revision. */
92
+ budgetGrants?: Array<{
93
+ nodeId: string;
94
+ tier: 'pair' | 'run';
95
+ }>;
96
+ /** RECORD ONLY: blocked nodes re-run by this revision. State advances
97
+ * through the `nodeRetryRequested` written in the same lock; replay never
98
+ * applies this list, reconciliation re-appends a lost retry from it. */
99
+ retry?: Array<{
100
+ nodeId: string;
101
+ instanceId?: string;
102
+ }>;
103
+ /** RECORD ONLY: reassignments, applied by the `nodeReassigned` written in
104
+ * the same lock (reconciled the same way as `retry`). */
105
+ assign?: Array<{
106
+ nodeId: string;
107
+ from?: string;
108
+ to: string;
109
+ }>;
110
+ }
111
+ /** Set when the main bot made the change on its own in a turn woken by
112
+ * this run's events (design §13.6). The reason becomes mandatory with the
113
+ * wake-up wiring; until then it carries the edit's note (may be empty). */
114
+ export interface V3AutoProvenance {
115
+ reason: string;
116
+ }
38
117
  export type V3Event = {
39
118
  type: 'runStarted';
40
119
  runId: string;
120
+ /** Stamped by a runtime executing goal nodes through bot sessions. */
121
+ nodeExecutor?: 'bot';
41
122
  } | {
42
123
  type: 'nodeDispatched';
43
124
  nodeId: string;
44
125
  instanceId?: string;
45
126
  attemptId: string;
46
127
  loop?: V3LoopRef;
128
+ /** Present when the attempt is executed by an external bot session
129
+ * (`run.json` `nodeExecutor: "bot"`). Such attempts own no local worker
130
+ * process, so they never enter the worker attempt ledger. */
131
+ nodeExecutor?: 'bot';
132
+ /** Flow revision the attempt was dispatched under. Absent = 1 (the
133
+ * approved DAG), so runs that never revised keep their exact bytes. */
134
+ revision?: number;
135
+ } | {
136
+ /** A flow revision took effect (design §13.3). `dag-revisions/<NNN>.json`
137
+ * holds the full new DAG; every digest here is of the exact file bytes
138
+ * and replay fails closed on a mismatch. */
139
+ type: 'dagRevised';
140
+ revision: number;
141
+ baseRevision: number;
142
+ sha256: string;
143
+ patchSha256: string;
144
+ /** `dag-revisions/<NNN>.bots.json`: snapshots of bots the revision
145
+ * newly brought into the run (always initiator-confirmed). */
146
+ botsSha256?: string;
147
+ summary: string;
148
+ /** Free-text note supplied with the edit (display only). */
149
+ note?: string;
150
+ /** Operator: the turn's open_id, or `main_bot` for a change the main
151
+ * bot made on its own in a turn this run's events woke. */
152
+ by: string;
153
+ /** Only with `by: 'main_bot'`: why it acted (design §13.6). */
154
+ auto?: V3AutoProvenance;
155
+ /** Present when the revision was a confirmed proposal. */
156
+ approval?: {
157
+ by: string;
158
+ proposedBy: string;
159
+ };
160
+ effects?: V3RevisionEffects;
161
+ } | {
162
+ /** A revision that needs the initiator's confirmation (design §13.5).
163
+ * Its files are already written; it takes effect only through a later
164
+ * `dagRevised` carrying `approval`. A pending wait lives in
165
+ * `waits/revisions/<NNN>.json`. */
166
+ type: 'dagRevisionProposed';
167
+ revision: number;
168
+ baseRevision: number;
169
+ sha256: string;
170
+ patchSha256: string;
171
+ botsSha256?: string;
172
+ summary: string;
173
+ note?: string;
174
+ by: string;
175
+ auto?: V3AutoProvenance;
176
+ reasons: V3RevisionConfirmReason[];
177
+ /** Existing nodes the proposal touches; they are not dispatched while
178
+ * it is pending (the rest of the run keeps going). */
179
+ touched: string[];
180
+ /** The pending proposal this one carries onto a direct revision that
181
+ * took effect first (same patch, same proposer, re-based): landing
182
+ * supersedes it, and its card and wait move here. */
183
+ carriedFrom?: number;
184
+ } | {
185
+ type: 'dagRevisionApproved';
186
+ revision: number;
187
+ by: string;
188
+ } | {
189
+ type: 'dagRevisionRejected';
190
+ revision: number;
191
+ by: string;
192
+ /** `stale` = the flow moved on (another revision took effect, or the
193
+ * proposal no longer applies to the current node states);
194
+ * `superseded` = a newer proposal replaced it; `runEnded` = the run
195
+ * left running/blocked before anyone decided. */
196
+ reason: 'rejected' | 'stale' | 'superseded' | 'runEnded';
197
+ detail?: string;
198
+ } | {
199
+ /** Durable intent written before any handoff message is sent. */
200
+ type: 'nodeHandoffPrepared';
201
+ nodeId: string;
202
+ instanceId?: string;
203
+ attemptId: string;
204
+ targetLarkAppId: string;
205
+ placement: V3ExternalPlacement;
206
+ /** Flow revision the attempt was dispatched under (1 = approved DAG). */
207
+ revision: number;
208
+ idempotency: V3HandoffIdempotency;
209
+ /** Engine clock (ms) at preparation; bounds same-key re-dispatch. */
210
+ preparedAt: number;
211
+ } | {
212
+ type: 'nodeHandoffSent';
213
+ nodeId: string;
214
+ instanceId?: string;
215
+ attemptId: string;
216
+ handoffMessageId: string;
217
+ nodeCardMessageId?: string;
218
+ threadId?: string;
219
+ sentAt: number;
220
+ /** Absolute engine-clock deadline for the target bot to accept. */
221
+ acceptDeadlineAt: number;
222
+ } | {
223
+ type: 'nodeHandoffAccepted';
224
+ nodeId: string;
225
+ instanceId?: string;
226
+ attemptId: string;
227
+ sessionId: string;
228
+ acceptedAt: number;
229
+ /** Absolute engine-clock deadline = acceptedAt + node timeoutSec. */
230
+ deadlineAt: number;
231
+ } | {
232
+ /** The bot's turn ended without a valid submission (display only). */
233
+ type: 'nodeStalled';
234
+ nodeId: string;
235
+ instanceId?: string;
236
+ attemptId: string;
237
+ at: number;
238
+ } | {
239
+ type: 'nodeReassigned';
240
+ nodeId: string;
241
+ instanceId?: string;
242
+ /** The open external attempt this reassignment closed, if any. */
243
+ attemptId?: string;
244
+ from: string;
245
+ to: string;
246
+ by: string;
247
+ /** Main-bot provenance of an automatic change (design §13.6). */
248
+ auto?: V3AutoProvenance;
47
249
  } | {
48
250
  type: 'hostInputPrepared';
49
251
  nodeId: string;
@@ -148,6 +350,9 @@ export type V3Event = {
148
350
  preview: string;
149
351
  by: string;
150
352
  };
353
+ /** Operator (`main_bot` for an automatic retry), when recorded. */
354
+ by?: string;
355
+ auto?: V3AutoProvenance;
151
356
  } | {
152
357
  type: 'gateDispatched';
153
358
  nodeId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "botmux-workflow-core",
3
- "version": "3.55.0",
3
+ "version": "3.57.0",
4
4
  "description": "Daemon-independent Workflow v3 schema, scheduler, control policy, and host contracts",
5
5
  "type": "module",
6
6
  "sideEffects": false,