Evidence Mentor: autonomous local evidence runner

.gitattributes

@@ -0,0 +1 @@
+docs/evidence/he-retrieval-qualification-protocol-v1.md text eol=lf

build.gradle.kts

@@ -136,6 +136,34 @@ tasks.withType<Jar>().configureEach {
     isReproducibleFileOrder = true
 }
 
+tasks.register<JavaExec>("brightfieldQualification") {
+    group = "verification"
+    description = "Runs synthetic-only cell and IHC pre-qualification checks."
+    dependsOn(tasks.classes)
+    classpath = sourceSets.main.get().runtimeClasspath
+    mainClass = "org.pathlab.forge.evidence.BrightfieldQualificationHarness"
+    val report = providers.gradleProperty("pathlab.qualification.output")
+        .orElse(layout.buildDirectory.file("qualification/brightfield-report.json").map { it.asFile.absolutePath })
+    args(
+        "--packs", file("src/main/resources/evidence-packs").absolutePath,
+        "--output", report.get())
+}
+
+tasks.register<JavaExec>("cellInstanceQualification") {
+    group = "verification"
+    description = "Runs the frozen held-out cell-instance qualification evaluator."
+    dependsOn(tasks.classes)
+    classpath = sourceSets.main.get().runtimeClasspath
+    mainClass = "org.pathlab.forge.evidence.CellInstanceQualificationEvaluator"
+    maxHeapSize = "768m"
+    val cohort = providers.gradleProperty("pathlab.cell.cohort")
+    val cohortSha = providers.gradleProperty("pathlab.cell.cohortSha256")
+    val report = providers.gradleProperty("pathlab.cell.output")
+        .orElse(layout.buildDirectory.file("qualification/cell-instance-metrics.json")
+            .map { it.asFile.absolutePath })
+    doFirst { setArgs(listOf(cohort.get(), cohortSha.get(), report.get())) }
+}
+
 val installVersionedRuntime = tasks.register<Sync>("installVersionedRuntime") {
     dependsOn(tasks.installDist)
     val localAppData = providers.environmentVariable("LOCALAPPDATA")

contracts/evidence-mentor/README.md

@@ -0,0 +1,10 @@
+# Evidence Mentor contracts
+
+These schemas are the cross-repository truth boundary for the private research MVP.
+
+- `pathlab.ai-pack/1` describes a locally installed expert pack and its rights/resource gates.
+- `pathlab.ai-evidence/1` is the immutable, signed, slide-bound result accepted by Viewer.
+- `pathlab.knowledge-pack/1` contains reviewed atomic claims; the tutor may select claim IDs but may not invent factual prose.
+- `pathlab.model-qualification-report/1` records checksum-bound synthetic or held-out checks without activating a pack.
+
+Raw WSI pixels and reusable embeddings are never valid evidence-bundle members. All contracts are research-only and fail closed.

contracts/evidence-mentor/pathlab-ai-evidence-v1.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://pathlab.local/schemas/pathlab-ai-evidence-v1.schema.json",
+  "title": "PathLab AI Evidence v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "bundleId", "source", "pack", "status", "researchOnly", "notDiagnostic", "reviewRequired", "coordinates", "evidence", "cellAggregates", "ihcDescriptors", "citations", "qc", "provenance", "manifestSha256", "signature"],
+  "properties": {
+    "schema": {"const": "pathlab.ai-evidence/1"},
+    "bundleId": {"type": "string", "pattern": "^[A-Za-z0-9._-]{1,120}$"},
+    "source": {"type": "object", "additionalProperties": false, "required": ["slideSha256", "revision"], "properties": {"slideSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "revision": {"type": "string", "minLength": 1, "maxLength": 160}}},
+    "pack": {"type": "object", "additionalProperties": false, "required": ["id", "version", "manifestSha256", "preprocessing", "artifacts", "allowedUse", "validationStatus"], "properties": {"id": {"type": "string", "maxLength": 120}, "version": {"type": "string", "maxLength": 64}, "manifestSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "preprocessing": {"type": "string", "maxLength": 120}, "artifacts": {"type": "array", "maxItems": 16, "items": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}, "allowedUse": {"const": "private-research"}, "validationStatus": {"enum": ["experimental", "qualified"]}}},
+    "status": {"enum": ["completed", "partial", "abstained", "unsupported", "failed"]},
+    "researchOnly": {"const": true},
+    "notDiagnostic": {"const": true},
+    "reviewRequired": {"const": true},
+    "coordinates": {"type": "object", "additionalProperties": false, "required": ["space", "originX", "originY", "scaleX", "scaleY"], "properties": {"space": {"const": "source-pixel"}, "originX": {"type": "number", "minimum": 0}, "originY": {"type": "number", "minimum": 0}, "scaleX": {"type": "number", "exclusiveMinimum": 0}, "scaleY": {"type": "number", "exclusiveMinimum": 0}}},
+    "evidence": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/$defs/region"}},
+    "cellAggregates": {"type": "array", "maxItems": 1000, "items": {"type": "object", "additionalProperties": false, "required": ["regionId", "algorithm", "count", "densityPerMm2", "meanNucleusAreaPx2"], "properties": {"regionId": {"type": "string", "maxLength": 120}, "algorithm": {"enum": ["hovernet-fast", "od-watershed", "od-connected-components"]}, "count": {"type": "integer", "minimum": 0}, "densityPerMm2": {"type": ["number", "null"], "minimum": 0}, "meanNucleusAreaPx2": {"type": ["number", "null"], "minimum": 0}, "meanNucleusPerimeterPx": {"type": ["number", "null"], "minimum": 0}, "meanNucleusEccentricity": {"type": ["number", "null"], "minimum": 0, "maximum": 1}, "meanNucleusSolidity": {"type": ["number", "null"], "minimum": 0, "maximum": 1}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}}}},
+    "ihcDescriptors": {"type": "array", "maxItems": 1000, "items": {"type": "object", "additionalProperties": false, "required": ["regionId", "marker", "compartment", "dabAreaFraction", "meanDabOd", "researchEstimate"], "properties": {"regionId": {"type": "string", "maxLength": 120}, "markerId": {"enum": ["generic", "er", "pr", "ki-67", "her2", "pd-l1"]}, "marker": {"enum": ["generic", "er", "pr", "ki-67", "her2", "pd-l1"]}, "markerIdentitySource": {"enum": ["unknown", "faculty-authored", "slide-label", "import-metadata"]}, "analysisMode": {"enum": ["marker-aware", "generic-fallback", "generic-descriptive"]}, "cellMaskSource": {"enum": ["hovernet-fast", "od-watershed", "od-connected-components"]}, "compartmentSource": {"enum": ["none", "faculty-authored", "faculty-approved", "model-suggested"]}, "calibrationStatus": {"enum": ["calibrated", "relative_only", "not_evaluable"]}, "compartment": {"enum": ["nuclear", "membrane", "tumor-immune-region", "generic-region"]}, "dabAreaFraction": {"type": "number", "minimum": 0, "maximum": 1}, "meanDabOd": {"type": "number", "minimum": 0}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "abstentionReason": {"type": ["string", "null"], "maxLength": 500}, "researchEstimate": {"const": true}}}},
+    "citations": {"type": "array", "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["claimId", "sourceUrl"], "properties": {"claimId": {"type": "string", "maxLength": 160}, "sourceUrl": {"type": "string", "format": "uri", "maxLength": 1000}}}},
+    "qc": {"type": "object", "additionalProperties": false, "required": ["focus", "tissueFraction", "uncertainty", "abstentionReasons"], "properties": {"focus": {"type": "number", "minimum": 0, "maximum": 1}, "tissueFraction": {"type": "number", "minimum": 0, "maximum": 1}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "abstentionReasons": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 500}}, "calibrationStatus": {"enum": ["calibrated", "relative_only", "not_evaluable"]}, "backgroundFraction": {"type": "number", "minimum": 0, "maximum": 1}, "saturationFraction": {"type": "number", "minimum": 0, "maximum": 1}, "stainSeparation": {"type": "number", "minimum": 0, "maximum": 1}, "warnings": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 500}}}},
+    "provenance": {"type": "object", "additionalProperties": false, "required": ["createdAt", "codeRevision", "offlineAnalysis"], "properties": {"createdAt": {"type": "string", "format": "date-time"}, "codeRevision": {"type": "string", "maxLength": 160}, "offlineAnalysis": {"const": true}}},
+    "manifestSha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "signature": {"type": "object", "additionalProperties": false, "required": ["algorithm", "keyId", "publicKeyDer", "value"], "properties": {"algorithm": {"const": "Ed25519"}, "keyId": {"type": "string", "maxLength": 160}, "publicKeyDer": {"type": "string", "minLength": 1}, "value": {"type": "string", "minLength": 1}}}
+  },
+  "$defs": {
+    "region": {"type": "object", "additionalProperties": false, "required": ["id", "stage", "kind", "x", "y", "width", "height", "score"], "properties": {"id": {"type": "string", "maxLength": 120}, "stage": {"enum": ["coarse", "refined"]}, "kind": {"enum": ["support", "similar", "contrast"]}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}, "score": {"type": "number", "minimum": 0, "maximum": 1}, "thumbnail": {"type": "string", "pattern": "^thumbnails/[A-Za-z0-9._-]+\\.(png|jpg|webp)$"}}}
+  }
+}

contracts/evidence-mentor/pathlab-ai-evidence-v2.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://pathlab.local/schemas/pathlab-ai-evidence-v2.schema.json",
+  "title": "PathLab AI Evidence v2", "type": "object", "additionalProperties": false,
+  "required": ["schema", "bundleId", "source", "pack", "qualificationAttestationSha256", "status", "researchOnly", "notDiagnostic", "reviewRequired", "coordinates", "regions", "cellInstances", "cellAggregates", "ihcDescriptors", "specialStainDescriptors", "cytologyDescriptors", "citations", "qc", "provenance", "manifestSha256", "signature"],
+  "properties": {
+    "schema": {"const": "pathlab.ai-evidence/2"}, "bundleId": {"$ref": "#/$defs/id"},
+    "source": {"type": "object", "additionalProperties": false, "required": ["slideSha256", "revision", "width", "height"], "properties": {"slideSha256": {"$ref": "#/$defs/sha"}, "revision": {"type": "string", "minLength": 1, "maxLength": 160}, "width": {"type": "integer", "minimum": 1}, "height": {"type": "integer", "minimum": 1}}},
+    "pack": {"type": "object", "additionalProperties": false, "required": ["id", "version", "manifestSha256", "capability", "scope", "preprocessing", "artifacts"], "properties": {"id": {"$ref": "#/$defs/id"}, "version": {"type": "string", "maxLength": 64}, "manifestSha256": {"$ref": "#/$defs/sha"}, "capability": {"type": "string", "maxLength": 120}, "scope": {"enum": ["deployment", "research-restricted"]}, "preprocessing": {"type": "string", "maxLength": 160}, "artifacts": {"type": "array", "maxItems": 32, "items": {"$ref": "#/$defs/sha"}}}},
+    "qualificationAttestationSha256": {"$ref": "#/$defs/sha"}, "status": {"enum": ["completed", "partial", "abstained", "unsupported", "failed"]},
+    "researchOnly": {"const": true}, "notDiagnostic": {"const": true}, "reviewRequired": {"const": true},
+    "coordinates": {"type": "object", "additionalProperties": false, "required": ["space", "originX", "originY", "scaleX", "scaleY"], "properties": {"space": {"const": "source-pixel"}, "originX": {"type": "number", "minimum": 0}, "originY": {"type": "number", "minimum": 0}, "scaleX": {"type": "number", "exclusiveMinimum": 0}, "scaleY": {"type": "number", "exclusiveMinimum": 0}}},
+    "regions": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/$defs/region"}},
+    "cellInstances": {"type": "array", "maxItems": 100000, "items": {"type": "object", "additionalProperties": false, "required": ["id", "regionId", "maskEncoding", "mask", "areaPx2", "perimeterPx", "eccentricity", "solidity", "meanIntensity", "uncertainty", "category"], "properties": {"id": {"$ref": "#/$defs/id"}, "regionId": {"$ref": "#/$defs/id"}, "maskEncoding": {"enum": ["polygon", "rle"]}, "mask": {"type": "array", "minItems": 3, "maxItems": 4096, "items": {"type": "number", "minimum": 0}}, "areaPx2": {"type": "number", "minimum": 0}, "perimeterPx": {"type": "number", "minimum": 0}, "eccentricity": {"type": "number", "minimum": 0, "maximum": 1}, "solidity": {"type": "number", "minimum": 0, "maximum": 1}, "meanIntensity": {"type": "number", "minimum": 0, "maximum": 1}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "category": {"enum": ["unclassified", "model-category-1", "model-category-2", "model-category-3", "model-category-4", "model-category-5"]}}}},
+    "cellAggregates": {"type": "array", "maxItems": 1000, "items": {"type": "object", "additionalProperties": false, "required": ["regionId", "algorithm", "count", "densityPerMm2", "distributions", "uncertainty", "qc"], "properties": {"regionId": {"$ref": "#/$defs/id"}, "algorithm": {"enum": ["hovernet-fast", "pathosam", "od-watershed"]}, "count": {"type": "integer", "minimum": 0}, "densityPerMm2": {"type": ["number", "null"], "minimum": 0}, "distributions": {"type": "object"}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "qc": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 200}}}}},
+    "ihcDescriptors": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/$defs/stainDescriptor"}},
+    "specialStainDescriptors": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/$defs/stainDescriptor"}},
+    "cytologyDescriptors": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/$defs/stainDescriptor"}},
+    "citations": {"type": "array", "maxItems": 100, "items": {"type": "object", "additionalProperties": false, "required": ["claimId", "sourceUrl"], "properties": {"claimId": {"$ref": "#/$defs/id"}, "sourceUrl": {"type": "string", "format": "uri", "maxLength": 1000}}}},
+    "qc": {"type": "object", "additionalProperties": false, "required": ["focus", "tissueFraction", "uncertainty", "abstentionReasons", "warnings"], "properties": {"focus": {"type": "number", "minimum": 0, "maximum": 1}, "tissueFraction": {"type": "number", "minimum": 0, "maximum": 1}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "abstentionReasons": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 500}}, "warnings": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 500}}}},
+    "provenance": {"type": "object", "additionalProperties": false, "required": ["createdAt", "codeRevision", "offlineAnalysis", "campaignId"], "properties": {"createdAt": {"type": "string", "format": "date-time"}, "codeRevision": {"type": "string", "maxLength": 160}, "offlineAnalysis": {"const": true}, "campaignId": {"type": ["string", "null"], "maxLength": 120}}},
+    "manifestSha256": {"$ref": "#/$defs/sha"}, "signature": {"$ref": "#/$defs/signature"}
+  },
+  "$defs": {
+    "id": {"type": "string", "pattern": "^[A-Za-z0-9._-]{1,160}$"}, "sha": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "region": {"type": "object", "additionalProperties": false, "required": ["id", "stage", "kind", "reviewStatus", "x", "y", "width", "height", "score"], "properties": {"id": {"$ref": "#/$defs/id"}, "stage": {"enum": ["coarse", "refined"]}, "kind": {"enum": ["support", "similar", "contrast", "analysis", "tumor-compartment", "immune-compartment"]}, "reviewStatus": {"enum": ["unreviewed", "faculty-authored", "faculty-approved"]}, "x": {"type": "number", "minimum": 0}, "y": {"type": "number", "minimum": 0}, "width": {"type": "number", "exclusiveMinimum": 0}, "height": {"type": "number", "exclusiveMinimum": 0}, "score": {"type": "number", "minimum": 0, "maximum": 1}, "thumbnail": {"type": "string", "pattern": "^thumbnails/[A-Za-z0-9._-]+\\.(png|jpg|webp)$"}}},
+    "stainDescriptor": {"type": "object", "additionalProperties": false, "required": ["regionId", "stainId", "markerId", "analysisMode", "cellMaskSource", "compartmentSource", "calibrationStatus", "measurements", "qc", "uncertainty", "abstentionReason", "researchEstimate"], "properties": {"regionId": {"$ref": "#/$defs/id"}, "stainId": {"enum": ["ihc_dab", "pas", "pas_d", "trichrome", "gms", "afb", "papanicolaou", "generic_brightfield"]}, "markerId": {"enum": ["generic", "er", "pr", "ki-67", "her2", "pd-l1", "none"]}, "analysisMode": {"enum": ["marker-aware", "generic-fallback", "generic-descriptive", "special-stain-descriptive", "cytology-descriptive"]}, "cellMaskSource": {"enum": ["hovernet-fast", "pathosam", "od-watershed", "none"]}, "compartmentSource": {"enum": ["none", "faculty-authored", "faculty-approved", "model-suggested"]}, "calibrationStatus": {"enum": ["calibrated", "relative_only", "not_evaluable"]}, "measurements": {"type": "object"}, "qc": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 200}}, "uncertainty": {"type": "number", "minimum": 0, "maximum": 1}, "abstentionReason": {"type": ["string", "null"], "maxLength": 500}, "researchEstimate": {"const": true}}},
+    "signature": {"type": "object", "additionalProperties": false, "required": ["algorithm", "keyId", "value"], "properties": {"algorithm": {"const": "Ed25519"}, "keyId": {"$ref": "#/$defs/sha"}, "value": {"type": "string", "minLength": 1, "maxLength": 1000}}}
+  }
+}