owenloop 0.3.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/model.js CHANGED
@@ -391,8 +391,14 @@ function idleEligible(step, arts, time) {
391
391
  * output to discharge. This is the scheduling gate (§11.4): necessary, not
392
392
  * sufficient; the commit fingerprint (§12.2) is the correctness boundary.
393
393
  * Assumes `pendingOwed` has already been materialized into `arts`.
394
+ *
395
+ * `opts.ignoreFreeze` (used by `modelCheck`'s stall-vs-true-deadlock
396
+ * recompute): when true, treat every `frozen()` guard as false — i.e.
397
+ * "what would be eligible if every maxAttempts/maxSchemaFailures/held brake
398
+ * were lifted (a human `retry` = unlimited attempts)". It ONLY lifts the
399
+ * freeze; group-exclusivity, input-green gates, and `isDebt` are untouched.
394
400
  */
395
- export function eligibleFirings(def, arts, time) {
401
+ export function eligibleFirings(def, arts, time, opts) {
396
402
  const firings = [];
397
403
  for (const step of def.steps) {
398
404
  // M2: calls: steps are machine-handled (the engine spawns the child); never emit a worker firing.
@@ -436,7 +442,7 @@ export function eligibleFirings(def, arts, time) {
436
442
  if (plainSatisfied) {
437
443
  const outs = plainOutputs(step).filter((p) => {
438
444
  const a = arts.get(p);
439
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
445
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
440
446
  });
441
447
  if (outs.length) {
442
448
  firings.push({ step: step.name, key: '', inputs: plainPaths, outputs: outs });
@@ -463,7 +469,9 @@ export function eligibleFirings(def, arts, time) {
463
469
  // never be a group member today — this check is defensive, not reachable,
464
470
  // and exists so a future relaxation of the singleton-only restriction can't
465
471
  // silently reopen the eligibility/commit-check gap this file fixes.
466
- if (!isDebt(outArt) || frozen(outArt, step) || groupBlockingWinner(def, arts, outPath) !== undefined)
472
+ if (!isDebt(outArt) ||
473
+ (!opts?.ignoreFreeze && frozen(outArt, step)) ||
474
+ groupBlockingWinner(def, arts, outPath) !== undefined)
467
475
  continue;
468
476
  firings.push({
469
477
  step: step.name,
@@ -494,7 +502,7 @@ export function eligibleFirings(def, arts, time) {
494
502
  .map((p) => p.stem)
495
503
  .filter((p) => {
496
504
  const a = arts.get(p);
497
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
505
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
498
506
  });
499
507
  if (outs.length) {
500
508
  firings.push({
@@ -519,7 +527,7 @@ export function eligibleFirings(def, arts, time) {
519
527
  // Workflow IS all-green. Check if the evaluator still has a debt to discharge.
520
528
  const outs = plainOutputs(step).filter((p) => {
521
529
  const a = arts.get(p);
522
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
530
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
523
531
  });
524
532
  if (outs.length > 0) {
525
533
  firings.push({
@@ -536,7 +544,7 @@ export function eligibleFirings(def, arts, time) {
536
544
  if (idleEligible(step, arts, time)) {
537
545
  const outs = plainOutputs(step).filter((p) => {
538
546
  const a = arts.get(p);
539
- return isDebt(a) && !frozen(a, step) && groupBlockingWinner(def, arts, p) === undefined;
547
+ return isDebt(a) && (opts?.ignoreFreeze || !frozen(a, step)) && groupBlockingWinner(def, arts, p) === undefined;
540
548
  });
541
549
  if (outs.length > 0) {
542
550
  firings.push({
@@ -561,6 +569,77 @@ function plainOutputs(step) {
561
569
  out.push(sealPath(p.stem));
562
570
  return out;
563
571
  }
572
+ /**
573
+ * Forward stem-reachability fixpoint from the seeded workflow inputs: a step's
574
+ * produced stems become reachable once every one of its consumed stems is
575
+ * reachable. Intentionally duplicates defs.ts's `reachabilityErrors` fixpoint
576
+ * rather than importing it — defs.ts does not import model.ts and model.ts
577
+ * does not import defs.ts; canEverFire's discharge-set logic (below) depends
578
+ * on model.ts's own mode helpers, so importing across the boundary either way
579
+ * would create a cycle. This local copy keeps the import graph acyclic.
580
+ */
581
+ function reachableStems(def) {
582
+ const reachable = new Set(def.inputs.map((i) => i.name));
583
+ let changed = true;
584
+ while (changed) {
585
+ changed = false;
586
+ for (const step of def.steps) {
587
+ if (!step.consumes.every((c) => reachable.has(c.stem)))
588
+ continue;
589
+ for (const p of step.produces) {
590
+ if (!reachable.has(p.stem)) {
591
+ reachable.add(p.stem);
592
+ changed = true;
593
+ }
594
+ }
595
+ }
596
+ }
597
+ return reachable;
598
+ }
599
+ /**
600
+ * Pure static predicate: can `step` EVER fire, under ANY search bounds?
601
+ *
602
+ * A SOUND detector of deadness: returns false ONLY when we are CERTAIN no
603
+ * firing can ever be pushed for this step, mirroring the discharge-set logic
604
+ * `eligibleFirings` (above) actually uses. When uncertain, returns true (the
605
+ * safe, non-failing default) — a false "structurally dead" would wrongly make
606
+ * `check` exit nonzero, so soundness is biased toward under-reporting.
607
+ *
608
+ * - Reachability: if any consumed stem is not reachable from the workflow
609
+ * inputs (see `reachableStems`), the step can never fire. Belt-and-suspenders
610
+ * — `validateDef`'s `reachabilityErrors` already turns this into a hard error
611
+ * before `modelCheck` ever runs, so this arm is defensive, not the live path.
612
+ * - Judge step (`step.judges`): fires against the judged stem, not a produces
613
+ * set; can-fire iff the judged stem is reachable (already implied by the
614
+ * reachability arm above, since a judge step consumes the judged stem — kept
615
+ * explicit for clarity and to stay correct if judge-step synthesis changes).
616
+ * - reduce: the discharge set is `singletonProduces(step)` only (see the
617
+ * reduce branch of `eligibleFirings`) — zero singleton produces means no
618
+ * firing is ever pushed, regardless of bounds.
619
+ * - map: needs both a map-consume and a map-produce to bind an element.
620
+ * - plain (inputsGreen / allGreen / idle): the discharge set is `plainOutputs`
621
+ * (singleton produces + collection seals) — empty means no firing ever.
622
+ *
623
+ * `reachable` may be precomputed once by the caller and passed in (modelCheck
624
+ * calls this per dead step and must not recompute the fixpoint each time).
625
+ */
626
+ export function canEverFire(step, def, reachable) {
627
+ const reach = reachable ?? reachableStems(def);
628
+ if (!step.consumes.every((c) => reach.has(c.stem)))
629
+ return false;
630
+ if (step.judges)
631
+ return reach.has(step.judges);
632
+ switch (stepMode(step)) {
633
+ case 'reduce':
634
+ return singletonProduces(step).length > 0;
635
+ case 'map':
636
+ return !!mapProduce(step) && !!mapConsume(step);
637
+ case 'plain':
638
+ return plainOutputs(step).length > 0;
639
+ default:
640
+ return true; // not certain of deadness — default to can-fire (soundness bias)
641
+ }
642
+ }
564
643
  // ---- level-triggered maintenance (§11.8, §12.3) -----------------------------
565
644
  /**
566
645
  * The standing guard: re-derive the invariant "an artifact is green only while
@@ -1525,6 +1604,9 @@ function seedArts(def, assumeProvided = false) {
1525
1604
  // seedOwed=false → seed green (version 1); seedOwed=true → seed owed (version 0)
1526
1605
  // The checker has no runtime `provide` values, so seedOwed inputs start owed —
1527
1606
  // unless assumeProvided, which models "the operator ran `provide` at create".
1607
+ // This function's own default stays false; the `owenloop check` CLI command
1608
+ // now passes assumeProvided: true by default (its `--strict-inputs` flag
1609
+ // passes false to restore this owed-start behavior) — see CheckOptions.
1528
1610
  const seedGreen = !input.seedOwed || assumeProvided;
1529
1611
  arts.set(input.name, {
1530
1612
  workflow: '',
@@ -1857,10 +1939,29 @@ function canonicalKey(def, arts) {
1857
1939
  * Bounded reachability / liveness checker over a workflow definition.
1858
1940
  *
1859
1941
  * Explores the full (or depth/state-bounded) state space via BFS to find:
1860
- * - deadlocks: reachable states that are not done and have no eligible firings
1861
- * - stuck states: reachable states with a stalled debt
1942
+ * - a non-done, zero-eligible-firings state is split into exactly ONE of two
1943
+ * mutually exclusive buckets by recomputing eligibility with every freeze
1944
+ * lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
1945
+ * - stall states: the recompute yields >= 1 firing — the state's only
1946
+ * blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
1947
+ * held). A by-design human-escalation brake. EXPECTED, never a defect.
1948
+ * - true deadlocks: the recompute STILL yields zero firings — a genuine
1949
+ * structural dead-end with no path to completion even at unlimited
1950
+ * attempts. A real defect.
1951
+ * - stuck states: reachable states that have a stalled debt but STILL have
1952
+ * >= 1 eligible firing elsewhere (a brake tripped on one branch while the
1953
+ * line moves on another). Informational only; a no-moves state is never
1954
+ * listed here — it lands in `stallStates` or `deadlocks` instead, so no
1955
+ * state is ever double-listed.
1862
1956
  * - completability: whether any reachable state is done (with an example path)
1863
- * - dead steps: steps whose name never appears as a firing in any explored transition
1957
+ * - dead steps: steps whose name never appears as a firing in any explored
1958
+ * transition. Split into two categories by the static `canEverFire` check
1959
+ * (independent of search bounds):
1960
+ * - structurally-dead: `canEverFire` is false — the step can NEVER fire
1961
+ * regardless of `--max-depth`/`--max-states`. A genuine wiring defect.
1962
+ * - unreached-within-bounds: `canEverFire` is true — the step CAN fire in
1963
+ * principle but the bounded search didn't reach it. A bounds artifact,
1964
+ * not a defect; raising `--max-states`/`--max-depth` may surface it.
1864
1965
  *
1865
1966
  * Pure — no store, no engine, no IO.
1866
1967
  */
@@ -1878,10 +1979,12 @@ export function modelCheck(def, opts = {}) {
1878
1979
  bounded: false,
1879
1980
  boundsHit: [],
1880
1981
  deadlocks: [],
1982
+ stallStates: [],
1881
1983
  stuck: [],
1882
1984
  completable: false,
1883
1985
  completePath: undefined,
1884
- deadSteps: [],
1986
+ structurallyDeadSteps: [],
1987
+ unreachedSteps: [],
1885
1988
  invariantViolations: [],
1886
1989
  stats: { statesExplored: 0, depthReached: 0 },
1887
1990
  };
@@ -1926,17 +2029,29 @@ export function modelCheck(def, opts = {}) {
1926
2029
  }
1927
2030
  continue; // done states have no successors
1928
2031
  }
1929
- // Check stuck (any debt.stalled)
1930
- if (status.debts.some((d) => d.stalled)) {
1931
- report.stuck.push({ path: node.path });
1932
- // continue exploring (there may be other paths)
1933
- }
1934
2032
  const firings = status.eligible;
1935
- // Check deadlock: non-done, no eligible firings
2033
+ // Non-done state with no eligible firings: classify by recomputing eligibility
2034
+ // as if every freeze/stall were lifted (unlimited attempts). If a producer
2035
+ // would re-arm → an EXPECTED stall state (a by-design brake). If not → a
2036
+ // TRUE deadlock (a structural dead-end with no path to completion even at
2037
+ // unlimited attempts).
1936
2038
  if (firings.length === 0 && !status.done) {
1937
- report.deadlocks.push({ path: node.path });
2039
+ const lifted = eligibleFirings(def, node.arts, undefined, { ignoreFreeze: true });
2040
+ if (lifted.length > 0) {
2041
+ report.stallStates.push({ path: node.path });
2042
+ }
2043
+ else {
2044
+ report.deadlocks.push({ path: node.path });
2045
+ }
1938
2046
  continue;
1939
2047
  }
2048
+ // The state HAS eligible firings (the line can still move). If a brake tripped
2049
+ // on some *other* branch, record it as an informational stuck state. A no-moves
2050
+ // stall state never reaches here (it `continue`d above), so no state is ever
2051
+ // listed in both `stuck` and `stallStates`/`deadlocks`.
2052
+ if (status.debts.some((d) => d.stalled)) {
2053
+ report.stuck.push({ path: node.path });
2054
+ }
1940
2055
  // Respect maxDepth
1941
2056
  if (node.depth >= maxDepth) {
1942
2057
  boundsHit.add('maxDepth');
@@ -1970,9 +2085,21 @@ export function modelCheck(def, opts = {}) {
1970
2085
  report.stats.depthReached = depthReached;
1971
2086
  report.boundsHit = [...boundsHit];
1972
2087
  report.bounded = boundsHit.size > 0;
1973
- // Dead steps: steps in the def that never appeared as a firing.step
1974
- report.deadSteps = def.steps
1975
- .filter((l) => !firedSteps.has(l.name))
1976
- .map((l) => l.name);
2088
+ // Dead steps: steps in the def that never appeared as a firing.step, split
2089
+ // by the static canEverFire check into structurally-dead (a real wiring
2090
+ // defect — can never fire regardless of bounds) vs unreached-within-bounds
2091
+ // (can fire in principle; the bounded search just didn't reach it).
2092
+ // Compute the reachability fixpoint once, not per dead step.
2093
+ const reachable = reachableStems(def);
2094
+ for (const l of def.steps) {
2095
+ if (firedSteps.has(l.name))
2096
+ continue;
2097
+ if (canEverFire(l, def, reachable)) {
2098
+ report.unreachedSteps.push(l.name);
2099
+ }
2100
+ else {
2101
+ report.structurallyDeadSteps.push(l.name);
2102
+ }
2103
+ }
1977
2104
  return report;
1978
2105
  }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * owenwork settings file writer — the ONE place the owenloop CLI writes into a
3
+ * sibling tool's config.
4
+ *
5
+ * `owenwork` (the wiring that runs orders) reads its settings from
6
+ * `$XDG_CONFIG_HOME/owenwork/settings.json` (else `$HOME/.config/owenwork/
7
+ * settings.json`) and, by design, NEVER writes them — the owenloop CLI's `setup`
8
+ * command is the writer, so a fresh `owenloop setup` can point owenwork at the
9
+ * hub it just authenticated against.
10
+ *
11
+ * This module writes exactly ONE key — `hubOrigin` — and preserves every other
12
+ * key byte-for-byte (forward-compat with owenwork's own `cacheDir`, `agentsDir`,
13
+ * `stateDir`, `dispatchCap`, `commandRouting`, and any future/unknown key). It
14
+ * never writes a secret: nothing secret is in scope here by construction (the
15
+ * hub ORIGIN is public).
16
+ *
17
+ * Corrupt-file policy: a settings file that exists but does not parse as a JSON
18
+ * OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
19
+ * it cannot safely merge into. That mirrors owenwork's own validator wording
20
+ * family ("not an object").
21
+ *
22
+ * Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
23
+ * util.ts — no CLI/engine closure.
24
+ */
25
+ /**
26
+ * The owenwork settings file path for this environment. `XDG_CONFIG_HOME` (when
27
+ * set and non-blank) wins over `HOME`, matching owenwork's own resolution and
28
+ * the owenloop credential store's `configDir`. Throws when neither is set.
29
+ */
30
+ export declare function owenworkSettingsPath(env: Record<string, string | undefined>): string;
31
+ /**
32
+ * Read and parse the owenwork settings file at `path`.
33
+ *
34
+ * - Missing file → `null` (an absent settings file is not an error; the writer
35
+ * creates one).
36
+ * - Present and parses to a JSON OBJECT → that object (a `Record`).
37
+ * - Present but not valid JSON, or valid JSON that is NOT an object (an array,
38
+ * `null`, a number, a string) → a hard `CliError` naming the path. The writer
39
+ * must never clobber a file it cannot merge into.
40
+ */
41
+ export declare function readOwenworkSettingsRaw(path: string): Record<string, unknown> | null;
42
+ /** The outcome of a `writeOwenworkHubOrigin` call — the path written and the
43
+ * previous `hubOrigin` value (`undefined` when the key was absent or the file
44
+ * did not exist), so a caller can report an old→new transition. */
45
+ export interface OwenworkWriteResult {
46
+ path: string;
47
+ previous: string | undefined;
48
+ }
49
+ /**
50
+ * Set ONLY the `hubOrigin` key in the owenwork settings file to `origin`,
51
+ * preserving every other key. Read the existing file (a parse failure is a hard
52
+ * `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
53
+ * directory, and write atomically (temp + rename via `writeFileAtomic`). The
54
+ * file is pretty-printed with a trailing newline. Returns the path and the
55
+ * previous `hubOrigin` (if any).
56
+ */
57
+ export declare function writeOwenworkHubOrigin(env: Record<string, string | undefined>, origin: string): OwenworkWriteResult;
@@ -0,0 +1,84 @@
1
+ /**
2
+ * owenwork settings file writer — the ONE place the owenloop CLI writes into a
3
+ * sibling tool's config.
4
+ *
5
+ * `owenwork` (the wiring that runs orders) reads its settings from
6
+ * `$XDG_CONFIG_HOME/owenwork/settings.json` (else `$HOME/.config/owenwork/
7
+ * settings.json`) and, by design, NEVER writes them — the owenloop CLI's `setup`
8
+ * command is the writer, so a fresh `owenloop setup` can point owenwork at the
9
+ * hub it just authenticated against.
10
+ *
11
+ * This module writes exactly ONE key — `hubOrigin` — and preserves every other
12
+ * key byte-for-byte (forward-compat with owenwork's own `cacheDir`, `agentsDir`,
13
+ * `stateDir`, `dispatchCap`, `commandRouting`, and any future/unknown key). It
14
+ * never writes a secret: nothing secret is in scope here by construction (the
15
+ * hub ORIGIN is public).
16
+ *
17
+ * Corrupt-file policy: a settings file that exists but does not parse as a JSON
18
+ * OBJECT is a hard error naming the path — the writer refuses to CLOBBER a file
19
+ * it cannot safely merge into. That mirrors owenwork's own validator wording
20
+ * family ("not an object").
21
+ *
22
+ * Imports only node builtins, `writeFileAtomic` from hub.ts, and `CliError` from
23
+ * util.ts — no CLI/engine closure.
24
+ */
25
+ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
26
+ import { dirname, join } from 'node:path';
27
+ import { writeFileAtomic } from "./hub.js";
28
+ import { CliError } from "./util.js";
29
+ /**
30
+ * The owenwork settings file path for this environment. `XDG_CONFIG_HOME` (when
31
+ * set and non-blank) wins over `HOME`, matching owenwork's own resolution and
32
+ * the owenloop credential store's `configDir`. Throws when neither is set.
33
+ */
34
+ export function owenworkSettingsPath(env) {
35
+ const xdg = env.XDG_CONFIG_HOME;
36
+ if (xdg && xdg.trim() !== '')
37
+ return join(xdg, 'owenwork', 'settings.json');
38
+ const home = env.HOME;
39
+ if (home && home.trim() !== '')
40
+ return join(home, '.config', 'owenwork', 'settings.json');
41
+ throw new CliError('cannot locate a config directory for owenwork settings: set HOME or XDG_CONFIG_HOME');
42
+ }
43
+ /**
44
+ * Read and parse the owenwork settings file at `path`.
45
+ *
46
+ * - Missing file → `null` (an absent settings file is not an error; the writer
47
+ * creates one).
48
+ * - Present and parses to a JSON OBJECT → that object (a `Record`).
49
+ * - Present but not valid JSON, or valid JSON that is NOT an object (an array,
50
+ * `null`, a number, a string) → a hard `CliError` naming the path. The writer
51
+ * must never clobber a file it cannot merge into.
52
+ */
53
+ export function readOwenworkSettingsRaw(path) {
54
+ if (!existsSync(path))
55
+ return null;
56
+ let parsed;
57
+ try {
58
+ parsed = JSON.parse(readFileSync(path, 'utf8'));
59
+ }
60
+ catch {
61
+ throw new CliError(`owenwork settings file at ${path} is not valid JSON — fix or remove it before running setup`);
62
+ }
63
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
64
+ throw new CliError(`owenwork settings file at ${path} is not a JSON object — fix or remove it before running setup`);
65
+ }
66
+ return parsed;
67
+ }
68
+ /**
69
+ * Set ONLY the `hubOrigin` key in the owenwork settings file to `origin`,
70
+ * preserving every other key. Read the existing file (a parse failure is a hard
71
+ * `CliError` — never clobber), spread it, overwrite `hubOrigin`, `mkdir -p` the
72
+ * directory, and write atomically (temp + rename via `writeFileAtomic`). The
73
+ * file is pretty-printed with a trailing newline. Returns the path and the
74
+ * previous `hubOrigin` (if any).
75
+ */
76
+ export function writeOwenworkHubOrigin(env, origin) {
77
+ const path = owenworkSettingsPath(env);
78
+ const existing = readOwenworkSettingsRaw(path);
79
+ const previous = existing !== undefined && existing !== null && typeof existing.hubOrigin === 'string' ? existing.hubOrigin : undefined;
80
+ const merged = { ...(existing ?? {}), hubOrigin: origin };
81
+ mkdirSync(dirname(path), { recursive: true });
82
+ writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`);
83
+ return { path, previous };
84
+ }
package/dist/types.d.ts CHANGED
@@ -556,7 +556,12 @@ export interface CheckOptions {
556
556
  * Seed `seedOwed: true` inputs green, as if `provide` already ran. The checker
557
557
  * has no runtime provide values, so without this every seedOwed input starts
558
558
  * owed with no transition that can green it — a def whose inputs the operator
559
- * supplies at create time reports a false depth-0 deadlock. Default false.
559
+ * supplies at create time reports a false depth-0 deadlock. Default (this
560
+ * field, when calling `modelCheck` directly) is false — that library default
561
+ * is unchanged. The `owenloop check` CLI command, however, now defaults this
562
+ * to true (seedOwed inputs are assumed provided by default, modeling the
563
+ * operator's `provide` at create); its `--strict-inputs` flag opts back out
564
+ * to false, restoring the seedOwed-starts-owed behavior described above.
560
565
  */
561
566
  assumeProvided?: boolean;
562
567
  }
@@ -567,18 +572,55 @@ export interface CheckReport {
567
572
  bounded: boolean;
568
573
  /** Which bounds were hit, for honest reporting. */
569
574
  boundsHit: ('maxDepth' | 'maxStates')[];
570
- /** Reachable states where done=false and eligibleFirings=[]: a genuine deadlock. */
575
+ /**
576
+ * Reachable non-done states with zero eligible firings that have NO path to
577
+ * completion even at unlimited attempts — i.e. recomputing eligibility with
578
+ * all freezes lifted (a human `retry` = unlimited attempts) STILL yields
579
+ * zero firings. A genuine structural dead-end (TRUE deadlock). A definite
580
+ * defect only when the search was exhaustive (`!bounded`) — the
581
+ * maxCollectionSize cap can otherwise manufacture a spurious no-moves
582
+ * state. Always present ([] when none).
583
+ */
571
584
  deadlocks: CheckFinding[];
572
- /** Reachable states that have a stalled debt (judgmentRejects >= cap). */
585
+ /**
586
+ * Reachable non-done states with zero eligible firings whose ONLY blocker
587
+ * is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held).
588
+ * Recomputing eligibility with all freezes lifted (a human `retry` =
589
+ * unlimited attempts) yields >= 1 firing, so a producer would re-arm and
590
+ * the line could move. These are the DESIGNED human-escalation brakes —
591
+ * EXPECTED, never a defect; they do not affect the exit code. Always
592
+ * present ([] when none).
593
+ */
594
+ stallStates: CheckFinding[];
595
+ /**
596
+ * Reachable states that have a stalled debt (maxAttempts/maxSchemaFailures/
597
+ * held) BUT still have >= 1 eligible firing — a brake tripped on one branch
598
+ * while the line can still move on another. Informational; NOT a defect on
599
+ * its own. A no-moves state whose only blocker is a frozen debt is recorded
600
+ * under `stallStates` instead, never here — so no state appears in both
601
+ * `stuck` and `stallStates`/`deadlocks`.
602
+ */
573
603
  stuck: CheckFinding[];
574
604
  /** Whether any explored state is done, and (when true) one example path to it. */
575
605
  completable: boolean;
576
606
  completePath?: CheckStep[];
577
607
  /**
578
- * Step names that never appear as the firing step in any explored transition
579
- * (dynamically dead within the bounded search).
608
+ * Step names that never appear as the firing step in any explored transition,
609
+ * AND a static "can this step ever fire?" check (independent of bounds) is
610
+ * CERTAIN no firing can ever be pushed for it (see model.ts `canEverFire`).
611
+ * A genuine wiring defect — always present ([] when none), and (unlike
612
+ * `unreachedSteps`) ALWAYS a definite finding regardless of `bounded`,
613
+ * because the check needs no search bounds to be certain.
614
+ */
615
+ structurallyDeadSteps: string[];
616
+ /**
617
+ * Step names that never appear as the firing step in any explored transition,
618
+ * but the static `canEverFire` check says they COULD fire in principle — the
619
+ * bounded search just didn't reach them before exhausting `--max-states`/
620
+ * `--max-depth`. Informational only, NOT a defect: a bounds artifact. Raising
621
+ * the search bounds may make the step fire. Always present ([] when none).
580
622
  */
581
- deadSteps: string[];
623
+ unreachedSteps: string[];
582
624
  /**
583
625
  * Invariants that are violated in some reachable state. Always present ([]
584
626
  * when no invariants declared or none violated). Each entry is deduplicated by
package/dist/util.d.ts CHANGED
@@ -1,4 +1,28 @@
1
1
  /** Small dependency-light helpers. */
2
+ /**
3
+ * A user-facing CLI/library error whose `message` is printed as-is (no stack
4
+ * trace) — the "expected, explained" failure class, distinct from a programming
5
+ * bug. Homed here in `util.ts` (which has no project-internal imports) so it can
6
+ * be shared by `cli.ts` (where `RateLimitError extends CliError`) and
7
+ * `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
8
+ * cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
9
+ * NOT re-exported from the package barrel (`src/index.ts`): it was module-private
10
+ * before, and the credential-write PR does not widen the public API beyond the
11
+ * functions the proposal names.
12
+ *
13
+ * `exitCode` lets a specific failure map to a distinct process exit status
14
+ * (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
15
+ * every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
16
+ * which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
17
+ * non-default codes today are `agent new`'s exit 2 (hub unresolvable) and exit 3
18
+ * (human credential absent/irrecoverable).
19
+ */
20
+ export declare class CliError extends Error {
21
+ readonly exitCode: number;
22
+ constructor(message: string, opts?: {
23
+ exitCode?: number;
24
+ });
25
+ }
2
26
  /**
3
27
  * `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
4
28
  * create it through a symlinked component (SEC-3, parent-directory half).
package/dist/util.js CHANGED
@@ -1,6 +1,31 @@
1
1
  /** Small dependency-light helpers. */
2
2
  import { createHash, randomBytes } from 'node:crypto';
3
3
  import { lstatSync, mkdirSync } from 'node:fs';
4
+ /**
5
+ * A user-facing CLI/library error whose `message` is printed as-is (no stack
6
+ * trace) — the "expected, explained" failure class, distinct from a programming
7
+ * bug. Homed here in `util.ts` (which has no project-internal imports) so it can
8
+ * be shared by `cli.ts` (where `RateLimitError extends CliError`) and
9
+ * `credentials.ts` (which must throw it without importing `cli.ts`, avoiding a
10
+ * cycle and keeping the library barrel from ever loading `cli.ts`). Deliberately
11
+ * NOT re-exported from the package barrel (`src/index.ts`): it was module-private
12
+ * before, and the credential-write PR does not widen the public API beyond the
13
+ * functions the proposal names.
14
+ *
15
+ * `exitCode` lets a specific failure map to a distinct process exit status
16
+ * (consumed by both entry-point catches in `cli.ts`). It defaults to `1`, so
17
+ * every existing `new CliError(msg)` — and `RateLimitError extends CliError`,
18
+ * which inherits this constructor — keeps its byte-for-byte exit-1 behavior. The
19
+ * non-default codes today are `agent new`'s exit 2 (hub unresolvable) and exit 3
20
+ * (human credential absent/irrecoverable).
21
+ */
22
+ export class CliError extends Error {
23
+ exitCode;
24
+ constructor(message, opts) {
25
+ super(message);
26
+ this.exitCode = opts?.exitCode ?? 1;
27
+ }
28
+ }
4
29
  /**
5
30
  * `mkdir -p` for a project-state directory (e.g. `.owenloop`), refusing to
6
31
  * create it through a symlinked component (SEC-3, parent-directory half).
package/docs/authoring.md CHANGED
@@ -441,6 +441,11 @@ By default a step fires when its consumed inputs are all green (`inputsGreen`).
441
441
  # order.cause is 'allGreen' when done, 'idle' when stuck past 30m
442
442
  ```
443
443
 
444
+ An `allGreen`/`idle` step must not also declare `consumes:` — both firing kinds
445
+ carry an empty input fingerprint, so a commit can never satisfy it, and
446
+ `owenloop lint` hard-errors on it. Declare the step's output under
447
+ `produces:`/`generates:` only.
448
+
444
449
  **Alarms.** A worker that needs a heartbeat or a deadline can call
445
450
  `engine.setAlarm(workflow, step, at)` with an absolute timestamp — it overrides the
446
451
  relative `idleAfter` window and survives a process restart.
@@ -460,6 +465,10 @@ relative `idleAfter` window and survives a process restart.
460
465
  A step consumes in exactly one mode — plain, a single map, or a single reduce. The
461
466
  validator enforces this at load time, so you don't hit it as a runtime surprise.
462
467
 
468
+ A reduce step needs at least one singleton produce (via `produces:` or `generates:`)
469
+ to discharge into — reducing into collection produces only leaves nothing for the
470
+ step to fire, and `owenloop lint` hard-errors on it.
471
+
463
472
  Collections add fan-out/fan-in on top of the base grammar: a step emits N
464
473
  items, a `map` runs once per item, a `reduce` runs once they're all in, and a
465
474
  suffixed reduce (`src[*].child`) can fan in on a map's per-element output