soloforge 1.2.7 → 1.2.9

package/dist/engine/config_precedence_contract.d.ts

@@ -0,0 +1,269 @@
+import type { FieldClass } from "./zero_config_init.js";
+/** 规范化解析来源 — 用于优先级排序 */
+export type ConfigSource = "user_task" | "cli_flag" | "mcp_param" | "confirmed_config" | "project_policy" | "fingerprint" | "blueprint" | "product_profile" | "knowledge_default" | "global_default";
+/** 证据元数据来源 — 通过 mapEvidenceSource() 映射到规范来源 */
+export type EvidenceMetadataSource = "user_declared" | "confirmed" | "detected";
+export type ConfigLifetime = "single_invocation" | "task" | "project_persistent" | "global";
+export type OverrideDecision = "selected" | "overridden" | "blocked_by_guard" | "stale_warning" | "advisory_only";
+export interface ConfigValueEvidence {
+    field_path: string;
+    value: unknown;
+    source: ConfigSource;
+    confidence: number;
+    evidence_ref?: string;
+    updated_at: string;
+}
+export interface ConfigConflict {
+    source_a: ConfigSource;
+    source_b: ConfigSource;
+    field_path: string;
+    reason: string;
+    requires_human: boolean;
+}
+export interface ConfigResolutionReport {
+    field_path: string;
+    selected: ConfigValueEvidence;
+    candidates: ConfigValueEvidence[];
+    conflicts: ConfigConflict[];
+    overridden_by_guard?: string;
+    lifetime: ConfigLifetime;
+}
+export interface ConfigEvidenceEntry {
+    field_path: string;
+    value_hash: string;
+    source: ConfigSource | EvidenceMetadataSource;
+    confidence: number;
+    evidence_refs: string[];
+    confirmed_by?: string;
+    lifetime: ConfigLifetime;
+    collected_at: string;
+    expires_at?: string;
+}
+export interface ConfigPrecedenceRule {
+    id: string;
+    higher_source: ConfigSource;
+    lower_source: ConfigSource;
+    description: string;
+    override_behavior: OverrideDecision;
+    requires_report: boolean;
+}
+export interface ConfigPrecedenceGovernanceFinding {
+    severity: "hard_fail" | "advisory";
+    rule: string;
+    field_path?: string;
+    message: string;
+}
+/** 上位约束列表 — 这些约束不可被任何配置覆盖 */
+export declare const UPPER_BOUND_GUARDS: readonly ["enforced_guard", "privacy_secret_policy", "contract_state", "command_safety", "delivery_authorization", "data_sovereignty", "destructive_action_gate", "human_sovereignty"];
+export type UpperBoundGuard = (typeof UPPER_BOUND_GUARDS)[number];
+interface StaleRule {
+    id: string;
+    trigger: "config_vs_fingerprint_mismatch" | "config_vs_blueprint_mismatch" | "fingerprint_drift";
+    severity: "warning" | "hard_fail";
+    description: string;
+    action: string;
+}
+/** 列出所有配置优先级规则
+ * @returns 优先级规则数组
+ */
+export declare function listPrecedenceRules(): ConfigPrecedenceRule[];
+/** 列出所有配置过期检测规则
+ * @returns 过期规则数组
+ */
+export declare function listStaleRules(): StaleRule[];
+/** 获取配置来源的优先级排名（数值越小优先级越高）
+ * @param source - 配置来源
+ * @returns 优先级排名索引
+ */
+export declare function getPrecedenceRank(source: ConfigSource): number;
+/** 获取配置来源的生命周期
+ * @param source - 配置来源
+ * @returns 生命周期类型
+ */
+export declare function getSourceLifetime(source: ConfigSource): ConfigLifetime;
+/** 判断来源 a 的优先级是否高于来源 b
+ * @param a - 配置来源 a
+ * @param b - 配置来源 b
+ * @returns a 是否优先级更高
+ */
+export declare function isHigherPriority(a: ConfigSource, b: ConfigSource): boolean;
+/** 解析单个配置字段 — 按优先级排序候选值并检测冲突
+ * @param fieldPath - 字段路径
+ * @param candidates - 候选值列表
+ * @returns 配置解析报告
+ */
+export declare function resolveConfigField(fieldPath: string, candidates: ConfigValueEvidence[]): ConfigResolutionReport;
+/** 解析所有配置字段
+ * @param fieldCandidates - 字段路径到候选值列表的映射
+ * @returns 所有字段的解析报告数组
+ */
+export declare function resolveAllFields(fieldCandidates: Record<string, ConfigValueEvidence[]>): ConfigResolutionReport[];
+export interface GuardCheckResult {
+    blocked: boolean;
+    report: ConfigResolutionReport;
+}
+/** 检查上位约束是否阻止该配置
+ * @param report - 配置解析报告
+ * @param guardId - 上位约束 ID
+ * @returns 约束检查结果
+ */
+export declare function checkGuardOverride(report: ConfigResolutionReport, guardId: UpperBoundGuard): GuardCheckResult;
+/** 检测配置是否过期 — 比较确认值与指纹值是否一致
+ * @param confirmedValue - 已确认的配置值
+ * @param fingerprintValue - 当前指纹值
+ * @returns 是否过期及警告信息
+ */
+export declare function detectStaleConfig(confirmedValue: ConfigValueEvidence, fingerprintValue: ConfigValueEvidence): {
+    isStale: boolean;
+    warning: string;
+};
+/** C 类字段列表 — 仅允许人工确认写入，永不自动写入 */
+export declare const C_CLASS_FIELDS: string[];
+/** 判断字段是否为 C 类字段
+ * @param fieldPath - 字段路径
+ * @returns 是否为 C 类字段
+ */
+export declare function isCClassField(fieldPath: string): boolean;
+/** 获取配置字段的分类（C 类或 B 类）
+ * @param fieldPath - 字段路径
+ * @param explicitClass - 显式指定的分类（可选）
+ * @returns 字段分类
+ */
+export declare function getConfigFieldClass(fieldPath: string, explicitClass?: FieldClass): FieldClass;
+/** 判断字段是否允许自动写入
+ * @param fieldPath - 字段路径
+ * @param fieldClass - 字段分类
+ * @param source - 配置来源
+ * @returns 是否允许及原因
+ */
+export declare function canAutoWriteField(fieldPath: string, fieldClass: FieldClass, source: ConfigSource | string): {
+    allowed: boolean;
+    reason: string;
+};
+/** 将证据元数据来源映射为规范配置来源
+ * @param source - 原始来源标识
+ * @returns 规范配置来源
+ */
+export declare function mapEvidenceSource(source: string): ConfigSource;
+/** 创建配置值证据
+ * @param fieldPath - 字段路径
+ * @param value - 配置值
+ * @param source - 配置来源
+ * @param confidence - 置信度
+ * @param evidenceRef - 证据引用（可选）
+ * @returns 配置值证据
+ */
+export declare function createConfigValueEvidence(fieldPath: string, value: unknown, source: ConfigSource, confidence: number, evidenceRef?: string): ConfigValueEvidence;
+/** 创建配置证据条目
+ * @param fieldPath - 字段路径
+ * @param value - 配置值
+ * @param source - 配置来源
+ * @param options - 可选参数
+ * @param options.confidence - 置信度（可选，默认 1.0）
+ * @param options.evidence_refs - 证据引用列表（可选）
+ * @param options.confirmed_by - 确认者（可选）
+ * @param options.expires_at - 过期时间（可选）
+ * @returns 配置证据条目
+ */
+/**
+ * 创建配置证据条目。
+ * @param field - 配置字段名
+ * @param source - 证据来源
+ * @param value - 字段值
+ * @returns 证据条目
+ */
+export declare function createConfigEvidenceEntry(fieldPath: string, value: unknown, source: ConfigSource, options?: {
+    confidence?: number;
+    evidence_refs?: string[];
+    confirmed_by?: string;
+    expires_at?: string;
+}): ConfigEvidenceEntry;
+/** 计算值的简易哈希
+ * @param value - 待哈希的值
+ * @returns 十六进制哈希字符串
+ */
+export declare function hashValue(value: unknown): string;
+/** 生成配置字段解析结果的中文解释
+ * @param report - 配置解析报告
+ * @returns 格式化的中文解释文本
+ */
+export declare function explainField(report: ConfigResolutionReport): string;
+/** 判断来源是否可安全写入配置（非 CLI/MCP 临时参数）
+ * @param source - 配置来源
+ * @returns 是否可安全写入
+ */
+export declare function isCliWriteSafe(source: ConfigSource): boolean;
+/** 执行配置优先级治理校验
+ * @param reports - 配置解析报告列表
+ * @param entries - 配置证据条目列表
+ * @returns 治理发现列表
+ */
+export declare function validateConfigPrecedence(reports: ConfigResolutionReport[], entries: ConfigEvidenceEntry[]): ConfigPrecedenceGovernanceFinding[];
+/** 生成配置冲突的中文报告
+ * @param report - 配置解析报告
+ * @returns 格式化的冲突报告文本
+ */
+export declare function buildConflictReport(report: ConfigResolutionReport): string;
+export interface ConfigFieldResolution {
+    field_path: string;
+    resolved_value: unknown;
+    source: ConfigSource;
+    stale_warning?: string;
+    conflict_report?: string;
+}
+/**
+ * 逐字段候选来源 — 支持所有 ConfigSource 类型。
+ * 每个键为字段路径，值为候选证据数组。
+ */
+export interface FieldCandidates {
+    [fieldPath: string]: ConfigValueEvidence[];
+}
+/**
+ * 旧版三来源简写 (向后兼容)。
+ */
+export interface LegacyFieldSources {
+    config_value: unknown;
+    fingerprint_value?: unknown;
+    user_override?: unknown;
+}
+/** 从候选来源解析所有配置字段，支持新旧两种格式和冲突检测
+ * @param fields - 字段候选值映射（FieldCandidates 新格式或 LegacyFieldSources 旧格式）
+ * @returns 解析结果、解析报告和警告信息
+ */
+export declare function resolveConfigFromSources(fields: FieldCandidates | Record<string, LegacyFieldSources>): {
+    resolutions: ConfigFieldResolution[];
+    reports: ConfigResolutionReport[];
+    warnings: string[];
+};
+export interface ResolveProjectConfigOptions {
+    /** 来自当前用户任务意图的逐字段覆盖 */
+    user_task_overrides?: Record<string, unknown>;
+    /** 来自 CLI 参数的逐字段覆盖 */
+    cli_overrides?: Record<string, unknown>;
+    /** 来自 MCP 参数的逐字段覆盖 */
+    mcp_overrides?: Record<string, unknown>;
+    /** 除默认集之外需要额外解析的字段 */
+    extra_fields?: string[];
+    /** 指定需要解析的字段 (默认为标准集) */
+    fields?: string[];
+}
+export interface ResolveProjectConfigResult {
+    reports: ConfigResolutionReport[];
+    resolutions: ConfigFieldResolution[];
+    warnings: string[];
+    entries: ConfigEvidenceEntry[];
+}
+/**
+ * 共享函数，解析当前项目配置。
+ * 读取 config.yaml、实时指纹、证据条目，并接受所有候选来源。
+ * expand()、配置解析/解释、校验、状态、治理都必须复用此函数 — 不可重复逻辑。
+ *
+ * 证据条目不是候选值 — 仅用于校验：
+ * 检查来源/生命周期合规性和 value_hash 匹配。
+ *
+ * product_profile: fingerprint 候选仅来自确定性产品证据
+ * (package.json soloforge.product_profile)，不使用技术形态推断。
+ */
+export declare function resolveCurrentProjectConfigReports(projectPath: string, options?: ResolveProjectConfigOptions): Promise<ResolveProjectConfigResult>;
+export {};
+//# sourceMappingURL=config_precedence_contract.d.ts.map

package/dist/engine/config_precedence_contract.d.ts.map

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