owenloop 0.2.0 → 0.3.1
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/CHANGELOG.md +65 -0
- package/README.md +94 -7
- package/bin/owenloop.mjs +2 -2
- package/dist/add.d.ts +412 -0
- package/dist/add.js +999 -0
- package/dist/cli.d.ts +47 -0
- package/dist/cli.js +1809 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +171 -21
- package/dist/engine.d.ts +395 -40
- package/dist/engine.js +1118 -135
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +290 -0
- package/dist/hub.js +408 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/model.js +20 -9
- package/dist/store.d.ts +14 -2
- package/dist/store.js +285 -35
- package/dist/types.d.ts +120 -0
- package/dist/untar.d.ts +47 -0
- package/dist/untar.js +164 -0
- package/dist/util.d.ts +76 -0
- package/dist/util.js +96 -0
- package/docs/authoring.md +118 -1
- package/docs/cli.md +446 -3
- package/docs/design.md +259 -32
- package/docs/embedding.md +81 -10
- package/examples/workflows/command-worker.yaml +56 -0
- package/package.json +1 -1
package/dist/store.js
CHANGED
|
@@ -52,6 +52,35 @@ CREATE TABLE IF NOT EXISTS artifact (
|
|
|
52
52
|
CREATE INDEX IF NOT EXISTS artifact_wf ON artifact (workflow);
|
|
53
53
|
CREATE INDEX IF NOT EXISTS artifact_wf_accept ON artifact (workflow, acceptance);
|
|
54
54
|
|
|
55
|
+
-- Immutable audit history. artifact remains the small current-state projection.
|
|
56
|
+
CREATE TABLE IF NOT EXISTS artifact_version (
|
|
57
|
+
id TEXT PRIMARY KEY,
|
|
58
|
+
workflow TEXT NOT NULL,
|
|
59
|
+
path TEXT NOT NULL,
|
|
60
|
+
version INTEGER NOT NULL,
|
|
61
|
+
producer TEXT NOT NULL,
|
|
62
|
+
value TEXT,
|
|
63
|
+
fingerprint TEXT,
|
|
64
|
+
initial_acceptance TEXT NOT NULL,
|
|
65
|
+
created_at INTEGER NOT NULL,
|
|
66
|
+
UNIQUE (workflow, path, version)
|
|
67
|
+
);
|
|
68
|
+
CREATE INDEX IF NOT EXISTS artifact_version_wf_path ON artifact_version (workflow, path, version);
|
|
69
|
+
|
|
70
|
+
CREATE TABLE IF NOT EXISTS artifact_event (
|
|
71
|
+
id TEXT PRIMARY KEY,
|
|
72
|
+
workflow TEXT NOT NULL,
|
|
73
|
+
path TEXT NOT NULL,
|
|
74
|
+
version INTEGER NOT NULL,
|
|
75
|
+
action TEXT NOT NULL,
|
|
76
|
+
actor TEXT NOT NULL,
|
|
77
|
+
reason TEXT,
|
|
78
|
+
kind TEXT,
|
|
79
|
+
metadata TEXT,
|
|
80
|
+
created_at INTEGER NOT NULL
|
|
81
|
+
);
|
|
82
|
+
CREATE INDEX IF NOT EXISTS artifact_event_wf_path_version_at ON artifact_event (workflow, path, version, created_at, id);
|
|
83
|
+
|
|
55
84
|
CREATE TABLE IF NOT EXISTS task (
|
|
56
85
|
id TEXT PRIMARY KEY,
|
|
57
86
|
workflow TEXT NOT NULL,
|
|
@@ -79,6 +108,10 @@ CREATE TABLE IF NOT EXISTS run (
|
|
|
79
108
|
session_id TEXT,
|
|
80
109
|
fingerprint TEXT,
|
|
81
110
|
cause TEXT,
|
|
111
|
+
-- The flattened order packet issued at claim time (§8 / Gap 1), JSON in TEXT
|
|
112
|
+
-- (precedent: fingerprint, def_snapshot). Named order_json, NOT order — ORDER
|
|
113
|
+
-- is a reserved SQL keyword. Nullable: absent on runs created before v7.
|
|
114
|
+
order_json TEXT,
|
|
82
115
|
created_at INTEGER NOT NULL,
|
|
83
116
|
updated_at INTEGER NOT NULL
|
|
84
117
|
);
|
|
@@ -103,8 +136,16 @@ CREATE TABLE IF NOT EXISTS meta (
|
|
|
103
136
|
*
|
|
104
137
|
* Bumped to '6' for instance-to-definition pinning (§28): the `workflow`
|
|
105
138
|
* table gains `def_snapshot`/`def_hash` columns (see `migrate()`).
|
|
139
|
+
*
|
|
140
|
+
* Bumped to '7' for claim-time order-packet persistence (§8 / Gap 1): the `run`
|
|
141
|
+
* table gains `order_json` (see `migrate()`).
|
|
142
|
+
* Bumped to '8' for REL-5: a partial UNIQUE index on the child-instance
|
|
143
|
+
* parent-coordinates (`produced_by_wf`, `produced_by_path`) so two concurrent
|
|
144
|
+
* driver ticks cannot each insert a child for the same `calls:` step.
|
|
145
|
+
*
|
|
146
|
+
* Bumped to '9' for immutable artifact payload/version and lifecycle-event history.
|
|
106
147
|
*/
|
|
107
|
-
const SCHEMA_VERSION = '
|
|
148
|
+
const SCHEMA_VERSION = '9';
|
|
108
149
|
/** Thrown by the `Store` constructor when the on-disk `schema_version` is
|
|
109
150
|
* newer than this binary's `SCHEMA_VERSION` — the operator needs to
|
|
110
151
|
* upgrade their owenloop install to open this database. */
|
|
@@ -114,6 +155,58 @@ export class StoreVersionError extends Error {
|
|
|
114
155
|
function toJson(v) {
|
|
115
156
|
return v === undefined ? null : JSON.stringify(v);
|
|
116
157
|
}
|
|
158
|
+
/**
|
|
159
|
+
* Key-order-independent canonical serialization of a JSON-shaped value.
|
|
160
|
+
* Plain objects are rebuilt with their keys sorted and `undefined`-valued
|
|
161
|
+
* properties dropped (mirroring `JSON.stringify`, so `{ x: undefined }` and
|
|
162
|
+
* `{}` canonicalize the same). Array order is preserved — `reasons` is an
|
|
163
|
+
* append-only thread whose order is significant. Values passed here already
|
|
164
|
+
* round-trip through JSON columns, so no Date/Map/cycle handling is needed.
|
|
165
|
+
* Used by `putArtifact` to decide "changed vs no-op" without being fooled by
|
|
166
|
+
* property insertion order (which would append a false `artifact_event`).
|
|
167
|
+
*/
|
|
168
|
+
function canonicalJson(v) {
|
|
169
|
+
return JSON.stringify(canonicalize(v));
|
|
170
|
+
}
|
|
171
|
+
function canonicalize(v) {
|
|
172
|
+
if (Array.isArray(v))
|
|
173
|
+
return v.map(canonicalize);
|
|
174
|
+
if (v !== null && typeof v === 'object') {
|
|
175
|
+
const src = v;
|
|
176
|
+
const out = {};
|
|
177
|
+
for (const k of Object.keys(src).sort()) {
|
|
178
|
+
if (src[k] !== undefined)
|
|
179
|
+
out[k] = canonicalize(src[k]);
|
|
180
|
+
}
|
|
181
|
+
return out;
|
|
182
|
+
}
|
|
183
|
+
return v;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* The semantic fields of an artifact that define "has this changed?" — an
|
|
187
|
+
* explicit projection so identity/timestamp columns (`id`, `updatedAt`) and
|
|
188
|
+
* insertion order never influence the decision. `terminal` is normalized to a
|
|
189
|
+
* boolean because `mapArtifact` always materializes it while callers may omit
|
|
190
|
+
* it; without this, every repeat write that omits `terminal` would read as
|
|
191
|
+
* changed and append a false event.
|
|
192
|
+
*/
|
|
193
|
+
function artifactSemantics(x) {
|
|
194
|
+
return {
|
|
195
|
+
workflow: x.workflow,
|
|
196
|
+
path: x.path,
|
|
197
|
+
producer: x.producer,
|
|
198
|
+
acceptance: x.acceptance,
|
|
199
|
+
version: x.version,
|
|
200
|
+
value: x.value,
|
|
201
|
+
fingerprint: x.fingerprint,
|
|
202
|
+
reasons: x.reasons,
|
|
203
|
+
judgmentRejects: x.judgmentRejects,
|
|
204
|
+
schemaRejects: x.schemaRejects,
|
|
205
|
+
sealOf: x.sealOf,
|
|
206
|
+
terminal: x.terminal ?? false,
|
|
207
|
+
approvals: x.approvals,
|
|
208
|
+
};
|
|
209
|
+
}
|
|
117
210
|
function fromJson(s, fallback, ctx) {
|
|
118
211
|
if (s === null || s === undefined)
|
|
119
212
|
return fallback;
|
|
@@ -164,6 +257,33 @@ function mapArtifact(r) {
|
|
|
164
257
|
out.approvals = approvals;
|
|
165
258
|
return out;
|
|
166
259
|
}
|
|
260
|
+
function mapArtifactVersion(r) {
|
|
261
|
+
const out = {
|
|
262
|
+
id: r.id, workflow: r.workflow, path: r.path, version: r.version, producer: r.producer,
|
|
263
|
+
initialAcceptance: r.initial_acceptance, createdAt: r.created_at,
|
|
264
|
+
};
|
|
265
|
+
const value = fromJson(r.value, undefined, { table: 'artifact_version', id: r.id, column: 'value' });
|
|
266
|
+
const fingerprint = fromJson(r.fingerprint, undefined, { table: 'artifact_version', id: r.id, column: 'fingerprint' });
|
|
267
|
+
if (value !== undefined)
|
|
268
|
+
out.value = value;
|
|
269
|
+
if (fingerprint !== undefined)
|
|
270
|
+
out.fingerprint = fingerprint;
|
|
271
|
+
return out;
|
|
272
|
+
}
|
|
273
|
+
function mapArtifactEvent(r) {
|
|
274
|
+
const out = {
|
|
275
|
+
id: r.id, workflow: r.workflow, path: r.path, version: r.version, action: r.action,
|
|
276
|
+
actor: r.actor, timestamp: r.created_at,
|
|
277
|
+
};
|
|
278
|
+
if (r.reason !== null)
|
|
279
|
+
out.reason = r.reason;
|
|
280
|
+
if (r.kind !== null)
|
|
281
|
+
out.kind = r.kind;
|
|
282
|
+
const metadata = fromJson(r.metadata, undefined, { table: 'artifact_event', id: r.id, column: 'metadata' });
|
|
283
|
+
if (metadata !== undefined)
|
|
284
|
+
out.metadata = metadata;
|
|
285
|
+
return out;
|
|
286
|
+
}
|
|
167
287
|
function mapTask(r) {
|
|
168
288
|
const out = {
|
|
169
289
|
id: r.id,
|
|
@@ -208,6 +328,13 @@ function mapRun(r) {
|
|
|
208
328
|
out.fingerprint = fp;
|
|
209
329
|
if (r.cause !== null)
|
|
210
330
|
out.cause = r.cause;
|
|
331
|
+
const order = fromJson(r.order_json, undefined, {
|
|
332
|
+
table: 'run',
|
|
333
|
+
id: r.id,
|
|
334
|
+
column: 'order_json',
|
|
335
|
+
});
|
|
336
|
+
if (order !== undefined)
|
|
337
|
+
out.order = order;
|
|
211
338
|
return out;
|
|
212
339
|
}
|
|
213
340
|
function mapWorkflow(r) {
|
|
@@ -238,24 +365,51 @@ export class Store {
|
|
|
238
365
|
db;
|
|
239
366
|
constructor(path) {
|
|
240
367
|
this.db = new DatabaseSync(path);
|
|
241
|
-
|
|
368
|
+
// Connection-scoped only — no file mutation, safe before the version check.
|
|
242
369
|
this.db.exec('PRAGMA busy_timeout = 5000');
|
|
370
|
+
// Refuse an on-disk schema newer than this binary before any file-mutating
|
|
371
|
+
// pragma or DDL. Re-check again under the migration write lock below.
|
|
372
|
+
try {
|
|
373
|
+
this.refuseIfNewer();
|
|
374
|
+
}
|
|
375
|
+
catch (err) {
|
|
376
|
+
this.db.close();
|
|
377
|
+
throw err;
|
|
378
|
+
}
|
|
379
|
+
this.db.exec('PRAGMA journal_mode = WAL');
|
|
243
380
|
this.db.exec('PRAGMA foreign_keys = ON');
|
|
244
381
|
this.db.exec('PRAGMA synchronous = NORMAL');
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
382
|
+
try {
|
|
383
|
+
this.tx(() => {
|
|
384
|
+
const cur = this.refuseIfNewer();
|
|
385
|
+
this.premigrate();
|
|
386
|
+
this.db.exec(SCHEMA);
|
|
387
|
+
// Version 9 introduces immutable history. Earlier databases have no
|
|
388
|
+
// retained historical payloads, but their lifecycle reasons can be
|
|
389
|
+
// copied into append-only events exactly once.
|
|
390
|
+
const backfillLegacyEvents = cur !== undefined && parseInt(cur, 10) < 9;
|
|
391
|
+
this.migrate(backfillLegacyEvents);
|
|
392
|
+
if (cur !== SCHEMA_VERSION)
|
|
393
|
+
this.setMeta('schema_version', SCHEMA_VERSION);
|
|
394
|
+
});
|
|
395
|
+
}
|
|
396
|
+
catch (err) {
|
|
397
|
+
if (err instanceof StoreVersionError)
|
|
398
|
+
this.db.close();
|
|
399
|
+
throw err;
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
/** Read the stored schema version without writing, refusing newer databases. */
|
|
403
|
+
refuseIfNewer() {
|
|
404
|
+
const metaExists = this.db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'`).get() !== undefined;
|
|
405
|
+
if (!metaExists)
|
|
406
|
+
return undefined;
|
|
248
407
|
const cur = this.getMeta('schema_version');
|
|
249
|
-
if (cur !== undefined) {
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
if (curNum > ownNum) {
|
|
253
|
-
throw new StoreVersionError(`database schema_version ${cur} is newer than this owenloop's schema_version ${SCHEMA_VERSION}; ` +
|
|
254
|
-
`upgrade your owenloop install to open this database`);
|
|
255
|
-
}
|
|
408
|
+
if (cur !== undefined && parseInt(cur, 10) > parseInt(SCHEMA_VERSION, 10)) {
|
|
409
|
+
throw new StoreVersionError(`database schema_version ${cur} is newer than this owenloop's schema_version ${SCHEMA_VERSION}; ` +
|
|
410
|
+
`upgrade your owenloop install to open this database`);
|
|
256
411
|
}
|
|
257
|
-
|
|
258
|
-
this.setMeta('schema_version', SCHEMA_VERSION);
|
|
412
|
+
return cur;
|
|
259
413
|
}
|
|
260
414
|
close() {
|
|
261
415
|
this.db.close();
|
|
@@ -295,7 +449,7 @@ export class Store {
|
|
|
295
449
|
* (no `schema_rejects`) needs an explicit `ALTER TABLE`. Additive and
|
|
296
450
|
* idempotent — safe to run on every open.
|
|
297
451
|
*/
|
|
298
|
-
migrate() {
|
|
452
|
+
migrate(backfillLegacyEvents) {
|
|
299
453
|
const artifactCols = this.db.prepare(`PRAGMA table_info(artifact)`).all();
|
|
300
454
|
if (!artifactCols.some((c) => c.name === 'schema_rejects')) {
|
|
301
455
|
this.db.exec(`ALTER TABLE artifact ADD COLUMN schema_rejects INTEGER NOT NULL DEFAULT 0`);
|
|
@@ -304,6 +458,10 @@ export class Store {
|
|
|
304
458
|
if (!runCols.some((c) => c.name === 'cause')) {
|
|
305
459
|
this.db.exec(`ALTER TABLE run ADD COLUMN cause TEXT`);
|
|
306
460
|
}
|
|
461
|
+
// §8 / Gap 1: claim-time order-packet persistence (schema v7).
|
|
462
|
+
if (!runCols.some((c) => c.name === 'order_json')) {
|
|
463
|
+
this.db.exec(`ALTER TABLE run ADD COLUMN order_json TEXT`);
|
|
464
|
+
}
|
|
307
465
|
const taskCols = this.db.prepare(`PRAGMA table_info(task)`).all();
|
|
308
466
|
if (!taskCols.some((c) => c.name === 'alarm_at')) {
|
|
309
467
|
this.db.exec(`ALTER TABLE task ADD COLUMN alarm_at INTEGER`);
|
|
@@ -321,6 +479,20 @@ export class Store {
|
|
|
321
479
|
}
|
|
322
480
|
// Reverse-lookup index (CREATE INDEX IF NOT EXISTS is idempotent).
|
|
323
481
|
this.db.exec(`CREATE INDEX IF NOT EXISTS workflow_produced_by ON workflow(produced_by_wf, produced_by_path)`);
|
|
482
|
+
// REL-5 (schema v8): make duplicate calls: children physically impossible
|
|
483
|
+
// for future writers. Legacy duplicates are tolerated until cleaned up.
|
|
484
|
+
const dupe = this.db
|
|
485
|
+
.prepare(`SELECT 1 FROM workflow
|
|
486
|
+
WHERE produced_by_wf IS NOT NULL AND produced_by_path IS NOT NULL
|
|
487
|
+
GROUP BY produced_by_wf, produced_by_path
|
|
488
|
+
HAVING COUNT(*) > 1
|
|
489
|
+
LIMIT 1`)
|
|
490
|
+
.get();
|
|
491
|
+
if (dupe === undefined) {
|
|
492
|
+
this.db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS workflow_produced_by_unique
|
|
493
|
+
ON workflow(produced_by_wf, produced_by_path)
|
|
494
|
+
WHERE produced_by_wf IS NOT NULL AND produced_by_path IS NOT NULL`);
|
|
495
|
+
}
|
|
324
496
|
// §24: judges — the per-version sign-off ledger (judge name -> approved version).
|
|
325
497
|
if (!artifactCols.some((c) => c.name === 'approvals')) {
|
|
326
498
|
this.db.exec(`ALTER TABLE artifact ADD COLUMN approvals TEXT`);
|
|
@@ -334,6 +506,27 @@ export class Store {
|
|
|
334
506
|
if (!wfCols.some((c) => c.name === 'def_hash')) {
|
|
335
507
|
this.db.exec(`ALTER TABLE workflow ADD COLUMN def_hash TEXT`);
|
|
336
508
|
}
|
|
509
|
+
// Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
|
|
510
|
+
// reason thread. Re-opening an already-v8 database must not manufacture a
|
|
511
|
+
// second copy of its lifecycle events (even though the legacy keys differ
|
|
512
|
+
// from regular reason-event keys). Historical payloads overwritten before
|
|
513
|
+
// v8 remain unrecoverable by design.
|
|
514
|
+
if (backfillLegacyEvents) {
|
|
515
|
+
const legacy = this.db.prepare('SELECT * FROM artifact').all();
|
|
516
|
+
for (const raw of legacy) {
|
|
517
|
+
const art = mapArtifact(raw);
|
|
518
|
+
for (let i = 0; i < art.reasons.length; i++) {
|
|
519
|
+
const reason = art.reasons[i];
|
|
520
|
+
this.insertArtifactEvent({
|
|
521
|
+
workflow: art.workflow, path: art.path,
|
|
522
|
+
version: reason.fromVersion ?? art.version,
|
|
523
|
+
action: reason.action, actor: reason.by, reason: reason.text,
|
|
524
|
+
timestamp: reason.at, kind: reason.kind,
|
|
525
|
+
key: `legacy:${i}:${reason.at}:${reason.action}:${reason.by}:${reason.text}`,
|
|
526
|
+
});
|
|
527
|
+
}
|
|
528
|
+
}
|
|
529
|
+
}
|
|
337
530
|
}
|
|
338
531
|
/**
|
|
339
532
|
* Run `fn` in a `BEGIN IMMEDIATE` transaction (write lock acquired up front).
|
|
@@ -397,6 +590,8 @@ export class Store {
|
|
|
397
590
|
/** Deletes only this workflow's own rows (artifact/task/run/workflow). Does NOT
|
|
398
591
|
* cascade to children spawned via calls: — see deleteWorkflowCascade for that. */
|
|
399
592
|
deleteWorkflow(id) {
|
|
593
|
+
this.db.prepare('DELETE FROM artifact_event WHERE workflow = ?').run(id);
|
|
594
|
+
this.db.prepare('DELETE FROM artifact_version WHERE workflow = ?').run(id);
|
|
400
595
|
this.db.prepare('DELETE FROM artifact WHERE workflow = ?').run(id);
|
|
401
596
|
this.db.prepare('DELETE FROM task WHERE workflow = ?').run(id);
|
|
402
597
|
this.db.prepare('DELETE FROM run WHERE workflow = ?').run(id);
|
|
@@ -419,7 +614,7 @@ export class Store {
|
|
|
419
614
|
*/
|
|
420
615
|
findChildByParent(parentWf, parentPath) {
|
|
421
616
|
const r = this.db
|
|
422
|
-
.prepare('SELECT * FROM workflow WHERE produced_by_wf = ? AND produced_by_path = ?')
|
|
617
|
+
.prepare('SELECT * FROM workflow WHERE produced_by_wf = ? AND produced_by_path = ? ORDER BY created_at, id LIMIT 1')
|
|
423
618
|
.get(parentWf, parentPath);
|
|
424
619
|
return r ? mapWorkflow(r) : undefined;
|
|
425
620
|
}
|
|
@@ -434,7 +629,10 @@ export class Store {
|
|
|
434
629
|
}
|
|
435
630
|
// -- artifact ----------------------------------------------------------------
|
|
436
631
|
getArtifact(workflow, path) {
|
|
437
|
-
|
|
632
|
+
const r = this.db
|
|
633
|
+
.prepare('SELECT * FROM artifact WHERE workflow = ? AND path = ?')
|
|
634
|
+
.get(workflow, path);
|
|
635
|
+
return r ? mapArtifact(r) : undefined;
|
|
438
636
|
}
|
|
439
637
|
getArtifactById(id) {
|
|
440
638
|
const r = this.db.prepare('SELECT * FROM artifact WHERE id = ?').get(id);
|
|
@@ -447,16 +645,17 @@ export class Store {
|
|
|
447
645
|
return rows.map(mapArtifact);
|
|
448
646
|
}
|
|
449
647
|
/** Insert or fully replace the artifact at (workflow, path). */
|
|
450
|
-
putArtifact(data) {
|
|
648
|
+
putArtifact(data, provenance) {
|
|
649
|
+
const previous = this.getArtifact(data.workflow, data.path);
|
|
451
650
|
const id = artifactId(data.workflow, data.path);
|
|
452
|
-
const at = nowMs();
|
|
651
|
+
const at = provenance?.timestamp ?? nowMs();
|
|
453
652
|
this.db
|
|
454
653
|
.prepare(`INSERT INTO artifact
|
|
455
654
|
(id, workflow, path, producer, acceptance, version, value, fingerprint,
|
|
456
655
|
reasons, judgment_rejects, schema_rejects, seal_of, terminal, approvals, updated_at)
|
|
457
656
|
VALUES (@id, @workflow, @path, @producer, @acceptance, @version, @value, @fingerprint,
|
|
458
657
|
@reasons, @judgment_rejects, @schema_rejects, @seal_of, @terminal, @approvals, @updated_at)
|
|
459
|
-
ON CONFLICT(
|
|
658
|
+
ON CONFLICT(workflow, path) DO UPDATE SET
|
|
460
659
|
producer = excluded.producer,
|
|
461
660
|
acceptance = excluded.acceptance,
|
|
462
661
|
version = excluded.version,
|
|
@@ -486,14 +685,65 @@ export class Store {
|
|
|
486
685
|
approvals: toJson(data.approvals),
|
|
487
686
|
updated_at: at,
|
|
488
687
|
});
|
|
489
|
-
|
|
688
|
+
const changed = !previous || canonicalJson(artifactSemantics(previous)) !== canonicalJson(artifactSemantics(data));
|
|
689
|
+
if (changed) {
|
|
690
|
+
if (data.version > 0 && (!previous || data.version > previous.version)) {
|
|
691
|
+
this.db.prepare(`INSERT INTO artifact_version (id, workflow, path, version, producer, value, fingerprint, initial_acceptance, created_at)
|
|
692
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(workflow, path, version) DO NOTHING`).run(detId('artver', data.workflow, data.path, String(data.version)), data.workflow, data.path, data.version, data.producer, toJson(data.value), toJson(data.fingerprint), data.acceptance, at);
|
|
693
|
+
}
|
|
694
|
+
const appended = previous ? data.reasons.slice(previous.reasons.length) : data.reasons;
|
|
695
|
+
if (appended.length) {
|
|
696
|
+
for (let i = 0; i < appended.length; i++) {
|
|
697
|
+
const r = appended[i];
|
|
698
|
+
this.insertArtifactEvent({ workflow: data.workflow, path: data.path, version: r.fromVersion ?? data.version,
|
|
699
|
+
action: r.action, actor: r.by, reason: r.text, timestamp: r.at, kind: r.kind,
|
|
700
|
+
key: `reason:${previous?.reasons.length ?? 0}:${i}:${r.at}:${r.action}:${r.by}:${r.text}` });
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
else {
|
|
704
|
+
const action = provenance?.action ?? (data.version > (previous?.version ?? 0)
|
|
705
|
+
? (data.acceptance === 'submitted' ? 'submitted' : 'produced')
|
|
706
|
+
: data.acceptance !== previous?.acceptance ? data.acceptance : 'updated');
|
|
707
|
+
this.insertArtifactEvent({ workflow: data.workflow, path: data.path, version: data.version, action,
|
|
708
|
+
actor: provenance?.actor ?? (data.producer || 'engine'), reason: provenance?.reason,
|
|
709
|
+
timestamp: at, kind: provenance?.kind, key: provenance?.key });
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
return this.getArtifact(data.workflow, data.path);
|
|
713
|
+
}
|
|
714
|
+
insertArtifactEvent(event) {
|
|
715
|
+
const identity = event.key ?? `${event.action}:${event.actor}:${event.reason ?? ''}:${event.timestamp}:${event.kind ?? ''}`;
|
|
716
|
+
const id = detId('artevt', event.workflow, event.path, String(event.version), identity);
|
|
717
|
+
this.db.prepare(`INSERT INTO artifact_event (id, workflow, path, version, action, actor, reason, kind, metadata, created_at)
|
|
718
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING`).run(id, event.workflow, event.path, event.version, event.action, event.actor, event.reason ?? null, event.kind ?? null, toJson(event.metadata), event.timestamp);
|
|
719
|
+
}
|
|
720
|
+
/** Returns history for exactly one artifact; list/status reads stay projection-only. */
|
|
721
|
+
getArtifactHistory(workflow, path) {
|
|
722
|
+
const current = this.getArtifact(workflow, path);
|
|
723
|
+
if (!current)
|
|
724
|
+
return undefined;
|
|
725
|
+
const versions = this.db.prepare('SELECT * FROM artifact_version WHERE workflow = ? AND path = ? ORDER BY version, created_at, id').all(workflow, path).map(mapArtifactVersion);
|
|
726
|
+
const events = this.db.prepare('SELECT * FROM artifact_event WHERE workflow = ? AND path = ? ORDER BY created_at, id').all(workflow, path).map(mapArtifactEvent);
|
|
727
|
+
const versioned = new Set(versions.map((v) => v.version));
|
|
728
|
+
return {
|
|
729
|
+
current,
|
|
730
|
+
versions: versions.map((v) => ({ ...v, events: events.filter((e) => e.version === v.version) })),
|
|
731
|
+
// A pre-v8 reason can point at an overwritten version whose payload
|
|
732
|
+
// cannot be reconstructed. Keep that event visible at the artifact
|
|
733
|
+
// level rather than silently dropping it from history.
|
|
734
|
+
events: events.filter((e) => !versioned.has(e.version)),
|
|
735
|
+
};
|
|
490
736
|
}
|
|
491
737
|
deleteArtifact(workflow, path) {
|
|
492
|
-
this.db.prepare('DELETE FROM
|
|
738
|
+
this.db.prepare('DELETE FROM artifact_event WHERE workflow = ? AND path = ?').run(workflow, path);
|
|
739
|
+
this.db.prepare('DELETE FROM artifact_version WHERE workflow = ? AND path = ?').run(workflow, path);
|
|
740
|
+
this.db.prepare('DELETE FROM artifact WHERE workflow = ? AND path = ?').run(workflow, path);
|
|
493
741
|
}
|
|
494
742
|
// -- task --------------------------------------------------------------------
|
|
495
743
|
getTask(workflow, step, key) {
|
|
496
|
-
const r = this.db
|
|
744
|
+
const r = this.db
|
|
745
|
+
.prepare('SELECT * FROM task WHERE workflow = ? AND step = ? AND key = ?')
|
|
746
|
+
.get(workflow, step, key);
|
|
497
747
|
return r ? mapTask(r) : undefined;
|
|
498
748
|
}
|
|
499
749
|
listTasks(workflow) {
|
|
@@ -514,7 +764,7 @@ export class Store {
|
|
|
514
764
|
this.db
|
|
515
765
|
.prepare(`INSERT INTO task (id, workflow, step, key, status, run, claimed_at, attempts, alarm_at, heartbeat_at, updated_at)
|
|
516
766
|
VALUES (@id, @workflow, @step, @key, @status, @run, @claimed_at, @attempts, @alarm_at, @heartbeat_at, @updated_at)
|
|
517
|
-
ON CONFLICT(
|
|
767
|
+
ON CONFLICT(workflow, step, key) DO UPDATE SET
|
|
518
768
|
status = excluded.status,
|
|
519
769
|
run = excluded.run,
|
|
520
770
|
claimed_at = excluded.claimed_at,
|
|
@@ -544,11 +794,10 @@ export class Store {
|
|
|
544
794
|
}
|
|
545
795
|
/** Persist an absolute alarm time for an idle evaluator step. */
|
|
546
796
|
setAlarm(workflow, step, at) {
|
|
547
|
-
const id = taskId(workflow, step, '');
|
|
548
797
|
const existing = this.getTask(workflow, step, '');
|
|
549
798
|
if (existing) {
|
|
550
|
-
this.db.prepare('UPDATE task SET alarm_at = ?, updated_at = ? WHERE
|
|
551
|
-
.run(at, nowMs(),
|
|
799
|
+
this.db.prepare('UPDATE task SET alarm_at = ?, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?')
|
|
800
|
+
.run(at, nowMs(), workflow, step, '');
|
|
552
801
|
}
|
|
553
802
|
else {
|
|
554
803
|
// Rare: evaluator step has never been ticked. Insert a minimal idle row.
|
|
@@ -557,14 +806,12 @@ export class Store {
|
|
|
557
806
|
}
|
|
558
807
|
/** Clear the alarm (set alarm_at = NULL). */
|
|
559
808
|
clearAlarm(workflow, step) {
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
.run(nowMs(), id);
|
|
809
|
+
this.db.prepare('UPDATE task SET alarm_at = NULL, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?')
|
|
810
|
+
.run(nowMs(), workflow, step, '');
|
|
563
811
|
}
|
|
564
812
|
/** Update only heartbeat_at on the task row — targeted write, no read-modify-write. */
|
|
565
813
|
touchHeartbeat(workflow, step, key, now) {
|
|
566
|
-
|
|
567
|
-
this.db.prepare('UPDATE task SET heartbeat_at = ?, updated_at = ? WHERE id = ?').run(now, nowMs(), id);
|
|
814
|
+
this.db.prepare('UPDATE task SET heartbeat_at = ?, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?').run(now, nowMs(), workflow, step, key);
|
|
568
815
|
}
|
|
569
816
|
/**
|
|
570
817
|
* Derive last_progress as MAX(artifact.updated_at) for the workflow.
|
|
@@ -579,15 +826,18 @@ export class Store {
|
|
|
579
826
|
// -- run ---------------------------------------------------------------------
|
|
580
827
|
insertRun(id, data, at = nowMs()) {
|
|
581
828
|
this.db
|
|
582
|
-
.prepare(`INSERT INTO run (id, workflow, step, key, outcome, summary, session_id, fingerprint, cause, created_at, updated_at)
|
|
583
|
-
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
584
|
-
.run(id, data.workflow, data.step, data.key ?? '', data.outcome ?? null, data.summary ?? null, data.sessionId ?? null, toJson(data.fingerprint), data.cause ?? null, at, at);
|
|
829
|
+
.prepare(`INSERT INTO run (id, workflow, step, key, outcome, summary, session_id, fingerprint, cause, order_json, created_at, updated_at)
|
|
830
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
831
|
+
.run(id, data.workflow, data.step, data.key ?? '', data.outcome ?? null, data.summary ?? null, data.sessionId ?? null, toJson(data.fingerprint), data.cause ?? null, toJson(data.order), at, at);
|
|
585
832
|
return this.getRun(id);
|
|
586
833
|
}
|
|
587
834
|
updateRun(id, patch) {
|
|
588
835
|
const cur = this.getRun(id);
|
|
589
836
|
if (!cur)
|
|
590
837
|
throw new Error(`run not found: ${id}`);
|
|
838
|
+
// order_json is DELIBERATELY excluded from `merged` and the UPDATE below:
|
|
839
|
+
// the order packet is immutable after claim (§8 / Gap 1). Omitting it makes
|
|
840
|
+
// that structural — no close/outcome/summary write can ever clobber it.
|
|
591
841
|
const merged = {
|
|
592
842
|
workflow: cur.workflow,
|
|
593
843
|
step: cur.step,
|
package/dist/types.d.ts
CHANGED
|
@@ -71,6 +71,43 @@ export interface ArtifactData {
|
|
|
71
71
|
/** §24 judges: sign-off ledger — judge name → version that judge approved */
|
|
72
72
|
approvals?: Record<string, number>;
|
|
73
73
|
}
|
|
74
|
+
/** An immutable payload snapshot made whenever an artifact receives a new version. */
|
|
75
|
+
export interface ArtifactVersion {
|
|
76
|
+
id: string;
|
|
77
|
+
workflow: string;
|
|
78
|
+
path: string;
|
|
79
|
+
version: number;
|
|
80
|
+
producer: string;
|
|
81
|
+
value?: Record<string, unknown>;
|
|
82
|
+
fingerprint?: Fingerprint;
|
|
83
|
+
initialAcceptance: Acceptance;
|
|
84
|
+
createdAt: number;
|
|
85
|
+
}
|
|
86
|
+
/** One immutable lifecycle transition for an artifact version (version 0 is valid). */
|
|
87
|
+
export interface ArtifactEvent {
|
|
88
|
+
id: string;
|
|
89
|
+
workflow: string;
|
|
90
|
+
path: string;
|
|
91
|
+
version: number;
|
|
92
|
+
action: string;
|
|
93
|
+
actor: Author;
|
|
94
|
+
reason?: string;
|
|
95
|
+
timestamp: number;
|
|
96
|
+
kind?: RejectKind;
|
|
97
|
+
metadata?: Record<string, unknown>;
|
|
98
|
+
}
|
|
99
|
+
/** Narrow history read used by consumers that open a single artifact. */
|
|
100
|
+
export interface ArtifactHistory {
|
|
101
|
+
current: ArtifactData & {
|
|
102
|
+
id: string;
|
|
103
|
+
updatedAt: number;
|
|
104
|
+
};
|
|
105
|
+
versions: Array<ArtifactVersion & {
|
|
106
|
+
events: ArtifactEvent[];
|
|
107
|
+
}>;
|
|
108
|
+
/** Events associated with version zero, before a payload has been produced. */
|
|
109
|
+
events: ArtifactEvent[];
|
|
110
|
+
}
|
|
74
111
|
/** A task/lease node — the claimable unit of work-in-flight (design §2.2). */
|
|
75
112
|
export interface TaskData {
|
|
76
113
|
workflow: string;
|
|
@@ -86,6 +123,45 @@ export interface TaskData {
|
|
|
86
123
|
alarmAt?: number;
|
|
87
124
|
}
|
|
88
125
|
/** A run node — audit/budget trail, and the holder of a claim's fingerprint. */
|
|
126
|
+
/** A self-contained unit of work emitted by a tick. */
|
|
127
|
+
export interface Order {
|
|
128
|
+
run: string;
|
|
129
|
+
workflow: string;
|
|
130
|
+
step: string;
|
|
131
|
+
key: string;
|
|
132
|
+
index?: number;
|
|
133
|
+
inputs: string[];
|
|
134
|
+
outputs: string[];
|
|
135
|
+
workdir?: string;
|
|
136
|
+
model?: string;
|
|
137
|
+
/** Declares which kind of executor this order is for. Absent = 'agent'
|
|
138
|
+
* (today's behavior). Opaque to the engine; carried through verbatim from
|
|
139
|
+
* the step definition, same pass-through contract as `model`/`x`. */
|
|
140
|
+
worker?: string;
|
|
141
|
+
/** The command string for a `worker: command` order. Opaque to the engine
|
|
142
|
+
* — never parsed, never shelled out. */
|
|
143
|
+
command?: string;
|
|
144
|
+
/** Opaque config object for a non-agent/non-command worker type (or
|
|
145
|
+
* alongside `command`). Carried through untouched, contents never read. */
|
|
146
|
+
spec?: Record<string, unknown>;
|
|
147
|
+
/** §27.3: the step's opaque `x:` extension map, carried through untouched
|
|
148
|
+
* (same pass-through contract as `model`). The engine never reads it —
|
|
149
|
+
* it exists for the external runner/tooling consuming this order. */
|
|
150
|
+
x?: Record<string, unknown>;
|
|
151
|
+
prompt: string;
|
|
152
|
+
/** captured handles of the green inputs this run builds on */
|
|
153
|
+
consumes: Record<string, unknown>;
|
|
154
|
+
/** the owed outputs and their accumulated reason threads (the feedback channel) */
|
|
155
|
+
owes: Array<{
|
|
156
|
+
path: string;
|
|
157
|
+
acceptance: string;
|
|
158
|
+
judgmentRejects: number;
|
|
159
|
+
schemaRejects: number;
|
|
160
|
+
reasons: ReasonEntry[];
|
|
161
|
+
}>;
|
|
162
|
+
/** The trigger that woke this firing (§21). Absent = 'inputsGreen'. */
|
|
163
|
+
cause?: FiringTrigger;
|
|
164
|
+
}
|
|
89
165
|
export interface RunData {
|
|
90
166
|
workflow: string;
|
|
91
167
|
step: string;
|
|
@@ -97,6 +173,12 @@ export interface RunData {
|
|
|
97
173
|
fingerprint?: Fingerprint;
|
|
98
174
|
/** The firing trigger that woke this run (§21). Absent = 'inputsGreen'. */
|
|
99
175
|
cause?: FiringTrigger;
|
|
176
|
+
/** The flattened order packet issued at claim time (§8 / Gap 1) — the exact
|
|
177
|
+
* Order buildOrder emitted, written in the SAME transaction that created
|
|
178
|
+
* this run. Immutable after insert: updateRun never touches it. The
|
|
179
|
+
* replay/eval/paper-trail record (buildOrder is deterministic modulo run
|
|
180
|
+
* id). Absent on runs created before schema v7. */
|
|
181
|
+
order?: Order;
|
|
100
182
|
}
|
|
101
183
|
export interface WorkflowData {
|
|
102
184
|
def: string;
|
|
@@ -173,6 +255,17 @@ export interface ProducePattern {
|
|
|
173
255
|
inputs?: boolean;
|
|
174
256
|
cadence?: string;
|
|
175
257
|
maxRunsPerDay?: number;
|
|
258
|
+
/** Declares which kind of executor this judge's synthesized order is for.
|
|
259
|
+
* Same opaque-passthrough contract as StepDef.worker — default 'agent'
|
|
260
|
+
* when omitted. */
|
|
261
|
+
worker?: string;
|
|
262
|
+
/** Required when worker is 'command'; the command string for that worker
|
|
263
|
+
* to run. Opaque to the engine — never parsed, never shelled out. */
|
|
264
|
+
command?: string;
|
|
265
|
+
/** Optional opaque config object for a non-agent/non-command worker type
|
|
266
|
+
* (or additionally alongside `command`). Shape-checked as a plain map
|
|
267
|
+
* only (mirrors `x:`'s asExtension contract) — contents never read. */
|
|
268
|
+
spec?: Record<string, unknown>;
|
|
176
269
|
}>;
|
|
177
270
|
}
|
|
178
271
|
/**
|
|
@@ -227,6 +320,19 @@ export interface StepDef {
|
|
|
227
320
|
* model.ts effectiveMaxSchemaFailures()). */
|
|
228
321
|
maxSchemaFailures: number;
|
|
229
322
|
model?: string;
|
|
323
|
+
/** Declares which kind of executor this step's order is for. Default
|
|
324
|
+
* 'agent' when omitted (today's behavior — every existing def is
|
|
325
|
+
* unchanged). Opaque to the engine beyond the shape rules validateDef
|
|
326
|
+
* enforces; carried through verbatim on the Order, same contract as
|
|
327
|
+
* `model`. */
|
|
328
|
+
worker?: string;
|
|
329
|
+
/** Required when worker is 'command'; the command string for that worker
|
|
330
|
+
* to run. Opaque to the engine — never parsed, never shelled out. */
|
|
331
|
+
command?: string;
|
|
332
|
+
/** Optional opaque config object for a non-agent/non-command worker type
|
|
333
|
+
* (or additionally alongside `command`). Shape-checked as a plain map
|
|
334
|
+
* only (mirrors `x:`'s asExtension contract) — contents never read. */
|
|
335
|
+
spec?: Record<string, unknown>;
|
|
230
336
|
/** opaque location hint passed through on the order; no default — absent unless the def sets it */
|
|
231
337
|
workdir?: string;
|
|
232
338
|
/** the step's output is a destructive completion (e.g. a merge): green is terminal (§15.2) */
|
|
@@ -241,6 +347,16 @@ export interface StepDef {
|
|
|
241
347
|
idleAfterMs?: number;
|
|
242
348
|
/** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
|
|
243
349
|
reapTtlMs?: number;
|
|
350
|
+
/** A2: opaque routing labels for peer-orchestrator claim filtering. A tick
|
|
351
|
+
* caller passing a label filter only claims steps whose labels intersect it;
|
|
352
|
+
* absent (or empty, normalized to absent at parse) = claimable by any caller.
|
|
353
|
+
* Distinct from `worker`/`workers` (executor-kind), which this never touches. */
|
|
354
|
+
labels?: string[];
|
|
355
|
+
/** A3 (REL-8): per-step OPT-IN max total lease lifetime override in
|
|
356
|
+
* milliseconds — the cap on `claimedAt + maxLease` past which renewals can no
|
|
357
|
+
* longer keep a lease fresh. Overrides the engine `maxLeaseMs`; when both are
|
|
358
|
+
* unset there is NO cap and heartbeats extend the lease indefinitely. */
|
|
359
|
+
maxLeaseMs?: number;
|
|
244
360
|
body: string;
|
|
245
361
|
/** Mode 2 foundation: name of the child workflow this step delegates to. Machine-handled, never a worker firing. */
|
|
246
362
|
calls?: string;
|
|
@@ -283,6 +399,10 @@ export interface WorkflowDef {
|
|
|
283
399
|
/** §27.3: opaque workflow-level extension map (`x:`). Validated as a plain
|
|
284
400
|
* map at load time, never interpreted by the engine. */
|
|
285
401
|
x?: Record<string, unknown>;
|
|
402
|
+
/** Optional allow-list of worker values; when present, validateDef errors
|
|
403
|
+
* on any step/judge whose `worker` is not in this list (typo guard).
|
|
404
|
+
* Absent = any worker string accepted. */
|
|
405
|
+
workers?: string[];
|
|
286
406
|
}
|
|
287
407
|
export interface InputDef {
|
|
288
408
|
name: string;
|