eduevidence 5.2.0

package/schemas/v3/run-manifest.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v3/run-manifest.schema.json",
+  "title": "BenchmarkRunManifest",
+  "description": "Layer B empirical benchmark run manifest (v3). Every empirical run MUST record the full environment so results are reproducible: model family/version, temperature, tool set, search provider, question-set version, timestamps, per-attempt usage (tokens/latency/cost) and failures. SIMULATED runs must set run_mode=simulated and may never be presented as model performance.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "run_id",
+    "run_mode",
+    "created_at",
+    "questions_version",
+    "baselines",
+    "repeats",
+    "environment",
+    "attempts"
+  ],
+  "properties": {
+    "run_id": {
+      "type": "string",
+      "pattern": "^run-[0-9]{8}-[0-9]{6}$"
+    },
+    "run_mode": {
+      "type": "string",
+      "enum": [
+        "empirical",
+        "simulated"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "questions_version": {
+      "type": "string",
+      "description": "git commit or tag of benchmarks/questions.jsonl used"
+    },
+    "baselines": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "B0_direct_llm",
+          "B1_search_llm",
+          "B2_standard_agent",
+          "B3_eduevidence_single",
+          "B4_eduevidence_agent_mcp"
+        ]
+      }
+    },
+    "repeats": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "budget_tokens": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "driver",
+        "model_family",
+        "model_version",
+        "temperature",
+        "tools",
+        "search_provider",
+        "agent_mcp_used"
+      ],
+      "properties": {
+        "driver": {
+          "type": "string",
+          "enum": [
+            "api",
+            "cli",
+            "sim"
+          ]
+        },
+        "model_family": {
+          "type": "string"
+        },
+        "model_version": {
+          "type": "string"
+        },
+        "temperature": {
+          "type": "number"
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "search_provider": {
+          "type": "string"
+        },
+        "agent_mcp_used": {
+          "type": "boolean"
+        }
+      }
+    },
+    "attempts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "attempt_id",
+          "question_id",
+          "baseline",
+          "attempt",
+          "status",
+          "started_at",
+          "finished_at"
+        ],
+        "properties": {
+          "attempt_id": {
+            "type": "string"
+          },
+          "question_id": {
+            "type": "string"
+          },
+          "baseline": {
+            "type": "string"
+          },
+          "attempt": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "completed",
+              "failed",
+              "budget_stopped"
+            ]
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "started_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "finished_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "prompt_tokens": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "completion_tokens": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "latency_s": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "cost_usd": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "artifacts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Relative paths of per-attempt artifact files (response text / parsed result)."
+          }
+        }
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  }
+}

package/schemas/v3/synthesis.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v3/synthesis.schema.json",
+  "title": "LibrarySynthesis",
+  "description": "Cross-project synthesis over the Shared Research Library (v3): aggregates verified facts (sources/studies/findings/audits) from one immutable library revision into an outcome-level overview. Interpretive summary only - it never rewrites library state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "synthesis_id",
+    "library_revision",
+    "generated_at",
+    "independent_studies",
+    "source_count",
+    "outcomes",
+    "extensions"
+  ],
+  "properties": {
+    "synthesis_id": {
+      "type": "string",
+      "pattern": "^SYN-[0-9a-f]{8}$"
+    },
+    "library_revision": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "independent_studies": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "source_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "outcomes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "outcome_token",
+          "positive_findings",
+          "negative_findings",
+          "null_findings",
+          "study_keys"
+        ],
+        "properties": {
+          "outcome_token": {
+            "type": "string"
+          },
+          "positive_findings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "negative_findings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "null_findings": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "study_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/v4/drift-report.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v4/drift-report.schema.json",
+  "title": "DriftReport",
+  "description": "One living-evidence refresh outcome (v4): how the graph revision and adjudication moved between the tracked DecisionSnapshot and the fresh one, which new evidence entered the graph, and a suggested_action for a human reviewer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "drift_id",
+    "subscription_id",
+    "from_revision",
+    "to_revision",
+    "generated_at",
+    "new_evidence_ids",
+    "summary",
+    "suggested_action",
+    "extensions"
+  ],
+  "properties": {
+    "drift_id": {
+      "type": "string",
+      "pattern": "^DRF-"
+    },
+    "subscription_id": {
+      "type": "string",
+      "pattern": "^SUB-"
+    },
+    "from_revision": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "to_revision": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "new_evidence_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "suggested_action": {
+      "type": "string",
+      "enum": [
+        "confirmed",
+        "changed",
+        "needs_review"
+      ]
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Carries the machine-readable decision_diff plus evidence hashes committed by this refresh."
+    }
+  }
+}

package/schemas/v4/evidence-library.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v4/evidence-library.schema.json",
+  "title": "BuiltinEvidenceLibrary",
+  "description": "Offline builtin evidence library (v4). A snapshot of condensed evidence summaries extracted from the gold benchmark annotations (benchmarks/annotations/gold-Q01..Q30: key_claims / key_supporting_sources / known_contradictions / correct_outcome_types) plus the three example workflow evidence.jsonl files (ai-coding-assistant, ai-tutor, ai-writing-assistant). Entries are deduplicated on (source_id, outcome_token, claim_text). The library powers the offline preliminary verdict (engine/library_builtin.preliminary_verdict): direction=support means the evidence favors adopting the intervention (=> pilot), direction=contradict means it opposes adoption (=> reject), direction=neutral is inconclusive. The library is conservative by design: it never yields adopt.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["library_id", "version", "generated_at", "entries", "coverage_note"],
+  "properties": {
+    "library_id": { "type": "string", "description": "Stable identifier of this builtin library." },
+    "version": { "type": "string", "description": "Library version string, echoed by preliminary_verdict as library_version." },
+    "generated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp of generation." },
+    "coverage_note": { "type": "string", "description": "Provenance note: extraction sources, dedup key, direction semantics and known limitations." },
+    "entries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "entry_id", "source_id", "title", "year", "outcome_token",
+          "direction", "study_type", "claim_text", "effect_summary",
+          "confidence_markers", "domains"
+        ],
+        "properties": {
+          "entry_id": { "type": "string", "description": "Unique entry id inside this library (lib-... / gold-...)." },
+          "source_id": { "type": "string", "description": "Stable source identifier (e.g. GOLD-Q01 or S-2023-kazemitabaar)." },
+          "title": { "type": "string", "description": "Human-readable title of the underlying source / annotation unit." },
+          "year": { "type": ["integer", "null"], "description": "Publication year of the underlying source; null when unknown (e.g. gold annotation units)." },
+          "outcome_token": { "type": "string", "description": "Primary taxonomy outcome token the evidence speaks to (accuracy, retention, transfer, ...)." },
+          "outcome_tokens": { "type": "array", "items": { "type": "string" }, "description": "All taxonomy outcome tokens the evidence speaks to (multi-outcome gold questions)." },
+          "direction": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "Adoption-relevant direction: support => favors adoption (pilot), contradict => opposes adoption (reject), neutral => inconclusive." },
+          "study_type": { "type": "string", "enum": ["rct", "quasi_experimental", "observational", "survey", "qualitative", "meta_analysis", "literature_review", "case_study", "mixed_methods", "benchmark_annotation", "example_workflow"], "description": "Study design / provenance kind of the underlying evidence." },
+          "claim_text": { "type": "string", "description": "The claim this entry condenses (verbatim from the source where possible)." },
+          "effect_summary": { "type": "string", "description": "One-line summary of the observed effect / direction." },
+          "confidence_markers": { "type": "array", "items": { "type": "string" }, "description": "Provenance & confidence markers (gold_annotation, evidence_level, quality_score, expected_decision, ...)." },
+          "domains": { "type": "array", "items": { "type": "string" }, "description": "Benchmark domains the entry applies to (ai_higher_education, teaching_methods, learning_psychology, assessment_edtech, example workflow names)." }
+        }
+      }
+    }
+  }
+}

package/schemas/v4/living-subscription.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v4/living-subscription.schema.json",
+  "title": "LivingEvidenceSubscription",
+  "description": "A living-evidence watch (v4): binds a revision-bound DecisionSnapshot to a question and query terms, so refresh() can fold newly discovered evidence into the graph and emit drift reports. Subscriptions are durable project records under living/subscriptions/.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "subscription_id",
+    "decision_snapshot_id",
+    "question",
+    "query_terms",
+    "status",
+    "created_at",
+    "extensions"
+  ],
+  "properties": {
+    "subscription_id": {
+      "type": "string",
+      "pattern": "^SUB-"
+    },
+    "decision_snapshot_id": {
+      "type": "string",
+      "pattern": "^DEC-"
+    },
+    "question": {
+      "type": "string",
+      "minLength": 1
+    },
+    "query_terms": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "active",
+        "paused"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Refresh state: last_snapshot_id / last_drift_id / last_refreshed_at / from_graph_revision / to_graph_revision / ingested_evidence_hashes."
+    }
+  }
+}

package/schemas/v4/meta-analysis.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v4/meta-analysis.schema.json",
+  "title": "MetaAnalysisV4",
+  "description": "v4 quantitative evidence synthesis (meta-analysis) contract: fixed/random effect-size pooling with heterogeneity statistics (Q, I2, tau2), publication-bias diagnostics (Egger regression, Rosenthal fail-safe N), leave-one-out robustness and a final robust/fragile label. Produced by engine/meta_analysis.run_meta_analysis; interpretive output only, never rewrites library state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "meta_analysis_id", "outcome_id", "generated_at", "k",
+    "pooled_fixed", "pooled_random", "Q", "df", "I2", "tau2",
+    "egger", "fail_safe_n", "leave_one_out", "label", "studies"
+  ],
+  "properties": {
+    "meta_analysis_id": { "type": "string", "pattern": "^MA-" },
+    "outcome_id": { "type": "string", "minLength": 1 },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "k": { "type": "integer", "minimum": 0 },
+    "pooled_fixed": { "$ref": "#/definitions/pooled" },
+    "pooled_random": { "$ref": "#/definitions/pooled" },
+    "Q": { "type": "number", "minimum": 0 },
+    "df": { "type": "integer", "minimum": 0 },
+    "I2": { "type": "number", "minimum": 0, "maximum": 100 },
+    "tau2": { "type": "number", "minimum": 0 },
+    "egger": { "$ref": "#/definitions/egger" },
+    "fail_safe_n": { "$ref": "#/definitions/fail_safe_n" },
+    "leave_one_out": { "$ref": "#/definitions/leave_one_out" },
+    "label": { "type": "string", "enum": ["robust", "fragile"] },
+    "studies": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/study_row" }
+    },
+    "not_extractable": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/not_extractable_row" }
+    }
+  },
+  "definitions": {
+    "pooled": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "k", "d", "se", "ci_low", "ci_high", "z", "p_value"],
+      "properties": {
+        "method": { "type": "string", "enum": ["fixed_effect", "random_effect"] },
+        "k": { "type": "integer", "minimum": 0 },
+        "d": { "type": "number" },
+        "se": { "type": "number", "minimum": 0 },
+        "ci_low": { "type": "number" },
+        "ci_high": { "type": "number" },
+        "z": { "type": "number" },
+        "p_value": { "type": "number", "minimum": 0, "maximum": 1 },
+        "weights": { "type": "array", "items": { "type": "number" } },
+        "sum_w": { "type": "number", "minimum": 0 },
+        "tau2": { "type": "number", "minimum": 0 },
+        "Q": { "type": "number", "minimum": 0 },
+        "df": { "type": "integer", "minimum": 0 },
+        "I2": { "type": "number", "minimum": 0, "maximum": 100 }
+      }
+    },
+    "study_row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["study_id", "outcome_id", "d", "se", "n"],
+      "properties": {
+        "study_id": { "type": "string", "minLength": 1 },
+        "outcome_id": { "type": "string", "minLength": 1 },
+        "d": { "type": "number" },
+        "se": { "type": "number", "minimum": 0 },
+        "n": { "type": ["integer", "null"], "minimum": 0 },
+        "not_extractable": { "type": "boolean" },
+        "reason": { "type": ["string", "null"] }
+      }
+    },
+    "not_extractable_row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["study_id", "outcome_id", "d", "se", "n", "not_extractable", "reason"],
+      "properties": {
+        "study_id": { "type": "string", "minLength": 1 },
+        "outcome_id": { "type": "string", "minLength": 1 },
+        "d": { "type": ["number", "null"] },
+        "se": { "type": ["number", "null"] },
+        "n": { "type": ["integer", "null"], "minimum": 0 },
+        "not_extractable": { "type": "boolean", "const": true },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "egger": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["applicable"],
+      "properties": {
+        "applicable": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "k": { "type": "integer", "minimum": 0 },
+        "intercept": { "type": "number" },
+        "se_intercept": { "type": "number", "minimum": 0 },
+        "slope": { "type": "number" },
+        "t": { "type": "number" },
+        "p_value": { "type": "number", "minimum": 0, "maximum": 1 },
+        "significant": { "type": "boolean" },
+        "bias_detected": { "type": "boolean" }
+      }
+    },
+    "fail_safe_n": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "k", "sum_z", "n_fail_safe", "tolerates_5"],
+      "properties": {
+        "method": { "type": "string", "enum": ["rosenthal"] },
+        "k": { "type": "integer", "minimum": 0 },
+        "sum_z": { "type": "number" },
+        "z_crit": { "type": "number", "minimum": 0 },
+        "z_crit_squared": { "type": "number", "minimum": 0 },
+        "n_fail_safe": { "type": "number", "minimum": 0 },
+        "tolerates_5": { "type": "boolean" }
+      }
+    },
+    "leave_one_out": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "method", "k", "full_pooled", "iterations",
+        "n_direction_flips", "n_ci_crossings", "n_decision_changes"
+      ],
+      "properties": {
+        "method": { "type": "string", "enum": ["leave_one_out"] },
+        "k": { "type": "integer", "minimum": 0 },
+        "full_pooled": { "$ref": "#/definitions/pooled" },
+        "iterations": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/loo_iteration" }
+        },
+        "n_direction_flips": { "type": "integer", "minimum": 0 },
+        "n_ci_crossings": { "type": "integer", "minimum": 0 },
+        "n_decision_changes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "loo_iteration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["removed_study_id", "pooled", "direction_flip", "ci_crosses_zero", "decision_changed"],
+      "properties": {
+        "removed_study_id": { "type": "string", "minLength": 1 },
+        "removed_index": { "type": "integer", "minimum": 0 },
+        "pooled": { "$ref": "#/definitions/pooled" },
+        "direction_flip": { "type": "boolean" },
+        "ci_crosses_zero": { "type": "boolean" },
+        "decision_changed": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/verdict.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/verdict.schema.json",
+  "title": "EducationVerdict",
+  "description": "Output of the Evidence Tribunal: what the evidence supports, cannot support, and the recommended action. Decision is one of ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE (expressed here as adopt|pilot|reject|insufficient_evidence). confidence 由 scripts/compute_confidence.py 确定性计算并覆盖模型值；confidence_score 是规则化指数（0-1），不是概率。扩展字段一律放在 extensions 内。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["decision_question", "recommended_action", "confidence"],
+  "properties": {
+    "decision_question": { "type": "string" },
+    "target_population": { "type": "string" },
+    "target_context": { "type": "string" },
+    "supported_claims": { "type": "array", "items": { "type": "string" } },
+    "uncertain_claims": { "type": "array", "items": { "type": "string" } },
+    "contradicted_claims": { "type": "array", "items": { "type": "string" } },
+    "reason_for_disagreement": { "type": "string" },
+    "methodology_summary": { "type": "string" },
+    "outcome_specific_findings": { "type": "object", "additionalProperties": true },
+    "short_term_effect": { "type": ["string", "null"] },
+    "long_term_effect": { "type": ["string", "null"] },
+    "transfer_effect": { "type": ["string", "null"] },
+    "risk_effect": { "type": ["string", "null"] },
+    "applicability": { "type": "object", "additionalProperties": true },
+    "confidence": { "type": "string", "enum": ["High", "Moderate", "Low", "Insufficient"] },
+    "confidence_score": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "maximum": 1,
+      "description": "规则化置信度指数（0-1），由 compute_confidence.py 覆盖模型值。不是概率，禁止宣传为百分比。"
+    },
+    "confidence_policy_version": { "type": "string", "description": "确定性置信度策略版本号（如 2026-08-12.v1）。" },
+    "independent_studies": { "type": ["integer", "null"], "minimum": 0, "description": "独立研究数（按 study_id/source_id 去重）。" },
+    "independent_samples": { "type": ["integer", "null"], "minimum": 0, "description": "独立样本数（按 sample_id 去重）。" },
+    "confidence_breakdown": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Rule-based components: evidence_quality, consistency, directness, evidence_count, independent_studies, independent_samples, conflict_penalty, unsupported_penalty."
+    },
+    "raw_model_confidence": {
+      "type": ["string", "null"],
+      "description": "模型原始 confidence 输出（被确定性值覆盖前的值，仅供审计比对）。"
+    },
+    "raw_model_confidence_breakdown": { "type": "object", "additionalProperties": true },
+    "what_can_be_claimed": { "type": "array", "items": { "type": "string" } },
+    "what_cannot_be_claimed": { "type": "array", "items": { "type": "string" } },
+    "missing_evidence": { "type": "array", "items": { "type": "string" } },
+    "recommended_action": { "type": "string", "enum": ["adopt", "pilot", "reject", "insufficient_evidence"] },
+    "decision_rationale": { "type": "string" },
+    "exceeds_evidence_boundary": { "type": "array", "items": { "type": "string" }, "description": "Conclusions that currently go beyond the evidence boundary." },
+    "extensions": {
+      "type": "object",
+      "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
+      "additionalProperties": true
+    }
+  }
+}