hm-pt-core 1.0.0 → 1.0.2

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/decode_raw.js

@@ -21,9 +21,10 @@ export function decodeRawByRegistry(raw, registry, options = {}) {
         };
     }
     const allFields = parseAllFieldsFromRaw(raw, fmt);
+    const renderContext = { eventName: fmt.eventName, eventId };
     const mode = options.tracePrintMode ?? "printf";
     if (fmt.printFmt && mode === "fieldDict") {
-        let renderedFieldDict = renderPrintFmtAsFieldDict(fmt.printFmt, fmt.printArgs, allFields);
+        let renderedFieldDict = renderPrintFmtAsFieldDict(fmt.printFmt, fmt.printArgs, allFields, renderContext);
         const transform = registry.transformFieldDictByEventId?.get(eventId);
         if (transform) {
             renderedFieldDict = transform({
@@ -42,7 +43,9 @@ export function decodeRawByRegistry(raw, registry, options = {}) {
             skipped: false,
         };
     }
-    const renderedText = fmt.printFmt ? renderPrintFmt(fmt.printFmt, fmt.printArgs, allFields) : undefined;
+    const renderedText = fmt.printFmt
+        ? renderPrintFmt(fmt.printFmt, fmt.printArgs, allFields, renderContext)
+        : undefined;
     return {
         commonType: eventId,
         commonFields,

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,13 +218,93 @@ 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";
+}
+function isDataLocType(typeName) {
+    return normalizeType(typeName).includes("__data_loc");
+}
+function parseDataLocElementType(typeName, signed) {
+    const t = normalizeType(typeName);
+    const m = t.match(/^__data_loc\s+(.+)\[\]$/);
+    if (!m)
+        return undefined;
+    const elemTypeName = m[1].trim();
+    const elemSize = inferScalarSize(elemTypeName, signed);
+    if (elemSize === undefined)
+        return undefined;
+    return { elemTypeName, elemSize, signed: isSignedElementType(elemTypeName, signed) };
+}
+function isSignedElementType(elemTypeName, fieldSigned) {
+    const t = normalizeType(elemTypeName);
+    if (t.includes("unsigned"))
+        return false;
+    if (t === "char" && !fieldSigned)
+        return false;
+    return fieldSigned || t === "signed char" || t === "short" || t === "int" || t === "long" || t === "long long" || t === "__s64";
+}
+function inferScalarSize(typeName, signed) {
+    const t = normalizeType(typeName);
+    if (t.includes("double"))
+        return 8;
+    if (t.includes("long long") || t === "__s64")
+        return 8;
+    if (t.includes("long"))
+        return 8;
+    if (t.includes("short"))
+        return 2;
+    if (t.includes("char") || t.includes("int") || t.includes("float"))
+        return 4;
+    if (t.includes("unsigned") || signed)
+        return 4;
+    return undefined;
+}
+function assertFieldInBounds(fieldName, offset, size, rawLength) {
+    if (offset < 0 || offset + size > rawLength) {
+        throw new TraceFieldDecodeError(`Field "${fieldName}" out of bounds: offset=${offset}, size=${size}, raw.length=${rawLength}`, fieldName, offset, size, rawLength);
+    }
+}
+function readLocatorField(view, field) {
+    assertFieldInBounds(field.name, field.offset, field.size, view.byteLength);
+    const locField = {
+        ...field,
+        typeName: "unsigned int",
+        signed: false,
+        size: 4,
+    };
+    const loc = readFieldScalarUnchecked(view, locField);
+    if (typeof loc !== "number") {
+        throw new TraceFieldDecodeError(`Field "${field.name}" __data_loc locator is invalid`, field.name, field.offset, field.size, view.byteLength);
+    }
+    return loc;
+}
+function readDynamicRegionAsArray(raw, view, field, dataOffset, byteLen, elemTypeName, elemSize, elemSigned) {
+    if (byteLen === 0)
+        return [];
+    if (byteLen % elemSize !== 0) {
+        throw new TraceFieldDecodeError(`Field "${field.name}" __data_loc length ${byteLen} is not divisible by element size ${elemSize}`, field.name, dataOffset, byteLen, raw.length);
+    }
+    assertFieldInBounds(field.name, dataOffset, byteLen, raw.length);
+    const count = byteLen / elemSize;
+    const values = [];
+    for (let i = 0; i < count; i++) {
+        const elemField = {
+            typeName: elemTypeName,
+            name: field.name,
+            offset: dataOffset + i * elemSize,
+            size: elemSize,
+            signed: elemSigned,
+        };
+        values.push(readFieldScalarUnchecked(view, elemField));
+    }
+    return values;
+}
 /**
  * 从 little-endian 原始缓冲区按字段描述读一个标量
  */
-function readFieldScalar(view, field) {
+function readFieldScalarUnchecked(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") {
@@ -130,7 +336,14 @@ function readFieldScalar(view, field) {
         }
         return view.getBigUint64(offset, true);
     }
-    return undefined;
+    throw new TraceFieldDecodeError(`Field "${field.name}" has unsupported scalar size ${size}`, field.name, offset, size, view.byteLength);
+}
+/**
+ * 从 little-endian 原始缓冲区按字段描述读一个标量；越界时抛出 TraceFieldDecodeError。
+ */
+function readFieldScalar(view, field) {
+    assertFieldInBounds(field.name, field.offset, field.size, view.byteLength);
+    return readFieldScalarUnchecked(view, field);
 }
 function parseArrayName(name) {
     const m = name.match(/^(\w+)\[(\d+)\]$/);
@@ -144,9 +357,10 @@ function readFieldValue(view, field) {
         return readFieldScalar(view, field);
     if (arr.len <= 0)
         return [];
-    const elemSize = Math.floor(field.size / arr.len);
-    if (elemSize <= 0)
-        return undefined;
+    if (field.size % arr.len !== 0) {
+        throw new TraceFieldDecodeError(`Field "${field.name}" size ${field.size} is not divisible by array length ${arr.len}`, field.name, field.offset, field.size, view.byteLength);
+    }
+    const elemSize = field.size / arr.len;
     const values = [];
     for (let i = 0; i < arr.len; i++) {
         const elemField = {
@@ -155,10 +369,7 @@ function readFieldValue(view, field) {
             offset: field.offset + i * elemSize,
             size: elemSize,
         };
-        const v = readFieldScalar(view, elemField);
-        if (v === undefined)
-            return undefined;
-        values.push(v);
+        values.push(readFieldScalar(view, elemField));
     }
     return values;
 }
@@ -171,10 +382,9 @@ export function parseCommonFieldsFromRaw(raw, format) {
     for (const field of format.fields) {
         if (!field.name.startsWith("common_"))
             continue;
-        const v = readFieldScalar(view, field);
-        if (v !== undefined) {
-            out[field.name] = v;
-        }
+        if (field.offset + field.size > view.byteLength)
+            continue;
+        out[field.name] = readFieldScalar(view, field);
     }
     return out;
 }
@@ -188,23 +398,18 @@ export function parseAllFieldsFromRaw(raw, format) {
         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
+        if (isDataLocType(field.typeName)) {
+            const loc = readLocatorField(view, field);
+            const locKey = `__data_loc_${field.name}`;
+            out[locKey] = loc;
+            const dataOffset = loc & 0xffff;
+            const byteLen = (loc >>> 16) & 0xffff;
+            if (byteLen > 0 && (dataOffset < 0 || dataOffset + byteLen > raw.length)) {
+                throw new TraceFieldDecodeError(`Field "${field.name}" __data_loc out of bounds: offset=${dataOffset}, len=${byteLen}, raw.length=${raw.length}`, field.name, dataOffset, byteLen, raw.length);
+            }
+            if (t.includes("char")) {
+                if (byteLen > 0) {
+                    const bytes = raw.subarray(dataOffset, dataOffset + byteLen);
                     const nul = bytes.indexOf(0);
                     const slice = nul >= 0 ? bytes.subarray(0, nul) : bytes;
                     out[field.name] = UTF8_DECODER.decode(slice);
@@ -212,13 +417,20 @@ export function parseAllFieldsFromRaw(raw, format) {
                 else {
                     out[field.name] = "";
                 }
+                continue;
+            }
+            const elemInfo = parseDataLocElementType(field.typeName, field.signed);
+            if (!elemInfo) {
+                throw new TraceFieldDecodeError(`Field "${field.name}" uses unsupported __data_loc element type "${field.typeName}"`, field.name, field.offset, field.size, raw.length);
             }
+            out[key] = readDynamicRegionAsArray(raw, view, field, dataOffset, byteLen, elemInfo.elemTypeName, elemInfo.elemSize, elemInfo.signed);
             continue;
         }
-        const v = readFieldValue(view, field);
-        if (v !== undefined) {
-            out[key] = v;
+        if (arr && isCharType(field.typeName)) {
+            out[key] = readCharArrayAsString(raw, field.offset, field.size, field.name);
+            continue;
         }
+        out[key] = readFieldValue(view, field);
     }
     return out;
 }
@@ -233,8 +445,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 +474,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 +506,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;
@@ -307,8 +525,11 @@ export function buildTraceParserRegistry(formatTexts) {
             if (typeof src !== "string" && src.transformFieldDict) {
                 transformFieldDictByEventId.set(fmt.eventId, src.transformFieldDict);
             }
+            else {
+                transformFieldDictByEventId.delete(fmt.eventId);
+            }
         }
-    }
+    });
     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,17 @@ export declare function tokenizePrintfFormat(printFmt: string): Array<{
     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 interface PrintFmtRenderContext {
+    eventName?: string;
+    eventId?: number;
+}
+/** 测试专用：重置 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, context?: PrintFmtRenderContext): Record<string, string>;
+export declare function renderPrintFmt(printFmt: string, printArgs: string[] | undefined, fieldMap: PrintFieldMap, context?: PrintFmtRenderContext): 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,52 @@ 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");
+    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, "#")) {
-        if (radix === 16)
-            body = (upper ? "0X" : "0x") + body;
-        else if (radix === 8 && body !== "0" && !body.startsWith("0"))
-            body = "0" + body;
+        if (radix === 16 && unsigned !== 0n) {
+            prefix = upper ? "0X" : "0x";
+        }
+        else if (radix === 8) {
+            if (unsigned === 0n && (prec === 0 || body === "")) {
+                body = "0";
+            }
+            else if (body === "") {
+                body = "0";
+            }
+            else if (!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);
+    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 +215,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;
@@ -228,6 +343,16 @@ export function tokenizePrintfFormat(printFmt) {
     flushText();
     return out;
 }
+function assertPrintArgCount(printFmt, printArgs, context) {
+    const specCount = extractPrintfSpecs(printFmt).length;
+    const argCount = printArgs?.length ?? 0;
+    if (argCount < specCount) {
+        const eventLabel = context?.eventName !== undefined
+            ? `"${context.eventName}"${context.eventId !== undefined ? ` (ID ${context.eventId})` : ""}`
+            : "unknown event";
+        throw new Error(`Print fmt for event ${eventLabel} requires ${specCount} args but got ${argCount} at spec index ${argCount}: "${printFmt}"`);
+    }
+}
 function extractPrintfSpecs(printFmt) {
     const cached = PRINT_FMT_SPEC_CACHE.get(printFmt);
     if (cached)
@@ -246,12 +371,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 +414,29 @@ 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+)\)(?:\[(\d+)])?$/);
+    if (m) {
+        const v = fieldMap[m[1]];
+        if (!Array.isArray(v)) {
+            throw new Error(`__get_dynamic_array(${m[1]}) requires an array field, got ${typeof v}`);
+        }
+        if (m[2] !== undefined) {
+            const idx = parseInt(m[2], 10);
+            if (idx < 0 || idx >= v.length) {
+                throw new Error(`Invalid print arg index for __get_dynamic_array(${m[1]})[${m[2]}]`);
+            }
+            return v[idx];
+        }
+        return v;
+    }
+    m = expr.match(/^REC->(\w+)&0xffff$/);
     if (m) {
         const v = fieldMap[m[1]];
         const n = typeof v === "number" ? v : 0;
@@ -280,32 +449,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 +505,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+)\)(?:\[(\d+)])?$/);
+    if (mGetArr) {
+        return mGetArr[2] !== undefined ? `${mGetArr[1]}__${mGetArr[2]}` : mGetArr[1];
+    }
     // REC->__data_loc_path&0xffff 在 fieldDict 中收敛为 path 作为键名
     const mDataLocOff = k.match(/^__data_loc_(\w+)&0xffff$/);
     if (mDataLocOff) {
@@ -326,7 +520,8 @@ function fieldKeyFromNormalizedArg(normalizedArg, index) {
     }
     return k.length > 0 ? k : `arg${index}`;
 }
-export function renderPrintFmtAsFieldDict(printFmt, printArgs, fieldMap) {
+export function renderPrintFmtAsFieldDict(printFmt, printArgs, fieldMap, context) {
+    assertPrintArgCount(printFmt, printArgs, context);
     const { normalizedArgs, values } = buildPrintArgValues(printArgs, fieldMap);
     const specs = extractPrintfSpecs(printFmt);
     const out = {};
@@ -340,7 +535,8 @@ export function renderPrintFmtAsFieldDict(printFmt, printArgs, fieldMap) {
     }
     return out;
 }
-export function renderPrintFmt(printFmt, printArgs, fieldMap) {
+export function renderPrintFmt(printFmt, printArgs, fieldMap, context) {
+    assertPrintArgCount(printFmt, printArgs, context);
     const { normalizedArgs, values } = buildPrintArgValues(printArgs, fieldMap);
     const tokens = getCachedPrintfTokens(printFmt);
     let argIdx = 0;

package/package.json

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