ckb-cycle-tools 1.2.0 → 1.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.
package/dist/diff.d.ts CHANGED
@@ -17,6 +17,61 @@ export interface CycleReport {
17
17
  * fails on these, from either side.
18
18
  */
19
19
  errors?: string[];
20
+ /**
21
+ * What the numbers were measured with (1.3.0 and later). A diff checks the two
22
+ * sides' manifests: changed scenario inputs, another debugger, another CKB-VM.
23
+ */
24
+ manifest?: ReportManifest;
25
+ }
26
+ /**
27
+ * A reproducibility manifest. Every string in it can come from a pull request
28
+ * (a path in its cycles.json, the toolchain its build printed): whatever shows
29
+ * it cleans it as any other report text.
30
+ */
31
+ export interface ReportManifest {
32
+ /** This object's layout. */
33
+ schema: 1;
34
+ /** The package that wrote the report, e.g. `{ name: "ckb-cycle-tools", version: "1.3.0" }`. */
35
+ tool: {
36
+ name: string;
37
+ version: string;
38
+ };
39
+ debugger: {
40
+ /** `--version`, as the report's `debugger`. */
41
+ version: string;
42
+ /** The native binary every scenario ran, and its sha256. */
43
+ path?: string;
44
+ sha256?: string;
45
+ /** For a WebAssembly build: its id (the sha256 of the .wasm). */
46
+ wasm?: string;
47
+ };
48
+ /** The commit checked out where the cycles.json is, and where the binaries came from with --binaries-from. */
49
+ git?: {
50
+ commit?: string;
51
+ binaries?: string;
52
+ };
53
+ /** Free text the caller gave (`--toolchain`): the compiler and build profile, e.g. `rustc -V`. */
54
+ toolchain?: string;
55
+ scenarios: ScenarioManifest[];
56
+ }
57
+ export interface ScenarioManifest {
58
+ name: string;
59
+ /** The CKB-VM version the scenario's `hash_type: "type"` scripts ran on. */
60
+ scriptVersion?: number;
61
+ /**
62
+ * sha256 over what decides what the scenario runs: its cycles.json entry
63
+ * (canonical, without its name or file path) and its mock or transaction file
64
+ * as read. Two reports with the same scenario name and a different hash did
65
+ * not measure the same thing.
66
+ */
67
+ inputs?: string;
68
+ /** The binaries swapped in, as read: the path the config gives, sha256, size in bytes. */
69
+ binaries?: {
70
+ name: string;
71
+ path: string;
72
+ sha256: string;
73
+ size: number;
74
+ }[];
20
75
  }
21
76
  export interface ScenarioResult {
22
77
  name: string;
@@ -38,7 +93,35 @@ export interface ScenarioResult {
38
93
  */
39
94
  binaryMissing?: boolean;
40
95
  missingBinaries?: string[];
96
+ /**
97
+ * Set when some group rejects (added after 1.2.0): the selector of the group the
98
+ * node would stop at, the first failing one in its order (lock groups, then
99
+ * type groups, each by script hash). The node reports no cycles for a
100
+ * rejected transaction, so the groups' cycles, each run on its own, do not
101
+ * add up to anything the node spends.
102
+ */
103
+ nodeStopsAt?: string;
104
+ /**
105
+ * Set only when the groups' cycles add up to more than the node's limit for
106
+ * one transaction (added after 1.3.0): `limit` is the consensus
107
+ * `max_block_cycles` (3,500,000,000 on mainnet and testnet), `sum` the groups'
108
+ * cycles. ckb-debugger gives each group that limit on its own; the node gives
109
+ * it to the whole transaction, so it would reject this one (exceeded max
110
+ * cycles). `nodeStopsAt` names the group where the running sum passes it.
111
+ */
112
+ overTxLimit?: {
113
+ limit: number;
114
+ sum: number;
115
+ };
41
116
  }
117
+ /**
118
+ * A scenario's `overTxLimit`, read defensively (a report file is the PR's):
119
+ * undefined unless both numbers are there and the sum is over the limit.
120
+ */
121
+ export declare function overTxLimitOf(s: ScenarioResult): {
122
+ limit: number;
123
+ sum: number;
124
+ } | undefined;
42
125
  export interface GroupResult {
43
126
  /** ckb-debugger's selector, e.g. `input.0.lock`: the key a group is matched by across reports. */
44
127
  selector: string;
@@ -52,6 +135,14 @@ export interface GroupResult {
52
135
  error?: string;
53
136
  /** Cycles; 0 when the VM stopped the script (`error`), whose count is not a cost. */
54
137
  cycles: number;
138
+ /**
139
+ * Set on every group of a scenario where some group rejects (added after 1.2.0):
140
+ * whether the node would run this group at all. It stops at the first failing
141
+ * group in its order (the scenario's `nodeStopsAt`); every group is still run
142
+ * on its own here, so the ones after it have a result and cycles the node
143
+ * would never produce. Absent when every group accepts: the node runs them all.
144
+ */
145
+ nodeReaches?: boolean;
55
146
  /**
56
147
  * The binary this group's code stands for was not in the checkout (the base):
57
148
  * its numbers are the mock's code, not that build's, so it is not compared.
@@ -72,6 +163,36 @@ export interface GroupResult {
72
163
  spawned?: number;
73
164
  /** With `spawned`: the cycles the function profile covers (the root script's own run). */
74
165
  profiled?: number;
166
+ /**
167
+ * With `spawned` (added after 1.3.0, ckb-debugger 1.1.2 and later): each
168
+ * spawned script's own profile, from a `--vm-id` replay of it. Its numbers
169
+ * are profiled frames, not a split of `cycles`: they leave out loading the
170
+ * binary and what the spawn costs the parent. `cycles` stays the total.
171
+ */
172
+ children?: ChildResult[];
173
+ /** With `spawned`: why some or all spawned scripts have no profile of their own (an older ckb-debugger, a replay that failed). */
174
+ childrenNote?: string;
175
+ }
176
+ /** A spawned script's own profile, in a report (added after 1.3.0). */
177
+ export interface ChildResult {
178
+ /** Its VM id (ckb-debugger's `--vm-id`): what a child is matched by across reports. */
179
+ vm: number;
180
+ /** The VM that spawned it: 0 is the group's own script. */
181
+ parent: number;
182
+ /** A name for the binary it ran (the config's binary name), or its short data hash. */
183
+ script: string;
184
+ /** The data hash of the binary it ran. */
185
+ codeHash?: string;
186
+ /** The replay's exit code: -1 with `error` when the VM stopped it. Absent with `failed`. */
187
+ result?: number;
188
+ error?: string;
189
+ /** The cycles in its profiled frames. Absent with `failed`. */
190
+ profiled?: number;
191
+ /** Its costliest functions, heaviest self first (at most FUNCTION_LIMIT), when its binary has a symbols build. */
192
+ functions?: FunctionResult[];
193
+ functionsWarning?: string;
194
+ /** Why it has no profile: the replay could not be run or read. */
195
+ failed?: string;
75
196
  }
76
197
  export interface FunctionResult {
77
198
  name: string;
@@ -94,6 +215,29 @@ export interface FunctionDelta {
94
215
  /** Set when both sides are known. */
95
216
  delta?: number;
96
217
  }
218
+ /** A spawned script on both sides of a diff, matched by VM id. Its numbers are profiled frames. */
219
+ export interface ChildDelta {
220
+ vm: number;
221
+ /** The head's name for it (the base's when it is gone). */
222
+ script: string;
223
+ /** Each side's result (`ok`, `exit 9`, `not profiled`) and profiled cycles; a side is absent when it had no such VM. */
224
+ base?: {
225
+ result: string;
226
+ profiled?: number;
227
+ };
228
+ head?: {
229
+ result: string;
230
+ profiled?: number;
231
+ };
232
+ /** Set when both sides have profiled cycles. */
233
+ delta?: number;
234
+ /** Its profiled cycles or result differ, or it is on one side only. */
235
+ changed: boolean;
236
+ /** Its functions whose self cycles changed, when the head recorded them. */
237
+ functions?: FunctionDelta[];
238
+ /** Why the head has no functions or no profile for it. */
239
+ note?: string;
240
+ }
97
241
  /** `error`: the head could not run the scenario. `base-error`: the base could not, so nothing was compared. */
98
242
  export type RowKind = "same" | "changed" | "result" | "new" | "removed" | "error" | "base-error";
99
243
  export interface DiffRow {
@@ -125,8 +269,24 @@ export interface DiffRow {
125
269
  spawned?: number;
126
270
  /** With `spawned`: the cycles the head's function profile covers. */
127
271
  profiled?: number;
128
- /** Why the base side of this group was not compared (its binary was not in the base checkout). */
272
+ /** With `spawned`: each spawned script's profile on both sides, by VM id (head reports from 1.1.2 debuggers, added after 1.3.0). */
273
+ children?: ChildDelta[];
274
+ /** The head's reason some spawned scripts have no profile of their own. */
275
+ childrenNote?: string;
276
+ /** Why the base side of this group was not compared (its binary was not in the base checkout, its inputs changed). */
129
277
  notCompared?: string;
278
+ /** Not compared because the scenario's inputs differ between the two reports' manifests. */
279
+ inputsChanged?: boolean;
280
+ }
281
+ /** One side's manifest, as a comment shows it. */
282
+ export interface ManifestSummary {
283
+ tool?: string;
284
+ debugger?: string;
285
+ debuggerSha256?: string;
286
+ wasm?: string;
287
+ commit?: string;
288
+ binariesCommit?: string;
289
+ toolchain?: string;
130
290
  }
131
291
  export interface CycleDiff {
132
292
  rows: DiffRow[];
@@ -161,6 +321,40 @@ export interface CycleDiff {
161
321
  head: string;
162
322
  };
163
323
  threshold?: number;
324
+ /**
325
+ * Groups not compared because their scenario's inputs (mock, transaction
326
+ * file, cycles.json entry) differ between the manifests. A gated diff fails
327
+ * on them unless `allowChangedInputs`.
328
+ */
329
+ inputsChanged?: number;
330
+ /** The scenarios whose inputs changed. */
331
+ changedScenarios?: string[];
332
+ /**
333
+ * Why the two reports did not run in the same environment, from their
334
+ * manifests: another ckb-debugger (version or binary), another CKB-VM version
335
+ * for a scenario. A gated diff fails on any.
336
+ */
337
+ environment?: string[];
338
+ /** What could not be checked, or differs without failing: a report without a manifest, another toolchain. */
339
+ notes?: string[];
340
+ /** Each side's manifest, short, for the comment. */
341
+ manifests?: {
342
+ base?: ManifestSummary;
343
+ head?: ManifestSummary;
344
+ };
345
+ /**
346
+ * Head scenarios whose groups add up to more than the node's per-transaction
347
+ * limit while the base's did not (`newScenario`: no base scenario ran to
348
+ * compare with). The node would reject them (exceeded max cycles) though every
349
+ * group may accept: a gated diff fails on one the base ran under the limit, as
350
+ * on a group that starts rejecting; `failOnResultChange` on any.
351
+ */
352
+ overTxLimit?: {
353
+ scenario: string;
354
+ limit: number;
355
+ sum: number;
356
+ newScenario?: boolean;
357
+ }[];
164
358
  }
165
359
  export interface DiffOptions {
166
360
  /** Percent. An increase above it is flagged, and makes `failed` true. */
@@ -169,7 +363,11 @@ export interface DiffOptions {
169
363
  failOnResultChange?: boolean;
170
364
  /** Removed, renamed or uncompared base groups do not fail a gated diff. */
171
365
  allowRemoved?: boolean;
366
+ /** Scenarios whose inputs changed (manifest hashes differ) do not fail a gated diff; still not compared. */
367
+ allowChangedInputs?: boolean;
172
368
  }
369
+ /** The note on a group whose scenario's inputs differ between base and head. */
370
+ export declare const INPUTS_CHANGED = "inputs changed: the scenario's mock, transaction file or cycles.json entry differs from the base's";
173
371
  /** The message for a binary no scenario's cell deps match, in a report's `errors` and the diff. */
174
372
  export declare const unmatchedError: (name: string) => string;
175
373
  /**
@@ -179,6 +377,12 @@ export declare const unmatchedError: (name: string) => string;
179
377
  */
180
378
  export declare function resultLabel(g: Pick<GroupResult, "result" | "error">): string;
181
379
  export declare function diffReports(base: CycleReport, head: CycleReport, options?: DiffOptions): CycleDiff;
380
+ /**
381
+ * Each spawned script on both sides, by VM id, in VM order. Without base
382
+ * children (an older report, an older debugger) every head child has no base
383
+ * side: what it costs is shown, not a change.
384
+ */
385
+ export declare function childDeltas(base: ChildResult[] | undefined, head: ChildResult[]): ChildDelta[];
182
386
  /**
183
387
  * The functions whose self cycles differ between two lists, largest change
184
388
  * first. One whose other side is not known (see FunctionDelta) is kept, ranked
@@ -192,7 +396,16 @@ export declare function functionDeltas(base: FunctionResult[] | undefined, head:
192
396
  * run, an error in either report, and a base group with nothing to compare
193
397
  * against (removed, renamed, moved, or measured without its binary) unless
194
398
  * `allowRemoved`. A head group the VM stopped is a result change, and over any
195
- * `failAbove` threshold.
399
+ * `failAbove` threshold. With a gate set, a group that accepted on the base and
400
+ * rejects on the head (`ok` → `exit N` or a VM error) always fails, whatever its
401
+ * cycles: a cheaper rejection is not a saving. `failOnResultChange` fails on any
402
+ * result change besides (reject → accept, one exit code or VM error to another,
403
+ * a new group that does not accept). A new group has no base that accepted, so
404
+ * this rule leaves it alone: with `failAbove` alone it fails only as before (a
405
+ * new group the VM stopped is over the threshold). A scenario whose groups add
406
+ * up to more than the node's per-transaction limit on the head, and not on the
407
+ * base, counts as a group that starts rejecting (the node would reject it); a
408
+ * new scenario over the limit, as a new group that does not accept.
196
409
  */
197
410
  export declare function diffFailed(diff: CycleDiff, options?: DiffOptions): boolean;
198
411
  /**
@@ -219,7 +432,10 @@ export declare function spawnNote(r: {
219
432
  head?: {
220
433
  cycles?: number;
221
434
  };
435
+ children?: unknown[];
222
436
  }): string;
437
+ /** What a spawned script's numbers are, under every list of them. */
438
+ export declare const CHILDREN_FOOTNOTE = "Profiled frames of each spawned script, from a ckb-debugger --vm-id replay of it: they leave out loading its binary and what the spawn costs the parent, so they do not add up to the group's cycles, which stay the total.";
223
439
  /** The hidden marker that identifies the sticky comment, so it is updated instead of duplicated. */
224
440
  export declare const COMMENT_MARKER = "<!-- ckb-cycles-report -->";
225
441
  export interface MarkdownOptions {
@@ -234,5 +450,10 @@ export interface MarkdownOptions {
234
450
  * reverse) matters more than any cycle count.
235
451
  */
236
452
  export declare function formatMarkdown(diff: CycleDiff, options?: MarkdownOptions): string;
453
+ /**
454
+ * One line per side that has a manifest: tool, debugger (and its binary's
455
+ * hash), commit, toolchain. Plain text: the caller cleans it (md or termLine).
456
+ */
457
+ export declare function manifestLines(diff: CycleDiff): string[];
237
458
  /** The same table for a terminal. */
238
459
  export declare function formatText(diff: CycleDiff): string;