@opengeni/core 0.28.1 → 1.0.0

package/src/domain/governed-learning-slack-publication.ts

@@ -0,0 +1,157 @@
+import type {
+  GovernedLearningActivationReceipt,
+  GovernedLearningActivationUndoReceipt,
+} from "@opengeni/contracts";
+import {
+  enqueueMemorySlackPublication,
+  getCurrentMemorySlackPublicationConfiguration,
+  resolveGovernedLearningEvidenceOrigin,
+  type Database,
+  type EnqueueMemorySlackPublicationResult,
+  type GovernedLearningEvidenceOrigin,
+} from "@opengeni/db";
+
+/**
+ * Narrow post-persistence notification port for governed-learning activation
+ * and undo receipts (migration 0269). The evaluator/controller own policy,
+ * authority, and the immutable receipts; this adapter only projects bounded,
+ * content-free facts into the existing Slack publication outbox. It never
+ * reads proposal content, evidence bytes, or destination bodies.
+ */
+export type GovernedLearningSlackEvent =
+  | {
+      kind: "activated";
+      receipt: GovernedLearningActivationReceipt;
+      sessionId: string | null;
+      attemptId: string | null;
+    }
+  | { kind: "undone"; receipt: GovernedLearningActivationUndoReceipt };
+
+export type GovernedLearningSlackPublicationResult =
+  | {
+      kind: "evidence_origin_unresolved" | "slack_derived_evidence" | "policy_quiet";
+      enqueue: null;
+    }
+  | { kind: "enqueued"; enqueue: EnqueueMemorySlackPublicationResult };
+
+export type GovernedLearningSlackProjection = {
+  summary: string;
+  outcome: "activated" | "undone";
+  destination: "instruction_policy" | "preference";
+  sourceKind: "scoped-knowledge-evidence" | "task-note" | null;
+  destinationRevisionId: string;
+  destinationVersion: number;
+  activationReceiptId: string;
+  undoReceiptId: string | null;
+  occurredAt: string;
+};
+
+const DESTINATION_LABEL: Record<"instruction_policy" | "preference", string> = {
+  instruction_policy: "workspace instruction policy",
+  preference: "workspace preference",
+};
+const SOURCE_LABEL: Record<"scoped-knowledge-evidence" | "task-note", string> = {
+  "scoped-knowledge-evidence": "workspace knowledge evidence",
+  "task-note": "a task note",
+};
+
+export function governedLearningSlackImportance(
+  event: GovernedLearningSlackEvent,
+): "major" | "normal" | "minor" {
+  if (event.kind === "undone") return "major";
+  return event.receipt.destination === "instruction_policy" ? "major" : "normal";
+}
+
+export function governedLearningSlackProjection(
+  event: GovernedLearningSlackEvent,
+): GovernedLearningSlackProjection {
+  if (event.kind === "activated") {
+    const receipt = event.receipt;
+    return {
+      summary: `Automatically activated a ${DESTINATION_LABEL[receipt.destination]} learned from ${SOURCE_LABEL[receipt.sourceKind]} (revision ${receipt.destinationNewVersion}). Undo is available through the workspace learning API.`,
+      outcome: "activated",
+      destination: receipt.destination,
+      sourceKind: receipt.sourceKind,
+      destinationRevisionId: receipt.destinationRevisionId,
+      destinationVersion: receipt.destinationNewVersion,
+      activationReceiptId: receipt.id,
+      undoReceiptId: null,
+      occurredAt: receipt.effectiveAt,
+    };
+  }
+  const receipt = event.receipt;
+  return {
+    summary: `Undid an automatic ${DESTINATION_LABEL[receipt.destination]} activation (revision ${receipt.destinationOldVersion} → ${receipt.destinationNewVersion}).`,
+    outcome: "undone",
+    destination: receipt.destination,
+    sourceKind: null,
+    destinationRevisionId: receipt.destinationActivatedRevisionId,
+    destinationVersion: receipt.destinationNewVersion,
+    activationReceiptId: receipt.activationReceiptId,
+    undoReceiptId: receipt.id,
+    occurredAt: receipt.effectiveAt,
+  };
+}
+
+/** Evidence that itself came from a Slack knowledge connector must never republish to Slack. */
+export function governedLearningEvidenceIsSlackDerived(
+  origin: GovernedLearningEvidenceOrigin,
+): boolean {
+  return origin.kind === "document" && /slack/iu.test(origin.providerKey ?? "");
+}
+
+export async function publishGovernedLearningEventToSlack(
+  db: Database,
+  event: GovernedLearningSlackEvent,
+  options: {
+    resolveEvidenceOrigin?: typeof resolveGovernedLearningEvidenceOrigin;
+    configuration?: typeof getCurrentMemorySlackPublicationConfiguration;
+    enqueue?: typeof enqueueMemorySlackPublication;
+  } = {},
+): Promise<GovernedLearningSlackPublicationResult> {
+  const workspaceId = event.receipt.workspaceId;
+  if (event.kind === "activated") {
+    // Loop prevention: evidence that came from a Slack knowledge connector
+    // must not be republished to Slack. Task-note evidence is always local.
+    const origin = await (options.resolveEvidenceOrigin ?? resolveGovernedLearningEvidenceOrigin)(
+      db,
+      { workspaceId, evidenceId: event.receipt.evidenceId },
+    );
+    if (!origin) return { kind: "evidence_origin_unresolved", enqueue: null };
+    if (governedLearningEvidenceIsSlackDerived(origin)) {
+      return { kind: "slack_derived_evidence", enqueue: null };
+    }
+  }
+  const importance = governedLearningSlackImportance(event);
+  const configuration = await (
+    options.configuration ?? getCurrentMemorySlackPublicationConfiguration
+  )(db, workspaceId);
+  const deliveryMode = configuration?.autoImportances.includes(importance)
+    ? "auto"
+    : configuration?.reviewImportances.includes(importance)
+      ? "review"
+      : null;
+  if (!configuration?.enabled || !deliveryMode) return { kind: "policy_quiet", enqueue: null };
+
+  const projection = governedLearningSlackProjection(event);
+  const receipt = event.receipt;
+  const enqueue = await (options.enqueue ?? enqueueMemorySlackPublication)(db, {
+    accountId: receipt.accountId,
+    workspaceId,
+    sourceType: "durable_learning",
+    sourceId: receipt.id,
+    sourceVersion: String(projection.destinationVersion),
+    sourceIdempotencyKey: `governed-learning:${event.kind}:${receipt.id}`,
+    projection: { ...projection },
+    importance,
+    deliveryMode,
+    actor: {
+      kind: "service",
+      subjectId: receipt.serviceActorSubjectId,
+      initiatingHumanSubjectId: receipt.initiatingHumanSubjectId,
+      sessionId: event.kind === "activated" ? event.sessionId : null,
+      attemptId: event.kind === "activated" ? event.attemptId : null,
+    },
+  });
+  return { kind: "enqueued", enqueue };
+}

package/src/domain/insights-timing.ts

@@ -0,0 +1,95 @@
+import { withDatabaseTimingObserver, type DatabaseTimingObservation } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+
+const phases = new Set([
+  "auth",
+  "require_workspace",
+  "model_bundle",
+  "usage_bundle",
+  "live_warm",
+  "scheduled_tasks",
+  "session_depth",
+  "floor_sessions",
+  "online_machines",
+  "attached_sessions",
+  "scheduled_fires",
+] as const);
+export type InsightsPhase = typeof phases extends Set<infer T> ? T : never;
+export type InsightsPhaseObservation = {
+  phase: InsightsPhase;
+  stage: "helper" | DatabaseTimingObservation["stage"];
+  outcome: "completed" | "failed";
+  durationMs: number;
+};
+export type InsightsPhaseObserver = (observation: InsightsPhaseObservation) => void;
+const stages = new Set([
+  "helper",
+  "transaction_admission",
+  "savepoint_admission",
+  "rls_setup",
+  "scoped_callback",
+]);
+
+function observeSafely(
+  observer: InsightsPhaseObserver,
+  observation: InsightsPhaseObservation,
+): void {
+  try {
+    void Promise.resolve(observer(observation)).catch(() => undefined);
+  } catch {
+    // Telemetry is never authoritative for results or authorization.
+  }
+}
+
+/** Helper durations overlap under Promise.all; they must not be summed as request latency. */
+export async function measureInsightsPhase<T>(
+  observer: InsightsPhaseObserver | undefined,
+  phase: InsightsPhase,
+  work: () => Promise<T>,
+): Promise<T> {
+  if (!observer) return work();
+  const started = performance.now();
+  let outcome: InsightsPhaseObservation["outcome"] = "failed";
+  try {
+    const result = await withDatabaseTimingObserver(
+      (observation) => observeSafely(observer, { ...observation, phase }),
+      work,
+    );
+    outcome = "completed";
+    return result;
+  } finally {
+    observeSafely(observer, {
+      phase,
+      stage: "helper",
+      outcome,
+      durationMs: performance.now() - started,
+    });
+  }
+}
+
+/** Closed runtime label projection: caller input, SQL and identities never become labels. */
+export function workspaceInsightsPhaseMetricObserver(
+  observability: Pick<Observability, "observeHistogram"> | null | undefined,
+): InsightsPhaseObserver | undefined {
+  if (!observability) return undefined;
+  return (observation) => {
+    try {
+      const result = observability.observeHistogram({
+        name: "opengeni_workspace_insights_phase_duration_seconds",
+        help: "Insights helper and scoped DB durations; admission includes BEGIN or SAVEPOINT, scoped callback is not pure SQL time. Concurrent phases overlap.",
+        buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 3, 5, 10, 30, 60],
+        labels: {
+          phase: phases.has(observation.phase) ? observation.phase : "unknown",
+          stage: stages.has(observation.stage) ? observation.stage : "unknown",
+          outcome: observation.outcome === "completed" ? "completed" : "failed",
+        },
+        value: Number.isFinite(observation.durationMs)
+          ? Math.max(0, observation.durationMs) / 1_000
+          : 0,
+      });
+      void Promise.resolve(result).catch(() => undefined);
+    } catch {
+      // Includes exporter and metric registration failures.
+    }
+  };
+}

package/src/domain/insights-usage.ts

@@ -0,0 +1,67 @@
+import type {
+  InsightsCallsQuery,
+  InsightsCallsResponse,
+  InsightsUsageQuery,
+  InsightsUsageRange,
+  InsightsUsageResponse,
+} from "@opengeni/contracts/insights-usage";
+import { readInsightsCalls, readInsightsUsage, type Database } from "@opengeni/db";
+
+export type InsightsQueryScope = {
+  accountId: string;
+  /** null means organization scope; it does not grant workspace/session access. */
+  workspaceId: string | null;
+  /** Server-verified metadata authority; billing permission alone supplies none. */
+  detailsWorkspaceIds?: readonly string[];
+  /** Existing organization service-key authority applies only to shared workspaces. */
+  detailsSharedWorkspaces?: boolean;
+};
+
+export async function getInsightsUsage(
+  db: Database,
+  input: InsightsQueryScope & { query: InsightsUsageQuery; now?: Date },
+): Promise<InsightsUsageResponse> {
+  return await readInsightsUsage(db, { ...input, now: input.now ?? new Date() });
+}
+
+export async function listInsightsCalls(
+  db: Database,
+  input: InsightsQueryScope & { query: InsightsCallsQuery; now?: Date },
+): Promise<InsightsCallsResponse> {
+  return await readInsightsCalls(db, { ...input, now: input.now ?? new Date() });
+}
+
+/** UTC windows retain the actual request timestamp, including empty midnight windows. */
+export function insightsUsageWindow(range: InsightsUsageRange, now = new Date()) {
+  if (!Number.isFinite(now.getTime())) throw new Error("Invalid Insights request time");
+  const until = new Date(now);
+  const since = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  switch (range) {
+    case "today":
+      break;
+    case "week":
+      since.setUTCDate(since.getUTCDate() - 6);
+      break;
+    case "month":
+      since.setUTCDate(1);
+      break;
+    case "30d":
+      since.setUTCDate(since.getUTCDate() - 29);
+      break;
+    case "90d":
+      since.setUTCDate(since.getUTCDate() - 89);
+      break;
+    case "ytd":
+      since.setUTCMonth(0, 1);
+      break;
+  }
+  const priorUntil = new Date(since);
+  const priorSince = new Date(priorUntil.getTime() - (until.getTime() - since.getTime()));
+  return {
+    since,
+    until,
+    priorSince,
+    priorUntil,
+    bucket: range === "today" ? ("hour" as const) : ("day" as const),
+  };
+}