@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/registry-carrier.ts

@@ -0,0 +1,107 @@
+/**
+ * The registry's Page carrier (registry design v3 §9): the signed registry
+ * document, gzipped and base64'd into one CommonMark link-reference
+ * definition, `[loom-registry:v3]: #loom "<base64 gzip>"`. Same trick the
+ * typed-block carriers use (`galaxy-markdown-adapter.ts`): it renders to
+ * nothing on the Page and survives storage byte for byte.
+ *
+ * The carrier is unauthenticated on the wire. What it decodes to goes through
+ * `RegistryStore.ingestText`, where the session signature decides whether it
+ * is this session's own state (a continuation) or an import. Nothing here
+ * trusts it.
+ *
+ * Pi-free, like the rest of the trusted core.
+ */
+
+import { gunzipSync, gzipSync } from "zlib";
+import {
+  NOTEBOOK_FENCE_READ_PREFIXES,
+  NOTEBOOK_FENCE_WRITE_PREFIX,
+} from "../../shared/notebook-fences.js";
+
+/**
+ * Past this many characters an encoded carrier is neither emitted nor read.
+ * Galaxy puts no length limit on page content (`TEXT` column, no
+ * `max_length` on the payload), and the proxy in front of a public server
+ * allows request bodies far larger, so the bound is ours: every push stores a
+ * full page revision, and a registry that big belongs in a history dataset,
+ * not in every revision of a Page. Measured on synthetic registries (one full
+ * tool approval with submission and evaluation per attempt, about 2 KB of JSON
+ * each; the facts themselves stay in `templates/`): 200 attempts encode to
+ * 13 KB and 1,000 to 56 KB. Real attempts vary more and compress less, but
+ * typical JSON still gzips several-fold, so a few hundred attempts sit well
+ * under the cap. Not measured against usegalaxy.eu itself; the round trip at
+ * the cap is a unit test.
+ */
+export const MAX_CARRIER_CHARS = 512 * 1024;
+
+/** The decoded registry may not be larger than the store accepts anyway. */
+export const MAX_CARRIER_DECODED_BYTES = 4 * 1024 * 1024;
+
+const WRITE_PREFIX = NOTEBOOK_FENCE_WRITE_PREFIX;
+const ALT = NOTEBOOK_FENCE_READ_PREFIXES.join("|");
+// Whole line, so carrier-shaped text inside prose is never read as one.
+const LINE = new RegExp(`^\\[(?:${ALT})-registry:v3\\]: #(?:${ALT}) "([A-Za-z0-9+/=]*)"[ \\t]*$`);
+// Anything that looks like it means to be a registry carrier, valid or not.
+const LOOKS_LIKE = new RegExp(`^\\s*\\[(?:${ALT})-registry:v\\d+\\]:`, "i");
+
+export class CarrierTooLargeError extends Error {
+  constructor(chars: number) {
+    super(`the registry carrier would be ${chars} characters, over the ${MAX_CARRIER_CHARS} cap`);
+    this.name = "CarrierTooLargeError";
+  }
+}
+
+/** Encode a serialised registry as a carrier line. Throws past the cap. */
+export function encodeRegistryCarrier(registryText: string): string {
+  const b64 = gzipSync(Buffer.from(registryText, "utf-8")).toString("base64");
+  const line = `[${WRITE_PREFIX}-registry:v3]: #${WRITE_PREFIX} "${b64}"`;
+  if (line.length > MAX_CARRIER_CHARS) throw new CarrierTooLargeError(line.length);
+  return line;
+}
+
+export type CarrierExtraction =
+  | { kind: "none"; body: string }
+  | { kind: "found"; body: string; registryText: string }
+  | { kind: "rejected"; body: string; reason: string };
+
+/**
+ * Take the registry carrier out of pulled Page content. The body always comes
+ * back without any carrier-shaped line, so a carrier never lands in the
+ * notebook whatever happens to it. More than one carrier, an oversized one, or
+ * one that doesn't decode is rejected as a whole.
+ */
+export function extractRegistryCarrier(content: string): CarrierExtraction {
+  const kept: string[] = [];
+  const found: string[] = [];
+  let malformed = false;
+  for (const line of content.split("\n")) {
+    if (!LOOKS_LIKE.test(line)) {
+      kept.push(line);
+      continue;
+    }
+    const m = line.match(LINE);
+    if (!m) malformed = true;
+    else found.push(m[1]);
+    if (line.length > MAX_CARRIER_CHARS) malformed = true;
+  }
+  // Push puts the carrier after a blank line at the end; take that with it.
+  const removed = kept.length !== content.split("\n").length;
+  const body = removed ? kept.join("\n").replace(/\s+$/, "") + "\n" : content;
+  if (malformed) return { kind: "rejected", body, reason: "malformed or oversized carrier" };
+  if (found.length === 0) return { kind: "none", body };
+  if (found.length > 1) return { kind: "rejected", body, reason: `${found.length} carriers` };
+  if (found[0].length > MAX_CARRIER_CHARS) {
+    return { kind: "rejected", body, reason: "oversized carrier" };
+  }
+  let registryText: string;
+  try {
+    const raw = gunzipSync(Buffer.from(found[0], "base64"), {
+      maxOutputLength: MAX_CARRIER_DECODED_BYTES,
+    });
+    registryText = raw.toString("utf-8");
+  } catch (err) {
+    return { kind: "rejected", body, reason: `carrier doesn't decode: ${(err as Error).message}` };
+  }
+  return { kind: "found", body, registryText };
+}

package/extensions/orbit/registry-eligibility.ts

@@ -0,0 +1,95 @@
+/**
+ * `handoff_eligible` (registry design v3 §7) as a pure function of an attempt
+ * and the registry's exceptions.
+ *
+ * The formula is v3's. The checks after it are cross-checks against the facts
+ * the evaluation was supposed to be derived from, so an evaluation that claims
+ * more than the attempt supports -- a manual predicate "passed" with no user
+ * attestation, an `excepted` conformity with no user exception behind it,
+ * `integrity: ok` on a run Galaxy never confirmed -- fails closed instead of
+ * being believed. None of
+ * them can make an attempt eligible that the formula alone would not.
+ */
+
+import type { Attempt, Exception } from "./registry-schema";
+
+export function computeHandoffEligible(
+  attempt: Attempt,
+  exceptions: readonly Exception[] = [],
+): boolean {
+  const ev = attempt.evaluation;
+  const pv = attempt.provenance;
+  if (!ev || !pv) return false;
+
+  const formula =
+    ev.execution === "success" &&
+    (ev.conformity === "conformant" || ev.conformity === "excepted") &&
+    (ev.predicate_result === "pass" || ev.predicate_result === "attested") &&
+    ev.integrity === "ok" &&
+    ev.authority === "established" &&
+    pv.authority === "established";
+  if (!formula) return false;
+
+  // Integrity is `unverified_identity` while Galaxy hasn't confirmed the run.
+  if (!attempt.submission?.server_verified) return false;
+
+  // Every way past a check is a user exception for this attempt and, when there
+  // is an approval, its revision -- one scope per check, so attesting a result
+  // can't also excuse how it was submitted. An ungated attempt has no approval to
+  // match, which is why v3 §6 lets only an exception make it eligible.
+  const revision = attempt.approval?.spec_revision;
+  const userExcepted = (scope: Exception["scope"], assertionId?: string) =>
+    exceptions.some(
+      (x) =>
+        x.attempt_id === attempt.attempt_id &&
+        x.by === "user" &&
+        x.scope === scope &&
+        x.assertion_id === assertionId &&
+        (revision === undefined || x.spec_revision === revision),
+    );
+
+  if (ev.conformity === "conformant") {
+    const outcome = attempt.submission.check.outcome;
+    if (outcome === "conformant_by_construction") {
+      // The harness built the request from a user approval in this session.
+      if (attempt.approval?.by !== "user") return false;
+      // A revoked approval no longer vouches for the run, even one it already submitted.
+      if (attempt.approval.status !== "live") return false;
+    } else if (outcome === "conformant_by_reconcile") {
+      // Galaxy's account of the run matched the frozen Spec when this session
+      // checked. That's an execution fact, not consent, so a restored approval
+      // is enough to check against -- but a revoked one still withdraws it.
+      if (!attempt.approval || attempt.approval.status === "revoked") return false;
+    } else {
+      return false;
+    }
+  } else if (!userExcepted("submission_check")) {
+    return false;
+  }
+
+  // What a person vouches for counts, but under its own label: a result no code
+  // checked is `attested`, never `pass`, and needs the attestation on record.
+  const attested = () => ev.predicate_result === "attested" && userExcepted("manual_attestation");
+
+  const spec = attempt.approval?.spec_snapshot;
+  if (!spec) {
+    // Ungated: there's no frozen predicate to hold the evaluation to, so the
+    // result has to be attested. Excusing how it was submitted doesn't excuse
+    // what came out.
+    return attested();
+  }
+  const predicate = spec.predicate;
+  if (predicate.kind === "manual") return attested();
+  // Only a manual predicate is the user's to vouch for; the rest are checked.
+  if (ev.predicate_result !== "pass") return false;
+  if (predicate.kind === "assertions_pass") {
+    if (predicate.ids.length === 0) return false;
+    // An excepted assertion is a failure the user chose to accept; it counts
+    // only with their evidence-gate exception naming that assertion.
+    const accepted = (id: string) =>
+      ev.assertions[id] === "pass" ||
+      (ev.assertions[id] === "excepted" && userExcepted("evidence_gate", id));
+    if (!predicate.ids.every(accepted)) return false;
+  }
+  return true;
+}

package/extensions/orbit/registry-evaluation.ts

@@ -0,0 +1,403 @@
+/**
+ * The evaluation half of the registry (design v3 §7): given an attempt and
+ * what Galaxy said about its run in this session, decide the four facts and
+ * what the submission check now says.
+ *
+ * Pure and pi-free, like the rest of the trusted core. The harness gathers the
+ * facts (`registry-evaluator.ts`) and writes the result through the store; this
+ * module only reads them. Nothing here takes a fact from the notebook.
+ *
+ * Fails toward "not shown". A fact that can't be read is `unknown` or
+ * `unevaluable`, and a comparison that can't be made exactly is `unverified`,
+ * never a match. A mismatch is only claimed when both sides were read and
+ * differ.
+ */
+
+import {
+  canonicalJson,
+  sha256Hex,
+  type Attempt,
+  type Diff,
+  type Exception,
+  type Predicate,
+  type Spec,
+} from "./registry-schema";
+
+/** One dataset a job read or wrote, as Galaxy reported it. */
+export interface RunDataset {
+  name: string;
+  id: string;
+  src?: string;
+  ext?: string;
+  state?: string;
+}
+
+/** One job of the run. Absent fields are ones Galaxy didn't give. */
+export interface RunJob {
+  job_id: string;
+  tool_id?: string;
+  tool_version?: string;
+  state?: string;
+  params?: Record<string, unknown>;
+  inputs?: RunDataset[];
+  outputs?: RunDataset[];
+  /** Set when the job's details couldn't be fetched. */
+  unavailable?: string;
+}
+
+/**
+ * What the harness learned about one attempt's run from Galaxy, this session.
+ * Built only from Galaxy's answers; the notebook never contributes.
+ */
+export interface RunFacts {
+  kind: "invocation" | "job";
+  run_id: string;
+  /** Galaxy answered for exactly this id on this session's server. */
+  verified: boolean;
+  /**
+   * `success`: done, and every job ok. `failed`: done, and something errored,
+   * was cancelled, or Galaxy failed it. `running`: Galaxy can still move it.
+   * `unknown`: couldn't tell, or done with nothing that succeeded.
+   */
+  state: "success" | "failed" | "running" | "unknown";
+  history_id?: string;
+  jobs: RunJob[];
+  /** Invocation only: the workflow inputs Galaxy recorded, by step index. */
+  workflow_inputs?: Record<string, { id: string; src?: string }>;
+  /** `fixture` when the Tier-1 seam answered instead of a server. */
+  source: "galaxy" | "fixture";
+}
+
+export type ConformityCheck =
+  | { outcome: "match" }
+  | { outcome: "mismatch"; diff: Diff[] }
+  | { outcome: "unverifiable"; reason: string };
+
+/**
+ * Walk a Galaxy flat parameter path (`queries_0|input2`) into a job's
+ * effective params. Galaxy hands top-level values back JSON-encoded as often
+ * as not, so a string that parses is read as what it encodes. Undefined when
+ * any step doesn't resolve.
+ */
+export function effectiveParam(params: Record<string, unknown>, path: string): unknown {
+  const decode = (v: unknown): unknown => {
+    if (typeof v !== "string") return v;
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  };
+  let node: unknown = params;
+  for (const part of path.split("|")) {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return undefined;
+    const rec = node as Record<string, unknown>;
+    if (Object.prototype.hasOwnProperty.call(rec, part)) {
+      node = decode(rec[part]);
+      continue;
+    }
+    // A repeat element: `queries_0` is `queries[0]`.
+    const m = part.match(/^(.+)_(\d+)$/);
+    if (!m || !Object.prototype.hasOwnProperty.call(rec, m[1])) return undefined;
+    const list = decode(rec[m[1]]);
+    if (!Array.isArray(list)) return undefined;
+    node = decode(list[Number(m[2])]);
+    if (node === undefined) return undefined;
+  }
+  return node;
+}
+
+/**
+ * Whether an observed value is the approved one. Galaxy stores scalars as
+ * strings and dataset parameters as `{src, id}`, so both of those are read
+ * through; anything else has to be canonically equal.
+ */
+export function sameValue(approved: unknown, observed: unknown): boolean | undefined {
+  if (observed === undefined) return undefined;
+  if (observed && typeof observed === "object" && !Array.isArray(observed)) {
+    const o = observed as Record<string, unknown>;
+    // `{values: [{src, id}]}` and `{src, id}` are how a data parameter comes back.
+    const values = Array.isArray(o.values) ? o.values : [o];
+    const ids = values
+      .map((v) => (v && typeof v === "object" ? (v as Record<string, unknown>).id : undefined))
+      .filter((id): id is string => typeof id === "string");
+    if (ids.length > 0 && (typeof approved === "string" || Array.isArray(approved))) {
+      const want = Array.isArray(approved) ? approved.map(String) : [approved];
+      return canonicalJson([...want].sort()) === canonicalJson([...ids].sort());
+    }
+  }
+  if (approved === null || typeof approved !== "object") {
+    if (observed === null || typeof observed !== "object") {
+      return String(approved) === String(observed);
+    }
+    return false;
+  }
+  try {
+    return canonicalJson(approved) === canonicalJson(observed);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Re-check the run Galaxy reports against the frozen Spec (the
+ * `conformant_by_reconcile` route). Tools and user-defined tools are compared
+ * job by job: tool id, version, every approved input and every override.
+ * Workflows can't be compared yet -- an invocation doesn't report the stored
+ * workflow or its version -- so they come back unverifiable.
+ */
+export function checkConformity(spec: Spec, facts: RunFacts): ConformityCheck {
+  if (!facts.verified) return { outcome: "unverifiable", reason: "run not verified on Galaxy" };
+  if (spec.target.kind === "workflow") {
+    return {
+      outcome: "unverifiable",
+      reason: "an invocation doesn't report which workflow version ran",
+    };
+  }
+  if (facts.kind !== "job") {
+    return { outcome: "unverifiable", reason: "a tool approval recorded against an invocation" };
+  }
+  // Where it ran is part of what was approved: a matching job in some other
+  // history is some other run.
+  if (facts.history_id === undefined) {
+    return { outcome: "unverifiable", reason: "history not reported" };
+  }
+  if (facts.history_id !== spec.history_id) {
+    return {
+      outcome: "mismatch",
+      diff: [{ path: "history_id", approved: spec.history_id, observed: facts.history_id }],
+    };
+  }
+  // One job for a plain run, many when it mapped over. A job whose details
+  // never came could have run anything.
+  const jobs = facts.jobs;
+  if (jobs.length === 0) return { outcome: "unverifiable", reason: "no job details" };
+  if (jobs.some((j) => j.unavailable)) {
+    return { outcome: "unverifiable", reason: "some job details unavailable" };
+  }
+  const diff: Diff[] = [];
+  let unknown: string | null = null;
+  const wantTool = spec.target.kind === "udt" ? spec.target.tool_uuid : spec.target.tool_id;
+
+  for (const job of jobs) {
+    const at = (p: string) => `jobs.${job.job_id}.${p}`;
+    if (job.tool_id === undefined || wantTool === undefined) unknown ??= "tool id not reported";
+    else if (spec.target.kind === "tool" && job.tool_id !== wantTool) {
+      diff.push({ path: at("tool_id"), approved: wantTool, observed: job.tool_id });
+    }
+    if (spec.target.kind === "udt") {
+      // A user-defined tool's job reports a tool id Galaxy minted, not its
+      // uuid, so the target is only checked through the definition digest
+      // slice 3 re-checks at dispatch. Say so rather than calling it a match.
+      unknown ??= "a user-defined tool's job doesn't name its uuid";
+    }
+    if (job.tool_version === undefined) unknown ??= "tool version not reported";
+    else if (job.tool_version !== spec.target.version) {
+      diff.push({
+        path: at("tool_version"),
+        approved: spec.target.version,
+        observed: job.tool_version,
+      });
+    }
+    for (const input of spec.inputs) {
+      if (input.src !== "hda") {
+        // A collection maps over: each job sees an element, not the collection.
+        unknown ??= `input ${input.slot} is a ${input.src}`;
+        continue;
+      }
+      const seen = job.inputs?.find((d) => d.name === input.slot);
+      if (!job.inputs) unknown ??= "job inputs not reported";
+      else if (!seen) unknown ??= `input ${input.slot} not reported`;
+      else if (seen.id !== input.id) {
+        diff.push({ path: at(`inputs.${input.slot}`), approved: input.id, observed: seen.id });
+      }
+    }
+    for (const o of spec.overrides) {
+      if (!job.params) {
+        unknown ??= "job parameters not reported";
+        continue;
+      }
+      const observed = effectiveParam(job.params, o.param);
+      const same = sameValue(o.value, observed);
+      if (same === undefined) unknown ??= `parameter ${o.param} not reported`;
+      else if (!same) diff.push({ path: at(`params.${o.param}`), approved: o.value, observed });
+    }
+  }
+  if (diff.length > 0) return { outcome: "mismatch", diff };
+  if (unknown) return { outcome: "unverifiable", reason: unknown };
+  return { outcome: "match" };
+}
+
+/** This attempt's own outputs: datasets its jobs wrote. Never an older dataset. */
+function outputsOf(facts: RunFacts): RunDataset[] {
+  const out = new Map<string, RunDataset>();
+  for (const job of facts.jobs) for (const d of job.outputs ?? []) out.set(d.id, d);
+  return [...out.values()];
+}
+
+/**
+ * The predicate over this attempt's outputs. `manual` and `assertions_pass`
+ * are never evaluated here: a manual one is the user's call (attested through
+ * an exception), and assertions don't exist yet (#477).
+ */
+export function evaluatePredicate(
+  predicate: Predicate,
+  facts: RunFacts,
+): "pass" | "fail" | "unevaluable" {
+  if (facts.state !== "success") return "unevaluable";
+  if (predicate.kind === "manual" || predicate.kind === "assertions_pass") return "unevaluable";
+  const outputs = outputsOf(facts);
+  if (facts.jobs.some((j) => !j.outputs)) return "unevaluable";
+  const matching = outputs.filter(
+    (d) => (predicate.ext === undefined || d.ext === predicate.ext) && d.state === "ok",
+  );
+  if (outputs.some((d) => d.ext === undefined && predicate.ext !== undefined)) {
+    return "unevaluable";
+  }
+  if (predicate.kind === "exists_with_ext") {
+    return matching.length >= (predicate.min_count ?? 1) ? "pass" : "fail";
+  }
+  return matching.length === predicate.count ? "pass" : "fail";
+}
+
+/** The `spec_revision` an exception on an attempt with no approval carries. */
+export const NO_APPROVAL_REVISION = "0".repeat(64);
+
+function userException(
+  attempt: Attempt,
+  exceptions: readonly Exception[],
+  scope: Exception["scope"],
+): boolean {
+  const revision = attempt.approval?.spec_revision ?? NO_APPROVAL_REVISION;
+  return exceptions.some(
+    (x) =>
+      x.attempt_id === attempt.attempt_id &&
+      x.by === "user" &&
+      x.scope === scope &&
+      x.assertion_id === undefined &&
+      x.spec_revision === revision,
+  );
+}
+
+export interface EvaluationResult {
+  evaluation: NonNullable<Attempt["evaluation"]>;
+  provenance: NonNullable<Attempt["provenance"]>;
+  /** The submission's check and identity as this evaluation leaves them. */
+  check: NonNullable<Attempt["submission"]>["check"];
+  server_verified: boolean;
+}
+
+/**
+ * Evaluate one attempt that has a submission against facts gathered this
+ * session. The caller writes the result; `computeHandoffEligible` then derives
+ * the flag and cross-checks every claim here against the attempt.
+ *
+ * `factsRef` names where the facts are stored; the provenance digest is theirs.
+ */
+export function evaluateAttempt(
+  attempt: Attempt,
+  facts: RunFacts,
+  exceptions: readonly Exception[],
+  opts: {
+    now: string;
+    factsRef: string;
+    /**
+     * Whether the template the approval froze is in this registry's store and
+     * hashes to its name. A Spec that arrived without one -- in a carrier, say
+     * -- was never checked against anything, so a run matching it shows nothing.
+     */
+    templateFrozen?: boolean;
+  },
+): EvaluationResult {
+  const submission = attempt.submission;
+  if (!submission) throw new Error(`attempt ${attempt.attempt_id} has no submission`);
+  const execution: NonNullable<Attempt["evaluation"]>["execution"] =
+    facts.state === "success" ? "success" : facts.state === "failed" ? "failed" : "unknown";
+
+  // Fixture answers are not a server's word: they exercise the path in Tier-1
+  // without ever counting as established.
+  const established = facts.source === "galaxy" && facts.verified;
+
+  let check = { ...submission.check };
+  delete check.diff;
+  const spec = attempt.approval?.spec_snapshot;
+  if (check.outcome !== "conformant_by_construction" && spec && execution !== "unknown") {
+    const c = checkConformity(spec, facts);
+    const attemptHistory =
+      facts.history_id !== undefined && facts.history_id !== attempt.history_id
+        ? [{ path: "attempt.history_id", approved: attempt.history_id, observed: facts.history_id }]
+        : [];
+    if (attemptHistory.length > 0) {
+      check = {
+        outcome: "mismatch",
+        mode: check.mode,
+        diff: [...attemptHistory, ...(c.outcome === "mismatch" ? c.diff : [])],
+      };
+    } else if (c.outcome === "match" && !opts.templateFrozen) {
+      check = { outcome: "unverified", mode: check.mode };
+    } else if (c.outcome === "match")
+      check = { outcome: "conformant_by_reconcile", mode: check.mode };
+    else if (c.outcome === "mismatch")
+      check = { outcome: "mismatch", mode: check.mode, diff: c.diff };
+    else check = { outcome: "unverified", mode: check.mode };
+  } else if (check.outcome === "conformant_by_construction" && spec && facts.verified) {
+    // Built from the Spec, but Galaxy may still have run something else (a
+    // version swapped under the request). A definite difference is an
+    // effective contradiction; anything less leaves construction standing.
+    const c = checkConformity(spec, facts);
+    if (c.outcome === "mismatch") {
+      check = { outcome: "conformant_by_construction", mode: check.mode, diff: c.diff };
+    }
+  }
+  const effectiveContradiction =
+    check.outcome === "conformant_by_construction" && (check.diff?.length ?? 0) > 0;
+
+  const conformity: NonNullable<Attempt["evaluation"]>["conformity"] = userException(
+    attempt,
+    exceptions,
+    "submission_check",
+  )
+    ? "excepted"
+    : effectiveContradiction || check.outcome === "mismatch"
+      ? "nonconformant"
+      : check.outcome === "conformant_by_construction" ||
+          check.outcome === "conformant_by_reconcile"
+        ? "conformant"
+        : "unverified";
+
+  let predicate_result: NonNullable<Attempt["evaluation"]>["predicate_result"];
+  if (!spec || spec.predicate.kind === "manual") {
+    predicate_result =
+      execution === "success" && userException(attempt, exceptions, "manual_attestation")
+        ? "attested"
+        : "unevaluable";
+  } else {
+    predicate_result = evaluatePredicate(spec.predicate, facts);
+  }
+
+  const integrity: NonNullable<Attempt["evaluation"]>["integrity"] = !facts.verified
+    ? "unverified_identity"
+    : effectiveContradiction
+      ? "effective_contradiction"
+      : "ok";
+
+  return {
+    evaluation: {
+      execution,
+      conformity,
+      predicate_result,
+      assertions: {},
+      integrity,
+      authority: established ? "established" : "historical",
+      evaluated_at: opts.now,
+    },
+    provenance: {
+      ref: { kind: "file", id: opts.factsRef },
+      digest: sha256Hex(canonicalJson(facts)),
+      enrichment: facts.jobs.some((j) => j.unavailable) ? "unavailable" : "complete",
+      authority: established ? "established" : "historical",
+    },
+    check,
+    server_verified: facts.verified,
+  };
+}