pi-better-subagents 0.26.2 → 0.27.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.
- package/README.md +23 -6
- package/child-operations.ts +1109 -0
- package/child-ownership.ts +12 -1
- package/cleanup.ts +11 -2
- package/docs/usage.md +44 -3
- package/finalization.ts +53 -8
- package/goal-provider.ts +42 -4
- package/index.ts +549 -14
- package/lifecycle.ts +26 -0
- package/navigator.mjs +13 -2
- package/navigator.ts +1 -0
- package/operation-bridge-types.ts +1109 -0
- package/package.json +2 -1
- package/park-checkpoint.ts +61 -0
- package/parse.ts +19 -1
- package/registry.ts +192 -6
- package/session-store.ts +3 -0
- package/shared-execution-policy.ts +2 -0
- package/shared-operation-coordinator/index.ts +113 -0
- package/shared-operation-coordinator/src/errors.ts +75 -0
- package/shared-operation-coordinator/src/operations.ts +376 -0
- package/shared-operation-coordinator/src/outbox.ts +431 -0
- package/shared-operation-coordinator/src/rows.ts +439 -0
- package/shared-operation-coordinator/src/schema.ts +244 -0
- package/shared-operation-coordinator/src/sqlite.ts +239 -0
- package/shared-operation-coordinator/src/store.ts +397 -0
- package/shared-operation-coordinator/src/types.ts +648 -0
- package/shared-operation-coordinator/src/validate.ts +239 -0
- package/shared-operation-coordinator/src/waits.ts +1378 -0
- package/shared-task-exec.ts +9 -0
- package/stop.ts +7 -3
- package/task-guard.ts +22 -3
- package/task-policy.ts +7 -0
- package/worker-operations-host.ts +1226 -0
- package/worker-waits.ts +2549 -0
|
@@ -0,0 +1,439 @@
|
|
|
1
|
+
// Generated from packages/operation-coordinator/src/rows.ts. Do not edit directly.
|
|
2
|
+
/**
|
|
3
|
+
* Row mapping for the coordinator store.
|
|
4
|
+
*
|
|
5
|
+
* Reads are strict: a column that does not match its declared shape raises
|
|
6
|
+
* `store-corruption` instead of being coerced, so a damaged journal is reported
|
|
7
|
+
* rather than silently reinterpreted.
|
|
8
|
+
*/
|
|
9
|
+
import {
|
|
10
|
+
columnBoolean,
|
|
11
|
+
columnJson,
|
|
12
|
+
columnNullableNumber,
|
|
13
|
+
columnNullableText,
|
|
14
|
+
columnNumber,
|
|
15
|
+
columnText,
|
|
16
|
+
getRow,
|
|
17
|
+
getRows,
|
|
18
|
+
type StoreContext,
|
|
19
|
+
} from "./sqlite.ts";
|
|
20
|
+
import { StoreError } from "./errors.ts";
|
|
21
|
+
import type {
|
|
22
|
+
AcknowledgeDisposition,
|
|
23
|
+
EvidenceKind,
|
|
24
|
+
EvidencePinRecord,
|
|
25
|
+
EvidenceReadRecord,
|
|
26
|
+
ObserverHealth,
|
|
27
|
+
OperationEvidenceRecord,
|
|
28
|
+
OperationPhase,
|
|
29
|
+
OperationRecord,
|
|
30
|
+
OutboxDispatchClaim,
|
|
31
|
+
OutboxEventRecord,
|
|
32
|
+
OutboxState,
|
|
33
|
+
OwnerIdentity,
|
|
34
|
+
OwnerKind,
|
|
35
|
+
ResumeClaimRecord,
|
|
36
|
+
ResumeClaimState,
|
|
37
|
+
ResumeLeaseIdentity,
|
|
38
|
+
SupervisionIdentity,
|
|
39
|
+
TerminalOutcome,
|
|
40
|
+
WaitAcknowledgement,
|
|
41
|
+
WaitDependencyRecord,
|
|
42
|
+
WaitParkIntent,
|
|
43
|
+
WaitPhase,
|
|
44
|
+
WaitRecord,
|
|
45
|
+
} from "./types.ts";
|
|
46
|
+
|
|
47
|
+
// ---- owner identity -----------------------------------------------------
|
|
48
|
+
|
|
49
|
+
export function ownerFromRow(row: Record<string, unknown>, prefix = "owner"): OwnerIdentity {
|
|
50
|
+
const kind = columnText(row, `${prefix}_kind`) as OwnerKind;
|
|
51
|
+
return {
|
|
52
|
+
kind,
|
|
53
|
+
sessionId: columnText(row, `${prefix}_session_id`),
|
|
54
|
+
workspace: columnText(row, `${prefix}_workspace`),
|
|
55
|
+
branchId: columnNullableText(row, `${prefix}_branch_id`),
|
|
56
|
+
goalId: columnNullableText(row, `${prefix}_goal_id`),
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ---- operations ---------------------------------------------------------
|
|
61
|
+
|
|
62
|
+
export function getOperationRow(
|
|
63
|
+
ctx: StoreContext,
|
|
64
|
+
operationId: string,
|
|
65
|
+
): Record<string, unknown> | undefined {
|
|
66
|
+
return getRow(ctx, "SELECT * FROM operations WHERE operation_id = ?", operationId);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function getOperationRowByTask(
|
|
70
|
+
ctx: StoreContext,
|
|
71
|
+
taskId: string,
|
|
72
|
+
): Record<string, unknown> | undefined {
|
|
73
|
+
return getRow(ctx, "SELECT * FROM operations WHERE task_id = ?", taskId);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export function mapOperation(row: Record<string, unknown>): OperationRecord {
|
|
77
|
+
return {
|
|
78
|
+
operationId: columnText(row, "operation_id"),
|
|
79
|
+
taskId: columnText(row, "task_id"),
|
|
80
|
+
launchToken: columnText(row, "launch_token"),
|
|
81
|
+
owner: ownerFromRow(row),
|
|
82
|
+
observer: {
|
|
83
|
+
kind: columnText(row, "observer_kind"),
|
|
84
|
+
version: columnText(row, "observer_version"),
|
|
85
|
+
},
|
|
86
|
+
supervision: columnJson<SupervisionIdentity>(row, "supervision_json"),
|
|
87
|
+
authorityRef: columnNullableText(row, "authority_ref"),
|
|
88
|
+
intentRef: columnNullableText(row, "intent_ref"),
|
|
89
|
+
phase: columnText(row, "phase") as OperationPhase,
|
|
90
|
+
health: columnText(row, "health") as ObserverHealth,
|
|
91
|
+
healthReason: columnNullableText(row, "health_reason"),
|
|
92
|
+
terminalRevision: columnNumber(row, "terminal_revision"),
|
|
93
|
+
terminalOutcome: columnNullableText(row, "terminal_outcome") as TerminalOutcome | null,
|
|
94
|
+
terminalEventId: columnNullableText(row, "terminal_event_id"),
|
|
95
|
+
terminalDetailLost: columnBoolean(row, "terminal_detail_lost"),
|
|
96
|
+
terminalReason: columnNullableText(row, "terminal_reason"),
|
|
97
|
+
createdAt: columnNumber(row, "created_at"),
|
|
98
|
+
updatedAt: columnNumber(row, "updated_at"),
|
|
99
|
+
terminalAt: columnNullableNumber(row, "terminal_at"),
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function readOperation(ctx: StoreContext, operationId: string): OperationRecord | null {
|
|
104
|
+
const row = getOperationRow(ctx, operationId);
|
|
105
|
+
return row ? mapOperation(row) : null;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function requireOperation(ctx: StoreContext, operationId: string): OperationRecord {
|
|
109
|
+
const row = getOperationRow(ctx, operationId);
|
|
110
|
+
if (!row) {
|
|
111
|
+
throw new StoreError(
|
|
112
|
+
"unknown-operation",
|
|
113
|
+
`No durable operation is registered as ${operationId}. Register the launch before reporting a terminal outcome or waiting on it.`,
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
return mapOperation(row);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export function mapOperationEvidence(row: Record<string, unknown>): OperationEvidenceRecord {
|
|
120
|
+
const summary = columnNullableText(row, "summary");
|
|
121
|
+
const bytes = columnNullableNumber(row, "bytes");
|
|
122
|
+
const record: OperationEvidenceRecord = {
|
|
123
|
+
operationId: columnText(row, "operation_id"),
|
|
124
|
+
terminalRevision: columnNumber(row, "terminal_revision"),
|
|
125
|
+
ordinal: columnNumber(row, "ordinal"),
|
|
126
|
+
kind: columnText(row, "kind") as EvidenceKind,
|
|
127
|
+
ref: columnText(row, "ref"),
|
|
128
|
+
detailLost: columnBoolean(row, "detail_lost"),
|
|
129
|
+
capturedAt: columnNumber(row, "captured_at"),
|
|
130
|
+
};
|
|
131
|
+
if (summary !== null) record.summary = summary;
|
|
132
|
+
if (bytes !== null) record.bytes = bytes;
|
|
133
|
+
return record;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
export function readOperationEvidence(
|
|
137
|
+
ctx: StoreContext,
|
|
138
|
+
operationId: string,
|
|
139
|
+
terminalRevision?: number,
|
|
140
|
+
): OperationEvidenceRecord[] {
|
|
141
|
+
const rows = terminalRevision === undefined
|
|
142
|
+
? getRows(
|
|
143
|
+
ctx,
|
|
144
|
+
"SELECT * FROM operation_evidence WHERE operation_id = ? ORDER BY terminal_revision, ordinal",
|
|
145
|
+
operationId,
|
|
146
|
+
)
|
|
147
|
+
: getRows(
|
|
148
|
+
ctx,
|
|
149
|
+
"SELECT * FROM operation_evidence WHERE operation_id = ? AND terminal_revision = ? ORDER BY ordinal",
|
|
150
|
+
operationId,
|
|
151
|
+
terminalRevision,
|
|
152
|
+
);
|
|
153
|
+
return rows.map(mapOperationEvidence);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// ---- waits --------------------------------------------------------------
|
|
157
|
+
|
|
158
|
+
export function getWaitRow(
|
|
159
|
+
ctx: StoreContext,
|
|
160
|
+
waitId: string,
|
|
161
|
+
generation: number,
|
|
162
|
+
): Record<string, unknown> | undefined {
|
|
163
|
+
return getRow(ctx, "SELECT * FROM waits WHERE wait_id = ? AND generation = ?", waitId, generation);
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
export function latestWaitGeneration(ctx: StoreContext, waitId: string): number | null {
|
|
167
|
+
const row = getRow(ctx, "SELECT MAX(generation) AS generation FROM waits WHERE wait_id = ?", waitId);
|
|
168
|
+
if (!row) return null;
|
|
169
|
+
const value = columnNullableNumber(row, "generation");
|
|
170
|
+
return value ?? null;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export function readWaitRow(
|
|
174
|
+
ctx: StoreContext,
|
|
175
|
+
waitId: string,
|
|
176
|
+
generation?: number,
|
|
177
|
+
): Record<string, unknown> | null {
|
|
178
|
+
if (generation !== undefined) return getWaitRow(ctx, waitId, generation) ?? null;
|
|
179
|
+
const latest = latestWaitGeneration(ctx, waitId);
|
|
180
|
+
if (latest === null) return null;
|
|
181
|
+
return getWaitRow(ctx, waitId, latest) ?? null;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
export function requireWaitRow(
|
|
185
|
+
ctx: StoreContext,
|
|
186
|
+
waitId: string,
|
|
187
|
+
generation: number,
|
|
188
|
+
): Record<string, unknown> {
|
|
189
|
+
const row = getWaitRow(ctx, waitId, generation);
|
|
190
|
+
if (!row) {
|
|
191
|
+
throw new StoreError(
|
|
192
|
+
"unknown-wait",
|
|
193
|
+
`No wait generation ${generation} is registered for ${waitId}. Read the current generation before acting on it.`,
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
return row;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
export function readDependencies(
|
|
200
|
+
ctx: StoreContext,
|
|
201
|
+
waitId: string,
|
|
202
|
+
generation: number,
|
|
203
|
+
): WaitDependencyRecord[] {
|
|
204
|
+
return getRows(
|
|
205
|
+
ctx,
|
|
206
|
+
"SELECT * FROM wait_dependencies WHERE wait_id = ? AND generation = ? ORDER BY ordinal",
|
|
207
|
+
waitId,
|
|
208
|
+
generation,
|
|
209
|
+
).map((row) => ({
|
|
210
|
+
operationId: columnText(row, "operation_id"),
|
|
211
|
+
link: columnText(row, "link") as "owner" | "explicit",
|
|
212
|
+
terminalRevision: columnNumber(row, "terminal_revision"),
|
|
213
|
+
terminalOutcome: columnNullableText(row, "terminal_outcome") as TerminalOutcome | null,
|
|
214
|
+
settledAt: columnNullableNumber(row, "settled_at"),
|
|
215
|
+
}));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
export interface DependencyState {
|
|
219
|
+
dependencies: WaitDependencyRecord[];
|
|
220
|
+
/** Every dependency has a terminal revision. */
|
|
221
|
+
settled: boolean;
|
|
222
|
+
settledAt: number | null;
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
export function dependencyState(
|
|
226
|
+
ctx: StoreContext,
|
|
227
|
+
waitId: string,
|
|
228
|
+
generation: number,
|
|
229
|
+
): DependencyState {
|
|
230
|
+
const dependencies = readDependencies(ctx, waitId, generation);
|
|
231
|
+
const settled = dependencies.length > 0 && dependencies.every((dep) => dep.terminalRevision > 0);
|
|
232
|
+
const settledTimes = dependencies
|
|
233
|
+
.map((dep) => dep.settledAt)
|
|
234
|
+
.filter((value): value is number => value !== null);
|
|
235
|
+
return {
|
|
236
|
+
dependencies,
|
|
237
|
+
settled,
|
|
238
|
+
settledAt: settled && settledTimes.length > 0 ? Math.max(...settledTimes) : null,
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
export function mapWait(ctx: StoreContext, row: Record<string, unknown>): WaitRecord {
|
|
243
|
+
const waitId = columnText(row, "wait_id");
|
|
244
|
+
const generation = columnNumber(row, "generation");
|
|
245
|
+
const state = dependencyState(ctx, waitId, generation);
|
|
246
|
+
const acknowledgement = columnJson<WaitAcknowledgement>(row, "acknowledgement_json");
|
|
247
|
+
return {
|
|
248
|
+
waitId,
|
|
249
|
+
generation,
|
|
250
|
+
owner: ownerFromRow(row),
|
|
251
|
+
phase: columnText(row, "phase") as WaitPhase,
|
|
252
|
+
phaseReason: columnNullableText(row, "phase_reason"),
|
|
253
|
+
cancelEpoch: columnNumber(row, "cancel_epoch"),
|
|
254
|
+
continuationNote: columnText(row, "continuation_note"),
|
|
255
|
+
park: columnJson<WaitParkIntent>(row, "park_json"),
|
|
256
|
+
origin: columnJson<WaitRecord["origin"]>(row, "origin_json"),
|
|
257
|
+
dependencies: state.dependencies,
|
|
258
|
+
settled: state.settled,
|
|
259
|
+
settledAt: state.settledAt,
|
|
260
|
+
acknowledgement: acknowledgement
|
|
261
|
+
? { ...acknowledgement, disposition: acknowledgement.disposition as AcknowledgeDisposition }
|
|
262
|
+
: null,
|
|
263
|
+
createdAt: columnNumber(row, "created_at"),
|
|
264
|
+
updatedAt: columnNumber(row, "updated_at"),
|
|
265
|
+
};
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
export function readWait(ctx: StoreContext, waitId: string, generation?: number): WaitRecord | null {
|
|
269
|
+
const row = readWaitRow(ctx, waitId, generation);
|
|
270
|
+
return row ? mapWait(ctx, row) : null;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
export function requireWait(ctx: StoreContext, waitId: string, generation: number): WaitRecord {
|
|
274
|
+
return mapWait(ctx, requireWaitRow(ctx, waitId, generation));
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
// ---- resume claims ------------------------------------------------------
|
|
278
|
+
|
|
279
|
+
export function mapClaim(row: Record<string, unknown>): ResumeClaimRecord {
|
|
280
|
+
return {
|
|
281
|
+
claimId: columnText(row, "claim_id"),
|
|
282
|
+
claimToken: columnText(row, "claim_token"),
|
|
283
|
+
waitId: columnText(row, "wait_id"),
|
|
284
|
+
generation: columnNumber(row, "generation"),
|
|
285
|
+
cancelEpoch: columnNumber(row, "cancel_epoch"),
|
|
286
|
+
state: columnText(row, "state") as ResumeClaimState,
|
|
287
|
+
attemptId: columnNullableText(row, "attempt_id"),
|
|
288
|
+
launchToken: columnNullableText(row, "launch_token"),
|
|
289
|
+
lease: columnJson<ResumeLeaseIdentity>(row, "lease_json") ?? { ownerId: "unknown" },
|
|
290
|
+
reservedCheckpointId: columnText(row, "reserved_checkpoint_id"),
|
|
291
|
+
claimedAt: columnNumber(row, "claimed_at"),
|
|
292
|
+
publishedAt: columnNullableNumber(row, "published_at"),
|
|
293
|
+
releasedAt: columnNullableNumber(row, "released_at"),
|
|
294
|
+
invalidatedAt: columnNullableNumber(row, "invalidated_at"),
|
|
295
|
+
reason: columnNullableText(row, "reason"),
|
|
296
|
+
};
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
export function readClaim(ctx: StoreContext, claimId: string): ResumeClaimRecord | null {
|
|
300
|
+
const row = getRow(ctx, "SELECT * FROM resume_claims WHERE claim_id = ?", claimId);
|
|
301
|
+
return row ? mapClaim(row) : null;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
export function readActiveClaim(
|
|
305
|
+
ctx: StoreContext,
|
|
306
|
+
waitId: string,
|
|
307
|
+
generation: number,
|
|
308
|
+
): ResumeClaimRecord | null {
|
|
309
|
+
const row = getRow(
|
|
310
|
+
ctx,
|
|
311
|
+
"SELECT * FROM resume_claims WHERE wait_id = ? AND generation = ? AND state IN ('claimed', 'published')",
|
|
312
|
+
waitId,
|
|
313
|
+
generation,
|
|
314
|
+
);
|
|
315
|
+
return row ? mapClaim(row) : null;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
export function requireClaim(ctx: StoreContext, claimId: string): ResumeClaimRecord {
|
|
319
|
+
const claim = readClaim(ctx, claimId);
|
|
320
|
+
if (!claim) {
|
|
321
|
+
throw new StoreError(
|
|
322
|
+
"claim-state",
|
|
323
|
+
`No resume claim ${claimId} is recorded. Claims are created by claimResume and are not caller-supplied.`,
|
|
324
|
+
);
|
|
325
|
+
}
|
|
326
|
+
return claim;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
// ---- evidence reads and pins -------------------------------------------
|
|
330
|
+
|
|
331
|
+
export function mapEvidenceRead(row: Record<string, unknown>): EvidenceReadRecord {
|
|
332
|
+
return {
|
|
333
|
+
waitId: columnText(row, "wait_id"),
|
|
334
|
+
generation: columnNumber(row, "generation"),
|
|
335
|
+
operationId: columnText(row, "operation_id"),
|
|
336
|
+
terminalRevision: columnNumber(row, "terminal_revision"),
|
|
337
|
+
reader: {
|
|
338
|
+
kind: columnText(row, "reader_kind") as OwnerKind,
|
|
339
|
+
sessionId: columnText(row, "reader_session_id"),
|
|
340
|
+
workspace: columnText(row, "reader_workspace"),
|
|
341
|
+
branchId: columnNullableText(row, "reader_branch_id"),
|
|
342
|
+
goalId: columnNullableText(row, "reader_goal_id"),
|
|
343
|
+
},
|
|
344
|
+
readAt: columnNumber(row, "read_at"),
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
export function mapEvidencePin(row: Record<string, unknown>): EvidencePinRecord {
|
|
349
|
+
return {
|
|
350
|
+
pinId: columnText(row, "pin_id"),
|
|
351
|
+
waitId: columnText(row, "wait_id"),
|
|
352
|
+
generation: columnNumber(row, "generation"),
|
|
353
|
+
operationId: columnText(row, "operation_id"),
|
|
354
|
+
terminalRevision: columnNumber(row, "terminal_revision"),
|
|
355
|
+
kind: columnText(row, "kind") as EvidenceKind,
|
|
356
|
+
ref: columnText(row, "ref"),
|
|
357
|
+
summary: columnNullableText(row, "summary"),
|
|
358
|
+
detailLost: columnBoolean(row, "detail_lost"),
|
|
359
|
+
bytes: columnNullableNumber(row, "bytes"),
|
|
360
|
+
pinnedAt: columnNumber(row, "pinned_at"),
|
|
361
|
+
releasedAt: columnNullableNumber(row, "released_at"),
|
|
362
|
+
releaseReason: columnNullableText(row, "release_reason"),
|
|
363
|
+
};
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
export function readPins(
|
|
367
|
+
ctx: StoreContext,
|
|
368
|
+
waitId: string,
|
|
369
|
+
generation: number,
|
|
370
|
+
includeReleased: boolean,
|
|
371
|
+
): EvidencePinRecord[] {
|
|
372
|
+
const rows = includeReleased
|
|
373
|
+
? getRows(
|
|
374
|
+
ctx,
|
|
375
|
+
"SELECT * FROM evidence_pins WHERE wait_id = ? AND generation = ? ORDER BY pinned_at, pin_id",
|
|
376
|
+
waitId,
|
|
377
|
+
generation,
|
|
378
|
+
)
|
|
379
|
+
: getRows(
|
|
380
|
+
ctx,
|
|
381
|
+
"SELECT * FROM evidence_pins WHERE wait_id = ? AND generation = ? AND released_at IS NULL ORDER BY pinned_at, pin_id",
|
|
382
|
+
waitId,
|
|
383
|
+
generation,
|
|
384
|
+
);
|
|
385
|
+
return rows.map(mapEvidencePin);
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
export function readPinsForRevision(
|
|
389
|
+
ctx: StoreContext,
|
|
390
|
+
waitId: string,
|
|
391
|
+
generation: number,
|
|
392
|
+
operationId: string,
|
|
393
|
+
terminalRevision: number,
|
|
394
|
+
): EvidencePinRecord[] {
|
|
395
|
+
return getRows(
|
|
396
|
+
ctx,
|
|
397
|
+
`SELECT * FROM evidence_pins
|
|
398
|
+
WHERE wait_id = ? AND generation = ? AND operation_id = ? AND terminal_revision = ?
|
|
399
|
+
ORDER BY pinned_at, pin_id`,
|
|
400
|
+
waitId,
|
|
401
|
+
generation,
|
|
402
|
+
operationId,
|
|
403
|
+
terminalRevision,
|
|
404
|
+
).map(mapEvidencePin);
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
// ---- outbox -------------------------------------------------------------
|
|
408
|
+
|
|
409
|
+
export function mapOutbox(ctx: StoreContext, row: Record<string, unknown>): OutboxEventRecord {
|
|
410
|
+
const waitId = columnText(row, "wait_id");
|
|
411
|
+
const generation = columnNumber(row, "generation");
|
|
412
|
+
const operationId = columnText(row, "operation_id");
|
|
413
|
+
const terminalRevision = columnNumber(row, "terminal_revision");
|
|
414
|
+
return {
|
|
415
|
+
eventId: columnText(row, "event_id"),
|
|
416
|
+
operationId,
|
|
417
|
+
terminalRevision,
|
|
418
|
+
waitId,
|
|
419
|
+
generation,
|
|
420
|
+
recipient: ownerFromRow(row, "recipient"),
|
|
421
|
+
evidence: readPinsForRevision(ctx, waitId, generation, operationId, terminalRevision),
|
|
422
|
+
state: columnText(row, "state") as OutboxState,
|
|
423
|
+
attempts: columnNumber(row, "attempts"),
|
|
424
|
+
dispatchClaim: columnJson<OutboxDispatchClaim>(row, "dispatch_claim_json"),
|
|
425
|
+
createdAt: columnNumber(row, "created_at"),
|
|
426
|
+
claimedAt: columnNullableNumber(row, "claimed_at"),
|
|
427
|
+
deliveredAt: columnNullableNumber(row, "delivered_at"),
|
|
428
|
+
acknowledgedAt: columnNullableNumber(row, "acknowledged_at"),
|
|
429
|
+
voidedAt: columnNullableNumber(row, "voided_at"),
|
|
430
|
+
reason: columnNullableText(row, "reason"),
|
|
431
|
+
};
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
export function readOutboxRow(
|
|
435
|
+
ctx: StoreContext,
|
|
436
|
+
eventId: string,
|
|
437
|
+
): Record<string, unknown> | null {
|
|
438
|
+
return getRow(ctx, "SELECT * FROM outbox_events WHERE event_id = ?", eventId) ?? null;
|
|
439
|
+
}
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
// Generated from packages/operation-coordinator/src/schema.ts. Do not edit directly.
|
|
2
|
+
/**
|
|
3
|
+
* Schema v1 for the durable operation coordinator.
|
|
4
|
+
*
|
|
5
|
+
* The store refuses to open a database whose recorded version it does not
|
|
6
|
+
* understand, and leaves the file untouched. An unreadable or newer database
|
|
7
|
+
* disables the feature; it never deletes records to recover.
|
|
8
|
+
*
|
|
9
|
+
* Uniqueness constraints carry lifecycle invariants into the database itself:
|
|
10
|
+
*
|
|
11
|
+
* - one durable operation per background task id;
|
|
12
|
+
* - one pending wait generation per owner identity (partial unique index);
|
|
13
|
+
* - one active resume claim per wait generation (partial unique index);
|
|
14
|
+
* - one outbox event per terminal revision per wait generation;
|
|
15
|
+
* - one evidence pin per reference and one evidence read per revision.
|
|
16
|
+
*/
|
|
17
|
+
import { SCHEMA_VERSION } from "./types.ts";
|
|
18
|
+
import { StoreError } from "./errors.ts";
|
|
19
|
+
import { columnText, getRow, getRows, run, type StoreContext } from "./sqlite.ts";
|
|
20
|
+
|
|
21
|
+
const DDL: readonly string[] = [
|
|
22
|
+
`CREATE TABLE schema_meta (
|
|
23
|
+
key TEXT PRIMARY KEY,
|
|
24
|
+
value TEXT NOT NULL
|
|
25
|
+
)`,
|
|
26
|
+
`CREATE TABLE operations (
|
|
27
|
+
operation_id TEXT PRIMARY KEY,
|
|
28
|
+
task_id TEXT NOT NULL UNIQUE,
|
|
29
|
+
launch_token TEXT NOT NULL,
|
|
30
|
+
owner_kind TEXT NOT NULL,
|
|
31
|
+
owner_session_id TEXT NOT NULL,
|
|
32
|
+
owner_workspace TEXT NOT NULL,
|
|
33
|
+
owner_branch_id TEXT,
|
|
34
|
+
owner_goal_id TEXT,
|
|
35
|
+
observer_kind TEXT NOT NULL,
|
|
36
|
+
observer_version TEXT NOT NULL,
|
|
37
|
+
supervision_json TEXT,
|
|
38
|
+
authority_ref TEXT,
|
|
39
|
+
intent_ref TEXT,
|
|
40
|
+
phase TEXT NOT NULL,
|
|
41
|
+
health TEXT NOT NULL,
|
|
42
|
+
health_reason TEXT,
|
|
43
|
+
terminal_revision INTEGER NOT NULL DEFAULT 0,
|
|
44
|
+
terminal_outcome TEXT,
|
|
45
|
+
terminal_event_id TEXT,
|
|
46
|
+
terminal_detail_lost INTEGER NOT NULL DEFAULT 0,
|
|
47
|
+
terminal_reason TEXT,
|
|
48
|
+
created_at INTEGER NOT NULL,
|
|
49
|
+
updated_at INTEGER NOT NULL,
|
|
50
|
+
terminal_at INTEGER
|
|
51
|
+
)`,
|
|
52
|
+
`CREATE INDEX operations_owner ON operations (owner_kind, owner_session_id)`,
|
|
53
|
+
`CREATE INDEX operations_phase ON operations (phase)`,
|
|
54
|
+
`CREATE TABLE operation_evidence (
|
|
55
|
+
operation_id TEXT NOT NULL REFERENCES operations (operation_id),
|
|
56
|
+
terminal_revision INTEGER NOT NULL,
|
|
57
|
+
ordinal INTEGER NOT NULL,
|
|
58
|
+
kind TEXT NOT NULL,
|
|
59
|
+
ref TEXT NOT NULL,
|
|
60
|
+
summary TEXT,
|
|
61
|
+
detail_lost INTEGER NOT NULL DEFAULT 0,
|
|
62
|
+
bytes INTEGER,
|
|
63
|
+
captured_at INTEGER NOT NULL,
|
|
64
|
+
PRIMARY KEY (operation_id, terminal_revision, ordinal)
|
|
65
|
+
)`,
|
|
66
|
+
`CREATE TABLE waits (
|
|
67
|
+
wait_id TEXT NOT NULL,
|
|
68
|
+
generation INTEGER NOT NULL,
|
|
69
|
+
owner_kind TEXT NOT NULL,
|
|
70
|
+
owner_session_id TEXT NOT NULL,
|
|
71
|
+
owner_workspace TEXT NOT NULL,
|
|
72
|
+
owner_branch_id TEXT,
|
|
73
|
+
owner_goal_id TEXT,
|
|
74
|
+
phase TEXT NOT NULL,
|
|
75
|
+
phase_reason TEXT,
|
|
76
|
+
cancel_epoch INTEGER NOT NULL DEFAULT 0,
|
|
77
|
+
continuation_note TEXT NOT NULL,
|
|
78
|
+
park_json TEXT,
|
|
79
|
+
origin_json TEXT,
|
|
80
|
+
settled_at INTEGER,
|
|
81
|
+
acknowledged_at INTEGER,
|
|
82
|
+
acknowledgement_json TEXT,
|
|
83
|
+
created_at INTEGER NOT NULL,
|
|
84
|
+
updated_at INTEGER NOT NULL,
|
|
85
|
+
PRIMARY KEY (wait_id, generation)
|
|
86
|
+
)`,
|
|
87
|
+
// At most one generation per owner identity (session + branch) may be pending.
|
|
88
|
+
`CREATE UNIQUE INDEX waits_one_pending_per_owner
|
|
89
|
+
ON waits (owner_kind, owner_session_id, coalesce(owner_branch_id, ''))
|
|
90
|
+
WHERE phase NOT IN ('consumed', 'cancelled')`,
|
|
91
|
+
`CREATE INDEX waits_owner ON waits (owner_kind, owner_session_id)`,
|
|
92
|
+
`CREATE TABLE wait_dependencies (
|
|
93
|
+
wait_id TEXT NOT NULL,
|
|
94
|
+
generation INTEGER NOT NULL,
|
|
95
|
+
ordinal INTEGER NOT NULL,
|
|
96
|
+
operation_id TEXT NOT NULL REFERENCES operations (operation_id),
|
|
97
|
+
link TEXT NOT NULL,
|
|
98
|
+
terminal_revision INTEGER NOT NULL DEFAULT 0,
|
|
99
|
+
terminal_outcome TEXT,
|
|
100
|
+
settled_at INTEGER,
|
|
101
|
+
PRIMARY KEY (wait_id, generation, operation_id)
|
|
102
|
+
)`,
|
|
103
|
+
`CREATE INDEX wait_dependencies_operation ON wait_dependencies (operation_id, terminal_revision)`,
|
|
104
|
+
`CREATE TABLE resume_claims (
|
|
105
|
+
claim_id TEXT PRIMARY KEY,
|
|
106
|
+
wait_id TEXT NOT NULL,
|
|
107
|
+
generation INTEGER NOT NULL,
|
|
108
|
+
cancel_epoch INTEGER NOT NULL,
|
|
109
|
+
claim_token TEXT NOT NULL UNIQUE,
|
|
110
|
+
state TEXT NOT NULL,
|
|
111
|
+
attempt_id TEXT UNIQUE,
|
|
112
|
+
launch_token TEXT,
|
|
113
|
+
lease_json TEXT NOT NULL,
|
|
114
|
+
reserved_checkpoint_id TEXT NOT NULL,
|
|
115
|
+
claimed_at INTEGER NOT NULL,
|
|
116
|
+
published_at INTEGER,
|
|
117
|
+
released_at INTEGER,
|
|
118
|
+
invalidated_at INTEGER,
|
|
119
|
+
reason TEXT
|
|
120
|
+
)`,
|
|
121
|
+
`CREATE UNIQUE INDEX resume_claims_one_active
|
|
122
|
+
ON resume_claims (wait_id, generation)
|
|
123
|
+
WHERE state IN ('claimed', 'published')`,
|
|
124
|
+
`CREATE TABLE evidence_reads (
|
|
125
|
+
wait_id TEXT NOT NULL,
|
|
126
|
+
generation INTEGER NOT NULL,
|
|
127
|
+
operation_id TEXT NOT NULL,
|
|
128
|
+
terminal_revision INTEGER NOT NULL,
|
|
129
|
+
reader_kind TEXT NOT NULL,
|
|
130
|
+
reader_session_id TEXT NOT NULL,
|
|
131
|
+
reader_workspace TEXT NOT NULL,
|
|
132
|
+
reader_branch_id TEXT,
|
|
133
|
+
reader_goal_id TEXT,
|
|
134
|
+
read_at INTEGER NOT NULL,
|
|
135
|
+
PRIMARY KEY (wait_id, generation, operation_id, terminal_revision)
|
|
136
|
+
)`,
|
|
137
|
+
`CREATE TABLE evidence_pins (
|
|
138
|
+
pin_id TEXT PRIMARY KEY,
|
|
139
|
+
wait_id TEXT NOT NULL,
|
|
140
|
+
generation INTEGER NOT NULL,
|
|
141
|
+
operation_id TEXT NOT NULL,
|
|
142
|
+
terminal_revision INTEGER NOT NULL,
|
|
143
|
+
kind TEXT NOT NULL,
|
|
144
|
+
ref TEXT NOT NULL,
|
|
145
|
+
summary TEXT,
|
|
146
|
+
detail_lost INTEGER NOT NULL DEFAULT 0,
|
|
147
|
+
bytes INTEGER,
|
|
148
|
+
pinned_at INTEGER NOT NULL,
|
|
149
|
+
released_at INTEGER,
|
|
150
|
+
release_reason TEXT
|
|
151
|
+
)`,
|
|
152
|
+
`CREATE UNIQUE INDEX evidence_pins_reference
|
|
153
|
+
ON evidence_pins (wait_id, generation, operation_id, terminal_revision, kind, ref)`,
|
|
154
|
+
`CREATE INDEX evidence_pins_operation ON evidence_pins (operation_id, terminal_revision, released_at)`,
|
|
155
|
+
`CREATE TABLE outbox_events (
|
|
156
|
+
event_id TEXT PRIMARY KEY,
|
|
157
|
+
operation_id TEXT NOT NULL,
|
|
158
|
+
terminal_revision INTEGER NOT NULL,
|
|
159
|
+
wait_id TEXT NOT NULL,
|
|
160
|
+
generation INTEGER NOT NULL,
|
|
161
|
+
recipient_kind TEXT NOT NULL,
|
|
162
|
+
recipient_session_id TEXT NOT NULL,
|
|
163
|
+
recipient_workspace TEXT NOT NULL,
|
|
164
|
+
recipient_branch_id TEXT,
|
|
165
|
+
recipient_goal_id TEXT,
|
|
166
|
+
state TEXT NOT NULL,
|
|
167
|
+
attempts INTEGER NOT NULL DEFAULT 0,
|
|
168
|
+
dispatch_claim_json TEXT,
|
|
169
|
+
created_at INTEGER NOT NULL,
|
|
170
|
+
claimed_at INTEGER,
|
|
171
|
+
delivered_at INTEGER,
|
|
172
|
+
acknowledged_at INTEGER,
|
|
173
|
+
voided_at INTEGER,
|
|
174
|
+
reason TEXT,
|
|
175
|
+
UNIQUE (operation_id, terminal_revision, wait_id, generation)
|
|
176
|
+
)`,
|
|
177
|
+
`CREATE INDEX outbox_recipient ON outbox_events (recipient_kind, recipient_session_id, state)`,
|
|
178
|
+
`CREATE INDEX outbox_wait ON outbox_events (wait_id, generation)`,
|
|
179
|
+
];
|
|
180
|
+
|
|
181
|
+
const SCHEMA_VERSION_KEY = "schema_version";
|
|
182
|
+
|
|
183
|
+
function existingTables(ctx: StoreContext): string[] {
|
|
184
|
+
return getRows(
|
|
185
|
+
ctx,
|
|
186
|
+
`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`,
|
|
187
|
+
).map((row) => columnText(row, "name"));
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Create the schema on an empty database, or verify the recorded version.
|
|
192
|
+
* Any mismatch refuses without modifying the file.
|
|
193
|
+
*/
|
|
194
|
+
export function ensureSchema(ctx: StoreContext): void {
|
|
195
|
+
const tables = existingTables(ctx);
|
|
196
|
+
const hasMeta = tables.includes("schema_meta");
|
|
197
|
+
if (!hasMeta) {
|
|
198
|
+
if (tables.length > 0) {
|
|
199
|
+
throw new StoreError(
|
|
200
|
+
"schema-version",
|
|
201
|
+
`The database at this path holds tables (${tables.join(", ")}) but no ${SCHEMA_VERSION_KEY}. It was not written by the operation coordinator; refusing to reuse or clear it.`,
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
ctx.transaction(() => {
|
|
205
|
+
for (const statement of DDL) ctx.db.exec(statement);
|
|
206
|
+
run(ctx, "INSERT INTO schema_meta (key, value) VALUES (?, ?)", SCHEMA_VERSION_KEY, String(SCHEMA_VERSION));
|
|
207
|
+
});
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
const row = getRow(ctx, "SELECT value FROM schema_meta WHERE key = ?", SCHEMA_VERSION_KEY);
|
|
212
|
+
if (!row) {
|
|
213
|
+
throw new StoreError(
|
|
214
|
+
"schema-version",
|
|
215
|
+
`The database at this path has no ${SCHEMA_VERSION_KEY} record. Refusing to read or migrate unknown records.`,
|
|
216
|
+
);
|
|
217
|
+
}
|
|
218
|
+
const raw = columnText(row, "value");
|
|
219
|
+
const recorded = Number(raw);
|
|
220
|
+
if (!Number.isInteger(recorded) || recorded < 1) {
|
|
221
|
+
throw new StoreError(
|
|
222
|
+
"schema-version",
|
|
223
|
+
`The database records schema version ${JSON.stringify(raw)}, which is not a usable version. Records are left in place.`,
|
|
224
|
+
);
|
|
225
|
+
}
|
|
226
|
+
if (recorded > SCHEMA_VERSION) {
|
|
227
|
+
throw new StoreError(
|
|
228
|
+
"schema-version",
|
|
229
|
+
`The database was written by schema version ${recorded}; this build understands version ${SCHEMA_VERSION}. Upgrade the harness instead of downgrading the records.`,
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
if (recorded < SCHEMA_VERSION) {
|
|
233
|
+
throw new StoreError(
|
|
234
|
+
"schema-version",
|
|
235
|
+
`The database is at schema version ${recorded}; this build needs version ${SCHEMA_VERSION}. No migration is provided for this pair; records are left in place.`,
|
|
236
|
+
);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/** Test and diagnostic seam: read the recorded schema version without opening a store. */
|
|
241
|
+
export function readSchemaVersion(ctx: StoreContext): number | null {
|
|
242
|
+
const row = getRow(ctx, "SELECT value FROM schema_meta WHERE key = ?", SCHEMA_VERSION_KEY);
|
|
243
|
+
return row ? Number(columnText(row, "value")) : null;
|
|
244
|
+
}
|