owenloop 0.5.10 → 0.5.12
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 +14 -0
- package/dist/src/cli.js +5 -3
- package/dist/src/defs.d.ts +9 -0
- package/dist/src/defs.js +75 -15
- package/dist/src/engine.d.ts +46 -3
- package/dist/src/engine.js +394 -16
- package/dist/src/factory.js +5 -3
- package/dist/src/implements.d.ts +2 -21
- package/dist/src/index.d.ts +4 -4
- package/dist/src/index.js +3 -3
- package/dist/src/mcp/server.js +3 -5
- package/dist/src/model.js +6 -6
- package/dist/src/order-resolver.js +1 -0
- package/dist/src/store/gc.js +1 -0
- package/dist/src/store.d.ts +2 -0
- package/dist/src/store.js +135 -17
- package/dist/src/types.d.ts +36 -0
- package/dist/src/types.js +4 -0
- package/docs/authoring.md +74 -1
- package/docs/design.md +1 -1
- package/docs/mcp-charter-eval.md +101 -32
- package/package.json +1 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/index.js
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* workflow definitions + a Step Agent that executes orders) layers a concrete
|
|
12
12
|
* process — software delivery, research, triage — on top of it.
|
|
13
13
|
*/
|
|
14
|
-
export { CallsPinError, Engine, ModifierRefusalError } from "./engine.js";
|
|
14
|
+
export { CallsPinError, Engine, InterfaceBindingRefusalError, InterfaceCallPinError, ModifierRefusalError, } from "./engine.js";
|
|
15
15
|
// Routing capabilities: offer-time composition and the claim-side match. The
|
|
16
16
|
// hub imports these to reason about the same compounds the engine composes.
|
|
17
17
|
export { applyCapabilityMappings, applyCapabilityRewrites, capabilityName, claimMatches, composeCapabilities, DEFAULT_MATCH_MODE, MODIFIER_SEPARATOR, } from "./capabilities.js";
|
|
@@ -22,7 +22,7 @@ export { Store, openStore, readRuntimeSnapshotBundlePins, StoreVersionError } fr
|
|
|
22
22
|
// store above): two-level digest-addressed workflow objects + coordinate
|
|
23
23
|
// index, `.wnlp` bundle installation, and fail-closed resolution.
|
|
24
24
|
export { defDigest, collectWorkflowStoreGarbage, emptyWorkflowStoreIndex, globalStoreRoot, hardenObjectModes, installWorkflowBundle, inspectCasDefs, isDefDigest, loadCasDefs, planWorkflowStoreGc, objectDestRelPath, objectDirForDigest, parseWorkflowCoordinate, parseWorkflowStoreIndex, projectStoreRoot, probeObjectDir, probeStoreRoot, readWorkflowStoreIndex, recoverWorkflowStore, resolveWorkflowCoordinate, resolveWorkflowDigest, serializeWorkflowStoreIndex, storeIndexPath, workflowCoordinate, workflowStoreStatePaths, WORKFLOW_STORE_INDEX_VERSION, WorkflowStoreError, StoreIndexError, StoreDigestError, StoreCoordinateError, StoreAmbiguityError, StoreNotFoundError, StoreIntegrityError, StoreConflictError, StoreDefinitionVerificationError, StoreOriginPolicyError, StorePathError, BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, createExecutionOriginVerifier, originEvidencePath, persistOriginEvidence, readOriginEvidence, } from "./store/index.js";
|
|
25
|
-
export { buildDef, cancelCleanupSteps, DefError, expandIncludes, finalizeDefs, hashDef, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, resolveCallsTarget, SUPPORTED_ENGINE_VERSION, validateDef } from "./defs.js";
|
|
25
|
+
export { buildDef, cancelCleanupSteps, DefError, expandIncludes, finalizeDefs, hashDef, InterfaceCallDefinitionError, lintDef, loadDefFile, loadDefs, loadDefsRaw, parseDef, resolveCallsTarget, SUPPORTED_ENGINE_VERSION, validateDef } from "./defs.js";
|
|
26
26
|
export { checkInterfaceCompatibility, implementsIssues } from "./implements.js";
|
|
27
27
|
export { credentialSlot, hashDefForHub, keychainServiceFor, normalizeOrigin, readStoredCredential } from "./hub.js";
|
|
28
28
|
export { deleteCredential, ensureFreshOAuth, storeCredential } from "./credentials.js";
|
|
@@ -40,6 +40,6 @@ export { enrollmentGrantSchema, orderSchema, originSchema, policyFloorSchema, pu
|
|
|
40
40
|
// typed errors. Low-level tar builders and add install primitives are
|
|
41
41
|
// deliberately NOT exported through this surface (see docs/bundles.md).
|
|
42
42
|
export { BundleError, DEFAULT_BUNDLE_LIMITS, digestBundle, inspectBundle, packBundle, unpackBundle } from "./bundle/index.js";
|
|
43
|
-
export { DEBT_STATES, SETTLED_STATES } from "./types.js";
|
|
43
|
+
export { DEBT_STATES, isCallStep, SETTLED_STATES } from "./types.js";
|
|
44
44
|
// ---- WP-D2 signed submission records ----
|
|
45
45
|
export { canonicalValueBytes, valueDigestHex, buildSubmissionRecord, signSubmission } from "./crypto/index.js";
|
package/dist/src/mcp/server.js
CHANGED
|
@@ -61,11 +61,9 @@ const OUR_PROTOCOL_VERSION = '2025-06-18';
|
|
|
61
61
|
//
|
|
62
62
|
// Commit the charter edit and the regenerated baseline together.
|
|
63
63
|
//
|
|
64
|
-
//
|
|
65
|
-
//
|
|
66
|
-
//
|
|
67
|
-
// re-run before concluding an edit helped or hurt. The run history and the
|
|
68
|
-
// per-arm ranges live in docs/mcp-charter-eval.md.
|
|
64
|
+
// The unchanged 35773e2e control has ten Claude 4/4 samples and Codex values
|
|
65
|
+
// 3, 4, 4, 2, 3, 2, 2, 3, 3, 3. No charter effect can be inferred from the
|
|
66
|
+
// Codex score; the full negative-result finding is in docs/mcp-charter-eval.md.
|
|
69
67
|
//
|
|
70
68
|
// search_workflows is deliberately NOT named here. The eval scores the first
|
|
71
69
|
// tool call, and offering a second discovery verb in the charter competes with
|
package/dist/src/model.js
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
* The artifact set for one workflow instance is passed as a `Map<path, data>`.
|
|
11
11
|
*/
|
|
12
12
|
import { bindProduce, elementPath, isMemberOf, parseElement, sealPath, sealStem, } from "./paths.js";
|
|
13
|
-
import { DEBT_STATES, OUTSTANDING_STATES, SETTLED_STATES } from "./types.js";
|
|
13
|
+
import { DEBT_STATES, isCallStep, OUTSTANDING_STATES, SETTLED_STATES } from "./types.js";
|
|
14
14
|
/**
|
|
15
15
|
* Time facts used only when classifying a model-checker no-moves state. This
|
|
16
16
|
* asks whether elapsed idle time could release a move; it deliberately does
|
|
@@ -431,7 +431,7 @@ export function requiredInputs(def, arts, art) {
|
|
|
431
431
|
*/
|
|
432
432
|
function maintenanceInputs(def, arts, art) {
|
|
433
433
|
const step = stepByName(def, art.producer);
|
|
434
|
-
if (step
|
|
434
|
+
if (step !== undefined && isCallStep(step))
|
|
435
435
|
return Object.values(step.callsInputs ?? {});
|
|
436
436
|
return requiredInputs(def, arts, art);
|
|
437
437
|
}
|
|
@@ -595,7 +595,7 @@ function callsGateReady(step, arts) {
|
|
|
595
595
|
function callsDischargeFirings(def, arts) {
|
|
596
596
|
const firings = [];
|
|
597
597
|
for (const step of def.steps) {
|
|
598
|
-
if (!step
|
|
598
|
+
if (!isCallStep(step))
|
|
599
599
|
continue;
|
|
600
600
|
if (!callsGateReady(step, arts))
|
|
601
601
|
continue;
|
|
@@ -670,7 +670,7 @@ export function eligibleFirings(def, arts, time, opts) {
|
|
|
670
670
|
const firings = [];
|
|
671
671
|
for (const step of def.steps) {
|
|
672
672
|
// M2: calls: steps are machine-handled (the engine spawns the child); never emit a worker firing.
|
|
673
|
-
if (step
|
|
673
|
+
if (isCallStep(step))
|
|
674
674
|
continue;
|
|
675
675
|
// §24: a judge step fires through the NORMAL pipeline (§7.1) — level-triggered
|
|
676
676
|
// on "the judged stem is submitted and this judge hasn't approved the current
|
|
@@ -937,7 +937,7 @@ export function maintainDecisions(def, arts, time) {
|
|
|
937
937
|
// was made on green inputs (§16.1).
|
|
938
938
|
if (art.acceptance === 'skipped') {
|
|
939
939
|
const producerStep = stepByName(def, art.producer);
|
|
940
|
-
const isCallsCascade = producerStep
|
|
940
|
+
const isCallsCascade = producerStep !== undefined && isCallStep(producerStep) && isEngineStructuralSkip(art);
|
|
941
941
|
const req = isCallsCascade ? maintenanceInputs(def, arts, art) : requiredInputs(def, arts, art);
|
|
942
942
|
const allGreen = req.length > 0 && req.every((p) => isGreen(arts.get(p)));
|
|
943
943
|
const moved = !fingerprintMatches(arts, req, art.fingerprint ?? {});
|
|
@@ -1988,7 +1988,7 @@ function eligibleOutcomes(def, arts, firing) {
|
|
|
1988
1988
|
// calls: produce may carry neither `judges:` nor `group:` (rejected by
|
|
1989
1989
|
// `buildStep`). Modeling only the green keeps the successor set faithful to
|
|
1990
1990
|
// what the engine can actually do here.
|
|
1991
|
-
if (step
|
|
1991
|
+
if (isCallStep(step))
|
|
1992
1992
|
return ['green'];
|
|
1993
1993
|
const stem = collectionStem(step);
|
|
1994
1994
|
const outPath = firing.outputs[0] ?? '';
|
|
@@ -111,6 +111,7 @@ export function defInstructionDigest(def) {
|
|
|
111
111
|
...(s.capabilities !== undefined ? { capabilities: s.capabilities } : {}),
|
|
112
112
|
...(s.maxLeaseMs !== undefined ? { maxLeaseMs: s.maxLeaseMs } : {}),
|
|
113
113
|
...(s.calls !== undefined ? { calls: s.calls } : {}),
|
|
114
|
+
...(s.callsInterface !== undefined ? { callsInterface: s.callsInterface } : {}),
|
|
114
115
|
...(s.callsInputs !== undefined ? { callsInputs: s.callsInputs } : {}),
|
|
115
116
|
...(s.judges !== undefined ? { judges: s.judges } : {}),
|
|
116
117
|
...(s.groups !== undefined ? { groups: s.groups } : {}),
|
package/dist/src/store/gc.js
CHANGED
|
@@ -266,6 +266,7 @@ export function planWorkflowStoreGc(args) {
|
|
|
266
266
|
const digests = [
|
|
267
267
|
...(snapshot.bundleDigest === undefined ? [] : [defDigest(snapshot.bundleDigest)]),
|
|
268
268
|
...snapshot.bundleLock.map((digest) => defDigest(digest)),
|
|
269
|
+
...(snapshot.interfaceBindingDigests ?? []).map((digest) => defDigest(digest)),
|
|
269
270
|
];
|
|
270
271
|
for (const digest of digests) {
|
|
271
272
|
if (targetCoordinatesForDigest(digest).length > 0) {
|
package/dist/src/store.d.ts
CHANGED
|
@@ -44,6 +44,8 @@ export interface RuntimeSnapshotBundlePins {
|
|
|
44
44
|
bundleLock: string[];
|
|
45
45
|
/** Exact versioned calls not already covered by this snapshot's bundle lock. */
|
|
46
46
|
exactCalls?: string[];
|
|
47
|
+
/** Start-bound implementation bundles retained before any child is spawned. */
|
|
48
|
+
interfaceBindingDigests?: string[];
|
|
47
49
|
}
|
|
48
50
|
/**
|
|
49
51
|
* Read bundle pins from an EXISTING runtime database without migrating or
|
package/dist/src/store.js
CHANGED
|
@@ -84,23 +84,35 @@ export function readRuntimeSnapshotBundlePins(path) {
|
|
|
84
84
|
if (!hasWorkflow)
|
|
85
85
|
return [];
|
|
86
86
|
const columns = db.prepare('PRAGMA table_info(workflow)').all();
|
|
87
|
-
|
|
87
|
+
const hasSnapshotColumn = columns.some((column) => column.name === 'def_snapshot');
|
|
88
|
+
const hasBindingsColumn = columns.some((column) => column.name === 'interface_bindings');
|
|
89
|
+
if (!hasSnapshotColumn && !hasBindingsColumn)
|
|
88
90
|
return [];
|
|
91
|
+
const snapshotProjection = hasSnapshotColumn ? 'def_snapshot' : 'NULL AS def_snapshot';
|
|
92
|
+
const bindingProjection = hasBindingsColumn ? 'interface_bindings' : 'NULL AS interface_bindings';
|
|
93
|
+
const predicates = [
|
|
94
|
+
...(hasSnapshotColumn ? ['def_snapshot IS NOT NULL'] : []),
|
|
95
|
+
...(hasBindingsColumn ? ['interface_bindings IS NOT NULL'] : []),
|
|
96
|
+
];
|
|
89
97
|
const rows = db
|
|
90
|
-
.prepare(
|
|
98
|
+
.prepare(`SELECT id, ${snapshotProjection}, ${bindingProjection} FROM workflow `
|
|
99
|
+
+ `WHERE ${predicates.join(' OR ')} ORDER BY created_at, id`)
|
|
91
100
|
.all();
|
|
92
101
|
return rows.map((row) => {
|
|
93
|
-
let
|
|
94
|
-
|
|
95
|
-
snapshot
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
+
let record = {};
|
|
103
|
+
if (row.def_snapshot !== null) {
|
|
104
|
+
let snapshot;
|
|
105
|
+
try {
|
|
106
|
+
snapshot = JSON.parse(row.def_snapshot);
|
|
107
|
+
}
|
|
108
|
+
catch (error) {
|
|
109
|
+
throw new Error(`workflow '${row.id}' has malformed def_snapshot JSON: ${error.message}`);
|
|
110
|
+
}
|
|
111
|
+
if (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)) {
|
|
112
|
+
throw new Error(`workflow '${row.id}' has malformed def_snapshot: expected an object`);
|
|
113
|
+
}
|
|
114
|
+
record = snapshot;
|
|
102
115
|
}
|
|
103
|
-
const record = snapshot;
|
|
104
116
|
const rawDigest = record.bundleDigest;
|
|
105
117
|
let bundleDigest;
|
|
106
118
|
if (rawDigest !== undefined && rawDigest !== '') {
|
|
@@ -120,11 +132,15 @@ export function readRuntimeSnapshotBundlePins(path) {
|
|
|
120
132
|
}
|
|
121
133
|
return digest;
|
|
122
134
|
});
|
|
123
|
-
const exactCalls = exactCallsFromSnapshot(record, row.id);
|
|
135
|
+
const exactCalls = row.def_snapshot === null ? [] : exactCallsFromSnapshot(record, row.id);
|
|
136
|
+
const interfaceBindingDigests = [
|
|
137
|
+
...new Set((parseStoredInterfaceBindings(row.interface_bindings, row.id) ?? []).map((binding) => binding.digest)),
|
|
138
|
+
].sort(compareStoreText);
|
|
124
139
|
return {
|
|
125
140
|
...(bundleDigest === undefined ? {} : { bundleDigest }),
|
|
126
141
|
bundleLock: [...new Set(bundleLock)].sort(compareStoreText),
|
|
127
142
|
...(exactCalls.length === 0 ? {} : { exactCalls }),
|
|
143
|
+
...(interfaceBindingDigests.length === 0 ? {} : { interfaceBindingDigests }),
|
|
128
144
|
};
|
|
129
145
|
});
|
|
130
146
|
}
|
|
@@ -148,6 +164,7 @@ CREATE TABLE IF NOT EXISTS workflow (
|
|
|
148
164
|
params TEXT NOT NULL DEFAULT '{}',
|
|
149
165
|
modifier TEXT,
|
|
150
166
|
meta TEXT,
|
|
167
|
+
interface_bindings TEXT,
|
|
151
168
|
created_at INTEGER NOT NULL
|
|
152
169
|
);
|
|
153
170
|
|
|
@@ -272,8 +289,11 @@ CREATE TABLE IF NOT EXISTS meta (
|
|
|
272
289
|
*
|
|
273
290
|
* Bumped to '11' for bound artifacts: the `workflow` table gains nullable
|
|
274
291
|
* JSON `meta` for non-routing `meta.<key>` artifact binds.
|
|
292
|
+
*
|
|
293
|
+
* Bumped to '12' for immutable start-time interface-call bindings: the
|
|
294
|
+
* `workflow` table gains nullable JSON `interface_bindings`.
|
|
275
295
|
*/
|
|
276
|
-
const SCHEMA_VERSION = '
|
|
296
|
+
const SCHEMA_VERSION = '12';
|
|
277
297
|
/** Thrown by the `Store` constructor when the on-disk `schema_version` is
|
|
278
298
|
* newer than this binary's `SCHEMA_VERSION` — the operator needs to
|
|
279
299
|
* upgrade their owenloop install to open this database. */
|
|
@@ -346,6 +366,98 @@ function fromJson(s, fallback, ctx) {
|
|
|
346
366
|
throw new Error(`Corrupt JSON in ${ctx.table}.${ctx.column} for row ${ctx.id}: ${msg}`);
|
|
347
367
|
}
|
|
348
368
|
}
|
|
369
|
+
function parseStoredInterfaceBindings(s, workflow) {
|
|
370
|
+
const value = fromJson(s, undefined, {
|
|
371
|
+
table: 'workflow',
|
|
372
|
+
id: workflow,
|
|
373
|
+
column: 'interface_bindings',
|
|
374
|
+
});
|
|
375
|
+
if (value === undefined)
|
|
376
|
+
return undefined;
|
|
377
|
+
if (!Array.isArray(value)) {
|
|
378
|
+
throw new Error(`workflow '${workflow}' has malformed interface_bindings: expected an array`);
|
|
379
|
+
}
|
|
380
|
+
const seenClaims = new Set();
|
|
381
|
+
for (const [index, binding] of value.entries()) {
|
|
382
|
+
const path = `workflow '${workflow}' interface_bindings[${index}]`;
|
|
383
|
+
if (typeof binding !== 'object' || binding === null || Array.isArray(binding)) {
|
|
384
|
+
throw new Error(`${path} is malformed: expected an object`);
|
|
385
|
+
}
|
|
386
|
+
const record = binding;
|
|
387
|
+
const bindingKeys = Object.keys(record).filter((key) => key !== 'interface' && key !== 'target' && key !== 'digest' && key !== 'signature');
|
|
388
|
+
if (bindingKeys.length > 0) {
|
|
389
|
+
throw new Error(`${path} is malformed: unknown field${bindingKeys.length === 1 ? '' : 's'} ${bindingKeys.join(', ')}`);
|
|
390
|
+
}
|
|
391
|
+
const claim = record.interface;
|
|
392
|
+
if (typeof claim !== 'object' || claim === null || Array.isArray(claim)) {
|
|
393
|
+
throw new Error(`${path}.interface is malformed: expected an object`);
|
|
394
|
+
}
|
|
395
|
+
const claimRecord = claim;
|
|
396
|
+
const claimKeys = Object.keys(claimRecord).filter((key) => key !== 'name' && key !== 'version');
|
|
397
|
+
if (claimKeys.length > 0) {
|
|
398
|
+
throw new Error(`${path}.interface is malformed: unknown field${claimKeys.length === 1 ? '' : 's'} ${claimKeys.join(', ')}`);
|
|
399
|
+
}
|
|
400
|
+
if (typeof claimRecord.name !== 'string' || claimRecord.name.trim() === ''
|
|
401
|
+
|| typeof claimRecord.version !== 'string' || claimRecord.version.trim() === '') {
|
|
402
|
+
throw new Error(`${path}.interface is malformed: name and version must be non-empty strings`);
|
|
403
|
+
}
|
|
404
|
+
const claimKey = JSON.stringify([claimRecord.name, claimRecord.version]);
|
|
405
|
+
if (seenClaims.has(claimKey)) {
|
|
406
|
+
throw new Error(`${path}.interface is malformed: duplicate interface claim ${claimRecord.name}@${claimRecord.version}`);
|
|
407
|
+
}
|
|
408
|
+
seenClaims.add(claimKey);
|
|
409
|
+
if (typeof record.target !== 'string') {
|
|
410
|
+
throw new Error(`${path}.target is malformed: expected an exact workflow coordinate`);
|
|
411
|
+
}
|
|
412
|
+
try {
|
|
413
|
+
parseWorkflowCoordinate(record.target);
|
|
414
|
+
}
|
|
415
|
+
catch (error) {
|
|
416
|
+
throw new Error(`${path}.target is malformed: ${error.message}`);
|
|
417
|
+
}
|
|
418
|
+
if (typeof record.digest !== 'string' || !isDefDigest(record.digest)) {
|
|
419
|
+
throw new Error(`${path}.digest is noncanonical: ${JSON.stringify(record.digest)}`);
|
|
420
|
+
}
|
|
421
|
+
const signature = record.signature;
|
|
422
|
+
if (typeof signature !== 'object' || signature === null || Array.isArray(signature)) {
|
|
423
|
+
throw new Error(`${path}.signature is malformed: expected an object`);
|
|
424
|
+
}
|
|
425
|
+
const signatureRecord = signature;
|
|
426
|
+
const signatureKeys = Object.keys(signatureRecord).filter((key) => key !== 'inputs' && key !== 'outputs');
|
|
427
|
+
if (signatureKeys.length > 0) {
|
|
428
|
+
throw new Error(`${path}.signature is malformed: unknown field${signatureKeys.length === 1 ? '' : 's'} ${signatureKeys.join(', ')}`);
|
|
429
|
+
}
|
|
430
|
+
if (!Array.isArray(signatureRecord.inputs) || !Array.isArray(signatureRecord.outputs)) {
|
|
431
|
+
throw new Error(`${path}.signature is malformed: inputs and outputs must be arrays`);
|
|
432
|
+
}
|
|
433
|
+
const signatureArtifacts = {
|
|
434
|
+
inputs: signatureRecord.inputs,
|
|
435
|
+
outputs: signatureRecord.outputs,
|
|
436
|
+
};
|
|
437
|
+
for (const direction of ['inputs', 'outputs']) {
|
|
438
|
+
for (const [artifactIndex, artifact] of signatureArtifacts[direction].entries()) {
|
|
439
|
+
const artifactPath = `${path}.signature.${direction}[${artifactIndex}]`;
|
|
440
|
+
if (typeof artifact !== 'object' || artifact === null || Array.isArray(artifact)) {
|
|
441
|
+
throw new Error(`${artifactPath} is malformed: expected an object`);
|
|
442
|
+
}
|
|
443
|
+
const artifactRecord = artifact;
|
|
444
|
+
const artifactKeys = Object.keys(artifactRecord).filter((key) => key !== 'name' && key !== 'schema');
|
|
445
|
+
if (artifactKeys.length > 0) {
|
|
446
|
+
throw new Error(`${artifactPath} is malformed: unknown field${artifactKeys.length === 1 ? '' : 's'} ${artifactKeys.join(', ')}`);
|
|
447
|
+
}
|
|
448
|
+
if (typeof artifactRecord.name !== 'string' || artifactRecord.name.trim() === '') {
|
|
449
|
+
throw new Error(`${artifactPath}.name is malformed: expected a non-empty string`);
|
|
450
|
+
}
|
|
451
|
+
if (artifactRecord.schema !== undefined
|
|
452
|
+
&& typeof artifactRecord.schema !== 'boolean'
|
|
453
|
+
&& (typeof artifactRecord.schema !== 'object' || artifactRecord.schema === null || Array.isArray(artifactRecord.schema))) {
|
|
454
|
+
throw new Error(`${artifactPath}.schema is malformed: expected a JSON Schema object or boolean`);
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
}
|
|
459
|
+
return value;
|
|
460
|
+
}
|
|
349
461
|
function mapArtifact(r) {
|
|
350
462
|
const out = {
|
|
351
463
|
id: r.id,
|
|
@@ -498,6 +610,9 @@ function mapWorkflow(r) {
|
|
|
498
610
|
});
|
|
499
611
|
if (meta !== undefined)
|
|
500
612
|
out.meta = meta;
|
|
613
|
+
const interfaceBindings = parseStoredInterfaceBindings(r.interface_bindings, r.id);
|
|
614
|
+
if (interfaceBindings !== undefined)
|
|
615
|
+
out.interfaceBindings = interfaceBindings;
|
|
501
616
|
return out;
|
|
502
617
|
}
|
|
503
618
|
// ---- the store ---------------------------------------------------------------
|
|
@@ -659,6 +774,9 @@ export class Store {
|
|
|
659
774
|
if (!wfCols.some((c) => c.name === 'meta')) {
|
|
660
775
|
this.db.exec(`ALTER TABLE workflow ADD COLUMN meta TEXT`);
|
|
661
776
|
}
|
|
777
|
+
if (!wfCols.some((c) => c.name === 'interface_bindings')) {
|
|
778
|
+
this.db.exec(`ALTER TABLE workflow ADD COLUMN interface_bindings TEXT`);
|
|
779
|
+
}
|
|
662
780
|
// Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
|
|
663
781
|
// reason thread. Re-opening an already-v8 database must not manufacture a
|
|
664
782
|
// second copy of its lifecycle events (even though the legacy keys differ
|
|
@@ -745,9 +863,9 @@ export class Store {
|
|
|
745
863
|
const at = nowMs();
|
|
746
864
|
this.db
|
|
747
865
|
.prepare(`INSERT INTO workflow
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
.run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, toJson(data.meta), at);
|
|
866
|
+
(id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, meta, interface_bindings, created_at)
|
|
867
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
868
|
+
.run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, toJson(data.meta), toJson(data.interfaceBindings), at);
|
|
751
869
|
return this.getWorkflow(id);
|
|
752
870
|
}
|
|
753
871
|
/**
|
package/dist/src/types.d.ts
CHANGED
|
@@ -42,6 +42,32 @@ export type RejectKind = 'judgment' | 'structural' | 'validation' | 'invalidated
|
|
|
42
42
|
export type ReasonAction = 'reject' | 'retract' | 'skip' | 'reopen' | 'retry' | 'ask' | 'born-rejected' | 'schema-reject' | 'pinned';
|
|
43
43
|
/** A JSON Schema, as authored in a definition: an object, or a boolean (allow/deny all). */
|
|
44
44
|
export type JsonSchema = Record<string, unknown> | boolean;
|
|
45
|
+
/** A versioned external interface coordinate. Names and versions are opaque. */
|
|
46
|
+
export interface WorkflowInterfaceClaim {
|
|
47
|
+
name: string;
|
|
48
|
+
version: string;
|
|
49
|
+
}
|
|
50
|
+
/** A named input or public output and the schema that defines its values. */
|
|
51
|
+
export interface WorkflowInterfaceArtifact {
|
|
52
|
+
name: string;
|
|
53
|
+
schema?: JsonSchema;
|
|
54
|
+
}
|
|
55
|
+
/** The typed portion of an external workflow interface. */
|
|
56
|
+
export interface WorkflowInterfaceSignature {
|
|
57
|
+
inputs: WorkflowInterfaceArtifact[];
|
|
58
|
+
outputs: WorkflowInterfaceArtifact[];
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* One hub-selected implementation pinned when an instance starts. The engine
|
|
62
|
+
* validates the exact coordinate, bundle digest, nominal claim, and structural
|
|
63
|
+
* signature before persisting this immutable mapping.
|
|
64
|
+
*/
|
|
65
|
+
export interface InterfaceCallBinding {
|
|
66
|
+
interface: WorkflowInterfaceClaim;
|
|
67
|
+
target: string;
|
|
68
|
+
digest: string;
|
|
69
|
+
signature: WorkflowInterfaceSignature;
|
|
70
|
+
}
|
|
45
71
|
/** One entry in an artifact's append-only reason thread (design §4). */
|
|
46
72
|
export interface ReasonEntry {
|
|
47
73
|
at: number;
|
|
@@ -364,6 +390,12 @@ export interface WorkflowData {
|
|
|
364
390
|
modifier?: string;
|
|
365
391
|
/** Engine-written, non-routing metadata populated by artifact binds. */
|
|
366
392
|
meta?: Record<string, unknown>;
|
|
393
|
+
/**
|
|
394
|
+
* Complete, normalized start-time interface-call bindings inherited by every
|
|
395
|
+
* calls child. Immutable instance state: routing/meta updates and adopt never
|
|
396
|
+
* rewrite it, and legacy rows map SQL NULL to true property absence.
|
|
397
|
+
*/
|
|
398
|
+
interfaceBindings?: InterfaceCallBinding[];
|
|
367
399
|
/** Instance-to-definition pinning (§28): the compiled def this instance was
|
|
368
400
|
* created against, snapshotted verbatim as JSON. Absent on rows created
|
|
369
401
|
* before this feature shipped — those instances fall back to today's
|
|
@@ -610,6 +642,8 @@ export interface StepDef {
|
|
|
610
642
|
body: string;
|
|
611
643
|
/** Mode 2 foundation: name of the child workflow this step delegates to. Machine-handled, never a worker firing. */
|
|
612
644
|
calls?: string;
|
|
645
|
+
/** Versioned interface delegated to through the instance's immutable start-time binding. */
|
|
646
|
+
callsInterface?: WorkflowInterfaceClaim;
|
|
613
647
|
/** Mode 2 foundation: child input name → parent artifact name wiring for a calls: step. */
|
|
614
648
|
callsInputs?: Record<string, string>;
|
|
615
649
|
/** §24 judges: marker naming the produce stem this synthesized step judges. Mirrors `calls?`. */
|
|
@@ -621,6 +655,8 @@ export interface StepDef {
|
|
|
621
655
|
* `buildOrder` onto the Order for an external runner/tooling to read. */
|
|
622
656
|
x?: Record<string, unknown>;
|
|
623
657
|
}
|
|
658
|
+
/** True for either statically-targeted or start-bound machine call steps. */
|
|
659
|
+
export declare function isCallStep(step: Pick<StepDef, 'calls' | 'callsInterface'>): boolean;
|
|
624
660
|
/** A workflow definition: a set of steps plus declared external inputs. */
|
|
625
661
|
export interface WorkflowDef {
|
|
626
662
|
name: string;
|
package/dist/src/types.js
CHANGED
|
@@ -25,3 +25,7 @@ export const OUTSTANDING_STATES = new Set([
|
|
|
25
25
|
...DEBT_STATES,
|
|
26
26
|
'submitted',
|
|
27
27
|
]);
|
|
28
|
+
/** True for either statically-targeted or start-bound machine call steps. */
|
|
29
|
+
export function isCallStep(step) {
|
|
30
|
+
return step.calls !== undefined || step.callsInterface !== undefined;
|
|
31
|
+
}
|
package/docs/authoring.md
CHANGED
|
@@ -451,6 +451,11 @@ if nothing consumes it. A stem under `generates:` is deliberately consumed by no
|
|
|
451
451
|
are otherwise identical: schema-validated, fingerprinted, greenable, and visible in
|
|
452
452
|
`status`/`show`.
|
|
453
453
|
|
|
454
|
+
Call steps are also consumers for this check. For `calls:` and `callsInterface:`, each
|
|
455
|
+
parent-artifact value in the child-input `inputs:` mapping counts as consumed even when
|
|
456
|
+
the step's ordinary `consumes:` list is empty; the mapping keys are child input names and
|
|
457
|
+
do not count.
|
|
458
|
+
|
|
454
459
|
## `bind:` — write an accepted artifact into run state
|
|
455
460
|
|
|
456
461
|
A produce mapping may declare a `bind:` target. When that artifact is accepted,
|
|
@@ -551,6 +556,16 @@ regardless of `executor:` — that requirement is orthogonal to this feature and
|
|
|
551
556
|
applies even to a `executor: command` judge (the field just goes unread by a
|
|
552
557
|
non-agent dispatcher).
|
|
553
558
|
|
|
559
|
+
Native judges declared here inherit the producing step's `capabilities:` when a
|
|
560
|
+
judge omits that key: the synthesized judge receives a copy. A non-empty
|
|
561
|
+
`capabilities:` list on the judge is authoritative and replaces — rather than
|
|
562
|
+
extends — the producer list; `capabilities: []` is invalid, so omit the key to
|
|
563
|
+
request inheritance. At offer time, the run modifier composes with every
|
|
564
|
+
capability in the resulting judge list just as it does for an ordinary step
|
|
565
|
+
(for example, `wise` under `deep` is offered as `wise:deep`). If neither the
|
|
566
|
+
producer nor judge supplies capabilities, the judge remains capability-silent,
|
|
567
|
+
and there is nothing to compose.
|
|
568
|
+
|
|
554
569
|
Author `x:` on the producer step, not on individual judge entries. Every native
|
|
555
570
|
judge synthesized from that producer inherits the producer's complete parsed
|
|
556
571
|
`x:` map. Each judge receives an independent deep clone, so runner-side
|
|
@@ -642,7 +657,7 @@ from dead-end warnings, but unlike `terminal:` they stay re-armable.
|
|
|
642
657
|
| `generates:` | step | yes | yes | internal sink, not the public interface |
|
|
643
658
|
| `outputs:` | workflow | yes | yes | public interface / composition boundary |
|
|
644
659
|
|
|
645
|
-
## Composition — `include:` (compile-time) and
|
|
660
|
+
## Composition — `include:` (compile-time) and runtime calls
|
|
646
661
|
|
|
647
662
|
Two ways to build a workflow out of other workflows:
|
|
648
663
|
|
|
@@ -716,6 +731,64 @@ the engine re-provides it to the existing child — it never spawns a duplicate.
|
|
|
716
731
|
| Use for | New combined workflows | Embedding an existing workflow as a black box |
|
|
717
732
|
| Visibility | All child stems visible in the parent | Only the declared `produces:` artifact |
|
|
718
733
|
|
|
734
|
+
### Calling a start-bound interface
|
|
735
|
+
|
|
736
|
+
`callsInterface:` is the interface-targeted form of a runtime call. The workflow
|
|
737
|
+
author names the exact interface version the step requires, while the host that starts
|
|
738
|
+
the instance selects the installed implementation. The engine validates that selection
|
|
739
|
+
before it writes the root instance and pins the complete binding set for the lifetime of
|
|
740
|
+
the run.
|
|
741
|
+
|
|
742
|
+
```yaml
|
|
743
|
+
steps:
|
|
744
|
+
- name: report
|
|
745
|
+
callsInterface:
|
|
746
|
+
name: report
|
|
747
|
+
version: 1.0.0
|
|
748
|
+
inputs:
|
|
749
|
+
source: prepared_source
|
|
750
|
+
produces: [report]
|
|
751
|
+
```
|
|
752
|
+
|
|
753
|
+
`callsInterface:` and `calls:` are mutually exclusive. Otherwise the call-step contract
|
|
754
|
+
is the same: exactly one `produces:` entry, child-input-to-parent-artifact `inputs:`
|
|
755
|
+
wiring, no `judges:` or `group:`, engine-managed spawning, and no Worker order for the
|
|
756
|
+
call step itself. Interface calls v1 also require the chosen implementation workflow to
|
|
757
|
+
declare exactly one public `outputs:` entry.
|
|
758
|
+
|
|
759
|
+
The host supplies one binding for every interface called directly by the workflow when
|
|
760
|
+
it invokes `Engine.createInstance`:
|
|
761
|
+
|
|
762
|
+
```ts
|
|
763
|
+
engine.createInstance('parent', {
|
|
764
|
+
interfaceBindings: [{
|
|
765
|
+
interface: { name: 'report', version: '1.0.0' },
|
|
766
|
+
target: 'acme/report@2.3.1',
|
|
767
|
+
digest: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
|
|
768
|
+
signature: {
|
|
769
|
+
inputs: [{ name: 'source', schema: { type: 'object' } }],
|
|
770
|
+
outputs: [{ name: 'report', schema: { type: 'object' } }],
|
|
771
|
+
},
|
|
772
|
+
}],
|
|
773
|
+
});
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
`target` must be an exact installed workflow coordinate and `digest` must be that
|
|
777
|
+
bundle's canonical lowercase SHA-256 digest. The target must carry a matching valid
|
|
778
|
+
`x.implements` claim, its declared input and output schemas must be structurally
|
|
779
|
+
compatible with the supplied signature, and every wired child input must exist in both
|
|
780
|
+
the signature and target. A missing, duplicate, malformed, stale, or incompatible
|
|
781
|
+
binding throws the named `InterfaceBindingRefusalError` before any workflow or artifact
|
|
782
|
+
row is inserted.
|
|
783
|
+
|
|
784
|
+
The root's normalized bindings are inherited unchanged by every child. At spawn time
|
|
785
|
+
the engine resolves the implementation by its exact digest again and transactionally
|
|
786
|
+
compares it with the persisted target and digest. A missing or repointed implementation
|
|
787
|
+
becomes visible structural debt on the parent call output; the engine does not fall
|
|
788
|
+
back, reselect, or rebind. Updates to installed implementations therefore affect only
|
|
789
|
+
new instances whose host selects them. Selection, ranking, and receipt authorship belong
|
|
790
|
+
to the host; the engine accepts, validates, persists, and enforces the resulting pin.
|
|
791
|
+
|
|
719
792
|
## `effect:` — re-running steps with side effects
|
|
720
793
|
|
|
721
794
|
By default a step is **idempotent** — safe to re-run if its inputs move, which is what
|
package/docs/design.md
CHANGED
|
@@ -628,7 +628,7 @@ A green, value-defined declared outcome may carry a status-bearing value (e.g. `
|
|
|
628
628
|
|
|
629
629
|
#### §23.6.5 Gate fingerprint and re-arm
|
|
630
630
|
|
|
631
|
-
The machine-green fingerprint covers `gateStems` (the parent artifacts wired into the child via `callsInputs`) plus, as of F4 (§23.6.8), a reserved `__child_outcome_version__` key pinning the child outcome's version. The cross-instance join/re-green trigger is handled by `maintainCalls`'s outcome-value, `workflowDone`, and version-pin checks, not by green-fingerprint invalidation in the pure forward cascade: a calls: step still declares `consumes: []`, and its live green fingerprint must not be compared with the gate-only dependency set. Maintenance does use `callsInputs` separately to find dead gate branches, structurally skip the calls output and its downstream branch, and revive an engine-authored cascade skip after the gate returns green with moved versions. Human or producer skips retain the child-outcome pin semantics in §23.6.8 and are not revived merely because the gate is green.
|
|
631
|
+
The machine-green fingerprint covers `gateStems` (the parent artifacts wired into the child via `callsInputs`) plus, as of F4 (§23.6.8), a reserved `__child_outcome_version__` key pinning the child outcome's version. The cross-instance join/re-green trigger is handled by `maintainCalls`'s outcome-value, `workflowDone`, and version-pin checks, not by green-fingerprint invalidation in the pure forward cascade: a calls: step still declares `consumes: []`, and its live green fingerprint must not be compared with the gate-only dependency set. Dead-end lint nevertheless treats every parent-artifact value in `callsInputs` as consumed; these values are lint consumers, not ordinary `consumes:` edges. Maintenance does use `callsInputs` separately to find dead gate branches, structurally skip the calls output and its downstream branch, and revive an engine-authored cascade skip after the gate returns green with moved versions. Human or producer skips retain the child-outcome pin semantics in §23.6.8 and are not revived merely because the gate is green.
|
|
632
632
|
|
|
633
633
|
#### §23.6.6 Transaction composition
|
|
634
634
|
|