@ancientpantheon/khronoton-core 0.13.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.
- package/CHANGELOG.md +15 -0
- package/README.md +4 -0
- package/dist/{chunk-IAK4UEAA.js → chunk-A5YODPKQ.js} +123 -13
- package/dist/{chunk-7H5TM3CS.js → chunk-WKI52IPY.js} +1 -1
- package/dist/handlers/steps.js +51 -14
- package/dist/hooks/index.js +2 -2
- package/dist/provider/index.js +2 -2
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +9 -0
- package/dist/server/planners/registry.d.ts +41 -3
- package/dist/server/planners/registry.js +49 -5
- package/dist/server/planners/stoa-wrap.d.ts +11 -7
- package/dist/server/planners/stoa-wrap.js +61 -33
- package/dist/server/pure/yields.d.ts +57 -0
- package/dist/server/pure/yields.js +101 -0
- package/dist/server/runs-driver.js +89 -18
- package/dist/server/schema.d.ts +4 -3
- package/dist/server/schema.js +17 -1
- package/dist/server/store/index.d.ts +2 -1
- package/dist/server/store/index.js +3 -1
- package/dist/server/store/steps.d.ts +12 -0
- package/dist/server/store/steps.js +26 -3
- package/dist/server/store/yields.d.ts +46 -0
- package/dist/server/store/yields.js +73 -0
- package/dist/ui/index.js +2 -2
- package/package.json +1 -1
|
@@ -34,6 +34,8 @@ export { computeDefinitionFingerprint } from "../pure/fingerprint.js";
|
|
|
34
34
|
// ── Public observability: token toggle, by-token read, counts, health, projector ──
|
|
35
35
|
export { getCodexCronotonByPublicToken, setPublicObservable, getCronotonFireCounts, deriveCronotonHealth, toPublicCronotonView, } from "./public.js";
|
|
36
36
|
// ── Chained-run step definitions: insert / list ──────────────────────────────
|
|
37
|
-
export { insertStep, listStepsForCronoton } from "./steps.js";
|
|
37
|
+
export { insertStep, listStepsForCronoton, getStepByIndex } from "./steps.js";
|
|
38
38
|
// ── Chained runs + legs: create / read / leg lifecycle ────────────────────────
|
|
39
39
|
export { createRun, getRun, listRunLegs, listRunsForCronoton, insertRunLeg, claimLegForSubmit, releaseLegClaim, markLegSubmitted, markLegConfirmed, markLegFailed, listInFlightRuns, advanceRunStep, markRunTerminal, bumpRunAttempt, touchRunDeadline, } from "./runs.js";
|
|
40
|
+
// ── Step-to-step yield carry: upsert / read the per-run named-yield pool ─────
|
|
41
|
+
export { upsertYield, getYieldPool } from "./yields.js";
|
|
@@ -11,6 +11,7 @@ export interface InsertStepInput {
|
|
|
11
11
|
plannerName?: string;
|
|
12
12
|
plannerParams?: unknown;
|
|
13
13
|
idempotent?: boolean;
|
|
14
|
+
yieldAs?: string;
|
|
14
15
|
}
|
|
15
16
|
export interface CodexCronotonStepRow {
|
|
16
17
|
id: string;
|
|
@@ -27,6 +28,7 @@ export interface CodexCronotonStepRow {
|
|
|
27
28
|
idempotent: number;
|
|
28
29
|
created_at: string;
|
|
29
30
|
modified_at: string;
|
|
31
|
+
yield_as: string | null;
|
|
30
32
|
}
|
|
31
33
|
/**
|
|
32
34
|
* Insert one step row. Returns the new row's id.
|
|
@@ -40,3 +42,13 @@ export interface CodexCronotonStepRow {
|
|
|
40
42
|
export declare function insertStep(input: InsertStepInput, dep: DbDep): string;
|
|
41
43
|
/** Full raw snake_case rows for a cronoton's steps, ordered by step_index ASC. */
|
|
42
44
|
export declare function listStepsForCronoton(codexCronotonId: string, dep: DbDep): CodexCronotonStepRow[];
|
|
45
|
+
/**
|
|
46
|
+
* One step row at a specific `(codexCronotonId, stepIndex)` slot, or `null`.
|
|
47
|
+
* A direct point lookup hitting `idx_codex_cronoton_steps_order` (the
|
|
48
|
+
* existing unique index on exactly this pair, `schema.ts`), instead of a
|
|
49
|
+
* caller fetching every step for the cronoton via {@link listStepsForCronoton}
|
|
50
|
+
* and filtering client-side for one row — a confirmed LOW performance
|
|
51
|
+
* finding from `handlers/steps.ts`'s standalone fire/simulate route, which
|
|
52
|
+
* only ever needs one step per request.
|
|
53
|
+
*/
|
|
54
|
+
export declare function getStepByIndex(codexCronotonId: string, stepIndex: number, dep: DbDep): CodexCronotonStepRow | null;
|
|
@@ -9,6 +9,13 @@
|
|
|
9
9
|
* validation of step sequencing, no planner-registry lookup, no "is this the
|
|
10
10
|
* right next step" decision logic — that's explicitly Phase 2's job
|
|
11
11
|
* (`pure/run-advance.ts`), not this layer's.
|
|
12
|
+
*
|
|
13
|
+
* `yieldAs`/`yield_as` (step-to-step yield carry, per
|
|
14
|
+
* `docs/work/khronoton-step-yield-carry/design.md`) applies uniformly to
|
|
15
|
+
* BOTH step modes: for `mode:'single'` it names what to store the confirmed
|
|
16
|
+
* leg's on-chain return value as; for `mode:'planner'` it names what to
|
|
17
|
+
* store the planner's returned yield value as. The step row itself owns the
|
|
18
|
+
* yield's NAME either way — never the planner, never hard-coded elsewhere.
|
|
12
19
|
*/
|
|
13
20
|
import crypto from "node:crypto";
|
|
14
21
|
import { isUniqueConstraintError, StepAlreadyExistsError } from "./errors.js";
|
|
@@ -29,9 +36,9 @@ export function insertStep(input, dep) {
|
|
|
29
36
|
.prepare(`INSERT INTO codex_cronoton_steps
|
|
30
37
|
(id, codex_cronoton_id, step_index, mode, pact_code, config_json,
|
|
31
38
|
payload_json, gas_payer_json, signers_json, planner_name,
|
|
32
|
-
planner_params_json, idempotent, created_at, modified_at)
|
|
33
|
-
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
34
|
-
.run(id, input.codexCronotonId, input.stepIndex, input.mode, input.pactCode ?? null, input.config !== undefined ? JSON.stringify(input.config) : null, input.payload !== undefined ? JSON.stringify(input.payload) : null, input.gasPayer !== undefined ? JSON.stringify(input.gasPayer) : null, input.signers !== undefined ? JSON.stringify(input.signers) : null, input.plannerName ?? null, input.plannerParams !== undefined ? JSON.stringify(input.plannerParams) : null, input.idempotent ? 1 : 0, now, now);
|
|
39
|
+
planner_params_json, idempotent, created_at, modified_at, yield_as)
|
|
40
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
|
|
41
|
+
.run(id, input.codexCronotonId, input.stepIndex, input.mode, input.pactCode ?? null, input.config !== undefined ? JSON.stringify(input.config) : null, input.payload !== undefined ? JSON.stringify(input.payload) : null, input.gasPayer !== undefined ? JSON.stringify(input.gasPayer) : null, input.signers !== undefined ? JSON.stringify(input.signers) : null, input.plannerName ?? null, input.plannerParams !== undefined ? JSON.stringify(input.plannerParams) : null, input.idempotent ? 1 : 0, now, now, input.yieldAs ?? null);
|
|
35
42
|
}
|
|
36
43
|
catch (error) {
|
|
37
44
|
if (isUniqueConstraintError(error)) {
|
|
@@ -49,3 +56,19 @@ export function listStepsForCronoton(codexCronotonId, dep) {
|
|
|
49
56
|
ORDER BY step_index ASC`)
|
|
50
57
|
.all(codexCronotonId);
|
|
51
58
|
}
|
|
59
|
+
/**
|
|
60
|
+
* One step row at a specific `(codexCronotonId, stepIndex)` slot, or `null`.
|
|
61
|
+
* A direct point lookup hitting `idx_codex_cronoton_steps_order` (the
|
|
62
|
+
* existing unique index on exactly this pair, `schema.ts`), instead of a
|
|
63
|
+
* caller fetching every step for the cronoton via {@link listStepsForCronoton}
|
|
64
|
+
* and filtering client-side for one row — a confirmed LOW performance
|
|
65
|
+
* finding from `handlers/steps.ts`'s standalone fire/simulate route, which
|
|
66
|
+
* only ever needs one step per request.
|
|
67
|
+
*/
|
|
68
|
+
export function getStepByIndex(codexCronotonId, stepIndex, dep) {
|
|
69
|
+
const row = dep.db
|
|
70
|
+
.prepare(`SELECT * FROM codex_cronoton_steps
|
|
71
|
+
WHERE codex_cronoton_id = ? AND step_index = ?`)
|
|
72
|
+
.get(codexCronotonId, stepIndex);
|
|
73
|
+
return row ?? null;
|
|
74
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { DbDep } from "../seams.js";
|
|
2
|
+
/**
|
|
3
|
+
* Insert-or-overwrite one named yield for a run. `ON CONFLICT(run_id, name)
|
|
4
|
+
* DO UPDATE` is the design's stated overwrite semantics (design.md's
|
|
5
|
+
* "Storage" section): a replanned step's freshest computed value always
|
|
6
|
+
* wins, with no separate invalidation step needed since nothing downstream
|
|
7
|
+
* of an unconfirmed step ever runs yet. `value` is JSON-stringified so any
|
|
8
|
+
* JSON-serializable on-chain return value (string, number, object) round-trips.
|
|
9
|
+
*
|
|
10
|
+
* `input.value` is normalized to `null` first when it is `undefined` —
|
|
11
|
+
* `JSON.stringify(undefined)` returns the JS value `undefined`, not a
|
|
12
|
+
* string, which `better-sqlite3`'s `.run()` refuses to bind (it only
|
|
13
|
+
* accepts numbers/bigints/strings/buffers/`null`) and throws. A caller can
|
|
14
|
+
* legitimately hit this: `runs-driver.ts`'s single-mode confirm path stores
|
|
15
|
+
* whatever on-chain return value a `ListenResult` carries, and that `data`
|
|
16
|
+
* field is optional on the wire — a real review finding caught this
|
|
17
|
+
* crashing AFTER the leg's `markLegConfirmed` write had already committed,
|
|
18
|
+
* permanently stranding an otherwise-successful run with no yield ever
|
|
19
|
+
* recorded. `null` round-trips through `value_json`/`getYieldPool` like any
|
|
20
|
+
* other JSON value, so a caller that legitimately yields `null` is
|
|
21
|
+
* unaffected — this only changes what an absent/`undefined` value becomes.
|
|
22
|
+
*/
|
|
23
|
+
export declare function upsertYield(input: {
|
|
24
|
+
runId: string;
|
|
25
|
+
name: string;
|
|
26
|
+
value: unknown;
|
|
27
|
+
stepIndex: number;
|
|
28
|
+
}, dep: DbDep): void;
|
|
29
|
+
/**
|
|
30
|
+
* The full `{name: value}` map for a run — `{}` for a run with zero yields.
|
|
31
|
+
* Every `value_json` is parsed back into its original JSON value, so a
|
|
32
|
+
* caller resolving a `{"$yield": "<name>"}` placeholder (`pure/yields.ts`)
|
|
33
|
+
* reads the same shape that was originally passed to {@link upsertYield}.
|
|
34
|
+
*
|
|
35
|
+
* Built via `Object.create(null)`, NOT a `{}` literal — a plain object
|
|
36
|
+
* literal inherits `Object.prototype`, so `pure/yields.ts`'s own
|
|
37
|
+
* `name in pool` membership check (which walks the prototype chain) would
|
|
38
|
+
* otherwise treat `"toString"`/`"constructor"`/`"hasOwnProperty"`/etc. as
|
|
39
|
+
* present even for an empty pool, silently resolving a `$yield` reference
|
|
40
|
+
* to a built-in function instead of throwing `YieldNotFoundError` — exactly
|
|
41
|
+
* the "never silently guess" invariant this feature is built around. A
|
|
42
|
+
* prototype-less object also makes a yield legitimately named `"__proto__"`
|
|
43
|
+
* store as an ordinary own property instead of reassigning the object's own
|
|
44
|
+
* prototype (which a `{}` literal's special `__proto__` setter would do).
|
|
45
|
+
*/
|
|
46
|
+
export declare function getYieldPool(runId: string, dep: DbDep): Record<string, unknown>;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* yields — the decision-free CRUD layer for `codex_cronoton_run_yields`, the
|
|
3
|
+
* flat named-yield pool a chained run's steps write to and read from (per
|
|
4
|
+
* `docs/work/khronoton-step-yield-carry/design.md`). Mirrors `./runs.ts`'s
|
|
5
|
+
* own style (`crypto.randomUUID()` ids, a `DbDep`-shaped second arg) rather
|
|
6
|
+
* than introducing a new idiom for this one table.
|
|
7
|
+
*
|
|
8
|
+
* No resolution/validation logic lives here — "does a referenced yield name
|
|
9
|
+
* exist" (`YieldNotFoundError`) is `pure/yields.ts`'s job (Wave 2's T2), not
|
|
10
|
+
* this layer's; this file only ever does the mechanical read/write.
|
|
11
|
+
*/
|
|
12
|
+
import crypto from "node:crypto";
|
|
13
|
+
/**
|
|
14
|
+
* Insert-or-overwrite one named yield for a run. `ON CONFLICT(run_id, name)
|
|
15
|
+
* DO UPDATE` is the design's stated overwrite semantics (design.md's
|
|
16
|
+
* "Storage" section): a replanned step's freshest computed value always
|
|
17
|
+
* wins, with no separate invalidation step needed since nothing downstream
|
|
18
|
+
* of an unconfirmed step ever runs yet. `value` is JSON-stringified so any
|
|
19
|
+
* JSON-serializable on-chain return value (string, number, object) round-trips.
|
|
20
|
+
*
|
|
21
|
+
* `input.value` is normalized to `null` first when it is `undefined` —
|
|
22
|
+
* `JSON.stringify(undefined)` returns the JS value `undefined`, not a
|
|
23
|
+
* string, which `better-sqlite3`'s `.run()` refuses to bind (it only
|
|
24
|
+
* accepts numbers/bigints/strings/buffers/`null`) and throws. A caller can
|
|
25
|
+
* legitimately hit this: `runs-driver.ts`'s single-mode confirm path stores
|
|
26
|
+
* whatever on-chain return value a `ListenResult` carries, and that `data`
|
|
27
|
+
* field is optional on the wire — a real review finding caught this
|
|
28
|
+
* crashing AFTER the leg's `markLegConfirmed` write had already committed,
|
|
29
|
+
* permanently stranding an otherwise-successful run with no yield ever
|
|
30
|
+
* recorded. `null` round-trips through `value_json`/`getYieldPool` like any
|
|
31
|
+
* other JSON value, so a caller that legitimately yields `null` is
|
|
32
|
+
* unaffected — this only changes what an absent/`undefined` value becomes.
|
|
33
|
+
*/
|
|
34
|
+
export function upsertYield(input, dep) {
|
|
35
|
+
const id = crypto.randomUUID();
|
|
36
|
+
const now = new Date().toISOString();
|
|
37
|
+
const value = input.value === undefined ? null : input.value;
|
|
38
|
+
dep.db
|
|
39
|
+
.prepare(`INSERT INTO codex_cronoton_run_yields (id, run_id, name, value_json, step_index, created_at)
|
|
40
|
+
VALUES (?, ?, ?, ?, ?, ?)
|
|
41
|
+
ON CONFLICT(run_id, name) DO UPDATE SET
|
|
42
|
+
value_json = excluded.value_json,
|
|
43
|
+
step_index = excluded.step_index,
|
|
44
|
+
created_at = excluded.created_at`)
|
|
45
|
+
.run(id, input.runId, input.name, JSON.stringify(value), input.stepIndex, now);
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* The full `{name: value}` map for a run — `{}` for a run with zero yields.
|
|
49
|
+
* Every `value_json` is parsed back into its original JSON value, so a
|
|
50
|
+
* caller resolving a `{"$yield": "<name>"}` placeholder (`pure/yields.ts`)
|
|
51
|
+
* reads the same shape that was originally passed to {@link upsertYield}.
|
|
52
|
+
*
|
|
53
|
+
* Built via `Object.create(null)`, NOT a `{}` literal — a plain object
|
|
54
|
+
* literal inherits `Object.prototype`, so `pure/yields.ts`'s own
|
|
55
|
+
* `name in pool` membership check (which walks the prototype chain) would
|
|
56
|
+
* otherwise treat `"toString"`/`"constructor"`/`"hasOwnProperty"`/etc. as
|
|
57
|
+
* present even for an empty pool, silently resolving a `$yield` reference
|
|
58
|
+
* to a built-in function instead of throwing `YieldNotFoundError` — exactly
|
|
59
|
+
* the "never silently guess" invariant this feature is built around. A
|
|
60
|
+
* prototype-less object also makes a yield legitimately named `"__proto__"`
|
|
61
|
+
* store as an ordinary own property instead of reassigning the object's own
|
|
62
|
+
* prototype (which a `{}` literal's special `__proto__` setter would do).
|
|
63
|
+
*/
|
|
64
|
+
export function getYieldPool(runId, dep) {
|
|
65
|
+
const rows = dep.db
|
|
66
|
+
.prepare(`SELECT name, value_json FROM codex_cronoton_run_yields WHERE run_id = ?`)
|
|
67
|
+
.all(runId);
|
|
68
|
+
const pool = Object.create(null);
|
|
69
|
+
for (const row of rows) {
|
|
70
|
+
pool[row.name] = JSON.parse(row.value_json);
|
|
71
|
+
}
|
|
72
|
+
return pool;
|
|
73
|
+
}
|
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-
|
|
2
|
-
import { useKhronotonAdapter, useKhronotonConfig, parseRuntimeArgKeys, summariseSchedule, KhronotonStaticContext, useKhronoton, computeNextFire, InvalidScheduleConfigError } from '../chunk-
|
|
1
|
+
import { useCronotons, useCronoton, useCronotonActions, useExecuteNow, useSimulate, useServerResolvers, useManualBatch, useStartBatch, useCancelBatch, useTrigger, useCronotonFires, useRecoverFire } from '../chunk-WKI52IPY.js';
|
|
2
|
+
import { useKhronotonAdapter, useKhronotonConfig, parseRuntimeArgKeys, summariseSchedule, KhronotonStaticContext, useKhronoton, computeNextFire, InvalidScheduleConfigError } from '../chunk-A5YODPKQ.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.
|
|
3
|
+
"version": "0.14.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",
|