@ancientpantheon/khronoton-core 0.1.1 → 0.2.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 +75 -3
- package/dist/server/executor-signers.d.ts +29 -0
- package/dist/server/executor-signers.js +60 -0
- package/dist/server/executor.d.ts +53 -0
- package/dist/server/executor.js +280 -0
- package/dist/server/index.d.ts +27 -0
- package/dist/server/index.js +51 -0
- package/dist/server/loop.d.ts +36 -0
- package/dist/server/loop.js +51 -0
- package/dist/server/pure/capability.d.ts +31 -0
- package/dist/server/pure/capability.js +63 -0
- package/dist/server/pure/fingerprint.d.ts +8 -0
- package/dist/server/pure/fingerprint.js +44 -0
- package/dist/server/pure/runtime-args.d.ts +34 -0
- package/dist/server/pure/runtime-args.js +99 -0
- package/dist/server/resolvers.d.ts +140 -0
- package/dist/server/resolvers.js +200 -0
- package/dist/server/schema.d.ts +31 -0
- package/dist/server/schema.js +93 -0
- package/dist/server/seams.d.ts +231 -0
- package/dist/server/seams.js +34 -0
- package/dist/server/store/claim.d.ts +59 -0
- package/dist/server/store/claim.js +97 -0
- package/dist/server/store/cronoton.d.ts +79 -0
- package/dist/server/store/cronoton.js +268 -0
- package/dist/server/store/errors.d.ts +26 -0
- package/dist/server/store/errors.js +40 -0
- package/dist/server/store/fires.d.ts +77 -0
- package/dist/server/store/fires.js +170 -0
- package/dist/server/store/index.d.ts +26 -0
- package/dist/server/store/index.js +33 -0
- package/dist/server/store/manual-batch.d.ts +38 -0
- package/dist/server/store/manual-batch.js +110 -0
- package/dist/server/store/mappers.d.ts +21 -0
- package/dist/server/store/mappers.js +62 -0
- package/dist/server/tick.d.ts +83 -0
- package/dist/server/tick.js +235 -0
- package/dist/server/types.d.ts +220 -0
- package/dist/server/types.js +14 -0
- package/package.json +14 -2
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The server tick — the async select → claim → fire → record → finalize → audit
|
|
3
|
+
* sequence, lifted from the Hub `lib/codex-cronoton/tick.ts` into a pure
|
|
4
|
+
* ctx-taking form.
|
|
5
|
+
*
|
|
6
|
+
* The Hub reached its DB, audit log, and fire dispatcher through ambient globals
|
|
7
|
+
* (`getDb()`, `logAuditFromWorker`, a `stoicism-mint` re-export). Here every one
|
|
8
|
+
* of those is injected on {@link TickCtx} and threaded explicitly: `{ db }` into
|
|
9
|
+
* each store call, `{ db, resolveFireMode }` into the fire record, the full
|
|
10
|
+
* `{ runtime, resolver, config, db, deps }` into {@link fireByServerResolver},
|
|
11
|
+
* and `onAudit(...)` for the two audit action strings.
|
|
12
|
+
*
|
|
13
|
+
* ── CLAIM-BEFORE-FIRE / once-only contract (LOAD-BEARING) ─────────────────────
|
|
14
|
+
* Because the fire runs inline and can block for minutes, each due row's
|
|
15
|
+
* `next_fire_at` MUST be advanced (recurring) or cleared (one-time) atomically
|
|
16
|
+
* BEFORE the await via {@link claimDueCodexCronoton}:
|
|
17
|
+
* - claim wins (true) → the row is no longer due/re-selectable; fire it.
|
|
18
|
+
* - claim lost (false) → an overlapping tick or a manual Execute-Now already
|
|
19
|
+
* claimed it → SKIP (no fire).
|
|
20
|
+
* The per-row atomic claim is the PRIMARY double-fire guard.
|
|
21
|
+
*
|
|
22
|
+
* ── Failure policy ────────────────────────────────────────────────────────────
|
|
23
|
+
* Single attempt, no retry, no backoff, NO auto-pause. Exactly ONE fire row per
|
|
24
|
+
* fire. A recurring FAILURE stays `active` (its next_fire_at was already advanced
|
|
25
|
+
* by the claim — the failure lives only in fire history). A one-time fire applies
|
|
26
|
+
* the executor's terminal intent (success → completed, failure → error). The fire
|
|
27
|
+
* dispatcher NEVER throws — the tick reads `result.ok`; the surrounding try/catch
|
|
28
|
+
* isolates only orchestration errors (rowToDefinition parse, recordFire write).
|
|
29
|
+
*
|
|
30
|
+
* The ONLY status write this tick issues is the one-time terminal transition via
|
|
31
|
+
* {@link applyTerminalIntent}. It NEVER writes `status='paused'` and issues NO
|
|
32
|
+
* post-fire recurring advance (the claim already advanced it).
|
|
33
|
+
*/
|
|
34
|
+
import { fetchDueCodexCronotons, claimDueCodexCronoton, applyTerminalIntent, } from "./store/claim.js";
|
|
35
|
+
import { rowToDefinition } from "./store/mappers.js";
|
|
36
|
+
import { recordFire } from "./store/fires.js";
|
|
37
|
+
import { computeDefinitionFingerprint } from "./pure/fingerprint.js";
|
|
38
|
+
import { fetchDueManualBatches, claimManualBatchFire, cancelManualBatch, } from "./store/manual-batch.js";
|
|
39
|
+
import { getCodexCronoton } from "./store/cronoton.js";
|
|
40
|
+
import { fireByServerResolver } from "./resolvers.js";
|
|
41
|
+
import { TICK_BATCH_LIMIT } from "./seams.js";
|
|
42
|
+
/**
|
|
43
|
+
* One multi-tx `onTx` collector + the `FireTxKey[]` it fills, threaded into
|
|
44
|
+
* {@link fireByServerResolver} so an INLINE multi-tx fire records the per-tx
|
|
45
|
+
* breakdown. A no-op for single-tx/no-resolver rows (the single-tx path never
|
|
46
|
+
* invokes `onTx`), so it is safe to pass unconditionally.
|
|
47
|
+
*/
|
|
48
|
+
function makeTxKeyCollector() {
|
|
49
|
+
const txKeys = [];
|
|
50
|
+
return {
|
|
51
|
+
txKeys,
|
|
52
|
+
deps: {
|
|
53
|
+
onTx: (tx) => txKeys.push({
|
|
54
|
+
kind: tx.kind,
|
|
55
|
+
chainId: tx.chainId,
|
|
56
|
+
requestKey: tx.requestKey,
|
|
57
|
+
ok: tx.ok,
|
|
58
|
+
}),
|
|
59
|
+
},
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Select → claim → fire → record → finalize → audit for every due codex
|
|
64
|
+
* cronoton. Fires INLINE via {@link fireByServerResolver} (map §8 divergence #3:
|
|
65
|
+
* always through the dispatcher, never the executor directly).
|
|
66
|
+
*/
|
|
67
|
+
export async function codexCronotonTickOnce(now, ctx) {
|
|
68
|
+
const firedIds = [];
|
|
69
|
+
const failedIds = [];
|
|
70
|
+
const skippedIds = [];
|
|
71
|
+
const due = fetchDueCodexCronotons(now, ctx.config?.tickBatchLimit ?? TICK_BATCH_LIMIT, {
|
|
72
|
+
db: ctx.db,
|
|
73
|
+
});
|
|
74
|
+
for (const row of due) {
|
|
75
|
+
try {
|
|
76
|
+
const claimed = claimDueCodexCronoton(row, now, { db: ctx.db });
|
|
77
|
+
if (!claimed) {
|
|
78
|
+
skippedIds.push(row.id);
|
|
79
|
+
continue;
|
|
80
|
+
}
|
|
81
|
+
const scheduleKind = row.schedule_mode === "one-time" ? "one-time" : "recurring";
|
|
82
|
+
const definition = rowToDefinition(row);
|
|
83
|
+
const { txKeys, deps: collectDeps } = makeTxKeyCollector();
|
|
84
|
+
const result = await fireByServerResolver(definition, row, {
|
|
85
|
+
runtime: ctx.runtime,
|
|
86
|
+
resolver: ctx.resolver,
|
|
87
|
+
config: ctx.config,
|
|
88
|
+
db: ctx.db,
|
|
89
|
+
deps: collectDeps,
|
|
90
|
+
});
|
|
91
|
+
const fingerprint = computeDefinitionFingerprint(row);
|
|
92
|
+
const fireId = recordFire({
|
|
93
|
+
codexCronotonId: row.id,
|
|
94
|
+
jobId: null,
|
|
95
|
+
firedAt: now.toISOString(),
|
|
96
|
+
status: result.ok ? "success" : "failure",
|
|
97
|
+
requestKey: result.requestKey,
|
|
98
|
+
chainId: result.chainId,
|
|
99
|
+
errorMessage: result.error,
|
|
100
|
+
chainResponse: result.rawResult,
|
|
101
|
+
definitionFingerprint: fingerprint,
|
|
102
|
+
txKeys,
|
|
103
|
+
}, { db: ctx.db, resolveFireMode: ctx.resolveFireMode });
|
|
104
|
+
// Recurring: next_fire_at was already advanced by the claim (a failed
|
|
105
|
+
// recurring stays active — no post-fire advance). One-time: next_fire_at
|
|
106
|
+
// was already cleared by the claim — apply the terminal status.
|
|
107
|
+
if (scheduleKind === "one-time") {
|
|
108
|
+
applyTerminalIntent(row.id, result.terminalIntent, { db: ctx.db });
|
|
109
|
+
}
|
|
110
|
+
await ctx.onAudit({
|
|
111
|
+
action: result.ok ? "codex_cronoton.fire" : "codex_cronoton.fire_failed",
|
|
112
|
+
result: result.ok ? "success" : "failure",
|
|
113
|
+
targetKind: "codex_cronoton",
|
|
114
|
+
targetId: row.id,
|
|
115
|
+
detail: {
|
|
116
|
+
codexCronotonId: row.id,
|
|
117
|
+
fireId,
|
|
118
|
+
requestKey: result.requestKey,
|
|
119
|
+
chainId: result.chainId,
|
|
120
|
+
actor: "scheduler",
|
|
121
|
+
scheduleKind,
|
|
122
|
+
terminalStatus: result.terminalIntent?.status,
|
|
123
|
+
definitionFingerprint: fingerprint,
|
|
124
|
+
errorMessage: result.error,
|
|
125
|
+
message: result.error,
|
|
126
|
+
},
|
|
127
|
+
});
|
|
128
|
+
if (result.ok)
|
|
129
|
+
firedIds.push(row.id);
|
|
130
|
+
else
|
|
131
|
+
failedIds.push(row.id);
|
|
132
|
+
}
|
|
133
|
+
catch (err) {
|
|
134
|
+
// Orchestration error (rowToDefinition parse, recordFire write). The claim
|
|
135
|
+
// already advanced/cleared next_fire_at, so this row will NOT re-arm;
|
|
136
|
+
// isolate the failure and continue to the next row. Surface the diagnostic
|
|
137
|
+
// (matching the Hub) so a "fired but the fire-record write failed" case is
|
|
138
|
+
// never silent — the id also lands in skippedIds.
|
|
139
|
+
console.error(`khronoton tick: codex cronoton ${row.id} skipped after an orchestration error`, err);
|
|
140
|
+
skippedIds.push(row.id);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return { firedIds, failedIds, skippedIds };
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Process due manual-execution batches — the "Execute Now ×N" rail. For each
|
|
147
|
+
* batch with a due slot it fires the PARENT cronoton ONCE (the same shared fire +
|
|
148
|
+
* fire-row recording as the scheduled tick), spaced by the batch's interval. Each
|
|
149
|
+
* slot is CLAIMED before the inline fire so an overlapping tick cannot double-fire
|
|
150
|
+
* it. A batch fire records a fire row + a `manual_fire` audit (actor 'ancient',
|
|
151
|
+
* via 'manual_batch', attributed to the batch's creator) and NEVER advances the
|
|
152
|
+
* cronoton's own schedule. If the parent has left 'active', the batch is
|
|
153
|
+
* auto-cancelled instead of fired.
|
|
154
|
+
*/
|
|
155
|
+
export async function processDueManualBatchesOnce(now, ctx) {
|
|
156
|
+
const firedIds = [];
|
|
157
|
+
const failedIds = [];
|
|
158
|
+
const skippedIds = [];
|
|
159
|
+
const cancelledIds = [];
|
|
160
|
+
const due = fetchDueManualBatches(now, ctx.config?.tickBatchLimit ?? TICK_BATCH_LIMIT, {
|
|
161
|
+
db: ctx.db,
|
|
162
|
+
});
|
|
163
|
+
for (const batch of due) {
|
|
164
|
+
try {
|
|
165
|
+
const cronoton = getCodexCronoton(batch.codex_cronoton_id, { db: ctx.db });
|
|
166
|
+
if (!cronoton || cronoton.status !== "active") {
|
|
167
|
+
// Parent paused / deleted / terminal — stop the batch.
|
|
168
|
+
cancelManualBatch(batch.id, { db: ctx.db });
|
|
169
|
+
cancelledIds.push(batch.id);
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
const claimed = claimManualBatchFire(batch, now, { db: ctx.db });
|
|
173
|
+
if (!claimed) {
|
|
174
|
+
skippedIds.push(batch.id);
|
|
175
|
+
continue;
|
|
176
|
+
}
|
|
177
|
+
const batchIndex = batch.completed + 1;
|
|
178
|
+
const definition = rowToDefinition(cronoton);
|
|
179
|
+
const { txKeys, deps: collectDeps } = makeTxKeyCollector();
|
|
180
|
+
const result = await fireByServerResolver(definition, cronoton, {
|
|
181
|
+
runtime: ctx.runtime,
|
|
182
|
+
resolver: ctx.resolver,
|
|
183
|
+
config: ctx.config,
|
|
184
|
+
db: ctx.db,
|
|
185
|
+
deps: collectDeps,
|
|
186
|
+
});
|
|
187
|
+
const fingerprint = computeDefinitionFingerprint(cronoton);
|
|
188
|
+
const fireId = recordFire({
|
|
189
|
+
codexCronotonId: cronoton.id,
|
|
190
|
+
jobId: null,
|
|
191
|
+
firedAt: now.toISOString(),
|
|
192
|
+
status: result.ok ? "success" : "failure",
|
|
193
|
+
requestKey: result.requestKey,
|
|
194
|
+
chainId: result.chainId,
|
|
195
|
+
errorMessage: result.error,
|
|
196
|
+
chainResponse: result.rawResult,
|
|
197
|
+
definitionFingerprint: fingerprint,
|
|
198
|
+
txKeys,
|
|
199
|
+
}, { db: ctx.db, resolveFireMode: ctx.resolveFireMode });
|
|
200
|
+
await ctx.onAudit({
|
|
201
|
+
action: result.ok ? "codex_cronoton.manual_fire" : "codex_cronoton.fire_failed",
|
|
202
|
+
result: result.ok ? "success" : "failure",
|
|
203
|
+
targetKind: "codex_cronoton",
|
|
204
|
+
targetId: cronoton.id,
|
|
205
|
+
detail: {
|
|
206
|
+
codexCronotonId: cronoton.id,
|
|
207
|
+
fireId,
|
|
208
|
+
actor: "ancient",
|
|
209
|
+
via: "manual_batch",
|
|
210
|
+
batchId: batch.id,
|
|
211
|
+
batchIndex,
|
|
212
|
+
batchTotal: batch.total,
|
|
213
|
+
scheduleKind: "recurring",
|
|
214
|
+
createdBy: batch.created_by,
|
|
215
|
+
requestKey: result.requestKey,
|
|
216
|
+
chainId: result.chainId,
|
|
217
|
+
definitionFingerprint: fingerprint,
|
|
218
|
+
errorMessage: result.error,
|
|
219
|
+
message: result.error,
|
|
220
|
+
},
|
|
221
|
+
});
|
|
222
|
+
if (result.ok)
|
|
223
|
+
firedIds.push(batch.id);
|
|
224
|
+
else
|
|
225
|
+
failedIds.push(batch.id);
|
|
226
|
+
}
|
|
227
|
+
catch (err) {
|
|
228
|
+
// Isolate the per-batch orchestration failure and surface the diagnostic
|
|
229
|
+
// (matching the Hub) rather than dropping it silently.
|
|
230
|
+
console.error(`khronoton tick: manual batch ${batch.id} skipped after an orchestration error`, err);
|
|
231
|
+
skippedIds.push(batch.id);
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
return { firedIds, failedIds, skippedIds, cancelledIds };
|
|
235
|
+
}
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared domain types for the Khronoton server-side executor and store.
|
|
3
|
+
*
|
|
4
|
+
* `CodexTxDefinition` is the single constructed-tx shape every caller
|
|
5
|
+
* (simulate API, manual-fire API, scheduled-fire worker tick) passes to the
|
|
6
|
+
* executor. The result + terminal-intent types are imported by those same
|
|
7
|
+
* callers so the executor stays the single source of truth for the contract.
|
|
8
|
+
*
|
|
9
|
+
* The DB row types + their client-facing projections describe the three
|
|
10
|
+
* server tables (`codex_cronotons`, `codex_cronoton_fires`,
|
|
11
|
+
* `codex_cronoton_manual_batches`). JSON columns are raw strings at the row
|
|
12
|
+
* layer; higher layers parse them into the structured types above.
|
|
13
|
+
*/
|
|
14
|
+
import type { ScheduleMode } from "../schedule.js";
|
|
15
|
+
/**
|
|
16
|
+
* Opaque chain identifier. Genericized to `string` — this package carries no
|
|
17
|
+
* chain dependency (the source Hub imported a concrete `ChainId`).
|
|
18
|
+
*/
|
|
19
|
+
export type ChainId = string;
|
|
20
|
+
/** Run mode: `simulate` signs + dirty-reads but never submits; `fire` submits. */
|
|
21
|
+
export type ExecutorMode = "simulate" | "fire";
|
|
22
|
+
/** One-time entries terminate after a single fire; recurring re-fire on schedule. */
|
|
23
|
+
export type ScheduleKind = "one-time" | "recurring";
|
|
24
|
+
/** Capability scoping for a signer: `pure` (unrestricted) or `scoped` (capped). */
|
|
25
|
+
export type CapabilityMode = "pure" | "scoped";
|
|
26
|
+
/** A signer reference — pubkey + how its signature is scoped. Codex-only: no secrets. */
|
|
27
|
+
export interface CodexSigner {
|
|
28
|
+
/** 64-hex Ed25519 public key (no `k:` prefix). Must be resolvable by the codex. */
|
|
29
|
+
readonly publicKey: string;
|
|
30
|
+
readonly capabilityMode: CapabilityMode;
|
|
31
|
+
/** Newline-separated capability lines (e.g. `(coin.GAS)`). Empty for pure signers. */
|
|
32
|
+
readonly capabilities: string;
|
|
33
|
+
}
|
|
34
|
+
/** Gas-payer reference: the protocol gas station, or a codex `k:` account. */
|
|
35
|
+
export interface CodexGasPayer {
|
|
36
|
+
readonly type: "codex" | "gas-station";
|
|
37
|
+
/** Codex gas-payer pubkey/address (the `k:` is derived). Absent for gas-station. */
|
|
38
|
+
readonly address?: string;
|
|
39
|
+
/**
|
|
40
|
+
* The codex public key that signs the gas station's `DALOS.GAS_PAYER`
|
|
41
|
+
* capability. Required (and only meaningful) for `type:'gas-station'`: the
|
|
42
|
+
* executor synthesizes a scoped GAS_PAYER signer for this key, so the gas
|
|
43
|
+
* station pays while this codex key authorizes the payment. The `coin.GAS`
|
|
44
|
+
* for a codex gas-payer rides on `address`, not here.
|
|
45
|
+
*/
|
|
46
|
+
readonly gasStationSignerKey?: string;
|
|
47
|
+
}
|
|
48
|
+
/** Transaction config — chain, gas, ttl. `gasPrice` is in ANU. */
|
|
49
|
+
export interface CodexTxConfig {
|
|
50
|
+
readonly chainId: string;
|
|
51
|
+
/** Gas price in ANU (converted to STOA via `anuToStoa` at build time). */
|
|
52
|
+
readonly gasPrice: number;
|
|
53
|
+
readonly gasLimit: number;
|
|
54
|
+
/** When true, the executor calibrates the gas limit from a dirty-read. */
|
|
55
|
+
readonly autoGasLimit: boolean;
|
|
56
|
+
/** Time-to-live in seconds. */
|
|
57
|
+
readonly ttl: number;
|
|
58
|
+
}
|
|
59
|
+
/** The full constructed-tx definition — the one shape all callers pass. */
|
|
60
|
+
export interface CodexTxDefinition {
|
|
61
|
+
readonly pactCode: string;
|
|
62
|
+
readonly config: CodexTxConfig;
|
|
63
|
+
/** env-data + keysets: each key becomes one `addData(key, value)`. */
|
|
64
|
+
readonly payload: Record<string, unknown>;
|
|
65
|
+
readonly gasPayer: CodexGasPayer;
|
|
66
|
+
readonly signers: CodexSigner[];
|
|
67
|
+
/** Drives terminal-intent computation. Defaults to `recurring` when absent. */
|
|
68
|
+
readonly scheduleKind?: ScheduleKind;
|
|
69
|
+
/**
|
|
70
|
+
* Names a server-side payload resolver (e.g. `'stoicism-mint'`). When set, the
|
|
71
|
+
* fire-time wrapper fills designated payload keys from live server data and
|
|
72
|
+
* settles server balances after a successful on-chain submit. Absent for
|
|
73
|
+
* ordinary cronotons, which fire through the executor unchanged.
|
|
74
|
+
*/
|
|
75
|
+
readonly serverResolver?: string;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Terminal-transition INTENT for a one-time entry, COMPUTED (not persisted) by
|
|
79
|
+
* the executor. The caller reads this off the result and writes the table +
|
|
80
|
+
* clears the next-fire time. `null` for recurring entries and all simulate runs.
|
|
81
|
+
*/
|
|
82
|
+
export interface TerminalIntent {
|
|
83
|
+
readonly status: "completed" | "error";
|
|
84
|
+
/** Always true for one-time terminal transitions — its single attempt is spent. */
|
|
85
|
+
readonly clearNextFire: true;
|
|
86
|
+
}
|
|
87
|
+
/** Result of a `simulate` run. Never submits. */
|
|
88
|
+
export interface SimulateResult {
|
|
89
|
+
readonly ok: boolean;
|
|
90
|
+
readonly mode: "simulate";
|
|
91
|
+
/** Present when `autoGasLimit` and the dirty-read returned a gas figure. */
|
|
92
|
+
readonly calibratedGasLimit?: number;
|
|
93
|
+
readonly gasUsed?: number;
|
|
94
|
+
readonly rawResult?: unknown;
|
|
95
|
+
readonly error?: string;
|
|
96
|
+
/** Always `null` for simulate. */
|
|
97
|
+
readonly terminalIntent: null;
|
|
98
|
+
}
|
|
99
|
+
/** Result of a `fire` run. Submits (unless pre-flight fails). */
|
|
100
|
+
export interface FireResult {
|
|
101
|
+
readonly ok: boolean;
|
|
102
|
+
readonly mode: "fire";
|
|
103
|
+
readonly requestKey?: string;
|
|
104
|
+
readonly chainId?: string;
|
|
105
|
+
readonly rawResult?: unknown;
|
|
106
|
+
readonly error?: string;
|
|
107
|
+
/** Computed one-time terminal intent; `null` for recurring. */
|
|
108
|
+
readonly terminalIntent: TerminalIntent | null;
|
|
109
|
+
}
|
|
110
|
+
export type ExecutorResult = SimulateResult | FireResult;
|
|
111
|
+
/** The raw `codex_cronotons` row shape (JSON columns are still strings here). */
|
|
112
|
+
export interface CodexCronotonRow {
|
|
113
|
+
id: string;
|
|
114
|
+
name: string;
|
|
115
|
+
description: string | null;
|
|
116
|
+
pact_code: string;
|
|
117
|
+
config_json: string;
|
|
118
|
+
payload_json: string | null;
|
|
119
|
+
gas_payer_json: string;
|
|
120
|
+
signers_json: string;
|
|
121
|
+
schedule_mode: ScheduleMode;
|
|
122
|
+
schedule_config_json: string;
|
|
123
|
+
/**
|
|
124
|
+
* Name of the fire-time server payload resolver, or null/absent for ordinary
|
|
125
|
+
* rows. Optional so pre-migration row doubles (test fixtures) typecheck; real
|
|
126
|
+
* rows from `SELECT *` carry the column (value may be null).
|
|
127
|
+
*/
|
|
128
|
+
server_resolver?: string | null;
|
|
129
|
+
/**
|
|
130
|
+
* When 1, this cronoton may be fired by the external HMAC endpoint. Optional
|
|
131
|
+
* so pre-migration row doubles (test fixtures) typecheck; real rows carry it.
|
|
132
|
+
*/
|
|
133
|
+
external_fireable?: number;
|
|
134
|
+
/**
|
|
135
|
+
* JSON string[] of env-data keys a trigger supplies at fire time; null/absent
|
|
136
|
+
* = an ordinary fixed-definition cronoton. Optional so pre-migration row
|
|
137
|
+
* doubles (test fixtures) typecheck.
|
|
138
|
+
*/
|
|
139
|
+
runtime_arg_keys?: string | null;
|
|
140
|
+
status: "active" | "paused" | "completed" | "error";
|
|
141
|
+
next_fire_at: string | null;
|
|
142
|
+
last_fire_at: string | null;
|
|
143
|
+
created_at: string;
|
|
144
|
+
modified_at: string;
|
|
145
|
+
created_by: string;
|
|
146
|
+
}
|
|
147
|
+
/** The list/limbo projection the route attaches `scheduleSummary` to. */
|
|
148
|
+
export interface CodexCronotonListItem {
|
|
149
|
+
id: string;
|
|
150
|
+
name: string;
|
|
151
|
+
scheduleMode: ScheduleMode;
|
|
152
|
+
status: CodexCronotonRow["status"];
|
|
153
|
+
nextFireAt: string | null;
|
|
154
|
+
lastFireAt: string | null;
|
|
155
|
+
createdAt: string;
|
|
156
|
+
modifiedAt: string;
|
|
157
|
+
createdBy: string;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Launch-state provenance of a fire — 'test' pre-lock, 'live' once the
|
|
161
|
+
* consumer's live state is locked.
|
|
162
|
+
*/
|
|
163
|
+
export type CodexFireMode = "test" | "live";
|
|
164
|
+
/**
|
|
165
|
+
* One on-chain transaction recorded under a single fire. A multi-tx fire (e.g.
|
|
166
|
+
* a pool payout) spans many: cross-chain burns + SPV continuations + the bulk
|
|
167
|
+
* transfer. The worker appends one of these as each tx lands; the fire history
|
|
168
|
+
* surfaces a count badge that expands to a per-tx explorer link.
|
|
169
|
+
*/
|
|
170
|
+
export interface FireTxKey {
|
|
171
|
+
/** 'burn' (source→0 initiate) | 'continuation' (SPV step on 0) | 'bulk' (payout transfer). */
|
|
172
|
+
kind: "burn" | "continuation" | "bulk";
|
|
173
|
+
/** Source chain for burn/continuation; '0' for the bulk transfer. */
|
|
174
|
+
chainId: string;
|
|
175
|
+
requestKey: string;
|
|
176
|
+
/** Whether the tx confirmed ok (best-effort; absent = unknown/in-flight). */
|
|
177
|
+
ok?: boolean;
|
|
178
|
+
}
|
|
179
|
+
/** The client-facing projection of a `codex_cronoton_fires` row. */
|
|
180
|
+
export interface CodexCronotonFireRow {
|
|
181
|
+
id: string;
|
|
182
|
+
firedAt: string;
|
|
183
|
+
status: "success" | "failure" | "running" | "nothing";
|
|
184
|
+
requestKey: string | null;
|
|
185
|
+
chainId: string | null;
|
|
186
|
+
errorMessage: string | null;
|
|
187
|
+
chainResponse: unknown;
|
|
188
|
+
definitionFingerprint: string | null;
|
|
189
|
+
mode: CodexFireMode;
|
|
190
|
+
/** Timestamp a failed fire was reconciled to success via `recoverFire`; null for natively-successful or never-recovered fires. */
|
|
191
|
+
recoveredAt: string | null;
|
|
192
|
+
/** Per-tx request keys for a multi-tx fire (empty for ordinary single-tx fires). */
|
|
193
|
+
txKeys: FireTxKey[];
|
|
194
|
+
}
|
|
195
|
+
/** Raw `codex_cronoton_manual_batches` row. */
|
|
196
|
+
export interface CodexManualBatchRow {
|
|
197
|
+
id: string;
|
|
198
|
+
codex_cronoton_id: string;
|
|
199
|
+
total: number;
|
|
200
|
+
completed: number;
|
|
201
|
+
interval_seconds: number;
|
|
202
|
+
status: "active" | "completed" | "cancelled";
|
|
203
|
+
next_at: string | null;
|
|
204
|
+
created_at: string;
|
|
205
|
+
modified_at: string;
|
|
206
|
+
created_by: string;
|
|
207
|
+
}
|
|
208
|
+
/** Client-facing projection of a batch (progress + schedule). */
|
|
209
|
+
export interface ManualBatchView {
|
|
210
|
+
id: string;
|
|
211
|
+
codexCronotonId: string;
|
|
212
|
+
total: number;
|
|
213
|
+
completed: number;
|
|
214
|
+
remaining: number;
|
|
215
|
+
intervalSeconds: number;
|
|
216
|
+
status: "active" | "completed" | "cancelled";
|
|
217
|
+
nextAt: string | null;
|
|
218
|
+
createdBy: string;
|
|
219
|
+
createdAt: string;
|
|
220
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared domain types for the Khronoton server-side executor and store.
|
|
3
|
+
*
|
|
4
|
+
* `CodexTxDefinition` is the single constructed-tx shape every caller
|
|
5
|
+
* (simulate API, manual-fire API, scheduled-fire worker tick) passes to the
|
|
6
|
+
* executor. The result + terminal-intent types are imported by those same
|
|
7
|
+
* callers so the executor stays the single source of truth for the contract.
|
|
8
|
+
*
|
|
9
|
+
* The DB row types + their client-facing projections describe the three
|
|
10
|
+
* server tables (`codex_cronotons`, `codex_cronoton_fires`,
|
|
11
|
+
* `codex_cronoton_manual_batches`). JSON columns are raw strings at the row
|
|
12
|
+
* layer; higher layers parse them into the structured types above.
|
|
13
|
+
*/
|
|
14
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ancientpantheon/khronoton-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.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",
|
|
@@ -10,6 +10,11 @@
|
|
|
10
10
|
"types": "./dist/index.d.ts",
|
|
11
11
|
"import": "./dist/index.js",
|
|
12
12
|
"require": "./dist/index.js"
|
|
13
|
+
},
|
|
14
|
+
"./server": {
|
|
15
|
+
"types": "./dist/server/index.d.ts",
|
|
16
|
+
"import": "./dist/server/index.js",
|
|
17
|
+
"require": "./dist/server/index.js"
|
|
13
18
|
}
|
|
14
19
|
},
|
|
15
20
|
"files": [
|
|
@@ -38,5 +43,12 @@
|
|
|
38
43
|
"registry": "https://registry.npmjs.org",
|
|
39
44
|
"access": "public"
|
|
40
45
|
},
|
|
41
|
-
"license": "UNLICENSED"
|
|
46
|
+
"license": "UNLICENSED",
|
|
47
|
+
"optionalDependencies": {
|
|
48
|
+
"better-sqlite3": "^12.11.1"
|
|
49
|
+
},
|
|
50
|
+
"devDependencies": {
|
|
51
|
+
"@types/better-sqlite3": "^7.6.13",
|
|
52
|
+
"better-sqlite3": "^12.11.1"
|
|
53
|
+
}
|
|
42
54
|
}
|