@ancientpantheon/khronoton-core 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +83 -3
  3. package/dist/PactCodeMirror-HQTGE2K3.js +64 -0
  4. package/dist/chunk-DK4CDPXH.js +379 -0
  5. package/dist/chunk-U3F5HEHO.js +1639 -0
  6. package/dist/context-BKtdrA2B.d.ts +363 -0
  7. package/dist/handlers/batch.d.ts +21 -0
  8. package/dist/handlers/batch.js +57 -0
  9. package/dist/handlers/context.d.ts +94 -0
  10. package/dist/handlers/context.js +75 -0
  11. package/dist/handlers/cronoton.d.ts +70 -0
  12. package/dist/handlers/cronoton.js +165 -0
  13. package/dist/handlers/execute.d.ts +30 -0
  14. package/dist/handlers/execute.js +227 -0
  15. package/dist/handlers/http.d.ts +85 -0
  16. package/dist/handlers/http.js +84 -0
  17. package/dist/handlers/index.d.ts +27 -0
  18. package/dist/handlers/index.js +34 -0
  19. package/dist/handlers/read.d.ts +29 -0
  20. package/dist/handlers/read.js +94 -0
  21. package/dist/hooks/index.d.ts +143 -0
  22. package/dist/hooks/index.js +2 -0
  23. package/dist/provider/index.d.ts +421 -0
  24. package/dist/provider/index.js +675 -0
  25. package/dist/server/executor-signers.d.ts +29 -0
  26. package/dist/server/executor-signers.js +60 -0
  27. package/dist/server/executor.d.ts +53 -0
  28. package/dist/server/executor.js +280 -0
  29. package/dist/server/index.d.ts +27 -0
  30. package/dist/server/index.js +51 -0
  31. package/dist/server/loop.d.ts +36 -0
  32. package/dist/server/loop.js +51 -0
  33. package/dist/server/pure/capability.d.ts +31 -0
  34. package/dist/server/pure/capability.js +63 -0
  35. package/dist/server/pure/fingerprint.d.ts +8 -0
  36. package/dist/server/pure/fingerprint.js +44 -0
  37. package/dist/server/pure/runtime-args.d.ts +34 -0
  38. package/dist/server/pure/runtime-args.js +99 -0
  39. package/dist/server/resolvers.d.ts +140 -0
  40. package/dist/server/resolvers.js +200 -0
  41. package/dist/server/schema.d.ts +31 -0
  42. package/dist/server/schema.js +93 -0
  43. package/dist/server/seams.d.ts +231 -0
  44. package/dist/server/seams.js +34 -0
  45. package/dist/server/store/claim.d.ts +59 -0
  46. package/dist/server/store/claim.js +97 -0
  47. package/dist/server/store/cronoton.d.ts +79 -0
  48. package/dist/server/store/cronoton.js +268 -0
  49. package/dist/server/store/errors.d.ts +26 -0
  50. package/dist/server/store/errors.js +40 -0
  51. package/dist/server/store/fires.d.ts +77 -0
  52. package/dist/server/store/fires.js +170 -0
  53. package/dist/server/store/index.d.ts +26 -0
  54. package/dist/server/store/index.js +33 -0
  55. package/dist/server/store/manual-batch.d.ts +38 -0
  56. package/dist/server/store/manual-batch.js +110 -0
  57. package/dist/server/store/mappers.d.ts +21 -0
  58. package/dist/server/store/mappers.js +62 -0
  59. package/dist/server/tick.d.ts +83 -0
  60. package/dist/server/tick.js +235 -0
  61. package/dist/server/types.d.ts +220 -0
  62. package/dist/server/types.js +14 -0
  63. package/dist/types-u_nUX1Bg.d.ts +222 -0
  64. package/dist/ui/index.d.ts +235 -0
  65. package/dist/ui/index.js +3646 -0
  66. package/dist/ui.css +35 -0
  67. package/package.json +64 -5
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Public entry for `@ancientpantheon/khronoton-core/handlers` — the
3
+ * framework-agnostic route surface over the `/server` store + executor. A
4
+ * consumer adapts its framework's request/response into {@link HandlerRequest} /
5
+ * {@link HandlerResponse}, injects a {@link HandlerContext} (db + runtime +
6
+ * resolver + an {@link AuthSeam}), and calls the sixteen handlers below.
7
+ *
8
+ * The read handlers keep their contract names here (aliasing their module's
9
+ * `*Handler` implementations), so the barrel exposes the exact route contract
10
+ * from [PARITY §4]. This entry is React-free and built by `tsc` (not tsup) so it
11
+ * stays importable in any server runtime; it imports no `@stoachain/*` (REQ-P01).
12
+ *
13
+ * Every re-export is `export type` where the symbol is a type, so the emitted
14
+ * `.d.ts` stays fully erasable. Explicit `.js` extensions throughout.
15
+ */
16
+ export { listHandler as listCodexCronotons, getHandler as getCodexCronoton, signersHandler as fetchSigners, firesHandler as fetchFires, } from "./read.js";
17
+ export { commitCodexCronoton, editCodexCronoton, pauseCodexCronoton, resumeCodexCronoton, deleteCodexCronoton, } from "./cronoton.js";
18
+ export type { CommitBody, CommitEnvelope, CommitSchedule } from "./cronoton.js";
19
+ export { simulateCodexTx, executeNow, triggerCronoton, recoverFire } from "./execute.js";
20
+ export { startExecuteBatch, getExecuteBatch, cancelExecuteBatch } from "./batch.js";
21
+ export { json, err, errorBody, mapStoreError } from "./http.js";
22
+ export type { HandlerRequest, HandlerResponse } from "./http.js";
23
+ export { defaultSignerSource, descriptorSourceToDisplay } from "./http.js";
24
+ export type { SignerSource, CodexSignerDescriptor } from "./http.js";
25
+ export { defaultOpenAuth, NeedsConfirmError } from "./context.js";
26
+ export type { Handler, HandlerContext, AuthSeam, AuthIdentity, AuthResult, } from "./context.js";
27
+ export type { ChainRuntime, Config, Database, KeyResolver, OnAudit, ResolveFireMode, } from "./context.js";
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Public entry for `@ancientpantheon/khronoton-core/handlers` — the
3
+ * framework-agnostic route surface over the `/server` store + executor. A
4
+ * consumer adapts its framework's request/response into {@link HandlerRequest} /
5
+ * {@link HandlerResponse}, injects a {@link HandlerContext} (db + runtime +
6
+ * resolver + an {@link AuthSeam}), and calls the sixteen handlers below.
7
+ *
8
+ * The read handlers keep their contract names here (aliasing their module's
9
+ * `*Handler` implementations), so the barrel exposes the exact route contract
10
+ * from [PARITY §4]. This entry is React-free and built by `tsc` (not tsup) so it
11
+ * stays importable in any server runtime; it imports no `@stoachain/*` (REQ-P01).
12
+ *
13
+ * Every re-export is `export type` where the symbol is a type, so the emitted
14
+ * `.d.ts` stays fully erasable. Explicit `.js` extensions throughout.
15
+ */
16
+ // ── Read handlers (TC.2) — aliased to their contract names ────────────────────
17
+ export { listHandler as listCodexCronotons, getHandler as getCodexCronoton, signersHandler as fetchSigners, firesHandler as fetchFires, } from "./read.js";
18
+ // ── Cronoton-lifecycle handlers (TC.3) ────────────────────────────────────────
19
+ export { commitCodexCronoton, editCodexCronoton, pauseCodexCronoton, resumeCodexCronoton, deleteCodexCronoton, } from "./cronoton.js";
20
+ // ── Execution handlers (TC.4) ─────────────────────────────────────────────────
21
+ export { simulateCodexTx, executeNow, triggerCronoton, recoverFire } from "./execute.js";
22
+ // ── Manual-batch handlers (TC.5) ──────────────────────────────────────────────
23
+ export { startExecuteBatch, getExecuteBatch, cancelExecuteBatch } from "./batch.js";
24
+ // ── Kernel contract (TC.1): normalized request/response + helpers ─────────────
25
+ // The request/response shapes plus the response helpers a consumer needs to
26
+ // build its own auth seam, signer source, or error mapping.
27
+ export { json, err, errorBody, mapStoreError } from "./http.js";
28
+ // ── Kernel contract (TC.1): signer descriptor seam (secret-free) ──────────────
29
+ export { defaultSignerSource, descriptorSourceToDisplay } from "./http.js";
30
+ // ── Kernel contract (TC.1): handler context + auth/confirm seam ───────────────
31
+ // The gate wrappers stay module-internal to the handlers; a consumer WIRES the
32
+ // surface with the context type, the injectable auth seam, and the default open
33
+ // (trusted single-tenant) impl.
34
+ export { defaultOpenAuth, NeedsConfirmError } from "./context.js";
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The read-tier route surface: `list`, `get`, `signers`, `fires`. Every one runs
3
+ * behind the READ gate ({@link withRead}) — no fresh-confirm is demanded, so a
4
+ * plain viewer can observe the codex-cronoton state (matching the Hub's
5
+ * SSR-public list/detail). These handlers ORCHESTRATE the `/server` store; they
6
+ * do not reimplement any query.
7
+ *
8
+ * The two pieces of branching that live in THIS layer (not the store) are the
9
+ * defensive query parsing — NaN/garbage falls back to a default, and every value
10
+ * is clamped to the store's own bounds so the echoed page window matches what was
11
+ * used — and the fire page-size default of 50 (REQ-G08/REQ-H07), which overrides
12
+ * the store's own default of 20. The signer projection stays SECRET-FREE
13
+ * (REQ-H10): only `publicKey` + a coarse `display`, never key material.
14
+ */
15
+ import { type HandlerResponse } from "./http.js";
16
+ import { type HandlerContext } from "./context.js";
17
+ import type { HandlerRequest } from "./http.js";
18
+ /** `GET /` — the newest-first cronoton list (store clamps limit 1..200). */
19
+ export declare function listHandler(ctx: HandlerContext, request: HandlerRequest): Promise<HandlerResponse>;
20
+ /** `GET /[id]` — the single cronoton row, or 404 when absent. */
21
+ export declare function getHandler(ctx: HandlerContext, request: HandlerRequest): Promise<HandlerResponse>;
22
+ /** `GET /signers` — the SECRET-FREE signer descriptors (never key material). */
23
+ export declare function signersHandler(ctx: HandlerContext, request: HandlerRequest): Promise<HandlerResponse>;
24
+ /**
25
+ * `GET /[id]/fires?limit&offset` — paginated fire history. The page size defaults
26
+ * to 50 (REQ-G08) — overriding the store's own default of 20 — and both echoed
27
+ * values reflect the window actually queried.
28
+ */
29
+ export declare function firesHandler(ctx: HandlerContext, request: HandlerRequest): Promise<HandlerResponse>;
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The read-tier route surface: `list`, `get`, `signers`, `fires`. Every one runs
3
+ * behind the READ gate ({@link withRead}) — no fresh-confirm is demanded, so a
4
+ * plain viewer can observe the codex-cronoton state (matching the Hub's
5
+ * SSR-public list/detail). These handlers ORCHESTRATE the `/server` store; they
6
+ * do not reimplement any query.
7
+ *
8
+ * The two pieces of branching that live in THIS layer (not the store) are the
9
+ * defensive query parsing — NaN/garbage falls back to a default, and every value
10
+ * is clamped to the store's own bounds so the echoed page window matches what was
11
+ * used — and the fire page-size default of 50 (REQ-G08/REQ-H07), which overrides
12
+ * the store's own default of 20. The signer projection stays SECRET-FREE
13
+ * (REQ-H10): only `publicKey` + a coarse `display`, never key material.
14
+ */
15
+ import { json, err, defaultSignerSource, } from "./http.js";
16
+ import { withRead } from "./context.js";
17
+ import { listCodexCronotons, getCodexCronoton, listFires, } from "../server/index.js";
18
+ /** First scalar of a query value (a repeated key arrives as an array); `undefined` if empty. */
19
+ function firstScalar(raw) {
20
+ const value = Array.isArray(raw) ? raw[0] : raw;
21
+ return value === undefined || value === null || value === "" ? undefined : value;
22
+ }
23
+ /**
24
+ * Parse a query int, falling back to `def` for absent/NaN input, then clamp into
25
+ * `[min, max]`. Clamping in the handler (not only in the store) keeps the echoed
26
+ * `limit`/`offset` equal to the window actually queried.
27
+ */
28
+ function clampInt(raw, { def, min, max }) {
29
+ const scalar = firstScalar(raw);
30
+ const parsed = scalar === undefined ? Number.NaN : Number.parseInt(scalar, 10);
31
+ const base = Number.isNaN(parsed) ? def : parsed;
32
+ const lowerBounded = Math.max(base, min);
33
+ return max === undefined ? lowerBounded : Math.min(lowerBounded, max);
34
+ }
35
+ const CRONOTON_STATUSES = new Set([
36
+ "active",
37
+ "paused",
38
+ "completed",
39
+ "error",
40
+ ]);
41
+ /** Narrow a raw query status to the row union, or `undefined` for an unknown value. */
42
+ function parseStatus(raw) {
43
+ const scalar = firstScalar(raw);
44
+ return scalar !== undefined && CRONOTON_STATUSES.has(scalar)
45
+ ? scalar
46
+ : undefined;
47
+ }
48
+ // ── Handlers ──────────────────────────────────────────────────────────────────
49
+ /** `GET /` — the newest-first cronoton list (store clamps limit 1..200). */
50
+ export async function listHandler(ctx, request) {
51
+ return withRead(ctx, request, async () => {
52
+ const query = request.query ?? {};
53
+ const codexCronotons = listCodexCronotons({
54
+ limit: clampInt(query.limit, { def: 50, min: 1, max: 200 }),
55
+ offset: clampInt(query.offset, { def: 0, min: 0 }),
56
+ status: parseStatus(query.status),
57
+ }, { db: ctx.db });
58
+ return json(200, { ok: true, codexCronotons });
59
+ });
60
+ }
61
+ /** `GET /[id]` — the single cronoton row, or 404 when absent. */
62
+ export async function getHandler(ctx, request) {
63
+ return withRead(ctx, request, async () => {
64
+ const id = request.params?.id ?? "";
65
+ const codexCronoton = getCodexCronoton(id, { db: ctx.db });
66
+ if (!codexCronoton) {
67
+ return err(404, "not found");
68
+ }
69
+ return json(200, { ok: true, codexCronoton });
70
+ });
71
+ }
72
+ /** `GET /signers` — the SECRET-FREE signer descriptors (never key material). */
73
+ export async function signersHandler(ctx, request) {
74
+ return withRead(ctx, request, async () => {
75
+ const source = ctx.signers ?? defaultSignerSource(ctx.resolver);
76
+ const signers = await source.listSignerDescriptors();
77
+ return json(200, { ok: true, signers });
78
+ });
79
+ }
80
+ /**
81
+ * `GET /[id]/fires?limit&offset` — paginated fire history. The page size defaults
82
+ * to 50 (REQ-G08) — overriding the store's own default of 20 — and both echoed
83
+ * values reflect the window actually queried.
84
+ */
85
+ export async function firesHandler(ctx, request) {
86
+ return withRead(ctx, request, async () => {
87
+ const id = request.params?.id ?? "";
88
+ const query = request.query ?? {};
89
+ const limit = clampInt(query.limit, { def: 50, min: 1, max: 100 });
90
+ const offset = clampInt(query.offset, { def: 0, min: 0 });
91
+ const { fires, total } = listFires(id, { limit, offset }, { db: ctx.db });
92
+ return json(200, { ok: true, fires, total, limit, offset });
93
+ });
94
+ }
@@ -0,0 +1,143 @@
1
+ import { L as ListCronotonsQuery, C as CommitBody, a as CommitView, E as EditPatch, b as EditView, T as ToggleView, D as DeleteView, c as CancelBatchView, d as ExecuteView, R as RecoverView, S as SimulateEnvelope, e as SimulateView, f as StartBatchView, g as RuntimeArgs } from '../context-BKtdrA2B.js';
2
+ export { U as UseKhronotonResult, u as useKhronoton } from '../context-BKtdrA2B.js';
3
+ import { C as CodexCronotonRow, a as CodexCronotonFireRow, M as ManualBatchView } from '../types-u_nUX1Bg.js';
4
+ import 'react';
5
+
6
+ /** The `useCronotons()` return shape — the list, its load state, and a refetch. */
7
+ interface UseCronotonsView {
8
+ cronotons: CodexCronotonRow[];
9
+ loading: boolean;
10
+ error: Error | null;
11
+ /** Re-run the load (SSR-style refresh the action hooks call after a mutation). */
12
+ refetch: () => Promise<void>;
13
+ }
14
+ declare function useCronotons(query?: ListCronotonsQuery): UseCronotonsView;
15
+
16
+ /** The `useCronoton()` return shape — the row, its load state, and a refetch. */
17
+ interface UseCronotonView {
18
+ cronoton: CodexCronotonRow | null;
19
+ loading: boolean;
20
+ error: Error | null;
21
+ /** Re-run the load (SSR-style refresh the action hooks call after a mutation). */
22
+ refetch: () => Promise<void>;
23
+ }
24
+ declare function useCronoton(id: string): UseCronotonView;
25
+
26
+ interface UseCronotonFiresOptions {
27
+ /** Overrides the provider's page size (default 50) for this history view. */
28
+ pageSize?: number;
29
+ }
30
+ interface UseCronotonFiresResult {
31
+ fires: CodexCronotonFireRow[];
32
+ total: number;
33
+ page: number;
34
+ pageCount: number;
35
+ loading: boolean;
36
+ error: Error | null;
37
+ setPage: (page: number) => void;
38
+ refetch: () => void;
39
+ }
40
+ declare function useCronotonFires(id: string, opts?: UseCronotonFiresOptions): UseCronotonFiresResult;
41
+
42
+ /** The `useManualBatch` return surface the Phase-E detail view consumes. */
43
+ interface UseManualBatchResult {
44
+ /** The current batch projection, or `null` when the cronoton has no active batch. */
45
+ batch: ManualBatchView | null;
46
+ /** `true` while a batch is running — the poller-live / show-progress flag. */
47
+ active: boolean;
48
+ /** `true` from mount until the first explicit load settles. */
49
+ loading: boolean;
50
+ /** An explicit-load failure (mount or `refetch`); poll failures never set this. */
51
+ error: Error | null;
52
+ /** Re-read the batch on demand (e.g. after a start/cancel action elsewhere). */
53
+ refetch: () => Promise<void>;
54
+ }
55
+ declare function useManualBatch(id: string): UseManualBatchResult;
56
+
57
+ /** A successful action: the adapter body, untouched. */
58
+ interface ActionOk<T> {
59
+ ok: true;
60
+ result: T;
61
+ }
62
+ /** A failed action: a cancelled re-confirm, a second expiry, or a transport error. */
63
+ interface ActionFail {
64
+ ok: false;
65
+ error: Error;
66
+ }
67
+ /** The envelope every `run` resolves to — the host branches on `ok`. */
68
+ type ActionResult<T> = ActionOk<T> | ActionFail;
69
+ /** One lifecycle action's public surface. */
70
+ interface GatedAction<Args extends unknown[], T> {
71
+ run: (...args: Args) => Promise<ActionResult<T>>;
72
+ pending: boolean;
73
+ error: Error | null;
74
+ result: T | null;
75
+ }
76
+ type CreateAction = GatedAction<[CommitBody], CommitView>;
77
+ type EditAction = GatedAction<[EditPatch], EditView>;
78
+ type ToggleAction = GatedAction<[], ToggleView>;
79
+ type DeleteAction = GatedAction<[], DeleteView>;
80
+ /** The bundle `useCronotonActions` returns. */
81
+ interface CronotonActions {
82
+ create: CreateAction;
83
+ edit: EditAction;
84
+ pause: ToggleAction;
85
+ resume: ToggleAction;
86
+ remove: DeleteAction;
87
+ }
88
+ interface UseCronotonActionsOptions {
89
+ /** Fired after any successful mutation — the host's SSR-style refetch hook. */
90
+ onSuccess?: () => void;
91
+ }
92
+ /**
93
+ * The lifecycle action bundle. Pass the detail-page `id` to scope
94
+ * edit/pause/resume/remove to that cronoton; `create` needs no id. Every action
95
+ * is confirm-gated with the shared retry-once re-prompt.
96
+ */
97
+ declare function useCronotonActions(id?: string, options?: UseCronotonActionsOptions): CronotonActions;
98
+
99
+ /**
100
+ * The shared execution-action result. `run` performs the action and returns the
101
+ * adapter body on success (or `undefined` when the call threw), while `pending`,
102
+ * `error`, and `result` mirror the last invocation for render.
103
+ */
104
+ interface UseExecuteActionResult<TArgs extends unknown[], TView> {
105
+ /** Perform the action; resolves the adapter body, or `undefined` on a thrown error. */
106
+ run: (...args: TArgs) => Promise<TView | undefined>;
107
+ /** True while `run` is in flight. */
108
+ pending: boolean;
109
+ /** A transport/confirm failure (a thrown path). Never set for a 200-on-`ok:false` body. */
110
+ error: Error | null;
111
+ /** The last successful adapter body — including a fire-level `{ ok:false }`. */
112
+ result?: TView;
113
+ }
114
+ /** Fire a cronoton once, right now, outside its schedule (confirm-gated). */
115
+ declare function useExecuteNow(): UseExecuteActionResult<[id: string], ExecuteView>;
116
+ /** Fire a cronoton now with supplied runtime args (confirm-gated). */
117
+ declare function useTrigger(): UseExecuteActionResult<[
118
+ id: string,
119
+ args: RuntimeArgs
120
+ ], ExecuteView>;
121
+ /** Preview a tx build/gas without firing it (confirm-gated; full union returned). */
122
+ declare function useSimulate(): UseExecuteActionResult<[
123
+ envelope: SimulateEnvelope
124
+ ], SimulateView>;
125
+ /** Start a manual execute-batch of `count` fires (confirm-gated). */
126
+ declare function useStartBatch(): UseExecuteActionResult<[
127
+ id: string,
128
+ count: number
129
+ ], StartBatchView>;
130
+ /**
131
+ * Cancel the active manual batch — CONFIRM-FREE (REQ-H09). Deliberately bypasses
132
+ * `runGated`: a runaway batch must halt in one click, never blocked on a
133
+ * confirm-gate expiry.
134
+ */
135
+ declare function useCancelBatch(): UseExecuteActionResult<[id: string], CancelBatchView>;
136
+ /** Reconcile a stale failed fire against the chain (confirm-gated; REQ-G09). */
137
+ declare function useRecoverFire(): UseExecuteActionResult<[
138
+ id: string,
139
+ fireId: string,
140
+ requestKey: string
141
+ ], RecoverView>;
142
+
143
+ export { type ActionFail, type ActionOk, type ActionResult, type CreateAction, type CronotonActions, type DeleteAction, type EditAction, type GatedAction, type ToggleAction, type UseCronotonActionsOptions, type UseCronotonFiresOptions, type UseCronotonFiresResult, type UseCronotonView, type UseCronotonsView, type UseExecuteActionResult, type UseManualBatchResult, useCancelBatch, useCronoton, useCronotonActions, useCronotonFires, useCronotons, useExecuteNow, useManualBatch, useRecoverFire, useSimulate, useStartBatch, useTrigger };
@@ -0,0 +1,2 @@
1
+ export { useCancelBatch, useCronoton, useCronotonActions, useCronotonFires, useCronotons, useExecuteNow, useManualBatch, useRecoverFire, useSimulate, useStartBatch, useTrigger } from '../chunk-DK4CDPXH.js';
2
+ export { useKhronoton } from '../chunk-U3F5HEHO.js';