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.
Files changed (83) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1196 -164
  28. package/dist/src/defs.d.ts +32 -1
  29. package/dist/src/defs.js +391 -79
  30. package/dist/src/engine.d.ts +62 -19
  31. package/dist/src/engine.js +180 -70
  32. package/dist/src/hub.d.ts +77 -0
  33. package/dist/src/hub.js +162 -0
  34. package/dist/src/implements.d.ts +56 -0
  35. package/dist/src/implements.js +790 -0
  36. package/dist/src/index.d.ts +8 -6
  37. package/dist/src/index.js +4 -3
  38. package/dist/src/mcp/serve.js +254 -45
  39. package/dist/src/mcp/server.d.ts +10 -7
  40. package/dist/src/mcp/server.js +53 -8
  41. package/dist/src/model.d.ts +46 -10
  42. package/dist/src/model.js +220 -74
  43. package/dist/src/store/def-source.d.ts +19 -0
  44. package/dist/src/store/def-source.js +87 -17
  45. package/dist/src/store/gc-recovery.d.ts +46 -0
  46. package/dist/src/store/gc-recovery.js +258 -0
  47. package/dist/src/store/gc.d.ts +94 -0
  48. package/dist/src/store/gc.js +562 -0
  49. package/dist/src/store/index.d.ts +3 -1
  50. package/dist/src/store/index.js +2 -0
  51. package/dist/src/store/install.d.ts +34 -5
  52. package/dist/src/store/install.js +73 -11
  53. package/dist/src/store/pre-commit-verifier.js +42 -2
  54. package/dist/src/store/snapshot-guard.d.ts +18 -0
  55. package/dist/src/store/snapshot-guard.js +94 -0
  56. package/dist/src/store.d.ts +64 -4
  57. package/dist/src/store.js +211 -8
  58. package/dist/src/types.d.ts +61 -17
  59. package/dist/src/util.js +4 -1
  60. package/docs/authoring.md +145 -8
  61. package/docs/bundles.md +19 -0
  62. package/docs/cli.md +270 -30
  63. package/docs/crypto.md +13 -7
  64. package/docs/design.md +107 -46
  65. package/docs/evals/mcp-charter-baseline.json +428 -0
  66. package/docs/mcp-charter-eval.md +124 -0
  67. package/docs/shift-logs.md +18 -0
  68. package/docs/wire-contracts.md +28 -7
  69. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  70. package/examples/workflows/ship.yaml +28 -2
  71. package/package.json +2 -1
  72. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  73. package/plugins/claude-code/plugin/.mcp.json +1 -1
  74. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  75. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  76. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  77. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  81. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  82. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  83. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -96,6 +96,22 @@ export declare function digestScopedCallsTargetKey(digest: string, target: strin
96
96
  * spawns at runtime.
97
97
  */
98
98
  export declare function resolveCallsTarget(defs: Map<string, WorkflowDef>, target: string, from: WorkflowDef): WorkflowDef | undefined;
99
+ /** A calls cycle and the resolved definition keys on its displayed path. */
100
+ export interface CallsCycleFinding {
101
+ message: string;
102
+ members: string[];
103
+ }
104
+ /**
105
+ * Report calls cycles in a flat def map. This is the Mode 2 analogue of the
106
+ * Mode 1 include-cycle guard in expandIncludes; the two edge kinds stay
107
+ * deliberately separate. Findings use resolved map identity, not bare call
108
+ * text, so CAS bundle siblings cannot be accidentally fused. The first finding
109
+ * is strict loading's legacy DFS witness. Further findings add at most one
110
+ * deterministic witness for each still-unattributed cyclic member, keeping
111
+ * authoring attribution polynomial and every finding's members consistent with
112
+ * its displayed path without enumerating exponentially many simple cycles.
113
+ */
114
+ export declare function reportCallsCycles(defs: Map<string, WorkflowDef>): CallsCycleFinding[];
99
115
  /** Load and validate a single workflow definition from a YAML file. */
100
116
  export declare function loadDefFile(file: string): WorkflowDef;
101
117
  /**
@@ -130,7 +146,8 @@ export declare function loadDefsUnfinalized(dir: string): Map<string, WorkflowDe
130
146
  * (each def possibly still carrying `_includes`), it: expands each def's
131
147
  * includes; runs the cross-def `calls:` checks (target existence, `callsInputs`
132
148
  * key validity, exactly-one child output); runs `validateDef` per expanded def;
133
- * and finally `detectCallsCycles` over the whole expanded map. Returns the
149
+ * and finally performs the bounded first-cycle DFS over the whole expanded map.
150
+ * `reportCallsCycles` exposes the wider per-member authoring report. Returns the
134
151
  * expanded, validated map. Throws `DefError` on the first problem — the same
135
152
  * messages, in the same order, the filesystem loader has always produced (this
136
153
  * is a pure extraction of what used to live inline in `loadDefs`).
@@ -153,6 +170,12 @@ export interface FinalizeDefsOptions {
153
170
  */
154
171
  allowUnresolvedCalls?: boolean;
155
172
  }
173
+ /**
174
+ * Return every direct cross-definition `calls:` error for one expanded
175
+ * definition. Strict loading uses the first result to retain its historical
176
+ * throw behavior; tolerant authoring commands can present the complete list.
177
+ */
178
+ export declare function validateCallsEdges(def: WorkflowDef, defs: Map<string, WorkflowDef>, options?: FinalizeDefsOptions): string[];
156
179
  export declare function finalizeDefs(raw: Map<string, WorkflowDef>, options?: FinalizeDefsOptions): Map<string, WorkflowDef>;
157
180
  /** One file that `loadDefsRaw` could not turn into a def (malformed YAML, bad shape, duplicate name). */
158
181
  export interface DefLoadFailure {
@@ -168,4 +191,12 @@ export interface DefLoadFailure {
168
191
  * Two-phase: Phase 1 collects all defs. Phase 2 expands includes best-effort
169
192
  * (silently skips expansion failures so the lint caller sees un-expanded defs).
170
193
  */
194
+ export declare function scanDefsRaw(dir: string, failures?: DefLoadFailure[]): Map<string, WorkflowDef>;
195
+ /** Best-effort include expansion for a complete, already-merged raw map. */
196
+ export declare function expandDefsRaw(raw: Map<string, WorkflowDef>): Map<string, WorkflowDef>;
197
+ /**
198
+ * Compatibility wrapper for tolerant single-directory loading. Raw loading
199
+ * builds and expands includes best-effort; callers explicitly invoke shared
200
+ * calls validation and cycle reporting against the complete definition map.
201
+ */
171
202
  export declare function loadDefsRaw(dir: string, failures?: DefLoadFailure[]): Map<string, WorkflowDef>;
package/dist/src/defs.js CHANGED
@@ -915,13 +915,23 @@ export function expandIncludes(def, resolve, stack) {
915
915
  stepIdx++;
916
916
  }
917
917
  }
918
- return {
918
+ const expanded = {
919
919
  ...def,
920
920
  steps: resultSteps,
921
921
  inputs: resultInputs,
922
922
  outputs: resultOutputs.length > 0 ? resultOutputs : def.outputs,
923
923
  _includes: undefined,
924
924
  };
925
+ // CAS store roots are live loader provenance, deliberately non-enumerable so
926
+ // they never enter hashes or persisted snapshots. The spread above therefore
927
+ // cannot carry them. Preserve the original descriptor explicitly so an
928
+ // include-expanded CAS definition still coordinates its snapshot writes with
929
+ // bundle GC.
930
+ const storeRoots = Object.getOwnPropertyDescriptor(def, 'bundleStoreRoots');
931
+ if (storeRoots !== undefined) {
932
+ Object.defineProperty(expanded, 'bundleStoreRoots', storeRoots);
933
+ }
934
+ return expanded;
925
935
  }
926
936
  /** Build a validated `WorkflowDef` from a parsed YAML object (or throw DefError). */
927
937
  export function parseDef(raw, source, baseDir) {
@@ -1893,6 +1903,150 @@ function unroutedCapabilityWarnings(def) {
1893
1903
  }
1894
1904
  return warnings;
1895
1905
  }
1906
+ /** Whether a discovery-convention value is a YAML mapping. */
1907
+ function isDiscoveryMap(value) {
1908
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
1909
+ }
1910
+ /**
1911
+ * Return advisory issues for Owenloop's optional x.discovery convention.
1912
+ *
1913
+ * This deliberately does not assign a severity. W2.1 can promote these same
1914
+ * deterministic issues for library definitions without duplicating validation.
1915
+ * The parser and engine continue to treat all extension contents as opaque.
1916
+ */
1917
+ function discoveryIssues(def) {
1918
+ const issues = [];
1919
+ const discovery = def.x?.discovery;
1920
+ if (discovery === undefined)
1921
+ return ['x.discovery: missing required discovery metadata'];
1922
+ if (!isDiscoveryMap(discovery))
1923
+ return ['x.discovery: expected a map'];
1924
+ const requiredString = (value, path) => {
1925
+ if (typeof value !== 'string' || value.trim() === '') {
1926
+ issues.push(path + ': expected a non-empty string');
1927
+ return undefined;
1928
+ }
1929
+ return value;
1930
+ };
1931
+ const requiredPhraseList = (value, path) => {
1932
+ if (!Array.isArray(value) || value.length === 0) {
1933
+ issues.push(path + ': expected a non-empty array of non-empty strings');
1934
+ return;
1935
+ }
1936
+ for (const [index, item] of value.entries())
1937
+ requiredString(item, path + '[' + index + ']');
1938
+ };
1939
+ /**
1940
+ * Validate a mapping in the order its fields were authored. Required
1941
+ * fields absent from the mapping follow in the convention's fixed order,
1942
+ * making both kinds of diagnostic deterministic.
1943
+ */
1944
+ const visitMapFields = (value, allowed, path, visitKnownField) => {
1945
+ const allowedSet = new Set(allowed);
1946
+ const present = new Set();
1947
+ for (const key of Object.keys(value)) {
1948
+ if (!allowedSet.has(key)) {
1949
+ issues.push(path + '.' + key + ': unknown field');
1950
+ continue;
1951
+ }
1952
+ present.add(key);
1953
+ visitKnownField(key, value[key]);
1954
+ }
1955
+ for (const key of allowed)
1956
+ if (!present.has(key))
1957
+ visitKnownField(key, undefined);
1958
+ };
1959
+ const inputs = new Map(def.inputs.map((input) => [input.name, { schema: input.schema }]));
1960
+ const outputs = new Map((def.outputs ?? []).map((name) => {
1961
+ const artifact = def.steps.flatMap((step) => [...step.produces, ...(step.generates ?? [])])
1962
+ .find((produce) => produce.stem === name);
1963
+ return [name, { schema: artifact?.schema }];
1964
+ }));
1965
+ const validateInterfaceEntries = (value, path, declared) => {
1966
+ const fieldPath = 'x.discovery.interface.' + path;
1967
+ const singular = path === 'inputs' ? 'input' : 'output';
1968
+ if (!Array.isArray(value)) {
1969
+ issues.push(fieldPath + ': expected an array');
1970
+ return;
1971
+ }
1972
+ const seen = new Set();
1973
+ for (const [index, entry] of value.entries()) {
1974
+ const entryPath = fieldPath + '[' + index + ']';
1975
+ if (!isDiscoveryMap(entry)) {
1976
+ issues.push(entryPath + ': expected a map');
1977
+ continue;
1978
+ }
1979
+ visitMapFields(entry, ['name', 'summary', 'schemaRef'], entryPath, (key, fieldValue) => {
1980
+ switch (key) {
1981
+ case 'name': {
1982
+ const name = requiredString(fieldValue, entryPath + '.name');
1983
+ if (name === undefined)
1984
+ break;
1985
+ // Record every non-blank name before declaration lookup. This
1986
+ // preserves both useful findings for repeated unknown names.
1987
+ if (seen.has(name)) {
1988
+ issues.push(entryPath + '.name: duplicate workflow ' + singular + " '" + name + "'");
1989
+ }
1990
+ else {
1991
+ seen.add(name);
1992
+ }
1993
+ const artifact = declared.get(name);
1994
+ if (artifact === undefined) {
1995
+ issues.push(entryPath + '.name: unknown workflow ' + singular + " '" + name + "'");
1996
+ }
1997
+ else if (artifact.schema === undefined) {
1998
+ issues.push(entryPath + '.schemaRef: workflow ' + singular + " '" + name + "' has no schema");
1999
+ }
2000
+ break;
2001
+ }
2002
+ case 'summary':
2003
+ requiredString(fieldValue, entryPath + '.summary');
2004
+ break;
2005
+ case 'schemaRef': {
2006
+ const schemaRef = requiredString(fieldValue, entryPath + '.schemaRef');
2007
+ if (schemaRef !== undefined && !schemaRef.startsWith('#/')) {
2008
+ issues.push(entryPath + '.schemaRef: expected a local JSON pointer starting with \'#/\'');
2009
+ }
2010
+ break;
2011
+ }
2012
+ }
2013
+ });
2014
+ }
2015
+ for (const name of declared.keys()) {
2016
+ if (!seen.has(name))
2017
+ issues.push(fieldPath + ': missing workflow ' + singular + " '" + name + "'");
2018
+ }
2019
+ };
2020
+ const validateInterface = (value) => {
2021
+ if (!isDiscoveryMap(value)) {
2022
+ issues.push('x.discovery.interface: expected a map');
2023
+ return;
2024
+ }
2025
+ visitMapFields(value, ['inputs', 'outputs'], 'x.discovery.interface', (key, fieldValue) => {
2026
+ if (key === 'inputs')
2027
+ validateInterfaceEntries(fieldValue, 'inputs', inputs);
2028
+ else
2029
+ validateInterfaceEntries(fieldValue, 'outputs', outputs);
2030
+ });
2031
+ };
2032
+ visitMapFields(discovery, ['description', 'whenToUse', 'notFor', 'interface'], 'x.discovery', (key, value) => {
2033
+ switch (key) {
2034
+ case 'description':
2035
+ requiredString(value, 'x.discovery.description');
2036
+ break;
2037
+ case 'whenToUse':
2038
+ requiredPhraseList(value, 'x.discovery.whenToUse');
2039
+ break;
2040
+ case 'notFor':
2041
+ requiredPhraseList(value, 'x.discovery.notFor');
2042
+ break;
2043
+ case 'interface':
2044
+ validateInterface(value);
2045
+ break;
2046
+ }
2047
+ });
2048
+ return issues;
2049
+ }
1896
2050
  /**
1897
2051
  * Static lint over a workflow definition. Returns both the hard errors from
1898
2052
  * `validateDef` (which `parseDef` / `loadDefFile` would throw on) and
@@ -1906,7 +2060,7 @@ function unroutedCapabilityWarnings(def) {
1906
2060
  export function lintDef(def) {
1907
2061
  const errors = validateDef(def);
1908
2062
  const warnings = errors.length === 0
1909
- ? [...deadEndWarnings(def), ...danglingReduceSuffixWarnings(def), ...unroutedCapabilityWarnings(def)]
2063
+ ? [...deadEndWarnings(def), ...danglingReduceSuffixWarnings(def), ...unroutedCapabilityWarnings(def), ...discoveryIssues(def)]
1910
2064
  : [];
1911
2065
  return { errors, warnings };
1912
2066
  }
@@ -1982,49 +2136,195 @@ export function resolveCallsTarget(defs, target, from) {
1982
2136
  const key = resolveCallsTargetKey(defs, target, from);
1983
2137
  return key === undefined ? undefined : defs.get(key);
1984
2138
  }
1985
- // ---- M2-CYCLE: cross-def calls-cycle detection --------------------------------
2139
+ function buildCallsGraph(defs) {
2140
+ const keys = [...defs.keys()];
2141
+ const edges = new Map();
2142
+ for (const [key, def] of defs) {
2143
+ // WS-6: graph nodes are RESOLVED map keys, not bare calls text. Two bundles
2144
+ // may both export `build` without being fused into one graph node.
2145
+ const children = new Set();
2146
+ for (const step of def.steps) {
2147
+ if (step.calls === undefined)
2148
+ continue;
2149
+ const child = resolveCallsTargetKey(defs, step.calls, def);
2150
+ if (child !== undefined)
2151
+ children.add(child);
2152
+ }
2153
+ edges.set(key, [...children]);
2154
+ }
2155
+ return {
2156
+ keys,
2157
+ order: new Map(keys.map((key, index) => [key, index])),
2158
+ edges,
2159
+ };
2160
+ }
1986
2161
  /**
1987
- * Walk the calls: edges in a flat def map and throw a DefError if any cycle exists.
1988
- * This is the Mode 2 analogue of the Mode 1 include-cycle guard in expandIncludes.
1989
- * Note: include: and calls: are DIFFERENT edge kinds — they are checked separately.
1990
- *
1991
- * Called from loadDefs Phase 2 after all defs are expanded and per-def validated.
2162
+ * Preserve the original tri-color DFS exactly for strict loading. It stops at
2163
+ * the first back edge, so finalizeDefs remains O(V+E) and retains its stable
2164
+ * first-cycle message and traversal precedence.
1992
2165
  */
1993
- function detectCallsCycles(defs) {
2166
+ function findFirstCallsCycle(graph) {
1994
2167
  const WHITE = 0, GREY = 1, BLACK = 2;
1995
- const color = new Map([...defs.keys()].map((k) => [k, WHITE]));
2168
+ const color = new Map(graph.keys.map((key) => [key, WHITE]));
1996
2169
  const stack = [];
1997
- // WS-6: the walk must key on RESOLVED identity, not on the bare `calls:` text.
1998
- // Two installed bundles may each export a workflow named `build`; keying the
1999
- // walk by that bare text would fuse them into one node and report a cycle that
2000
- // does not exist. `resolveCallsTarget` maps (edge text, calling def) to the
2001
- // exact map key the engine will spawn, so each bundle's `build` stays its own
2002
- // node under its own qualified key.
2003
- const visit = (name) => {
2004
- color.set(name, GREY);
2005
- stack.push(name);
2006
- const def = defs.get(name);
2007
- // Unique calls: edges from this def (multiple steps might call the same child)
2008
- const callsEdges = new Set((def?.steps ?? []).filter((l) => l.calls).map((l) => l.calls));
2009
- for (const edge of callsEdges) {
2010
- const child = def === undefined ? undefined : resolveCallsTargetKey(defs, edge, def);
2011
- if (child === undefined)
2012
- continue; // missing-def error is reported separately in loadDefs
2013
- const c = color.get(child) ?? WHITE;
2014
- if (c === GREY) {
2015
- const from = stack.indexOf(child);
2016
- throw new DefError(`calls cycle: ${[...stack.slice(from), child].join(' -> ')}`);
2170
+ const visit = (key) => {
2171
+ color.set(key, GREY);
2172
+ stack.push(key);
2173
+ for (const child of graph.edges.get(key) ?? []) {
2174
+ const state = color.get(child) ?? WHITE;
2175
+ if (state === GREY)
2176
+ return [...stack.slice(stack.indexOf(child)), child];
2177
+ if (state === WHITE) {
2178
+ const found = visit(child);
2179
+ if (found !== undefined)
2180
+ return found;
2017
2181
  }
2018
- if (c === WHITE)
2019
- visit(child);
2020
2182
  }
2021
2183
  stack.pop();
2022
- color.set(name, BLACK);
2184
+ color.set(key, BLACK);
2185
+ return undefined;
2186
+ };
2187
+ for (const key of graph.keys) {
2188
+ if ((color.get(key) ?? WHITE) !== WHITE)
2189
+ continue;
2190
+ const found = visit(key);
2191
+ if (found !== undefined)
2192
+ return found;
2193
+ }
2194
+ return undefined;
2195
+ }
2196
+ function cycleFingerprint(cycle) {
2197
+ const members = cycle.slice(0, -1);
2198
+ return members
2199
+ .map((_, index) => [...members.slice(index), ...members.slice(0, index)].join('\u0000'))
2200
+ .sort()[0] ?? '';
2201
+ }
2202
+ function canonicalizeCycle(cycle, order) {
2203
+ const members = cycle.slice(0, -1);
2204
+ let first = 0;
2205
+ for (let index = 1; index < members.length; index++) {
2206
+ if ((order.get(members[index]) ?? Number.MAX_SAFE_INTEGER) < (order.get(members[first]) ?? Number.MAX_SAFE_INTEGER)) {
2207
+ first = index;
2208
+ }
2209
+ }
2210
+ const rotated = [...members.slice(first), ...members.slice(0, first)];
2211
+ return [...rotated, rotated[0]];
2212
+ }
2213
+ /** Return each cyclic SCC, indexed by every member, using deterministic Tarjan traversal. */
2214
+ function cyclicComponentsByMember(graph) {
2215
+ let nextIndex = 0;
2216
+ const index = new Map();
2217
+ const lowlink = new Map();
2218
+ const stack = [];
2219
+ const onStack = new Set();
2220
+ const byMember = new Map();
2221
+ const visit = (key) => {
2222
+ index.set(key, nextIndex);
2223
+ lowlink.set(key, nextIndex);
2224
+ nextIndex++;
2225
+ stack.push(key);
2226
+ onStack.add(key);
2227
+ for (const child of graph.edges.get(key) ?? []) {
2228
+ if (!index.has(child)) {
2229
+ visit(child);
2230
+ lowlink.set(key, Math.min(lowlink.get(key), lowlink.get(child)));
2231
+ }
2232
+ else if (onStack.has(child)) {
2233
+ lowlink.set(key, Math.min(lowlink.get(key), index.get(child)));
2234
+ }
2235
+ }
2236
+ if (lowlink.get(key) !== index.get(key))
2237
+ return;
2238
+ const members = [];
2239
+ while (stack.length > 0) {
2240
+ const member = stack.pop();
2241
+ onStack.delete(member);
2242
+ members.push(member);
2243
+ if (member === key)
2244
+ break;
2245
+ }
2246
+ const cyclic = members.length > 1 || (graph.edges.get(key) ?? []).includes(key);
2247
+ if (!cyclic)
2248
+ return;
2249
+ const component = new Set(members);
2250
+ for (const member of members)
2251
+ byMember.set(member, component);
2252
+ };
2253
+ for (const key of graph.keys) {
2254
+ if (!index.has(key))
2255
+ visit(key);
2256
+ }
2257
+ return byMember;
2258
+ }
2259
+ /** Find one deterministic simple cycle through member inside its cyclic SCC. */
2260
+ function cycleThroughMember(member, component, graph) {
2261
+ const pathBack = (key, target, path, seen) => {
2262
+ for (const child of graph.edges.get(key) ?? []) {
2263
+ if (!component.has(child))
2264
+ continue;
2265
+ if (child === target)
2266
+ return [...path, child];
2267
+ if (seen.has(child))
2268
+ continue;
2269
+ seen.add(child);
2270
+ const found = pathBack(child, target, [...path, child], seen);
2271
+ if (found !== undefined)
2272
+ return found;
2273
+ }
2274
+ return undefined;
2023
2275
  };
2024
- for (const name of defs.keys()) {
2025
- if ((color.get(name) ?? WHITE) === WHITE)
2026
- visit(name);
2276
+ for (const child of graph.edges.get(member) ?? []) {
2277
+ if (!component.has(child))
2278
+ continue;
2279
+ if (child === member)
2280
+ return [member, member];
2281
+ const found = pathBack(child, member, [child], new Set([member, child]));
2282
+ if (found !== undefined)
2283
+ return [member, ...found];
2027
2284
  }
2285
+ return undefined;
2286
+ }
2287
+ /**
2288
+ * Report calls cycles in a flat def map. This is the Mode 2 analogue of the
2289
+ * Mode 1 include-cycle guard in expandIncludes; the two edge kinds stay
2290
+ * deliberately separate. Findings use resolved map identity, not bare call
2291
+ * text, so CAS bundle siblings cannot be accidentally fused. The first finding
2292
+ * is strict loading's legacy DFS witness. Further findings add at most one
2293
+ * deterministic witness for each still-unattributed cyclic member, keeping
2294
+ * authoring attribution polynomial and every finding's members consistent with
2295
+ * its displayed path without enumerating exponentially many simple cycles.
2296
+ */
2297
+ export function reportCallsCycles(defs) {
2298
+ const graph = buildCallsGraph(defs);
2299
+ const first = findFirstCallsCycle(graph);
2300
+ if (first === undefined)
2301
+ return [];
2302
+ const cycles = [first];
2303
+ const seen = new Set([cycleFingerprint(first)]);
2304
+ const attributed = new Set(first.slice(0, -1));
2305
+ const components = cyclicComponentsByMember(graph);
2306
+ for (const member of graph.keys) {
2307
+ if (attributed.has(member))
2308
+ continue;
2309
+ const component = components.get(member);
2310
+ if (component === undefined)
2311
+ continue;
2312
+ const witness = cycleThroughMember(member, component, graph);
2313
+ if (witness === undefined)
2314
+ continue; // unreachable for a member of a cyclic SCC
2315
+ const cycle = canonicalizeCycle(witness, graph.order);
2316
+ for (const cycleMember of cycle.slice(0, -1))
2317
+ attributed.add(cycleMember);
2318
+ const fingerprint = cycleFingerprint(cycle);
2319
+ if (seen.has(fingerprint))
2320
+ continue;
2321
+ seen.add(fingerprint);
2322
+ cycles.push(cycle);
2323
+ }
2324
+ return cycles.map((cycle) => ({
2325
+ message: `calls cycle: ${cycle.join(' -> ')}`,
2326
+ members: cycle.slice(0, -1),
2327
+ }));
2028
2328
  }
2029
2329
  // ---- filesystem loading ------------------------------------------------------
2030
2330
  /** Load and validate a single workflow definition from a YAML file. */
@@ -2103,51 +2403,59 @@ export function loadDefsUnfinalized(dir) {
2103
2403
  }
2104
2404
  return raw;
2105
2405
  }
2406
+ /**
2407
+ * Return every direct cross-definition `calls:` error for one expanded
2408
+ * definition. Strict loading uses the first result to retain its historical
2409
+ * throw behavior; tolerant authoring commands can present the complete list.
2410
+ */
2411
+ export function validateCallsEdges(def, defs, options = {}) {
2412
+ const errors = [];
2413
+ for (const step of def.steps) {
2414
+ if (!step.calls)
2415
+ continue;
2416
+ const childDef = resolveCallsTarget(defs, step.calls, def);
2417
+ if (!childDef) {
2418
+ if (options.allowUnresolvedCalls !== true
2419
+ && options.allowUnresolvedVersionedCalls?.has(step.calls) !== true) {
2420
+ errors.push(`calls names workflow '${step.calls}' which does not exist`);
2421
+ }
2422
+ continue;
2423
+ }
2424
+ const childInputNames = new Set(childDef.inputs.map((input) => input.name));
2425
+ for (const key of Object.keys(step.callsInputs ?? {})) {
2426
+ if (!childInputNames.has(key)) {
2427
+ errors.push(`calls '${step.name}' maps input '${key}' which workflow '${step.calls}' does not declare`);
2428
+ }
2429
+ }
2430
+ const childOutputs = childDef.outputs ?? [];
2431
+ if (childOutputs.length === 0) {
2432
+ errors.push(`calls names workflow '${step.calls}' which declares no outputs:`);
2433
+ }
2434
+ if (childOutputs.length > 1) {
2435
+ errors.push(`calls names workflow '${step.calls}' which declares ${childOutputs.length} outputs:, calls: v1 requires exactly one`);
2436
+ }
2437
+ }
2438
+ return errors;
2439
+ }
2106
2440
  export function finalizeDefs(raw, options = {}) {
2107
2441
  const out = new Map();
2108
2442
  const resolver = (name) => raw.get(name);
2109
2443
  for (const [name, def] of raw) {
2110
2444
  const expanded = expandIncludes(def, resolver);
2111
- // M2-VALIDATE cross-def: target-def existence + child input-key validity.
2112
- // These cannot live in validateDef (pure per-def, no resolver) — same split as expandIncludes.
2113
- //
2114
- // WS-6: `calls:` targets resolve through `resolveCallsTarget` (scope-aware),
2115
- // NOT through the plain `resolver` used for `include:` expansion above.
2116
- // `include:` is a DIFFERENT edge kind and is deliberately left on the flat
2117
- // lookup — this workstream is `calls:`-only.
2118
- for (const l of expanded.steps) {
2119
- if (!l.calls)
2120
- continue;
2121
- const childDef = resolveCallsTarget(raw, l.calls, expanded);
2122
- if (!childDef) {
2123
- if (options.allowUnresolvedCalls === true
2124
- || options.allowUnresolvedVersionedCalls?.has(l.calls) === true)
2125
- continue;
2126
- throw new DefError(`calls names workflow '${l.calls}' which does not exist`);
2127
- }
2128
- const childInputNames = new Set(childDef.inputs.map((i) => i.name));
2129
- for (const k of Object.keys(l.callsInputs ?? {})) {
2130
- if (!childInputNames.has(k)) {
2131
- throw new DefError(`calls '${l.name}' maps input '${k}' which workflow '${l.calls}' does not declare`);
2132
- }
2133
- }
2134
- // M2B-OUTCOME v1: the called workflow must declare exactly one output.
2135
- const childOutputs = childDef.outputs ?? [];
2136
- if (childOutputs.length === 0) {
2137
- throw new DefError(`calls names workflow '${l.calls}' which declares no outputs:`);
2138
- }
2139
- if (childOutputs.length > 1) {
2140
- throw new DefError(`calls names workflow '${l.calls}' which declares ${childOutputs.length} outputs:, calls: v1 requires exactly one`);
2141
- }
2142
- }
2445
+ const callsErrors = validateCallsEdges(expanded, raw, options);
2446
+ if (callsErrors.length > 0)
2447
+ throw new DefError(callsErrors[0]);
2143
2448
  const errors = validateDef(expanded);
2144
2449
  if (errors.length) {
2145
2450
  throw new DefError(`invalid workflow '${name}' (${def.dir ?? 'unknown'}):\n - ${errors.join('\n - ')}`);
2146
2451
  }
2147
2452
  out.set(name, expanded);
2148
2453
  }
2149
- // M2-CYCLE: detect calls: cycles over the full expanded def map (after all per-def checks pass).
2150
- detectCallsCycles(out);
2454
+ // Preserve strict loading's first, stable cycle error after all per-def checks
2455
+ // without paying the wider authoring reporter's per-member attribution cost.
2456
+ const cycle = findFirstCallsCycle(buildCallsGraph(out));
2457
+ if (cycle !== undefined)
2458
+ throw new DefError(`calls cycle: ${cycle.join(' -> ')}`);
2151
2459
  return out;
2152
2460
  }
2153
2461
  /**
@@ -2159,7 +2467,7 @@ export function finalizeDefs(raw, options = {}) {
2159
2467
  * Two-phase: Phase 1 collects all defs. Phase 2 expands includes best-effort
2160
2468
  * (silently skips expansion failures so the lint caller sees un-expanded defs).
2161
2469
  */
2162
- export function loadDefsRaw(dir, failures) {
2470
+ export function scanDefsRaw(dir, failures) {
2163
2471
  // Phase 1: build all defs, skipping (and recording) malformed files.
2164
2472
  const raw = new Map();
2165
2473
  const tryAdd = (file) => {
@@ -2189,7 +2497,10 @@ export function loadDefsRaw(dir, failures) {
2189
2497
  tryAdd(full);
2190
2498
  }
2191
2499
  }
2192
- // Phase 2: expand includes best-effort; on failure keep the un-expanded def.
2500
+ return raw;
2501
+ }
2502
+ /** Best-effort include expansion for a complete, already-merged raw map. */
2503
+ export function expandDefsRaw(raw) {
2193
2504
  const out = new Map();
2194
2505
  const resolver = (name) => raw.get(name);
2195
2506
  for (const [name, def] of raw) {
@@ -2202,12 +2513,13 @@ export function loadDefsRaw(dir, failures) {
2202
2513
  out.set(name, def);
2203
2514
  }
2204
2515
  }
2205
- // M2-CYCLE: best-effort calls-cycle check so lint can surface cycle errors.
2206
- try {
2207
- detectCallsCycles(out);
2208
- }
2209
- catch {
2210
- // Cycle errors are surfaced via validateDef in the lint caller; swallow here.
2211
- }
2212
2516
  return out;
2213
2517
  }
2518
+ /**
2519
+ * Compatibility wrapper for tolerant single-directory loading. Raw loading
2520
+ * builds and expands includes best-effort; callers explicitly invoke shared
2521
+ * calls validation and cycle reporting against the complete definition map.
2522
+ */
2523
+ export function loadDefsRaw(dir, failures) {
2524
+ return expandDefsRaw(scanDefsRaw(dir, failures));
2525
+ }