@opengeni/core 0.28.1 → 1.0.0

package/dist/domain/governed-learning-slack-publication.d.ts

@@ -0,0 +1,45 @@
+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;
+};
+export declare function governedLearningSlackImportance(event: GovernedLearningSlackEvent): "major" | "normal" | "minor";
+export declare function governedLearningSlackProjection(event: GovernedLearningSlackEvent): GovernedLearningSlackProjection;
+/** Evidence that itself came from a Slack knowledge connector must never republish to Slack. */
+export declare function governedLearningEvidenceIsSlackDerived(origin: GovernedLearningEvidenceOrigin): boolean;
+export declare function publishGovernedLearningEventToSlack(db: Database, event: GovernedLearningSlackEvent, options?: {
+    resolveEvidenceOrigin?: typeof resolveGovernedLearningEvidenceOrigin;
+    configuration?: typeof getCurrentMemorySlackPublicationConfiguration;
+    enqueue?: typeof enqueueMemorySlackPublication;
+}): Promise<GovernedLearningSlackPublicationResult>;

package/dist/domain/insights-timing.d.ts

@@ -0,0 +1,16 @@
+import { type DatabaseTimingObservation } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+declare const phases: Set<"attached_sessions" | "auth" | "floor_sessions" | "live_warm" | "model_bundle" | "online_machines" | "require_workspace" | "scheduled_fires" | "scheduled_tasks" | "session_depth" | "usage_bundle">;
+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;
+/** Helper durations overlap under Promise.all; they must not be summed as request latency. */
+export declare function measureInsightsPhase<T>(observer: InsightsPhaseObserver | undefined, phase: InsightsPhase, work: () => Promise<T>): Promise<T>;
+/** Closed runtime label projection: caller input, SQL and identities never become labels. */
+export declare function workspaceInsightsPhaseMetricObserver(observability: Pick<Observability, "observeHistogram"> | null | undefined): InsightsPhaseObserver | undefined;
+export {};

package/dist/domain/insights-usage.d.ts

@@ -0,0 +1,27 @@
+import type { InsightsCallsQuery, InsightsCallsResponse, InsightsUsageQuery, InsightsUsageRange, InsightsUsageResponse } from "@opengeni/contracts/insights-usage";
+import { 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 declare function getInsightsUsage(db: Database, input: InsightsQueryScope & {
+    query: InsightsUsageQuery;
+    now?: Date;
+}): Promise<InsightsUsageResponse>;
+export declare function listInsightsCalls(db: Database, input: InsightsQueryScope & {
+    query: InsightsCallsQuery;
+    now?: Date;
+}): Promise<InsightsCallsResponse>;
+/** UTC windows retain the actual request timestamp, including empty midnight windows. */
+export declare function insightsUsageWindow(range: InsightsUsageRange, now?: Date): {
+    since: Date;
+    until: Date;
+    priorSince: Date;
+    priorUntil: Date;
+    bucket: "day" | "hour";
+};

package/dist/domain/insights.d.ts

@@ -1,11 +1,38 @@
 import { type Settings } from "@opengeni/config";
 import { type InsightsRange, type WorkspaceInsightsResponse } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
+import { type InsightsPhaseObserver } from "./insights-timing.js";
+export { measureInsightsPhase, workspaceInsightsPhaseMetricObserver } from "./insights-timing.js";
+export type { InsightsPhaseObservation, InsightsPhaseObserver } from "./insights-timing.js";
+export declare const WORKSPACE_INSIGHTS_PROVIDER_FILTER_MAX_UTF8_BYTES = 256;
+export declare const WORKSPACE_INSIGHTS_MODEL_FILTER_MAX_UTF8_BYTES = 512;
+export type WorkspaceInsightsFilterField = "provider" | "model" | "rootSessionId" | "sessionId";
+export declare class WorkspaceInsightsFilterValidationError extends Error {
+    readonly field: WorkspaceInsightsFilterField;
+    readonly maxUtf8Bytes: number;
+    constructor(field: WorkspaceInsightsFilterField, maxUtf8Bytes: number, message?: string);
+}
+/** Normalize a session drilldown scope; only exact UUIDs are accepted. */
+export declare function normalizeWorkspaceInsightsSessionScope(value: string | null | undefined, field: "rootSessionId" | "sessionId"): string | null;
+/** Normalize the public filter sentinel and enforce the database authority envelope. */
+export declare function normalizeWorkspaceInsightsFilter(value: string | null | undefined, field: WorkspaceInsightsFilterField): string | null;
 export type GetWorkspaceInsightsInput = {
     workspaceId: string;
     range: InsightsRange;
     provider?: string | null;
     model?: string | null;
+    rootSessionId?: string | null;
+    sessionId?: string | null;
     now?: Date;
 };
-export declare function getWorkspaceInsights(db: Database, settings: Settings, input: GetWorkspaceInsightsInput): Promise<WorkspaceInsightsResponse>;
+export declare function insightsSessionLabel(input: {
+    id: string;
+    title: string | null;
+    depth?: number | null;
+}): string;
+export declare function insightsProjectLabel(input: {
+    kind: "project" | "other" | "unfiled" | "unavailable" | "deleted";
+    name: string | null;
+    projects: number;
+}): string;
+export declare function getWorkspaceInsights(db: Database, settings: Settings, input: GetWorkspaceInsightsInput, observePhase?: InsightsPhaseObserver): Promise<WorkspaceInsightsResponse>;

package/dist/domain/knowledge-files.d.ts

@@ -0,0 +1,20 @@
+import { type KnowledgeContext } from "@opengeni/db";
+import type { ApiRouteDeps } from "../dependencies.js";
+/** Existing original -> one source revision, through the ordinary task policy. */
+export declare function prepareKnowledgeFile(deps: Pick<ApiRouteDeps, "db" | "objectStorage" | "getDocumentServices">, context: KnowledgeContext, fileId: string, purpose?: "evidence" | "reference"): Promise<{
+    status: "retained";
+    fileId: string;
+    filename: string;
+    receipt: {
+        operationId: string;
+        entryId: string;
+        revisionId: string;
+        version: number;
+        outcome: "archived" | "pending" | "published" | "rejected";
+        reviewBatchId: string | null;
+        replayed: boolean;
+    };
+} | {
+    status: "disabled";
+    fileId: string;
+}>;

package/dist/domain/knowledge-messages.d.ts

@@ -0,0 +1,39 @@
+import { type Database, type KnowledgeContext } from "@opengeni/db";
+/** Retain actual message bytes, never a model-authored reconstruction of a confirmation. */
+export declare function retainKnowledgeMessage(db: Database, context: KnowledgeContext, messageId?: string): Promise<{
+    retained: boolean;
+    reason: string;
+    entryId?: never;
+    revisionId?: never;
+    outcome?: never;
+    messageId?: never;
+    reused?: never;
+} | {
+    retained: boolean;
+    reason: string;
+    entryId: string;
+    revisionId?: never;
+    outcome?: never;
+    messageId?: never;
+    reused?: never;
+} | {
+    reason?: never;
+    retained: boolean;
+    entryId: string;
+    revisionId: string;
+    outcome: "pending" | "published" | "superseded";
+    messageId: string;
+    reused: boolean;
+} | {
+    operationId: string;
+    entryId: string;
+    revisionId: string;
+    version: number;
+    outcome: "archived" | "pending" | "published" | "rejected";
+    reviewBatchId: string | null;
+    replayed: boolean;
+    reason?: never;
+    reused?: never;
+    retained: boolean;
+    messageId: string;
+}>;

package/dist/domain/knowledge-messages.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/knowledge-preparation.d.ts

@@ -0,0 +1,10 @@
+import { KnowledgeSavePreparationRequest, type KnowledgeSavePreparationResponse } from "@opengeni/contracts";
+import { getKnowledgeEntry, listKnowledgeEntries, type Database, type KnowledgeContext } from "@opengeni/db";
+import type { DocumentEmbedder } from "@opengeni/documents";
+import type { Settings } from "@opengeni/config";
+import { searchKnowledgeEntries } from "./knowledge-search.js";
+export declare function prepareKnowledgeSave(db: Database, context: KnowledgeContext, input: KnowledgeSavePreparationRequest, embedder: () => DocumentEmbedder, services?: {
+    get: typeof getKnowledgeEntry;
+    list: typeof listKnowledgeEntries;
+    search: typeof searchKnowledgeEntries;
+}, settings?: Settings): Promise<KnowledgeSavePreparationResponse>;

package/dist/domain/knowledge-preparation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/knowledge-search.d.ts

@@ -0,0 +1,15 @@
+import { KnowledgeEntryListRequest, type KnowledgeEntryListResponse } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import { type Database, type KnowledgeContext } from "@opengeni/db";
+import type { DocumentEmbedder } from "@opengeni/documents";
+import type { z } from "zod";
+export declare class KnowledgeVectorFundingError extends Error {
+    readonly code = "knowledge_vector_funding_required";
+    constructor();
+}
+export declare class KnowledgeVectorQueryRejectedError extends Error {
+    readonly code: "pagination_unavailable" | "query_limit" | "quota";
+    constructor(code: "pagination_unavailable" | "query_limit" | "quota", message: string);
+}
+/** Shared search path for HTTP and both first-party retrieval servers. */
+export declare function searchKnowledgeEntries(db: Database, context: KnowledgeContext, input: z.input<typeof KnowledgeEntryListRequest>, embedder: () => DocumentEmbedder, settings?: Settings): Promise<KnowledgeEntryListResponse>;

package/dist/domain/knowledge-search.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/knowledge.d.ts

@@ -0,0 +1,9 @@
+import type { AccessGrant, Permission } from "@opengeni/contracts";
+import type { KnowledgeContext } from "@opengeni/db";
+import { type AccessGrantAuthorization } from "../access/index.js";
+import type { ApiRouteDeps } from "../dependencies.js";
+/** A delegated MCP gateway can retrieve shared Knowledge. Its subject label
+ * does not establish personal ownership or human review authority. */
+export declare function knowledgeContextForGateway(deps: Pick<ApiRouteDeps, "db">, grant: AccessGrant): Promise<KnowledgeContext>;
+/** One host boundary for HTTP, SDK-through-HTTP and first-party Knowledge tools. */
+export declare function knowledgeContextForAccess(deps: Pick<ApiRouteDeps, "db">, access: AccessGrantAuthorization, permission: Permission): Promise<KnowledgeContext>;

package/dist/domain/mcp-account-bindings.d.ts

@@ -0,0 +1,19 @@
+import type { McpServerConfig } from "@opengeni/config";
+import { type ConnectionMetadata, type McpConnectionAccountBinding, type McpConnectionAccountSelection, type McpPersonalConnectionDelegation } from "@opengeni/contracts";
+/** Account routes are stable across retries, but are never parsed to discover
+ * authority. The canonical server is retained separately in the binding. */
+export declare function mcpAccountRouteId(serverId: string, connectionId: string): string;
+/** Pure admission projection over an already authorized inventory. Explicit
+ * pairs narrow one connector; omission attaches all eligible accounts. */
+export declare function mcpAccountBindingsFromVisibleConnections(input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string | null;
+    servers: McpServerConfig[];
+    connections: ConnectionMetadata[];
+    selections?: McpConnectionAccountSelection[];
+    /** The complete accepted set, including an explicitly empty set. */
+    selectionsFrozen?: boolean;
+}): McpConnectionAccountBinding[];
+/** Workspace accounts never acquire a fabricated personal owner/delegation. */
+export declare function personalDelegationsForAccountBindings(bindings: McpConnectionAccountBinding[]): McpPersonalConnectionDelegation[];

package/dist/domain/mcp-account-routes.d.ts

@@ -0,0 +1,21 @@
+import type { Settings } from "@opengeni/config";
+import type { McpConnectionAccountBinding, ToolRef } from "@opengeni/contracts";
+import type { ApiIntegrationRuntime } from "@opengeni/db";
+/** Expand only after canonical tool-policy admission. Aliases are execution
+ * identities, never an alternate way to gain admission to a connector. */
+export declare function expandMcpAccountRoutes(input: {
+    settings: Settings;
+    tools: ToolRef[];
+    bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+}): {
+    settings: Settings;
+    tools: ToolRef[];
+    accountLabels: ReadonlyMap<string, string>;
+};
+/** Each adapter closes over its own immutable credential ref and authority
+ * generation. Sharing a provider transport never shares a credential resolver. */
+export declare function expandApiIntegrationAccountRoutes(input: {
+    integrations: readonly ApiIntegrationRuntime[];
+    bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+    tools: readonly ToolRef[];
+}): ApiIntegrationRuntime[];

package/dist/domain/native-mcp-connection-admission.d.ts

@@ -0,0 +1,3 @@
+import type { McpServerConnectionRef } from "@opengeni/contracts";
+/** Reject retired authority sources instead of aliasing them to native IDs. */
+export declare function assertNativeMcpConnectionRef(connectionRef: McpServerConnectionRef | null | undefined): void;

package/dist/domain/organization-integration-catalog.d.ts

@@ -0,0 +1,15 @@
+import { type IntegrationSourceInput, type OrganizationIntegrationPolicy } from "@opengeni/contracts";
+/** Admission for source discovery, before any credential-bearing network work.
+ * Auto-detection may try only protocols the organization actually permits.
+ */
+export declare function integrationSourceForOrganizationPolicy(policy: OrganizationIntegrationPolicy, source: IntegrationSourceInput): IntegrationSourceInput;
+/** Product identities owned by the server, independent of mutable workspace catalogs. */
+export declare function organizationIntegrationCatalog(): {
+    integrations: Array<{
+        key: string;
+        label: string;
+        kind: "curated" | "custom";
+    }>;
+};
+/** Only use for a validated built-in Connect adapter, never caller-authored catalog metadata. */
+export declare function integrationKeyForConnectProvider(providerId: string): string | null;

package/dist/domain/organization-membership-lifecycle.d.ts

@@ -0,0 +1 @@
+export declare function organizationMembershipHttpStatus(sqlState: string | null): 400 | 403 | 404 | 409 | null;

package/dist/domain/personal-connection-delegations.d.ts

@@ -1,9 +1,16 @@
 import type { McpServerConfig, Settings } from "@opengeni/config";
-import type { AccessGrant, ConnectionMetadata, McpPersonalConnectionDelegation, SessionTurn, SocialConnection, ToolRef } from "@opengeni/contracts";
+import type { AccessGrant, ConnectionMetadata, McpConnectionAccountBinding, McpConnectionAccountSelection, McpPersonalConnectionDelegation, ResourceRef, SessionTurn, SocialConnection, ToolRef } from "@opengeni/contracts";
 import { type Database, type ResolveConnectionCredentialInput, type ResolveConnectionCredentialResult } from "@opengeni/db";
+export { ConnectionAccountSelectionError } from "./connection-account-selection-error.js";
 export type PersonalConnectionDelegationSource = {
     kind: "subject";
     subjectId: string;
+    /**
+     * Organization of the authorizing grant. The owner-only
+     * personal-workspace pointer lives on an organization membership, so
+     * the account is part of the question, not an optimization.
+     */
+    accountId: string;
 } | {
     kind: "turn";
     sessionId: string;
@@ -21,12 +28,19 @@ export type AuthorizedAtlassianConnection = {
 };
 export declare function directPersonalConnectionSubjectId(turn: Pick<SessionTurn, "source" | "initiator" | "initiatorContext">): string | undefined;
 export declare function personalConnectionDelegationSourceForGrant(grant: AccessGrant): PersonalConnectionDelegationSource;
+/** Account-picker inventory: shared workspace accounts and this sender's own
+ * personal accounts. Visibility is never an execution grant or a credential
+ * response; every selected connection is validated again at admission/use. */
+export declare function listOwnConnectionAccountsForGrant(db: Database, grant: AccessGrant, options?: {
+    includeInactive?: boolean;
+}): Promise<ConnectionMetadata[]>;
 export declare function authorizedSocialConnectionsForGrant(input: {
     db: Database;
     grant: AccessGrant;
     limit?: number;
 }): Promise<AuthorizedSocialConnection[]>;
-export declare function authorizedAtlassianConnectionsForGrant(input: {
+/** Historical native Atlassian grants no longer authorize API execution. */
+export declare function authorizedAtlassianConnectionsForGrant(_input: {
     db: Database;
     grant: AccessGrant;
 }): Promise<AuthorizedAtlassianConnection[]>;
@@ -35,10 +49,29 @@ export declare function personalConnectionDelegationsFromVisibleConnections(inpu
     servers: McpServerConfig[];
     subjectId: string;
     connections: ConnectionMetadata[];
+    authoritySelections?: McpConnectionAccountSelection[];
 }): McpPersonalConnectionDelegation[];
 export declare function personalConnectionDelegationsFromParent(input: {
     servers: McpServerConfig[];
     parentDelegations: McpPersonalConnectionDelegation[];
+    personalGitHubResources?: ResourceRef[];
+    targetSessionId?: string;
+}): McpPersonalConnectionDelegation[];
+/**
+ * Freezes Google Drive publishing only when one exact subject-owned connection
+ * is eligible. Multiple writable Google accounts are intentionally ambiguous:
+ * callers must narrow the connection before a later turn can advertise or use
+ * the private publication tool.
+ */
+export declare function googleDrivePublicationDelegationFromVisibleConnections(input: {
+    subjectId: string;
+    connections: ConnectionMetadata[];
+    authoritySelection?: McpConnectionAccountSelection;
+}): McpPersonalConnectionDelegation | null;
+/** Native Atlassian credentials remain stored but are not new turn authority. */
+export declare function personalAtlassianDelegationsFromVisibleConnections(_input: {
+    subjectId: string;
+    connections: ConnectionMetadata[];
 }): McpPersonalConnectionDelegation[];
 export declare function personalConnectionDelegationsEqual(left: McpPersonalConnectionDelegation[], right: McpPersonalConnectionDelegation[]): boolean;
 export declare function personalConnectionDelegationForServer(delegations: McpPersonalConnectionDelegation[], server: Pick<McpServerConfig, "id" | "connectionRef">): McpPersonalConnectionDelegation | null;
@@ -53,13 +86,63 @@ export declare function withFrozenPersonalConnectionDelegations(input: {
     resolveCredential: ConnectionCredentialResolver;
     settings: Pick<Settings, "mcpServers">;
     personalConnectionDelegations: McpPersonalConnectionDelegation[];
+    /**
+     * Does the frozen delegation owner still hold workspace authority? Supply
+     * the canonical `namedSubjectHasLiveWorkspaceAuthority` resolver, never a bare
+     * `workspace_memberships` lookup: a managed human's personal workspace has
+     * no membership row, so a bare lookup revokes the owner's own connections.
+     */
     ownerHasWorkspaceMembership: (subjectId: string) => Promise<boolean>;
 }): ConnectionCredentialResolver;
-export declare function freezePersonalConnectionDelegations(input: {
+/** Freeze all native account routes without conflating workspace ownership
+ * with the exact causal human required for personal connections. */
+export declare function freezeConnectionAccounts(input: Parameters<typeof freezePersonalConnectionDelegations>[0] & {
+    accountId: string;
+}): Promise<{
+    mcpAccountBindings: McpConnectionAccountBinding[] | null;
+    personalConnectionDelegations: McpPersonalConnectionDelegation[];
+}>;
+/** Shared workspace accounts plus the entitled owner's own active accounts. */
+export declare function visibleMcpAccountConnections(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    source: Exclude<PersonalConnectionDelegationSource, {
+        kind: "turn";
+    }>;
+}): Promise<ConnectionMetadata[]>;
+/**
+ * Every account a fresh, selection-free freeze would bind for the generic MCP
+ * routes among `tools`: exactly what `freezeConnectionAccounts` binds when no
+ * account is chosen. The same entitlement contract applies: `source` is a
+ * grant-derived or frozen-owner subject, never a looked-up one. Read-only; it
+ * never persists a delegation.
+ */
+export declare function availableMcpAccountBindings(input: {
     db: Database;
+    accountId: string;
     workspaceId: string;
     settings: Pick<Settings, "mcpServers">;
     tools: ToolRef[];
+    source: Exclude<PersonalConnectionDelegationSource, {
+        kind: "turn";
+    }>;
+    /** Result of `visibleMcpAccountConnections` for the same source, when already read. */
+    connections?: ConnectionMetadata[];
+}): Promise<McpConnectionAccountBinding[]>;
+export declare function freezePersonalConnectionDelegations(input: {
+    db: Database;
+    workspaceId: string;
+    settings: Pick<Settings, "mcpServers"> & Partial<Pick<Settings, "githubPersonalOauthEnabled">>;
+    tools: ToolRef[];
+    resources?: ResourceRef[];
     source: PersonalConnectionDelegationSource;
+    authoritySelections?: McpConnectionAccountSelection[];
+    /** Internal durable schedule snapshot, not a default account selector. */
+    authoritySelectionsFrozen?: boolean;
+    /** Exact first-party export tool + permission gate, not broad opengeni attachment. */
+    googleDrivePublicationEnabled?: boolean;
+    /** Exact first-party Atlassian tool + permission gate. */
+    atlassianEnabled?: boolean;
+    /** Exact target for successor-mode projection (`session` never crosses it). */
+    targetSessionId?: string;
 }): Promise<McpPersonalConnectionDelegation[]>;
-export {};