soloforge 1.2.19 → 1.2.20

package/dist/engine/contract_registry.js

@@ -0,0 +1,1159 @@
+/**
+ * 统一契约注册表 — 将治理对象从 capability 扩展到多 kind contract。
+ *
+ * 问题二十 (Unified Contract Registry) 核心实现:
+ * - 统一登记 workflow、guard、verification、delivery、failure、degradation、
+ *   metric、language_policy 等所有核心契约
+ * - contract_id 作为一等治理身份
+ * - policy_id 到 contract_id 的映射
+ * - 契约状态门控、漂移检测、依赖校验、证据校验
+ * - Runtime hard fail gating
+ *
+ * Capability Registry 保留为能力状态事实源，此表覆盖更广泛的契约类型。
+ */
+import { getCapability } from "./capability_registry.js";
+// ── 内置契约注册表 ──
+const BUILTIN_CONTRACTS = [
+    // ── 1. 工作流契约 ──
+    {
+        contract_id: "workflow_contract",
+        kind: "workflow",
+        name: "工作流契约",
+        state: "enforced",
+        owner_component: "engine/workflow_contract_registry",
+        owner_files: ["src/engine/workflow_contract_registry.ts"],
+        test_files: ["tests/engine/workflow_contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/workflow_contract_registry.test.ts"],
+        knowledge_refs: ["templates/knowledge/rules/工作流契约规则.md"],
+        prompt_refs: [],
+        depends_on: ["route_decision_contract"],
+        consumed_by: ["tool_invocation_contract", "main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 workflow 有集成测试"],
+        demotion_conditions: ["workflow regression check 漏检"],
+        evidence_requirements: ["validateWorkflowContracts 无 hard_fail"],
+        policy_id: "CAP-021",
+        capability_ids: ["workflow_contract"],
+    },
+    // ── 2. 工具调用契约 ──
+    {
+        contract_id: "tool_invocation_contract",
+        kind: "guard",
+        name: "工具调用契约",
+        state: "enforced",
+        owner_component: "engine/tool_invocation_contract_registry",
+        owner_files: ["src/engine/tool_invocation_contract_registry.ts"],
+        test_files: ["tests/engine/tool_invocation_contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/tool_invocation_contract_registry.test.ts"],
+        knowledge_refs: ["templates/knowledge/rules/工具调用规则.md"],
+        prompt_refs: [],
+        depends_on: ["workflow_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 MCP tool 有 invocation test"],
+        demotion_conditions: ["tool invocation regression 漏检"],
+        evidence_requirements: ["validateToolInvocation 无 hard_fail"],
+        policy_id: "CAP-022",
+        capability_ids: ["tool_invocation_contract"],
+    },
+    // ── 3. 机制契约 ──
+    {
+        contract_id: "mechanism_contract",
+        kind: "mechanism_family",
+        name: "机制契约",
+        state: "enforced",
+        owner_component: "engine/mechanism_contract_registry",
+        owner_files: ["src/engine/mechanism_contract_registry.ts"],
+        test_files: ["tests/engine/mechanism_contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/mechanism_contract_registry.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["workflow_contract", "tool_invocation_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 P0 机制有 lifecycle test"],
+        demotion_conditions: ["机制 regression check 漏检"],
+        evidence_requirements: ["validateMechanismContracts 无 hard_fail"],
+    },
+    // ── 4. 产物契约 ──
+    {
+        contract_id: "artifact_contract",
+        kind: "delivery",
+        name: "产物契约",
+        state: "enforced",
+        owner_component: "engine/artifact_contract_registry",
+        owner_files: ["src/engine/artifact_contract_registry.ts"],
+        test_files: ["tests/engine/artifact_contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/artifact_contract_registry.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["workflow_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 artifact kind 有测试"],
+        demotion_conditions: ["artifact regression 漏检"],
+        evidence_requirements: ["validateArtifactContracts 无 hard_fail"],
+    },
+    // ── 5. 输入物料契约 ──
+    {
+        contract_id: "input_material_contract",
+        kind: "verification",
+        name: "输入物料契约",
+        state: "enforced",
+        owner_component: "engine/input_material_contract_registry",
+        owner_files: ["src/engine/input_material_contract_registry.ts"],
+        test_files: ["tests/engine/input_material_contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/input_material_contract_registry.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["privacy_secret_contract"],
+        consumed_by: ["workflow_contract", "main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 material kind 有测试"],
+        demotion_conditions: ["material regression 漏检"],
+        evidence_requirements: ["input material contract 验证通过"],
+    },
+    // ── 6. 命令执行契约 ──
+    {
+        contract_id: "command_execution_contract",
+        kind: "guard",
+        name: "命令执行契约",
+        state: "enforced",
+        owner_component: "engine/command_execution_contract",
+        owner_files: ["src/engine/command_execution_contract.ts"],
+        test_files: ["tests/engine/command_execution_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/command_execution_contract.test.ts"],
+        knowledge_refs: ["templates/knowledge/rules/命令执行规则.md"],
+        prompt_refs: [],
+        depends_on: ["tool_invocation_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["覆盖所有 destructive 命令模式"],
+        demotion_conditions: ["destructive 命令漏检"],
+        evidence_requirements: ["命令分级测试通过"],
+        policy_id: "CAP-025",
+        capability_ids: ["command_execution"],
+    },
+    // ── 7. 隐私/敏感信息契约 ──
+    {
+        contract_id: "privacy_secret_contract",
+        kind: "guard",
+        name: "隐私/敏感信息契约",
+        state: "enforced",
+        owner_component: "engine/privacy_secret_contract",
+        owner_files: ["src/engine/privacy_secret_contract.ts"],
+        test_files: ["tests/engine/privacy_secret_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/privacy_secret_contract.test.ts"],
+        knowledge_refs: ["templates/knowledge/rules/敏感信息处理规则.md"],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["input_material_contract", "main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["覆盖所有 PII 类型"],
+        demotion_conditions: ["secret scanner 产生大量误报"],
+        evidence_requirements: ["RedactionRecord 测试通过"],
+        policy_id: "CAP-024",
+        capability_ids: ["privacy_secret"],
+    },
+    // ── 8. 配置优先级契约 ──
+    {
+        contract_id: "config_precedence_contract",
+        kind: "guard",
+        name: "配置优先级契约",
+        state: "enforced",
+        owner_component: "engine/config_precedence_contract",
+        owner_files: ["src/engine/config_precedence_contract.ts"],
+        test_files: ["tests/engine/config_precedence_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/config_precedence_contract.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有优先级冲突有测试"],
+        demotion_conditions: ["优先级回归漏检"],
+        evidence_requirements: ["validateConfigPrecedence 无 hard_fail"],
+    },
+    // ── 9. 用户反馈契约 ──
+    {
+        contract_id: "user_feedback_contract",
+        kind: "delivery",
+        name: "用户反馈契约",
+        state: "enforced",
+        owner_component: "engine/user_feedback_contract",
+        owner_files: ["src/engine/user_feedback_contract.ts"],
+        test_files: ["tests/engine/user_feedback_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/user_feedback_contract.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有反馈类型有测试"],
+        demotion_conditions: ["反馈回归漏检"],
+        evidence_requirements: ["用户反馈契约验证通过"],
+    },
+    // ── 10. 主链路接入契约 ──
+    {
+        contract_id: "main_path_integration_contract",
+        kind: "verification",
+        name: "主链路接入防孤岛契约",
+        state: "enforced",
+        owner_component: "engine/main_path_integration_contract",
+        owner_files: ["src/engine/main_path_integration_contract.ts"],
+        test_files: ["tests/engine/main_path_integration_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/main_path_integration_contract.test.ts"],
+        knowledge_refs: ["templates/knowledge/rules/防孤岛实现规则.md"],
+        prompt_refs: [],
+        depends_on: [
+            "workflow_contract",
+            "tool_invocation_contract",
+            "mechanism_contract",
+            "artifact_contract",
+        ],
+        consumed_by: ["contract_governance"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 enforced 模块有 entry trace"],
+        demotion_conditions: ["orphan scan 产生大量误报"],
+        evidence_requirements: ["validateMainPathIntegration 无 hard_fail"],
+        policy_id: "CAP-023",
+        capability_ids: ["main_path_integration"],
+    },
+    // ── 11. 路由决策契约 ──
+    {
+        contract_id: "route_decision_contract",
+        kind: "workflow",
+        name: "路由决策契约",
+        state: "enforced",
+        owner_component: "engine/route_decision_contract_verifier",
+        owner_files: ["src/engine/route_decision_contract_verifier.ts"],
+        test_files: ["tests/engine/route_decision_contract.test.ts"],
+        lifecycle_test_files: ["tests/engine/route_decision_contract.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["workflow_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有路由决策有测试"],
+        demotion_conditions: ["路由决策回归漏检"],
+        evidence_requirements: ["verifyRouteDecisionContract 无 hard_fail"],
+    },
+    // ── 12. 契约治理契约（问题二十自治理） ──
+    {
+        contract_id: "contract_governance",
+        kind: "verification",
+        name: "契约治理契约",
+        state: "enforced",
+        owner_component: "engine/contract_registry",
+        owner_files: ["src/engine/contract_registry.ts"],
+        test_files: ["tests/engine/contract_registry.test.ts"],
+        lifecycle_test_files: ["tests/engine/contract_registry.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [
+            "main_path_integration_contract",
+            "workflow_contract",
+            "tool_invocation_contract",
+        ],
+        consumed_by: [],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有核心契约已在 Unified Contract Registry 登记"],
+        demotion_conditions: ["契约治理检查产生大量误报"],
+        evidence_requirements: [
+            "validateContractRegistry 无 hard_fail",
+            "所有核心 contract 已登记",
+            "policy_id 到 contract_id 映射完整",
+        ],
+    },
+    // ── 13. 知识注入契约 ──
+    {
+        contract_id: "knowledge_injection_contract",
+        kind: "knowledge_injection",
+        name: "知识注入契约",
+        state: "advisory",
+        owner_component: "engine/knowledge_injection_boundary",
+        owner_files: ["src/engine/knowledge_injection_boundary.ts"],
+        test_files: ["tests/engine/knowledge_injection_boundary.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["workflow_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["知识注入边界有完整集成测试"],
+        demotion_conditions: ["知识注入产生安全逃逸"],
+        evidence_requirements: ["knowledge injection boundary 测试通过"],
+    },
+    // ── 14. 失败/恢复契约 ──
+    {
+        contract_id: "failure_recovery_contract",
+        kind: "failure",
+        name: "失败/恢复契约",
+        state: "advisory",
+        owner_component: "engine/failure_classifier",
+        owner_files: ["src/engine/failure_classifier.ts"],
+        test_files: ["tests/engine/failure_classifier.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["workflow_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["所有失败分类有恢复策略测试"],
+        demotion_conditions: ["失败恢复逻辑产生误判"],
+        evidence_requirements: ["failure classifier 测试通过"],
+    },
+    // ── 15. 降级契约 ──
+    {
+        contract_id: "degradation_contract",
+        kind: "degradation",
+        name: "降级契约",
+        state: "advisory",
+        owner_component: "engine/runtime_safety",
+        owner_files: ["src/engine/runtime_safety.ts"],
+        test_files: ["tests/engine/runtime_safety.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["failure_recovery_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["降级事件用户可见测试通过"],
+        demotion_conditions: ["降级逻辑产生误判"],
+        evidence_requirements: ["runtime safety 测试通过"],
+    },
+    // ── 16. 指标契约 ──
+    {
+        contract_id: "metric_contract",
+        kind: "metric",
+        name: "指标契约",
+        state: "advisory",
+        owner_component: "engine/observability",
+        owner_files: ["src/engine/observability.ts"],
+        test_files: ["tests/engine/observability.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["所有治理指标有采集和聚合测试"],
+        demotion_conditions: ["指标采集影响性能"],
+        evidence_requirements: ["observability 测试通过"],
+    },
+    // ── 17. 语言策略契约 ──
+    {
+        contract_id: "language_policy_contract",
+        kind: "language_policy",
+        name: "语言策略契约",
+        state: "advisory",
+        owner_component: "engine/core_engineering_principles",
+        owner_files: ["src/engine/core_engineering_principles.ts"],
+        test_files: ["tests/engine/core_engineering_principles.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["中文语义优先覆盖所有用户可见路径"],
+        demotion_conditions: ["语言策略产生误判阻断"],
+        evidence_requirements: ["core engineering principles 测试通过"],
+    },
+    // ── 18. 任务上下文契约 ──
+    {
+        contract_id: "task_context_contract",
+        kind: "task_context",
+        name: "任务上下文契约",
+        state: "enforced",
+        owner_component: "engine/task_context",
+        owner_files: ["src/engine/task_context.ts"],
+        test_files: ["tests/engine/task_context.test.ts"],
+        lifecycle_test_files: ["tests/engine/task_context.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["workflow_contract", "main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["TaskContext 生命周期测试覆盖所有状态转移"],
+        demotion_conditions: ["TaskContext 逃逸（绕过状态机）"],
+        evidence_requirements: ["task_context 生命周期测试通过"],
+        policy_id: "CAP-001",
+        capability_ids: ["task_context_lifecycle"],
+    },
+    // ── 19. 技术决策契约 ──
+    {
+        contract_id: "technology_decision_contract",
+        kind: "technology_decision",
+        name: "技术决策契约",
+        state: "advisory",
+        owner_component: "engine/decision_contract",
+        owner_files: ["src/engine/decision_contract.ts"],
+        test_files: ["tests/engine/decision_contract.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["技术决策字段覆盖所有关键维度"],
+        demotion_conditions: ["决策字段冗余影响可读性"],
+        evidence_requirements: ["decision contract 测试通过"],
+    },
+    // ── 20. 知识演化契约 ──
+    {
+        contract_id: "knowledge_evolution_contract",
+        kind: "knowledge_evolution",
+        name: "知识演化契约",
+        state: "advisory",
+        owner_component: "engine/knowledge_sovereignty",
+        owner_files: ["src/engine/knowledge_sovereignty.ts"],
+        test_files: ["tests/engine/knowledge_sovereignty.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["knowledge_injection_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["知识演化生命周期有完整测试"],
+        demotion_conditions: ["知识演化逻辑产生误判"],
+        evidence_requirements: ["knowledge sovereignty 测试通过"],
+    },
+    // ── 21. 诊断码契约 ──
+    {
+        contract_id: "diagnostic_code_contract",
+        kind: "guard",
+        name: "诊断码契约",
+        state: "enforced",
+        owner_component: "engine/diagnostic_registry",
+        owner_files: ["src/engine/diagnostic_registry.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["contract_governance"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 blocking/critical 事件有诊断码"],
+        demotion_conditions: ["诊断码检查产生大量误报"],
+        evidence_requirements: ["diagnostic registry 测试通过"],
+    },
+    // ── 22. 强制护栏契约 ──
+    {
+        contract_id: "enforcement_guard_contract",
+        kind: "guard",
+        name: "强制护栏契约",
+        state: "enforced",
+        owner_component: "engine/enforcement_guard",
+        owner_files: ["src/engine/enforcement_guard.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["diagnostic_code_contract", "command_execution_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["覆盖七类护栏且有 must-fail 测试"],
+        demotion_conditions: ["护栏阻断产生大量误报"],
+        evidence_requirements: ["enforcement guard 测试通过"],
+    },
+    // ── 23. 验证契约 ──
+    {
+        contract_id: "verification_contract",
+        kind: "verification",
+        name: "验证契约",
+        state: "enforced",
+        owner_component: "engine/verification_contract",
+        owner_files: ["src/engine/verification_contract.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["main_path_integration_contract"],
+        consumed_by: ["delivery_readiness_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["VerificationPlan 与 VerificationEvidence 分离有测试"],
+        demotion_conditions: ["验证契约检查产生大量误报"],
+        evidence_requirements: ["verification contract 测试通过"],
+    },
+    // ── 24. 交付就绪契约 ──
+    {
+        contract_id: "delivery_readiness_contract",
+        kind: "delivery",
+        name: "交付就绪契约",
+        state: "enforced",
+        owner_component: "engine/delivery_readiness",
+        owner_files: ["src/engine/delivery_readiness.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["verification_contract", "enforcement_guard_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["交付许可不触发交付执行有测试"],
+        demotion_conditions: ["交付门控产生大量误报"],
+        evidence_requirements: ["delivery readiness 测试通过"],
+    },
+    // ── 25. 失败报告契约 ──
+    {
+        contract_id: "failure_report_contract",
+        kind: "failure",
+        name: "失败报告契约",
+        state: "enforced",
+        owner_component: "engine/failure_report",
+        owner_files: ["src/engine/failure_report.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["diagnostic_code_contract", "failure_recovery_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["所有 FailureClass 有恢复策略和测试"],
+        demotion_conditions: ["失败分类产生大量误判"],
+        evidence_requirements: ["failure report 测试通过"],
+    },
+    // ── 26. 降级契约 ──
+    {
+        contract_id: "degradation_event_contract",
+        kind: "degradation",
+        name: "降级事件契约",
+        state: "enforced",
+        owner_component: "engine/degradation",
+        owner_files: ["src/engine/degradation.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["diagnostic_code_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["降级事件用户可见有测试"],
+        demotion_conditions: ["降级检查产生大量误报"],
+        evidence_requirements: ["degradation 测试通过"],
+    },
+    // ── 27. 工作区隔离契约 ──
+    {
+        contract_id: "workspace_isolation_contract",
+        kind: "guard",
+        name: "工作区隔离契约",
+        state: "enforced",
+        owner_component: "engine/workspace_lease",
+        owner_files: ["src/engine/workspace_lease.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["diagnostic_code_contract"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: true,
+        promotion_conditions: ["并发冲突检测有测试"],
+        demotion_conditions: ["lease 冲突检测产生大量误报"],
+        evidence_requirements: ["workspace lease 测试通过"],
+    },
+    // ── 28. 测试策略契约 ──
+    {
+        contract_id: "test_strategy_contract",
+        kind: "verification",
+        name: "测试策略契约",
+        state: "advisory",
+        owner_component: "engine/test_strategy",
+        owner_files: ["src/engine/test_strategy.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["contract_governance"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["enforced contract lifecycle test 覆盖完整"],
+        demotion_conditions: ["测试策略检查产生大量误报"],
+        evidence_requirements: ["test strategy 测试通过"],
+    },
+    // ── 29. 机制族映射契约 ──
+    {
+        contract_id: "mechanism_family_contract",
+        kind: "mechanism_family",
+        name: "机制族映射契约",
+        state: "advisory",
+        owner_component: "engine/mechanism_family_registry",
+        owner_files: ["src/engine/mechanism_family_registry.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: ["contract_governance"],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["所有设计机制族有 owner module 和测试"],
+        demotion_conditions: ["机制族映射产生大量误报"],
+        evidence_requirements: ["mechanism family registry 测试通过"],
+    },
+    // ── 30. 语言策略契约 ──
+    {
+        contract_id: "language_policy_contract_entry",
+        kind: "language_policy",
+        name: "语言策略契约",
+        state: "advisory",
+        owner_component: "engine/language_policy_contract",
+        owner_files: ["src/engine/language_policy_contract.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["中文语义覆盖所有用户可见路径"],
+        demotion_conditions: ["语言策略产生误判阻断"],
+        evidence_requirements: ["language policy 测试通过"],
+    },
+    // ── 31. 保留策略契约 ──
+    {
+        contract_id: "retention_policy_contract",
+        kind: "knowledge_evolution",
+        name: "保留策略契约",
+        state: "advisory",
+        owner_component: "engine/retention_policy",
+        owner_files: ["src/engine/retention_policy.ts"],
+        test_files: ["tests/engine/batch2_scenario_matrix.test.ts"],
+        lifecycle_test_files: [],
+        knowledge_refs: [],
+        prompt_refs: [],
+        depends_on: [],
+        consumed_by: ["main_path_integration_contract"],
+        hard_fail_allowed: false,
+        promotion_conditions: ["所有记录类型有保留策略"],
+        demotion_conditions: ["清理策略删除仍被引用的 evidence"],
+        evidence_requirements: ["retention policy 测试通过"],
+    },
+];
+// ── 运行时注册表（允许动态添加，用于测试和扩展） ──
+let runtimeEntries = null;
+function getRegistry() {
+    if (!runtimeEntries) {
+        runtimeEntries = new Map();
+        for (const entry of BUILTIN_CONTRACTS) {
+            runtimeEntries.set(entry.contract_id, cloneEntry(entry));
+        }
+    }
+    return runtimeEntries;
+}
+function cloneEntry(e) {
+    return {
+        ...e,
+        owner_files: [...e.owner_files],
+        test_files: [...e.test_files],
+        lifecycle_test_files: [...e.lifecycle_test_files],
+        knowledge_refs: [...e.knowledge_refs],
+        prompt_refs: [...e.prompt_refs],
+        depends_on: [...e.depends_on],
+        consumed_by: [...e.consumed_by],
+        promotion_conditions: [...e.promotion_conditions],
+        demotion_conditions: [...e.demotion_conditions],
+        evidence_requirements: [...e.evidence_requirements],
+        capability_ids: e.capability_ids ? [...e.capability_ids] : undefined,
+    };
+}
+// ── 查询函数 ──
+/** 获取所有契约条目 */
+export function getAllContracts() {
+    return [...getRegistry().values()].map(cloneEntry);
+}
+/** 按 contract_id 获取 */
+export function getContractById(id) {
+    const entry = getRegistry().get(id);
+    return entry ? cloneEntry(entry) : undefined;
+}
+/** 按 policy_id 查找对应 contract_id */
+export function getContractByPolicyId(policyId) {
+    for (const entry of getRegistry().values()) {
+        if (entry.policy_id === policyId)
+            return cloneEntry(entry);
+    }
+    return undefined;
+}
+/** 按类型列出契约 */
+export function listContractsByKind(kind) {
+    return [...getRegistry().values()]
+        .filter((e) => e.kind === kind)
+        .map(cloneEntry);
+}
+/** 按状态列出契约 */
+export function listContractsByState(state) {
+    return [...getRegistry().values()]
+        .filter((e) => e.state === state)
+        .map(cloneEntry);
+}
+/** 列出所有契约 */
+export function listContracts() {
+    return getAllContracts();
+}
+/** 注册表汇总统计 */
+export function getContractRegistrySummary() {
+    const entries = [...getRegistry().values()];
+    const ALL_KINDS = [
+        "capability", "mechanism_family", "workflow", "guard",
+        "knowledge_injection", "verification", "delivery", "failure",
+        "degradation", "metric", "language_policy", "technology_decision",
+        "task_context", "knowledge_evolution",
+    ];
+    const ALL_STATES = [
+        "draft", "advisory", "enforced", "experimental", "deprecated", "removed",
+    ];
+    const by_kind = Object.fromEntries(ALL_KINDS.map((k) => [k, entries.filter((e) => e.kind === k).length]));
+    const by_state = Object.fromEntries(ALL_STATES.map((s) => [s, entries.filter((e) => e.state === s).length]));
+    const canHardFail = entries.filter((e) => e.hard_fail_allowed && e.state === "enforced");
+    const cannotHardFail = entries.filter((e) => !(e.hard_fail_allowed && e.state === "enforced"));
+    return {
+        total: entries.length,
+        by_kind,
+        by_state,
+        can_hard_fail: canHardFail.map((e) => e.contract_id),
+        cannot_hard_fail: cannotHardFail.map((e) => e.contract_id),
+    };
+}
+// ── Runtime hard fail gating ──
+/**
+ * 判断契约是否允许 hard fail。
+ * 只有 state=enforced 且 hard_fail_allowed=true 的契约才能阻断。
+ */
+export function canContractHardFail(contractId) {
+    const entry = getRegistry().get(contractId);
+    if (!entry)
+        return false;
+    return entry.state === "enforced" && entry.hard_fail_allowed;
+}
+/**
+ * Runtime hard fail gate — 未登记的契约不得 hard fail。
+ * 用于运行时检查 workflow 是否引用了合法的 guard/verification/failure 契约。
+ */
+export function runtimeHardFailGate(contractId, context) {
+    const entry = getRegistry().get(contractId);
+    if (!entry) {
+        return {
+            allowed: false,
+            reason: `契约 ${contractId} 未在 Unified Contract Registry 登记，不得 hard fail`,
+        };
+    }
+    if (entry.state === "removed") {
+        return {
+            allowed: false,
+            reason: `契约 ${contractId} 已移除，${context} 不得引用已移除契约`,
+        };
+    }
+    if (entry.state === "deprecated") {
+        if (entry.replacement_contract_id) {
+            return {
+                allowed: false,
+                reason: `契约 ${contractId} 已废弃，替代契约: ${entry.replacement_contract_id}，请迁移到替代契约`,
+            };
+        }
+        if (entry.migration_note) {
+            return {
+                allowed: false,
+                reason: `契约 ${contractId} 已废弃，迁移说明: ${entry.migration_note}`,
+            };
+        }
+        return {
+            allowed: false,
+            reason: `契约 ${contractId} 已废弃且无替代/迁移说明，${context} 不得引用`,
+        };
+    }
+    if (entry.state === "advisory" || entry.state === "experimental" || entry.state === "draft") {
+        return {
+            allowed: false,
+            reason: `契约 ${contractId} 状态为 ${entry.state}，advisory/experimental/draft 契约只能 warning/advisory，不能阻断主流程`,
+        };
+    }
+    if (entry.state === "enforced" && !entry.hard_fail_allowed) {
+        return {
+            allowed: false,
+            reason: `契约 ${contractId} enforced 但 hard_fail_allowed=false，不得阻断`,
+        };
+    }
+    if (entry.state === "enforced" && entry.hard_fail_allowed) {
+        return { allowed: true, reason: "契约已强制登记且允许 hard fail" };
+    }
+    return { allowed: false, reason: `契约 ${contractId} 状态为 ${entry.state}，不允许 hard fail` };
+}
+// ── 契约治理内核 ──
+/**
+ * 验证契约注册表完整性。
+ * 检查: 唯一性、字段完整性、文件存在、状态约束、依赖存在性、capability 冲突等。
+ */
+export function validateContractRegistry(existingFiles) {
+    const findings = [];
+    const entries = [...getRegistry().values()];
+    const idSet = new Set();
+    for (const entry of entries) {
+        // 1. contract_id 唯一且非空
+        if (!entry.contract_id || entry.contract_id.trim() === "") {
+            findings.push({
+                contract_id: entry.contract_id || "",
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "contract_id_nonempty",
+                message_zh: "contract_id 不能为空",
+                evidence_refs: [],
+            });
+            continue;
+        }
+        if (idSet.has(entry.contract_id)) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "contract_id_unique",
+                message_zh: `contract_id ${entry.contract_id} 重复`,
+                evidence_refs: [],
+            });
+        }
+        idSet.add(entry.contract_id);
+        // 2. kind/state/owner/test 字段完整
+        if (!entry.kind) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "kind_required",
+                message_zh: `契约 ${entry.contract_id} 缺少 kind`,
+                evidence_refs: [],
+            });
+        }
+        if (!entry.state) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "state_required",
+                message_zh: `契约 ${entry.contract_id} 缺少 state`,
+                evidence_refs: [],
+            });
+        }
+        if (!entry.owner_component) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "owner_required",
+                message_zh: `契约 ${entry.contract_id} 缺少 owner_component`,
+                evidence_refs: [],
+            });
+        }
+        if (entry.test_files.length === 0) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "test_files_required",
+                message_zh: `契约 ${entry.contract_id} 无测试文件，所有核心契约必须有测试`,
+                evidence_refs: [],
+            });
+        }
+        // 3. owner_files/test_files 存在性（当 existingFiles 提供时）
+        if (existingFiles) {
+            const isEnforcedOrHardFail = entry.state === "enforced" || entry.hard_fail_allowed;
+            for (const f of entry.owner_files) {
+                if (!existingFiles.has(f)) {
+                    findings.push({
+                        contract_id: entry.contract_id,
+                        kind: entry.kind,
+                        severity: isEnforcedOrHardFail ? "hard_fail" : "warning",
+                        rule: "owner_file_exists",
+                        message_zh: `契约 ${entry.contract_id} 的 owner_file ${f} 不存在${isEnforcedOrHardFail ? "（enforced/hard_fail 契约必须存在）" : ""}`,
+                        evidence_refs: [f],
+                    });
+                }
+            }
+            for (const f of entry.test_files) {
+                if (!existingFiles.has(f)) {
+                    findings.push({
+                        contract_id: entry.contract_id,
+                        kind: entry.kind,
+                        severity: isEnforcedOrHardFail ? "hard_fail" : "warning",
+                        rule: "test_file_exists",
+                        message_zh: `契约 ${entry.contract_id} 的 test_file ${f} 不存在${isEnforcedOrHardFail ? "（enforced/hard_fail 契约必须存在）" : ""}`,
+                        evidence_refs: [f],
+                    });
+                }
+            }
+            for (const f of entry.lifecycle_test_files) {
+                if (!existingFiles.has(f)) {
+                    findings.push({
+                        contract_id: entry.contract_id,
+                        kind: entry.kind,
+                        severity: "hard_fail",
+                        rule: "lifecycle_test_file_exists",
+                        message_zh: `契约 ${entry.contract_id} 的 lifecycle_test_file ${f} 不存在`,
+                        evidence_refs: [f],
+                    });
+                }
+            }
+        }
+        // 4. hard_fail_allowed=true 必须 state=enforced 且 lifecycle_test_files 非空
+        if (entry.hard_fail_allowed) {
+            if (entry.state !== "enforced") {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "hard_fail_requires_enforced",
+                    message_zh: `契约 ${entry.contract_id} 的 hard_fail_allowed=true 但 state=${entry.state}，只有 enforced 契约允许 hard fail`,
+                    evidence_refs: [],
+                });
+            }
+            if (entry.lifecycle_test_files.length === 0) {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "hard_fail_requires_lifecycle_tests",
+                    message_zh: `契约 ${entry.contract_id} 的 hard_fail_allowed=true 但无 lifecycle_test_files`,
+                    evidence_refs: [],
+                });
+            }
+        }
+        // 5. advisory/experimental/draft 不得 hard_fail_allowed
+        if ((entry.state === "advisory" ||
+            entry.state === "experimental" ||
+            entry.state === "draft") &&
+            entry.hard_fail_allowed) {
+            findings.push({
+                contract_id: entry.contract_id,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "non_enforced_no_hard_fail",
+                message_zh: `契约 ${entry.contract_id} 的 state=${entry.state}，advisory/experimental/draft 契约不得 hard_fail_allowed=true`,
+                evidence_refs: [],
+            });
+        }
+        // 6. deprecated 必须有 replacement_contract_id 或 migration_note
+        if (entry.state === "deprecated") {
+            if (!entry.replacement_contract_id && !entry.migration_note) {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "deprecated_requires_replacement",
+                    message_zh: `契约 ${entry.contract_id} 已废弃但无 replacement_contract_id 或 migration_note`,
+                    evidence_refs: [],
+                });
+            }
+        }
+        // 7. removed 不得被 workflow/prompt/consumed_by 主链路引用
+        if (entry.state === "removed") {
+            if (entry.consumed_by.length > 0) {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "removed_not_referenced",
+                    message_zh: `已移除契约 ${entry.contract_id} 仍被 consumed_by 引用: ${entry.consumed_by.join(", ")}`,
+                    evidence_refs: entry.consumed_by,
+                });
+            }
+            if (entry.prompt_refs.length > 0) {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "removed_no_prompt_refs",
+                    message_zh: `已移除契约 ${entry.contract_id} 仍被 prompt 引用: ${entry.prompt_refs.join(", ")}`,
+                    evidence_refs: entry.prompt_refs,
+                });
+            }
+        }
+        // 8. depends_on 指向的契约必须存在
+        for (const depId of entry.depends_on) {
+            if (!getRegistry().has(depId)) {
+                findings.push({
+                    contract_id: entry.contract_id,
+                    kind: entry.kind,
+                    severity: "hard_fail",
+                    rule: "dependency_exists",
+                    message_zh: `契约 ${entry.contract_id} 依赖不存在的契约 ${depId}`,
+                    evidence_refs: [depId],
+                });
+            }
+            else {
+                const dep = getRegistry().get(depId);
+                // 8a. 依赖不得指向 removed
+                if (dep.state === "removed") {
+                    findings.push({
+                        contract_id: entry.contract_id,
+                        kind: entry.kind,
+                        severity: "hard_fail",
+                        rule: "dependency_not_removed",
+                        message_zh: `契约 ${entry.contract_id} 依赖已移除的契约 ${depId}`,
+                        evidence_refs: [depId],
+                    });
+                }
+                // 8b. 指向 deprecated 必须有 migration note 或 replacement
+                if (dep.state === "deprecated" && !dep.replacement_contract_id && !dep.migration_note) {
+                    findings.push({
+                        contract_id: entry.contract_id,
+                        kind: entry.kind,
+                        severity: "warning",
+                        rule: "dependency_deprecated_migration",
+                        message_zh: `契约 ${entry.contract_id} 依赖已废弃的契约 ${depId}，该废弃契约无替代或迁移说明`,
+                        evidence_refs: [depId],
+                    });
+                }
+            }
+        }
+        // 9. capability state 与 contract state 冲突检查
+        if (entry.policy_id && entry.capability_ids && entry.capability_ids.length > 0) {
+            for (const capId of entry.capability_ids) {
+                const cap = getCapability(capId);
+                if (cap) {
+                    const conflict = checkCapabilityContractConflict(cap.state, entry.state, capId, entry.contract_id);
+                    if (conflict) {
+                        findings.push(conflict);
+                    }
+                }
+            }
+        }
+    }
+    return findings;
+}
+/**
+ * 检查 capability state 与 contract state 冲突。
+ * capability enforced 但对应 contract advisory/removed 必须报告。
+ */
+function checkCapabilityContractConflict(capState, contractState, capId, contractId) {
+    // capability enforced 但 contract advisory/removed/draft — 冲突
+    if (capState === "enforced" &&
+        (contractState === "advisory" ||
+            contractState === "removed" ||
+            contractState === "draft")) {
+        return {
+            contract_id: contractId,
+            kind: "capability",
+            severity: "hard_fail",
+            rule: "capability_contract_state_conflict",
+            message_zh: `能力 ${capId} 状态为 enforced，但对应契约 ${contractId} 状态为 ${contractState}，存在冲突`,
+            evidence_refs: [capId, contractId],
+        };
+    }
+    // capability advisory 但 contract enforced — 冲突（反向）
+    if (capState === "advisory" && contractState === "enforced") {
+        return {
+            contract_id: contractId,
+            kind: "capability",
+            severity: "warning",
+            rule: "capability_contract_state_conflict",
+            message_zh: `能力 ${capId} 状态为 advisory，但对应契约 ${contractId} 状态为 enforced，可能需要同步`,
+            evidence_refs: [capId, contractId],
+        };
+    }
+    return null;
+}
+/**
+ * 验证 workflow 引用的契约是否合法。
+ * workflow 引用不存在、removed 或非法 deprecated contract 必须 blocked。
+ */
+export function validateWorkflowContractRefs(workflowId, referencedContractIds) {
+    const findings = [];
+    for (const refId of referencedContractIds) {
+        const entry = getRegistry().get(refId);
+        if (!entry) {
+            findings.push({
+                contract_id: refId,
+                kind: "workflow",
+                severity: "hard_fail",
+                rule: "workflow_ref_exists",
+                message_zh: `工作流 ${workflowId} 引用不存在的契约 ${refId}`,
+                evidence_refs: [workflowId, refId],
+            });
+            continue;
+        }
+        if (entry.state === "removed") {
+            findings.push({
+                contract_id: refId,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "workflow_ref_not_removed",
+                message_zh: `工作流 ${workflowId} 引用已移除的契约 ${refId}`,
+                evidence_refs: [workflowId, refId],
+            });
+        }
+        // deprecated 一律 hard_fail/blocked；有 replacement 提示迁移
+        if (entry.state === "deprecated") {
+            const hint = entry.replacement_contract_id
+                ? `，替代契约: ${entry.replacement_contract_id}`
+                : entry.migration_note
+                    ? `，迁移说明: ${entry.migration_note}`
+                    : "，无替代或迁移说明";
+            findings.push({
+                contract_id: refId,
+                kind: entry.kind,
+                severity: "hard_fail",
+                rule: "workflow_ref_deprecated_blocked",
+                message_zh: `工作流 ${workflowId} 引用已废弃的契约 ${refId}${hint}`,
+                evidence_refs: [workflowId, refId],
+            });
+        }
+        // advisory/experimental 只能 warning，不能阻断
+        if (entry.state === "advisory" || entry.state === "experimental" || entry.state === "draft") {
+            findings.push({
+                contract_id: refId,
+                kind: entry.kind,
+                severity: "advisory",
+                rule: "workflow_ref_advisory_only",
+                message_zh: `工作流 ${workflowId} 引用的契约 ${refId} 状态为 ${entry.state}，只能 advisory，不能阻断主流程`,
+                evidence_refs: [workflowId, refId],
+            });
+        }
+    }
+    return findings;
+}
+// ── 动态注册（用于测试和扩展） ──
+/** 注册新契约（运行时） */
+export function registerContract(entry) {
+    const registry = getRegistry();
+    if (registry.has(entry.contract_id)) {
+        return { success: false, error: `contract_id ${entry.contract_id} 已存在` };
+    }
+    registry.set(entry.contract_id, cloneEntry(entry));
+    return { success: true };
+}
+/**
+ * 内部 helper: 只允许通过 ContractStateStore.apply 调用。
+ * 此函数不导出。ContractStateStore 通过 createContractStateApplier 获取闭包引用。
+ */
+function applyContractStateOverride(override) {
+    const registry = getRegistry();
+    const entry = registry.get(override.contract_id);
+    if (!entry)
+        return;
+    const updated = cloneEntry(entry);
+    updated.state = override.new_state;
+    if (override.replacement_contract_id) {
+        updated.replacement_contract_id = override.replacement_contract_id;
+    }
+    if (override.migration_note) {
+        updated.migration_note = override.migration_note;
+    }
+    registry.set(override.contract_id, updated);
+}
+/** 工厂函数: 返回 applyContractStateOverride 闭包引用，仅供 ContractStateStore 使用 */
+export function createContractStateApplier() {
+    return applyContractStateOverride;
+}
+/** 重置运行时注册表为内置契约（用于测试清理） */
+export function resetRegistry() {
+    runtimeEntries = null;
+}
+/** 获取所有 policy_id → contract_id 映射 */
+export function getPolicyToContractMapping() {
+    const result = [];
+    for (const entry of getRegistry().values()) {
+        if (entry.policy_id) {
+            result.push({ policy_id: entry.policy_id, contract_id: entry.contract_id });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=contract_registry.js.map