@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/renderer-foundation/types.d.ts

@@ -1,55 +1,82 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
+import type { LinkedResourceEntry, MailTemplateMeta, PdfPageFormat, PdfTemplateMeta, TemplateScope } from "../template-resolver/index.js";
 import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.js";
 export type RenderRequest = {
-    kind: "notification";
-    payload: NotificationPayload;
-} | {
-    kind: "mail-html";
-    payload: MailHtmlPayload;
+    kind: "mail";
+    payload: MailPayload;
 } | {
     kind: "document-pdf";
-    payload: DocumentPayload;
+    payload: DocumentPdfPayload;
     options?: PdfOptions;
 } | {
     kind: "image-snapshot";
     payload: DocumentPayload;
     options?: ImageOptions;
 };
-export type RenderResponse = {
-    kind: "notification";
-    html: string;
-    text?: string;
-} | {
-    kind: "mail-html";
+export type RenderedTemplateRef = {
+    readonly templateId: string;
+    readonly templateVersion: number;
+    readonly scope: TemplateScope;
+};
+export type RenderProvenance = {
+    readonly template?: RenderedTemplateRef;
+    readonly layout?: RenderedTemplateRef;
+};
+export type InlineAttachmentRef = {
+    readonly kind: "inline";
+    readonly cid: string;
+    readonly fileRefId: string;
+};
+export type FileAttachmentRef = {
+    readonly kind: "file";
+    readonly fileRefId: string;
+    readonly fileName: string;
+};
+export type RenderedPdfAttachmentRef = {
+    readonly kind: "rendered-pdf";
+    readonly templateSlug: string;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly fileName: string;
+    readonly locale?: string;
+};
+export type MailAttachmentRef = InlineAttachmentRef | FileAttachmentRef | RenderedPdfAttachmentRef;
+export type RenderResponse = ({
+    kind: "mail";
+    subject: string;
     html: string;
     text: string;
+    previewText?: string;
+    fromName?: string;
+    replyTo?: string;
+    attachments?: readonly MailAttachmentRef[];
 } | {
     kind: "document-pdf";
     pdfBytes: Uint8Array;
     pageCount: number;
     sizeBytes: number;
+    fileName: string;
 } | {
     kind: "image-snapshot";
     imageBytes: Uint8Array;
     format: "png" | "jpg";
     width: number;
     height: number;
+}) & RenderProvenance;
+export type MailDraft = {
+    readonly content: string;
+    readonly meta: MailTemplateMeta;
+    readonly variableSchema?: Readonly<Record<string, unknown>>;
+    /** Images and attachments of the row being edited; absent means those of the stored template. */
+    readonly linkedResources?: Readonly<Record<string, LinkedResourceEntry>>;
 };
-export type NotificationPayload = {
-    readonly template?: string;
-    readonly content?: string;
-    readonly contentFormat?: ContentFormat;
-    readonly variables?: Readonly<Record<string, unknown>>;
-    readonly locale?: string;
-};
-export type MailHtmlPayload = {
-    readonly template?: string;
-    readonly content?: string;
-    readonly contentFormat?: ContentFormat;
-    readonly variables?: Readonly<Record<string, unknown>>;
-    readonly locale?: string;
-    readonly subject?: string;
+export type MailPayload = {
+    readonly slug: string;
+    readonly locale: string;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly unsubscribeUrl?: string;
+    readonly draft?: MailDraft;
 };
 export type DocumentPayload = {
     readonly template?: string;
@@ -58,8 +85,35 @@ export type DocumentPayload = {
     readonly variables?: Readonly<Record<string, unknown>>;
     readonly locale?: string;
 };
+export type DocumentPdfPayload = {
+    readonly slug: string;
+    readonly locale: string;
+    readonly variables: Readonly<Record<string, unknown>>;
+};
+export type DocumentPdfDraft = {
+    readonly content: string;
+    readonly meta: PdfTemplateMeta | null;
+    readonly variableSchema?: Readonly<Record<string, unknown>>;
+};
+export type DocumentPreviewRequest = DocumentPdfPayload & {
+    readonly draft?: DocumentPdfDraft;
+};
+export type DocumentPreview = {
+    readonly title: string;
+    readonly fileName: string;
+    readonly bodyHtml: string;
+    readonly layout: {
+        readonly slug: string;
+        readonly scope: TemplateScope;
+        readonly headerHtml: string;
+        readonly signatureHtml: string;
+        readonly footerHtml: string;
+    } | null;
+    /** Image keys the body or the layout asks for that no file is linked to. */
+    readonly missingResourceKeys: readonly string[];
+};
 export type PdfOptions = {
-    readonly format?: "A4" | "Letter";
+    readonly format?: PdfPageFormat;
     readonly marginMm?: {
         top?: number;
         right?: number;
@@ -70,6 +124,7 @@ export type PdfOptions = {
     readonly footerTemplate?: string;
     readonly printBackground?: boolean;
     readonly displayHeaderFooter?: boolean;
+    readonly landscape?: boolean;
 };
 export type ImageOptions = {
     readonly width?: number;
@@ -78,18 +133,25 @@ export type ImageOptions = {
     readonly quality?: number;
 };
 export type RendererContext = {
-    readonly db: DbConnection;
+    readonly db: DbRunner | TenantDb;
     readonly registry: Registry;
     readonly tenantId: TenantId;
+    /** Tenant-scoped config for plugins that read the tenant currency or
+     *  branding; plugins fall back to request defaults when absent. */
+    readonly config?: ConfigAccessor;
+    /** Only plugins that embed resource bytes (PDF) need it; without it images are dropped. */
+    readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
 };
 export type RendererPlugin = {
     readonly name: string;
     readonly kinds: ReadonlyArray<RenderKind>;
     render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+    /** Optional: plugins that print documents offer a preview that never reaches the print service. */
+    previewDocument?(req: DocumentPreviewRequest, ctx: RendererContext): Promise<DocumentPreview>;
 };
 export declare class RendererError extends Error {
-    readonly code: "no_plugin_for_kind" | "invalid_payload" | "other";
-    constructor(message: string, code: "no_plugin_for_kind" | "invalid_payload" | "other");
+    readonly code: "no_plugin_for_kind" | "invalid_payload" | "unavailable" | "other";
+    constructor(message: string, code: "no_plugin_for_kind" | "invalid_payload" | "unavailable" | "other");
 }
 export type RendererRegistrationPlugin = Omit<RendererPlugin, "name">;
 export declare function isRendererRegistrationPlugin(o: unknown): o is RendererRegistrationPlugin;

package/dist/renderer-pdf/feature.js

@@ -13,7 +13,13 @@ export async function renderTablePdfRequest(req) {
         ...(req.options?.format && { format: req.options.format }),
         ...(req.options?.marginMm && { marginMm: req.options.marginMm }),
     });
-    return { kind: "document-pdf", pdfBytes, pageCount, sizeBytes: pdfBytes.byteLength };
+    return {
+        kind: "document-pdf",
+        pdfBytes,
+        pageCount,
+        sizeBytes: pdfBytes.byteLength,
+        fileName: `${req.payload.slug}.pdf`,
+    };
 }
 export function createRendererPdfFeature() {
     return defineFeature("renderer-pdf", (r) => {

package/dist/renderer-pdf/render-table-pdf.d.ts

@@ -1,54 +1,48 @@
 import * as z from "zod";
-export declare const pdfTableDocumentSchema: z.ZodObject<{
+import type { PdfPageFormat } from "../template-resolver/index.js";
+declare const pdfTableColumnSchema: z.ZodReadonly<z.ZodObject<{
+    header: z.ZodString;
+    weight: z.ZodOptional<z.ZodNumber>;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+    }>>;
+}, z.core.$strip>>;
+export declare const pdfTableDocumentSchema: z.ZodReadonly<z.ZodObject<{
     title: z.ZodString;
     subtitle: z.ZodOptional<z.ZodString>;
-    meta: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    meta: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
         label: z.ZodString;
         value: z.ZodString;
-    }, z.core.$strip>>>;
-    columns: z.ZodArray<z.ZodObject<{
+    }, z.core.$strip>>>>>;
+    columns: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
         header: z.ZodString;
         weight: z.ZodOptional<z.ZodNumber>;
         align: z.ZodOptional<z.ZodEnum<{
             left: "left";
             right: "right";
         }>>;
-    }, z.core.$strip>>;
-    rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>>;
+    rows: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodArray<z.ZodString>>>>;
     emptyText: z.ZodOptional<z.ZodString>;
     footerText: z.ZodOptional<z.ZodString>;
     pageLabel: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type PdfTableColumn = {
-    readonly header: string;
-    readonly weight?: number;
-    readonly align?: "left" | "right";
-};
-export type PdfTableDocument = {
-    readonly title: string;
-    readonly subtitle?: string;
-    readonly meta?: readonly {
-        readonly label: string;
-        readonly value: string;
-    }[];
-    readonly columns: readonly PdfTableColumn[];
-    readonly rows: readonly (readonly string[])[];
-    readonly emptyText?: string;
-    readonly footerText?: string;
-    /** Template with `{page}` and `{pages}`; default `"{page} / {pages}"`. */
-    readonly pageLabel?: string;
-};
+}, z.core.$strip>>;
+export type PdfTableColumn = z.infer<typeof pdfTableColumnSchema>;
+export type PdfTableDocument = z.infer<typeof pdfTableDocumentSchema>;
+declare const marginMmSchema: z.ZodReadonly<z.ZodObject<{
+    top: z.ZodOptional<z.ZodNumber>;
+    right: z.ZodOptional<z.ZodNumber>;
+    bottom: z.ZodOptional<z.ZodNumber>;
+    left: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
 export type PdfTableOptions = {
-    readonly format?: "A4" | "Letter";
-    readonly marginMm?: {
-        readonly top?: number;
-        readonly right?: number;
-        readonly bottom?: number;
-        readonly left?: number;
-    };
+    readonly format?: PdfPageFormat;
+    readonly marginMm?: z.input<typeof marginMmSchema>;
 };
 export type PdfTableResult = {
     readonly pdfBytes: Uint8Array;
     readonly pageCount: number;
 };
 export declare function renderTablePdf(doc: PdfTableDocument, options?: PdfTableOptions): Promise<PdfTableResult>;
+export {};

package/dist/renderer-pdf/render-table-pdf.js

@@ -1,22 +1,44 @@
 import { PDFDocument, rgb, StandardFonts } from "pdf-lib";
 import * as z from "zod";
 import { RendererError } from "../renderer-foundation/index.js";
-export const pdfTableDocumentSchema = z.object({
+// Upper bounds keep a hostile or runaway payload from exhausting memory and CPU in layout.
+const PDF_TABLE_MAX_ROWS = 10_000;
+const PDF_TABLE_MAX_COLUMNS = 30;
+const PDF_TABLE_MAX_CELL_LENGTH = 5_000;
+const pdfTableColumnSchema = z
+    .object({
+    header: z.string(),
+    weight: z.number().positive().optional(),
+    align: z.enum(["left", "right"]).optional(),
+})
+    .readonly();
+export const pdfTableDocumentSchema = z
+    .object({
     title: z.string(),
     subtitle: z.string().optional(),
-    meta: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
-    columns: z
-        .array(z.object({
-        header: z.string(),
-        weight: z.number().positive().optional(),
-        align: z.enum(["left", "right"]).optional(),
-    }))
-        .min(1),
-    rows: z.array(z.array(z.string())),
+    meta: z
+        .array(z.object({ label: z.string(), value: z.string() }).readonly())
+        .readonly()
+        .optional(),
+    columns: z.array(pdfTableColumnSchema).min(1).max(PDF_TABLE_MAX_COLUMNS).readonly(),
+    rows: z
+        .array(z.array(z.string().max(PDF_TABLE_MAX_CELL_LENGTH)).readonly())
+        .max(PDF_TABLE_MAX_ROWS)
+        .readonly(),
     emptyText: z.string().optional(),
     footerText: z.string().optional(),
+    // Template with `{page}` and `{pages}`; default `"{page} / {pages}"`.
     pageLabel: z.string().optional(),
-});
+})
+    .readonly();
+const marginMmSchema = z
+    .object({
+    top: z.number().nonnegative().optional(),
+    right: z.number().nonnegative().optional(),
+    bottom: z.number().nonnegative().optional(),
+    left: z.number().nonnegative().optional(),
+})
+    .readonly();
 const POINTS_PER_MM = 72 / 25.4;
 const PAGE_SIZE_POINTS = {
     A4: { width: 595.28, height: 841.89 },
@@ -31,6 +53,7 @@ const LINE_HEIGHT_FACTOR = 1.3;
 const CELL_PADDING_X = 4;
 const CELL_PADDING_Y = 3;
 const FOOTER_RESERVE = 16;
+const MIN_COLUMN_WIDTH = 20;
 const META_LABEL_GAP = 10;
 const BLOCK_GAP = 10;
 const REPLACEMENT_CHAR = "?";
@@ -46,7 +69,7 @@ function createEncodableText(font) {
     const supported = new Set(font.getCharacterSet());
     return (text) => {
         let result = "";
-        for (const char of text.replace(/\t/g, " ")) {
+        for (const char of text.replace(/\r\n?/g, "\n").replace(/\t/g, " ")) {
             const codePoint = char.codePointAt(0) ?? 0;
             result += codePoint === 0x0a || supported.has(codePoint) ? char : REPLACEMENT_CHAR;
         }
@@ -111,25 +134,22 @@ function assertRowShape(doc) {
         }
     });
 }
-export async function renderTablePdf(doc, options) {
-    if (doc.columns.length === 0) {
-        throw new RendererError("table needs at least one column", "invalid_payload");
+function resolveTableLayout(doc, options, fonts, clean) {
+    const marginMm = marginMmSchema.safeParse(options?.marginMm ?? {});
+    if (!marginMm.success) {
+        throw new RendererError("margins must be non-negative numbers", "invalid_payload");
     }
-    assertRowShape(doc);
-    const pdf = await PDFDocument.create({ updateMetadata: false });
-    const fonts = {
-        regular: await pdf.embedFont(StandardFonts.Helvetica),
-        bold: await pdf.embedFont(StandardFonts.HelveticaBold),
-    };
-    const clean = createEncodableText(fonts.regular);
     const pageSize = PAGE_SIZE_POINTS[options?.format ?? "A4"];
     const margin = {
-        top: (options?.marginMm?.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
-        right: (options?.marginMm?.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
-        bottom: (options?.marginMm?.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
-        left: (options?.marginMm?.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
+        top: (marginMm.data.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
+        right: (marginMm.data.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
+        bottom: (marginMm.data.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
+        left: (marginMm.data.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
     };
     const contentWidth = pageSize.width - margin.left - margin.right;
+    if (contentWidth < MIN_COLUMN_WIDTH * doc.columns.length) {
+        throw new RendererError("margins leave no room for table columns", "invalid_payload");
+    }
     const contentBottom = margin.bottom + FOOTER_RESERVE;
     const columnWidths = resolveColumnWidths(doc.columns, contentWidth);
     const bodyLineHeight = lineHeightFor(BODY_SIZE);
@@ -139,6 +159,33 @@ export async function renderTablePdf(doc, options) {
     }
     const headerLines = doc.columns.map((column, index) => wrapText(clean(column.header), fonts.bold, BODY_SIZE, (columnWidths[index] ?? contentWidth) - 2 * CELL_PADDING_X));
     const headerHeight = Math.max(...headerLines.map((lines) => lines.length)) * bodyLineHeight + 2 * CELL_PADDING_Y;
+    // A header this tall would leave every continuation page without room for a row.
+    if (rowSpaceOnEmptyPage - headerHeight < bodyLineHeight + 2 * CELL_PADDING_Y) {
+        throw new RendererError("table header leaves no room for rows", "invalid_payload");
+    }
+    return {
+        pageSize,
+        margin,
+        contentWidth,
+        contentBottom,
+        columnWidths,
+        bodyLineHeight,
+        headerLines,
+        headerHeight,
+    };
+}
+export async function renderTablePdf(doc, options) {
+    if (doc.columns.length === 0) {
+        throw new RendererError("table needs at least one column", "invalid_payload");
+    }
+    assertRowShape(doc);
+    const pdf = await PDFDocument.create({ updateMetadata: false });
+    const fonts = {
+        regular: await pdf.embedFont(StandardFonts.Helvetica),
+        bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+    };
+    const clean = createEncodableText(fonts.regular);
+    const { pageSize, margin, contentWidth, contentBottom, columnWidths, bodyLineHeight, headerLines, headerHeight, } = resolveTableLayout(doc, options, fonts, clean);
     let page = pdf.addPage([pageSize.width, pageSize.height]);
     let cursorY = pageSize.height - margin.top;
     function drawLines(lines, font, size, left, width, topY, align, color = TEXT_COLOR) {
@@ -154,14 +201,27 @@ export async function renderTablePdf(doc, options) {
             });
         });
     }
+    function startBlankPage() {
+        page = pdf.addPage([pageSize.width, pageSize.height]);
+        cursorY = pageSize.height - margin.top;
+    }
+    function ensureRoom(height) {
+        if (cursorY - height < contentBottom)
+            startBlankPage();
+    }
+    // Line by line, so a block taller than one page continues on the next.
+    function flowLines(lines, font, size, left, width, color = TEXT_COLOR) {
+        const lineHeight = lineHeightFor(size);
+        for (const line of lines) {
+            ensureRoom(lineHeight);
+            drawLines([line], font, size, left, width, cursorY, "left", color);
+            cursorY -= lineHeight;
+        }
+    }
     function drawIntroBlock() {
-        const titleLines = wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth);
-        drawLines(titleLines, fonts.bold, TITLE_SIZE, margin.left, contentWidth, cursorY, "left");
-        cursorY -= titleLines.length * lineHeightFor(TITLE_SIZE);
+        flowLines(wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth), fonts.bold, TITLE_SIZE, margin.left, contentWidth);
         if (doc.subtitle !== undefined) {
-            const subtitleLines = wrapText(clean(doc.subtitle), fonts.regular, SUBTITLE_SIZE, contentWidth);
-            drawLines(subtitleLines, fonts.regular, SUBTITLE_SIZE, margin.left, contentWidth, cursorY, "left", MUTED_COLOR);
-            cursorY -= subtitleLines.length * lineHeightFor(SUBTITLE_SIZE);
+            flowLines(wrapText(clean(doc.subtitle), fonts.regular, SUBTITLE_SIZE, contentWidth), fonts.regular, SUBTITLE_SIZE, margin.left, contentWidth, MUTED_COLOR);
         }
         const meta = doc.meta ?? [];
         if (meta.length > 0) {
@@ -171,9 +231,9 @@ export async function renderTablePdf(doc, options) {
                 META_LABEL_GAP;
             meta.forEach((entry, index) => {
                 const valueLines = wrapText(clean(entry.value), fonts.regular, BODY_SIZE, contentWidth - labelWidth);
+                ensureRoom(bodyLineHeight);
                 drawLines([labels[index] ?? ""], fonts.bold, BODY_SIZE, margin.left, labelWidth, cursorY, "left");
-                drawLines(valueLines, fonts.regular, BODY_SIZE, margin.left + labelWidth, contentWidth - labelWidth, cursorY, "left");
-                cursorY -= valueLines.length * bodyLineHeight;
+                flowLines(valueLines, fonts.regular, BODY_SIZE, margin.left + labelWidth, contentWidth - labelWidth);
             });
         }
         cursorY -= BLOCK_GAP;
@@ -235,6 +295,7 @@ export async function renderTablePdf(doc, options) {
         }
     }
     drawIntroBlock();
+    ensureRoom(headerHeight + bodyLineHeight + 2 * CELL_PADDING_Y);
     drawTableHeader();
     if (doc.rows.length === 0 && doc.emptyText !== undefined) {
         drawRow([

package/dist/secrets/feature.js

@@ -60,20 +60,21 @@ export function requireSecretsContext(ctx, handlerName) {
                 "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
         });
     }
-    const raw = ctx.secrets;
     const userId = ctx._userId;
     if (!userId) {
         throw new InternalError({
             message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
         });
     }
-    return {
+    const withAudit = (raw) => ({
+        withRunner: (runner) => withAudit(raw.withRunner(runner)),
         get: (tenantId, key, overrideAudit) => raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
         // No audit injection: has() is metadata-only and never logs a read.
         has: raw.has.bind(raw),
         set: raw.set.bind(raw),
         delete: raw.delete.bind(raw),
-    };
+    });
+    return withAudit(ctx.secrets);
 }
 function resolveSecretsAccess(opts) {
     if (opts.access !== undefined && opts.roles !== undefined) {

package/dist/secrets/handlers/delete.write.d.ts

@@ -4,4 +4,4 @@ export declare function createDeleteHandler(access?: AccessRule): import("@cosmi
     key: z.ZodString;
 }, z.core.$strip>, {
     key: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/secrets/handlers/set.write.d.ts

@@ -8,4 +8,4 @@ export declare function createSetHandler(access?: AccessRule): import("@cosmicdr
 }, z.core.$strip>, {
     key: string;
     redactedPreview: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/secrets/secrets-context.js

@@ -44,12 +44,21 @@ function resolveKey(keyOrHandle) {
     return typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
 }
 export function createSecretsContext(opts) {
-    const { db, masterKeyProvider } = opts;
+    const { masterKeyProvider } = opts;
     const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
+    return buildSecretsContext(opts, provider, opts.db, false);
+}
+// `runnerIsTransaction`: the runner is a caller-owned transaction, so audited reads join it
+// instead of opening a second connection (which would deadlock a small pool).
+function buildSecretsContext(opts, provider, db, runnerIsTransaction) {
+    const { masterKeyProvider } = opts;
     async function lookup(tenantId, key) {
         return fetchOne(db, tenantSecretsTable, { tenantId, key });
     }
     return {
+        withRunner(runner) {
+            return buildSecretsContext(opts, provider, runner, true);
+        },
         async get(tenantId, keyOrHandle, auditCtx) {
             const key = resolveKey(keyOrHandle);
             // Atomic audit + read: a decrypt that "escaped" the audit trail
@@ -65,7 +74,7 @@ export function createSecretsContext(opts) {
                 const plaintext = await decryptValue(decodeStoredEnvelope(existing.envelope), provider);
                 return createSecret(plaintext);
             }
-            const plaintext = await transaction(db, async (tx) => {
+            const readAndAudit = async (tx) => {
                 // Inline select inside the TX via raw client — fetchOne's connection
                 // type doesn't widen to the transaction object cleanly.
                 const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
@@ -99,7 +108,10 @@ export function createSecretsContext(opts) {
                     metadata,
                 });
                 return pt;
-            });
+            };
+            const plaintext = runnerIsTransaction
+                ? await readAndAudit(db)
+                : await transaction(db, readAndAudit);
             if (plaintext === undefined)
                 return undefined;
             // Brand the plaintext only after audit committed. The response

package/dist/sessions/db/queries/cleanup.js

@@ -1,12 +1,12 @@
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 export async function deleteStaleSessionsBatch(db, olderThanDays, batchSize) {
-    const rows = (await asRawClient(db).unsafe(`DELETE FROM "store_user_sessions"
+    const rows = await asRawClient(db).unsafe(`DELETE FROM "store_user_sessions"
      WHERE "id" IN (
        SELECT "id" FROM "store_user_sessions"
        WHERE "expires_at" < now() - ($1::int * interval '1 day')
           OR "revoked_at" < now() - ($1::int * interval '1 day')
        LIMIT $2
      )
-     RETURNING "id"`, [olderThanDays, batchSize]));
+     RETURNING "id"`, [olderThanDays, batchSize]);
     return rows.length;
 }

package/dist/sessions/feature.js

@@ -24,7 +24,7 @@ export function bindAutoRevokeFromFeature(feature) {
     if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
         const { bindAutoRevokeOnPasswordChange } = exports;
         if (typeof bindAutoRevokeOnPasswordChange === "function") {
-            // @cast-boundary exports-walk — feature.exports is untyped by design
+            // @cast-boundary feature-exports — feature.exports is untyped by design
             return bindAutoRevokeOnPasswordChange;
         }
     }

package/dist/sessions/handlers/list.query.js

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, definePagedQueryHandler, MAX_LIST_LIMIT, } from "@cosmicdrift/kumiko-framework/engine";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.js";
 import { userSessionTable } from "../schema/user-session.js";
@@ -10,7 +11,7 @@ import { userSessionTable } from "../schema/user-session.js";
 // non-exposed column.
 const SORTABLE_COLUMNS = ["id", "userId", "createdAt", "expiresAt", "revokedAt"];
 function isSortableColumn(value) {
-    return SORTABLE_COLUMNS.includes(value);
+    return isOneOf(SORTABLE_COLUMNS, value);
 }
 // Admin view of every session in the active tenant. ctx.db (TenantDb)
 // applies tenant-scoping automatically on selects from tables with a

package/dist/sessions/handlers/revoke-all-for-user.write.d.ts

@@ -6,4 +6,4 @@ export declare const revokeAllForUserWrite: import("@cosmicdrift/kumiko-types/de
 }, z.core.$strip>, {
     count: number;
     userId: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/sessions/handlers/revoke-all-others.write.d.ts

@@ -1,4 +1,4 @@
 import * as z from "zod";
 export declare const revokeAllOthersWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"user-session:revoke-all-others", z.ZodObject<{}, z.core.$strip>, {
     count: number;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/sessions/handlers/revoke.write.d.ts

@@ -3,4 +3,4 @@ export declare const revokeWrite: import("@cosmicdrift/kumiko-types/define-handl
     id: z.ZodUUID;
 }, z.core.$strip>, {
     id: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/shared/attachment-file-name.d.ts

@@ -0,0 +1,3 @@
+import * as z from "zod";
+export declare const attachmentFileNameSchema: z.ZodString;
+export declare function sanitizePdfAttachmentFileName(raw: string, templateSlug: string): string;