@cosmicdrift/kumiko-samples 0.404.1 → 0.405.0

package/packages/bundled-features/src/folders/web/folder-manager.tsx

@@ -26,14 +26,10 @@
 // src (node_modules is ignored by default) or these classes never compile. money-
 // horse already does; that scan is a real shipping requirement for any host.
 
-import {
-  useDispatcher,
-  usePrimitives,
-  useQuery,
-  useTranslation,
-} from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { ChevronRight, File, Folder, type LucideIcon, Pencil, Plus, Trash2 } from "lucide-react";
 import { type DragEvent, type ReactNode, useEffect, useState } from "react";
+import { useDispatchedWrites } from "../../shared/web/use-dispatched-writes.ts";
 import { FoldersHandlers, FoldersQueries } from "./constants.ts";
 import { buildFolderTree, type FolderNode, type FolderRow } from "./tree.ts";
 
@@ -99,13 +95,15 @@ export function FolderManager({
 }): ReactNode {
   const { Banner, Button, Dialog, Input, Text } = usePrimitives();
   const t = useTranslation();
-  const dispatcher = useDispatcher();
   const catalog = useQuery<FolderListResponse>(FoldersQueries.folderList, {});
   const [pending, setPending] = useState<Pending>(null);
   const [draftName, setDraftName] = useState("");
   const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(loadCollapsed);
-  const [busy, setBusy] = useState(false);
-  const [errorKey, setErrorKey] = useState<string | null>(null);
+  const { busy, setBusy, errorKey, setErrorKey, writeOk, apply } = useDispatchedWrites(async () => {
+    setPending(null);
+    await catalog.refetch();
+    await filing?.onReassigned();
+  });
   const [dragOverKey, setDragOverKey] = useState<string | null>(null);
   const [pendingDelete, setPendingDelete] = useState<FolderNode | null>(null);
 
@@ -177,29 +175,6 @@ export function FolderManager({
     setPending({ mode: "rename", id: folder.id, version: folder.version });
   };
 
-  const apply = async (write: () => Promise<boolean>): Promise<void> => {
-    setBusy(true);
-    setErrorKey(null);
-    try {
-      if (await write()) {
-        setPending(null);
-        await catalog.refetch();
-        await filing?.onReassigned();
-      }
-    } finally {
-      setBusy(false);
-    }
-  };
-
-  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
-    const result = await dispatcher.write(type, payload);
-    if (!result.isSuccess) {
-      setErrorKey(result.error.i18nKey);
-      return false;
-    }
-    return true;
-  };
-
   const saveDraft = (): void => {
     const name = draftName.trim();
     if (name === "" || pending === null) return;

package/packages/bundled-features/src/folders/web/folder-section.tsx

@@ -18,6 +18,7 @@ import {
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useState } from "react";
+import { useDispatchedWrites } from "../../shared/web/use-dispatched-writes.ts";
 import { FoldersHandlers, FoldersQueries } from "./constants.ts";
 import { type FolderRow, folderPath } from "./tree.ts";
 
@@ -58,8 +59,10 @@ export function FolderSection({
     { enabled },
   );
   const [newName, setNewName] = useState("");
-  const [busy, setBusy] = useState(false);
-  const [errorKey, setErrorKey] = useState<string | null>(null);
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+  const { busy, errorKey, setErrorKey, writeOk, apply } = useDispatchedWrites(refetch);
 
   if (entityId === null) {
     return (
@@ -95,29 +98,6 @@ export function FolderSection({
     ...folders.map((f) => ({ value: f.id, label: folderPath(folders, f.id) })),
   ];
 
-  const refetch = async (): Promise<void> => {
-    await Promise.all([catalog.refetch(), assignments.refetch()]);
-  };
-
-  const apply = async (write: () => Promise<boolean>): Promise<void> => {
-    setBusy(true);
-    setErrorKey(null);
-    try {
-      if (await write()) await refetch();
-    } finally {
-      setBusy(false);
-    }
-  };
-
-  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
-    const result = await dispatcher.write(type, payload);
-    if (!result.isSuccess) {
-      setErrorKey(result.error.i18nKey);
-      return false;
-    }
-    return true;
-  };
-
   const onSelect = (next: string): void => {
     if (next === currentFolderId) return;
     void apply(() =>

package/packages/bundled-features/src/form-draft/handlers/save.write.ts

@@ -1,6 +1,7 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { failUnprocessable, type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { isUniqueConstraintFailure } from "../../shared/index.ts";
 import { countDraftsByOwner } from "../db/queries/draft-count.ts";
 import { formDraftExecutor } from "../executor.ts";
 import { lookupDraft } from "../lookup.ts";
@@ -11,6 +12,9 @@ import {
   FORM_DRAFT_UNIQUE_KEY_CONSTRAINT,
 } from "../web/constants.ts";
 
+const SAVE_DRAFT_COUNT_REASON =
+  "COUNT(*) of the caller's own drafts without loading 64KB value blobs";
+
 /**
  * save is an upsert keyed on (tenantId, ownerId, draftKey) — same
  * lookup-then-create|update-with-race-retry idiom as
@@ -20,20 +24,6 @@ import {
  * winner's row, and updates it (with the winner's version) instead of
  * erroring.
  */
-function isDraftKeyConflict(failure: WriteFailure): boolean {
-  const error = failure.error as {
-    code?: string;
-    details?: { constraintName?: string };
-  }; // @cast-boundary error-details
-  return (
-    error.code === "unique_violation" &&
-    error.details?.constraintName === FORM_DRAFT_UNIQUE_KEY_CONSTRAINT
-  );
-}
-
-const SAVE_DRAFT_COUNT_REASON =
-  "COUNT(*) of the caller's own drafts without loading 64KB value blobs";
-
 export const saveDraftWrite = defineWriteHandler({
   name: "save",
   schema: saveDraftPayloadSchema,
@@ -69,7 +59,7 @@ export const saveDraftWrite = defineWriteHandler({
 
     const result = await formDraftExecutor.create({ ownerId, draftKey, draft }, event.user, ctx.db);
     if (result.isSuccess) return result;
-    if (!isDraftKeyConflict(result)) return result;
+    if (!isUniqueConstraintFailure(result, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT)) return result;
 
     const winner = await lookupDraft(ctx.db, event.user.tenantId, ownerId, draftKey);
     if (!winner) return result;

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -228,12 +228,8 @@ export function createInboundMailFoundationFeature(options: InboundMailRoleOptio
 
       // Plugin extension point — providers register via
       // r.useExtension("inboundMailProvider", "<key>", plugin).
-      r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
-        onRegister: () => {
-          // No side-effects at register-time — lookup happens at runtime
-          // via resolveInboundProviderForKey/-Account.
-        },
-      });
+      // Lookup happens at runtime via resolveInboundProviderForKey/-Account.
+      r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {});
 
       // Sync machinery: high-frequency tick state, deliberately NOT
       // event-sourced — r.storeTable keeps the migration DDL but excludes the

package/packages/bundled-features/src/inbound-mail-foundation/oauth-state.ts

@@ -11,9 +11,10 @@
 // in the HMAC input, timing-safe comparison, expiry in the clear-text
 // segment).
 
-import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { hmacSignatureMatches, signHmacSha256Base64Url } from "../shared/index.ts";
 
 const STATE_PURPOSE = "inbound-mail-oauth-connect";
 
@@ -34,10 +35,6 @@ export type VerifyOAuthStateResult =
   | { readonly ok: true; readonly payload: OAuthStatePayload }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
-function sign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
-}
-
 function hmacInput(payloadB64: string, expiresAtMs: number): string {
   return `${STATE_PURPOSE}:${payloadB64}.${expiresAtMs}`;
 }
@@ -51,7 +48,7 @@ export function signOAuthState(
   const full: OAuthStatePayload = { ...payload, nonce: randomUUID() };
   const payloadB64 = Buffer.from(JSON.stringify(full), "utf8").toString("base64url");
   const expiresAtMs = now.add({ minutes: ttlMinutes }).epochMilliseconds;
-  const signature = sign(hmacInput(payloadB64, expiresAtMs), secret);
+  const signature = signHmacSha256Base64Url(hmacInput(payloadB64, expiresAtMs), secret);
   return `${payloadB64}.${expiresAtMs}.${signature}`;
 }
 
@@ -70,13 +67,8 @@ export function verifyOAuthState(
     return { ok: false, reason: "malformed" };
   }
 
-  const expected = sign(hmacInput(payloadB64, expiresAtMs), secret);
-  const expectedBuf = Buffer.from(expected, "base64url");
-  const providedBuf = Buffer.from(providedSig, "base64url");
-  // Check the length before timingSafeEqual: it throws on a length mismatch,
-  // and the throw itself leaks information through timing.
-  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+  const expected = signHmacSha256Base64Url(hmacInput(payloadB64, expiresAtMs), secret);
+  if (!hmacSignatureMatches(expected, providedSig)) return { ok: false, reason: "bad_signature" };
 
   if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
     return { ok: false, reason: "expired" };

package/packages/bundled-features/src/inbound-mail-foundation/tenant-destroy-hook.ts

@@ -16,8 +16,8 @@
 // unreadable. These hooks dispose of the rows.
 
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
-import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
-import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
+import type { TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveAndDeleteTenantRows } from "../tenant-lifecycle/index.ts";
 import { seenMessageTable, syncCursorTable } from "./entities.ts";
 import {
   INBOUND_MESSAGE_AGGREGATE_TYPE,
@@ -32,31 +32,21 @@ import {
 } from "./projection.ts";
 import { quarantineTable } from "./quarantine-entities.ts";
 
-const ARCHIVED_BY = "tenant-lifecycle:destroy";
-const REASON = "tenant_destroy";
-
 // archiveStream sits outside TenantDb's own methods — needs the escape hatch.
 export const INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON =
   "tenant-destroy archives each inbound-mail entity's event-streams before the projection rows are deleted";
 
-async function archiveAndDeleteRows(
+function archiveAndDeleteRows(
   ctx: TenantDataHookCtx,
   table: EntityTableMeta,
   aggregateType: string,
 ): Promise<readonly string[]> {
-  declareEscapeHatch({ reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON });
-  const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
-  for (const row of rows) {
-    await archiveStream(ctx.db.unsafeRaw(), {
-      tenantId: ctx.tenantId,
-      aggregateId: row.id,
-      aggregateType,
-      archivedBy: ARCHIVED_BY,
-      reason: REASON,
-    });
-  }
-  await ctx.db.deleteMany(table, { tenantId: ctx.tenantId });
-  return rows.map((row) => row.id);
+  return archiveAndDeleteTenantRows(
+    ctx,
+    table,
+    aggregateType,
+    INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON,
+  );
 }
 
 export async function mailAccountTenantDestroyHook(ctx: TenantDataHookCtx): Promise<void> {

package/packages/bundled-features/src/jobs/handlers/tenant-failures.query.ts

@@ -2,8 +2,8 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { serializeJobSubject } from "@cosmicdrift/kumiko-framework/jobs";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import { parseSubject } from "../parse-subject.ts";
 import { tenantJobFailuresTable } from "../tenant-job-failure-table.ts";
 
 type TenantJobFailureRow = {
@@ -16,20 +16,6 @@ type TenantJobFailureRow = {
 
 const DEFAULT_LIMIT = 50;
 
-function isSubjectEntry(value: unknown): value is [string, unknown] {
-  return Array.isArray(value) && typeof value[0] === "string";
-}
-
-function parseSubject(stored: string | null): Record<string, unknown> | null {
-  if (stored === null) return null;
-  // A corrupt subject must not fail the whole list — the record still tells
-  // the tenant which job failed and why. parseJsonSafe only survives a
-  // SyntaxError, so the shape needs its own check.
-  const parsed = parseJsonSafe<unknown>(stored, null);
-  if (!Array.isArray(parsed)) return null;
-  return Object.fromEntries(parsed.filter(isSubjectEntry));
-}
-
 export function createTenantFailuresQuery(readRoles: readonly string[]) {
   return defineQueryHandler({
     name: "failures",

package/packages/bundled-features/src/jobs/handlers/tenant-runs.query.ts

@@ -2,8 +2,8 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { serializeJobSubject } from "@cosmicdrift/kumiko-framework/jobs";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import { parseSubject } from "../parse-subject.ts";
 import { type TenantJobRunStatus, tenantJobRunsTable } from "../tenant-job-run-table.ts";
 
 type TenantJobRunRow = {
@@ -19,19 +19,6 @@ type TenantJobRunRow = {
 
 const DEFAULT_LIMIT = 50;
 
-function isSubjectEntry(value: unknown): value is [string, unknown] {
-  return Array.isArray(value) && typeof value[0] === "string";
-}
-
-function parseSubject(stored: string | null): Record<string, unknown> | null {
-  if (stored === null) return null;
-  // A corrupt subject must not fail the whole list; parseJsonSafe only
-  // survives a SyntaxError, so the shape needs its own check.
-  const parsed = parseJsonSafe<unknown>(stored, null);
-  if (!Array.isArray(parsed)) return null;
-  return Object.fromEntries(parsed.filter(isSubjectEntry));
-}
-
 export function createTenantRunsQuery(readRoles: readonly string[]) {
   return defineQueryHandler({
     name: "tenant-runs",

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -153,6 +153,27 @@ async function encryptLogMessages<T extends { readonly message: string }>(
   }));
 }
 
+async function insertEncryptedRunLogs(
+  db: DbConnection,
+  runId: string,
+  triggeredById: string | null,
+  logs: readonly { readonly level: string; readonly message: string; readonly timestamp: string }[],
+): Promise<void> {
+  // skip: empty log batch — the worker ran silent, no child rows to insert
+  if (logs.length === 0) return;
+  const encryptedLogs = await encryptLogMessages(logs, triggeredById);
+  await insertMany(
+    db,
+    jobRunLogsTable,
+    encryptedLogs.map((log) => ({
+      runId,
+      level: log.level,
+      message: log.message,
+      timestamp: parseJobInstant(log.timestamp),
+    })),
+  );
+}
+
 // Mirrors encryptFailureError for the failure-path `error` column:
 // stored alongside logs[].message under the same triggering user's DEK, so
 // a log/error pair from the same failed run decrypt together or erase
@@ -349,14 +370,7 @@ async function recordTenantRunOutcome(
   // A failed attempt BullMQ will retry goes back to waiting: the tenant keeps
   // seeing pending work, not a failure the next attempt may still resolve.
   if (result === "failed" && !outcome.finalAttempt) {
-    await inTenantScope(key.tenantId, () =>
-      updateMany(
-        db,
-        tenantJobRunsTable,
-        { status: "queued", startedAt: null, finishedAt: null, updatedAt: now },
-        { tenantId: key.tenantId, jobName, bullJobId },
-      ),
-    );
+    await markTenantRunQueued(db, key.tenantId, jobName, bullJobId, now);
     // skip: retry pending, the row stays active until the final attempt
     return;
   }
@@ -403,12 +417,22 @@ async function requeueTenantRun(
   const key = tenantRunKey(jobName, meta.tenantVisibleRun.tenantId, meta.tenantVisibleRun.subject);
   // skip: system-tenant run, no tenant-scoped query reads it
   if (!key) return;
-  await inTenantScope(key.tenantId, () =>
+  await markTenantRunQueued(db, key.tenantId, jobName, bullJobId, Temporal.Now.instant());
+}
+
+async function markTenantRunQueued(
+  db: DbConnection,
+  tenantId: string,
+  jobName: string,
+  bullJobId: string,
+  updatedAt: Temporal.Instant,
+): Promise<void> {
+  await inTenantScope(tenantId, () =>
     updateMany(
       db,
       tenantJobRunsTable,
-      { status: "queued", startedAt: null, finishedAt: null, updatedAt: Temporal.Now.instant() },
-      { tenantId: key.tenantId, jobName, bullJobId },
+      { status: "queued", startedAt: null, finishedAt: null, updatedAt },
+      { tenantId, jobName, bullJobId },
     ),
   );
 }
@@ -672,21 +696,7 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
         },
         { id: runId },
       );
-      // skip: empty log batch — the worker ran silent. No child rows to
-      // insert; the status update above already recorded completion.
-      if (payload.logs.length > 0) {
-        const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
-        await insertMany(
-          db,
-          jobRunLogsTable,
-          encryptedLogs.map((log) => ({
-            runId,
-            level: log.level,
-            message: log.message,
-            timestamp: parseJobInstant(log.timestamp),
-          })),
-        );
-      }
+      await insertEncryptedRunLogs(db, runId, triggeredById, payload.logs);
       runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
     },
 
@@ -746,20 +756,7 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
         },
         { id: runId },
       );
-      // skip: empty log batch — mirror of onJobComplete
-      if (payload.logs.length > 0) {
-        const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
-        await insertMany(
-          db,
-          jobRunLogsTable,
-          encryptedLogs.map((log) => ({
-            runId,
-            level: log.level,
-            message: log.message,
-            timestamp: parseJobInstant(log.timestamp),
-          })),
-        );
-      }
+      await insertEncryptedRunLogs(db, runId, triggeredById, payload.logs);
       runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
     },
   };

package/packages/bundled-features/src/jobs/parse-subject.ts

@@ -0,0 +1,15 @@
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+
+function isSubjectEntry(value: unknown): value is [string, unknown] {
+  return Array.isArray(value) && typeof value[0] === "string";
+}
+
+// A corrupt subject must not fail the whole list: the record still tells the
+// tenant which job failed. parseJsonSafe only survives a SyntaxError, so the
+// shape needs its own check.
+export function parseSubject(stored: string | null): Record<string, unknown> | null {
+  if (stored === null) return null;
+  const parsed = parseJsonSafe<unknown>(stored, null);
+  if (!Array.isArray(parsed)) return null;
+  return Object.fromEntries(parsed.filter(isSubjectEntry));
+}

package/packages/bundled-features/src/ledger/feature.ts

@@ -21,6 +21,7 @@ import {
   defineFeature,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveFeatureAccess } from "../shared/index.ts";
 import { accountEntity, scheduleEntity, transactionEntity } from "./entity.ts";
 import { createConfirmSchedulePeriodHandler } from "./handlers/confirm-schedule-period.write.ts";
 import { createCreateTransactionHandler } from "./handlers/create-transaction.write.ts";
@@ -166,18 +167,12 @@ export type LedgerFeatureOptions = {
   readonly toggleable?: LedgerToggleable;
 };
 
-function resolveAccess(opts: LedgerFeatureOptions): AccessRule {
-  if (opts.access !== undefined) return opts.access;
-  if (opts.roles !== undefined) return { roles: opts.roles };
-  return DEFAULT_LEDGER_ACCESS;
-}
-
 // Options wrapper. Without options returns the module-level singleton (no
 // rebuild). access/roles/toggleable build a fresh feature-definition.
 export function createLedgerFeature(opts: LedgerFeatureOptions = {}): typeof defaultLedgerFeature {
   if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
     return defaultLedgerFeature;
   }
-  const access = resolveAccess(opts);
+  const access = resolveFeatureAccess(opts, DEFAULT_LEDGER_ACCESS);
   return defineFeature(LEDGER_FEATURE_NAME, (r) => registerLedger(r, access, opts.toggleable));
 }

package/packages/bundled-features/src/mail-foundation/feature.ts

@@ -141,13 +141,9 @@ export function createMailFoundationFeature() {
       // Plugin extension-point. Provider-features register here. The
       // entityName at registration time becomes the value tenants pick in
       // `provider` config-key (e.g. "smtp", "brevo-api").
-      r.extendsRegistrar(MAIL_TRANSPORT_EXTENSION, {
-        onRegister: () => {
-          // No side-effects at register-time — the registry stores the
-          // usage, factory looks it up at request-time. Same shape as
-          // delivery's extendsRegistrar.
-        },
-      });
+      // The registry stores the usage, factory looks it up at request-time. Same shape as
+      // delivery's extendsRegistrar.
+      r.extendsRegistrar(MAIL_TRANSPORT_EXTENSION, {});
 
       // Empty = this tenant has no own provider: tenantMailTransport yields null and
       // channel-email uses the app transport, so empty is a valid choice a tenant can

package/packages/bundled-features/src/managed-pages/render-page-body.ts

@@ -1,4 +1,5 @@
 import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { createLruCache } from "@cosmicdrift/kumiko-framework/utils";
 import { renderSafeMarkdown } from "../page-render/index.ts";
 import { sanitizeDocumentHtml } from "../template-resolver/index.ts";
 import type { BodyFormat } from "./constants.ts";
@@ -29,8 +30,7 @@ export type PageBodyRendererDeps = {
 };
 
 // Every write bumps the version, so a (page, version) key never serves stale
-// HTML. A Map keeps insertion order: delete+reinsert on a hit makes the first
-// key the least recently used one.
+// HTML.
 function cacheKeyOf(page: RenderablePageBody): string {
   return [page.tenantId, page.slug, page.lang, page.version, page.updatedAt, page.bodyFormat].join(
     "\u0000",
@@ -47,7 +47,7 @@ export function createPageBodyRenderer(
   const sanitizeDocument = deps.sanitizeDocument ?? sanitizeDocumentHtml;
   const renderMarkdown = deps.renderMarkdown ?? renderSafeMarkdown;
   const maxEntries = deps.maxEntries ?? MAX_CACHED_BODIES;
-  const cache = new Map<string, string>();
+  const cache = createLruCache<string, string>({ maxEntries });
 
   function renderUncached(page: RenderablePageBody, log: WarnLogger): string {
     if (page.bodyFormat === "markdown") return renderMarkdown(page.body);
@@ -63,18 +63,10 @@ export function createPageBodyRenderer(
   return (page, log = defaultLog) => {
     const key = cacheKeyOf(page);
     const cached = cache.get(key);
-    if (cached !== undefined) {
-      cache.delete(key);
-      cache.set(key, cached);
-      return cached;
-    }
+    if (cached !== undefined) return cached;
     const html = renderUncached(page, log);
     if (html.length > MAX_CACHED_BODY_LENGTH) return html;
     cache.set(key, html);
-    if (cache.size > maxEntries) {
-      const oldest = cache.keys().next();
-      if (!oldest.done) cache.delete(oldest.value);
-    }
     return html;
   };
 }

package/packages/bundled-features/src/notes-history/feature.ts

@@ -20,7 +20,7 @@ import {
   type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { assertNoWhereRuleInOwnershipWrite } from "../shared/index.ts";
+import { assertNoWhereRuleInOwnershipWrite, resolveFeatureAccess } from "../shared/index.ts";
 import { createNoteEntryEntity, noteMentionEntity } from "./entity.ts";
 import { createNoteEntryExecutor } from "./executor.ts";
 import { createAddNoteHandler } from "./handlers/add-note.write.ts";
@@ -104,12 +104,6 @@ export type NotesHistoryFeatureOptions = {
   readonly parents?: readonly string[];
 };
 
-function resolveAccess(opts: NotesHistoryFeatureOptions): AccessRule {
-  if (opts.access !== undefined) return opts.access;
-  if (opts.roles !== undefined) return { roles: opts.roles };
-  return DEFAULT_NOTES_HISTORY_ACCESS;
-}
-
 // Options wrapper. Without options returns the module-level singleton (no
 // rebuild). access/roles/ownership build a fresh feature-definition.
 export function createNotesHistoryFeature(
@@ -135,6 +129,11 @@ export function createNotesHistoryFeature(
     );
   }
   return defineFeature(NOTES_HISTORY_FEATURE_NAME, (r) =>
-    registerNotesHistory(r, resolveAccess(opts), opts.ownership, opts.parents),
+    registerNotesHistory(
+      r,
+      resolveFeatureAccess(opts, DEFAULT_NOTES_HISTORY_ACCESS),
+      opts.ownership,
+      opts.parents,
+    ),
   );
 }

package/packages/bundled-features/src/personal-access-tokens/handlers/list.query.ts

@@ -4,6 +4,7 @@ import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.ts";
 import { isExpiredAt } from "../expiry.ts";
+import { parseScopeNames } from "../parse-scope-names.ts";
 import { apiTokenTable } from "../schema/api-token.ts";
 
 // `sort` arrives raw from the client's query string. selectMany's orderBy has
@@ -28,15 +29,6 @@ function tokenStatus(row: {
   return "active";
 }
 
-function parseScopeNames(raw: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
-  } catch {
-    return [];
-  }
-}
-
 // The caller's own tokens — metadata only, never the hash or plaintext.
 // Includes revoked/expired rows so the UI can show history; `prefix` is the
 // only fragment of the secret ever exposed.

package/packages/bundled-features/src/personal-access-tokens/hash.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
 import { generateToken, PAT_TOKEN_PREFIX } from "@cosmicdrift/kumiko-framework/api";
+import { hashOpaqueTokenSync } from "@cosmicdrift/kumiko-framework/crypto";
 import { PAT_PREFIX_DISPLAY_LENGTH } from "./web/constants.ts";
 
 // A PAT is high-entropy (32 random bytes from generateToken). A single SHA-256
@@ -8,7 +8,7 @@ import { PAT_PREFIX_DISPLAY_LENGTH } from "./web/constants.ts";
 // passwords). Only the hash is persisted — the plaintext exists once, in the
 // create response.
 export function hashPatToken(rawToken: string): string {
-  return createHash("sha256").update(rawToken).digest("hex");
+  return hashOpaqueTokenSync(rawToken);
 }
 
 export function mintPatToken(): { raw: string; hash: string; prefix: string } {

package/packages/bundled-features/src/personal-access-tokens/parse-scope-names.ts

@@ -0,0 +1,9 @@
+// Drops non-string entries rather than rejecting the whole array.
+export function parseScopeNames(raw: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
+  } catch {
+    return [];
+  }
+}