Standardize real-screen evidence manifests without rewriting history

evidence/real-screen/README.md

@@ -0,0 +1,58 @@
+# ĀML™ Real-Screen Evidence Corpus
+
+This directory contains project-authored real-screen experiments. The purpose of the corpus is reproducibility, not promotional proof.
+
+## Canonical manifest for new experiments
+
+New experiments should include a `manifest.json` conforming to:
+
+`schema/real-screen-evidence-manifest.schema.json`
+
+The manifest should identify, without guessing or backfilling unavailable facts:
+
+- experiment identifier;
+- source URL and capture time when known;
+- capture method and provenance;
+- every preserved screen/source artifact and its SHA-256;
+- a separate labels file, its SHA-256, and explicit label provenance;
+- the exact ĀML version or commit and policy used;
+- receipt path, SHA-256, and receipt root when present;
+- whether a deterministic rerun was actually performed and whether it was byte-identical;
+- after-state evidence when captured;
+- an explicit `real_screen_evidence_eligible` boolean;
+- a plain-language claim boundary.
+
+## Evidence boundary
+
+`attention_cost`, `restoration_value`, and similar review labels in this corpus are declared project/operator judgments unless a specific experiment establishes a different provenance. They are not objective measurements of cognition, attention, neurological state, psychology, wellbeing, morality, accessibility outcomes, or clinical outcomes.
+
+A source-code change, successful build, deployment instruction, or business result is not automatically a verified production after-state. Production verification requires its own capture and provenance.
+
+A project-authored experiment is not independent validation. Repository tests, GitHub traffic, clone counts, outreach, and internal reproduction do not establish external adoption.
+
+## Eligibility rule
+
+Set `real_screen_evidence_eligible: true` only when the experiment actually satisfies the project’s stated real-screen evidence requirements, including sufficient capture provenance, hashable artifacts, labels/provenance, exact policy/runtime identification, and reproducible decision evidence.
+
+When evidence is incomplete, preserve it and set the value to `false`. Do not manufacture missing timestamps, screenshots, hashes, browser metadata, or post-deployment observations.
+
+## Legacy experiment directories
+
+Experiments created before this manifest contract may remain in their historical shape. They should be treated as legacy/unmigrated unless and until their existing artifacts can be mapped into `manifest.json` without inventing missing information.
+
+Migration is additive: do not modify historical captured artifacts merely to satisfy the new schema, because doing so would invalidate the very hashes the corpus is intended to preserve.
+
+## Recommended directory shape
+
+```text
+evidence/real-screen/<experiment-id>/
+  README.md
+  manifest.json
+  capture-metadata.json
+  labels.json
+  receipt.json
+  screen.html / screenshot.png / other captured artifacts
+  after/                     # optional, only when actually captured
+```
+
+The manifest is the index. The underlying evidence files remain the evidence.

schema/real-screen-evidence-manifest.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aruintelligence/aml-core/schema/real-screen-evidence-manifest.schema.json",
+  "title": "ĀML Real-Screen Evidence Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "experiment_id",
+    "source",
+    "capture",
+    "labels",
+    "aml",
+    "receipt",
+    "reproducibility",
+    "real_screen_evidence_eligible",
+    "claim_boundary"
+  ],
+  "properties": {
+    "schema": {"const": "aml-real-screen-evidence-manifest/1"},
+    "experiment_id": {"type": "string", "minLength": 1},
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url"],
+      "properties": {
+        "url": {"type": "string", "format": "uri"},
+        "captured_at": {"type": ["string", "null"], "format": "date-time"},
+        "environment": {"type": ["string", "null"]}
+      }
+    },
+    "capture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method", "artifacts"],
+      "properties": {
+        "method": {"type": "string", "minLength": 1},
+        "provenance": {"type": ["string", "null"]},
+        "artifacts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "sha256"],
+            "properties": {
+              "path": {"type": "string", "minLength": 1},
+              "media_type": {"type": ["string", "null"]},
+              "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
+            }
+          }
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256", "provenance"],
+      "properties": {
+        "path": {"type": "string", "minLength": 1},
+        "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "provenance": {"type": "string", "minLength": 1},
+        "measurement_boundary": {"type": ["string", "null"]}
+      }
+    },
+    "aml": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version_or_commit", "policy"],
+      "properties": {
+        "version_or_commit": {"type": "string", "minLength": 1},
+        "policy": {"type": "string", "minLength": 1}
+      }
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"type": "string", "minLength": 1},
+        "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "root": {"type": ["string", "null"]}
+      }
+    },
+    "reproducibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rerun_performed", "byte_identical"],
+      "properties": {
+        "rerun_performed": {"type": "boolean"},
+        "byte_identical": {"type": ["boolean", "null"]},
+        "notes": {"type": ["string", "null"]}
+      }
+    },
+    "after_state": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "captured_at": {"type": ["string", "null"], "format": "date-time"},
+        "artifacts": {"type": "array"},
+        "production_verified": {"type": "boolean"}
+      }
+    },
+    "real_screen_evidence_eligible": {"type": "boolean"},
+    "claim_boundary": {"type": "string", "minLength": 1},
+    "legacy_migration_notes": {"type": ["string", "null"]}
+  }
+}

test/real-screen-evidence-contract.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+
+const schema = JSON.parse(fs.readFileSync('schema/real-screen-evidence-manifest.schema.json', 'utf8'));
+const readme = fs.readFileSync('evidence/real-screen/README.md', 'utf8');
+
+test('real-screen evidence manifest requires provenance, hashes, reproducibility and explicit eligibility', () => {
+  assert.equal(schema.properties.schema.const, 'aml-real-screen-evidence-manifest/1');
+  for (const field of ['source', 'capture', 'labels', 'aml', 'receipt', 'reproducibility', 'real_screen_evidence_eligible', 'claim_boundary']) {
+    assert.ok(schema.required.includes(field), `manifest must require ${field}`);
+  }
+  assert.equal(schema.properties.real_screen_evidence_eligible.type, 'boolean');
+  assert.equal(schema.properties.capture.properties.artifacts.items.properties.sha256.pattern, '^[a-f0-9]{64}$');
+  assert.equal(schema.properties.labels.properties.sha256.pattern, '^[a-f0-9]{64}$');
+  assert.equal(schema.properties.receipt.properties.sha256.pattern, '^[a-f0-9]{64}$');
+});
+
+test('real-screen corpus documentation refuses invented historical evidence and objective cognition claims', () => {
+  assert.match(readme, /Do not manufacture missing timestamps, screenshots, hashes, browser metadata, or post-deployment observations/);
+  assert.match(readme, /not objective measurements of cognition/i);
+  assert.match(readme, /not independent validation/i);
+  assert.match(readme, /legacy\/unmigrated/i);
+});