@ancientpantheon/khronoton-core 0.2.0 → 0.4.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.
@@ -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 };
@@ -0,0 +1,222 @@
1
+ /**
2
+ * schedule — pure schedule model and timing math for @ancientpantheon/khronoton-core.
3
+ *
4
+ * Public surface:
5
+ * - ScheduleMode (7 literal values)
6
+ * - ScheduleConfig (discriminated union by `.mode`)
7
+ * - InvalidScheduleConfigError (typed reject)
8
+ * - computeNextFire(mode, config, now): Date | null
9
+ * - summariseSchedule(mode, config): string
10
+ *
11
+ * Contract:
12
+ * - TOTAL — a valid (mode, config, now) triple never throws;
13
+ * InvalidScheduleConfigError is reserved for malformed
14
+ * configs. Recurring modes always yield a future Date; the
15
+ * terminal `one-time` mode legitimately yields `null` once
16
+ * its single fire is in the past (a valid result, not an
17
+ * error).
18
+ * - MONOTONIC — for the same RECURRING schedule, later `now` ->
19
+ * equal-or-later next-fire (when both `now`s sit
20
+ * at-or-after the same prior fire). Enforced by the
21
+ * algorithm shape: every recurring mode iterates strictly
22
+ * forward from `now`. (`one-time` is exempt: once spent it
23
+ * returns `null`, which is the monotonic terminal state.)
24
+ * - PURE — no `Math.random`, no `Date.now()`. `now` is the
25
+ * explicit input. Two calls with identical args return
26
+ * identical results.
27
+ *
28
+ * Cron mode (5-field UTC):
29
+ * - Pruned in-tree parser; no `cron-parser` dependency added.
30
+ * - Standard 5-field shape: `minute hour dayOfMonth month dayOfWeek`.
31
+ * - Syntax supported per field:
32
+ * * (any)
33
+ * N (literal int)
34
+ * N,M,... (comma list)
35
+ * N-M (inclusive range)
36
+ * *<NN (step from start)
37
+ * N/M (step from N)
38
+ * - Out of scope (explicitly rejected): `@hourly` / `@daily` macros,
39
+ * seconds field, `L`/`W`/`#` Quartz extensions.
40
+ *
41
+ * The behavior of this engine is locked by the contract suites in
42
+ * `tests/`: schedule-compute-next-fire.test.ts, schedule-extended-modes.test.ts,
43
+ * schedule-new-modes.test.ts, and schedule-cron-dom-dow-or.test.ts.
44
+ */
45
+ type ScheduleMode = 'daily-at-utc' | 'every-n-minutes' | 'weekly' | 'monthly' | 'cron-expression' | 'one-time' | 'several-times-per-day';
46
+ type DailyAtUtcConfig = {
47
+ mode: 'daily-at-utc';
48
+ hours: number[];
49
+ minute: number;
50
+ };
51
+ type EveryNMinutesConfig = {
52
+ mode: 'every-n-minutes';
53
+ startDate: string;
54
+ intervalMinutes: number;
55
+ };
56
+ type WeeklyConfig = {
57
+ mode: 'weekly';
58
+ daysOfWeek: number[];
59
+ hour: number;
60
+ minute: number;
61
+ };
62
+ type MonthlyConfig = {
63
+ mode: 'monthly';
64
+ daysOfMonth: number[];
65
+ hour: number;
66
+ minute: number;
67
+ };
68
+ type CronExpressionConfig = {
69
+ mode: 'cron-expression';
70
+ expression: string;
71
+ };
72
+ type OneTimeConfig = {
73
+ mode: 'one-time';
74
+ /** ISO8601 instant at which the schedule fires exactly once. */
75
+ fireAt: string;
76
+ };
77
+ type SeveralTimesPerDayConfig = {
78
+ mode: 'several-times-per-day';
79
+ /** Per-entry UTC time-of-day; fires at each one, every day. */
80
+ times: {
81
+ hour: number;
82
+ minute: number;
83
+ }[];
84
+ };
85
+ type ScheduleConfig = DailyAtUtcConfig | EveryNMinutesConfig | WeeklyConfig | MonthlyConfig | CronExpressionConfig | OneTimeConfig | SeveralTimesPerDayConfig;
86
+
87
+ /**
88
+ * Shared domain types for the Khronoton server-side executor and store.
89
+ *
90
+ * `CodexTxDefinition` is the single constructed-tx shape every caller
91
+ * (simulate API, manual-fire API, scheduled-fire worker tick) passes to the
92
+ * executor. The result + terminal-intent types are imported by those same
93
+ * callers so the executor stays the single source of truth for the contract.
94
+ *
95
+ * The DB row types + their client-facing projections describe the three
96
+ * server tables (`codex_cronotons`, `codex_cronoton_fires`,
97
+ * `codex_cronoton_manual_batches`). JSON columns are raw strings at the row
98
+ * layer; higher layers parse them into the structured types above.
99
+ */
100
+
101
+ /** Capability scoping for a signer: `pure` (unrestricted) or `scoped` (capped). */
102
+ type CapabilityMode = "pure" | "scoped";
103
+ /** A signer reference — pubkey + how its signature is scoped. Codex-only: no secrets. */
104
+ interface CodexSigner {
105
+ /** 64-hex Ed25519 public key (no `k:` prefix). Must be resolvable by the codex. */
106
+ readonly publicKey: string;
107
+ readonly capabilityMode: CapabilityMode;
108
+ /** Newline-separated capability lines (e.g. `(coin.GAS)`). Empty for pure signers. */
109
+ readonly capabilities: string;
110
+ }
111
+ /** Gas-payer reference: the protocol gas station, or a codex `k:` account. */
112
+ interface CodexGasPayer {
113
+ readonly type: "codex" | "gas-station";
114
+ /** Codex gas-payer pubkey/address (the `k:` is derived). Absent for gas-station. */
115
+ readonly address?: string;
116
+ /**
117
+ * The codex public key that signs the gas station's `DALOS.GAS_PAYER`
118
+ * capability. Required (and only meaningful) for `type:'gas-station'`: the
119
+ * executor synthesizes a scoped GAS_PAYER signer for this key, so the gas
120
+ * station pays while this codex key authorizes the payment. The `coin.GAS`
121
+ * for a codex gas-payer rides on `address`, not here.
122
+ */
123
+ readonly gasStationSignerKey?: string;
124
+ }
125
+ /** Transaction config — chain, gas, ttl. `gasPrice` is in ANU. */
126
+ interface CodexTxConfig {
127
+ readonly chainId: string;
128
+ /** Gas price in ANU (converted to STOA via `anuToStoa` at build time). */
129
+ readonly gasPrice: number;
130
+ readonly gasLimit: number;
131
+ /** When true, the executor calibrates the gas limit from a dirty-read. */
132
+ readonly autoGasLimit: boolean;
133
+ /** Time-to-live in seconds. */
134
+ readonly ttl: number;
135
+ }
136
+ /** The raw `codex_cronotons` row shape (JSON columns are still strings here). */
137
+ interface CodexCronotonRow {
138
+ id: string;
139
+ name: string;
140
+ description: string | null;
141
+ pact_code: string;
142
+ config_json: string;
143
+ payload_json: string | null;
144
+ gas_payer_json: string;
145
+ signers_json: string;
146
+ schedule_mode: ScheduleMode;
147
+ schedule_config_json: string;
148
+ /**
149
+ * Name of the fire-time server payload resolver, or null/absent for ordinary
150
+ * rows. Optional so pre-migration row doubles (test fixtures) typecheck; real
151
+ * rows from `SELECT *` carry the column (value may be null).
152
+ */
153
+ server_resolver?: string | null;
154
+ /**
155
+ * When 1, this cronoton may be fired by the external HMAC endpoint. Optional
156
+ * so pre-migration row doubles (test fixtures) typecheck; real rows carry it.
157
+ */
158
+ external_fireable?: number;
159
+ /**
160
+ * JSON string[] of env-data keys a trigger supplies at fire time; null/absent
161
+ * = an ordinary fixed-definition cronoton. Optional so pre-migration row
162
+ * doubles (test fixtures) typecheck.
163
+ */
164
+ runtime_arg_keys?: string | null;
165
+ status: "active" | "paused" | "completed" | "error";
166
+ next_fire_at: string | null;
167
+ last_fire_at: string | null;
168
+ created_at: string;
169
+ modified_at: string;
170
+ created_by: string;
171
+ }
172
+ /**
173
+ * Launch-state provenance of a fire — 'test' pre-lock, 'live' once the
174
+ * consumer's live state is locked.
175
+ */
176
+ type CodexFireMode = "test" | "live";
177
+ /**
178
+ * One on-chain transaction recorded under a single fire. A multi-tx fire (e.g.
179
+ * a pool payout) spans many: cross-chain burns + SPV continuations + the bulk
180
+ * transfer. The worker appends one of these as each tx lands; the fire history
181
+ * surfaces a count badge that expands to a per-tx explorer link.
182
+ */
183
+ interface FireTxKey {
184
+ /** 'burn' (source→0 initiate) | 'continuation' (SPV step on 0) | 'bulk' (payout transfer). */
185
+ kind: "burn" | "continuation" | "bulk";
186
+ /** Source chain for burn/continuation; '0' for the bulk transfer. */
187
+ chainId: string;
188
+ requestKey: string;
189
+ /** Whether the tx confirmed ok (best-effort; absent = unknown/in-flight). */
190
+ ok?: boolean;
191
+ }
192
+ /** The client-facing projection of a `codex_cronoton_fires` row. */
193
+ interface CodexCronotonFireRow {
194
+ id: string;
195
+ firedAt: string;
196
+ status: "success" | "failure" | "running" | "nothing";
197
+ requestKey: string | null;
198
+ chainId: string | null;
199
+ errorMessage: string | null;
200
+ chainResponse: unknown;
201
+ definitionFingerprint: string | null;
202
+ mode: CodexFireMode;
203
+ /** Timestamp a failed fire was reconciled to success via `recoverFire`; null for natively-successful or never-recovered fires. */
204
+ recoveredAt: string | null;
205
+ /** Per-tx request keys for a multi-tx fire (empty for ordinary single-tx fires). */
206
+ txKeys: FireTxKey[];
207
+ }
208
+ /** Client-facing projection of a batch (progress + schedule). */
209
+ 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
+ }
221
+
222
+ export type { CodexCronotonRow as C, ManualBatchView as M, ScheduleMode as S, CodexCronotonFireRow as a, CodexTxConfig as b, CodexGasPayer as c, CodexSigner as d, ScheduleConfig as e, CodexFireMode as f };
@@ -0,0 +1,235 @@
1
+ import { ReactNode } from 'react';
2
+ import { a as CodexCronotonFireRow, C as CodexCronotonRow, f as CodexFireMode } from '../types-u_nUX1Bg.js';
3
+
4
+ /**
5
+ * The theming boundary. Every Khronoton UI surface renders inside a
6
+ * `<KhronotonUiRoot>` so the `.khronoton-ui` scope carries the `--khr-*`
7
+ * tokens (see `@ancientpantheon/khronoton-core/ui.css`). Components style
8
+ * exclusively via inline `var(--khr-*)` — no Tailwind/utility classes ship.
9
+ *
10
+ * A consumer recolors by overriding the tokens at `body .khronoton-ui`:
11
+ *
12
+ * ```css
13
+ * body .khronoton-ui { --khr-accent: #d4a04a; --khr-bg: #0d0a07; }
14
+ * ```
15
+ */
16
+ interface KhronotonUiRootProps {
17
+ children: ReactNode;
18
+ /** Extra classes merged after the `khronoton-ui` scope class. */
19
+ className?: string;
20
+ }
21
+ declare function KhronotonUiRoot({ children, className }: KhronotonUiRootProps): ReactNode;
22
+
23
+ /**
24
+ * Presentational status/mode atoms for the codex-cronoton surfaces. Every atom
25
+ * styles ONLY via inline `var(--khr-*)` tokens (see `ui.css`); the state → color
26
+ * + label decisions live in the pure `*Style` maps below so they can be unit
27
+ * tested and reused (e.g. a status legend) without mounting React.
28
+ */
29
+ type CronotonStatus = CodexCronotonRow["status"];
30
+ type FireStatus = CodexCronotonFireRow["status"];
31
+ type FireMode = CodexFireMode;
32
+ declare function CronotonStatusBadge({ status, }: {
33
+ status: CronotonStatus;
34
+ }): ReactNode;
35
+ declare function FireStatusBadge({ status }: {
36
+ status: FireStatus;
37
+ }): ReactNode;
38
+ declare function ModeChip({ mode }: {
39
+ mode: FireMode;
40
+ }): ReactNode;
41
+ declare function ServerResolverPill(): ReactNode;
42
+ declare function ExternallyFireablePill(): ReactNode;
43
+
44
+ /**
45
+ * Viewer access model + the pure disable-rule predicates every codex-cronoton
46
+ * screen shares.
47
+ *
48
+ * Auth tier is NOT part of the provider config — the provider carries only the
49
+ * confirm-gate. The host resolves roles and passes the resulting {@link Access}
50
+ * down as a page-level prop; the UI renders tiers. Keeping every "is this action
51
+ * allowed, and why" decision here (pure, exhaustively tested) means no screen
52
+ * re-implements the disable/tooltip precedence in JSX — they consume these
53
+ * predicates and render the `{disabled, title}` verbatim.
54
+ */
55
+
56
+ /** logged-out (public read-only) · non-admin (signed in, cannot mutate) · admin. */
57
+ type AccessTier = "logged-out" | "non-admin" | "admin";
58
+ /** The viewer's tier plus, when signed in, their email (rendered in footers). */
59
+ interface Access {
60
+ readonly tier: AccessTier;
61
+ readonly email?: string;
62
+ }
63
+
64
+ /**
65
+ * `<CronotonList>` — the codex-cronoton LIST screen at Hub parity.
66
+ *
67
+ * A single-card table over `useCronotons()`: the three-tier "+ New" control, the
68
+ * six parity columns (Name · Operation/Schedule · Next fire · Last fire · Status ·
69
+ * Actions), the per-row Edit/Pause↔Resume/Execute-Now/Delete actions gated by the
70
+ * shared `access.ts` disable rules, and the native confirm → gated mutation →
71
+ * SSR-style refetch flow from `confirm-flows.ts`. No sort/filter/search/bulk/
72
+ * refresh-button/toasts — the Hub had none (REQ-L09).
73
+ *
74
+ * Router-agnostic: the host resolves the viewer tier (the `access` prop) and
75
+ * supplies navigation callbacks (`onOpen`/`onEdit`/`onNew`) instead of framework
76
+ * `<Link>`s. Theming is inline `var(--khr-*)` only; the page assembly wraps this in
77
+ * `<KhronotonUiRoot>` (this component renders no theming boundary of its own).
78
+ *
79
+ * ── The "Last fire" status ────────────────────────────────────────────────────
80
+ * The Hub coloured the Last-fire cell from a per-row last-fire-status subquery. The
81
+ * generic `CodexCronotonRow` does not carry that natively (the built-in store
82
+ * projection omits it), so the cell reads an OPTIONAL `last_fire_status` a host read
83
+ * may attach; absent ⇒ the "—" placeholder. See {@link CronotonListRow}.
84
+ */
85
+
86
+ /** The default `robots` policy — the list is publicly readable but not indexable. */
87
+ declare const DEFAULT_LIST_ROBOTS = "noindex,nofollow";
88
+ /**
89
+ * A list row plus the optional last-fire status the host read may attach (the
90
+ * generic {@link CodexCronotonRow} does not model it; see the module note).
91
+ */
92
+ type CronotonListRow = CodexCronotonRow & {
93
+ last_fire_status?: FireStatus | null;
94
+ };
95
+ interface CronotonListProps {
96
+ /** The viewer tier (+ email) the host resolves; drives every disable rule. */
97
+ access: Access;
98
+ /** Open a cronoton's detail/observe screen (the Name link + logged-out view). */
99
+ onOpen?: (id: string) => void;
100
+ /** Navigate to a cronoton's edit screen (admin-only Edit action). */
101
+ onEdit?: (id: string) => void;
102
+ /** Navigate to the create builder (admin-only "+ New Codex Cronoton"). */
103
+ onNew?: () => void;
104
+ /** The page `robots` meta content (REQ-G07); defaults to noindex,nofollow. */
105
+ robots?: string;
106
+ }
107
+ declare function CronotonList({ access, onOpen, onEdit, onNew, robots, }: CronotonListProps): ReactNode;
108
+
109
+ /** The default `robots` policy — the detail page is readable but not indexable. */
110
+ declare const DEFAULT_DETAIL_ROBOTS = "noindex,nofollow";
111
+ interface DetailProps {
112
+ /** The cronoton to observe. */
113
+ id: string;
114
+ /** The viewer tier (+ email) the host resolves; drives every disable rule. */
115
+ access: Access;
116
+ /** Return to the list screen (the back link). */
117
+ onBack?: () => void;
118
+ /** Navigate to this cronoton's edit screen (admin-only Edit action). */
119
+ onEdit?: (id: string) => void;
120
+ /** Navigate back to the list after a successful delete (the row is gone). */
121
+ onNavigateToList?: () => void;
122
+ /** The page `robots` meta content; defaults to noindex,nofollow. */
123
+ robots?: string;
124
+ }
125
+ declare function Detail({ id, access, onBack, onEdit, onNavigateToList, robots, }: DetailProps): ReactNode;
126
+
127
+ /**
128
+ * Builder assembly — the two-pane create/edit form (REQ-B01/B02/B11).
129
+ *
130
+ * This is the single owner of the shared {@link BuilderState}: it hosts the
131
+ * already-built controlled tabs (Config, Payload, Gas Payer, Signatures, Execute)
132
+ * and the Pact editor, wires each tab's `onChange` back into the one state, fetches
133
+ * the signer descriptors exactly once, and routes Commit through the create/edit
134
+ * action hooks (both confirm-gated via `runGated`).
135
+ *
136
+ * onChange contract per tab (the load-bearing detail): every tab EXCEPT Payload
137
+ * emits a full next `BuilderState` (so we pass `setState` directly); `PayloadTab`
138
+ * emits a `PayloadState` slice, which we splice back into the whole state. The tabs
139
+ * are controlled children — nothing owns form state but this component, so a tab
140
+ * switch never loses an edit.
141
+ *
142
+ * Edit mode (`editId`): the persisted row is fetched once and rehydrated through
143
+ * `detailToBuilderState` (payload forced to raw mode, gas price → ANU, signers
144
+ * lossy, schedule preserved, the create-only Row C hidden). Save issues a PATCH via
145
+ * `edit.run` (the patch is the full commit body — `EditPatch = Partial<CommitBody>`)
146
+ * rather than a create POST. On success either path calls `onDone` with the id.
147
+ */
148
+
149
+ /** Default `<meta name="robots">` for the builder route (host-overridable). */
150
+ declare const DEFAULT_BUILDER_ROBOTS = "noindex,nofollow";
151
+ interface BuilderProps {
152
+ /** Present → edit mode: rehydrate this cronoton and PATCH on save. Absent → create. */
153
+ readonly editId?: string;
154
+ /** Viewer tier; the builder is an admin-only surface (the host gates the route). */
155
+ readonly access: Access;
156
+ /** Called with the new/edited id after a successful commit so the host can navigate. */
157
+ readonly onDone?: (id?: string) => void;
158
+ /** Robots directive rendered into `<meta name="robots">`. */
159
+ readonly robots?: string;
160
+ }
161
+ /**
162
+ * The two-pane codex-cronoton builder. Owns `BuilderState`; renders the Pact editor
163
+ * on the left and the header + five-tab bar on the right, feeding every tab the
164
+ * shared state and folding its `onChange` back in.
165
+ */
166
+ declare function Builder({ editId, access: _access, onDone, robots, }: BuilderProps): ReactNode;
167
+
168
+ /**
169
+ * `<Public>` — the read-only public transparency wrapper over `<Detail>`.
170
+ *
171
+ * This is NOT a fork of Detail: it REUSES `<Detail>` with a fixed logged-out
172
+ * access tier. Detail already gates every control on `access` via the shared
173
+ * predicates, so pinning `access.tier` to `"logged-out"` hides all mutation
174
+ * affordances, the `<ManualBatchCard>` and `<RuntimeArgTriggerCard>` self-suppress
175
+ * to null, and the metadata panel + `<FireHistory>` (with Explorer verify links)
176
+ * remain visible — the whole point of a public transparency view. A public
177
+ * viewer's fire-poll hitting a gated JSON route fails silently: the underlying
178
+ * poller already swallows poll errors, so no error UI is (or should be) added.
179
+ *
180
+ * Detail owns the `<meta name="robots">`, so `robots` is only threaded through —
181
+ * never re-rendered here. Around Detail this adds a public chrome: a top bar
182
+ * announcing the read-only nature and an attribution footer reused verbatim from
183
+ * the list's logged-out footer.
184
+ *
185
+ * ## Mount discipline (REQ-PB03)
186
+ * The tree is browser-only — fire pollers and self-refreshing `RelativeTime`
187
+ * timers must NOT be server-rendered. The host mounts `<Public>` through an
188
+ * `ssr:false` dynamic import (or the framework equivalent):
189
+ *
190
+ * ```tsx
191
+ * import dynamic from "next/dynamic";
192
+ *
193
+ * const Public = dynamic(
194
+ * () => import("@ancientpantheon/khronoton-core/ui").then((m) => m.Public),
195
+ * { ssr: false },
196
+ * );
197
+ *
198
+ * export default function PublicCronotonPage({ params }: { params: { id: string } }) {
199
+ * return (
200
+ * <KhronotonProvider adapter={publicAdapter}>
201
+ * <KhronotonUiRoot>
202
+ * <Public id={params.id} />
203
+ * </KhronotonUiRoot>
204
+ * </KhronotonProvider>
205
+ * );
206
+ * }
207
+ * ```
208
+ */
209
+
210
+ /** The default `robots` policy for the public view — readable but not indexable. */
211
+ declare const DEFAULT_PUBLIC_ROBOTS = "noindex,nofollow";
212
+ interface PublicProps {
213
+ /** The cronoton to observe read-only. */
214
+ id: string;
215
+ /** The page `robots` meta content; defaults to noindex,nofollow. */
216
+ robots?: string;
217
+ }
218
+ declare function Public({ id, robots }: PublicProps): ReactNode;
219
+
220
+ interface RelativeTimeProps {
221
+ /** ISO-8601 timestamp to render relative to the current instant. */
222
+ iso: string;
223
+ /** Extra classes merged after the component renders as a `<time>` element. */
224
+ className?: string;
225
+ }
226
+ /**
227
+ * Self-refreshing relative-time label. Re-renders on an interval whose cadence
228
+ * tracks proximity (1s within a minute, 30s otherwise) and tears the interval
229
+ * down on unmount. SSR-safe: no window/timer is touched during a server render —
230
+ * the initial label is computed synchronously and the interval only arms in the
231
+ * browser effect.
232
+ */
233
+ declare function RelativeTime({ iso, className }: RelativeTimeProps): ReactNode;
234
+
235
+ export { type Access, type AccessTier, Builder, type BuilderProps, CronotonList, type CronotonListProps, type CronotonListRow, CronotonStatusBadge, DEFAULT_BUILDER_ROBOTS, DEFAULT_DETAIL_ROBOTS, DEFAULT_LIST_ROBOTS, DEFAULT_PUBLIC_ROBOTS, Detail, type DetailProps, ExternallyFireablePill, FireStatusBadge, KhronotonUiRoot, type KhronotonUiRootProps, CronotonList as List, ModeChip, Public, type PublicProps, RelativeTime, type RelativeTimeProps, ServerResolverPill };