@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.
@@ -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-7H5TM3CS.js';
2
- import { useKhronotonAdapter, useKhronotonConfig, parseRuntimeArgKeys, summariseSchedule, KhronotonStaticContext, useKhronoton, computeNextFire, InvalidScheduleConfigError } from '../chunk-IAK4UEAA.js';
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.13.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",