@ancientpantheon/khronoton-core 0.11.0 → 0.13.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 (71) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +114 -0
  3. package/dist/blockchain/stoachain.d.ts +1 -1
  4. package/dist/blockchain/stoachain.js +16 -1
  5. package/dist/{chunk-LX6T2BDL.js → chunk-7H5TM3CS.js} +1 -1
  6. package/dist/{chunk-GNQ2IVXA.js → chunk-IAK4UEAA.js} +731 -24
  7. package/dist/{context-89YS4xT3.d.ts → context-P-rCtBbJ.d.ts} +2 -2
  8. package/dist/handlers/execute.d.ts +12 -4
  9. package/dist/handlers/execute.js +42 -5
  10. package/dist/handlers/index.d.ts +4 -2
  11. package/dist/handlers/index.js +7 -2
  12. package/dist/handlers/public.d.ts +41 -0
  13. package/dist/handlers/public.js +78 -0
  14. package/dist/handlers/read.d.ts +11 -0
  15. package/dist/handlers/read.js +65 -1
  16. package/dist/handlers/steps.d.ts +3 -0
  17. package/dist/handlers/steps.js +115 -0
  18. package/dist/hooks/index.d.ts +4 -4
  19. package/dist/hooks/index.js +2 -2
  20. package/dist/provider/index.d.ts +4 -4
  21. package/dist/provider/index.js +33 -2
  22. package/dist/{seams-DUtxDw_U.d.ts → seams-Co8Tq4ka.d.ts} +24 -0
  23. package/dist/server/executor.d.ts +14 -1
  24. package/dist/server/executor.js +144 -26
  25. package/dist/server/index.d.ts +11 -2
  26. package/dist/server/index.js +29 -1
  27. package/dist/server/loop.d.ts +17 -13
  28. package/dist/server/loop.js +19 -12
  29. package/dist/server/planners/evict.d.ts +20 -0
  30. package/dist/server/planners/evict.js +143 -0
  31. package/dist/server/planners/inject.d.ts +22 -0
  32. package/dist/server/planners/inject.js +120 -0
  33. package/dist/server/planners/registry.d.ts +80 -0
  34. package/dist/server/planners/registry.js +50 -0
  35. package/dist/server/planners/stoa-unwrap.d.ts +23 -0
  36. package/dist/server/planners/stoa-unwrap.js +204 -0
  37. package/dist/server/planners/stoa-wrap.d.ts +22 -0
  38. package/dist/server/planners/stoa-wrap.js +201 -0
  39. package/dist/server/planners/unstall.d.ts +25 -0
  40. package/dist/server/planners/unstall.js +135 -0
  41. package/dist/server/pure/run-advance.d.ts +76 -0
  42. package/dist/server/pure/run-advance.js +94 -0
  43. package/dist/server/pure/split-plan.d.ts +144 -0
  44. package/dist/server/pure/split-plan.js +362 -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 +511 -0
  48. package/dist/server/schema.d.ts +12 -2
  49. package/dist/server/schema.js +105 -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/fires.js +27 -1
  55. package/dist/server/store/index.d.ts +8 -2
  56. package/dist/server/store/index.js +8 -2
  57. package/dist/server/store/mappers.d.ts +11 -0
  58. package/dist/server/store/mappers.js +20 -0
  59. package/dist/server/store/public.d.ts +104 -0
  60. package/dist/server/store/public.js +197 -0
  61. package/dist/server/store/runs.d.ts +233 -0
  62. package/dist/server/store/runs.js +341 -0
  63. package/dist/server/store/steps.d.ts +42 -0
  64. package/dist/server/store/steps.js +51 -0
  65. package/dist/server/tick.d.ts +7 -0
  66. package/dist/server/tick.js +50 -1
  67. package/dist/server/types.d.ts +55 -3
  68. package/dist/{types-DnFB1Yz-.d.ts → types-uYSglFrJ.d.ts} +13 -0
  69. package/dist/ui/index.d.ts +1 -1
  70. package/dist/ui/index.js +2 -2
  71. package/package.json +1 -1
@@ -53,6 +53,13 @@ export interface CodexTickResult {
53
53
  failedIds: string[];
54
54
  /** Rows skipped without firing (lost claim, or an orchestration error). */
55
55
  skippedIds: string[];
56
+ /**
57
+ * Chained-run ids created AND driven inline this pass (design.md §B).
58
+ * `loop.ts` passes this as `advanceInFlightRunsOnce`'s `excludeRunIds` so
59
+ * the sweep pass a moment later doesn't re-drive — and re-poll — a run
60
+ * this same tick pass already drove as far as it would synchronously go.
61
+ */
62
+ drivenRunIds: string[];
56
63
  }
57
64
  /**
58
65
  * Select → claim → fire → record → finalize → audit for every due codex
@@ -39,6 +39,10 @@ import { fetchDueManualBatches, claimManualBatchFire, cancelManualBatch, } from
39
39
  import { getCodexCronoton } from "./store/cronoton.js";
40
40
  import { fireByServerResolver } from "./resolvers.js";
41
41
  import { TICK_BATCH_LIMIT } from "./seams.js";
42
+ import { createRun } from "./store/runs.js";
43
+ import { RunAlreadyInFlightError } from "./store/errors.js";
44
+ import { listStepsForCronoton } from "./store/steps.js";
45
+ import { driveRunOnce } from "./runs-driver.js";
42
46
  /**
43
47
  * One multi-tx `onTx` collector + the `FireTxKey[]` it fills, threaded into
44
48
  * {@link fireByServerResolver} so an INLINE multi-tx fire records the per-tx
@@ -68,6 +72,7 @@ export async function codexCronotonTickOnce(now, ctx) {
68
72
  const firedIds = [];
69
73
  const failedIds = [];
70
74
  const skippedIds = [];
75
+ const drivenRunIds = [];
71
76
  const due = fetchDueCodexCronotons(now, ctx.config?.tickBatchLimit ?? TICK_BATCH_LIMIT, {
72
77
  db: ctx.db,
73
78
  });
@@ -78,6 +83,50 @@ export async function codexCronotonTickOnce(now, ctx) {
78
83
  skippedIds.push(row.id);
79
84
  continue;
80
85
  }
86
+ // Chained (≥1 codex_cronoton_steps row) vs plain — design.md §A/§B. A
87
+ // chained row never reaches the one-shot fire path below: its lifecycle
88
+ // lives in codex_cronoton_runs/..._run_legs, not codex_cronoton_fires.
89
+ const steps = listStepsForCronoton(row.id, { db: ctx.db });
90
+ if (steps.length > 0) {
91
+ try {
92
+ const runId = createRun({ codexCronotonId: row.id, stepCount: steps.length }, { db: ctx.db });
93
+ // Drive the freshly created run forward synchronously in this SAME
94
+ // tick pass, so step 0's leg is built AND submitted without waiting
95
+ // a full tickIntervalMs for the next advanceInFlightRunsOnce pass.
96
+ await driveRunOnce(runId, now, ctx);
97
+ // onAudit before the firedIds/drivenRunIds pushes, mirroring the
98
+ // plain-fire path below: onAudit "may be sync or async" (seams.ts)
99
+ // and isn't guaranteed non-throwing — a throw here is caught by
100
+ // the outer per-row catch and lands row.id in skippedIds, so it
101
+ // must never ALSO already be in firedIds by that point.
102
+ await ctx.onAudit({
103
+ action: "codex_cronoton.run_started",
104
+ result: "success",
105
+ targetKind: "codex_cronoton",
106
+ targetId: row.id,
107
+ detail: {
108
+ codexCronotonId: row.id,
109
+ runId,
110
+ stepCount: steps.length,
111
+ actor: "scheduler",
112
+ },
113
+ });
114
+ firedIds.push(row.id);
115
+ drivenRunIds.push(runId);
116
+ }
117
+ catch (err) {
118
+ if (err instanceof RunAlreadyInFlightError) {
119
+ // Self-blocked: an existing non-terminal run for this cronoton is
120
+ // already being driven by advanceInFlightRunsOnce every pass —
121
+ // the claim already advanced next_fire_at regardless (§C).
122
+ skippedIds.push(row.id);
123
+ }
124
+ else {
125
+ throw err;
126
+ }
127
+ }
128
+ continue;
129
+ }
81
130
  const scheduleKind = row.schedule_mode === "one-time" ? "one-time" : "recurring";
82
131
  const definition = rowToDefinition(row);
83
132
  const { txKeys, deps: collectDeps } = makeTxKeyCollector();
@@ -140,7 +189,7 @@ export async function codexCronotonTickOnce(now, ctx) {
140
189
  skippedIds.push(row.id);
141
190
  }
142
191
  }
143
- return { firedIds, failedIds, skippedIds };
192
+ return { firedIds, failedIds, skippedIds, drivenRunIds };
144
193
  }
145
194
  /**
146
195
  * Process due manual-execution batches — the "Execute Now ×N" rail. For each
@@ -17,8 +17,14 @@ import type { ScheduleMode } from "../schedule.js";
17
17
  * chain dependency (the source Hub imported a concrete `ChainId`).
18
18
  */
19
19
  export type ChainId = string;
20
- /** Run mode: `simulate` signs + dirty-reads but never submits; `fire` submits. */
21
- export type ExecutorMode = "simulate" | "fire";
20
+ /**
21
+ * Run mode: `simulate` signs + dirty-reads but never submits; `fire` submits
22
+ * AND awaits confirmation (listen); `submit` submits but does NOT await
23
+ * confirmation — the caller polls it separately (see {@link SubmitResult}
24
+ * and `ChainClient.pollRequestKeys`), which is what lets a chained,
25
+ * multi-leg run avoid blocking the scheduler on a 5-minute listen per leg.
26
+ */
27
+ export type ExecutorMode = "simulate" | "fire" | "submit";
22
28
  /** One-time entries terminate after a single fire; recurring re-fire on schedule. */
23
29
  export type ScheduleKind = "one-time" | "recurring";
24
30
  /** Capability scoping for a signer: `pure` (unrestricted) or `scoped` (capped). */
@@ -121,7 +127,40 @@ export interface FireResult {
121
127
  /** Computed one-time terminal intent; `null` for recurring. */
122
128
  readonly terminalIntent: TerminalIntent | null;
123
129
  }
124
- export type ExecutorResult = SimulateResult | FireResult;
130
+ /**
131
+ * Result of a `submit` run. Builds, signs, pre-flights, and submits — never
132
+ * calls `listenWithTimeout`. `ok: true` with a `requestKey` means "submitted,"
133
+ * not "confirmed"; confirmation is a separate poll (Phase 3), not this result.
134
+ * No `terminalIntent`: submit never resolves a one-time row's terminal state.
135
+ *
136
+ * A SHARPER caveat than "not confirmed yet": `ok: true` is not even proof the
137
+ * transaction reached the chain. The shared build-through-submit helper
138
+ * (`executor.ts`'s `submitTransaction`) treats ANY throw from the chain
139
+ * client's submit call as the ambiguous "lost the HTTP response, but the node
140
+ * may have already accepted it" case (REQ-23) whenever a request key can be
141
+ * derived from the signed command — which is unconditional, since that key is
142
+ * just the signed command's own hash, computed before the network call ever
143
+ * happens. For `fire` mode this is safe because the subsequent `listen` call
144
+ * eventually distinguishes a genuine rejection from a real confirmation; for
145
+ * `submit` mode there is no such follow-up inside this call. A caller polling
146
+ * a `requestKey` this result returns must be prepared for it to never
147
+ * confirm — that is an expected outcome requiring a bounded deadline + re-plan
148
+ * or fail-the-run response (see the chained-runs design's §5.5/§5.7), not a
149
+ * bug to work around by re-submitting (re-submitting a leg that already has a
150
+ * request key is exactly the unsafe case the "never re-submit, only poll"
151
+ * invariant exists to forbid).
152
+ */
153
+ export interface SubmitResult {
154
+ readonly ok: boolean;
155
+ readonly mode: "submit";
156
+ readonly requestKey?: string;
157
+ readonly chainId?: string;
158
+ readonly networkId?: string;
159
+ /** The preflight read, present on a pre-submit failure. */
160
+ readonly rawResult?: unknown;
161
+ readonly error?: string;
162
+ }
163
+ export type ExecutorResult = SimulateResult | FireResult | SubmitResult;
125
164
  /** The raw `codex_cronotons` row shape (JSON columns are still strings here). */
126
165
  export interface CodexCronotonRow {
127
166
  id: string;
@@ -151,6 +190,19 @@ export interface CodexCronotonRow {
151
190
  * doubles (test fixtures) typecheck.
152
191
  */
153
192
  runtime_arg_keys?: string | null;
193
+ /**
194
+ * Stable, URL-safe public lookup token; null/absent until the row is first
195
+ * made observable. Optional so pre-migration row doubles (test fixtures)
196
+ * typecheck; real rows from `SELECT *` carry the column (value may be null).
197
+ */
198
+ public_token?: string | null;
199
+ /**
200
+ * When 1, this cronoton's sanitized state is readable via the public
201
+ * by-token endpoint, bypassing admin auth entirely. Optional so
202
+ * pre-migration row doubles (test fixtures) typecheck; real rows from
203
+ * `SELECT *` carry the column.
204
+ */
205
+ public_observable?: number;
154
206
  status: "active" | "paused" | "completed" | "error";
155
207
  next_fire_at: string | null;
156
208
  last_fire_at: string | null;
@@ -176,6 +176,19 @@ interface CodexCronotonRow {
176
176
  * doubles (test fixtures) typecheck.
177
177
  */
178
178
  runtime_arg_keys?: string | null;
179
+ /**
180
+ * Stable, URL-safe public lookup token; null/absent until the row is first
181
+ * made observable. Optional so pre-migration row doubles (test fixtures)
182
+ * typecheck; real rows from `SELECT *` carry the column (value may be null).
183
+ */
184
+ public_token?: string | null;
185
+ /**
186
+ * When 1, this cronoton's sanitized state is readable via the public
187
+ * by-token endpoint, bypassing admin auth entirely. Optional so
188
+ * pre-migration row doubles (test fixtures) typecheck; real rows from
189
+ * `SELECT *` carry the column.
190
+ */
191
+ public_observable?: number;
179
192
  status: "active" | "paused" | "completed" | "error";
180
193
  next_fire_at: string | null;
181
194
  last_fire_at: string | null;
@@ -1,5 +1,5 @@
1
1
  import { ReactNode } from 'react';
2
- import { a as CodexCronotonFireRow, C as CodexCronotonRow, f as CodexFireMode } from '../types-DnFB1Yz-.js';
2
+ import { a as CodexCronotonFireRow, C as CodexCronotonRow, f as CodexFireMode } from '../types-uYSglFrJ.js';
3
3
 
4
4
  /**
5
5
  * The theming boundary. Every Khronoton UI surface renders inside a
package/dist/ui/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { useCronotons, useCronoton, useCronotonActions, useExecuteNow, useSimulate, useServerResolvers, useManualBatch, useStartBatch, useCancelBatch, useTrigger, useCronotonFires, useRecoverFire } from '../chunk-LX6T2BDL.js';
2
- import { useKhronotonAdapter, useKhronotonConfig, parseRuntimeArgKeys, summariseSchedule, KhronotonStaticContext, useKhronoton, computeNextFire, InvalidScheduleConfigError } from '../chunk-GNQ2IVXA.js';
1
+ import { useCronotons, useCronoton, useCronotonActions, useExecuteNow, useSimulate, useServerResolvers, useManualBatch, useStartBatch, useCancelBatch, useTrigger, useCronotonFires, useRecoverFire } from '../chunk-7H5TM3CS.js';
2
+ import { useKhronotonAdapter, useKhronotonConfig, parseRuntimeArgKeys, summariseSchedule, KhronotonStaticContext, useKhronoton, computeNextFire, InvalidScheduleConfigError } from '../chunk-IAK4UEAA.js';
3
3
  import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
4
4
  import { lazy, forwardRef, createElement, useState, useEffect, useCallback, useMemo, Suspense, useContext } from 'react';
5
5
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ancientpantheon/khronoton-core",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "Headless framework-agnostic scheduler engine: pure schedule math plus an injectable tick engine. No database, no job queue, no framework — hosts inject storage and firing via hooks.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",