@ohos-perf/core 0.12.1 → 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.
Files changed (3) hide show
  1. package/dist/index.d.ts +1252 -957
  2. package/dist/index.js +845 -246
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -394,6 +394,16 @@ interface SceneLayout {
394
394
  hilogFile: string;
395
395
  /** `hilog.jsonl` from the same capture: one typed row per log line. */
396
396
  hilogJsonlFile: string;
397
+ /**
398
+ * `redundant_file.txt`: the cold-start redundant-read report, when a scene
399
+ * carries one. Nothing here produces it yet; it is read when present.
400
+ */
401
+ redundantFile: string;
402
+ /**
403
+ * `jsheap.heapsnapshot`: the raw heap snapshot a `--mem-jsheap` capture
404
+ * pulled. Opaque to this package; it exists for DevEco Studio to open.
405
+ */
406
+ jsheapFile: string;
397
407
  metadataFile: string;
398
408
  }
399
409
  declare function createSceneLayout(root: string): SceneLayout;
@@ -1020,6 +1030,32 @@ declare class ScreenshotCollector implements Collector {
1020
1030
  }, layout: SceneLayout): Promise<ScreenshotCapture>;
1021
1031
  }
1022
1032
 
1033
+ /** What a successful capture produced, for `scene.json`. */
1034
+ interface JsheapCapture {
1035
+ readonly bytes: number;
1036
+ /** The device-side path the snapshot was pulled from. */
1037
+ readonly devicePath: string;
1038
+ }
1039
+ /**
1040
+ * Capture a JS heap snapshot into `jsheap.heapsnapshot`.
1041
+ *
1042
+ * A device that refuses `--mem-jsheap` — the usual reason is an app that is
1043
+ * not debug-signed — is a typed refusal carrying the device's own message,
1044
+ * never an empty file. The same applies to a command that succeeds but writes
1045
+ * nothing: the wait is bounded by `timeoutMs` and its expiry names what was
1046
+ * looked for.
1047
+ */
1048
+ declare class JsheapCollector implements Collector {
1049
+ readonly id = "jsheap";
1050
+ readonly provides: CapabilityId[];
1051
+ collect(hdc: Hdc, target: string, opts: {
1052
+ app: string;
1053
+ timeoutMs?: number;
1054
+ }, layout: SceneLayout): Promise<JsheapCapture>;
1055
+ }
1056
+ /** The snapshot's bytes, for a caller that wants to hash or inspect it. */
1057
+ declare function readJsheapSnapshot(layout: SceneLayout): Uint8Array | undefined;
1058
+
1023
1059
  /**
1024
1060
  * UI gesture injection.
1025
1061
  *
@@ -1315,6 +1351,14 @@ interface CollectOptions extends TraceCollectOptions {
1315
1351
  * capture. The raw log lands in `hilog.log`; parsing happens offline.
1316
1352
  */
1317
1353
  hilog?: boolean;
1354
+ /**
1355
+ * Also pull a JS heap snapshot.
1356
+ *
1357
+ * Capture only — the snapshot is opaque to this package and exists for
1358
+ * DevEco Studio to open. Requires `app` and a debug-signed or profilerable
1359
+ * app; the collector names the device's own refusal when it is not.
1360
+ */
1361
+ jsheap?: boolean;
1318
1362
  /**
1319
1363
  * Record this capture as one step of a scenario run. Written into
1320
1364
  * `scene.json`, so the scene names its own step after being copied out of
@@ -1337,6 +1381,7 @@ interface DeviceDeps {
1337
1381
  hidumper?: HidumperCollector;
1338
1382
  uitest?: UitestCollector;
1339
1383
  screenshot?: ScreenshotCollector;
1384
+ jsheap?: JsheapCollector;
1340
1385
  hilog?: HilogCollector;
1341
1386
  gesture?: GestureDriver;
1342
1387
  }
@@ -2409,214 +2454,287 @@ declare function discoverCases(dir: string, filter?: string): DiscoveredCase[];
2409
2454
  declare function loadCases(cases: readonly DiscoveredCase[]): CaseLoad[];
2410
2455
 
2411
2456
  /**
2412
- * Executing one scenario action against a device.
2413
- *
2414
- * The split with the runner is deliberate: this module performs exactly one
2415
- * action and throws when it fails, while the runner owns the record — when it
2416
- * happened, whether the step survived it, and what the trace says. That keeps
2417
- * "did it work" in one place and "what do we remember about it" in another.
2418
- *
2419
- * Quoting lives in `GestureDriver`, not here: it already knows that the device
2420
- * shell needs `'…'` and that a quote inside a text argument must be escaped.
2421
- * Quoting again here would send the quote characters to the device.
2457
+ * The HapRay parity ledger: one row per capability in the source-level
2458
+ * inventory of ArkAnalyzer-HapRay rev `9386e4e`.
2459
+ *
2460
+ * This exists because the claim drifted. The README said "18 ported / 9
2461
+ * partial / 8 missing" long after six releases had moved rows, and nothing
2462
+ * failed when it did — the numbers were prose. Here every row is data, the
2463
+ * summary is computed, and `parity.test.ts` checks the ported rows against the
2464
+ * analyzers the engine actually registers.
2465
+ *
2466
+ * The numbering is the inventory's own (`gap-analysis.md`), and it is what
2467
+ * the README and the site quote. Each `reason` for a non-ported row names what
2468
+ * is absent, so "not worth it" and "not done" are distinguishable.
2469
+ */
2470
+ /** How much of one HapRay capability this package implements. */
2471
+ type ParityStatus = 'ported' | 'partial' | 'missing' | 'out';
2472
+ interface ParityRow {
2473
+ /** The inventory's row number, 1-based. */
2474
+ readonly row: number;
2475
+ /** The capability, as the inventory names it. */
2476
+ readonly name: string;
2477
+ readonly status: ParityStatus;
2478
+ /**
2479
+ * What is absent, for a row that is not fully ported. Empty for `ported`.
2480
+ * A `missing` row is a gap this project intends to close; an `out` row is a
2481
+ * prerequisite this package refuses to ship.
2482
+ */
2483
+ readonly reason: string;
2484
+ /**
2485
+ * The analyzer class that carries this capability, when one analyzer does.
2486
+ * Checked against `defaultAnalyzers()`: a row cannot claim `ported` on the
2487
+ * strength of prose alone.
2488
+ */
2489
+ readonly analyzer?: string;
2490
+ }
2491
+ /**
2492
+ * Every capability, with the status this package's code supports today.
2422
2493
  *
2423
- * Selector actions (P17) need to see the screen, so they take a `dump` in the
2424
- * action context rather than a device method: reading the UI tree is
2425
- * `uitest dumpLayout` plus a file transfer, which the collector owns and the
2426
- * runner knows the path for. Passing a closure keeps `ActionDevice` unchanged,
2427
- * so `Device` still satisfies it structurally.
2494
+ * The moves since the inventory was written: `0.4.0` the report layer (33),
2495
+ * `0.5.0` frame load (9), `0.6.0` native memory (19), `0.7.0` hilog (30),
2496
+ * `0.8.0` run-only preparation (2), `0.9.0` UI capture (7) and UI comparison
2497
+ * (32) and animation (31, partial), `0.10.0` static HAP (25) and HAP size
2498
+ * (26) and static report artifacts (34), `0.11.0` flamegraph (22) and symbol
2499
+ * statistics (23), `0.12.0` the step DSL (3) and case discovery (1) and
2500
+ * per-step orchestration (6).
2428
2501
  */
2502
+ declare const PARITY_ROWS: readonly ParityRow[];
2503
+ /** The counts, computed from {@link PARITY_ROWS} rather than written down. */
2504
+ declare function paritySummary(): {
2505
+ ported: number;
2506
+ partial: number;
2507
+ missing: number;
2508
+ out: number;
2509
+ total: number;
2510
+ };
2429
2511
 
2430
- /** The device surface actions need. `Device` satisfies it structurally. */
2431
- interface ActionDevice {
2432
- readonly id: string;
2433
- shell(cmd: string): Promise<{
2434
- stdout: string;
2435
- stderr: string;
2436
- code: number;
2437
- }>;
2438
- gesture(g: Gesture): Promise<GestureResult>;
2439
- }
2440
2512
  /**
2441
- * What a selector action needs beyond the device: a fresh look at the screen.
2513
+ * One binder-related `callstack` row with its arguments resolved.
2442
2514
  *
2443
- * Optional so a coordinate-only scenario keeps calling `executeAction` with
2444
- * three arguments; a selector action without one is a typed refusal rather
2445
- * than a crash.
2515
+ * `args` is keyed by the `data_dict` text for `args.key`. A value becomes a
2516
+ * string when `args.datatype = 1` and the value is present in `data_dict`;
2517
+ * otherwise it stays the numeric `args.value`. Keys missing from `data_dict`
2518
+ * are dropped, mirroring HapRay's loader.
2519
+ *
2520
+ * `code` is special-cased like HapRay: when its first whitespace-separated
2521
+ * token starts with `0x`, the token is parsed as hexadecimal and stored as a
2522
+ * number (for example `"0x10 Java Layer Dependent"` → `16`). A token that
2523
+ * fails to parse leaves the original value untouched.
2446
2524
  */
2447
- interface ActionContext {
2448
- readonly dump: () => Promise<readonly UiNode[]>;
2525
+ interface BinderEvent {
2526
+ id: number;
2527
+ ts: number;
2528
+ dur: number;
2529
+ name: string;
2530
+ cat: string;
2531
+ callid: number;
2532
+ args: Record<string, string | number>;
2449
2533
  }
2450
2534
  /**
2451
- * Perform one action and return what the device said.
2535
+ * Typed accessor over binder events stored in `callstack`.
2452
2536
  *
2453
- * `launch` and `forceStop` use the scenario's app; a `wait` sleeps without a
2454
- * device call. A `marker` is refused here — the runner records markers with a
2455
- * device-uptime instant, and having two layers able to "execute" one would
2456
- * let them disagree about whether it happened.
2537
+ * Events are the `callstack` rows whose `name` contains `binder`, with their
2538
+ * `args` rows joined through `callstack.argsetid = args.argset`. Ordering is
2539
+ * `id`; `args` within one event follow `args.id`, so a repeated key resolves
2540
+ * to its last row deterministically. `callstack`, `args` and `data_dict` are
2541
+ * core trace_streamer tables, so no `hasTable()` guard is used.
2457
2542
  */
2458
- declare function executeAction(device: ActionDevice, app: string, action: ScenarioAction, context?: ActionContext): Promise<{
2459
- output?: string;
2460
- }>;
2543
+ declare class BinderQuery {
2544
+ private readonly db;
2545
+ constructor(db: QueryHandle);
2546
+ /** All binder events, ordered by `callstack.id`. */
2547
+ events(): BinderEvent[];
2548
+ }
2461
2549
 
2550
+ /** One side of a binder transaction, as reported by `computeBinderAnalysis`. */
2551
+ interface BinderEndpoint {
2552
+ pid: number | null;
2553
+ tid: number | null;
2554
+ procName: string | null;
2555
+ threadName: string | null;
2556
+ }
2462
2557
  /**
2463
- * The scenario runner: ordered steps, one capture window each.
2464
- *
2465
- * The shape that matters is the phase order. `setup` runs before the capture
2466
- * so the state you want to measure is already on screen; `actions` run
2467
- * *inside* the window so the gesture that causes the work is in the trace;
2468
- * `cleanup` runs after, always. HapRay's DSL parses setup and cleanup and
2469
- * never executes them — executing all three is why this exists.
2558
+ * One paired (or half) binder communication record.
2470
2559
  *
2471
- * Nothing here analyzes. A step directory is a scene, so `ohos-perf analyze`,
2472
- * `report` and `query` apply to it unchanged.
2560
+ * `latencyMs` is `null` unless both a request and a response exist. A half
2561
+ * transaction stays in `transactions` (it carries a `transaction id`) but never
2562
+ * contributes to `processStats`, `threadStats`, or `interfaceStats`.
2473
2563
  */
2474
-
2475
- /** One action's outcome, as `steps.json` records it. */
2476
- interface ActionOutcome {
2477
- readonly action: ScenarioAction;
2478
- /** Device uptime in ns, read immediately before the action; absent when the read failed. */
2479
- readonly atNs?: number;
2480
- /** Host clock at the action, ms. */
2481
- readonly atMs: number;
2482
- readonly ok: boolean;
2483
- readonly output?: string;
2484
- readonly error?: string;
2564
+ interface BinderTransaction {
2565
+ transactionId: string | number;
2566
+ caller: BinderEndpoint;
2567
+ callee: BinderEndpoint;
2568
+ requestTs: number | null;
2569
+ responseTs: number | null;
2570
+ latencyMs: number | null;
2485
2571
  }
2486
- /** One assertion's outcome, as `steps.json` records it. */
2487
- interface ExpectationOutcome {
2488
- /** What was asserted, in the author's terms — `present: text containing "Done"`. */
2489
- readonly label: string;
2490
- readonly ok: boolean;
2491
- /** Nodes matched, or for `foreground`, the nodes belonging to the app. */
2492
- readonly actual: number;
2493
- /** Why it failed, and what the screen held; absent when it held. */
2494
- readonly detail?: string;
2572
+ /** HapRay `_aggregate_stats` row, camelCased for this package. */
2573
+ interface BinderProcessStat {
2574
+ callerProc: string;
2575
+ calleeProc: string;
2576
+ count: number;
2577
+ avgLatency: number;
2578
+ minLatency: number;
2579
+ maxLatency: number;
2580
+ qps: number | null;
2581
+ avgIntervalMs: number | null;
2495
2582
  }
2496
- interface RunStepResult {
2497
- readonly round: number;
2498
- readonly index: number;
2499
- readonly id: string;
2500
- readonly name: string;
2501
- readonly status: 'ok' | 'failed';
2502
- /** Present only when a scene exists on disk. */
2503
- readonly sceneDir?: string;
2504
- readonly startedAtMs: number;
2505
- readonly durationMs: number;
2506
- readonly actions: readonly ActionOutcome[];
2507
- /** Present only when the step declared `expect`. */
2508
- readonly expectations?: readonly ExpectationOutcome[];
2509
- readonly error?: string;
2583
+ /** HapRay `_aggregate_by_thread` row, camelCased for this package. */
2584
+ interface BinderThreadStat {
2585
+ callerProc: string;
2586
+ callerTid: number | null;
2587
+ callerThreadName: string | null;
2588
+ calleeProc: string;
2589
+ calleeTid: number | null;
2590
+ calleeThreadName: string | null;
2591
+ count: number;
2592
+ avgLatency: number;
2593
+ minLatency: number;
2594
+ maxLatency: number;
2595
+ qps: number | null;
2596
+ avgIntervalMs: number | null;
2510
2597
  }
2511
- interface RunResult {
2512
- readonly scenario: string;
2513
- readonly app: string;
2514
- readonly device: {
2515
- id: string;
2516
- kind: string;
2517
- };
2518
- readonly rounds: number;
2519
- readonly status: 'completed' | 'failed';
2520
- readonly steps: readonly RunStepResult[];
2521
- readonly startedAtMs: number;
2522
- readonly durationMs: number;
2523
- readonly pids: {
2524
- pids: readonly number[];
2525
- processNames: readonly string[];
2526
- };
2527
- /** Absent when the device would not report one. Never a fabricated `0.0.0`. */
2528
- readonly appVersion?: string;
2598
+ /** HapRay `_aggregate_by_interface` row, camelCased for this package. */
2599
+ interface BinderInterfaceStat {
2600
+ code: string;
2601
+ count: number;
2602
+ avgLatency: number;
2603
+ minLatency: number;
2604
+ maxLatency: number;
2605
+ qps: number | null;
2606
+ avgIntervalMs: number | null;
2607
+ topCallerProc: string;
2608
+ topCalleeProc: string;
2609
+ callerProcVariety: number;
2610
+ calleeProcVariety: number;
2529
2611
  }
2530
- /** The collect request one step turns into. Mirrors `Device.collect`. */
2531
- interface RunnerCollectOptions {
2532
- app: string;
2533
- durationMs: number;
2534
- sceneRoot: string;
2535
- step: SceneStepRef;
2536
- procfs?: boolean;
2537
- hiprofiler?: {
2538
- plugins: readonly HiprofilerPluginName[];
2539
- };
2540
- hiperf?: {
2541
- frequency?: number;
2542
- };
2543
- hidumper?: boolean;
2544
- uitest?: boolean;
2545
- hilog?: boolean;
2612
+ /** Everything `computeBinderAnalysis` derives from one trace database. */
2613
+ interface BinderAnalysis {
2614
+ transactions: BinderTransaction[];
2615
+ processStats: BinderProcessStat[];
2616
+ threadStats: BinderThreadStat[];
2617
+ interfaceStats: BinderInterfaceStat[];
2546
2618
  }
2547
- /** The device surface the runner needs. `Device` satisfies it structurally. */
2548
- interface RunnerDevice {
2549
- readonly id: string;
2550
- readonly kind: string;
2551
- shell(cmd: string): Promise<{
2552
- stdout: string;
2553
- stderr: string;
2554
- code: number;
2555
- }>;
2556
- gesture(g: Gesture): Promise<GestureResult>;
2557
- collect(opts: RunnerCollectOptions): Promise<{
2558
- ingest(): Promise<{
2559
- close(): void;
2560
- }>;
2561
- }>;
2562
- /**
2563
- * Flattened on-screen UI tree, for `expect` and selector actions.
2564
- *
2565
- * Optional because a coordinate-only scenario never needs a screen, and a
2566
- * test that does not assert should not have to fake one. A step that does
2567
- * assert on a device without it is a named refusal, not a crash.
2568
- */
2569
- uiTree?(): Promise<readonly UiNode[]>;
2619
+ /**
2620
+ * Port of HapRay `IpcBinderAnalyzer._analyze_impl` for one trace database.
2621
+ *
2622
+ * Filtering, request/response pairing, enrichment and the three aggregations
2623
+ * mirror `ipc_binder_analyzer.py` rev `9386e4e`. The deliberate differences:
2624
+ * an empty `appPids` filters everything (HapRay would disable the filter),
2625
+ * stats ties are broken by identity instead of Python's unstable order, and
2626
+ * no value is rounded here (HapRay rounds only when writing its report).
2627
+ * Every mean is guarded (`timing` returns `null` for an empty group), so a
2628
+ * trace with only half transactions never produces `NaN`.
2629
+ */
2630
+ declare function computeBinderAnalysis(db: QueryHandle, opts: {
2631
+ appPids: number[];
2632
+ }): BinderAnalysis;
2633
+ /**
2634
+ * Binder analyzer over `callstack` / `args` / `data_dict` SQL.
2635
+ *
2636
+ * The engine gates this analyzer on `trace.binder`; `ctx.db` is still checked
2637
+ * because the handle is optional on `AnalyzeContext`. Without it the analyzer
2638
+ * emits one `no_data` evidence naming `ctx.db` and no metrics rather than
2639
+ * pretending zero binder traffic is a measurement.
2640
+ */
2641
+ declare class BinderAnalyzer implements Analyzer {
2642
+ readonly id = "binder";
2643
+ readonly requires: CapabilityId[];
2644
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
2570
2645
  }
2571
- interface RunOptions {
2572
- readonly outDir: string;
2573
- /** Overrides the scenario's own `rounds` when set. */
2574
- readonly rounds?: number;
2575
- /** Step ids to run; order in the scenario wins. */
2576
- readonly only?: readonly string[];
2577
- /** Continue after a failed step instead of stopping. */
2578
- readonly keepGoing?: boolean;
2579
- /** Injected clock, for tests. */
2580
- readonly now?: () => number;
2646
+
2647
+ /**
2648
+ * One row of `callstack` with camelCase field names.
2649
+ *
2650
+ * `ts` and `dur` are nanoseconds; `0`/`''` mean absent. The column is spelled
2651
+ * `argsetid` (no underscore), so its field keeps that spelling. `flag`,
2652
+ * `traceLevel`, `traceTag`, `customCategory` and `customArgs` are stored as
2653
+ * text even though some look numeric.
2654
+ */
2655
+ interface CallstackEvent {
2656
+ id: number;
2657
+ ts: number;
2658
+ dur: number;
2659
+ callid: number;
2660
+ cat: string;
2661
+ name: string;
2662
+ depth: number;
2663
+ cookie: number;
2664
+ parentId: number;
2665
+ argsetid: number;
2666
+ chainId: string;
2667
+ spanId: string;
2668
+ parentSpanId: string;
2669
+ flag: string;
2670
+ traceLevel: string;
2671
+ traceTag: string;
2672
+ customCategory: string;
2673
+ customArgs: string;
2674
+ childCallid: number;
2581
2675
  }
2582
2676
  /**
2583
- * Run a scenario: every selected (round, step) pair, one scene each.
2677
+ * A callstack row plus its arguments, keyed by the `data_dict` text.
2584
2678
  *
2585
- * The returned result is what `steps.json` records; the files are written
2586
- * before returning, on the success and the failure path alike, so a run that
2587
- * stopped at step 2 still says what step 1 produced.
2679
+ * Values are strings when `args.datatype = 1` and the value is present in
2680
+ * `data_dict`; otherwise they stay the raw numeric `args.value`. Arguments
2681
+ * whose key has no `data_dict` row are dropped (matching HapRay).
2588
2682
  */
2589
- declare class ScenarioRunner {
2590
- private readonly device;
2591
- private readonly opts;
2592
- private readonly now;
2593
- constructor(device: RunnerDevice, opts: RunOptions);
2594
- run(scenario: Scenario): Promise<RunResult>;
2683
+ interface CallstackEventWithArgs extends CallstackEvent {
2684
+ args: Record<string, string | number>;
2685
+ }
2686
+ /**
2687
+ * Typed accessor over `callstack`.
2688
+ *
2689
+ * All list accessors share `ORDER BY ts, id` and inclusive `ts` ranges.
2690
+ * `callstack`, `args` and `data_dict` are core trace_streamer tables, so no
2691
+ * `hasTable()` guard is used.
2692
+ */
2693
+ declare class CallstackQuery {
2694
+ private readonly db;
2695
+ constructor(db: QueryHandle);
2696
+ /** All callstack rows in `[startNs, endNs]` (or the whole trace). */
2697
+ all(range?: TimeRange): CallstackEvent[];
2595
2698
  /**
2596
- * The steps to run, in scenario order.
2699
+ * Rows whose `name` matches `pattern` as a SQL `LIKE` operand.
2597
2700
  *
2598
- * `--only` is a filter, not an ordering: typing `scroll,open` still runs
2599
- * `open` first, because a step may depend on the state a previous one left.
2701
+ * `pattern` is always bound, never interpolated, so a pattern containing
2702
+ * quotes or a `--` comment is matched as text. The result is capped by
2703
+ * `opts.limit` (default {@link DEFAULT_MATCH_LIMIT}), and `opts.range`
2704
+ * restricts `ts` inclusively.
2705
+ *
2706
+ * `opts.ipids` restricts the result to rows emitted by a thread of one of
2707
+ * those processes. **An empty array matches nothing** — an empty app
2708
+ * identity means no process was identified, and widening to device-wide is
2709
+ * the attribution bug `MemoryMeasureAnalyzer` guards against. `undefined`
2710
+ * leaves the query unscoped.
2600
2711
  */
2601
- private selectedSteps;
2602
- private runStep;
2712
+ matching(pattern: string, opts?: {
2713
+ range?: TimeRange;
2714
+ limit?: number;
2715
+ ipids?: readonly number[];
2716
+ }): CallstackEvent[];
2603
2717
  /**
2604
- * Perform one action and record it; never throws.
2718
+ * Rows `matching()` would return without its `opts.limit` cap.
2605
2719
  *
2606
- * A `marker` is recorded here, not executed: it is an annotation with a
2607
- * device-uptime instant — the thing that lets a later query line a tap up
2608
- * with a trace row — and there is no trace event behind it. Recording it in
2609
- * the runner is what keeps "it happened" in the same place as "when".
2720
+ * Uses the same `WHERE` as `matching()`, so the pair can report a true
2721
+ * match count while the fetched rows stay bounded. An empty `opts.ipids`
2722
+ * counts zero, for the same reason `matching()` returns nothing.
2610
2723
  */
2611
- private perform;
2724
+ countMatching(pattern: string, opts?: {
2725
+ range?: TimeRange;
2726
+ ipids?: readonly number[];
2727
+ }): number;
2728
+ /**
2729
+ * Callstack rows with their arguments resolved through `args` + `data_dict`.
2730
+ *
2731
+ * A key is **always** looked up in `data_dict`; a value is looked up only
2732
+ * when `datatype = 1`. Unresolvable keys are skipped. Rows are grouped by
2733
+ * `callstack.id` and returned in `ts, id` order; when the same key appears
2734
+ * more than once for one row, the last `args.id` wins.
2735
+ */
2736
+ withArgs(range?: TimeRange): CallstackEventWithArgs[];
2612
2737
  }
2613
- /**
2614
- * Write `testInfo.json`, `steps.json` and `pids.json` into a run directory.
2615
- *
2616
- * Pretty-printed with two spaces and one trailing newline, like `scene.json`,
2617
- * so a run is diff-friendly and byte-stable apart from its clock fields.
2618
- */
2619
- declare function writeRunFiles(outDir: string, result: RunResult): void;
2620
2738
 
2621
2739
  /**
2622
2740
  * Frame status as stored in `frame_slice.flag`.
@@ -2748,533 +2866,177 @@ declare class FrameQuery {
2748
2866
  }
2749
2867
 
2750
2868
  /**
2751
- * One row of `process` with camelCase field names.
2869
+ * One `process_measure` observation, joined to its filter.
2752
2870
  *
2753
- * `startTs` is nanoseconds, but **`0` means absent, not time zero**: on the
2754
- * measured 249MB trace `process.start_ts` is NULL on all 437 rows, so a
2755
- * consumer must not read `startTs === 0` as "started at the trace origin".
2756
- * The same NULL-to-0 rule applies to every other numeric field.
2871
+ * `tsNs`/`durNs` are the stored values unchanged: measured on the Mate 60,
2872
+ * `trace_range.start_ts` equals `MIN(process_measure.ts)` exactly and a 3 s
2873
+ * capture spans ~2.0e9, so this table is already in the trace's nanosecond
2874
+ * clock. The names carry the unit so consumers never have to guess.
2757
2875
  *
2758
- * `name` is `''` when the column is NULL (60 of the 437 real rows). Duplicate
2759
- * non-empty names are common (`sh` ×86, `hidumper` ×46), so a `ProcessInfo`
2760
- * identifies one row, not one logical process; see `ProcessQuery.byName`.
2876
+ * `value` is the filter's raw measured value. For the `mem.*` filters the
2877
+ * unit is **KiB**, not bytes: measured against `/proc/<pid>/status`, a
2878
+ * `mem.rss` row of 664420 matched `VmRSS: 664584 kB` and `mem.vm.size`
2879
+ * 106161468 matched `VmSize: 106161468 kB` exactly. Converting to bytes is
2880
+ * the analyzer's job, because only it knows which filter it read.
2761
2881
  */
2762
- interface ProcessInfo {
2763
- id: number;
2764
- ipid: number;
2765
- pid: number;
2882
+ interface ProcessMeasure {
2883
+ tsNs: number;
2884
+ durNs: number;
2885
+ filterId: number;
2886
+ /** Filter name, e.g. `mem.rss`; `''` means the join found no filter. */
2766
2887
  name: string;
2767
- startTs: number;
2768
- switchCount: number;
2769
- threadCount: number;
2770
- sliceCount: number;
2771
- memCount: number;
2888
+ /** Process id the filter was recorded for. */
2889
+ ipid: number;
2890
+ /** Raw filter value; `mem.*` values are KiB (see the interface note). */
2891
+ value: number;
2772
2892
  }
2773
- /**
2774
- * One row of `thread` with camelCase field names.
2775
- *
2776
- * `startTs` and `endTs` are nanoseconds, but **`0` means absent, not time
2777
- * zero**: on the measured 249MB trace `thread.end_ts` is NULL on all 1231
2778
- * rows, and `startTs` can be NULL too. A consumer must not read
2779
- * `endTs === 0` as "ended at the trace origin".
2780
- */
2781
- interface ThreadInfo {
2893
+ /** One `process_measure_filter` row. */
2894
+ interface ProcessMeasureFilter {
2782
2895
  id: number;
2783
- itid: number;
2784
- tid: number;
2785
2896
  name: string;
2786
- startTs: number;
2787
- endTs: number;
2788
2897
  ipid: number;
2789
- isMainThread: boolean;
2790
- switchCount: number;
2791
2898
  }
2792
2899
  /**
2793
- * Typed accessor over `process`.
2900
+ * Typed accessor over the memory-plugin tables.
2794
2901
  *
2795
- * A truncated or sparse scene can lack the `process` table entirely (e.g. a
2796
- * capture holding only `callstack` and `frame_slice`). Every accessor therefore
2797
- * checks `hasTable()` first and returns `[]`/`undefined` instead of letting
2798
- * SQLite throw `no such table: process` — the same guard idiom as the other
2799
- * query classes use for their optional tables.
2902
+ * These tables exist only when a capture ran `memory-plugin` with
2903
+ * `report_process_tree` and `report_sysmem`; an ftrace-only scene has neither,
2904
+ * and every method then returns `[]` instead of letting SQLite throw
2905
+ * `no such table`. Rows are ordered by `ts, filter_id` (with `value` as a final
2906
+ * tie-break) so equal timestamps stay deterministic (D5).
2800
2907
  */
2801
- declare class ProcessQuery {
2908
+ declare class MemMeasureQuery {
2802
2909
  private readonly db;
2803
2910
  constructor(db: QueryHandle);
2911
+ /** True when both tables the joined query needs are present. */
2912
+ hasTable(): boolean;
2913
+ /** Every measure in `[startNs, endNs]` (or the whole trace). */
2914
+ all(range?: TimeRange): ProcessMeasure[];
2804
2915
  /**
2805
- * Every process row, ordered by `id` ascending.
2806
- *
2807
- * Ordering is fixed rather than left to SQLite so the result is byte-stable
2808
- * across runs (D5). An absent table returns `[]`.
2809
- */
2810
- all(): ProcessInfo[];
2811
- /**
2812
- * The process row named `name`, or `undefined` if none exists.
2813
- *
2814
- * **Duplicate names resolve to the lowest `id`.** The measured trace has
2815
- * heavy duplication (`sh` ×86, `hidumper` ×46, `ls` ×38, `head` ×36) and
2816
- * "return any matching row" would make output depend on row order, which
2817
- * violates the determinism requirement (D5). `ORDER BY id LIMIT 1` fixes the
2818
- * tie-break.
2819
- *
2820
- * Rows with `name IS NULL` map to `ProcessInfo.name === ''`, but
2821
- * `byName('')` does **not** find them: SQL `name = ''` never matches NULL.
2822
- * A NULL-named row is reachable only through `all()`. An absent table returns
2823
- * `undefined`.
2824
- */
2825
- byName(name: string): ProcessInfo | undefined;
2826
- /**
2827
- * The process row whose **`pid`** is `pid`, or `undefined` if none exists.
2916
+ * Measures whose filter `ipid` is one of `ipids`.
2828
2917
  *
2829
- * Like {@link byName}, duplicate matches resolve to the lowest `id` so output
2830
- * is deterministic (D5). This is the safe pid→ipid step: never compare a pid
2831
- * against `thread.ipid` or another ipid column directly. An absent table
2832
- * returns `undefined`.
2918
+ * **The argument is an `ipid`, not a `pid`.** `process_measure_filter.ipid`
2919
+ * is the trace database's internal process id: measured on the Mate 60,
2920
+ * sceneboard has `ipid=117` and `pid=6500`, so passing a pid would silently
2921
+ * return another process's rows (or none). `ProcessQuery.byPid` is the safe
2922
+ * pid→ipid step. An empty `ipids` returns `[]` without issuing `IN ()`.
2833
2923
  */
2834
- byPid(pid: number): ProcessInfo | undefined;
2835
- /**
2836
- * One `pid` per requested name, **in the order the names were given**;
2837
- * unknown names are skipped (so the result may be shorter than `names`).
2838
- *
2839
- * Each name resolves with the same lowest-`id` rule as `byName`. A name
2840
- * repeated in `names` therefore yields its pid once per occurrence, and
2841
- * names resolving to the same `pid` are not deduplicated. An absent table
2842
- * returns `[]`.
2843
- */
2844
- pidsFor(names: string[]): number[];
2845
- private hasTable;
2846
- }
2847
- /**
2848
- * Typed accessor over `thread`.
2849
- *
2850
- * Every method returns `all()`'s row shape in `id` ascending order.
2851
- * `mainThreads()` and `forProcess()` filter that set rather than issuing their
2852
- * own SQL, so their NULL handling cannot drift from `all()`. `forPid()` joins
2853
- * through `process` and reuses the same `toThread` mapping, so only its
2854
- * predicate differs.
2855
- *
2856
- * A truncated or sparse scene can lack the `thread` table (the wakeup analysis
2857
- * joins it unguarded), so every accessor checks `hasTable()` first and returns
2858
- * `[]` instead of letting SQLite throw `no such table: thread`, matching the
2859
- * other query classes' guard idiom.
2860
- */
2861
- declare class ThreadQuery {
2862
- private readonly db;
2863
- constructor(db: QueryHandle);
2864
- /** Every thread row, ordered by `id` ascending. An absent table returns `[]`. */
2865
- all(): ThreadInfo[];
2866
- /**
2867
- * Rows with `is_main_thread = 1`.
2868
- *
2869
- * This is one row per process, not one row overall: the measured trace has
2870
- * 437 main threads over 437 processes.
2871
- */
2872
- mainThreads(): ThreadInfo[];
2873
- /**
2874
- * Rows whose `ipid` belongs to the given process, ordered by `id`.
2875
- *
2876
- * **The argument is an `ipid`, not a `pid`.** `frame_slice.ipid` and
2877
- * `callstack.ipid` are ipids, so this is the right accessor for frame and
2878
- * binder analysis. If you have a `pid` — for example the value
2879
- * `ProcessQuery.pidsFor()` returns — use {@link forPid} instead.
2880
- *
2881
- * Passing a pid here is not merely "not found": ipids and pids are different
2882
- * number spaces that overlap, so a pid can name a *different* process's
2883
- * ipid. Measured on the 249MB trace, of 437 processes 396 pids are not a
2884
- * legal ipid (this returns `[]`), 1 pid happens to equal its own ipid, and
2885
- * **40 silently return another process's threads**. For example `hilogd`
2886
- * has `ipid=4, pid=113`, and ipid 113 belongs to `sh` — so
2887
- * `forProcess(113)` returns `sh`'s thread with no error.
2888
- */
2889
- forProcess(ipid: number): ThreadInfo[];
2890
- /**
2891
- * Rows of the process whose **`pid`** is `pid`, ordered by `id`.
2892
- *
2893
- * Resolves the pid through `process` (`thread.ipid = process.ipid`) rather
2894
- * than comparing it against `thread.ipid` directly, so a pid can never be
2895
- * mistaken for an ipid — see {@link forProcess} for the measured overlap.
2896
- * Measured: `hilogd` (pid 113) yields its 6 threads, `ohos.sceneboard` 32,
2897
- * `render_service` 17, `sh` 1. Pids are unique on the measured traces, so
2898
- * the join cannot fan out; an unknown pid returns `[]`. The join reads both
2899
- * `thread` and `process`, so an absent one of them returns `[]`.
2900
- */
2901
- forPid(pid: number): ThreadInfo[];
2902
- private hasTable;
2924
+ forIpids(ipids: number[], range?: TimeRange): ProcessMeasure[];
2925
+ /** Every filter row, ordered by `id`. */
2926
+ filters(): ProcessMeasureFilter[];
2927
+ private select;
2928
+ private has;
2903
2929
  }
2904
2930
 
2905
- /**
2906
- * One row of `sched_slice` with camelCase field names.
2907
- *
2908
- * `ts`, `dur` and `tsEnd` are nanoseconds. Null numerics become `0` and null
2909
- * text becomes `''` through `num`/`str`; `0` therefore means absent.
2910
- */
2911
- interface SchedSlice {
2931
+ /** One `perf_thread` row; `threadId` joins `perf_sample.thread_id`. */
2932
+ interface PerfThread {
2912
2933
  id: number;
2913
- ts: number;
2914
- dur: number;
2915
- tsEnd: number;
2916
- cpu: number;
2917
- itid: number;
2918
- ipid: number;
2919
- endState: string;
2920
- priority: number;
2921
- argSetid: number;
2934
+ threadId: number;
2935
+ processId: number;
2936
+ threadName: string;
2922
2937
  }
2923
2938
  /**
2924
- * One wakeup row of `instant` with camelCase field names.
2939
+ * One `perf_sample` row with camelCase field names.
2925
2940
  *
2926
- * `InstantQuery.wakeups()` keeps only `sched_wakeup`/`sched_waking` rows whose
2927
- * `ref_type` is `itid` and whose `ref` and `wakeup_from` are both present, so
2928
- * those two fields are non-null in practice; they are still normalised to `0`
2929
- * like every other numeric column. `instant` has no `id` column.
2941
+ * `timestampTrace` is the trace-relative nanosecond timestamp and is the
2942
+ * column ranges are applied to (matching HapRay's preferred timestamp column).
2943
+ * `timeStamp` is kept as a separate field for callers that need the raw perf
2944
+ * timestamp.
2930
2945
  */
2931
- interface WakeupEvent {
2932
- ts: number;
2946
+ interface PerfSampleRow {
2947
+ id: number;
2948
+ callchainId: number;
2949
+ timeStamp: number;
2950
+ threadId: number;
2951
+ eventCount: number;
2952
+ eventTypeId: number;
2953
+ timestampTrace: number;
2954
+ cpuId: number;
2955
+ threadState: string;
2956
+ }
2957
+ /** One resolved frame of a perf callchain. */
2958
+ interface PerfFunction {
2959
+ symbol: string;
2933
2960
  name: string;
2934
- ref: number;
2935
- wakeupFrom: number;
2936
- refType: string;
2937
- value: number;
2961
+ filePath: string;
2962
+ }
2963
+ /** A callchain for one perf thread, frames ordered by `depth`. */
2964
+ interface PerfCallchain {
2965
+ threadId: number;
2966
+ callchainId: number;
2967
+ functions: PerfFunction[];
2938
2968
  }
2939
2969
  /**
2940
- * Typed accessor over `sched_slice`.
2970
+ * Sample weight attributed to one leaf symbol.
2941
2971
  *
2942
- * Ordering is always `ts, id` so equal timestamps keep a stable, documented
2943
- * order. Time ranges are inclusive at both ends. `sched_slice` is a core
2944
- * trace_streamer table, so no `hasTable()` guard is used.
2972
+ * `event_count` is attributed to the deepest frame of the sample's callchain
2973
+ * (the "self" cost), so rows answer "which function was executing when the
2974
+ * sample was taken". A chain whose deepest frame has an empty symbol is not
2975
+ * attributable and contributes no row.
2945
2976
  */
2946
- declare class SchedQuery {
2947
- private readonly db;
2948
- constructor(db: QueryHandle);
2949
- /** All slices in `[startNs, endNs]` (or the whole trace), ordered by `ts, id`. */
2950
- all(range?: TimeRange): SchedSlice[];
2951
- /**
2952
- * Slices belonging to any of `itids`, ordered by `ts, id`.
2953
- *
2954
- * An empty `itids` returns `[]` without issuing `IN ()`, which SQLite
2955
- * rejects.
2956
- */
2957
- forItids(itids: number[], range?: TimeRange): SchedSlice[];
2977
+ interface PerfLeafAttribution {
2978
+ symbol: string;
2979
+ filePath: string;
2980
+ samples: number;
2981
+ /** True when `symbol` is a `file+0xoffset` reference, not a name. */
2982
+ unresolved: boolean;
2958
2983
  }
2959
2984
  /**
2960
- * Typed accessor over `instant`, limited to scheduler wakeup events.
2985
+ * One row of summed sample weight per `(symbol, filePath, unresolved)`.
2961
2986
  *
2962
- * The predicate is fixed: `sched_wakeup`/`sched_waking`, `ref_type = 'itid'`,
2963
- * and both `ref` and `wakeup_from` present. `instant` has no `id` column, so
2964
- * the stable ordering is `ts, ref, wakeup_from`.
2987
+ * This is the population {@link PerfQuery.leafAttribution} returns, plus the
2988
+ * frames no symbol resolves at all, so the rows sum to the window's weight.
2989
+ * `unresolved` separates "the recorder had no symbol" from "the lookup
2990
+ * missed": a `libfoo.so+0x1cce24` symbol is honest, and counting it as
2991
+ * resolved would make the numbers read better than the capture is.
2965
2992
  */
2966
- declare class InstantQuery {
2967
- private readonly db;
2968
- constructor(db: QueryHandle);
2969
- /**
2970
- * Wakeup events whose `ts` is in `[startNs, endNs]`, ordered by
2971
- * `ts, ref, wakeup_from`.
2972
- */
2973
- wakeups(range: TimeRange): WakeupEvent[];
2993
+ interface SymbolStat {
2994
+ symbol: string;
2995
+ filePath: string;
2996
+ samples: number;
2997
+ unresolved: boolean;
2974
2998
  }
2975
-
2976
2999
  /**
2977
- * One row of `thread_state` with camelCase field names.
3000
+ * True when a resolved symbol is a `file+0xoffset` reference or empty.
2978
3001
  *
2979
- * `ts` and `dur` are nanoseconds. `0`/`''` mean absent, as everywhere else in
2980
- * the query layer. The P1 schema has no `id` column on this table, so no
2981
- * identifier is exposed; ordering uses `ts, itid, state`.
3002
+ * The converter writes `libfoo.so+0x1cce24` when it has no symbol for an
3003
+ * address, so the text is honest but unnamed. A space means the text is a
3004
+ * sentence or a demangled signature, never that form. The file path is never
3005
+ * part of the test: an unresolved frame still names the library it ran in,
3006
+ * which is what makes the evidence actionable.
2982
3007
  */
2983
- interface ThreadState {
2984
- ts: number;
2985
- dur: number;
2986
- cpu: number;
2987
- itid: number;
2988
- tid: number;
2989
- pid: number;
2990
- state: string;
2991
- argSetid: number;
3008
+ declare function isUnresolvedSymbol(symbol: string): boolean;
3009
+ /**
3010
+ * One folded stack, in the format `flamegraph.pl` and every flamegraph viewer
3011
+ * understands: `a;b;c` with `samples` samples ending at `c`.
3012
+ */
3013
+ interface FoldedStack {
3014
+ /** Semicolon-joined symbol path, root first. */
3015
+ stack: string;
3016
+ /** The last symbol on the stack — the frame the samples were taken in. */
3017
+ leaf: string;
3018
+ /** Summed `event_count` of every sample folded into this stack. */
3019
+ samples: number;
2992
3020
  }
2993
3021
  /**
2994
- * Typed accessor over `thread_state`.
3022
+ * Typed accessor over the optional `perf_*` tables.
2995
3023
  *
2996
- * Every method orders by `ts, itid, state` — the secondary keys make equal
2997
- * timestamps deterministic even though the table has no `id`. Time ranges are
2998
- * inclusive at both ends. `thread_state` is a core trace_streamer table, so no
2999
- * `hasTable()` guard is used.
3024
+ * These tables exist only when a perf trace was ingested; every accessor
3025
+ * therefore checks `hasTable()` first and returns `[]`/`false` instead of
3026
+ * letting SQLite throw `no such table`. The query layer is read-only and never
3027
+ * creates the indexes HapRay's `ensure_perf_trace_indexes` would add.
3000
3028
  */
3001
- declare class ThreadStateQuery {
3029
+ declare class PerfQuery {
3002
3030
  private readonly db;
3003
3031
  constructor(db: QueryHandle);
3004
- /** All states in `[startNs, endNs]` (or the whole trace). */
3005
- all(range?: TimeRange): ThreadState[];
3032
+ /** True when `perf_sample` exists and contains at least one row. */
3033
+ hasSamples(): boolean;
3006
3034
  /**
3007
- * States of the given `itids`, ordered by `ts, itid, state`.
3035
+ * True when `perf_files` exists, so a frame can carry a symbol at all.
3008
3036
  *
3009
- * An empty `itids` returns `[]` without issuing `IN ()`.
3010
- */
3011
- forItids(itids: number[], range?: TimeRange): ThreadState[];
3012
- }
3013
-
3014
- /**
3015
- * One `process_measure` observation, joined to its filter.
3016
- *
3017
- * `tsNs`/`durNs` are the stored values unchanged: measured on the Mate 60,
3018
- * `trace_range.start_ts` equals `MIN(process_measure.ts)` exactly and a 3 s
3019
- * capture spans ~2.0e9, so this table is already in the trace's nanosecond
3020
- * clock. The names carry the unit so consumers never have to guess.
3021
- *
3022
- * `value` is the filter's raw measured value. For the `mem.*` filters the
3023
- * unit is **KiB**, not bytes: measured against `/proc/<pid>/status`, a
3024
- * `mem.rss` row of 664420 matched `VmRSS: 664584 kB` and `mem.vm.size`
3025
- * 106161468 matched `VmSize: 106161468 kB` exactly. Converting to bytes is
3026
- * the analyzer's job, because only it knows which filter it read.
3027
- */
3028
- interface ProcessMeasure {
3029
- tsNs: number;
3030
- durNs: number;
3031
- filterId: number;
3032
- /** Filter name, e.g. `mem.rss`; `''` means the join found no filter. */
3033
- name: string;
3034
- /** Process id the filter was recorded for. */
3035
- ipid: number;
3036
- /** Raw filter value; `mem.*` values are KiB (see the interface note). */
3037
- value: number;
3038
- }
3039
- /** One `process_measure_filter` row. */
3040
- interface ProcessMeasureFilter {
3041
- id: number;
3042
- name: string;
3043
- ipid: number;
3044
- }
3045
- /**
3046
- * Typed accessor over the memory-plugin tables.
3047
- *
3048
- * These tables exist only when a capture ran `memory-plugin` with
3049
- * `report_process_tree` and `report_sysmem`; an ftrace-only scene has neither,
3050
- * and every method then returns `[]` instead of letting SQLite throw
3051
- * `no such table`. Rows are ordered by `ts, filter_id` (with `value` as a final
3052
- * tie-break) so equal timestamps stay deterministic (D5).
3053
- */
3054
- declare class MemMeasureQuery {
3055
- private readonly db;
3056
- constructor(db: QueryHandle);
3057
- /** True when both tables the joined query needs are present. */
3058
- hasTable(): boolean;
3059
- /** Every measure in `[startNs, endNs]` (or the whole trace). */
3060
- all(range?: TimeRange): ProcessMeasure[];
3061
- /**
3062
- * Measures whose filter `ipid` is one of `ipids`.
3063
- *
3064
- * **The argument is an `ipid`, not a `pid`.** `process_measure_filter.ipid`
3065
- * is the trace database's internal process id: measured on the Mate 60,
3066
- * sceneboard has `ipid=117` and `pid=6500`, so passing a pid would silently
3067
- * return another process's rows (or none). `ProcessQuery.byPid` is the safe
3068
- * pid→ipid step. An empty `ipids` returns `[]` without issuing `IN ()`.
3069
- */
3070
- forIpids(ipids: number[], range?: TimeRange): ProcessMeasure[];
3071
- /** Every filter row, ordered by `id`. */
3072
- filters(): ProcessMeasureFilter[];
3073
- private select;
3074
- private has;
3075
- }
3076
-
3077
- /**
3078
- * One row of `callstack` with camelCase field names.
3079
- *
3080
- * `ts` and `dur` are nanoseconds; `0`/`''` mean absent. The column is spelled
3081
- * `argsetid` (no underscore), so its field keeps that spelling. `flag`,
3082
- * `traceLevel`, `traceTag`, `customCategory` and `customArgs` are stored as
3083
- * text even though some look numeric.
3084
- */
3085
- interface CallstackEvent {
3086
- id: number;
3087
- ts: number;
3088
- dur: number;
3089
- callid: number;
3090
- cat: string;
3091
- name: string;
3092
- depth: number;
3093
- cookie: number;
3094
- parentId: number;
3095
- argsetid: number;
3096
- chainId: string;
3097
- spanId: string;
3098
- parentSpanId: string;
3099
- flag: string;
3100
- traceLevel: string;
3101
- traceTag: string;
3102
- customCategory: string;
3103
- customArgs: string;
3104
- childCallid: number;
3105
- }
3106
- /**
3107
- * A callstack row plus its arguments, keyed by the `data_dict` text.
3108
- *
3109
- * Values are strings when `args.datatype = 1` and the value is present in
3110
- * `data_dict`; otherwise they stay the raw numeric `args.value`. Arguments
3111
- * whose key has no `data_dict` row are dropped (matching HapRay).
3112
- */
3113
- interface CallstackEventWithArgs extends CallstackEvent {
3114
- args: Record<string, string | number>;
3115
- }
3116
- /**
3117
- * Typed accessor over `callstack`.
3118
- *
3119
- * All list accessors share `ORDER BY ts, id` and inclusive `ts` ranges.
3120
- * `callstack`, `args` and `data_dict` are core trace_streamer tables, so no
3121
- * `hasTable()` guard is used.
3122
- */
3123
- declare class CallstackQuery {
3124
- private readonly db;
3125
- constructor(db: QueryHandle);
3126
- /** All callstack rows in `[startNs, endNs]` (or the whole trace). */
3127
- all(range?: TimeRange): CallstackEvent[];
3128
- /**
3129
- * Rows whose `name` matches `pattern` as a SQL `LIKE` operand.
3130
- *
3131
- * `pattern` is always bound, never interpolated, so a pattern containing
3132
- * quotes or a `--` comment is matched as text. The result is capped by
3133
- * `opts.limit` (default {@link DEFAULT_MATCH_LIMIT}), and `opts.range`
3134
- * restricts `ts` inclusively.
3135
- *
3136
- * `opts.ipids` restricts the result to rows emitted by a thread of one of
3137
- * those processes. **An empty array matches nothing** — an empty app
3138
- * identity means no process was identified, and widening to device-wide is
3139
- * the attribution bug `MemoryMeasureAnalyzer` guards against. `undefined`
3140
- * leaves the query unscoped.
3141
- */
3142
- matching(pattern: string, opts?: {
3143
- range?: TimeRange;
3144
- limit?: number;
3145
- ipids?: readonly number[];
3146
- }): CallstackEvent[];
3147
- /**
3148
- * Rows `matching()` would return without its `opts.limit` cap.
3149
- *
3150
- * Uses the same `WHERE` as `matching()`, so the pair can report a true
3151
- * match count while the fetched rows stay bounded. An empty `opts.ipids`
3152
- * counts zero, for the same reason `matching()` returns nothing.
3153
- */
3154
- countMatching(pattern: string, opts?: {
3155
- range?: TimeRange;
3156
- ipids?: readonly number[];
3157
- }): number;
3158
- /**
3159
- * Callstack rows with their arguments resolved through `args` + `data_dict`.
3160
- *
3161
- * A key is **always** looked up in `data_dict`; a value is looked up only
3162
- * when `datatype = 1`. Unresolvable keys are skipped. Rows are grouped by
3163
- * `callstack.id` and returned in `ts, id` order; when the same key appears
3164
- * more than once for one row, the last `args.id` wins.
3165
- */
3166
- withArgs(range?: TimeRange): CallstackEventWithArgs[];
3167
- }
3168
-
3169
- /** One `perf_thread` row; `threadId` joins `perf_sample.thread_id`. */
3170
- interface PerfThread {
3171
- id: number;
3172
- threadId: number;
3173
- processId: number;
3174
- threadName: string;
3175
- }
3176
- /**
3177
- * One `perf_sample` row with camelCase field names.
3178
- *
3179
- * `timestampTrace` is the trace-relative nanosecond timestamp and is the
3180
- * column ranges are applied to (matching HapRay's preferred timestamp column).
3181
- * `timeStamp` is kept as a separate field for callers that need the raw perf
3182
- * timestamp.
3183
- */
3184
- interface PerfSampleRow {
3185
- id: number;
3186
- callchainId: number;
3187
- timeStamp: number;
3188
- threadId: number;
3189
- eventCount: number;
3190
- eventTypeId: number;
3191
- timestampTrace: number;
3192
- cpuId: number;
3193
- threadState: string;
3194
- }
3195
- /** One resolved frame of a perf callchain. */
3196
- interface PerfFunction {
3197
- symbol: string;
3198
- name: string;
3199
- filePath: string;
3200
- }
3201
- /** A callchain for one perf thread, frames ordered by `depth`. */
3202
- interface PerfCallchain {
3203
- threadId: number;
3204
- callchainId: number;
3205
- functions: PerfFunction[];
3206
- }
3207
- /**
3208
- * Sample weight attributed to one leaf symbol.
3209
- *
3210
- * `event_count` is attributed to the deepest frame of the sample's callchain
3211
- * (the "self" cost), so rows answer "which function was executing when the
3212
- * sample was taken". A chain whose deepest frame has an empty symbol is not
3213
- * attributable and contributes no row.
3214
- */
3215
- interface PerfLeafAttribution {
3216
- symbol: string;
3217
- filePath: string;
3218
- samples: number;
3219
- /** True when `symbol` is a `file+0xoffset` reference, not a name. */
3220
- unresolved: boolean;
3221
- }
3222
- /**
3223
- * One row of summed sample weight per `(symbol, filePath, unresolved)`.
3224
- *
3225
- * This is the population {@link PerfQuery.leafAttribution} returns, plus the
3226
- * frames no symbol resolves at all, so the rows sum to the window's weight.
3227
- * `unresolved` separates "the recorder had no symbol" from "the lookup
3228
- * missed": a `libfoo.so+0x1cce24` symbol is honest, and counting it as
3229
- * resolved would make the numbers read better than the capture is.
3230
- */
3231
- interface SymbolStat {
3232
- symbol: string;
3233
- filePath: string;
3234
- samples: number;
3235
- unresolved: boolean;
3236
- }
3237
- /**
3238
- * True when a resolved symbol is a `file+0xoffset` reference or empty.
3239
- *
3240
- * The converter writes `libfoo.so+0x1cce24` when it has no symbol for an
3241
- * address, so the text is honest but unnamed. A space means the text is a
3242
- * sentence or a demangled signature, never that form. The file path is never
3243
- * part of the test: an unresolved frame still names the library it ran in,
3244
- * which is what makes the evidence actionable.
3245
- */
3246
- declare function isUnresolvedSymbol(symbol: string): boolean;
3247
- /**
3248
- * One folded stack, in the format `flamegraph.pl` and every flamegraph viewer
3249
- * understands: `a;b;c` with `samples` samples ending at `c`.
3250
- */
3251
- interface FoldedStack {
3252
- /** Semicolon-joined symbol path, root first. */
3253
- stack: string;
3254
- /** The last symbol on the stack — the frame the samples were taken in. */
3255
- leaf: string;
3256
- /** Summed `event_count` of every sample folded into this stack. */
3257
- samples: number;
3258
- }
3259
- /**
3260
- * Typed accessor over the optional `perf_*` tables.
3261
- *
3262
- * These tables exist only when a perf trace was ingested; every accessor
3263
- * therefore checks `hasTable()` first and returns `[]`/`false` instead of
3264
- * letting SQLite throw `no such table`. The query layer is read-only and never
3265
- * creates the indexes HapRay's `ensure_perf_trace_indexes` would add.
3266
- */
3267
- declare class PerfQuery {
3268
- private readonly db;
3269
- constructor(db: QueryHandle);
3270
- /** True when `perf_sample` exists and contains at least one row. */
3271
- hasSamples(): boolean;
3272
- /**
3273
- * True when `perf_files` exists, so a frame can carry a symbol at all.
3274
- *
3275
- * A capture without it has no symbol table to resolve against: every frame
3276
- * is unnamed for that reason, not because its callchain was truncated. The
3277
- * distinction matters to the wording a reader gets.
3037
+ * A capture without it has no symbol table to resolve against: every frame
3038
+ * is unnamed for that reason, not because its callchain was truncated. The
3039
+ * distinction matters to the wording a reader gets.
3278
3040
  */
3279
3041
  hasSymbolTable(): boolean;
3280
3042
  /**
@@ -3421,176 +3183,255 @@ declare class PerfQuery {
3421
3183
  }
3422
3184
 
3423
3185
  /**
3424
- * One `native_hook` row with camelCase field names.
3186
+ * One row of `process` with camelCase field names.
3425
3187
  *
3426
- * `event_type` is alloc for `'AllocEvent'`/`'MmapEvent'`/`0`, free for
3427
- * `'FreeEvent'`/`'MunmapEvent'`/`1`, and anything else is neither. `null` means
3428
- * the column itself was NULL, which is not an allocation: the direction is
3429
- * unknown, so it stays `null` and the pairing layer counts it as `other`.
3430
- * `heapSize` is a magnitude: the stored sign carries no meaning, the pairing
3431
- * layer applies the direction. `allHeapSize` and `currentSizeDur` are read for
3432
- * callers but are never interpreted — their semantics are undocumented upstream.
3433
- */
3434
- interface NativeHookEvent {
3435
- id: number;
3436
- callchainId: number;
3188
+ * `startTs` is nanoseconds, but **`0` means absent, not time zero**: on the
3189
+ * measured 249MB trace `process.start_ts` is NULL on all 437 rows, so a
3190
+ * consumer must not read `startTs === 0` as "started at the trace origin".
3191
+ * The same NULL-to-0 rule applies to every other numeric field.
3192
+ *
3193
+ * `name` is `''` when the column is NULL (60 of the 437 real rows). Duplicate
3194
+ * non-empty names are common (`sh` ×86, `hidumper` ×46), so a `ProcessInfo`
3195
+ * identifies one row, not one logical process; see `ProcessQuery.byName`.
3196
+ */
3197
+ interface ProcessInfo {
3198
+ id: number;
3437
3199
  ipid: number;
3438
- /** `process.pid` resolved through `ipid`; the number space an app is known by. */
3439
3200
  pid: number;
3440
- itid: number;
3441
- eventType: number | string | null;
3442
- subTypeId: number;
3201
+ name: string;
3443
3202
  startTs: number;
3444
- endTs: number;
3445
- dur: number;
3446
- /** Heap address; `0` means the column was NULL, so the block cannot be freed. */
3447
- addr: number;
3448
- heapSize: number;
3449
- allHeapSize: number;
3450
- currentSizeDur: number;
3451
- lastLibId: number;
3452
- lastSymbolId: number;
3453
- }
3454
- /** One frame of a native callchain, ordered by `depth`. */
3455
- interface NativeHookFrame {
3456
- id: number;
3457
- callchainId: number;
3458
- depth: number;
3459
- ip: number;
3460
- symbolId: number;
3461
- fileId: number;
3462
- offset: number;
3463
- symbolOffset: number;
3464
- vaddr: number;
3203
+ switchCount: number;
3204
+ threadCount: number;
3205
+ sliceCount: number;
3206
+ memCount: number;
3465
3207
  }
3466
3208
  /**
3467
- * One `native_hook_statistic` row: a pre-aggregated alloc/free pair per
3468
- * callchain, with no per-allocation timestamp, thread or address.
3209
+ * One row of `thread` with camelCase field names.
3210
+ *
3211
+ * `startTs` and `endTs` are nanoseconds, but **`0` means absent, not time
3212
+ * zero**: on the measured 249MB trace `thread.end_ts` is NULL on all 1231
3213
+ * rows, and `startTs` can be NULL too. A consumer must not read
3214
+ * `endTs === 0` as "ended at the trace origin".
3469
3215
  */
3470
- interface NativeHookStatistic {
3216
+ interface ThreadInfo {
3471
3217
  id: number;
3472
- callchainId: number;
3218
+ itid: number;
3219
+ tid: number;
3220
+ name: string;
3221
+ startTs: number;
3222
+ endTs: number;
3473
3223
  ipid: number;
3474
- ts: number;
3475
- type: number | string;
3476
- subTypeId: number;
3477
- applyCount: number;
3478
- releaseCount: number;
3479
- applySize: number;
3480
- releaseSize: number;
3481
- lastLibId: number;
3482
- lastSymbolId: number;
3224
+ isMainThread: boolean;
3225
+ switchCount: number;
3483
3226
  }
3484
3227
  /**
3485
- * Typed, batched access to the `native_hook*` tables.
3486
- *
3487
- * The tables exist only when a capture ran `hiprofiler` with the `nativehook`
3488
- * plugin, so every accessor checks `sqlite_master` first and returns
3489
- * `[]`/`false`/an empty map instead of letting SQLite throw `no such table`.
3490
- * That is what lets the analyzer report a degraded proxy with a reason rather
3491
- * than crash on a plain hitrace capture.
3228
+ * Typed accessor over `process`.
3492
3229
  *
3493
- * `events` joins `process` on `ipid` and filters on `process.pid`, which is the
3494
- * same number space the rest of the package resolves an app to.
3230
+ * A truncated or sparse scene can lack the `process` table entirely (e.g. a
3231
+ * capture holding only `callstack` and `frame_slice`). Every accessor therefore
3232
+ * checks `hasTable()` first and returns `[]`/`undefined` instead of letting
3233
+ * SQLite throw `no such table: process` — the same guard idiom as the other
3234
+ * query classes use for their optional tables.
3495
3235
  */
3496
- declare class NativeHookQuery {
3236
+ declare class ProcessQuery {
3497
3237
  private readonly db;
3498
3238
  constructor(db: QueryHandle);
3499
- /** True when `native_hook` exists and holds at least one row. */
3500
- hasData(): boolean;
3501
- /** True when `native_hook_statistic` exists and holds at least one row. */
3502
- hasStatistics(): boolean;
3503
3239
  /**
3504
- * App events ordered by `(start_ts, id)`, optionally inside an inclusive
3505
- * `range` on `start_ts`.
3240
+ * Every process row, ordered by `id` ascending.
3506
3241
  *
3507
- * The `(start_ts, id)` tie-break is ours; upstream orders by timestamp alone,
3508
- * which makes a capture with equal timestamps depend on row order.
3242
+ * Ordering is fixed rather than left to SQLite so the result is byte-stable
3243
+ * across runs (D5). An absent table returns `[]`.
3244
+ */
3245
+ all(): ProcessInfo[];
3246
+ /**
3247
+ * The process row named `name`, or `undefined` if none exists.
3509
3248
  *
3510
- * `DISTINCT` on the event columns collapses the duplicate rows a repeated
3511
- * `process.ipid` would produce: a merged trace can carry two `process` rows
3512
- * with the same ipid, and a plain join then returns each event once per row,
3513
- * doubling every byte. `p.pid` is selected from the same ipid group, so the
3514
- * duplicate rows are identical.
3249
+ * **Duplicate names resolve to the lowest `id`.** The measured trace has
3250
+ * heavy duplication (`sh` ×86, `hidumper` ×46, `ls` ×38, `head` ×36) and
3251
+ * "return any matching row" would make output depend on row order, which
3252
+ * violates the determinism requirement (D5). `ORDER BY id LIMIT 1` fixes the
3253
+ * tie-break.
3254
+ *
3255
+ * Rows with `name IS NULL` map to `ProcessInfo.name === ''`, but
3256
+ * `byName('')` does **not** find them: SQL `name = ''` never matches NULL.
3257
+ * A NULL-named row is reachable only through `all()`. An absent table returns
3258
+ * `undefined`.
3515
3259
  */
3516
- events(pids: readonly number[], range?: TimeRange): NativeHookEvent[];
3517
- /** Frames of `callchainIds`, ordered by `(callchain_id, depth, id)`. */
3518
- frames(callchainIds: readonly number[]): Map<number, NativeHookFrame[]>;
3260
+ byName(name: string): ProcessInfo | undefined;
3519
3261
  /**
3520
- * Statistics rows for the app, ordered by `(ts, id)`.
3262
+ * The process row whose **`pid`** is `pid`, or `undefined` if none exists.
3521
3263
  *
3522
- * `DISTINCT` and the `process` guard mirror {@link events} for the same two
3523
- * reasons: a repeated ipid must not multiply rows, and a missing join table
3524
- * must degrade rather than throw.
3264
+ * Like {@link byName}, duplicate matches resolve to the lowest `id` so output
3265
+ * is deterministic (D5). This is the safe pid→ipid step: never compare a pid
3266
+ * against `thread.ipid` or another ipid column directly. An absent table
3267
+ * returns `undefined`.
3525
3268
  */
3526
- statistics(pids: readonly number[]): NativeHookStatistic[];
3527
- /** `data_dict` text for `ids`; ids absent from the table are simply missing. */
3528
- dataDict(ids: readonly number[]): Map<number, string>;
3269
+ byPid(pid: number): ProcessInfo | undefined;
3270
+ /**
3271
+ * One `pid` per requested name, **in the order the names were given**;
3272
+ * unknown names are skipped (so the result may be shorter than `names`).
3273
+ *
3274
+ * Each name resolves with the same lowest-`id` rule as `byName`. A name
3275
+ * repeated in `names` therefore yields its pid once per occurrence, and
3276
+ * names resolving to the same `pid` are not deduplicated. An absent table
3277
+ * returns `[]`.
3278
+ */
3279
+ pidsFor(names: string[]): number[];
3529
3280
  private hasTable;
3530
3281
  }
3531
-
3532
3282
  /**
3533
- * One binder-related `callstack` row with its arguments resolved.
3534
- *
3535
- * `args` is keyed by the `data_dict` text for `args.key`. A value becomes a
3536
- * string when `args.datatype = 1` and the value is present in `data_dict`;
3537
- * otherwise it stays the numeric `args.value`. Keys missing from `data_dict`
3538
- * are dropped, mirroring HapRay's loader.
3283
+ * Typed accessor over `thread`.
3539
3284
  *
3540
- * `code` is special-cased like HapRay: when its first whitespace-separated
3541
- * token starts with `0x`, the token is parsed as hexadecimal and stored as a
3542
- * number (for example `"0x10 Java Layer Dependent"` → `16`). A token that
3543
- * fails to parse leaves the original value untouched.
3544
- */
3545
- interface BinderEvent {
3546
- id: number;
3547
- ts: number;
3548
- dur: number;
3549
- name: string;
3550
- cat: string;
3551
- callid: number;
3552
- args: Record<string, string | number>;
3553
- }
3554
- /**
3555
- * Typed accessor over binder events stored in `callstack`.
3285
+ * Every method returns `all()`'s row shape in `id` ascending order.
3286
+ * `mainThreads()` and `forProcess()` filter that set rather than issuing their
3287
+ * own SQL, so their NULL handling cannot drift from `all()`. `forPid()` joins
3288
+ * through `process` and reuses the same `toThread` mapping, so only its
3289
+ * predicate differs.
3556
3290
  *
3557
- * Events are the `callstack` rows whose `name` contains `binder`, with their
3558
- * `args` rows joined through `callstack.argsetid = args.argset`. Ordering is
3559
- * `id`; `args` within one event follow `args.id`, so a repeated key resolves
3560
- * to its last row deterministically. `callstack`, `args` and `data_dict` are
3561
- * core trace_streamer tables, so no `hasTable()` guard is used.
3291
+ * A truncated or sparse scene can lack the `thread` table (the wakeup analysis
3292
+ * joins it unguarded), so every accessor checks `hasTable()` first and returns
3293
+ * `[]` instead of letting SQLite throw `no such table: thread`, matching the
3294
+ * other query classes' guard idiom.
3562
3295
  */
3563
- declare class BinderQuery {
3296
+ declare class ThreadQuery {
3564
3297
  private readonly db;
3565
3298
  constructor(db: QueryHandle);
3566
- /** All binder events, ordered by `callstack.id`. */
3567
- events(): BinderEvent[];
3299
+ /** Every thread row, ordered by `id` ascending. An absent table returns `[]`. */
3300
+ all(): ThreadInfo[];
3301
+ /**
3302
+ * Rows with `is_main_thread = 1`.
3303
+ *
3304
+ * This is one row per process, not one row overall: the measured trace has
3305
+ * 437 main threads over 437 processes.
3306
+ */
3307
+ mainThreads(): ThreadInfo[];
3308
+ /**
3309
+ * Rows whose `ipid` belongs to the given process, ordered by `id`.
3310
+ *
3311
+ * **The argument is an `ipid`, not a `pid`.** `frame_slice.ipid` and
3312
+ * `callstack.ipid` are ipids, so this is the right accessor for frame and
3313
+ * binder analysis. If you have a `pid` — for example the value
3314
+ * `ProcessQuery.pidsFor()` returns — use {@link forPid} instead.
3315
+ *
3316
+ * Passing a pid here is not merely "not found": ipids and pids are different
3317
+ * number spaces that overlap, so a pid can name a *different* process's
3318
+ * ipid. Measured on the 249MB trace, of 437 processes 396 pids are not a
3319
+ * legal ipid (this returns `[]`), 1 pid happens to equal its own ipid, and
3320
+ * **40 silently return another process's threads**. For example `hilogd`
3321
+ * has `ipid=4, pid=113`, and ipid 113 belongs to `sh` — so
3322
+ * `forProcess(113)` returns `sh`'s thread with no error.
3323
+ */
3324
+ forProcess(ipid: number): ThreadInfo[];
3325
+ /**
3326
+ * Rows of the process whose **`pid`** is `pid`, ordered by `id`.
3327
+ *
3328
+ * Resolves the pid through `process` (`thread.ipid = process.ipid`) rather
3329
+ * than comparing it against `thread.ipid` directly, so a pid can never be
3330
+ * mistaken for an ipid — see {@link forProcess} for the measured overlap.
3331
+ * Measured: `hilogd` (pid 113) yields its 6 threads, `ohos.sceneboard` 32,
3332
+ * `render_service` 17, `sh` 1. Pids are unique on the measured traces, so
3333
+ * the join cannot fan out; an unknown pid returns `[]`. The join reads both
3334
+ * `thread` and `process`, so an absent one of them returns `[]`.
3335
+ */
3336
+ forPid(pid: number): ThreadInfo[];
3337
+ private hasTable;
3568
3338
  }
3569
3339
 
3570
3340
  /**
3571
- * One `app_startup` row with camelCase field names.
3341
+ * One row of `sched_slice` with camelCase field names.
3572
3342
  *
3573
- * `startTime`/`endTime` are nanoseconds. `startName` is kept as the raw
3574
- * integer column (the table stores an id there); `0`/`''` mean absent.
3343
+ * `ts`, `dur` and `tsEnd` are nanoseconds. Null numerics become `0` and null
3344
+ * text becomes `''` through `num`/`str`; `0` therefore means absent.
3575
3345
  */
3576
- interface StartupRecord {
3346
+ interface SchedSlice {
3577
3347
  id: number;
3578
- callId: number;
3348
+ ts: number;
3349
+ dur: number;
3350
+ tsEnd: number;
3351
+ cpu: number;
3352
+ itid: number;
3579
3353
  ipid: number;
3580
- tid: number;
3581
- startTime: number;
3582
- endTime: number;
3583
- startName: number;
3584
- packedName: string;
3354
+ endState: string;
3355
+ priority: number;
3356
+ argSetid: number;
3585
3357
  }
3586
3358
  /**
3587
- * Typed accessor over the optional `app_startup` table.
3359
+ * One wakeup row of `instant` with camelCase field names.
3588
3360
  *
3589
- * The table is absent in traces that did not capture startup events, so every
3590
- * accessor returns `[]` in that case instead of throwing. Ordering is
3591
- * `start_time, id`; ranges are inclusive and apply to `start_time`.
3361
+ * `InstantQuery.wakeups()` keeps only `sched_wakeup`/`sched_waking` rows whose
3362
+ * `ref_type` is `itid` and whose `ref` and `wakeup_from` are both present, so
3363
+ * those two fields are non-null in practice; they are still normalised to `0`
3364
+ * like every other numeric column. `instant` has no `id` column.
3592
3365
  */
3593
- declare class StartupQuery {
3366
+ interface WakeupEvent {
3367
+ ts: number;
3368
+ name: string;
3369
+ ref: number;
3370
+ wakeupFrom: number;
3371
+ refType: string;
3372
+ value: number;
3373
+ }
3374
+ /**
3375
+ * Typed accessor over `sched_slice`.
3376
+ *
3377
+ * Ordering is always `ts, id` so equal timestamps keep a stable, documented
3378
+ * order. Time ranges are inclusive at both ends. `sched_slice` is a core
3379
+ * trace_streamer table, so no `hasTable()` guard is used.
3380
+ */
3381
+ declare class SchedQuery {
3382
+ private readonly db;
3383
+ constructor(db: QueryHandle);
3384
+ /** All slices in `[startNs, endNs]` (or the whole trace), ordered by `ts, id`. */
3385
+ all(range?: TimeRange): SchedSlice[];
3386
+ /**
3387
+ * Slices belonging to any of `itids`, ordered by `ts, id`.
3388
+ *
3389
+ * An empty `itids` returns `[]` without issuing `IN ()`, which SQLite
3390
+ * rejects.
3391
+ */
3392
+ forItids(itids: number[], range?: TimeRange): SchedSlice[];
3393
+ }
3394
+ /**
3395
+ * Typed accessor over `instant`, limited to scheduler wakeup events.
3396
+ *
3397
+ * The predicate is fixed: `sched_wakeup`/`sched_waking`, `ref_type = 'itid'`,
3398
+ * and both `ref` and `wakeup_from` present. `instant` has no `id` column, so
3399
+ * the stable ordering is `ts, ref, wakeup_from`.
3400
+ */
3401
+ declare class InstantQuery {
3402
+ private readonly db;
3403
+ constructor(db: QueryHandle);
3404
+ /**
3405
+ * Wakeup events whose `ts` is in `[startNs, endNs]`, ordered by
3406
+ * `ts, ref, wakeup_from`.
3407
+ */
3408
+ wakeups(range: TimeRange): WakeupEvent[];
3409
+ }
3410
+
3411
+ /**
3412
+ * One `app_startup` row with camelCase field names.
3413
+ *
3414
+ * `startTime`/`endTime` are nanoseconds. `startName` is kept as the raw
3415
+ * integer column (the table stores an id there); `0`/`''` mean absent.
3416
+ */
3417
+ interface StartupRecord {
3418
+ id: number;
3419
+ callId: number;
3420
+ ipid: number;
3421
+ tid: number;
3422
+ startTime: number;
3423
+ endTime: number;
3424
+ startName: number;
3425
+ packedName: string;
3426
+ }
3427
+ /**
3428
+ * Typed accessor over the optional `app_startup` table.
3429
+ *
3430
+ * The table is absent in traces that did not capture startup events, so every
3431
+ * accessor returns `[]` in that case instead of throwing. Ordering is
3432
+ * `start_time, id`; ranges are inclusive and apply to `start_time`.
3433
+ */
3434
+ declare class StartupQuery {
3594
3435
  private readonly db;
3595
3436
  constructor(db: QueryHandle);
3596
3437
  /** All startup rows in `[startNs, endNs]` (or the whole trace). */
@@ -3605,7 +3446,45 @@ declare class StartupQuery {
3605
3446
  private hasTable;
3606
3447
  }
3607
3448
 
3608
- type EvidenceKind = 'no_data' | 'jank' | 'frame_load' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'native_memory' | 'hilog_match' | 'gc_pressure' | 'rs_skip' | 'startup' | 'ui_tree' | 'tech_stack' | 'duplicate_asset' | 'oversized_asset' | 'symbol_stats' | 'unresolved_symbol';
3449
+ /**
3450
+ * One row of `thread_state` with camelCase field names.
3451
+ *
3452
+ * `ts` and `dur` are nanoseconds. `0`/`''` mean absent, as everywhere else in
3453
+ * the query layer. The P1 schema has no `id` column on this table, so no
3454
+ * identifier is exposed; ordering uses `ts, itid, state`.
3455
+ */
3456
+ interface ThreadState {
3457
+ ts: number;
3458
+ dur: number;
3459
+ cpu: number;
3460
+ itid: number;
3461
+ tid: number;
3462
+ pid: number;
3463
+ state: string;
3464
+ argSetid: number;
3465
+ }
3466
+ /**
3467
+ * Typed accessor over `thread_state`.
3468
+ *
3469
+ * Every method orders by `ts, itid, state` — the secondary keys make equal
3470
+ * timestamps deterministic even though the table has no `id`. Time ranges are
3471
+ * inclusive at both ends. `thread_state` is a core trace_streamer table, so no
3472
+ * `hasTable()` guard is used.
3473
+ */
3474
+ declare class ThreadStateQuery {
3475
+ private readonly db;
3476
+ constructor(db: QueryHandle);
3477
+ /** All states in `[startNs, endNs]` (or the whole trace). */
3478
+ all(range?: TimeRange): ThreadState[];
3479
+ /**
3480
+ * States of the given `itids`, ordered by `ts, itid, state`.
3481
+ *
3482
+ * An empty `itids` returns `[]` without issuing `IN ()`.
3483
+ */
3484
+ forItids(itids: number[], range?: TimeRange): ThreadState[];
3485
+ }
3486
+
3487
+ type EvidenceKind = 'no_data' | 'jank' | 'frame_load' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'native_memory' | 'hilog_match' | 'gc_pressure' | 'rs_skip' | 'startup' | 'ui_tree' | 'tech_stack' | 'duplicate_asset' | 'oversized_asset' | 'symbol_stats' | 'unresolved_symbol' | 'redundant_file';
3609
3488
  /**
3610
3489
  * A follow-up query an agent can issue to drill into an evidence item.
3611
3490
  *
@@ -3751,6 +3630,16 @@ interface AnalyzeContext {
3751
3630
  callstacks?: CallstackQuery;
3752
3631
  perf?: PerfQuery;
3753
3632
  binder?: BinderQuery;
3633
+ /**
3634
+ * The binder analysis, when a caller already computed it.
3635
+ *
3636
+ * The fault tree's `ipc_binder` section is derived from this typed result
3637
+ * rather than from a shared JSON file the way HapRay does it — at its own
3638
+ * revision HapRay's registry order makes that file stale, so the section
3639
+ * reports nothing. When absent the fault tree computes the analysis itself
3640
+ * from `db`, so the section never depends on analyzer ordering.
3641
+ */
3642
+ binderAnalysis?: BinderAnalysis;
3754
3643
  startup?: StartupQuery;
3755
3644
  /**
3756
3645
  * The memory-plugin tables (`process_measure` joined to its filter). Present
@@ -3772,6 +3661,12 @@ interface AnalyzeContext {
3772
3661
  * with no user configuration still produces HapRay's numbers.
3773
3662
  */
3774
3663
  hilogRules?: readonly HilogRule[];
3664
+ /**
3665
+ * The raw `redundant_file.txt` a scene carried, when it did. HapRay's
3666
+ * cold-start redundant-file I/O reads this file; the analyzer reports
3667
+ * `no_data` with a reason when it is absent rather than three zeros.
3668
+ */
3669
+ redundantFile?: string;
3775
3670
  /**
3776
3671
  * The scene's flattened UI tree, when it carried a `ui.json`. The `ui`
3777
3672
  * analyzer decides from what it is given rather than declaring `ui.tree` as a
@@ -3798,26 +3693,578 @@ interface AnalyzeContext {
3798
3693
  deviceId: string;
3799
3694
  }
3800
3695
  /**
3801
- * An analyzer's output.
3802
- *
3803
- * Both arrays are explicitly sorted by the analyzer (D5: output must be
3804
- * byte-stable for identical input). `metrics` is sorted by `id`; `evidence`
3805
- * by `(kind, startNs, id)`.
3696
+ * An analyzer's output.
3697
+ *
3698
+ * Both arrays are explicitly sorted by the analyzer (D5: output must be
3699
+ * byte-stable for identical input). `metrics` is sorted by `id`; `evidence`
3700
+ * by `(kind, startNs, id)`.
3701
+ */
3702
+ interface AnalyzeResult {
3703
+ metrics: Metric[];
3704
+ evidence: Evidence[];
3705
+ }
3706
+ /**
3707
+ * One analysis pass over a trace.
3708
+ *
3709
+ * `requires` is checked against the capability matrix by the caller, not by
3710
+ * `run`: an analyzer never has to decide what "unsupported device" means.
3711
+ */
3712
+ interface Analyzer {
3713
+ readonly id: string;
3714
+ readonly requires: CapabilityId[];
3715
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
3716
+ }
3717
+
3718
+ /**
3719
+ * Cold-start redundant-file I/O (HapRay parity row 21).
3720
+ *
3721
+ * HapRay counts the file reads a launch performs more than once, from
3722
+ * `htrace/stepN/redundant_file.txt`. The file's producer is not part of
3723
+ * HapRay's Python pipeline, so this module defines the contract explicitly
3724
+ * rather than guessing at an undocumented format:
3725
+ *
3726
+ * # comment
3727
+ * /data/storage/el2/base/files/config.json USED
3728
+ * /data/storage/el2/base/files/cache.bin UNUSED
3729
+ * /data/storage/el2/base/files/notes.txt
3730
+ *
3731
+ * One path per line, an optional `USED` / `UNUSED` marker, `#` comments and
3732
+ * blank lines ignored. A path with no marker is counted as used — a read that
3733
+ * happened — because the alternative is to silently drop it.
3734
+ *
3735
+ * `reads` counts every line; `files` counts distinct paths. A path read three
3736
+ * times is one file and three reads, which is the distinction the capability
3737
+ * exists to make.
3738
+ */
3739
+
3740
+ /** One path in a redundant-file report, with the reads it accounted for. */
3741
+ interface RedundantFileEntry {
3742
+ readonly path: string;
3743
+ readonly reads: number;
3744
+ readonly used: boolean;
3745
+ }
3746
+ /** A parsed `redundant_file.txt`. */
3747
+ interface RedundantFileReport {
3748
+ /** Every line with a path; a repeated path contributes each time. */
3749
+ readonly reads: number;
3750
+ /** Distinct paths. */
3751
+ readonly files: readonly RedundantFileEntry[];
3752
+ readonly used: number;
3753
+ readonly unused: number;
3754
+ }
3755
+ /**
3756
+ * Parse a `redundant_file.txt`.
3757
+ *
3758
+ * A line that is neither blank, a comment, nor `<path> [USED|UNUSED]` is a
3759
+ * refusal naming its line number. Skipping it would undercount the very thing
3760
+ * the capability reports, and a report that silently drops input is worse than
3761
+ * no report.
3762
+ */
3763
+ declare function parseRedundantFile(text: string): RedundantFileReport;
3764
+ /**
3765
+ * The analyzer.
3766
+ *
3767
+ * No capability is required: the report is a scene file, so it is available
3768
+ * wherever the capture produced one. Absence of the file is `no_data` with a
3769
+ * reason, never three zeros.
3770
+ */
3771
+ declare class RedundantFileAnalyzer implements Analyzer {
3772
+ readonly id = "redundant-file";
3773
+ readonly requires: never[];
3774
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
3775
+ }
3776
+
3777
+ /**
3778
+ * HapFlow static/dynamic integration (HapRay parity row 29).
3779
+ *
3780
+ * HapRay produces `fileDepGraph.json`, `moduleDepGraph.json` and
3781
+ * `hierarchical_integrated_data.json` from a Homecheck checkout — a Node
3782
+ * process with `node_modules` and a 16 GiB heap — and assigns a file to a HAR
3783
+ * by path segments and basename. Its viewer is a log-only stub.
3784
+ *
3785
+ * This port keeps the arithmetic and drops the prerequisites: the file list
3786
+ * and module declarations are inputs, so the graph is a deterministic pure
3787
+ * function. There is no Homecheck checkout to keep in sync and no heap
3788
+ * requirement.
3789
+ *
3790
+ * Ownership is segment-aware. HapRay compares path prefixes as strings, so
3791
+ * `feature-detail/…` would match a module called `feature`; here a path is
3792
+ * split into segments and the longest matching module path wins, which is what
3793
+ * a person reading the tree would say.
3794
+ */
3795
+ /** A module (HAR or HSP) and the directory it owns. */
3796
+ interface ModuleDecl {
3797
+ readonly name: string;
3798
+ /** The directory prefix, relative to the project root, e.g. `feature`. */
3799
+ readonly path: string;
3800
+ }
3801
+ /** One file and the module that owns it, if any. */
3802
+ interface DepGraphFile {
3803
+ readonly path: string;
3804
+ /** Absent when no module's path is a segment-prefix of this file's path. */
3805
+ readonly module?: string;
3806
+ }
3807
+ /** One import edge between two files. */
3808
+ interface DepGraphEdge {
3809
+ readonly from: string;
3810
+ readonly to: string;
3811
+ }
3812
+ /** How many edges cross from one module to another. */
3813
+ interface HarEdge {
3814
+ readonly from: string;
3815
+ readonly to: string;
3816
+ readonly count: number;
3817
+ }
3818
+ /** A dependency cycle's cost: the sum of the modules' durations along it. */
3819
+ interface TimingCycle {
3820
+ readonly modules: readonly string[];
3821
+ readonly ms: number;
3822
+ }
3823
+ interface DepGraph {
3824
+ readonly files: readonly DepGraphFile[];
3825
+ readonly edges: readonly DepGraphEdge[];
3826
+ /** Cross-module edge counts, sorted by `(from, to)`. */
3827
+ readonly harEdges: readonly HarEdge[];
3828
+ /** Only non-empty when per-module durations were supplied. */
3829
+ readonly timingCycles: readonly TimingCycle[];
3830
+ }
3831
+ /**
3832
+ * Build the dependency graph.
3833
+ *
3834
+ * `files` are project-relative paths; `modules` declare ownership; `edges`
3835
+ * are imports between those paths. Output order is fixed — files by path,
3836
+ * edges by `(from, to)`, cross-module counts by `(from, to)` — so two runs
3837
+ * over the same input produce identical JSON.
3838
+ */
3839
+ declare function buildDepGraph(files: readonly string[], modules: readonly ModuleDecl[], edges?: readonly DepGraphEdge[], durationsMs?: Readonly<Record<string, number>>): DepGraph;
3840
+
3841
+ /**
3842
+ * Which way a metric improves.
3843
+ *
3844
+ * A metric id absent from {@link METRIC_DIRECTIONS} has no known direction:
3845
+ * a rise is neither good nor bad, so the comparison reports it as
3846
+ * `incomparable` rather than guessing. Guessing is worse than admitting
3847
+ * ignorance here — a baseline report that calls a regression an improvement
3848
+ * sends the reader after the wrong problem.
3849
+ */
3850
+ type MetricDirection = 'lower' | 'higher';
3851
+ /**
3852
+ * The direction of every metric the analyzers emit.
3853
+ *
3854
+ * Frame throughput counts are higher-is-better (`frame.fps`,
3855
+ * `frame.count`, `frame.rendered.count`); every frame quality rate and every
3856
+ * latency, memory, redundant-thread and startup figure is lower-is-better.
3857
+ * `fault.*` counters are event counts whose meaning depends on the event, so
3858
+ * they are deliberately absent. Degraded proxies are absent too: a
3859
+ * `*.degraded` zero is not a measurement to compare.
3860
+ */
3861
+ declare const METRIC_DIRECTIONS: Readonly<Record<string, MetricDirection>>;
3862
+ type DeltaStatus = 'improved' | 'regressed' | 'unchanged' | 'added' | 'removed' | 'incomparable';
3863
+ interface MetricDelta {
3864
+ readonly id: string;
3865
+ readonly unit: MetricUnit;
3866
+ readonly baseline: number | string | null;
3867
+ readonly current: number | string | null;
3868
+ /** Numeric difference (current - baseline); absent for non-numeric or added/removed. */
3869
+ readonly delta?: number;
3870
+ /** Percent change; absent when baseline is 0 or either side is non-numeric. */
3871
+ readonly deltaPct?: number;
3872
+ readonly fidelity: Fidelity;
3873
+ readonly status: DeltaStatus;
3874
+ }
3875
+ interface BaselineComparison {
3876
+ readonly rows: MetricDelta[];
3877
+ /** Count of rows per status; all six keys are always present. */
3878
+ readonly totals: Record<DeltaStatus, number>;
3879
+ }
3880
+ /**
3881
+ * Compare two analyses metric by metric.
3882
+ *
3883
+ * The rows are the union of both metric id sets sorted by id, so the output is
3884
+ * byte-identical for the same inputs (D5) and two runs can be diffed directly.
3885
+ * Only metrics present on both sides with numeric values can be improved or
3886
+ * regressed; everything else is reported as what it is — `added`, `removed`,
3887
+ * or `incomparable` — and never silently dropped.
3888
+ *
3889
+ * `deltaPct` divides by `|baseline|`, so a metric that moved from -10 to -5
3890
+ * reads as a 50% change toward zero rather than a sign-flipped one. A zero
3891
+ * baseline has no percentage: every change is infinitely large, which is not
3892
+ * a useful number.
3893
+ */
3894
+ declare function compareResults(baseline: AnalyzeResult, current: AnalyzeResult): BaselineComparison;
3895
+
3896
+ /**
3897
+ * Scene + step comparison (HapRay parity row 35, the pivot half).
3898
+ *
3899
+ * HapRay pivots a comparison by scene + step + version. `compareResults`
3900
+ * compares two flat metric sets, which is right for one scene and wrong for a
3901
+ * multi-step run: merging the steps would attribute every change to "the
3902
+ * run" instead of to the step that moved.
3903
+ *
3904
+ * `compareScenes` keeps the attribution. Each step is compared against the
3905
+ * same step id on the baseline, and a step that exists on one side only is
3906
+ * reported as `added` or `removed` rather than silently dropped — the same
3907
+ * honesty rule `compareResults` applies to metrics.
3908
+ *
3909
+ * Steps are sorted by id, so the output is byte-identical for the same input
3910
+ * whatever order the caller supplies them in.
3911
+ */
3912
+
3913
+ /** One step's analysis, named by the step it belongs to. */
3914
+ interface SceneStep {
3915
+ readonly stepId: string;
3916
+ readonly result: AnalyzeResult;
3917
+ }
3918
+ /** What the comparison could say about one step. */
3919
+ type StepStatus = 'compared' | 'added' | 'removed';
3920
+ interface StepComparison {
3921
+ readonly stepId: string;
3922
+ readonly status: StepStatus;
3923
+ /**
3924
+ * Metric-by-metric rows. For `added` and `removed` every row is the one-sided
3925
+ * classification `compareResults` already produces, so a reader sees the
3926
+ * metrics a step brought or took away.
3927
+ */
3928
+ readonly rows: readonly MetricDelta[];
3929
+ }
3930
+ interface ScenesComparison {
3931
+ /** Sorted by step id. */
3932
+ readonly steps: readonly StepComparison[];
3933
+ /** Steps only the baseline had. */
3934
+ readonly removed: readonly string[];
3935
+ /** Steps only the current run had. */
3936
+ readonly added: readonly string[];
3937
+ }
3938
+ /**
3939
+ * Compare two multi-step runs, step by step.
3940
+ *
3941
+ * A duplicate step id on one side is a caller error — the pivot would be
3942
+ * ambiguous — so it is refused rather than resolved by picking one.
3943
+ */
3944
+ declare function compareScenes(baseline: readonly SceneStep[], current: readonly SceneStep[]): ScenesComparison;
3945
+ /** Stable JSON for the comparison; `JSON.stringify` of the same shape. */
3946
+ declare function renderScenesComparison(comparison: ScenesComparison): string;
3947
+
3948
+ /** Sorts steps by id; exported for a caller assembling them from a run. */
3949
+ declare function sortSteps(steps: readonly SceneStep[]): SceneStep[];
3950
+
3951
+ /**
3952
+ * Executing one scenario action against a device.
3953
+ *
3954
+ * The split with the runner is deliberate: this module performs exactly one
3955
+ * action and throws when it fails, while the runner owns the record — when it
3956
+ * happened, whether the step survived it, and what the trace says. That keeps
3957
+ * "did it work" in one place and "what do we remember about it" in another.
3958
+ *
3959
+ * Quoting lives in `GestureDriver`, not here: it already knows that the device
3960
+ * shell needs `'…'` and that a quote inside a text argument must be escaped.
3961
+ * Quoting again here would send the quote characters to the device.
3962
+ *
3963
+ * Selector actions (P17) need to see the screen, so they take a `dump` in the
3964
+ * action context rather than a device method: reading the UI tree is
3965
+ * `uitest dumpLayout` plus a file transfer, which the collector owns and the
3966
+ * runner knows the path for. Passing a closure keeps `ActionDevice` unchanged,
3967
+ * so `Device` still satisfies it structurally.
3968
+ */
3969
+
3970
+ /** The device surface actions need. `Device` satisfies it structurally. */
3971
+ interface ActionDevice {
3972
+ readonly id: string;
3973
+ shell(cmd: string): Promise<{
3974
+ stdout: string;
3975
+ stderr: string;
3976
+ code: number;
3977
+ }>;
3978
+ gesture(g: Gesture): Promise<GestureResult>;
3979
+ }
3980
+ /**
3981
+ * What a selector action needs beyond the device: a fresh look at the screen.
3982
+ *
3983
+ * Optional so a coordinate-only scenario keeps calling `executeAction` with
3984
+ * three arguments; a selector action without one is a typed refusal rather
3985
+ * than a crash.
3986
+ */
3987
+ interface ActionContext {
3988
+ readonly dump: () => Promise<readonly UiNode[]>;
3989
+ }
3990
+ /**
3991
+ * Perform one action and return what the device said.
3992
+ *
3993
+ * `launch` and `forceStop` use the scenario's app; a `wait` sleeps without a
3994
+ * device call. A `marker` is refused here — the runner records markers with a
3995
+ * device-uptime instant, and having two layers able to "execute" one would
3996
+ * let them disagree about whether it happened.
3997
+ */
3998
+ declare function executeAction(device: ActionDevice, app: string, action: ScenarioAction, context?: ActionContext): Promise<{
3999
+ output?: string;
4000
+ }>;
4001
+
4002
+ /**
4003
+ * The scenario runner: ordered steps, one capture window each.
4004
+ *
4005
+ * The shape that matters is the phase order. `setup` runs before the capture
4006
+ * so the state you want to measure is already on screen; `actions` run
4007
+ * *inside* the window so the gesture that causes the work is in the trace;
4008
+ * `cleanup` runs after, always. HapRay's DSL parses setup and cleanup and
4009
+ * never executes them — executing all three is why this exists.
4010
+ *
4011
+ * Nothing here analyzes. A step directory is a scene, so `ohos-perf analyze`,
4012
+ * `report` and `query` apply to it unchanged.
4013
+ */
4014
+
4015
+ /** One action's outcome, as `steps.json` records it. */
4016
+ interface ActionOutcome {
4017
+ readonly action: ScenarioAction;
4018
+ /** Device uptime in ns, read immediately before the action; absent when the read failed. */
4019
+ readonly atNs?: number;
4020
+ /** Host clock at the action, ms. */
4021
+ readonly atMs: number;
4022
+ readonly ok: boolean;
4023
+ readonly output?: string;
4024
+ readonly error?: string;
4025
+ }
4026
+ /** One assertion's outcome, as `steps.json` records it. */
4027
+ interface ExpectationOutcome {
4028
+ /** What was asserted, in the author's terms — `present: text containing "Done"`. */
4029
+ readonly label: string;
4030
+ readonly ok: boolean;
4031
+ /** Nodes matched, or for `foreground`, the nodes belonging to the app. */
4032
+ readonly actual: number;
4033
+ /** Why it failed, and what the screen held; absent when it held. */
4034
+ readonly detail?: string;
4035
+ }
4036
+ interface RunStepResult {
4037
+ readonly round: number;
4038
+ readonly index: number;
4039
+ readonly id: string;
4040
+ readonly name: string;
4041
+ readonly status: 'ok' | 'failed';
4042
+ /** Present only when a scene exists on disk. */
4043
+ readonly sceneDir?: string;
4044
+ readonly startedAtMs: number;
4045
+ readonly durationMs: number;
4046
+ readonly actions: readonly ActionOutcome[];
4047
+ /** Present only when the step declared `expect`. */
4048
+ readonly expectations?: readonly ExpectationOutcome[];
4049
+ readonly error?: string;
4050
+ }
4051
+ interface RunResult {
4052
+ readonly scenario: string;
4053
+ readonly app: string;
4054
+ readonly device: {
4055
+ id: string;
4056
+ kind: string;
4057
+ };
4058
+ readonly rounds: number;
4059
+ readonly status: 'completed' | 'failed';
4060
+ readonly steps: readonly RunStepResult[];
4061
+ readonly startedAtMs: number;
4062
+ readonly durationMs: number;
4063
+ readonly pids: {
4064
+ pids: readonly number[];
4065
+ processNames: readonly string[];
4066
+ };
4067
+ /** Absent when the device would not report one. Never a fabricated `0.0.0`. */
4068
+ readonly appVersion?: string;
4069
+ }
4070
+ /** The collect request one step turns into. Mirrors `Device.collect`. */
4071
+ interface RunnerCollectOptions {
4072
+ app: string;
4073
+ durationMs: number;
4074
+ sceneRoot: string;
4075
+ step: SceneStepRef;
4076
+ procfs?: boolean;
4077
+ hiprofiler?: {
4078
+ plugins: readonly HiprofilerPluginName[];
4079
+ };
4080
+ hiperf?: {
4081
+ frequency?: number;
4082
+ };
4083
+ hidumper?: boolean;
4084
+ uitest?: boolean;
4085
+ hilog?: boolean;
4086
+ }
4087
+ /** The device surface the runner needs. `Device` satisfies it structurally. */
4088
+ interface RunnerDevice {
4089
+ readonly id: string;
4090
+ readonly kind: string;
4091
+ shell(cmd: string): Promise<{
4092
+ stdout: string;
4093
+ stderr: string;
4094
+ code: number;
4095
+ }>;
4096
+ gesture(g: Gesture): Promise<GestureResult>;
4097
+ collect(opts: RunnerCollectOptions): Promise<{
4098
+ ingest(): Promise<{
4099
+ close(): void;
4100
+ }>;
4101
+ }>;
4102
+ /**
4103
+ * Flattened on-screen UI tree, for `expect` and selector actions.
4104
+ *
4105
+ * Optional because a coordinate-only scenario never needs a screen, and a
4106
+ * test that does not assert should not have to fake one. A step that does
4107
+ * assert on a device without it is a named refusal, not a crash.
4108
+ */
4109
+ uiTree?(): Promise<readonly UiNode[]>;
4110
+ }
4111
+ interface RunOptions {
4112
+ readonly outDir: string;
4113
+ /** Overrides the scenario's own `rounds` when set. */
4114
+ readonly rounds?: number;
4115
+ /** Step ids to run; order in the scenario wins. */
4116
+ readonly only?: readonly string[];
4117
+ /** Continue after a failed step instead of stopping. */
4118
+ readonly keepGoing?: boolean;
4119
+ /** Injected clock, for tests. */
4120
+ readonly now?: () => number;
4121
+ }
4122
+ /**
4123
+ * Run a scenario: every selected (round, step) pair, one scene each.
4124
+ *
4125
+ * The returned result is what `steps.json` records; the files are written
4126
+ * before returning, on the success and the failure path alike, so a run that
4127
+ * stopped at step 2 still says what step 1 produced.
4128
+ */
4129
+ declare class ScenarioRunner {
4130
+ private readonly device;
4131
+ private readonly opts;
4132
+ private readonly now;
4133
+ constructor(device: RunnerDevice, opts: RunOptions);
4134
+ run(scenario: Scenario): Promise<RunResult>;
4135
+ /**
4136
+ * The steps to run, in scenario order.
4137
+ *
4138
+ * `--only` is a filter, not an ordering: typing `scroll,open` still runs
4139
+ * `open` first, because a step may depend on the state a previous one left.
4140
+ */
4141
+ private selectedSteps;
4142
+ private runStep;
4143
+ /**
4144
+ * Perform one action and record it; never throws.
4145
+ *
4146
+ * A `marker` is recorded here, not executed: it is an annotation with a
4147
+ * device-uptime instant — the thing that lets a later query line a tap up
4148
+ * with a trace row — and there is no trace event behind it. Recording it in
4149
+ * the runner is what keeps "it happened" in the same place as "when".
4150
+ */
4151
+ private perform;
4152
+ }
4153
+ /**
4154
+ * Write `testInfo.json`, `steps.json` and `pids.json` into a run directory.
4155
+ *
4156
+ * Pretty-printed with two spaces and one trailing newline, like `scene.json`,
4157
+ * so a run is diff-friendly and byte-stable apart from its clock fields.
4158
+ */
4159
+ declare function writeRunFiles(outDir: string, result: RunResult): void;
4160
+
4161
+ /**
4162
+ * One `native_hook` row with camelCase field names.
4163
+ *
4164
+ * `event_type` is alloc for `'AllocEvent'`/`'MmapEvent'`/`0`, free for
4165
+ * `'FreeEvent'`/`'MunmapEvent'`/`1`, and anything else is neither. `null` means
4166
+ * the column itself was NULL, which is not an allocation: the direction is
4167
+ * unknown, so it stays `null` and the pairing layer counts it as `other`.
4168
+ * `heapSize` is a magnitude: the stored sign carries no meaning, the pairing
4169
+ * layer applies the direction. `allHeapSize` and `currentSizeDur` are read for
4170
+ * callers but are never interpreted — their semantics are undocumented upstream.
4171
+ */
4172
+ interface NativeHookEvent {
4173
+ id: number;
4174
+ callchainId: number;
4175
+ ipid: number;
4176
+ /** `process.pid` resolved through `ipid`; the number space an app is known by. */
4177
+ pid: number;
4178
+ itid: number;
4179
+ eventType: number | string | null;
4180
+ subTypeId: number;
4181
+ startTs: number;
4182
+ endTs: number;
4183
+ dur: number;
4184
+ /** Heap address; `0` means the column was NULL, so the block cannot be freed. */
4185
+ addr: number;
4186
+ heapSize: number;
4187
+ allHeapSize: number;
4188
+ currentSizeDur: number;
4189
+ lastLibId: number;
4190
+ lastSymbolId: number;
4191
+ }
4192
+ /** One frame of a native callchain, ordered by `depth`. */
4193
+ interface NativeHookFrame {
4194
+ id: number;
4195
+ callchainId: number;
4196
+ depth: number;
4197
+ ip: number;
4198
+ symbolId: number;
4199
+ fileId: number;
4200
+ offset: number;
4201
+ symbolOffset: number;
4202
+ vaddr: number;
4203
+ }
4204
+ /**
4205
+ * One `native_hook_statistic` row: a pre-aggregated alloc/free pair per
4206
+ * callchain, with no per-allocation timestamp, thread or address.
3806
4207
  */
3807
- interface AnalyzeResult {
3808
- metrics: Metric[];
3809
- evidence: Evidence[];
4208
+ interface NativeHookStatistic {
4209
+ id: number;
4210
+ callchainId: number;
4211
+ ipid: number;
4212
+ ts: number;
4213
+ type: number | string;
4214
+ subTypeId: number;
4215
+ applyCount: number;
4216
+ releaseCount: number;
4217
+ applySize: number;
4218
+ releaseSize: number;
4219
+ lastLibId: number;
4220
+ lastSymbolId: number;
3810
4221
  }
3811
4222
  /**
3812
- * One analysis pass over a trace.
4223
+ * Typed, batched access to the `native_hook*` tables.
3813
4224
  *
3814
- * `requires` is checked against the capability matrix by the caller, not by
3815
- * `run`: an analyzer never has to decide what "unsupported device" means.
4225
+ * The tables exist only when a capture ran `hiprofiler` with the `nativehook`
4226
+ * plugin, so every accessor checks `sqlite_master` first and returns
4227
+ * `[]`/`false`/an empty map instead of letting SQLite throw `no such table`.
4228
+ * That is what lets the analyzer report a degraded proxy with a reason rather
4229
+ * than crash on a plain hitrace capture.
4230
+ *
4231
+ * `events` joins `process` on `ipid` and filters on `process.pid`, which is the
4232
+ * same number space the rest of the package resolves an app to.
3816
4233
  */
3817
- interface Analyzer {
3818
- readonly id: string;
3819
- readonly requires: CapabilityId[];
3820
- run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4234
+ declare class NativeHookQuery {
4235
+ private readonly db;
4236
+ constructor(db: QueryHandle);
4237
+ /** True when `native_hook` exists and holds at least one row. */
4238
+ hasData(): boolean;
4239
+ /** True when `native_hook_statistic` exists and holds at least one row. */
4240
+ hasStatistics(): boolean;
4241
+ /**
4242
+ * App events ordered by `(start_ts, id)`, optionally inside an inclusive
4243
+ * `range` on `start_ts`.
4244
+ *
4245
+ * The `(start_ts, id)` tie-break is ours; upstream orders by timestamp alone,
4246
+ * which makes a capture with equal timestamps depend on row order.
4247
+ *
4248
+ * `DISTINCT` on the event columns collapses the duplicate rows a repeated
4249
+ * `process.ipid` would produce: a merged trace can carry two `process` rows
4250
+ * with the same ipid, and a plain join then returns each event once per row,
4251
+ * doubling every byte. `p.pid` is selected from the same ipid group, so the
4252
+ * duplicate rows are identical.
4253
+ */
4254
+ events(pids: readonly number[], range?: TimeRange): NativeHookEvent[];
4255
+ /** Frames of `callchainIds`, ordered by `(callchain_id, depth, id)`. */
4256
+ frames(callchainIds: readonly number[]): Map<number, NativeHookFrame[]>;
4257
+ /**
4258
+ * Statistics rows for the app, ordered by `(ts, id)`.
4259
+ *
4260
+ * `DISTINCT` and the `process` guard mirror {@link events} for the same two
4261
+ * reasons: a repeated ipid must not multiply rows, and a missing join table
4262
+ * must degrade rather than throw.
4263
+ */
4264
+ statistics(pids: readonly number[]): NativeHookStatistic[];
4265
+ /** `data_dict` text for `ids`; ids absent from the table are simply missing. */
4266
+ dataDict(ids: readonly number[]): Map<number, string>;
4267
+ private hasTable;
3821
4268
  }
3822
4269
 
3823
4270
  /**
@@ -4372,103 +4819,6 @@ declare class FaultTreeAnalyzer implements Analyzer {
4372
4819
  run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4373
4820
  }
4374
4821
 
4375
- /** One side of a binder transaction, as reported by `computeBinderAnalysis`. */
4376
- interface BinderEndpoint {
4377
- pid: number | null;
4378
- tid: number | null;
4379
- procName: string | null;
4380
- threadName: string | null;
4381
- }
4382
- /**
4383
- * One paired (or half) binder communication record.
4384
- *
4385
- * `latencyMs` is `null` unless both a request and a response exist. A half
4386
- * transaction stays in `transactions` (it carries a `transaction id`) but never
4387
- * contributes to `processStats`, `threadStats`, or `interfaceStats`.
4388
- */
4389
- interface BinderTransaction {
4390
- transactionId: string | number;
4391
- caller: BinderEndpoint;
4392
- callee: BinderEndpoint;
4393
- requestTs: number | null;
4394
- responseTs: number | null;
4395
- latencyMs: number | null;
4396
- }
4397
- /** HapRay `_aggregate_stats` row, camelCased for this package. */
4398
- interface BinderProcessStat {
4399
- callerProc: string;
4400
- calleeProc: string;
4401
- count: number;
4402
- avgLatency: number;
4403
- minLatency: number;
4404
- maxLatency: number;
4405
- qps: number | null;
4406
- avgIntervalMs: number | null;
4407
- }
4408
- /** HapRay `_aggregate_by_thread` row, camelCased for this package. */
4409
- interface BinderThreadStat {
4410
- callerProc: string;
4411
- callerTid: number | null;
4412
- callerThreadName: string | null;
4413
- calleeProc: string;
4414
- calleeTid: number | null;
4415
- calleeThreadName: string | null;
4416
- count: number;
4417
- avgLatency: number;
4418
- minLatency: number;
4419
- maxLatency: number;
4420
- qps: number | null;
4421
- avgIntervalMs: number | null;
4422
- }
4423
- /** HapRay `_aggregate_by_interface` row, camelCased for this package. */
4424
- interface BinderInterfaceStat {
4425
- code: string;
4426
- count: number;
4427
- avgLatency: number;
4428
- minLatency: number;
4429
- maxLatency: number;
4430
- qps: number | null;
4431
- avgIntervalMs: number | null;
4432
- topCallerProc: string;
4433
- topCalleeProc: string;
4434
- callerProcVariety: number;
4435
- calleeProcVariety: number;
4436
- }
4437
- /** Everything `computeBinderAnalysis` derives from one trace database. */
4438
- interface BinderAnalysis {
4439
- transactions: BinderTransaction[];
4440
- processStats: BinderProcessStat[];
4441
- threadStats: BinderThreadStat[];
4442
- interfaceStats: BinderInterfaceStat[];
4443
- }
4444
- /**
4445
- * Port of HapRay `IpcBinderAnalyzer._analyze_impl` for one trace database.
4446
- *
4447
- * Filtering, request/response pairing, enrichment and the three aggregations
4448
- * mirror `ipc_binder_analyzer.py` rev `9386e4e`. The deliberate differences:
4449
- * an empty `appPids` filters everything (HapRay would disable the filter),
4450
- * stats ties are broken by identity instead of Python's unstable order, and
4451
- * no value is rounded here (HapRay rounds only when writing its report).
4452
- * Every mean is guarded (`timing` returns `null` for an empty group), so a
4453
- * trace with only half transactions never produces `NaN`.
4454
- */
4455
- declare function computeBinderAnalysis(db: QueryHandle, opts: {
4456
- appPids: number[];
4457
- }): BinderAnalysis;
4458
- /**
4459
- * Binder analyzer over `callstack` / `args` / `data_dict` SQL.
4460
- *
4461
- * The engine gates this analyzer on `trace.binder`; `ctx.db` is still checked
4462
- * because the handle is optional on `AnalyzeContext`. Without it the analyzer
4463
- * emits one `no_data` evidence naming `ctx.db` and no metrics rather than
4464
- * pretending zero binder traffic is a measurement.
4465
- */
4466
- declare class BinderAnalyzer implements Analyzer {
4467
- readonly id = "binder";
4468
- readonly requires: CapabilityId[];
4469
- run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4470
- }
4471
-
4472
4822
  /**
4473
4823
  * Memory analyzer over the procfs capture that accompanied the trace.
4474
4824
  *
@@ -5317,61 +5667,6 @@ declare function analyzeHap(bytes: Uint8Array, packageName: string): HapAnalysis
5317
5667
  /** Wrap an analysis as the `static-hap` section the report renderer takes. */
5318
5668
  declare function hapSection(analysis: HapAnalysis): AnalyzerSection;
5319
5669
 
5320
- /**
5321
- * Which way a metric improves.
5322
- *
5323
- * A metric id absent from {@link METRIC_DIRECTIONS} has no known direction:
5324
- * a rise is neither good nor bad, so the comparison reports it as
5325
- * `incomparable` rather than guessing. Guessing is worse than admitting
5326
- * ignorance here — a baseline report that calls a regression an improvement
5327
- * sends the reader after the wrong problem.
5328
- */
5329
- type MetricDirection = 'lower' | 'higher';
5330
- /**
5331
- * The direction of every metric the analyzers emit.
5332
- *
5333
- * Frame throughput counts are higher-is-better (`frame.fps`,
5334
- * `frame.count`, `frame.rendered.count`); every frame quality rate and every
5335
- * latency, memory, redundant-thread and startup figure is lower-is-better.
5336
- * `fault.*` counters are event counts whose meaning depends on the event, so
5337
- * they are deliberately absent. Degraded proxies are absent too: a
5338
- * `*.degraded` zero is not a measurement to compare.
5339
- */
5340
- declare const METRIC_DIRECTIONS: Readonly<Record<string, MetricDirection>>;
5341
- type DeltaStatus = 'improved' | 'regressed' | 'unchanged' | 'added' | 'removed' | 'incomparable';
5342
- interface MetricDelta {
5343
- readonly id: string;
5344
- readonly unit: MetricUnit;
5345
- readonly baseline: number | string | null;
5346
- readonly current: number | string | null;
5347
- /** Numeric difference (current - baseline); absent for non-numeric or added/removed. */
5348
- readonly delta?: number;
5349
- /** Percent change; absent when baseline is 0 or either side is non-numeric. */
5350
- readonly deltaPct?: number;
5351
- readonly fidelity: Fidelity;
5352
- readonly status: DeltaStatus;
5353
- }
5354
- interface BaselineComparison {
5355
- readonly rows: MetricDelta[];
5356
- /** Count of rows per status; all six keys are always present. */
5357
- readonly totals: Record<DeltaStatus, number>;
5358
- }
5359
- /**
5360
- * Compare two analyses metric by metric.
5361
- *
5362
- * The rows are the union of both metric id sets sorted by id, so the output is
5363
- * byte-identical for the same inputs (D5) and two runs can be diffed directly.
5364
- * Only metrics present on both sides with numeric values can be improved or
5365
- * regressed; everything else is reported as what it is — `added`, `removed`,
5366
- * or `incomparable` — and never silently dropped.
5367
- *
5368
- * `deltaPct` divides by `|baseline|`, so a metric that moved from -10 to -5
5369
- * reads as a 50% change toward zero rather than a sign-flipped one. A zero
5370
- * baseline has no percentage: every change is infinitely large, which is not
5371
- * a useful number.
5372
- */
5373
- declare function compareResults(baseline: AnalyzeResult, current: AnalyzeResult): BaselineComparison;
5374
-
5375
5670
  /** The report document schema. A change to any shape below bumps this. */
5376
5671
  declare const REPORT_SCHEMA_VERSION = 1;
5377
5672
  /** Who produced the report; the version is the CLI package version. */
@@ -5580,4 +5875,4 @@ interface FlamegraphPageInput {
5580
5875
  */
5581
5876
  declare function renderFlamegraphHtml(input: FlamegraphPageInput): string;
5582
5877
 
5583
- export { type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AppIdentity, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CaseLoad, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DiscoveredCase, type DrillDownHandle, type DuplicateGroup, EXCLUDE_PATTERNS, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, type ExpectPresent, type ExpectationOutcome, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, GEOMETRY_TOLERANCE_PX, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, IGNORED_ATTRIBUTES, type ImageComparison, IngestError, InstantQuery, type InventoryFile, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationPotential, type OversizedFile, PLANE_A_PLUGINS, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, type Rect, type RedundancyLevel, type RedundancyType, type RedundantThreadPattern, type RedundantThreadsSummary, RenderAnalyzer, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStepRef, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type Selector, type SelectorRect, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, type StepExpectation, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TraceCollectOptions, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, aggregateUnreleased, analyzeHap, analyzeThreadWakeup, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, categorize, classifyNativePath, compareImages, compareResults, compareSceneDirs, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, decodePng, defaultAnalyzers, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evidence, executeAction, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hiperfRecordCommand, ingestScene, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, pairNativeMemory, parseBounds, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseScenario, parseSelector, parseSmapsRollup, queryDefinitions, readHidumperCapture, readHilogText, readProcfsSamples, readSceneMetadata, readUiTree, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderSummaryJson, renderUiDiffHtml, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, round2HalfEven, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, summarizeReport, tableRowCounts, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };
5878
+ export { type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AppIdentity, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CaseLoad, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, type DepGraph, type DepGraphEdge, type DepGraphFile, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DiscoveredCase, type DrillDownHandle, type DuplicateGroup, EXCLUDE_PATTERNS, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, type ExpectPresent, type ExpectationOutcome, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, GEOMETRY_TOLERANCE_PX, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, type HarEdge, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, IGNORED_ATTRIBUTES, type ImageComparison, IngestError, InstantQuery, type InventoryFile, type JsheapCapture, JsheapCollector, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type ModuleDecl, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationPotential, type OversizedFile, PARITY_ROWS, PLANE_A_PLUGINS, type ParityRow, type ParityStatus, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, type Rect, type RedundancyLevel, type RedundancyType, RedundantFileAnalyzer, type RedundantFileEntry, type RedundantFileReport, type RedundantThreadPattern, type RedundantThreadsSummary, RenderAnalyzer, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStep, type SceneStepRef, type ScenesComparison, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type Selector, type SelectorRect, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, type StepComparison, type StepExpectation, type StepStatus, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TimingCycle, type TraceCollectOptions, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, aggregateUnreleased, analyzeHap, analyzeThreadWakeup, buildDepGraph, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, categorize, classifyNativePath, compareImages, compareResults, compareSceneDirs, compareScenes, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, decodePng, defaultAnalyzers, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evidence, executeAction, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hiperfRecordCommand, ingestScene, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, pairNativeMemory, paritySummary, parseBounds, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseRedundantFile, parseScenario, parseSelector, parseSmapsRollup, queryDefinitions, readHidumperCapture, readHilogText, readJsheapSnapshot, readProcfsSamples, readSceneMetadata, readUiTree, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderScenesComparison, renderSummaryJson, renderUiDiffHtml, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, round2HalfEven, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, sortSteps, summarizeReport, tableRowCounts, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };