@oracle-agent/oracle 0.35.42 → 0.35.43

package/public/oracle-splash/eval/live-eval.js

@@ -0,0 +1,546 @@
+// Live evaluation feed reader for the public /eval page.
+//
+// Producer records are serialized by a process this page cannot audit, so
+// nothing here upgrades a recorded claim into a verified one. The sha256 in a
+// descriptor proves that the bytes we fetched are the bytes the producer
+// hashed; it proves nothing about whether the run happened or what it did.
+// Every path below fails closed: an unreadable, unexpected, or unhashed feed
+// leaves the last good result on screen, labelled as cached.
+
+export const FEED_URL = "./live/index.json";
+export const POLL_INTERVAL_MS = 3000;
+export const REQUEST_TIMEOUT_MS = 8000;
+export const STALE_AFTER_MS = 30000;
+
+export const SLICE_ROSTER = [
+  "guards",
+  "fidelity",
+  "golden-prepare",
+  "hybrid",
+  "desk",
+  "agentic",
+  "adversarial",
+  "contracts",
+  "rlm",
+  "native",
+];
+
+const RUN_STATES = ["running", "passed", "failed", "blocked", "interrupted"];
+const SLICE_STATES = ["queued", "running", "passed", "failed", "blocked", "skipped", "unavailable"];
+const COUNT_KEYS = ["total", "pass", "fail", "skipped", "cancelled", "todo"];
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const COMMIT = /^[0-9a-f]{40}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const RECORD_PATH = /^runs\/([0-9a-f-]{36})\/([1-9][0-9]*)\.json$/;
+
+const VERSION_NOTE = "Source package version, not a confirmed installed release.";
+const RECORDED_PASS = "recorded pass \u00b7 unattested";
+
+const RUN_PRESENTATION = {
+  running: { label: "running", tone: "blue" },
+  passed: { label: RECORDED_PASS, tone: "amber" },
+  failed: { label: "recorded failure", tone: "red" },
+  blocked: { label: "blocked", tone: "red" },
+  interrupted: { label: "interrupted", tone: "red" },
+};
+
+const SLICE_PRESENTATION = {
+  queued: { label: "queued", tone: "muted" },
+  running: RUN_PRESENTATION.running,
+  passed: RUN_PRESENTATION.passed,
+  failed: RUN_PRESENTATION.failed,
+  blocked: RUN_PRESENTATION.blocked,
+  skipped: { label: "skipped", tone: "amber" },
+  unavailable: { label: "not available", tone: "amber" },
+};
+
+const fail = (error) => ({ ok: false, error });
+const isPlainObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isIso = (value) => typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+
+function sameSource(a, b) {
+  if (!isPlainObject(a) || !isPlainObject(b)) return false;
+  return a.commit === b.commit && a.dirty === b.dirty && a.node === b.node;
+}
+
+function validSource(source) {
+  if (!isPlainObject(source)) return false;
+  if (typeof source.commit !== "string") return false;
+  if (source.commit !== "unknown" && !COMMIT.test(source.commit)) return false;
+  if (source.dirty !== null && typeof source.dirty !== "boolean") return false;
+  return typeof source.node === "string" && source.node.length > 0;
+}
+
+export function safeLiveUrl(recordPath) {
+  if (typeof recordPath !== "string" || !RECORD_PATH.test(recordPath)) return null;
+  return `./live/${recordPath}`;
+}
+
+export function validateDescriptor(descriptor) {
+  if (!isPlainObject(descriptor)) return fail("descriptor is not an object");
+  const { runId, startedAt, updatedAt, finishedAt, status, scope } = descriptor;
+  if (typeof runId !== "string" || !UUID_V4.test(runId)) return fail("run id is not a lowercase uuid v4");
+  if (!RUN_STATES.includes(status)) return fail("unknown run status");
+  if (scope !== "development") return fail("scope must be development");
+  if (!isIso(startedAt) || !isIso(updatedAt)) return fail("start or update time is not an ISO instant");
+  if (Date.parse(updatedAt) < Date.parse(startedAt)) return fail("update time precedes start time");
+  if (status === "running") {
+    if (finishedAt !== null) return fail("a running run cannot have a finish time");
+  } else {
+    if (!isIso(finishedAt)) return fail("a completed run needs a finish time");
+    if (Date.parse(finishedAt) < Date.parse(startedAt)) return fail("finish time precedes start time");
+  }
+  if (typeof descriptor.packageVersion !== "string" || !SEMVER.test(descriptor.packageVersion)) return fail("bad package version");
+  if (typeof descriptor.target !== "string" || descriptor.target.trim().length === 0) return fail("target is empty");
+  if (!validSource(descriptor.source)) return fail("source provenance is incomplete");
+  if (typeof descriptor.sha256 !== "string" || !SHA256.test(descriptor.sha256)) return fail("digest is not 64 lowercase hex");
+  const match = RECORD_PATH.exec(String(descriptor.record ?? ""));
+  if (!match) return fail("record path is not runs/<runId>/<revision>.json");
+  if (match[1] !== runId) return fail("record path belongs to another run");
+  return { ok: true, revision: Number(match[2]) };
+}
+
+export function recordLocation(descriptor) {
+  const checked = validateDescriptor(descriptor);
+  if (!checked.ok) return null;
+  const url = safeLiveUrl(descriptor.record);
+  if (!url) return null;
+  return { url, revision: checked.revision };
+}
+
+export function validateManifest(manifest) {
+  if (!isPlainObject(manifest)) return { ...fail("feed is not an object"), runs: [] };
+  if (manifest.schemaVersion !== 1) return { ...fail("unsupported feed schema"), runs: [] };
+  if (manifest.kind !== "oracle-eval-feed") return { ...fail("unexpected feed kind"), runs: [] };
+  if (!isIso(manifest.updatedAt)) return { ...fail("feed update time is not an ISO instant"), runs: [] };
+  if (!Array.isArray(manifest.runs)) return { ...fail("feed runs is not a list"), runs: [] };
+
+  const seen = new Set();
+  let previous = Infinity;
+  for (const descriptor of manifest.runs) {
+    const checked = validateDescriptor(descriptor);
+    if (!checked.ok) return { ...fail(checked.error), runs: [] };
+    if (seen.has(descriptor.runId)) return { ...fail("duplicate run id in feed"), runs: [] };
+    seen.add(descriptor.runId);
+    const at = Date.parse(descriptor.startedAt);
+    if (at > previous) return { ...fail("feed runs are not newest first"), runs: [] };
+    previous = at;
+  }
+  return { ok: true, runs: manifest.runs, updatedAt: manifest.updatedAt };
+}
+
+function validateCounts(counts) {
+  if (counts === undefined) return true;
+  if (!isPlainObject(counts)) return false;
+  for (const key of Object.keys(counts)) if (!COUNT_KEYS.includes(key)) return false;
+  for (const key of ["total", "pass", "fail"]) if (!isCount(counts[key])) return false;
+  let sum = counts.pass + counts.fail;
+  for (const key of ["skipped", "cancelled", "todo"]) {
+    if (counts[key] === undefined) continue;
+    if (!isCount(counts[key])) return false;
+    sum += counts[key];
+  }
+  return sum === counts.total;
+}
+
+export function validateRecord(record, descriptor) {
+  const bound = validateDescriptor(descriptor);
+  if (!bound.ok) return fail(bound.error);
+  if (!isPlainObject(record)) return fail("record is not an object");
+  if (record.schemaVersion !== 1) return fail("unsupported record schema");
+  if (record.kind !== "oracle-eval-run") return fail("unexpected record kind");
+  if (record.package !== "@oracle-agent/oracle") return fail("unexpected package");
+  if (record.scope !== "development") return fail("scope must be development");
+  if (record.runId !== descriptor.runId) return fail("record run id does not match the descriptor");
+  if (!Number.isInteger(record.revision) || record.revision < 1) return fail("revision is not a positive integer");
+  if (record.revision !== bound.revision) return fail("revision does not match the record path");
+
+  for (const key of ["startedAt", "updatedAt", "finishedAt", "status", "packageVersion", "target"]) {
+    if (record[key] !== descriptor[key]) return fail(`record ${key} does not match the descriptor`);
+  }
+  if (!sameSource(record.source, descriptor.source)) return fail("record source does not match the descriptor");
+
+  const selected = record.selectedSlices;
+  if (!Array.isArray(selected) || selected.length === 0) return fail("no slices were selected");
+  const wanted = new Set();
+  for (const name of selected) {
+    if (!SLICE_ROSTER.includes(name)) return fail(`unknown slice ${String(name)}`);
+    if (wanted.has(name)) return fail("duplicate slice in the selection");
+    wanted.add(name);
+  }
+  if (!isPlainObject(record.slices)) return fail("slices is not an object");
+  const reported = Object.keys(record.slices);
+  for (const name of reported) {
+    if (!wanted.has(name)) return fail(`slice ${name} was reported without being selected`);
+  }
+  for (const name of wanted) {
+    if (!reported.includes(name)) return fail(`selected slice ${name} has no entry`);
+    const slice = record.slices[name];
+    if (!isPlainObject(slice)) return fail(`slice ${name} is not an object`);
+    if (!SLICE_STATES.includes(slice.status)) return fail(`slice ${name} has an unknown status`);
+    if (!validateCounts(slice.counts)) return fail(`slice ${name} has counts that do not reconcile`);
+    if (slice.durationMs !== undefined && !isCount(slice.durationMs)) return fail(`slice ${name} has a bad duration`);
+    if (slice.summary !== undefined && typeof slice.summary !== "string") return fail(`slice ${name} has a bad summary`);
+    if (slice.status === "passed" && slice.counts && (slice.counts.pass < 1 || slice.counts.fail > 0
+      || slice.counts.cancelled > 0 || slice.counts.todo > 0)) return fail(`slice ${name} contradicts its pass claim`);
+  }
+  if (record.status === "passed" && Object.values(record.slices).some((slice) => slice.status !== "passed")) return fail("run pass contradicts selected slices");
+
+  const evidence = record.evidence;
+  if (!isPlainObject(evidence)) return fail("evidence block is missing");
+  if (evidence.attested !== false) return fail("records are never attested");
+  if (typeof evidence.projection !== "string" || evidence.projection.length === 0) return fail("evidence projection is missing");
+  return { ok: true };
+}
+
+export function isCanonicalRecordText(text, record) {
+  return typeof text === "string" && text === `${JSON.stringify(record)}\n`;
+}
+
+export async function digestHex(text) {
+  const bytes = new TextEncoder().encode(text);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function verifyBytes(text, expected) {
+  if (typeof expected !== "string" || !SHA256.test(expected)) return false;
+  const actual = await digestHex(text);
+  if (actual.length !== expected.length) return false;
+  let diff = 0;
+  for (let index = 0; index < actual.length; index += 1) diff |= actual.charCodeAt(index) ^ expected.charCodeAt(index);
+  return diff === 0;
+}
+
+function formatDuration(durationMs) {
+  if (durationMs < 1000) return `${durationMs} ms`;
+  return `${Number((durationMs / 1000).toFixed(2))} s`;
+}
+
+function presentSlice(name, record) {
+  const selected = record.selectedSlices.includes(name);
+  if (!selected) {
+    return {
+      name,
+      selected: false,
+      status: "not-run",
+      label: "not run",
+      tone: "muted",
+      counts: null,
+      countsLabel: "not run",
+      durationLabel: null,
+      summary: null,
+    };
+  }
+  const slice = record.slices[name];
+  const presentation = SLICE_PRESENTATION[slice.status];
+  const counts = slice.counts ?? null;
+  return {
+    name,
+    selected: true,
+    status: slice.status,
+    label: presentation.label,
+    tone: presentation.tone,
+    counts,
+    countsLabel: counts ? `${counts.pass} passed, ${counts.fail} failed of ${counts.total}` : "counts not published",
+    durationLabel: isCount(slice.durationMs) ? formatDuration(slice.durationMs) : null,
+    summary: typeof slice.summary === "string" ? slice.summary : null,
+  };
+}
+
+export function presentRun(record, descriptor, now) {
+  const presentation = RUN_PRESENTATION[record.status];
+  const running = record.status === "running";
+  const stale = running && now - Date.parse(record.updatedAt) > STALE_AFTER_MS;
+  const liveness = running ? (stale ? "stalled" : "live") : "historical";
+  const location = recordLocation(descriptor);
+  const dirty = record.source.dirty;
+  return {
+    runId: record.runId,
+    revision: record.revision,
+    statusLabel: presentation.label,
+    statusTone: presentation.tone,
+    liveness,
+    livenessLabel: liveness === "stalled"
+      ? "stalled / no recent update"
+      : liveness === "live" ? "live \u00b7 updating" : "completed record",
+    target: record.target,
+    commit: record.source.commit,
+    node: record.source.node,
+    dirtyLabel: dirty === true ? "dirty working tree" : dirty === false ? "clean working tree" : "working tree state unknown",
+    packageVersion: record.packageVersion,
+    packageVersionNote: VERSION_NOTE,
+    startedAt: record.startedAt,
+    updatedAt: record.updatedAt,
+    finishedAt: record.finishedAt,
+    recordUrl: location ? location.url : null,
+    selectedCount: record.selectedSlices.length,
+    slices: SLICE_ROSTER.map((name) => presentSlice(name, record)),
+  };
+}
+
+export function nextSelection(value) {
+  if (typeof value === "string" && UUID_V4.test(value)) return { mode: "pinned", runId: value };
+  return { mode: "latest" };
+}
+
+export function presentHistory(runs, selection) {
+  const list = Array.isArray(runs) ? runs : [];
+  const pinned = selection?.mode === "pinned" ? selection.runId : null;
+  const selected = pinned ? list.find((run) => run.runId === pinned) ?? null : list[0] ?? null;
+  const options = [{ value: "latest", label: "Follow latest", selected: !pinned }];
+  for (const run of list) {
+    options.push({
+      value: run.runId,
+      label: `${run.startedAt} \u00b7 ${run.status} \u00b7 ${run.runId.slice(0, 8)}`,
+      selected: run.runId === pinned,
+    });
+  }
+  return { options, selected, missing: Boolean(pinned) && selected === null };
+}
+
+export function initialState() {
+  return {
+    phase: "waiting",
+    statusLabel: "Waiting for the first published run.",
+    error: null,
+    manifest: null,
+    lastGood: null,
+    selection: { mode: "latest" },
+    checkedAt: null,
+  };
+}
+
+export function selectRun(state, value) {
+  return { ...state, selection: nextSelection(value) };
+}
+
+export function applyFeedResult(state, result, now) {
+  if (result?.ok) {
+    const checked = validateManifest(result.manifest);
+    if (!checked.ok) return applyFeedResult(state, { ok: false, kind: "invalid", error: checked.error }, now);
+    const manifest = { ...result.manifest, runs: checked.runs };
+    if (checked.runs.length === 0) {
+      return { ...state, phase: "waiting", statusLabel: "Waiting for the first published run.", error: null, manifest, lastGood: state.lastGood, checkedAt: now };
+    }
+    return { ...state, phase: "live", statusLabel: "Live feed", error: null, manifest, lastGood: { manifest, at: now }, checkedAt: now };
+  }
+  const error = result?.error ?? "feed unavailable";
+  if (!state.lastGood) {
+    return { ...state, phase: "disconnected", statusLabel: "Feed disconnected or invalid. No results are shown.", error, manifest: null, lastGood: null, checkedAt: now };
+  }
+  return { ...state, phase: "cached", statusLabel: "Cached result, not live. The feed is disconnected or invalid.", error, manifest: state.lastGood.manifest, checkedAt: now };
+}
+
+export function createPoller({ run, intervalMs = POLL_INTERVAL_MS, schedule, cancel }) {
+  let inFlight = null;
+  let chain = Promise.resolve();
+  let timer = null;
+  let stopped = false;
+
+  function tick() {
+    if (stopped || inFlight) return inFlight ?? Promise.resolve();
+    if (timer !== null) cancel(timer);
+    timer = null;
+    let started;
+    try {
+      started = Promise.resolve(run());
+    } catch (error) {
+      started = Promise.resolve();
+    }
+    chain = started.catch(() => {}).then(() => {
+      inFlight = null;
+      if (!stopped) timer = schedule(tick, intervalMs);
+    });
+    inFlight = chain;
+    return chain;
+  }
+
+  return {
+    tick,
+    settled: () => chain,
+    stop() {
+      stopped = true;
+      if (timer !== null) cancel(timer);
+      timer = null;
+    },
+  };
+}
+
+async function fetchFeed(url = FEED_URL) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { cache: "no-store", signal: controller.signal, credentials: "omit", redirect: "error" });
+    if (!response.ok) return { ok: false, kind: "disconnected", error: `feed responded ${response.status}` };
+    return { ok: true, manifest: JSON.parse(await response.text()) };
+  } catch (error) {
+    return { ok: false, kind: "disconnected", error: "feed request failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function fetchRecord(descriptor) {
+  const location = recordLocation(descriptor);
+  if (!location) return { ok: false, error: "record path rejected" };
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await fetch(location.url, { cache: "no-store", signal: controller.signal, credentials: "omit", redirect: "error" });
+    if (!response.ok) return { ok: false, error: `record responded ${response.status}` };
+    const text = await response.text();
+    if (!await verifyBytes(text, descriptor.sha256)) return { ok: false, error: "record digest mismatch" };
+    const record = JSON.parse(text);
+    if (!isCanonicalRecordText(text, record)) return { ok: false, error: "record bytes are not canonical" };
+    const checked = validateRecord(record, descriptor);
+    if (!checked.ok) return { ok: false, error: checked.error };
+    return { ok: true, record };
+  } catch (error) {
+    return { ok: false, error: "record request failed" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function setText(root, id, value) {
+  const node = root.getElementById(id);
+  if (node) node.textContent = value;
+}
+
+function textNode(root, tag, value, className) {
+  const node = root.createElement(tag);
+  node.textContent = value;
+  if (className) node.className = className;
+  return node;
+}
+
+function renderSlices(root, view) {
+  const grid = root.getElementById("live-slices");
+  if (!grid) return;
+  grid.replaceChildren();
+  for (const slice of view.slices) {
+    const card = root.createElement("article");
+    card.className = "live-card";
+    card.setAttribute("data-slice", slice.name);
+    card.setAttribute("data-state", slice.status);
+    card.setAttribute("data-tone", slice.tone);
+    const head = root.createElement("div");
+    head.className = "live-card-head";
+    head.append(textNode(root, "h3", slice.name), textNode(root, "span", slice.label, "live-pill"));
+    card.append(head, textNode(root, "p", slice.countsLabel, "live-card-counts"));
+    if (slice.durationLabel) card.append(textNode(root, "p", slice.durationLabel));
+    if (slice.summary) card.append(textNode(root, "p", slice.summary));
+    grid.append(card);
+  }
+}
+
+function renderHistory(root, history) {
+  const picker = root.getElementById("live-run-select");
+  if (!picker) return;
+  picker.replaceChildren();
+  for (const option of history.options) {
+    const node = root.createElement("option");
+    node.value = option.value;
+    node.textContent = option.label;
+    if (option.selected) node.selected = true;
+    picker.append(node);
+  }
+}
+
+function renderRecordLink(root, url) {
+  const link = root.getElementById("live-record");
+  const none = root.getElementById("live-record-none");
+  if (!link || !none) return;
+  if (url) {
+    link.setAttribute("href", url);
+    link.hidden = false;
+    none.hidden = true;
+  } else {
+    link.removeAttribute("href");
+    link.hidden = true;
+    none.hidden = false;
+  }
+}
+
+const DETAIL_FIELDS = [
+  ["live-run-status", (view) => view.statusLabel],
+  ["live-liveness", (view) => view.livenessLabel],
+  ["live-target", (view) => view.target],
+  ["live-commit", (view) => view.commit],
+  ["live-dirty", (view) => view.dirtyLabel],
+  ["live-version", (view) => view.packageVersion],
+  ["live-started", (view) => view.startedAt],
+  ["live-updated", (view) => view.updatedAt],
+];
+
+function renderFeedStatus(root, phase, label) {
+  const banner = root.getElementById("live-feed-status");
+  if (banner) banner.setAttribute("data-phase", phase);
+  setText(root, "live-feed-status", label);
+}
+
+function renderEmpty(root, phase, label) {
+  renderFeedStatus(root, phase, label);
+  for (const [id] of DETAIL_FIELDS) setText(root, id, "not published");
+  renderRecordLink(root, null);
+  const grid = root.getElementById("live-slices");
+  if (grid) grid.replaceChildren();
+}
+
+export function mount(root = globalThis.document) {
+  if (typeof root === "undefined" || !root || typeof root.getElementById !== "function") return null;
+  if (!root.getElementById("live-eval")) return null;
+
+  let state = initialState();
+  let lastRecord = null;
+  const announce = (record, connection) => root.dispatchEvent(new CustomEvent("oracle:eval-record", { detail: { record, connection } }));
+
+  async function refresh() {
+    state = applyFeedResult(state, await fetchFeed(), Date.now());
+    const history = presentHistory(state.manifest?.runs ?? [], state.selection);
+    renderHistory(root, history);
+    if (!history.selected) {
+      renderEmpty(root, state.phase, history.missing ? "The selected run is no longer published." : state.statusLabel);
+      announce(null, state.phase);
+      return;
+    }
+    const fetched = await fetchRecord(history.selected);
+    if (!fetched.ok) {
+      const label = `Record rejected, not live: ${fetched.error}`;
+      if (lastRecord?.runId === history.selected.runId) {
+        renderFeedStatus(root, "cached", label);
+        setText(root, "live-liveness", "cached result, not live");
+      } else renderEmpty(root, "disconnected", label);
+      announce(lastRecord, "cached");
+      return;
+    }
+    lastRecord = fetched.record;
+    const view = presentRun(fetched.record, history.selected, Date.now());
+    if (state.phase !== "live") view.livenessLabel = "cached result, not live";
+    renderFeedStatus(root, state.phase, state.statusLabel);
+    for (const [id, read] of DETAIL_FIELDS) setText(root, id, read(view));
+    renderRecordLink(root, view.recordUrl);
+    renderSlices(root, view);
+    announce(fetched.record, state.phase);
+  }
+
+  const poller = createPoller({
+    run: refresh,
+    schedule: (fn, ms) => globalThis.setTimeout(fn, ms),
+    cancel: (handle) => globalThis.clearTimeout(handle),
+  });
+
+  const picker = root.getElementById("live-run-select");
+  if (picker) picker.addEventListener("change", (event) => {
+    state = selectRun(state, event.target.value);
+    poller.tick();
+  });
+
+  poller.tick();
+  return poller;
+}
+
+if (typeof document !== "undefined") mount(document);

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.demi-hl/oracle",
   "description": "Keyless multichain crypto desk: chain reads + prepare-only unsigned txs. Your wallet signs.",
   "websiteUrl": "https://oracle.demi.la",
-  "version": "0.35.42",
+  "version": "0.35.43",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@oracle-agent/oracle",
-      "version": "0.35.42",
+      "version": "0.35.43",
       "transport": {
         "type": "stdio"
       },