@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/services/accounts/posix.ts

@@ -2,18 +2,19 @@ import { sql } from "bun";
 import {
   DEFAULT_LINUX_IDENTITY_CONFIGURATION,
   isPosixName,
-  LinuxIdentityConfigurationSchema,
   type LinuxIdentityConfiguration,
+  LinuxIdentityConfigurationSchema,
   type PosixIdentity,
   PosixOverridesSchema,
 } from "../../contracts/posix";
+import type { MutationResult } from "../../contracts/shared";
 import { freeipa } from "../../server/services";
+import { type AuditActor, audit } from "../audit";
 import { getFreeIpaConfig } from "../freeipa-config";
 import { readCompleteIpaList } from "../ipa/sync-planning";
-import { decryptValue } from "../settings/crypto";
 import * as settings from "../settings";
-import { audit, type AuditActor } from "../audit";
-import type { MutationResult } from "../../contracts/shared";
+import { decryptValue } from "../settings/crypto";
+import { create as createLocalGroup } from "./local-groups";
 
 const CONFIG_KEY = "linux.identity_config";
 export const POSIX_PAGE_SIZE = 50;
@@ -274,6 +275,34 @@ export const createPosixRuntime = (db: typeof sql = sql, readRanges = readIpaIdR
     }
   };
 
+  const assignGroup = async (tx: typeof sql, actor: Actor, id: string, ranges: IpaIdRange[]) => {
+    const config = await readConfig(tx);
+    if (!config.enabled) throw new PosixError("setup_disabled");
+    const [group] = await tx<
+      { id: string; name: string; provider: string; gid_number: number | null }[]
+    >`SELECT id, name, provider, gid_number FROM auth.groups WHERE id = ${id}::uuid`;
+    if (!group) throw new PosixError("group_not_found", 404);
+    if (group.provider !== "local") throw new PosixError("identity_not_locally_managed");
+    if (group.gid_number !== null) return { gidNumber: group.gid_number };
+    if (!isPosixName(group.name)) throw new PosixError("invalid_name");
+    const [conflict] = await tx`SELECT 1 FROM auth.groups WHERE id <> ${id}::uuid AND lower(name) = lower(${group.name}) LIMIT 1`;
+    if (conflict) throw new PosixError("group_conflict");
+    await checkRange(tx, config, ranges);
+    const gidNumber = await allocate(tx, "gid", id, config);
+    await tx`UPDATE auth.groups SET gid_number = ${gidNumber} WHERE id = ${id}::uuid`;
+    await audit.record(
+      {
+        action: "accounts.linux.provision_group",
+        outcome: "allowed",
+        actor: { userId: actor.id, roles: actor.roles },
+        target: { type: "group", id },
+        metadata: { gidNumber },
+      },
+      tx,
+    );
+    return { gidNumber };
+  };
+
   const service = {
     async configuration(actor: Actor) {
       requireAdmin(actor);
@@ -347,36 +376,23 @@ export const createPosixRuntime = (db: typeof sql = sql, readRanges = readIpaIdR
         return { ...candidate(row), identity: { ...candidate(row).identity!, ...parsed.data } };
       });
     },
+    async createGroup(actor: Actor, input: { name: string; description?: string }) {
+      requireAdmin(actor);
+      const ranges = await readRanges();
+      return db.begin(async (tx) => {
+        await lock(tx);
+        const created = await createLocalGroup(input, tx);
+        if (!created.ok) throw new PosixError("group_conflict");
+        const { gidNumber } = await assignGroup(tx, actor, created.data.id, ranges);
+        return { ...created.data, gidnumber: gidNumber };
+      });
+    },
     async provisionGroup(actor: Actor, id: string) {
       requireAdmin(actor);
       const ranges = await readRanges();
       return db.begin(async (tx) => {
         await lock(tx);
-        const config = await readConfig(tx);
-        if (!config.enabled) throw new PosixError("setup_disabled");
-        const [group] = await tx<
-          { id: string; name: string; provider: string; gid_number: number | null }[]
-        >`SELECT id, name, provider, gid_number FROM auth.groups WHERE id = ${id}::uuid`;
-        if (!group) throw new PosixError("group_not_found", 404);
-        if (group.provider !== "local") throw new PosixError("identity_not_locally_managed");
-        if (group.gid_number !== null) return { gidNumber: group.gid_number };
-        if (!isPosixName(group.name)) throw new PosixError("invalid_name");
-        const [conflict] = await tx`SELECT 1 FROM auth.groups WHERE id <> ${id}::uuid AND lower(name) = lower(${group.name}) LIMIT 1`;
-        if (conflict) throw new PosixError("group_conflict");
-        await checkRange(tx, config, ranges);
-        const gidNumber = await allocate(tx, "gid", id, config);
-        await tx`UPDATE auth.groups SET gid_number = ${gidNumber} WHERE id = ${id}::uuid`;
-        await audit.record(
-          {
-            action: "accounts.linux.provision_group",
-            outcome: "allowed",
-            actor: { userId: actor.id, roles: actor.roles },
-            target: { type: "group", id },
-            metadata: { gidNumber },
-          },
-          tx,
-        );
-        return { gidNumber };
+        return assignGroup(tx, actor, id, ranges);
       });
     },
   };

package/src/services/accounts/users.ts

@@ -172,7 +172,7 @@ export const get = async (params: { id: string } | { uid: string }): Promise<Use
   const { groupsAdmin } = await getFreeIpaConfig();
   const rows = await sql<DbRow[]>`
     SELECT u.*,
-      ${userIpaDataColumns},
+      ${userIpaDataColumns()},
       CASE
         WHEN u.provider = 'local' THEN u.admin
         ELSE EXISTS(
@@ -203,7 +203,7 @@ export const get = async (params: { id: string } | { uid: string }): Promise<Use
         ${managedGroupIdsSubquery(userIdExpr)}
       ), '{}') AS manages_group_ids
     FROM auth.users u
-    ${userIpaDataJoin}
+    ${userIpaDataJoin()}
     WHERE ${whereClause}
   `;
   if (rows.length === 0) return null;

package/src/services/announcements/index.ts

@@ -1,5 +1,11 @@
+import { requestCacheRedis } from "../request-cache-redis";
 import { err, fail, ok, type Result } from "@k2b/stdlib";
 import { sql } from "bun";
+import { HTTPException } from "hono/http-exception";
+import { hasRole, type User } from "../../contracts/shared";
+import { z } from "zod";
+import { AnnouncementDisplayEntrySchema } from "../../contracts/announcements";
+import { claimCacheFill, completeCacheFill } from "../cache-fill";
 import type {
   AnnouncementCookieState,
   AnnouncementDisplayEntry,
@@ -11,6 +17,17 @@ import { markdown } from "../../shared/markdown";
 import { logger } from "../logging";
 
 const log = logger("announcements");
+const ACTIVE_CACHE_KEY = "appglobalcache:shared:announcements:v1";
+const invalidateActiveCache = async () => (await requestCacheRedis()).del(ACTIVE_CACHE_KEY);
+const invalidateAfterMutation = async () => {
+  try {
+    await invalidateActiveCache();
+  } catch (error) {
+    // The database mutation already succeeded; do not invite duplicate creates.
+    // Unavailable Redis reads fall back to Postgres; old cache entries expire.
+    log.warn("Announcement saved but cache invalidation failed", { error: error instanceof Error ? error.message : String(error) });
+  }
+};
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
 type AnnouncementRow = {
@@ -119,6 +136,7 @@ const create = async (params: { data: CreateAnnouncement; actorId: string }): Pr
       RETURNING id, version, kind, title, body, tone, published_at, expires_at,
         created_at, updated_at, created_by, updated_by
     `;
+    if (row) await invalidateAfterMutation();
     return row ? ok(mapRow(row)) : fail(err.internal("Failed to create announcement."));
   } catch (error) {
     log.error("Failed to create announcement", { error: error instanceof Error ? error.message : String(error) });
@@ -156,6 +174,7 @@ const update = async (params: { id: string; data: UpdateAnnouncement; actorId: s
       RETURNING id, version, kind, title, body, tone, published_at, expires_at,
         created_at, updated_at, created_by, updated_by
     `;
+    if (row) await invalidateAfterMutation();
     return row ? ok(mapRow(row)) : fail(err.notFound("Announcement"));
   } catch (error) {
     log.error("Failed to update announcement", { id: params.id, error: error instanceof Error ? error.message : String(error) });
@@ -166,6 +185,7 @@ const update = async (params: { id: string; data: UpdateAnnouncement; actorId: s
 const remove = async (params: { id: string }): Promise<Result<void>> => {
   if (!UUID_PATTERN.test(params.id)) return fail(err.notFound("Announcement"));
   const result = await sql`DELETE FROM announcements.entries WHERE id = ${params.id}::uuid`;
+  if (result.count > 0) await invalidateAfterMutation();
   return result.count > 0 ? ok() : fail(err.notFound("Announcement"));
 };
 
@@ -182,28 +202,65 @@ const listActive = async (params: { now?: Date } = {}): Promise<AnnouncementEntr
   return rows.map(mapRow);
 };
 
-export const selectVisibleForState = (
-  entries: AnnouncementEntry[],
+const selectEntriesForState = <T extends { kind: AnnouncementEntry["kind"]; version: number }>(
+  entries: T[],
   state: AnnouncementCookieState,
-): { banners: AnnouncementDisplayEntry[]; announcements: AnnouncementDisplayEntry[]; latestAnnouncementVersion: number } => {
+) => {
   const dismissedBanners = new Set(state.dismissedBannerVersions);
   const activeAnnouncements = entries.filter((entry) => entry.kind === "announcement");
   const latestAnnouncementVersion = activeAnnouncements.reduce((max, entry) => Math.max(max, entry.version), state.seenAnnouncementVersion);
   return {
     banners: entries
       .filter((entry) => entry.kind === "banner" && !dismissedBanners.has(entry.version))
-      .sort((a, b) => b.version - a.version)
-      .map(renderAnnouncement),
+      .sort((a, b) => b.version - a.version),
     announcements: activeAnnouncements
       .filter((entry) => entry.version > state.seenAnnouncementVersion)
-      .sort((a, b) => b.version - a.version)
-      .map(renderAnnouncement),
+      .sort((a, b) => b.version - a.version),
     latestAnnouncementVersion,
   };
 };
 
+export const selectVisibleForState = (entries: AnnouncementEntry[], state: AnnouncementCookieState) => {
+  const selected = selectEntriesForState(entries, state);
+  return { ...selected, banners: selected.banners.map(renderAnnouncement), announcements: selected.announcements.map(renderAnnouncement) };
+};
+
+const cachedActive = async (): Promise<AnnouncementDisplayEntry[]> => {
+  let cached: string | null = null;
+  try {
+    cached = await (await requestCacheRedis()).get(ACTIVE_CACHE_KEY);
+  } catch {
+    /* Read authoritative data below. */
+  }
+  let entries: AnnouncementDisplayEntry[] | undefined;
+  if (cached !== null) {
+    try {
+      entries = z.array(AnnouncementDisplayEntrySchema).parse(JSON.parse(cached));
+    } catch {
+      /* Miss. */
+    }
+  }
+  if (!entries) {
+    const lease = await claimCacheFill(ACTIVE_CACHE_KEY, cached);
+    // Include scheduled entries: publish/expiry boundaries are applied at read time.
+    const rows = await sql<AnnouncementRow[]>`
+      SELECT id, version, kind, title, body, tone, published_at, expires_at,
+        created_at, updated_at, created_by, updated_by
+      FROM announcements.entries
+      WHERE expires_at IS NULL OR expires_at > now()
+      ORDER BY version DESC
+    `;
+    entries = rows.map((row) => renderAnnouncement(mapRow(row)));
+    await completeCacheFill(ACTIVE_CACHE_KEY, lease, JSON.stringify(entries), 300);
+  }
+  const now = Date.now();
+  return entries.filter((entry) => Date.parse(entry.publishedAt) <= now && (!entry.expiresAt || Date.parse(entry.expiresAt) > now));
+};
+
 const activeForState = async (params: { state: AnnouncementCookieState; now?: Date }) =>
-  selectVisibleForState(await listActive({ now: params.now }), params.state);
+  params.now
+    ? selectVisibleForState(await listActive({ now: params.now }), params.state)
+    : selectEntriesForState(await cachedActive(), params.state);
 
 export const announcements = {
   admin: {
@@ -212,6 +269,10 @@ export const announcements = {
     create,
     update,
     remove,
+    invalidateCache: async (actor: User | undefined) => {
+      if (!actor || !hasRole(actor, "admin")) throw new HTTPException(403, { message: "Administrator access required" });
+      await invalidateActiveCache();
+    },
   },
   active: {
     list: listActive,

package/src/services/audit/index.ts

@@ -236,7 +236,7 @@ const record = async (params: AuditRecordParams, db: AuditDb = sql): Promise<voi
         ${asString(params.error?.code ?? null)},
         ${sanitizeAuditText(params.error?.message ?? null)},
         ${asString(params.requestId)},
-        ${JSON.stringify(metadata)}::jsonb
+        ${JSON.stringify(metadata)}::text::jsonb
       )
     `;
   } catch (error) {

package/src/services/cache-fill.ts

@@ -0,0 +1,35 @@
+import { requestCacheRedis } from "./request-cache-redis";
+
+// Non-JSON markers remain compatible with older readers: they discard them and
+// use Postgres. A marker can never be confused with a stored JSON setting value.
+export const MISSING_SETTING = "!cloud:missing-setting:v1";
+const FILL_PREFIX = "!cloud:cache-fill:v1:";
+const COMPLETE = `if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
+end return nil`;
+const DISCARD = `if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end return 0`;
+
+/** A concurrent invalidation deletes the lease, so an old read cannot refill it. */
+export const claimCacheFill = async (key: string, observed: string | null): Promise<string | null> => {
+  try {
+    if (observed?.startsWith(FILL_PREFIX)) return null;
+    const redis = await requestCacheRedis();
+    if (observed !== null) await redis.send("EVAL", [DISCARD, "1", key, observed]);
+    const token = FILL_PREFIX + crypto.randomUUID();
+    // A slow loader may still return its value, but loses permission to cache it.
+    return (await redis.send("SET", [key, token, "NX", "EX", "5"])) === "OK" ? token : null;
+  } catch {
+    return null;
+  }
+};
+
+export const completeCacheFill = async (key: string, token: string | null, value: string, ttlSeconds: number): Promise<void> => {
+  if (!token) return;
+  try {
+    await (await requestCacheRedis()).send("EVAL", [COMPLETE, "1", key, token, value, String(ttlSeconds)]);
+  } catch {
+    // A cache failure does not change a successful authoritative read.
+  }
+};

package/src/services/help/index.ts

@@ -0,0 +1,109 @@
+import { type SQL, sql } from "bun";
+import { getApp, listApps } from "../../_internal/registry";
+import type { AppRegistryEntry } from "../../contracts/registry";
+import { resolveAppPresentations } from "../../shared/app-presentation";
+import { helpLocaleChain } from "../../shared/help";
+import { logger } from "../logging";
+import { HELP_RESOURCE_PAGE_SIZE, type HelpSelection, hasHelpBm25, metadata, queryHelp } from "./store";
+import type { HelpReader } from "./types";
+
+export { cleanupHelp, migrateHelp, registerHelp } from "./store";
+export type { HelpArticle, HelpMatch, HelpMetadata, HelpReader, HelpReaderFactory } from "./types";
+
+const log = logger("help");
+
+export const createHelpReader = (
+  locale: string,
+  dependencies: {
+    db?: SQL;
+    listApps?: () => Promise<AppRegistryEntry[]>;
+    getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
+  } = {},
+): HelpReader => {
+  const db = dependencies.db ?? sql;
+  const select = async (appId?: string): Promise<HelpSelection[]> => {
+    const apps = appId
+      ? [await (dependencies.getApp ?? getApp)(appId)].filter((app): app is AppRegistryEntry => app !== null)
+      : await (dependencies.listApps ?? listApps)();
+    return resolveAppPresentations(apps, locale).flatMap((app) =>
+      app.help
+        ? [
+            {
+              app_id: app.id,
+              app_name: app.name,
+              manifest_hash: app.help.manifestHash,
+              locales: helpLocaleChain(locale, app.help.baseLocale),
+            },
+          ]
+        : [],
+    );
+  };
+  return {
+    async manifest(appId) {
+      const app = await (dependencies.getApp ?? getApp)(appId);
+      if (!app?.help) return null;
+      const [corpus] = await db`SELECT 1 FROM help.corpora WHERE app_id=${app.id} AND manifest_hash=${app.help.manifestHash}`;
+      if (!corpus) return null;
+      const rows = await queryHelp(
+        [
+          {
+            app_id: app.id,
+            app_name: app.name,
+            manifest_hash: app.help.manifestHash,
+            locales: helpLocaleChain(locale, app.help.baseLocale),
+          },
+        ],
+        {},
+        db,
+      );
+      return {
+        ...app.help,
+        locale,
+        documents: rows
+          .sort((a, b) => a.sort_order - b.sort_order || a.title.localeCompare(b.title))
+          .map((row) => ({
+            id: row.document_id,
+            title: row.title,
+            icon: row.icon ?? undefined,
+            description: row.description ?? undefined,
+            order: row.sort_order,
+            locale: row.locale,
+            searchUrl: `/api/help/v1/${encodeURIComponent(appId)}/search`,
+            url: `/api/help/v1/${encodeURIComponent(appId)}/documents/${encodeURIComponent(row.document_id)}`,
+          })),
+      };
+    },
+    async list(cursor = "") {
+      return (await queryHelp(await select(), { cursor, limit: HELP_RESOURCE_PAGE_SIZE + 1 }, db)).map(metadata);
+    },
+    async read(input) {
+      const [row] = await queryHelp(await select(input.appId), { documentId: input.documentId, body: true, limit: 1 }, db);
+      return row?.markdown === undefined ? null : { ...metadata(row), markdown: row.markdown };
+    },
+    async search(input) {
+      const query = input.query.trim().slice(0, 200);
+      if (!query) return [];
+      const selection = await select(input.appId);
+      if (!selection.length) return [];
+      const options = { query, limit: Math.max(1, Math.min(Math.floor(Number.isFinite(input.limit) ? input.limit! : 10), 25)) };
+      const bm25 = await hasHelpBm25(db);
+      const rows = await queryHelp(selection, { ...options, bm25 }, db).catch((error: unknown) => {
+        // Only missing optional SQL objects qualify for fallback, not connection/query errors.
+        const code = error && typeof error === "object" ? (Reflect.get(error, "errno") ?? Reflect.get(error, "code")) : undefined;
+        if (!bm25 || !["42883", "42704", "42P01"].includes(String(code))) throw error;
+        log.warn("BM25 unavailable; using native Help search");
+        return queryHelp(selection, options, db);
+      });
+      return rows.map((row) => ({
+        kind: "help",
+        appId: row.app_id,
+        appName: row.app_name,
+        locale: row.locale,
+        documentId: row.document_id,
+        title: row.title,
+        description: row.description ?? undefined,
+      }));
+    },
+  };
+};
+export { startHelpMaintenance } from "./maintenance";

package/src/services/help/maintenance.ts

@@ -0,0 +1,25 @@
+import { logger } from "../logging";
+import { cleanupHelp } from "./store";
+
+const log = logger("help:maintenance");
+/** Core owns the timer; stop waits for the current bounded deletion. */
+export const startHelpMaintenance = (): (() => Promise<void>) => {
+  let stopped = false;
+  let inFlight: Promise<void> | undefined;
+  let timer: ReturnType<typeof setTimeout>;
+  const run = () => {
+    inFlight = cleanupHelp()
+      .catch((error) => {
+        log.error("Expired Help cleanup failed", { error: error instanceof Error ? error.message : String(error) });
+      })
+      .finally(() => {
+        if (!stopped) timer = setTimeout(run, 60_000);
+      });
+  };
+  timer = setTimeout(run, 60_000);
+  return async () => {
+    stopped = true;
+    clearTimeout(timer);
+    await inFlight;
+  };
+};

package/src/services/help/store.ts

@@ -0,0 +1,180 @@
+import { type SQL, sql } from "bun";
+import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
+import type { HelpCorpus, HelpMetadata } from "./types";
+
+// One expired app lease of grace after an app can no longer be discovered.
+export const HELP_RETENTION_MS = APP_REGISTRY_TTL_MS * 2;
+export const HELP_RESOURCE_PAGE_SIZE = 100;
+const searchConfigs = ["english", "german", "simple"] as const;
+
+export const migrateHelp = async (db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext('cloud:help:migrate'))`;
+    await tx`CREATE SCHEMA IF NOT EXISTS help`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS help.corpora (
+    app_id text NOT NULL, manifest_hash text NOT NULL, base_locale text NOT NULL,
+    last_seen_at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (app_id, manifest_hash)
+  )`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS help_expiry_idx ON help.corpora(last_seen_at)`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS help.documents (
+    app_id text NOT NULL, manifest_hash text NOT NULL, locale text NOT NULL, document_id text NOT NULL,
+    title text NOT NULL, description text, icon text, sort_order integer NOT NULL,
+    markdown text NOT NULL, search_text text NOT NULL, search_config text NOT NULL,
+    search_document tsvector NOT NULL,
+    PRIMARY KEY (app_id, manifest_hash, locale, document_id),
+    FOREIGN KEY (app_id, manifest_hash) REFERENCES help.corpora ON DELETE CASCADE
+  )`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS help_search_idx ON help.documents USING gin(search_document)`.simple();
+  });
+  // The operator enables the extension; Help never installs server extensions.
+  const [extension] = await db<{ installed: boolean }[]>`SELECT EXISTS (
+    SELECT 1 FROM pg_extension WHERE extname = 'pg_textsearch') AS installed`;
+  if (extension?.installed) {
+    try {
+      for (const config of searchConfigs) {
+        await db
+          .unsafe(`CREATE INDEX IF NOT EXISTS help_bm25_${config}_idx ON help.documents
+        USING bm25(search_text) WITH (text_config='${config}') WHERE search_config='${config}'`)
+          .simple();
+      }
+    } catch (error) {
+      console.warn("Optional Help BM25 indexes unavailable; native search remains active", error);
+    }
+  }
+};
+
+/** Commit the complete source once; subsequent app heartbeats only renew its lease. */
+export const registerHelp = async (corpus: HelpCorpus, db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SET LOCAL statement_timeout = '10s'`.simple();
+    const renewed = await tx`UPDATE help.corpora SET last_seen_at = clock_timestamp()
+      WHERE app_id = ${corpus.appId} AND manifest_hash = ${corpus.manifestHash} RETURNING app_id`;
+    if (renewed.length) return;
+    const inserted = await tx`INSERT INTO help.corpora(app_id, manifest_hash, base_locale)
+      VALUES (${corpus.appId}, ${corpus.manifestHash}, ${corpus.baseLocale})
+      ON CONFLICT (app_id, manifest_hash) DO UPDATE SET last_seen_at = clock_timestamp()
+      RETURNING (xmax = 0) AS inserted`;
+    if (!inserted[0]?.inserted) return;
+    for (const [locale, documents] of [[corpus.baseLocale, corpus.documents] as const, ...Object.entries(corpus.documentsByLocale)]) {
+      const config = locale.split("-")[0] === "de" ? "german" : locale.split("-")[0] === "en" ? "english" : "simple";
+      // One bounded article per statement; no duplicate whole-corpus JSON transport.
+      for (const document of documents) {
+        const text = `${document.title}\n${document.description ?? ""}\n${document.searchText}`;
+        await tx`INSERT INTO help.documents(app_id, manifest_hash, locale, document_id, title, description, icon,
+          sort_order, markdown, search_text, search_config, search_document)
+          VALUES (${corpus.appId}, ${corpus.manifestHash}, ${locale}, ${document.id}, ${document.title},
+            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.markdown}, ${text}, ${config},
+            setweight(to_tsvector(${config}::regconfig, ${document.id + " " + document.title}), 'A') ||
+            setweight(to_tsvector(${config}::regconfig, ${document.description ?? ""}), 'B') ||
+            setweight(to_tsvector(${config}::regconfig, ${document.searchText}), 'D'))`;
+      }
+    }
+  });
+};
+
+/** Row locks serialize cleanup with publication/renewal. Delete at most one corpus per tick. */
+export const cleanupHelp = async (db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SET LOCAL statement_timeout = '10s'`.simple();
+    await tx`DELETE FROM help.corpora WHERE (app_id, manifest_hash) IN (
+    SELECT app_id, manifest_hash FROM help.corpora
+    WHERE last_seen_at < now() - ${HELP_RETENTION_MS} * interval '1 millisecond'
+    ORDER BY last_seen_at LIMIT 1 FOR UPDATE SKIP LOCKED
+  )`;
+  });
+};
+
+export type HelpSelection = { app_id: string; app_name: string; manifest_hash: string; locales: string[] };
+type Row = {
+  app_id: string;
+  app_name: string;
+  manifest_hash: string;
+  locale: string;
+  document_id: string;
+  title: string;
+  description: string | null;
+  icon: string | null;
+  sort_order: number;
+  markdown?: string;
+};
+export const metadata = (row: Row): HelpMetadata => ({
+  appId: row.app_id,
+  appName: row.app_name,
+  manifestHash: row.manifest_hash,
+  locale: row.locale,
+  documentId: row.document_id,
+  title: row.title,
+  description: row.description ?? undefined,
+  icon: row.icon ?? undefined,
+  order: row.sort_order,
+});
+
+export const hasHelpBm25 = async (db: SQL = sql): Promise<boolean> => {
+  const [row] = await db<{ ready: boolean }[]>`SELECT
+    EXISTS (SELECT 1 FROM pg_extension WHERE extname='pg_textsearch') AND
+    (SELECT count(*) = 3 FROM pg_index i JOIN pg_class c ON c.oid=i.indexrelid JOIN pg_am a ON a.oid=c.relam
+      WHERE c.oid IN (to_regclass('help.help_bm25_english_idx'), to_regclass('help.help_bm25_german_idx'),
+        to_regclass('help.help_bm25_simple_idx')) AND i.indisvalid AND a.amname='bm25') AS ready`;
+  return row?.ready === true;
+};
+
+/** Locale precedence is applied before matching, ranking and limiting, including partial translations. */
+export const queryHelp = async (
+  selection: HelpSelection[],
+  input: {
+    query?: string;
+    documentId?: string;
+    body?: boolean;
+    limit?: number;
+    cursor?: string;
+    bm25?: boolean;
+  },
+  db: SQL = sql,
+): Promise<Row[]> => {
+  if (!selection.length) return [];
+  const ranked = input.query !== undefined;
+  const nativeRank = `ts_rank_cd(d.search_document, websearch_to_tsquery(d.search_config::regconfig, $2))`;
+  const bm25Rank = `CASE d.search_config ${searchConfigs
+    .map((config) => `WHEN '${config}' THEN d.search_text <@> to_bm25query($2, 'help.help_bm25_${config}_idx')`)
+    .join(" ")} END`;
+  const matching = searchConfigs
+    .map((config) => `(d.search_config='${config}' AND d.search_document @@ websearch_to_tsquery('${config}', $2))`)
+    .join(" OR ");
+  const pending = db.unsafe<Row[]>(
+    `WITH active AS (
+    SELECT * FROM jsonb_to_recordset(($1::text)::jsonb) AS a(app_id text, app_name text, manifest_hash text, locales text[])
+  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order
+    ${input.body ? ", d.markdown" : ""}
+    FROM help.documents d JOIN active a ON a.app_id=d.app_id AND a.manifest_hash=d.manifest_hash
+    WHERE length($2::text) >= 0 AND d.locale=ANY(a.locales)
+      AND NOT EXISTS (SELECT 1 FROM help.documents preferred
+        WHERE preferred.app_id=d.app_id AND preferred.manifest_hash=d.manifest_hash AND preferred.document_id=d.document_id
+          AND preferred.locale=ANY(a.locales) AND array_position(a.locales, preferred.locale)<array_position(a.locales, d.locale))
+      AND ($3::text IS NULL OR d.document_id=$3)
+      AND ($4::text IS NULL OR ('cloud://help/' || d.app_id || '/' || d.document_id) COLLATE "C" > $4)
+      ${ranked ? `AND (lower(d.document_id)=lower($2) OR lower(d.title)=lower($2) OR ${matching})` : ""}
+    ORDER BY ${
+      ranked
+        ? `(lower(d.document_id)=lower($2) OR lower(d.title)=lower($2)) DESC,
+      ${input.bm25 ? bm25Rank + " ASC," : ""} ${nativeRank} DESC,`
+        : ""
+    }
+      d.app_id COLLATE "C", ${input.cursor !== undefined ? "" : "d.sort_order,"} d.document_id COLLATE "C"
+    ${input.limit !== undefined ? "LIMIT $5" : ""}`,
+    [
+      JSON.stringify(selection),
+      input.query ?? "",
+      input.documentId ?? null,
+      input.cursor ?? null,
+      ...(input.limit !== undefined ? [input.limit] : []),
+    ],
+  );
+  // Match the app publication write deadline and bound abandoned reads at the driver.
+  const timeout = setTimeout(() => pending.cancel(), 10_000);
+  try {
+    return await pending;
+  } finally {
+    clearTimeout(timeout);
+  }
+};

package/src/services/help/types.ts

@@ -0,0 +1,46 @@
+import type { AppRegistryHelpSummary } from "../../contracts/registry";
+import type { HelpDocumentManifest } from "../../shared/help";
+
+export type HelpDocument = {
+  id: string;
+  title: string;
+  icon?: string;
+  description?: string;
+  order: number;
+  markdown: string;
+  searchText: string;
+};
+
+export type HelpCorpus = {
+  appId: string;
+  manifestHash: string;
+  baseLocale: string;
+  documents: readonly HelpDocument[];
+  documentsByLocale: Readonly<Record<string, readonly HelpDocument[]>>;
+};
+
+export type HelpMetadata = {
+  appId: string;
+  appName: string;
+  manifestHash: string;
+  locale: string;
+  documentId: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  order: number;
+};
+export type HelpArticle = HelpMetadata & { markdown: string };
+export type HelpMatch = Pick<HelpMetadata, "appId" | "appName" | "locale" | "documentId" | "title" | "description"> & { kind: "help" };
+export type HelpSearchInput = { query: string; appId?: string; limit?: number };
+export type HelpReadInput = { appId: string; documentId: string };
+export type HelpManifestResult = AppRegistryHelpSummary & { locale: string; documents: readonly HelpDocumentManifest[] };
+
+/** One request's language; operations resolve the current published app versions. */
+export type HelpReader = {
+  manifest(appId: string): Promise<HelpManifestResult | null>;
+  list(cursor?: string): Promise<HelpMetadata[]>;
+  search(input: HelpSearchInput): Promise<HelpMatch[]>;
+  read(input: HelpReadInput): Promise<HelpArticle | null>;
+};
+export type HelpReaderFactory = (locale: string) => HelpReader;