eduevidence 5.2.0

package/schemas/v2/finding.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/finding.schema.json",
+  "title": "Finding",
+  "description": "What a study actually observed. effect_direction records the observed direction only; relation to a Claim lives on the EvidenceLink, never here. Never infer missing precision in effect_estimate.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "finding_id", "study_id", "finding_type", "outcome_id", "measure",
+    "effect_direction", "raw_result_text", "source_locator", "extensions"
+  ],
+  "properties": {
+    "finding_id": { "type": "string", "pattern": "^FND-" },
+    "study_id": { "type": "string", "pattern": "^(STU-|STUDY-)" },
+    "finding_type": {
+      "type": "string",
+      "enum": [
+        "quantitative_effect", "association", "descriptive", "qualitative_theme",
+        "implementation_finding", "process_finding"
+      ]
+    },
+    "outcome_id": { "type": "string", "pattern": "^OUT-" },
+    "measure": { "type": "string", "minLength": 1 },
+    "timepoint": { "type": ["string", "null"] },
+    "effect_direction": {
+      "type": "string",
+      "enum": ["positive", "negative", "null", "mixed", "not_applicable"]
+    },
+    "effect_estimate": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["metric", "raw_text"],
+      "properties": {
+        "metric": { "type": "string", "minLength": 1 },
+        "value": { "type": ["number", "null"] },
+        "unit": { "type": ["string", "null"] },
+        "ci_low": { "type": ["number", "null"] },
+        "ci_high": { "type": ["number", "null"] },
+        "p_value": { "type": ["number", "null"] },
+        "raw_text": { "type": "string", "minLength": 1 }
+      }
+    },
+    "raw_result_text": { "type": "string", "minLength": 1 },
+    "source_locator": { "type": "string", "minLength": 1 },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/graph-revision.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/graph-revision.schema.json",
+  "title": "GraphRevision",
+  "description": "Immutable revision manifest. graph/HEAD is authoritative; this manifest describes one committed snapshot.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "revision", "parent_revision", "run_id", "reason",
+    "touched_entities", "before_hash", "after_hash", "created_at", "extensions"
+  ],
+  "properties": {
+    "revision": { "type": "integer", "minimum": 1 },
+    "parent_revision": { "type": "integer", "minimum": 0 },
+    "run_id": { "type": "string", "pattern": "^RUN-" },
+    "reason": { "type": "string", "minLength": 1 },
+    "touched_entities": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string", "minLength": 1 },
+        "uniqueItems": true
+      }
+    },
+    "before_hash": { "type": "string", "minLength": 1 },
+    "after_hash": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/knowledge-gap.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/knowledge-gap.schema.json",
+  "title": "KnowledgeGap",
+  "description": "A structured evidence-coverage gap derived from graph coverage — never free-form 'future work' text. Every gap stores related Claim/Outcome IDs and the graph revision it was derived from.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "gap_id", "gap_type", "related_claim_ids", "related_outcome_ids",
+    "priority", "reasoning", "status", "derived_from_graph_revision",
+    "extensions"
+  ],
+  "properties": {
+    "gap_id": { "type": "string", "pattern": "^GAP-" },
+    "gap_type": {
+      "type": "string",
+      "enum": [
+        "missing_direct_evidence", "missing_population", "missing_context",
+        "missing_outcome", "missing_retention", "missing_transfer",
+        "methodology_weakness", "unresolved_conflict",
+        "insufficient_sample_independence"
+      ]
+    },
+    "related_claim_ids": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "related_outcome_ids": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+    "reasoning": { "type": "string", "minLength": 1 },
+    "status": { "type": "string", "enum": ["open", "addressed", "superseded"] },
+    "derived_from_graph_revision": { "type": "integer", "minimum": 1 },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/methodology-audit.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/methodology-audit.schema.json",
+  "title": "MethodologyAudit",
+  "description": "Methodological appraisal. Quality belongs primarily to Study/method appraisal, not duplicated into every Claim link.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "audit_id", "study_id", "policy_version",
+    "design_quality", "sample_quality", "measurement_validity", "temporal_strength",
+    "bias_checks", "confounders", "limitations",
+    "overall_status", "audited_at", "extensions"
+  ],
+  "properties": {
+    "audit_id": { "type": "string", "pattern": "^AUD-" },
+    "study_id": { "type": "string", "pattern": "^(STU-|STUDY-)" },
+    "policy_version": { "type": "string", "minLength": 1 },
+    "design_quality": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "sample_quality": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "measurement_validity": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "temporal_strength": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "bias_checks": { "type": "array", "items": { "type": "string" } },
+    "confounders": { "type": "array", "items": { "type": "string" } },
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "outcome_specific_notes": { "type": "string" },
+    "overall_status": { "type": "string", "enum": ["pass", "concern", "fail"] },
+    "audited_at": { "type": "string", "format": "date-time" },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/outcome.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/outcome.schema.json",
+  "title": "Outcome",
+  "description": "A measurable education outcome from the Outcome Taxonomy: learning / task performance / process / risk.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["outcome_id", "name", "outcome_type", "extensions"],
+  "properties": {
+    "outcome_id": { "type": "string", "pattern": "^OUT-" },
+    "name": { "type": "string", "minLength": 1 },
+    "outcome_type": {
+      "type": "string",
+      "enum": ["learning", "task_performance", "process", "risk"]
+    },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/project.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/project.schema.json",
+  "title": "Project",
+  "description": "Long-lived research project owning a versioned Project Evidence Graph. Run is an execution attempt inside a Project; the Project is the durable unit.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "project_id", "title", "domain", "question", "research_mode",
+    "decision_target", "created_at", "updated_at", "engine_version",
+    "schema_version", "graph_revision", "status"
+  ],
+  "properties": {
+    "project_id": { "type": "string", "pattern": "^PRJ-" },
+    "title": { "type": "string", "minLength": 1 },
+    "domain": { "type": "string", "enum": ["education"] },
+    "question": { "type": "string", "minLength": 1 },
+    "research_mode": { "type": "string", "enum": ["evidence_review", "full_research_cycle"] },
+    "decision_target": {
+      "type": "string",
+      "enum": ["evidence_review", "teaching_decision", "teaching_pilot", "evaluation_plan", "research_cycle"]
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" },
+    "engine_version": { "type": "string", "minLength": 1 },
+    "schema_version": { "type": "string", "const": "2.0" },
+    "graph_revision": { "type": "integer", "minimum": 0 },
+    "status": { "type": "string", "enum": ["active", "waiting_for_user", "completed", "archived", "failed"] },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/research-intent.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/research-intent.schema.json",
+  "title": "ResearchIntent",
+  "description": "Structured intent driving mode recommendation. decision_target controls the requested deliverable; research_mode controls lifecycle depth.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "decision_target", "wants_existing_evidence", "wants_study_design",
+    "has_user_data", "wants_data_analysis", "wants_decision_update"
+  ],
+  "properties": {
+    "decision_target": {
+      "type": "string",
+      "enum": ["evidence_review", "teaching_decision", "teaching_pilot", "evaluation_plan", "research_cycle"]
+    },
+    "wants_existing_evidence": { "type": "boolean" },
+    "wants_study_design": { "type": "boolean" },
+    "has_user_data": { "type": "boolean" },
+    "wants_data_analysis": { "type": "boolean" },
+    "wants_decision_update": { "type": "boolean" },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/run.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/run.schema.json",
+  "title": "Run",
+  "description": "One execution attempt or mutation inside a Project. A Run starts at graph_revision_before and, on completion, records graph_revision_after.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "run_id", "project_id", "purpose", "started_at", "status",
+    "graph_revision_before", "graph_revision_after",
+    "capabilities", "execution_backend", "policy_versions"
+  ],
+  "properties": {
+    "run_id": { "type": "string", "pattern": "^RUN-" },
+    "project_id": { "type": "string", "pattern": "^PRJ-" },
+    "purpose": { "type": "string", "minLength": 1 },
+    "started_at": { "type": "string", "format": "date-time" },
+    "status": { "type": "string", "enum": ["running", "completed", "failed", "aborted"] },
+    "graph_revision_before": { "type": "integer", "minimum": 0 },
+    "graph_revision_after": { "type": ["integer", "null"], "minimum": 0 },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "execution_backend": {
+      "type": "string",
+      "enum": ["agent_mcp_enhanced", "host_native_subagents", "sequential_main_agent"]
+    },
+    "policy_versions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_validation", "methodology", "confidence"],
+      "properties": {
+        "source_validation": { "type": "string", "minLength": 1 },
+        "methodology": { "type": "string", "minLength": 1 },
+        "confidence": { "type": "string", "minLength": 1 },
+        "extensions": { "type": "object" }
+      }
+    },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/source.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/source.schema.json",
+  "title": "Source",
+  "description": "A verifiable research source. canonical_locator is an absolute external URI or an explicit project:// URI; raw filesystem paths stay provenance metadata.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "source_id", "origin", "source_type", "canonical_locator",
+    "validation_status", "extensions"
+  ],
+  "properties": {
+    "source_id": { "type": "string", "pattern": "^(SRC-|S-)" },
+    "origin": { "type": "string", "enum": ["external", "project"] },
+    "source_type": { "type": "string", "minLength": 1 },
+    "canonical_locator": { "type": "string", "format": "uri" },
+    "validation_status": {
+      "type": "string",
+      "enum": ["valid", "accepted_partial", "invalid", "failed"]
+    },
+    "content_hash": { "type": ["string", "null"], "minLength": 1 },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/study-design.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/study-design.schema.json",
+  "title": "StudyDesign",
+  "description": "An evidence-grounded study design plan. A StudyDesign can only be created from one or more explicit KnowledgeGap entities. Carries analysis_requirements[] but NOT analysis_plan_id — the separately versioned AnalysisPlan owns design_id, avoiding a circular reference. EduEvidence flags human-subject ethics fields but never claims ethics approval.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "design_id", "gap_ids", "research_question", "design_type",
+    "population", "sampling_plan", "intervention", "comparison",
+    "outcomes", "measures", "timepoints", "assignment_strategy",
+    "confounder_plan", "analysis_requirements", "success_criteria",
+    "stop_conditions", "ethics_flags", "preregistration_fields",
+    "derived_from_graph_revision", "created_at", "extensions"
+  ],
+  "properties": {
+    "design_id": { "type": "string", "pattern": "^DSN-" },
+    "gap_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^GAP-" },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "research_question": { "type": "string", "minLength": 1 },
+    "design_type": {
+      "type": "string",
+      "enum": ["rct", "cluster_rct", "quasi_experimental", "pre_post",
+               "observational", "survey", "qualitative", "mixed_methods"]
+    },
+    "population": { "type": "string", "minLength": 1 },
+    "sampling_plan": { "type": "string", "minLength": 1 },
+    "intervention": { "type": ["string", "null"] },
+    "comparison": { "type": ["string", "null"] },
+    "outcomes": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "measures": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "timepoints": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "assignment_strategy": { "type": "string", "minLength": 1 },
+    "confounder_plan": { "type": "string" },
+    "analysis_requirements": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "success_criteria": { "type": "array", "items": { "type": "string" } },
+    "stop_conditions": { "type": "array", "items": { "type": "string" } },
+    "ethics_flags": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "human_subjects", "sensitive_data", "minors_involved",
+        "consent_status", "ethics_review_required", "deidentification_required"
+      ],
+      "properties": {
+        "human_subjects": { "type": "boolean" },
+        "sensitive_data": { "type": "boolean" },
+        "minors_involved": { "type": "boolean" },
+        "consent_status": { "type": "string", "enum": ["obtained", "pending", "not_required", "unknown"] },
+        "ethics_review_required": { "type": "boolean" },
+        "deidentification_required": { "type": "boolean" },
+        "extensions": { "type": "object" }
+      }
+    },
+    "preregistration_fields": { "type": "object" },
+    "derived_from_graph_revision": { "type": "integer", "minimum": 1 },
+    "created_at": { "type": "string", "format": "date-time" },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v2/study.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/study.schema.json",
+  "title": "Study",
+  "description": "One study inside a Source. independence_key identifies independent study/sample units; identity_status records identity confidence instead of aggressive merging.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "study_id", "source_ids", "study_design", "population", "sample_ids",
+    "independence_key", "identity_status", "extensions"
+  ],
+  "properties": {
+    "study_id": { "type": "string", "pattern": "^(STU-|STUDY-)" },
+    "source_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^(SRC-|S-)" },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "study_design": { "type": "string", "minLength": 1 },
+    "population": { "type": "string", "minLength": 1 },
+    "sample_ids": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "sample_size": { "type": ["integer", "null"], "minimum": 0 },
+    "intervention": { "type": ["string", "null"] },
+    "comparison": { "type": ["string", "null"] },
+    "independence_key": { "type": "string", "minLength": 1 },
+    "identity_status": {
+      "type": "string",
+      "enum": ["resolved", "unresolved", "legacy"]
+    },
+    "extensions": { "type": "object" }
+  }
+}

package/schemas/v3/pilot-outcome.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/v3/pilot-outcome.schema.json",
+  "title": "PilotOutcomeRecord",
+  "description": "Decision-to-Outcome Loop record (v3): a PilotRun bound to a DecisionSnapshot that carries outcome data through import -> analysis -> re-adjudication. PII columns are forbidden by anon_policy; student data stays local.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "pilot_id",
+    "project_id",
+    "decision_snapshot_id",
+    "title",
+    "start_date",
+    "end_date",
+    "conditions",
+    "sample_size",
+    "design_id",
+    "anon_policy",
+    "outcome_columns",
+    "status",
+    "created_at",
+    "extensions"
+  ],
+  "properties": {
+    "pilot_id": {
+      "type": "string",
+      "pattern": "^PIL-[0-9a-f]{8}$"
+    },
+    "project_id": {
+      "type": "string"
+    },
+    "decision_snapshot_id": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "start_date": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "end_date": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "conditions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "sample_size": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "design_id": {
+      "type": "string",
+      "description": "Study design the pilot implements"
+    },
+    "anon_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "no_pii_columns",
+        "note"
+      ],
+      "properties": {
+        "no_pii_columns": {
+          "type": "boolean"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "outcome_columns": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Outcome Taxonomy tokens measured by the pilot"
+    },
+    "dataset_asset_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "analysis_run_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "registered",
+        "data_imported",
+        "analyzed",
+        "adjudicated"
+      ]
+    },
+    "redecide": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "new_decision_snapshot_id": {
+          "type": "string"
+        },
+        "graph_revision": {
+          "type": "integer"
+        },
+        "diff": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}