@manta-eu/client 0.1.9 → 0.2.0

package/src/shared/memory-keyword-recall.ts

@@ -0,0 +1,149 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { memoryTokens, type DiversityCandidate } from "./memory-diversity";
+
+export const rankFusionConstant = 60;
+
+export const maxKeywordTerms = 8;
+
+export type KeywordCandidate = DiversityCandidate & { iri: string };
+
+// A term feeds a SPARQL CONTAINS that admits rows, so a stray function word like "the" would widen the pool to the
+// entire store.
+const stopWords = new Set([
+  "the",
+  "and",
+  "but",
+  "for",
+  "not",
+  "you",
+  "your",
+  "our",
+  "are",
+  "was",
+  "were",
+  "has",
+  "have",
+  "had",
+  "with",
+  "from",
+  "that",
+  "this",
+  "these",
+  "those",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "how",
+  "can",
+  "could",
+  "would",
+  "should",
+  "will",
+  "shall",
+  "may",
+  "might",
+  "must",
+  "there",
+  "their",
+  "them",
+  "they",
+  "its",
+  "his",
+  "her",
+  "him",
+  "she",
+  "here",
+  "into",
+  "onto",
+  "over",
+  "under",
+  "about",
+  "than",
+  "then",
+  "some",
+  "any",
+  "all",
+  "both",
+  "each",
+  "more",
+  "most",
+  "other",
+  "such",
+  "only",
+  "own",
+  "same",
+  "too",
+  "very",
+  "just",
+  "now",
+  "get",
+  "got",
+  "let",
+  "make",
+  "made",
+  "does",
+  "did",
+  "done",
+  "been",
+  "being",
+  "also",
+  "well",
+  "much",
+  "many",
+  "like",
+  "want",
+  "need",
+  "give",
+  "take",
+  "see",
+]);
+
+export function keywordTerms(text: string, limit: number = maxKeywordTerms): string[] {
+  return [...memoryTokens({ label: text })]
+    .filter((token) => !stopWords.has(token))
+    .sort((a, b) => b.length - a.length || a.localeCompare(b))
+    .slice(0, limit);
+}
+
+export function keywordOverlap(memory: DiversityCandidate, terms: readonly string[]): number {
+  if (!isPresent(terms)) return 0;
+  const tokens = memoryTokens(memory);
+  let hits = 0;
+  for (const term of terms) if (tokens.has(term)) hits += 1;
+  return hits;
+}
+
+export function fuseRankings<T extends { iri: string }>(lists: readonly (readonly T[])[]): T[] {
+  const scores = new Map<string, number>();
+  const byIri = new Map<string, T>();
+
+  for (const list of lists) {
+    list.forEach((item, rank) => {
+      scores.set(item.iri, (scores.get(item.iri) ?? 0) + 1 / (rankFusionConstant + rank));
+      if (!byIri.has(item.iri)) byIri.set(item.iri, item);
+    });
+  }
+
+  return [...scores.entries()]
+    .sort(([iriA, scoreA], [iriB, scoreB]) => scoreB - scoreA || iriA.localeCompare(iriB))
+    .map(([iri]) => byIri.get(iri))
+    .filter((item) => item !== undefined);
+}
+
+export function fuseKeywordRanking<T extends KeywordCandidate>(semanticOrder: readonly T[], queryText: string): T[] {
+  const terms = keywordTerms(queryText);
+  if (!isPresent(terms) || !isPresent(semanticOrder)) return [...semanticOrder];
+
+  const keywordOrder = semanticOrder
+    .map((memory) => ({ memory, hits: keywordOverlap(memory, terms) }))
+    .filter((scored) => scored.hits > 0)
+    .sort((a, b) => b.hits - a.hits)
+    .map((scored) => scored.memory);
+
+  if (!isPresent(keywordOrder)) return [...semanticOrder];
+
+  return fuseRankings([semanticOrder, keywordOrder]);
+}

package/src/shared/memory-kind-iris.ts

@@ -0,0 +1,36 @@
+import { vocabBase } from "@manta-eu/ldo/realm";
+
+// GraphQL MemoryKind, backend valid-kind?, and KG sh:in must stay in sync with this.
+export const memoryKinds = ["preference", "fact", "objective", "context"] as const;
+export type MemoryKind = (typeof memoryKinds)[number];
+
+const memoryKindIriBase = `${vocabBase}MemoryKind_`;
+
+export const memoryKindIris = Object.fromEntries(
+  memoryKinds.map((kind) => [kind, `${memoryKindIriBase}${kind}`]),
+) as Record<MemoryKind, string>;
+
+export type MemoryKindIri = (typeof memoryKindIris)[MemoryKind];
+
+const iriToKind = new Map<string, MemoryKind>(memoryKinds.map((kind) => [memoryKindIris[kind], kind]));
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+export function isKindIri(iri: string): boolean {
+  return iriToKind.has(iri);
+}
+
+export function kindIriToKind(iri: string): MemoryKind | null {
+  return iriToKind.get(iri) ?? null;
+}
+
+export function kindIriToLabel(iri: string): string | null {
+  const kind = iriToKind.get(iri);
+  return kind ? capitalize(kind) : null;
+}
+
+export function kindToKindIri(kind: MemoryKind): string {
+  return memoryKindIris[kind];
+}

package/src/shared/memory-preload-gate.ts

@@ -0,0 +1,150 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { msPerDay, parseMemoryDate } from "./memory-dates";
+import { shouldDemoteOnUsage, type UseWeights } from "./memory-decay";
+
+export { parseMemoryDate };
+export type { UseWeights };
+
+export const memoryPreloadConfidenceThreshold = 0.75;
+export const memoryPreloadImportanceThreshold = 4;
+export const memorySearchImportanceThreshold = 2;
+
+export const memoryPreloadRowLimit = 20;
+
+export const companyMemoryScope = "company";
+
+export const validFromWorthShowingDays = 2;
+
+export const trustedUntilExpiringSoonDays = 7;
+
+export type MemoryPreloadCandidate = {
+  importance: number;
+  confidence?: number | null;
+  memoryValidUntil?: Date | string | null;
+  memoryValidFrom?: Date | string | null;
+  memoryTrustedUntil?: Date | string | null;
+  memoryUseCount?: number | null;
+  memoryCiteCount?: number | null;
+  memoryLastUsedAt?: Date | string | null;
+  scope?: string | null;
+  supersededBy?: string | null;
+};
+
+export type MemoryPreloadExclusion =
+  | "archived"
+  | "importance"
+  | "confidence"
+  | "stale"
+  | "expired"
+  | "scheduled"
+  | "cold";
+
+export function isPastTrustedUntilAt(memoryTrustedUntil: Date | string | null | undefined, now: Date): boolean {
+  const horizon = parseMemoryDate(memoryTrustedUntil);
+  return horizon != null && horizon <= now;
+}
+
+// Elapsed time, not calendar days: this module runs in the browser too, where the local zone would
+// shift the boundary by a day either side of UTC.
+export function isTrustedUntilExpiringSoon(memoryTrustedUntil: Date | string | null | undefined, now: Date): boolean {
+  const horizon = parseMemoryDate(memoryTrustedUntil);
+  if (horizon == null || horizon <= now) return false;
+  return horizon.getTime() - now.getTime() <= trustedUntilExpiringSoonDays * msPerDay;
+}
+
+export function isMemoryArchived(memory: MemoryPreloadCandidate): boolean {
+  return isPresent(memory.supersededBy);
+}
+
+export function isNeverUsed(memory: MemoryPreloadCandidate, now: Date = new Date()): boolean {
+  return isMemoryPreloaded(memory, now) && (memory.memoryUseCount ?? 0) + (memory.memoryCiteCount ?? 0) === 0;
+}
+
+export function needsTrustReview(memory: MemoryPreloadCandidate, now: Date = new Date()): boolean {
+  if (isMemoryArchived(memory)) return false;
+  if (memory.memoryValidUntil) return false;
+  return (
+    isPastTrustedUntilAt(memory.memoryTrustedUntil, now) || isTrustedUntilExpiringSoon(memory.memoryTrustedUntil, now)
+  );
+}
+
+export function isMemorySearchable(memory: MemoryPreloadCandidate): boolean {
+  return !isMemoryArchived(memory) && memory.importance >= memorySearchImportanceThreshold;
+}
+
+// Mirrors the SPARQL pre-load gate; "cold" stays client-side since decay is weighted per caller.
+export function memoryPreloadQueryExclusions(
+  memory: MemoryPreloadCandidate,
+  now: Date = new Date(),
+): MemoryPreloadExclusion[] {
+  const exclusions: MemoryPreloadExclusion[] = [];
+  if (isMemoryArchived(memory)) exclusions.push("archived");
+  if (memory.importance < memoryPreloadImportanceThreshold) exclusions.push("importance");
+  if (
+    memory.scope !== companyMemoryScope &&
+    memory.confidence != null &&
+    memory.confidence < memoryPreloadConfidenceThreshold
+  ) {
+    exclusions.push("confidence");
+  }
+  if (isPastTrustedUntilAt(memory.memoryTrustedUntil, now)) exclusions.push("stale");
+
+  // Mirrors liveContextMemoryDateFilter: the query drops on all three date predicates, not just trust.
+  const validUntil = parseMemoryDate(memory.memoryValidUntil);
+  if (validUntil != null && validUntil <= now) exclusions.push("expired");
+  const validFrom = parseMemoryDate(memory.memoryValidFrom);
+  if (validFrom != null && validFrom > now) exclusions.push("scheduled");
+
+  return exclusions;
+}
+
+export function isMemoryQueryGateEligible(memory: MemoryPreloadCandidate, now: Date = new Date()): boolean {
+  return !isPresent(memoryPreloadQueryExclusions(memory, now));
+}
+
+export function memoryPreloadExclusions(
+  memory: MemoryPreloadCandidate,
+  now: Date = new Date(),
+  weights?: UseWeights,
+): MemoryPreloadExclusion[] {
+  const exclusions = memoryPreloadQueryExclusions(memory, now);
+  if (shouldDemoteOnUsage(memory, now, weights)) exclusions.push("cold");
+
+  return exclusions;
+}
+
+export function isMemoryPreloaded(
+  memory: MemoryPreloadCandidate,
+  now: Date = new Date(),
+  weights?: UseWeights,
+): boolean {
+  return !isPresent(memoryPreloadExclusions(memory, now, weights));
+}
+
+const exclusionReasons: Record<MemoryPreloadExclusion, string> = {
+  archived: "it was replaced by a newer memory",
+  importance: `importance is below ${memoryPreloadImportanceThreshold} (High)`,
+  confidence: `confidence is below ${memoryPreloadConfidenceThreshold} — it has not been reviewed`,
+  stale: "it is no longer trusted and needs re-confirming",
+  expired: "its expiry date has passed",
+  scheduled: "it does not take effect until a later date",
+  cold: "nothing has used it in a long time, so it no longer earns a place in every prompt",
+};
+
+export function describeMemoryPreloadExclusions(
+  memory: MemoryPreloadCandidate,
+  exclusions: MemoryPreloadExclusion[],
+): string {
+  if (!isPresent(exclusions)) {
+    return `In your assistant's context, up to ${memoryPreloadRowLimit} per scope on any one turn (most relevant first).`;
+  }
+
+  const reasons = exclusions.map((exclusion) => exclusionReasons[exclusion]).join("; ");
+  return isMemorySearchable(memory)
+    ? `Not in context: ${reasons}. Still retrievable with searchMemories.`
+    : `Not in context: ${reasons}. Not retrievable with searchMemories either.`;
+}
+
+export function describeMemoryPreload(memory: MemoryPreloadCandidate, now: Date = new Date()): string {
+  return describeMemoryPreloadExclusions(memory, memoryPreloadExclusions(memory, now));
+}

package/src/shared/memory-sources.ts

@@ -0,0 +1,5 @@
+import { expandPrefix } from "./rdf-namespaces";
+
+export const userManualMemorySource = expandPrefix(":UserManual");
+
+export const derivedAbstractionMemorySource = expandPrefix(":DerivedAbstraction");

package/src/shared/memory-teams.ts

@@ -0,0 +1,3 @@
+export function unionOfTeams(teamSets: readonly (readonly string[] | null | undefined)[]): string[] {
+  return [...new Set(teamSets.flatMap((teams) => teams ?? []))];
+}

package/src/shared/memory-token-budget.ts

@@ -0,0 +1,31 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { memoryPreloadRowLimit } from "./memory-preload-gate";
+
+// 4 chars/token approximates English prose; the serving model's real tokenizer is not available in the Worker.
+export const charsPerTokenEstimate = 4;
+
+export const memoryPreloadRowTokenAllowance = 120;
+
+export const memoryPreloadTokenBudgetPerBlock = memoryPreloadRowLimit * memoryPreloadRowTokenAllowance;
+
+export const memoryPreloadBlockCount = 3;
+
+export const memoryPreloadTokenBudgetTotal = memoryPreloadTokenBudgetPerBlock * memoryPreloadBlockCount;
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / charsPerTokenEstimate);
+}
+
+export function packToBudget<T>(items: readonly T[], cost: (item: T) => number, budget: number): T[] {
+  const kept: T[] = [];
+  let spent = 0;
+
+  for (const item of items) {
+    const itemCost = cost(item);
+    if (isPresent(kept) && spent + itemCost > budget) continue;
+    kept.push(item);
+    spent += itemCost;
+  }
+
+  return kept;
+}

package/src/shared/memory-volatility.ts

@@ -0,0 +1,90 @@
+import { msPerDay, parseMemoryDate } from "./memory-dates";
+
+export const memoryVolatilities = ["stable", "slow", "volatile"] as const;
+
+export type MemoryVolatility = (typeof memoryVolatilities)[number];
+
+export type MemoryVolatilityRule = { trustDays: number | null; maxImportance: number };
+
+export const volatilityRules: Record<MemoryVolatility, MemoryVolatilityRule> = {
+  stable: { trustDays: null, maxImportance: 5 },
+  slow: { trustDays: 90, maxImportance: 3 },
+  volatile: { trustDays: 7, maxImportance: 2 },
+};
+
+export const defaultMemoryVolatility: MemoryVolatility = "slow";
+
+export function isMemoryVolatility(value: unknown): value is MemoryVolatility {
+  return typeof value === "string" && memoryVolatilities.includes(value as MemoryVolatility);
+}
+
+export function normalizeVolatility(value: unknown): MemoryVolatility {
+  return isMemoryVolatility(value) ? value : defaultMemoryVolatility;
+}
+
+export function volatilityTrustDays(volatility: unknown): number | null {
+  return volatilityRules[normalizeVolatility(volatility)].trustDays;
+}
+
+export function maxImportanceForVolatility(volatility: unknown): number {
+  return volatilityRules[normalizeVolatility(volatility)].maxImportance;
+}
+
+export const volatilityInferenceSlack = 1.5;
+
+export function inferVolatility(
+  memoryTrustedUntil: Date | string | null | undefined,
+  since: Date | string | null | undefined,
+): MemoryVolatility {
+  if (memoryTrustedUntil == null) return "stable";
+
+  const horizon = parseMemoryDate(memoryTrustedUntil);
+  const from = parseMemoryDate(since);
+  if (horizon == null || from == null) return defaultMemoryVolatility;
+
+  const spanDays = (horizon.getTime() - from.getTime()) / msPerDay;
+  const volatileDays = volatilityRules.volatile.trustDays ?? 0;
+  return spanDays <= volatileDays * volatilityInferenceSlack ? "volatile" : defaultMemoryVolatility;
+}
+
+export type VolatilityTrace = {
+  memoryTrustedUntil?: Date | string | null;
+  memoryValidUntil?: Date | string | null;
+  extractedAt?: Date | string | null;
+};
+
+export function isDeadlineDerivedHorizon(
+  memoryTrustedUntil: Date | string | null | undefined,
+  memoryValidUntil: Date | string | null | undefined,
+): boolean {
+  const horizon = parseMemoryDate(memoryTrustedUntil);
+  const deadline = parseMemoryDate(memoryValidUntil);
+  return horizon != null && deadline != null && horizon.getTime() === deadline.getTime();
+}
+
+export function importanceCeilingFor(memory: VolatilityTrace): number {
+  return isDeadlineDerivedHorizon(memory.memoryTrustedUntil, memory.memoryValidUntil)
+    ? maxImportanceForVolatility("stable")
+    : maxImportanceForVolatility(inferVolatility(memory.memoryTrustedUntil, memory.extractedAt));
+}
+
+export function capHorizonByDeadline(
+  horizon: string | null,
+  memoryValidUntil: string | null,
+  now: Date = new Date(),
+): string | null {
+  const deadline = memoryValidUntil != null && new Date(memoryValidUntil) > now ? memoryValidUntil : null;
+  if (deadline == null) return horizon;
+  if (horizon == null) return deadline;
+  return new Date(deadline) < new Date(horizon) ? deadline : horizon;
+}
+
+export function resolveTrustedUntil(
+  volatility: unknown,
+  memoryValidUntil: string | null,
+  now: Date = new Date(),
+): string | null {
+  const days = volatilityTrustDays(volatility);
+  const fromVolatility = days != null ? new Date(now.getTime() + days * msPerDay).toISOString() : null;
+  return capHorizonByDeadline(fromVolatility, memoryValidUntil, now);
+}

package/src/shared/message-utils.ts

@@ -0,0 +1,37 @@
+import { isPresent } from "@manta-eu/lib/present";
+import type { FileUIPart } from "ai";
+import { v7 as uuidv7 } from "uuid";
+import type { OperatorAllowedModel } from "./model";
+import type { PageContext } from "./page-context";
+import type { ChatUIMessage } from "./index";
+
+export type CreateUserMessageArgs = {
+  text: string;
+  fileParts?: FileUIPart[];
+  pageContext?: PageContext;
+  model?: OperatorAllowedModel;
+};
+
+export function createUserMessage(args: CreateUserMessageArgs): ChatUIMessage {
+  const { text, fileParts, pageContext, model } = args;
+  const parts: ChatUIMessage["parts"] = [];
+
+  if (isPresent(fileParts)) {
+    parts.push(...fileParts);
+  }
+
+  if (text) {
+    parts.push({ type: "text", text });
+  }
+
+  return {
+    id: uuidv7(),
+    role: "user",
+    parts,
+    metadata: {
+      createdAt: new Date().toISOString(),
+      ...(pageContext && { pageContext }),
+      ...(model && { model }),
+    },
+  };
+}

package/src/shared/model.ts

@@ -0,0 +1,117 @@
+import type { LanguageModel } from "ai";
+import { z } from "zod";
+
+export const opus_5_5 = "claude-opus-5-5" satisfies LanguageModel;
+export const sonnet_4_5 = "claude-sonnet-4-5-20250929" satisfies LanguageModel;
+export const haiku_4_5 = "claude-haiku-4-5-20251001" satisfies LanguageModel;
+export const vllmPrimaryModel = "vllm-primary" satisfies LanguageModel;
+export const vertexClaudeModel = "vertex-claude" satisfies LanguageModel;
+
+export const anthropicPrimaryModel = opus_5_5;
+
+export const anthropicSupportedMimeTypes: readonly string[] = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+];
+
+export const vllmSupportedMimeTypes: readonly string[] = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+
+export const modelOptions = [
+  {
+    id: opus_5_5,
+    label: "Claude Opus",
+    provider: "anthropic",
+    contextWindow: 200_000,
+    isOperatorAllowed: true,
+    supportedMimeTypes: anthropicSupportedMimeTypes,
+    supportsPromptCaching: true,
+  },
+  {
+    id: sonnet_4_5,
+    label: "Claude Sonnet",
+    provider: "anthropic",
+    contextWindow: 200_000,
+    isOperatorAllowed: true,
+    supportedMimeTypes: anthropicSupportedMimeTypes,
+    supportsPromptCaching: true,
+  },
+  {
+    id: haiku_4_5,
+    label: "Claude Haiku",
+    provider: "anthropic",
+    contextWindow: 200_000,
+    isOperatorAllowed: false,
+    supportedMimeTypes: anthropicSupportedMimeTypes,
+    supportsPromptCaching: true,
+  },
+  {
+    id: vllmPrimaryModel,
+    label: "Manta LLM",
+    provider: "vllm",
+    contextWindow: 262_144,
+    isOperatorAllowed: true,
+    supportedMimeTypes: vllmSupportedMimeTypes,
+    supportsPromptCaching: false,
+  },
+  {
+    id: vertexClaudeModel,
+    label: "Claude (Vertex AI)",
+    provider: "google-vertex-anthropic",
+    // A floor, not the exact window: the model behind this id is whatever GOOGLE_VERTEX_MODEL
+    // names, and which Claude generations a project can reach depends on its pinned region.
+    contextWindow: 200_000,
+    isOperatorAllowed: true,
+    supportedMimeTypes: anthropicSupportedMimeTypes,
+    supportsPromptCaching: true,
+  },
+] as const;
+
+export type MantaModelId = (typeof modelOptions)[number]["id"];
+
+const modelById = new Map<MantaModelId, (typeof modelOptions)[number]>(modelOptions.map((m) => [m.id, m]));
+
+export const getModelMetaById = (modelId: MantaModelId) => {
+  const meta = modelById.get(modelId);
+
+  if (!meta) {
+    throw new Error(`Unknown model ID: ${modelId}`);
+  }
+
+  return meta;
+};
+
+export const getSupportedMimeTypes = (modelId: MantaModelId) => {
+  return getModelMetaById(modelId).supportedMimeTypes;
+};
+
+export function requiresSingleSystemMessage(modelId: MantaModelId): boolean {
+  return !getModelMetaById(modelId).supportsPromptCaching;
+}
+
+const validModelSchema = z.enum(modelOptions.map((m) => m.id));
+export const isValidModelId = (value: unknown): value is MantaModelId => {
+  return validModelSchema.safeParse(value).success;
+};
+
+export const operatorModelOptions = modelOptions.filter((m) => m.isOperatorAllowed);
+
+export type OperatorAllowedModel = (typeof operatorModelOptions)[number]["id"];
+
+export function isOperatorAllowedModel(value: unknown): value is OperatorAllowedModel {
+  return isValidModelId(value) && getModelMetaById(value).isOperatorAllowed;
+}
+
+export type AllowedModels = readonly [MantaModelId, ...MantaModelId[]];
+
+export function getMinimumContextWindow(allowedModels: AllowedModels): number {
+  return Math.min(...allowedModels.map((modelId) => getModelMetaById(modelId).contextWindow));
+}
+
+export function operatorModelOptionsFor(allowedModels: readonly MantaModelId[]) {
+  const allowed = new Set<MantaModelId>(allowedModels);
+
+  return operatorModelOptions.filter((model) => allowed.has(model.id));
+}

package/src/shared/org-roles.ts

@@ -0,0 +1,21 @@
+import type { Capability } from "./permissions";
+
+export type OrgRoleDefinition = {
+  readonly id: string;
+  readonly groupName: string;
+  readonly label: string;
+  readonly capabilities: readonly Capability[];
+};
+
+export const orgAdminRole: OrgRoleDefinition = {
+  id: "admin",
+  groupName: "Admins",
+  label: "Admin",
+  capabilities: ["team:manage", "org:settings", "org:integrations", "org:streams", "org:memories"],
+};
+
+export const plainMemberRole = "user";
+
+export function findOrgRole(roles: readonly OrgRoleDefinition[], id: string): OrgRoleDefinition | undefined {
+  return roles.find((role) => role.id === id);
+}

package/src/shared/page-context.ts

@@ -0,0 +1,7 @@
+import type { IRI } from "@manta-eu/rdf-lib/namespaces";
+
+/** The entities a screen is showing, so the agent can answer about what the user is looking at. */
+export type PageContext = {
+  iris: IRI[];
+  typenames: string[];
+};

package/src/shared/permissions.ts

@@ -0,0 +1,19 @@
+import { orgAdminRole } from "./org-roles";
+
+export const capabilities = ["team:manage", "org:settings", "org:integrations", "org:streams", "org:memories"] as const;
+
+export type Capability = (typeof capabilities)[number];
+
+export function isCapability(value: string): value is Capability {
+  return capabilities.some((candidate) => candidate === value);
+}
+
+export type CapabilityPrincipal = {
+  isOperator: boolean;
+  isOrgAdmin: boolean;
+};
+
+export function hasCapability(principal: CapabilityPrincipal, capability: Capability): boolean {
+  if (principal.isOperator) return true;
+  return principal.isOrgAdmin && orgAdminRole.capabilities.includes(capability);
+}