@kelpie/server 0.10.0 → 0.12.0

package/src/modules/partnerships/schema.ts

@@ -1,7 +1,9 @@
+import { sql } from 'drizzle-orm'
+import { check, date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+import { PIPELINE_KINDS } from '@kelpie/schemas'
 import type { CustomFieldValue } from '@kelpie/schemas'
-import { date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
 
-import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import { createdAt, oneOf, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
 import type { SearchVectorPart } from '../../lib/columns.ts'
 import { companies } from '../companies/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
@@ -32,6 +34,8 @@ export const partnerships = pgTable(
     successLooksLike: text('success_looks_like').notNull().default(''),
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
+    convertedTargetType: text('converted_target_type'),
+    convertedTargetId: text('converted_target_id'),
     // Workspace-defined fields, keyed by definition key. See people/schema.ts.
     customFields: jsonb('custom_fields')
       .$type<Readonly<Record<string, CustomFieldValue>>>()
@@ -53,6 +57,10 @@ export const partnerships = pgTable(
     index('partnerships_company_idx').on(table.companyId),
     index('partnerships_stage_idx').on(table.stageId),
     index('partnerships_search_idx').using('gin', table.searchVector),
+    check(
+      'partnerships_converted_target_type_check',
+      sql`${table.convertedTargetType} is null or ${oneOf('partnerships_converted_target_type_check', table.convertedTargetType, PIPELINE_KINDS)}`,
+    ),
   ],
 )
 

package/src/modules/partnerships/service.ts

@@ -21,6 +21,7 @@ import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import { clearConversionPointersToTarget } from '../conversions/clearPointers.ts'
 import * as companyRepository from '../companies/repository.ts'
 import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
 import * as personLinks from '../personLinks.ts'
@@ -499,6 +500,8 @@ export function createPartnershipsService(
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
+        await clearConversionPointersToTarget(tx, workspaceId, 'partnership', id)
+
         // Notes, activities, decisions, plan items, and person_links have no
         // key back to the partnership, so they are removed here, in the same
         // transaction.

package/src/modules/partnerships/tools.ts

@@ -2,6 +2,8 @@ import { z } from 'zod'
 
 import type { McpToolRegistry } from '../../runtime/module.ts'
 import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import type { ConversionsService } from '../conversions/index.ts'
+import { registerPipelineConvertTool } from '../conversions/mcp.ts'
 import { createBody, partnershipResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
 import type { PartnershipsService } from './service.ts'
 
@@ -16,7 +18,11 @@ const listArgs = z.strictObject({
   person_id: idSetArg.optional().describe('Only partnerships one of these people is a contact on.'),
 })
 
-export function registerPartnershipsTools(mcp: McpToolRegistry, service: PartnershipsService): void {
+export function registerPartnershipsTools(
+  mcp: McpToolRegistry,
+  service: PartnershipsService,
+  conversions: ConversionsService,
+): void {
   registerCrudTools(mcp, {
     resource: 'partnerships',
     subject: 'partnership',
@@ -38,4 +44,6 @@ export function registerPartnershipsTools(mcp: McpToolRegistry, service: Partner
     updateArgs: updateBody.extend({ id: idArg }),
     toUpdateInput,
   })
+
+  registerPipelineConvertTool(mcp, conversions, 'partnership')
 }

package/src/modules/people/personConsentWrites.ts

@@ -8,7 +8,7 @@ import { personConsents } from './schema.ts'
 
 /**
  * Writes to `person_consents`, shared by the manual PATCH override and every
- * capture site (forms, lists, imports). Every write is idempotent — a second
+ * capture site (forms, imports). Every write is idempotent — a second
  * grant for the same (person, purpose) with the same source is a no-op.
  *
  * `source` follows the shape in `docs/privacy.md`:

package/src/modules/people/schema.ts

@@ -84,7 +84,7 @@ export const people = pgTable(
     lastContactedAt: moment('last_contacted_at'),
     // The Article 21 objection. A global do-not-contact signal, independent
     // of consent purposes: agents check this before outreach regardless of
-    // per-purpose consent state. Never touched by forms, lists, or imports —
+    // per-purpose consent state. Never touched by forms or imports —
     // the workspace member owns this flag.
     doNotContact: boolean('do_not_contact').notNull().default(false),
     // Workspace-defined fields, keyed by definition key. The custom-fields

package/src/modules/plans/repository.ts

@@ -158,6 +158,30 @@ export async function deleteForTarget(
   return deleted.length
 }
 
+/** Moves every plan item from one target to another inside a conversion transaction. */
+export async function repointForTarget(
+  db: Queryable,
+  workspaceId: string,
+  fromType: string,
+  fromId: string,
+  toType: string,
+  toId: string,
+): Promise<number> {
+  const updated = await db
+    .update(planItems)
+    .set({ targetType: toType, targetId: toId })
+    .where(
+      and(
+        eq(planItems.workspaceId, workspaceId),
+        eq(planItems.targetType, fromType),
+        eq(planItems.targetId, fromId),
+      ),
+    )
+    .returning({ id: planItems.id })
+
+  return updated.length
+}
+
 /** Whether a member belongs to this workspace, for validating `owner_id`. */
 export async function memberExists(
   db: Queryable,

package/src/modules/raises/events.ts

@@ -12,6 +12,10 @@ export const raisesEvents = {
     fromStageId: z.string().nullable(),
     toStageId: z.string(),
   }),
+  'raises.raise.converted': z.object({
+    targetType: z.string(),
+    targetId: z.string(),
+  }),
 } satisfies ModuleEventCatalog
 
 export type RaiseCreatedData = Record<string, never>
@@ -23,6 +27,10 @@ export interface RaiseStageChangedData {
   readonly fromStageId: string | null
   readonly toStageId: string
 }
+export interface RaiseConvertedData {
+  readonly targetType: string
+  readonly targetId: string
+}
 
 declare module '../../runtime/events.ts' {
   interface KelpieEventMap {
@@ -30,5 +38,6 @@ declare module '../../runtime/events.ts' {
     'raises.raise.updated': RaiseUpdatedData
     'raises.raise.deleted': RaiseDeletedData
     'raises.raise.stage_changed': RaiseStageChangedData
+    'raises.raise.converted': RaiseConvertedData
   }
 }

package/src/modules/raises/index.ts

@@ -1,5 +1,6 @@
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createActivityRecorder } from '../activities/index.ts'
+import { createConversionsFromContext } from '../conversions/index.ts'
 import { createCustomFieldValues } from '../custom-fields/index.ts'
 import { raisesEvents } from './events.ts'
 import { mountRaisesRoutes } from './routes.ts'
@@ -22,6 +23,7 @@ export function createRaisesModule(migrationsDirectory: string): KelpieModule {
     events: raisesEvents,
 
     register(context) {
+      const conversions = createConversionsFromContext(context)
       const service = createRaisesService({
         db: context.db,
         transaction: context.transaction,
@@ -37,10 +39,10 @@ export function createRaisesModule(migrationsDirectory: string): KelpieModule {
       context.schema(schema, migrationsDirectory)
 
       context.routes((router) => {
-        mountRaisesRoutes(router, { db: context.db, now: context.now, service })
+        mountRaisesRoutes(router, { db: context.db, now: context.now, service, conversions })
       })
 
-      registerRaisesTools(context.mcp, service)
+      registerRaisesTools(context.mcp, service, conversions)
 
       return Promise.resolve()
     },

package/src/modules/raises/routes.ts

@@ -1,4 +1,4 @@
-import { customFieldsPatchShape } from '@kelpie/schemas'
+import { convertPipelineRecordBody, convertedToResponse, customFieldsPatchShape } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 import { z } from 'zod'
 
@@ -8,6 +8,8 @@ import type { Actor } from '../auth/actor.ts'
 import { resolveActorFrom } from '../auth/credentials.ts'
 import type { CredentialDependencies } from '../auth/credentials.ts'
 import { renderCustomFieldsForWire } from '../custom-fields/wire.ts'
+import { mountPipelineConvertRoute } from '../conversions/routes.ts'
+import type { ConversionsService } from '../conversions/index.ts'
 import type { CreateRaiseInput, RaiseView, RaisesService, UpdateRaiseInput } from './service.ts'
 
 /** Wire shapes for `/v1/raises`. Bodies are strict; an unknown field is a 422, per `api.md`. */
@@ -58,6 +60,7 @@ export const updateBody = z.strictObject(raiseShape).partial()
 
 export interface RaisesRoutesDependencies extends CredentialDependencies {
   readonly service: RaisesService
+  readonly conversions: ConversionsService
 }
 
 export function toCreateInput(body: z.infer<typeof createBody>): CreateRaiseInput {
@@ -111,6 +114,7 @@ export function raiseResponse(raise: RaiseView): Record<string, unknown> {
     person_ids: raise.personIds,
     summary: raise.summary,
     tags: raise.tags,
+    converted_to: convertedToResponse(raise.convertedTargetType, raise.convertedTargetId),
     custom_fields: renderCustomFieldsForWire(raise.customFields),
     created_at: raise.createdAt.toISOString(),
     updated_at: raise.updatedAt.toISOString(),
@@ -164,4 +168,10 @@ export function mountRaisesRoutes(router: Hono, dependencies: RaisesRoutesDepend
 
     return context.body(null, 204)
   })
+
+  mountPipelineConvertRoute(router, '/raises/:id/convert', {
+    ...dependencies,
+    sourceKind: 'raise',
+    bodySchema: convertPipelineRecordBody,
+  })
 }

package/src/modules/raises/schema.ts

@@ -1,7 +1,9 @@
+import { sql } from 'drizzle-orm'
+import { check, bigint, date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
+import { PIPELINE_KINDS } from '@kelpie/schemas'
 import type { CustomFieldValue } from '@kelpie/schemas'
-import { bigint, date, index, jsonb, pgTable, text } from 'drizzle-orm/pg-core'
 
-import { createdAt, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
+import { createdAt, oneOf, primaryId, searchVector, updatedAt } from '../../lib/columns.ts'
 import type { SearchVectorPart } from '../../lib/columns.ts'
 import { companies } from '../companies/schema.ts'
 import { pipelineStages } from '../pipelines/schema.ts'
@@ -34,6 +36,8 @@ export const raises = pgTable(
     expectedClose: date('expected_close'),
     summary: text('summary').notNull().default(''),
     tags: text('tags').array().notNull().default([]),
+    convertedTargetType: text('converted_target_type'),
+    convertedTargetId: text('converted_target_id'),
     // Workspace-defined fields, keyed by definition key. See people/schema.ts.
     customFields: jsonb('custom_fields')
       .$type<Readonly<Record<string, CustomFieldValue>>>()
@@ -54,6 +58,10 @@ export const raises = pgTable(
     index('raises_company_idx').on(table.companyId),
     index('raises_stage_idx').on(table.stageId),
     index('raises_search_idx').using('gin', table.searchVector),
+    check(
+      'raises_converted_target_type_check',
+      sql`${table.convertedTargetType} is null or ${oneOf('raises_converted_target_type_check', table.convertedTargetType, PIPELINE_KINDS)}`,
+    ),
   ],
 )
 

package/src/modules/raises/service.ts

@@ -21,6 +21,7 @@ import type { Actor } from '../auth/actor.ts'
 import { actorMemberId, requireWorkspaceId } from '../auth/actor.ts'
 import './events.ts'
 import { deleteRecordsAttachedTo } from '../attachedRecords.ts'
+import { clearConversionPointersToTarget } from '../conversions/clearPointers.ts'
 import * as companyRepository from '../companies/repository.ts'
 import type { CustomFieldValuesValidator } from '../custom-fields/values.ts'
 import * as personLinks from '../personLinks.ts'
@@ -499,6 +500,8 @@ export function createRaisesService(dependencies: RaisesDependencies): RaisesSer
       await dependencies.transaction(async ({ tx, events }) => {
         await require(workspaceId, id)
 
+        await clearConversionPointersToTarget(tx, workspaceId, 'raise', id)
+
         // Notes, activities, decisions, plan items, and person_links have no key back to the raise;
         // activities, decisions and plan items have no key, so they are removed
         // here, in the same transaction.

package/src/modules/raises/tools.ts

@@ -2,6 +2,8 @@ import { z } from 'zod'
 
 import type { McpToolRegistry } from '../../runtime/module.ts'
 import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import type { ConversionsService } from '../conversions/index.ts'
+import { registerPipelineConvertTool } from '../conversions/mcp.ts'
 import { createBody, raiseResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
 import type { RaisesService } from './service.ts'
 
@@ -15,7 +17,11 @@ const listArgs = z.strictObject({
   person_id: idSetArg.optional().describe('Only raises one of these people is key on.'),
 })
 
-export function registerRaisesTools(mcp: McpToolRegistry, service: RaisesService): void {
+export function registerRaisesTools(
+  mcp: McpToolRegistry,
+  service: RaisesService,
+  conversions: ConversionsService,
+): void {
   registerCrudTools(mcp, {
     resource: 'raises',
     subject: 'raise',
@@ -36,4 +42,6 @@ export function registerRaisesTools(mcp: McpToolRegistry, service: RaisesService
     updateArgs: updateBody.extend({ id: idArg }),
     toUpdateInput,
   })
+
+  registerPipelineConvertTool(mcp, conversions, 'raise')
 }

package/src/modules/workspace/routes.ts

@@ -26,8 +26,6 @@ export const updateBody = z
     name: z.string().min(1),
     slug: z.string().min(1).max(63).regex(slugPattern, 'Use lowercase letters, digits, and hyphens'),
     timezone: timezoneSchema,
-    tagline: z.string().nullable(),
-    one_liner: z.string().nullable(),
   })
   .partial()
 
@@ -65,8 +63,6 @@ export function workspaceResponse(workspace: WorkspaceView): Record<string, unkn
     name: workspace.name,
     slug: workspace.slug,
     timezone: workspace.timezone,
-    tagline: workspace.tagline,
-    one_liner: workspace.oneLiner,
   }
 }
 
@@ -122,8 +118,6 @@ export function mountWorkspaceRoutes(router: Hono, dependencies: WorkspaceRoutes
       ...(body.name === undefined ? {} : { name: body.name }),
       ...(body.slug === undefined ? {} : { slug: body.slug }),
       ...(body.timezone === undefined ? {} : { timezone: body.timezone }),
-      ...(body.tagline === undefined ? {} : { tagline: body.tagline }),
-      ...(body.one_liner === undefined ? {} : { oneLiner: body.one_liner }),
     })
 
     return context.json(workspaceResponse(workspace))

package/src/modules/workspace/schema.ts

@@ -14,8 +14,6 @@ export const workspaces = pgTable('workspaces', {
   name: text('name').notNull(),
   slug: text('slug').notNull().unique(),
   timezone: text('timezone').notNull(),
-  tagline: text('tagline'),
-  oneLiner: text('one_liner'),
   createdAt: createdAt(),
   updatedAt: updatedAt(),
 })

package/src/modules/workspace/seedStarterForms.ts

@@ -0,0 +1,98 @@
+import type { IdFactory } from '../../lib/ids.ts'
+import type { Transaction } from '../../runtime/transaction.ts'
+import { STARTER_FORMS } from '../forms/starters.ts'
+import type { StarterConsentPurposeSlug, StarterListSlug } from '../forms/starters.ts'
+import * as formsRepository from '../forms/repository.ts'
+import { STARTER_LISTS } from '../lists/starters.ts'
+import * as listsRepository from '../lists/repository.ts'
+
+export interface SeedStarterFormsInput {
+  readonly workspaceId: string
+  readonly createId: IdFactory
+  readonly generatePublicKey: () => string
+  readonly consentPurposeIdsBySlug: Readonly<Partial<Record<StarterConsentPurposeSlug, string>>>
+}
+
+/**
+ * Inserts the starter lists and forms for a new workspace.
+ *
+ * Called from `WorkspaceService.create()` in the same transaction as handbook
+ * pages and consent purposes, so a reader never lands in an empty forms list.
+ */
+export async function seedStarterForms(
+  tx: Transaction,
+  input: SeedStarterFormsInput,
+): Promise<void> {
+  const listIdsBySlug = new Map<StarterListSlug, string>()
+
+  for (const list of STARTER_LISTS) {
+    const id = input.createId('list')
+    await listsRepository.insertList(tx, {
+      id,
+      workspaceId: input.workspaceId,
+      name: list.name,
+      description: null,
+      targetType: list.targetType,
+    })
+    listIdsBySlug.set(list.slug as StarterListSlug, id)
+  }
+
+  for (const form of STARTER_FORMS) {
+    const formId = input.createId('form')
+    await formsRepository.insertForm(tx, {
+      id: formId,
+      workspaceId: input.workspaceId,
+      name: form.name,
+      title: form.title,
+      description: form.description,
+      status: 'active',
+      thankYouMessage: form.thankYouMessage,
+      publicKey: input.generatePublicKey(),
+    })
+
+    await formsRepository.insertFields(
+      tx,
+      form.fields.map((field, index) => {
+        const consentPurposeIds =
+          field.consentPurposeSlug === undefined
+            ? []
+            : (() => {
+                const purposeId = input.consentPurposeIdsBySlug[field.consentPurposeSlug]
+                if (purposeId === undefined) {
+                  throw new Error(
+                    `Starter form ${form.slug} names unknown consent purpose ${field.consentPurposeSlug}`,
+                  )
+                }
+                return [purposeId]
+              })()
+
+        return {
+          id: input.createId('formField'),
+          workspaceId: input.workspaceId,
+          formId,
+          label: field.label,
+          type: field.type,
+          required: field.required,
+          mapTo: field.mapTo,
+          options: [],
+          placeholder: field.placeholder ?? null,
+          statement: field.statement ?? null,
+          consentPurposeIds,
+          consentPurposeLabels: {},
+          sortOrder: index,
+        }
+      }),
+    )
+
+    const linkedListId =
+      form.linkedListSlug === undefined ? undefined : listIdsBySlug.get(form.linkedListSlug)
+
+    if (form.linkedListSlug !== undefined && linkedListId === undefined) {
+      throw new Error(`Starter form ${form.slug} names unknown list ${form.linkedListSlug}`)
+    }
+
+    if (linkedListId !== undefined) {
+      await formsRepository.replaceFormLists(tx, input.workspaceId, formId, [linkedListId])
+    }
+  }
+}

package/src/modules/workspace/service.ts

@@ -17,6 +17,7 @@ import * as authRepository from '../auth/repository.ts'
 import { SEATS_LIMIT } from './capabilities.ts'
 import { STARTER_CONSENT_PURPOSES } from '../consent-purposes/starters.ts'
 import * as repository from './repository.ts'
+import { seedStarterForms } from './seedStarterForms.ts'
 import { parseInvitableRole, parseMemberRole, roleAllows } from './roles.ts'
 import type { InvitableRole, InviteStatus, MemberRole } from './roles.ts'
 import {
@@ -55,8 +56,6 @@ export interface WorkspaceView {
   readonly name: string
   readonly slug: string
   readonly timezone: string
-  readonly tagline: string | null
-  readonly oneLiner: string | null
 }
 
 export interface MemberView {
@@ -104,8 +103,6 @@ export interface UpdateWorkspaceInput {
   readonly name?: string | undefined
   readonly slug?: string | undefined
   readonly timezone?: string | undefined
-  readonly tagline?: string | null | undefined
-  readonly oneLiner?: string | null | undefined
 }
 
 export interface WorkspaceService {
@@ -145,8 +142,6 @@ function toWorkspaceView(record: repository.WorkspaceRecord): WorkspaceView {
     name: record.name,
     slug: record.slug,
     timezone: record.timezone,
-    tagline: record.tagline,
-    oneLiner: record.oneLiner,
   }
 }
 
@@ -472,19 +467,32 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
           ),
         )
 
+        const consentPurposeIdsBySlug: Partial<Record<string, string>> = {}
+
         await repository.insertConsentPurposes(
           tx,
-          STARTER_CONSENT_PURPOSES.map((purpose, index) => ({
-            id: dependencies.createId('consentPurpose'),
-            workspaceId,
-            slug: purpose.slug,
-            label: purpose.label,
-            description: purpose.description,
-            defaultStatus: purpose.defaultStatus,
-            sortOrder: index,
-          })),
+          STARTER_CONSENT_PURPOSES.map((purpose, index) => {
+            const id = dependencies.createId('consentPurpose')
+            consentPurposeIdsBySlug[purpose.slug] = id
+            return {
+              id,
+              workspaceId,
+              slug: purpose.slug,
+              label: purpose.label,
+              description: purpose.description,
+              defaultStatus: purpose.defaultStatus,
+              sortOrder: index,
+            }
+          }),
         )
 
+        await seedStarterForms(tx, {
+          workspaceId,
+          createId: dependencies.createId,
+          generatePublicKey: generateToken,
+          consentPurposeIdsBySlug,
+        })
+
         // The session that created the workspace should land in it.
         await authRepository.setActiveWorkspace(tx, actor.sessionId, workspaceId)
 

package/src/modules/workspace/tools.ts

@@ -27,7 +27,7 @@ export function registerWorkspaceTools(mcp: McpToolRegistry, service: WorkspaceS
   mcp.tool({
     name: 'workspace_get',
     description:
-      'This workspace\'s name, slug, timezone, tagline and one-liner. Mirrors GET /v1/workspaces/{id}.',
+      'This workspace\'s name, slug, and timezone. Mirrors GET /v1/workspaces/{id}.',
     inputSchema: noArgs,
     invoke: async (_args, actor) =>
       workspaceResponse(await service.get(actor, requireWorkspaceId(actor))),

package/src/runtime/module.ts

@@ -1,4 +1,4 @@
-import type { Handler, Hono, MiddlewareHandler } from 'hono'
+import type { Context, Handler, Hono, MiddlewareHandler } from 'hono'
 import type { ZodType } from 'zod'
 
 import type { Actor } from '../lib/actor.ts'
@@ -58,6 +58,53 @@ export interface McpToolRegistry {
   tool<Input>(definition: McpToolDefinition<Input>): void
 }
 
+/**
+ * An identity a module verified somewhere else, handed back for core to sign in.
+ *
+ * Core never learns what OIDC or SAML is. Verification is the module's job and
+ * core does not redo it; core's job is that everything downstream of the cookie
+ * is identical to a password sign-in.
+ */
+export interface VerifiedIdentity {
+  readonly email: string
+  /** Core refuses the identity when false, rather than assuming the module checked. */
+  readonly emailVerified: boolean
+  /** The provider's display name, when it has one. The local part of the address is used otherwise. */
+  readonly name: string | null
+  /** Who verified it, recorded on the session: the module id, optionally suffixed (`sign-in:google`). */
+  readonly verifiedBy: string
+  /**
+   * What to do with an address core has never seen. The policy is the module's,
+   * because only it knows whether its provider vouches for strangers; executing
+   * it is core's.
+   */
+  readonly provision: 'create' | 'refuse'
+}
+
+/** The account a completed sign-in belongs to. */
+export interface CompletedSignInAccount {
+  readonly id: string
+  readonly email: string
+  readonly name: string
+  readonly emailVerified: boolean
+}
+
+export interface CompletedSignIn {
+  readonly account: CompletedSignInAccount
+  /** True when this sign-in provisioned the account rather than finding it. */
+  readonly created: boolean
+  readonly activeWorkspaceId: string | null
+}
+
+/**
+ * Completes a sign-in. Takes the Hono context because writing the session
+ * cookie on it is the point.
+ */
+export type ExternalSignInHandler = (
+  context: Context,
+  identity: VerifiedIdentity,
+) => Promise<CompletedSignIn>
+
 /**
  * What a module gets to build with, beyond its own contributions.
  *
@@ -119,6 +166,28 @@ export interface ModuleContext extends ModuleServices {
    * delegates to the provider `email.provider` picked.
    */
   readonly email: EmailSender
+  /**
+   * Installs the one implementation of external sign-in. Core's `auth` module
+   * calls this; a second caller fails boot.
+   *
+   * The same shape as `provideEmailSender`: a capability only one module owns,
+   * reached by every module through a proxy, so registration order does not
+   * matter to a consumer.
+   */
+  provideExternalSignIn(handler: ExternalSignInHandler): void
+  /**
+   * Completes a sign-in for an identity this module already verified: finds or
+   * provisions the account, issues a session, and writes the session cookie on
+   * `context`.
+   *
+   * The alternative is a module writing core's `sessions` table itself, which
+   * ties it to core's token hashing, cookie flags and expiry with nothing
+   * keeping the two in step (`modules.md`).
+   *
+   * @throws ExternalSignInError when the identity is unverified, or unknown and
+   *   the module asked for `provision: 'refuse'`.
+   */
+  completeExternalSignIn(context: Context, identity: VerifiedIdentity): Promise<CompletedSignIn>
   /**
    * Registers routes that mount under `/v1/public`, take no credentials, and
    * answer cross-origin requests from any site.