@manta-eu/react 0.1.9 → 0.2.0

package/src/routes/memories/components/badges.tsx

@@ -0,0 +1,235 @@
+import { GQLMemoryScope, type GQLMemoryKind } from "@manta-eu/client";
+import {
+  describeMemoryPreloadExclusions,
+  isMemoryArchived,
+  isMemorySearchable,
+  memoryPreloadExclusions,
+  type MemoryPreloadCandidate,
+} from "@manta-eu/client/shared/memory-preload-gate";
+import { formatEntityName } from "@manta-eu/client/shared/rdf-namespaces";
+import { isPresent } from "@manta-eu/lib/present";
+import { CopyCheck, Link2, Quote } from "lucide-react";
+import { match, P } from "ts-pattern";
+import { unconfirmedHorizonLabel, type MemoryWindowState } from "../expiry-utils";
+import { Badge } from "#components/badge/index";
+import { Tooltip, TooltipContent, TooltipTrigger } from "#components/tooltip/index";
+import { cn } from "#lib/utils";
+
+export type ScopeBadgeProps = { scope: GQLMemoryScope };
+
+export function ScopeBadge(props: ScopeBadgeProps) {
+  const { scope } = props;
+  const { className, label } = match(scope)
+    .with(GQLMemoryScope.Company, () => ({ className: "bg-accent/10 text-accent-foreground", label: "Company" }))
+    .with(GQLMemoryScope.Team, () => ({ className: "bg-warning/10 text-warning-foreground", label: "Team" }))
+    .with(GQLMemoryScope.User, () => ({ className: "bg-muted-foreground/10 text-muted-foreground", label: "Personal" }))
+    .exhaustive();
+
+  return (
+    <Badge size="sm" className={className}>
+      {label}
+    </Badge>
+  );
+}
+
+function autoCapturedTooltip(confidence: number): string {
+  const pct = Math.round(confidence * 100);
+  const prefix = `Auto-captured from chat history (${pct}% confidence).`;
+
+  // TODO: revisit these confidence tiers/copy - refine until good enough or drop entirely.
+  const note = match(confidence)
+    .with(P.number.gte(0.9), () => "Likely accurate, but worth a quick glance.")
+    .with(P.number.gte(0.7), () => "Decent signal - review before relying on it.")
+    .with(P.number.gte(0.5), () => "Moderate confidence - verify this.")
+    .otherwise(() => "Low confidence - treat with caution.");
+  return `${prefix} ${note}`;
+}
+
+export function AutoCapturedBadge(props: { confidence: number }) {
+  const { confidence } = props;
+  const pct = Math.round(confidence * 100);
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Badge size="sm" className="bg-faint border border-muted-border text-muted-foreground cursor-default">
+          Captured · {pct}%
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs typography-small">{autoCapturedTooltip(confidence)}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+export type DuplicateMatch = { label: string; reason: string };
+
+export function DuplicateBadge(props: { matches: DuplicateMatch[] }) {
+  const { matches } = props;
+  if (!isPresent(matches)) return null;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Badge size="sm" className="bg-warning/10 text-warning-foreground border border-warning/30 cursor-default">
+          <CopyCheck className="size-3" />
+          Possible duplicate
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs typography-small text-left">
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground">Looks like it duplicates:</span>
+          {matches.map((match) => (
+            <div key={match.label}>
+              <span className="typography-small-medium">{match.label}</span>
+              {match.reason ? ` - ${match.reason}` : ""}
+            </div>
+          ))}
+        </div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+export type KindBadgeProps = {
+  kind: GQLMemoryKind;
+};
+
+export function KindBadge(props: KindBadgeProps) {
+  const { kind } = props;
+
+  return (
+    <Badge size="sm" variant="secondary" className="capitalize">
+      {kind}
+    </Badge>
+  );
+}
+
+export type SchemaBadgeProps = {
+  label?: string | null;
+};
+
+export function SchemaBadge(props: SchemaBadgeProps) {
+  const { label } = props;
+  if (!label) return null;
+
+  return (
+    <Badge size="sm" variant="secondary" className="max-w-[28ch] truncate" title={label}>
+      {label}
+    </Badge>
+  );
+}
+
+const outOfWindowCopy = {
+  expired: {
+    label: "Expired",
+    why: "Its expiry date has passed, so the agent can neither pre-load nor search it. Nothing was deleted — edit the expiry date to bring it back.",
+  },
+  scheduled: {
+    label: "Scheduled",
+    why: "Its start date is in the future, so the agent cannot use it yet. Edit the start date to bring it forward.",
+  },
+} as const;
+
+export type OutOfWindowBadgeProps = { state: Exclude<MemoryWindowState, "active"> };
+
+export function OutOfWindowBadge(props: OutOfWindowBadgeProps) {
+  const { label, why } = outOfWindowCopy[props.state];
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Badge size="sm" className="bg-warning/10 text-warning-foreground border border-warning/30 cursor-default">
+          {label}
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs typography-small">{why}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+export type PreloadedBadgeProps = { memory: MemoryPreloadCandidate };
+
+export type PreloadBadgeTone = "pinned" | "heldOut" | "unreachable";
+
+export type PreloadBadgeContent = {
+  label: "Pinned" | "Unconfirmed" | "Unreachable" | "Cold";
+  preloaded: boolean;
+  tone: PreloadBadgeTone;
+  why: string;
+};
+
+export function preloadBadgeContent(memory: MemoryPreloadCandidate, now?: Date): PreloadBadgeContent | null {
+  if (isMemoryArchived(memory)) return null;
+
+  const exclusions = memoryPreloadExclusions(memory, now);
+  const preloaded = !isPresent(exclusions);
+  const why = describeMemoryPreloadExclusions(memory, exclusions);
+
+  if (preloaded) return { label: "Pinned", preloaded, tone: "pinned", why };
+  if (!isMemorySearchable(memory)) return { label: "Unreachable", preloaded, tone: "unreachable", why };
+  if (exclusions.includes("importance")) return null;
+  if (exclusions.length === 1 && exclusions[0] === "cold") {
+    return { label: "Cold", preloaded, tone: "heldOut", why };
+  }
+  return { label: unconfirmedHorizonLabel, preloaded, tone: "heldOut", why };
+}
+
+const preloadBadgeToneClass: Record<PreloadBadgeTone, string> = {
+  pinned: "bg-faint border-muted-border text-default-foreground",
+  heldOut: "bg-muted-foreground/10 border-muted-border text-muted-foreground",
+  unreachable: "bg-warning/10 border-warning/30 text-warning-foreground",
+};
+
+export function PreloadedBadge(props: PreloadedBadgeProps) {
+  const content = preloadBadgeContent(props.memory);
+  if (!content) return null;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Badge size="sm" className={cn("border cursor-default", preloadBadgeToneClass[content.tone])}>
+          {content.label}
+        </Badge>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs typography-small">{content.why}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+export type MemoryEvidenceProps = { evidence?: string | null };
+
+export function MemoryEvidence(props: MemoryEvidenceProps) {
+  const { evidence } = props;
+  if (!isPresent(evidence)) return null;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="mt-1 flex cursor-default items-start gap-1.5 border-l-2 border-muted-border pl-2 typography-tiny italic text-muted-foreground">
+          <Quote className="mt-0.5 size-3 shrink-0" />
+          <span className="line-clamp-2 break-words">{evidence}</span>
+        </span>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs typography-small text-left">
+        What the user said that this memory was extracted from. Chat history is deleted after 30 days, so this quote
+        stays as the record of where the memory came from.
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+export type MemoryAboutProps = { aboutEntityIris?: string[] | null };
+
+export function MemoryAbout(props: MemoryAboutProps) {
+  const { aboutEntityIris } = props;
+  if (!isPresent(aboutEntityIris)) return null;
+
+  return (
+    <span className="mt-1 flex flex-wrap items-center gap-1">
+      <Link2 className="size-3 shrink-0 text-muted-foreground" />
+      {aboutEntityIris.map((iri) => (
+        <Badge key={iri} size="sm" variant="secondary" className="max-w-[24ch] truncate" title={iri}>
+          {formatEntityName(iri)}
+        </Badge>
+      ))}
+    </span>
+  );
+}

package/src/routes/memories/expiry-utils.ts

@@ -0,0 +1,117 @@
+import {
+  isPastTrustedUntilAt,
+  parseMemoryDate,
+  validFromWorthShowingDays,
+} from "@manta-eu/client/shared/memory-preload-gate";
+import { differenceInCalendarDays, format } from "date-fns";
+import { match } from "ts-pattern";
+
+// Compares by timestamp, not calendar day, so a memory expiring tonight is not expired yet.
+export function formatExpiryRelative(expiresAt: Date | string | null | undefined, now: Date = new Date()): string {
+  const at = parseMemoryDate(expiresAt);
+  if (!at) return "Never expires";
+  if (at.getTime() <= now.getTime()) return "Expired";
+  const days = differenceInCalendarDays(at, now);
+  if (days <= 0) return "Expires today";
+  if (days === 1) return "Expires tomorrow";
+  return `Expires in ${days}d`;
+}
+
+export function formatExpiryDate(expiresAt: Date | string | null | undefined, now: Date = new Date()): string {
+  const at = parseMemoryDate(expiresAt);
+  if (!at) return "Never";
+  if (at.getTime() <= now.getTime()) return "Expired";
+  return format(at, "MMM d, yyyy");
+}
+
+export type MemoryHorizon =
+  | { kind: "none"; at: null }
+  | { kind: "expiry"; at: Date | string }
+  | { kind: "trust"; at: Date | string };
+
+export function memoryHorizon(
+  memoryValidUntil: Date | string | null | undefined,
+  memoryTrustedUntil: Date | string | null | undefined,
+): MemoryHorizon {
+  if (memoryValidUntil) return { kind: "expiry", at: memoryValidUntil };
+  if (memoryTrustedUntil) return { kind: "trust", at: memoryTrustedUntil };
+  return { kind: "none", at: null };
+}
+
+export type MemoryWindowState = "active" | "expired" | "scheduled";
+
+export function memoryWindowState(
+  memoryValidFrom: Date | string | null | undefined,
+  memoryValidUntil: Date | string | null | undefined,
+  now: Date = new Date(),
+): MemoryWindowState {
+  const until = parseMemoryDate(memoryValidUntil);
+  if (until && until.getTime() <= now.getTime()) return "expired";
+  const from = parseMemoryDate(memoryValidFrom);
+  if (from && from.getTime() > now.getTime()) return "scheduled";
+  return "active";
+}
+
+// Past horizon means the data is still valid and never deleted, just no longer relied on.
+export function isTrustExpired(memoryTrustedUntil: Date | string | null | undefined, now: Date = new Date()): boolean {
+  return isPastTrustedUntilAt(memoryTrustedUntil, now);
+}
+
+export const unconfirmedHorizonLabel = "Unconfirmed";
+
+export function formatHorizonDate(horizon: MemoryHorizon, now: Date = new Date()): string {
+  return match(horizon)
+    .with({ kind: "none" }, () => "Never")
+    .with({ kind: "expiry" }, ({ at }) => formatExpiryDate(at, now))
+    .with({ kind: "trust" }, ({ at }) => {
+      const parsed = parseMemoryDate(at);
+      if (!parsed) return "Never";
+      return isTrustExpired(at, now) ? unconfirmedHorizonLabel : `~${format(parsed, "MMM d, yyyy")}`;
+    })
+    .exhaustive();
+}
+
+function trustedForLabel(at: Date | string, now: Date): string {
+  const parsed = parseMemoryDate(at);
+  if (!parsed) return "Never expires";
+  const days = differenceInCalendarDays(parsed, now);
+  if (days <= 0) return "Trusted until today";
+  return days === 1 ? "Trusted until tomorrow" : `Trusted for ${days}d`;
+}
+
+export function formatHorizonRelative(horizon: MemoryHorizon, now: Date = new Date()): string {
+  return match(horizon)
+    .with({ kind: "none" }, () => "Never expires")
+    .with({ kind: "expiry" }, ({ at }) => formatExpiryRelative(at, now))
+    .with({ kind: "trust" }, ({ at }) => (isTrustExpired(at, now) ? unconfirmedHorizonLabel : trustedForLabel(at, now)))
+    .exhaustive();
+}
+
+export function compareMemoryHorizons(a: MemoryHorizon, b: MemoryHorizon): number {
+  const left = parseMemoryDate(a.at);
+  const right = parseMemoryDate(b.at);
+  if (!left || !right) return left ? -1 : right ? 1 : 0;
+  return left.getTime() - right.getTime();
+}
+
+export function shouldShowValidFrom(
+  updatedAt: Date | string | null | undefined,
+  memoryValidFrom: Date | string | null | undefined,
+): boolean {
+  const since = parseMemoryDate(memoryValidFrom);
+  const recorded = parseMemoryDate(updatedAt);
+  if (!since || !recorded) return false;
+  return differenceInCalendarDays(recorded, since) >= validFromWorthShowingDays;
+}
+
+export function formatHorizonTooltip(horizon: MemoryHorizon, now: Date = new Date()): string {
+  return match(horizon)
+    .with({ kind: "none" }, () => "Never expires")
+    .with({ kind: "expiry" }, ({ at }) => `No longer true after this date. ${formatExpiryRelative(at, now)}`)
+    .with({ kind: "trust" }, (trust) =>
+      isTrustExpired(trust.at, now)
+        ? "Past the date it was trusted until, so it no longer pre-loads into conversations. Still true, still searchable, and never deleted."
+        : `Stops pre-loading into conversations after this date, but stays searchable. ${formatHorizonRelative(trust, now)}`,
+    )
+    .exhaustive();
+}

package/src/routes/memories/hooks/useConflictCheck.ts

@@ -0,0 +1,66 @@
+import {
+  DetectMemoryConflictsDocument,
+  GQLMemoryScope,
+  type GQLConflictingMemory,
+  type GQLDetectMemoryConflictsQuery,
+  type GQLDetectMemoryConflictsQueryVariables,
+} from "@manta-eu/client";
+import { useCallback, useState } from "react";
+import { useMantaClient } from "#providers/index";
+
+const conflictCheckTimeoutMs = 15_000;
+
+export type ConflictCheckInput = {
+  label: string;
+  description: string;
+  scope: GQLMemoryScope;
+  teams?: string[];
+  excludeIri?: string;
+};
+
+export type ConflictCheckResult = {
+  conflicts: GQLConflictingMemory[];
+  timedOut: boolean;
+};
+
+export type UseConflictCheckResult = {
+  check: (input: ConflictCheckInput) => Promise<ConflictCheckResult>;
+  isChecking: boolean;
+};
+
+export function useConflictCheck(): UseConflictCheckResult {
+  const { mantaClient } = useMantaClient();
+  const [isChecking, setIsChecking] = useState(false);
+
+  const check = useCallback(
+    async (input: ConflictCheckInput): Promise<ConflictCheckResult> => {
+      setIsChecking(true);
+      try {
+        const result = await mantaClient.request<GQLDetectMemoryConflictsQuery, GQLDetectMemoryConflictsQueryVariables>(
+          {
+            document: DetectMemoryConflictsDocument,
+            variables: {
+              input: {
+                label: input.label,
+                description: input.description,
+                scope: input.scope,
+                teams: input.scope === GQLMemoryScope.Team ? (input.teams ?? []) : undefined,
+                excludeIri: input.excludeIri ?? undefined,
+                wantToStopAfterMs: conflictCheckTimeoutMs,
+              },
+            },
+            signal: AbortSignal.timeout(conflictCheckTimeoutMs + 5_000),
+          },
+        );
+        return result.detectMemoryConflicts;
+      } catch {
+        return { conflicts: [], timedOut: false };
+      } finally {
+        setIsChecking(false);
+      }
+    },
+    [mantaClient],
+  );
+
+  return { check, isChecking };
+}

package/src/routes/memories/hooks/useDuplicateDetection.ts

@@ -0,0 +1,90 @@
+import type { GQLConflictingMemory, GQLMemory } from "@manta-eu/client";
+import { isPresent } from "@manta-eu/lib/present";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useConflictCheck } from "./useConflictCheck";
+
+export type DuplicateMatches = Map<string, GQLConflictingMemory[]>;
+
+// Caps how many memories run semantic detection in one pass, so a large unreviewed queue
+// cannot fan out into an unbounded number of detection calls.
+const defaultMaxChecks = 25;
+
+// Only memories with a description carry enough signal for semantic comparison.
+export function pickDuplicateTargets(memories: GQLMemory[], max: number = defaultMaxChecks): GQLMemory[] {
+  return memories.filter((m) => isPresent(m.description)).slice(0, max);
+}
+
+function buildMemoryKey(memory: GQLMemory): string {
+  return `${memory.iri}:${memory.scope}:${memory.label}:${memory.description ?? ""}`;
+}
+
+function targetSignature(memories: GQLMemory[]): string {
+  return memories.map(buildMemoryKey).join("|");
+}
+
+// Runs the existing semantic conflict check (SEMSIM recall pre-filter + LLM precision judge)
+// across a set of memories and returns, per memory IRI, the existing memories it likely
+// duplicates. Results are cached by IRI+label+description so re-renders and tab switches do
+// not re-issue detection for unchanged memories. Nothing is mutated — this only surfaces
+// candidates; the user still confirms any supersession in the review dialog.
+export function useDuplicateDetection(
+  memories: GQLMemory[],
+  options: { enabled?: boolean; max?: number } = {},
+): { duplicates: DuplicateMatches; isDetecting: boolean } {
+  const { enabled = true, max = defaultMaxChecks } = options;
+  const { check } = useConflictCheck();
+
+  const targets = useMemo(() => (enabled ? pickDuplicateTargets(memories, max) : []), [memories, enabled, max]);
+  const signature = useMemo(() => targetSignature(targets), [targets]);
+
+  const [duplicates, setDuplicates] = useState<DuplicateMatches>(new Map());
+  const [isDetecting, setIsDetecting] = useState(false);
+
+  const cacheRef = useRef<Map<string, GQLConflictingMemory[]>>(new Map());
+  const checkRef = useRef(check);
+  checkRef.current = check;
+  const targetsRef = useRef(targets);
+  targetsRef.current = targets;
+
+  useEffect(() => {
+    const current = targetsRef.current;
+    if (!isPresent(current)) {
+      setDuplicates(new Map());
+      setIsDetecting(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsDetecting(true);
+
+    void (async () => {
+      const next: DuplicateMatches = new Map();
+      for (const memory of current) {
+        const key = buildMemoryKey(memory);
+        let conflicts = cacheRef.current.get(key);
+        if (conflicts == null) {
+          const result = await checkRef.current({
+            label: memory.label,
+            description: memory.description ?? "",
+            scope: memory.scope,
+            excludeIri: memory.iri,
+          });
+          if (cancelled) return;
+          conflicts = result.conflicts;
+          cacheRef.current.set(key, conflicts);
+        }
+        if (isPresent(conflicts)) next.set(memory.iri, conflicts);
+      }
+      if (!cancelled) {
+        setDuplicates(next);
+        setIsDetecting(false);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [signature]);
+
+  return { duplicates, isDetecting };
+}

package/src/routes/memories/hooks/useLiveContext.ts

@@ -0,0 +1,143 @@
+import { liveContextMemoryDateFilter } from "@manta-eu/client/shared/live-context";
+import { compactUri, prependMissingSparqlPrefixes } from "@manta-eu/client/shared/rdf-namespaces";
+import { isSparqlJsonResults, type SparqlBinding, type SparqlJsonResults } from "@manta-eu/client/types/sparql-types";
+import { useQuery } from "@tanstack/react-query";
+import { useMantaClient } from "#providers/index";
+
+const rdfTypeIri = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+const trivialTypePrefixes = ["rdf:", "rdfs:", "owl:", "xsd:"];
+
+export const liveContextSelectQuery = `SELECT ?entity ?property ?value WHERE {
+  :LiveContext_Chat :includes ?entity .
+  ?entity ?property ?value .
+  ${liveContextMemoryDateFilter}
+}`;
+
+export type EntityProperty = {
+  predicate: string;
+  value: string;
+  isUri: boolean;
+  datatype?: string;
+};
+
+export type LiveContextEntity = {
+  iri: string;
+  compactedIri: string;
+  types: string[];
+  properties: EntityProperty[];
+};
+
+export type LiveContextGroup = {
+  type: string;
+  typeLabel: string;
+  entities: LiveContextEntity[];
+};
+
+function formatTypeLabel(compacted: string): string {
+  const localName = compacted.includes(":") ? (compacted.split(":")[1] ?? compacted) : compacted;
+  return localName.replace(/([A-Z])/g, " $1").trim();
+}
+
+function sparqlValueIsUri(node: SparqlBinding[string]): boolean {
+  return node.type === "uri";
+}
+
+function sparqlValueDatatype(node: SparqlBinding[string]): string | undefined {
+  if ("datatype" in node && typeof node.datatype === "string") {
+    return node.datatype;
+  }
+  return undefined;
+}
+
+export function parseLiveContext(data: SparqlJsonResults): LiveContextGroup[] {
+  const entityMap = new Map<string, { types: string[]; properties: EntityProperty[] }>();
+
+  for (const binding of data.results.bindings) {
+    const entityNode = binding["entity"];
+    const propertyNode = binding["property"];
+    const valueNode = binding["value"];
+
+    if (!entityNode || !propertyNode || !valueNode) continue;
+
+    const entityIri = entityNode.value;
+    const propertyIri = propertyNode.value;
+
+    if (!entityMap.has(entityIri)) {
+      entityMap.set(entityIri, { types: [], properties: [] });
+    }
+
+    const entry = entityMap.get(entityIri);
+    if (!entry) continue;
+
+    if (propertyIri === rdfTypeIri) {
+      const compacted = compactUri(valueNode.value);
+      if (!trivialTypePrefixes.some((p) => compacted.startsWith(p))) {
+        if (!entry.types.includes(compacted)) {
+          entry.types.push(compacted);
+        }
+      }
+    } else {
+      const isUri = sparqlValueIsUri(valueNode);
+      entry.properties.push({
+        predicate: compactUri(propertyIri),
+        value: isUri ? compactUri(valueNode.value) : valueNode.value,
+        isUri,
+        datatype: sparqlValueDatatype(valueNode),
+      });
+    }
+  }
+
+  const groupMap = new Map<string, LiveContextGroup>();
+
+  for (const [iri, { types, properties }] of entityMap) {
+    const primaryType = types[0] ?? "Unknown";
+
+    if (!groupMap.has(primaryType)) {
+      groupMap.set(primaryType, {
+        type: primaryType,
+        typeLabel: formatTypeLabel(primaryType),
+        entities: [],
+      });
+    }
+
+    const group = groupMap.get(primaryType);
+    if (!group) continue;
+
+    group.entities.push({
+      iri,
+      compactedIri: compactUri(iri),
+      types,
+      properties: [...properties].sort((a, b) => a.predicate.localeCompare(b.predicate)),
+    });
+  }
+
+  return [...groupMap.values()].sort((a, b) => a.typeLabel.localeCompare(b.typeLabel));
+}
+
+export const liveContextQueryKey = ["live-context"] as const;
+
+export function useLiveContext() {
+  const { sparqlFetch, onUnauthorized } = useMantaClient();
+
+  return useQuery({
+    queryKey: liveContextQueryKey,
+    queryFn: async (): Promise<LiveContextGroup[]> => {
+      const response = await sparqlFetch(prependMissingSparqlPrefixes(liveContextSelectQuery));
+
+      if (!response.ok) {
+        if (response.status === 401) {
+          onUnauthorized();
+        }
+        throw new Error(`SPARQL query failed: ${response.status}`);
+      }
+
+      const raw: unknown = await response.json();
+
+      if (!isSparqlJsonResults(raw)) {
+        throw new Error("Invalid SPARQL results format");
+      }
+
+      return parseLiveContext(raw);
+    },
+  });
+}