@crombolo/server 0.10.0 → 0.12.1

package/src/jobs.ts

@@ -1,16 +1,25 @@
 /**
  * Background jobs, as Umbraco runs them: scheduled publishing every minute and
- * version cleanup every hour when it is enabled. Each run can also be called directly, which is
+ * version cleanup every hour when it is enabled, plus the search indexer
+ * draining its queue and the audit log ageing out old entries hourly. Each run can also be called directly, which is
  * how tests drive them. On a multi-node Postgres site every node runs them;
- * each schedule is claimed atomically, so it runs once.
+ * each schedule and queued item is claimed atomically, so it runs once.
  */
 
 import type { NodeSchemaState } from '@crombolo/data'
-import { type Db, DocumentRepository, PublishBlockedError } from '@crombolo/data'
+import {
+  AuditLog,
+  type Db,
+  DocumentRepository,
+  PublishBlockedError,
+  SearchIndex,
+} from '@crombolo/data'
 import type { PublishedCache } from '@crombolo/render'
+import { auditRetainedSince, recordAudit } from './adapters/audit.ts'
 import type { WorkflowRunner, WorkflowRunReport } from './form-workflows.ts'
 import { logger } from './logging.ts'
 import type { MediaFileStore } from './media-files.ts'
+import type { WebhookService } from './webhooks.ts'
 
 export interface JobsOptions {
   db: Db
@@ -33,6 +42,13 @@ export interface JobsOptions {
    */
   formWorkflows?: WorkflowRunner
   formWorkflowsMs?: number
+  /** Raises the publishes scheduled publishing makes, and drains the delivery queue. */
+  webhooks?: Pick<WebhookService, 'raise' | 'runDue'>
+  webhooksMs?: number
+  /** How often the search indexer looks for queued items; a write here also starts it at once. */
+  searchIndexingMs?: number
+  /** Days the audit log keeps an entry; 0 or absent keeps them forever. */
+  auditRetentionDays?: number
 }
 
 export interface ScheduledRun {
@@ -45,6 +61,14 @@ export interface BackgroundJobs {
   runScheduledPublishing(now?: Date): Promise<ScheduledRun>
   /** Runs the form workflows that are due; a no-op when none are configured. */
   runFormWorkflows(now?: Date): Promise<WorkflowRunReport>
+  /** Delivers the webhook and bundle events that are due. */
+  runWebhooks(now?: Date): Promise<WorkflowRunReport>
+  /** Indexes every queued item, and returns how many. docs/search.md. */
+  runSearchIndexing(): Promise<number>
+  /** Something was queued here: index it shortly, rather than at the next tick. */
+  kickSearchIndexing(): void
+  /** Deletes audit entries older than the retention period, and returns how many. */
+  runAuditRetention(now?: Date): Promise<number>
   /** Runs whether or not the hourly job is enabled; the policy decides what goes. */
   runVersionCleanup(now?: Date): Promise<{ nodes: number; versionsDeleted: number }>
   start(): void
@@ -60,6 +84,9 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
   })
   const timers: Array<ReturnType<typeof setInterval>> = []
   let running = false
+  const search = new SearchIndex(options.db)
+  let indexing: Promise<number> | undefined
+  let kicked: ReturnType<typeof setTimeout> | undefined
 
   async function runScheduledPublishing(now = new Date()): Promise<ScheduledRun> {
     const run: ScheduledRun = { published: [], unpublished: [], failed: [] }
@@ -67,13 +94,20 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
       if (!(await documents.claimSchedule(due.id))) continue
       const cultures = due.culture ? [due.culture] : null
       try {
-        if (due.action === 'Release') {
-          await documents.publish(due.key, cultures)
-          run.published.push(due.key)
-        } else {
-          await documents.unpublish(due.key, cultures)
-          run.unpublished.push(due.key)
-        }
+        const release = due.action === 'Release'
+        const changed = release
+          ? await documents.publish(due.key, cultures)
+          : await documents.unpublish(due.key, cultures)
+        ;(release ? run.published : run.unpublished).push(due.key)
+        await recordAudit(options.db, {
+          category: 'content',
+          action: release ? 'Publish' : 'Unpublish',
+          source: 'job',
+          entityType: 'Document',
+          entityKey: due.key,
+          entityName: changed?.variants[0]?.name ?? null,
+          detail: `Scheduled${due.culture ? ` (${due.culture})` : ''}`,
+        })
         options.onDocumentChanged?.(due.key)
       } catch (error) {
         if (!(error instanceof PublishBlockedError)) throw error
@@ -81,13 +115,26 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
       }
     }
     if (run.published.length + run.unpublished.length > 0) options.cache.invalidate()
+    for (const key of run.published)
+      await options.webhooks?.raise({ alias: 'Umbraco.ContentPublish', key })
+    for (const key of run.unpublished)
+      await options.webhooks?.raise({ alias: 'Umbraco.ContentUnpublish', key })
     return run
   }
 
+  async function runAuditRetention(now = new Date()): Promise<number> {
+    const before = auditRetainedSince(options.auditRetentionDays ?? 0, now)
+    return before ? new AuditLog(options.db).prune(before) : 0
+  }
+
   async function runVersionCleanup(now = new Date()) {
     return documents.cleanupVersions(now, options.versionCleanup)
   }
 
+  async function runWebhooks(now = new Date()): Promise<WorkflowRunReport> {
+    return (await options.webhooks?.runDue(now)) ?? { claimed: 0, done: 0, retrying: 0, failed: 0 }
+  }
+
   async function runFormWorkflows(now = new Date()): Promise<WorkflowRunReport> {
     return (
       (await options.formWorkflows?.runDue(now)) ?? {
@@ -99,6 +146,20 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
     )
   }
 
+  // Its own guard rather than `guarded`: indexing a big rebuild must not hold up
+  // a scheduled publish, and a kick while it runs joins the run in progress.
+  function runSearchIndexing(): Promise<number> {
+    indexing ??= search.indexAll().finally(() => {
+      indexing = undefined
+    })
+    return indexing
+  }
+
+  const indexQuietly = () =>
+    runSearchIndexing().catch((error: unknown) => {
+      logger('jobs').error('Search indexing failed', { error })
+    })
+
   const guarded = (job: () => Promise<unknown>) => async () => {
     if (running) return
     running = true
@@ -120,18 +181,38 @@ export function createBackgroundJobs(options: JobsOptions): BackgroundJobs {
   return {
     runScheduledPublishing,
     runVersionCleanup,
+    runAuditRetention,
     runFormWorkflows,
+    runWebhooks,
+    runSearchIndexing,
+    kickSearchIndexing() {
+      if (timers.length === 0 || kicked) return
+      kicked = setTimeout(() => {
+        kicked = undefined
+        void indexQuietly()
+      }, 250)
+      kicked.unref()
+    },
     start() {
       every(options.scheduledPublishingMs ?? 60_000, runScheduledPublishing)
+      // The queue is shared, so this also picks up what other nodes wrote.
+      const searchTimer = setInterval(indexQuietly, options.searchIndexingMs ?? 5_000)
+      searchTimer.unref()
+      timers.push(searchTimer)
       // More often than the other jobs: somebody waiting on a form notification
       // notices a minute, and a queue row is cheap to look for.
       if (options.formWorkflows) every(options.formWorkflowsMs ?? 15_000, runFormWorkflows)
+      // As often, for the same reason: a receiver that is waiting notices a minute.
+      if (options.webhooks) every(options.webhooksMs ?? 15_000, runWebhooks)
       if (options.versionCleanup.enabled) every(60 * 60_000, runVersionCleanup)
+      if (options.auditRetentionDays) every(60 * 60_000, runAuditRetention)
       const files = options.mediaFiles
       if (files) every(60 * 60_000, () => files.cleanupExpired())
     },
     stop() {
       for (const timer of timers.splice(0)) clearInterval(timer)
+      if (kicked) clearTimeout(kicked)
+      kicked = undefined
     },
     started() {
       return timers.length > 0

package/src/media-files.ts

@@ -262,12 +262,14 @@ export async function readBlobs(
 export async function placeBlobs(
   store: MediaStore,
   blobs: ReadonlyMap<string, string>,
+  /** Turns a carried file's bytes into the media file's: opens a sealed one. */
+  open: (key: string, bytes: Uint8Array) => Uint8Array = (_key, bytes) => bytes,
 ): Promise<{ placed: number; bytes: number }> {
   let placed = 0
   let bytes = 0
   for (const [key, path] of blobs) {
     const file = Bun.file(path)
-    const content = new Uint8Array(await file.arrayBuffer())
+    const content = open(key, new Uint8Array(await file.arrayBuffer()))
     await store.put(key, content, { contentType: contentTypeFor(key) })
     placed += 1
     bytes += content.length

package/src/member-auth.ts

@@ -22,6 +22,7 @@
 import {
   expireCookie,
   hashPassword,
+  isNativeHash,
   memberCookieName,
   passwordConfigJson,
   readCookie,
@@ -69,6 +70,8 @@ export interface MemberAuth {
   decide(content: PublishedContent, member: RequestMember | undefined): Promise<AccessDecision>
   /** Handles the member endpoints, or undefined when the path is not one. */
   handle(request: Request, pathname: string): Promise<Response | undefined>
+  /** The `Set-Cookie` value that ends a member's site session. */
+  signOutCookie(): string
 }
 
 const isFormPost = (request: Request) =>
@@ -249,10 +252,22 @@ export function createMemberAuth(
       await verifyPassword(input.password ?? '', await hashPassword(crypto.randomUUID()))
       return failed()
     }
-    if (!(await verifyPassword(input.password ?? '', member.passwordHash))) {
+    if (
+      !(await verifyPassword(input.password ?? '', member.passwordHash, {
+        passwordConfig: member.passwordConfig,
+        forMember: true,
+      }))
+    ) {
       await members.recordFailedLogin(member.key, config.maxFailedPasswordAttempts)
       return failed()
     }
+    // An imported Umbraco hash is replaced now the password is known to match it.
+    if (!isNativeHash(member.passwordHash))
+      await members.rehashPassword(
+        member.key,
+        await hashPassword(input.password ?? ''),
+        passwordConfigJson(),
+      )
     await members.recordLogin(member.key)
     return answer(
       request,
@@ -359,6 +374,7 @@ export function createMemberAuth(
   return {
     resolve,
     decide,
+    signOutCookie: () => expireCookie(cookie, config.secureCookies),
     async handle(request, pathname) {
       if (!pathname.startsWith(`${MEMBER_ROUTE_PREFIX}/`)) return undefined
       const action = pathname.slice(MEMBER_ROUTE_PREFIX.length + 1)

package/src/models-builder.ts

@@ -7,6 +7,7 @@
  * "out of date" is answered by generating the types and comparing them with
  * what is on disk, which cannot drift from the question being asked.
  */
+
 import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
@@ -15,9 +16,11 @@ import type {
   ModelsBuilderPort,
   OutOfDateStatus,
 } from '@crombolo/api-management'
+import type { FormTypes } from '@crombolo/core'
 import { generateTypes, loadSchemaDirectory, validateSchemaSet } from '@crombolo/schema'
 import type { CromboloConfig } from './config.ts'
 import { VERSION } from './config.ts'
+import { formTypesFor } from './form-types.ts'
 import { logger } from './logging.ts'
 
 /** The file `crombolo generate` writes, inside the schema directory. */
@@ -26,10 +29,10 @@ export const GENERATED_FILE = 'content-types.d.ts'
 export type Intended = { types: string } | { problems: string[] }
 
 /** What `crombolo generate` would write now, or the problems stopping it. */
-export function intendedTypes(schemaDir: string): Intended {
+export function intendedTypes(schemaDir: string, formTypes?: FormTypes): Intended {
   if (!existsSync(schemaDir)) return { problems: [`No schema directory at ${schemaDir}`] }
-  const loaded = loadSchemaDirectory(schemaDir)
-  const problems = [...loaded.problems, ...validateSchemaSet(loaded.set)]
+  const loaded = loadSchemaDirectory(schemaDir, { formTypes })
+  const problems = [...loaded.problems, ...validateSchemaSet(loaded.set, { types: formTypes })]
   if (problems.length > 0)
     return {
       problems: problems.map((p) => `${p.file}${p.path ? ` (${p.path})` : ''}: ${p.message}`),
@@ -40,8 +43,9 @@ export function intendedTypes(schemaDir: string): Intended {
 /** Undefined when the schema does not generate, so staleness is unknowable. */
 export async function compareModels(
   schemaDir: string,
+  formTypes?: FormTypes,
 ): Promise<{ outOfDate: boolean } | undefined> {
-  const intended = intendedTypes(schemaDir)
+  const intended = intendedTypes(schemaDir, formTypes)
   if ('problems' in intended) return undefined
   const target = join(schemaDir, GENERATED_FILE)
   if (!existsSync(target)) return { outOfDate: true }
@@ -50,7 +54,7 @@ export async function compareModels(
 }
 
 export function createModelsBuilderPort(
-  config: Pick<CromboloConfig, 'schemaDir'>,
+  config: Pick<CromboloConfig, 'schemaDir'> & Partial<Pick<CromboloConfig, 'bundles'>>,
 ): ModelsBuilderPort {
   // Umbraco keeps the last generation error in memory and shows it on the
   // dashboard; a build that succeeds clears it.
@@ -58,7 +62,7 @@ export function createModelsBuilderPort(
   const log = logger('models-builder')
 
   const describe = async (): Promise<ModelsBuilderInfo> => {
-    const compared = await compareModels(config.schemaDir)
+    const compared = await compareModels(config.schemaDir, formTypesFor(config))
     return {
       // The models are TypeScript source, written on request: Umbraco's mode for
       // exactly that. The client only explains its own four mode strings.
@@ -78,13 +82,13 @@ export function createModelsBuilderPort(
     info: describe,
 
     async status(): Promise<OutOfDateStatus> {
-      const compared = await compareModels(config.schemaDir)
+      const compared = await compareModels(config.schemaDir, formTypesFor(config))
       if (!compared) return 'Unknown'
       return compared.outOfDate ? 'OutOfDate' : 'Current'
     },
 
     async build() {
-      const intended = intendedTypes(config.schemaDir)
+      const intended = intendedTypes(config.schemaDir, formTypesFor(config))
       if ('problems' in intended) {
         lastError = intended.problems.join('\n')
         log.warn('Models were not generated: {problems}', { problems: intended.problems.length })

package/src/ports.ts

@@ -1,16 +1,19 @@
 /** Implementations of the Management API ports. */
+
+import { resolveDeliveryApiSettings } from '@crombolo/api-delivery'
 import type {
   CurrentUserPort,
   LocalizationPort,
   ManagementApiDeps,
   ManifestPort,
   NodeLookup,
+  PreviewPort,
   Principal,
   ServerPort,
   TemporaryFilePort,
   UserItemPort,
 } from '@crombolo/api-management'
-import { AuthStore } from '@crombolo/auth'
+import { AuthStore, expireCookie, serializeCookie } from '@crombolo/auth'
 import {
   ASSISTANT_MANIFEST_ID,
   type BackOfficePaths,
@@ -28,6 +31,7 @@ import {
 import {
   ContentTypeRepository,
   type Db,
+  DynamicRootRepository,
   LanguageRepository,
   RedirectRepository,
   TagRepository,
@@ -35,6 +39,7 @@ import {
 } from '@crombolo/data'
 import type { PublishedCache } from '@crombolo/render'
 import { createNodeLookup } from './access.ts'
+import { createAuditHistory } from './adapters/audit.ts'
 import { createBlueprintPort } from './adapters/blueprints.ts'
 import { createPackagePort } from './adapters/bundles.ts'
 import {
@@ -47,24 +52,29 @@ import { createDictionaryPort } from './adapters/dictionary.ts'
 import { createDocumentPort } from './adapters/documents.ts'
 import { createElementPort } from './adapters/elements.ts'
 import { createFileSystemPort } from './adapters/file-system.ts'
+import { createDiagnosticsPort } from './adapters/health.ts'
 import { createMediaPort } from './adapters/media.ts'
 import { createMemberGroupPort } from './adapters/member-groups.ts'
 import { createMemberPort } from './adapters/members.ts'
 import { createPublicAccessPort } from './adapters/public-access.ts'
 import { createRedirectPort } from './adapters/redirects.ts'
 import { createReferencePort } from './adapters/references.ts'
+import { createRelationPort } from './adapters/relations.ts'
 import {
   createSchemaFileWriter,
   type SchemaFiles,
   type SchemaFileWriter,
 } from './adapters/schema-files.ts'
+import { createSearchIndexPort } from './adapters/search-index.ts'
 import { createTemplateFileStore } from './adapters/template-files.ts'
 import { createTemplateQueryPort } from './adapters/template-query.ts'
 import { avatarUrls, createUserPorts } from './adapters/users.ts'
+import { createWebhookPort } from './adapters/webhooks.ts'
 import { COMPONENT_SNIPPETS } from './component-snippets.ts'
 import { type CromboloConfig, type UserLinkSender, VERSION } from './config.ts'
 import { type EmailPort, resolveEmailPort } from './email.ts'
 import { createFileIntake } from './file-intake.ts'
+import { formTypesFor } from './form-types.ts'
 import { createLogViewerPort } from './log-viewer.ts'
 import { logger } from './logging.ts'
 import { MediaFileStore } from './media-files.ts'
@@ -73,6 +83,7 @@ import { createOEmbedService } from './oembed.ts'
 import { createRedirectTracker } from './redirects.ts'
 import { componentAliasesIn, type SchemaBoot } from './schema.ts'
 import { publishSchema } from './schema-store.ts'
+import { createWebhookService, type WebhookService } from './webhooks.ts'
 
 /** Re-exported for tests; the canonical list lives in @crombolo/core. */
 export const CORE_SECTIONS = CORE_SECTION_ALIASES
@@ -109,6 +120,18 @@ function createServerPort(config: CromboloConfig, canSendUserLinks: boolean): Se
   }
 }
 
+/** Umbraco's preview cookie; with a signed-in editor it turns on draft rendering. */
+export const PREVIEW_COOKIE = 'UMB_PREVIEW'
+
+function createPreviewPort(config: CromboloConfig): PreviewPort {
+  return {
+    enter: () => [
+      serializeCookie({ name: PREVIEW_COOKIE, value: 'preview', secure: config.secureCookies }),
+    ],
+    exit: () => [expireCookie(PREVIEW_COOKIE, config.secureCookies)],
+  }
+}
+
 function createManifestPort(
   paths: BackOfficePaths,
   extensions: ExtensionRegistry,
@@ -324,12 +347,13 @@ export function resolveUserLinkSender(
 }
 
 /** Where the backoffice writes schema files, and whether it may. */
-function schemaFiles(config: CromboloConfig): SchemaFiles {
+export function schemaFiles(config: CromboloConfig): SchemaFiles {
   const store = config.schemaStore
   return {
     schemaDir: config.schemaDir,
     writable: config.schemaWritable,
     componentAliases: () => componentAliasesIn(config.componentsDir),
+    formTypes: formTypesFor(config),
     // Only when a store is configured: a schema directory in a repository is
     // already where the files durably live.
     onChanged: store
@@ -357,6 +381,8 @@ export interface DepsOptions {
   extensions: ExtensionRegistry
   /** Omitted only by tests that exercise the contract without a database. */
   db?: Db
+  /** The site's webhooks, shared with the delivery job and the event source. */
+  webhooks?: WebhookService
   /** Required alongside `db` to serve documents, which invalidate the cache. */
   cache?: PublishedCache
   schema?: SchemaBoot
@@ -374,6 +400,8 @@ export interface DepsOptions {
    * tells the other nodes to look; without it they keep the view they imported.
    */
   onViewsChange?: (alias: string) => void | Promise<void>
+  /** Items were queued for the search index; the indexer can start on them now. */
+  onSearchQueued?: () => void
 }
 
 function createTemporaryFilePort(files: MediaFileStore): TemporaryFilePort {
@@ -402,6 +430,7 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
   const sendUserLink = resolveUserLinkSender(options.config, email)
   const deps: ManagementApiDeps = {
     server: createServerPort(options.config, Boolean(sendUserLink)),
+    preview: createPreviewPort(options.config),
     // An unconfigured assistant contributes no extension, so the backoffice has
     // no drawer, no button and nothing to load.
     manifests: createManifestPort(
@@ -437,6 +466,16 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
   deps.stylesheets = createFileSystemPort(options.config.stylesheetsDir, { extension: '.css' })
   deps.scripts = createFileSystemPort(options.config.scriptsDir, { extension: '.js' })
   if (options.db) {
+    const dynamicRoots = new DynamicRootRepository(options.db)
+    deps.dynamicRoots = { resolve: (query) => dynamicRoots.resolve(query) }
+    deps.diagnostics = createDiagnosticsPort({
+      config: options.config,
+      db: options.db,
+      media: mediaFiles.store,
+      email,
+      nodeState: options.schema?.nodeState,
+      fetch: options.fetch,
+    })
     const tags = new TagRepository(options.db)
     deps.tags = { list: (filter) => tags.all(filter) }
     deps.users = createUserItemPort(options.db)
@@ -489,6 +528,9 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       nodeState: options.schema?.nodeState,
       nodeId: options.schema?.nodeId,
       valueIntake,
+      apiMemberUserNames: resolveDeliveryApiSettings(
+        options.config.deliveryApi,
+      ).memberAuthorization.clientCredentialsFlow.associatedMembers.map((m) => m.userName),
     })
     deps.publicAccess = createPublicAccessPort(options.db, {
       onChange: () => options.cache?.invalidate(),
@@ -500,6 +542,17 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       onChange: () => options.cache?.invalidate(),
     })
     deps.references = createReferencePort(options.db)
+    deps.relations = createRelationPort(options.db)
+    deps.webhooks = createWebhookPort(
+      options.webhooks ??
+        createWebhookService({
+          db: options.db,
+          schemaDir: options.config.schemaDir,
+          filesWritable: options.config.schemaWritable,
+          secretKey: options.config.secretKey,
+          bundles: options.config.bundles,
+        }),
+    )
     deps.redirects = createRedirectPort(options.db, options.cache, {
       isTracking: options.config.trackRedirects,
       onChange: () => options.cache?.invalidate(),
@@ -514,12 +567,14 @@ export function createDeps(options: DepsOptions): ManagementApiDeps {
       stylesheets: deps.stylesheets,
       scripts: deps.scripts,
     })
+    deps.auditHistory = createAuditHistory(options.db, options.config.auditRetentionDays)
     if (options.cache) {
       const cache = options.cache
       deps.templateQuery = createTemplateQueryPort({
         cache,
         types: new ContentTypeRepository(options.db),
       })
+      deps.searchIndex = createSearchIndexPort(options.db, options.onSearchQueued)
       deps.publishedCache = {
         reload: () => cache.invalidate(),
         rebuild: async () => {

package/src/schema.ts

@@ -6,6 +6,7 @@
 
 import { existsSync, watch } from 'node:fs'
 import {
+  CACHE_INSTRUCTION_CHANNEL,
   type CacheInstructionKind,
   cacheInstructionsAfter,
   compareStates,
@@ -39,7 +40,8 @@ import {
   writeKeysBack,
 } from '@crombolo/schema'
 import { listComponents } from './components.ts'
-import type { CromboloConfig } from './config.ts'
+import { type CromboloConfig, VERSION } from './config.ts'
+import { formTypesFor } from './form-types.ts'
 import { logger } from './logging.ts'
 import { materialiseSchema } from './schema-store.ts'
 
@@ -72,7 +74,7 @@ export async function checkSchemaDirectory(
   node: { nodeId: string; revision: string },
   options: { set?: Record<string, unknown> } = {},
 ): Promise<CheckReport> {
-  const loaded = loadSchemaDirectory(config.schemaDir)
+  const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
   return runCheck(
     db,
     loaded,
@@ -108,6 +110,7 @@ export function syncOptionsFor(config: CromboloConfig): SyncOptions {
   return {
     mode: config.development ? 'development' : 'production',
     componentAliases: componentAliasesIn(config.componentsDir),
+    formTypes: formTypesFor(config),
   }
 }
 
@@ -121,7 +124,7 @@ export async function syncSchemaDirectory(
   // The files are read under the lock the backoffice's schema writes hold, so a
   // sync never applies a snapshot that a later backoffice change has overtaken.
   return db.locks.withLock(Locks.Schema, async () => {
-    const loaded = loadSchemaDirectory(config.schemaDir)
+    const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
     const report = await syncSchema(
       db,
       loaded,
@@ -145,15 +148,15 @@ export async function bootSchema(db: Db, config: CromboloConfig): Promise<Schema
   const nodeId = config.nodeId
   if (!existsSync(config.schemaDir)) {
     const nodeState = { version: '0', revision: config.schemaRevision }
-    await touchServer(db, { nodeId, ...nodeState, role: config.role })
+    await touchServer(db, { nodeId, ...nodeState, role: config.role, cromboloVersion: VERSION })
     await ensureSystemMediaTypes(db, { linkFolderChildren: true })
     await ensureSystemMemberTypes(db)
     await ensureSystemContentTypes(db)
     return { nodeState, nodeId, report: undefined, compatibilityMode: false }
   }
-  const loaded = loadSchemaDirectory(config.schemaDir)
+  const loaded = loadSchemaDirectory(config.schemaDir, { formTypes: formTypesFor(config) })
   const nodeState = { version: loaded.set.version, revision: config.schemaRevision }
-  await touchServer(db, { nodeId, ...nodeState, role: config.role })
+  await touchServer(db, { nodeId, ...nodeState, role: config.role, cromboloVersion: VERSION })
   if (!config.syncSchemaAtBoot)
     return { nodeState, nodeId, report: undefined, compatibilityMode: false }
 
@@ -246,11 +249,18 @@ export interface CachePollerOptions {
   onInstruction(kind: CacheInstructionKind, payload: Record<string, unknown>): void
 }
 
-/** Polls `cache_instruction` from where this node came in; own instructions are skipped. */
+/**
+ * Polls `cache_instruction` from where this node came in; own instructions are
+ * skipped. Where the database can notify, a write wakes it at once and the
+ * timer is only the fallback.
+ */
 export class CacheInstructionPoller {
   #options: CachePollerOptions
   #cursor = 0
   #timer: ReturnType<typeof setInterval> | undefined
+  #unlisten: (() => Promise<void>) | undefined
+  #running: Promise<number> | undefined
+  #queued: Promise<number> | undefined
   #behind = false
   #bootLedgerId = 0
   #readsUnsafe = false
@@ -287,11 +297,39 @@ export class CacheInstructionPoller {
     if (intervalMs > 0) {
       this.#timer = setInterval(() => void this.poll().catch(() => {}), intervalMs)
       this.#timer.unref()
+      // Without it the timer still delivers everything, only later.
+      this.#unlisten = await this.#options.db
+        .listen?.(CACHE_INSTRUCTION_CHANNEL, () => void this.poll().catch(() => {}))
+        .catch(() => undefined)
     }
   }
 
-  /** Returns how many foreign instructions were applied. */
-  async poll(): Promise<number> {
+  /**
+   * Returns how many foreign instructions were applied. One poll at a time: a
+   * call while one runs waits for a single follow-up, so a burst of wake-ups
+   * reads the table twice, not once each.
+   */
+  poll(): Promise<number> {
+    if (this.#queued) return this.#queued
+    if (!this.#running) return this.#start()
+    this.#queued = this.#running
+      .catch(() => 0)
+      .then(() => {
+        this.#queued = undefined
+        return this.#start()
+      })
+    return this.#queued
+  }
+
+  #start(): Promise<number> {
+    const run = this.#pollOnce().finally(() => {
+      if (this.#running === run) this.#running = undefined
+    })
+    this.#running = run
+    return run
+  }
+
+  async #pollOnce(): Promise<number> {
     const { db, nodeId, nodeState, onInstruction } = this.#options
     const instructions = await cacheInstructionsAfter(db, this.#cursor)
     let applied = 0
@@ -301,7 +339,12 @@ export class CacheInstructionPoller {
       onInstruction(instruction.kind, instruction.payload)
       applied += 1
     }
-    await touchServer(db, { nodeId, ...nodeState, role: this.#options.role })
+    await touchServer(db, {
+      nodeId,
+      ...nodeState,
+      role: this.#options.role,
+      cromboloVersion: VERSION,
+    })
     const current = await currentSchemaState(db)
     const behind = compareStates(nodeState, current) < 0
     if (behind && !this.#behind) onInstruction('schema', { stateId: current.id })
@@ -317,6 +360,8 @@ export class CacheInstructionPoller {
   stop(): void {
     if (this.#timer) clearInterval(this.#timer)
     this.#timer = undefined
+    void this.#unlisten?.().catch(() => {})
+    this.#unlisten = undefined
   }
 }
 
@@ -376,7 +421,9 @@ export async function importSchema(
 
   const report = await syncSchemaDirectory(db, config, node)
   if (report.action === 'applied') {
-    boot.nodeState.version = loadSchemaDirectory(config.schemaDir).set.version
+    boot.nodeState.version = loadSchemaDirectory(config.schemaDir, {
+      formTypes: formTypesFor(config),
+    }).set.version
     boot.nodeState.revision = config.schemaRevision
   }
   return {