@ohos-perf/core 0.19.0 → 0.21.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 +489 -2
  2. package/dist/index.js +1011 -72
  3. package/package.json +48 -48
package/dist/index.d.ts CHANGED
@@ -3613,7 +3613,7 @@ declare class ThreadStateQuery {
3613
3613
  forItids(itids: number[], range?: TimeRange): ThreadState[];
3614
3614
  }
3615
3615
 
3616
- 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' | 'coverage';
3616
+ 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' | 'coverage' | 'optimization';
3617
3617
  /**
3618
3618
  * A follow-up query an agent can issue to drill into an evidence item.
3619
3619
  *
@@ -4850,6 +4850,21 @@ interface RunOptions {
4850
4850
  /** Injected clock, for tests. */
4851
4851
  readonly now?: () => number;
4852
4852
  }
4853
+ /**
4854
+ * Evaluate a step's `expect` block against one dump.
4855
+ *
4856
+ * Every clause is evaluated even after one fails: a reader looking at a
4857
+ * failed step wants to know that the screen also lost the toolbar, not just
4858
+ * that it lost the first thing checked. `foreground` comes last so the
4859
+ * clauses an author wrote in order appear in that order, and a screenshot
4860
+ * showing the launcher explains the `present` misses above it.
4861
+ *
4862
+ * `foreground` means the app owns at least one node. A system dialog drawn
4863
+ * over the app is still the app's screen — the title bar and the window frame
4864
+ * belong to it — so requiring the app to own *every* node would fail on the
4865
+ * one case an author most wants to assert.
4866
+ */
4867
+ declare function evaluateExpectation(expect: StepExpectation, nodes: readonly UiNode[], app: string): ExpectationOutcome[];
4853
4868
  /**
4854
4869
  * Run a scenario: every selected (round, step) pair, one scene each.
4855
4870
  *
@@ -4889,6 +4904,255 @@ declare class ScenarioRunner {
4889
4904
  */
4890
4905
  declare function writeRunFiles(outDir: string, result: RunResult): void;
4891
4906
 
4907
+ /**
4908
+ * The model-driven UI agent (HapRay parity row 5).
4909
+ *
4910
+ * HapRay's `gui-agent` wraps the external `phone_agent` package: the model is
4911
+ * shown a screenshot, answers with one action, and says `finished` when it
4912
+ * believes the task is done. Three things make that unusable as a measurement
4913
+ * tool, and each is fixed here rather than reproduced.
4914
+ *
4915
+ * 1. **`finished` is taken on faith.** A model that taps a button which does
4916
+ * nothing and then declares success is recorded as a success. Here a
4917
+ * completion claim carries an expectation, the expectation is evaluated
4918
+ * against a fresh dump, and a claim the screen contradicts is recorded as
4919
+ * `unverified` — a failure with the clause that failed named.
4920
+ * 2. **The safety rule lives only in the prompt.** HapRay tells the model to
4921
+ * avoid payment, ordering and transfers; a model that ignores the sentence
4922
+ * acts anyway. Here the guard reads the node the tap lands on and refuses
4923
+ * the gesture outright. An irreversible action stops the run: a model that
4924
+ * reached for a payment button has lost the thread of the task, and asking
4925
+ * it again spends steps on the one thing that must not happen.
4926
+ * 3. **The log cannot be replayed.** HapRay records `{action, thinking,
4927
+ * message}` as prose, so two runs of the same task are two unrelated logs.
4928
+ * Here every step records the gesture and the screen hash either side of
4929
+ * it, so {@link replayAgent} can walk the same path on another build
4930
+ * without a model, and stop at the first screen that is not the recorded
4931
+ * one.
4932
+ *
4933
+ * The model is injected, never bundled: {@link AgentModel} is one method, so a
4934
+ * caller supplies whatever client it has, and the loop is tested without a
4935
+ * network or a device.
4936
+ */
4937
+
4938
+ /** The device surface the loop needs. `Device` satisfies it structurally. */
4939
+ interface AgentDevice {
4940
+ readonly id: string;
4941
+ /** A fresh flattened dump, as `Device.uiTree` returns. */
4942
+ uiTree(): Promise<readonly UiNode[]>;
4943
+ gesture(g: Gesture): Promise<GestureResult>;
4944
+ }
4945
+ /** What the model answers: one gesture, or a claim that the task is done. */
4946
+ type AgentDecision = {
4947
+ readonly action: Gesture;
4948
+ readonly reason: string;
4949
+ } | {
4950
+ readonly done: true;
4951
+ readonly reason: string;
4952
+ readonly expect?: StepExpectation;
4953
+ };
4954
+ /** One earlier step, as the model sees it when deciding the next. */
4955
+ interface AgentHistoryEntry {
4956
+ readonly step: number;
4957
+ readonly status: AgentStepStatus;
4958
+ readonly reason: string;
4959
+ /** What the step did, as `describeDecision` renders it. */
4960
+ readonly did?: string;
4961
+ readonly detail?: string;
4962
+ }
4963
+ /** Everything a model is shown. A client renders this into its own prompt. */
4964
+ interface AgentTurn {
4965
+ readonly task: string;
4966
+ readonly app: string;
4967
+ /** Zero-based index of the step being decided. */
4968
+ readonly step: number;
4969
+ readonly maxSteps: number;
4970
+ /** The current screen, one line per node. */
4971
+ readonly screen: string;
4972
+ /** The steps already taken, oldest first. */
4973
+ readonly history: readonly AgentHistoryEntry[];
4974
+ }
4975
+ /** The injected client. One method, so any endpoint fits. */
4976
+ interface AgentModel {
4977
+ decide(request: AgentTurn): Promise<AgentDecision>;
4978
+ }
4979
+ /**
4980
+ * How a step ended.
4981
+ *
4982
+ * `acted` is a gesture the device accepted, `failed` one it rejected,
4983
+ * `refused` one the guard stopped before it reached the device, `verified` a
4984
+ * completion claim the screen confirmed, and `unverified` one it did not.
4985
+ */
4986
+ type AgentStepStatus = 'acted' | 'failed' | 'refused' | 'verified' | 'unverified';
4987
+ interface AgentStep {
4988
+ readonly index: number;
4989
+ readonly status: AgentStepStatus;
4990
+ readonly reason: string;
4991
+ /** The gesture performed or attempted; absent for a refusal or a claim. */
4992
+ readonly action?: Gesture;
4993
+ /** Why the step ended that way, when the status alone does not say. */
4994
+ readonly detail?: string;
4995
+ /** The screen hash before the step. */
4996
+ readonly before: string;
4997
+ /** The screen hash after it; equal to `before` when nothing moved. */
4998
+ readonly after: string;
4999
+ readonly navigated: boolean;
5000
+ }
5001
+ type AgentStatus = 'completed' | 'unverified' | 'refused' | 'exhausted';
5002
+ /** A run, complete enough to replay and to compare against another run. */
5003
+ interface AgentTranscript {
5004
+ readonly version: 1;
5005
+ readonly task: string;
5006
+ readonly app: string;
5007
+ readonly steps: readonly AgentStep[];
5008
+ readonly status: AgentStatus;
5009
+ /** Distinct screen hashes reached, including the one it started on. */
5010
+ readonly statesReached: number;
5011
+ }
5012
+ type AgentResult = AgentTranscript;
5013
+ interface AgentOptions {
5014
+ readonly task: string;
5015
+ readonly app: string;
5016
+ /** Hard cap on model turns. HapRay's default is 50. */
5017
+ readonly maxSteps: number;
5018
+ /** Let the guard's refusals through. Off by default. */
5019
+ readonly allowIrreversible?: boolean;
5020
+ }
5021
+ /** One irreversible action the guard recognises. */
5022
+ interface IrreversiblePattern {
5023
+ readonly pattern: RegExp;
5024
+ /** Why the action is refused; the text a refusal records. */
5025
+ readonly why: string;
5026
+ /** A label that matches `pattern`, so a test can prove the row is live. */
5027
+ readonly sample: string;
5028
+ }
5029
+ /**
5030
+ * The actions the guard refuses.
5031
+ *
5032
+ * Each pattern names an act, not a topic: `Payment settings` is a screen a
5033
+ * walk may legitimately open, while `立即支付` is money leaving an account.
5034
+ * Matching on a bare substring would block the settings page a task needs.
5035
+ */
5036
+ declare const IRREVERSIBLE_PATTERNS: readonly IrreversiblePattern[];
5037
+ /** Why tapping this node is irreversible, or `undefined` when it is safe. */
5038
+ declare function irreversibleReason(node: UiNode): string | undefined;
5039
+ /** One line naming what a decision does, for a transcript or a history entry. */
5040
+ declare function describeDecision(decision: AgentDecision): string;
5041
+ /**
5042
+ * Render a dump for a model prompt: one line per node, in tree order.
5043
+ *
5044
+ * The fields are the ones a decision is made from — what it says, what it is,
5045
+ * what it is called, where it is, and whether it can be tapped. A node that
5046
+ * cannot be tapped is marked so the model does not spend a step on it, which
5047
+ * is the single most common wasted turn in HapRay's runs.
5048
+ */
5049
+ declare function renderTree(tree: readonly UiNode[]): string;
5050
+ /**
5051
+ * The prompt for one decision.
5052
+ *
5053
+ * A plain string, not a message list: whatever client a caller brings turns
5054
+ * this into its own request shape. It states the answer format literally
5055
+ * because a model that invents a gesture name fails far from the answer that
5056
+ * caused it, and it shows the history because a model that cannot see its own
5057
+ * steps repeats them.
5058
+ */
5059
+ declare function agentPrompt(request: AgentTurn): string;
5060
+ /**
5061
+ * Read a model's answer.
5062
+ *
5063
+ * The answer is data from outside this package, so every field is checked
5064
+ * here: an unknown gesture name, a malformed expectation, or an object that is
5065
+ * both an action and a completion is a refusal naming what was wrong. A
5066
+ * refusal now beats a confusing failure inside the gesture driver or the
5067
+ * expectation evaluator, where the cause is no longer visible.
5068
+ */
5069
+ declare function parseDecision(text: string): AgentDecision;
5070
+ /**
5071
+ * Run the loop until the model's claim is verified, the guard refuses, or the
5072
+ * step budget runs out.
5073
+ *
5074
+ * The order of checks matters: an irreversible target is refused *before* the
5075
+ * gesture reaches the device, and a completion claim is evaluated against the
5076
+ * screen the model was shown rather than a fresh one — the model has to be
5077
+ * judged on what it saw.
5078
+ */
5079
+ declare function runAgent(device: AgentDevice, model: AgentModel, options: AgentOptions): Promise<AgentResult>;
5080
+ /** What a replay did. */
5081
+ interface ReplayResult {
5082
+ /** Steps whose gesture reached the device. */
5083
+ readonly performed: number;
5084
+ /** Steps skipped because they never touched the device. */
5085
+ readonly skipped: number;
5086
+ /** The step whose recorded screen did not match; absent when it matched. */
5087
+ readonly divergedAt?: number;
5088
+ }
5089
+ /**
5090
+ * Walk a recorded transcript again, without a model.
5091
+ *
5092
+ * The recorded gesture is a coordinate, so it only means what it meant on the
5093
+ * screen it was recorded against. Each step re-dumps, compares the hash to the
5094
+ * recorded `before`, and stops at the first mismatch: continuing would send
5095
+ * taps into whatever the new build put in those places.
5096
+ *
5097
+ * A step with no gesture (a refusal, or a completion claim) is skipped: it
5098
+ * never touched the device, so there is nothing to replay.
5099
+ */
5100
+ declare function replayAgent(device: AgentDevice, transcript: AgentTranscript): Promise<ReplayResult>;
5101
+
5102
+ /**
5103
+ * The HTTP model client for the GUI agent (HapRay parity row 5).
5104
+ *
5105
+ * HapRay's `gui-agent` imports the external `phone_agent` package, whose client
5106
+ * reads `GLM_BASE_URL` / `GLM_API_KEY` / `GLM_MODEL` and posts to an
5107
+ * OpenAI-compatible `/chat/completions` endpoint. This is that protocol,
5108
+ * written here so the package does not depend on `phone_agent`, and with
5109
+ * `fetch` injected so a test never opens a socket and a caller can point it at
5110
+ * any endpoint that speaks the same shape.
5111
+ *
5112
+ * Two things differ from HapRay's client:
5113
+ *
5114
+ * - **An unparseable answer is refused here.** HapRay passes the model's prose
5115
+ * through to the loop, so a formatting mistake surfaces as an agent failure.
5116
+ * Here {@link parseDecision} runs inside the client, so the error names the
5117
+ * answer that caused it.
5118
+ * - **Nothing is defaulted silently.** No base URL is guessed and no key is
5119
+ * invented: a host with no configuration gets a refusal naming the variables
5120
+ * to set, not a request to a host the user never named.
5121
+ */
5122
+
5123
+ /** The slice of `fetch` this client needs. Injected, never imported. */
5124
+ type AgentFetch = (url: string, init: RequestInit) => Promise<Response>;
5125
+ interface HttpAgentModelOptions {
5126
+ /** The endpoint root, without `/chat/completions`. */
5127
+ readonly baseUrl: string;
5128
+ readonly apiKey: string;
5129
+ readonly model: string;
5130
+ readonly fetch: AgentFetch;
5131
+ /** Request timeout in ms. Defaults to 60 s. */
5132
+ readonly timeoutMs?: number;
5133
+ }
5134
+ interface AgentConfig {
5135
+ readonly baseUrl: string;
5136
+ readonly apiKey: string;
5137
+ readonly model: string;
5138
+ }
5139
+ /**
5140
+ * Read the client configuration from the environment.
5141
+ *
5142
+ * `undefined` when no endpoint is configured: a caller then refuses with a
5143
+ * message naming the variables, which is better than a request to a guessed
5144
+ * host. A base URL without a key is also `undefined` — half a configuration is
5145
+ * a mistake, not a default.
5146
+ */
5147
+ declare function readAgentConfig(env: Record<string, string | undefined>): AgentConfig | undefined;
5148
+ /**
5149
+ * A model client over an OpenAI-compatible endpoint.
5150
+ *
5151
+ * The options are validated once, at construction, so a misconfiguration fails
5152
+ * before a device is touched rather than on the first decision.
5153
+ */
5154
+ declare function httpAgentModel(options: HttpAgentModelOptions): AgentModel;
5155
+
4892
5156
  /**
4893
5157
  * One `native_hook` row with camelCase field names.
4894
5158
  *
@@ -6185,6 +6449,229 @@ declare function isZip(bytes: Uint8Array): boolean;
6185
6449
  /** Read the central directory and return an archive over `bytes`. */
6186
6450
  declare function openZip(bytes: Uint8Array): ZipArchive;
6187
6451
 
6452
+ /**
6453
+ * A reader for the ELF headers, sections and symbols of an OHOS native binary.
6454
+ *
6455
+ * This exists for HapRay parity row 27. HapRay's `opt-detector` answers "what
6456
+ * optimization level was this built at, and was LTO on?" by feeding raw
6457
+ * `.text` bytes to a ~2 GB LSTM and a 551-feature SVM and printing the guess
6458
+ * as a percentage. An ELF records much of that directly — LTO leaves
6459
+ * `lto_priv.*` symbols and `.gnu.lto_*` sections, `-O0` leaves debug
6460
+ * sections, and the instruction mix is a fact about the bytes — so the
6461
+ * analyzer built on this reader reports what the file says and labels the
6462
+ * parts that are inference.
6463
+ *
6464
+ * What is here is deliberately narrow: the section header table, the two
6465
+ * symbol tables, and a decoder for the AArch64 instruction classes whose
6466
+ * density differs across optimization levels. There is no program-header
6467
+ * walk, no relocation processing, no dynamic-section parsing and no
6468
+ * disassembly — nothing this reader does not have a caller for.
6469
+ *
6470
+ * ## Refusals
6471
+ *
6472
+ * Every read is bounds-checked against the buffer, because a `.so` shipped
6473
+ * inside an app is attacker-controlled input as far as this package is
6474
+ * concerned. A bad magic, a short header, an unsupported class and a section
6475
+ * table pointing past the end are typed refusals naming the field, not bare
6476
+ * `RangeError`s from a `DataView`.
6477
+ */
6478
+ /** `e_machine` for AArch64, the only machine an OHOS app ships. */
6479
+ declare const EM_AARCH64 = 183;
6480
+ /** One section header, as much of it as a caller here needs. */
6481
+ interface ElfSection {
6482
+ readonly name: string;
6483
+ readonly type: number;
6484
+ readonly flags: number;
6485
+ /** Offset of the payload in the file. */
6486
+ readonly offset: number;
6487
+ /** Declared size. A `NOBITS` section declares one but occupies no bytes. */
6488
+ readonly size: number;
6489
+ /** Entry size for a table section (`sh_entsize`), else 0. */
6490
+ readonly entrySize: number;
6491
+ }
6492
+ /** One symbol, with the binding and type decoded from `st_info`. */
6493
+ interface ElfSymbol {
6494
+ readonly name: string;
6495
+ readonly bind: 'local' | 'global' | 'weak' | 'other';
6496
+ readonly type: 'notype' | 'func' | 'object' | 'section' | 'file' | 'other';
6497
+ readonly size: number;
6498
+ /** Section index the symbol belongs to; 0 for undefined, 0xfff1 for absolute. */
6499
+ readonly sectionIndex: number;
6500
+ }
6501
+ interface ElfFile {
6502
+ readonly bits: 32 | 64;
6503
+ readonly endian: 'little' | 'big';
6504
+ readonly machine: number;
6505
+ /** `e_type`: 1 relocatable, 2 executable, 3 shared object, 4 core. */
6506
+ readonly type: number;
6507
+ readonly sections: readonly ElfSection[];
6508
+ readonly symbols: readonly ElfSymbol[];
6509
+ /** The section with this name, or `undefined`. */
6510
+ readonly section: (name: string) => ElfSection | undefined;
6511
+ /** The payload of a section; empty for `NOBITS` and for a missing section. */
6512
+ readonly bytesOf: (name: string) => Uint8Array;
6513
+ }
6514
+ /**
6515
+ * Read an ELF's headers, sections and symbols.
6516
+ *
6517
+ * Only 64-bit little-endian is decoded. The class and endianness are read
6518
+ * first and refused by name, so a 32-bit or big-endian file gets a message
6519
+ * saying which shape was unsupported rather than a nonsensical section table.
6520
+ */
6521
+ declare function readElf(bytes: Uint8Array): ElfFile;
6522
+ /** The instruction classes whose density differs across optimization levels. */
6523
+ type InstructionClass = 'ret' | 'blr' | 'br' | 'bl' | 'b' | 'bcond' | 'cbz' | 'tbz' | 'adrp' | 'adr' | 'ldr' | 'str' | 'add' | 'vector' | 'other';
6524
+ /** Per-class instruction counts over a `.text` payload. */
6525
+ type InstructionCounts = Record<InstructionClass, number> & {
6526
+ total: number;
6527
+ };
6528
+ /**
6529
+ * Classify one AArch64 instruction word.
6530
+ *
6531
+ * The masks are the ARM ARM's fixed-field encodings for the classes whose
6532
+ * frequency a compiler changes: `ret`/`blr`/`br` (branch-register), `bl`/`b`
6533
+ * (immediate branch), `b.cond`, `cbz`/`cbnz`, `tbz`/`tbnz`, `adrp`/`adr`, and
6534
+ * the SIMD group. `other` covers everything else, which is most arithmetic.
6535
+ *
6536
+ * The order matters: `br`/`blr`/`ret` share a mask and are separated by their
6537
+ * `opc` field, and `b`/`bl` share a mask separated by bit 31.
6538
+ */
6539
+ declare function classifyInstruction(word: number): InstructionClass;
6540
+ /**
6541
+ * Count instruction classes over a payload.
6542
+ *
6543
+ * A trailing partial word is not an instruction and is not counted; a section
6544
+ * whose size is not a multiple of four is legal padding.
6545
+ */
6546
+ declare function countInstructions(payload: Uint8Array): InstructionCounts;
6547
+
6548
+ /**
6549
+ * Optimization-level and LTO detection for an OHOS native binary (HapRay
6550
+ * parity row 27).
6551
+ *
6552
+ * HapRay's `opt-detector` answers two questions — "which `-O` level was this
6553
+ * built at?" and "was LTO on?" — by feeding raw `.text` bytes to a ~2 GB
6554
+ * TensorFlow LSTM and a 551-feature SVM, then printing the guess as a
6555
+ * percentage. Its own source records the accuracy: at the threshold it ships,
6556
+ * low-optimization binaries are misreported 16.7% of the time, and the model
6557
+ * is AArch64-only.
6558
+ *
6559
+ * This does not ship that model. It reads the ELF instead, because the ELF
6560
+ * records several of the answers:
6561
+ *
6562
+ * - **LTO** leaves `lto_priv.*` symbols (GCC's own bookkeeping for a symbol
6563
+ * that survived link-time optimization with local visibility) and
6564
+ * `.gnu.lto_*` sections. Their presence is evidence; their absence from a
6565
+ * file that still has a symbol table is evidence of absence. A stripped file
6566
+ * with no symbol table is `unknown`, not `absent` — the markers may simply
6567
+ * have been removed.
6568
+ * - **The `-O` level** is recorded in `.comment` when the toolchain writes it.
6569
+ * That is the compiler's own statement, so it wins over any inference.
6570
+ * - **The instruction mix** is a fact about the bytes: SIMD density, branch
6571
+ * density and call/return balance all shift with optimization. When nothing
6572
+ * recorded the level, the mix produces a verdict labelled `inferred`, with
6573
+ * the signals named so a reader can disagree with it.
6574
+ *
6575
+ * What is never done is presenting an inference as a measurement. The
6576
+ * `fidelity` on each metric says which it is.
6577
+ */
6578
+
6579
+ /** One binary to inspect: its archive-relative path and its bytes. */
6580
+ interface BinaryInput {
6581
+ readonly path: string;
6582
+ readonly bytes: Uint8Array;
6583
+ }
6584
+ /** What the ELF itself records, before any judgement is applied. */
6585
+ interface BinaryFacts {
6586
+ readonly path: string;
6587
+ readonly size: number;
6588
+ readonly machine: number;
6589
+ /** Bytes of the `.text` section; 0 when the file has none. */
6590
+ readonly textBytes: number;
6591
+ readonly instructions: InstructionCounts;
6592
+ /**
6593
+ * `present` when an LTO marker was found, `absent` when a symbol table
6594
+ * exists and none was, `unknown` when there is no symbol table to search.
6595
+ */
6596
+ readonly lto: 'present' | 'absent' | 'unknown';
6597
+ /** The symbols and sections that proved LTO, in the order they were found. */
6598
+ readonly ltoMarkers: readonly string[];
6599
+ readonly debug: boolean;
6600
+ readonly debugSections: readonly string[];
6601
+ /** NUL-separated strings from `.comment`, in file order. */
6602
+ readonly compiler: readonly string[];
6603
+ /** `-O` flags the build recorded, in file order. */
6604
+ readonly recordedFlags: readonly string[];
6605
+ readonly symbols: {
6606
+ readonly functions: number;
6607
+ readonly global: number;
6608
+ readonly local: number;
6609
+ readonly weak: number;
6610
+ };
6611
+ /** True when no function symbol survived, so symbol-level LTO evidence is gone. */
6612
+ readonly stripped: boolean;
6613
+ }
6614
+ type OptimizationLevel = 'unoptimized' | 'low' | 'medium' | 'high' | 'unknown';
6615
+ /** How a level was decided: the compiler said so, or the mix was read. */
6616
+ type OptimizationBasis = 'recorded' | 'inferred' | 'none';
6617
+ interface OptimizationVerdict {
6618
+ readonly level: OptimizationLevel;
6619
+ readonly basis: OptimizationBasis;
6620
+ /** The signals that produced an `inferred` verdict; empty otherwise. */
6621
+ readonly signals: readonly string[];
6622
+ }
6623
+ /** One inspected binary, with the facts and the verdict kept apart. */
6624
+ interface BinaryReport {
6625
+ readonly path: string;
6626
+ readonly facts: BinaryFacts;
6627
+ readonly verdict: OptimizationVerdict;
6628
+ }
6629
+ interface OptimizationAnalysis {
6630
+ readonly schemaVersion: 1;
6631
+ readonly package: string;
6632
+ readonly binaries: readonly BinaryReport[];
6633
+ readonly totals: {
6634
+ readonly binaries: number;
6635
+ readonly lto: number;
6636
+ readonly debug: number;
6637
+ readonly stripped: number;
6638
+ };
6639
+ readonly metrics: Metric[];
6640
+ readonly evidence: Evidence[];
6641
+ }
6642
+ /**
6643
+ * Inspect one ELF.
6644
+ *
6645
+ * A refusal names the binary, because a package holds many and "not an ELF"
6646
+ * alone would not say which one the caller has to look at.
6647
+ */
6648
+ declare function inspectBinary(input: BinaryInput): BinaryFacts;
6649
+ /**
6650
+ * Decide the optimization level, preferring what the compiler recorded.
6651
+ *
6652
+ * The inference is deliberately coarse: three signals, two thresholds. A
6653
+ * richer model would be a guess dressed as a measurement, which is the defect
6654
+ * this row exists to fix.
6655
+ */
6656
+ declare function classifyOptimization(facts: BinaryFacts): OptimizationVerdict;
6657
+ /**
6658
+ * Pull the arm64 shared objects out of a package, or take a bare `.so`.
6659
+ *
6660
+ * An `ar` archive is refused by name: it is a third container format, and
6661
+ * returning an empty report for one would read as "no optimizations found"
6662
+ * when the truth is "this package did not look".
6663
+ */
6664
+ declare function extractBinaries(input: BinaryInput): BinaryInput[];
6665
+ /**
6666
+ * Measure every binary and summarise the package.
6667
+ *
6668
+ * Binaries are sorted by path, and every number is derived from the bytes, so
6669
+ * two runs over the same package produce the same document.
6670
+ */
6671
+ declare function analyzeBinaries(inputs: readonly BinaryInput[], packageName: string): OptimizationAnalysis;
6672
+ /** Wrap an analysis as the `optimization` section the report renderer takes. */
6673
+ declare function optimizationSection(analysis: OptimizationAnalysis): AnalyzerSection;
6674
+
6188
6675
  type FileCategory = 'images' | 'videos' | 'audio' | 'fonts' | 'scripts' | 'styles' | 'binaries' | 'bytecode' | 'data' | 'other';
6189
6676
  /** One archive entry, measured. Paths are archive names, forward slashes. */
6190
6677
  interface InventoryFile {
@@ -6432,4 +6919,4 @@ interface FlamegraphPageInput {
6432
6919
  */
6433
6920
  declare function renderFlamegraphHtml(input: FlamegraphPageInput): string;
6434
6921
 
6435
- export { ANIMATION_BANDS, type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AnimationAnalysis, type AnimationLabel, type AnimationSeverity, type AppIdentity, BUNDLE_RENDERED_FILES, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, type BundleRerenderInput, 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, CoverageAnalyzer, type CoverageCounts, type CoverageFile, type CoverageRatio, type CoverageReport, 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, type ExplorationAction, type ExplorationClock, type ExplorationDevice, type ExplorationDeviceOptions, type ExplorationHost, type ExplorationOptions, type ExplorationOutcome, type ExplorationResult, type ExplorationState, type ExplorationStep, type ExplorationStrategy, type ExplorationTargetDevice, 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, MIN_HASH_PIXELS, 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 PixelOnlyChange, 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, type RegionPixelChange, RenderAnalyzer, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RsSkipTraceMethod, 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, type Trend, type TrendOrder, type TrendPoint, type TrendRun, type TrendSeries, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnmeasuredRegion, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, aggregateUnreleased, analyseAnimations, analyzeHap, analyzeThreadWakeup, animationSeverity, buildDepGraph, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, buildTrend, categorize, classifyNativePath, compareImages, compareRegion, compareResults, compareSceneDirs, compareScenes, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, cropRegion, decodePng, defaultAnalyzers, deviceExplorationHost, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evidence, executeAction, explorationDevice, explore, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hashTree, hiperfRecordCommand, ingestScene, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, pairNativeMemory, paritySummary, parseBounds, parseCoverageReport, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseRedundantFile, parseScenario, parseSelector, parseSmapsRollup, planNextAction, queryDefinitions, readHidumperCapture, readHilogText, readJsheapSnapshot, readProcfsSamples, readSceneMetadata, readUiTree, renderBundle, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderScenesComparison, renderSummaryJson, renderTrendHtml, renderTrendJson, renderUiDiffHtml, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, round2HalfEven, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, sortSteps, summarizeReport, tableRowCounts, trendRunFromReport, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };
6922
+ export { ANIMATION_BANDS, type ActionContext, type ActionDevice, type ActionOutcome, type ActiveAlloc, type AgentConfig, type AgentDecision, type AgentDevice, type AgentFetch, type AgentHistoryEntry, type AgentModel, type AgentOptions, type AgentResult, type AgentStatus, type AgentStep, type AgentStepStatus, type AgentTranscript, type AgentTurn, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AnimationAnalysis, type AnimationLabel, type AnimationSeverity, type AppIdentity, BUNDLE_RENDERED_FILES, type BaselineComparison, type BelowThresholdPattern, type BinaryFacts, type BinaryInput, type BinaryReport, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, type BundleRerenderInput, 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, CoverageAnalyzer, type CoverageCounts, type CoverageFile, type CoverageRatio, type CoverageReport, 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, EM_AARCH64, EXCLUDE_PATTERNS, type ElfFile, type ElfSection, type ElfSymbol, 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, type ExplorationAction, type ExplorationClock, type ExplorationDevice, type ExplorationDeviceOptions, type ExplorationHost, type ExplorationOptions, type ExplorationOutcome, type ExplorationResult, type ExplorationState, type ExplorationStep, type ExplorationStrategy, type ExplorationTargetDevice, 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, type HttpAgentModelOptions, IGNORED_ATTRIBUTES, IRREVERSIBLE_PATTERNS, type ImageComparison, IngestError, InstantQuery, type InstructionClass, type InstructionCounts, type InventoryFile, type IrreversiblePattern, type JsheapCapture, JsheapCollector, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MIN_HASH_PIXELS, 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 OptimizationAnalysis, type OptimizationBasis, type OptimizationLevel, type OptimizationPotential, type OptimizationVerdict, 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 PixelOnlyChange, 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, type RegionPixelChange, RenderAnalyzer, type ReplayResult, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RsSkipTraceMethod, 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, type Trend, type TrendOrder, type TrendPoint, type TrendRun, type TrendSeries, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnmeasuredRegion, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, agentPrompt, aggregateUnreleased, analyseAnimations, analyzeBinaries, analyzeHap, analyzeThreadWakeup, animationSeverity, buildDepGraph, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, buildTrend, categorize, classifyInstruction, classifyNativePath, classifyOptimization, compareImages, compareRegion, compareResults, compareSceneDirs, compareScenes, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, countInstructions, createSceneLayout, cropRegion, decodePng, defaultAnalyzers, describeDecision, deviceExplorationHost, dhash, diffTrees, discoverCases, encodePng, escapeHtml, evaluateExpectation, evidence, executeAction, explorationDevice, explore, extractBinaries, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hashTree, hiperfRecordCommand, httpAgentModel, ingestScene, inspectBinary, irreversibleReason, isUnresolvedSymbol, isZip, loadCases, lookupQuery, markRegions, matchHapRules, matchRules, matchSelector, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, optimizationSection, pairNativeMemory, paritySummary, parseBounds, parseCoverageReport, parseDecision, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseRedundantFile, parseScenario, parseSelector, parseSmapsRollup, planNextAction, queryDefinitions, readAgentConfig, readElf, readHidumperCapture, readHilogText, readJsheapSnapshot, readProcfsSamples, readSceneMetadata, readUiTree, renderBundle, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderScenesComparison, renderSummaryJson, renderTree, renderTrendHtml, renderTrendJson, renderUiDiffHtml, replayAgent, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, resolveSelector, round2HalfEven, runAgent, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, sortSteps, summarizeReport, tableRowCounts, trendRunFromReport, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };