@opengeni/core 3.0.1 → 3.1.2

package/dist/domain/agent-config-resolution.d.ts

@@ -0,0 +1,49 @@
+import { type Settings } from "@opengeni/config";
+import { type AgentConfigCreator, type AgentConfigParent, type AgentConfigRequest, type FirstPartyMcpToolName, type ResolvedAgentCapabilities, type ResolvedAgentConfig, type Session, type SessionToolPolicy, type ToolRef } from "@opengeni/contracts";
+/**
+ * Run an agent-config resolution step and surface its typed failure as a 422
+ * whose `cause` keeps the `AgentConfigError` (the API renders its code as
+ * `details.code`; MCP and Slack keep the plain message).
+ */
+export declare function withAgentConfigHttpErrors<T>(fn: () => T): T;
+/** The current effective capabilities of a null-config session (the conversion/child ceiling). */
+export declare function legacySessionAgentCapabilities(settings: Settings, session: Pick<Session, "firstPartyMcpTools" | "tools" | "toolPolicy">, workspaceSettings: unknown, 
+/** The workspace's current omitted-tools default server ids, when known. */
+defaultServerIds?: Iterable<string>): ResolvedAgentCapabilities;
+/** A parent session as a resolution input: its frozen config, or its legacy ceiling. */
+export declare function agentConfigParentFor(settings: Settings, parent: Session, workspaceSettings: unknown): AgentConfigParent;
+/**
+ * Resolve the frozen agent configuration for a new session. Every creator
+ * calls this: `createSessionForRequest` (public API, MCP `session_create`,
+ * Slack, drafts), automations, and the scheduled worker. Returns `config:
+ * null` for exact legacy behavior.
+ */
+export declare function resolveSessionAgentConfigForCreate(input: {
+    settings: Settings;
+    creator: AgentConfigCreator;
+    request: AgentConfigRequest | undefined;
+    instructions: string | undefined;
+    workspaceSettings: unknown;
+    parent: Session | null;
+    goal: boolean;
+}): {
+    config: ResolvedAgentConfig | null;
+    instructions: string | undefined;
+};
+/**
+ * Write a resolved configuration through to the legacy columns the runtime
+ * reads today. `null` returns the inputs unchanged; `"all"` also does.
+ */
+export declare function applySessionAgentConfigWriteThrough(input: {
+    config: ResolvedAgentConfig | null;
+    firstPartyMcpTools: FirstPartyMcpToolName[];
+    explicitFirstPartyMcpTools?: readonly FirstPartyMcpToolName[] | undefined;
+    tools: ToolRef[];
+    toolPolicy: SessionToolPolicy;
+    productServerIds: Iterable<string>;
+    explicitServerIds?: Iterable<string> | undefined;
+}): {
+    firstPartyMcpTools: FirstPartyMcpToolName[];
+    tools: ToolRef[];
+    toolPolicy: SessionToolPolicy;
+};

package/dist/domain/automations.d.ts

@@ -1,4 +1,9 @@
-import { AutomationAcceptedExecution, AutomationNormalizedEvent, AutomationSessionTemplate, type AutomationAdapterId, type AutomationSource, type AutomationTrigger } from "@opengeni/contracts";
+import { AutomationAcceptedExecution, AutomationNormalizedEvent, AutomationSessionTemplate, type AccessGrant, type Permission, type AutomationAdapterId, type AutomationSource, type AutomationTrigger } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+/** Canonical authenticated grant or exact server-owned originating policy only. */
+export declare function automationCredentialRestrictionForGrant(db: Database, grant: AccessGrant): Promise<AutomationSessionTemplate["credentialRestriction"]>;
+/** Explicit delegated scopes must stay within the frozen setup ceiling. */
+export declare function requireAutomationCredentialRestrictionPermissions(restriction: AutomationSessionTemplate["credentialRestriction"], permissions: readonly Permission[]): void;
 export type AutomationAdapterRenderResult = {
     initialMessage: string;
     sessionTemplate: AutomationSessionTemplate;
@@ -48,4 +53,6 @@ export declare function buildAutomationAcceptedExecution(input: {
     eventId: string;
     event: AutomationNormalizedEvent;
     render: AutomationAdapterRenderResult;
+    /** Trusted caller restriction from the immutable stored event, not adapter JSON. */
+    credentialRestriction?: "developer_setup";
 }): AutomationAcceptedExecution;

package/dist/domain/capabilities.d.ts

@@ -1,13 +1,16 @@
 import { type Settings } from "@opengeni/config";
-import { CapabilityCatalogItem, type AccessGrant, type CapabilityCatalogResponse, type CapabilityInstallation, type CreateCapabilityCatalogItemRequest, type EnableCapabilityRequest, type McpPersonalConnectionDelegation } from "@opengeni/contracts";
-import { type Database, type ApiIntegrationRuntime, type EnabledMcpCapabilityServer } from "@opengeni/db";
+import { CapabilityCatalogItem, OPENGENI_BROWSER_EXTENSION_URL, type AccessGrant, type CapabilityCatalogResponse, type CapabilityInstallation, type CreateCapabilityCatalogItemRequest, type EnableCapabilityRequest, type McpPersonalConnectionDelegation } from "@opengeni/contracts";
+import { type SubscriptionCoreCodexAppsRequestAuth, type CodexCutoverDisposition, type Database, type ApiIntegrationRuntime, type EnabledMcpCapabilityServer } from "@opengeni/db";
 declare const officialMcpRegistryUrl = "https://registry.modelcontextprotocol.io";
 export declare function buildCapabilityCatalog(input: {
     db: Database;
     workspaceId: string;
     settings: Settings;
     subjectId?: string | null;
+    /** The workspace's organization, when the caller knows it (skips a lookup). */
+    accountId?: string;
 }): Promise<CapabilityCatalogResponse>;
+export declare function applyOperatorOAuthClientRequirement(item: CapabilityCatalogItem, configured: (issuer: string) => boolean): CapabilityCatalogItem;
 export declare function createCatalogItem(input: {
     db: Database;
     accountId: string;
@@ -23,6 +26,14 @@ type EnableCapabilityInput = {
     capabilityId: string;
     payload: EnableCapabilityRequest;
     probeMcpServer?: McpCapabilityProbe;
+    /** Server-owned receipt from a just-verified native Connect credential.
+     * Never projected into EnableCapabilityRequest or accepted from a client. */
+    verifiedConnection?: {
+        id: string;
+        version: number;
+        endpointUrl: string;
+        connectivity: Record<string, unknown>;
+    };
 };
 export declare function enableCapability(input: EnableCapabilityInput): Promise<CapabilityInstallation>;
 /** Probe outside a durable Connect commit; persist the exact prepared settings
@@ -33,7 +44,7 @@ export declare function prepareCapabilityEnable(input: EnableCapabilityInput): P
         accountId: string;
         workspaceId: string;
         capabilityId: string;
-        kind: "api" | "mcp" | "pack" | "plugin" | "skill";
+        kind: "api" | "mcp" | "plugin" | "skill";
         status: "active" | "disabled";
         config: Record<string, unknown>;
         metadata: Record<string, unknown>;
@@ -47,12 +58,13 @@ export type McpCapabilityProbeInput = {
     url: string;
     timeoutMs: number;
     headers?: Record<string, string>;
+    settings?: Settings;
 };
 export type McpCapabilityProbeResult = {
     toolCount: number;
 };
 export type McpCapabilityProbe = (input: McpCapabilityProbeInput) => Promise<McpCapabilityProbeResult>;
-export declare function validateMcpCapabilityConnection(item: CapabilityCatalogItem, probe?: McpCapabilityProbe, headers?: Record<string, string>): Promise<Record<string, unknown>>;
+export declare function validateMcpCapabilityConnection(item: CapabilityCatalogItem, probe?: McpCapabilityProbe, headers?: Record<string, string>, settings?: Settings): Promise<Record<string, unknown>>;
 export declare function disableCapability(input: {
     db: Database;
     accountId: string;
@@ -64,12 +76,68 @@ export declare function settingsWithEnabledCapabilityMcpServers(db: Database, wo
     subjectId?: string;
     personalConnectionDelegations?: readonly McpPersonalConnectionDelegation[];
     onResolvedApiIntegrations?: (integrations: readonly ApiIntegrationRuntime[]) => void;
+    /** Every enabled capability server read, before static-id shadowing. */
+    onResolvedCapabilityServers?: (servers: readonly EnabledMcpCapabilityServer[]) => void;
+    /**
+     * The Codex Apps designation the caller already resolves (a claim reads
+     * its cutover once), or what it knows for resolving it here.
+     */
+    codexApps?: Promise<CodexAppsDesignationForRun | null> | CodexAppsRunContext;
+    /**
+     * `db` is one bounded transaction: run the reads one after another, since
+     * its RLS scopes must not overlap.
+     */
+    oneReadAtATime?: boolean;
+}): Promise<Settings>;
+/**
+ * `settingsWithEnabledCapabilityMcpServers` for a live target fence: only the
+ * rows that can produce `serverIds`. That is the capability installations that
+ * produced them at preparation plus any catalog item explicitly claiming one of
+ * those ids (shadowing), integrations with exactly those runtime keys (read
+ * with the same subject visibility), and the Codex designation only when Codex
+ * Apps itself is a target. Static servers come from `settings`, unchanged.
+ * Restricted to `serverIds`, the result equals the complete projection.
+ */
+export declare function settingsWithEnabledCapabilityMcpServersForTargets(db: Database, workspaceId: string, settings: Settings, options: {
+    subjectId: string;
+    accountId: string;
+    serverIds: readonly string[];
+    capabilityIds: readonly string[];
+    onResolvedApiIntegrations?: (integrations: readonly ApiIntegrationRuntime[]) => void;
+    /** Checked between reads: a stopped caller starts no further read. */
+    signal?: AbortSignal;
 }): Promise<Settings>;
 export declare function apiIntegrationsMatchingDelegations(integrations: readonly ApiIntegrationRuntime[], delegations: readonly McpPersonalConnectionDelegation[]): ApiIntegrationRuntime[];
 export declare function settingsWithApiIntegrationServers(settings: Settings, integrations: readonly ApiIntegrationRuntime[]): Settings;
 /**
- * Resolve executable Apps authority. The connector must remain active and its
- * exact owner must still hold workspace connection-management permission.
+ * The workspace's executable Codex Apps designation. Without a Codex cutover
+ * row this is the legacy designation (`resolveCodexAppsCredentialIdForRun`).
+ * With an enabled cutover it is the core designation, which the database
+ * rechecks (designated shared Codex connection, still in the workspace's
+ * scope, active). A disabled cutover row designates nothing and reads no
+ * legacy Codex table.
+ */
+export type CodexAppsDesignationForRun = {
+    source: "core";
+    accountId: string;
+    connectionId: string;
+};
+/**
+ * What the caller already knows, so the resolver does not read it again: the
+ * workspace's organization (skips the workspace lookup) and the organization's
+ * Codex cutover disposition (skips the cutover read; a claim has read it).
+ */
+export type CodexAppsRunContext = {
+    accountId?: string;
+    disposition?: CodexCutoverDisposition | Promise<CodexCutoverDisposition>;
+};
+export declare function resolveCodexAppsDesignationForRun(db: Database, workspaceId: string, known?: CodexAppsRunContext): Promise<CodexAppsDesignationForRun | null>;
+/** Runtime Apps authentication for whichever designation `resolveCodexAppsDesignationForRun` returned. */
+export declare function codexAppsRequestAuthForDesignation(db: Database, settings: Settings, workspaceId: string, designation: CodexAppsDesignationForRun): SubscriptionCoreCodexAppsRequestAuth;
+/**
+ * Resolve the legacy executable Apps authority. Organizations with a Codex
+ * cutover row (enabled or disabled) have none here: their designation lives
+ * on the core (`resolveCodexAppsDesignationForRun`).
  */
 export declare function resolveCodexAppsCredentialIdForRun(db: Database, workspaceId: string): Promise<string | null>;
 /**
@@ -101,17 +169,53 @@ export declare function codexAppsCatalogItem(available: boolean): CapabilityCata
  * recommend the owning product flow without manufacturing an enabled catalog
  * row for GitHub resources, Documents, schedules, or other platform features.
  */
-export declare function nativeConnectionCapabilityRecommendations(): CapabilityCatalogItem[];
-export declare function applyCapabilityEnablement(item: CapabilityCatalogItem, installation: CapabilityInstallation | undefined, activePackIds: Set<string>): CapabilityCatalogItem;
+/** The in-chat card id for connecting a person's own computer. */
+export declare const CONNECTED_MACHINE_CAPABILITY_ID = "api:connected-machine";
+export { OPENGENI_BROWSER_EXTENSION_URL };
+export declare function nativeConnectionCapabilityRecommendations(options?: {
+    connectedMachines?: boolean;
+}): CapabilityCatalogItem[];
+export declare function applyCapabilityEnablement(item: CapabilityCatalogItem, installation: CapabilityInstallation | undefined): CapabilityCatalogItem;
 export type CapabilityCatalogSearchMatch = {
     item: CapabilityCatalogItem;
     score: number;
     matchedOn: Array<"name" | "provider" | "tag" | "category" | "description" | "id">;
+    /**
+     * True when the item matched only through the typo-tolerant tier (an edit
+     * distance hit), never through an exact, prefix, or substring hit.
+     */
+    approximate: boolean;
+};
+export type CapabilityCatalogSuggestion = {
+    item: CapabilityCatalogItem;
+    /** Name similarity to the query in [0, 1]; 1 means identical once normalized. */
+    similarity: number;
 };
 /**
  * Deterministically rank the already-merged workspace catalog for an agent.
  * The caller still owns live authorization checks (GitHub binding, OAuth row,
  * and so on); this function searches metadata only and never probes a provider
  * or exposes credential/setup prose to the model.
+ *
+ * Exact word, prefix, and substring hits rank first. A typo-tolerant tier
+ * (bounded Damerau-Levenshtein on name, provider-domain, and tag words, plus
+ * the space-stripped name against the space-stripped query) contributes a
+ * smaller score so a one-letter spelling difference still finds the entry.
  */
 export declare function searchCapabilityCatalogItems(items: readonly CapabilityCatalogItem[], query: string, limit?: number): CapabilityCatalogSearchMatch[];
+/**
+ * Closest catalog names for a query that matched nothing. A miss must never
+ * read as "this integration does not exist" while the workspace has entries,
+ * so callers surface these as explicitly labelled suggestions. An empty
+ * (all-punctuation) query returns the first entries by name for browsing.
+ */
+export declare function suggestCapabilityCatalogItems(items: readonly CapabilityCatalogItem[], query: string, limit?: number): CapabilityCatalogSuggestion[];
+/**
+ * The vendor domain search may match. A stored providerDomain wins. Workspace
+ * and operator entries (manual, configured, built-in) without one fall back to
+ * the registrable domain of their endpoint (api.wisprflow.ai -> wisprflow.ai).
+ * Registry rows do not: their endpoints may sit on a third-party host. This is
+ * a search-only projection and never changes the stored item or any
+ * connection/authority matching.
+ */
+export declare function capabilityCatalogSearchProviderDomain(item: CapabilityCatalogItem): string | null;

package/dist/domain/connection-account-selection-error.d.ts

@@ -0,0 +1,8 @@
+import { HTTPException } from "hono/http-exception";
+import { ConnectionAccountSelectionDiagnostic } from "@opengeni/contracts";
+/** An account choice needs attention; retrying the same work cannot fix it. */
+export declare class ConnectionAccountSelectionError extends HTTPException {
+    name: string;
+    readonly diagnostic: ConnectionAccountSelectionDiagnostic;
+    constructor(message: string, diagnostic?: ConnectionAccountSelectionDiagnostic);
+}

package/dist/domain/connector-tool-permissions.d.ts

@@ -0,0 +1,62 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Settings } from "@opengeni/config";
+import type { AccessGrant, ConnectorToolPermissionsResponse, UpdateConnectorToolPermissionsRequest, ConnectionMetadata, McpServerConnectionRef, SessionMcpToolPermissionsQuery, SessionMcpToolPermissionsResponse, UpdateSessionMcpToolPermissionsRequest } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+type Input = {
+    db: Database;
+    settings: Settings;
+    workspaceId: string;
+    grant: AccessGrant;
+    capabilityId: string;
+    personalOwnerVerified: boolean;
+    connectionId?: string;
+    instanceKey?: string;
+};
+type ListedTool = {
+    name: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    annotations?: {
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        title?: string | undefined;
+    } | undefined;
+    _meta?: Record<string, unknown> | undefined;
+};
+export declare function connectorToolGroup(tool: ListedTool): "read" | "write" | "other";
+/** A selector can supply discovery credentials only when one visible account
+ * matches. Never apply one account's approval choices to an arbitrary sibling. */
+export declare function unpinnedConnectorToolPermissionAccount<T extends ConnectionMetadata>(ref: McpServerConnectionRef, visible: T[], subjectId: string): T | null;
+export declare function connectorToolPermissionReference(ref: McpServerConnectionRef, connectionId: string): McpServerConnectionRef;
+/** Use the same adapter-owned identities as execution for reviewed local catalogs. */
+export declare function reviewedConnectorToolCatalog(server: Pick<Settings["mcpServers"][number], "url" | "connectionRef" | "allowedTools">, grantedScopes: readonly string[], deployment: Pick<Settings, "gmailWatchTopicName">): ListedTool[] | null;
+/** Collect discovery pages without changing the caller's connection or authority. */
+export declare function collectConnectorToolPages(client: Pick<Client, "listTools">, deadline: AbortSignal): Promise<ListedTool[]>;
+export declare function getConnectorToolPermissions(input: Input): Promise<ConnectorToolPermissionsResponse>;
+export declare function updateConnectorToolPermissions(input: Input & {
+    payload: UpdateConnectorToolPermissionsRequest;
+}): Promise<void>;
+/**
+ * Same secret-free identity the runtime derives for a credential-free session MCP server.
+ * Keyed to the exact URL: a different URL string gets different rules.
+ */
+export declare function sessionMcpToolPermissionConnectionId(serverId: string, url: string): string;
+type SessionMcpInput = {
+    db: Database;
+    workspaceId: string;
+    grant: AccessGrant;
+};
+/**
+ * Saved Allow/Ask/Block choices for a host-attached session MCP server. The
+ * host owns the tool catalog; Opengeni owns the rules and enforces them on the
+ * next attempt of every session in this workspace that attaches the same
+ * server id and exact URL.
+ */
+export declare function getSessionMcpToolPermissions(input: SessionMcpInput & {
+    query: SessionMcpToolPermissionsQuery;
+}): Promise<SessionMcpToolPermissionsResponse>;
+/** Agents and service principals cannot change the permissions that bound them. */
+export declare function updateSessionMcpToolPermissions(input: SessionMcpInput & {
+    payload: UpdateSessionMcpToolPermissionsRequest;
+}): Promise<void>;
+export {};

package/dist/domain/direct-model-provider.d.ts

@@ -0,0 +1,3 @@
+import { DirectModelProviderMetadata } from "@opengeni/contracts";
+/** Verify the customer's exact route without persisting their key or test response. */
+export declare function verifyDirectModelAccess(input: DirectModelProviderMetadata, apiKey: string, fetchImpl?: typeof fetch): Promise<void>;

package/dist/domain/editable-artifacts/agent-application.d.ts

@@ -1,5 +1,5 @@
 import { type DocumentArtifactCommand, type DocumentArtifactQuery, type PresentationArtifactCommand, type PresentationArtifactQuery, type SpreadsheetArtifactCommand, type SpreadsheetArtifactKernelQuery } from "@opengeni/contracts/editable-artifacts";
-import type { EditableArtifactDurableExportService, EditableArtifactMaterializationFormat, EditableArtifactMaterializationJob } from "./durable-export.js";
+import { type EditableArtifactDurableExportService, type EditableArtifactMaterializationFormat, type EditableArtifactMaterializationJob } from "./durable-export.js";
 import type { EditableArtifactService } from "./service.js";
 import { type EditableArtifact, type EditableArtifactActor, type EditableArtifactClientTransactionId, type EditableArtifactId, type EditableArtifactModality, type EditableArtifactOriginalImport, type EditableArtifactScope, type ImportEditableArtifactRequest } from "./types.js";
 import type { EditableArtifactKernelState } from "./ports.js";
@@ -30,6 +30,7 @@ export type EditableArtifactAgentContext = Readonly<{
 }>;
 export type EditableArtifactAgentMetadata = Readonly<{
     id: string;
+    artifactReference: string;
     modality: EditableArtifactModality;
     title: string;
     lifecycle: EditableArtifact["lifecycle"];
@@ -116,6 +117,12 @@ 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;
 }>;
@@ -125,6 +132,7 @@ export type EditableArtifactAgentApplicationDependencies = Readonly<{
  */
 export declare class EditableArtifactAgentApplication {
     private readonly dependencies;
+    describeExportFormats(): string;
     constructor(dependencies: EditableArtifactAgentApplicationDependencies);
     list(input: EditableArtifactAgentContext & Readonly<{
         limit?: number;
@@ -151,6 +159,7 @@ export declare class EditableArtifactAgentApplication {
     }>): Promise<Readonly<{
         artifact: EditableArtifactAgentMetadata;
         projection: unknown;
+        inspectionReceiptId?: string;
     }>>;
     apply(input: EditableArtifactAgentContext & Readonly<{
         artifactId: EditableArtifactId;

package/dist/domain/editable-artifacts/durable-export.d.ts

@@ -4,6 +4,17 @@ import { type EditableArtifactActor, type EditableArtifactCausalFrontier, type E
 export declare const EDITABLE_ARTIFACT_EXPORT_MAX_DOWNLOAD_BYTES: number;
 export declare const EDITABLE_ARTIFACT_EXPORT_MAX_OPTIONS_BYTES: number;
 export type EditableArtifactMaterializationFormat = "xlsx" | "pptx" | "docx" | "pdf" | "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 declare const EDITABLE_ARTIFACT_EXPORT_FORMATS: Readonly<Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>>;
+/** Human/agent-readable summary of {@link EDITABLE_ARTIFACT_EXPORT_FORMATS}. */
+export declare function describeEditableArtifactExportFormats(): string;
+export declare function describeConfiguredExportFormats(configuredFormats: Readonly<Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>>): string;
+/** Typed refusal that tells the caller which formats do exist. */
+export declare function unsupportedEditableArtifactExport(modality: EditableArtifactModality, format: string, formats?: Readonly<Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>>): EditableArtifactDurableExportError;
 export type EditableArtifactMaterializationMimeType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/pdf" | "image/png" | "image/webp";
 export type EditableArtifactPinnedVersion = Readonly<{
     scope: EditableArtifactScope;
@@ -58,6 +69,9 @@ 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;
         format: EditableArtifactMaterializationFormat;
@@ -165,7 +179,7 @@ export type EditableArtifactMaterializationDownload = Readonly<{
 export type EditableArtifactDurableExportErrorCode = "invalid_request" | "not_found" | "forbidden" | "conflict" | "unsupported_format" | "not_ready" | "unavailable";
 export declare class EditableArtifactDurableExportError extends Error {
     readonly code: EditableArtifactDurableExportErrorCode;
-    constructor(code: EditableArtifactDurableExportErrorCode);
+    constructor(code: EditableArtifactDurableExportErrorCode, message?: string);
 }
 export type EditableArtifactDurableExportServiceDependencies = Readonly<{
     authorization: EditableArtifactAuthorizationPort;
@@ -178,6 +192,13 @@ export type EditableArtifactDurableExportServiceDependencies = Readonly<{
 export declare class EditableArtifactDurableExportService {
     private readonly dependencies;
     constructor(dependencies: EditableArtifactDurableExportServiceDependencies);
+    describeFormats(): string;
+    /** Read-only exact preflight: no snapshot, ID allocation, or store write. */
+    preflight(input: {
+        modality: EditableArtifactModality;
+        format: EditableArtifactMaterializationFormat;
+        options?: Readonly<Record<string, unknown>>;
+    }): Promise<EditableArtifactMaterializationProfile>;
     pinVersion(input: DurableExportContext & {
         idempotencyKey: string;
         name: string;

package/dist/domain/editable-artifacts/ports.d.ts

@@ -1,3 +1,4 @@
+import type { Database } from "@opengeni/db";
 import type { EditableArtifact, EditableArtifactActor, EditableArtifactCausalFrontier, EditableArtifactId, EditableArtifactLiveOutboxRecord, EditableArtifactMutationIntent, EditableArtifactOperationId, EditableArtifactOperationRecord, EditableArtifactOriginOperation, EditableArtifactOriginalImport, EditableArtifactOutboxId, EditableArtifactOutboxRetryFailureCode, EditableArtifactOutboxDeadLetterFailureCode, EditableArtifactPermission, EditableArtifactReceipt, EditableArtifactScope, EditableArtifactSequenceCheckpoint, EditableArtifactSnapshotId, EditableArtifactSnapshotMetadata, EditableArtifactStableId, EditableArtifactStateHash, EditableArtifactTransactionId, EditableArtifactClientTransactionId, EditableArtifactCommittedTransactionRecord, EditableArtifactModality, EditableArtifactRequestHash, EditableArtifactSerialized, EditableArtifactSerializedCommittedTransactionRecord, EditableArtifactSerializedSnapshotMetadata, EditableArtifactSpreadsheet, EditableArtifactSpreadsheetCommittedTransactionRecord, EditableArtifactSpreadsheetSnapshotMetadata, CreateEditableArtifactResult, PublishEditableArtifactSnapshotRequest, ValidatedEditableArtifactMutationIntent } from "./types.js";
 export type EditableArtifactAuthorizationRequest = Readonly<{
     scope: EditableArtifactScope;
@@ -202,6 +203,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<{
     operationId: EditableArtifactOperationId;
@@ -232,6 +235,12 @@ export type ExpectedEditableArtifactPredecessor = Readonly<{
     replicaId: EditableArtifactReceipt["replicaId"];
     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<{
     scope: EditableArtifactScope;
     artifactId: EditableArtifactId;
@@ -239,6 +248,7 @@ export type TryCommitAppliedEditableArtifactTransactionRequest = CommitAppliedEd
     expectedAuthorizationRevision: number;
     /** Rechecked by durable production stores in the commit transaction. */
     authorizationActor: EditableArtifactActor;
+    authorizeCommit?: EditableArtifactCommitAuthorizer;
     actorKey: string;
     clientTransactionId: EditableArtifactReceipt["clientTransactionId"];
     requestHash: EditableArtifactReceipt["requestHash"];

package/dist/domain/editable-artifacts/service.d.ts

@@ -1,4 +1,4 @@
-import type { AuthoritativeEditableArtifactKernelPort, EditableArtifactAuthorizationPort, EditableArtifactClockPort, EditableArtifactCompactionPort, EditableArtifactGenesisPort, EditableArtifactKernelState, EditableArtifactMutationIntentCodecPort, EditableArtifactSnapshotVerifierPort, EditableArtifactStableIdFactoryPort, EditableArtifactStorePort } from "./ports.js";
+import type { EditableArtifactCommitAuthorizer, AuthoritativeEditableArtifactKernelPort, EditableArtifactAuthorizationPort, EditableArtifactClockPort, EditableArtifactCompactionPort, EditableArtifactGenesisPort, EditableArtifactKernelState, EditableArtifactMutationIntentCodecPort, EditableArtifactSnapshotVerifierPort, EditableArtifactStableIdFactoryPort, EditableArtifactStorePort } from "./ports.js";
 import { type ApplyEditableArtifactTransactionRequest, type ApplyEditableArtifactTransactionResult, type CreateEditableArtifactRequest, type CreateEditableArtifactResult, type ImportEditableArtifactRequest, type EditableArtifact, type EditableArtifactActor, type EditableArtifactClientTransactionId, type EditableArtifactReceipt, type EditableArtifactScope, type EditableArtifactSnapshotMetadata, type PublishEditableArtifactSnapshotRequest } from "./types.js";
 export declare const EDITABLE_ARTIFACT_MAX_OPERATIONS_PER_TRANSACTION = 4096;
 export declare const EDITABLE_ARTIFACT_MAX_UNDO_TARGETS_PER_TRANSACTION: number;
@@ -80,6 +80,8 @@ export declare class EditableArtifactService {
         artifactId: EditableArtifact["id"];
         actor: EditableArtifactActor;
         request: ApplyEditableArtifactTransactionRequest;
+        /** Authenticated backend authority, not part of the client mutation envelope. */
+        authorizeCommit?: EditableArtifactCommitAuthorizer;
     }): Promise<ApplyEditableArtifactTransactionResult>;
     private applyTransactionOptimistically;
     compactCurrentHead(input: {

package/dist/domain/editable-artifacts/types.d.ts

@@ -2,7 +2,7 @@ import type { EditableArtifactMutationIntent as ContractEditableArtifactMutation
 /**
  * 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/dist/domain/encryption-key.d.ts

@@ -0,0 +1,12 @@
+import { 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 declare function requireEnvironmentEncryption(settings: Settings): Uint8Array;
+/**
+ * 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 declare function variableSetsRemovedError(field: string): HTTPException;

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,14 +1,19 @@
 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";
+export type WorkspaceInsightsFilterField = "provider" | "model" | "rootSessionId" | "sessionId";
 export declare class WorkspaceInsightsFilterValidationError extends Error {
     readonly field: WorkspaceInsightsFilterField;
     readonly maxUtf8Bytes: number;
-    constructor(field: WorkspaceInsightsFilterField, 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 = {
@@ -16,6 +21,14 @@ export type GetWorkspaceInsightsInput = {
     range: InsightsRange;
     provider?: string | null;
     model?: string | null;
+    rootSessionId?: string | null;
+    sessionId?: string | null;
+    /**
+     * Resolves the reading person, only once the rollup runs. The per-schedule
+     * list leaves out other people's Only me schedules; their usage stays in the
+     * per-person private totals.
+     */
+    viewerSubjectId?: () => Promise<string | null>;
     now?: Date;
 };
 export declare function insightsSessionLabel(input: {
@@ -23,4 +36,9 @@ export declare function insightsSessionLabel(input: {
     title: string | null;
     depth?: number | null;
 }): string;
-export declare function getWorkspaceInsights(db: Database, settings: Settings, input: GetWorkspaceInsightsInput): Promise<WorkspaceInsightsResponse>;
+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

@@ -1,7 +1,7 @@
 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): Promise<{
+export declare function prepareKnowledgeFile(deps: Pick<ApiRouteDeps, "db" | "objectStorage" | "getDocumentServices">, context: KnowledgeContext, fileId: string, purpose?: "evidence" | "reference"): Promise<{
     status: "retained";
     fileId: string;
     filename: string;

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 {};