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/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): ArtifactRow;
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 = '6';
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
- this.db.exec('PRAGMA journal_mode = WAL');
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
- this.premigrate();
246
- this.db.exec(SCHEMA);
247
- this.migrate();
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
- const curNum = parseInt(cur, 10);
251
- const ownNum = parseInt(SCHEMA_VERSION, 10);
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
- if (cur !== SCHEMA_VERSION)
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;