owenloop 0.5.9 → 0.5.10
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 +44 -0
- package/README.md +77 -37
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.js +7 -0
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +92 -14
- package/dist/packages/work/src/harness/claude.js +16 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- package/dist/packages/work/src/roles/agent-run.js +38 -10
- package/dist/packages/work/src/roles/exec.js +25 -8
- package/dist/packages/work/src/shift/loop.js +118 -4
- package/dist/packages/work/src/shift/runtime.d.ts +3 -0
- package/dist/packages/work/src/shift/runtime.js +10 -1
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/src/capabilities.d.ts +70 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +2 -2
- package/dist/src/cli.js +1196 -164
- package/dist/src/defs.d.ts +32 -1
- package/dist/src/defs.js +391 -79
- package/dist/src/engine.d.ts +62 -19
- package/dist/src/engine.js +180 -70
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +56 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +8 -6
- package/dist/src/index.js +4 -3
- package/dist/src/mcp/serve.js +254 -45
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +46 -10
- package/dist/src/model.js +220 -74
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +562 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +64 -4
- package/dist/src/store.js +211 -8
- package/dist/src/types.d.ts +61 -17
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +145 -8
- package/docs/bundles.md +19 -0
- package/docs/cli.md +270 -30
- package/docs/crypto.md +13 -7
- package/docs/design.md +107 -46
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/shift-logs.md +18 -0
- package/docs/wire-contracts.md +28 -7
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/ship.yaml +28 -2
- package/package.json +2 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/dist/src/store.js
CHANGED
|
@@ -13,7 +13,125 @@
|
|
|
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 { lstatSync } from 'node:fs';
|
|
16
17
|
import { detId, nowMs } from "./util.js";
|
|
18
|
+
import { compareStoreText, defDigest, isDefDigest, parseWorkflowCoordinate } from "./store/types.js";
|
|
19
|
+
import { withWorkflowSnapshotStoreGuard } from "./store/snapshot-guard.js";
|
|
20
|
+
function exactCallsFromSnapshot(record, workflow) {
|
|
21
|
+
const rawSteps = record.steps;
|
|
22
|
+
if (rawSteps === undefined)
|
|
23
|
+
return [];
|
|
24
|
+
if (!Array.isArray(rawSteps)) {
|
|
25
|
+
throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps: expected an array`);
|
|
26
|
+
}
|
|
27
|
+
const exactCalls = new Set();
|
|
28
|
+
for (const [index, rawStep] of rawSteps.entries()) {
|
|
29
|
+
if (typeof rawStep !== 'object' || rawStep === null || Array.isArray(rawStep)) {
|
|
30
|
+
throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps[${index}]: expected an object`);
|
|
31
|
+
}
|
|
32
|
+
const calls = rawStep.calls;
|
|
33
|
+
if (calls === undefined)
|
|
34
|
+
continue;
|
|
35
|
+
if (typeof calls !== 'string') {
|
|
36
|
+
throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps[${index}].calls: expected a string`);
|
|
37
|
+
}
|
|
38
|
+
if (!calls.includes('@'))
|
|
39
|
+
continue;
|
|
40
|
+
try {
|
|
41
|
+
parseWorkflowCoordinate(calls);
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
throw new Error(`workflow '${workflow}' has malformed exact def_snapshot calls target ${JSON.stringify(calls)}: ` +
|
|
45
|
+
error.message);
|
|
46
|
+
}
|
|
47
|
+
const rawLock = record.bundleLock;
|
|
48
|
+
if (typeof rawLock === 'object'
|
|
49
|
+
&& rawLock !== null
|
|
50
|
+
&& !Array.isArray(rawLock)
|
|
51
|
+
&& Object.prototype.hasOwnProperty.call(rawLock, calls))
|
|
52
|
+
continue;
|
|
53
|
+
exactCalls.add(calls);
|
|
54
|
+
}
|
|
55
|
+
return [...exactCalls].sort(compareStoreText);
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Read bundle pins from an EXISTING runtime database without migrating or
|
|
59
|
+
* otherwise writing it. GC deliberately cannot use {@link openStore}: opening
|
|
60
|
+
* the normal store enables write-oriented pragmas and schema migration, while
|
|
61
|
+
* a dry run must remain observational. Legacy databases without the workflow
|
|
62
|
+
* table or def_snapshot column simply predate snapshot pinning and contribute
|
|
63
|
+
* no pins.
|
|
64
|
+
*/
|
|
65
|
+
export function readRuntimeSnapshotBundlePins(path) {
|
|
66
|
+
if (lstatSync(path, { throwIfNoEntry: false }) === undefined)
|
|
67
|
+
return [];
|
|
68
|
+
const db = new DatabaseSync(path, { readOnly: true });
|
|
69
|
+
try {
|
|
70
|
+
const hasMeta = db
|
|
71
|
+
.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'`)
|
|
72
|
+
.get() !== undefined;
|
|
73
|
+
if (hasMeta) {
|
|
74
|
+
const row = db.prepare(`SELECT v FROM meta WHERE k = 'schema_version'`).get();
|
|
75
|
+
const current = row?.v;
|
|
76
|
+
if (current !== undefined && parseInt(current, 10) > parseInt(SCHEMA_VERSION, 10)) {
|
|
77
|
+
throw new StoreVersionError(`database schema_version ${current} is newer than this owenloop's schema_version ${SCHEMA_VERSION}; ` +
|
|
78
|
+
'upgrade your owenloop install to open this database');
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
const hasWorkflow = db
|
|
82
|
+
.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow'`)
|
|
83
|
+
.get() !== undefined;
|
|
84
|
+
if (!hasWorkflow)
|
|
85
|
+
return [];
|
|
86
|
+
const columns = db.prepare('PRAGMA table_info(workflow)').all();
|
|
87
|
+
if (!columns.some((column) => column.name === 'def_snapshot'))
|
|
88
|
+
return [];
|
|
89
|
+
const rows = db
|
|
90
|
+
.prepare('SELECT id, def_snapshot FROM workflow WHERE def_snapshot IS NOT NULL ORDER BY created_at, id')
|
|
91
|
+
.all();
|
|
92
|
+
return rows.map((row) => {
|
|
93
|
+
let snapshot;
|
|
94
|
+
try {
|
|
95
|
+
snapshot = JSON.parse(row.def_snapshot);
|
|
96
|
+
}
|
|
97
|
+
catch (error) {
|
|
98
|
+
throw new Error(`workflow '${row.id}' has malformed def_snapshot JSON: ${error.message}`);
|
|
99
|
+
}
|
|
100
|
+
if (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)) {
|
|
101
|
+
throw new Error(`workflow '${row.id}' has malformed def_snapshot: expected an object`);
|
|
102
|
+
}
|
|
103
|
+
const record = snapshot;
|
|
104
|
+
const rawDigest = record.bundleDigest;
|
|
105
|
+
let bundleDigest;
|
|
106
|
+
if (rawDigest !== undefined && rawDigest !== '') {
|
|
107
|
+
if (typeof rawDigest !== 'string' || !isDefDigest(rawDigest)) {
|
|
108
|
+
throw new Error(`workflow '${row.id}' has noncanonical def_snapshot.bundleDigest ${JSON.stringify(rawDigest)}`);
|
|
109
|
+
}
|
|
110
|
+
bundleDigest = rawDigest;
|
|
111
|
+
}
|
|
112
|
+
const rawLock = record.bundleLock;
|
|
113
|
+
if (rawLock !== undefined && (typeof rawLock !== 'object' || rawLock === null || Array.isArray(rawLock))) {
|
|
114
|
+
throw new Error(`workflow '${row.id}' has malformed def_snapshot.bundleLock: expected an object`);
|
|
115
|
+
}
|
|
116
|
+
const bundleLock = Object.entries((rawLock ?? {})).map(([target, digest]) => {
|
|
117
|
+
if (typeof digest !== 'string' || !isDefDigest(digest)) {
|
|
118
|
+
throw new Error(`workflow '${row.id}' has noncanonical def_snapshot.bundleLock[${JSON.stringify(target)}] ` +
|
|
119
|
+
`${JSON.stringify(digest)}`);
|
|
120
|
+
}
|
|
121
|
+
return digest;
|
|
122
|
+
});
|
|
123
|
+
const exactCalls = exactCallsFromSnapshot(record, row.id);
|
|
124
|
+
return {
|
|
125
|
+
...(bundleDigest === undefined ? {} : { bundleDigest }),
|
|
126
|
+
bundleLock: [...new Set(bundleLock)].sort(compareStoreText),
|
|
127
|
+
...(exactCalls.length === 0 ? {} : { exactCalls }),
|
|
128
|
+
};
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
finally {
|
|
132
|
+
db.close();
|
|
133
|
+
}
|
|
134
|
+
}
|
|
17
135
|
// ---- deterministic ids -------------------------------------------------------
|
|
18
136
|
export function artifactId(workflow, path) {
|
|
19
137
|
return detId('art', workflow, path);
|
|
@@ -385,6 +503,7 @@ function mapWorkflow(r) {
|
|
|
385
503
|
// ---- the store ---------------------------------------------------------------
|
|
386
504
|
export class Store {
|
|
387
505
|
db;
|
|
506
|
+
activeSnapshotDigests = new Set();
|
|
388
507
|
constructor(path) {
|
|
389
508
|
this.db = new DatabaseSync(path);
|
|
390
509
|
// Connection-scoped only — no file mutation, safe before the version check.
|
|
@@ -581,6 +700,35 @@ export class Store {
|
|
|
581
700
|
throw err;
|
|
582
701
|
}
|
|
583
702
|
}
|
|
703
|
+
/**
|
|
704
|
+
* Persist one or more CAS-backed definition snapshots under the same
|
|
705
|
+
* workflow-store lock used by install and GC. Reachability is revalidated
|
|
706
|
+
* before `BEGIN IMMEDIATE`; the guarded digest set then authorizes only the
|
|
707
|
+
* low-level snapshot writes performed by this transaction.
|
|
708
|
+
*/
|
|
709
|
+
txWithWorkflowSnapshots(snapshots, fn) {
|
|
710
|
+
const defs = Array.isArray(snapshots) ? snapshots : [snapshots];
|
|
711
|
+
return withWorkflowSnapshotStoreGuard(defs, (guardedDigests) => {
|
|
712
|
+
for (const digest of guardedDigests)
|
|
713
|
+
this.activeSnapshotDigests.add(digest);
|
|
714
|
+
try {
|
|
715
|
+
return this.tx(fn);
|
|
716
|
+
}
|
|
717
|
+
finally {
|
|
718
|
+
for (const digest of guardedDigests)
|
|
719
|
+
this.activeSnapshotDigests.delete(digest);
|
|
720
|
+
}
|
|
721
|
+
});
|
|
722
|
+
}
|
|
723
|
+
assertWorkflowSnapshotGuard(snapshot) {
|
|
724
|
+
if (snapshot?.bundleDigest === undefined || (snapshot.bundleStoreRoots?.length ?? 0) === 0)
|
|
725
|
+
return;
|
|
726
|
+
const digest = defDigest(snapshot.bundleDigest);
|
|
727
|
+
if (!this.activeSnapshotDigests.has(digest)) {
|
|
728
|
+
throw new Error(`refusing uncoordinated workflow snapshot write for bundle ${digest}: ` +
|
|
729
|
+
'use txWithWorkflowSnapshots so bundle GC cannot race the commit');
|
|
730
|
+
}
|
|
731
|
+
}
|
|
584
732
|
// -- meta --------------------------------------------------------------------
|
|
585
733
|
getMeta(k) {
|
|
586
734
|
const row = this.db.prepare('SELECT v FROM meta WHERE k = ?').get(k);
|
|
@@ -593,6 +741,7 @@ export class Store {
|
|
|
593
741
|
}
|
|
594
742
|
// -- workflow ----------------------------------------------------------------
|
|
595
743
|
insertWorkflow(id, data, producedBy) {
|
|
744
|
+
this.assertWorkflowSnapshotGuard(data.defSnapshot);
|
|
596
745
|
const at = nowMs();
|
|
597
746
|
this.db
|
|
598
747
|
.prepare(`INSERT INTO workflow
|
|
@@ -607,6 +756,7 @@ export class Store {
|
|
|
607
756
|
* decide what "drift" means, it just persists what the engine computed.
|
|
608
757
|
*/
|
|
609
758
|
repinWorkflowDef(id, snapshot, hash) {
|
|
759
|
+
this.assertWorkflowSnapshotGuard(snapshot);
|
|
610
760
|
this.db
|
|
611
761
|
.prepare('UPDATE workflow SET def_snapshot = ?, def_hash = ? WHERE id = ?')
|
|
612
762
|
.run(JSON.stringify(snapshot), hash, id);
|
|
@@ -924,8 +1074,10 @@ export class Store {
|
|
|
924
1074
|
if (!cur)
|
|
925
1075
|
throw new Error(`run not found: ${id}`);
|
|
926
1076
|
// order_json is DELIBERATELY excluded from `merged` and the UPDATE below:
|
|
927
|
-
//
|
|
928
|
-
//
|
|
1077
|
+
// no close/outcome/summary write can ever clobber the order packet, and
|
|
1078
|
+
// omitting the column makes that structural rather than a convention.
|
|
1079
|
+
// `restampOrderTarget` below is the ONE writer of order_json after claim,
|
|
1080
|
+
// and it rewrites a single `owes[].version` and nothing else.
|
|
929
1081
|
const merged = {
|
|
930
1082
|
workflow: cur.workflow,
|
|
931
1083
|
step: cur.step,
|
|
@@ -941,28 +1093,79 @@ export class Store {
|
|
|
941
1093
|
.run(merged.key ?? '', merged.outcome ?? null, merged.summary ?? null, merged.sessionId ?? null, toJson(merged.fingerprint), merged.cause ?? null, nowMs(), id);
|
|
942
1094
|
return this.getRun(id);
|
|
943
1095
|
}
|
|
1096
|
+
/**
|
|
1097
|
+
* Re-stamp ONE owed version target on a run's persisted order packet.
|
|
1098
|
+
*
|
|
1099
|
+
* The order is frozen at claim with exactly one exception, and this is it.
|
|
1100
|
+
* When a reject re-arms a still-open claim, the artifact has already been
|
|
1101
|
+
* bumped by the commit that preceded the reject, so the target the claim
|
|
1102
|
+
* froze at issue names a version the next commit will overshoot — and the
|
|
1103
|
+
* producer would sign that stale number into its submission proof while the
|
|
1104
|
+
* hub keys the stored proof row by the version actually committed. Everything
|
|
1105
|
+
* else about the packet stays frozen, and `updateRun` still cannot touch it
|
|
1106
|
+
* at all.
|
|
1107
|
+
*
|
|
1108
|
+
* No-ops when the run has no persisted order (pre-schema-v7 rows), when the
|
|
1109
|
+
* order does not owe `path`, or when the target already is `version` — so
|
|
1110
|
+
* callers can call it unconditionally, and re-stamping is idempotent.
|
|
1111
|
+
*/
|
|
1112
|
+
restampOrderTarget(id, path, version) {
|
|
1113
|
+
const cur = this.getRun(id);
|
|
1114
|
+
if (!cur?.order)
|
|
1115
|
+
return;
|
|
1116
|
+
const owed = cur.order.owes.find((o) => o.path === path);
|
|
1117
|
+
if (owed === undefined || owed.version === version)
|
|
1118
|
+
return;
|
|
1119
|
+
// Rebuilt immutably (map, not in-place mutation) so no caller is left
|
|
1120
|
+
// holding a half-mutated Order read before this write.
|
|
1121
|
+
const next = {
|
|
1122
|
+
...cur.order,
|
|
1123
|
+
owes: cur.order.owes.map((o) => (o.path === path ? { ...o, version } : o)),
|
|
1124
|
+
};
|
|
1125
|
+
this.db
|
|
1126
|
+
.prepare('UPDATE run SET order_json = ?, updated_at = ? WHERE id = ?')
|
|
1127
|
+
.run(toJson(next), nowMs(), id);
|
|
1128
|
+
}
|
|
944
1129
|
getRun(id) {
|
|
945
1130
|
const r = this.db.prepare('SELECT * FROM run WHERE id = ?').get(id);
|
|
946
1131
|
return r ? mapRun(r) : undefined;
|
|
947
1132
|
}
|
|
948
|
-
/**
|
|
1133
|
+
/**
|
|
1134
|
+
* How many runs of this step since `sinceMs` (for the daily budget window).
|
|
1135
|
+
*
|
|
1136
|
+
* `released` RUNS ARE EXCLUDED — a lease returned unused is not a firing. See
|
|
1137
|
+
* `RunData.outcome` for why this is not the same as `no_work`, which stays
|
|
1138
|
+
* counted because the step did run.
|
|
1139
|
+
*/
|
|
949
1140
|
countRuns(workflow, step, sinceMs) {
|
|
950
1141
|
const row = this.db
|
|
951
|
-
.prepare('SELECT COUNT(*) AS n FROM run WHERE workflow = ? AND step = ? AND created_at >= ?'
|
|
1142
|
+
.prepare('SELECT COUNT(*) AS n FROM run WHERE workflow = ? AND step = ? AND created_at >= ?'
|
|
1143
|
+
+ " AND (outcome IS NULL OR outcome != 'released')")
|
|
952
1144
|
.get(workflow, step, sinceMs);
|
|
953
1145
|
return row.n;
|
|
954
1146
|
}
|
|
955
|
-
/**
|
|
1147
|
+
/**
|
|
1148
|
+
* The most recent run of this step, if any (for cadence gating).
|
|
1149
|
+
*
|
|
1150
|
+
* `released` runs are excluded for the same reason `countRuns` excludes them:
|
|
1151
|
+
* a lease handed straight back did not fire the step, so it must not restart
|
|
1152
|
+
* the cadence clock. Without this a server that claims and releases on every
|
|
1153
|
+
* sweep holds a throttled step off indefinitely — each handback pushes the
|
|
1154
|
+
* next eligible time further out than the sweep interval that produced it.
|
|
1155
|
+
*/
|
|
956
1156
|
latestRun(workflow, step) {
|
|
957
1157
|
const r = this.db
|
|
958
|
-
.prepare(
|
|
1158
|
+
.prepare("SELECT * FROM run WHERE workflow = ? AND step = ? AND (outcome IS NULL OR outcome != 'released')"
|
|
1159
|
+
+ ' ORDER BY created_at DESC LIMIT 1')
|
|
959
1160
|
.get(workflow, step);
|
|
960
1161
|
return r ? mapRun(r) : undefined;
|
|
961
1162
|
}
|
|
962
1163
|
/**
|
|
963
1164
|
* Count of consecutive trailing `failed` runs for this step+key — the
|
|
964
|
-
* crash-step signal. Any closed run that is NOT `failed`
|
|
965
|
-
* breaks the streak; still-open runs (outcome
|
|
1165
|
+
* crash-step signal. Any closed run that is NOT `failed`
|
|
1166
|
+
* (ok/no_work/released/skipped) breaks the streak; still-open runs (outcome
|
|
1167
|
+
* NULL) are ignored. `released` breaks it exactly as `no_work` did before the
|
|
1168
|
+
* two were split, so the crash-step signal is unchanged by that split.
|
|
966
1169
|
*/
|
|
967
1170
|
recentFailedRuns(workflow, step, key = '') {
|
|
968
1171
|
const rows = this.db
|
package/dist/src/types.d.ts
CHANGED
|
@@ -170,6 +170,12 @@ export interface Order {
|
|
|
170
170
|
* (`wise` → `wise:deep`), or the authored names verbatim when the run
|
|
171
171
|
* carries no modifier. Absent when the step authored none.
|
|
172
172
|
*
|
|
173
|
+
* A caller may also supply a capability MAPPING, which substitutes its own
|
|
174
|
+
* capability name for the authored one before the modifier is attached. Such
|
|
175
|
+
* an order carries no in-band marker — unlike a reroute, nothing here says a
|
|
176
|
+
* mapping fired. The authored name stays recoverable through `defDigest`,
|
|
177
|
+
* which pins the def that wrote it.
|
|
178
|
+
*
|
|
173
179
|
* This is the value a claiming crew's bindings are matched against and the
|
|
174
180
|
* value the shift's settings map is keyed by. It is a snapshot of the offer:
|
|
175
181
|
* an already-claimed order is never recomposed, so re-reading it later
|
|
@@ -263,11 +269,12 @@ export interface Order {
|
|
|
263
269
|
* stalls the step. This closes that: the requirement is stated up front,
|
|
264
270
|
* from the same declaration the refusal will be measured against.
|
|
265
271
|
*
|
|
266
|
-
* It is a COPY, not a reference.
|
|
267
|
-
*
|
|
268
|
-
*
|
|
269
|
-
*
|
|
270
|
-
*
|
|
272
|
+
* It is a COPY, not a reference. Nothing rewrites the schema on a persisted
|
|
273
|
+
* order — `Store.restampOrderTarget`, the one post-claim writer, touches
|
|
274
|
+
* only `owes[].version` — so this is the schema as it stood at claim time;
|
|
275
|
+
* a def edited mid-run leaves the projected schema and the enforced one
|
|
276
|
+
* able to disagree, exactly as `defDigest` already records for the rest of
|
|
277
|
+
* the order.
|
|
271
278
|
*/
|
|
272
279
|
schema?: JsonSchema;
|
|
273
280
|
/**
|
|
@@ -299,7 +306,31 @@ export interface RunData {
|
|
|
299
306
|
workflow: string;
|
|
300
307
|
step: string;
|
|
301
308
|
key?: string;
|
|
302
|
-
|
|
309
|
+
/**
|
|
310
|
+
* How the run ended, or `undefined` while it is still open.
|
|
311
|
+
*
|
|
312
|
+
* `no_work` and `released` are NOT the same thing, and the difference is
|
|
313
|
+
* load-bearing for the daily budget and the cadence gate:
|
|
314
|
+
*
|
|
315
|
+
* - `no_work` — the step RAN and had nothing to produce. A `merge-gate` that
|
|
316
|
+
* polled CI and found it still pending, an `ask` that handed the question
|
|
317
|
+
* to a human, a holder that rejected its input. Work happened; these runs
|
|
318
|
+
* spend budget and restart the cadence clock, which is exactly how a
|
|
319
|
+
* `cadenceSecs` poll stays throttled.
|
|
320
|
+
* - `released` — the LEASE WAS RETURNED UNUSED. Nothing ran. A server already
|
|
321
|
+
* at its agent cap handing the claim straight back or a pickup window that
|
|
322
|
+
* lapsed with no first contact increments the task's lease-churn
|
|
323
|
+
* `attempts`, while a private born-reject re-arm does not. All remain
|
|
324
|
+
* outside the daily budget and cadence: they are not firings, they are
|
|
325
|
+
* claims that were withdrawn.
|
|
326
|
+
*
|
|
327
|
+
* Conflating them stalled a live run. Six capacity handbacks against a step
|
|
328
|
+
* declaring `maxRunsPerDay: 6` spent the whole allowance before it executed
|
|
329
|
+
* once; the engine then deferred it `daily-budget` until local midnight while
|
|
330
|
+
* its artifact still read `attemptsUsed: 0`. Lease-churn attempts are status
|
|
331
|
+
* telemetry, not the rework budget (`judgmentRejects`) and not a run.
|
|
332
|
+
*/
|
|
333
|
+
outcome?: 'ok' | 'no_work' | 'released' | 'failed' | 'skipped';
|
|
303
334
|
summary?: string;
|
|
304
335
|
sessionId?: string;
|
|
305
336
|
/** the version of every consumed input at claim time (§12.2 commit CAS) */
|
|
@@ -308,8 +339,10 @@ export interface RunData {
|
|
|
308
339
|
cause?: FiringTrigger;
|
|
309
340
|
/** The flattened order packet issued at claim time (§8 / Gap 1) — the exact
|
|
310
341
|
* Order buildOrder emitted, written in the SAME transaction that created
|
|
311
|
-
* this run.
|
|
312
|
-
*
|
|
342
|
+
* this run. `updateRun` never touches it, so no close/outcome write can
|
|
343
|
+
* clobber it; `Store.restampOrderTarget` is the single narrow exception,
|
|
344
|
+
* rewriting one `owes[].version` when a reject re-arms a still-open claim.
|
|
345
|
+
* The replay/eval/paper-trail record (buildOrder is deterministic modulo run
|
|
313
346
|
* id). Absent on runs created before schema v7. */
|
|
314
347
|
order?: Order;
|
|
315
348
|
}
|
|
@@ -803,11 +836,20 @@ export interface CheckReport {
|
|
|
803
836
|
bounded: boolean;
|
|
804
837
|
/** Which bounds were hit, for honest reporting. */
|
|
805
838
|
boundsHit: ('maxDepth' | 'maxStates')[];
|
|
839
|
+
/**
|
|
840
|
+
* True when the search expanded at least one reachable `emit-seal` outcome.
|
|
841
|
+
* This describes the search shape, not a BFS stop condition, and does not
|
|
842
|
+
* contribute to `bounded`.
|
|
843
|
+
*/
|
|
844
|
+
collectionCapApplied: boolean;
|
|
845
|
+
/** Effective per-seal member-count cap, including the default when unspecified. */
|
|
846
|
+
maxCollectionSize: number;
|
|
806
847
|
/**
|
|
807
848
|
* Reachable non-done states with zero eligible firings that have NO path to
|
|
808
|
-
* completion even
|
|
809
|
-
* all freezes lifted (a human `retry` =
|
|
810
|
-
*
|
|
849
|
+
* completion even after unlimited attempts and elapsed idle time — i.e.
|
|
850
|
+
* recomputing eligibility with all freezes lifted (a human `retry` =
|
|
851
|
+
* unlimited attempts) and eventual idle time STILL yields zero firings. A
|
|
852
|
+
* genuine structural dead-end (TRUE deadlock). A definite
|
|
811
853
|
* defect only when the search was exhaustive (`!bounded`) — the
|
|
812
854
|
* maxCollectionSize cap can otherwise manufacture a spurious no-moves
|
|
813
855
|
* state. Always present ([] when none).
|
|
@@ -815,12 +857,14 @@ export interface CheckReport {
|
|
|
815
857
|
deadlocks: CheckFinding[];
|
|
816
858
|
/**
|
|
817
859
|
* Reachable non-done states with zero eligible firings whose ONLY blocker
|
|
818
|
-
* is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held)
|
|
819
|
-
*
|
|
820
|
-
*
|
|
821
|
-
*
|
|
822
|
-
*
|
|
823
|
-
*
|
|
860
|
+
* is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held) or an
|
|
861
|
+
* idle trigger whose threshold has not yet elapsed. Recomputing eligibility
|
|
862
|
+
* with all freezes lifted (a human `retry` = unlimited attempts) and
|
|
863
|
+
* eventual idle time yields >= 1 firing, so a producer would re-arm or an
|
|
864
|
+
* idle step would become eligible. These are expected brakes/waits — never
|
|
865
|
+
* a defect; they do not affect the exit code. This classification does not
|
|
866
|
+
* itself make an idle successor reachable in the timeless BFS, so
|
|
867
|
+
* `completable` can remain false. Always present ([] when none).
|
|
824
868
|
*/
|
|
825
869
|
stallStates: CheckFinding[];
|
|
826
870
|
/**
|
package/dist/src/util.js
CHANGED
|
@@ -138,7 +138,10 @@ export function parseDurationMs(spec) {
|
|
|
138
138
|
const m = DUR_RE.exec(String(spec).trim());
|
|
139
139
|
if (!m)
|
|
140
140
|
throw new Error(`bad duration: ${spec} (use 90m, 2h, or seconds)`);
|
|
141
|
-
|
|
141
|
+
const milliseconds = Number(m[1]) * UNIT_MS[m[2]];
|
|
142
|
+
if (!Number.isFinite(milliseconds))
|
|
143
|
+
throw new Error(`bad duration: ${spec} (duration is too large)`);
|
|
144
|
+
return milliseconds;
|
|
142
145
|
}
|
|
143
146
|
/** "30m" → 1800 seconds. */
|
|
144
147
|
export function parseDurationSecs(spec) {
|
package/docs/authoring.md
CHANGED
|
@@ -92,6 +92,92 @@ steps:
|
|
|
92
92
|
anything: goes # untouched onto the order (Order.x); see design.md §27.3
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
+
## x.discovery — advisory workflow discovery metadata
|
|
96
|
+
|
|
97
|
+
x.discovery is an Owenloop-owned convention inside the otherwise opaque
|
|
98
|
+
top-level x: map. It lets a person or catalog tool understand what a workflow
|
|
99
|
+
does, when to choose it, when a close-looking workflow is the wrong choice, and
|
|
100
|
+
how to seed/read its public interface:
|
|
101
|
+
|
|
102
|
+
~~~yaml
|
|
103
|
+
x:
|
|
104
|
+
discovery:
|
|
105
|
+
description: >-
|
|
106
|
+
One non-empty paragraph explaining the workflow in colleague-facing language.
|
|
107
|
+
whenToUse:
|
|
108
|
+
- a non-empty trigger phrase
|
|
109
|
+
notFor:
|
|
110
|
+
- a non-empty anti-trigger phrase
|
|
111
|
+
interface:
|
|
112
|
+
inputs:
|
|
113
|
+
- name: proposal
|
|
114
|
+
summary: A non-empty description of the seed value.
|
|
115
|
+
schemaRef: "#/inputs/0/schema"
|
|
116
|
+
outputs:
|
|
117
|
+
- name: merge
|
|
118
|
+
summary: A non-empty description of the public result.
|
|
119
|
+
schemaRef: "#/steps/6/produces/0/schema"
|
|
120
|
+
~~~
|
|
121
|
+
|
|
122
|
+
The bag itself is optional today, so existing definitions remain compatible.
|
|
123
|
+
Its absence is a lint warning, not a loading or execution failure. Once the bag
|
|
124
|
+
is present, all four top-level fields are required: catalog browsing
|
|
125
|
+
(description), positive routing (whenToUse), false-positive avoidance (notFor),
|
|
126
|
+
and usable seeding/result information (interface) answer separate questions. In
|
|
127
|
+
particular, an anti-trigger is not redundant with a trigger: it rules out the
|
|
128
|
+
nearby cases that would otherwise appear to match.
|
|
129
|
+
|
|
130
|
+
description must be a non-empty string. whenToUse and notFor must each be
|
|
131
|
+
non-empty arrays of non-empty strings. interface.inputs and interface.outputs
|
|
132
|
+
are required arrays, though either can be empty when the workflow genuinely has
|
|
133
|
+
no declared inputs or no public outputs. Each entry must have a non-empty name,
|
|
134
|
+
summary, and schemaRef. The entries cover every declared input and every public
|
|
135
|
+
outputs: name exactly once; no unknown or duplicate names are allowed. Their
|
|
136
|
+
named artifacts must carry schemas. schemaRef is a local JSON Pointer beginning
|
|
137
|
+
#/ to that existing machine schema, not a second copy of the schema.
|
|
138
|
+
|
|
139
|
+
owenloop lint reports missing or malformed discovery data as field-specific
|
|
140
|
+
warnings. These warnings do not fail lint, loading, packing, publishing, pushing,
|
|
141
|
+
or execution. Other x vocabularies remain opaque and unrestricted; only this
|
|
142
|
+
authoring-lint convention is recognized.
|
|
143
|
+
|
|
144
|
+
## x.implements — advisory external interface claims
|
|
145
|
+
|
|
146
|
+
When present, x.implements must be a non-empty array of external interface
|
|
147
|
+
coordinates a definition claims to satisfy:
|
|
148
|
+
|
|
149
|
+
~~~yaml
|
|
150
|
+
x:
|
|
151
|
+
implements:
|
|
152
|
+
- name: research-report
|
|
153
|
+
version: "1"
|
|
154
|
+
- name: auditable-report
|
|
155
|
+
version: "2026-08"
|
|
156
|
+
~~~
|
|
157
|
+
|
|
158
|
+
Every entry contains exactly non-empty string name and version fields. More
|
|
159
|
+
than one claim is allowed, but an exact name/version coordinate may appear only
|
|
160
|
+
once. Version is intentionally an opaque string here: Owenloop does not impose
|
|
161
|
+
SemVer or catalog policy. Malformed claims are warning-only authoring lint, so
|
|
162
|
+
they neither stop lint nor turn loading or execution into a failure. Keeping
|
|
163
|
+
the field under x also means binaries at engine version 1 ignore it and continue
|
|
164
|
+
to load definitions written before or after the convention.
|
|
165
|
+
|
|
166
|
+
x.discovery.interface and x.implements answer different questions.
|
|
167
|
+
x.discovery.interface describes this definition's own inputs and public outputs
|
|
168
|
+
and owns the local schemaRef vocabulary. x.implements only names an external
|
|
169
|
+
catalog contract; it deliberately copies no schemas, artifact mappings, or
|
|
170
|
+
summaries and introduces no second pointer convention. Catalog lookup and
|
|
171
|
+
publish-time rejection are hub responsibilities, not owenloop lint.
|
|
172
|
+
|
|
173
|
+
Catalog or publish tooling that needs to compare a claimed interface with a
|
|
174
|
+
workflow can use the exported `checkInterfaceCompatibility` helper. It checks
|
|
175
|
+
inputs contravariantly and outputs covariantly using the supported structural
|
|
176
|
+
JSON Schema subset. When a schema combines root constraints with a top-level
|
|
177
|
+
`anyOf` or `oneOf`, those root constraints remain in force while branch coverage
|
|
178
|
+
is checked; union branches are not treated as standalone schemas. The checker
|
|
179
|
+
continues to fail closed for unsupported or unprovable schema constructs.
|
|
180
|
+
|
|
95
181
|
## `model:` — quality tiers, not vendor ids
|
|
96
182
|
|
|
97
183
|
The engine never calls a model; `model:` is an opaque string that rides the
|
|
@@ -311,6 +397,52 @@ check.
|
|
|
311
397
|
`capabilities:` says *which* caller may claim it in the first place — a tick filter
|
|
312
398
|
locally, a bound crew on a hub.
|
|
313
399
|
|
|
400
|
+
### The trust boundary: publishing shares, installing scopes
|
|
401
|
+
|
|
402
|
+
`push` and `install` both put a def on your hub, and they treat its capabilities
|
|
403
|
+
differently on purpose.
|
|
404
|
+
|
|
405
|
+
`owenloop push` publishes defs **your org authored**. Their capabilities join the
|
|
406
|
+
org's **shared** vocabulary as written: two of your own defs that both author
|
|
407
|
+
`review` deliberately mean the same `review`, served by the same crews. That is
|
|
408
|
+
the whole value of a shared vocabulary.
|
|
409
|
+
|
|
410
|
+
`owenloop install <owner>/<repo>` publishes a def **someone else authored**. An
|
|
411
|
+
outside author writing `review` is not making your org's claim, so every
|
|
412
|
+
capability an installed def authors becomes `<def-name>.<capability>` —
|
|
413
|
+
`analyzer.review`, not `review` — unless you say otherwise, once, at install
|
|
414
|
+
time. Scoping is the default because the failure it prevents is silent: an
|
|
415
|
+
outside def entering the shared vocabulary starts drawing orders from the crews
|
|
416
|
+
already bound to that name.
|
|
417
|
+
|
|
418
|
+
Link deliberately, when you actually mean it. If your `reviewers` crew genuinely
|
|
419
|
+
should serve the installed def's `review`, answer the install prompt with
|
|
420
|
+
`code-review` (or whatever your org calls it), or pass
|
|
421
|
+
`--map review=code-review`. Then the org name it takes is the one your crews are
|
|
422
|
+
already bound to, and it draws from them by design rather than by collision.
|
|
423
|
+
|
|
424
|
+
**Never edit a def's content to get the mapping you want.** The mapping is
|
|
425
|
+
org-side data, recorded against `(def, authored-name)` on your hub; the def stays
|
|
426
|
+
byte-for-byte as its author wrote it, so upstream updates keep applying. Editing
|
|
427
|
+
`capabilities:` in a def you did not author forks it.
|
|
428
|
+
|
|
429
|
+
Four names, in the order the engine derives them:
|
|
430
|
+
|
|
431
|
+
| Vocabulary | Where it comes from |
|
|
432
|
+
| --- | --- |
|
|
433
|
+
| **authored** | what the def's YAML says, e.g. `review` |
|
|
434
|
+
| **mapped** | the org name a capability mapping gives it, e.g. `analyzer.review` |
|
|
435
|
+
| **composed** | the mapped name plus the run's modifier, e.g. `analyzer.review:deep` |
|
|
436
|
+
| **offered** | the composed name after any capability reroute rewrites it |
|
|
437
|
+
|
|
438
|
+
The two rewrite points key on different halves and fire at different times.
|
|
439
|
+
**Mappings key on the AUTHORED name and apply BEFORE composition** — they answer
|
|
440
|
+
"what does this def's `review` mean here". **Reroutes key on the COMPOSED string
|
|
441
|
+
and apply AFTER composition** — they answer "where should `analyzer.review:deep`
|
|
442
|
+
go right now". A reroute is therefore the operational lever (move traffic
|
|
443
|
+
today); a mapping is the identity decision (what this def's capability *is* in
|
|
444
|
+
your org).
|
|
445
|
+
|
|
314
446
|
## `produces:` vs `generates:`
|
|
315
447
|
|
|
316
448
|
A stem under `produces:` is expected to be consumed downstream — owenloop's lint warns
|
|
@@ -482,11 +614,13 @@ produces:
|
|
|
482
614
|
- **`atLeastOne`** — no refusal, no auto-skip; once any one member is green,
|
|
483
615
|
the rest no longer count as outstanding for done-ness.
|
|
484
616
|
|
|
485
|
-
A
|
|
486
|
-
|
|
617
|
+
A manual/branch skip re-arms only after its upstream inputs move. An exclusive
|
|
618
|
+
group skip has an additional inverse: if the green winner is rejected or
|
|
619
|
+
retracted, a sibling whose latest skip reason is `exclusive` immediately
|
|
620
|
+
returns to `owed`; a structurally skipped sibling does not. See
|
|
487
621
|
[`routing-groups.yaml`](../examples/workflows/routing-groups.yaml) for a
|
|
488
|
-
runnable example, and [`docs/design.md` §26](design.md) for the full
|
|
489
|
-
|
|
622
|
+
runnable example, and [`docs/design.md` §26](design.md) for the full design
|
|
623
|
+
(refusal timing, the judges interaction, and the model-checker parity
|
|
490
624
|
guarantee).
|
|
491
625
|
|
|
492
626
|
Eligibility (the automatic sweep) is pre-filtered the same way commit-time
|
|
@@ -560,7 +694,7 @@ steps:
|
|
|
560
694
|
calls: delivery # bare local name; use <package>/<workflow> for a CAS target
|
|
561
695
|
inputs: # child input → parent artifact (gate: sandbox green)
|
|
562
696
|
proposal: proposal
|
|
563
|
-
produces: [delivered] #
|
|
697
|
+
produces: [delivered] # mirrors a green/value-defined output only after delivery is done
|
|
564
698
|
- name: teardown
|
|
565
699
|
consumes: [delivered]
|
|
566
700
|
produces: [torn_down]
|
|
@@ -568,9 +702,12 @@ steps:
|
|
|
568
702
|
body: Tear down and green `torn_down`.
|
|
569
703
|
```
|
|
570
704
|
|
|
571
|
-
The engine spawns the child when the gate inputs are green
|
|
572
|
-
`calls:` output
|
|
573
|
-
|
|
705
|
+
The engine spawns the child when the gate inputs are green and keeps the parent's
|
|
706
|
+
`calls:` output owed until the child's declared output is green/value-defined **and**
|
|
707
|
+
`workflowDone(childDef, childArts)` says the whole child is done. Only then does it
|
|
708
|
+
mirror that value into the parent (no Worker run). A child with cleanup or a manually
|
|
709
|
+
supplied input still outstanding keeps the parent output owed. If a gate input changes,
|
|
710
|
+
the engine re-provides it to the existing child — it never spawns a duplicate.
|
|
574
711
|
|
|
575
712
|
| | `include:` (Mode 1) | `calls:` (Mode 2) |
|
|
576
713
|
|---|---|---|
|
package/docs/bundles.md
CHANGED
|
@@ -161,6 +161,25 @@ This check is separate from the read-only file modes applied during install. Ins
|
|
|
161
161
|
|
|
162
162
|
An executable file installed by an older Owenloop release may already have lost its execute bit because older hardening mapped every regular file to `0444`. Reinstalling the exact original `.wnlp` is a supported atomic repair for that same-digest object. Owenloop first applies strict archive parsing, manifest and runtime admission, configured signature and policy verification, per-file integrity verification, and canonical digest verification to the supplied archive. Owenloop then reconstructs and completely verifies a clean staged object before replacing the broken destination through the normal journaled directory swap. The broken object's bytes are never reused. The prior object remains as the swap backup until the unchanged same-digest index state is durably committed; a failed repair restores the recoverable prior object and index state. A successful repair preserves the existing coordinate-to-digest mapping, and a later reinstall follows normal idempotent deduplication.
|
|
163
163
|
|
|
164
|
+
## Authenticated recovery for worker store misses
|
|
165
|
+
|
|
166
|
+
When a modern command or agent worker cannot resolve an exact order digest from
|
|
167
|
+
either local workflow store, it performs one authenticated recovery attempt.
|
|
168
|
+
Using that worker's scoped bearer, it reads raw canonical bytes from
|
|
169
|
+
`GET /api/bundles/<digest>`, required publication evidence from
|
|
170
|
+
`GET /api/publications/<digest>`, and optional origin evidence from
|
|
171
|
+
`GET /api/origins/<digest>`, then installs only into the global store. The
|
|
172
|
+
original store lookup is retried once after a successful install; a store hit
|
|
173
|
+
does no hub I/O.
|
|
174
|
+
|
|
175
|
+
Recovery is fail-closed. The installer compares the ingested canonical digest
|
|
176
|
+
with the order digest before any object or index mutation, and the required
|
|
177
|
+
pre-commit verifier validates the supplied publication/origin evidence under
|
|
178
|
+
the normal policy before the journaled install can commit. Missing or malformed
|
|
179
|
+
publication evidence, redirects, non-404 origin errors, body caps, timeouts,
|
|
180
|
+
content mismatches, invalid signatures, or policy refusals leave the store
|
|
181
|
+
unchanged and the worker reports the ordinary instruction-resolution failure.
|
|
182
|
+
|
|
164
183
|
## Bundle assets during execution
|
|
165
184
|
|
|
166
185
|
When a command or agent step resolves its definition from an installed bundle,
|