spectra-cli 4.1.1

package/dist/panoramic/cache/schemas.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 内容哈希缓存 Zod Schema 定义
+ * 三层 schema：FileHashRecord → ManifestEntry → CacheManifest
+ * 预留 dependencyGraph 字段供 Feature 101（graph-persistence）扩展
+ */
+import { z } from 'zod';
+/** 单个源文件的哈希记录 Schema */
+export declare const FileHashRecordSchema: z.ZodObject<{
+    /** 文件绝对路径 */
+    path: z.ZodString;
+    /** SHA256(filePath + fileContent) */
+    hash: z.ZodString;
+    /** 文件最后修改时间（Unix ms） */
+    mtime: z.ZodNumber;
+    /** 文件字节大小 */
+    size: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    hash: string;
+    size: number;
+    mtime: number;
+}, {
+    path: string;
+    hash: string;
+    size: number;
+    mtime: number;
+}>;
+/** 单个源文件的哈希记录类型 */
+export type FileHashRecord = z.infer<typeof FileHashRecordSchema>;
+/** 单个 generator 的 manifest 条目 Schema */
+export declare const ManifestEntrySchema: z.ZodObject<{
+    /** cache key（SHA256 of generator + context + files） */
+    cacheKey: z.ZodString;
+    /** generator.id */
+    generatorId: z.ZodString;
+    /** 该 generator 输入的源文件列表 */
+    inputFiles: z.ZodArray<z.ZodObject<{
+        /** 文件绝对路径 */
+        path: z.ZodString;
+        /** SHA256(filePath + fileContent) */
+        hash: z.ZodString;
+        /** 文件最后修改时间（Unix ms） */
+        mtime: z.ZodNumber;
+        /** 文件字节大小 */
+        size: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        hash: string;
+        size: number;
+        mtime: number;
+    }, {
+        path: string;
+        hash: string;
+        size: number;
+        mtime: number;
+    }>, "many">;
+    /** 生成的输出文件路径列表（相对于 outputDir） */
+    outputFiles: z.ZodArray<z.ZodString, "many">;
+    /** manifest entry 创建/更新时间（Unix ms） */
+    createdAt: z.ZodNumber;
+    /** 输出内容类型（对应 generator 生成的文档类型） */
+    type: z.ZodOptional<z.ZodString>;
+    /** 预留字段：供 Feature 101（graph-persistence）扩展依赖图 */
+    dependencyGraph: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    cacheKey: string;
+    generatorId: string;
+    inputFiles: {
+        path: string;
+        hash: string;
+        size: number;
+        mtime: number;
+    }[];
+    outputFiles: string[];
+    createdAt: number;
+    type?: string | undefined;
+    dependencyGraph?: unknown;
+}, {
+    cacheKey: string;
+    generatorId: string;
+    inputFiles: {
+        path: string;
+        hash: string;
+        size: number;
+        mtime: number;
+    }[];
+    outputFiles: string[];
+    createdAt: number;
+    type?: string | undefined;
+    dependencyGraph?: unknown;
+}>;
+/** 单个 generator 的 manifest 条目类型 */
+export type ManifestEntry = z.infer<typeof ManifestEntrySchema>;
+/** 缓存 manifest Schema */
+export declare const CacheManifestSchema: z.ZodObject<{
+    /** schema 版本，用于向前兼容校验 */
+    version: z.ZodLiteral<"1">;
+    /** manifest 最后写入时间（Unix ms） */
+    updatedAt: z.ZodNumber;
+    /** cacheKey → ManifestEntry 的映射 */
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** cache key（SHA256 of generator + context + files） */
+        cacheKey: z.ZodString;
+        /** generator.id */
+        generatorId: z.ZodString;
+        /** 该 generator 输入的源文件列表 */
+        inputFiles: z.ZodArray<z.ZodObject<{
+            /** 文件绝对路径 */
+            path: z.ZodString;
+            /** SHA256(filePath + fileContent) */
+            hash: z.ZodString;
+            /** 文件最后修改时间（Unix ms） */
+            mtime: z.ZodNumber;
+            /** 文件字节大小 */
+            size: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }, {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }>, "many">;
+        /** 生成的输出文件路径列表（相对于 outputDir） */
+        outputFiles: z.ZodArray<z.ZodString, "many">;
+        /** manifest entry 创建/更新时间（Unix ms） */
+        createdAt: z.ZodNumber;
+        /** 输出内容类型（对应 generator 生成的文档类型） */
+        type: z.ZodOptional<z.ZodString>;
+        /** 预留字段：供 Feature 101（graph-persistence）扩展依赖图 */
+        dependencyGraph: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        cacheKey: string;
+        generatorId: string;
+        inputFiles: {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }[];
+        outputFiles: string[];
+        createdAt: number;
+        type?: string | undefined;
+        dependencyGraph?: unknown;
+    }, {
+        cacheKey: string;
+        generatorId: string;
+        inputFiles: {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }[];
+        outputFiles: string[];
+        createdAt: number;
+        type?: string | undefined;
+        dependencyGraph?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    entries: Record<string, {
+        cacheKey: string;
+        generatorId: string;
+        inputFiles: {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }[];
+        outputFiles: string[];
+        createdAt: number;
+        type?: string | undefined;
+        dependencyGraph?: unknown;
+    }>;
+    version: "1";
+    updatedAt: number;
+}, {
+    entries: Record<string, {
+        cacheKey: string;
+        generatorId: string;
+        inputFiles: {
+            path: string;
+            hash: string;
+            size: number;
+            mtime: number;
+        }[];
+        outputFiles: string[];
+        createdAt: number;
+        type?: string | undefined;
+        dependencyGraph?: unknown;
+    }>;
+    version: "1";
+    updatedAt: number;
+}>;
+/** 缓存 manifest 类型 */
+export type CacheManifest = z.infer<typeof CacheManifestSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/panoramic/cache/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/panoramic/cache/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,wBAAwB;AACxB,eAAO,MAAM,oBAAoB;IAC/B,aAAa;;IAEb,qCAAqC;;IAErC,wBAAwB;;IAExB,aAAa;;;;;;;;;;;;EAEb,CAAC;AAEH,mBAAmB;AACnB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,wCAAwC;AACxC,eAAO,MAAM,mBAAmB;IAC9B,uDAAuD;;IAEvD,mBAAmB;;IAEnB,2BAA2B;;QAvB3B,aAAa;;QAEb,qCAAqC;;QAErC,wBAAwB;;QAExB,aAAa;;;;;;;;;;;;;IAmBb,iCAAiC;;IAEjC,sCAAsC;;IAEtC,mCAAmC;;IAEnC,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEjD,CAAC;AAEH,mCAAmC;AACnC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,yBAAyB;AACzB,eAAO,MAAM,mBAAmB;IAC9B,yBAAyB;;IAEzB,+BAA+B;;IAE/B,mCAAmC;;QA7BnC,uDAAuD;;QAEvD,mBAAmB;;QAEnB,2BAA2B;;YAvB3B,aAAa;;YAEb,qCAAqC;;YAErC,wBAAwB;;YAExB,aAAa;;;;;;;;;;;;;QAmBb,iCAAiC;;QAEjC,sCAAsC;;QAEtC,mCAAmC;;QAEnC,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBjD,CAAC;AAEH,qBAAqB;AACrB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/panoramic/cache/schemas.js

@@ -0,0 +1,53 @@
+/**
+ * 内容哈希缓存 Zod Schema 定义
+ * 三层 schema：FileHashRecord → ManifestEntry → CacheManifest
+ * 预留 dependencyGraph 字段供 Feature 101（graph-persistence）扩展
+ */
+import { z } from 'zod';
+// ============================================================
+// FileHashRecord — 单个源文件的哈希记录
+// ============================================================
+/** 单个源文件的哈希记录 Schema */
+export const FileHashRecordSchema = z.object({
+    /** 文件绝对路径 */
+    path: z.string(),
+    /** SHA256(filePath + fileContent) */
+    hash: z.string(),
+    /** 文件最后修改时间（Unix ms） */
+    mtime: z.number(),
+    /** 文件字节大小 */
+    size: z.number(),
+});
+// ============================================================
+// ManifestEntry — 单个 generator 的 manifest 条目
+// ============================================================
+/** 单个 generator 的 manifest 条目 Schema */
+export const ManifestEntrySchema = z.object({
+    /** cache key（SHA256 of generator + context + files） */
+    cacheKey: z.string(),
+    /** generator.id */
+    generatorId: z.string(),
+    /** 该 generator 输入的源文件列表 */
+    inputFiles: z.array(FileHashRecordSchema),
+    /** 生成的输出文件路径列表（相对于 outputDir） */
+    outputFiles: z.array(z.string()),
+    /** manifest entry 创建/更新时间（Unix ms） */
+    createdAt: z.number(),
+    /** 输出内容类型（对应 generator 生成的文档类型） */
+    type: z.string().optional(),
+    /** 预留字段：供 Feature 101（graph-persistence）扩展依赖图 */
+    dependencyGraph: z.unknown().optional(),
+});
+// ============================================================
+// CacheManifest — 顶层 manifest 结构
+// ============================================================
+/** 缓存 manifest Schema */
+export const CacheManifestSchema = z.object({
+    /** schema 版本，用于向前兼容校验 */
+    version: z.literal('1'),
+    /** manifest 最后写入时间（Unix ms） */
+    updatedAt: z.number(),
+    /** cacheKey → ManifestEntry 的映射 */
+    entries: z.record(z.string(), ManifestEntrySchema),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/panoramic/cache/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../../src/panoramic/cache/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,8BAA8B;AAC9B,+DAA+D;AAE/D,wBAAwB;AACxB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,aAAa;IACb,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,qCAAqC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,wBAAwB;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,aAAa;IACb,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC,CAAC;AAKH,+DAA+D;AAC/D,6CAA6C;AAC7C,+DAA+D;AAE/D,wCAAwC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,uDAAuD;IACvD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,mBAAmB;IACnB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,2BAA2B;IAC3B,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;IACzC,iCAAiC;IACjC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAChC,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,mCAAmC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,iDAAiD;IACjD,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAKH,+DAA+D;AAC/D,iCAAiC;AACjC,+DAA+D;AAE/D,yBAAyB;AACzB,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,yBAAyB;IACzB,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IACvB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,mCAAmC;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC;CACnD,CAAC,CAAC"}

package/dist/panoramic/cluster-orchestrator.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Cluster Orchestrator — Spectra v4.1.0 MapReduce 统一调度层
+ *
+ * 设计权威：specs/140-spectra-doc-pipeline-quality/research/02-mapreduce-architecture.md §二
+ * 业务范围：specs/140-spectra-doc-pipeline-quality/spec.md (FR-001 ~ FR-002, FR-014)
+ *
+ * 职责边界：
+ * 1. Phase A 聚类策略（community → directory → single fallback chain）
+ * 2. Phase B 并发 Map（maxConcurrency=4，per-call timeout=180s）
+ * 3. Phase C 单次 Reduce（timeout=300s，1 次重试）
+ * 4. FFD 装箱拆分（cluster 超 maxSize=15 或超 tokenBudget 时按 module 大小降序装箱）
+ * 5. 6 个 Telemetry hooks 在正确时机触发
+ * 6. mergeConfidence 程序化打分（high/medium/low）
+ *
+ * 通用性：本模块不写文件、不知道 outputDir。fail-closed 时返回 finalOutput=null + diagnostics，
+ * 由调用方（ADR / narrative / hyperedges pipeline）负责写 `_PIPELINE_FAILED.md` 标记
+ * （沿用 Feature 135 模式，参见 src/panoramic/batch-project-docs.ts）。
+ */
+import { z } from 'zod';
+import type { GraphJSON } from './graph/graph-types.js';
+/** 默认 Map 并发度（避免触发 Anthropic API 429；Q12 决议）*/
+export declare const DEFAULT_MAX_CONCURRENCY = 4;
+/** 默认 Map per-call 超时（180s）*/
+export declare const DEFAULT_PER_CALL_TIMEOUT_MS = 180000;
+/** 默认 Reduce 超时（300s）*/
+export declare const DEFAULT_REDUCE_TIMEOUT_MS = 300000;
+/** 默认 community 聚类 minSize（< minSize 的 input 走 single fallback）*/
+export declare const DEFAULT_COMMUNITY_MIN_SIZE = 3;
+/** 默认 community 聚类 maxSize（Q14 决议：与 100k token budget 匹配）*/
+export declare const DEFAULT_COMMUNITY_MAX_SIZE = 15;
+/** 默认 cluster 总 token 预算（每 Map call input ≤ 100k tokens）*/
+export declare const DEFAULT_TOKEN_BUDGET = 100000;
+/** 默认 sharedHeader 预留 token 额度 */
+export declare const DEFAULT_SHARED_HEADER_BUDGET = 15000;
+export declare const callTelemetrySchema: z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    modelId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    modelId: string;
+}, {
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    modelId: string;
+}>;
+/** 单次 LLM 调用的可观测性元数据 */
+export type CallTelemetry = z.infer<typeof callTelemetrySchema>;
+/**
+ * Community 策略：复用 src/panoramic/community/ 的 Louvain 检测
+ * 调用方需提供 graph 与 input → nodeId 映射；
+ * 可选提供 directoryFallback 在 community 失败时降级为 directory 策略（保留三级 fallback chain）
+ */
+export interface ClusterStrategyCommunity<TInput> {
+    kind: 'community';
+    /** 最小社区节点数；<= 0 视为不过滤（默认 3）*/
+    minSize?: number;
+    /** 最大社区节点数；超过则触发 FFD 装箱拆分（默认 15）*/
+    maxSize?: number;
+    /** Louvain 检测的图（NetworkX node-link 格式）*/
+    graph: GraphJSON;
+    /** TInput → graph nodeId 映射 */
+    getInputId: (input: TInput) => string;
+    /**
+     * 可选：community 失败时启用 directory 降级所需的路径访问器。
+     * 不提供时直接降级到 single（fallback 退化为两级）。
+     */
+    directoryFallback?: {
+        getInputPath: (input: TInput) => string;
+    };
+}
+/** Directory 策略：按 path.dirname 分组 */
+export interface ClusterStrategyDirectory<TInput> {
+    kind: 'directory';
+    /** TInput → 文件路径映射 */
+    getInputPath: (input: TInput) => string;
+}
+/** Single 策略：所有 input 进 1 个 cluster */
+export interface ClusterStrategySingle {
+    kind: 'single';
+}
+export type ClusterStrategy<TInput> = ClusterStrategyCommunity<TInput> | ClusterStrategyDirectory<TInput> | ClusterStrategySingle;
+export interface MapOptions<TInput, TMapOutput> {
+    /**
+     * 单 cluster Map 函数；返回 (TMapOutput, telemetry)。
+     * 可选 `signal` 在超时时被 abort：caller 应将其转发给底层 LLM SDK 调用
+     * （如 `client.messages.create({ ...args, signal })`），以便真正取消 in-flight 请求；
+     * 调用方忽略 signal 时本字段无副作用，但 orchestrator 的 timeout 语义会退化为
+     * "Promise.race 赢得超时但底层调用继续 background 跑"（不影响 dispatch 正确性，
+     * 但会浪费 token 配额）。
+     */
+    fn: (cluster: TInput[], sharedHeader: string, signal?: AbortSignal) => Promise<{
+        output: TMapOutput;
+        telemetry: CallTelemetry;
+    }>;
+    /** 模型选择（仅记录到 telemetry，不影响 dispatch 行为）*/
+    model?: 'sonnet' | 'opus';
+    /** 最大并发度（默认 4）*/
+    maxConcurrency?: number;
+    /** 单次 Map 调用超时 ms（默认 180_000）*/
+    perCallTimeout?: number;
+}
+export interface ReduceOptions<TMapOutput, TReduceOutput> {
+    /**
+     * 单次 Reduce 函数。`signal` 含义同 MapOptions.fn — caller 转发给 SDK 才能真正取消。
+     */
+    fn: (mapOutputs: TMapOutput[], sharedHeader: string, signal?: AbortSignal) => Promise<{
+        output: TReduceOutput;
+        telemetry: CallTelemetry;
+    }>;
+    /** 模型选择（仅记录到 telemetry）*/
+    model?: 'sonnet' | 'opus';
+    /** 单次 Reduce 调用超时 ms（默认 300_000）*/
+    timeout?: number;
+}
+export interface TokenBudgetOptions {
+    /** 每 cluster 总 token 预算（含 sharedHeader）（默认 100_000）*/
+    totalBudget?: number;
+    /** sharedHeader 预留固定额度（默认 15_000）*/
+    sharedHeaderBudget?: number;
+    /**
+     * 计算单 input 的 token 数。默认按 JSON.stringify(input).length / 3.5 粗算。
+     * 调用方可注入更精确的估算（如真实 tokenizer）。
+     */
+    estimateInputTokens?: (input: unknown) => number;
+}
+export interface TelemetryHooks<TInput, TMapOutput, TReduceOutput> {
+    /** 聚类完成后触发，参数为最终 cluster 列表（含 FFD 拆分后）*/
+    onClusterPlanned?: (clusters: TInput[][]) => void;
+    /** 每 cluster Map 开始前触发（idx 从 0 起）*/
+    onMapStart?: (clusterIdx: number, size: number) => void;
+    /** 单 cluster Map 成功后触发 */
+    onMapComplete?: (clusterIdx: number, output: TMapOutput, telemetry: CallTelemetry) => void;
+    /** 单 cluster Map 失败后触发 */
+    onMapFailed?: (clusterIdx: number, error: Error) => void;
+    /** Reduce 开始前触发 */
+    onReduceStart?: (mapOutputCount: number) => void;
+    /** Reduce 成功后触发（重试成功时也只触发一次）*/
+    onReduceComplete?: (output: TReduceOutput, telemetry: CallTelemetry) => void;
+}
+export interface ClusterDispatchOptions<TInput, TMapOutput, TReduceOutput> extends TelemetryHooks<TInput, TMapOutput, TReduceOutput> {
+    /** Phase A 输入项（通常是 module spec 列表）*/
+    inputs: TInput[];
+    /** Phase A 聚类策略 */
+    clusterStrategy: ClusterStrategy<TInput>;
+    /** Phase B shared context — 每个 cluster 都看到的全局信息（避免跨 cluster 依赖丢失）*/
+    sharedHeader: () => Promise<string>;
+    /** Phase B Map 配置 */
+    map: MapOptions<TInput, TMapOutput>;
+    /** Phase C Reduce 配置 */
+    reduce: ReduceOptions<TMapOutput, TReduceOutput>;
+    /** Token 预算配置（控制 FFD 装箱）*/
+    tokenBudget?: TokenBudgetOptions;
+}
+export interface ClusterDispatchDiagnostics {
+    /** 最终 cluster 数（含 FFD 拆分后）*/
+    clusterCount: number;
+    /** 初始聚类策略（含 fallback 后真正生效的）*/
+    appliedStrategy: ClusterStrategy<unknown>['kind'];
+    /** Map 成功 cluster 数 */
+    mapSucceeded: number;
+    /** Map 失败 cluster 数 */
+    mapFailed: number;
+    /** Map 阶段 token 累计 */
+    mapTotalTokens: {
+        input: number;
+        output: number;
+    };
+    /** Reduce 阶段 token 累计（含重试）*/
+    reduceTokens: {
+        input: number;
+        output: number;
+    };
+    /** Reduce 重试次数（0 = 一次成功；1 = 重试 1 次成功；>=1 时 finalOutput=null 表示重试仍失败）*/
+    reduceRetries: number;
+    /** 总耗时 ms（从 dispatch 入口到 reduce 完成或 fail-closed 决策）*/
+    totalDurationMs: number;
+    /** 程序化合并置信度 */
+    mergeConfidence: 'high' | 'medium' | 'low';
+    /** fail-closed 标志（true 时 finalOutput=null）*/
+    failClosed: boolean;
+    /** fail-closed 原因（仅 failClosed=true 时填充）*/
+    failClosedReason?: 'map-below-threshold' | 'reduce-failed' | 'clustering-failed' | 'shared-header-failed';
+    /** FFD 拆分次数（>0 表示有 cluster 因超 budget/maxSize 被拆分）*/
+    clusterSplits: number;
+    /**
+     * 单 input 单独超过 token budget 的数量（FFD 无法装下"巨型模块"）。
+     * 这些 input 仍然出现在某个 bin 中（保留零模块丢失承诺），但 caller 应感知并决定
+     * 是否对其本身做截断或拒绝；orchestrator 不强行删除它们。
+     */
+    oversizedInputs: number;
+}
+export interface ClusterDispatchResult<TReduceOutput> {
+    /** 成功时为 Reduce 输出；fail-closed 时为 null */
+    finalOutput: TReduceOutput | null;
+    diagnostics: ClusterDispatchDiagnostics;
+}
+declare function defaultEstimateTokens(input: unknown): number;
+/**
+ * 在 timeoutMs 内 race 一个由 taskFn 启动的任务；
+ * 超时时 abort 内部 AbortController（taskFn 接收 signal，可转发给 fetch / SDK 真正取消）。
+ *
+ * 限制：JS Promise 模型无 cancellation 原语；如果 taskFn 不消费 signal，
+ * 超时只让本函数返回 reject 但底层 promise 仍在 background 运行（产生 token 浪费）。
+ */
+declare function withTimeoutAndSignal<T>(taskFn: (signal: AbortSignal) => Promise<T>, timeoutMs: number, label: string): Promise<T>;
+/**
+ * 安全调用 telemetry hook：同时处理同步抛错和 async hook 返回的 rejected Promise，
+ * 避免单点观测/上报失败影响 dispatch 主流程（CLAUDE.local.md 守则）。
+ *
+ * 设计：fire-and-forget — hook 不阻塞 dispatch；async rejection 通过 .catch 吞掉 + warn
+ * （否则 Node.js 会抛 unhandledRejection 影响进程稳定性）。
+ *
+ * 类型放宽到 `() => void | Promise<void>` 是因为生产 telemetry/export hook
+ * 通常是异步的（如发送 HTTP 给监控服务）；旧的 `() => void` 类型在 TS 下仍能接受
+ * async callback（async function 隐式返回 Promise<void>），不会编译错。
+ */
+declare function safeInvokeHook(label: string, fn: (() => void | Promise<void>) | undefined): void;
+interface ClusteringResult<TInput> {
+    clusters: TInput[][];
+    /** 实际生效的策略（可能因 fallback 异于请求）*/
+    appliedStrategy: ClusterStrategy<unknown>['kind'];
+}
+/**
+ * 执行聚类策略，依次尝试 community → directory → single fallback chain。
+ * 任何级失败（抛异常 / 产出 0 cluster）均自动降级，不向上抛错。
+ */
+declare function applyClusteringStrategy<TInput>(inputs: TInput[], strategy: ClusterStrategy<TInput>, minSize: number): ClusteringResult<TInput>;
+/** 简单 dirname（避开 Node path 模块的 OS 差异，使用纯字符串处理）*/
+declare function dirname(filePath: string): string;
+/**
+ * First-Fit-Decreasing 装箱拆分：
+ * 当 cluster 模块数 > maxSize 或 cluster token 总和 > tokenBudget 时，
+ * 按 module token 大小降序排序后装入 capacity=tokenBudget 的子 bin，
+ * 不能放入现有 bin 时新建 bin。
+ *
+ * **保证零模块丢失**（与"截断尾部"模式严格区分；架构 §二 与 spec FR-001）。
+ *
+ * 巨型模块边界：当单个 input 的 token 数 > tokenBudget 时（"巨型模块"），
+ * 仍然把它单独放入一个 bin（保持零模块丢失），但通过返回值的 `oversizedCount`
+ * 报告这一情况，由 caller 决定是否对该 input 自身做截断或拒绝。
+ * orchestrator 不强行删除 oversized input，因为这违反"零模块丢失"承诺。
+ *
+ * @returns `{ bins, oversizedCount }`；合规时 bins=[cluster] 且 oversizedCount=0
+ */
+declare function splitClusterByFFD<TInput>(cluster: TInput[], maxSize: number, tokenBudget: number, estimateTokens: (input: unknown) => number): {
+    bins: TInput[][];
+    oversizedCount: number;
+};
+/**
+ * MapReduce 统一调度入口。
+ *
+ * 阶段：
+ *   1. 聚类（Phase A）— 三级 fallback chain
+ *   2. FFD 装箱拆分（Phase A.5）— 超 maxSize/tokenBudget 拆分，零模块丢失
+ *   3. 计算 sharedHeader（一次，传给所有 Map）
+ *   4. Map 并发调度（Phase B）— maxConcurrency=4，per-call timeout=180s
+ *   5. Map < 50% 成功 → fail-closed 不进 Reduce
+ *   6. Reduce + 1 次重试（Phase C）— timeout=300s
+ *   7. 计算 mergeConfidence（high/medium/low）
+ *   8. 触发 6 个 telemetry hooks
+ */
+export declare function clusterDispatch<TInput, TMapOutput, TReduceOutput>(options: ClusterDispatchOptions<TInput, TMapOutput, TReduceOutput>): Promise<ClusterDispatchResult<TReduceOutput>>;
+/** @internal — 仅供单元测试导入；生产代码请使用 clusterDispatch 主入口 */
+export declare const __internal: {
+    splitClusterByFFD: typeof splitClusterByFFD;
+    applyClusteringStrategy: typeof applyClusteringStrategy;
+    defaultEstimateTokens: typeof defaultEstimateTokens;
+    withTimeoutAndSignal: typeof withTimeoutAndSignal;
+    safeInvokeHook: typeof safeInvokeHook;
+    dirname: typeof dirname;
+};
+export {};
+//# sourceMappingURL=cluster-orchestrator.d.ts.map

package/dist/panoramic/cluster-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-orchestrator.d.ts","sourceRoot":"","sources":["../../src/panoramic/cluster-orchestrator.ts"],"names":[],"mappings":"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"}