@memberjunction/server 6.2.0-edge.4 → 6.2.0-edge.6

package/src/integration/CustomColumnPromoter.ts

@@ -300,7 +300,12 @@ export class IntegrationCustomColumnPromoter {
         // step with the database.
         let batchResults: RSUPipelineResult[] = [];
         if (batchInputs.length > 0) {
-            const batch = await RuntimeSchemaManager.Instance.RunPipelineBatch(batchInputs);
+            // Retrying variant. This runs UNATTENDED, mid-sync, with no operator watching: a
+            // transient ExecuteMigration / RunCodeGen / CompileTypeScript / RestartMJAPI failure
+            // drops the whole promotion, and the columns simply stay in overflow until something
+            // triggers a promotion again. The wrapper replays only those four steps and only while
+            // nothing in the batch was applied, so a partially-applied batch is still returned as-is.
+            const batch = await RuntimeSchemaManager.Instance.RunPipelineBatchWithRetry(batchInputs);
             batchResults = batch.Results ?? [];
             // M3: make the freshly-created EntityFields + regenerated sprocs visible in-process
             // ONCE for the whole batch. CRITICAL: the spread below builds sproc calls from this

package/src/logging/variablesLoggingMiddleware.ts

@@ -1,7 +1,7 @@
-import type { MiddlewareFn } from 'type-graphql';
+import type { MiddlewareFn, ResolverData } from 'type-graphql';
 import { getMetadataStorage } from 'type-graphql';
-import { getNamedType } from 'graphql';
-import type { GraphQLArgument } from 'graphql';
+import { defaultFieldResolver, getNamedType } from 'graphql';
+import type { GraphQLArgument, GraphQLField, GraphQLObjectType, GraphQLSchema } from 'graphql';
 import { configInfo } from '../config.js';
 import type { AppContext } from '../types.js';
 import { RedactArg } from './secretRedactor.js';
@@ -191,6 +191,62 @@ export const VariablesLoggingMiddleware: MiddlewareFn<AppContext> = async (actio
 /** @deprecated Use {@link VariablesLoggingMiddleware}. */
 export const variablesLoggingMiddleware: MiddlewareFn<AppContext> = VariablesLoggingMiddleware;
 
+/**
+ * Attaches {@link VariablesLoggingMiddleware} ONLY to root `Query`, `Mutation`, and `Subscription`
+ * fields on the compiled GraphQLSchema instead of registering it via TypeGraphQL `globalMiddlewares`.
+ *
+ * Registering a global middleware in TypeGraphQL wraps every scalar and child field resolver across
+ * all 300+ `@ObjectType` entities in an async middleware chain, allocating $O(\text{Rows} \times \text{Fields})$
+ * Promises per query even when `logVariables` is false or `info.path.prev !== undefined`.
+ * Wrapping only the root operation fields reduces middleware invocations from ~15,000 per 500-row
+ * `RunView` response down to 1.
+ */
+export function ApplyRootVariablesLoggingMiddleware(
+  schema: GraphQLSchema,
+  middleware: MiddlewareFn<AppContext> = VariablesLoggingMiddleware
+): GraphQLSchema {
+  const rootTypes: Array<GraphQLObjectType | null | undefined> = [
+    schema.getQueryType(),
+    schema.getMutationType(),
+    schema.getSubscriptionType(),
+  ];
+
+  for (const rootType of rootTypes) {
+    if (!rootType) continue;
+    const fields = rootType.getFields();
+    for (const field of Object.values(fields) as Array<GraphQLField<unknown, AppContext>>) {
+      if (field.resolve) {
+        const originalResolve = field.resolve;
+        field.resolve = (root, args, context, info) => {
+          const action: ResolverData<AppContext> = {
+            root,
+            args: args as Record<string, unknown>,
+            context,
+            info,
+          };
+          return middleware(action, async () => originalResolve(root, args, context, info));
+        };
+      }
+      if (field.subscribe) {
+        const originalSubscribe = field.subscribe;
+        field.subscribe = (root, args, context, info) => {
+          const action: ResolverData<AppContext> = {
+            root,
+            args: args as Record<string, unknown>,
+            context,
+            info,
+          };
+          return middleware(action, async () =>
+            originalSubscribe ? originalSubscribe(root, args, context, info) : defaultFieldResolver(root, args, context, info)
+          );
+        };
+      }
+    }
+  }
+
+  return schema;
+}
+
 /**
  * Heuristic: an arg is "custom" (i.e. needs `@NoLog` discipline because metadata can't redact it)
  * when its GraphQL input type is not a known `Create<X>Input` / `Update<X>Input` for an entity

package/src/multiTenancy/index.ts

@@ -9,7 +9,9 @@
 
 import type { RequestHandler } from 'express';
 import type { PreRunViewHook, PreSaveHook } from '@memberjunction/core';
-import { Metadata, type UserInfo, type TenantContext } from '@memberjunction/core';
+import { DatabaseProviderBase, Metadata, type UserInfo, type TenantContext } from '@memberjunction/core';
+import { PostgreSQLDialect, SQLServerDialect, type SQLParserDialect } from '@memberjunction/sql-dialect';
+import { IsBalancedSQLFragment } from '@memberjunction/sql-parser';
 import type { MultiTenancyConfig } from '../config.js';
 import type { UserPayload } from '../types.js';
 import { CloneUserForSessionContext } from '../auth/sessionUserClone.js';
@@ -161,6 +163,25 @@ function isAdminUser(user: UserInfo, adminRoles: string[]): boolean {
   );
 }
 
+/** Dialects to read an ExtraFilter with when the active provider's dialect cannot be resolved. */
+const ALL_FILTER_DIALECTS: SQLParserDialect[] = [new SQLServerDialect(), new PostgreSQLDialect()];
+
+/**
+ * Throws unless the caller's ExtraFilter stays inside the parentheses the tenant predicate is
+ * ANDed after. A filter such as `1=1) OR (1=1` would close them early and leave the tenant
+ * predicate on one side of an OR the caller controls.
+ */
+function assertExtraFilterBalanced(extraFilter: string): void {
+  const provider = Metadata.Provider; // global-provider-ok: same rationale as isEntityScoped above — hooks carry no per-request provider
+  const dialects = provider instanceof DatabaseProviderBase ? [provider.Dialect] : ALL_FILTER_DIALECTS;
+  for (const dialect of dialects) {
+    const check = IsBalancedSQLFragment(extraFilter, dialect);
+    if (!check.IsBalanced) {
+      throw new Error(`[MultiTenancy] Invalid ExtraFilter: ${check.Reason}`);
+    }
+  }
+}
+
 /**
  * Creates a PreRunViewHook that auto-injects tenant WHERE clauses
  * into RunView queries for scoped entities.
@@ -206,7 +227,8 @@ export function CreateTenantPreRunViewHook(config: MultiTenancyConfig): PreRunVi
 
     // Inject the tenant filter
     if (params.ExtraFilter && typeof params.ExtraFilter === 'string' && params.ExtraFilter.trim().length > 0) {
-      params.ExtraFilter = `(${params.ExtraFilter}) AND ${tenantFilter}`;
+      assertExtraFilterBalanced(params.ExtraFilter);
+      params.ExtraFilter = `(${params.ExtraFilter}) AND (${tenantFilter})`;
     } else {
       params.ExtraFilter = tenantFilter;
     }

package/src/realtimeSessions/README.md

@@ -64,9 +64,13 @@ The principal comes from the **server-authenticated** context (`userPayload.user
 argument. An id argument only selects *which of the caller's own sessions*.
 
 A caller may use a session when `AIAgentSession.UserID` equals their user (`UUIDsEqual`). Widget guests all
-share one Anonymous user, so for an anonymous/magic-link principal that is **not enough**: the guest's
-signed per-session scope (`MagicLinkScope.ResourceID`) must equal the session's conversation `ExternalID`.
-An anonymous principal with no scope is refused outright.
+share one Anonymous user, so for an anonymous/magic-link principal that is **not enough**: the session's
+conversation `ExternalID` must equal the principal's scope identity (`ResolveSessionScopeIdentity`): the
+signed `MagicLinkScope.ResourceID` when the token carries one, else the anonymous visitor's `mj_sid`.
+`SessionManager` stamps that same value when it creates the conversation. An anonymous principal with
+neither is refused outright. A *named* user with a resource scope must match too, which keeps one person's
+different links apart; but it may also use its own session on a conversation that carries no stamp (one
+started from the Conversations app) when its own row-level security let it read that conversation.
 
 - Refusals are uniform ("session not found") whether the session is missing or simply not yours, so ids
   cannot be probed.

package/src/realtimeSessions/RealtimeSessionVerificationService.ts

@@ -30,6 +30,7 @@ import {
     type VerificationOperationResult,
     type VerificationSettings,
 } from './verificationWorkflow.js';
+import { ConfiguredPublicUrl } from '../apiRoot.js';
 
 /** Purpose label for principal-resolution diagnostics. */
 const PRINCIPAL_PURPOSE = 'RealtimeVerification';
@@ -37,7 +38,7 @@ const PRINCIPAL_PURPOSE = 'RealtimeVerification';
 /** The base URL emailed links are built from: explicit setting, else the server's public URL (same derivation magic links use). */
 function resolvePublicBaseUrl(explicit: string | undefined): string | undefined {
     const candidate =
-        explicit?.trim() || configInfo.publicUrl || `${configInfo.baseUrl}:${configInfo.graphqlPort}${configInfo.graphqlRootPath || ''}`;
+        explicit?.trim() || ConfiguredPublicUrl();
     return candidate ? TrimTrailingSlashes(candidate) : undefined;
 }
 

package/src/realtimeSessions/RealtimeVerifyRouter.ts

@@ -31,6 +31,7 @@ import { LogError } from '@memberjunction/core';
 import { configInfo } from '../config.js';
 import { RealtimeSessionVerificationService } from './RealtimeSessionVerificationService.js';
 import { BuildVerifyConfirmHtml, BuildVerifyErrorHtml, BuildVerifyFailureHtml, BuildVerifySuccessHtml } from './verificationPages.js';
+import { ApiRoute } from '../apiRoot.js';
 
 /** Mount path of the public verify routes. Under `/realtime`, which is already reserved against server extensions. */
 export const REALTIME_VERIFY_MOUNT_PATH = '/realtime/verify';
@@ -79,7 +80,7 @@ export function CreateRealtimeVerifyRouter(
     // SAFE: renders the confirmation button. Never consumes the token (see the module header).
     router.get('/:token', limiter, (req: Request, res: Response) => {
         const token = typeof req.params.token === 'string' ? req.params.token : '';
-        sendPage(res, 200, BuildVerifyConfirmHtml(token, REALTIME_VERIFY_MOUNT_PATH));
+        sendPage(res, 200, BuildVerifyConfirmHtml(token, ApiRoute(REALTIME_VERIFY_MOUNT_PATH)));
     });
 
     // The side-effecting redemption, gated by a human gesture.

package/src/realtimeSessions/RecordingAssemblyScheduler.ts

@@ -0,0 +1,234 @@
+/**
+ * @fileoverview Per-session timers that assemble a client-direct realtime recording from its shard ledger
+ * off the request path.
+ *
+ * The recording REST routes only record shards and the terminal signal; they never decode. When a route
+ * learns a session is ready (every expected shard present) it asks for an assembly now; when shards are
+ * missing it asks for one after the grace period, forced to `Partial`. This scheduler turns those requests
+ * into at most one pending timer and at most one running assembly per session in this process.
+ *
+ * Correctness across processes does not depend on it: every run starts with the ledger's atomic
+ * `ClaimAssembly`, so of two instances (or two timers) only the claim winner assembles. The per-session
+ * guard here only avoids wasted claims. A run that dies with the process leaves the session `Assembling`,
+ * and the session janitor's stale re-claim is the backstop for that and for any request dropped here.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { DatabaseProviderBase, LogError, LogStatus, UserInfo } from '@memberjunction/core';
+import { BaseSingleton, IShutdownable, ShutdownRegistry } from '@memberjunction/global';
+import {
+    AssembleRealtimeRecordingFromLedger, AssembleRealtimeRecordingInput, AssembleRealtimeRecordingOutcome,
+    IRealtimeRecordingLedger, SqlRealtimeRecordingLedger,
+} from '@memberjunction/ai-agents';
+
+/** A cancellable one-shot timer. */
+export interface RecordingAssemblyTimer {
+    Cancel(): void;
+}
+
+/** Time source of the scheduler; injectable so tests can drive it. */
+export interface RecordingAssemblyClock {
+    /** Milliseconds since the epoch. */
+    Now(): number;
+    /** Runs `callback` once after `delayMs`. The timer must not keep the process alive. */
+    StartTimer(callback: () => void, delayMs: number): RecordingAssemblyTimer;
+}
+
+/** The narrow scheduling contract the recording routes depend on. */
+export interface IRecordingAssemblyScheduler {
+    /**
+     * Requests an assembly of `sessionID` after `delayMs`. `forcePartial` assembles what exists even when
+     * shards are missing (the grace period ran out). See {@link RecordingAssemblyScheduler.ScheduleAssembly}.
+     */
+    ScheduleAssembly(sessionID: string, delayMs: number, forcePartial: boolean): void;
+}
+
+/** What {@link RecordingAssemblyScheduler.Start} needs. */
+export interface RecordingAssemblySchedulerOptions {
+    /** The server's own provider; assembly is server-owned background work, not a request. */
+    Provider: DatabaseProviderBase;
+    /** The user assembly runs as (the system user). */
+    SystemUser: UserInfo;
+    /** Grace before a `Deferred` (incomplete) assembly is retried as forced `Partial`. */
+    GraceMs: () => number;
+    /** Defaults to {@link SqlRealtimeRecordingLedger}. */
+    CreateLedger?: (provider: DatabaseProviderBase, contextUser: UserInfo) => IRealtimeRecordingLedger;
+    /** Defaults to {@link AssembleRealtimeRecordingFromLedger}. */
+    Assemble?: (input: AssembleRealtimeRecordingInput) => Promise<AssembleRealtimeRecordingOutcome>;
+    /** Defaults to `Date.now` and unref'd `setTimeout`. */
+    Clock?: RecordingAssemblyClock;
+}
+
+interface PendingAssembly {
+    DueAt: number;
+    ForcePartial: boolean;
+    Timer: RecordingAssemblyTimer;
+}
+
+const NODE_CLOCK: RecordingAssemblyClock = {
+    Now: () => Date.now(),
+    StartTimer: (callback, delayMs) => {
+        const handle = setTimeout(callback, delayMs);
+        handle.unref?.();
+        return { Cancel: () => clearTimeout(handle) };
+    },
+};
+
+/**
+ * Process-wide scheduler of recording assemblies (see the file overview). Call {@link Start} once at
+ * server startup; requests made before it (or after {@link Shutdown}) are logged and dropped, leaving the
+ * session to the janitor.
+ */
+export class RecordingAssemblyScheduler extends BaseSingleton<RecordingAssemblyScheduler> implements IShutdownable, IRecordingAssemblyScheduler {
+    private _options: Required<RecordingAssemblySchedulerOptions> | null = null;
+    private _registered = false;
+    /** Pending timers keyed by lowercase session id. */
+    private readonly pending = new Map<string, PendingAssembly>();
+    /** Lowercase ids of sessions with an assembly running in this process. */
+    private readonly running = new Set<string>();
+    /** Sessions asked for again while running, with the ForcePartial to re-run with. */
+    private readonly rerun = new Map<string, boolean>();
+
+    protected constructor() {
+        super();
+    }
+
+    /** Process-wide singleton accessor. */
+    public static get Instance(): RecordingAssemblyScheduler {
+        return super.getInstance<RecordingAssemblyScheduler>();
+    }
+
+    /** Identifier surfaced in graceful-shutdown logs. */
+    public readonly ShutdownName = 'RecordingAssemblyScheduler';
+
+    /** Configures the scheduler and enables it; calling again replaces the configuration. */
+    public Start(options: RecordingAssemblySchedulerOptions): void {
+        this._options = {
+            CreateLedger: (provider, contextUser) => new SqlRealtimeRecordingLedger(provider, contextUser),
+            Assemble: AssembleRealtimeRecordingFromLedger,
+            Clock: NODE_CLOCK,
+            ...options,
+        };
+        if (!this._registered) {
+            ShutdownRegistry.Instance.Register(this);
+            this._registered = true;
+        }
+    }
+
+    /**
+     * Requests an assembly of `sessionID` after `delayMs`. One pending timer per session: a request
+     * replaces the pending one only when it would fire sooner (at the same time, the merged request keeps
+     * `forcePartial` if either had it). A timer that fires while the session's previous run is still going
+     * is remembered and run right after it, never alongside it.
+     *
+     * Trade-off: a sooner un-forced request replaces a pending forced one. If that run comes back
+     * `Deferred` (still incomplete), the forced `Partial` is re-scheduled a full grace from then, so a
+     * forced Partial can land up to ~2× the grace after the first terminal signal. Accepted: the sooner
+     * run completes the recording outright whenever the missing shards did arrive.
+     */
+    public ScheduleAssembly(sessionID: string, delayMs: number, forcePartial: boolean): void {
+        const options = this._options;
+        if (!options) {
+            LogError(`RecordingAssemblyScheduler: not running; dropped the assembly request for session ${sessionID} (the session janitor will assemble it)`);
+            return;
+        }
+        const key = sessionID.toLowerCase();
+        const dueAt = options.Clock.Now() + Math.max(0, delayMs);
+        const existing = this.pending.get(key);
+        if (existing && existing.DueAt < dueAt) {
+            return;
+        }
+        if (existing && existing.DueAt === dueAt) {
+            existing.ForcePartial = existing.ForcePartial || forcePartial;
+            return;
+        }
+        existing?.Timer.Cancel();
+        const timer = options.Clock.StartTimer(() => this.onTimer(key, sessionID), dueAt - options.Clock.Now());
+        this.pending.set(key, { DueAt: dueAt, ForcePartial: forcePartial, Timer: timer });
+    }
+
+    /**
+     * Cancels every pending timer and stops accepting requests until the next {@link Start}. A running
+     * assembly is not awaited: if the process exits under it, the session stays `Assembling` and the
+     * janitor's stale re-claim finishes it. Idempotent.
+     */
+    public Shutdown(): void {
+        for (const entry of this.pending.values()) {
+            entry.Timer.Cancel();
+        }
+        this.pending.clear();
+        this.rerun.clear();
+        this._options = null;
+    }
+
+    private onTimer(key: string, sessionID: string): void {
+        const entry = this.pending.get(key);
+        if (!entry) {
+            return;
+        }
+        this.pending.delete(key);
+        if (this.running.has(key)) {
+            this.rerun.set(key, (this.rerun.get(key) ?? false) || entry.ForcePartial);
+            return;
+        }
+        void this.runUntilSettled(key, sessionID, entry.ForcePartial);
+    }
+
+    /** Runs the session's assembly, then any re-run requested meanwhile. Never rejects. */
+    private async runUntilSettled(key: string, sessionID: string, forcePartial: boolean): Promise<void> {
+        this.running.add(key);
+        try {
+            let next: boolean | undefined = forcePartial;
+            while (next !== undefined) {
+                await this.runOnce(sessionID, next);
+                next = this.rerun.get(key);
+                this.rerun.delete(key);
+            }
+        } finally {
+            this.running.delete(key);
+        }
+    }
+
+    /** One claim + assembly. Logs every failure with the session id; never throws. */
+    private async runOnce(sessionID: string, forcePartial: boolean): Promise<void> {
+        const options = this._options;
+        if (!options) {
+            LogStatus(`RecordingAssemblyScheduler: shut down before session ${sessionID} could assemble; the session janitor will assemble it`);
+            return;
+        }
+        try {
+            const ledger = options.CreateLedger(options.Provider, options.SystemUser);
+            const version = await ledger.ClaimAssembly(sessionID, null);
+            if (version === null) {
+                LogStatus(`RecordingAssemblyScheduler: session ${sessionID} not claimable (assembled, assembling elsewhere, or failed); skipping`);
+                return;
+            }
+            const outcome = await options.Assemble({
+                SessionID: sessionID, Version: version, Ledger: ledger,
+                ContextUser: options.SystemUser, Provider: options.Provider, ForcePartial: forcePartial,
+            });
+            this.handleOutcome(sessionID, version, outcome, options);
+        } catch (error) {
+            LogError(`RecordingAssemblyScheduler: assembly of session ${sessionID} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    private handleOutcome(
+        sessionID: string,
+        version: number,
+        outcome: AssembleRealtimeRecordingOutcome,
+        options: Required<RecordingAssemblySchedulerOptions>,
+    ): void {
+        if (outcome === 'Deferred') {
+            // Incomplete and not forced: give missing shards the grace period, then assemble what exists.
+            LogStatus(`RecordingAssemblyScheduler: session ${sessionID} (version ${version}) is missing shards; assembling as Partial after the grace period`);
+            this.ScheduleAssembly(sessionID, options.GraceMs(), true);
+            return;
+        }
+        if (outcome === 'Retry') {
+            LogError(`RecordingAssemblyScheduler: assembly of session ${sessionID} (version ${version}) hit a transient error; the session janitor re-claims it later`);
+            return;
+        }
+        LogStatus(`RecordingAssemblyScheduler: session ${sessionID} (version ${version}) assembly finished: ${outcome}`);
+    }
+}

package/src/realtimeSessions/SessionVerificationPortsBase.ts

@@ -54,6 +54,7 @@ function toSnapshot(loaded: LoadedSessionForAccess): SessionSnapshot {
         AgentSessionID: Session.ID,
         OwnerUserID: Session.UserID,
         ConversationExternalID: loaded.ConversationExternalID,
+        ConversationReadable: loaded.ConversationReadable,
         Status: Session.Status,
         ConfigRaw: Session.Config_,
         // `__mj_CreatedAt` is the row's creation instant — i.e. the session start. It is read-only and

package/src/realtimeSessions/index.ts

@@ -14,3 +14,5 @@ export * from './sessionConfigStamps.js';
 export * from './SessionVerificationPortsBase.js';
 export * from './RealtimeSessionVerificationService.js';
 export * from './RealtimeVerifyRouter.js';
+export * from './ownedRealtimeSession.js';
+export * from './RecordingAssemblyScheduler.js';

package/src/realtimeSessions/ownedRealtimeSession.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview The ownership gate for client-direct realtime session writes: the GraphQL mutations of
+ * `RealtimeClientSessionResolver` and the recording REST routes both load the session through
+ * {@link LoadOwnedRealtimeSession}, so "may this caller write to this session?" is decided in one place.
+ *
+ * @module @memberjunction/server/realtimeSessions
+ */
+import { IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+import type { MJAIAgentSessionEntity } from '@memberjunction/core-entities';
+import { AuthorizeSessionAccess, LoadSessionConversationScope } from './sessionAccess.js';
+
+const SESSION_ENTITY = 'MJ: AI Agent Sessions';
+
+/** The session does not exist, or the caller cannot read it. */
+export class RealtimeSessionNotFoundError extends Error {
+    constructor(public readonly AgentSessionID: string) {
+        super(`Realtime session ${AgentSessionID} not found`);
+        this.name = 'RealtimeSessionNotFoundError';
+    }
+}
+
+/** The session exists but the caller may not use it: another user owns it, or (for a scoped or anonymous caller) its conversation carries another scope identity. */
+export class RealtimeSessionOwnershipError extends Error {
+    constructor(public readonly AgentSessionID: string) {
+        super('Not authorized: you do not own this realtime session');
+        this.name = 'RealtimeSessionOwnershipError';
+    }
+}
+
+/**
+ * Loads a session under the caller's identity and enforces ownership: `UserID === contextUser.ID`, then the
+ * scope rule of {@link AuthorizeSessionAccess} (every anonymous visitor shares one Anonymous user, so the
+ * session's conversation `ExternalID` must equal the caller's scope identity). It deliberately does NOT
+ * reject `Closed` sessions: the final channel-state flush and the recording terminal signal legitimately
+ * arrive after the session closed. Loading as the caller also applies the entity's row-level security.
+ *
+ * @throws RealtimeSessionNotFoundError when the row does not load
+ * @throws RealtimeSessionOwnershipError when another user owns the session (logged with both user ids) or
+ *   the scope rule refuses the caller (logged with the refusal reason)
+ */
+export async function LoadOwnedRealtimeSession(
+    agentSessionId: string,
+    contextUser: UserInfo,
+    provider: IMetadataProvider,
+): Promise<MJAIAgentSessionEntity> {
+    const session = await provider.GetEntityObject<MJAIAgentSessionEntity>(SESSION_ENTITY, contextUser);
+    if (!(await session.Load(agentSessionId))) {
+        throw new RealtimeSessionNotFoundError(agentSessionId);
+    }
+    if (!UUIDsEqual(session.UserID, contextUser.ID)) {
+        LogError(
+            `LoadOwnedRealtimeSession: ownership check failed — user ${contextUser.ID} attempted to operate on session ${agentSessionId} owned by ${session.UserID}`,
+        );
+        throw new RealtimeSessionOwnershipError(agentSessionId);
+    }
+    const conversation = await LoadSessionConversationScope(session, contextUser, provider);
+    const access = AuthorizeSessionAccess(
+        { SessionUserID: session.UserID, ConversationExternalID: conversation.ExternalID, ConversationReadable: conversation.Readable },
+        contextUser,
+    );
+    if (!access.Allowed) {
+        LogError(
+            `LoadOwnedRealtimeSession: session access refused (${access.Reason}) — user ${contextUser.ID} attempted to operate on session ${agentSessionId}`,
+        );
+        throw new RealtimeSessionOwnershipError(agentSessionId);
+    }
+    return session;
+}