@bevel-software/platform-core-backend 0.1.0

package/src/core/create-core-services.ts

@@ -0,0 +1,501 @@
+import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, PROTECTED_BRANCHES, SKILLS_DIR, TOOLS_DIR } from '@bevel-software/platform-shared';
+import { CoreConfig } from '../core-config.js';
+import { getDb, type Database } from '../modules/database/connection.js';
+import { runCoreMigrations } from '../modules/database/migrate.js';
+import { coreMigrationsDir } from '../assets.js';
+import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
+import { KbSeedService } from '../modules/workspace/kb-seed.service.js';
+import { SpillStore } from '../modules/workspace/spill-store.js';
+import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
+import { AuthService } from '../modules/auth/auth.service.js';
+import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
+import { createAuthMiddleware } from '../modules/auth/auth.middleware.js';
+import { AccessControlService } from '../modules/access/access-control.service.js';
+import { CreatorAccessService } from '../modules/access/creator-access.js';
+import { SkillService } from '../modules/skills/index.js';
+import { ToolManualService } from '../modules/tool-manuals/index.js';
+import {
+  DbSecretsVaultService,
+  McpOAuthDiscoveryService,
+  registerBevelSecretsVariableLoader,
+} from '../modules/secrets-vault/index.js';
+import { GitService } from '../modules/workflow/git/git.service.js';
+import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
+import { WorkspaceMutex } from '../modules/workflow/git/mutex.js';
+import { assertGitVersion } from '../modules/workflow/git/git-version.js';
+import { DiffService } from '../modules/diff/diff.service.js';
+import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
+import { FileLockService } from '../modules/workflow/file-lock.service.js';
+import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import { FileChangeNotifier } from '../modules/workflow/file-change-notifier.js';
+import { WorkflowService } from '../modules/workflow/workflow.service.js';
+import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
+import { SessionOntologyService } from '../modules/workflow/session-ontology.service.js';
+import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
+import {
+  PendingCommitsWorker,
+  consoleSystemNoticeSink,
+} from '../modules/workflow/pending-commits.worker.js';
+import { ensureRecoveryBotUser } from '../modules/workflow/recovery-bot.js';
+import { AdminAccessService } from '../modules/admin/admin-access.service.js';
+import { ExternalApiKeyService } from '../modules/tool-auth/external-api-key.service.js';
+import { InternalTokenService } from '../modules/tool-auth/internal-token.service.js';
+import {
+  createToolAuthMiddleware,
+  createManualAuthMiddleware,
+} from '../modules/tool-auth/tool-auth.middleware.js';
+import { unmeteredLlmUsage, type ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
+import { McpSessionStore } from '../modules/mcp/mcp-session-store.js';
+import { McpService } from '../modules/mcp/mcp.service.js';
+import { createMcpAuthMiddleware } from '../modules/mcp/mcp-auth.middleware.js';
+import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js';
+import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { ToolRegistry } from '../modules/tool-registry/tool-registry.js';
+import { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+import { TokenCrypto } from '../shared/token-crypto.js';
+import { noopRecoveryAgent, type CorePorts } from './core-ports.js';
+
+/**
+ * Everything the CORE composition builds: the core services `createCoreServer`
+ * mounts, plus the primitives the enterprise overlay's own construction needs
+ * (db, event bus, notifier, registries, middlewares, …).
+ *
+ * The fields under "server-time seams" are deliberately MUTABLE: they are only
+ * read when the server is built / at request time, and the enterprise overlay
+ * overwrites them after `createCoreServices` returns (its implementations need
+ * core services to construct). See {@link CorePorts} for the pattern.
+ */
+export interface CoreServices {
+  config: CoreConfig;
+  db: Database;
+  workspaceService: WorkspaceService;
+  kbSeedService: KbSeedService;
+  spillStore: SpillStore;
+  accessControl: AccessControlService;
+  creatorAccess: CreatorAccessService;
+  sessionOntologyService: SessionOntologyService;
+  routineWritePolicy: RoutineWritePolicyService;
+  skillService: SkillService;
+  toolManualService: ToolManualService;
+  authService: AuthService;
+  authMiddleware: ReturnType<typeof createAuthMiddleware>;
+  accountErasureService: AccountErasureService;
+  gitService: GitService;
+  pullRequestService: PullRequestService;
+  diffService: DiffService;
+  reviewWorkflowService: ReviewWorkflowService;
+  fileLockService: FileLockService;
+  workflowService: WorkflowService;
+  eventBus: WorkflowEventBus;
+  fileChangeNotifier: FileChangeNotifier;
+  pendingCommitsService: PendingCommitsService;
+  pendingCommitsWorker: PendingCommitsWorker;
+  recoveryBot: AuthUser;
+  adminAccess: AdminAccessService;
+  secretsVaultService: DbSecretsVaultService;
+  externalApiKeyService: ExternalApiKeyService;
+  internalTokenService: InternalTokenService;
+  mcpService: McpService;
+  mcpAuthMiddleware: ReturnType<typeof createMcpAuthMiddleware>;
+  mcpOAuthProvider: BevelOAuthProvider;
+  toolRegistry: ToolRegistry;
+  toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
+  manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
+  toolHandlerFactory: ReturnType<typeof createToolHandlerFactory>;
+  // ── Server-time seams (enterprise overwrites after construction) ────────
+  /** `start_session` backing — core default {@link UuidSessionSink}. */
+  sessionSink: ISessionSink;
+  /** Connection-key LLM metering view — core default unmetered. */
+  usageMeter: ILlmUsageMeter;
+  /** SSO plugins the auth router mounts — same array instance as the port. */
+  authProviders: AuthProviderPlugin[];
+}
+
+export async function createCoreServices(
+  config: CoreConfig,
+  ports: CorePorts = {},
+): Promise<CoreServices> {
+  // Fail fast on a runtime whose git is too old for `--no-write-fetch-head`
+  // (see `git-version.ts`): every clone, fetch and refresh below depends on it,
+  // so an unsupported binary is better surfaced here than at the first merge.
+  await assertGitVersion();
+  const db = getDb(config.databaseUrl);
+  // Migrations must run BEFORE any service that reads or writes a managed
+  // table. `PendingCommitsService.startupReconcile` (called later in this
+  // function) hits `pending_commits` — on a fresh DB, deferring migrations to
+  // after createServices would 42P01 the boot.
+  //
+  // DIVERGENCE vs bevel-platform's copy of this file (Phase C reconciliation):
+  // upstream still calls the legacy single-folder `runMigrations(db)`; this
+  // package runs its own squashed idempotent CORE history from the packaged
+  // `migrations/` folder, tracked in `__drizzle_migrations_core`. An
+  // enterprise overlay runs its own history AFTER this (see migrate.ts).
+  await runCoreMigrations(db, coreMigrationsDir());
+  const workspaceService = new WorkspaceService(
+    config.workspacesRoot,
+    config.kbRepoUrl,
+    config.kbDirName,
+    config.gitUsername,
+  );
+  // Seed (or top-up) the KB remote before the first clone so the rest of the app
+  // can keep assuming the remote already carries the protected branches + base
+  // scaffolding — a fresh or partially-populated remote no longer needs to have
+  // been forked from the standalone template.
+  const kbSeedService = new KbSeedService(
+    config.kbRepoUrl,
+    config.kbTemplateDir,
+    [...PROTECTED_BRANCHES],
+    DEFAULT_BRANCH,
+    config.seedAdminEmails,
+    config.gitUsername,
+  );
+  workspaceService.setSeedService(kbSeedService);
+  // Shared, workspace-independent store for oversized `call_tool_chain` results,
+  // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
+  const spillStore = new SpillStore(config.spillRoot);
+  const accessControl = new AccessControlService(workspaceService, config.kbDirName);
+  // Creator read-grant on creation: read is default-deny, so every surface
+  // that creates KB files/folders (human routes, agent tools, upload apply)
+  // consults this planner to keep creations visible to their creator.
+  const creatorAccess = new CreatorAccessService(workspaceService, accessControl, config.kbDirName);
+
+  // Ontology-session boundary: records each agent run's touched ontologies and
+  // blocks writes once a run has crossed ontologies. Postgres-backed so the
+  // boundary survives a restart.
+  const sessionOntologyService = new SessionOntologyService(db);
+  // Per-run write restriction (by file extension). Shared by the workspace tool
+  // surface (which enforces it) and the routine runner (which sets it for
+  // dashboard-only `watchlist_check` runs). In-memory: a restriction lives only for
+  // one run, unlike the Postgres-backed ontology touched-set above.
+  const routineWritePolicy = new RoutineWritePolicyService();
+  // Skills: discovered from the default-branch workspace only (global catalog).
+  const skillService = new SkillService(workspaceService, accessControl, config.kbDirName);
+  // Tool manuals: user-authored `*.tool` files under `Tools/` in the default
+  // branch — access-controlled like Skills, served to external agents via
+  // `GET /api/agent/all-tools` and registered on the MCP proxy's UTCP client.
+  const toolManualService = new ToolManualService(workspaceService, accessControl, config.kbDirName);
+  // Auth service — resolves identities for login, PR author attribution, and
+  // access lookups. (Change requests now store the author email directly, so
+  // PullRequestService no longer depends on it for attribution.)
+  const authService = new AuthService(db, config);
+  const authMiddleware = createAuthMiddleware(authService);
+
+  // Shared mutex so git and diff operations on the same workspace serialize
+  // against each other — a backup-reseed races a concurrent commit otherwise.
+  const workspaceMutex = new WorkspaceMutex();
+  // Workflow lifecycle hooks — the ONE registry this composition shares
+  // between GitService (advisory commit validation), the session-ontology
+  // gate (blocking preWrite), and the enterprise composition root, which
+  // registers module-owned handlers on `workflowService.hooks` right after
+  // this function returns. Core registers none: no commit-time validation
+  // (advisory anyway) and no ontology write block.
+  const workflowHooks = new WorkflowHooks();
+  const gitService = new GitService(
+    workspaceService,
+    workflowHooks,
+    config.kbDirName,
+    workspaceMutex,
+    accessControl,
+  );
+  // A fresh clone has already fetched every ref — let the git layer skip the
+  // redundant implicit `git fetch` on the first `listBranches` after bootstrap.
+  workspaceService.setWorkspaceClonedListener((id) => gitService.noteWorkspaceFetched(id));
+  const pullRequestService = new PullRequestService(
+    db,
+    workspaceService,
+    accessControl,
+    gitService,
+  );
+  const diffService = new DiffService(
+    workspaceService,
+    workspaceMutex,
+    config.workspacesRoot,
+    config.backupsRoot,
+    config.kbDirName,
+  );
+  // Late-bind the diff service into WorkspaceService so file writes/moves
+  // trigger backup updates. (GitService used to take a diffService too — for
+  // the post-switch backup reseed — but switchBranch is gone with the
+  // per-branch workspace model, so the injection no longer applies.)
+  workspaceService.setDiffService(diffService);
+  const reviewWorkflowService = new ReviewWorkflowService(
+    db,
+    accessControl,
+    workspaceService,
+    gitService,
+  );
+  // Late-bind the comment enricher so PullRequestService.getPrDetail includes
+  // our DB-backed comments without forcing a circular constructor dependency.
+  pullRequestService.setDetailEnricher(reviewWorkflowService);
+
+  // Workflow facade — the abstraction every app consumer should reach for
+  // instead of the individual git / PR / review-workflow services. See
+  // PLAN.md for the migration story. Today it delegates straight through;
+  // implementations migrate into the workflow module over later steps.
+  const fileLockService = new FileLockService(db);
+  // Background commit queue. The `WorkflowService.releaseLock` path
+  // enqueues a row here instead of running commitFile + push inline; the
+  // worker drains the queue out of band so a git hiccup can't block the
+  // user-visible save path. See `lock-decoupling-plan.md`.
+  const pendingCommitsService = new PendingCommitsService(db);
+  // Let the git status path tell an expected dirty tree (queued saves still
+  // draining) from a genuinely orphaned one before it warns loudly.
+  gitService.setPendingCommitsProbe((workspaceId) =>
+    pendingCommitsService.hasAnyForWorkspace(workspaceId),
+  );
+  // In-process event bus: every WorkflowService mutation method that
+  // succeeds emits a typed event; the SSE route fans it to connected
+  // browser sessions. Single instance per Node process — survives across
+  // requests, doesn't survive restarts (clients reconnect + resync).
+  const eventBus = new WorkflowEventBus();
+  // In-process post-commit hook (distinct from the SSE bus): fires once per
+  // committed change (batched paths) so catalogs refresh instantly and the
+  // id-repair keeps the id namespace collision-free. Subscribers are registered
+  // below, once the reacting services exist.
+  const fileChangeNotifier = new FileChangeNotifier();
+  const workflowService = new WorkflowService(
+    db,
+    gitService,
+    pullRequestService,
+    reviewWorkflowService,
+    workspaceService,
+    accessControl,
+    fileLockService,
+    pendingCommitsService,
+    config.kbDirName,
+    eventBus,
+    fileChangeNotifier,
+    // Exposed as `workflowService.hooks` — the SAME instance GitService and
+    // the session-ontology gate consult, so enterprise registrations against
+    // it reach every hook point.
+    workflowHooks,
+  );
+
+  // Subscriber A — catalog freshness: a committed change drops the affected
+  // caches immediately instead of waiting out their TTLs. The tool/skill
+  // catalogs are global but read the DEFAULT branch only, so only
+  // default-branch changes under their folders matter. (The kb-graph id-index
+  // invalidation that used to live in this subscriber is registered by the
+  // enterprise overlay, next to the kb-graph service it belongs to — the
+  // caches are independent, so the split preserves behavior.)
+  fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
+    if (branch !== DEFAULT_BRANCH) return;
+    if (paths.some((p) => p.startsWith(`${config.kbDirName}/${TOOLS_DIR}/`))) toolManualService.invalidate();
+    if (paths.some((p) => p.startsWith(`${config.kbDirName}/${SKILLS_DIR}/`))) skillService.invalidate();
+  });
+
+  // Admin = `Admin` role in roles.yaml, resolved through the access model on the
+  // default branch (no env allow-list).
+  const adminAccess = new AdminAccessService(accessControl, workspaceService, DEFAULT_BRANCH);
+
+  // Secrets Vault: the per-user store of credentials (static API keys + OAuth
+  // tokens) that back UTCP tool variables (`${FOO_API_KEY}`). Encrypted at rest
+  // with the connector-config key; read only by the `bevel-secrets` variable
+  // loader at tool-call time. Swap-seam: `ISecretsVaultService` could later be a
+  // client's external secret manager without touching the loader or the tools.
+  const secretsVaultService = new DbSecretsVaultService(
+    db,
+    config.secretsEncKey,
+    undefined,
+    // Scope-driven resolution: a `.tool`'s declared variable scope decides whether
+    // `resolve` reads the shared (admin) row or the caller's own per-user row.
+    (key) => toolManualService.scopeOfVariable(key),
+  );
+  // Register the `bevel-secrets` UTCP variable loader against this vault so any
+  // UTCP client can resolve `${VAR}` from the caller's secrets at tool-call time.
+  registerBevelSecretsVariableLoader(secretsVaultService);
+
+  // Zero-config OAuth for bare `type: mcp` `.tool`s: when the remote server
+  // demands OAuth (MCP authorization spec), discover its authorization server,
+  // dynamically register a public PKCE client, and persist the provider as the
+  // shared vault row — the tool catalog then decorates the manual with a
+  // synthetic per-user sign-in. Setter-injected: this service needs the vault,
+  // which is constructed after the tool-manual service.
+  const mcpOAuthDiscovery = new McpOAuthDiscoveryService({
+    secretsVault: secretsVaultService,
+    redirectUri: `${config.publicBackendUrl}/api/secrets/oauth/callback`,
+  });
+  toolManualService.setMcpAuthDiscovery(mcpOAuthDiscovery);
+
+  // Least-privilege internal tokens: minted per (workspace, user, scope) by the
+  // agents' code-mode clients and by the MCP proxy, verified by the tool-auth
+  // middleware below — the same instance must back both sides.
+  const internalTokenService = new InternalTokenService({ prefix: config.internalTokenPrefix });
+
+  // GDPR erasure path: admin-driven user deletion. The core service erases the
+  // rows it owns; each module contributes its slice as a participant.
+  const accountErasureService = new AccountErasureService(db, ports.erasureParticipants ?? []);
+
+  // MCP (remote agent access). ExternalApiKeyService handles connection-key
+  // lifecycle; McpSessionStore holds per-session userId in memory
+  // (single-replica — see docs/mcp-remote-access.md). McpService is now a
+  // GENERIC proxy: per session it discovers the UTCP manual at /api/agent/utcp
+  // over loopback and re-exposes every tool, dispatching calls back through the
+  // REST tool surface (so agent logic + metering live there, once).
+  const externalApiKeyService = new ExternalApiKeyService(db, config.externalApiKeyPrefix);
+  const mcpSessionStore = new McpSessionStore();
+  const mcpService = new McpService(
+    mcpSessionStore,
+    {
+      // Loopback to our own REST tool surface — 127.0.0.1 (not localhost) to pin
+      // IPv4 and dodge resolver ambiguity. The proxy authenticates each call with
+      // the caller's own connection key.
+      loopbackBaseUrl: `http://127.0.0.1:${config.port}`,
+      // Manual namespace + UTCP variable prefix (KNOWLEDGE_BASE_API_URL / …).
+      manualName: 'KNOWLEDGE_BASE',
+      // Oversized chain results spill here too — an external MCP session has no
+      // ambient workspace, so it reads the spill back by ref via `read_file`.
+      spillStore,
+      // For the needs-authorization setup link surfaced to external agents.
+      publicFrontendUrl: config.publicFrontendUrl,
+    },
+    // Pre-dispatch per-user credential check: the vault answers "has this caller
+    // set it?" and the manual catalog answers "which user-scoped vars does this
+    // tool need?".
+    secretsVaultService,
+    toolManualService,
+    // Loopback bearer mint for OAuth/JWT sessions — their own bearer would
+    // 401 at the connection-key/internal-only /api/agent/* hop.
+    internalTokenService,
+    // Session-grant reset for broken tool sign-ins. A closure because the
+    // provider is constructed just below (it needs nothing from McpService;
+    // the binding is only dereferenced at call time, long after boot).
+    (bearer) => mcpOAuthProvider.revokeByAccessToken(bearer),
+  );
+  // MCP OAuth 2.1 authorization server (our own AS): lets MCP clients with no
+  // pre-shared connection key connect via the standard 401 → discovery → DCR →
+  // authorize (PKCE) flow. The authorize step routes the browser to /connect
+  // where the user configures their tools; the resulting access token resolves
+  // to that user in the MCP auth middleware, like a connection key.
+  const mcpOAuthProvider = new BevelOAuthProvider({
+    db,
+    crypto: config.secretsEncKey ? new TokenCrypto(config.secretsEncKey) : null,
+    stateSecret: config.jwtSecret,
+    publicFrontendUrl: config.publicFrontendUrl,
+    tokenPrefix: config.mcpOAuthTokenPrefix,
+  });
+  // RFC 9728 pointer carried on every MCP 401 challenge so OAuth-capable
+  // clients discover the AS. Single source of truth for the resource id.
+  const mcpResourceUrl = new URL('/api/mcp', config.publicBackendUrl);
+  const mcpResourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(mcpResourceUrl);
+  const mcpAuthMiddleware = createMcpAuthMiddleware(
+    authService,
+    externalApiKeyService,
+    mcpOAuthProvider,
+    mcpResourceMetadataUrl,
+  );
+
+  // ── Unified tool surface ──────────────────────────────────────────────
+  // ONE catalog of self-describing UTCP tools, served as two manuals (external
+  // for CI/MCP; internal for our agent's loopback code-mode client) and hosted
+  // by each owning module behind shared auth + context utilities. The core
+  // server assembles the router (registers tool defs + mounts endpoints). The
+  // `internalTokenService` minted above (shared with the agent factories) is
+  // the same one the tool-auth middleware verifies internal tokens against.
+  const toolRegistry = new ToolRegistry();
+  const resolveToolContext = createToolContextResolver({
+    authService,
+    workspaceService,
+    workflowService,
+    events: eventBus,
+    kbDirName: config.kbDirName,
+    creatorAccess,
+  });
+  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext);
+  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService);
+  // Read-only manual endpoints accept the above PLUS a browser JWT, so a
+  // logged-in user can browse the catalog with their session. Execution routes
+  // keep `toolAuthMiddleware` (no JWT), so a session can read but not invoke.
+  const manualAuthMiddleware = createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService);
+
+  // Recovery-bot identity: a synthetic `recovery-bot@bevel.local` user
+  // backing (a) the recovery agent's commit authorship and (b) the
+  // `'system'` feedback notice's user_id FK. Idempotent ensure so this
+  // is safe to call on every boot.
+  const recoveryBot = await ensureRecoveryBotUser(db);
+
+  // Background commit worker. Drains `pending_commits` rows that the
+  // refactored `releaseLock` enqueues. On terminal failure (transient
+  // retry budget AND recovery-agent budget exhausted) the worker emits
+  // a `'system'` feedback notice that admins triage out of band.
+  //
+  // The orphan-startup sweep runs BEFORE start() so any rows that
+  // previous deploys left as `running` (process crashed mid-commit) get
+  // reset to `pending` before the worker starts claiming. The sweep
+  // also enqueues working-tree dirt that pre-dates the queue (the
+  // existing `target-company-state` orphans).
+  await pendingCommitsService.startupReconcile(
+    workspaceService.knownWorkspaces(),
+    { scan: (ws) => workspaceService.scanOrphanedPaths(ws.id) },
+    { email: recoveryBot.email, name: recoveryBot.name },
+  );
+  const pendingCommitsWorker = new PendingCommitsWorker({
+    service: pendingCommitsService,
+    workflow: {
+      runPendingCommit: (workspaceId, branch, path, user) =>
+        workflowService.runPendingCommit(workspaceId, branch, path, user),
+    },
+    // Both escalation sinks come through CorePorts: the recovery agent and the
+    // notice sink are enterprise-owned (background-agent factory / feedback
+    // dashboard); core defaults skip recovery and log to stderr.
+    recoveryAgent: ports.recoveryAgent ?? noopRecoveryAgent,
+    feedback: ports.systemNotice ?? consoleSystemNoticeSink,
+    workspaces: {
+      knownWorkspaces: () => workspaceService.knownWorkspaces(),
+    },
+    recoveryBot: {
+      id: recoveryBot.id,
+      email: recoveryBot.email,
+      name: recoveryBot.name,
+    },
+  });
+  pendingCommitsWorker.start();
+
+  return {
+    config,
+    db,
+    workspaceService,
+    kbSeedService,
+    spillStore,
+    accessControl,
+    creatorAccess,
+    sessionOntologyService,
+    routineWritePolicy,
+    skillService,
+    toolManualService,
+    authService,
+    authMiddleware,
+    accountErasureService,
+    gitService,
+    pullRequestService,
+    diffService,
+    reviewWorkflowService,
+    fileLockService,
+    workflowService,
+    eventBus,
+    fileChangeNotifier,
+    pendingCommitsService,
+    pendingCommitsWorker,
+    recoveryBot,
+    adminAccess,
+    secretsVaultService,
+    externalApiKeyService,
+    internalTokenService,
+    mcpService,
+    mcpAuthMiddleware,
+    mcpOAuthProvider,
+    toolRegistry,
+    toolAuthMiddleware,
+    manualAuthMiddleware,
+    toolHandlerFactory,
+    // Server-time seams — defaults here; the enterprise overlay overwrites
+    // (or, for the array, pushes into) these after construction.
+    sessionSink: ports.sessionSink ?? new UuidSessionSink(),
+    usageMeter: ports.usageMeter ?? unmeteredLlmUsage,
+    authProviders: ports.authProviders ?? [],
+  };
+}