eduevidence 6.0.0 → 6.2.0

package/schemas/evidence.schema.json

@@ -5,77 +5,350 @@
   "description": "Claim-level evidence object. MANDATORY fields (schema v1.1): evidence_id, source_id, study_id, sample_id, claim_id, claim, outcome_type, relation_to_claim, effect_direction, source_location. Missing any mandatory field marks the object as UNSUPPORTED. 三种方向语义严格分开：relation_to_claim（支持/反驳某条 claim）、effect_direction（研究观察到的效应方向）、decision_relation（对最终教学决策的意义）。direction 为旧契约字段，仅向后兼容，已废弃（deprecated）。扩展字段一律放在 extensions 内。",
   "type": "object",
   "additionalProperties": false,
-  "required": ["evidence_id", "source_id", "study_id", "sample_id", "claim_id", "claim", "outcome_type", "relation_to_claim", "effect_direction", "source_location"],
+  "required": [
+    "evidence_id",
+    "source_id",
+    "study_id",
+    "sample_id",
+    "claim_id",
+    "claim",
+    "outcome_type",
+    "relation_to_claim",
+    "effect_direction",
+    "source_location"
+  ],
   "properties": {
-    "evidence_id": { "type": "string", "examples": ["E-001"] },
-    "source_id": { "type": "string", "examples": ["S-2023-kazemitabaar"] },
-    "study_id": { "type": "string", "description": "所属研究的稳定标识，用于独立研究计数（独立于 evidence_id，防止同一研究的多条 Evidence Object 重复放大信心）。" },
-    "sample_id": { "type": "string", "description": "所属样本的稳定标识，用于独立样本计数。无法区分样本时可显式使用 UNKNOWN-SAMPLE-<study_id>，但不能静默缺失。" },
-    "claim_id": { "type": "string", "description": "该证据所绑定 Claim 的稳定标识（Claim Registry 一等字段，Claim -> Evidence -> Source 不再依赖渲染阶段临时编号）。", "examples": ["C-003"] },
-    "title": { "type": "string" },
-    "year": { "type": ["integer", "null"] },
+    "evidence_id": {
+      "type": "string",
+      "examples": [
+        "E-001"
+      ]
+    },
+    "source_id": {
+      "type": "string",
+      "examples": [
+        "S-2023-kazemitabaar"
+      ]
+    },
+    "study_id": {
+      "type": "string",
+      "description": "所属研究的稳定标识，用于独立研究计数（独立于 evidence_id，防止同一研究的多条 Evidence Object 重复放大信心）。"
+    },
+    "sample_id": {
+      "type": "string",
+      "description": "所属样本的稳定标识，用于独立样本计数。无法区分样本时可显式使用 UNKNOWN-SAMPLE-<study_id>，但不能静默缺失。"
+    },
+    "claim_id": {
+      "type": "string",
+      "description": "该证据所绑定 Claim 的稳定标识（Claim Registry 一等字段，Claim -> Evidence -> Source 不再依赖渲染阶段临时编号）。",
+      "examples": [
+        "C-003"
+      ]
+    },
+    "title": {
+      "type": "string"
+    },
+    "year": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
     "study_type": {
       "type": "string",
-      "enum": ["rct", "quasi_experimental", "observational", "survey", "qualitative", "meta_analysis", "literature_review", "case_study", "mixed_methods"]
+      "enum": [
+        "rct",
+        "quasi_experimental",
+        "observational",
+        "survey",
+        "qualitative",
+        "meta_analysis",
+        "literature_review",
+        "case_study",
+        "mixed_methods"
+      ]
+    },
+    "education_level": {
+      "type": "string",
+      "examples": [
+        "undergraduate",
+        "k12",
+        "graduate"
+      ]
+    },
+    "subject": {
+      "type": "string",
+      "examples": [
+        "programming",
+        "mathematics",
+        "writing"
+      ]
+    },
+    "population": {
+      "type": "string",
+      "examples": [
+        "first_year_CS_students"
+      ]
+    },
+    "sample_size": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "minimum": 0
+    },
+    "intervention": {
+      "type": "string",
+      "examples": [
+        "copilot_allowed_in_lab"
+      ]
+    },
+    "comparison": {
+      "type": "string",
+      "examples": [
+        "no_ai_control_group"
+      ]
     },
-    "education_level": { "type": "string", "examples": ["undergraduate", "k12", "graduate"] },
-    "subject": { "type": "string", "examples": ["programming", "mathematics", "writing"] },
-    "population": { "type": "string", "examples": ["first_year_CS_students"] },
-    "sample_size": { "type": ["integer", "null"], "minimum": 0 },
-    "intervention": { "type": "string", "examples": ["copilot_allowed_in_lab"] },
-    "comparison": { "type": "string", "examples": ["no_ai_control_group"] },
     "outcome_type": {
       "type": "string",
       "enum": [
-        "knowledge_gain", "concept_understanding", "retention", "transfer",
-        "independent_problem_solving", "completion_time", "accuracy",
-        "code_quality", "assignment_score", "engagement", "motivation",
-        "cognitive_load", "help_seeking", "metacognition", "ai_dependency",
-        "over_reliance", "reduced_effort", "reduced_transfer",
-        "academic_integrity_risk", "false_confidence"
+        "knowledge_gain",
+        "concept_understanding",
+        "retention",
+        "transfer",
+        "independent_problem_solving",
+        "completion_time",
+        "accuracy",
+        "code_quality",
+        "assignment_score",
+        "engagement",
+        "motivation",
+        "cognitive_load",
+        "help_seeking",
+        "metacognition",
+        "ai_dependency",
+        "over_reliance",
+        "reduced_effort",
+        "reduced_transfer",
+        "academic_integrity_risk",
+        "false_confidence",
+        "policy_effectiveness",
+        "cost_effectiveness",
+        "equity",
+        "feasibility",
+        "implementation_risk"
+      ],
+      "description": "Outcome Taxonomy token, as registered in domains/<id>/outcome_taxonomy.json. Education registers the first 20 tokens (learning / task_performance / process / risk categories); policy registers the remaining 5 (effectiveness / cost / equity / feasibility / risk). The registry is the authority - scripts/check_protocol_alignment.py fails if this enum and the registry disagree."
+    },
+    "outcome_measure": {
+      "type": "string",
+      "examples": [
+        "final_exam_score",
+        "post_test_transfer_task"
+      ]
+    },
+    "claim": {
+      "type": "string",
+      "description": "The specific claim this evidence supports or contradicts."
+    },
+    "direction": {
+      "type": "string",
+      "enum": [
+        "support",
+        "contradict",
+        "neutral"
+      ],
+      "description": "DEPRECATED: legacy direction field, kept for backward compatibility only. Use relation_to_claim instead."
+    },
+    "relation_to_claim": {
+      "type": "string",
+      "enum": [
+        "support",
+        "contradict",
+        "neutral"
+      ],
+      "description": "该证据与 claim 的关系（支持/反驳/中性）。Claim Audit 只依据此字段判断支持/反驳，不得用 effect_direction 或 legacy direction 替代。"
+    },
+    "effect_direction": {
+      "type": "string",
+      "enum": [
+        "positive",
+        "negative",
+        "null"
+      ],
+      "description": "研究观察到的效应方向。Outcome 可视化 / 聚合只依据此字段。"
+    },
+    "decision_relation": {
+      "type": "string",
+      "enum": [
+        "support_adoption",
+        "oppose_adoption",
+        "conditional",
+        "neutral"
+      ],
+      "description": "该证据对最终教学决策的意义（支持采纳/反对采纳/有条件采纳/中性）。跨研究一致性（Consistency）与 Tribunal 依据此字段计算。"
+    },
+    "effect": {
+      "type": "string",
+      "examples": [
+        "positive_medium",
+        "null",
+        "negative_small"
+      ]
+    },
+    "duration": {
+      "type": "string",
+      "examples": [
+        "8_weeks"
       ]
     },
-    "outcome_measure": { "type": "string", "examples": ["final_exam_score", "post_test_transfer_task"] },
-    "claim": { "type": "string", "description": "The specific claim this evidence supports or contradicts." },
-    "direction": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "DEPRECATED: legacy direction field, kept for backward compatibility only. Use relation_to_claim instead." },
-    "relation_to_claim": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "该证据与 claim 的关系（支持/反驳/中性）。Claim Audit 只依据此字段判断支持/反驳，不得用 effect_direction 或 legacy direction 替代。" },
-    "effect_direction": { "type": "string", "enum": ["positive", "negative", "null"], "description": "研究观察到的效应方向。Outcome 可视化 / 聚合只依据此字段。" },
-    "decision_relation": { "type": "string", "enum": ["support_adoption", "oppose_adoption", "conditional", "neutral"], "description": "该证据对最终教学决策的意义（支持采纳/反对采纳/有条件采纳/中性）。跨研究一致性（Consistency）与 Tribunal 依据此字段计算。" },
-    "effect": { "type": "string", "examples": ["positive_medium", "null", "negative_small"] },
-    "duration": { "type": "string", "examples": ["8_weeks"] },
-    "method": { "type": "string", "examples": ["quasi_experimental_pre_post"] },
-    "strengths": { "type": "array", "items": { "type": "string" } },
-    "limitations": { "type": "array", "items": { "type": "string" } },
-    "confounders": { "type": "array", "items": { "type": "string" } },
-    "source_location": { "type": "string", "description": "Verifiable pointer to the source (DOI / URL / database identifier / page)." },
+    "method": {
+      "type": "string",
+      "examples": [
+        "quasi_experimental_pre_post"
+      ]
+    },
+    "strengths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "confounders": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "source_location": {
+      "type": "string",
+      "description": "Verifiable pointer to the source (DOI / URL / database identifier / page)."
+    },
     "quality_dimensions": {
       "type": "object",
       "additionalProperties": true,
       "description": "D1 Study Design, D2 Sample Quality, D3 Measurement Validity, D4 Temporal Strength, D5 Directness. Each scored 0/1/2.",
       "properties": {
-        "D1_study_design": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D2_sample_quality": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D3_measurement_validity": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D4_temporal_strength": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D5_directness": { "type": "integer", "minimum": 0, "maximum": 2 }
+        "D1_study_design": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D2_sample_quality": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D3_measurement_validity": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D4_temporal_strength": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D5_directness": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        }
       }
     },
-    "quality_score": { "type": ["number", "null"], "minimum": 0, "maximum": 10 },
+    "quality_score": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0,
+      "maximum": 10
+    },
     "evidence_level": {
       "type": "string",
-      "enum": ["strong", "moderate", "weak", "very_weak"]
+      "enum": [
+        "strong",
+        "moderate",
+        "weak",
+        "very_weak"
+      ]
     },
     "applicability": {
       "type": "object",
       "additionalProperties": true,
       "description": "Match against the target context: learner match, subject match, tool match, usage match, teacher support match."
     },
-    "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
-    "status": { "type": "string", "enum": ["SUPPORTED", "UNSUPPORTED", "DOWNGRADE_CONFIDENCE", "CONTRADICT"], "default": "SUPPORTED" },
+    "confidence": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "SUPPORTED",
+        "UNSUPPORTED",
+        "DOWNGRADE_CONFIDENCE",
+        "CONTRADICT"
+      ],
+      "default": "SUPPORTED"
+    },
     "extensions": {
       "type": "object",
       "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
       "additionalProperties": true
+    },
+    "effect_size": {
+      "type": [
+        "number",
+        "object",
+        "null"
+      ],
+      "description": "Standardized effect size for this finding: a bare number for g, or an object such as {metric, value, ci_lower, ci_upper, p_value}. Read by the forest-plot and cascade extractors; rendering is suppressed when absent rather than approximated."
+    },
+    "effect_estimate": {
+      "type": [
+        "number",
+        "object",
+        "null"
+      ],
+      "description": "Raw effect estimate carried through V1 -> V2 migration so magnitudes survive the hop."
+    },
+    "wwc_rating": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "meets_without_reservations",
+        "meets_with_reservations",
+        "does_not_meet",
+        null
+      ],
+      "description": "WWC 5.0 study rating, when the auditor assigned one."
+    },
+    "outcome_dimension": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Coarse outcome dimension used for grouping (falls back to outcome_type)."
+    },
+    "study_label": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Human-readable study label used on chart axes."
     }
   }
 }

package/schemas/fetch-result.schema.json

@@ -33,7 +33,8 @@
         "markdown_new",
         "defuddle",
         "raw_html",
-        "pdf_parser"
+        "pdf_parser",
+        "sciverse_content"
       ]
     },
     "fetch_status": {

package/schemas/report-result.schema.json

@@ -232,9 +232,9 @@
         "required": [
           "evidence_id",
           "source_id",
-          "outcome_type",
-          "direction"
-        ]
+          "outcome_type"
+        ],
+        "description": "Evidence row as embedded in a rendered result. `direction` is NOT required: it is deprecated in schemas/evidence.schema.json, and consumers must read relation_to_claim (claim support) and effect_direction (observed effect) instead."
       },
       "description": "Evidence rows (projection of evidence.schema.json; stage-level gate enforces the full contract)."
     },

package/schemas/report-spec.schema.json

@@ -2,129 +2,127 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/37chengshan/eduevidence/schemas/report-spec.schema.json",
   "title": "ReportSpec",
-  "description": "report_spec.json — the Visualization Planner output (v5 方案 §9-10, §36). Declares sections and components from the frozen Component Catalog; the deterministic renderer turns it into HTML. No free-form DOM. 扩展字段一律放在各对象 extensions 内。",
+  "description": "Build record emitted next to every rendered report by visualization/eduevidence-report/scripts/build_report.py. It records which theme was baked, which charts the gallery selected or suppressed (with reasons), the integrity-gate result, and the chapter outline. It is a projection record, never a research fact store. Legacy packs that predate this contract carry a smaller shape (mode/title/theme/sections) which is accepted for compatibility.",
   "type": "object",
   "additionalProperties": false,
-  "required": [
-    "title",
-    "theme",
-    "sections"
-  ],
+  "required": [],
   "properties": {
-    "title": {
+    "generated_by": {
       "type": "string"
     },
-    "theme": {
-      "type": "string",
-      "enum": [
-        "claude",
-        "academic",
-        "datalab",
-        "datalab-dark",
-        "presentation"
-      ]
+    "source": {
+      "type": "string"
     },
-    "mode": {
-      "type": "string",
-      "enum": [
-        "research",
-        "demo"
-      ],
-      "default": "research"
+    "question": {
+      "type": "string"
     },
-    "generated_at": {
-      "type": "string",
-      "format": "date-time"
+    "theme_selected": {
+      "type": "string"
     },
-    "sections": {
+    "theme_display": {
+      "type": "string"
+    },
+    "theme_available": {
       "type": "array",
       "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": [
-          "id",
-          "title",
-          "component"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "examples": [
-              "01-executive-decision"
-            ]
-          },
-          "title": {
-            "type": "string"
-          },
-          "component": {
-            "type": "string",
-            "enum": [
-              "ReportShell",
-              "Section",
-              "DecisionCard",
-              "ConfidenceBadge",
-              "OutcomeSummary",
-              "InteractiveChart",
-              "AcademicFigure",
-              "InfographicBlock",
-              "EvidenceMatrix",
-              "EvidenceRow",
-              "TribunalView",
-              "MethodologyPanel",
-              "ConflictCard",
-              "ClaimTrace",
-              "ApplicabilityCard",
-              "InterventionTimeline",
-              "EvaluationFlow",
-              "BenchmarkPanel",
-              "SourceList",
-              "ProvenancePanel",
-              "Footnote"
-            ]
-          },
-          "data_ref": {
-            "type": "string",
-            "description": "Pointer into result.json (e.g. 'decision', 'evidence', 'sources')."
-          },
-          "props": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Component props (theme-agnostic)."
-          }
-        }
+        "type": "string"
+      }
+    },
+    "theme_selection": {
+      "type": "string"
+    },
+    "lang_default": {
+      "type": "string"
+    },
+    "lang_switchable": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "report_pages": {
+      "type": "array",
+      "items": {
+        "type": "string"
       }
     },
+    "full_report_outline": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Chapter plan actually rendered, plus the source it was resolved from (result.report_outline, or safe_fallback)."
+    },
+    "visualization_decisions": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "lieflat_gallery": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Selected / suppressed / rejected gallery entries with reasons, and the layout_source (visual_layout or deterministic_fallback)."
+    },
     "charts": {
       "type": "array",
-      "description": "Chart declarations (see chart-spec.schema.json).",
       "items": {
         "$ref": "chart-spec.schema.json"
+      },
+      "description": "Chart records; each one must satisfy schemas/chart-spec.schema.json."
+    },
+    "infographics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    },
+    "academic_figures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true
       }
     },
+    "integrity_gate": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "mode": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "theme": {
+      "type": "string"
+    },
+    "sections": {
+      "type": "array"
+    },
+    "generated_at": {
+      "type": "string"
+    },
     "integrity": {
       "type": "object",
-      "additionalProperties": false,
-      "description": "Scientific Integrity Gate result (v5 方案 §27).",
-      "properties": {
-        "status": {
-          "type": "string",
-          "enum": [
-            "VALID",
-            "REPORT_INVALID"
-          ]
-        },
-        "checks": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        }
-      }
+      "additionalProperties": true
     },
     "extensions": {
       "type": "object",
-      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
       "additionalProperties": true
     }
-  }
+  },
+  "anyOf": [
+    {
+      "required": [
+        "theme_selected",
+        "integrity_gate"
+      ]
+    },
+    {
+      "required": [
+        "mode",
+        "title",
+        "theme",
+        "sections"
+      ]
+    }
+  ]
 }