@cosmicdrift/kumiko-framework 0.366.0 → 0.367.0

package/agents/examples/user-data-rights.md

@@ -133,6 +133,10 @@ import {
   tenantRetentionOverrideEntity,
 } from "@cosmicdrift/kumiko-bundled-features/data-retention";
 import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import {
+  tenantMembershipEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
   createUserFeature,
   USER_STATUS,
@@ -144,7 +148,7 @@ import {
   runForgetCleanup,
   runUserExport,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
-import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -185,23 +189,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, noteEntity);
   await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
-      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-      tenant_id UUID NOT NULL,
-      user_id TEXT NOT NULL,
-      version INTEGER NOT NULL DEFAULT 0,
-      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      inserted_by_id TEXT,
-      modified_by_id TEXT,
-      is_deleted BOOLEAN NOT NULL DEFAULT false,
-      deleted_at TIMESTAMPTZ,
-      deleted_by_id TEXT,
-      roles TEXT NOT NULL DEFAULT '[]',
-      UNIQUE(user_id, tenant_id)
-    )
-  `);
+  await unsafeCreateEntityTable(stack.db, tenantMembershipEntity);
 });
 
 afterAll(async () => {
@@ -233,14 +221,11 @@ async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {
     status: opts.status ?? USER_STATUS.Active,
     gracePeriodEnd: opts.gracePeriodEnd ?? null,
   });
-  await asRawClient(stack.db).unsafe(
-    `
-    INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
-    VALUES ($1, $2, '["Member"]')
-    ON CONFLICT DO NOTHING
-  `,
-    [TENANT_A, ALICE_ID],
-  );
+  await seedRow(stack.db, tenantMembershipsTable, {
+    tenantId: TENANT_A,
+    userId: ALICE_ID,
+    roles: '["Member"]',
+  });
 }
 
 async function seedNote(id: string, title: string): Promise<void> {

package/agents/features.md

@@ -106,7 +106,7 @@ Requires: `delivery`, `secrets`
 
 ## channel-email
 
-Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.
+Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.
 
 Category: notifications
 
@@ -206,7 +206,7 @@ Exposes APIs: `retention.policyFor`
 
 ## delivery
 
-The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.
+The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.
 
 Category: notifications
 
@@ -413,7 +413,7 @@ German UI and mail copy for framework screens. Opt-in; not included by includeBu
 
 ## mail-foundation
 
-Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.
+Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.
 
 Category: notifications
 
@@ -538,7 +538,7 @@ Requires: `template-resolver`
 
 ## renderer-mail-html
 
-A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
+A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
 
 Requires: `renderer-foundation`, `template-resolver`
 

package/dist/db/queries/seed-context.js

@@ -1,6 +1,5 @@
 import { unsafeReadRetrying } from "../query.js";
 import { tableExists } from "../schema-inspection.js";
-import { SOFT_DELETE_LIVE_ROW_PREDICATE } from "../table-builder.js";
 export async function selectUserByEmail(db, email) {
     const rows = await unsafeReadRetrying(db, `SELECT id::text AS id, email, tenant_id::text AS tenant_id
      FROM read_users
@@ -27,11 +26,12 @@ export async function selectAllTenants(db) {
 }
 // Column names are fixed fragments; every filter value is a bound parameter.
 // template-resolver is an optional feature — without its table the answer is
-// "no templates", not an error.
+// "no templates", not an error. The template entity has no soft delete, so the
+// table has no is_deleted column to filter on.
 export async function selectTemplateResources(db, filter) {
     if (!(await tableExists(db, "read_template_resources")))
         return [];
-    const conditions = ["tenant_id = $1", SOFT_DELETE_LIVE_ROW_PREDICATE];
+    const conditions = ["tenant_id = $1"];
     const params = [filter.tenantId];
     for (const [column, value] of [
         ["slug", filter.slug],

package/dist/engine/feature-config-events-jobs.d.ts

@@ -26,6 +26,8 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
         readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -39,6 +41,8 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
         readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {

package/dist/engine/feature-config-events-jobs.js

@@ -220,6 +220,8 @@ export function buildConfigEventsJobsMethods(state, name) {
                 ...(resolvedDefinition.renamedFrom !== undefined
                     ? { renamedFrom: resolvedDefinition.renamedFrom }
                     : {}),
+                ...(resolvedDefinition.systemOnly === true ? { systemOnly: true } : {}),
+                ...(resolvedDefinition.unsubscribe === true ? { unsubscribe: true } : {}),
             };
         },
         translations(def) {

package/dist/engine/registry-ingest.js

@@ -108,6 +108,9 @@ const RESERVED_TEMPLATE_VARIABLE_NAMES = new Set([
     "link",
     "money",
     "date",
+    "richText",
+    "stepIs",
+    "percent",
 ]);
 const KEBAB_NOTIFICATION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 function isTemplateVariableName(value) {

package/dist/engine/template-variables.d.ts

@@ -23,6 +23,9 @@ export declare const templateVariable: {
     readonly date: (opts?: CommonOptions & {
         readonly example?: string;
     }) => TemplateScalarVariableDef;
+    readonly percent: (opts?: CommonOptions & {
+        readonly example?: number;
+    }) => TemplateScalarVariableDef;
     readonly list: (item: Readonly<Record<string, TemplateScalarVariableDef>>, opts?: CommonOptions & {
         readonly example?: readonly Readonly<Record<string, unknown>>[];
     }) => TemplateListVariableDef;

package/dist/engine/template-variables.js

@@ -16,6 +16,7 @@ export const templateVariable = {
         type: "date",
         ...opts,
     }),
+    percent: (opts = {}) => ({ type: "percent", ...opts }),
     list: (item, opts = {}) => ({ type: "list", item, ...opts }),
 };
 const LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
@@ -48,6 +49,8 @@ function scalarToZod(def) {
             return moneySchema;
         case "date":
             return dateSchema;
+        case "percent":
+            return z.number().finite();
     }
 }
 function variableToZod(def) {

package/dist/files/create-file-ref-from-bytes.d.ts

@@ -19,6 +19,7 @@ export type CreateFileRefInput = {
         readonly entityId?: string;
     };
 };
+export declare function filesUnavailableMessage(caller: string): string;
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;
 export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "files" | "registry" | "user">;
 export declare function uploadFileBytesBeforeTransaction(ctx: UploadFileBytesContext, input: CreateFileRefInput): Promise<BeforeTransactionResult<UploadedFileBytes>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -4,6 +4,11 @@ import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcc
 import { fileRefsTable } from "./file-ref-table.js";
 import { readFilesRouteOptions } from "./file-routes.js";
 import { assertSafeStorageKey } from "./types.js";
+// The handler context has no HTTP/job/seed marker to name, so the message states the actual
+// cause: the dispatcher's AppContext carries no file-provider resolver.
+export function filesUnavailableMessage(caller) {
+    return `${caller}: ctx.files is unavailable because no file-provider resolver is wired on this dispatcher context. Mount a file-provider-* feature and build the dispatcher context with withFileProviderResolver (HTTP, job and seed dispatchers each need it)`;
+}
 // Server-side counterpart of POST /files for handlers/jobs that produce bytes
 // themselves (generated PDFs, exports). Same validation, storage layout and
 // fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
@@ -11,7 +16,7 @@ export async function createFileRefFromBytes(ctx, input) {
     const { files } = ctx;
     if (!files) {
         return writeFailure(new InternalError({
-            message: "createFileRefFromBytes: ctx.files is unavailable — mount a file-provider feature to store files",
+            message: filesUnavailableMessage("createFileRefFromBytes"),
         }));
     }
     const outcome = await storeFileAsFileRef({
@@ -48,7 +53,7 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
     const { files } = ctx;
     if (!files) {
         return writeFailure(new InternalError({
-            message: "uploadFileBytesBeforeTransaction: ctx.files is unavailable — mount a file-provider feature to store files",
+            message: filesUnavailableMessage("uploadFileBytesBeforeTransaction"),
         }));
     }
     const outcome = await writeAcceptedFileBytes({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.366.0",
+  "version": "0.367.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.366.0",
-    "@cosmicdrift/kumiko-types": "0.366.0",
+    "@cosmicdrift/kumiko-http": "0.367.0",
+    "@cosmicdrift/kumiko-types": "0.367.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.366.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.367.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "Seed context finds template resources again",
+    "detail": "findTemplateResources in the seed context filtered on an is_deleted column that the template resource table does not have, so every seed that read template resources failed. The query now reads the live rows only."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Seeds can store files and see why a write failed",
+    "detail": "ProdSeedFn deps now carry createFileRef(tenantId, input), which stores bytes as a fileRef with the same validation and storage layout as POST /files, without a helper write handler. A seed write that fails with internal_error now names the handler and the cause message instead of a bare \"internal error\". The seed dispatcher gets the app's dispatcherOptions (and the job runner in all-in-one mode), like the HTTP dispatcher. The \"ctx.files is unavailable\" message of createFileRefFromBytes names the real cause: the dispatcher context has no file-provider resolver."
+  },
   {
     "version": "0.366.0",
     "type": "breaking",