hm-pt-core 1.0.0

package/README.md

@@ -0,0 +1,32 @@
+# hm-pt-core
+
+DFX perf trace 公共层：跨 **hiperf_txt_parser** 与 **hmtrace-parser** 共享的数据类型与 trace format 解码原语。
+
+## 安装
+
+```bash
+npm install hm-pt-core
+```
+
+## 导出
+
+- **perf 类型**：`RecordSample`, `PerfData`, `CallchainEntry`, `RawEntry`, …
+- **trace 机制**：`parseTraceFormat`, `buildTraceParserRegistry`, `decodeRawByRegistry`, `tokenizePrintfFormat`, …
+- **hitrace 契约**：`HitraceRecordSnapshot`, `HitraceThreadIndexSnapshot`
+- **工具**：`isPerfDataLike`
+
+## 版本兼容
+
+| hm-pt-core | hiperf_txt_parser | hmtrace-parser |
+|------------|-------------------|----------------|
+| 1.0.x      | 2.0.x             | 0.8.x          |
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm run test:all
+```
+
+提交前需依次跑通 `npm run build` 与 `npm run test:all`（功能测试 + 性能测试）。

package/dist/hitrace/contract.d.ts

@@ -0,0 +1,16 @@
+/**
+ * hitrace 与 perf 合并侧车数据契约（可 structuredClone 进 Worker）。
+ * 由 hmtrace-parser `buildHitraceIndexSnapshot` 构建。
+ */
+/** 预处理后的单条 hitrace 记录（桶内按 timestampNs 升序） */
+export type HitraceRecordSnapshot = {
+    timestampNs: number;
+    functionName: string;
+    fieldDict: Record<string, string>;
+    /** 已废弃：hmtrace-parser 不再写入；仅当无 fieldDict 时作遗留 fallback 尝试 decode raw */
+    rawLines?: Array<{
+        hex: string;
+    }>;
+};
+/** 线程索引键 `${tgid}:${pid}`（hitrace 语义；对齐 hiperf sample.pid/tgid） */
+export type HitraceThreadIndexSnapshot = Record<string, readonly HitraceRecordSnapshot[]>;

package/dist/hitrace/contract.js

@@ -0,0 +1,5 @@
+/**
+ * hitrace 与 perf 合并侧车数据契约（可 structuredClone 进 Worker）。
+ * 由 hmtrace-parser `buildHitraceIndexSnapshot` 构建。
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * hm-pt-core：perf trace 公共类型与 trace format 解码原语。
+ */
+export type { RecordSampleHeader, CallchainEntry, RawEntry, CallchainFramesEntry, RecordSample, PerfData, } from "./perf/types.js";
+export { isPerfDataLike } from "./perf/is_perf_data_like.js";
+export type { HitraceRecordSnapshot, HitraceThreadIndexSnapshot, } from "./hitrace/contract.js";
+export type { TraceFormatField, ParsedTraceFormat, FieldDictTransformFn, TraceParserRegistry, DecodedRawSample, TracePrintMode, DecodeRawByRegistryOptions, } from "./trace/types.js";
+export type { Endian } from "./trace/parse.js";
+export type { PrintfSpec } from "./trace/printf.js";
+export { parseTraceFormat, parseCommonFieldsFromRaw, parseAllFieldsFromRaw, rawHexLinesToBuffer, bufferToRawHexLines, buildTraceParserRegistry, } from "./trace/parse.js";
+export { formatPrintfValue, tokenizePrintfFormat } from "./trace/printf.js";
+export { decodeRawByRegistry } from "./trace/decode_raw.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * hm-pt-core：perf trace 公共类型与 trace format 解码原语。
+ */
+export { isPerfDataLike } from "./perf/is_perf_data_like.js";
+export { parseTraceFormat, parseCommonFieldsFromRaw, parseAllFieldsFromRaw, rawHexLinesToBuffer, bufferToRawHexLines, buildTraceParserRegistry, } from "./trace/parse.js";
+export { formatPrintfValue, tokenizePrintfFormat } from "./trace/printf.js";
+export { decodeRawByRegistry } from "./trace/decode_raw.js";

package/dist/perf/is_perf_data_like.d.ts

@@ -0,0 +1,3 @@
+import type { PerfData } from "./types.js";
+/** 是否为 `{ recordSamples: ... }` 形态的 {@link PerfData}（用于统一 API 入参判别）。 */
+export declare function isPerfDataLike(x: unknown): x is PerfData;

package/dist/perf/is_perf_data_like.js

@@ -0,0 +1,8 @@
+/** 是否为 `{ recordSamples: ... }` 形态的 {@link PerfData}（用于统一 API 入参判别）。 */
+export function isPerfDataLike(x) {
+    return (typeof x === "object" &&
+        x !== null &&
+        !Array.isArray(x) &&
+        "recordSamples" in x &&
+        Array.isArray(x.recordSamples));
+}

package/dist/perf/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 与 hiperf 导出结构对应的 **核心数据类型**。
+ */
+/** 单条 `record sample` 首行的 type / misc / size 数值。 */
+export interface RecordSampleHeader {
+    type: number;
+    misc: number;
+    size: number;
+}
+export interface CallchainEntry {
+    nr: number;
+    addresses: string[];
+}
+export interface RawEntry {
+    size: number;
+    lines: Array<{
+        hex: string;
+        short?: string;
+    }>;
+}
+interface ServerEntry {
+    nr: number;
+    pids: number[];
+}
+export interface CallchainFramesEntry {
+    count: number;
+    frames: string[];
+}
+export interface RecordSample {
+    header: RecordSampleHeader;
+    sample_type: string;
+    id: number;
+    ip: string;
+    pid: number;
+    tid: number;
+    time: number;
+    stream_id: number;
+    cpu: number;
+    res: number;
+    period: number;
+    callchain?: CallchainEntry;
+    raw?: RawEntry;
+    /** tracePrintMode 为 fieldDict 且解码成功时：print 各参数键值（用于导出 txt/json） */
+    traceFieldDict?: Record<string, string>;
+    server?: ServerEntry;
+    callchainFrames?: CallchainFramesEntry;
+}
+export type PerfData = {
+    recordSamples: RecordSample[];
+};
+export {};

package/dist/perf/types.js

@@ -0,0 +1,4 @@
+/**
+ * 与 hiperf 导出结构对应的 **核心数据类型**。
+ */
+export {};

package/dist/trace/decode_raw.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 对一条 raw 数据先解 common_*，再按 common_type 选择解析器，最后按 print fmt 渲染。
+ * 找不到解析器时返回 skipped=true（不打印日志）。
+ */
+import type { DecodeRawByRegistryOptions, DecodedRawSample, TraceParserRegistry } from "./types.js";
+export declare function decodeRawByRegistry(raw: Uint8Array, registry: TraceParserRegistry, options?: DecodeRawByRegistryOptions): Omit<DecodedRawSample, "sampleIndex">;

package/dist/trace/decode_raw.js

@@ -0,0 +1,53 @@
+import { parseAllFieldsFromRaw, parseCommonFieldsFromRaw } from "./parse.js";
+import { renderPrintFmt, renderPrintFmtAsFieldDict } from "./printf.js";
+export function decodeRawByRegistry(raw, registry, options = {}) {
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const commonType = raw.length >= 2 ? view.getUint16(0, true) : undefined;
+    const commonFields = registry.commonFormat !== undefined
+        ? parseCommonFieldsFromRaw(raw, registry.commonFormat)
+        : {};
+    const commonTypeFromFields = commonFields.common_type;
+    const eventId = typeof commonTypeFromFields === "bigint"
+        ? Number(commonTypeFromFields)
+        : typeof commonTypeFromFields === "number"
+            ? commonTypeFromFields
+            : commonType;
+    const fmt = eventId === undefined ? undefined : registry.byEventId.get(eventId);
+    if (eventId === undefined || !fmt) {
+        return {
+            commonType: eventId,
+            commonFields,
+            skipped: true,
+        };
+    }
+    const allFields = parseAllFieldsFromRaw(raw, fmt);
+    const mode = options.tracePrintMode ?? "printf";
+    if (fmt.printFmt && mode === "fieldDict") {
+        let renderedFieldDict = renderPrintFmtAsFieldDict(fmt.printFmt, fmt.printArgs, allFields);
+        const transform = registry.transformFieldDictByEventId?.get(eventId);
+        if (transform) {
+            renderedFieldDict = transform({
+                eventId,
+                eventName: fmt.eventName,
+                rawFieldMap: allFields,
+                fieldDict: renderedFieldDict,
+            });
+        }
+        return {
+            commonType: eventId,
+            commonFields,
+            eventName: fmt.eventName,
+            renderedFieldDict,
+            renderedText: JSON.stringify(renderedFieldDict),
+            skipped: false,
+        };
+    }
+    const renderedText = fmt.printFmt ? renderPrintFmt(fmt.printFmt, fmt.printArgs, allFields) : undefined;
+    return {
+        commonType: eventId,
+        commonFields,
+        eventName: fmt.eventName,
+        renderedText,
+        skipped: false,
+    };
+}

package/dist/trace/parse.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Trace format 文本解析、raw 缓冲与 registry 构建。
+ * @module traceFormat
+ */
+import type { FieldDictTransformFn, ParsedTraceFormat, TraceParserRegistry } from "./types.js";
+export type Endian = "le" | "be";
+/**
+ * 解析 sample/trace_format 风格的文本，得到字段列表
+ */
+export declare function parseTraceFormat(text: string): ParsedTraceFormat;
+/**
+ * 仅解析 format 中 common_* 字段（按 offset/size/signed，小端）
+ */
+export declare function parseCommonFieldsFromRaw(raw: Uint8Array, format: ParsedTraceFormat): Record<string, number | bigint>;
+/**
+ * 解析 format 中全部字段（含数组），数组字段名会去掉 []，如 args[6] => args: [...]
+ */
+export declare function parseAllFieldsFromRaw(raw: Uint8Array, format: ParsedTraceFormat): Record<string, number | bigint | string | Array<number | bigint>>;
+/**
+ * 将 perf 文本里 raw 段的 hex 行拼成连续字节（小端）。
+ *
+ * 规则：每行视为一个整数 token（如 0x12345678），按该 token 的字节宽度转成 LE 字节序。
+ * 例如：0x12345678 => [0x78, 0x56, 0x34, 0x12]
+ */
+export declare function rawHexLinesToBuffer(lines: Array<{
+    hex: string;
+}>, endian?: Endian): Uint8Array;
+/**
+ * 将字节缓冲按小端编码为 raw hex 行。
+ * 默认每行 4 字节（即 8 hex digits）。
+ */
+export declare function bufferToRawHexLines(raw: Uint8Array, bytesPerLine?: number, endian?: Endian): Array<{
+    hex: string;
+}>;
+/**
+ * 从多个 trace_format 文本构建解析器集合（按 event ID 索引）。
+ *
+ * 为了让 fieldDict 模式下能对特定事件的 dict 做二次加工，这里支持将「文本 + 回调」直接绑定：
+ *
+ * - 传入 string 时：等价于只提供 format 文本，不带回调；
+ * - 传入 { text, transformFieldDict } 时：该文本解析出的 eventId 会绑定对应回调。
+ *
+ * 若用户未配置 transformFieldDict，或未使用 fieldDict 模式，则不会做任何额外处理。
+ */
+export declare function buildTraceParserRegistry(formatTexts: Array<string | {
+    text: string;
+    transformFieldDict?: FieldDictTransformFn;
+}>): TraceParserRegistry;

package/dist/trace/parse.js

@@ -0,0 +1,317 @@
+/**
+ * Trace format 文本解析、raw 缓冲与 registry 构建。
+ * @module traceFormat
+ */
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: false });
+const FIELD_LINE_RE = /^\s*field\s*:\s*([^;]+)\s*;\s*offset\s*:\s*(\d+)\s*;\s*size\s*:\s*(\d+)\s*;\s*signed\s*:\s*([01])\s*;?\s*$/i;
+function hexNibble(ch) {
+    const code = ch.charCodeAt(0);
+    if (code >= 48 && code <= 57)
+        return code - 48; // 0-9
+    const lower = code | 32; // to lower
+    if (lower >= 97 && lower <= 102)
+        return lower - 87; // a-f
+    return -1;
+}
+function hexPairToByte(hi, lo) {
+    const h = hexNibble(hi);
+    const l = hexNibble(lo);
+    if (h < 0 || l < 0)
+        return 0;
+    return (h << 4) | l;
+}
+function splitTypeAndName(rest) {
+    const trimmed = rest.trim();
+    const m = trimmed.match(/^(.+?)\s+(\w+(?:\[[^\]]*])?)$/);
+    if (!m) {
+        return { typeName: trimmed, name: trimmed };
+    }
+    return { typeName: m[1].trim(), name: m[2] };
+}
+/**
+ * 解析 sample/trace_format 风格的文本，得到字段列表
+ */
+export function parseTraceFormat(text) {
+    const lines = text.split(/\r?\n/);
+    let eventName;
+    let eventId;
+    const fields = [];
+    let printFmt;
+    let printArgs;
+    let inFormat = false;
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        if (!inFormat) {
+            const nameM = t.match(/^name\s*:\s*(.+)$/i);
+            if (nameM) {
+                eventName = nameM[1].trim();
+                continue;
+            }
+            const idM = t.match(/^id\s*:\s*(\d+)\s*$/i);
+            if (idM) {
+                eventId = parseInt(idM[1], 10);
+                continue;
+            }
+            if (/^format\s*:/i.test(t)) {
+                inFormat = true;
+                continue;
+            }
+            continue;
+        }
+        if (/^print\s+fmt\s*:/i.test(t)) {
+            const pf = t.match(/^print\s+fmt\s*:\s*"([^"]*)"\s*(?:,\s*(.*))?$/i);
+            if (pf) {
+                printFmt = pf[1];
+                const argsPart = pf[2];
+                if (argsPart) {
+                    const exprs = argsPart.match(/REC->[^,]+/g);
+                    printArgs = exprs ? exprs.map((s) => s.trim()) : [];
+                }
+                else {
+                    printArgs = [];
+                }
+            }
+            break;
+        }
+        const fm = t.match(FIELD_LINE_RE);
+        if (!fm)
+            continue;
+        const { typeName, name } = splitTypeAndName(fm[1]);
+        fields.push({
+            typeName,
+            name,
+            offset: parseInt(fm[2], 10),
+            size: parseInt(fm[3], 10),
+            signed: fm[4] === "1",
+        });
+    }
+    return { eventName, eventId, printFmt, printArgs, fields };
+}
+function normalizeType(t) {
+    return t.replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * 从 little-endian 原始缓冲区按字段描述读一个标量
+ */
+function readFieldScalar(view, field) {
+    const { offset, size, signed, typeName } = field;
+    if (offset + size > view.byteLength)
+        return undefined;
+    const t = normalizeType(typeName);
+    if (size === 1) {
+        if (signed || t === "signed char") {
+            return view.getInt8(offset);
+        }
+        return view.getUint8(offset);
+    }
+    if (size === 2) {
+        if (signed || t === "short") {
+            return view.getInt16(offset, true);
+        }
+        return view.getUint16(offset, true);
+    }
+    if (size === 4) {
+        if (t.includes("float")) {
+            return view.getFloat32(offset, true);
+        }
+        if (signed || t === "int" || t === "long" /* 32-bit 内核上 */) {
+            return view.getInt32(offset, true);
+        }
+        return view.getUint32(offset, true);
+    }
+    if (size === 8) {
+        if (t.includes("double")) {
+            return view.getFloat64(offset, true);
+        }
+        if (signed || t === "long" || t === "long long" || t === "__s64") {
+            return view.getBigInt64(offset, true);
+        }
+        return view.getBigUint64(offset, true);
+    }
+    return undefined;
+}
+function parseArrayName(name) {
+    const m = name.match(/^(\w+)\[(\d+)\]$/);
+    if (!m)
+        return undefined;
+    return { baseName: m[1], len: parseInt(m[2], 10) };
+}
+function readFieldValue(view, field) {
+    const arr = parseArrayName(field.name);
+    if (!arr)
+        return readFieldScalar(view, field);
+    if (arr.len <= 0)
+        return [];
+    const elemSize = Math.floor(field.size / arr.len);
+    if (elemSize <= 0)
+        return undefined;
+    const values = [];
+    for (let i = 0; i < arr.len; i++) {
+        const elemField = {
+            ...field,
+            name: arr.baseName,
+            offset: field.offset + i * elemSize,
+            size: elemSize,
+        };
+        const v = readFieldScalar(view, elemField);
+        if (v === undefined)
+            return undefined;
+        values.push(v);
+    }
+    return values;
+}
+/**
+ * 仅解析 format 中 common_* 字段（按 offset/size/signed，小端）
+ */
+export function parseCommonFieldsFromRaw(raw, format) {
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const out = {};
+    for (const field of format.fields) {
+        if (!field.name.startsWith("common_"))
+            continue;
+        const v = readFieldScalar(view, field);
+        if (v !== undefined) {
+            out[field.name] = v;
+        }
+    }
+    return out;
+}
+/**
+ * 解析 format 中全部字段（含数组），数组字段名会去掉 []，如 args[6] => args: [...]
+ */
+export function parseAllFieldsFromRaw(raw, format) {
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const out = {};
+    for (const field of format.fields) {
+        const arr = parseArrayName(field.name);
+        const key = arr ? arr.baseName : field.name;
+        const t = normalizeType(field.typeName);
+        // __data_loc char[] reason: 实际存一个 u32，低 16 位为 offset，高 16 位为 length
+        if (t.includes("__data_loc") && t.includes("char")) {
+            const locField = {
+                ...field,
+                typeName: "unsigned int",
+                signed: false,
+                size: 4,
+            };
+            const loc = readFieldScalar(view, locField);
+            if (typeof loc === "number") {
+                const locKey = `__data_loc_${field.name}`;
+                out[locKey] = loc;
+                const offset = loc & 0xffff;
+                const len = (loc >>> 16) & 0xffff;
+                if (offset >= 0 && len > 0 && offset + len <= raw.length) {
+                    const bytes = raw.subarray(offset, offset + len);
+                    // 去掉末尾 \0
+                    const nul = bytes.indexOf(0);
+                    const slice = nul >= 0 ? bytes.subarray(0, nul) : bytes;
+                    out[field.name] = UTF8_DECODER.decode(slice);
+                }
+                else {
+                    out[field.name] = "";
+                }
+            }
+            continue;
+        }
+        const v = readFieldValue(view, field);
+        if (v !== undefined) {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+/**
+ * 将 perf 文本里 raw 段的 hex 行拼成连续字节（小端）。
+ *
+ * 规则：每行视为一个整数 token（如 0x12345678），按该 token 的字节宽度转成 LE 字节序。
+ * 例如：0x12345678 => [0x78, 0x56, 0x34, 0x12]
+ */
+export function rawHexLinesToBuffer(lines, endian = "le") {
+    const normalizedTokens = [];
+    let totalBytes = 0;
+    for (const { hex } of lines) {
+        let s = hex.replace(/^0x/i, "").trim();
+        if (!s)
+            continue;
+        if (s.length % 2 === 1)
+            s = "0" + s;
+        normalizedTokens.push(s);
+        totalBytes += s.length / 2;
+    }
+    const out = new Uint8Array(totalBytes);
+    let pos = 0;
+    for (const s of normalizedTokens) {
+        if (endian === "le") {
+            for (let i = s.length - 2; i >= 0; i -= 2) {
+                out[pos++] = hexPairToByte(s[i], s[i + 1]);
+            }
+        }
+        else {
+            for (let i = 0; i < s.length; i += 2) {
+                out[pos++] = hexPairToByte(s[i], s[i + 1]);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * 将字节缓冲按小端编码为 raw hex 行。
+ * 默认每行 4 字节（即 8 hex digits）。
+ */
+export function bufferToRawHexLines(raw, bytesPerLine = 4, endian = "le") {
+    if (bytesPerLine <= 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < raw.length; i += bytesPerLine) {
+        const end = Math.min(i + bytesPerLine, raw.length);
+        let value = 0n;
+        if (endian === "le") {
+            for (let j = 0; j < end - i; j++) {
+                value |= BigInt(raw[i + j]) << BigInt(8 * j);
+            }
+        }
+        else {
+            for (let j = 0; j < end - i; j++) {
+                value = (value << 8n) | BigInt(raw[i + j]);
+            }
+        }
+        const width = (end - i) * 2;
+        out.push({ hex: "0x" + value.toString(16).padStart(width, "0") });
+    }
+    return out;
+}
+/**
+ * 从多个 trace_format 文本构建解析器集合（按 event ID 索引）。
+ *
+ * 为了让 fieldDict 模式下能对特定事件的 dict 做二次加工，这里支持将「文本 + 回调」直接绑定：
+ *
+ * - 传入 string 时：等价于只提供 format 文本，不带回调；
+ * - 传入 { text, transformFieldDict } 时：该文本解析出的 eventId 会绑定对应回调。
+ *
+ * 若用户未配置 transformFieldDict，或未使用 fieldDict 模式，则不会做任何额外处理。
+ */
+export function buildTraceParserRegistry(formatTexts) {
+    const byEventId = new Map();
+    let commonFormat;
+    const transformFieldDictByEventId = new Map();
+    for (const src of formatTexts) {
+        const text = typeof src === "string" ? src : src.text;
+        const fmt = parseTraceFormat(text);
+        if (fmt.eventId !== undefined) {
+            byEventId.set(fmt.eventId, fmt);
+            if (!commonFormat && fmt.fields.some((f) => f.name === "common_type")) {
+                commonFormat = fmt;
+            }
+            if (typeof src !== "string" && src.transformFieldDict) {
+                transformFieldDictByEventId.set(fmt.eventId, src.transformFieldDict);
+            }
+        }
+    }
+    return {
+        byEventId,
+        commonFormat,
+        transformFieldDictByEventId: transformFieldDictByEventId.size > 0 ? transformFieldDictByEventId : undefined,
+    };
+}

package/dist/trace/printf.d.ts

@@ -0,0 +1,32 @@
+/**
+ * printf / fieldDict 格式化与 print fmt 渲染。
+ * @module traceFormat
+ */
+type PrintFieldMap = Record<string, number | bigint | string | Array<number | bigint>>;
+/** 与 C printf 接近的转换说明符（不含 * 动态宽度等） */
+export interface PrintfSpec {
+    flags: string;
+    width?: number;
+    precision?: number;
+    length: string;
+    conv: string;
+}
+/**
+ * 按 C printf 子集格式化：标志 -+ #0 空格，宽度，精度，长度 hl ll hh，转换 d i u x X o s p。
+ */
+export declare function formatPrintfValue(value: number | bigint | string, spec: PrintfSpec): string;
+/**
+ * 将 print fmt 拆成文本、`%%`、与带参数的转换说明符。
+ */
+export declare function tokenizePrintfFormat(printFmt: string): Array<{
+    kind: "text";
+    text: string;
+} | {
+    kind: "literal_pct";
+} | {
+    kind: "spec";
+    spec: PrintfSpec;
+}>;
+export declare function renderPrintFmtAsFieldDict(printFmt: string, printArgs: string[] | undefined, fieldMap: PrintFieldMap): Record<string, string>;
+export declare function renderPrintFmt(printFmt: string, printArgs: string[] | undefined, fieldMap: PrintFieldMap): string;
+export {};

package/dist/trace/printf.js

@@ -0,0 +1,360 @@
+/**
+ * printf / fieldDict 格式化与 print fmt 渲染。
+ * @module traceFormat
+ */
+const PRINT_FMT_TOKEN_CACHE = new Map();
+const PRINT_FMT_SPEC_CACHE = new Map();
+const NORMALIZED_PRINT_ARGS_CACHE = new WeakMap();
+const EMPTY_PRINT_ARGS = [];
+const PRINT_FLAG_CHARS = new Set(["-", "+", "#", "0", " "]);
+const VALID_PRINTF_CONV = new Set(["d", "i", "u", "x", "X", "o", "s", "S", "p", "P"]);
+function hasPrintfFlag(flags, f) {
+    return flags.includes(f);
+}
+function toBigIntForPrintf(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "string")
+        return 0n;
+    if (!Number.isFinite(value))
+        return 0n;
+    return BigInt(Math.trunc(value));
+}
+/** 按 64 位无符号解释（与内核 trace 常见 long 一致） */
+function asUInt64(n) {
+    return n & ((1n << 64n) - 1n);
+}
+function applyWidth(s, width, leftAlign, zeroPad) {
+    if (width === undefined || s.length >= width)
+        return s;
+    const padLen = width - s.length;
+    const ch = zeroPad && !leftAlign ? "0" : " ";
+    if (leftAlign)
+        return s + ch.repeat(padLen);
+    return ch.repeat(padLen) + s;
+}
+/** 带符号十进制：支持 precision、0 宽度、+- 空格 */
+function formatPrintfD(n, spec) {
+    const neg = n < 0n;
+    const abs = neg ? -n : n;
+    let digits = abs.toString(10);
+    const prec = spec.precision !== undefined ? spec.precision : 1;
+    digits = digits.padStart(Math.max(prec, digits.length), "0");
+    let sign = "";
+    if (neg)
+        sign = "-";
+    else if (hasPrintfFlag(spec.flags, "+"))
+        sign = "+";
+    else if (hasPrintfFlag(spec.flags, " "))
+        sign = " ";
+    const body = sign + digits;
+    if (spec.width === undefined || body.length >= spec.width)
+        return body;
+    const padLen = spec.width - body.length;
+    if (hasPrintfFlag(spec.flags, "0") && !hasPrintfFlag(spec.flags, "-") && spec.precision === undefined) {
+        if (sign)
+            return sign + "0".repeat(padLen) + digits;
+        return "0".repeat(padLen) + body;
+    }
+    if (hasPrintfFlag(spec.flags, "-"))
+        return body + " ".repeat(padLen);
+    return " ".repeat(padLen) + body;
+}
+function formatPrintfUnsignedRadix(unsigned, spec, radix, upper) {
+    let body = radix === 16
+        ? upper
+            ? unsigned.toString(16).toUpperCase()
+            : unsigned.toString(16)
+        : unsigned.toString(radix);
+    const precDefault = 1;
+    const prec = spec.precision !== undefined ? spec.precision : precDefault;
+    body = body.padStart(Math.max(prec, body.length), "0");
+    if (hasPrintfFlag(spec.flags, "#")) {
+        if (radix === 16)
+            body = (upper ? "0X" : "0x") + body;
+        else if (radix === 8 && body !== "0" && !body.startsWith("0"))
+            body = "0" + body;
+    }
+    const zeroPad = hasPrintfFlag(spec.flags, "0") &&
+        !hasPrintfFlag(spec.flags, "-") &&
+        spec.precision === undefined;
+    return applyWidth(body, spec.width, hasPrintfFlag(spec.flags, "-"), zeroPad);
+}
+/**
+ * 按 C printf 子集格式化：标志 -+ #0 空格，宽度，精度，长度 hl ll hh，转换 d i u x X o s p。
+ */
+export function formatPrintfValue(value, spec) {
+    const conv = spec.conv;
+    const cl = conv.toLowerCase();
+    if (conv === "s" || conv === "S") {
+        let s = typeof value === "string" ? value : String(value);
+        if (spec.precision !== undefined) {
+            s = s.slice(0, spec.precision);
+        }
+        return applyWidth(s, spec.width, hasPrintfFlag(spec.flags, "-"), false);
+    }
+    const n = toBigIntForPrintf(value);
+    if (conv === "p" || conv === "P") {
+        const u = asUInt64(n);
+        const upper = conv === "P";
+        let body = upper ? u.toString(16).toUpperCase() : u.toString(16);
+        const prec = spec.precision !== undefined ? spec.precision : 1;
+        body = body.padStart(Math.max(prec, body.length), "0");
+        const zeroPad = hasPrintfFlag(spec.flags, "0") &&
+            !hasPrintfFlag(spec.flags, "-") &&
+            spec.precision === undefined;
+        return applyWidth(body, spec.width, hasPrintfFlag(spec.flags, "-"), zeroPad);
+    }
+    if (cl === "d" || cl === "i") {
+        return formatPrintfD(n, spec);
+    }
+    if (cl === "u" || cl === "x" || cl === "X" || cl === "o") {
+        const u = asUInt64(n);
+        if (cl === "u") {
+            let body = u.toString(10);
+            const prec = spec.precision !== undefined ? spec.precision : 1;
+            body = body.padStart(Math.max(prec, body.length), "0");
+            const zeroPad = hasPrintfFlag(spec.flags, "0") &&
+                !hasPrintfFlag(spec.flags, "-") &&
+                spec.precision === undefined;
+            return applyWidth(body, spec.width, hasPrintfFlag(spec.flags, "-"), zeroPad);
+        }
+        if (cl === "o") {
+            return formatPrintfUnsignedRadix(u, spec, 8, false);
+        }
+        return formatPrintfUnsignedRadix(u, spec, 16, conv === "X");
+    }
+    return String(value);
+}
+/**
+ * 将 print fmt 拆成文本、`%%`、与带参数的转换说明符。
+ */
+export function tokenizePrintfFormat(printFmt) {
+    const out = [];
+    let i = 0;
+    let textBuf = "";
+    const flushText = () => {
+        if (textBuf.length > 0) {
+            out.push({ kind: "text", text: textBuf });
+            textBuf = "";
+        }
+    };
+    while (i < printFmt.length) {
+        if (printFmt[i] !== "%") {
+            textBuf += printFmt[i];
+            i++;
+            continue;
+        }
+        flushText();
+        const pctPos = i;
+        if (i + 1 >= printFmt.length) {
+            textBuf += "%";
+            i++;
+            continue;
+        }
+        if (printFmt[i + 1] === "%") {
+            out.push({ kind: "literal_pct" });
+            i += 2;
+            continue;
+        }
+        i++;
+        let flags = "";
+        while (i < printFmt.length && PRINT_FLAG_CHARS.has(printFmt[i])) {
+            flags += printFmt[i];
+            i++;
+        }
+        let width;
+        if (i < printFmt.length && printFmt[i] >= "0" && printFmt[i] <= "9") {
+            let w = 0;
+            while (i < printFmt.length && printFmt[i] >= "0" && printFmt[i] <= "9") {
+                w = w * 10 + (printFmt[i].charCodeAt(0) - 48);
+                i++;
+            }
+            width = w;
+        }
+        let precision;
+        if (i < printFmt.length && printFmt[i] === ".") {
+            i++;
+            if (i < printFmt.length && printFmt[i] >= "0" && printFmt[i] <= "9") {
+                let p = 0;
+                while (i < printFmt.length && printFmt[i] >= "0" && printFmt[i] <= "9") {
+                    p = p * 10 + (printFmt[i].charCodeAt(0) - 48);
+                    i++;
+                }
+                precision = p;
+            }
+            else {
+                precision = 0;
+            }
+        }
+        let length = "";
+        if (i < printFmt.length) {
+            if (printFmt[i] === "h") {
+                length = "h";
+                i++;
+                if (i < printFmt.length && printFmt[i] === "h") {
+                    length = "hh";
+                    i++;
+                }
+            }
+            else if (printFmt[i] === "l") {
+                length = "l";
+                i++;
+                if (i < printFmt.length && printFmt[i] === "l") {
+                    length = "ll";
+                    i++;
+                }
+            }
+            else if (printFmt[i] === "L" ||
+                printFmt[i] === "j" ||
+                printFmt[i] === "z" ||
+                printFmt[i] === "t") {
+                length = printFmt[i];
+                i++;
+            }
+        }
+        if (i >= printFmt.length) {
+            textBuf += printFmt.slice(pctPos, i);
+            break;
+        }
+        const conv = printFmt[i];
+        i++;
+        if (!VALID_PRINTF_CONV.has(conv)) {
+            textBuf += printFmt.slice(pctPos, i);
+            continue;
+        }
+        out.push({ kind: "spec", spec: { flags, width, precision, length, conv } });
+    }
+    flushText();
+    return out;
+}
+function extractPrintfSpecs(printFmt) {
+    const cached = PRINT_FMT_SPEC_CACHE.get(printFmt);
+    if (cached)
+        return cached;
+    const specs = tokenizePrintfFormat(printFmt)
+        .filter((t) => t.kind === "spec")
+        .map((t) => t.spec);
+    PRINT_FMT_SPEC_CACHE.set(printFmt, specs);
+    return specs;
+}
+function getCachedPrintfTokens(printFmt) {
+    const cached = PRINT_FMT_TOKEN_CACHE.get(printFmt);
+    if (cached)
+        return cached;
+    const tokens = tokenizePrintfFormat(printFmt);
+    PRINT_FMT_TOKEN_CACHE.set(printFmt, tokens);
+    return tokens;
+}
+function normalizePrintExpr(exprRaw) {
+    let expr = exprRaw.trim();
+    while (expr.startsWith("("))
+        expr = expr.slice(1).trim();
+    while (expr.endsWith(")"))
+        expr = expr.slice(0, -1).trim();
+    expr = expr.replace(/\s+/g, "");
+    return expr;
+}
+function getNormalizedPrintArgs(printArgs) {
+    if (!printArgs || printArgs.length === 0)
+        return EMPTY_PRINT_ARGS;
+    const cached = NORMALIZED_PRINT_ARGS_CACHE.get(printArgs);
+    if (cached)
+        return cached;
+    const normalizedArgs = printArgs.map(normalizePrintExpr);
+    NORMALIZED_PRINT_ARGS_CACHE.set(printArgs, normalizedArgs);
+    return normalizedArgs;
+}
+function evalPrintArgExpr(exprRaw, fieldMap) {
+    const expr = normalizePrintExpr(exprRaw);
+    let m = expr.match(/^REC->(\w+)&0xffff$/);
+    if (m) {
+        const v = fieldMap[m[1]];
+        const n = typeof v === "number" ? v : 0;
+        return n & 0xffff;
+    }
+    m = expr.match(/^REC->(\w+)>>16$/);
+    if (m) {
+        const v = fieldMap[m[1]];
+        const n = typeof v === "number" ? v : 0;
+        return (n >>> 16) & 0xffff;
+    }
+    m = expr.match(/^REC->(\w+)(?:\[(\d+)])?$/);
+    if (!m)
+        return 0;
+    const name = m[1];
+    const idxRaw = m[2];
+    const v = fieldMap[name];
+    if (idxRaw !== undefined) {
+        const idx = parseInt(idxRaw, 10);
+        if (Array.isArray(v) && idx >= 0 && idx < v.length) {
+            return v[idx];
+        }
+        return 0;
+    }
+    if (Array.isArray(v))
+        return v[0] ?? 0;
+    return v ?? 0;
+}
+function buildPrintArgValues(printArgs, fieldMap) {
+    const normalizedArgs = getNormalizedPrintArgs(printArgs);
+    const values = (printArgs ?? []).map((e) => evalPrintArgExpr(e, fieldMap));
+    return { normalizedArgs, values };
+}
+function formatOnePrintArg(idx, spec, fieldMap, normalizedArgs, values) {
+    const v = values[idx] ?? 0;
+    const argExpr = normalizedArgs[idx] ?? "";
+    if (spec.conv === "s" || spec.conv === "S") {
+        const m = argExpr.match(/^REC->__data_loc_(\w+)(?:&0xffff)?(?:>>16)?$/);
+        if (m) {
+            const s = fieldMap[m[1]];
+            if (typeof s === "string") {
+                return formatPrintfValue(s, spec);
+            }
+        }
+    }
+    return formatPrintfValue(v, spec);
+}
+function fieldKeyFromNormalizedArg(normalizedArg, index) {
+    let k = normalizedArg;
+    if (k.startsWith("REC->"))
+        k = k.slice(5);
+    // REC->__data_loc_path&0xffff 在 fieldDict 中收敛为 path 作为键名
+    const mDataLocOff = k.match(/^__data_loc_(\w+)&0xffff$/);
+    if (mDataLocOff) {
+        return mDataLocOff[1];
+    }
+    return k.length > 0 ? k : `arg${index}`;
+}
+export function renderPrintFmtAsFieldDict(printFmt, printArgs, fieldMap) {
+    const { normalizedArgs, values } = buildPrintArgValues(printArgs, fieldMap);
+    const specs = extractPrintfSpecs(printFmt);
+    const out = {};
+    const seen = new Map();
+    for (let i = 0; i < specs.length; i++) {
+        const base = fieldKeyFromNormalizedArg(normalizedArgs[i] ?? "", i);
+        const n = (seen.get(base) ?? 0) + 1;
+        seen.set(base, n);
+        const key = n === 1 ? base : `${base}__${n}`;
+        out[key] = formatOnePrintArg(i, specs[i], fieldMap, normalizedArgs, values);
+    }
+    return out;
+}
+export function renderPrintFmt(printFmt, printArgs, fieldMap) {
+    const { normalizedArgs, values } = buildPrintArgValues(printArgs, fieldMap);
+    const tokens = getCachedPrintfTokens(printFmt);
+    let argIdx = 0;
+    let out = "";
+    for (const tok of tokens) {
+        if (tok.kind === "text") {
+            out += tok.text;
+        }
+        else if (tok.kind === "literal_pct") {
+            out += "%";
+        }
+        else {
+            out += formatOnePrintArg(argIdx++, tok.spec, fieldMap, normalizedArgs, values);
+        }
+    }
+    return out;
+}

package/dist/trace/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Trace format 相关类型定义。
+ */
+export interface TraceFormatField {
+    /** 完整类型串，如 "unsigned short"、"int" */
+    typeName: string;
+    /** 字段名，如 common_type、args[6] */
+    name: string;
+    offset: number;
+    size: number;
+    signed: boolean;
+}
+export interface ParsedTraceFormat {
+    eventName?: string;
+    eventId?: number;
+    printFmt?: string;
+    printArgs?: string[];
+    fields: TraceFormatField[];
+}
+/** 在 fieldDict 模式下，对某个事件的 fieldDict 做二次加工的回调 */
+export type FieldDictTransformFn = (params: {
+    eventId?: number;
+    eventName?: string;
+    rawFieldMap: Record<string, number | bigint | string | Array<number | bigint>>;
+    fieldDict: Record<string, string>;
+}) => Record<string, string>;
+export interface TraceParserRegistry {
+    byEventId: Map<number, ParsedTraceFormat>;
+    commonFormat?: ParsedTraceFormat;
+    transformFieldDictByEventId?: Map<number, FieldDictTransformFn>;
+}
+export interface DecodedRawSample {
+    sampleIndex: number;
+    commonType?: number;
+    commonFields: Record<string, number | bigint>;
+    eventName?: string;
+    renderedText?: string;
+    renderedFieldDict?: Record<string, string>;
+    skipped: boolean;
+}
+/** printf：整条 print fmt 渲染为一句；fieldDict：按格式符逐项生成字段名 → 格式化字符串 */
+export type TracePrintMode = "printf" | "fieldDict";
+export interface DecodeRawByRegistryOptions {
+    tracePrintMode?: TracePrintMode;
+}

package/dist/trace/types.js

@@ -0,0 +1,4 @@
+/**
+ * Trace format 相关类型定义。
+ */
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "hm-pt-core",
+  "version": "1.0.0",
+  "description": "DFX perf trace shared types and trace format decode primitives",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:perf": "node --test tests/*.perf.mjs",
+    "test:all": "npm run test && npm run test:perf"
+  },
+  "keywords": [
+    "perf",
+    "trace",
+    "hm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  }
+}