owenloop 0.2.1 → 0.4.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/CHANGELOG.md +67 -0
- package/README.md +82 -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 +43 -0
- package/dist/cli.js +1865 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +112 -19
- package/dist/engine.d.ts +338 -50
- package/dist/engine.js +854 -170
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +514 -0
- package/dist/hub.js +783 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/store.d.ts +14 -2
- package/dist/store.js +269 -21
- package/dist/types.d.ts +92 -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 +48 -1
- package/docs/cli.md +509 -3
- package/docs/design.md +72 -9
- package/docs/embedding.md +87 -7
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -12,12 +12,14 @@
|
|
|
12
12
|
* process — software delivery, research, triage — on top of it.
|
|
13
13
|
*/
|
|
14
14
|
export { Engine } from './engine.ts';
|
|
15
|
-
export type { CommitResult, CreateOpts, DefResolver, DeferredFiring, DeferredReason, EmitResult, EngineEvent, EngineListener, EngineWorkflowStatus, Order, TickResult, } from './engine.ts';
|
|
15
|
+
export type { CommitResult, CreateOpts, DefResolver, DeferredFiring, DeferredReason, EmitResult, EngineEvent, EngineListener, EngineWorkflowStatus, Order, ReapDetail, ReapReason, TickResult, } from './engine.ts';
|
|
16
16
|
export { createEngine } from './factory.ts';
|
|
17
17
|
export type { CreateEngineOpts, CreatedEngine } from './factory.ts';
|
|
18
18
|
export { Store, openStore, StoreVersionError } from './store.ts';
|
|
19
19
|
export type { ArtifactRow, RunRow, TaskRow, WorkflowRow } from './store.ts';
|
|
20
|
-
export { buildDef, DefError, expandIncludes, hashDef, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, SUPPORTED_ENGINE_VERSION, validateDef } from './defs.ts';
|
|
20
|
+
export { buildDef, DefError, expandIncludes, finalizeDefs, hashDef, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, SUPPORTED_ENGINE_VERSION, validateDef } from './defs.ts';
|
|
21
|
+
export { credentialSlot, hashDefForHub, keychainServiceFor, normalizeOrigin, readStoredCredential } from './hub.ts';
|
|
22
|
+
export type { Credential, CredentialSlotSelector, Keychain, ReadStoredCredentialOpts } from './hub.ts';
|
|
21
23
|
export type { DefLoadFailure } from './defs.ts';
|
|
22
24
|
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from './model.ts';
|
|
23
25
|
export type { ArtifactMap, Blocker, Firing, TimeFacts, WorkflowStatus } from './model.ts';
|
package/dist/index.js
CHANGED
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
export { Engine } from "./engine.js";
|
|
15
15
|
export { createEngine } from "./factory.js";
|
|
16
16
|
export { Store, openStore, StoreVersionError } from "./store.js";
|
|
17
|
-
export { buildDef, DefError, expandIncludes, hashDef, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, SUPPORTED_ENGINE_VERSION, validateDef } from "./defs.js";
|
|
17
|
+
export { buildDef, DefError, expandIncludes, finalizeDefs, hashDef, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, SUPPORTED_ENGINE_VERSION, validateDef } from "./defs.js";
|
|
18
|
+
export { credentialSlot, hashDefForHub, keychainServiceFor, normalizeOrigin, readStoredCredential } from "./hub.js";
|
|
18
19
|
export { buildGraph, buildTrace, eligibleFirings, graphToDot, graphToMermaid, isStalled, modelCheck, workflowStatus, } from "./model.js";
|
|
19
20
|
export { parseConsume, parseProduce, } from "./paths.js";
|
|
20
21
|
export { assertValidSchema, summarizeIssues, validateValue } from "./schema.js";
|
package/dist/model.d.ts
CHANGED
|
@@ -191,6 +191,31 @@ export interface Blocker {
|
|
|
191
191
|
step: string;
|
|
192
192
|
blockedOn: string[];
|
|
193
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* A compact summary of a `calls:` child instance, attached to the parent's
|
|
196
|
+
* `calls:` debt by `Engine.status()`. A pure data shape (no logic) so it can
|
|
197
|
+
* live here next to `WorkflowStatus` — the `debts[]` entry type references it,
|
|
198
|
+
* and `model.ts` imports nothing from `engine.ts`, which avoids a source cycle.
|
|
199
|
+
* All the instance-crossing work that populates it (resolving the child def,
|
|
200
|
+
* reading the child's artifacts, recursing along the unpaid `calls:` path)
|
|
201
|
+
* stays in `engine.ts`; `workflowStatus` never sets it.
|
|
202
|
+
* - `workflow` — the child instance id (the handle a human uses to inspect /
|
|
203
|
+
* `retry` the child).
|
|
204
|
+
* - `def` — the child def name.
|
|
205
|
+
* - `done` — the child's own done-ness.
|
|
206
|
+
* - `stalled` — true when the child (or, recursively, any descendant on ITS
|
|
207
|
+
* unpaid `calls:` path) has a stalled debt; lets a grandchild stall surface
|
|
208
|
+
* as `child.stalled: true` on the root debt.
|
|
209
|
+
* - `debts` — a COUNT of the child's own debts (the `workflow` id is the
|
|
210
|
+
* inspection handle for the detail).
|
|
211
|
+
*/
|
|
212
|
+
export interface ChildStatusSummary {
|
|
213
|
+
workflow: string;
|
|
214
|
+
def: string;
|
|
215
|
+
done: boolean;
|
|
216
|
+
stalled: boolean;
|
|
217
|
+
debts: number;
|
|
218
|
+
}
|
|
194
219
|
export interface WorkflowStatus {
|
|
195
220
|
done: boolean;
|
|
196
221
|
debts: Array<{
|
|
@@ -212,6 +237,17 @@ export interface WorkflowStatus {
|
|
|
212
237
|
* Absent when zero or unknown.
|
|
213
238
|
*/
|
|
214
239
|
attempts?: number;
|
|
240
|
+
/**
|
|
241
|
+
* §23.6.8: when this debt is a `calls:` step's produced artifact and a
|
|
242
|
+
* child instance has been spawned, a summary of that child (id, def,
|
|
243
|
+
* done-ness, recursive stall flag, own-debt count). Engine-enriched from
|
|
244
|
+
* the cross-instance store like `failedRuns`/`attempts` — populated only
|
|
245
|
+
* by `Engine.status()`, never by the pure `workflowStatus`. Absent when
|
|
246
|
+
* the debt is not a `calls:` artifact, no child exists yet, or the child's
|
|
247
|
+
* def is unresolvable (unpinned row whose def was removed — the summary is
|
|
248
|
+
* enrichment and must not make `status` throw).
|
|
249
|
+
*/
|
|
250
|
+
child?: ChildStatusSummary;
|
|
215
251
|
}>;
|
|
216
252
|
eligible: Firing[];
|
|
217
253
|
blocked: Blocker[];
|
package/dist/store.d.ts
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* and (de)serialized at the boundary so callers always see real objects.
|
|
14
14
|
*/
|
|
15
15
|
import { DatabaseSync } from 'node:sqlite';
|
|
16
|
-
import type { ArtifactData, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
|
|
16
|
+
import type { ArtifactData, ArtifactHistory, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
|
|
17
17
|
export interface ArtifactRow extends ArtifactData {
|
|
18
18
|
id: string;
|
|
19
19
|
updatedAt: number;
|
|
@@ -46,6 +46,8 @@ export declare class StoreVersionError extends Error {
|
|
|
46
46
|
export declare class Store {
|
|
47
47
|
readonly db: DatabaseSync;
|
|
48
48
|
constructor(path: string);
|
|
49
|
+
/** Read the stored schema version without writing, refusing newer databases. */
|
|
50
|
+
private refuseIfNewer;
|
|
49
51
|
close(): void;
|
|
50
52
|
/**
|
|
51
53
|
* Pre-schema migration: rename the legacy `loop` column to `step` on an
|
|
@@ -109,7 +111,17 @@ export declare class Store {
|
|
|
109
111
|
getArtifactById(id: string): ArtifactRow | undefined;
|
|
110
112
|
listArtifacts(workflow: string): ArtifactRow[];
|
|
111
113
|
/** Insert or fully replace the artifact at (workflow, path). */
|
|
112
|
-
putArtifact(data: ArtifactData
|
|
114
|
+
putArtifact(data: ArtifactData, provenance?: {
|
|
115
|
+
action?: string;
|
|
116
|
+
actor?: string;
|
|
117
|
+
reason?: string;
|
|
118
|
+
kind?: string;
|
|
119
|
+
timestamp?: number;
|
|
120
|
+
key?: string;
|
|
121
|
+
}): ArtifactRow;
|
|
122
|
+
private insertArtifactEvent;
|
|
123
|
+
/** Returns history for exactly one artifact; list/status reads stay projection-only. */
|
|
124
|
+
getArtifactHistory(workflow: string, path: string): ArtifactHistory | undefined;
|
|
113
125
|
deleteArtifact(workflow: string, path: string): void;
|
|
114
126
|
getTask(workflow: string, step: string, key: string): TaskRow | undefined;
|
|
115
127
|
listTasks(workflow: string): TaskRow[];
|
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
|
}
|
|
@@ -450,9 +645,10 @@ export class Store {
|
|
|
450
645
|
return rows.map(mapArtifact);
|
|
451
646
|
}
|
|
452
647
|
/** Insert or fully replace the artifact at (workflow, path). */
|
|
453
|
-
putArtifact(data) {
|
|
648
|
+
putArtifact(data, provenance) {
|
|
649
|
+
const previous = this.getArtifact(data.workflow, data.path);
|
|
454
650
|
const id = artifactId(data.workflow, data.path);
|
|
455
|
-
const at = nowMs();
|
|
651
|
+
const at = provenance?.timestamp ?? nowMs();
|
|
456
652
|
this.db
|
|
457
653
|
.prepare(`INSERT INTO artifact
|
|
458
654
|
(id, workflow, path, producer, acceptance, version, value, fingerprint,
|
|
@@ -489,9 +685,58 @@ export class Store {
|
|
|
489
685
|
approvals: toJson(data.approvals),
|
|
490
686
|
updated_at: at,
|
|
491
687
|
});
|
|
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
|
+
}
|
|
492
712
|
return this.getArtifact(data.workflow, data.path);
|
|
493
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
|
+
};
|
|
736
|
+
}
|
|
494
737
|
deleteArtifact(workflow, path) {
|
|
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);
|
|
495
740
|
this.db.prepare('DELETE FROM artifact WHERE workflow = ? AND path = ?').run(workflow, path);
|
|
496
741
|
}
|
|
497
742
|
// -- task --------------------------------------------------------------------
|
|
@@ -581,15 +826,18 @@ export class Store {
|
|
|
581
826
|
// -- run ---------------------------------------------------------------------
|
|
582
827
|
insertRun(id, data, at = nowMs()) {
|
|
583
828
|
this.db
|
|
584
|
-
.prepare(`INSERT INTO run (id, workflow, step, key, outcome, summary, session_id, fingerprint, cause, created_at, updated_at)
|
|
585
|
-
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
586
|
-
.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);
|
|
587
832
|
return this.getRun(id);
|
|
588
833
|
}
|
|
589
834
|
updateRun(id, patch) {
|
|
590
835
|
const cur = this.getRun(id);
|
|
591
836
|
if (!cur)
|
|
592
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.
|
|
593
841
|
const merged = {
|
|
594
842
|
workflow: cur.workflow,
|
|
595
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;
|
|
@@ -265,6 +347,16 @@ export interface StepDef {
|
|
|
265
347
|
idleAfterMs?: number;
|
|
266
348
|
/** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
|
|
267
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;
|
|
268
360
|
body: string;
|
|
269
361
|
/** Mode 2 foundation: name of the child workflow this step delegates to. Machine-handled, never a worker firing. */
|
|
270
362
|
calls?: string;
|