@ats-cx/cx-core 0.1.0

package/dist/semantics/resolver.d.ts

@@ -0,0 +1,37 @@
+import type { EventSemantics } from "../types.js";
+/**
+ * 事件语义表。
+ *
+ * 这层的目标不是“为每个埋点写诊断规则”，而是为事件补充统一语义标签。
+ * 规则引擎只消费这些语义标签，不直接依赖具体事件名。
+ *
+ * 显式语义表由调用方注入（来自 ResolvedConfig.eventSemantics），本模块不读文件。
+ */
+export type SemanticsResolver = (event: {
+    eventName: string;
+    payload?: Record<string, unknown>;
+} | string) => EventSemantics;
+/**
+ * 创建事件语义解析器，显式语义表由调用方注入。
+ */
+export declare function createSemanticsResolver(explicitMap: Record<string, Partial<EventSemantics>>): SemanticsResolver;
+/**
+ * 是否属于会改变项目状态的事件。
+ * - definite: 明确会改状态
+ * - possible: 可能会改状态
+ * - commit: 属于保存/持久化，不算“编辑动作”，但在链路判断里很重要
+ */
+export declare function hasStateChange(semantics: EventSemantics, options?: {
+    includePossible?: boolean;
+    includeCommit?: boolean;
+}): boolean;
+/** 判断语义是否表示“保存动作”。 */
+export declare function isSaveEvent(semantics: EventSemantics): boolean;
+/** 判断语义是否表示“进入编辑态/页面”。 */
+export declare function isEnterEvent(semantics: EventSemantics): boolean;
+/** 判断语义是否表示“离开编辑态/页面”。 */
+export declare function isLeaveEvent(semantics: EventSemantics): boolean;
+/** 判断语义是否属于显式错误类事件。 */
+export declare function isErrorEvent(semantics: EventSemantics): boolean;
+/** 把状态变更级别转成人类可读中文，供诊断文案复用。 */
+export declare function describeStateChange(semantics: EventSemantics): string;

package/dist/semantics/resolver.js

@@ -0,0 +1,220 @@
+/**
+ * 名称推断规则。
+ *
+ * 这是语义层的“兜底能力”：
+ * - 如果事件没有显式配置，就尝试按名字模式推断；
+ * - 推断结果优先级低于显式配置；
+ * - 推断只提供“足够好”的默认值，不追求 100% 正确。
+ */
+const INFERENCE_RULES = [
+    {
+        test: /error|fail|exception/i,
+        semantics: {
+            category: "error",
+            action: "error_event",
+            entityType: "project",
+            stateChange: "none",
+            tags: ["explicit_error"],
+        },
+    },
+    {
+        test: /save/i,
+        semantics: {
+            category: "persistence",
+            action: "save",
+            entityType: "project",
+            persistenceStage: "save",
+            stateChange: "commit",
+            tags: ["project_persist"],
+        },
+    },
+    {
+        test: /close|leave|exit/i,
+        semantics: {
+            category: "lifecycle",
+            action: "leave",
+            entityType: "session",
+            lifecycleStage: "leave",
+            stateChange: "none",
+            tags: ["lifecycle_leave"],
+        },
+    },
+    {
+        test: /open|enter/i,
+        semantics: {
+            category: "lifecycle",
+            action: "enter",
+            entityType: "session",
+            lifecycleStage: "enter",
+            stateChange: "none",
+            tags: ["lifecycle_enter"],
+        },
+    },
+    {
+        test: /switch|navigate|jump/i,
+        semantics: {
+            category: "navigation",
+            action: "navigate",
+            entityType: "page",
+            stateChange: "none",
+            tags: ["navigation"],
+        },
+    },
+    {
+        test: /transform|update|replace|delete|add|crop|rotate|move|resize/i,
+        semantics: {
+            category: "mutation",
+            action: "mutate",
+            entityType: "element",
+            stateChange: "possible",
+            tags: ["state_change_candidate"],
+        },
+    },
+];
+const DEFAULT_SEMANTICS = Object.freeze({
+    category: "unknown",
+    action: "unknown",
+    entityType: "unknown",
+    lifecycleStage: null,
+    persistenceStage: null,
+    stateChange: "none",
+    tags: [],
+});
+/**
+ * 规范化显式语义配置，保证规则引擎拿到的字段总是完整可预期的。
+ */
+function normalizeExplicitSemantics(semantics) {
+    return Object.freeze({
+        category: semantics.category || "unknown",
+        action: semantics.action || "unknown",
+        entityType: semantics.entityType || "unknown",
+        lifecycleStage: semantics.lifecycleStage || null,
+        persistenceStage: semantics.persistenceStage || null,
+        stateChange: semantics.stateChange || "none",
+        tags: uniqueArray(Array.isArray(semantics.tags) ? semantics.tags : []),
+    });
+}
+/**
+ * 基于事件名和 payload 做兜底语义推断。
+ *
+ * 推断只在没有显式配置时发挥主要作用，因此宁可保守，也不追求过度“聪明”。
+ */
+function inferEventSemantics(eventName, payload = {}) {
+    for (const rule of INFERENCE_RULES) {
+        if (rule.test.test(eventName)) {
+            return { ...rule.semantics };
+        }
+    }
+    if (payload.elementId || payload.id) {
+        return {
+            category: "workflow",
+            action: "element_related",
+            entityType: "element",
+            stateChange: "none",
+            tags: ["element_context"],
+        };
+    }
+    if (typeof payload.sheetIndex === "number") {
+        return {
+            category: "navigation",
+            action: "page_related",
+            entityType: "page",
+            stateChange: "none",
+            tags: ["page_context"],
+        };
+    }
+    return { ...DEFAULT_SEMANTICS };
+}
+/**
+ * 对数组做去空值去重，常用于 tags 合并。
+ */
+function uniqueArray(items) {
+    return [...new Set(items.filter(Boolean))];
+}
+/**
+ * 创建事件语义解析器，显式语义表由调用方注入。
+ */
+export function createSemanticsResolver(explicitMap) {
+    const explicitEventSemantics = Object.freeze(Object.fromEntries(Object.entries(explicitMap).map(([eventName, semantics]) => [
+        eventName,
+        normalizeExplicitSemantics(semantics),
+    ])));
+    return function resolveEventSemantics(event) {
+        const eventName = typeof event === "string" ? event : event.eventName || "";
+        const payload = typeof event === "string" ? {} : event.payload || {};
+        const inferred = inferEventSemantics(eventName, payload);
+        const hasExplicitSemantics = Boolean(explicitEventSemantics[eventName]);
+        const explicit = explicitEventSemantics[eventName] || {};
+        const resolvedTags = hasExplicitSemantics
+            ? uniqueArray((explicit.tags && explicit.tags.length ? explicit.tags : inferred.tags) || [])
+            : uniqueArray(inferred.tags || []);
+        const merged = {
+            ...DEFAULT_SEMANTICS,
+            ...inferred,
+            ...explicit,
+            tags: resolvedTags,
+            source: {
+                explicit: hasExplicitSemantics,
+                inferred: inferred.category !== "unknown",
+            },
+        };
+        if (payload.message || payload.stack) {
+            merged.tags = uniqueArray([...merged.tags, "error_payload"]);
+            if (merged.category === "unknown") {
+                merged.category = "error";
+                merged.action = "error_payload";
+            }
+        }
+        return merged;
+    };
+}
+/**
+ * 是否属于会改变项目状态的事件。
+ * - definite: 明确会改状态
+ * - possible: 可能会改状态
+ * - commit: 属于保存/持久化，不算“编辑动作”，但在链路判断里很重要
+ */
+export function hasStateChange(semantics, options = {}) {
+    const includePossible = options.includePossible !== false;
+    const includeCommit = options.includeCommit === true;
+    if (semantics.stateChange === "definite") {
+        return true;
+    }
+    if (includePossible && semantics.stateChange === "possible") {
+        return true;
+    }
+    if (includeCommit && semantics.stateChange === "commit") {
+        return true;
+    }
+    return false;
+}
+/** 判断语义是否表示“保存动作”。 */
+export function isSaveEvent(semantics) {
+    return semantics.category === "persistence" && semantics.persistenceStage === "save";
+}
+/** 判断语义是否表示“进入编辑态/页面”。 */
+export function isEnterEvent(semantics) {
+    return semantics.category === "lifecycle" && semantics.lifecycleStage === "enter";
+}
+/** 判断语义是否表示“离开编辑态/页面”。 */
+export function isLeaveEvent(semantics) {
+    return semantics.category === "lifecycle" && semantics.lifecycleStage === "leave";
+}
+/** 判断语义是否属于显式错误类事件。 */
+export function isErrorEvent(semantics) {
+    return semantics.category === "error";
+}
+/** 把状态变更级别转成人类可读中文，供诊断文案复用。 */
+export function describeStateChange(semantics) {
+    if (semantics.stateChange === "definite") {
+        return "明确修改类事件";
+    }
+    if (semantics.stateChange === "possible") {
+        return "可能修改类事件";
+    }
+    if (semantics.stateChange === "commit") {
+        return "持久化事件";
+    }
+    return "非修改类事件";
+}
+//# sourceMappingURL=resolver.js.map

package/dist/semantics/table-loader.d.ts

@@ -0,0 +1,11 @@
+import type { EventSemantics } from "../types.js";
+export type EventSemanticsTable = Record<string, Partial<EventSemantics>>;
+/**
+ * 读一份事件语义表并跑共享校验——所有读表路径的唯一入口（spec §4 消费方 2）。
+ *
+ * required=true 用于工作区模式：工作区表是唯一来源，缺表不回落工具箱种子表，
+ * 静默回落会让诊断读到别的仓库的语义，比报错难查得多。
+ */
+export declare function loadEventSemanticsTable(filePath: string, options?: {
+    required?: boolean;
+}): EventSemanticsTable;

package/dist/semantics/table-loader.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { validateEventSemanticsTable } from "./table-schema.js";
+/**
+ * 读一份事件语义表并跑共享校验——所有读表路径的唯一入口（spec §4 消费方 2）。
+ *
+ * required=true 用于工作区模式：工作区表是唯一来源，缺表不回落工具箱种子表，
+ * 静默回落会让诊断读到别的仓库的语义，比报错难查得多。
+ */
+export function loadEventSemanticsTable(filePath, options = {}) {
+    if (!existsSync(filePath)) {
+        if (options.required) {
+            throw new Error(`错误: 事件语义表 ${filePath} 不存在。\n` +
+                "请在宿主仓库根重新运行 cx-cli init 补齐（工作区模式不回落工具箱种子表）。");
+        }
+        return {};
+    }
+    let text;
+    try {
+        text = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`错误: 无法读取事件语义表 ${filePath}（${reason}）。\n` +
+            "请确认路径是可读 JSON 文件/检查路径权限；工作区文件缺失可在宿主根运行 cx-cli init。");
+    }
+    let table;
+    try {
+        table = JSON.parse(text);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`错误: 事件语义表 ${filePath} 不是合法 JSON（${reason}）。`);
+    }
+    const violations = validateEventSemanticsTable({ text, table });
+    if (violations.length > 0) {
+        throw new Error([
+            `错误: 事件语义表 ${filePath} 未通过校验（${violations.length} 项）：`,
+            ...violations.map(violation => `  - ${violation}`),
+            "规则、空白白名单与大小写登记清单见 packages/core/src/semantics/table-schema.ts。",
+        ].join("\n"));
+    }
+    return table;
+}
+//# sourceMappingURL=table-loader.js.map

package/dist/semantics/table-schema.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 尾/前导空白键白名单（spec §4.2 规则 1）。
+ * 均为宿主真实埋点（02 票源码钉死：埋点管线不 trim、运行时精确匹配），不是维护事故。
+ * 宿主修掉笔误后从这里移除——收缩前须确认无其他宿主的工作区表仍持有该键。
+ */
+export declare const WHITESPACE_KEY_ALLOWLIST: ReadonlyArray<{
+    key: string;
+    evidence: string;
+}>;
+/**
+ * 大小写重复键登记清单（spec §4.2 规则 2）：登记制，不硬禁。
+ * 运行时按事件名精确匹配，三组都是两条真实埋点（camelCase 走 logger.track，
+ * PascalCase 走老的 logEvent.addPageEvent）；未登记的新冲突组一律报错。
+ */
+export declare const CASE_CONFLICT_REGISTRY: ReadonlyArray<ReadonlyArray<string>>;
+/**
+ * 校验一份事件语义表，返回违规文案数组（空数组 = 通过）。
+ * text 是表的原始 JSON 文本：JSON 文本层的完全重复键只有读原文才看得见
+ * （JSON.parse 会静默让后者覆盖前者）。
+ */
+export declare function validateEventSemanticsTable(input: {
+    text: string;
+    table: unknown;
+}): string[];
+/**
+ * 从原始 JSON 文本收集顶层键（含重复）。
+ * 逐字符扫描：字符串字面量整段跳过（避免值里的花括号扰动深度），
+ * 深度为 1 且其后第一个非空白字符是冒号的字符串，即顶层键。
+ */
+export declare function collectTopLevelKeys(text: string): string[];

package/dist/semantics/table-schema.js

@@ -0,0 +1,186 @@
+import { z } from "zod";
+/**
+ * 事件语义表的共享校验（spec 组件 A）。
+ *
+ * 纯函数、不碰文件系统：读表在 table-loader.ts，测试与运行时加载共用这里的规则。
+ * 下面的 zod 枚举与两份清单即权威口径，不另写值域文档。
+ */
+/** 条目 schema：strict object——未知字段名一律报错，防 provenance 之类的字段名笔误混进来。 */
+const entrySchema = z
+    .object({
+    category: z.enum(["lifecycle", "mutation", "navigation", "persistence", "workflow", "error"]),
+    action: z.string().min(1),
+    entityType: z.enum(["project", "session", "page", "element"]),
+    lifecycleStage: z.enum(["enter", "leave"]).optional(),
+    persistenceStage: z.literal("save").optional(),
+    stateChange: z.enum(["none", "possible", "definite", "commit"]),
+    tags: z.array(z.string().min(1)).min(1),
+})
+    .strict()
+    .refine(entry => (entry.category === "lifecycle") === (entry.lifecycleStage !== undefined), {
+    message: "category=lifecycle 与 lifecycleStage 必须同时出现（互为充要）",
+})
+    .refine(entry => (entry.category === "persistence") === (entry.persistenceStage !== undefined), {
+    message: "category=persistence 与 persistenceStage 必须同时出现（互为充要）",
+});
+/**
+ * 尾/前导空白键白名单（spec §4.2 规则 1）。
+ * 均为宿主真实埋点（02 票源码钉死：埋点管线不 trim、运行时精确匹配），不是维护事故。
+ * 宿主修掉笔误后从这里移除——收缩前须确认无其他宿主的工作区表仍持有该键。
+ */
+export const WHITESPACE_KEY_ALLOWLIST = [
+    { key: "addVarnishingText ", evidence: "src:src/apps/photobook/components/OptionalButtonList/index.js#L331" },
+    { key: "addSpineVarnishingText ", evidence: "src:src/apps/photobook/components/OptionalButtonList/index.js#L314" },
+];
+/**
+ * 大小写重复键登记清单（spec §4.2 规则 2）：登记制，不硬禁。
+ * 运行时按事件名精确匹配，三组都是两条真实埋点（camelCase 走 logger.track，
+ * PascalCase 走老的 logEvent.addPageEvent）；未登记的新冲突组一律报错。
+ */
+export const CASE_CONFLICT_REGISTRY = [
+    ["saveProject", "SaveProject"],
+    ["clickCropImage", "ClickCropImage"],
+    ["addVarnishingText", "addVarnishingText "],
+];
+/**
+ * 校验一份事件语义表，返回违规文案数组（空数组 = 通过）。
+ * text 是表的原始 JSON 文本：JSON 文本层的完全重复键只有读原文才看得见
+ * （JSON.parse 会静默让后者覆盖前者）。
+ */
+export function validateEventSemanticsTable(input) {
+    const { text, table } = input;
+    if (typeof table !== "object" || table === null || Array.isArray(table)) {
+        return ["表本身不是 JSON 对象（应为 事件名 → 语义条目 的映射）"];
+    }
+    const entries = table;
+    const violations = [];
+    const conflictViolations = checkCaseConflicts(Object.keys(entries));
+    const seen = new Set();
+    for (const key of collectTopLevelKeys(text)) {
+        if (seen.has(key)) {
+            violations.push(`键 ${JSON.stringify(key)}: JSON 文本层重复出现，JSON.parse 会静默丢弃前一条`);
+            continue;
+        }
+        seen.add(key);
+        if (!Object.prototype.hasOwnProperty.call(entries, key)) {
+            continue;
+        }
+        appendEntryViolations(violations, key, entries[key]);
+        violations.push(...(conflictViolations.get(key) ?? []));
+    }
+    // 若 text 与 table 不一致，仍校验 table 中未出现在原文的键。
+    for (const key of Object.keys(entries)) {
+        if (seen.has(key)) {
+            continue;
+        }
+        appendEntryViolations(violations, key, entries[key]);
+        violations.push(...(conflictViolations.get(key) ?? []));
+    }
+    return violations;
+}
+function appendEntryViolations(violations, key, value) {
+    violations.push(...checkKey(key));
+    const parsed = entrySchema.safeParse(value);
+    if (parsed.success) {
+        return;
+    }
+    for (const issue of parsed.error.issues) {
+        const path = issue.path.length > 0 ? `.${issue.path.join(".")}` : "";
+        violations.push(`键 ${JSON.stringify(key)}${path}: ${issue.message}`);
+    }
+}
+/** 单键的空白/控制字符/归一化规则（spec §4.2 规则 1、3）。 */
+function checkKey(key) {
+    const violations = [];
+    const quoted = JSON.stringify(key);
+    if (/[\t\n\r]/.test(key)) {
+        violations.push(`键 ${quoted}: 含制表符或换行（无例外硬禁）`);
+    }
+    if (/ {2,}/.test(key)) {
+        violations.push(`键 ${quoted}: 含内部连续空格（无例外硬禁）`);
+    }
+    if (key.trim() === "") {
+        violations.push(`键 ${quoted}: 全空白或空键（无例外硬禁）`);
+    }
+    else if (key !== key.trim() && !WHITESPACE_KEY_ALLOWLIST.some(item => item.key === key)) {
+        violations.push(`键 ${quoted}: 含尾部/前导空白且不在白名单内；确属宿主真实埋点请附 src: 证据登记进 WHITESPACE_KEY_ALLOWLIST`);
+    }
+    if (key !== key.normalize("NFC")) {
+        violations.push(`键 ${quoted}: 不是 Unicode NFC 归一化形式（无例外硬禁）`);
+    }
+    return violations;
+}
+/** trim+casefold 冲突组必须在登记清单里逐组登记（spec §4.2 规则 2）。 */
+function checkCaseConflicts(keys) {
+    const groups = new Map();
+    for (const key of keys) {
+        const folded = key.trim().toLowerCase();
+        groups.set(folded, [...(groups.get(folded) ?? []), key]);
+    }
+    const registered = new Set(CASE_CONFLICT_REGISTRY.map(groupId));
+    const violations = new Map();
+    for (const [folded, group] of groups) {
+        if (group.length < 2 || registered.has(groupId(group))) {
+            continue;
+        }
+        const message = `大小写重复键组 [${group.map(key => JSON.stringify(key)).join(", ")}]（trim+casefold 后同为 ${JSON.stringify(folded)}）未登记；` +
+            "确属两条真实埋点请登记进 CASE_CONFLICT_REGISTRY，否则删掉多余的一条";
+        const firstKey = group[0];
+        violations.set(firstKey, [...(violations.get(firstKey) ?? []), message]);
+    }
+    return violations;
+}
+/** 组标识与成员顺序无关。 */
+function groupId(group) {
+    return JSON.stringify([...group].sort());
+}
+/**
+ * 从原始 JSON 文本收集顶层键（含重复）。
+ * 逐字符扫描：字符串字面量整段跳过（避免值里的花括号扰动深度），
+ * 深度为 1 且其后第一个非空白字符是冒号的字符串，即顶层键。
+ */
+export function collectTopLevelKeys(text) {
+    const keys = [];
+    let depth = 0;
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '"') {
+            const { value, next } = readJsonString(text, index);
+            let cursor = next;
+            while (cursor < text.length && /\s/.test(text[cursor])) {
+                cursor += 1;
+            }
+            if (depth === 1 && text[cursor] === ":") {
+                keys.push(value);
+            }
+            index = next;
+            continue;
+        }
+        if (char === "{" || char === "[") {
+            depth += 1;
+        }
+        else if (char === "}" || char === "]") {
+            depth -= 1;
+        }
+        index += 1;
+    }
+    return keys;
+}
+/** 读一段 JSON 字符串字面量：转义感知地找到收尾引号，再交给 JSON.parse 解码。 */
+function readJsonString(text, start) {
+    let index = start + 1;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === "\\") {
+            index += 2;
+            continue;
+        }
+        if (char === '"') {
+            return { value: JSON.parse(text.slice(start, index + 1)), next: index + 1 };
+        }
+        index += 1;
+    }
+    throw new Error("事件语义表 JSON 文本不完整：字符串字面量未闭合");
+}
+//# sourceMappingURL=table-schema.js.map

package/dist/types.d.ts

@@ -0,0 +1,164 @@
+import type { ApmProviderConfig } from "./apm/config.js";
+import type { ApmProviderState } from "./apm/config-state.js";
+/** 归一化后的单条日志事件。 */
+export interface NormalizedEvent {
+    originalIndex: number;
+    eventName: string;
+    logTime: string;
+    logTimestamp: number;
+    /** 服务器接收时间（批次到达时刻）；日志源无该字段时为空串，不回退 log_time。不参与排序。 */
+    receivedTime: string;
+    receivedTimestamp: number;
+    sessionId: string;
+    projectId: string;
+    userId: string;
+    type: string;
+    subType: string;
+    pageUrl: string;
+    route: string;
+    query: Record<string, string>;
+    payload: Record<string, unknown>;
+    device: {
+        osType: string;
+        deviceType: string;
+        host: string;
+        agentVersion: string;
+        terminalId: string;
+    };
+    raw: unknown;
+}
+export interface SessionGroup {
+    sessionId: string;
+    projectId: string;
+    userId: string;
+    startedAt: string;
+    endedAt: string;
+    eventCount: number;
+    events: NormalizedEvent[];
+}
+export interface LogEnvelope {
+    generatedAt: string;
+    sourcePath: string;
+    eventCount: number;
+    sessions: SessionGroup[];
+    events: NormalizedEvent[];
+}
+export type StateChange = "none" | "possible" | "definite" | "commit";
+export interface EventSemantics {
+    category: string;
+    action: string;
+    entityType: string;
+    lifecycleStage: "enter" | "leave" | null;
+    persistenceStage: "save" | null;
+    stateChange: StateChange;
+    tags: string[];
+    source?: {
+        explicit: boolean;
+        inferred: boolean;
+    };
+}
+export type Severity = "high" | "medium" | "low";
+export interface DiagnosticRule {
+    id: string;
+    enabled: boolean;
+    kind: string;
+    description: string;
+    severity: Severity | null;
+    maxGapSeconds: number | null;
+    lookahead: number;
+    includePossibleStateChange: boolean;
+    severityByStateChange: Partial<Record<StateChange, Severity>>;
+    reasonTemplates: {
+        default?: string;
+    };
+}
+export interface SuspiciousSignal {
+    severity: Severity;
+    ruleId: string;
+    type: string;
+    eventName: string;
+    logTime: string;
+    reason: string;
+}
+export interface AnnotatedEvent extends NormalizedEvent {
+    semantics: EventSemantics;
+}
+export interface ProjectPage {
+    id: string | null;
+    type: string | null;
+    path: string;
+    order: number;
+    collectionName: string;
+    collectionIndex: number;
+    width: number | null;
+    height: number | null;
+    elementCount: number;
+    elementTypes: Record<string, number>;
+}
+export interface ProjectElement {
+    lookupKey: string;
+    id: string | null;
+    oriElementId: string | null;
+    type: string;
+    pageId: string | null;
+    pagePath: string;
+    pageOrder: number;
+    pageCollection: string;
+    pageCollectionIndex: number;
+    elementOrder: number;
+    imageRef: string | null;
+    imageName: string | null;
+    geometry: Record<string, unknown>;
+    crop: Record<string, unknown>;
+    meta: Record<string, unknown>;
+}
+export interface NormalizedProject {
+    generatedAt: string;
+    sourcePath: string;
+    projectMeta: Record<string, unknown>;
+    imageCount: number;
+    pageCount: number;
+    elementCount: number;
+    pageCollectionCounts: Record<string, number>;
+    elementTypeCounts: Record<string, number>;
+    pages: ProjectPage[];
+    elements: ProjectElement[];
+    elementIndex: Record<string, ProjectElement>;
+    images: Array<{
+        guid: string | null;
+        encImgId: string | null;
+        name: string | null;
+        width: number | null;
+        height: number | null;
+        uploadTime: string | null;
+    }>;
+}
+/** 运行时源码仓库绑定：id + 绝对路径。三仓由 CLI 的 HOST_SOURCE_BINDINGS 合成，不来自配置文件。 */
+export interface SourceRepoBinding {
+    id: string;
+    path: string;
+}
+export interface ResolvedConfig {
+    configDir: string;
+    runsDir: string;
+    outDir: string;
+    projectHistoryDir: string;
+    logSource: {
+        type: "apm";
+    } | {
+        type: "file";
+        path: string;
+    };
+    apmProvider: ApmProviderConfig | null;
+    /** null 表示已配置；其余三态说明不可用原因与应填写的覆盖文件。 */
+    apmProviderState: ApmProviderState | null;
+    eventSemantics: Record<string, Partial<EventSemantics>>;
+    diagnosticRules: DiagnosticRule[];
+}
+export interface SourceVersion {
+    repoId: string;
+    commit: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+    reachable: boolean;
+}