@opengeni/core 0.21.10 → 0.28.0

package/src/domain/fiken.ts

@@ -0,0 +1,88 @@
+import {
+  FIKEN_CREDENTIAL_LABEL,
+  FIKEN_CREDENTIAL_ROLE,
+  FIKEN_PROVIDER_DOMAIN,
+  FikenConnectionMetadata,
+  type ConnectionMetadata,
+  type FikenCompanySummary,
+  type FikenConnectionMetadata as FikenMetadata,
+} from "@opengeni/contracts";
+
+export function fikenConnectionMetadata(metadata: Record<string, unknown>): FikenMetadata | null {
+  const parsed = FikenConnectionMetadata.safeParse(metadata);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * A workspace-shared Fiken connection created through one of the verified
+ * install paths: the pasted personal API token (`api_key`) or the Fiken OAuth
+ * app flow (`oauth2`). Both are deliberately workspace-owned; personal
+ * ("Connect only for me") ownership needs the delegation-snapshot lane and is
+ * not yet wired for the first-party fiken tools.
+ */
+export function isFikenConnection(connection: ConnectionMetadata): boolean {
+  return (
+    connection.subjectId === null &&
+    connection.providerDomain === FIKEN_PROVIDER_DOMAIN &&
+    (connection.kind === "api_key" || connection.kind === "oauth2") &&
+    fikenConnectionMetadata(connection.metadata)?.credentialRole === FIKEN_CREDENTIAL_ROLE
+  );
+}
+
+/**
+ * The Fiken credential role is reserved for the verified install routes.
+ * Generic connection create/update must reject it so a caller cannot forge a
+ * "verified" Fiken row (with attacker-chosen companies metadata) that the
+ * first-party fiken tools would then bind to. Mirrors the Slack bot guard.
+ */
+export function hasReservedFikenMetadata(
+  metadata: Record<string, unknown> | null | undefined,
+): boolean {
+  return (
+    metadata?.credentialRole === FIKEN_CREDENTIAL_ROLE ||
+    metadata?.credentialLabel === FIKEN_CREDENTIAL_LABEL
+  );
+}
+
+/**
+ * One default-company rule for both verified lanes: an explicit request wins
+ * when the credential can access it, then a still-accessible previous default
+ * survives reconnect, then a single-company credential auto-selects. Returns
+ * null (caller decides whether that is an error) when a requested slug is not
+ * among the verified companies.
+ */
+export function resolveFikenDefaultCompanySlug(input: {
+  requested: string | null;
+  previous: string | null;
+  companies: readonly FikenCompanySummary[];
+}): string | null {
+  const accessible = (slug: string | null): slug is string =>
+    slug !== null && input.companies.some((company) => company.slug === slug);
+  if (input.requested !== null) {
+    return accessible(input.requested) ? input.requested : null;
+  }
+  if (accessible(input.previous)) {
+    return input.previous;
+  }
+  return input.companies.length === 1 ? input.companies[0]!.slug : null;
+}
+
+/**
+ * The row a capability tile or tool default should bind to when several Fiken
+ * connections exist: usable status first, then newest update, then immutable
+ * UUID descending as the stable tie-breaker.
+ */
+export function preferredFikenConnection<
+  T extends Pick<ConnectionMetadata, "status" | "updatedAt" | "id">,
+>(connections: readonly T[]): T | null {
+  const statusRank = (status: ConnectionMetadata["status"]): number =>
+    status === "active" ? 0 : status === "needs_reauth" ? 1 : 2;
+  return (
+    [...connections].sort(
+      (left, right) =>
+        statusRank(left.status) - statusRank(right.status) ||
+        right.updatedAt.localeCompare(left.updatedAt) ||
+        right.id.localeCompare(left.id),
+    )[0] ?? null
+  );
+}

package/src/domain/insights.ts

@@ -7,6 +7,7 @@ import {
 import {
   aggregateModelCallFacts,
   aggregateModelCallFactsByDay,
+  aggregateModelCallFactsByHour,
   aggregateRootSessionDrivers,
   aggregateScheduleFacts,
   aggregateSessionDepth,
@@ -15,13 +16,16 @@ import {
   countScheduledTaskFires,
   countSessionsAttachedToGroups,
   enumerateUtcDays,
+  enumerateUtcHours,
   listFloorSessions,
   listLiveWarmLeases,
   listModelCallFacets,
+  listRecentModelCalls,
   listScheduledTasks,
   requireWorkspace,
   sumUsageQuantity,
   sumUsageQuantityByDay,
+  sumUsageQuantityByHour,
   sumUsageQuantityInRange,
   type Database,
 } from "@opengeni/db";
@@ -37,7 +41,7 @@ export type GetWorkspaceInsightsInput = {
 };
 
 function microsToUsd(micros: number): number {
-  return Math.round((micros / 1_000_000) * 100) / 100;
+  return micros / 1_000_000;
 }
 
 function cacheHitPct(cached: number, input: number): number {
@@ -81,29 +85,29 @@ function resolveRangeWindow(
       since = startOfUtcDay(now);
       rangeLabel = "Today (UTC)";
       priorLabel = "Prior equal window";
-      seriesLabel = "Credit $ (UTC day)";
-      cacheSeriesLabel = "Cache hit %";
+      seriesLabel = "Credit $ / UTC hour";
+      cacheSeriesLabel = "Cache hit % / UTC hour";
       break;
     case "week":
       since = new Date(startOfUtcDay(now).getTime() - 6 * 24 * 60 * 60 * 1000);
       rangeLabel = "Last 7 days (UTC)";
       priorLabel = "Prior 7 days";
-      seriesLabel = "Credit $ / day";
-      cacheSeriesLabel = "Cache hit % / day";
+      seriesLabel = "Credit $ / UTC day";
+      cacheSeriesLabel = "Cache hit % / UTC day";
       break;
     case "month":
       since = startOfUtcMonth(now);
       rangeLabel = "This month (UTC)";
       priorLabel = "Prior equal window";
-      seriesLabel = "Credit $ / day";
-      cacheSeriesLabel = "Cache hit % / day";
+      seriesLabel = "Credit $ / UTC day";
+      cacheSeriesLabel = "Cache hit % / UTC day";
       break;
     case "ytd":
       since = startOfUtcYear(now);
       rangeLabel = "Year to date (UTC)";
       priorLabel = "Prior equal window";
-      seriesLabel = "Credit $ / day";
-      cacheSeriesLabel = "Cache hit % / day";
+      seriesLabel = "Credit $ / UTC day";
+      cacheSeriesLabel = "Cache hit % / UTC day";
       break;
     default: {
       const _exhaustive: never = range;
@@ -163,6 +167,12 @@ function billingPathOf(value: string): "opengeni_credits" | "external" {
   return value === "external" ? "external" : "opengeni_credits";
 }
 
+function pricingSourceOf(
+  value: string | null,
+): "configured_list_price" | "gateway_reported" | null {
+  return value === "configured_list_price" || value === "gateway_reported" ? value : null;
+}
+
 export async function getWorkspaceInsights(
   db: Database,
   settings: Settings,
@@ -175,6 +185,10 @@ export async function getWorkspaceInsights(
   const model = input.model?.trim() || null;
   const modelFilterActive = Boolean(provider || model);
   const filter = { provider, model };
+  const aggregateFactsForSeries =
+    input.range === "today" ? aggregateModelCallFactsByHour : aggregateModelCallFactsByDay;
+  const sumUsageForSeries =
+    input.range === "today" ? sumUsageQuantityByHour : sumUsageQuantityByDay;
 
   const [
     workspaceCreditMicros,
@@ -197,6 +211,7 @@ export async function getWorkspaceInsights(
     billableTokensUsed,
     agentRunsUsed,
     facets,
+    recentCalls,
   ] = await Promise.all([
     sumUsageQuantityInRange(db, {
       workspaceId: input.workspaceId,
@@ -234,19 +249,19 @@ export async function getWorkspaceInsights(
       until: window.priorUntil,
       ...filter,
     }),
-    aggregateModelCallFactsByDay(db, {
+    aggregateFactsForSeries(db, {
       workspaceId: input.workspaceId,
       since: window.since,
       until: window.until,
       ...filter,
     }),
-    sumUsageQuantityByDay(db, {
+    sumUsageForSeries(db, {
       workspaceId: input.workspaceId,
       eventType: "sandbox.warm_seconds",
       since: window.since,
       until: window.until,
     }),
-    sumUsageQuantityByDay(db, {
+    sumUsageForSeries(db, {
       workspaceId: input.workspaceId,
       eventType: "model.cost",
       since: window.since,
@@ -276,7 +291,7 @@ export async function getWorkspaceInsights(
     aggregateSessionDepth(db, input.workspaceId),
     listFloorSessions(db, input.workspaceId, 24),
     settings.sandboxSelfhostedEnabled
-      ? countOnlineMachines(db, input.workspaceId, MACHINE_HEARTBEAT_FRESH_MS)
+      ? countOnlineMachines(db, input.workspaceId, MACHINE_HEARTBEAT_FRESH_MS, now)
       : Promise.resolve(0),
     sumUsageQuantity(db, {
       workspaceId: input.workspaceId,
@@ -293,23 +308,37 @@ export async function getWorkspaceInsights(
       since: window.since,
       until: window.until,
     }),
+    listRecentModelCalls(db, {
+      workspaceId: input.workspaceId,
+      since: window.since,
+      until: window.until,
+      ...filter,
+      limit: 50,
+    }),
   ]);
 
-  // Exact prior costs for the current top drivers — never a separate top-N page that
-  // drops roots and invents +$full as "new" spend.
-  const priorRootDrivers = await aggregateRootSessionDrivers(db, {
-    workspaceId: input.workspaceId,
-    since: window.priorSince,
-    until: window.priorUntil,
-    ...filter,
-    rootSessionIds: rootDrivers.map((row) => row.rootSessionId),
-  });
-
-  const attached = await countSessionsAttachedToGroups(
-    db,
-    input.workspaceId,
-    warmGroups.map((group) => group.groupId),
-  );
+  const [priorRootDrivers, attached, fireCounts] = await Promise.all([
+    // Exact prior costs for the current top drivers — never a separate top-N page that
+    // drops roots and invents +$full as "new" spend.
+    aggregateRootSessionDrivers(db, {
+      workspaceId: input.workspaceId,
+      since: window.priorSince,
+      until: window.priorUntil,
+      ...filter,
+      rootSessionIds: rootDrivers.map((row) => row.rootSessionId),
+    }),
+    countSessionsAttachedToGroups(
+      db,
+      input.workspaceId,
+      warmGroups.map((group) => group.groupId),
+    ),
+    countScheduledTaskFires(db, {
+      workspaceId: input.workspaceId,
+      since: window.since,
+      until: window.until,
+      taskIds: tasks.map((task) => task.id),
+    }),
+  ]);
   const backendByGroup = new Map(liveWarm.map((lease) => [lease.groupId, lease.backend]));
   const warmSecondsByGroup = new Map(warmGroups.map((group) => [group.groupId, group.warmSeconds]));
 
@@ -323,36 +352,82 @@ export async function getWorkspaceInsights(
       inputTokens: row.inputTokens,
       outputTokens: row.outputTokens,
       cachedTokens: row.cachedTokens,
+      cacheInputTokens: row.cacheInputTokens,
       cacheWriteTokens: row.cacheWriteTokens,
       reasoningTokens: row.reasoningTokens,
+      totalTokens: row.totalTokens,
+      tokenKnownCalls: row.tokenKnownCalls,
+      cacheKnownCalls: row.cacheKnownCalls,
       creditUsd: microsToUsd(row.pricedCostMicros),
+      estimatedProviderUsd: microsToUsd(row.estimatedProviderCostMicros),
+      estimatedProviderCostKnownCalls: row.estimatedProviderCostKnownCalls,
     }))
-    .sort((a, b) => b.inputTokens - a.inputTokens);
+    .sort((a, b) => b.totalTokens - a.totalTokens);
 
   const creditMicros = modelRows.reduce((sum, row) => sum + row.pricedCostMicros, 0);
   const priorCreditMicros = priorModelRows.reduce((sum, row) => sum + row.pricedCostMicros, 0);
+  const estimatedProviderCostMicros = modelRows.reduce(
+    (sum, row) => sum + row.estimatedProviderCostMicros,
+    0,
+  );
+  const priorEstimatedProviderCostMicros = priorModelRows.reduce(
+    (sum, row) => sum + row.estimatedProviderCostMicros,
+    0,
+  );
+  const estimatedProviderCostKnownCalls = modelRows.reduce(
+    (sum, row) => sum + row.estimatedProviderCostKnownCalls,
+    0,
+  );
+  const priorEstimatedProviderCostKnownCalls = priorModelRows.reduce(
+    (sum, row) => sum + row.estimatedProviderCostKnownCalls,
+    0,
+  );
+  const modelCalls = modelRows.reduce((sum, row) => sum + row.calls, 0);
   const priorInputTokens = priorModelRows.reduce((sum, row) => sum + row.inputTokens, 0);
+  const priorTotalTokens = priorModelRows.reduce((sum, row) => sum + row.totalTokens, 0);
   const priorCachedTokens = priorModelRows.reduce((sum, row) => sum + row.cachedTokens, 0);
+  const priorCacheInputTokens = priorModelRows.reduce((sum, row) => sum + row.cacheInputTokens, 0);
   const priorCalls = priorModelRows.reduce((sum, row) => sum + row.calls, 0);
 
-  const days = enumerateUtcDays(window.since, window.until);
-  const series = days.map((day) => {
-    const facts = factDays.get(day) ?? {
+  const buckets =
+    input.range === "today"
+      ? enumerateUtcHours(window.since, window.until)
+      : enumerateUtcDays(window.since, window.until);
+  const series = buckets.map((bucket) => {
+    const facts = factDays.get(bucket) ?? {
       costMicros: 0,
+      estimatedProviderCostMicros: 0,
+      estimatedProviderCostKnownCalls: 0,
       inputTokens: 0,
+      outputTokens: 0,
       cachedTokens: 0,
+      cacheInputTokens: 0,
+      cacheWriteTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0,
+      tokenKnownCalls: 0,
+      cacheKnownCalls: 0,
       calls: 0,
     };
     const modelCostMicros = modelFilterActive
       ? facts.costMicros
-      : (costDays.get(day) ?? facts.costMicros);
+      : (costDays.get(bucket) ?? facts.costMicros);
     return {
-      label: day.slice(5),
+      label: input.range === "today" ? bucket.slice(11) : bucket.slice(5),
       modelCostUsd: microsToUsd(modelCostMicros),
-      warmSeconds: warmDays.get(day) ?? 0,
+      estimatedProviderUsd: microsToUsd(facts.estimatedProviderCostMicros),
+      estimatedProviderCostKnownCalls: facts.estimatedProviderCostKnownCalls,
+      warmSeconds: warmDays.get(bucket) ?? 0,
       inputTokens: facts.inputTokens,
+      outputTokens: facts.outputTokens,
       cachedTokens: facts.cachedTokens,
-      cacheHitPct: cacheHitPct(facts.cachedTokens, facts.inputTokens),
+      cacheInputTokens: facts.cacheInputTokens,
+      cacheWriteTokens: facts.cacheWriteTokens,
+      reasoningTokens: facts.reasoningTokens,
+      totalTokens: facts.totalTokens,
+      tokenKnownCalls: facts.tokenKnownCalls,
+      cacheKnownCalls: facts.cacheKnownCalls,
+      cacheHitPct: cacheHitPct(facts.cachedTokens, facts.cacheInputTokens),
       calls: facts.calls,
     };
   });
@@ -360,7 +435,10 @@ export async function getWorkspaceInsights(
   const priorDriverByRoot = new Map(
     priorRootDrivers.map((row) => [row.rootSessionId, row.pricedCostMicros]),
   );
-  const creditUsdForPct = Math.max(microsToUsd(creditMicros), 0.01);
+  const totalTokensForPct = Math.max(
+    rootDrivers.reduce((sum, row) => sum + row.totalTokens, 0),
+    1,
+  );
   const drivers = rootDrivers.map((row) => {
     const creditUsd = microsToUsd(row.pricedCostMicros);
     const priorUsd = microsToUsd(priorDriverByRoot.get(row.rootSessionId) ?? 0);
@@ -369,19 +447,19 @@ export async function getWorkspaceInsights(
       groupBy: "root_session" as const,
       label: row.title?.trim() || row.rootSessionId.slice(0, 8),
       creditUsd,
-      tokens: row.inputTokens,
-      cacheHitPct: cacheHitPct(row.cachedTokens, row.inputTokens),
-      pctOfCreditUsd: Math.min(100, Math.round((creditUsd / creditUsdForPct) * 100)),
-      deltaUsdVsPrior: Math.round((creditUsd - priorUsd) * 100) / 100,
+      estimatedProviderUsd: microsToUsd(row.estimatedProviderCostMicros),
+      estimatedProviderCostKnownCalls: row.estimatedProviderCostKnownCalls,
+      tokens: row.totalTokens,
+      cacheHitPct: cacheHitPct(row.cachedTokens, row.cacheInputTokens),
+      pctOfCreditUsd:
+        creditMicros > 0
+          ? Math.min(100, Math.round((row.pricedCostMicros / creditMicros) * 100))
+          : 0,
+      pctOfTokens: Math.min(100, Math.round((row.totalTokens / totalTokensForPct) * 100)),
+      deltaUsdVsPrior: creditUsd - priorUsd,
     };
   });
 
-  const fireCounts = await countScheduledTaskFires(db, {
-    workspaceId: input.workspaceId,
-    since: window.since,
-    until: window.until,
-    taskIds: tasks.map((task) => task.id),
-  });
   const scheduleFactById = new Map(scheduleFacts.map((row) => [row.scheduledTaskId, row] as const));
   const schedules = tasks.map((task) => {
     const fact = scheduleFactById.get(task.id);
@@ -390,8 +468,10 @@ export async function getWorkspaceInsights(
       name: task.name,
       fires: fireCounts.get(task.id) ?? 0,
       creditUsd: fact ? microsToUsd(fact.pricedCostMicros) : null,
-      tokens: fact ? fact.inputTokens : null,
-      cacheHitPct: fact ? cacheHitPct(fact.cachedTokens, fact.inputTokens) : null,
+      estimatedProviderUsd: fact ? microsToUsd(fact.estimatedProviderCostMicros) : null,
+      estimatedProviderCostKnownCalls: fact ? fact.estimatedProviderCostKnownCalls : null,
+      tokens: fact ? fact.totalTokens : null,
+      cacheHitPct: fact ? cacheHitPct(fact.cachedTokens, fact.cacheInputTokens) : null,
       billing: fact ? billingPathOf(fact.billingPath) : null,
     };
   });
@@ -422,6 +502,9 @@ export async function getWorkspaceInsights(
     priorLabel: window.priorLabel,
     seriesLabel: window.seriesLabel,
     cacheSeriesLabel: window.cacheSeriesLabel,
+    windowStart: window.since.toISOString(),
+    windowEnd: window.until.toISOString(),
+    generatedAt: now.toISOString(),
     timezone: "UTC",
     models,
     facets,
@@ -432,6 +515,30 @@ export async function getWorkspaceInsights(
     })),
     drivers,
     schedules,
+    recentCalls: recentCalls.map((row) => ({
+      id: row.id,
+      occurredAt: row.occurredAt.toISOString(),
+      recordedAt: row.recordedAt.toISOString(),
+      sessionId: row.sessionId,
+      sessionTitle: row.sessionTitle?.trim() || "Untitled session",
+      turnId: row.turnId,
+      provider: row.provider,
+      providerApi: row.providerApi,
+      model: row.model,
+      billing: billingPathOf(row.billingPath),
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      cachedTokens: row.cachedTokens,
+      cacheWriteTokens: row.cacheWriteTokens,
+      reasoningTokens: row.reasoningTokens,
+      totalTokens: row.totalTokens,
+      creditUsd: microsToUsd(row.pricedCostMicros),
+      estimatedProviderUsd:
+        row.estimatedProviderCostMicros == null
+          ? null
+          : microsToUsd(row.estimatedProviderCostMicros),
+      pricingSource: pricingSourceOf(row.pricingSource),
+    })),
     warmSeconds,
     priorWarmSeconds,
     warmGroups: warmGroups.map((group) => ({
@@ -458,8 +565,14 @@ export async function getWorkspaceInsights(
     priorWorkspaceCreditUsd: microsToUsd(priorWorkspaceCreditMicros),
     creditUsd: microsToUsd(creditMicros),
     priorCreditUsd: microsToUsd(priorCreditMicros),
+    estimatedProviderUsd: microsToUsd(estimatedProviderCostMicros),
+    priorEstimatedProviderUsd: microsToUsd(priorEstimatedProviderCostMicros),
+    estimatedProviderCostKnownCalls,
+    priorEstimatedProviderCostKnownCalls,
+    modelCalls,
     priorInputTokens,
-    priorCacheHitPct: cacheHitPct(priorCachedTokens, priorInputTokens),
+    priorTotalTokens,
+    priorCacheHitPct: cacheHitPct(priorCachedTokens, priorCacheInputTokens),
     priorCalls,
     goalsActive: depth.goalsActive,
     goalsCompleted: depth.goalsCompleted,

package/src/domain/memory-slack-delivery.ts

@@ -0,0 +1,204 @@
+import type { MemorySlackPublicationDistribution } from "@opengeni/contracts";
+import {
+  correctWorkspaceMemory,
+  enqueueMemorySlackPublication,
+  getCurrentMemorySlackPublicationConfiguration,
+  getWorkspaceMemorySlackPublicationSnapshot,
+  saveWorkspaceMemory,
+  withWorkspaceRls,
+  type CorrectWorkspaceMemoryInput,
+  type CorrectWorkspaceMemoryResult,
+  type Database,
+  type EnqueueMemorySlackPublicationResult,
+  type MemoryEmbedder,
+  type MemorySlackPublicationActor,
+  type SaveWorkspaceMemoryInput,
+  type SaveWorkspaceMemoryResult,
+  type WorkspaceMemorySlackPublicationSnapshot,
+} from "@opengeni/db";
+import {
+  evaluateMemorySlackPublication,
+  type MemorySlackOrigin,
+  type MemorySlackPublicationDecision,
+} from "./memory-slack-publication";
+
+export type MemorySlackPublicationCommitRequest = {
+  distribution: MemorySlackPublicationDistribution;
+  actor: MemorySlackPublicationActor;
+  ownerLabel?: string | null;
+  origin?: MemorySlackOrigin;
+};
+
+export type MemorySlackPublicationCommitResult = {
+  decision: MemorySlackPublicationDecision | null;
+  enqueue: EnqueueMemorySlackPublicationResult | null;
+};
+
+export async function saveWorkspaceMemoryWithSlackPublication(
+  db: Database,
+  input: SaveWorkspaceMemoryInput,
+  publication: MemorySlackPublicationCommitRequest | null,
+  embedder?: MemoryEmbedder,
+): Promise<SaveWorkspaceMemoryResult & { slackPublication: MemorySlackPublicationCommitResult }> {
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    const result = await saveWorkspaceMemory(scopedDb, input, embedder);
+    const slackPublication = publication
+      ? await publishSavedMemoryMutation(scopedDb, input, result, publication)
+      : { decision: null, enqueue: null };
+    return { ...result, slackPublication };
+  });
+}
+
+export async function correctWorkspaceMemoryWithSlackPublication(
+  db: Database,
+  input: CorrectWorkspaceMemoryInput,
+  publication: MemorySlackPublicationCommitRequest | null,
+  embedder?: MemoryEmbedder,
+): Promise<
+  CorrectWorkspaceMemoryResult & { slackPublication: MemorySlackPublicationCommitResult }
+> {
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    const result = await correctWorkspaceMemory(scopedDb, input, embedder);
+    if (!publication || result.action !== "superseded" || !result.replacement) {
+      return { ...result, slackPublication: { decision: null, enqueue: null } };
+    }
+    const replacement = await requiredSnapshot(scopedDb, input.workspaceId, result.replacement.id);
+    const slackPublication = await evaluateAndEnqueue(scopedDb, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      snapshot: replacement,
+      changeKind: "corrected",
+      relatedMemoryId: result.memory.id,
+      occurredAt: result.replacement.updatedAt,
+      publication,
+    });
+    return { ...result, slackPublication };
+  });
+}
+
+async function publishSavedMemoryMutation(
+  db: Database,
+  input: SaveWorkspaceMemoryInput,
+  result: SaveWorkspaceMemoryResult,
+  publication: MemorySlackPublicationCommitRequest,
+): Promise<MemorySlackPublicationCommitResult> {
+  if (result.updated || (result.deduped && !result.superseded)) {
+    return { decision: null, enqueue: null };
+  }
+
+  if (result.superseded) {
+    const replacement = await requiredSnapshot(db, input.workspaceId, result.memory.id);
+    if (replacement.supersedesId === result.superseded.id) {
+      return await evaluateAndEnqueue(db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        snapshot: replacement,
+        changeKind: "corrected",
+        relatedMemoryId: result.superseded.id,
+        occurredAt: result.memory.updatedAt,
+        publication,
+      });
+    }
+    const retired = await requiredSnapshot(db, input.workspaceId, result.superseded.id);
+    return await evaluateAndEnqueue(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      snapshot: retired,
+      changeKind: "superseded",
+      relatedMemoryId: result.memory.id,
+      occurredAt: result.superseded.updatedAt,
+      publication,
+    });
+  }
+
+  const created = await requiredSnapshot(db, input.workspaceId, result.memory.id);
+  return await evaluateAndEnqueue(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    snapshot: created,
+    changeKind: "created",
+    relatedMemoryId: null,
+    occurredAt: result.memory.createdAt,
+    publication,
+  });
+}
+
+async function evaluateAndEnqueue(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    snapshot: WorkspaceMemorySlackPublicationSnapshot;
+    changeKind: "created" | "corrected" | "superseded";
+    relatedMemoryId: string | null;
+    occurredAt: string;
+    publication: MemorySlackPublicationCommitRequest;
+  },
+): Promise<MemorySlackPublicationCommitResult> {
+  const configuration = await getCurrentMemorySlackPublicationConfiguration(db, input.workspaceId);
+  const decision = evaluateMemorySlackPublication({
+    context: {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      now: input.occurredAt,
+    },
+    policy: configuration
+      ? {
+          enabled: configuration.enabled,
+          autoImportances: configuration.autoImportances,
+          reviewImportances: configuration.reviewImportances,
+        }
+      : undefined,
+    memory: {
+      sourceType: "workspace_memory",
+      accountId: input.snapshot.accountId,
+      workspaceId: input.snapshot.workspaceId,
+      id: input.snapshot.id,
+      version: input.snapshot.version,
+      status: input.snapshot.status as Parameters<
+        typeof evaluateMemorySlackPublication
+      >[0]["memory"]["status"],
+      kind: input.snapshot.kind as Parameters<
+        typeof evaluateMemorySlackPublication
+      >[0]["memory"]["kind"],
+      scopeType: input.snapshot.scopeType as Parameters<
+        typeof evaluateMemorySlackPublication
+      >[0]["memory"]["scopeType"],
+      namespace: input.snapshot.namespace,
+      labels: input.snapshot.labels,
+      validFrom: input.snapshot.validFrom,
+      validUntil: input.snapshot.validUntil,
+      supersedesId: input.snapshot.supersedesId,
+      supersededById: input.snapshot.supersededById,
+    },
+    change: {
+      kind: input.changeKind,
+      relatedMemoryId: input.relatedMemoryId,
+      occurredAt: input.occurredAt,
+      origin: input.publication.origin ?? "native",
+      ownerLabel: input.publication.ownerLabel ?? null,
+    },
+    distribution: input.publication.distribution,
+  });
+  if (!decision.eligible) return { decision, enqueue: null };
+
+  const enqueue = await enqueueMemorySlackPublication(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sourceType: "workspace_memory",
+    sourceId: input.snapshot.id,
+    sourceVersion: String(input.snapshot.version),
+    sourceIdempotencyKey: decision.idempotencyKey,
+    projection: decision.projection,
+    importance: decision.projection.importance,
+    deliveryMode: decision.deliveryMode,
+    actor: input.publication.actor,
+  });
+  return { decision, enqueue };
+}
+
+async function requiredSnapshot(db: Database, workspaceId: string, memoryId: string) {
+  const snapshot = await getWorkspaceMemorySlackPublicationSnapshot(db, workspaceId, memoryId);
+  if (!snapshot) throw new Error("Memory Slack publication source disappeared before commit");
+  return snapshot;
+}