@ancientpantheon/khronoton-core 0.3.0 → 0.4.1

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 CHANGED
@@ -4,6 +4,25 @@ All notable changes to `@ancientpantheon/khronoton-core`.
4
4
 
5
5
  The engine's pre-extraction history lives in the AncientHoldings hub, whose inline scheduler ("Cronoton") this package extracts and generalises.
6
6
 
7
+ ## 0.4.1 — 2026-07-22
8
+
9
+ **PATCH — dependency rename, no code change.**
10
+
11
+ The Ouronet protocol dependency moved scope: `@stoachain/ouronet-core` → **`@ouronet/ouronet-core`**. Same code and version line; the package was split out of `StoaChain/stoa-js` into [`OuroborosNetwork/ouronet-libs`](https://github.com/OuroborosNetwork/ouronet-libs) in the Phase-4 reorganisation so that published identity matches org ownership. The old name is deprecated on npm.
12
+
13
+ This needs a release rather than a local edit: the published `0.4.0` peer-depends on the old name, and a consumer that also depends on the new one ends up demanding two different chain versions at once — `@ouronet/ouronet-core` pins `@stoachain/kadena-stoic-legacy` exactly, so the two cannot coexist. Anyone consuming this package alongside the renamed stack should move to 0.4.1.
14
+
15
+ **799 specs pass.**
16
+
17
+ ## 0.4.0 — 2026-07-13
18
+
19
+ Made khronoton **chain-polyglot**: the package now ships the chain adapters it needs to talk to each supported chain, as a `/blockchain/<chain>` subpath family — rather than a separate npm package per chain. This keeps khronoton a single drop-in for every automaton while it speaks each chain's language natively. Root `.`/`/server`/`/handlers` outputs are unchanged.
20
+
21
+ - **`/blockchain/stoachain`** — `createStoachainRuntime(config?) → Promise<ChainRuntime>` wraps the `@stoachain/*` runtime (client, signing, gas, constants) into the core `ChainRuntime` seam, so a StoaChain automaton (Mnemosyne, Caduceus, Aletheia, …) injects one object instead of reaching for `@stoachain/*` directly. Loads the SDK via SEQUENTIAL `await import()` (concurrent `Promise.all` crashes Node 24 with `ERR_INTERNAL_ASSERTION`); an optional `nodeBaseUrl` routes `getPactUrl`. Future chains land as sibling `/blockchain/<chain>` subpaths.
22
+ - **Optional-peer model.** Each chain's SDK is an **optional peer dependency** (`@stoachain/*@^4.3.6` for `/blockchain/stoachain`) and is imported LAZILY inside the factory. So `npm install @ancientpantheon/khronoton-core` pulls zero chain SDKs, importing the subpath costs nothing, and only calling the factory needs the SDK — a consumer carries only the chain(s) it actually uses. `react` remains an optional peer for the `/provider`/`/hooks`/`/ui` subpaths.
23
+ - **Consolidation.** This folds in the previously-separate `@ancientpantheon/khronoton-stoachain` package (built + tested but never published to npm); that package is removed. Its tests move into core under `src/blockchain/`: 8 mocked adapter tests run in the normal gate, while the 2 real-`@stoachain` integration tests (`*.real.test.ts`) run via `npm run test:integration` — kept OUT of the publish/CI gate so a release never depends on the external chain SDK's behaviour in the CI environment.
24
+ - **Packaging.** `/blockchain/stoachain` carries dual `{ types, import, require }` conditions and is dist-smoked under both; it builds via tsup with `@stoachain/*` external, so the byte-stable `tsc` core (`.`/`/server`/`/handlers`) is untouched.
25
+
7
26
  ## 0.3.0 — 2026-07-13
8
27
 
9
28
  Added the complete drop-in **codex-cronoton experience layer** — the UI, API handlers, and React data layer a consumer needs to reproduce the AncientHoldings Hub's cronoton UX end to end. The root `.` schedule engine and the `/server` automaton engine are **byte-unchanged** from 0.2.0 (verified by SHA-256 over the `dist/index.*` + `dist/server/**` outputs); this release is purely additive on new subpaths.
package/README.md CHANGED
@@ -6,13 +6,19 @@ Khronoton is the "When do I act?" Constructor of the Pantheon architecture — t
6
6
 
7
7
  ## Status
8
8
 
9
- **`0.3.0` on public npmjs** — the complete drop-in codex-cronoton experience, matching the AncientHoldings Hub. On top of the byte-unchanged root `.` schedule engine and `/server` automaton engine (both from 0.2.0), 0.3.0 adds the whole experience layer as new subpaths so a consumer wires the Hub's cronoton UX end to end without re-implementing it:
9
+ **`0.4.1` on public npmjs** — **PATCH (dependency rename, no code change).** Released 2026-07-22. `@stoachain/ouronet-core` → `@ouronet/ouronet-core` — same code, new scope, following the Phase-4 split into OuroborosNetwork/ouronet-libs. **799 specs pass.**
10
+
11
+ **`0.4.0` on public npmjs** — the complete drop-in codex-cronoton experience, matching the AncientHoldings Hub, now **chain-polyglot**. On top of the byte-unchanged root `.` schedule engine and `/server` automaton engine (both from 0.2.0), the package ships the whole experience layer as subpaths so a consumer wires the Hub's cronoton UX end to end without re-implementing it:
10
12
 
11
13
  - **`/handlers`** — framework-agnostic HTTP route handlers over the `/server` store + executor (list/get/fires/signers/commit/edit/pause/resume/delete/simulate/execute-now/trigger/batch/recover), driven by a tiny `HandlerRequest`/`HandlerResponse` seam so any router (Next.js, Express, …) can mount them.
12
14
  - **`/provider` + `/hooks`** — the React data layer: `<KhronotonProvider adapter={…}>`, the 16-method `KhronotonAdapter` seam with two reference adapters (`createFetchAdapter` over HTTP, `createMemoryAdapter` over in-process handlers), the shared `runGated` confirm-retry, and the data + action hooks (`useCronotons`/`useCronoton`/`useCronotonFires`/`useManualBatch` + the lifecycle/execute action hooks).
13
15
  - **`/ui` + `/ui.css`** — the React UI at full Hub parity: the four screens **List**, **Detail/Observe** (fire history with 50/page pager, definition-drift flag, result tooltip, pluggable multi-tx renderer, wired recover), **Builder** (two-pane create + edit, Config/Payload/Gas Payer/Signatures/Execute tabs, Simulate→AUTO-gas calibrate), and a **Public** read-only transparency view — themed entirely through `--khr-*` CSS variables inside `<KhronotonUiRoot>`.
14
16
 
15
- Chain specifics stay out of core: the `@stoachain/*` `ChainRuntime` wrap ships as the separate **`@ancientpantheon/khronoton-stoachain`** adapter, so core remains zero-runtime-dependency and chain-agnostic. Every JS subpath resolves under both import conditions (ESM `import` + CJS `require`); React is an optional peer for the `/provider`, `/hooks`, and `/ui` subpaths only. The root `.` and `/server` outputs are byte-identical to 0.2.0.
17
+ Khronoton isn't chain-*agnostic* — it's chain-*polyglot*: the root schedule/tick engine orchestrates, and the **`/blockchain/<chain>`** subpath family teaches it to speak each supported chain's language natively (0.4.0):
18
+
19
+ - **`/blockchain/stoachain`** — `createStoachainRuntime(config?)` wraps the `@stoachain/*` runtime into the core `ChainRuntime` seam, so a StoaChain automaton injects one object instead of reaching for `@stoachain/*` directly. Future chains land as sibling subpaths (`/blockchain/<chain>`).
20
+
21
+ Each chain's SDK is an **optional peer dependency** (`@stoachain/*` for `/blockchain/stoachain`), and the adapter imports it lazily — so `npm install @ancientpantheon/khronoton-core` pulls **zero** chain SDKs, and you carry only the SDK(s) for the chain(s) you actually import. It's one package, one version, one drop-in for every automaton. Likewise React is an optional peer for the `/provider`, `/hooks`, and `/ui` subpaths only. Every JS subpath resolves under both import conditions (ESM `import` + CJS `require`); the root `.`, `/server`, and `/handlers` outputs are byte-identical to 0.3.0/0.2.0.
16
22
 
17
23
  ## Schedule engine
18
24
 
@@ -224,6 +230,10 @@ npm install @ancientpantheon/khronoton-core
224
230
 
225
231
  ## Version history
226
232
 
233
+ **v0.4.1** — dependency rename, no code change. Released 2026-07-22. `@stoachain/ouronet-core` → `@ouronet/ouronet-core`. **799 specs pass.**
234
+
235
+ **v0.4.0** — Made khronoton **chain-polyglot**: added the `/blockchain/<chain>` subpath family, starting with `/blockchain/stoachain` (`createStoachainRuntime(config?)` → the core `ChainRuntime` seam, wrapping `@stoachain/*`). Each chain's SDK is an **optional peer dependency** imported lazily, so the package stays zero-SDK on install and a consumer carries only the chains it imports — one package, one drop-in for every automaton, rather than a separate npm package per chain. (This folds in the previously-separate `@ancientpantheon/khronoton-stoachain`, which is removed and was never published.) Root `.`/`/server`/`/handlers` outputs unchanged. React and `@stoachain/*` are optional peers for their respective subpaths only.
236
+
227
237
  **v0.3.0** — Added the complete drop-in **experience layer** on new subpaths, byte-preserving the root `.` and `/server` outputs from 0.2.0: `/handlers` (framework-agnostic HTTP route handlers over the store + executor, behind a tiny request/response seam), `/provider` + `/hooks` (the React data layer — `<KhronotonProvider>`, the 16-method `KhronotonAdapter` seam with `createFetchAdapter`/`createMemoryAdapter` reference adapters, the shared `runGated` confirm-retry, and the data + action hooks), and `/ui` + `/ui.css` (the React UI at full Hub parity — the four screens List, Detail/Observe with the 50/page fire-history pager + definition-drift + result tooltip + pluggable multi-tx renderer + wired recover, the two-pane create/edit Builder with Simulate→AUTO-gas calibrate, and a Public read-only view — themed via `--khr-*` inside `<KhronotonUiRoot>`). Chain specifics stay out of core as the separate `@ancientpantheon/khronoton-stoachain` `ChainRuntime` adapter; core stays zero-runtime-dependency with React an optional peer for the three React subpaths. Every JS subpath resolves under both ESM `import` and CJS `require`.
228
238
 
229
239
  **v0.2.0** — Added the server/automaton engine on the new `@ancientpantheon/khronoton-core/server` subpath (dual ESM `import` + CJS `require`), behind six injection seams (`KeyResolver`, `ChainRuntime`, `Database`, `onAudit`, `resolveFireMode`, `Config`): the store + atomic claim-before-fire (exactly-once, proven end-to-end), the headless single-transaction executor (never-throws-on-fire, dirty-read pre-flight, AUTO-gas calibrate, 504/derived-key recovery), the server tick + `startKhronotonLoop`, the server-resolver registry/dispatcher, and `installSchema` for the three tables — lifted faithfully from the AncientHoldings hub's inline `codex-cronoton` system and generalised. The root `.` schedule engine is unchanged.
@@ -0,0 +1,48 @@
1
+ import { C as ChainRuntime } from '../seams-BvPnTSmg.js';
2
+
3
+ /**
4
+ * `@ancientpantheon/khronoton-core/blockchain/stoachain` — the StoaChain edge.
5
+ *
6
+ * khronoton is chain-POLYGLOT, not chain-agnostic: the root `.` schedule engine
7
+ * and the `/server` tick/store engine orchestrate, and each `/blockchain/<chain>`
8
+ * subpath teaches them to speak one chain's language. This one wraps the
9
+ * `@stoachain/*` runtime into the core {@link ChainRuntime} seam so a StoaChain
10
+ * automaton injects one object instead of reaching for `@stoachain/*` directly.
11
+ *
12
+ * The `@stoachain/*` packages are OPTIONAL PEER DEPENDENCIES: importing this
13
+ * subpath costs nothing (the SDK imports are lazy, inside the factory), so a
14
+ * consumer who never talks StoaChain never installs them. Only calling
15
+ * `createStoachainRuntime()` pulls the SDK — and a StoaChain automaton has it.
16
+ */
17
+ /**
18
+ * Consumer-facing knobs for {@link createStoachainRuntime}. Every field is
19
+ * optional; an omitted field falls back to the corresponding `@stoachain/*`
20
+ * constant. `nodeBaseUrl`, when set, builds a per-chain Pact URL against the
21
+ * consumer's chainweb node; otherwise the runtime uses `constants.getPactUrl`.
22
+ */
23
+ interface StoachainRuntimeConfig {
24
+ /** Consumer chainweb base; when set, builds getPactUrl, else uses constants.getPactUrl. */
25
+ nodeBaseUrl?: string;
26
+ /** Kadena network id; defaults to constants.KADENA_NETWORK. */
27
+ networkId?: string;
28
+ /** Kadena namespace; defaults to ouronetConstants.KADENA_NAMESPACE. */
29
+ namespace?: string;
30
+ /** Gas station account; defaults to ouronetConstants.STOA_AUTONOMIC_OURONETGASSTATION. */
31
+ gasStationAccount?: string;
32
+ }
33
+ /**
34
+ * Builds the {@link ChainRuntime} seam by wrapping the `@stoachain/*` runtime
35
+ * once. Async because `@stoachain/*` are `type:module` ESM: every value is
36
+ * pulled via `await import()` (a static value-import would break CJS `tsx`
37
+ * workers), every type via `import type`.
38
+ *
39
+ * The imports run SEQUENTIALLY, not via `Promise.all`. The `@stoachain/*` ESM
40
+ * modules internally `require()` one another; loading them concurrently races
41
+ * on Node's ESM/CJS interop and throws `ERR_INTERNAL_ASSERTION` ("Cannot
42
+ * require() ES Module ... not yet fully loaded") on Node 24+. Sequential
43
+ * awaits let each module (and its nested requires) fully settle before the next
44
+ * begins. This is a one-time cost at factory creation, so the latency is moot.
45
+ */
46
+ declare function createStoachainRuntime(config?: StoachainRuntimeConfig): Promise<ChainRuntime>;
47
+
48
+ export { type StoachainRuntimeConfig, createStoachainRuntime };
@@ -0,0 +1,27 @@
1
+ // src/blockchain/stoachain.ts
2
+ async function createStoachainRuntime(config) {
3
+ const client = await import('@stoachain/kadena-stoic-legacy/client');
4
+ const signing = await import('@stoachain/stoa-core/signing');
5
+ const gas = await import('@stoachain/stoa-core/gas');
6
+ const constants = await import('@stoachain/stoa-core/constants');
7
+ const ouronetConstants = await import('@ouronet/ouronet-core/constants');
8
+ const networkId = config?.networkId ?? constants.KADENA_NETWORK;
9
+ const namespace = config?.namespace ?? ouronetConstants.KADENA_NAMESPACE;
10
+ const gasStationAccount = config?.gasStationAccount ?? ouronetConstants.STOA_AUTONOMIC_OURONETGASSTATION;
11
+ const nodeBaseUrl = config?.nodeBaseUrl;
12
+ const getPactUrl = nodeBaseUrl ? (chainId) => `${nodeBaseUrl}/chainweb/0.0/${networkId}/chain/${chainId}/pact` : constants.getPactUrl;
13
+ return {
14
+ Pact: client.Pact,
15
+ createClient: client.createClient,
16
+ isSignedTransaction: client.isSignedTransaction,
17
+ universalSignTransaction: signing.universalSignTransaction,
18
+ calculateAutoGasLimit: gas.calculateAutoGasLimit,
19
+ anuToStoa: gas.anuToStoa,
20
+ getPactUrl,
21
+ networkId,
22
+ namespace,
23
+ gasStationAccount
24
+ };
25
+ }
26
+
27
+ export { createStoachainRuntime };
@@ -1,210 +1,9 @@
1
1
  import { ReactNode } from 'react';
2
2
  import { H as HandlerRequest, h as HandlerResponse, K as KhronotonProviderProps, i as KhronotonAdapter, j as SignerSource } from '../context-BKtdrA2B.js';
3
3
  export { c as CancelBatchView, k as CodexSignerDescriptor, C as CommitBody, a as CommitView, l as ConfirmGate, m as ConfirmOpts, n as DEFAULT_EXPLORER_BASE, o as DEFAULT_PAGE_SIZE, p as DEFAULT_POLL_CADENCE_MS, D as DeleteView, E as EditPatch, b as EditView, d as ExecuteView, F as FiresQuery, q as FiresView, G as GetBatchView, r as GetCronotonView, s as KhronotonConfig, t as KhronotonSnapshot, L as ListCronotonsQuery, v as ListCronotonsView, R as RecoverView, w as RenderMultiTx, g as RuntimeArgs, x as ServerResolverOption, y as SignersView, S as SimulateEnvelope, e as SimulateView, f as StartBatchView, T as ToggleView, U as UseKhronotonResult, z as assertAdapter, A as emptySnapshot, u as useKhronoton } from '../context-BKtdrA2B.js';
4
+ import { D as Database, C as ChainRuntime, K as KeyResolver, R as ResolveFireMode, O as OnAudit, a as Config } from '../seams-BvPnTSmg.js';
4
5
  export { a as CodexCronotonFireRow, C as CodexCronotonRow, M as ManualBatchView } from '../types-u_nUX1Bg.js';
5
6
 
6
- /**
7
- * The six injection seams the server automaton is built against.
8
- *
9
- * Every host-specific capability the Hub executor/store reached for directly
10
- * (`@stoachain/*` runtime, the codex key resolver, the ambient SQLite handle,
11
- * the audit log, the fire-mode signal, the tuning constants) is inverted here
12
- * into a narrow, dependency-free contract the consumer injects. This module
13
- * declares ONLY interfaces, type aliases, and the module-level default
14
- * constants — no orchestration logic. It imports nothing from `@stoachain/*`
15
- * and nothing from `better-sqlite3`; the carrier types
16
- * (`IKadenaKeypair`, `UniversalKeypair`, `IUnsignedCommand`) are genericized
17
- * and declared here so the emitted `.d.ts` carries zero external module
18
- * references.
19
- */
20
- /**
21
- * A resolved signing keypair returned by {@link KeyResolver}.
22
- *
23
- * `privateKey` here is the raw signing secret (hex). Note the field-name
24
- * divergence from {@link UniversalKeypair}, whose equivalent field is
25
- * `secretKey`; a consumer mapping a resolver result into a signer payload must
26
- * copy `privateKey -> secretKey`. `seedType` is genericized to `string`
27
- * (the Hub narrowed it to a `@stoachain` seed-type union). The derived-seed
28
- * WASM-signing path carries `encryptedSecretKey` + `password` through.
29
- */
30
- interface IKadenaKeypair {
31
- publicKey: string;
32
- privateKey: string;
33
- seedType: string;
34
- encryptedSecretKey?: string;
35
- password?: string;
36
- }
37
- /**
38
- * Resolves signer public keys to their keypairs and enumerates the pubkeys the
39
- * backing key store owns. Mirrors the Hub `CodexKeyResolver`: async lookups
40
- * and a `Set<string>` membership view.
41
- */
42
- interface KeyResolver {
43
- /** Resolve a signer public key to its keypair; rejects if not owned. */
44
- getKeyPairByPublicKey(publicKey: string): Promise<IKadenaKeypair>;
45
- /** Enumerate every public key the backing store can sign for. */
46
- listCodexPubs(): Promise<Set<string>>;
47
- /**
48
- * Optional last-resort resolution for a foreign key not in the store. A
49
- * headless consumer with no interactive prompt may omit this or reject
50
- * fast — a signer whose pubkey is unknown then fails at build time.
51
- */
52
- requestForeignKey?(publicKey: string): Promise<string>;
53
- }
54
- /**
55
- * A signer keypair as consumed by {@link ChainRuntime.universalSignTransaction}.
56
- *
57
- * Note `secretKey` here versus `privateKey` on {@link IKadenaKeypair}: the two
58
- * carriers describe the same secret under different field names, so a consumer
59
- * bridging resolver output into a signer must remap the field. `seedType` is
60
- * genericized to `string`.
61
- */
62
- interface UniversalKeypair {
63
- publicKey: string;
64
- secretKey: string;
65
- seedType: string;
66
- encryptedSecretKey?: string;
67
- password?: string;
68
- }
69
- /**
70
- * A genericized unsigned Kadena command (the Hub imported this from
71
- * `@stoachain/kadena-stoic-legacy/types`). Structural shape only, so a real
72
- * Kadena unsigned command satisfies it without pulling the chain dependency.
73
- */
74
- interface IUnsignedCommand {
75
- cmd: string;
76
- hash: string;
77
- sigs: Array<{
78
- sig?: string;
79
- } | undefined>;
80
- }
81
- /** The dirty-read (local simulation) result from {@link ChainRuntime}. */
82
- interface DirtyReadResult {
83
- result: {
84
- status: string;
85
- error?: {
86
- message?: string;
87
- };
88
- data?: unknown;
89
- };
90
- gas?: number;
91
- }
92
- /** The listen (confirmation) result from {@link ChainRuntime}. */
93
- interface ListenResult {
94
- result: {
95
- status: string;
96
- error?: {
97
- message?: string;
98
- };
99
- };
100
- reqKey?: string;
101
- }
102
- /** A network client bound to a single Pact endpoint URL. */
103
- interface ChainClient {
104
- dirtyRead(tx: unknown): Promise<DirtyReadResult>;
105
- submit(tx: unknown): Promise<{
106
- requestKey: string;
107
- }>;
108
- listen(desc: unknown): Promise<ListenResult>;
109
- }
110
- /**
111
- * The chain runtime seam — every `@stoachain/*` runtime value the executor
112
- * reaches for, inverted into one injectable object. Ported from the Hub's
113
- * private `StoachainRuntime` interface, with the ambient constants renamed to
114
- * seam-neutral names: `KADENA_NETWORK -> networkId`,
115
- * `STOA_AUTONOMIC_OURONETGASSTATION -> gasStationAccount`,
116
- * `KADENA_NAMESPACE -> namespace`. Deliberately excludes `pollRequestKeys`
117
- * (the executor confirms via `listen`, never polls).
118
- */
119
- interface ChainRuntime {
120
- Pact: {
121
- builder: {
122
- execution(code: string): unknown;
123
- };
124
- };
125
- createClient(url: string): ChainClient;
126
- isSignedTransaction(tx: unknown): boolean;
127
- universalSignTransaction(tx: IUnsignedCommand, keypairs: UniversalKeypair[]): Promise<unknown>;
128
- calculateAutoGasLimit(gas: number): number;
129
- anuToStoa(anu: number): number;
130
- getPactUrl(chainId: string): string;
131
- networkId: string;
132
- namespace: string;
133
- gasStationAccount: string;
134
- }
135
- /**
136
- * A prepared statement — the subset of the better-sqlite3 `Statement` surface
137
- * the store actually calls. Declared structurally (owned here, NOT re-exported
138
- * from `better-sqlite3`) so the emitted `.d.ts` references no external DB
139
- * module; a real better-sqlite3 `Statement` satisfies it.
140
- */
141
- interface Statement {
142
- run(...params: unknown[]): {
143
- changes: number;
144
- lastInsertRowid: number | bigint;
145
- };
146
- get(...params: unknown[]): unknown;
147
- all(...params: unknown[]): unknown[];
148
- }
149
- /**
150
- * The minimal synchronous SQL handle the store and `installSchema` require —
151
- * `exec` for DDL, `prepare(...)` for parameterized reads/writes. A real
152
- * better-sqlite3 `Database` instance structurally satisfies this, so no
153
- * `better-sqlite3` import (or `@types/better-sqlite3` dependency) leaks into
154
- * the public `/server` surface. `pragma`/`transaction` are intentionally
155
- * omitted — no store function needs them.
156
- */
157
- interface Database {
158
- exec(sql: string): unknown;
159
- prepare(sql: string): Statement;
160
- }
161
- /** The structured event passed to an {@link OnAudit} sink. */
162
- interface AuditEvent {
163
- action: string;
164
- result: string;
165
- targetKind: string;
166
- targetId: string;
167
- detail: unknown;
168
- }
169
- /**
170
- * Audit sink invoked on each mutating action. May be sync or async. The
171
- * default is a no-op: `() => {}` — a consumer wanting an audit trail injects
172
- * its own writer.
173
- */
174
- type OnAudit = (event: AuditEvent) => void | Promise<void>;
175
- /**
176
- * Resolves a cronoton id to its effective fire mode. Strictly SYNCHRONOUS (no
177
- * `Promise` in the union): better-sqlite3 is a synchronous driver and the store
178
- * binds the result directly into the fire-record INSERT. A consumer needing
179
- * async fire-mode resolution pre-resolves before invoking the tick.
180
- *
181
- * The default resolves to `'live'`. A consumer may honor a per-row
182
- * `fire_mode_override = 'live'` first, then fall back to a global signal.
183
- */
184
- type ResolveFireMode = (cronotonId: string) => 'test' | 'live';
185
- /**
186
- * Tuning knobs for the automaton. Every field maps to a module-level default
187
- * constant below; a consumer passes a `Partial<Config>` and each consumer site
188
- * reads `config?.<field> ?? <MODULE_DEFAULT>`, so an injected value takes
189
- * effect and an omitted one falls back.
190
- *
191
- * `gasPriceFloor` and `ttl` are intentionally absent: the Hub never clamped
192
- * gasPrice/ttl (the executor uses the per-cronoton `definition.config` values
193
- * directly), so exposing them as injectable would misrepresent the behavior.
194
- */
195
- interface Config {
196
- tickIntervalMs: number;
197
- listenTimeoutMs: number;
198
- autoGasCeiling: number;
199
- singleTxGasGuard: number;
200
- tickBatchLimit: number;
201
- manualBatch: {
202
- min: number;
203
- max: number;
204
- intervalSeconds: number;
205
- };
206
- }
207
-
208
7
  /**
209
8
  * The per-request handler context + the injectable auth/confirm seam + the two
210
9
  * gate wrappers.
@@ -0,0 +1,203 @@
1
+ /**
2
+ * The six injection seams the server automaton is built against.
3
+ *
4
+ * Every host-specific capability the Hub executor/store reached for directly
5
+ * (`@stoachain/*` runtime, the codex key resolver, the ambient SQLite handle,
6
+ * the audit log, the fire-mode signal, the tuning constants) is inverted here
7
+ * into a narrow, dependency-free contract the consumer injects. This module
8
+ * declares ONLY interfaces, type aliases, and the module-level default
9
+ * constants — no orchestration logic. It imports nothing from `@stoachain/*`
10
+ * and nothing from `better-sqlite3`; the carrier types
11
+ * (`IKadenaKeypair`, `UniversalKeypair`, `IUnsignedCommand`) are genericized
12
+ * and declared here so the emitted `.d.ts` carries zero external module
13
+ * references.
14
+ */
15
+ /**
16
+ * A resolved signing keypair returned by {@link KeyResolver}.
17
+ *
18
+ * `privateKey` here is the raw signing secret (hex). Note the field-name
19
+ * divergence from {@link UniversalKeypair}, whose equivalent field is
20
+ * `secretKey`; a consumer mapping a resolver result into a signer payload must
21
+ * copy `privateKey -> secretKey`. `seedType` is genericized to `string`
22
+ * (the Hub narrowed it to a `@stoachain` seed-type union). The derived-seed
23
+ * WASM-signing path carries `encryptedSecretKey` + `password` through.
24
+ */
25
+ interface IKadenaKeypair {
26
+ publicKey: string;
27
+ privateKey: string;
28
+ seedType: string;
29
+ encryptedSecretKey?: string;
30
+ password?: string;
31
+ }
32
+ /**
33
+ * Resolves signer public keys to their keypairs and enumerates the pubkeys the
34
+ * backing key store owns. Mirrors the Hub `CodexKeyResolver`: async lookups
35
+ * and a `Set<string>` membership view.
36
+ */
37
+ interface KeyResolver {
38
+ /** Resolve a signer public key to its keypair; rejects if not owned. */
39
+ getKeyPairByPublicKey(publicKey: string): Promise<IKadenaKeypair>;
40
+ /** Enumerate every public key the backing store can sign for. */
41
+ listCodexPubs(): Promise<Set<string>>;
42
+ /**
43
+ * Optional last-resort resolution for a foreign key not in the store. A
44
+ * headless consumer with no interactive prompt may omit this or reject
45
+ * fast — a signer whose pubkey is unknown then fails at build time.
46
+ */
47
+ requestForeignKey?(publicKey: string): Promise<string>;
48
+ }
49
+ /**
50
+ * A signer keypair as consumed by {@link ChainRuntime.universalSignTransaction}.
51
+ *
52
+ * Note `secretKey` here versus `privateKey` on {@link IKadenaKeypair}: the two
53
+ * carriers describe the same secret under different field names, so a consumer
54
+ * bridging resolver output into a signer must remap the field. `seedType` is
55
+ * genericized to `string`.
56
+ */
57
+ interface UniversalKeypair {
58
+ publicKey: string;
59
+ secretKey: string;
60
+ seedType: string;
61
+ encryptedSecretKey?: string;
62
+ password?: string;
63
+ }
64
+ /**
65
+ * A genericized unsigned Kadena command (the Hub imported this from
66
+ * `@stoachain/kadena-stoic-legacy/types`). Structural shape only, so a real
67
+ * Kadena unsigned command satisfies it without pulling the chain dependency.
68
+ */
69
+ interface IUnsignedCommand {
70
+ cmd: string;
71
+ hash: string;
72
+ sigs: Array<{
73
+ sig?: string;
74
+ } | undefined>;
75
+ }
76
+ /** The dirty-read (local simulation) result from {@link ChainRuntime}. */
77
+ interface DirtyReadResult {
78
+ result: {
79
+ status: string;
80
+ error?: {
81
+ message?: string;
82
+ };
83
+ data?: unknown;
84
+ };
85
+ gas?: number;
86
+ }
87
+ /** The listen (confirmation) result from {@link ChainRuntime}. */
88
+ interface ListenResult {
89
+ result: {
90
+ status: string;
91
+ error?: {
92
+ message?: string;
93
+ };
94
+ };
95
+ reqKey?: string;
96
+ }
97
+ /** A network client bound to a single Pact endpoint URL. */
98
+ interface ChainClient {
99
+ dirtyRead(tx: unknown): Promise<DirtyReadResult>;
100
+ submit(tx: unknown): Promise<{
101
+ requestKey: string;
102
+ }>;
103
+ listen(desc: unknown): Promise<ListenResult>;
104
+ }
105
+ /**
106
+ * The chain runtime seam — every `@stoachain/*` runtime value the executor
107
+ * reaches for, inverted into one injectable object. Ported from the Hub's
108
+ * private `StoachainRuntime` interface, with the ambient constants renamed to
109
+ * seam-neutral names: `KADENA_NETWORK -> networkId`,
110
+ * `STOA_AUTONOMIC_OURONETGASSTATION -> gasStationAccount`,
111
+ * `KADENA_NAMESPACE -> namespace`. Deliberately excludes `pollRequestKeys`
112
+ * (the executor confirms via `listen`, never polls).
113
+ */
114
+ interface ChainRuntime {
115
+ Pact: {
116
+ builder: {
117
+ execution(code: string): unknown;
118
+ };
119
+ };
120
+ createClient(url: string): ChainClient;
121
+ isSignedTransaction(tx: unknown): boolean;
122
+ universalSignTransaction(tx: IUnsignedCommand, keypairs: UniversalKeypair[]): Promise<unknown>;
123
+ calculateAutoGasLimit(gas: number): number;
124
+ anuToStoa(anu: number): number;
125
+ getPactUrl(chainId: string): string;
126
+ networkId: string;
127
+ namespace: string;
128
+ gasStationAccount: string;
129
+ }
130
+ /**
131
+ * A prepared statement — the subset of the better-sqlite3 `Statement` surface
132
+ * the store actually calls. Declared structurally (owned here, NOT re-exported
133
+ * from `better-sqlite3`) so the emitted `.d.ts` references no external DB
134
+ * module; a real better-sqlite3 `Statement` satisfies it.
135
+ */
136
+ interface Statement {
137
+ run(...params: unknown[]): {
138
+ changes: number;
139
+ lastInsertRowid: number | bigint;
140
+ };
141
+ get(...params: unknown[]): unknown;
142
+ all(...params: unknown[]): unknown[];
143
+ }
144
+ /**
145
+ * The minimal synchronous SQL handle the store and `installSchema` require —
146
+ * `exec` for DDL, `prepare(...)` for parameterized reads/writes. A real
147
+ * better-sqlite3 `Database` instance structurally satisfies this, so no
148
+ * `better-sqlite3` import (or `@types/better-sqlite3` dependency) leaks into
149
+ * the public `/server` surface. `pragma`/`transaction` are intentionally
150
+ * omitted — no store function needs them.
151
+ */
152
+ interface Database {
153
+ exec(sql: string): unknown;
154
+ prepare(sql: string): Statement;
155
+ }
156
+ /** The structured event passed to an {@link OnAudit} sink. */
157
+ interface AuditEvent {
158
+ action: string;
159
+ result: string;
160
+ targetKind: string;
161
+ targetId: string;
162
+ detail: unknown;
163
+ }
164
+ /**
165
+ * Audit sink invoked on each mutating action. May be sync or async. The
166
+ * default is a no-op: `() => {}` — a consumer wanting an audit trail injects
167
+ * its own writer.
168
+ */
169
+ type OnAudit = (event: AuditEvent) => void | Promise<void>;
170
+ /**
171
+ * Resolves a cronoton id to its effective fire mode. Strictly SYNCHRONOUS (no
172
+ * `Promise` in the union): better-sqlite3 is a synchronous driver and the store
173
+ * binds the result directly into the fire-record INSERT. A consumer needing
174
+ * async fire-mode resolution pre-resolves before invoking the tick.
175
+ *
176
+ * The default resolves to `'live'`. A consumer may honor a per-row
177
+ * `fire_mode_override = 'live'` first, then fall back to a global signal.
178
+ */
179
+ type ResolveFireMode = (cronotonId: string) => 'test' | 'live';
180
+ /**
181
+ * Tuning knobs for the automaton. Every field maps to a module-level default
182
+ * constant below; a consumer passes a `Partial<Config>` and each consumer site
183
+ * reads `config?.<field> ?? <MODULE_DEFAULT>`, so an injected value takes
184
+ * effect and an omitted one falls back.
185
+ *
186
+ * `gasPriceFloor` and `ttl` are intentionally absent: the Hub never clamped
187
+ * gasPrice/ttl (the executor uses the per-cronoton `definition.config` values
188
+ * directly), so exposing them as injectable would misrepresent the behavior.
189
+ */
190
+ interface Config {
191
+ tickIntervalMs: number;
192
+ listenTimeoutMs: number;
193
+ autoGasCeiling: number;
194
+ singleTxGasGuard: number;
195
+ tickBatchLimit: number;
196
+ manualBatch: {
197
+ min: number;
198
+ max: number;
199
+ intervalSeconds: number;
200
+ };
201
+ }
202
+
203
+ export type { ChainRuntime as C, Database as D, KeyResolver as K, OnAudit as O, ResolveFireMode as R, Config as a };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ancientpantheon/khronoton-core",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
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",
@@ -36,7 +36,12 @@
36
36
  "import": "./dist/ui/index.js",
37
37
  "require": "./dist/ui/index.js"
38
38
  },
39
- "./ui.css": "./dist/ui.css"
39
+ "./ui.css": "./dist/ui.css",
40
+ "./blockchain/stoachain": {
41
+ "types": "./dist/blockchain/stoachain.d.ts",
42
+ "import": "./dist/blockchain/stoachain.js",
43
+ "require": "./dist/blockchain/stoachain.js"
44
+ }
40
45
  },
41
46
  "files": [
42
47
  "dist",
@@ -54,6 +59,7 @@
54
59
  "build": "tsc -p tsconfig.build.json && tsup && node scripts/bundle-css.mjs",
55
60
  "typecheck": "tsc --noEmit",
56
61
  "test": "vitest run --passWithNoTests",
62
+ "test:integration": "vitest run --config vitest.integration.config.ts",
57
63
  "test:watch": "vitest",
58
64
  "clean": "rimraf dist"
59
65
  },
@@ -68,6 +74,9 @@
68
74
  },
69
75
  "license": "UNLICENSED",
70
76
  "peerDependencies": {
77
+ "@ouronet/ouronet-core": "^4.3.6",
78
+ "@stoachain/kadena-stoic-legacy": "^4.3.6",
79
+ "@stoachain/stoa-core": "^4.3.6",
71
80
  "react": "^18 || ^19",
72
81
  "react-dom": "^18 || ^19"
73
82
  },
@@ -77,6 +86,15 @@
77
86
  },
78
87
  "react-dom": {
79
88
  "optional": true
89
+ },
90
+ "@stoachain/kadena-stoic-legacy": {
91
+ "optional": true
92
+ },
93
+ "@stoachain/stoa-core": {
94
+ "optional": true
95
+ },
96
+ "@stoachain/ouronet-core": {
97
+ "optional": true
80
98
  }
81
99
  },
82
100
  "optionalDependencies": {
@@ -85,6 +103,9 @@
85
103
  "devDependencies": {
86
104
  "@codemirror/state": "^6.5.2",
87
105
  "@codemirror/view": "^6.36.4",
106
+ "@ouronet/ouronet-core": "^4.3.6",
107
+ "@stoachain/kadena-stoic-legacy": "^4.3.6",
108
+ "@stoachain/stoa-core": "^4.3.6",
88
109
  "@testing-library/dom": "^10.4.1",
89
110
  "@testing-library/react": "^16.3.2",
90
111
  "@types/better-sqlite3": "^7.6.13",