@ancientpantheon/khronoton-core 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +8 -0
  3. package/dist/blockchain/stoachain.d.ts +1 -1
  4. package/dist/blockchain/stoachain.js +16 -1
  5. package/dist/{chunk-GIGLXIMC.js → chunk-A5YODPKQ.js} +820 -23
  6. package/dist/{chunk-KQZYMPZS.js → chunk-WKI52IPY.js} +1 -1
  7. package/dist/{context-CApk-LP4.d.ts → context-P-rCtBbJ.d.ts} +1 -1
  8. package/dist/handlers/execute.d.ts +12 -4
  9. package/dist/handlers/execute.js +42 -5
  10. package/dist/handlers/index.d.ts +2 -1
  11. package/dist/handlers/index.js +4 -1
  12. package/dist/handlers/read.d.ts +11 -0
  13. package/dist/handlers/read.js +65 -1
  14. package/dist/handlers/steps.d.ts +3 -0
  15. package/dist/handlers/steps.js +152 -0
  16. package/dist/hooks/index.d.ts +3 -3
  17. package/dist/hooks/index.js +2 -2
  18. package/dist/provider/index.d.ts +3 -3
  19. package/dist/provider/index.js +33 -2
  20. package/dist/{seams-DUtxDw_U.d.ts → seams-Co8Tq4ka.d.ts} +24 -0
  21. package/dist/server/executor.d.ts +14 -1
  22. package/dist/server/executor.js +144 -26
  23. package/dist/server/index.d.ts +12 -2
  24. package/dist/server/index.js +38 -1
  25. package/dist/server/loop.d.ts +17 -13
  26. package/dist/server/loop.js +19 -12
  27. package/dist/server/planners/evict.d.ts +20 -0
  28. package/dist/server/planners/evict.js +143 -0
  29. package/dist/server/planners/inject.d.ts +22 -0
  30. package/dist/server/planners/inject.js +120 -0
  31. package/dist/server/planners/registry.d.ts +118 -0
  32. package/dist/server/planners/registry.js +94 -0
  33. package/dist/server/planners/stoa-unwrap.d.ts +23 -0
  34. package/dist/server/planners/stoa-unwrap.js +204 -0
  35. package/dist/server/planners/stoa-wrap.d.ts +26 -0
  36. package/dist/server/planners/stoa-wrap.js +229 -0
  37. package/dist/server/planners/unstall.d.ts +25 -0
  38. package/dist/server/planners/unstall.js +135 -0
  39. package/dist/server/pure/run-advance.d.ts +76 -0
  40. package/dist/server/pure/run-advance.js +94 -0
  41. package/dist/server/pure/split-plan.d.ts +144 -0
  42. package/dist/server/pure/split-plan.js +362 -0
  43. package/dist/server/pure/yields.d.ts +57 -0
  44. package/dist/server/pure/yields.js +101 -0
  45. package/dist/server/resolvers.js +48 -6
  46. package/dist/server/runs-driver.d.ts +92 -0
  47. package/dist/server/runs-driver.js +582 -0
  48. package/dist/server/schema.d.ts +6 -2
  49. package/dist/server/schema.js +89 -1
  50. package/dist/server/seams.d.ts +28 -0
  51. package/dist/server/seams.js +4 -0
  52. package/dist/server/store/errors.d.ts +38 -0
  53. package/dist/server/store/errors.js +61 -0
  54. package/dist/server/store/index.d.ts +7 -2
  55. package/dist/server/store/index.js +8 -2
  56. package/dist/server/store/mappers.d.ts +11 -0
  57. package/dist/server/store/mappers.js +20 -0
  58. package/dist/server/store/runs.d.ts +233 -0
  59. package/dist/server/store/runs.js +341 -0
  60. package/dist/server/store/steps.d.ts +54 -0
  61. package/dist/server/store/steps.js +74 -0
  62. package/dist/server/store/yields.d.ts +46 -0
  63. package/dist/server/store/yields.js +73 -0
  64. package/dist/server/tick.d.ts +7 -0
  65. package/dist/server/tick.js +50 -1
  66. package/dist/server/types.d.ts +42 -3
  67. package/dist/ui/index.js +2 -2
  68. package/package.json +1 -1
@@ -77,21 +77,63 @@ export async function dispatchMultiTxResolver(name, opts) {
77
77
  function postponed(error) {
78
78
  return { ok: false, mode: "fire", error, terminalIntent: null };
79
79
  }
80
+ /**
81
+ * Coerce a batch's `ok` field (typed `unknown` — the orchestrator's return
82
+ * shape is consumer-defined, see `MultiTxResolver.run`'s own doc) to a real
83
+ * boolean, or `undefined` for "does not meaningfully report." A strict
84
+ * `typeof === "boolean"` check alone would silently treat a batch reporting
85
+ * failure via a non-boolean value (the string `"false"`, `0`) as "didn't
86
+ * report," defeating the whole point of honoring `ok` — but `Boolean(value)`
87
+ * alone is ALSO wrong here, because `Boolean("false")` is `true` (any
88
+ * non-empty string is truthy in JS). Recognized: real booleans, the
89
+ * case-insensitive strings `"true"`/`"false"`, and numbers (`0` is `false`,
90
+ * anything else `true`). Anything else (`null`, an object, an unrecognized
91
+ * string) is treated as "does not report," falling back to the pre-existing
92
+ * `ok`-less behavior for that one batch.
93
+ */
94
+ function toReportedOk(value) {
95
+ if (typeof value === "boolean")
96
+ return value;
97
+ if (typeof value === "number")
98
+ return value !== 0;
99
+ if (typeof value === "string") {
100
+ const lower = value.toLowerCase();
101
+ if (lower === "true")
102
+ return true;
103
+ if (lower === "false")
104
+ return false;
105
+ }
106
+ return undefined;
107
+ }
80
108
  /**
81
109
  * Adapt a multi-tx orchestrator's run summary to a {@link FireResult} so the tick
82
- * records one observable fire row for the run. A returned summary always means
83
- * the run COMPLETED (`ok:true`); the summary is stashed in `rawResult` and the
84
- * first batch's request key (when present) is surfaced so the fire row links to
85
- * the on-chain batch.
110
+ * records one observable fire row for the run. The summary is stashed in
111
+ * `rawResult` and the first batch's request key (when present) is surfaced so the
112
+ * fire row links to the on-chain batch.
113
+ *
114
+ * Strictly-additive, opt-in contract on `ok`: a batch that carries no
115
+ * meaningfully-reporting `ok` value behaves exactly as before — it's assumed
116
+ * to have completed, so a summary whose batches are all `ok`-less (or there
117
+ * are no batches at all) adapts to `ok:true`. A batch that DOES report `ok`
118
+ * (via {@link toReportedOk}) is honored: the adapted result is `ok:true`
119
+ * only if every reporting batch reports `true`; otherwise it's `ok:false`
120
+ * with a descriptive error naming how many of the reporting batches failed.
86
121
  */
87
122
  function adaptMultiTxSummary(summary) {
88
123
  const s = (summary ?? {});
89
- const firstBatchKey = Array.isArray(s.batches) && s.batches.length > 0 ? s.batches[0]?.requestKey : undefined;
124
+ const batches = Array.isArray(s.batches) ? s.batches : [];
125
+ const firstBatchKey = batches.length > 0 ? batches[0]?.requestKey : undefined;
126
+ const reported = batches
127
+ .map((b) => toReportedOk(b.ok))
128
+ .filter((v) => v !== undefined);
129
+ const ok = reported.length === 0 ? true : reported.every((v) => v === true);
130
+ const failedCount = reported.filter((v) => v === false).length;
90
131
  return {
91
- ok: true,
132
+ ok,
92
133
  mode: "fire",
93
134
  requestKey: firstBatchKey,
94
135
  rawResult: summary,
136
+ error: ok ? undefined : `${failedCount} of ${reported.length} reporting batch(es) failed`,
95
137
  terminalIntent: null,
96
138
  };
97
139
  }
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The non-blocking chained-run driver — executes Phase 2's pure `advanceRun`
3
+ * decision function against the real store/chain, per
4
+ * `docs/work/khronoton-chained-runs-phase-3/design.md` §D/§F.
5
+ *
6
+ * `driveRunOnce` is a SINGLE-RUN, loop-until-no-progress pass: it repeatedly
7
+ * (1) reads the run + its current step + that step's legs, (2) calls the pure
8
+ * `advanceRun` to decide what happens next, and (3) executes the returned
9
+ * `RunAction`s against the store/executor — re-reading fresh state and
10
+ * calling `advanceRun` again after every mutating action, stopping only once
11
+ * a pass makes NO further store write (a `poll` that landed nothing new, a
12
+ * `submit-leg` that failed, or the defensive `wait`), the run/step vanishes,
13
+ * or an action throws.
14
+ *
15
+ * This internal looping is deliberate, not incidental: `advanceRun` itself
16
+ * documents its own terminal-run check (step 1) as "defends against a driver
17
+ * that calls advanceRun on a run it should have already stopped touching" —
18
+ * i.e. the pure function already anticipates being re-invoked, within one
19
+ * driver pass, on a run this SAME pass just terminalized. It is also the only
20
+ * way to satisfy design.md §B's requirement that a freshly created run's step
21
+ * 0 gets "planned-and-submitted" — i.e. both `replan-step` (build leg 0) AND
22
+ * `submit-leg` (submit it) — within the SAME tick pass that created the run,
23
+ * rather than waiting a full `tickIntervalMs` for the next
24
+ * `advanceInFlightRunsOnce` pass to notice the freshly-built leg.
25
+ *
26
+ * `advanceInFlightRunsOnce` is the scheduler-facing sweep: every in-flight
27
+ * run, one `driveRunOnce` each, same per-row isolation posture
28
+ * `codexCronotonTickOnce` already applies (one run's failure never blocks the
29
+ * others).
30
+ *
31
+ * Deliberately does NOT import anything from `./tick.js` or `./loop.js` —
32
+ * both of those import FROM this module in a later wave of this same phase;
33
+ * importing `TickCtx` here instead of declaring the structurally-compatible
34
+ * `RunsDriverCtx` below would create a circular import.
35
+ */
36
+ import type { ChainRuntime, Config, Database, KeyResolver, OnAudit } from "./seams.js";
37
+ /**
38
+ * The injected context `driveRunOnce`/`advanceInFlightRunsOnce` run against —
39
+ * a structural SUBSET of `tick.ts`'s `TickCtx` (same `db`/`runtime`/
40
+ * `resolver`/`onAudit`/`config` shape, `TickCtx` just adds `resolveFireMode`
41
+ * on top), so a real `TickCtx` satisfies this interface already and needs no
42
+ * conversion at either of this phase's tick/loop call sites.
43
+ */
44
+ export interface RunsDriverCtx {
45
+ db: Database;
46
+ runtime: ChainRuntime;
47
+ resolver: KeyResolver;
48
+ onAudit: OnAudit;
49
+ config?: Partial<Config>;
50
+ }
51
+ /**
52
+ * Thrown by `driveRunOnce` when a `mode: 'planner'` step names a
53
+ * `planner_name` that `resolvePlannerFor` cannot resolve — e.g. a typo, or a
54
+ * planner that genuinely hasn't been registered yet. The `StepPlanner`
55
+ * registry itself (`planners/registry.ts`) and its real planners
56
+ * (`ouronet.aqp-evict`/`ouronet.aqp-inject`/`ouronet.aqp-unstall`) are fully
57
+ * built; this error reports an unresolved NAME against that registry, not a
58
+ * missing registry mechanism.
59
+ */
60
+ export declare class PlannerNotRegisteredError extends Error {
61
+ constructor(plannerName: string);
62
+ }
63
+ /**
64
+ * Drive one run forward as far as it will synchronously go this pass — see
65
+ * the module doc above for why this loops internally rather than making a
66
+ * single `advanceRun` call. Returns once the run/current step vanishes (both
67
+ * defensive no-ops) or a pass makes no further progress.
68
+ */
69
+ export declare function driveRunOnce(runId: string, now: Date, ctx: RunsDriverCtx): Promise<void>;
70
+ /** Result of one {@link advanceInFlightRunsOnce} sweep. */
71
+ export interface AdvanceRunsResult {
72
+ /** Run ids successfully driven (possibly a no-op pass) this sweep. */
73
+ drivenIds: string[];
74
+ /** Run ids whose `driveRunOnce` call threw — isolated, not re-thrown. */
75
+ erroredIds: string[];
76
+ }
77
+ /**
78
+ * Sweep every in-flight run, driving each forward one `driveRunOnce` pass.
79
+ * Per-run `try`/`catch` isolation — one run's thrown error (including
80
+ * `PlannerNotRegisteredError`) never blocks the others — mirrors
81
+ * `codexCronotonTickOnce`'s own per-row isolation posture.
82
+ *
83
+ * `excludeRunIds`, when given, skips those runs entirely this sweep. This
84
+ * exists so `loop.ts` can pass the run ids `codexCronotonTickOnce` already
85
+ * drove inline this SAME pass (design.md §B's "plan-and-submit step 0
86
+ * within one tick pass," built by calling `driveRunOnce` directly from the
87
+ * tick) — without it, a freshly created run would be driven twice in one
88
+ * loop callback: once inline by the tick, once again by this sweep moments
89
+ * later, doubling `pollRequestKeys` traffic for no benefit (the inline call
90
+ * already drove it as far as it would synchronously go).
91
+ */
92
+ export declare function advanceInFlightRunsOnce(now: Date, ctx: RunsDriverCtx, excludeRunIds?: ReadonlySet<string>): Promise<AdvanceRunsResult>;