@ancientpantheon/khronoton-core 0.11.0 → 0.13.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 +36 -0
- package/README.md +114 -0
- package/dist/blockchain/stoachain.d.ts +1 -1
- package/dist/blockchain/stoachain.js +16 -1
- package/dist/{chunk-LX6T2BDL.js → chunk-7H5TM3CS.js} +1 -1
- package/dist/{chunk-GNQ2IVXA.js → chunk-IAK4UEAA.js} +731 -24
- package/dist/{context-89YS4xT3.d.ts → context-P-rCtBbJ.d.ts} +2 -2
- package/dist/handlers/execute.d.ts +12 -4
- package/dist/handlers/execute.js +42 -5
- package/dist/handlers/index.d.ts +4 -2
- package/dist/handlers/index.js +7 -2
- package/dist/handlers/public.d.ts +41 -0
- package/dist/handlers/public.js +78 -0
- package/dist/handlers/read.d.ts +11 -0
- package/dist/handlers/read.js +65 -1
- package/dist/handlers/steps.d.ts +3 -0
- package/dist/handlers/steps.js +115 -0
- package/dist/hooks/index.d.ts +4 -4
- package/dist/hooks/index.js +2 -2
- package/dist/provider/index.d.ts +4 -4
- package/dist/provider/index.js +33 -2
- package/dist/{seams-DUtxDw_U.d.ts → seams-Co8Tq4ka.d.ts} +24 -0
- package/dist/server/executor.d.ts +14 -1
- package/dist/server/executor.js +144 -26
- package/dist/server/index.d.ts +11 -2
- package/dist/server/index.js +29 -1
- package/dist/server/loop.d.ts +17 -13
- package/dist/server/loop.js +19 -12
- package/dist/server/planners/evict.d.ts +20 -0
- package/dist/server/planners/evict.js +143 -0
- package/dist/server/planners/inject.d.ts +22 -0
- package/dist/server/planners/inject.js +120 -0
- package/dist/server/planners/registry.d.ts +80 -0
- package/dist/server/planners/registry.js +50 -0
- package/dist/server/planners/stoa-unwrap.d.ts +23 -0
- package/dist/server/planners/stoa-unwrap.js +204 -0
- package/dist/server/planners/stoa-wrap.d.ts +22 -0
- package/dist/server/planners/stoa-wrap.js +201 -0
- package/dist/server/planners/unstall.d.ts +25 -0
- package/dist/server/planners/unstall.js +135 -0
- package/dist/server/pure/run-advance.d.ts +76 -0
- package/dist/server/pure/run-advance.js +94 -0
- package/dist/server/pure/split-plan.d.ts +144 -0
- package/dist/server/pure/split-plan.js +362 -0
- package/dist/server/resolvers.js +48 -6
- package/dist/server/runs-driver.d.ts +92 -0
- package/dist/server/runs-driver.js +511 -0
- package/dist/server/schema.d.ts +12 -2
- package/dist/server/schema.js +105 -1
- package/dist/server/seams.d.ts +28 -0
- package/dist/server/seams.js +4 -0
- package/dist/server/store/errors.d.ts +38 -0
- package/dist/server/store/errors.js +61 -0
- package/dist/server/store/fires.js +27 -1
- package/dist/server/store/index.d.ts +8 -2
- package/dist/server/store/index.js +8 -2
- package/dist/server/store/mappers.d.ts +11 -0
- package/dist/server/store/mappers.js +20 -0
- package/dist/server/store/public.d.ts +104 -0
- package/dist/server/store/public.js +197 -0
- package/dist/server/store/runs.d.ts +233 -0
- package/dist/server/store/runs.js +341 -0
- package/dist/server/store/steps.d.ts +42 -0
- package/dist/server/store/steps.js +51 -0
- package/dist/server/tick.d.ts +7 -0
- package/dist/server/tick.js +50 -1
- package/dist/server/types.d.ts +55 -3
- package/dist/{types-DnFB1Yz-.d.ts → types-uYSglFrJ.d.ts} +13 -0
- package/dist/ui/index.d.ts +1 -1
- package/dist/ui/index.js +2 -2
- package/package.json +1 -1
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* split-plan — the generic gas-probe-and-pack algorithm, ported faithfully
|
|
3
|
+
* from OuroborosNetwork's OuronetUI (`src/lib/signing/measureSplit.ts`;
|
|
4
|
+
* `evenSplit` from its `@ouronet/papyrus` dependency,
|
|
5
|
+
* `node_modules/@ouronet/papyrus/dist/batch.js`). Full rationale in
|
|
6
|
+
* `docs/work/khronoton-chained-runs-phase-4.1/design.md` §B.
|
|
7
|
+
*
|
|
8
|
+
* Given N items and a way to probe a candidate batch's real gas cost, this
|
|
9
|
+
* produces the fewest batches that each fit under a ceiling, using at most
|
|
10
|
+
* two cheap probes to SIZE the job (never probing the full selection, which
|
|
11
|
+
* the real source's own comments document as the exact call a node times
|
|
12
|
+
* out on) plus a small, strictly-bounded number of probes to CONFIRM and
|
|
13
|
+
* then tighten the plan. No DB, no chain client, no I/O — pure and
|
|
14
|
+
* dependency-free, following `run-advance.ts`/`capability.ts`'s convention
|
|
15
|
+
* of keeping types local to the module that owns them.
|
|
16
|
+
*
|
|
17
|
+
* Deliberately NOT ported (per design.md §B): `onProgress` callbacks (UI
|
|
18
|
+
* decoration) and the source's own "give up and submit one unmeasured
|
|
19
|
+
* giant batch anyway" fallback — a failure here is a plain `{ok:false,
|
|
20
|
+
* reason, ...}` return, never a thrown error and never a silently-accepted
|
|
21
|
+
* oversized batch. The caller decides what to do with it.
|
|
22
|
+
*/
|
|
23
|
+
export interface SplitModel {
|
|
24
|
+
/** Gas a transaction costs before any item is processed. Clamped to >= 0. */
|
|
25
|
+
fixed: number;
|
|
26
|
+
/** Marginal gas per item. Clamped to > 0. */
|
|
27
|
+
perItem: number;
|
|
28
|
+
}
|
|
29
|
+
/** What a probe of one candidate batch came back with. A refusal still
|
|
30
|
+
* carries information: `floor` is the gas the chain reported before
|
|
31
|
+
* stopping, a lower bound (never a total) on the true cost. */
|
|
32
|
+
export type ProbeOutcome = {
|
|
33
|
+
ok: true;
|
|
34
|
+
gas: number;
|
|
35
|
+
} | {
|
|
36
|
+
ok: false;
|
|
37
|
+
floor: number | null;
|
|
38
|
+
};
|
|
39
|
+
export type SplitSizing = {
|
|
40
|
+
ok: true;
|
|
41
|
+
/** The whole selection fits in ONE transaction. MEASURED, not modelled. */
|
|
42
|
+
fitsInOne: boolean;
|
|
43
|
+
/** The measured gas of the whole selection — non-null only when `fitsInOne`. */
|
|
44
|
+
measuredGas: number | null;
|
|
45
|
+
/** `fixed + perItem * n`: what one transaction would cost. Modelled unless `fitsInOne`. */
|
|
46
|
+
estimatedTotalGas: number;
|
|
47
|
+
/** How many transactions a split is expected to need. Modelled; planning may differ. */
|
|
48
|
+
estimatedTransactions: number;
|
|
49
|
+
model: SplitModel;
|
|
50
|
+
probes: number;
|
|
51
|
+
/** Carried into `planFromSizing` so the two probes are not paid for twice. */
|
|
52
|
+
readings: {
|
|
53
|
+
one: {
|
|
54
|
+
n: number;
|
|
55
|
+
gas: number;
|
|
56
|
+
};
|
|
57
|
+
sample: {
|
|
58
|
+
n: number;
|
|
59
|
+
gas: number;
|
|
60
|
+
};
|
|
61
|
+
};
|
|
62
|
+
} | {
|
|
63
|
+
ok: false;
|
|
64
|
+
reason: string;
|
|
65
|
+
/** Set when a SINGLE item already busts the ceiling — no split can fix that. */
|
|
66
|
+
infeasible?: {
|
|
67
|
+
singleItemGas: number;
|
|
68
|
+
ceiling: number;
|
|
69
|
+
};
|
|
70
|
+
estimatedTotalGas?: number;
|
|
71
|
+
probes: number;
|
|
72
|
+
};
|
|
73
|
+
export type SplitResult<T> = {
|
|
74
|
+
ok: true;
|
|
75
|
+
/** In-selection-order slices; concatenating them reproduces the selection exactly. */
|
|
76
|
+
batches: T[][];
|
|
77
|
+
/** MEASURED gas of the largest batch in `batches` — not an estimate, not a total. */
|
|
78
|
+
worstBatchGas: number;
|
|
79
|
+
/** `fixed + perItem * n` for the whole selection — an ESTIMATE, labelled as one. */
|
|
80
|
+
estimatedTotalGas: number;
|
|
81
|
+
model: SplitModel;
|
|
82
|
+
probes: number;
|
|
83
|
+
} | {
|
|
84
|
+
ok: false;
|
|
85
|
+
reason: string;
|
|
86
|
+
infeasible?: {
|
|
87
|
+
singleItemGas: number;
|
|
88
|
+
ceiling: number;
|
|
89
|
+
};
|
|
90
|
+
estimatedTotalGas?: number;
|
|
91
|
+
probes: number;
|
|
92
|
+
};
|
|
93
|
+
/** Fit the exact line through two points, clamped to a physically meaningful model. */
|
|
94
|
+
export declare function lineThrough(a: {
|
|
95
|
+
n: number;
|
|
96
|
+
gas: number;
|
|
97
|
+
}, b: {
|
|
98
|
+
n: number;
|
|
99
|
+
gas: number;
|
|
100
|
+
}): SplitModel;
|
|
101
|
+
/**
|
|
102
|
+
* Items one transaction can carry under `ceiling`, per `model`, with a
|
|
103
|
+
* safety margin. Pass `CONFIRMED_MARGIN` (0.99) when the model has been
|
|
104
|
+
* refitted through a real measurement at the size being planned — see
|
|
105
|
+
* that constant's own doc for why the two margins differ.
|
|
106
|
+
*/
|
|
107
|
+
export declare function capacityFor(model: SplitModel, ceiling: number, margin?: number): number;
|
|
108
|
+
/**
|
|
109
|
+
* Split `items` into `count` batches as EQUAL as possible — the first
|
|
110
|
+
* `items.length % count` batches absorb one extra item each, never "full
|
|
111
|
+
* chunks plus a near-empty remainder" (a near-empty last batch is one more
|
|
112
|
+
* signature for almost nothing). Exact port of `@ouronet/papyrus`'s
|
|
113
|
+
* `evenSplit` (`dist/batch.js`).
|
|
114
|
+
*/
|
|
115
|
+
export declare function evenSplit<T>(items: readonly T[], count: number): T[][];
|
|
116
|
+
/**
|
|
117
|
+
* STAGE 1 — size the work. At most two probes, both bounded in size, never
|
|
118
|
+
* the full selection: probe 1 item (fixed-cost reading), then probe
|
|
119
|
+
* `min(n, SAMPLE_SIZE)` items (slope reading). `fitsInOne` is the one
|
|
120
|
+
* claim here that is MEASURED rather than modelled: true only when the
|
|
121
|
+
* sample call covered the whole selection and it came back under ceiling.
|
|
122
|
+
*/
|
|
123
|
+
export declare function measureSize<T>(items: readonly T[], probe: (batch: readonly T[]) => Promise<ProbeOutcome>, ceiling: number): Promise<SplitSizing>;
|
|
124
|
+
/**
|
|
125
|
+
* STAGE 2 — turn a sizing into a confirmed plan. Takes the sizing rather
|
|
126
|
+
* than re-deriving it, so the two cheap probes `measureSize` already spent
|
|
127
|
+
* are not paid for twice; `probes` continues from `sizing.probes`.
|
|
128
|
+
*/
|
|
129
|
+
export declare function planFromSizing<T>(items: readonly T[], sizing: Extract<SplitSizing, {
|
|
130
|
+
ok: true;
|
|
131
|
+
}>, probe: (batch: readonly T[]) => Promise<ProbeOutcome>, ceiling: number): Promise<SplitResult<T>>;
|
|
132
|
+
/**
|
|
133
|
+
* Measure the selection and return the split, in one call — the ONE
|
|
134
|
+
* function any planner in this codebase actually needs. `measureSize`/
|
|
135
|
+
* `planFromSizing` stay exported separately only because the ported
|
|
136
|
+
* source itself exports them separately (and splitting them keeps each
|
|
137
|
+
* stage independently testable); the two-stage split exists in the
|
|
138
|
+
* source only to let a human approve between sizing and planning, which
|
|
139
|
+
* has no equivalent for a headless automaton here (design.md §B).
|
|
140
|
+
*
|
|
141
|
+
* Never throws for a probe failure — every failure path returns
|
|
142
|
+
* `{ok: false, reason, ...}`. The caller decides what to do with it.
|
|
143
|
+
*/
|
|
144
|
+
export declare function splitPlan<T>(items: readonly T[], probe: (batch: readonly T[]) => Promise<ProbeOutcome>, ceiling: number): Promise<SplitResult<T>>;
|
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* split-plan — the generic gas-probe-and-pack algorithm, ported faithfully
|
|
3
|
+
* from OuroborosNetwork's OuronetUI (`src/lib/signing/measureSplit.ts`;
|
|
4
|
+
* `evenSplit` from its `@ouronet/papyrus` dependency,
|
|
5
|
+
* `node_modules/@ouronet/papyrus/dist/batch.js`). Full rationale in
|
|
6
|
+
* `docs/work/khronoton-chained-runs-phase-4.1/design.md` §B.
|
|
7
|
+
*
|
|
8
|
+
* Given N items and a way to probe a candidate batch's real gas cost, this
|
|
9
|
+
* produces the fewest batches that each fit under a ceiling, using at most
|
|
10
|
+
* two cheap probes to SIZE the job (never probing the full selection, which
|
|
11
|
+
* the real source's own comments document as the exact call a node times
|
|
12
|
+
* out on) plus a small, strictly-bounded number of probes to CONFIRM and
|
|
13
|
+
* then tighten the plan. No DB, no chain client, no I/O — pure and
|
|
14
|
+
* dependency-free, following `run-advance.ts`/`capability.ts`'s convention
|
|
15
|
+
* of keeping types local to the module that owns them.
|
|
16
|
+
*
|
|
17
|
+
* Deliberately NOT ported (per design.md §B): `onProgress` callbacks (UI
|
|
18
|
+
* decoration) and the source's own "give up and submit one unmeasured
|
|
19
|
+
* giant batch anyway" fallback — a failure here is a plain `{ok:false,
|
|
20
|
+
* reason, ...}` return, never a thrown error and never a silently-accepted
|
|
21
|
+
* oversized batch. The caller decides what to do with it.
|
|
22
|
+
*/
|
|
23
|
+
/** The size of the second sizing sample — large enough that the slope
|
|
24
|
+
* reading isn't swamped by measurement noise on the fixed cost, small
|
|
25
|
+
* enough that the probe is an ordinary, cheap batch. Clamped down to `n`
|
|
26
|
+
* when the selection is smaller, in which case this single probe also
|
|
27
|
+
* settles the whole question (see `measureSize`'s `fitsInOne` check). */
|
|
28
|
+
const SAMPLE_SIZE = 64;
|
|
29
|
+
/** Plan for this fraction of the ceiling when the model is still an
|
|
30
|
+
* EXTRAPOLATED two-point fit (probe(1), probe(<=64)) — the line carries
|
|
31
|
+
* real extrapolation error when stretched to a batch an order of
|
|
32
|
+
* magnitude larger, and a cheap margin is the fix. */
|
|
33
|
+
const PLANNING_MARGIN = 0.92;
|
|
34
|
+
/** How many times the confirmation probe may refuse before planFromSizing
|
|
35
|
+
* gives up on this capacity. */
|
|
36
|
+
const MAX_CONFIRMATIONS = 3;
|
|
37
|
+
/** Capacity shrink applied after each refused confirmation. A refusal
|
|
38
|
+
* carries no usable magnitude (execution halts AT the declared limit, so
|
|
39
|
+
* the reported floor UNDER-states the true cost) — shrinking by a
|
|
40
|
+
* constant factor rather than refitting is the honest response. */
|
|
41
|
+
const SHRINK = 0.75;
|
|
42
|
+
/** The margin applied ONCE the model has been refitted through a
|
|
43
|
+
* confirmed batch measured at the size actually being planned — a
|
|
44
|
+
* different, tighter margin for a different (anchored, not
|
|
45
|
+
* extrapolated) model. */
|
|
46
|
+
const CONFIRMED_MARGIN = 0.99;
|
|
47
|
+
/** How many times the plan may be refitted upward from a confirmed
|
|
48
|
+
* measurement. A growth probe that is refused, or comes back over
|
|
49
|
+
* ceiling, leaves the last confirmed plan standing — growth can never
|
|
50
|
+
* make the answer worse. */
|
|
51
|
+
const MAX_GROWTHS = 2;
|
|
52
|
+
/** Fit the exact line through two points, clamped to a physically meaningful model. */
|
|
53
|
+
export function lineThrough(a, b) {
|
|
54
|
+
if (a.n === b.n) {
|
|
55
|
+
// No slope is determined by two readings at the same size. The only
|
|
56
|
+
// honest reading left is a through-the-origin rate, which OVER-states
|
|
57
|
+
// the marginal cost and so UNDER-states capacity — conservative in the
|
|
58
|
+
// direction that cannot produce a refused transaction.
|
|
59
|
+
return { fixed: 0, perItem: Math.max(a.gas / Math.max(a.n, 1), Number.MIN_VALUE) };
|
|
60
|
+
}
|
|
61
|
+
const slope = (b.gas - a.gas) / (b.n - a.n);
|
|
62
|
+
if (!(slope > 0)) {
|
|
63
|
+
// A non-positive slope is noise. The honest conservative reading of two
|
|
64
|
+
// measurements that do not increase is the HIGHEST observed rate
|
|
65
|
+
// through the origin: it over-states the marginal cost, so the plan
|
|
66
|
+
// has more transactions than it needs, which costs signatures rather
|
|
67
|
+
// than a refused transaction.
|
|
68
|
+
const rate = Math.max(a.gas / Math.max(a.n, 1), b.gas / Math.max(b.n, 1));
|
|
69
|
+
return { fixed: 0, perItem: Math.max(rate, Number.MIN_VALUE) };
|
|
70
|
+
}
|
|
71
|
+
const fixed = a.gas - slope * a.n;
|
|
72
|
+
return { fixed: Math.max(0, fixed), perItem: slope };
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Items one transaction can carry under `ceiling`, per `model`, with a
|
|
76
|
+
* safety margin. Pass `CONFIRMED_MARGIN` (0.99) when the model has been
|
|
77
|
+
* refitted through a real measurement at the size being planned — see
|
|
78
|
+
* that constant's own doc for why the two margins differ.
|
|
79
|
+
*/
|
|
80
|
+
export function capacityFor(model, ceiling, margin = PLANNING_MARGIN) {
|
|
81
|
+
const room = ceiling * margin - model.fixed;
|
|
82
|
+
return room <= 0 ? 0 : Math.floor(room / model.perItem);
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Split `items` into `count` batches as EQUAL as possible — the first
|
|
86
|
+
* `items.length % count` batches absorb one extra item each, never "full
|
|
87
|
+
* chunks plus a near-empty remainder" (a near-empty last batch is one more
|
|
88
|
+
* signature for almost nothing). Exact port of `@ouronet/papyrus`'s
|
|
89
|
+
* `evenSplit` (`dist/batch.js`).
|
|
90
|
+
*/
|
|
91
|
+
export function evenSplit(items, count) {
|
|
92
|
+
const n = items.length;
|
|
93
|
+
const batches = Math.max(1, Math.min(count, n || 1));
|
|
94
|
+
if (n === 0)
|
|
95
|
+
return [[]];
|
|
96
|
+
const base = Math.floor(n / batches);
|
|
97
|
+
const extra = n % batches; // the first `extra` batches absorb one extra item each
|
|
98
|
+
const out = [];
|
|
99
|
+
let i = 0;
|
|
100
|
+
for (let b = 0; b < batches; b++) {
|
|
101
|
+
const size = base + (b < extra ? 1 : 0);
|
|
102
|
+
out.push(items.slice(i, i + size));
|
|
103
|
+
i += size;
|
|
104
|
+
}
|
|
105
|
+
return out;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* STAGE 1 — size the work. At most two probes, both bounded in size, never
|
|
109
|
+
* the full selection: probe 1 item (fixed-cost reading), then probe
|
|
110
|
+
* `min(n, SAMPLE_SIZE)` items (slope reading). `fitsInOne` is the one
|
|
111
|
+
* claim here that is MEASURED rather than modelled: true only when the
|
|
112
|
+
* sample call covered the whole selection and it came back under ceiling.
|
|
113
|
+
*/
|
|
114
|
+
export async function measureSize(items, probe, ceiling) {
|
|
115
|
+
const n = items.length;
|
|
116
|
+
let probes = 0;
|
|
117
|
+
const run = async (batch) => {
|
|
118
|
+
probes++;
|
|
119
|
+
return probe(batch);
|
|
120
|
+
};
|
|
121
|
+
if (n === 0) {
|
|
122
|
+
return {
|
|
123
|
+
ok: true,
|
|
124
|
+
fitsInOne: true,
|
|
125
|
+
measuredGas: 0,
|
|
126
|
+
estimatedTotalGas: 0,
|
|
127
|
+
estimatedTransactions: 1,
|
|
128
|
+
model: { fixed: 0, perItem: 0 },
|
|
129
|
+
probes: 0,
|
|
130
|
+
readings: { one: { n: 0, gas: 0 }, sample: { n: 0, gas: 0 } },
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
// 1] ONE ITEM — the fixed cost. Without this point the only line
|
|
134
|
+
// available passes through the origin, which charges every item a
|
|
135
|
+
// share of the per-transaction overhead and systematically
|
|
136
|
+
// under-splits. The single cheapest call the operation has.
|
|
137
|
+
const one = await run(items.slice(0, 1));
|
|
138
|
+
if (!one.ok) {
|
|
139
|
+
return {
|
|
140
|
+
ok: false,
|
|
141
|
+
probes,
|
|
142
|
+
reason: "a single item could not be simulated" +
|
|
143
|
+
(one.floor != null ? ` (the chain stopped at ${one.floor.toLocaleString()} gas)` : "") +
|
|
144
|
+
".",
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
if (one.gas > ceiling) {
|
|
148
|
+
return {
|
|
149
|
+
ok: false,
|
|
150
|
+
probes,
|
|
151
|
+
estimatedTotalGas: one.gas * n,
|
|
152
|
+
infeasible: { singleItemGas: one.gas, ceiling },
|
|
153
|
+
reason: `one item alone costs ${one.gas.toLocaleString()} gas, over the ` +
|
|
154
|
+
`${ceiling.toLocaleString()} a transaction may use. No split can fix that — ` +
|
|
155
|
+
`this operation needs a multi-step route.`,
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
// A one-item selection is already answered — and it is a MEASUREMENT,
|
|
159
|
+
// not a model.
|
|
160
|
+
if (n === 1) {
|
|
161
|
+
return {
|
|
162
|
+
ok: true,
|
|
163
|
+
fitsInOne: true,
|
|
164
|
+
measuredGas: one.gas,
|
|
165
|
+
estimatedTotalGas: one.gas,
|
|
166
|
+
estimatedTransactions: 1,
|
|
167
|
+
model: { fixed: 0, perItem: one.gas },
|
|
168
|
+
probes,
|
|
169
|
+
readings: { one: { n: 1, gas: one.gas }, sample: { n: 1, gas: one.gas } },
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
// 2] A SAMPLE BATCH — the slope. Capped at SAMPLE_SIZE so this probe is
|
|
173
|
+
// always an ordinary batch, never the full selection.
|
|
174
|
+
const sampleN = Math.min(n, SAMPLE_SIZE);
|
|
175
|
+
const sample = await run(items.slice(0, sampleN));
|
|
176
|
+
if (!sample.ok) {
|
|
177
|
+
return {
|
|
178
|
+
ok: false,
|
|
179
|
+
probes,
|
|
180
|
+
reason: `a ${sampleN}-item sample could not be simulated` +
|
|
181
|
+
(sample.floor != null ? ` (the chain stopped at ${sample.floor.toLocaleString()} gas)` : "") +
|
|
182
|
+
". Try a smaller selection.",
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
const model = lineThrough({ n: 1, gas: one.gas }, { n: sampleN, gas: sample.gas });
|
|
186
|
+
const estimatedTotalGas = Math.round(model.fixed + model.perItem * n);
|
|
187
|
+
const readings = { one: { n: 1, gas: one.gas }, sample: { n: sampleN, gas: sample.gas } };
|
|
188
|
+
// THE WHOLE SELECTION ALREADY FITS, and the sample proves it when the
|
|
189
|
+
// sample IS the selection.
|
|
190
|
+
if (sampleN === n && sample.gas <= ceiling) {
|
|
191
|
+
return {
|
|
192
|
+
ok: true,
|
|
193
|
+
fitsInOne: true,
|
|
194
|
+
measuredGas: sample.gas,
|
|
195
|
+
estimatedTotalGas,
|
|
196
|
+
estimatedTransactions: 1,
|
|
197
|
+
model,
|
|
198
|
+
probes,
|
|
199
|
+
readings,
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
const capacity = capacityFor(model, ceiling);
|
|
203
|
+
if (capacity < 1) {
|
|
204
|
+
return {
|
|
205
|
+
ok: false,
|
|
206
|
+
probes,
|
|
207
|
+
estimatedTotalGas,
|
|
208
|
+
infeasible: { singleItemGas: one.gas, ceiling },
|
|
209
|
+
reason: `the fixed cost of one transaction (about ` +
|
|
210
|
+
`${Math.round(model.fixed).toLocaleString()} gas) leaves no room under the ` +
|
|
211
|
+
`${ceiling.toLocaleString()} limit. This operation needs a multi-step route.`,
|
|
212
|
+
};
|
|
213
|
+
}
|
|
214
|
+
return {
|
|
215
|
+
ok: true,
|
|
216
|
+
fitsInOne: false,
|
|
217
|
+
measuredGas: null,
|
|
218
|
+
estimatedTotalGas,
|
|
219
|
+
estimatedTransactions: Math.max(1, Math.ceil(n / capacity)),
|
|
220
|
+
model,
|
|
221
|
+
probes,
|
|
222
|
+
readings,
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* STAGE 2 — turn a sizing into a confirmed plan. Takes the sizing rather
|
|
227
|
+
* than re-deriving it, so the two cheap probes `measureSize` already spent
|
|
228
|
+
* are not paid for twice; `probes` continues from `sizing.probes`.
|
|
229
|
+
*/
|
|
230
|
+
export async function planFromSizing(items, sizing, probe, ceiling) {
|
|
231
|
+
const n = items.length;
|
|
232
|
+
let probes = sizing.probes;
|
|
233
|
+
const { model, estimatedTotalGas } = sizing;
|
|
234
|
+
const one = sizing.readings.one;
|
|
235
|
+
const run = async (batch) => {
|
|
236
|
+
probes++;
|
|
237
|
+
return probe(batch);
|
|
238
|
+
};
|
|
239
|
+
let capacity = capacityFor(model, ceiling);
|
|
240
|
+
if (capacity < 1) {
|
|
241
|
+
return {
|
|
242
|
+
ok: false,
|
|
243
|
+
probes,
|
|
244
|
+
estimatedTotalGas,
|
|
245
|
+
infeasible: { singleItemGas: one.gas, ceiling },
|
|
246
|
+
reason: `the fixed cost of one transaction (about ` +
|
|
247
|
+
`${Math.round(model.fixed).toLocaleString()} gas) leaves no room under the ` +
|
|
248
|
+
`${ceiling.toLocaleString()} limit. This operation needs a multi-step route.`,
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
/** Cut the selection at a capacity and name the batch whose measurement describes the plan. */
|
|
252
|
+
const planAt = (cap) => {
|
|
253
|
+
const count = Math.max(1, Math.ceil(n / Math.max(1, cap)));
|
|
254
|
+
const batches = evenSplit(items, count);
|
|
255
|
+
const first = batches[0];
|
|
256
|
+
if (first === undefined)
|
|
257
|
+
return null;
|
|
258
|
+
return { batches, largest: batches.reduce((a, b) => (b.length > a.length ? b : a), first) };
|
|
259
|
+
};
|
|
260
|
+
// CONFIRM THE PLAN ACTUALLY BEING RETURNED — the largest batch of the
|
|
261
|
+
// exact split handed back, so `worstBatchGas` describes this plan, not a
|
|
262
|
+
// nearby batch measured on the way.
|
|
263
|
+
let best = null;
|
|
264
|
+
for (let attempt = 0; attempt < MAX_CONFIRMATIONS; attempt++) {
|
|
265
|
+
const planned = planAt(capacity);
|
|
266
|
+
if (!planned) {
|
|
267
|
+
return { ok: false, probes, estimatedTotalGas, reason: "the split produced no batches." };
|
|
268
|
+
}
|
|
269
|
+
const got = await run(planned.largest);
|
|
270
|
+
if (got.ok && got.gas <= ceiling) {
|
|
271
|
+
best = { batches: planned.batches, gas: got.gas, size: planned.largest.length };
|
|
272
|
+
break;
|
|
273
|
+
}
|
|
274
|
+
// Refused or over. The line under-estimated; shrink capacity and try
|
|
275
|
+
// once more. A refusal carries no usable magnitude, which is why this
|
|
276
|
+
// shrinks by a constant rather than refitting.
|
|
277
|
+
const shrunk = Math.floor(capacity * SHRINK);
|
|
278
|
+
if (shrunk < 1 || shrunk === capacity)
|
|
279
|
+
break;
|
|
280
|
+
capacity = shrunk;
|
|
281
|
+
}
|
|
282
|
+
if (!best) {
|
|
283
|
+
return {
|
|
284
|
+
ok: false,
|
|
285
|
+
probes,
|
|
286
|
+
estimatedTotalGas,
|
|
287
|
+
reason: `could not confirm a batch size under ${ceiling.toLocaleString()} gas after ` +
|
|
288
|
+
`${probes} simulation(s). Try a smaller selection.`,
|
|
289
|
+
};
|
|
290
|
+
}
|
|
291
|
+
// PACK TIGHTER. The line from stage 1 is fitted at n=1 and n<=64 and
|
|
292
|
+
// extrapolated to the operating size, which is why PLANNING_MARGIN
|
|
293
|
+
// exists; stage 2 has just measured a real batch AT the planned size — a
|
|
294
|
+
// point the fit never had, and the only point that actually matters.
|
|
295
|
+
// Refitting through it replaces an extrapolation with an anchor, so the
|
|
296
|
+
// margin can step aside for CONFIRMED_MARGIN. This can never make the
|
|
297
|
+
// answer worse: `best` only ever advances on a confirmed measurement
|
|
298
|
+
// under ceiling, so a refused or over-ceiling growth probe just breaks
|
|
299
|
+
// the loop and leaves the previously confirmed plan exactly as it was.
|
|
300
|
+
let fitted = model;
|
|
301
|
+
for (let growth = 0; growth < MAX_GROWTHS; growth++) {
|
|
302
|
+
fitted = lineThrough({ n: 1, gas: one.gas }, { n: best.size, gas: best.gas });
|
|
303
|
+
const grown = capacityFor(fitted, ceiling, CONFIRMED_MARGIN);
|
|
304
|
+
if (grown <= best.size)
|
|
305
|
+
break;
|
|
306
|
+
const planned = planAt(grown);
|
|
307
|
+
// Fewer BATCHES is the only gain worth a probe. A larger capacity that
|
|
308
|
+
// still rounds to the same transaction count buys nothing.
|
|
309
|
+
if (!planned || planned.batches.length >= best.batches.length)
|
|
310
|
+
break;
|
|
311
|
+
const got = await run(planned.largest);
|
|
312
|
+
if (!got.ok || got.gas > ceiling)
|
|
313
|
+
break;
|
|
314
|
+
best = { batches: planned.batches, gas: got.gas, size: planned.largest.length };
|
|
315
|
+
}
|
|
316
|
+
return {
|
|
317
|
+
ok: true,
|
|
318
|
+
batches: best.batches,
|
|
319
|
+
worstBatchGas: best.gas,
|
|
320
|
+
// Reported from the REFITTED line: it is anchored at the operating
|
|
321
|
+
// size, so it is a better estimate of the whole job than the
|
|
322
|
+
// small-sample line that produced the first plan.
|
|
323
|
+
estimatedTotalGas: Math.round(fitted.fixed + fitted.perItem * n),
|
|
324
|
+
model: fitted,
|
|
325
|
+
probes,
|
|
326
|
+
};
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Measure the selection and return the split, in one call — the ONE
|
|
330
|
+
* function any planner in this codebase actually needs. `measureSize`/
|
|
331
|
+
* `planFromSizing` stay exported separately only because the ported
|
|
332
|
+
* source itself exports them separately (and splitting them keeps each
|
|
333
|
+
* stage independently testable); the two-stage split exists in the
|
|
334
|
+
* source only to let a human approve between sizing and planning, which
|
|
335
|
+
* has no equivalent for a headless automaton here (design.md §B).
|
|
336
|
+
*
|
|
337
|
+
* Never throws for a probe failure — every failure path returns
|
|
338
|
+
* `{ok: false, reason, ...}`. The caller decides what to do with it.
|
|
339
|
+
*/
|
|
340
|
+
export async function splitPlan(items, probe, ceiling) {
|
|
341
|
+
const sizing = await measureSize(items, probe, ceiling);
|
|
342
|
+
if (!sizing.ok) {
|
|
343
|
+
return {
|
|
344
|
+
ok: false,
|
|
345
|
+
probes: sizing.probes,
|
|
346
|
+
reason: sizing.reason,
|
|
347
|
+
estimatedTotalGas: sizing.estimatedTotalGas,
|
|
348
|
+
infeasible: sizing.infeasible,
|
|
349
|
+
};
|
|
350
|
+
}
|
|
351
|
+
if (sizing.fitsInOne) {
|
|
352
|
+
return {
|
|
353
|
+
ok: true,
|
|
354
|
+
batches: [[...items]],
|
|
355
|
+
worstBatchGas: sizing.measuredGas ?? 0,
|
|
356
|
+
estimatedTotalGas: sizing.estimatedTotalGas,
|
|
357
|
+
model: sizing.model,
|
|
358
|
+
probes: sizing.probes,
|
|
359
|
+
};
|
|
360
|
+
}
|
|
361
|
+
return planFromSizing(items, sizing, probe, ceiling);
|
|
362
|
+
}
|
package/dist/server/resolvers.js
CHANGED
|
@@ -77,21 +77,63 @@ export async function dispatchMultiTxResolver(name, opts) {
|
|
|
77
77
|
function postponed(error) {
|
|
78
78
|
return { ok: false, mode: "fire", error, terminalIntent: null };
|
|
79
79
|
}
|
|
80
|
+
/**
|
|
81
|
+
* Coerce a batch's `ok` field (typed `unknown` — the orchestrator's return
|
|
82
|
+
* shape is consumer-defined, see `MultiTxResolver.run`'s own doc) to a real
|
|
83
|
+
* boolean, or `undefined` for "does not meaningfully report." A strict
|
|
84
|
+
* `typeof === "boolean"` check alone would silently treat a batch reporting
|
|
85
|
+
* failure via a non-boolean value (the string `"false"`, `0`) as "didn't
|
|
86
|
+
* report," defeating the whole point of honoring `ok` — but `Boolean(value)`
|
|
87
|
+
* alone is ALSO wrong here, because `Boolean("false")` is `true` (any
|
|
88
|
+
* non-empty string is truthy in JS). Recognized: real booleans, the
|
|
89
|
+
* case-insensitive strings `"true"`/`"false"`, and numbers (`0` is `false`,
|
|
90
|
+
* anything else `true`). Anything else (`null`, an object, an unrecognized
|
|
91
|
+
* string) is treated as "does not report," falling back to the pre-existing
|
|
92
|
+
* `ok`-less behavior for that one batch.
|
|
93
|
+
*/
|
|
94
|
+
function toReportedOk(value) {
|
|
95
|
+
if (typeof value === "boolean")
|
|
96
|
+
return value;
|
|
97
|
+
if (typeof value === "number")
|
|
98
|
+
return value !== 0;
|
|
99
|
+
if (typeof value === "string") {
|
|
100
|
+
const lower = value.toLowerCase();
|
|
101
|
+
if (lower === "true")
|
|
102
|
+
return true;
|
|
103
|
+
if (lower === "false")
|
|
104
|
+
return false;
|
|
105
|
+
}
|
|
106
|
+
return undefined;
|
|
107
|
+
}
|
|
80
108
|
/**
|
|
81
109
|
* Adapt a multi-tx orchestrator's run summary to a {@link FireResult} so the tick
|
|
82
|
-
* records one observable fire row for the run.
|
|
83
|
-
* the
|
|
84
|
-
*
|
|
85
|
-
*
|
|
110
|
+
* records one observable fire row for the run. The summary is stashed in
|
|
111
|
+
* `rawResult` and the first batch's request key (when present) is surfaced so the
|
|
112
|
+
* fire row links to the on-chain batch.
|
|
113
|
+
*
|
|
114
|
+
* Strictly-additive, opt-in contract on `ok`: a batch that carries no
|
|
115
|
+
* meaningfully-reporting `ok` value behaves exactly as before — it's assumed
|
|
116
|
+
* to have completed, so a summary whose batches are all `ok`-less (or there
|
|
117
|
+
* are no batches at all) adapts to `ok:true`. A batch that DOES report `ok`
|
|
118
|
+
* (via {@link toReportedOk}) is honored: the adapted result is `ok:true`
|
|
119
|
+
* only if every reporting batch reports `true`; otherwise it's `ok:false`
|
|
120
|
+
* with a descriptive error naming how many of the reporting batches failed.
|
|
86
121
|
*/
|
|
87
122
|
function adaptMultiTxSummary(summary) {
|
|
88
123
|
const s = (summary ?? {});
|
|
89
|
-
const
|
|
124
|
+
const batches = Array.isArray(s.batches) ? s.batches : [];
|
|
125
|
+
const firstBatchKey = batches.length > 0 ? batches[0]?.requestKey : undefined;
|
|
126
|
+
const reported = batches
|
|
127
|
+
.map((b) => toReportedOk(b.ok))
|
|
128
|
+
.filter((v) => v !== undefined);
|
|
129
|
+
const ok = reported.length === 0 ? true : reported.every((v) => v === true);
|
|
130
|
+
const failedCount = reported.filter((v) => v === false).length;
|
|
90
131
|
return {
|
|
91
|
-
ok
|
|
132
|
+
ok,
|
|
92
133
|
mode: "fire",
|
|
93
134
|
requestKey: firstBatchKey,
|
|
94
135
|
rawResult: summary,
|
|
136
|
+
error: ok ? undefined : `${failedCount} of ${reported.length} reporting batch(es) failed`,
|
|
95
137
|
terminalIntent: null,
|
|
96
138
|
};
|
|
97
139
|
}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The non-blocking chained-run driver — executes Phase 2's pure `advanceRun`
|
|
3
|
+
* decision function against the real store/chain, per
|
|
4
|
+
* `docs/work/khronoton-chained-runs-phase-3/design.md` §D/§F.
|
|
5
|
+
*
|
|
6
|
+
* `driveRunOnce` is a SINGLE-RUN, loop-until-no-progress pass: it repeatedly
|
|
7
|
+
* (1) reads the run + its current step + that step's legs, (2) calls the pure
|
|
8
|
+
* `advanceRun` to decide what happens next, and (3) executes the returned
|
|
9
|
+
* `RunAction`s against the store/executor — re-reading fresh state and
|
|
10
|
+
* calling `advanceRun` again after every mutating action, stopping only once
|
|
11
|
+
* a pass makes NO further store write (a `poll` that landed nothing new, a
|
|
12
|
+
* `submit-leg` that failed, or the defensive `wait`), the run/step vanishes,
|
|
13
|
+
* or an action throws.
|
|
14
|
+
*
|
|
15
|
+
* This internal looping is deliberate, not incidental: `advanceRun` itself
|
|
16
|
+
* documents its own terminal-run check (step 1) as "defends against a driver
|
|
17
|
+
* that calls advanceRun on a run it should have already stopped touching" —
|
|
18
|
+
* i.e. the pure function already anticipates being re-invoked, within one
|
|
19
|
+
* driver pass, on a run this SAME pass just terminalized. It is also the only
|
|
20
|
+
* way to satisfy design.md §B's requirement that a freshly created run's step
|
|
21
|
+
* 0 gets "planned-and-submitted" — i.e. both `replan-step` (build leg 0) AND
|
|
22
|
+
* `submit-leg` (submit it) — within the SAME tick pass that created the run,
|
|
23
|
+
* rather than waiting a full `tickIntervalMs` for the next
|
|
24
|
+
* `advanceInFlightRunsOnce` pass to notice the freshly-built leg.
|
|
25
|
+
*
|
|
26
|
+
* `advanceInFlightRunsOnce` is the scheduler-facing sweep: every in-flight
|
|
27
|
+
* run, one `driveRunOnce` each, same per-row isolation posture
|
|
28
|
+
* `codexCronotonTickOnce` already applies (one run's failure never blocks the
|
|
29
|
+
* others).
|
|
30
|
+
*
|
|
31
|
+
* Deliberately does NOT import anything from `./tick.js` or `./loop.js` —
|
|
32
|
+
* both of those import FROM this module in a later wave of this same phase;
|
|
33
|
+
* importing `TickCtx` here instead of declaring the structurally-compatible
|
|
34
|
+
* `RunsDriverCtx` below would create a circular import.
|
|
35
|
+
*/
|
|
36
|
+
import type { ChainRuntime, Config, Database, KeyResolver, OnAudit } from "./seams.js";
|
|
37
|
+
/**
|
|
38
|
+
* The injected context `driveRunOnce`/`advanceInFlightRunsOnce` run against —
|
|
39
|
+
* a structural SUBSET of `tick.ts`'s `TickCtx` (same `db`/`runtime`/
|
|
40
|
+
* `resolver`/`onAudit`/`config` shape, `TickCtx` just adds `resolveFireMode`
|
|
41
|
+
* on top), so a real `TickCtx` satisfies this interface already and needs no
|
|
42
|
+
* conversion at either of this phase's tick/loop call sites.
|
|
43
|
+
*/
|
|
44
|
+
export interface RunsDriverCtx {
|
|
45
|
+
db: Database;
|
|
46
|
+
runtime: ChainRuntime;
|
|
47
|
+
resolver: KeyResolver;
|
|
48
|
+
onAudit: OnAudit;
|
|
49
|
+
config?: Partial<Config>;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Thrown by `driveRunOnce` when a `mode: 'planner'` step names a
|
|
53
|
+
* `planner_name` that `resolvePlannerFor` cannot resolve — e.g. a typo, or a
|
|
54
|
+
* planner that genuinely hasn't been registered yet. The `StepPlanner`
|
|
55
|
+
* registry itself (`planners/registry.ts`) and its real planners
|
|
56
|
+
* (`ouronet.aqp-evict`/`ouronet.aqp-inject`/`ouronet.aqp-unstall`) are fully
|
|
57
|
+
* built; this error reports an unresolved NAME against that registry, not a
|
|
58
|
+
* missing registry mechanism.
|
|
59
|
+
*/
|
|
60
|
+
export declare class PlannerNotRegisteredError extends Error {
|
|
61
|
+
constructor(plannerName: string);
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Drive one run forward as far as it will synchronously go this pass — see
|
|
65
|
+
* the module doc above for why this loops internally rather than making a
|
|
66
|
+
* single `advanceRun` call. Returns once the run/current step vanishes (both
|
|
67
|
+
* defensive no-ops) or a pass makes no further progress.
|
|
68
|
+
*/
|
|
69
|
+
export declare function driveRunOnce(runId: string, now: Date, ctx: RunsDriverCtx): Promise<void>;
|
|
70
|
+
/** Result of one {@link advanceInFlightRunsOnce} sweep. */
|
|
71
|
+
export interface AdvanceRunsResult {
|
|
72
|
+
/** Run ids successfully driven (possibly a no-op pass) this sweep. */
|
|
73
|
+
drivenIds: string[];
|
|
74
|
+
/** Run ids whose `driveRunOnce` call threw — isolated, not re-thrown. */
|
|
75
|
+
erroredIds: string[];
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Sweep every in-flight run, driving each forward one `driveRunOnce` pass.
|
|
79
|
+
* Per-run `try`/`catch` isolation — one run's thrown error (including
|
|
80
|
+
* `PlannerNotRegisteredError`) never blocks the others — mirrors
|
|
81
|
+
* `codexCronotonTickOnce`'s own per-row isolation posture.
|
|
82
|
+
*
|
|
83
|
+
* `excludeRunIds`, when given, skips those runs entirely this sweep. This
|
|
84
|
+
* exists so `loop.ts` can pass the run ids `codexCronotonTickOnce` already
|
|
85
|
+
* drove inline this SAME pass (design.md §B's "plan-and-submit step 0
|
|
86
|
+
* within one tick pass," built by calling `driveRunOnce` directly from the
|
|
87
|
+
* tick) — without it, a freshly created run would be driven twice in one
|
|
88
|
+
* loop callback: once inline by the tick, once again by this sweep moments
|
|
89
|
+
* later, doubling `pollRequestKeys` traffic for no benefit (the inline call
|
|
90
|
+
* already drove it as far as it would synchronously go).
|
|
91
|
+
*/
|
|
92
|
+
export declare function advanceInFlightRunsOnce(now: Date, ctx: RunsDriverCtx, excludeRunIds?: ReadonlySet<string>): Promise<AdvanceRunsResult>;
|