@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/memory-value-report.js

@@ -1,108 +1,377 @@
+/**
+ * M4 memory value evidence scorer (GitHub Issue #20/#223).
+ *
+ * The scorer is deliberately read-only. It accepts a public fixture or a
+ * private observed cohort manifest and emits one deterministic JSON report.
+ * Synthetic fixtures can prove the contract and calculations, but can never
+ * satisfy M4 Exit. Observed-private inputs only become exit-eligible when a
+ * human source-review attestation contract is present; the scorer validates
+ * that contract shape but does not inspect private raw material.
+ *
+ * Usage:
+ *   npx tsx scripts/memory-value-report.ts data/memory-value-fixture.json
+ */
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+const M4_ACCEPTANCE = {
+    minimumPairCountForExit: 5,
+    targetMedianReductionRatio: 0.5,
+};
+const HMAC_REF = /^hmac-sha256:[0-9a-f]{64}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISO_UTC_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function nonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
-function finiteNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value);
-}
 function round(value) {
     return Math.round((value + Number.EPSILON) * 1_000_000) / 1_000_000;
 }
-function nearestRank(values, percentile) {
-    if (values.length === 0) return 0;
-    const sorted = [
-        ...values
-    ].sort((a, b)=>a - b);
+function nearestRankRaw(values, percentile) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
     const index = Math.max(0, Math.ceil(percentile * sorted.length) - 1);
-    return round(sorted[index]);
+    return sorted[index];
+}
+function nearestRank(values, percentile) {
+    return round(nearestRankRaw(values, percentile));
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (isObject(value)) {
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function memoryValueSummaryDigest(input) {
+    const payload = isObject(input)
+        ? Object.fromEntries(Object.entries(input).filter(([key]) => key !== 'source_review'))
+        : input;
+    return createHash('sha256').update(canonical(payload)).digest('hex');
+}
+function exactKeys(value, label, keys, errors) {
+    const expected = new Set(keys);
+    if (Object.keys(value).some(key => !expected.has(key))) {
+        errors.push(`${label} contains undeclared field(s)`);
+    }
+    if (keys.some(key => !(key in value))) {
+        errors.push(`${label} is missing required field(s)`);
+    }
+}
+function object(value, label, errors) {
+    if (!isObject(value)) {
+        errors.push(`${label} must be an object`);
+        return null;
+    }
+    return value;
+}
+function array(value, label, errors, options = {}) {
+    if (!Array.isArray(value)) {
+        errors.push(`${label} must be an array`);
+        return [];
+    }
+    if (options.nonEmpty && value.length === 0)
+        errors.push(`${label} must be a non-empty array`);
+    return value;
 }
-function parseTimestamp(value, path, errors) {
+function string(value, label, errors) {
     if (!nonEmptyString(value)) {
-        errors.push(`${path} must be a non-empty ISO timestamp`);
+        errors.push(`${label} must be a non-empty string`);
+        return null;
+    }
+    return value;
+}
+function nullableString(value, label, errors) {
+    if (value === null)
+        return null;
+    return string(value, label, errors);
+}
+function boolean(value, label, errors) {
+    if (typeof value !== 'boolean') {
+        errors.push(`${label} must be boolean`);
+        return null;
+    }
+    return value;
+}
+function finiteNumber(value, label, errors) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        errors.push(`${label} must be a finite number`);
         return null;
     }
-    const parsed = Date.parse(value);
+    return value;
+}
+function integer(value, label, errors) {
+    const result = finiteNumber(value, label, errors);
+    if (result === null)
+        return null;
+    if (!Number.isInteger(result)) {
+        errors.push(`${label} must be an integer`);
+        return null;
+    }
+    return result;
+}
+function literal(value, label, allowed, errors) {
+    const result = string(value, label, errors);
+    if (result === null)
+        return null;
+    if (!allowed.includes(result)) {
+        errors.push(`${label} must be one of the declared enum values`);
+        return null;
+    }
+    return result;
+}
+function hmacRef(value, label, errors) {
+    const result = string(value, label, errors);
+    if (result === null)
+        return null;
+    if (!HMAC_REF.test(result)) {
+        errors.push(`${label} must be an hmac-sha256 pseudonymous reference`);
+        return null;
+    }
+    return result;
+}
+function nullableHmacRef(value, label, errors) {
+    if (value === null)
+        return null;
+    return hmacRef(value, label, errors);
+}
+function nullableSha256(value, label, errors) {
+    if (value === null)
+        return null;
+    const result = string(value, label, errors);
+    if (result === null)
+        return null;
+    if (!SHA256.test(result)) {
+        errors.push(`${label} must be a lowercase SHA-256 digest`);
+        return null;
+    }
+    return result;
+}
+function parseTimestamp(value, label, errors) {
+    const result = string(value, label, errors);
+    if (result === null)
+        return null;
+    if (!ISO_UTC_TIMESTAMP.test(result)) {
+        errors.push(`${label} must be a strict UTC ISO timestamp`);
+        return null;
+    }
+    const parsed = Date.parse(result);
     if (!Number.isFinite(parsed)) {
-        errors.push(`${path} is not a valid ISO timestamp`);
+        errors.push(`${label} must be a valid UTC ISO timestamp`);
         return null;
     }
-    return parsed;
+    const canonical = new Date(parsed).toISOString();
+    const normalized = result.includes('.') ? result : result.replace('Z', '.000Z');
+    if (canonical !== normalized) {
+        errors.push(`${label} must be a valid UTC ISO timestamp`);
+        return null;
+    }
+    return { text: result, ms: parsed };
 }
-function scoreFlow(value, path, expectedEligibleIndex, allowedWaitCodes, errors) {
-    if (!isObject(value)) {
-        errors.push(`${path} must be an object`);
+function nullableTimestamp(value, label, errors) {
+    if (value === null)
+        return null;
+    return parseTimestamp(value, label, errors);
+}
+function assertUnique(value, seen, label, errors) {
+    if (value === null)
+        return;
+    if (seen.has(value))
+        errors.push(`${label} must be unique`);
+    else
+        seen.add(value);
+}
+function waitCode(value, label, allowedWaitCodes, errors) {
+    const code = string(value, label, errors);
+    if (code === null)
+        return null;
+    if (!/^[a-z][a-z0-9_]{0,31}$/.test(code) || !allowedWaitCodes.has(code)) {
+        errors.push(`${label} must be predeclared by measurement_policy`);
         return null;
     }
-    const flowId = value.flow_id;
-    if (!nonEmptyString(flowId)) errors.push(`${path}.flow_id must be non-empty`);
-    if (value.eligible !== true) errors.push(`${path}.eligible must be true`);
-    if (value.status !== 'completed') errors.push(`${path}.status must be completed`);
-    if (value.eligible_planning_index !== expectedEligibleIndex) {
-        errors.push(`${path}.eligible_planning_index must be ${expectedEligibleIndex}`);
-    }
-    const startedAtMs = parseTimestamp(value.started_at, `${path}.started_at`, errors);
-    const completedAtMs = parseTimestamp(value.completed_at, `${path}.completed_at`, errors);
-    if (startedAtMs === null || completedAtMs === null) return null;
-    if (completedAtMs <= startedAtMs) {
-        errors.push(`${path}.completed_at must be after started_at`);
+    return code;
+}
+function scoreFlow(value, path, expectedEligibleIndex, allowedWaitCodes, errors) {
+    const raw = object(value, path, errors);
+    if (raw === null)
         return null;
+    exactKeys(raw, path, ['flow_id', 'eligible_planning_index', 'eligible', 'status', 'started_at', 'completed_at', 'external_waits'], errors);
+    const flowId = hmacRef(raw.flow_id, `${path}.flow_id`, errors);
+    const eligible = boolean(raw.eligible, `${path}.eligible`, errors);
+    if (eligible !== true)
+        errors.push(`${path}.eligible must be true`);
+    literal(raw.status, `${path}.status`, ['completed'], errors);
+    const eligiblePlanningIndex = integer(raw.eligible_planning_index, `${path}.eligible_planning_index`, errors);
+    if (eligiblePlanningIndex !== null && eligiblePlanningIndex !== expectedEligibleIndex) {
+        errors.push(`${path}.eligible_planning_index must match the paired flow position`);
     }
-    const rawWaits = value.external_waits;
-    if (!Array.isArray(rawWaits)) {
-        errors.push(`${path}.external_waits must be an array`);
+    const startedAt = parseTimestamp(raw.started_at, `${path}.started_at`, errors);
+    const completedAt = parseTimestamp(raw.completed_at, `${path}.completed_at`, errors);
+    if (startedAt === null || completedAt === null)
+        return null;
+    if (completedAt.ms <= startedAt.ms) {
+        errors.push(`${path}.completed_at must be after started_at`);
         return null;
     }
     const waits = [];
-    for (const [index, rawWait] of rawWaits.entries()){
+    for (const [index, rawWait] of array(raw.external_waits, `${path}.external_waits`, errors).entries()) {
         const waitPath = `${path}.external_waits[${index}]`;
-        if (!isObject(rawWait)) {
-            errors.push(`${waitPath} must be an object`);
+        const wait = object(rawWait, waitPath, errors);
+        if (wait === null)
             continue;
-        }
-        const code = rawWait.code;
-        if (!nonEmptyString(code) || !allowedWaitCodes.has(code)) {
-            errors.push(`${waitPath}.code must be predeclared by measurement_policy`);
+        exactKeys(wait, waitPath, ['code', 'started_at', 'completed_at'], errors);
+        const code = waitCode(wait.code, `${waitPath}.code`, allowedWaitCodes, errors);
+        const waitStartedAt = parseTimestamp(wait.started_at, `${waitPath}.started_at`, errors);
+        const waitCompletedAt = parseTimestamp(wait.completed_at, `${waitPath}.completed_at`, errors);
+        if (code === null || waitStartedAt === null || waitCompletedAt === null)
             continue;
-        }
-        const waitStartedAtMs = parseTimestamp(rawWait.started_at, `${waitPath}.started_at`, errors);
-        const waitCompletedAtMs = parseTimestamp(rawWait.completed_at, `${waitPath}.completed_at`, errors);
-        if (waitStartedAtMs === null || waitCompletedAtMs === null) continue;
-        if (waitCompletedAtMs <= waitStartedAtMs) {
+        if (waitCompletedAt.ms <= waitStartedAt.ms) {
             errors.push(`${waitPath}.completed_at must be after started_at`);
             continue;
         }
-        if (waitStartedAtMs < startedAtMs || waitCompletedAtMs > completedAtMs) {
+        if (waitStartedAt.ms < startedAt.ms || waitCompletedAt.ms > completedAt.ms) {
             errors.push(`${waitPath} must stay inside the planning flow`);
             continue;
         }
-        waits.push({
-            code,
-            startedAtMs: waitStartedAtMs,
-            completedAtMs: waitCompletedAtMs
-        });
-    }
-    waits.sort((a, b)=>a.startedAtMs - b.startedAtMs);
-    for(let index = 1; index < waits.length; index += 1){
+        waits.push({ code, startedAtMs: waitStartedAt.ms, completedAtMs: waitCompletedAt.ms });
+    }
+    waits.sort((a, b) => a.startedAtMs - b.startedAtMs);
+    for (let index = 1; index < waits.length; index += 1) {
         if (waits[index].startedAtMs < waits[index - 1].completedAtMs) {
             errors.push(`${path}.external_waits must not overlap`);
         }
     }
-    const externalWaitMs = waits.reduce((total, wait)=>total + wait.completedAtMs - wait.startedAtMs, 0);
-    const activeSeconds = (completedAtMs - startedAtMs - externalWaitMs) / 1_000;
-    if (activeSeconds <= 0) errors.push(`${path} must have positive active planning duration`);
-    return nonEmptyString(flowId) ? {
-        activeSeconds: round(activeSeconds),
-        completedAtMs,
-        flowId,
-        startedAtMs
-    } : null;
+    const externalWaitMs = waits.reduce((total, wait) => total + wait.completedAtMs - wait.startedAtMs, 0);
+    const activeSeconds = (completedAt.ms - startedAt.ms - externalWaitMs) / 1_000;
+    if (activeSeconds <= 0)
+        errors.push(`${path} must have positive active planning duration`);
+    return flowId === null
+        ? null
+        : { activeSeconds, completedAtMs: completedAt.ms, flowId, startedAtMs: startedAt.ms };
 }
-function invalidReport(errors, schema = '', evidenceKind = '') {
+function sourceReviewReport(evidenceKind, state, contractMet, fields = {}) {
+    const shared = {
+        reviewed_at: fields.reviewedAt ?? null,
+        reviewer_ref: fields.reviewerRef ?? null,
+        attestation_ref: fields.attestationRef ?? null,
+        private_source_digest_sha256: fields.privateSourceDigest ?? null,
+        reviewed_summary_digest_sha256: fields.reviewedSummaryDigest ?? null,
+        current_summary_digest_sha256: fields.currentSummaryDigest ?? null,
+    };
+    if (evidenceKind === 'synthetic_fixture') {
+        return {
+            required_for_exit: false,
+            state,
+            contract_met: false,
+            provenance_verified_by_scorer: false,
+            ...shared,
+            reason: 'synthetic_fixture validates formulas only and is never business evidence',
+        };
+    }
+    if (contractMet) {
+        return {
+            required_for_exit: true,
+            state,
+            contract_met: true,
+            provenance_verified_by_scorer: false,
+            ...shared,
+            reason: 'manual source-review attestation contract is present for this scoring payload; raw private source review remains a human responsibility',
+        };
+    }
+    return {
+        required_for_exit: evidenceKind === 'observed_private',
+        state,
+        contract_met: false,
+        provenance_verified_by_scorer: false,
+        ...shared,
+        reason: evidenceKind === 'observed_private'
+            ? 'observed_private remains a candidate until the manual source-review attestation contract matches this scoring payload'
+            : 'source kind is not exit-eligible',
+    };
+}
+function scoreSourceReview(value, evidenceKind, currentSummaryDigest, errors) {
+    const raw = object(value, 'source_review', errors);
+    if (raw === null) {
+        return { report: sourceReviewReport(evidenceKind, 'unknown', false, { currentSummaryDigest }) };
+    }
+    exactKeys(raw, 'source_review', [
+        'schema_version',
+        'state',
+        'reviewed_at',
+        'reviewer_ref',
+        'attestation_ref',
+        'private_source_digest_sha256',
+        'reviewed_summary_digest_sha256',
+        'checks',
+    ], errors);
+    literal(raw.schema_version, 'source_review.schema_version', ['memory_value_source_review.v1'], errors);
+    const state = literal(raw.state, 'source_review.state', ['not_required_for_synthetic', 'candidate', 'manual_attested'], errors) ?? 'unknown';
+    const reviewedAt = nullableTimestamp(raw.reviewed_at, 'source_review.reviewed_at', errors);
+    const reviewerRef = nullableHmacRef(raw.reviewer_ref, 'source_review.reviewer_ref', errors);
+    const attestationRef = nullableHmacRef(raw.attestation_ref, 'source_review.attestation_ref', errors);
+    const privateSourceDigest = nullableSha256(raw.private_source_digest_sha256, 'source_review.private_source_digest_sha256', errors);
+    const reviewedSummaryDigest = nullableSha256(raw.reviewed_summary_digest_sha256, 'source_review.reviewed_summary_digest_sha256', errors);
+    if (reviewedSummaryDigest !== null && reviewedSummaryDigest !== currentSummaryDigest) {
+        errors.push('source_review.reviewed_summary_digest_sha256 must match the current scoring payload digest');
+    }
+    const checks = object(raw.checks, 'source_review.checks', errors);
+    const parsedChecks = {};
+    if (checks !== null) {
+        exactKeys(checks, 'source_review.checks', [
+            'raw_private_material_excluded',
+            'paired_cohort_source_reviewed',
+            'summary_matches_private_source',
+            'no_synthetic_or_test_subjects',
+        ], errors);
+        for (const key of [
+            'raw_private_material_excluded',
+            'paired_cohort_source_reviewed',
+            'summary_matches_private_source',
+            'no_synthetic_or_test_subjects',
+        ]) {
+            const parsed = boolean(checks[key], `source_review.checks.${key}`, errors);
+            if (parsed !== null)
+                parsedChecks[key] = parsed;
+        }
+    }
+    if (evidenceKind === 'synthetic_fixture' && state !== 'not_required_for_synthetic') {
+        errors.push('source_review.state must match synthetic evidence');
+    }
+    if (evidenceKind === 'observed_private' && state === 'not_required_for_synthetic') {
+        errors.push('source_review.state must require observed private review');
+    }
+    const allReviewChecksMet = [
+        parsedChecks.raw_private_material_excluded,
+        parsedChecks.paired_cohort_source_reviewed,
+        parsedChecks.summary_matches_private_source,
+        parsedChecks.no_synthetic_or_test_subjects,
+    ].every(Boolean);
+    const contractMet = evidenceKind === 'observed_private'
+        && state === 'manual_attested'
+        && reviewedAt !== null
+        && reviewerRef !== null
+        && attestationRef !== null
+        && privateSourceDigest !== null
+        && reviewedSummaryDigest === currentSummaryDigest
+        && allReviewChecksMet;
+    return {
+        report: sourceReviewReport(evidenceKind, state, contractMet, {
+            reviewedAt: reviewedAt?.text ?? null,
+            reviewerRef,
+            attestationRef,
+            privateSourceDigest,
+            reviewedSummaryDigest,
+            currentSummaryDigest,
+        }),
+    };
+}
+function invalidReport(errors, schema = '', evidenceKind = '', sourceReview = sourceReviewReport(evidenceKind || null, 'unknown', false)) {
     return {
         schema: 'memory_value_report.v1',
         contract_valid: false,
@@ -111,91 +380,75 @@ function invalidReport(errors, schema = '', evidenceKind = '') {
             fixture_schema: schema,
             evidence_kind: evidenceKind,
             quantile_method: 'nearest_rank',
-            active_duration_rule: 'wall_clock_minus_non_overlapping_predeclared_external_waits'
+            active_duration_rule: 'wall_clock_minus_non_overlapping_predeclared_external_waits',
+            id_format: 'hmac-sha256:<64lowerhex>',
+            source_review: sourceReview,
         },
         cohort: {
             eligible_pair_count: 0,
-            first_active_seconds: {
-                p50: 0,
-                p75: 0
-            },
-            returning_active_seconds: {
-                p50: 0,
-                p75: 0
-            },
-            paired_reduction_ratio: {
-                p50: 0,
-                p75: 0
-            },
+            first_active_seconds: { p50: 0, p75: 0 },
+            returning_active_seconds: { p50: 0, p75: 0 },
+            paired_reduction_ratio: { p50: 0, p75: 0 },
             target_median_reduction_ratio: 0,
             target_met: false,
             minimum_pair_count_for_exit: 0,
-            sample_size_met: false
+            sample_size_met: false,
         },
         experience_reflux: {
             recalled_experience_count: 0,
             verified_experience_count: 0,
             baseline: null,
             baseline_available: false,
-            real_evidence: false
+            real_evidence: false,
         },
         preference_assertions: {
             total_count: 0,
             traceable_count: 0,
             traceable_ratio: 0,
             hard_filter_violation_count: 0,
-            contract_met: false
-        },
-        p4: {
-            state: 'unknown',
-            trigger_observed: false,
-            contract_met: false
+            contract_met: false,
         },
+        p4: { state: 'unknown', trigger_observed: false, contract_met: false },
         exit_evidence_eligible: false,
-        exit_ready: false
+        exit_ready: false,
     };
 }
 export function scoreMemoryValue(input) {
     const errors = [];
-    if (!isObject(input)) return invalidReport([
-        'root must be an object'
-    ]);
-    const schema = nonEmptyString(input.schema) ? input.schema : '';
-    const evidenceKind = nonEmptyString(input.evidence_kind) ? input.evidence_kind : '';
-    if (schema !== 'memory_value_fixture.v1') errors.push('schema must be memory_value_fixture.v1');
-    if (![
-        'synthetic_fixture',
-        'observed_private'
-    ].includes(evidenceKind)) {
-        errors.push('evidence_kind must be synthetic_fixture or observed_private');
-    }
-    const policy = input.measurement_policy;
-    if (!isObject(policy)) return invalidReport([
-        ...errors,
-        'measurement_policy must be an object'
-    ], schema, evidenceKind);
-    if (policy.quantile_method !== 'nearest_rank') errors.push('measurement_policy.quantile_method must be nearest_rank');
-    const rawWaitCodes = policy.predeclared_external_wait_codes;
+    if (!isObject(input))
+        return invalidReport(['root must be an object']);
+    exactKeys(input, 'root', ['schema', 'evidence_kind', 'source_review', 'measurement_policy', 'pairs', 'experience_reflux_events', 'preference_assertions', 'p4'], errors);
+    const currentSummaryDigest = memoryValueSummaryDigest(input);
+    const schema = literal(input.schema, 'schema', ['memory_value_fixture.v1'], errors);
+    const evidenceKind = literal(input.evidence_kind, 'evidence_kind', ['synthetic_fixture', 'observed_private'], errors);
+    const sourceReview = scoreSourceReview(input.source_review, evidenceKind, currentSummaryDigest, errors).report;
+    const policy = object(input.measurement_policy, 'measurement_policy', errors);
     const allowedWaitCodes = new Set();
-    if (!Array.isArray(rawWaitCodes) || rawWaitCodes.length === 0) {
-        errors.push('measurement_policy.predeclared_external_wait_codes must be a non-empty array');
-    } else {
-        for (const code of rawWaitCodes){
-            if (nonEmptyString(code)) allowedWaitCodes.add(code);
-            else errors.push('measurement_policy.predeclared_external_wait_codes must contain non-empty strings');
+    if (policy !== null) {
+        exactKeys(policy, 'measurement_policy', [
+            'quantile_method',
+            'predeclared_external_wait_codes',
+            'minimum_pair_count_for_exit',
+            'target_median_reduction_ratio',
+        ], errors);
+        literal(policy.quantile_method, 'measurement_policy.quantile_method', ['nearest_rank'], errors);
+        for (const code of array(policy.predeclared_external_wait_codes, 'measurement_policy.predeclared_external_wait_codes', errors, { nonEmpty: true })) {
+            if (!nonEmptyString(code) || !/^[a-z][a-z0-9_]{0,31}$/.test(code)) {
+                errors.push('measurement_policy.predeclared_external_wait_codes must contain declared wait-code strings');
+                continue;
+            }
+            if (allowedWaitCodes.has(code))
+                errors.push('measurement_policy.predeclared_external_wait_codes must not contain duplicates');
+            allowedWaitCodes.add(code);
+        }
+        const minimumPairCount = integer(policy.minimum_pair_count_for_exit, 'measurement_policy.minimum_pair_count_for_exit', errors);
+        if (minimumPairCount !== null && minimumPairCount !== M4_ACCEPTANCE.minimumPairCountForExit) {
+            errors.push(`measurement_policy.minimum_pair_count_for_exit is frozen at ${M4_ACCEPTANCE.minimumPairCountForExit}`);
+        }
+        const targetReduction = finiteNumber(policy.target_median_reduction_ratio, 'measurement_policy.target_median_reduction_ratio', errors);
+        if (targetReduction !== null && targetReduction !== M4_ACCEPTANCE.targetMedianReductionRatio) {
+            errors.push(`measurement_policy.target_median_reduction_ratio is frozen at ${M4_ACCEPTANCE.targetMedianReductionRatio}`);
         }
-    }
-    const minimumPairCount = policy.minimum_pair_count_for_exit;
-    const targetReduction = policy.target_median_reduction_ratio;
-    if (!Number.isInteger(minimumPairCount) || minimumPairCount <= 0) {
-        errors.push('measurement_policy.minimum_pair_count_for_exit must be a positive integer');
-    }
-    if (!finiteNumber(targetReduction) || targetReduction < 0 || targetReduction > 1) {
-        errors.push('measurement_policy.target_median_reduction_ratio must be between 0 and 1');
-    }
-    const rawPairs = input.pairs;
-    if (!Array.isArray(rawPairs) || rawPairs.length === 0) {
-        errors.push('pairs must be a non-empty array');
     }
     const firstDurations = [];
     const returningDurations = [];
@@ -203,103 +456,110 @@ export function scoreMemoryValue(input) {
     const pairIds = new Set();
     const subjectRefs = new Set();
     const flowIds = new Set();
-    for (const [index, rawPair] of (Array.isArray(rawPairs) ? rawPairs : []).entries()){
+    for (const [index, rawPair] of array(input.pairs, 'pairs', errors, { nonEmpty: true }).entries()) {
         const pairPath = `pairs[${index}]`;
-        if (!isObject(rawPair)) {
-            errors.push(`${pairPath} must be an object`);
+        const pair = object(rawPair, pairPath, errors);
+        if (pair === null)
             continue;
+        exactKeys(pair, pairPath, ['pair_id', 'subject_ref', 'first', 'returning'], errors);
+        const pairId = hmacRef(pair.pair_id, `${pairPath}.pair_id`, errors);
+        const subjectRef = hmacRef(pair.subject_ref, `${pairPath}.subject_ref`, errors);
+        assertUnique(pairId, pairIds, `${pairPath}.pair_id`, errors);
+        assertUnique(subjectRef, subjectRefs, `${pairPath}.subject_ref`, errors);
+        const first = scoreFlow(pair.first, `${pairPath}.first`, 1, allowedWaitCodes, errors);
+        const returning = scoreFlow(pair.returning, `${pairPath}.returning`, 2, allowedWaitCodes, errors);
+        for (const flow of [first, returning]) {
+            if (!flow)
+                continue;
+            assertUnique(flow.flowId, flowIds, `${pairPath}.flow_id`, errors);
         }
-        if (!nonEmptyString(rawPair.pair_id)) errors.push(`${pairPath}.pair_id must be non-empty`);
-        else if (pairIds.has(rawPair.pair_id)) errors.push(`${pairPath}.pair_id must be unique`);
-        else pairIds.add(rawPair.pair_id);
-        if (!nonEmptyString(rawPair.subject_ref)) {
-            errors.push(`${pairPath}.subject_ref must be a non-empty pseudonymous reference`);
-        } else if (subjectRefs.has(rawPair.subject_ref)) {
-            errors.push(`${pairPath}.subject_ref must be unique across the paired cohort`);
-        } else {
-            subjectRefs.add(rawPair.subject_ref);
-        }
-        const first = scoreFlow(rawPair.first, `${pairPath}.first`, 1, allowedWaitCodes, errors);
-        const returning = scoreFlow(rawPair.returning, `${pairPath}.returning`, 2, allowedWaitCodes, errors);
-        for (const flow of [
-            first,
-            returning
-        ]){
-            if (!flow) continue;
-            if (flowIds.has(flow.flowId)) errors.push(`${pairPath} flow_id values must be globally unique`);
-            flowIds.add(flow.flowId);
-        }
-        if (!first || !returning || first.activeSeconds <= 0 || returning.activeSeconds <= 0) continue;
+        if (!first || !returning || first.activeSeconds <= 0 || returning.activeSeconds <= 0)
+            continue;
         if (returning.startedAtMs <= first.completedAtMs) {
             errors.push(`${pairPath}.returning must start after the first completed flow`);
         }
         firstDurations.push(first.activeSeconds);
         returningDurations.push(returning.activeSeconds);
-        reductions.push(round((first.activeSeconds - returning.activeSeconds) / first.activeSeconds));
+        reductions.push((first.activeSeconds - returning.activeSeconds) / first.activeSeconds);
     }
-    const rawRefluxEvents = input.experience_reflux_events;
-    if (!Array.isArray(rawRefluxEvents)) errors.push('experience_reflux_events must be an array');
     const recalled = new Set();
     const verified = new Set();
-    for (const [index, rawEvent] of (Array.isArray(rawRefluxEvents) ? rawRefluxEvents : []).entries()){
+    const refluxEventKeys = new Set();
+    const refluxEvidenceRefs = new Set();
+    for (const [index, rawEvent] of array(input.experience_reflux_events, 'experience_reflux_events', errors).entries()) {
         const eventPath = `experience_reflux_events[${index}]`;
-        if (!isObject(rawEvent)) {
-            errors.push(`${eventPath} must be an object`);
+        const event = object(rawEvent, eventPath, errors);
+        if (event === null)
             continue;
-        }
-        if (!nonEmptyString(rawEvent.experience_id)) {
-            errors.push(`${eventPath}.experience_id must be non-empty`);
+        exactKeys(event, eventPath, ['experience_id', 'kind', 'evidence_ref'], errors);
+        const experienceId = hmacRef(event.experience_id, `${eventPath}.experience_id`, errors);
+        const kind = literal(event.kind, `${eventPath}.kind`, ['recalled', 'verified_outcome'], errors);
+        const evidenceRef = hmacRef(event.evidence_ref, `${eventPath}.evidence_ref`, errors);
+        assertUnique(evidenceRef, refluxEvidenceRefs, `${eventPath}.evidence_ref`, errors);
+        if (experienceId === null || kind === null)
             continue;
-        }
-        if (!nonEmptyString(rawEvent.evidence_ref)) errors.push(`${eventPath}.evidence_ref must be non-empty`);
-        if (rawEvent.kind === 'recalled') recalled.add(rawEvent.experience_id);
-        else if (rawEvent.kind === 'verified_outcome') verified.add(rawEvent.experience_id);
-        else errors.push(`${eventPath}.kind must be recalled or verified_outcome`);
+        assertUnique(`${kind}:${experienceId}`, refluxEventKeys, `${eventPath}.experience_id+kind`, errors);
+        if (kind === 'recalled')
+            recalled.add(experienceId);
+        else
+            verified.add(experienceId);
     }
-    for (const experienceId of verified){
-        if (!recalled.has(experienceId)) errors.push(`verified experience ${experienceId} must have a recalled event`);
+    for (const experienceId of verified) {
+        if (!recalled.has(experienceId))
+            errors.push('each verified_outcome experience must have a recalled event');
     }
-    const verifiedRecalledCount = [
-        ...verified
-    ].filter((id)=>recalled.has(id)).length;
+    const verifiedRecalledCount = [...verified].filter(id => recalled.has(id)).length;
     const refluxBaseline = recalled.size > 0 ? round(verifiedRecalledCount / recalled.size) : null;
-    const rawAssertions = input.preference_assertions;
-    if (!Array.isArray(rawAssertions)) errors.push('preference_assertions must be an array');
+    const assertionsRaw = array(input.preference_assertions, 'preference_assertions', errors);
     let traceableCount = 0;
     let hardFilterViolationCount = 0;
-    const assertions = Array.isArray(rawAssertions) ? rawAssertions : [];
-    for (const [index, rawAssertion] of assertions.entries()){
+    const assertionIds = new Set();
+    for (const [index, rawAssertion] of assertionsRaw.entries()) {
         const assertionPath = `preference_assertions[${index}]`;
-        if (!isObject(rawAssertion)) {
-            errors.push(`${assertionPath} must be an object`);
+        const assertion = object(rawAssertion, assertionPath, errors);
+        if (assertion === null)
             continue;
-        }
-        if (!nonEmptyString(rawAssertion.assertion_id)) errors.push(`${assertionPath}.assertion_id must be non-empty`);
-        if (nonEmptyString(rawAssertion.evidence_ref)) traceableCount += 1;
-        if (rawAssertion.hard_filter === true || rawAssertion.consumer === 'hard_filter') hardFilterViolationCount += 1;
+        exactKeys(assertion, assertionPath, ['assertion_id', 'evidence_ref', 'consumer', 'hard_filter'], errors);
+        const assertionId = hmacRef(assertion.assertion_id, `${assertionPath}.assertion_id`, errors);
+        const evidenceRef = hmacRef(assertion.evidence_ref, `${assertionPath}.evidence_ref`, errors);
+        const consumer = literal(assertion.consumer, `${assertionPath}.consumer`, ['ranking', 'explanation', 'hard_filter'], errors);
+        const hardFilter = boolean(assertion.hard_filter, `${assertionPath}.hard_filter`, errors);
+        assertUnique(assertionId, assertionIds, `${assertionPath}.assertion_id`, errors);
+        if (evidenceRef !== null)
+            traceableCount += 1;
+        if (hardFilter === true || consumer === 'hard_filter')
+            hardFilterViolationCount += 1;
     }
-    const traceableRatio = assertions.length > 0 ? round(traceableCount / assertions.length) : 0;
-    const assertionContractMet = assertions.length > 0 && traceableRatio === 1 && hardFilterViolationCount === 0;
-    const rawP4 = input.p4;
+    const traceableRatio = assertionsRaw.length > 0 ? round(traceableCount / assertionsRaw.length) : 0;
+    const assertionContractMet = assertionsRaw.length > 0 && traceableRatio === 1 && hardFilterViolationCount === 0;
     let p4State = 'unknown';
     let p4TriggerObserved = false;
-    if (!isObject(rawP4) || !isObject(rawP4.triggers)) {
-        errors.push('p4.state and p4.triggers must be declared');
-    } else {
-        if (nonEmptyString(rawP4.state)) p4State = rawP4.state;
-        else errors.push('p4.state must be non-empty');
-        p4TriggerObserved = rawP4.triggers.real_usage === true || rawP4.triggers.multi_user === true;
+    const rawP4 = object(input.p4, 'p4', errors);
+    if (rawP4 !== null) {
+        exactKeys(rawP4, 'p4', ['state', 'triggers'], errors);
+        p4State = literal(rawP4.state, 'p4.state', ['closed', 'open'], errors) ?? 'unknown';
+        const triggers = object(rawP4.triggers, 'p4.triggers', errors);
+        if (triggers !== null) {
+            exactKeys(triggers, 'p4.triggers', ['real_usage', 'multi_user'], errors);
+            const realUsage = boolean(triggers.real_usage, 'p4.triggers.real_usage', errors);
+            const multiUser = boolean(triggers.multi_user, 'p4.triggers.multi_user', errors);
+            p4TriggerObserved = realUsage === true || multiUser === true;
+        }
     }
     const p4ContractMet = p4TriggerObserved || p4State === 'closed';
-    if (errors.length > 0) return invalidReport(errors, schema, evidenceKind);
-    const medianReduction = nearestRank(reductions, 0.5);
-    const numericMinimumPairCount = minimumPairCount;
-    const numericTargetReduction = targetReduction;
-    const sampleSizeMet = firstDurations.length >= numericMinimumPairCount;
-    const targetMet = medianReduction >= numericTargetReduction;
-    const exitEvidenceEligible = evidenceKind === 'observed_private';
+    if (errors.length > 0)
+        return invalidReport(errors, schema ?? '', evidenceKind ?? '', sourceReview);
+    const medianReduction = nearestRankRaw(reductions, 0.5);
+    const sampleSizeMet = firstDurations.length >= M4_ACCEPTANCE.minimumPairCountForExit;
+    const targetMet = medianReduction >= M4_ACCEPTANCE.targetMedianReductionRatio;
+    const sourceEvidenceEligible = evidenceKind === 'observed_private' && sourceReview.contract_met;
     const baselineAvailable = refluxBaseline !== null;
-    const exitReady = exitEvidenceEligible && sampleSizeMet && targetMet && baselineAvailable && assertionContractMet && p4ContractMet;
+    const exitReady = sourceEvidenceEligible
+        && sampleSizeMet
+        && targetMet
+        && baselineAvailable
+        && assertionContractMet
+        && p4ContractMet;
     return {
         schema: 'memory_value_report.v1',
         contract_valid: true,
@@ -308,48 +568,41 @@ export function scoreMemoryValue(input) {
             fixture_schema: schema,
             evidence_kind: evidenceKind,
             quantile_method: 'nearest_rank',
-            active_duration_rule: 'wall_clock_minus_non_overlapping_predeclared_external_waits'
+            active_duration_rule: 'wall_clock_minus_non_overlapping_predeclared_external_waits',
+            id_format: 'hmac-sha256:<64lowerhex>',
+            source_review: sourceReview,
         },
         cohort: {
             eligible_pair_count: firstDurations.length,
-            first_active_seconds: {
-                p50: nearestRank(firstDurations, 0.5),
-                p75: nearestRank(firstDurations, 0.75)
-            },
-            returning_active_seconds: {
-                p50: nearestRank(returningDurations, 0.5),
-                p75: nearestRank(returningDurations, 0.75)
-            },
-            paired_reduction_ratio: {
-                p50: medianReduction,
-                p75: nearestRank(reductions, 0.75)
-            },
-            target_median_reduction_ratio: numericTargetReduction,
+            first_active_seconds: { p50: nearestRank(firstDurations, 0.5), p75: nearestRank(firstDurations, 0.75) },
+            returning_active_seconds: { p50: nearestRank(returningDurations, 0.5), p75: nearestRank(returningDurations, 0.75) },
+            paired_reduction_ratio: { p50: round(medianReduction), p75: nearestRank(reductions, 0.75) },
+            target_median_reduction_ratio: M4_ACCEPTANCE.targetMedianReductionRatio,
             target_met: targetMet,
-            minimum_pair_count_for_exit: numericMinimumPairCount,
-            sample_size_met: sampleSizeMet
+            minimum_pair_count_for_exit: M4_ACCEPTANCE.minimumPairCountForExit,
+            sample_size_met: sampleSizeMet,
         },
         experience_reflux: {
             recalled_experience_count: recalled.size,
             verified_experience_count: verifiedRecalledCount,
             baseline: refluxBaseline,
             baseline_available: baselineAvailable,
-            real_evidence: exitEvidenceEligible
+            real_evidence: sourceEvidenceEligible,
         },
         preference_assertions: {
-            total_count: assertions.length,
+            total_count: assertionsRaw.length,
             traceable_count: traceableCount,
             traceable_ratio: traceableRatio,
             hard_filter_violation_count: hardFilterViolationCount,
-            contract_met: assertionContractMet
+            contract_met: assertionContractMet,
         },
         p4: {
             state: p4State,
             trigger_observed: p4TriggerObserved,
-            contract_met: p4ContractMet
+            contract_met: p4ContractMet,
         },
-        exit_evidence_eligible: exitEvidenceEligible,
-        exit_ready: exitReady
+        exit_evidence_eligible: sourceEvidenceEligible,
+        exit_ready: exitReady,
     };
 }
 function main() {
@@ -362,18 +615,17 @@ function main() {
     let input;
     try {
         input = JSON.parse(readFileSync(resolve(inputPath), 'utf8'));
-    } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        console.error(`cannot read memory value input: ${message}`);
+    }
+    catch {
+        console.error('MEMORY_VALUE_INPUT_INVALID: input file could not be read or parsed');
         process.exitCode = 2;
         return;
     }
     const report = scoreMemoryValue(input);
     console.log(JSON.stringify(report, null, 2));
-    if (!report.contract_valid) process.exitCode = 2;
+    if (!report.contract_valid)
+        process.exitCode = 2;
 }
 const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
-if (import.meta.url === invokedPath) main();
-
-
-//# sourceURL=ts/scripts/memory-value-report.ts
+if (import.meta.url === invokedPath)
+    main();