hm-pt-core 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export type { RecordSampleHeader, CallchainEntry, RawEntry, CallchainFramesEntry
 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 { Endian, BuildTraceParserRegistryOptions } from "./trace/parse.js";
+export { TraceFieldDecodeError } 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";

package/dist/index.js

@@ -2,6 +2,7 @@
  * hm-pt-core：perf trace 公共类型与 trace format 解码原语。
  */
 export { isPerfDataLike } from "./perf/is_perf_data_like.js";
+export { TraceFieldDecodeError } from "./trace/parse.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/trace/parse.d.ts

@@ -4,6 +4,17 @@
  */
 import type { FieldDictTransformFn, ParsedTraceFormat, TraceParserRegistry } from "./types.js";
 export type Endian = "le" | "be";
+export declare class TraceFieldDecodeError extends Error {
+    readonly fieldName: string;
+    readonly offset: number;
+    readonly size: number;
+    readonly rawLength: number;
+    constructor(message: string, fieldName: string, offset: number, size: number, rawLength: number);
+}
+export interface BuildTraceParserRegistryOptions {
+    /** 允许后注册的 format 覆盖同 ID 事件；默认 false，重复 ID 会抛错 */
+    allowDuplicateEventIds?: boolean;
+}
 /**
  * 解析 sample/trace_format 风格的文本，得到字段列表
  */
@@ -45,4 +56,4 @@ export declare function bufferToRawHexLines(raw: Uint8Array, bytesPerLine?: numb
 export declare function buildTraceParserRegistry(formatTexts: Array<string | {
     text: string;
     transformFieldDict?: FieldDictTransformFn;
-}>): TraceParserRegistry;
+}>, options?: BuildTraceParserRegistryOptions): TraceParserRegistry;

package/dist/trace/parse.js

@@ -3,6 +3,20 @@
  * @module traceFormat
  */
 const UTF8_DECODER = new TextDecoder("utf-8", { fatal: false });
+export class TraceFieldDecodeError extends Error {
+    fieldName;
+    offset;
+    size;
+    rawLength;
+    constructor(message, fieldName, offset, size, rawLength) {
+        super(message);
+        this.fieldName = fieldName;
+        this.offset = offset;
+        this.size = size;
+        this.rawLength = rawLength;
+        this.name = "TraceFieldDecodeError";
+    }
+}
 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);
@@ -16,10 +30,129 @@ function hexNibble(ch) {
 function hexPairToByte(hi, lo) {
     const h = hexNibble(hi);
     const l = hexNibble(lo);
-    if (h < 0 || l < 0)
-        return 0;
+    if (h < 0 || l < 0) {
+        throw new Error(`Invalid hex byte: "${hi}${lo}"`);
+    }
     return (h << 4) | l;
 }
+function readCharArrayAsString(raw, offset, size, fieldName) {
+    if (offset < 0 || offset + size > raw.length) {
+        throw new TraceFieldDecodeError(`Field "${fieldName}" out of bounds: offset=${offset}, size=${size}, raw.length=${raw.length}`, fieldName, offset, size, raw.length);
+    }
+    const bytes = raw.subarray(offset, offset + size);
+    const nul = bytes.indexOf(0);
+    const slice = nul >= 0 ? bytes.subarray(0, nul) : bytes;
+    return UTF8_DECODER.decode(slice);
+}
+function decodePrintFmtEscape(line, escapeStart) {
+    let i = escapeStart + 1;
+    if (i >= line.length) {
+        throw new Error(`Incomplete escape in print fmt string literal at index ${escapeStart}`);
+    }
+    const esc = line[i];
+    i++;
+    switch (esc) {
+        case '"':
+            return { value: '"', next: i };
+        case "\\":
+            return { value: "\\", next: i };
+        case "n":
+            return { value: "\n", next: i };
+        case "t":
+            return { value: "\t", next: i };
+        case "r":
+            return { value: "\r", next: i };
+        case "x": {
+            if (i + 1 >= line.length) {
+                throw new Error(`Incomplete \\x escape in print fmt string literal at index ${escapeStart}`);
+            }
+            const hi = hexNibble(line[i]);
+            const lo = hexNibble(line[i + 1]);
+            if (hi < 0 || lo < 0) {
+                throw new Error(`Invalid \\x escape in print fmt string literal at index ${escapeStart}`);
+            }
+            return { value: String.fromCharCode((hi << 4) | lo), next: i + 2 };
+        }
+        default: {
+            if (esc >= "0" && esc <= "7") {
+                let oct = esc.charCodeAt(0) - 48;
+                let digits = 1;
+                while (digits < 3 && i < line.length && line[i] >= "0" && line[i] <= "7") {
+                    oct = oct * 8 + (line[i].charCodeAt(0) - 48);
+                    i++;
+                    digits++;
+                }
+                return { value: String.fromCharCode(oct & 0xff), next: i };
+            }
+            return { value: "\\" + esc, next: i };
+        }
+    }
+}
+/** 扫描 print fmt 行中的双引号字符串字面量，支持常见 C 字符串转义 */
+function parsePrintFmtStringLiteral(line, start) {
+    if (line[start] !== '"')
+        return undefined;
+    let i = start + 1;
+    let value = "";
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === "\\") {
+            const decoded = decodePrintFmtEscape(line, i);
+            value += decoded.value;
+            i = decoded.next;
+            continue;
+        }
+        if (ch === '"') {
+            return { value, end: i + 1 };
+        }
+        value += ch;
+        i++;
+    }
+    return undefined;
+}
+function scanBalancedPrintArgs(argsPart) {
+    const args = [];
+    let i = 0;
+    while (i < argsPart.length) {
+        while (i < argsPart.length && /\s/.test(argsPart[i]))
+            i++;
+        if (i >= argsPart.length)
+            break;
+        const start = i;
+        let depth = 0;
+        while (i < argsPart.length) {
+            const ch = argsPart[i];
+            if (ch === "(")
+                depth++;
+            else if (ch === ")")
+                depth = Math.max(0, depth - 1);
+            else if (ch === "," && depth === 0)
+                break;
+            i++;
+        }
+        const expr = argsPart.slice(start, i).trim();
+        if (expr)
+            args.push(expr);
+        if (argsPart[i] === ",")
+            i++;
+    }
+    return args;
+}
+function parsePrintFmtLine(line) {
+    const prefix = line.match(/^print\s+fmt\s*:\s*/i);
+    if (!prefix)
+        return undefined;
+    const lit = parsePrintFmtStringLiteral(line, prefix[0].length);
+    if (!lit)
+        return undefined;
+    const rest = line.slice(lit.end).trim();
+    if (!rest)
+        return { printFmt: lit.value, printArgs: [] };
+    const argsMatch = rest.match(/^,\s*(.*)$/);
+    if (!argsMatch)
+        return undefined;
+    return { printFmt: lit.value, printArgs: scanBalancedPrintArgs(argsMatch[1]) };
+}
 function splitTypeAndName(rest) {
     const trimmed = rest.trim();
     const m = trimmed.match(/^(.+?)\s+(\w+(?:\[[^\]]*])?)$/);
@@ -61,17 +194,10 @@ export function parseTraceFormat(text) {
             continue;
         }
         if (/^print\s+fmt\s*:/i.test(t)) {
-            const pf = t.match(/^print\s+fmt\s*:\s*"([^"]*)"\s*(?:,\s*(.*))?$/i);
+            const pf = parsePrintFmtLine(t);
             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 = [];
-                }
+                printFmt = pf.printFmt;
+                printArgs = pf.printArgs;
             }
             break;
         }
@@ -92,6 +218,10 @@ export function parseTraceFormat(text) {
 function normalizeType(t) {
     return t.replace(/\s+/g, " ").trim().toLowerCase();
 }
+function isCharType(typeName) {
+    const t = normalizeType(typeName);
+    return t === "char" || t === "signed char" || t === "unsigned char";
+}
 /**
  * 从 little-endian 原始缓冲区按字段描述读一个标量
  */
@@ -202,6 +332,9 @@ export function parseAllFieldsFromRaw(raw, format) {
                 out[locKey] = loc;
                 const offset = loc & 0xffff;
                 const len = (loc >>> 16) & 0xffff;
+                if (len > 0 && (offset < 0 || offset + len > raw.length)) {
+                    throw new TraceFieldDecodeError(`Field "${field.name}" __data_loc out of bounds: offset=${offset}, len=${len}, raw.length=${raw.length}`, field.name, offset, len, raw.length);
+                }
                 if (offset >= 0 && len > 0 && offset + len <= raw.length) {
                     const bytes = raw.subarray(offset, offset + len);
                     // 去掉末尾 \0
@@ -215,6 +348,10 @@ export function parseAllFieldsFromRaw(raw, format) {
             }
             continue;
         }
+        if (arr && isCharType(field.typeName)) {
+            out[key] = readCharArrayAsString(raw, field.offset, field.size, field.name);
+            continue;
+        }
         const v = readFieldValue(view, field);
         if (v !== undefined) {
             out[key] = v;
@@ -233,8 +370,9 @@ export function rawHexLinesToBuffer(lines, endian = "le") {
     let totalBytes = 0;
     for (const { hex } of lines) {
         let s = hex.replace(/^0x/i, "").trim();
-        if (!s)
-            continue;
+        if (!s) {
+            throw new Error(`Invalid hex token: "${hex}"`);
+        }
         if (s.length % 2 === 1)
             s = "0" + s;
         normalizedTokens.push(s);
@@ -261,8 +399,9 @@ export function rawHexLinesToBuffer(lines, endian = "le") {
  * 默认每行 4 字节（即 8 hex digits）。
  */
 export function bufferToRawHexLines(raw, bytesPerLine = 4, endian = "le") {
-    if (bytesPerLine <= 0)
-        return [];
+    if (!Number.isSafeInteger(bytesPerLine) || bytesPerLine <= 0) {
+        throw new RangeError(`bytesPerLine must be a positive safe integer, got ${bytesPerLine}`);
+    }
     const out = [];
     for (let i = 0; i < raw.length; i += bytesPerLine) {
         const end = Math.min(i + bytesPerLine, raw.length);
@@ -292,14 +431,18 @@ export function bufferToRawHexLines(raw, bytesPerLine = 4, endian = "le") {
  *
  * 若用户未配置 transformFieldDict，或未使用 fieldDict 模式，则不会做任何额外处理。
  */
-export function buildTraceParserRegistry(formatTexts) {
+export function buildTraceParserRegistry(formatTexts, options = {}) {
     const byEventId = new Map();
     let commonFormat;
     const transformFieldDictByEventId = new Map();
-    for (const src of formatTexts) {
+    formatTexts.forEach((src, sourceIndex) => {
         const text = typeof src === "string" ? src : src.text;
         const fmt = parseTraceFormat(text);
         if (fmt.eventId !== undefined) {
+            const existing = byEventId.get(fmt.eventId);
+            if (existing && !options.allowDuplicateEventIds) {
+                throw new Error(`Duplicate event ID ${fmt.eventId}: "${existing.eventName ?? "unknown"}" conflicts with "${fmt.eventName ?? "unknown"}" at format index ${sourceIndex}`);
+            }
             byEventId.set(fmt.eventId, fmt);
             if (!commonFormat && fmt.fields.some((f) => f.name === "common_type")) {
                 commonFormat = fmt;
@@ -308,7 +451,7 @@ export function buildTraceParserRegistry(formatTexts) {
                 transformFieldDictByEventId.set(fmt.eventId, src.transformFieldDict);
             }
         }
-    }
+    });
     return {
         byEventId,
         commonFormat,

package/dist/trace/printf.d.ts

@@ -3,6 +3,8 @@
  * @module traceFormat
  */
 type PrintFieldMap = Record<string, number | bigint | string | Array<number | bigint>>;
+/** printf 格式串解析缓存上限（LRU 淘汰） */
+export declare const PRINTF_CACHE_MAX_SIZE = 256;
 /** 与 C printf 接近的转换说明符（不含 * 动态宽度等） */
 export interface PrintfSpec {
     flags: string;
@@ -27,6 +29,13 @@ export declare function tokenizePrintfFormat(printFmt: string): Array<{
     kind: "spec";
     spec: PrintfSpec;
 }>;
+/** 测试专用：重置 printf 解析缓存 */
+export declare function resetPrintfCachesForTest(): void;
+/** 测试专用：读取 printf 解析缓存条目数 */
+export declare function getPrintfCacheSizesForTest(): {
+    tokens: number;
+    specs: number;
+};
 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

@@ -2,8 +2,42 @@
  * printf / fieldDict 格式化与 print fmt 渲染。
  * @module traceFormat
  */
-const PRINT_FMT_TOKEN_CACHE = new Map();
-const PRINT_FMT_SPEC_CACHE = new Map();
+/** printf 格式串解析缓存上限（LRU 淘汰） */
+export const PRINTF_CACHE_MAX_SIZE = 256;
+class LruCache {
+    maxSize;
+    map = new Map();
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value === undefined)
+            return undefined;
+        this.map.delete(key);
+        this.map.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.map.has(key))
+            this.map.delete(key);
+        this.map.set(key, value);
+        while (this.map.size > this.maxSize) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+    }
+    get size() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+const PRINT_FMT_TOKEN_CACHE = new LruCache(PRINTF_CACHE_MAX_SIZE);
+const PRINT_FMT_SPEC_CACHE = new LruCache(PRINTF_CACHE_MAX_SIZE);
 const NORMALIZED_PRINT_ARGS_CACHE = new WeakMap();
 const EMPTY_PRINT_ARGS = [];
 const PRINT_FLAG_CHARS = new Set(["-", "+", "#", "0", " "]);
@@ -24,6 +58,47 @@ function toBigIntForPrintf(value) {
 function asUInt64(n) {
     return n & ((1n << 64n) - 1n);
 }
+/** 按长度修饰符截断无符号值（C printf 语义） */
+function maskUnsignedByLength(n, length) {
+    switch (length) {
+        case "hh":
+            return n & 0xffn;
+        case "h":
+            return n & 0xffffn;
+        case "l":
+        case "ll":
+        case "j":
+        case "z":
+        case "t":
+        case "L":
+            return asUInt64(n);
+        default:
+            return n & 0xffffffffn;
+    }
+}
+function signExtend(value, bits) {
+    const mask = (1n << BigInt(bits)) - 1n;
+    const v = value & mask;
+    const signBit = 1n << BigInt(bits - 1);
+    return v >= signBit ? v - (1n << BigInt(bits)) : v;
+}
+/** 按长度修饰符截断并符号扩展有符号值（C printf 语义） */
+function maskSignedByLength(n, length) {
+    switch (length) {
+        case "hh":
+            return signExtend(n, 8);
+        case "h":
+            return signExtend(n, 16);
+        case "l":
+        case "ll":
+        case "j":
+        case "z":
+        case "t":
+            return signExtend(asUInt64(n), 64);
+        default:
+            return signExtend(n & 0xffffffffn, 32);
+    }
+}
 function applyWidth(s, width, leftAlign, zeroPad) {
     if (width === undefined || s.length >= width)
         return s;
@@ -37,9 +112,15 @@ function applyWidth(s, width, leftAlign, zeroPad) {
 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 digits;
+    if (prec === 0 && abs === 0n) {
+        digits = "";
+    }
+    else {
+        digits = abs.toString(10);
+        digits = digits.padStart(Math.max(prec, digits.length), "0");
+    }
     let sign = "";
     if (neg)
         sign = "-";
@@ -61,24 +142,42 @@ function formatPrintfD(n, spec) {
     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);
+    let prefix = "";
     const precDefault = 1;
     const prec = spec.precision !== undefined ? spec.precision : precDefault;
-    body = body.padStart(Math.max(prec, body.length), "0");
-    if (hasPrintfFlag(spec.flags, "#")) {
+    let body;
+    if (prec === 0 && unsigned === 0n) {
+        body = "";
+    }
+    else {
+        body =
+            radix === 16
+                ? upper
+                    ? unsigned.toString(16).toUpperCase()
+                    : unsigned.toString(16)
+                : unsigned.toString(radix);
+        body = body.padStart(Math.max(prec, body.length), "0");
+    }
+    if (hasPrintfFlag(spec.flags, "#") && unsigned !== 0n) {
         if (radix === 16)
-            body = (upper ? "0X" : "0x") + body;
+            prefix = upper ? "0X" : "0x";
         else if (radix === 8 && body !== "0" && !body.startsWith("0"))
-            body = "0" + body;
+            prefix = "0";
     }
     const zeroPad = hasPrintfFlag(spec.flags, "0") &&
         !hasPrintfFlag(spec.flags, "-") &&
         spec.precision === undefined;
-    return applyWidth(body, spec.width, hasPrintfFlag(spec.flags, "-"), zeroPad);
+    const leftAlign = hasPrintfFlag(spec.flags, "-");
+    if (zeroPad && prefix) {
+        const width = spec.width;
+        if (width !== undefined) {
+            const bodyWidth = Math.max(width - prefix.length, body.length);
+            body = body.padStart(bodyWidth, "0");
+        }
+        return prefix + body;
+    }
+    const combined = prefix + body;
+    return applyWidth(combined, spec.width, leftAlign, zeroPad);
 }
 /**
  * 按 C printf 子集格式化：标志 -+ #0 空格，宽度，精度，长度 hl ll hh，转换 d i u x X o s p。
@@ -106,14 +205,20 @@ export function formatPrintfValue(value, spec) {
         return applyWidth(body, spec.width, hasPrintfFlag(spec.flags, "-"), zeroPad);
     }
     if (cl === "d" || cl === "i") {
-        return formatPrintfD(n, spec);
+        return formatPrintfD(maskSignedByLength(n, spec.length), spec);
     }
     if (cl === "u" || cl === "x" || cl === "X" || cl === "o") {
-        const u = asUInt64(n);
+        const u = maskUnsignedByLength(n, spec.length);
         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");
+            let body;
+            if (prec === 0 && u === 0n) {
+                body = "";
+            }
+            else {
+                body = u.toString(10);
+                body = body.padStart(Math.max(prec, body.length), "0");
+            }
             const zeroPad = hasPrintfFlag(spec.flags, "0") &&
                 !hasPrintfFlag(spec.flags, "-") &&
                 spec.precision === undefined;
@@ -246,12 +351,34 @@ function getCachedPrintfTokens(printFmt) {
     PRINT_FMT_TOKEN_CACHE.set(printFmt, tokens);
     return tokens;
 }
+/** 测试专用：重置 printf 解析缓存 */
+export function resetPrintfCachesForTest() {
+    PRINT_FMT_TOKEN_CACHE.clear();
+    PRINT_FMT_SPEC_CACHE.clear();
+}
+/** 测试专用：读取 printf 解析缓存条目数 */
+export function getPrintfCacheSizesForTest() {
+    return { tokens: PRINT_FMT_TOKEN_CACHE.size, specs: PRINT_FMT_SPEC_CACHE.size };
+}
 function normalizePrintExpr(exprRaw) {
     let expr = exprRaw.trim();
-    while (expr.startsWith("("))
-        expr = expr.slice(1).trim();
-    while (expr.endsWith(")"))
-        expr = expr.slice(0, -1).trim();
+    if (expr.startsWith("(") && expr.endsWith(")")) {
+        let depth = 0;
+        let fullyWrapped = true;
+        for (let i = 0; i < expr.length; i++) {
+            if (expr[i] === "(")
+                depth++;
+            else if (expr[i] === ")")
+                depth--;
+            if (depth === 0 && i < expr.length - 1) {
+                fullyWrapped = false;
+                break;
+            }
+        }
+        if (fullyWrapped && depth === 0) {
+            expr = expr.slice(1, -1).trim();
+        }
+    }
     expr = expr.replace(/\s+/g, "");
     return expr;
 }
@@ -267,7 +394,21 @@ function getNormalizedPrintArgs(printArgs) {
 }
 function evalPrintArgExpr(exprRaw, fieldMap) {
     const expr = normalizePrintExpr(exprRaw);
-    let m = expr.match(/^REC->(\w+)&0xffff$/);
+    let m = expr.match(/^__get_str\((\w+)\)$/);
+    if (m) {
+        const v = fieldMap[m[1]];
+        if (typeof v === "string")
+            return v;
+        throw new Error(`__get_str(${m[1]}) requires a string field, got ${typeof v}`);
+    }
+    m = expr.match(/^__get_dynamic_array\((\w+)\)$/);
+    if (m) {
+        const v = fieldMap[m[1]];
+        if (Array.isArray(v))
+            return v;
+        throw new Error(`__get_dynamic_array(${m[1]}) requires an array field, got ${typeof v}`);
+    }
+    m = expr.match(/^REC->(\w+)&0xffff$/);
     if (m) {
         const v = fieldMap[m[1]];
         const n = typeof v === "number" ? v : 0;
@@ -280,32 +421,49 @@ function evalPrintArgExpr(exprRaw, fieldMap) {
         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];
+    if (m) {
+        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];
+            }
+            throw new Error(`Invalid print arg index for REC->${name}[${idxRaw}]`);
         }
-        return 0;
+        if (Array.isArray(v))
+            return v[0] ?? 0;
+        if (v !== undefined)
+            return v;
+        throw new Error(`Missing field for print arg REC->${name}`);
     }
-    if (Array.isArray(v))
-        return v[0] ?? 0;
-    return v ?? 0;
+    throw new Error(`Unknown print arg expression: ${exprRaw.trim()}`);
 }
 function buildPrintArgValues(printArgs, fieldMap) {
     const normalizedArgs = getNormalizedPrintArgs(printArgs);
     const values = (printArgs ?? []).map((e) => evalPrintArgExpr(e, fieldMap));
     return { normalizedArgs, values };
 }
+function resolvePrintArgValue(value) {
+    if (value === undefined)
+        return 0;
+    if (Array.isArray(value))
+        return value[0] ?? 0;
+    return value;
+}
 function formatOnePrintArg(idx, spec, fieldMap, normalizedArgs, values) {
-    const v = values[idx] ?? 0;
+    const v = resolvePrintArgValue(values[idx]);
     const argExpr = normalizedArgs[idx] ?? "";
     if (spec.conv === "s" || spec.conv === "S") {
-        const m = argExpr.match(/^REC->__data_loc_(\w+)(?:&0xffff)?(?:>>16)?$/);
+        let m = argExpr.match(/^__get_str\((\w+)\)$/);
+        if (m) {
+            const s = fieldMap[m[1]];
+            if (typeof s === "string") {
+                return formatPrintfValue(s, spec);
+            }
+        }
+        m = argExpr.match(/^REC->__data_loc_(\w+)(?:&0xffff)?(?:>>16)?$/);
         if (m) {
             const s = fieldMap[m[1]];
             if (typeof s === "string") {
@@ -319,6 +477,14 @@ function fieldKeyFromNormalizedArg(normalizedArg, index) {
     let k = normalizedArg;
     if (k.startsWith("REC->"))
         k = k.slice(5);
+    const mGetStr = k.match(/^__get_str\((\w+)\)$/);
+    if (mGetStr) {
+        return mGetStr[1];
+    }
+    const mGetArr = k.match(/^__get_dynamic_array\((\w+)\)$/);
+    if (mGetArr) {
+        return mGetArr[1];
+    }
     // REC->__data_loc_path&0xffff 在 fieldDict 中收敛为 path 作为键名
     const mDataLocOff = k.match(/^__data_loc_(\w+)&0xffff$/);
     if (mDataLocOff) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-pt-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "DFX perf trace shared types and trace format decode primitives",
   "type": "module",
   "main": "dist/index.js",