@litfamily/litopencode 1.0.0

package/qa/harness-speed-contract.mjs

@@ -0,0 +1,209 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateHarnessSpeedRecords } from "./harness-speed-verdict.mjs";
+
+const SCHEMA = "litfamily.harness-speed/v1";
+const SCENARIO_ID = "litfamily-speed-lit-activation-v1";
+const PRODUCT = "litopencode";
+const SCENARIO_BYTES = 1476;
+const SCENARIO_SHA256 = "aaef5ba778532013248f0b5c0a9f958468786840595e48cb84851ab88bf2b4be";
+const ARMS = ["baseline", "candidate", "control"];
+const PHASES = ["B0", "S1", "S2"];
+const COUNTERS = ["input_tokens", "cache_read_tokens", "cache_write_tokens", "output_tokens"];
+const FAILURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/u;
+const REQUIRED_FIELDS = [
+  "schema", "scenario_id", "product", "arm", "block", "order", "sequence", "phase",
+  "prompt_bytes", "prompt_sha256", "response_bytes", "response_sha256", "sentinel_match",
+  "route_observed", "output_policy_match", "correct", "failure_code", "timed_out",
+  "start_offset_ms", "first_content_offset_ms", "final_receipt_offset_ms", "exit_offset_ms",
+  ...COUNTERS
+];
+const FORBIDDEN_FIELDS = new Set([
+  "prompt", "response", "transcript", "url", "request_id", "thread_id", "session_id",
+  "credential", "authorization", "cookie", "api_key"
+]);
+const UNAVAILABLE = "UNAVAILABLE";
+
+export class HarnessSpeedContractError extends Error {
+  constructor(code, field = null) {
+    super(field === null ? code : `${code}:${field}`);
+    this.name = "HarnessSpeedContractError";
+    this.code = code;
+    this.field = field;
+  }
+}
+
+function reject(code, field = null) {
+  throw new HarnessSpeedContractError(code, field);
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertPrivacy(value, location = "cohort") {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertPrivacy(entry, `${location}[${index}]`));
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, entry] of Object.entries(value)) {
+    if (FORBIDDEN_FIELDS.has(key.toLowerCase())) reject("FORBIDDEN_FIELD", `${location}.${key}`);
+    assertPrivacy(entry, `${location}.${key}`);
+  }
+}
+
+function assertSafeCounter(value, field) {
+  if (value === UNAVAILABLE) return;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) reject("INVALID_COUNTER", field);
+  if (!Number.isSafeInteger(value)) reject("UNSAFE_COUNTER", field);
+}
+
+function assertOffset(value, field, unavailableAllowed = false) {
+  if (unavailableAllowed && value === UNAVAILABLE) return;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) reject("INVALID_TIME", field);
+}
+
+function phaseMap(scenario) {
+  if (!isObject(scenario) || !Array.isArray(scenario.records) || scenario.scenario_id !== SCENARIO_ID) {
+    reject("INVALID_SCENARIO");
+  }
+  return new Map(scenario.records.map((record) => [record.id, record]));
+}
+
+function validateRecord(record, index, scenarioPhases) {
+  const location = `records[${index}]`;
+  if (!isObject(record)) reject("INVALID_RECORD", location);
+  for (const field of REQUIRED_FIELDS) {
+    if (!Object.hasOwn(record, field)) reject("MISSING_RECORD_FIELD", `${location}.${field}`);
+  }
+  if (record.schema !== SCHEMA || record.scenario_id !== SCENARIO_ID || record.product !== PRODUCT) {
+    reject("RECORD_IDENTITY_MISMATCH", location);
+  }
+  if (!ARMS.includes(record.arm)) reject("INVALID_ARM", `${location}.arm`);
+  if (!Number.isInteger(record.block) || record.block < 1 || record.block > 6) reject("INVALID_BLOCK", location);
+  if (!Number.isInteger(record.order) || record.order < 1 || record.order > 3) reject("INVALID_ORDER", location);
+  if (!Number.isInteger(record.sequence) || record.sequence < 1 || record.sequence > 54) {
+    reject("INVALID_SEQUENCE", location);
+  }
+  const expected = scenarioPhases.get(record.phase);
+  if (!isObject(expected)) reject("INVALID_PHASE", `${location}.phase`);
+  if (record.prompt_bytes !== expected.prompt_bytes || record.prompt_sha256 !== expected.prompt_sha256) {
+    reject("PROMPT_IDENTITY_MISMATCH", location);
+  }
+  if (!Number.isSafeInteger(record.response_bytes) || record.response_bytes < 0) {
+    reject("INVALID_RESPONSE_IDENTITY", location);
+  }
+  if (typeof record.response_sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(record.response_sha256)) {
+    reject("INVALID_RESPONSE_IDENTITY", location);
+  }
+  for (const field of ["sentinel_match", "route_observed", "output_policy_match", "correct", "timed_out"]) {
+    if (typeof record[field] !== "boolean") reject("INVALID_BOOLEAN", `${location}.${field}`);
+  }
+  if (record.failure_code !== null
+    && (typeof record.failure_code !== "string" || !FAILURE_CODE_PATTERN.test(record.failure_code))) {
+    reject("INVALID_FAILURE_CODE", location);
+  }
+  const unsuccessful = !record.sentinel_match || !record.route_observed || !record.output_policy_match
+    || record.timed_out || record.failure_code !== null;
+  if (unsuccessful && record.failure_code === null) reject("INVALID_FAILURE_CODE", location);
+  assertOffset(record.start_offset_ms, `${location}.start_offset_ms`);
+  assertOffset(record.first_content_offset_ms, `${location}.first_content_offset_ms`, true);
+  assertOffset(record.final_receipt_offset_ms, `${location}.final_receipt_offset_ms`);
+  assertOffset(record.exit_offset_ms, `${location}.exit_offset_ms`);
+  const first = record.first_content_offset_ms === UNAVAILABLE
+    ? record.start_offset_ms
+    : record.first_content_offset_ms;
+  if (record.start_offset_ms > first || first > record.final_receipt_offset_ms
+    || record.final_receipt_offset_ms > record.exit_offset_ms) reject("NON_MONOTONIC_TIME", location);
+  for (const field of COUNTERS) assertSafeCounter(record[field], `${location}.${field}`);
+  const derivedCorrect = !unsuccessful;
+  if (record.correct !== derivedCorrect) reject("CORRECTNESS_MISMATCH", location);
+  if (record.sentinel_match
+    && (record.response_bytes !== expected.sentinel_bytes || record.response_sha256 !== expected.sentinel_sha256)) {
+    reject("SENTINEL_IDENTITY_MISMATCH", location);
+  }
+}
+
+function assertCohortShape(records) {
+  const seenArms = new Set(records.map((record) => record.arm));
+  for (const arm of ARMS) if (!seenArms.has(arm)) reject("MISSING_ARM", arm);
+  if (records.length !== 54) reject("INVALID_RECORD_COUNT");
+  const permutations = new Set();
+  for (let block = 1; block <= 6; block += 1) {
+    const blockArms = [];
+    for (let order = 1; order <= 3; order += 1) {
+      const start = ((block - 1) * 9) + ((order - 1) * 3);
+      const session = records.slice(start, start + 3);
+      const arm = session[0]?.arm;
+      if (!ARMS.includes(arm)) reject("INVALID_SESSION_ARM", `block-${block}-order-${order}`);
+      blockArms.push(arm);
+      session.forEach((record, phaseIndex) => {
+        const expectedSequence = start + phaseIndex + 1;
+        if (record.sequence !== expectedSequence) reject("INVALID_SEQUENCE", `sequence-${expectedSequence}`);
+        if (record.block !== block || record.order !== order || record.arm !== arm
+          || record.phase !== PHASES[phaseIndex]) reject("INVALID_SESSION_ORDER", `sequence-${expectedSequence}`);
+      });
+    }
+    if (new Set(blockArms).size !== 3) reject("INVALID_BLOCK_PERMUTATION", `block-${block}`);
+    const permutation = blockArms.join(",");
+    if (permutations.has(permutation)) reject("DUPLICATE_PERMUTATION", `block-${block}`);
+    permutations.add(permutation);
+  }
+  if (permutations.size !== 6) reject("INCOMPLETE_PERMUTATIONS");
+}
+
+export function validateScenarioBytes(bytes) {
+  if (!Buffer.isBuffer(bytes)) reject("INVALID_SCENARIO_BYTES");
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (bytes.length !== SCENARIO_BYTES || digest !== SCENARIO_SHA256) reject("STALE_SCENARIO");
+  const scenario = JSON.parse(bytes.toString("utf8"));
+  phaseMap(scenario);
+  return scenario;
+}
+
+export function validateHarnessSpeedCohort(cohort, scenario) {
+  assertPrivacy(cohort);
+  if (!isObject(cohort) || cohort.schema !== SCHEMA || cohort.scenario_id !== SCENARIO_ID
+    || cohort.product !== PRODUCT || !Array.isArray(cohort.records)) reject("COHORT_IDENTITY_MISMATCH");
+  const phases = phaseMap(scenario);
+  cohort.records.forEach((record, index) => validateRecord(record, index, phases));
+  assertCohortShape(cohort.records);
+  return evaluateHarnessSpeedRecords(cohort.records, reject);
+}
+
+export function scenarioSurfaceReceipt(bytes) {
+  const scenario = validateScenarioBytes(bytes);
+  return {
+    schema: "litfamily.harness-speed-surface/v1",
+    product: PRODUCT,
+    scenario_id: scenario.scenario_id,
+    fixture_bytes: bytes.length,
+    fixture_sha256: SCENARIO_SHA256,
+    phase_ids: scenario.records.map((record) => record.id),
+    provider_completions: 0,
+    raw_content_retained: false,
+    verdict: "PASS"
+  };
+}
+
+function main(argv) {
+  if (argv.length !== 2 || argv[0] !== "--self-check") reject("INVALID_CLI_USAGE");
+  process.stdout.write(`${JSON.stringify(scenarioSurfaceReceipt(readFileSync(argv[1])))}\n`);
+}
+
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && path.resolve(invokedPath) === fileURLToPath(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    if (error instanceof HarnessSpeedContractError) {
+      process.stderr.write(`${JSON.stringify({ verdict: "FAIL", code: error.code, field: error.field })}\n`);
+      process.exitCode = 1;
+    } else {
+      throw error;
+    }
+  }
+}

package/qa/harness-speed-v2-contract.mjs

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+
+const schema = "litfamily.harness-speed-v2/comparison/v1";
+const product = "litopencode";
+const baselineHead = "4d4fa72648dc1b0277a4d8787768828b66ee3de8";
+const baselineStatus = "09b2f68760bf47a94f0eb9bda264a9dc3f4117d77ef3f5c2f775083c712c2982";
+const sourceArtifact = "301cdc5e3579637365c220abec961ebde1354fbdd37cbaf41f8c9e9f3171971f";
+const fixtureHash = "aaef5ba778532013248f0b5c0a9f958468786840595e48cb84851ab88bf2b4be";
+const phases = Object.freeze(["startup_config", "rules_transform", "no_route_floor", "activation_ledger", "s2_continuation", "local_total"]);
+const arms = Object.freeze(["baseline", "candidate"]);
+const guardNames = Object.freeze(["correctness", "route", "banner", "ledger", "body", "payload", "direct", "compaction"]);
+const providerFields = Object.freeze(["input_tokens", "cache_read_tokens", "cache_write_tokens", "output_tokens"]);
+const envelopeKeys = "baseline,blocks,candidate,context_bytes,fixture,guards,lever,product,provider,raw_content_retained,schema";
+const proofKeys = "body_sha256,deterministic,host,loaded_sha256,mechanism,observed,surface";
+const forbiddenFields = new Set(["prompt", "response", "transcript", "url", "request_id", "session_id", "credential", "authorization", "cookie", "api_key"]);
+const misleadingFields = new Set(["verdict", "result", "claimedsuccess"]);
+const sha256Pattern = /^[a-f0-9]{64}$/u;
+
+export class HarnessSpeedV2ContractError extends Error {
+  constructor(code, field = null) {
+    super(field === null ? code : `${code}:${field}`);
+    Object.assign(this, { name: "HarnessSpeedV2ContractError", code, field });
+  }
+}
+
+function reject(code, field = null) {
+  throw new HarnessSpeedV2ContractError(code, field);
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function assertPrivacy(value, location = "receipt") {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertPrivacy(entry, `${location}[${index}]`));
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, entry] of Object.entries(value)) {
+    if (misleadingFields.has(key.toLowerCase().replace(/[_-]/gu, ""))) reject("MISLEADING_SUCCESS_FIELD", `${location}.${key}`);
+    if (forbiddenFields.has(key.toLowerCase())) reject("FORBIDDEN_FIELD", `${location}.${key}`);
+    assertPrivacy(entry, `${location}.${key}`);
+  }
+}
+
+function assertInteger(value, field, minimum = 0) {
+  if (!Number.isSafeInteger(value) || value < minimum) reject("INVALID_CANDIDATE_IDENTITY", field);
+}
+
+function assertHash(value, field, code) {
+  if (typeof value !== "string" || !sha256Pattern.test(value)) reject(code, field);
+}
+
+function assertIdentity(receipt) {
+  if (!isObject(receipt)) reject("INVALID_RECEIPT_IDENTITY");
+  if (Object.keys(receipt).sort().join(",") !== envelopeKeys) reject("UNEXPECTED_TOP_LEVEL_FIELD");
+  if (receipt.schema !== schema || receipt.product !== product) reject("INVALID_RECEIPT_IDENTITY");
+  if (!isObject(receipt.fixture) || receipt.fixture.bytes !== 1476 || receipt.fixture.sha256 !== fixtureHash) {
+    reject("FIXTURE_IDENTITY_MISMATCH");
+  }
+  if (!isObject(receipt.baseline) || receipt.baseline.source !== "frozen_repaired") reject("INVALID_BASELINE_SOURCE");
+  if (receipt.baseline.head !== baselineHead) reject("BASELINE_HEAD_MISMATCH");
+  if (receipt.baseline.source_artifact_sha256 !== sourceArtifact) reject("BASELINE_SOURCE_ARTIFACT_MISMATCH");
+  if (receipt.baseline.status_sha256 !== baselineStatus
+    || receipt.baseline.status_bytes !== 474 || receipt.baseline.status_records !== 14) {
+    reject("BASELINE_STATUS_MISMATCH");
+  }
+  assertHash(receipt.baseline.artifact_sha256, "baseline.artifact_sha256", "INVALID_BASELINE_IDENTITY");
+  if (!isObject(receipt.candidate)) reject("INVALID_CANDIDATE_IDENTITY");
+  if (receipt.candidate.head !== baselineHead) reject("CANDIDATE_HEAD_MISMATCH");
+  if (receipt.candidate.base_source_artifact_sha256 !== sourceArtifact) reject("CANDIDATE_BASE_SOURCE_ARTIFACT_MISMATCH");
+  assertHash(receipt.candidate.source_artifact_sha256, "candidate.source_artifact_sha256", "INVALID_CANDIDATE_SOURCE_ARTIFACT");
+  if (receipt.candidate.source_artifact_sha256 === sourceArtifact) reject("CANDIDATE_SOURCE_ARTIFACT_NOT_DISTINCT");
+  assertHash(receipt.candidate.artifact_sha256, "candidate.artifact_sha256", "INVALID_CANDIDATE_IDENTITY");
+  assertHash(receipt.candidate.status_sha256, "candidate.status_sha256", "INVALID_CANDIDATE_IDENTITY");
+  if (receipt.candidate.artifact_sha256 === receipt.baseline.artifact_sha256) reject("CANDIDATE_ARTIFACT_NOT_DISTINCT");
+  if (receipt.candidate.status_sha256 === receipt.baseline.status_sha256) reject("CANDIDATE_STATUS_NOT_DISTINCT");
+  assertInteger(receipt.candidate.status_bytes, "candidate.status_bytes", 1);
+  assertInteger(receipt.candidate.status_records, "candidate.status_records", 0);
+}
+
+function assertSamples(value, field) {
+  if (!Array.isArray(value) || value.length !== 5) reject("INVALID_SAMPLE_COUNT", field);
+  value.forEach((sample, index) => {
+    if (!isObject(sample) || Object.keys(sample).sort().join(",") !== "index,value_ms"
+      || typeof sample.value_ms !== "number" || !Number.isFinite(sample.value_ms) || sample.value_ms < 0) {
+      reject("INVALID_SAMPLE", `${field}[${index}]`);
+    }
+    if (sample.index !== index + 1) reject("INVALID_SAMPLE_INDEX", `${field}[${index}]`);
+  });
+  return value.map((sample) => sample.value_ms);
+}
+
+function collectSamples(receipt) {
+  if (!Array.isArray(receipt.blocks) || receipt.blocks.length !== 6) reject("INVALID_BLOCK_COUNT");
+  const collected = Object.fromEntries(arms.map((arm) => [arm, Object.fromEntries(phases.map((phase) => [phase, []]))]));
+  receipt.blocks.forEach((block, index) => {
+    const expectedOrder = index % 2 === 0 ? arms : [...arms].reverse();
+    if (!isObject(block) || block.block !== index + 1) reject("INVALID_BLOCK_ID", `blocks[${index}]`);
+    if (!Array.isArray(block.order) || block.order.length !== 2
+      || block.order.some((arm, orderIndex) => arm !== expectedOrder[orderIndex])) reject("INVALID_ARM_ORDER", `blocks[${index}]`);
+    for (const arm of arms) {
+      if (!isObject(block.arms?.[arm])) reject("INVALID_ARM", `blocks[${index}].${arm}`);
+      for (const phase of phases) {
+        const values = assertSamples(block.arms[arm][phase], `blocks[${index}].${arm}.${phase}`);
+        collected[arm][phase].push(...values);
+      }
+    }
+  });
+  return collected;
+}
+
+function nearestRank(values, percentile) {
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.ceil(percentile * sorted.length) - 1];
+}
+
+function summarize(collected) {
+  return Object.fromEntries(phases.map((phase) => {
+    const baseline = collected.baseline[phase];
+    const candidate = collected.candidate[phase];
+    const baselineP95 = nearestRank(baseline, 0.95);
+    const candidateP95 = nearestRank(candidate, 0.95);
+    const gain = baselineP95 > 0 ? (baselineP95 - candidateP95) / baselineP95 : null;
+    return [phase, {
+      baseline_p50_ms: nearestRank(baseline, 0.5),
+      baseline_p95_ms: baselineP95,
+      candidate_p50_ms: nearestRank(candidate, 0.5),
+      candidate_p95_ms: candidateP95,
+      gain_ratio: gain
+    }];
+  }));
+}
+
+function assertPerformance(receipt, metrics) {
+  const aggregate = metrics.local_total;
+  if (aggregate.candidate_p50_ms > aggregate.baseline_p50_ms) reject("AGGREGATE_P50_REGRESSION");
+  if (aggregate.candidate_p95_ms > aggregate.baseline_p95_ms) reject("AGGREGATE_P95_REGRESSION");
+  for (const phase of phases) {
+    if (metrics[phase].candidate_p95_ms > metrics[phase].baseline_p95_ms) reject("PHASE_P95_REGRESSION", phase);
+  }
+  const early = receipt.blocks.slice(0, 3).flatMap((block) => block.arms.baseline.local_total.map((sample) => sample.value_ms));
+  const late = receipt.blocks.slice(3).flatMap((block) => block.arms.baseline.local_total.map((sample) => sample.value_ms));
+  const earlyP95 = nearestRank(early, 0.95);
+  const drift = earlyP95 > 0 ? Math.abs(nearestRank(late, 0.95) - earlyP95) / earlyP95 : null;
+  if (drift === null || drift > 0.20) reject("BASELINE_DRIFT");
+  if (!isObject(receipt.lever)) reject("INVALID_LEVER_KIND");
+  if (receipt.lever.kind === "latency") {
+    if (!phases.includes(receipt.lever.phase)) reject("INVALID_LEVER_PHASE");
+    if (metrics[receipt.lever.phase].gain_ratio === null || metrics[receipt.lever.phase].gain_ratio < 0.15) {
+      reject("SELECTED_LATENCY_GAIN_NOT_MET");
+    }
+  } else if (receipt.lever.kind !== "context_bytes") reject("INVALID_LEVER_KIND");
+  return drift;
+}
+
+function assertSemanticAndProvider(receipt) {
+  if (!isObject(receipt.guards)) reject("SEMANTIC_GUARD_FAILED");
+  for (const name of guardNames) {
+    const guard = receipt.guards[name];
+    if (!isObject(guard) || guard.baseline !== true || guard.candidate !== true) reject("SEMANTIC_GUARD_FAILED", name);
+  }
+  if (!isObject(receipt.provider) || receipt.provider.calls !== 0 || receipt.provider.completions !== 0) {
+    reject("PROVIDER_ACTIVITY_OBSERVED");
+  }
+  for (const field of providerFields) {
+    if (receipt.provider[field] !== "UNAVAILABLE") reject("PROVIDER_FIELD_NOT_UNAVAILABLE", field);
+  }
+  if (receipt.raw_content_retained !== false) reject("RAW_CONTENT_RETAINED");
+}
+
+function assertContext(receipt) {
+  const context = receipt.context_bytes;
+  if (!isObject(context) || !Number.isSafeInteger(context.baseline) || context.baseline <= 0
+    || !Number.isSafeInteger(context.candidate) || context.candidate < 0) reject("INVALID_CONTEXT_BYTES");
+  const reduction = (context.baseline - context.candidate) / context.baseline;
+  if (reduction > 0) {
+    const proof = receipt.lever?.proof;
+    if (!isObject(proof) || Object.keys(proof).sort().join(",") !== proofKeys
+      || proof.mechanism !== "opencode_pre_request" || proof.observed !== true || proof.deterministic !== true
+      || proof.host !== "opencode" || proof.surface !== "pre_request"
+      || !sha256Pattern.test(proof.body_sha256 ?? "") || proof.loaded_sha256 !== proof.body_sha256) {
+      reject("DETERMINISTIC_LOADER_PROOF_REQUIRED");
+    }
+  }
+  if (receipt.lever?.kind === "context_bytes" && reduction < 0.25) reject("CONTEXT_REDUCTION_NOT_MET");
+  return reduction;
+}
+
+export function validateV2Comparison(receipt) {
+  assertPrivacy(receipt);
+  assertIdentity(receipt);
+  const collected = collectSamples(receipt);
+  const metrics = summarize(collected);
+  const baselineDrift = assertPerformance(receipt, metrics);
+  assertSemanticAndProvider(receipt);
+  const contextReduction = assertContext(receipt);
+  return {
+    schema: "litfamily.harness-speed-v2/verdict/v1",
+    product,
+    verdict: "PASS",
+    cohort: { blocks: 6, samples_per_arm_phase: 30 },
+    metrics: { aggregate: metrics.local_total, phases: metrics, baseline_drift_ratio: baselineDrift, context_reduction_ratio: contextReduction },
+    provider: { calls: 0, completions: 0, fields: "UNAVAILABLE" },
+    raw_content_retained: false
+  };
+}
+
+export function validateV2FixtureBytes(bytes) {
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (bytes.length !== 1476 || digest !== fixtureHash) reject("FIXTURE_IDENTITY_MISMATCH");
+}

package/qa/harness-speed-verdict.mjs

@@ -0,0 +1,105 @@
+const ARMS = ["baseline", "candidate", "control"];
+const UNAVAILABLE = "UNAVAILABLE";
+
+function nearestRank(values, percentile, reject) {
+  if (values.length === 0) reject("EMPTY_PERCENTILE");
+  const sorted = [...values].sort((left, right) => left - right);
+  return sorted[Math.max(0, Math.ceil(percentile * sorted.length) - 1)];
+}
+
+function e2e(record) {
+  return record.exit_offset_ms - record.start_offset_ms;
+}
+
+function numericSum(records, field, reject) {
+  let total = 0;
+  for (const record of records) {
+    const value = record[field];
+    if (value === UNAVAILABLE) return UNAVAILABLE;
+    total += value;
+    if (!Number.isSafeInteger(total)) reject("UNSAFE_COUNTER_SUM", field);
+  }
+  return total;
+}
+
+function armDiagnostics(records, reject) {
+  const input = numericSum(records, "input_tokens", reject);
+  const cache = numericSum(records, "cache_read_tokens", reject);
+  const compatible = records.every((record) => typeof record.input_tokens === "number"
+    && typeof record.cache_read_tokens === "number" && record.cache_read_tokens <= record.input_tokens);
+  return {
+    cache_read_share: typeof input === "number" && input > 0 && typeof cache === "number" ? cache / input : UNAVAILABLE,
+    uncached_input_per_correct_turn: compatible && records.length > 0
+      ? records.reduce((total, record) => total + record.input_tokens - record.cache_read_tokens, 0) / records.length
+      : UNAVAILABLE
+  };
+}
+
+export function evaluateHarnessSpeedRecords(records, reject) {
+  const measured = Object.fromEntries(ARMS.map((arm) => [arm,
+    records.filter((record) => record.arm === arm && record.phase !== "B0")]));
+  const warmups = Object.fromEntries(ARMS.map((arm) => [arm,
+    records.filter((record) => record.arm === arm && record.phase === "B0")]));
+  const durations = Object.fromEntries(ARMS.map((arm) => [arm, measured[arm].map(e2e)]));
+  const summaries = Object.fromEntries(ARMS.map((arm) => [arm, {
+    warmups_correct: warmups[arm].filter((record) => record.correct).length,
+    measured_correct: measured[arm].filter((record) => record.correct).length,
+    p50_ms: nearestRank(durations[arm], 0.5, reject),
+    p95_ms: nearestRank(durations[arm], 0.95, reject),
+    total_input_tokens: numericSum(measured[arm], "input_tokens", reject)
+  }]));
+  const ratios = measured.candidate.map((candidate) => {
+    const baseline = measured.baseline.find((record) => record.block === candidate.block && record.phase === candidate.phase);
+    if (baseline === undefined || e2e(baseline) <= 0) reject("INVALID_PAIR", `${candidate.block}-${candidate.phase}`);
+    return e2e(candidate) / e2e(baseline);
+  });
+  const earlyControl = durations.control.slice(0, 6);
+  const lateControl = durations.control.slice(6);
+  const earlyP95 = nearestRank(earlyControl, 0.95, reject);
+  if (earlyP95 <= 0) reject("INVALID_CONTROL_BASELINE");
+  const pairedMedianRatio = nearestRank(ratios, 0.5, reject);
+  const controlDriftRatio = Math.abs(nearestRank(lateControl, 0.95, reject) - earlyP95) / earlyP95;
+  const allCorrect = ARMS.every((arm) => summaries[arm].warmups_correct === 6
+    && summaries[arm].measured_correct === 12);
+  const baselineInput = summaries.baseline.total_input_tokens;
+  const candidateInput = summaries.candidate.total_input_tokens;
+  const antiPadding = typeof baselineInput === "number" && typeof candidateInput === "number"
+    ? candidateInput <= baselineInput : UNAVAILABLE;
+  const gates = {
+    correctness: allCorrect,
+    candidate_p95: summaries.candidate.p95_ms <= summaries.baseline.p95_ms * 0.85,
+    candidate_p50: summaries.candidate.p50_ms <= summaries.baseline.p50_ms,
+    paired_ratio: pairedMedianRatio <= 0.85,
+    control_drift: controlDriftRatio <= 0.20,
+    anti_padding: antiPadding
+  };
+  const candidateCache = numericSum(measured.candidate, "cache_read_tokens", reject);
+  const cacheCompatible = [...measured.baseline, ...measured.candidate].every((record) =>
+    typeof record.input_tokens === "number" && typeof record.cache_read_tokens === "number"
+    && record.cache_read_tokens <= record.input_tokens);
+  const latencySaved = cacheCompatible && typeof candidateCache === "number" && candidateCache > 0
+    ? (durations.baseline.reduce((sum, value) => sum + value, 0)
+      - durations.candidate.reduce((sum, value) => sum + value, 0)) / (candidateCache / 1000)
+    : UNAVAILABLE;
+  const reasonCodes = [];
+  if (!gates.correctness) reasonCodes.push("CORRECTNESS_FAILED");
+  if (!gates.candidate_p95) reasonCodes.push("CANDIDATE_P95_TARGET_NOT_MET");
+  if (!gates.candidate_p50) reasonCodes.push("CANDIDATE_P50_REGRESSION");
+  if (!gates.paired_ratio) reasonCodes.push("PAIRED_RATIO_TARGET_NOT_MET");
+  if (!gates.control_drift) reasonCodes.push("ENVIRONMENT_DRIFT");
+  if (gates.anti_padding === false) reasonCodes.push("INPUT_PADDING");
+  if (gates.anti_padding === UNAVAILABLE) reasonCodes.push("INPUT_TOKENS_UNAVAILABLE");
+  return {
+    verdict: reasonCodes.length === 0 ? "PASS"
+      : gates.anti_padding === UNAVAILABLE && reasonCodes.length === 1 ? UNAVAILABLE : "FAIL",
+    reason_codes: reasonCodes,
+    cohort: { records: 54, sessions_per_arm: 6, measured_turns_per_arm: 12 },
+    arms: summaries,
+    metrics: { paired_median_ratio: pairedMedianRatio, control_drift_ratio: controlDriftRatio },
+    gates,
+    diagnostics: {
+      cache: Object.fromEntries(ARMS.map((arm) => [arm, armDiagnostics(measured[arm], reject)])),
+      latency_saved_ms_per_1k_cache_read_tokens: latencySaved
+    }
+  };
+}