@opengeni/core 3.0.1 → 3.1.2

package/src/domain/editable-artifacts/agent-application.ts

@@ -26,10 +26,10 @@ import {
   type SpreadsheetArtifactKernelQuery,
 } from "@opengeni/contracts/editable-artifacts";
 
-import type {
-  EditableArtifactDurableExportService,
-  EditableArtifactMaterializationFormat,
-  EditableArtifactMaterializationJob,
+import {
+  type EditableArtifactDurableExportService,
+  type EditableArtifactMaterializationFormat,
+  type EditableArtifactMaterializationJob,
 } from "./durable-export";
 import {
   EditableArtifactDomainError,
@@ -76,6 +76,7 @@ export type EditableArtifactAgentContext = Readonly<{
 
 export type EditableArtifactAgentMetadata = Readonly<{
   id: string;
+  artifactReference: string;
   modality: EditableArtifactModality;
   title: string;
   lifecycle: EditableArtifact["lifecycle"];
@@ -174,6 +175,14 @@ export type EditableArtifactAgentApplicationDependencies = Readonly<{
   exports: EditableArtifactDurableExportService;
   associations: EditableArtifactAgentAssociationPort;
   inspector: EditableArtifactAgentInspectionKernelPort;
+  /** Production persists proof only after a successful native query. */
+  recordInspection?: (
+    input: EditableArtifactAgentContext & {
+      artifact: EditableArtifactAgentMetadata;
+      queryHash: string;
+      queryKind: string;
+    },
+  ) => Promise<string>;
   officeImports: EditableArtifactOfficeImportPort;
   workspaceFiles: EditableArtifactAgentWorkspaceFilePort;
 }>;
@@ -183,6 +192,9 @@ export type EditableArtifactAgentApplicationDependencies = Readonly<{
  * not another artifact engine: every mutation terminates at EditableArtifactService.
  */
 export class EditableArtifactAgentApplication {
+  describeExportFormats(): string {
+    return this.dependencies.exports.describeFormats();
+  }
   constructor(private readonly dependencies: EditableArtifactAgentApplicationDependencies) {}
 
   async list(
@@ -291,7 +303,13 @@ export class EditableArtifactAgentApplication {
   async inspect(
     input: EditableArtifactAgentContext &
       Readonly<{ artifactId: EditableArtifactId; request: EditableArtifactAgentQuery }>,
-  ): Promise<Readonly<{ artifact: EditableArtifactAgentMetadata; projection: unknown }>> {
+  ): Promise<
+    Readonly<{
+      artifact: EditableArtifactAgentMetadata;
+      projection: unknown;
+      inspectionReceiptId?: string;
+    }>
+  > {
     const context = agentContext(input);
     const artifactId = editableArtifactId(input.artifactId);
     const state = await this.dependencies.domain.readCurrentKernelState({
@@ -304,8 +322,21 @@ export class EditableArtifactAgentApplication {
     const queryBytes = encodeQuery(input.request);
     const responseBytes = await this.dependencies.inspector.query({ state, queryBytes });
     const projection = decodeQueryResponse(input.request.modality, responseBytes);
+    const inspectionReceiptId =
+      state.modality === "document"
+        ? await this.dependencies.recordInspection?.({
+            ...context,
+            artifact: projectArtifact(state.artifact),
+            queryHash: createHash("sha256").update(queryBytes).digest("hex"),
+            queryKind: input.request.query.kind,
+          })
+        : undefined;
     await this.touch(context, artifactId);
-    return Object.freeze({ artifact: projectArtifact(state.artifact), projection });
+    return Object.freeze({
+      artifact: projectArtifact(state.artifact),
+      projection,
+      ...(inspectionReceiptId ? { inspectionReceiptId } : {}),
+    });
   }
 
   async apply(
@@ -445,6 +476,12 @@ export class EditableArtifactAgentApplication {
       actor: context.actor,
       artifactId,
     });
+    // Refuse before pinning a version: the agent learns what does exist.
+    await this.dependencies.exports.preflight({
+      modality: artifact.modality,
+      format: input.format,
+      ...(input.options ? { options: input.options } : {}),
+    });
     const version = await this.dependencies.exports.pinVersion({
       scope: context.scope,
       actor: context.actor,
@@ -603,6 +640,7 @@ function commandProtocolVersion(modality: EditableArtifactModality): number {
 function projectArtifact(artifact: EditableArtifact): EditableArtifactAgentMetadata {
   return Object.freeze({
     id: artifact.id,
+    artifactReference: `[Open report](/workspaces/${artifact.scope.workspaceId}/artifacts/editable/${artifact.id})`,
     modality: artifact.modality,
     title: artifact.title,
     lifecycle: artifact.lifecycle,

package/src/domain/editable-artifacts/durable-export.ts

@@ -33,6 +33,63 @@ export type EditableArtifactMaterializationFormat =
   | "png"
   | "webp";
 
+/**
+ * Stock production export formats. Custom deployments advertise their own
+ * capabilities on the profile port; this list never overrides their resolver.
+ * Extend the stock list only together with a real deployed codec.
+ */
+export const EDITABLE_ARTIFACT_EXPORT_FORMATS: Readonly<
+  Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+> = Object.freeze({
+  spreadsheet: Object.freeze(["xlsx"] as const),
+  document: Object.freeze([] as const),
+  presentation: Object.freeze([] as const),
+});
+
+/** Human/agent-readable summary of {@link EDITABLE_ARTIFACT_EXPORT_FORMATS}. */
+export function describeEditableArtifactExportFormats(): string {
+  return describeConfiguredExportFormats(EDITABLE_ARTIFACT_EXPORT_FORMATS);
+}
+
+export function describeConfiguredExportFormats(
+  configuredFormats: Readonly<
+    Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+  >,
+): string {
+  const entries = Object.entries(configuredFormats) as Array<
+    [EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]]
+  >;
+  const supported = entries
+    .filter(([, formats]) => formats.length > 0)
+    .map(([modality, formats]) => `${modality} → ${formats.join(", ")}`);
+  const none = entries.filter(([, formats]) => formats.length === 0).map(([modality]) => modality);
+  return [
+    supported.length > 0
+      ? `Supported exports: ${supported.join("; ")}.`
+      : "No exports are available.",
+    none.length > 0
+      ? `${none.join(" and ")} artifacts cannot be exported yet (no PDF, DOCX, PPTX, or image export); share the live artifact with its artifactReference link instead.`
+      : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/** Typed refusal that tells the caller which formats do exist. */
+export function unsupportedEditableArtifactExport(
+  modality: EditableArtifactModality,
+  format: string,
+  formats = EDITABLE_ARTIFACT_EXPORT_FORMATS,
+): EditableArtifactDurableExportError {
+  const listed = (formats[modality] as readonly string[]).includes(format);
+  return new EditableArtifactDurableExportError(
+    "unsupported_format",
+    listed
+      ? `unsupported_format: this deployment does not serve a ${format} export of a ${modality} artifact with these options; retry with options omitted. ${describeConfiguredExportFormats(formats)}`
+      : `unsupported_format: a ${modality} artifact cannot be exported as ${format}. ${describeConfiguredExportFormats(formats)}`,
+  );
+}
+
 export type EditableArtifactMaterializationMimeType =
   | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
   | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
@@ -98,6 +155,11 @@ export type EditableArtifactMaterializationProfile = Readonly<{
 
 /** Server-owned profile lookup. Clients never supply executable identity facts. */
 export interface EditableArtifactMaterializationProfilePort {
+  /** Deployment-owned discovery; resolve remains the authority for exact options.
+   * Optional for existing custom adapters, whose support is resolved dynamically. */
+  supportedFormats?: Readonly<
+    Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+  >;
   resolve(
     input: Readonly<{
       modality: EditableArtifactModality;
@@ -223,8 +285,11 @@ export type EditableArtifactDurableExportErrorCode =
   | "unavailable";
 
 export class EditableArtifactDurableExportError extends Error {
-  constructor(readonly code: EditableArtifactDurableExportErrorCode) {
-    super(code);
+  constructor(
+    readonly code: EditableArtifactDurableExportErrorCode,
+    message?: string,
+  ) {
+    super(message ?? code);
     this.name = "EditableArtifactDurableExportError";
   }
 }
@@ -247,6 +312,38 @@ const PROFILE_TEXT = /^[\x21-\x7e]+$/u;
 export class EditableArtifactDurableExportService {
   constructor(private readonly dependencies: EditableArtifactDurableExportServiceDependencies) {}
 
+  describeFormats(): string {
+    const formats = this.dependencies.profiles.supportedFormats;
+    return formats
+      ? describeConfiguredExportFormats(formats)
+      : "Export formats are determined by this deployment's configured exporter; unsupported format/options combinations are refused before pinning.";
+  }
+
+  /** Read-only exact preflight: no snapshot, ID allocation, or store write. */
+  async preflight(input: {
+    modality: EditableArtifactModality;
+    format: EditableArtifactMaterializationFormat;
+    options?: Readonly<Record<string, unknown>>;
+  }): Promise<EditableArtifactMaterializationProfile> {
+    const format = materializationFormat(input.format);
+    const options = exactOptions(input.options ?? Object.freeze({}));
+    const profile = await this.dependencies.profiles.resolve({
+      modality: input.modality,
+      format,
+      options,
+    });
+    if (!profile) {
+      const formats = this.dependencies.profiles.supportedFormats;
+      if (formats) throw unsupportedEditableArtifactExport(input.modality, format, formats);
+      throw new EditableArtifactDurableExportError(
+        "unsupported_format",
+        `unsupported_format: this deployment does not serve ${input.modality} → ${format} with these options. ${this.describeFormats()}`,
+      );
+    }
+    validateProfile(profile, input.modality, format);
+    return profile;
+  }
+
   async pinVersion(
     input: DurableExportContext & {
       idempotencyKey: string;
@@ -307,13 +404,11 @@ export class EditableArtifactDurableExportService {
     const format = materializationFormat(input.format);
     const options = exactOptions(input.options ?? Object.freeze({}));
     const version = await this.getVersion(context, versionId);
-    const profile = await this.dependencies.profiles.resolve({
+    const profile = await this.preflight({
       modality: version.modality,
       format,
       options,
     });
-    if (!profile) throw new EditableArtifactDurableExportError("unsupported_format");
-    validateProfile(profile, version.modality, format);
     const requestHash = hashPublicRequest("materialize", [
       idempotencyKey,
       versionId,

package/src/domain/editable-artifacts/in-memory.ts

@@ -429,6 +429,9 @@ export class InMemoryEditableArtifactStore
     artifactId: EditableArtifactId,
     request: ReadEditableArtifactTransactionBasisRequest,
   ): Promise<EditableArtifactTransactionBasis> {
+    if (request.authorizeCommit) {
+      throw new TypeError("Transactional artifact authority requires a PostgreSQL store");
+    }
     const normalizedScope = editableArtifactScope(scope);
     const normalizedArtifactId = editableArtifactId(artifactId);
     const key = aggregateKey(normalizedScope, normalizedArtifactId);
@@ -496,6 +499,9 @@ export class InMemoryEditableArtifactStore
   async tryCommitAppliedTransaction(
     request: TryCommitAppliedEditableArtifactTransactionRequest,
   ): Promise<TryCommitAppliedEditableArtifactTransactionResult> {
+    if (request.authorizeCommit) {
+      throw new TypeError("Transactional artifact authority requires a PostgreSQL store");
+    }
     const scope = editableArtifactScope(request.scope);
     const artifactId = editableArtifactId(request.artifactId);
     const key = aggregateKey(scope, artifactId);

package/src/domain/editable-artifacts/ports.ts

@@ -1,3 +1,4 @@
+import type { Database } from "@opengeni/db";
 import type {
   EditableArtifact,
   EditableArtifactActor,
@@ -288,6 +289,8 @@ export type ReadEditableArtifactTransactionBasisRequest = Readonly<{
   clientTransactionId: EditableArtifactReceipt["clientTransactionId"];
   previousLocalTransactionId: EditableArtifactReceipt["previousLocalTransactionId"];
   selectiveUndoOperationIds: readonly EditableArtifactOperationId[];
+  /** Backend-only live authority; checked transactionally even on receipt replay. */
+  authorizeCommit?: EditableArtifactCommitAuthorizer;
 }>;
 
 export type EditableArtifactTransactionUndoBasis = Readonly<{
@@ -324,6 +327,13 @@ export type ExpectedEditableArtifactPredecessor = Readonly<{
   replicaCounter: number;
 }>;
 
+/**
+ * Receives the actual persistence transaction, never a separate pool handle.
+ * May run repeatedly for replay, lock admission and final persistence; must not
+ * perform external mutations. Stores without this transaction capability deny.
+ */
+export type EditableArtifactCommitAuthorizer = (tx: Database) => Promise<void>;
+
 export type TryCommitAppliedEditableArtifactTransactionRequest =
   CommitAppliedEditableArtifactTransaction &
     Readonly<{
@@ -333,6 +343,7 @@ export type TryCommitAppliedEditableArtifactTransactionRequest =
       expectedAuthorizationRevision: number;
       /** Rechecked by durable production stores in the commit transaction. */
       authorizationActor: EditableArtifactActor;
+      authorizeCommit?: EditableArtifactCommitAuthorizer;
       actorKey: string;
       clientTransactionId: EditableArtifactReceipt["clientTransactionId"];
       requestHash: EditableArtifactReceipt["requestHash"];

package/src/domain/editable-artifacts/service.ts

@@ -13,6 +13,7 @@ import {
   EditableArtifactUndoTargetError,
 } from "./errors";
 import type {
+  EditableArtifactCommitAuthorizer,
   AuthoritativeEditableArtifactKernelPort,
   EditableArtifactAuthorizationPort,
   EditableArtifactClockPort,
@@ -547,6 +548,8 @@ export class EditableArtifactService {
     artifactId: EditableArtifact["id"];
     actor: EditableArtifactActor;
     request: ApplyEditableArtifactTransactionRequest;
+    /** Authenticated backend authority, not part of the client mutation envelope. */
+    authorizeCommit?: EditableArtifactCommitAuthorizer;
   }): Promise<ApplyEditableArtifactTransactionResult> {
     const context = normalizeBoundaryContext(input);
     const request = normalizeTransactionEnvelope(input.request);
@@ -570,6 +573,19 @@ export class EditableArtifactService {
     }
     const intentBytes = request.intentBytes.slice();
     const actorKey = editableArtifactActorKey(context.actor);
+    // A source-bound caller must prove its own authority on commit/replay.
+    // Sharing another caller's in-flight result would skip that proof.
+    if (input.authorizeCommit) {
+      return await this.applyTransactionOptimistically({
+        context,
+        actorKey,
+        request,
+        intent,
+        intentBytes,
+        authorizationRevision,
+        authorizeCommit: input.authorizeCommit,
+      });
+    }
     const inFlightKey = transactionInFlightKey(
       context.scope,
       context.artifactId,
@@ -631,6 +647,7 @@ export class EditableArtifactService {
     intent: ValidatedEditableArtifactMutationIntent;
     intentBytes: Uint8Array;
     authorizationRevision: number;
+    authorizeCommit?: EditableArtifactCommitAuthorizer;
   }): Promise<ApplyEditableArtifactTransactionResult> {
     const { context, actorKey, request, intent, intentBytes } = input;
     let authorizationRevision = input.authorizationRevision;
@@ -643,6 +660,7 @@ export class EditableArtifactService {
           clientTransactionId: intent.clientTransactionId,
           previousLocalTransactionId: intent.previousLocalTransactionId,
           selectiveUndoOperationIds: intent.selectiveUndoOperationIds,
+          ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
         },
       );
       if (basisRead.kind === "existing") {
@@ -797,6 +815,7 @@ export class EditableArtifactService {
           expectedLifecycle: "active",
           expectedAuthorizationRevision: authorizationRevision,
           authorizationActor: context.actor,
+          ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
           expectedHeadSequence: artifact.headSequence,
           actorKey,
           clientTransactionId: intent.clientTransactionId,
@@ -1037,6 +1056,7 @@ export class EditableArtifactService {
         expectedLifecycle: "active",
         expectedAuthorizationRevision: authorizationRevision,
         authorizationActor: context.actor,
+        ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
         expectedHeadSequence: artifact.headSequence,
         actorKey,
         clientTransactionId: intent.clientTransactionId,

package/src/domain/editable-artifacts/types.ts

@@ -7,7 +7,7 @@ import { EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES } from "@opengeni/contracts/
 /**
  * Domain vocabulary for collaborative, editable Office-like artifacts.
  *
- * This is intentionally unrelated to OpenGeni's published HTML artifacts and
+ * This is intentionally unrelated to Opengeni's published HTML artifacts and
  * document-ingestion records. An editable artifact is mutable canonical model
  * state plus a causally ordered operation history.
  */

package/src/domain/encryption-key.ts

@@ -0,0 +1,26 @@
+import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * The deployment's at-rest encryption key (`OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY`),
+ * shared by vault values and stored connection credentials.
+ */
+export function requireEnvironmentEncryption(settings: Settings): Uint8Array {
+  const key = environmentsEncryptionKeyBytes(settings);
+  if (!key) {
+    throw new HTTPException(503, {
+      message: "secrets require OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY",
+    });
+  }
+  return key;
+}
+
+/**
+ * RM-1 for internal callers: Variable Sets were replaced by vaults, so a
+ * request that still selects one is refused instead of silently ignored.
+ */
+export function variableSetsRemovedError(field: string): HTTPException {
+  return new HTTPException(422, {
+    message: `variable_sets_removed: ${field} is no longer supported; Variable Sets were replaced by vaults (use vaultPolicy)`,
+  });
+}

package/src/domain/file-owner.ts

@@ -1,5 +1,9 @@
 import { requireLiveAgentAttemptAuthorization } from "../session-authorization";
-import { freezeAgentLearningPolicy, type SessionRlsActorContext } from "@opengeni/db";
+import {
+  freezeAgentLearningPolicy,
+  getSessionAuthorityProjection,
+  type SessionRlsActorContext,
+} from "@opengeni/db";
 import type { AccessGrant, Permission } from "@opengeni/contracts";
 import { requirePermission, type AccessGrantAuthorization } from "../access";
 import type { ApiRouteDeps } from "../dependencies";
@@ -44,7 +48,18 @@ export async function fileOwnerContextForAgent(
       executionGeneration: attempt.executionGeneration,
     },
   });
+  const sessionAuthority = await getSessionAuthorityProjection(
+    deps.db,
+    grant.workspaceId,
+    sessionId,
+  );
+  if (!sessionAuthority) throw new Error("File session authority unavailable");
   return {
+    sessionAttachmentReadAccess: {
+      sessionId,
+      authorityEpoch: sessionAuthority.authorityEpoch,
+      actor: attempt,
+    },
     subjectId: grant.subjectId,
     initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
     privateFileOwnerSubjectId: snapshot.defaultScope === "personal" ? snapshot.subjectId : null,

package/src/domain/github-action-policies.ts

@@ -150,7 +150,7 @@ export function githubAppActionPolicyActor(input: {
 }): GitHubActionPolicyActorBinding {
   return {
     actor: { kind: "workspace_app", installationId: input.installationId },
-    label: input.accountLogin ? `OpenGeni bot on ${input.accountLogin}` : "OpenGeni bot",
+    label: input.accountLogin ? `Opengeni bot on ${input.accountLogin}` : "Opengeni bot",
     connectionId: `github-app:${input.installationId}`,
     serverId: GITHUB_REST_MCP_APP_SERVER_ID,
   };

package/src/domain/github-skill-source.ts

@@ -4,6 +4,7 @@ import type { GitHubSkillSourceClient, GitHubSkillTreeEntry } from "./skill-impo
 import { pinnedFetch, readResponseJsonBounded, readResponseTextBounded } from "@opengeni/network";
 import {
   PORTABLE_SKILL_MAX_FILES,
+  PORTABLE_SKILL_MAX_FILE_BYTES,
   PORTABLE_SKILL_MAX_TOTAL_BYTES,
   type SkillLibraryFile,
 } from "@opengeni/runtime/skill-library";
@@ -11,7 +12,8 @@ import {
 const githubApiBase = "https://api.github.com";
 const githubRequestTimeoutMs = 15_000;
 const githubMetadataMaxBytes = 4 * 1024 * 1024;
-const githubBlobResponseMaxBytes = 512 * 1024;
+// GitHub blobs are base64-encoded JSON; allow framing and line wrapping.
+const githubBlobResponseMaxBytes = PORTABLE_SKILL_MAX_FILE_BYTES * 2;
 
 type GitHubJsonRequest = (path: string, maxBytes: number, label: string) => Promise<unknown>;
 

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),
+  };
+}