@danceiny/gotry 0.2.0-rc.31 → 0.2.0-rc.33

package/dist/src/booking-surface/server.js

@@ -11,6 +11,7 @@ import { BOOKING_COPILOT_ACCEPTED_TURN_KINDS, BOOKING_COPILOT_INGRESS_MODES, BOO
 import { bookingDigest, } from './runtime.js';
 import { validateBookingSurface } from './validation.js';
 import { extractBookingDispatchReason, normalizeBookingErrorCode, safeBookingErrorMessage } from './error-codes.js';
+import { tenantRejection } from './tenancy.js';
 /**
  * 单请求处理闭包(startBookingCopilotServer 的 createServer 回调原样摘出):
  * 探活(/healthz /status)+ 唯一 turn 路由 + 鉴权 + schema 头校验。
@@ -24,8 +25,23 @@ export function bookingCopilotTrafficHandler(deps) {
             sendJson(res, 404, { error: { code: 'not_found' } });
             return;
         }
-        const auth = String(req.headers.authorization ?? '');
-        if (!safeSecretEqual(auth, `Bearer ${apiKey}`)) {
+        // The one place a credential is read. The tenant form asks its authenticator, which names the caller; the shared
+        // form compares the deployment key as before. Neither reads a tenant from the request.
+        let caller = null;
+        if (composition.tenancy) {
+            try {
+                caller = await composition.tenancy.authenticate({ method: req.method ?? '', path: (req.url ?? '').split('?')[0] ?? '', headers: req.headers });
+            }
+            catch {
+                sendJson(res, 503, { error: { code: 'authentication_unavailable' } });
+                return;
+            }
+            if (!caller) {
+                sendJson(res, 401, { error: { code: 'unauthorized' } });
+                return;
+            }
+        }
+        else if (!apiKey || !safeSecretEqual(String(req.headers.authorization ?? ''), `Bearer ${apiKey}`)) {
             sendJson(res, 401, { error: { code: 'unauthorized' } });
             return;
         }
@@ -82,7 +98,7 @@ export function bookingCopilotTrafficHandler(deps) {
         const lifecycle = lifecycleFor(composition);
         lifecycle.acceptedRequests += 1;
         try {
-            await handleBookingCopilotRequest(req, res, composition, maxBodyBytes, negotiatedBookingSurfaceFeatures(req));
+            await handleBookingCopilotRequest(req, res, composition, maxBodyBytes, negotiatedBookingSurfaceFeatures(req), caller);
         }
         finally {
             finishAcceptedRequest(lifecycle);
@@ -137,18 +153,18 @@ function schedulePlannerSessionClose(composition, session) {
     void cleanup.then(() => lifecycle.closing.delete(cleanup));
 }
 /** Detach a session from the request path and close it in the composition lifecycle. */
-function releasePlannerSession(composition, taskId) {
+function releasePlannerSession(composition, sessionKey) {
     const sessions = sessionsFor(composition);
-    const session = sessions.get(taskId);
+    const session = sessions.get(sessionKey);
     if (!session)
         return;
-    sessions.delete(taskId);
+    sessions.delete(sessionKey);
     schedulePlannerSessionClose(composition, session);
 }
 async function drainPlannerSessions(composition) {
     const lifecycle = lifecycleFor(composition);
-    for (const [taskId, session] of lifecycle.active) {
-        lifecycle.active.delete(taskId);
+    for (const [sessionKey, session] of lifecycle.active) {
+        lifecycle.active.delete(sessionKey);
         schedulePlannerSessionClose(composition, session);
     }
     while (lifecycle.closing.size > 0) {
@@ -359,7 +375,7 @@ function fallbackErrorEvent(task, code) {
         error: { code: normalizeBookingErrorCode(code), message: safeBookingErrorMessage(normalizeBookingErrorCode(code)), retryable: false },
     };
 }
-function writeTypedError(res, composition, task, error, requestKey, includeSubmitted = false) {
+function writeTypedError(res, runtime, task, error, requestKey, includeSubmitted = false, isTenantFault = () => false) {
     const code = normalizeBookingErrorCode(error);
     // Provider/adapter exceptions can contain response bodies, URLs or request
     // context. Preserve only the closed code and coarse thrown-value class.
@@ -370,21 +386,66 @@ function writeTypedError(res, composition, task, error, requestKey, includeSubmi
     try {
         const decision = { kind: 'error', error: { code, message: safeBookingErrorMessage(code), retryable: false } };
         if (requestKey) {
-            const events = composition.runtime.applyDecisionBatch(task.taskId, requestKey, [decision], includeSubmitted, { suppressProgressStatuses: true });
+            const events = runtime.applyDecisionBatch(task.taskId, requestKey, [decision], includeSubmitted, { suppressProgressStatuses: true });
             for (const event of events)
                 write(res, event);
             return;
         }
-        write(res, composition.runtime.emitEvent(task.taskId, decision));
+        write(res, runtime.emitEvent(task.taskId, decision));
     }
-    catch {
+    catch (writeError) {
+        // A lease lost under the durable write is not a planner answer: nothing can be acknowledged, so the caller cuts the connection.
+        if (isTenantFault(writeError))
+            throw writeError;
         // The stream is already committed. Emit a schema-valid, non-durable
         // typed envelope instead of silently returning an empty HTTP 200 stream.
         write(res, fallbackErrorEvent(task, code));
     }
 }
-/** Handles one already-authenticated request inside the sole HTTP listener. */
-async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes, negotiatedFeatures) {
+/** The shared form's scope: the one runtime and planner of the composition, keys exactly as they were before tenants existed. */
+function sharedScope(composition) {
+    const ingress = composition.ingressMode === 'bff-ingress-binding' && composition.ingressBinding && composition.principal
+        ? { binding: composition.ingressBinding, principal: composition.principal }
+        : null;
+    return {
+        key: null,
+        runtime: composition.runtime,
+        plannerFactory: composition.plannerFactory,
+        ingress,
+        sessionKey: (taskId) => taskId,
+        flightKey: (parts) => JSON.stringify(parts),
+        runDecision: (work) => work(),
+        isTenantFault: () => false,
+        release: () => undefined,
+    };
+}
+/** Handles one already-authenticated request inside the sole HTTP listener: places it in its scope, then serves it there. */
+async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes, negotiatedFeatures, caller) {
+    let scope;
+    if (composition.tenancy) {
+        // Derive the tenant, admit the turn against its quotas and open its guarded ledger, all before the body is read.
+        try {
+            scope = await composition.tenancy.beginTurn(caller);
+        }
+        catch (error) {
+            const rejection = tenantRejection(error);
+            if (rejection.retryAfterSeconds !== undefined)
+                res.setHeader('retry-after', String(rejection.retryAfterSeconds));
+            sendJson(res, rejection.status, rejection.body);
+            return;
+        }
+    }
+    else {
+        scope = sharedScope(composition);
+    }
+    try {
+        await serveBookingTurn(req, res, composition, scope, maxBodyBytes, negotiatedFeatures);
+    }
+    finally {
+        scope.release();
+    }
+}
+async function serveBookingTurn(req, res, composition, scope, maxBodyBytes, negotiatedFeatures) {
     let turn;
     let browserRequestKey;
     let requestBinding;
@@ -399,11 +460,11 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
         if (parsed.kind === 'user.turn.ingress') {
             const ingress = parsed;
             browserRequestKey = ingress.requestKey;
-            if (composition.ingressMode !== 'bff-ingress-binding' || !composition.ingressBinding || !composition.principal) {
+            if (!scope.ingress) {
                 sendJson(res, 503, { error: { code: 'trusted_ingress_binding_required', mode: composition.ingressMode ?? 'bff-bound-turn-only', acceptedTurnKinds: [...BOOKING_COPILOT_ACCEPTED_TURN_KINDS] } });
                 return;
             }
-            const binding = await composition.ingressBinding.bind(ingress, composition.principal);
+            const binding = await scope.ingress.binding.bind(ingress, scope.ingress.principal);
             if (!validIngressBinding(binding, ingress)) {
                 sendJson(res, 502, { error: { code: 'invalid_ingress_binding' } });
                 return;
@@ -423,7 +484,7 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
                 ? { text: ingress.request.text, approval: { ...ingress.request.approval } }
                 : { text: ingress.request.text };
             turn = { schemaVersion: BOOKING_SURFACE_SCHEMA_VERSION, kind: 'user.turn', taskId: binding.taskId, turnId: binding.turnId, workspace: proposedBoundWorkspace, request: boundRequest };
-            requestBinding = { requestKey: ingress.requestKey, principal: composition.principal, ...(ingress.taskHandle ? { taskHandle: ingress.taskHandle } : {}) };
+            requestBinding = { requestKey: ingress.requestKey, principal: scope.ingress.principal, ...(ingress.taskHandle ? { taskHandle: ingress.taskHandle } : {}) };
             authorityFailureStatus = 502;
             const boundValid = validateBookingSurface(turn);
             if (!boundValid.ok) {
@@ -451,7 +512,7 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
     let replayEvents = null;
     let activeDecisionKey;
     try {
-        const existingAtAdmission = turn.taskId ? composition.runtime.resumeTask(turn.taskId) : null;
+        const existingAtAdmission = turn.taskId ? scope.runtime.resumeTask(turn.taskId) : null;
         const narrowedWorkspace = narrowWorkspaceOptionalAuthority(turn.workspace, negotiatedFeatures, existingAtAdmission?.allowedActions);
         if (!narrowedWorkspace) {
             const code = authorityFailureStatus === 502 ? 'invalid_ingress_binding' : 'invalid_bound_turn_authority';
@@ -461,26 +522,26 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
         turn = { ...turn, workspace: narrowedWorkspace };
         fresh = turn.kind === 'action.receipt.continuation' ? false : existingAtAdmission === null;
         if (turn.kind === 'action.receipt.continuation') {
-            replayKey = `receipt:${turn.receipt.actionId}:${composition.runtime.receiptDigest(turn.receipt)}`;
-            task = composition.runtime.continueWithReceipt(turn);
+            replayKey = `receipt:${turn.receipt.actionId}:${scope.runtime.receiptDigest(turn.receipt)}`;
+            task = scope.runtime.continueWithReceipt(turn);
             if (task.awaitingApproval) {
-                replayKey = composition.runtime.approvalPresentationRequestKey(turn.taskId);
+                replayKey = scope.runtime.approvalPresentationRequestKey(turn.taskId);
             }
-            replayEvents = composition.runtime.readDecisionBatch(turn.taskId, replayKey);
+            replayEvents = scope.runtime.readDecisionBatch(turn.taskId, replayKey);
             if (!replayEvents && task.phase === 'terminal')
-                replayEvents = composition.runtime.terminalDecisionBatch(turn.taskId, replayKey);
+                replayEvents = scope.runtime.terminalDecisionBatch(turn.taskId, replayKey);
         }
         else {
             const existing = existingAtAdmission;
             if (requestBinding && turn.kind === 'user.turn')
-                composition.runtime.assertRequestBinding(browserRequestKey, turn, requestBinding);
+                scope.runtime.assertRequestBinding(browserRequestKey, turn, requestBinding);
             const requestReplayKey = existing && browserRequestKey ? `ingress:${existing.taskId}:${browserRequestKey}` : undefined;
             const directReplayKey = existing && turn.kind === 'user.turn' && turn.turnId ? `turn:${existing.taskId}:${turn.turnId}` : undefined;
             const stableReplayKey = requestReplayKey ?? directReplayKey;
-            const stableReplay = stableReplayKey ? composition.runtime.readDecisionBatch(existing.taskId, stableReplayKey) : null;
+            const stableReplay = stableReplayKey ? scope.runtime.readDecisionBatch(existing.taskId, stableReplayKey) : null;
             if (stableReplay) {
                 if (existing && turn.kind === 'user.turn' && directReplayKey)
-                    composition.runtime.assertTurnBinding(existing.taskId, turn);
+                    scope.runtime.assertTurnBinding(existing.taskId, turn);
                 task = existing;
                 replayKey = stableReplayKey;
                 replayEvents = stableReplay;
@@ -490,7 +551,7 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
             }
             else if (existing?.phase === 'waiting_receipt') {
                 if (turn.kind === 'user.turn' && turn.request.approval)
-                    composition.runtime.assertApprovalNotConsumed(existing.taskId, turn.request.approval);
+                    scope.runtime.assertApprovalNotConsumed(existing.taskId, turn.request.approval);
                 const workspace = turn.workspace;
                 if (workspace.contextRef !== existing.contextRef || workspace.surface !== existing.surface || workspace.revision !== existing.revision || workspace.capabilities.surface !== existing.surface || !sameCapabilities(workspace.capabilities.allowedActions, existing.allowedActions))
                     throw new Error('task_conflict:workspace_mismatch');
@@ -500,23 +561,30 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
                 if (!turn.turnId || existing.lastTurnId !== turn.turnId)
                     throw new Error('receipt_required');
                 replayKey = browserRequestKey ? `ingress:${existing.taskId}:${browserRequestKey}` : `turn:${existing.taskId}:${existing.lastTurnId ?? existing.userTurnCount}`;
-                replayEvents = composition.runtime.readDecisionBatch(existing.taskId, replayKey);
+                replayEvents = scope.runtime.readDecisionBatch(existing.taskId, replayKey);
                 if (!replayEvents)
                     throw new Error('receipt_required');
                 task = existing;
             }
             else {
                 if (existing && turn.kind === 'user.turn' && turn.request.approval)
-                    composition.runtime.assertApprovalNotConsumed(existing.taskId, turn.request.approval);
-                task = composition.runtime.startTask(turn, requestBinding);
+                    scope.runtime.assertApprovalNotConsumed(existing.taskId, turn.request.approval);
+                task = scope.runtime.startTask(turn, requestBinding);
                 if (turn.kind === 'user.turn' && turn.taskId) {
                     replayKey = browserRequestKey ? `ingress:${task.taskId}:${browserRequestKey}` : `turn:${task.taskId}:${turn.turnId ?? task.userTurnCount}`;
-                    replayEvents = composition.runtime.readDecisionBatch(task.taskId, replayKey);
+                    replayEvents = scope.runtime.readDecisionBatch(task.taskId, replayKey);
                 }
             }
         }
     }
     catch (error) {
+        if (scope.isTenantFault(error)) {
+            const rejection = tenantRejection(error);
+            if (rejection.retryAfterSeconds !== undefined)
+                res.setHeader('retry-after', String(rejection.retryAfterSeconds));
+            sendJson(res, rejection.status, rejection.body);
+            return;
+        }
         const code = normalizeBookingErrorCode(error);
         console.error(JSON.stringify({ code, reason: extractBookingDispatchReason(error) }));
         sendJson(res, 409, { error: { code } });
@@ -526,7 +594,7 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
     res.flushHeaders();
     try {
         if (replayEvents) {
-            const progressEvents = composition.runtime.readProgressBatch(task.taskId, replayKey ?? `turn:${task.taskId}:${task.userTurnCount}`) ?? [];
+            const progressEvents = scope.runtime.readProgressBatch(task.taskId, replayKey ?? `turn:${task.taskId}:${task.userTurnCount}`) ?? [];
             for (const event of progressEvents)
                 write(res, event);
             if (progressEvents.length) {
@@ -534,7 +602,7 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
                 await new Promise((resolve) => setImmediate(resolve));
             }
             if (task.phase === 'terminal' || task.phase === 'error')
-                releasePlannerSession(composition, task.taskId);
+                releasePlannerSession(composition, scope.sessionKey(task.taskId));
             for (const event of replayEvents)
                 write(res, event);
         }
@@ -545,36 +613,39 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
             // committed progress but before its planner flight finishes. Re-serve
             // the durable progress batch so it receives the same prefix instead of
             // exposing a terminal-only tail.
-            const newlyPersistedProgress = composition.runtime.ensureProgressBatch(task.taskId, requestKey, fresh);
+            const newlyPersistedProgress = scope.runtime.ensureProgressBatch(task.taskId, requestKey, fresh);
             const progressEvents = newlyPersistedProgress.length > 0
                 ? newlyPersistedProgress
-                : (composition.runtime.readProgressBatch(task.taskId, requestKey) ?? []);
+                : (scope.runtime.readProgressBatch(task.taskId, requestKey) ?? []);
             const approval = turn.kind === 'user.turn' ? turn.request.approval : undefined;
-            const flightKey = JSON.stringify([task.taskId, approval ? `approval:${bookingDigest(approval)}` : requestKey]);
+            const flightKey = scope.flightKey([task.taskId, approval ? `approval:${bookingDigest(approval)}` : requestKey]);
             // Register or join the decision flight before yielding after the progress
             // flush. A duplicate that observed the durable progress must never miss
             // an about-to-finish flight and pay for a second model invocation.
-            const decisionOutcome = runDecisionSingleFlight(composition, flightKey, async () => {
+            // The decision work runs inside the scope: in the tenant form that proves the lease before and after it, lets a
+            // handoff drain it, and keeps its events from reaching the client if the lease was lost meanwhile.
+            const decisionOutcome = runDecisionSingleFlight(composition, flightKey, () => scope.runDecision(async () => {
                 // Cover the complementary late-join case: the prior flight may have
                 // committed its exact batch and left the in-memory map between request
                 // admission and this work starting.
-                const durableDecision = composition.runtime.readDecisionBatch(task.taskId, requestKey);
+                const durableDecision = scope.runtime.readDecisionBatch(task.taskId, requestKey);
                 if (durableDecision)
                     return durableDecision;
                 if (turn.kind === 'action.receipt.continuation' && task.awaitingApproval) {
-                    return composition.runtime.applyDecisionBatch(task.taskId, requestKey, [composition.runtime.approvalQuestion(task.taskId)], false);
+                    return scope.runtime.applyDecisionBatch(task.taskId, requestKey, [scope.runtime.approvalQuestion(task.taskId)], false);
                 }
                 const sessions = sessionsFor(composition);
-                const session = sessions.get(task.taskId) ?? composition.plannerFactory(task);
-                sessions.set(task.taskId, session);
-                const decisions = await session.next({ turn, task: composition.runtime.resumeTask(task.taskId) ?? task });
+                const sessionKey = scope.sessionKey(task.taskId);
+                const session = sessions.get(sessionKey) ?? scope.plannerFactory(task);
+                sessions.set(sessionKey, session);
+                const decisions = await session.next({ turn, task: scope.runtime.resumeTask(task.taskId) ?? task });
                 const plannerDecisions = decisions.length ? decisions : [{ kind: 'error', error: { code: 'PLANNER_NO_DECISION', message: 'Planner returned no typed decision.', retryable: false } }];
-                const events = composition.runtime.applyDecisionBatch(task.taskId, requestKey, plannerDecisions, fresh, { suppressProgressStatuses: true });
-                const updated = composition.runtime.resumeTask(task.taskId);
+                const events = scope.runtime.applyDecisionBatch(task.taskId, requestKey, plannerDecisions, fresh, { suppressProgressStatuses: true });
+                const updated = scope.runtime.resumeTask(task.taskId);
                 if (updated?.phase === 'terminal' || updated?.phase === 'error')
-                    releasePlannerSession(composition, task.taskId);
+                    releasePlannerSession(composition, sessionKey);
                 return events;
-            }).then((events) => ({ ok: true, events }), (error) => ({ ok: false, error }));
+            })).then((events) => ({ ok: true, events }), (error) => ({ ok: false, error }));
             for (const event of progressEvents)
                 write(res, event);
             if (progressEvents.length) {
@@ -589,61 +660,103 @@ async function handleBookingCopilotRequest(req, res, composition, maxBodyBytes,
         }
     }
     catch (error) {
-        writeTypedError(res, composition, task, error, activeDecisionKey, fresh);
-        const updated = composition.runtime.resumeTask(task.taskId);
-        if (updated?.phase === 'terminal' || updated?.phase === 'error')
-            releasePlannerSession(composition, task.taskId);
+        // A lease lost, fenced or handed off while the stream is open cannot be told to the client as an answer: nothing
+        // was acknowledged, so the connection is cut and the BFF retries the same request key on the next owner.
+        if (scope.isTenantFault(error)) {
+            res.destroy();
+            return;
+        }
+        try {
+            writeTypedError(res, scope.runtime, task, error, activeDecisionKey, fresh, scope.isTenantFault);
+            const updated = scope.runtime.resumeTask(task.taskId);
+            if (updated?.phase === 'terminal' || updated?.phase === 'error')
+                releasePlannerSession(composition, scope.sessionKey(task.taskId));
+        }
+        catch (faultWhileAnswering) {
+            // The lease went while the planner's error was being recorded: the same rule as above, and never an escaped rejection.
+            if (!scope.isTenantFault(faultWhileAnswering))
+                throw faultWhileAnswering;
+            res.destroy();
+        }
     }
     finally {
         res.end();
     }
 }
 export function startBookingCopilotServer(options) {
-    if (!options.apiKey)
+    // The shared form's key is checked first, exactly as before the tenant form existed.
+    if (!options.tenancy && !options.apiKey)
         return Promise.reject(new Error('booking_copilot_api_key_required'));
     if (options.artifactId !== undefined && !/^[0-9a-f]{40}$/.test(options.artifactId)) {
         return Promise.reject(new Error('booking_copilot_artifact_id_invalid'));
     }
-    if (!options.runtime || !options.plannerFactory) {
-        return Promise.reject(new Error('booking_copilot_runtime_and_planner_required'));
-    }
-    const hasIngressBinding = Boolean(options.ingressBinding);
-    const hasPrincipal = Boolean(options.principal);
-    if (hasIngressBinding !== hasPrincipal) {
-        return Promise.reject(new Error('booking_copilot_ingress_binding_pair_required'));
-    }
-    if (hasIngressBinding && (typeof options.ingressBinding?.bind !== 'function'
-        || typeof options.principal?.subject !== 'string' || options.principal.subject.length === 0 || options.principal.subject.length > 256
-        || typeof options.principal?.scope !== 'string' || options.principal.scope.length === 0 || options.principal.scope.length > 256)) {
-        return Promise.reject(new Error('booking_copilot_ingress_binding_invalid'));
-    }
-    const ingressMode = options.ingressMode ?? (hasIngressBinding ? 'bff-ingress-binding' : 'bff-bound-turn-only');
-    if (!BOOKING_COPILOT_INGRESS_MODES.includes(ingressMode)) {
-        return Promise.reject(new Error('booking_copilot_ingress_mode_invalid'));
-    }
-    if (ingressMode === 'bff-ingress-binding' && !hasIngressBinding) {
-        return Promise.reject(new Error('booking_copilot_ingress_binding_required'));
+    let composition;
+    let ingressMode;
+    if (options.tenancy) {
+        // One authentication system per form: the tenant form has no shared key and no shared runtime, planner or principal.
+        if (options.apiKey)
+            return Promise.reject(new Error('booking_copilot_tenancy_api_key_conflict'));
+        if (options.runtime || options.plannerFactory || options.ingressBinding || options.principal) {
+            return Promise.reject(new Error('booking_copilot_tenancy_shared_conflict'));
+        }
+        ingressMode = options.tenancy.ingressMode;
+        if (options.ingressMode !== undefined && options.ingressMode !== ingressMode) {
+            return Promise.reject(new Error('booking_copilot_ingress_mode_conflict'));
+        }
+        composition = { tenancy: options.tenancy, ingressMode };
     }
-    if (ingressMode === 'bff-bound-turn-only' && hasIngressBinding) {
-        return Promise.reject(new Error('booking_copilot_ingress_mode_conflict'));
+    else {
+        if (!options.runtime || !options.plannerFactory) {
+            return Promise.reject(new Error('booking_copilot_runtime_and_planner_required'));
+        }
+        const hasIngressBinding = Boolean(options.ingressBinding);
+        const hasPrincipal = Boolean(options.principal);
+        if (hasIngressBinding !== hasPrincipal) {
+            return Promise.reject(new Error('booking_copilot_ingress_binding_pair_required'));
+        }
+        if (hasIngressBinding && (typeof options.ingressBinding?.bind !== 'function'
+            || typeof options.principal?.subject !== 'string' || options.principal.subject.length === 0 || options.principal.subject.length > 256
+            || typeof options.principal?.scope !== 'string' || options.principal.scope.length === 0 || options.principal.scope.length > 256)) {
+            return Promise.reject(new Error('booking_copilot_ingress_binding_invalid'));
+        }
+        ingressMode = options.ingressMode ?? (hasIngressBinding ? 'bff-ingress-binding' : 'bff-bound-turn-only');
+        if (!BOOKING_COPILOT_INGRESS_MODES.includes(ingressMode)) {
+            return Promise.reject(new Error('booking_copilot_ingress_mode_invalid'));
+        }
+        if (ingressMode === 'bff-ingress-binding' && !hasIngressBinding) {
+            return Promise.reject(new Error('booking_copilot_ingress_binding_required'));
+        }
+        if (ingressMode === 'bff-bound-turn-only' && hasIngressBinding) {
+            return Promise.reject(new Error('booking_copilot_ingress_mode_conflict'));
+        }
+        composition = {
+            runtime: options.runtime,
+            plannerFactory: options.plannerFactory,
+            ...(hasIngressBinding ? { ingressBinding: options.ingressBinding, principal: options.principal } : {}),
+            ingressMode,
+        };
     }
-    const composition = {
-        runtime: options.runtime,
-        plannerFactory: options.plannerFactory,
-        ...(hasIngressBinding ? { ingressBinding: options.ingressBinding, principal: options.principal } : {}),
-        ingressMode,
-    };
     const maxBodyBytes = options.maxBodyBytes ?? 1_000_000;
     const runningIdentity = runtimeIdentity();
     const server = createServer((req, res) => {
-        void bookingCopilotTrafficHandler({
-            apiKey: options.apiKey,
+        const handled = bookingCopilotTrafficHandler({
+            ...(options.apiKey ? { apiKey: options.apiKey } : {}),
             composition,
             maxBodyBytes,
             ...(options.artifactId !== undefined ? { artifactId: options.artifactId } : {}),
             ingressMode,
             runningIdentity,
         })(req, res);
+        if (!options.tenancy) {
+            void handled;
+            return;
+        }
+        // One replica serves every tenant: whatever escapes one request ends that request, never the process.
+        handled.catch((error) => {
+            console.error('[booking-copilot] request failed:', JSON.stringify({ thrownType: error instanceof Error ? error.name : typeof error }));
+            if (!res.writableEnded)
+                res.destroy();
+        });
     });
     let closePromise;
     return new Promise((resolve, reject) => {

package/dist/src/booking-surface/startup.js

@@ -1,4 +1,5 @@
 /** Production composition entry for GoTry's BFF-only Booking Copilot server. */
+import { AsyncResource } from 'node:async_hooks';
 import { mkdirSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,6 +7,7 @@ import { ensureLedger } from '../state-ledger.js';
 import { buildDshPlannerEnvironment, createDshEmbeddedBookingPlanner, } from './dsh-planner.js';
 import { BookingCopilotTaskRuntime } from './runtime.js';
 import { BOOKING_COPILOT_INGRESS_MODES } from './contracts.js';
+import { assertManagedDshLimitsEnforceable } from './managed-dsh-run-port.js';
 import { startBookingCopilotServer, } from './server.js';
 const DEFAULT_DEPENDENCIES = {
     ensureLedger,
@@ -59,6 +61,155 @@ export function resolveBookingCopilotStartupConfig(env = process.env) {
         ingressMode: ingressMode,
     };
 }
+/** The listener settings of the multi-tenant form. There is no deployment key and no shared state root: the tenancy holds both roles. */
+export function resolveBookingCopilotTenantStartupConfig(env = process.env) {
+    const artifactId = env.GOTRY_BOOKING_COPILOT_ARTIFACT_ID || undefined;
+    if (artifactId !== undefined && !/^[0-9a-f]{40}$/.test(artifactId)) {
+        throw new Error('booking_copilot_artifact_id_invalid');
+    }
+    const rawIngressMode = env.GOTRY_BOOKING_COPILOT_INGRESS_MODE;
+    if (rawIngressMode !== undefined && rawIngressMode !== '' && !BOOKING_COPILOT_INGRESS_MODES.includes(rawIngressMode)) {
+        throw new Error('booking_copilot_ingress_mode_invalid');
+    }
+    return {
+        host: env.GOTRY_BOOKING_COPILOT_HOST || '127.0.0.1',
+        port: parsePort(env.GOTRY_BOOKING_COPILOT_PORT),
+        ...(artifactId === undefined ? {} : { artifactId }),
+        ...(rawIngressMode === undefined || rawIngressMode === '' ? {} : { ingressMode: rawIngressMode }),
+    };
+}
+/**
+ * Ceilings for each planner process tree in the multi-tenant form (docs/rfc/aaas-rfc.md §4.8, threat S-17). Every
+ * tenant on a replica shares its CPU and memory, so one runaway child must be stopped by a limit and not by the
+ * operating system's OOM killer. These numbers are a ceiling for a runaway, not a budget, and are unreviewed: they sit
+ * well above what an idle booted planner tree costs (see docs/ops/aaas-capacity-baseline.md) and a deployment that
+ * knows better passes its own `resourceLimits`.
+ */
+export const DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS = Object.freeze({
+    heapMb: 512,
+    maxRssBytes: 1536 * 1024 * 1024,
+    maxCpuSeconds: 120,
+    maxLineChars: 8 * 1024 * 1024,
+});
+/**
+ * The sampler is the only thing between a runaway planner child and the replica. If it cannot see the process table, the
+ * limits would silently govern nothing, so this fails first, with a name, before any child starts. Limits that need no
+ * sampler (a heap ceiling, a line cap) have nothing to check.
+ */
+export const assertPlannerLimitsEnforceable = assertManagedDshLimitsEnforceable;
+/**
+ * One planner per tenant, each rooted in that tenant's own directory, so planner sessions and working files never sit
+ * beside another tenant's. Planners are created lazily by the dsh adapter (no process starts until a session needs one).
+ * The dsh adapter does not report token usage yet, so until it does every invocation is charged the quota policy's
+ * worst case (`TenantQuotas.chargeUnprovenInvocation`).
+ */
+export function createDshTenantPlannerProvider(base, createPlanner = createDshEmbeddedBookingPlanner) {
+    // The real dsh planner of the tenant form never holds the deployment's LLM credential (docs/rfc/aaas-rfc.md §4.8, S-18):
+    // it is built with a broker that gives each planner process tree a ticket. A planner factory injected by a suite is
+    // the caller's own business and is not asked for one.
+    if (createPlanner === createDshEmbeddedBookingPlanner && base.llmTickets === undefined) {
+        throw new Error('tenant_planner_credential_broker_required');
+    }
+    const handles = [];
+    const realPlanner = createPlanner === createDshEmbeddedBookingPlanner;
+    let governable = false;
+    return {
+        async forTenant(context) {
+            if (realPlanner && !governable) {
+                await assertPlannerLimitsEnforceable(base.resourceLimits ?? DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS);
+                governable = true;
+            }
+            // Tickets issued for this tenant report their measured usage to this tenant's meter. The report is bound to the
+            // async context where the ticket is issued, which is inside the planner invocation that needs the port: the broker
+            // answers from its own request context, and the report must still land on the invocation that asked (and on no other).
+            const issuer = base.llmTickets;
+            const llmTickets = issuer && {
+                issue: (options = {}) => issuer.issue({
+                    ...options,
+                    onUsage: AsyncResource.bind((report) => context.reportUsage(report.model, report.usage)),
+                }),
+            };
+            const handle = await createPlanner({
+                ...base,
+                ...(llmTickets ? { llmTickets } : {}),
+                resourceLimits: base.resourceLimits ?? DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS,
+                // Both come from the tenant, never from the deployment-wide base: a shared label or root would defeat the point.
+                cachePartition: context.cachePartition,
+                stateRoot: context.tenantRoot,
+            });
+            handles.push(handle);
+            return handle.plannerFactory;
+        },
+        async close() {
+            const failures = [];
+            for (const handle of handles.splice(0)) {
+                try {
+                    await handle.close();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, 'booking_copilot_planner_shutdown_failed');
+        },
+    };
+}
+async function startTenantCopilot(env, dependencies, tenancy) {
+    if (dependencies.ingressBinding || dependencies.principal)
+        throw new Error('booking_copilot_tenancy_shared_conflict');
+    const config = resolveBookingCopilotTenantStartupConfig(env);
+    if (config.ingressMode !== undefined && config.ingressMode !== tenancy.ingressMode)
+        throw new Error('booking_copilot_ingress_mode_conflict');
+    let server;
+    try {
+        server = await dependencies.startServer({
+            tenancy,
+            ingressMode: tenancy.ingressMode,
+            host: config.host,
+            port: config.port,
+            ...(config.artifactId === undefined ? {} : { artifactId: config.artifactId }),
+        });
+    }
+    catch (error) {
+        try {
+            await tenancy.close();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'booking_copilot_startup_and_cleanup_failed');
+        }
+        throw error;
+    }
+    let closed = false;
+    return {
+        port: server.port,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const failures = [];
+            // Stop taking turns and drain the ones in flight first; then give the tenants back (planners, then leases).
+            try {
+                await server.close();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            try {
+                await tenancy.close();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, 'booking_copilot_shutdown_failed');
+        },
+    };
+}
 async function closeAll(server, planner, ledger) {
     const failures = [];
     for (const close of [
@@ -85,6 +236,8 @@ async function closeAll(server, planner, ledger) {
  * HTTP/SSE server. Only the HTTP layer receives the BFF deployment key.
  */
 export async function startBookingCopilotFromEnvironment(env = process.env, dependencies = DEFAULT_DEPENDENCIES) {
+    if (dependencies.tenancy)
+        return startTenantCopilot(env, dependencies, dependencies.tenancy);
     const config = resolveBookingCopilotStartupConfig(env);
     const activeDependencies = dependencies;
     const hasIngressBinding = Boolean(activeDependencies.ingressBinding);